divi: Instructions file for Codex

AGENTS.md

Dev environment

• Python version is defined in pyproject.toml (requires-python).
• Always use the virtual environment in .venv/ or venv/ when running commands.
• If neither exists, do not run any Python code until the human specifies which Python executable to use.
• uv is the primary workflow:
  • Install: uv sync --all-extras (always sync with extras to include ai dependencies)

Code style and formatting

• Use ruff for formatting, import sorting and linting.
• Do NOT run pre-commit run -a — it modifies unrelated files. Let pre-commit fire on commit.
• New/updated .py files (outside docs/) should include the license header from LICENSES/.license-header (pre-commit enforces this).
• Hook configuration lives in /.pre-commit-config.yaml; keep any new files compatible with these hooks.
• If the human is asking an inquisitive or brainstorm-style question, do not change code; respond with analysis or ideas only.

Testing

• Write spec-driven tests first (behavior-focused) before adding critical low-level mocking.
• Use pytest ecosystem tools (e.g., pytest-mock) only; avoid unittest unless no alternative exists and the human agrees.
• Markers are registered in pytest.ini. Do not run requires_api_key tests as an agent unless explicitly asked, and avoid e2e during development.
• API tests require a Qoro API key:
  • QORO_API_KEY=... uv run pytest -n auto --run-api-tests
  • or uv run pytest -n auto --run-api-tests --api-key your-key-here
• Never inline imports nor classes in test functions. If you are facing errors due to circular imports, ask for approval before inlining imports to fix it.
• Do not leave meta comments in source or tests that explain where other code moved (e.g. "tests live in …", "keep one smoke here"). Relocations should be obvious from module layout and test names; use docstrings only when they document behaviour under test.
• Use simulator fixtures from tests/conftest.py: dummy_simulator when a real backend is not needed (returns fake counts), default_test_simulator for actual circuit execution (QASM→shots), dummy_expval_backend for expval-mode tests. Never instantiate a simulator backend directly in a unit test — always use a fixture. A test that genuinely needs its own instance (e.g. it exercises constructor arguments or a backend configuration no fixture covers) is a special case: say so and get the human's agreement first.
• Test layout mirrors divi/ — one test_<module>.py per source module (see docs/source/development/testing.rst).
• Shared test infrastructure (do not mix roles):
  • conftest.py — pytest fixtures and hooks only (@pytest.fixture, pytest_addoption). Auto-discovered; never import from conftest in test code.
  • _helpers.py — explicit-import builders, assertion helpers, constants, and shared test doubles (e.g. DummySpecStage, backend spies). Use from tests.<pkg>._helpers import ….
  • _contracts.py — shared verify_* behavioural checks imported across multiple test_*.py files in the same package. Use a descriptive name such as _circuit_runner_contracts.py when the scope is narrower than the whole package.
  • Fixtures used by a single test file may stay in that file; promote to conftest.py when reused within the package or subtree.