ORBIT-Q: Instructions file for Codex

AGENTS.md

This repository hosts a Harbor benchmark suite for 12 standard quantum challenge tasks.

Active tasks:

tasks/challenge-01
...
tasks/challenge-12

Do not use the removed physical-sciences/physics/... smoke path as the active benchmark.

Quick Bootstrap

Run all commands from the repository root.

Use the local Harbor Python environment if it exists:

./.conda/harbor-py312/bin/harbor --help

If this environment is absent, create or install Harbor outside this repository, then keep using the repo root on PYTHONPATH so Harbor can import local adapters.

Build or refresh the framework-specific Docker image used by both agent and verifier. This is the first command to run on a new machine after Docker is available:

FRAMEWORK=tensorcircuit bash scripts/build_challenge_quantum_image.sh

The default TensorCircuit tag is:

challenge-benchmark-quantum-tensorcircuit:py311

Verify that the image contains Codex CLI and Claude Code:

docker run --rm challenge-benchmark-quantum-tensorcircuit:py311 \
  sh -lc 'codex --version && claude --version'

Generate framework prompt files and canonical tasks only when templates or upstream problem files change:

python3 scripts/generate_framework_prompts.py --framework tensorcircuit pennylane torchquantum
python3 scripts/generate_tc_challenge_tasks.py

By default the generator expects the upstream challenge-suite source repo next to this repository at ../tensorcircuit/examples/challenge_suite. Override it with TC_CHALLENGE_SUITE_SOURCE or --source if needed.

Do not regenerate tasks/challenge-* while a Harbor job is running. Local Harbor uses the live task directory as Docker context and compose project directory.

Framework Image Strategy

The benchmark intentionally uses stable framework-specific local images instead of asking Harbor to rebuild each task environment. Tasks do not carry Dockerfiles. Image definitions and framework Python dependencies are maintained under: