# Agent Base Protocol — Python

Python-specific tooling for the shared agent base protocol. Read `${CLAUDE_PLUGIN_ROOT}/references/shared/agent-base-protocol.md` first for the language-agnostic framework.

## Profiling Tools

The profiling gate requires quantified output from an actual profiler. For Python, use:

| Domain | Profiler | Command |
|--------|----------|---------|
| CPU | cProfile | `$RUNNER -m cProfile -o /tmp/profile.prof <script>` |
| Memory | tracemalloc | `tracemalloc.start()` in-script |
| Memory (native) | memray | `$RUNNER -m memray run --native --trace-python-allocators -o /tmp/mem.bin <script>` |
| Import time | importtime | `$RUNNER -X importtime <script> 2> /tmp/import.log` |
| Async | asyncio debug | `PYTHONASYNCIODEBUG=1 $RUNNER <script>` |
| Wall-clock | yappi | `yappi.set_clock_type('WALL')` |

## Pre-commit Hooks

Check for `.pre-commit-config.yaml` in the project root. If it exists, run `pre-commit run --all-files` before committing — CI failures from forgotten linting waste time.

## Test Discovery

Test commands are discovered by the setup agent and recorded in `.codeflash/setup.md`. Common patterns:

- `pytest` (most common)
- `python -m pytest`
- `uv run pytest`
- Custom: check `pyproject.toml` `[tool.pytest]` or `[tool.hatch]` sections

## Package Manager Detection

The setup agent detects the package manager. Common patterns:

| File present | Package manager | Install command |
|-------------|----------------|-----------------|
| `uv.lock` | uv | `uv sync` |
| `poetry.lock` | poetry | `poetry install` |
| `Pipfile.lock` | pipenv | `pipenv install` |
| `pyproject.toml` (only) | pip/uv | `uv pip install -e .` or `pip install -e .` |
| `requirements.txt` (only) | pip | `pip install -r requirements.txt` |

## I/O Ceiling — Wall-Clock Profiling

For Python, use `yappi` with `WALL` clock type to detect I/O ceilings:

```python
import yappi
yappi.set_clock_type('WALL')
yappi.start()
# ... run target ...
yappi.stop()
yappi.get_func_stats().print_all()
```

Compare `tsub` (CPU self time) vs `ttot` (wall-clock total). If `ttot >> tsub`, the gap is I/O wait.

## Python-Specific Constraints

- **No new dependencies** unless the user explicitly approves. Use stdlib alternatives.
- **Version compatibility**: Check `python_requires` in `pyproject.toml`. Don't use features from newer Python versions (e.g., `match` statements require 3.10+, `itertools.batched` requires 3.12+).
- **CPython assumptions**: Be aware of CPython-specific behavior (refcounting, GIL). Don't rely on them for correctness.
