paf

paf is a small, opinionated agent framework built on pydantic-ai V2. You describe an agent in a YAML spec, choose which capabilities it may use, and paf assembles the agent and runs it with durable conversations, long-term memory, and context management.

It ships with a terminal chat (paf chat), an SSE server for web front ends, and a Python API (Session) that both are built on. A companion web UI, paf-ui, talks to that server.

Full documentation lives at landonmclain.github.io/paf.

Why it exists

paf started from a handful of design principles drawn from earlier agent projects, not from a library. When pydantic-ai V2 turned out to provide much of what those principles called for, building thin on top of it made more sense than writing a new foundation.

pydantic-ai and its harness supply the agent loop, capabilities as the extension point, typed tools, agent specs, and several ready-made capabilities (context compaction, output limits, guardrails, MCP, a browser). paf is the layer around them:

• Assembly. One registry of everything an agent could use, and named profiles that decide what a given agent does use. YAML declares what YAML can describe; capabilities that need live Python objects (stores, search indexes) are built in code and merged in.
• Capabilities written for paf. Long-term memory, a Markdown vault, skills, a codebase map, web search and fetch, scoped file and git tools, and a shell with a command policy. The pydantic-ai ones are configured through the same specs.
• A runtime around them. A Session that persists every conversation to plain files and keeps it searchable, runs background work such as the memory and summary passes, and sits behind the terminal chat and the SSE server.

The principles behind it:

• Extend through capabilities. New behavior arrives as a capability rather than a change to the runtime.
• Single agent first. An Agent is the unit; delegation and background agents are built from the same pieces.
• Inspectable state. JSON and JSONL on disk, no database to run, so you can read, grep, and diff what the agent remembers.
• Optional tracing. Telemetry can go to Langfuse over OpenTelemetry.

Quickstart

Requires Python 3.12 and uv.

git clone https://github.com/landonmclain/paf.git
cd paf
uv sync
cp .env.example .env   # then set OPENAI_API_KEY

Start a conversation:

uv run paf chat                    # the default agent, demo_assistant
uv run paf chat --new              # the same agent, in a fresh conversation

The default model is openai:gpt-6-luna, so an OPENAI_API_KEY is the only required setting. Any pydantic-ai model string works in a spec's model: key, for example openrouter:... (set OPENROUTER_API_KEY) or a local ollama:... model. Web search works without a key; set TAVILY_API_KEY to use Tavily instead. To use the browser capability, install Chromium once with uv run playwright install chromium.

How it fits together

specs/<name>.yaml ──► build_agent ──► Agent ──► Session ──► paf chat
  model, instructions,    │                       │          ui/sse.py
  profile, per-capability │                       │          your code
  settings                ▼                       ▼
                 profile (allowlist)        data/  (runs, memory,
                 + capability catalog              conversations, plans)

• A spec (specs/<name>.yaml) names the model, the instructions, the profile, and settings for each capability (file-tool roots, shell backend, web domains, memory options, and so on).
• A profile (src/paf/capabilities/profiles.py) is the allowlist of capabilities that agent gets, drawn from the catalog in src/paf/capabilities/registry.py.
• build_agent (src/paf/specs.py) loads the spec with pydantic-ai's Agent.from_spec and merges in the capabilities built in Python (src/paf/capabilities/build.py).
• A Session (src/paf/runtime.py) owns a conversation: it restores prior history, stamps the date on each message, compacts context between turns, streams events, and schedules background work after each turn. Turns run as tasks the session owns, so a client can disconnect and reattach to a running turn.

Agents

Agent	Spec	Purpose
demo_assistant	specs/demo_assistant.yaml	Default for paf chat. Everything enabled, including experimental pieces.
secure_assistant	specs/secure_assistant.yaml	Locked-down agent: scoped file tools and sandboxed Python only, with every guard on. Needs Docker.

Other specs in specs/ serve benchmarks and tests. Subagents that agents can delegate to (coding, code review, research, writing) live in specs/sub_agents/, and the background agents that maintain memory and summaries live in specs/background_agents/.

A spec is plain YAML. Abridged:

name: my_agent
profile: assistant
model: openai:gpt-6-luna
instructions: |
  You are a capable general-purpose assistant and technical collaborator...

filesystem:
  root_dir: ~/projects/my-project
shell:
  cwd: ~/projects/my-project
  executor:
    backend: local   # or docker, for a locked-down container

This is the beginning of the README. Read the rest at the original. Read the full README ↗