This file guides coding agents working in this repository. It applies to the entire repo. Deeper AGENTS.md files may further specialize instructions and take precedence within their subtrees.

• Keep changes minimal, focused, and reversible; avoid broad refactors.
• Do not alter public API without explicit instruction; prefer additive changes.
• Never commit secrets (.env, API keys). Verify .gitignore is respected.
• Follow style tools; let formatters fix whitespace vs. hand edits.

• Create env: python -m venv .venv && source .venv/bin/activate
• Install dev deps: pip install -e '.[dev]'
• Install hooks: pre-commit install

• Quick check: make ci-fast (lint + typecheck + focused tests, coverage >= 80)
• Full local CI: make ci (lint, typecheck, tests)
• Tests: make test (filter: pytest -k <pattern> -q)
• Lint/format: make lint / make format then make precommit
• Typecheck: make typecheck
• Examples (fake backend): make examples-quick
• Provider examples (need keys): make examples-openai|anthropic|gemini|ollama
• Docs: make docs-serve (live) or make docs-build (strict)
• Release (trusted publishing): create and push a tag, see make release

• Unit/contracts/providers: make ci-fast
• Integration (requires keys): make itest or provider‑specific make itest-openai|anthropic|gemini|ollama
• Skip integ locally: ALLOY_IT_MODEL=none pytest -q
• Smoke examples without keys: make smoke-examples (uses ALLOY_BACKEND=fake)

• Default model: gpt-5-mini (override with ALLOY_MODEL)
• Useful vars: ALLOY_TEMPERATURE, ALLOY_MAX_TOKENS, ALLOY_SYSTEM/ALLOY_DEFAULT_SYSTEM, ALLOY_RETRY, ALLOY_MAX_TOOL_TURNS, ALLOY_EXTRA_JSON
• Provider keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY; use .env locally and dotenv -f .env run -- <cmd>

• Python: PEP 8 + type hints; 4‑space indent. Run ruff and black.
• Docstrings: concise, imperative; include non‑obvious types.
• Imports: re‑export public API from alloy/__init__.py; import via from alloy import ... in code/docs.
• Decorators: bare @command/@tool when no options; @command(...)/@tool(...) when passing options.

• Provider‑agnostic logic lives outside alloy/models/; provider adapters go in alloy/models/<provider>.py.
• Tools: prefer Design‑by‑Contract via @require/@ensure; raise ToolError with short, instructive messages.
• Streaming: text‑only; commands with tools or non‑string outputs do not stream.

• Do: use rg for fast search; keep diffs tight; update docs/tests when touching behavior.
• Do: run make precommit before proposing a PR.
• Don’t: bump dependencies or change public symbols to satisfy lint without discussion.
• Don’t: introduce provider‑specific behavior into core modules.

• src/alloy/: Core library.
  • ask.py, command.py, tool.py: Prompt, command, and tool orchestration.
  • config.py, types.py, errors.py: Configuration, shared types, errors.
  • models/: Model adapters (base.py, openai.py, anthropic.py, gemini.py, ollama.py). Put provider‑specific code here.
• examples/: Runnable scripts (basic_usage.py, tools_demo.py).
• alloy-spec-v1.md: Reference spec for behaviors and interfaces.
• .env: Local secrets (e.g., OPENAI_API_KEY). Do not commit.
• .venv/: Local virtual environment (git‑ignored). Do not commit.

• Create env: python -m venv .venv && source .venv/bin/activate
• Install dev deps (editable): pip install -e '.[dev]'
• Pre-commit: pre-commit install then make precommit (enforces imports and decorator style in code + docs)
• Run examples: python examples/basic_usage.py or python examples/tools_demo.py (more under examples/patterns/)
  • Streaming (text‑only): python examples/basic/streaming_outputs.py
• Lint/format: ruff . and black .
  • Without installing the package, examples/tests add src/ to sys.path for convenience.

Defaults: The global config uses model="gpt-5-mini" so you can call ask(...) and commands without configure(...). Use configure(...) to override. Streaming is text‑only across providers; commands with tools or non‑string outputs do not stream.

