# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Python (scripts, agents, libraries) + LLM / agent SDKs (Python) + pytest project.

Stack: Python (scripts, agents, libraries), LLM / agent SDKs (Python), pytest.

## Commands

- Install deps: `uv sync`
- Run: `uv run python -m <package>`
- Lint and format: `uv run ruff check . && uv run ruff format .`
- Type check: `uv run mypy .`
- Tests: `uv run pytest -q`

## Project structure

- Source in `src/<package>/`, tests in `tests/`, config in `pyproject.toml`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Python (scripts, agents, libraries)

- Target the Python version in `pyproject.toml`. Use modern syntax (`list[str]`, `X | None`).
- Type-hint all public functions.
- Use `pathlib` for paths, `logging` (not `print`) for diagnostics.
- Add dependencies with `uv add`; never pip install into the global interpreter.
- Keep functions small and pure where possible; isolate I/O at the edges.
- Catch specific exceptions only. Never use bare `except:`.

## LLM / agent SDKs (Python)

- Read API keys from env vars; never hardcode them or log them.
- Keep model names, temperatures and token limits in one settings module.
- Store prompts as versioned files or constants, not scattered f-strings.
- Use structured outputs / JSON schema (Pydantic models) when parsing model output; validate before acting on it.
- Set timeouts and retries with backoff on every API call; handle rate limits gracefully.
- Log token usage and cost per call so spend is visible.
- Agent tools must validate their arguments and must never run shell commands or SQL built from raw model output.

## pytest

- Tests live in `tests/` named `test_*.py`. Use plain `assert`.
- Share setup with fixtures in `conftest.py`; use `@pytest.mark.parametrize` for input tables.
- Mock external services (HTTP, LLM APIs, payment providers); tests must not hit the network.
- Every bug fix adds a regression test.

## Reference docs

- [uv docs](https://docs.astral.sh/uv/)
- [Ruff docs](https://docs.astral.sh/ruff/)
- [OpenAI Python SDK](https://github.com/openai/openai-python)
- [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python)
- [pytest docs](https://docs.pytest.org)