AGENTS.md

Repository Guidelines

Project Structure & Module Organization

The repository root is the package root for triagesieve_env, so top-level modules such as models.py, client.py, and inference.py are importable package modules. Keep runtime code in server/, baselines in baseline/, dataset artifacts in data/, helper CLIs in scripts/, and tests in tests/. Treat outputs/ and dist/ as generated output.

Build, Test, and Development Commands

• uv sync installs runtime and dev dependencies.
• pip install -e ".[dev]" is the fallback editable install.
• uv run server runs the FastAPI environment locally.
• python scripts/smoke_playthrough.py --difficulty easy --seed 42 runs the scripted expert baseline.
• python scripts/generate_episodes.py --seed 42 --count 100 --difficulty all --output data/seeded_episodes.jsonl regenerates the episode bank.
• python scripts/validate_episode_bank.py --input data/seeded_episodes.jsonl checks parse, determinism, and solvability.
• python -m pytest tests/ -m "not slow" -q runs the fast test suite; remove the marker filter to include API-backed tests.

Coding Style & Naming Conventions

Follow existing Python conventions: 4-space indentation, PEP 8 spacing, type hints on public functions, and concise docstrings where behavior is non-obvious. Use snake_case for modules, functions, and variables; PascalCase for Pydantic models, enums, and test classes; UPPER_SNAKE_CASE for constants. Keep imports explicit and package-relative inside subpackages. No formatter or linter is configured in pyproject.toml, so match the surrounding file style and preserve LF line endings.

Testing Guidelines

Tests use pytest and live under tests/ as test_*.py. Add focused regression coverage for every behavior change, especially state transitions, scoring, routing rules, and script entry points. Slow tests are marked with @pytest.mark.slow; keep external-model calls behind that marker. No hard coverage gate is configured, but changes to core environment logic should include tests that defend deterministic behavior.

Commit & Pull Request Guidelines

Recent commits use short, imperative subjects such as Fix cross-platform compatibility issues and Add server requirements.txt for standalone pip installs. Keep commit titles in that style and scope them to one change. PRs should summarize behavior changes, list validation commands run, note any data-file changes under data/, and include sample output or screenshots when touching docs, CLI flows, or server responses. Link the relevant issue when one exists.

Security & Configuration Tips

Keep secrets in local environment variables or .env; do not commit tokens. inference.py expects values such as HF_TOKEN, LOCAL_IMAGE_NAME, API_BASE_URL, and MODEL_NAME. Review generated JSON/JSONL artifacts before committing to avoid leaking temporary evaluation data.