{"data":{"kind":"file","path":"README.md","version_id":"q4gknpnjjcgva9n6j8i24sad","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":5407,"modified_at":"2026-10-04T16:43:13.992000","content_hash":"6f553fb8dd673831bc3570b4bb53ecba63b3fcd11068b1696940155dfbaccff9"},"entries":[],"content":"# Bio-Circuit: causal circuit environments\n\nThree text-only Verifiers v1 tasksets for interpreting Qwen3-4B through causal\nfeature interventions. This development release provides public evaluation\ncohorts and source code. **Scored rollouts require an external CUDA GPU backend.**\nIt is not a CPU-only environment and is not eligible for GPU-excluding runs.\n\n| Taskset ID | Task |\n|---|---|\n| `circuit-supernodes` | Infer a concept from evidence and identify causally necessary features |\n| `supernode-rediscovery` | Rediscover a circuit for a named semantic goal |\n| `suppressed-features` | Restore a subject model's output after feature corruption |\n\nAll three tasksets and the `circuit-null` harness ship in this one Python wheel.\nThe wheel includes backend source under `modal_app`; GPU dependencies are\ninstalled separately on the GPU host.\n\n## Public data\n\n[amitprakash2005/bio-circuit](https://huggingface.co/datasets/amitprakash2005/bio-circuit)\ncontains 16 evaluation tasks per taskset, full attribution graphs, provenance\nmanifests, SHA-256 hashes, schemas, and lightweight browsable indexes. The data\nis CC-BY-4.0 and downloads without an HF token. The loader pins an immutable\ndataset commit; a supplied local `dataset_file` takes precedence.\n\nCompressed data totals about 2.6 GiB, downloaded one taskset at a time. Parsed\ngraphs need substantially more RAM. No training data or validated SFT\ntrajectories are included. These evaluation cohorts are not a disjoint train set.\n\n## Install the environment client (no CUDA required)\n\nUse Python 3.13 for the evaluation client:\n\n```bash\nuv venv --python 3.13\nsource .venv/bin/activate\nuv pip install prime\nprime env install wazupsteve/circuit-supernodes\n```\n\nThe rediscovery/restoration modules and harness are included in that install.\nThis package uses the Verifiers v1 `Taskset` interface with `verifiers==0.2.1`.\n\n## Start your own subject backend\n\nThe backend needs an 80 GB-class NVIDIA GPU, suitable CUDA drivers, and disk for\nthe model and transcoders (allow at least 80 GB of cache/disk space). It loads\npublic `Qwen/Qwen3-4B` and `mwhanna/qwen3-4b-transcoders` weights. Self-hosting\nrequires no private service or author's Modal credentials.\n\nDownload and extract this environment's public source archive from Prime Hub.\nOn the GPU host, from the extracted directory, install the backend in a\n**separate Python 3.11 virtualenv**. Do not install the evaluation client there;\nthe backend and Verifiers use different numerical stacks.\n\n```bash\nuv venv --python 3.11 .venv-subject\nuv pip install --python .venv-subject/bin/python \\\n  'torch==2.8.0' --index-url https://download.pytorch.org/whl/cu126\nuv pip install --python .venv-subject/bin/python \\\n  'circuit-tracer==0.5.0' 'nnsight==0.6.1' 'transformer-lens==2.16.1' \\\n  'cloudpickle==3.0.0' 'huggingface-hub[hf_transfer]<1' \\\n  fastapi uvicorn typer pydantic tenacity httpx\n.venv-subject/bin/python -m modal_app.server --port 8000\n```\n\nThe server listens on loopback and serializes GPU operations. Reach it from\nthe evaluation machine through an SSH tunnel:\n\n```bash\nssh -N -L 8000:127.0.0.1:8000 user@gpu-host\n# In another terminal with the evaluation client virtualenv activated:\nexport SUBJECT_URL=http://127.0.0.1:8000\ncurl --fail \"$SUBJECT_URL/health\"\n```\n\nThe endpoint has no built-in authentication; keep it on loopback or a trusted\nprivate network. In a remote sandbox, localhost refers to that sandbox: configure\na backend address reachable from both the tool runtime and reward process.\nThe example below uses local subprocess runtimes.\n\nWithout `SUBJECT_URL`, the client uses the Modal app named `circuit-supernodes`.\nDeploy the included `modal_app/attribution.py` in your own Modal workspace and\nsupply your own Modal credentials to use that option. This release does not\nprovide a hosted GPU service or a published container image.\n\n## Run one evaluation\n\nSave this as `eval.toml` and provide policy inference credentials through the\nprovider configuration supported by Verifiers. Inference and GPU hosting incur\ncosts.\n\n```toml\nmodel = \"Qwen/Qwen3.5-4B\"\nnum_tasks = 1\nnum_rollouts = 1\nmax_turns = 8\n\n[sampling]\nmax_tokens = 16384\nenable_thinking = false\n\n[taskset]\nid = \"circuit-supernodes\"\n\n[harness]\nid = \"circuit-null\"\n```\n\n```bash\neval @ eval.toml --dry-run --no-push\neval @ eval.toml --no-push\n```\n\nChange `taskset.id` to `supernode-rediscovery` or `suppressed-features` for the\nother tasks. Defaults select the corresponding public evaluation file.\n`--dry-run` checks configuration only; a real rollout establishes end-to-end\nbackend operation. `--no-push` prevents result uploads, not provider calls.\n\nKeep heldout/control cohorts and corruption specifications inaccessible to the\npolicy. A public operator dataset is not a policy-visible tool response. These\ntasks have no gold-circuit labels; successful SFT trajectories must be generated\nand validated separately with live interventions and reward checks.\n\n## Development\n\nSource: [WazupSteve/bio-circuit](https://github.com/WazupSteve/bio-circuit).\nFrom `environments/circuit_supernodes` in the repository:\n\n```bash\nuv sync --frozen\nuv run pytest\nuv run ruff check .\nuv build\n```\n\nThe repository's `configs/rl/` files reference training data not included in this\nrelease. Hosted training is not validated by local dry runs. Provision the\nbackend and supply separately generated training data before attempting RL.\n","encoding":"utf-8","truncated":false,"total_bytes":5407},"status":null}