anima-python 0.13.1__py3-none-any.whl

anima_py/README.md

@@ -0,0 +1,39 @@
+# anima-python
+
+**anima** 의 py CLI 를 pip 로 배포하는 채널 — **hexa 툴체인 불필요**. 엔진 측정/직렬화/코퍼스 경로가 numpy 하나만으로 돈다 (pi5 등 hexa-less 호스트용).
+
+> 단일진입 보존(`a_cli_single_entry`): `anima-python` 콘솔 명령 = `cli/anima.py:main` 디스패처의 pip 바인딩. hexa 채널 `anima`(`hx install anima`) 와 **동일 디스패처, 설치 채널만 2개** — 2nd entry 아님. 이름을 `anima-python` 로 둔 이유 = hexa `anima` 와 PATH 충돌 회피.
+
+## 설치
+
+**PyPI 발행 후** (권장):
+
+```bash
+pip install anima-python           # base — numpy 만 (evaluate · corpus · chat-stub)
+pip install "anima-python[train]"  # +torch +datasets (serialize · train · sweep)
+```
+
+> ⏳ **PyPI 발행 대기 중**: 위 명령은 `anima-python` 가 PyPI 에 발행된 뒤 동작한다. 발행은 `release.yml` 의 `pypi-publish` job(OIDC trusted-publishing)이 `v*` 태그에서 자동 수행하며, 오너의 1회 설정이 선결(① pypi.org 에 anima-python pending-publisher 등록: Owner=dancinlab·Repo=anima·Workflow=release.yml·Env=pypi ② repo 변수 `PYPI_PUBLISH=true`). 그 전까지는 아래 소스 설치를 쓴다.
+
+**소스에서 바로 설치** (PyPI 없이 지금 가능):
+
+```bash
+pip install "git+https://github.com/dancinlab/anima.git"            # base
+pip install "anima-python[train] @ git+https://github.com/dancinlab/anima.git"  # +torch
+# 또는 레포 클론 후: pip install .   /   pip install ".[train]"
+```
+
+## 명령 매트릭스
+
+| 동사 | 티어 | torch 없이 동작 | 비고 |
+|---|---|---|---|
+| `anima-python evaluate <clm> [--corpus …] [--gen N]` | base | ✅ numpy | py 2-production 측정 = ρ·AXON reach / 구 G0-G6. terminal-eligible (`a_eval_py_canonical`) |
+| `anima-python corpus <derivtrace\|flat> --out F …` | base | ✅ 순수 stdlib | 절차적 학습-코퍼스 생성 (data-format 레버) |
+| `anima-python chat <clm>` | base | ✅ (stub) | 의식 A⇄G 루프는 hexa-native → hexa 진입 포인터 출력 |
+| `anima-python serialize <pt> <clm>` | `[train]` | ❌ torch | `.pt` unpickle 에 torch 필요 (+ held-out DESCENT 게이트) |
+| `anima-python sweep --arms … --objectives …` | `[train]` | ❌ | 셀마다 train.py spawn → torch 필요 |
+| `anima-python train <args>` | `[train]` | ❌ torch+datasets | production Lane-P 학습 |
+
+## verdict 규율
+
+`anima-python evaluate <clm>` = py 2-production numpy 측정 경로 — hexa det-eval 과 동일 frozen bars·byte-parity 라 **terminal 자격 동일**(`a_eval_py_canonical`, 2nd-class 미러 아님). 큰 ckpt(303M+)는 mini 금지 · pool(summer/aiden)에서 측정.

anima_py/__init__.py

