Metadata-Version: 2.4
Name: pydantic-acp
Version: 0.4.2
Summary: ACP adapter for pydantic-ai agents.
Project-URL: Homepage, https://github.com/vcoderun/acpkit
Project-URL: Issues, https://github.com/vcoderun/acpkit/issues
Project-URL: Repository, https://github.com/vcoderun/acpkit
Project-URL: Source, https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp
License: MIT
Requires-Python: >=3.11
Requires-Dist: agent-client-protocol==0.9.0
Requires-Dist: pydantic-ai-slim==1.73.0
Requires-Dist: pydantic>=2.7
Requires-Dist: typing-extensions>=4.12.0
Description-Content-Type: text/markdown

# pydantic-acp

`pydantic-acp` adapts `pydantic_ai.Agent` instances to the ACP agent interface.

## Entry Points

- `run_acp(...)`
- `create_acp_agent(...)`
- `AdapterConfig`
- `AcpSessionContext`
- `MemorySessionStore`
- `FileSessionStore`

## What It Covers

`pydantic-acp` includes:

- ACP session lifecycle and replay
- session-local model control
- providers for host-owned models, modes, config options, and plans
- native deferred approval bridging
- projection maps for filesystem diffs and bash previews
- capability bridges for hooks, history processors, prepare-tools, and MCP metadata
- hook introspection and `HookProjectionMap`
- client-backed filesystem and terminal helpers

Slash commands are available for:

- `/model`
- `/tools`
- `/hooks`
- `/mcp-servers`

## Quick Start

```python
from pydantic_ai import Agent
from pydantic_acp import run_acp

agent = Agent("openai:gpt-5", name="demo-agent")
run_acp(agent=agent)
```

## Configured Runtime

```python
from pathlib import Path

from pydantic_ai import Agent
from pydantic_acp import (
    AdapterConfig,
    FileSessionStore,
    NativeApprovalBridge,
    run_acp,
)

agent = Agent("openai:gpt-5", name="configured-agent")

run_acp(
    agent=agent,
    config=AdapterConfig(
        session_store=FileSessionStore(base_dir=Path(".acp-sessions")),
        approval_bridge=NativeApprovalBridge(enable_persistent_choices=True),
    ),
)
```

## Projection Maps

Filesystem projection:

```python
from pydantic_acp import FileSystemProjectionMap, run_acp

run_acp(
    agent=agent,
    projection_maps=(
        FileSystemProjectionMap(
            default_read_tool="read_file",
            default_write_tool="write_file",
            default_bash_tool="execute",
        ),
    ),
)
```

Hook projection:

```python
from pydantic_acp import HookProjectionMap, run_acp

run_acp(
    agent=agent,
    projection_maps=(
        HookProjectionMap(
            hidden_event_ids=frozenset({"after_model_request"}),
            event_labels={"before_tool_execute": "Starting Tool"},
        ),
    ),
)
```

## Factories, Providers, And Host Backends

Use `agent_factory` or `AgentSource` when the session context should influence agent creation.
Use providers when models, modes, config options, or plans belong to the host layer. Use
`ClientHostContext` when tools should talk back to the ACP client's filesystem or terminal.

## Examples

See [examples/pydantic/README.md](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/README.md) for
focused SDK examples and the full runnable demo.

Key examples:

- [examples/pydantic/static_agent.py](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/static_agent.py)
- [examples/pydantic/hook_projection.py](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/hook_projection.py)
- [examples/pydantic/strong_agent.py](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/strong_agent.py)

For full workspace documentation, see:

- [README.md](https://github.com/vcoderun/acpkit/blob/main/README.md)
- [docs/pydantic-acp.md](https://github.com/vcoderun/acpkit/blob/main/docs/pydantic-acp.md)
