|
1 | | -# Repository Guidelines |
2 | | - |
3 | | -## Project Structure & Module Organization |
4 | | -- `src/acp/`: runtime package exposing agent/client abstractions, transports, and the generated `schema.py`. |
5 | | -- `schema/`: upstream JSON schema sources; regenerate Python bindings with `make gen-all`. |
6 | | -- `examples/`: runnable scripts (`echo_agent.py`, `client.py`, `gemini.py`, etc.) demonstrating stdio orchestration patterns. |
7 | | -- `tests/`: pytest suite, including opt-in Gemini smoke checks under `tests/test_gemini_example.py`. |
8 | | -- `docs/`: MkDocs content powering the hosted documentation. |
9 | | - |
10 | | -## Build, Test, and Development Commands |
11 | | -- `make install` — provision the `uv` virtualenv and install pre-commit hooks. |
12 | | -- `make check` — run Ruff linting/formatting, type analysis, dependency hygiene, and lock verification. |
13 | | -- `make test` — execute `pytest` (with doctests) inside the managed environment. |
14 | | -- `make gen-all` — refresh protocol artifacts when the ACP schema version advances (`ACP_SCHEMA_VERSION=<ref>` to pin an upstream tag). |
15 | | - |
16 | | -## Coding Style & Naming Conventions |
17 | | -- Target Python 3.10+ with four-space indentation and type hints on public APIs. |
18 | | -- Ruff enforces formatting and lint rules (`uv run ruff check`, `uv run ruff format`); keep both clean before publishing. |
19 | | -- Prefer dataclasses or generated Pydantic models from `acp.schema` over ad-hoc dicts. Place shared utilities in `_`-prefixed internal modules. |
20 | | -- Prefer the builders in `acp.helpers` (for example `text_block`, `start_tool_call`) when constructing ACP payloads. The helpers instantiate the generated Pydantic models for you, keep literal discriminator fields out of call sites, and stay in lockstep with the schema thanks to the golden tests (`tests/test_golden.py`). |
21 | | - |
22 | | -## Testing Guidelines |
23 | | -- Tests live in `tests/` and must be named `test_*.py`. Use `pytest.mark.asyncio` for coroutine coverage. |
24 | | -- Run `make test` (or `uv run python -m pytest`) prior to commits; include reproducing steps for any added fixtures. |
25 | | -- Gemini CLI coverage is disabled by default. Set `ACP_ENABLE_GEMINI_TESTS=1` (and `ACP_GEMINI_BIN=/path/to/gemini`) to exercise `tests/test_gemini_example.py`. |
26 | | - |
27 | | -## Commit & Pull Request Guidelines |
28 | | -- Follow Conventional Commits (`feat:`, `fix:`, `docs:`, etc.) with succinct scopes, noting schema regenerations when applicable. |
29 | | -- PRs should describe exercised agent behaviours, link relevant issues, and include output from `make check` or focused pytest runs. |
30 | | -- Update documentation and examples whenever public APIs or transport behaviours change, and call out environment prerequisites for new integrations. |
| 1 | +# Repository Handbook |
| 2 | + |
| 3 | +Use this page as the quick orientation for the Python SDK repo. It mirrors the tone of the main README/index and surfaces what you need without hunting through multiple docs. |
| 4 | + |
| 5 | +## Repo Map |
| 6 | + |
| 7 | +| Path | Why it exists | |
| 8 | +| --- | --- | |
| 9 | +| `src/acp/` | Runtime package: agent/client bases, transports, helpers, schema bindings, contrib utilities | |
| 10 | +| `schema/` | Upstream JSON schema sources (regenerate with `make gen-all`) | |
| 11 | +| `examples/` | Runnable scripts such as `echo_agent.py`, `client.py`, `gemini.py`, `duet.py` | |
| 12 | +| `tests/` | Pytest suite, including optional Gemini smoke tests in `tests/test_gemini_example.py` | |
| 13 | +| `docs/` | MkDocs content published at `agentclientprotocol.github.io/python-sdk/` | |
| 14 | + |
| 15 | +## Daily Commands |
| 16 | + |
| 17 | +| Need | Command | |
| 18 | +| --- | --- | |
| 19 | +| Bootstrap env + pre-commit | `make install` | |
| 20 | +| Format, lint, types, deps | `make check` | |
| 21 | +| Test suite (pytest + doctest) | `make test` | |
| 22 | +| Regenerate schema + bindings | `ACP_SCHEMA_VERSION=<tag> make gen-all` | |
| 23 | + |
| 24 | +## Style Guardrails |
| 25 | + |
| 26 | +- Target Python 3.10+ and keep public APIs typed. |
| 27 | +- Ruff handles formatting + linting (`uv run ruff format` / `check`)—keep both clean before pushing. |
| 28 | +- Reach for the generated Pydantic models and helpers (e.g. `text_block`, `start_tool_call`) instead of hand-crafting dicts; helpers stay aligned with the schema via `tests/test_golden.py`. |
| 29 | +- Place reusable internals in `_`-prefixed modules. |
| 30 | + |
| 31 | +## Testing Expectations |
| 32 | + |
| 33 | +- Tests live under `tests/` and follow the `test_*.py` naming. Mark async tests with `pytest.mark.asyncio`. |
| 34 | +- Run `make test` (or `uv run python -m pytest`) before committing and include reproduction steps for new fixtures. |
| 35 | +- Gemini CLI checks are opt-in: set `ACP_ENABLE_GEMINI_TESTS=1` and optionally `ACP_GEMINI_BIN=/path/to/gemini` to exercise `tests/test_gemini_example.py`. |
| 36 | + |
| 37 | +## PR Checklist |
| 38 | + |
| 39 | +- Use Conventional Commit prefixes (`feat:`, `fix:`, `docs:`, etc.) and call out schema regenerations explicitly. |
| 40 | +- Summarise exercised behaviours, link related issues, and attach `make check` / targeted pytest output in PR descriptions. |
| 41 | +- Update docs/examples when user-visible APIs or transports change, and document any new environment requirements. |
31 | 42 |
|
32 | 43 | ## Agent Integration Tips |
33 | | -- Bootstrap agents from `examples/echo_agent.py` or `examples/agent.py`; pair with `examples/client.py` for round-trip validation. |
34 | | -- Use `spawn_agent_process` / `spawn_client_process` to embed ACP parties directly in Python applications. |
35 | | -- Validate new transports against `tests/test_rpc.py` and, when applicable, the Gemini example to ensure streaming updates and permission flows stay compliant. |
| 44 | + |
| 45 | +- Start new agents from `examples/echo_agent.py` or `examples/agent.py`; pair them with `examples/client.py` for loopback validation. |
| 46 | +- `spawn_agent_process` / `spawn_client_process` embed ACP parties inside Python apps without hand-wiring stdio. |
| 47 | +- Validate new transports against `tests/test_rpc.py` and (when relevant) the Gemini example to ensure streaming + permission flows stay compliant. |
0 commit comments