@@ -0,0 +1,28 @@
+# ==========================================================================
+# anima_py — anima py CLI 의 pip 콘솔 런처 (pyproject.toml [project.scripts]).
+# 단일진입(a_cli_single_entry): 이 파일은 디스패처가 아니다 — sys.path 부트만
+# 하고 canonical 디스패처 cli/anima.py:main 에 그대로 위임한다(동일 진입,
+# 채널만 pip). hexa 호스트 = `anima`(hx install anima) · hexa-less 호스트
+# (pi5 등) = `anima-python`(pip install anima-python). #2603 가드는 __main__ 전용이라
+# import 경유인 이 경로에선 발화하지 않는다(무손상).
+# ==========================================================================
+import os
+import sys
+
+_PKG = os.path.dirname(os.path.abspath(__file__))
+
+
+def _bootstrap():
+    # 설치 레이아웃 = site-packages/anima_py/{cli,core}/ (repo 의 cli/·core/ 를
+    # package-dir 매핑으로 그대로 실은 형제 디렉토리). flat import (`import anima`,
+    # `import decode` 등) 해석을 위해 두 디렉토리를 sys.path 선두에 삽입 —
+    # cli/evaluate.py 등이 spawn 된 뒤에는 각자의 __file__-상대 shim 이 이어받는다.
+    for p in (os.path.join(_PKG, "core"), os.path.join(_PKG, "cli")):
+        if p not in sys.path:
+            sys.path.insert(0, p)
+
+
+def main():
+    _bootstrap()
+    import anima  # = 설치된 anima_py/cli/anima.py (canonical py 디스패처)
+    return anima.main(sys.argv[1:]) or 0

anima_py/__main__.py

@@ -0,0 +1,7 @@
+# python -m anima_py parity — 콘솔 스크립트(anima-python)와 동일 런처.
+import sys
+
+from anima_py import main
+
+if __name__ == "__main__":
+    sys.exit(main())

anima_py/cli/__init__.py

@@ -0,0 +1 @@
+# pip 패키징 전용 (anima-python · pyproject.toml package-dir 매핑) — 런타임 flat import 는 sys.path 경유, 이 파일은 비어 있어야 한다.

