selectools: Instructions file for Codex

Selectools -- Agent Instructions

Commands

# Test (MUST pass before any commit)
pytest tests/ -x -q
pytest tests/ -k "not e2e" -x -q          # no API keys needed

# Format + lint (MUST run before commit — replaces Black + isort + flake8)
ruff format src/ tests/
ruff check src/ tests/ --fix

# Type check
mypy src/

# Security (MUST pass before release tags)
bandit -r src/ -ll -q -c pyproject.toml

# Docs
cp CHANGELOG.md docs/CHANGELOG.md && mkdocs build

Stack

• Python 3.9+ (CI: 3.9, 3.10, 3.11, 3.12, 3.13)
• pip + setuptools, src-layout: src/selectools/
• pytest (5000+ tests), Ruff (format + lint), mypy
• MkDocs Material for docs, deployed to GitHub Pages

Boundaries

Always (do without asking)

• Run ruff format and ruff check --fix on every modified file
• Run pytest tests/ -k "not e2e" -x -q after implementation changes
• Add type hints to all public APIs
• Add a regression test for every bug fix
• Apply @beta stability marker to new public symbols
• Use response_msg.content or "" when reading provider content

Ask First

• Adding new fields to AgentConfig, AgentResult, or AgentObserver
• Adding new StepType values to AgentTrace
• Modifying agent/core.py (the main agent loop)
• Changing public API signatures on @stable symbols
• Adding new dependencies to pyproject.toml

Never

• Push directly to main -- MUST use PR workflow
• Push to remote without explicit user request
• Call real LLM APIs in unit tests -- use RecordingProvider or mocks
• Use datetime.utcnow() -- MUST use datetime.now(timezone.utc)
• Use x = x or default when 0, "", or [] are valid values
• Create ThreadPoolExecutor() per-call in async code -- use module singleton
• Use self.config.model in astream() -- MUST use self._effective_model
• Stringify ToolCall objects -- check isinstance(chunk, str) first
• Skip the tools parameter in provider stream()/astream() methods
• Add co-author trailer lines to commits