• Indentation: 4 spaces; follow PEP 8 + type hints.
• Naming: snake_case for functions/vars, PascalCase for classes, UPPER_SNAKE_CASE for constants.
• Docstrings: Use concise, imperative summaries. Include argument/return types when non‑obvious.
• Public API: Re‑export only stable symbols in alloy/__init__.py; import public symbols via from alloy import ... (not submodules) in code and docs.
• Decorators: use bare @command/@tool when no options; use @command(...)/@tool(...) when passing options.
• Models: Keep provider‑agnostic logic outside models/; implement providers under alloy/models/<provider>.py.

• Default static return type for commands when output is omitted: sync → str, async → Awaitable[str].
• With output=T, calls return T (async → Awaitable[T]); .stream() yields str chunks; .async_() awaits to T.
• ask.stream_async(...) is typed as AsyncIterable[str].
• ParamSpec preserves prompt function parameters on the wrapped command.

• Framework: Prefer pytest.
• Layout: tests/ mirroring package modules; files named test_*.py.
• Running: pytest -q (add -k pattern to filter).
• Integration tests: require real API keys and model selection via env.
  • OpenAI: set OPENAI_API_KEY (optional ALLOY_IT_MODEL, default gpt-5-mini).
  • Anthropic: set ANTHROPIC_API_KEY (and ALLOY_IT_MODEL=claude-*).
  • Gemini: set GOOGLE_API_KEY (and ALLOY_IT_MODEL=gemini-*).
  • Ollama: run a local Ollama instance (and ALLOY_IT_MODEL=ollama:<name>).
  • To skip provider integ tests locally: ALLOY_IT_MODEL=none pytest -q.
• Coverage (target): Aim for meaningful tests around prompts/contracts and model adapters; include edge cases for parsing/validation.

• Commits: Use imperative mood; consider Conventional Commits (e.g., feat:, fix:, docs:) for clarity.
• Scope small, message specific: what/why over how.
• PRs: Include description, rationale, and screenshots/console snippets if behavior changes. Link related issues. Note any breaking changes.
• Checks: Ensure examples run (examples/*.py) and no regressions in public API.

• Secrets: Keep OPENAI_API_KEY in .env locally; never commit secrets.
• Git ignore: Ensure .env and .venv/ are ignored (they are in this repo). Never publish them.
• Fail‑safe defaults: Validate config in config.py; handle missing keys with clear errors.
• Environment overrides: You can set process env vars to avoid code changes: ALLOY_MODEL, ALLOY_TEMPERATURE, ALLOY_MAX_TOKENS, ALLOY_SYSTEM/ALLOY_DEFAULT_SYSTEM, ALLOY_RETRY, ALLOY_MAX_TOOL_TURNS, ALLOY_EXTRA_JSON (provider‑specific extras). Example: export ALLOY_MODEL=gpt-5-mini.
  • Default max_tool_turns is 10; increase if your workflows require more tool rounds.
  • Anthropic extras: anthropic_tool_choice (e.g., { "type": "auto"|"any"|"tool"|"none" }), anthropic_disable_parallel_tool_use (bool).
• Local runs: Use the dotenv CLI to load .env (e.g., dotenv -f .env run -- pytest). In CI, configure provider API keys as encrypted secrets and pass via environment variables (do not store keys in the repo).

• Use @require(predicate, message) to validate preconditions (receives inspect.BoundArguments).
• Use @ensure(predicate, message) to validate postconditions (receives the tool result).
• On failure, raise a ToolError message back to the model: OpenAI/Anthropic backends surface this as the tool output so the model can adjust (instead of a hard failure).
• Keep messages short and instructive (e.g., "run validate_data first", "must be even").

• Streaming is text‑only for all providers.
• Commands with tools or non‑string outputs do not stream; call them normally to get a typed result.

• Docs pages: Typing, Equivalence Guide, Tool Recipes (HTTP fetch, file search, provider‑backed web search, DBC sequence).
• Examples: see examples/basic_*.py, examples/tools_demo.py, examples/basic/streaming_outputs.py, and examples/patterns/* for orchestration patterns expressed via commands/tools.
• Keep griffe on the current major version pinned in pyproject.toml until mkdocstrings handles src/alloy/__init__.pyi cleanly during mkdocs build; major bumps currently break the docs workflow.

• Version in pyproject.toml; bump with changelog entries.
• Trusted Publishing: tag and push (e.g., git tag v0.2.0 && git push origin v0.2.0) to publish to PyPI via CI.