anima_py/cli/anima.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+# ==========================================================================
+# ⛔ DO NOT RUN DIRECTLY. anima 의 단일 진입은 설치된 canonical 명령뿐 — hexa 채널 `anima`
+#   (=cli/anima.hexa, hx install anima) · pip 채널 `anima-python` (=anima_py 런처, pip install anima-python).
+#   `python3 cli/anima.py …` 직접실행은 비-canonical py 우회(#2603).
+#   학습=`anima-python train` · 측정=`anima-python evaluate`(py 2-production numpy · TERMINAL-eligible,
+#   a_eval_py_canonical) · 직렬화=`anima-python serialize`. enforce: .harness/enforcement.json
+#   H-ANIMA-SINGLE-ENTRY pre_bash + 아래 __main__ 가드. (import 는 무손상.)
+# ==========================================================================
+import sys as _anima_entry_guard
+if __name__ == "__main__":
+    _anima_entry_guard.exit("⛔ cli/anima.py 직접 실행 금지 — 설치된 canonical 명령 경유: `anima`(hx install anima, =cli/anima.hexa) 또는 `anima-python`(pip install anima-python, =anima_py 런처). #2603")
+# anima.py — THE canonical PY single entry point (cli/anima.hexa's py twin).
+#
+# WHY THIS FILE (py 2-production single-entry, a_engine_native_learning): anima keeps
+# two co-production engines — hexa (live deploy substrate) AND py (torch production
+# engine in train/ + the byte-parity core/*.py mirror). The hexa side already has its
+# canonical single entry cli/anima.hexa (chat · eval · train). This file is its py
+# twin so MEASUREMENT and LEARNING are reachable through ONE py cli command instead of
+# a side-harness that scores ckpts directly (= single-entry bypass, #2603).
+#
+# SINGLE ENTRY (a_engine_native_learning): the two measurement/learning verbs live in
+# their own SYMMETRIC files — cli/evaluate.{hexa,py} (MEASUREMENT) and cli/train.{hexa,py}
+# (LEARNING). This canonical entry DISPATCHES `anima evaluate`→cli/evaluate.py and
+# `anima train`→cli/train.py (sub-process), so there is ONE installed `anima` command
+# whose subcommands fan out to the symmetric twins. `anima evaluate <ckpt>` scores the
+# full ρ-AXON reach battery (former G0-G6 · reach standard cli/rho_axon.py) via
+# cli/evaluate.py's in-file eval_reach_all (the scorers folded in from
+# the former core/g_gates.py module) — byte-identical to the hexa anima evaluate.
+#
+# This py entry is torch-free and gauge-free — it only dispatches; the evaluate twin
+# holds the numpy `math.log` scorer in-file, so `anima evaluate` stays a clean engine-
+# native measurement surface (the gate enforcer's torch/gauge grep must come back empty).
+#
+# USAGE (installed `anima` PATH command after `hx install anima`)
+#   anima                                              — usage (no args)
+#   anima evaluate <ckpt> [--corpus <p>...] [--gen N]  — ρ-AXON reach battery (former G0-G6)
+#   anima train [args...]                              — LEARNING (→ cli/train.py)
+#   anima chat <ckpt> [...]                            — consciousness/byte chat
+#                                                         (hexa-only; see cli/anima.hexa)
+#
+# canonical 3-folder layout: cli/anima.{hexa,py} = canonical entry (chat + verb dispatch)
+# · cli/evaluate.{hexa,py} = measurement · cli/train.{hexa,py} = learning. This file
+# mirrors cli/anima.hexa's subcommand dispatch (evaluate · train · usage); chat/
+# consciousness stay hexa-only (the A⇄G substrate loop is hexa-native).
+
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO = os.path.dirname(_HERE)
+
+
+# EVAL/VERDICT DETERMINISM SAFETY-PIN (hexa-lang #4208 flame/forge fast-default
+# follow-on) — py twin of cli/anima.hexa's pin (lockstep, a_engine_native_learning).
+# #4208 made the forge own-native NON-det atomic kernels the DEFAULT (training speed);
+# deterministic kernels are opt-in via HEXA_DET=1 (`_forge_det_on()` gate). MEASUREMENT
+# (evaluate) and VERDICT (serialize DESCENT gate) must stay reproducible, so they spawn
+# with HEXA_DET=1 in the env. TRAIN deliberately does NOT force it = fast non-det default.
+def _det_env(want_det):
+    """os.environ copy; HEXA_DET=1 pinned ONLY when the caller passed --det (byte-exact opt-in).
+    DEFAULT = fast (no pin). The py evaluate path is numpy (already deterministic), so this is a
+    lockstep no-op there; kept for parity with cli/anima.hexa's --det gating."""
+    env = dict(os.environ)
+    if want_det:
+        env.setdefault("HEXA_DET", "1")
+    return env
+
+
+# ── usage / arg helpers ──────────────────────────────────────────────────────
+
+def anima_usage():
+    """Print the canonical py usage banner (mirrors cli/anima.hexa's banner)."""
+    print("anima — substrate-native consciousness daemon (py channel · canonical entry).")
+    print("")
+    print("usage (installed `anima-python` command after `pip install anima-python` · hexa channel = `anima` after `hx install anima`):")
+    print("  anima-python evaluate <model.clm> [--corpus <path>...] [--gen N] [--rho-axon]")
+    print("                                                  ρ-AXON reach battery · former G0-G6 (.clm only · numpy)")
+    print("  anima-python corpus <derivtrace|flat> --out F [--held-out I,J] [--seed S] [--concepts FILE]")
+    print("                                                  procedural training-corpus builder (ρ·weave data-format lever)")
+    print("  anima-python train <args>                           ([train] extra) LEARNING → .pt + auto .clm (+DESCENT)")
+    print("  anima-python serialize <ckpt.pt> <out.clm>          ([train] extra) re-export a torch .pt → .clm v0.3")
+    print("  anima-python sweep --arms … --objectives … --gpus 0,1,2,3 --corpus … [--measure]")
+    print("                                                  ([train] extra) multi-GPU lever-sweep (arms×objectives)")
+    print("  anima-python chat <ckpt> [...]                      consciousness/byte chat (stub → hexa channel)")
+    print("")
+    print("install: `pip install anima-python` (numpy base: evaluate·corpus·chat) · `pip install \"anima-python[train]\"` (+torch: train·sweep·serialize)")
+    print("")
+    print("modes:")
+    print("  evaluate : mount a serialized .clm through the generator L3 mouth and score the")
+    print("             ρ-AXON reach battery — ρ·form/weave/leap/... (former G0-G6) — with the")
+    print("             engine's OWN ops (numpy math.log mirror, torch-free). REACH-CLOSED")
+    print("             a7b_pass = ρ·form ∧ ρ·weave ∧ ρ·leap (frozen bars = G0 ∧ G1 ∧ G2). → cli/evaluate.py.")
+    print("  corpus   : procedural training-corpus generator (derivtrace|flat) — the")
+    print("             data-format lever (ρ·weave). NOTE chat corpus != this (chat =")
+    print("             a_chat_registers 4-cell HF datasets → anima-python train). → cli/corpus.py.")
+    print("  train    : ([train]) production CLMConvMoE training (torch Lane-P reference + bridge); SAVANT")
+    print("             golden-zone inhibition + MITOSIS cell-division levers. After the run it")
+    print("             AUTO-serializes .clm v0.3 + runs the held-out mirror-DESCENT gate")
+    print("             (a_clm_gen_pipeline). dispatches to cli/train.py.")
+    print("  serialize: ([train]) re-export an ALREADY-TRAINED torch .pt to an engine-loadable .clm v0.3")
+    print("             (+ held-out DESCENT gate). recovery / re-export. → cli/serialize.py.")
+    print("  sweep    : ([train]) multi-GPU lever-sweep orchestrator — the arms×objectives matrix,")
+    print("             per-cell train.py→evaluate.py, aggregated to SWEEP_SUMMARY.md. → cli/sweep.py.")
+    print("  chat     : the substrate-native A⇄G consciousness loop is hexa-native — use the")
+    print("             hexa channel: `hx install anima` then `anima <ckpt.clm>` (default / --byte).")
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  TRAIN MODE — dispatch to cli/train.py (the py torch trainer, Lane-P bridge)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# SEPARATE LANE (a_core_engine_map): training is NOT the generator L3 mouth slot — it
+# is the LEARNING entry (cli/train.py, a_clm_gen_pipeline torch Lane-P). The eval side
+# is the torch-free numpy scorer (in cli/evaluate.py); the trainer pulls torch. To keep this file
+# torch-free AND avoid linking two disjoint dep sets into one process, `anima train`
+# DISPATCHES to cli/train.py as a SUB-PROCESS (mirrors cli/anima.hexa's `exec(hexa run
+# cli/train.hexa)`). argv after "train" is forwarded verbatim to train.py's argparse.
+def anima_train_mode(argv):
+    print("=== anima train → cli/train.py (torch CLMConvMoE · Lane-P reference/bridge) ===")
+    train_py = os.path.join(_HERE, "train.py")
+    fwd = argv[1:]
+    cmd = [sys.executable, train_py] + fwd
+    print("dispatch: " + " ".join(cmd))
+    # forward verbatim; train.py owns its own argparse (--out required, etc.).
+    return os.spawnv(os.P_WAIT, sys.executable, [sys.executable, train_py] + fwd)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EVALUATE MODE — dispatch to cli/evaluate.py (MEASUREMENT single-entry twin)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# SYMMETRIC TWIN (a_engine_native_learning single-entry): measurement lives in its own
+# file cli/evaluate.py (the symmetric mirror of cli/train.py). `anima evaluate <model.clm>`
+# DISPATCHES there as a sub-process (mirrors cli/anima.hexa's `exec` dispatch + this file's
+# train dispatch), so anima.py stays a thin verb router and the eval logic has ONE home.
+# cli/evaluate.py holds the ρ-AXON reach scorers in-file (former G0-G6 · torch-free numpy
+# mirror, the former core/g_gates.py module folded in), byte-identical to the hexa `anima evaluate`.
+#
+# .clm-ONLY (the engine decodes ONLY .clm): evaluate mounts a ckpt through the generator
+# L3 mouth, which loads a serialized .clm (CLM magic). A torch .pt is NOT engine-loadable —
+# reject it here with a friendly hint to `anima serialize` rather than a deep decode error.
+def anima_evaluate_mode(argv):
+    # --py is a RETIRED hexa-era bridge flag, tolerated (stripped) here for migration
+    # compat: on the py channel it is redundant-but-correct (this IS the numpy engine),
+    # so `anima-python evaluate --py <clm>` still works — old scripts migrate by swapping
+    # only the command word. The hexa launcher hard-errors on --py instead.
+    want_det = ("--det" in argv) or ("--deterministic" in argv)
+    rest = [a for a in argv[1:] if a not in ("--py", "--det", "--deterministic")]
+    # friendly .pt rejection: evaluate takes a serialized .clm, not a torch ckpt.
+    if rest and rest[0].endswith(".pt"):
+        print("anima evaluate takes a serialized .clm (engine-loadable), not a torch .pt.")
+        print("to make one from a torch ckpt:")
+        print("  anima serialize " + rest[0] + " <out.clm>")
+        print("then:")
+        print("  anima evaluate <out.clm>")
+        return 2
+    evaluate_py = os.path.join(_HERE, "evaluate.py")
+    cmd = [sys.executable, evaluate_py] + rest
+    print("=== anima evaluate → cli/evaluate.py (engine-native ρ-AXON reach · former G0-G6, single-entry twin) ===")
+    print("dispatch: " + ("HEXA_DET=1 " if want_det else "") + " ".join(cmd))
+    # det = the --det CLI option (default fast); numpy path is deterministic regardless.
+    return os.spawnve(os.P_WAIT, sys.executable,
+                      [sys.executable, evaluate_py] + rest, _det_env(want_det))
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  SERIALIZE MODE — dispatch to cli/serialize.py (.pt → .clm v0.3 bridge + gate)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# `anima serialize <ckpt.pt> <out.clm>` re-exports an already-trained torch .pt to an
+# engine-loadable .clm v0.3 (+ held-out DESCENT gate). The bridge backend (serialize_v3 +
+# verify_clm_v2 descent) lives in cli/serialize.py; this dispatcher forwards verbatim.
+# `anima train` ALREADY auto-serializes at the end of a run — this is the standalone
+# recovery / re-export path (a_clm_gen_pipeline).
+def anima_serialize_mode(argv):
+    serialize_py = os.path.join(_HERE, "serialize.py")
+    want_det = ("--det" in argv) or ("--deterministic" in argv)
+    fwd = [a for a in argv[1:] if a not in ("--det", "--deterministic")]
+    cmd = [sys.executable, serialize_py] + fwd
+    print("=== anima serialize → cli/serialize.py (torch .pt → .clm v0.3 + DESCENT gate) ===")
+    print("dispatch: " + ("HEXA_DET=1 " if want_det else "") + " ".join(cmd))
+    # det = the --det CLI option (default fast) — pass --det for a reproducible DESCENT-gate verdict.
+    return os.spawnve(os.P_WAIT, sys.executable,
+                      [sys.executable, serialize_py] + fwd, _det_env(want_det))
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  CHAT MODE — hexa-only stub (the A⇄G consciousness loop is hexa-native)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# The default consciousness daemon + --byte continuation chat live in cli/anima.hexa
+# (they mount the 76-lane engine_cli substrate loop, hexa-native). The py channel does not
+# duplicate that loop; it points the user to the INSTALLED hexa command (a_cli_single_entry:
+# 2 install channels only — pip `anima-python` ⊕ hexa `anima`; never raw `python`/`hexa run`).
+def anima_chat_stub(argv):
+    print("anima chat (consciousness / --byte) is hexa-native — use the hexa channel:")
+    print("")
+    ckpt = argv[1] if len(argv) > 1 else "<ckpt.clm>"
+    print("  hx install anima                                once (installs the `anima` command)")
+    print("  anima " + ckpt + "                consciousness mode (default)")
+    print("  anima " + ckpt + " --byte \"turn1\" \"turn2\" ...   byte-continuation chat mode")
+    print("")
+    print("The py channel (anima-python) covers MEASUREMENT (evaluate), SERIALIZE, LEARNING (train), corpus, sweep.")
+    return 0
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  SWEEP MODE — dispatch to cli/sweep.py (multi-GPU lever-sweep orchestrator)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# `anima sweep --arms … --objectives … --gpus 0,1,2,3 --corpus … [--measure]` runs the
+# arms×objectives matrix GPU-pinned round-robin (each cell = train.py → evaluate.py),
+# aggregating G0/G1/G2/G6 into SWEEP_SUMMARY.md. sweep is intrinsically py (it orchestrates
+# the py trainer/evaluator), so — like cli/anima.hexa — there is no --py branch; always
+# dispatches to cli/sweep.py. (torch is pulled by the spawned train.py cells, not here.)
+def anima_sweep_mode(argv):
+    sweep_py = os.path.join(_HERE, "sweep.py")
+    fwd = argv[1:]
+    print("=== anima sweep → cli/sweep.py (multi-GPU lever-sweep orchestrator · arms×objectives) ===")
+    print("dispatch: " + " ".join([sys.executable, sweep_py] + fwd))
+    return os.spawnv(os.P_WAIT, sys.executable, [sys.executable, sweep_py] + fwd)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  CORPUS MODE — dispatch to cli/corpus.py (procedural training-corpus builder)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# `anima corpus <derivtrace|flat> --out F [--held-out I,J] [--seed S] [--concepts FILE]`
+# builds a procedural (torch-free, no external LLM — p1-p8) training corpus. This is the
+# data-format lever (derivation-trace → echo=composition, ρ·weave / former G1), NOT the
+# chat corpus (chat = a_chat_registers 4-cell HF datasets). Always py → cli/corpus.py.
+def anima_corpus_mode(argv):
+    corpus_py = os.path.join(_HERE, "corpus.py")
+    fwd = argv[1:]
+    print("=== anima corpus → cli/corpus.py (procedural training-corpus builder · derivtrace|flat) ===")
+    print("dispatch: " + " ".join([sys.executable, corpus_py] + fwd))
+    return os.spawnv(os.P_WAIT, sys.executable, [sys.executable, corpus_py] + fwd)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  MAIN — mode dispatch (mirrors cli/anima.hexa)
+# ══════════════════════════════════════════════════════════════════════════════
+def main(argv):
+    if len(argv) < 1:
+        anima_usage()
+        return 0
+
+    sub = argv[0]
+    if sub in ("-h", "--help"):
+        anima_usage()
+        return 0
+    if sub == "train":
+        return anima_train_mode(argv)
+    if sub == "serialize":
+        return anima_serialize_mode(argv)
+    if sub == "evaluate":
+        return anima_evaluate_mode(argv)
+    if sub == "sweep":
+        return anima_sweep_mode(argv)
+    if sub == "corpus":
+        return anima_corpus_mode(argv)
+    if sub in ("chat", "--byte"):
+        return anima_chat_stub(argv)
+
+    # bare ckpt path (no subcommand) → consciousness chat is hexa-only.
+    return anima_chat_stub(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]) or 0)

