63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
|
# 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.
|