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:

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.

2.5 KiB Raw Blame History