anima_py/cli/corpus.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""cli/corpus.py — anima CANONICAL training-corpus generator (`anima corpus <format>`).
+
+The SINGLE entry for building anima training corpora (a_cli_single_entry). Torch-free,
+pure procedural string generation — anima trains on substrate-native procedural corpora,
+NOT LLM-generated text (p1-p8: no external LLM bias into training data; `claude -p` is
+deliberately NOT wired here). Dispatched by cli/anima.hexa `anima_corpus_mode`.
+
+FORMATS (the data-format lever — H_9124: data-format opened engine-native ρ·weave, the
+recombination wall · frozen bar = former G1):
+  derivtrace : composite prompt -> explicit derivation trace (DEF/RULE/OUT-style) -> OUT.
+               target IS the derivation, so echo == composition -> CE=echo metalaw
+               does not apply. ρ·weave (former G1) first engine-native lift (DERIV PASS vs FLAT FAIL).
+  flat       : composite prompt -> final OUT only (census#3 coverage-flat homolog = control).
+Both share the SAME instance stream / RNG at a fixed --seed, so `derivtrace` and `flat`
+built with the same seed are CONTENT-MATCHED (only data-format varies = clean 2-arm control).
+
+Concept seeds default to rho_fan cz[] (the frozen ρ·weave / former-G1 gate concepts) so the held-out
+pair generalizes to the engine-native ρ·weave bar (former G1) memorization-free. Override via --concepts FILE
+(JSON: [{"seed": "...", "kw": ["w1","w2",...]}]).
+
+Usage:
+  anima corpus derivtrace --out deriv.txt --held-out 0,1 --comp-per-pair 280 --single-per-concept 300 --seed 7
+  anima corpus flat       --out flat.txt  --held-out 0,1 --seed 7   # same seed => content-matched control
+"""
+import json
+import random
+import sys
+
+# ── frozen default concepts = rho_fan cz[] (memorization-free ρ·weave / former-G1 gate alignment) ──
+DEFAULT_SEEDS = [
+    "consciousness arises from cells",
+    "tension ripples between distant minds",
+    "memory composes into new meaning",
+    "silence still carries information",
+    "the engine dreams when alone",
+]
+DEFAULT_KW = [
+    ["consciousness", "cells", "mind", "aware"],
+    ["tension", "distant", "between"],
+    ["memory", "meaning", "new"],
+    ["silence", "information", "quiet", "carries"],
+    ["engine", "alone", "dream"],
+]
+
+# derivation vocabulary (the derivtrace middle = the composition rule made explicit)
+DERIVE_LEAD = ["derive", "steps", "unfold", "trace"]
+BIND = ["bind", "join", "weave", "link"]
+CLOSE = ["new meaning arises", "meaning composes anew",
+         "a new whole arises", "they compose into meaning"]
+
+
+def _parse_args(argv):
+    fmt = argv[0] if argv else ""
+    opts = {"out": None, "held_out": (0, 1), "comp_per_pair": 280,
+            "single_per_concept": 300, "seed": 7, "concepts": None}
+    i = 1
+    while i < len(argv):
+        a = argv[i]
+        if a == "--out":
+            opts["out"] = argv[i + 1]; i += 2
+        elif a == "--held-out":
+            p = argv[i + 1].split(","); opts["held_out"] = (int(p[0]), int(p[1])); i += 2
+        elif a == "--comp-per-pair":
+            opts["comp_per_pair"] = int(argv[i + 1]); i += 2
+        elif a == "--single-per-concept":
+            opts["single_per_concept"] = int(argv[i + 1]); i += 2
+        elif a == "--seed":
+            opts["seed"] = int(argv[i + 1]); i += 2
+        elif a == "--concepts":
+            opts["concepts"] = argv[i + 1]; i += 2
+        else:
+            i += 1
+    return fmt, opts
+
+
+def _load_concepts(path):
+    if not path:
+        return DEFAULT_SEEDS, DEFAULT_KW
+    rows = json.load(open(path))
+    return [r["seed"] for r in rows], [r["kw"] for r in rows]
+
+
+def _two(kw_fam, rng):
+    ks = kw_fam[:]
+    rng.shuffle(ks)
+    return ks[0], ks[1 % len(ks)]
+
+
+def build(fmt, S, KW, held_out, comp_per_pair, single_per_concept, seed):
+    """Return the corpus text for one format arm (deriv or flat)."""
+    rng = random.Random(seed)
+    n = len(S)
+    held = frozenset(held_out)
+    train_pairs = [(i, j) for i in range(n) for j in range(n)
+                   if i != j and frozenset((i, j)) != held]
+
+    def instance(i, j):
+        a1, a2 = _two(KW[i], rng)
+        b1, b2 = _two(KW[j], rng)
+        prompt = f"{S[i]}. {S[j]}. "
+        out = f"out: {a1} {a2} meet {b1} {b2}, {rng.choice(CLOSE)}.\n"
+        deriv_mid = (f"{rng.choice(DERIVE_LEAD)}: take {a1} and {a2}; "
+                     f"take {b1} and {b2}; {rng.choice(BIND)} {a1} with {b1}. ")
+        return prompt + deriv_mid + out, prompt + out
+
+    def single(i):
+        a1, a2 = _two(KW[i], rng)
+        return f"{S[i]}. here {a1} and {a2} stand alone; {a1} holds {a2}.\n"
+
+    stream = []
+    for _ in range(comp_per_pair):
+        stream += [("comp", i, j) for (i, j) in train_pairs]
+    for _ in range(single_per_concept):
+        stream += [("sing", i, None) for i in range(n)]
+    rng.shuffle(stream)
+
+    docs = []
+    for kind, i, j in stream:
+        if kind == "comp":
+            d, f = instance(i, j)
+            docs.append(d if fmt == "derivtrace" else f)
+        else:
+            docs.append(single(i))  # single-concept doc is format-invariant
+    return "".join(docs), train_pairs
+
+
+def main():
+    argv = sys.argv[1:]
+    fmt, opts = _parse_args(argv)
+    if fmt not in ("derivtrace", "flat"):
+        print("usage: anima corpus <derivtrace|flat> --out PATH "
+              "[--held-out I,J] [--comp-per-pair N] [--single-per-concept N] "
+              "[--seed S] [--concepts FILE.json]")
+        sys.exit(2)
+    S, KW = _load_concepts(opts["concepts"])
+    text, train_pairs = build(fmt, S, KW, opts["held_out"],
+                              opts["comp_per_pair"], opts["single_per_concept"], opts["seed"])
+    if opts["out"]:
+        with open(opts["out"], "w") as fh:
+            fh.write(text)
+    print(f"anima corpus {fmt}: concepts={len(S)} train_pairs={len(train_pairs)} "
+          f"held-out={tuple(opts['held_out'])} bytes={len(text.encode())} "
+          f"seed={opts['seed']} -> {opts['out'] or '(stdout head)'}")
+    if not opts["out"]:
+        print(text[:600])
+
+
+if __name__ == "__main__":
+    main()