| # Concept Lab (alpha, nothing measured yet) |
|
|
| A reusable concept does not have to live in trained weights. It can live in |
| a measured functional delta. |
|
|
| That is the whole bet. Measure what a piece of conditioning actually does to |
| the model, factor that measured effect into reusable components, and compile |
| the components back through the model's own conditioning channels. |
|
|
| ``` |
| examples -> functional deltas -> factorization -> portable operator |
| -> native conditioning |
| ``` |
|
|
| The primitive is a difference between two matched forward passes. For model |
| state `h` at layer `l`, sampling coordinate `s`, output segment `q`, base |
| input `x`, and a conditioning source `C`: |
|
|
| ``` |
| Delta(C; x, l, s, q) = h(x | C) - h(x | control(C)) |
| ``` |
|
|
| The control is doing the real work in that line. On H3 the interesting first |
| delta is not "reference versus no reference", because adding a reference |
| changes the packed layout, the presentation tokens, and the time origin of |
| the target stream all at once. It is "actual reference versus a |
| shape-matched control reference", which holds all three fixed and leaves |
| only the content. |
|
|
| ## Status |
|
|
| **Alpha, and deliberately narrow.** What exists is the data layer (the |
| contracts, the workspace, the verbs, and three surfaces over them) plus the |
| H3 capture tap that rides along on a render. What does not exist is anything |
| that turns a capture into a factor, or a factor into conditioning. |
|
|
| | built | not built | |
| |---|---| |
| | contracts with deterministic ids (`types.py`) | the delta engine (T3) | |
| | the workspace, export and import (`space.py`) | factorization strategies (T6+) | |
| | the verb layer (`api.py`) | the compiler (T9) | |
| | shell and agent surfaces (`cli.py`, `mcp.py`) | the rest of the node surface (T12) | |
| | the H3 backend's verified anchors (`backends/h3.py`) | | |
| | capture (T4/T5): tap + nodes built, E0 gates NOT yet run live | | |
|
|
| Unbuilt verbs raise and name the task that blocks them. They do not return |
| an empty result. In a subsystem whose output is evidence, a quiet nothing is |
| worse than a refusal, because the nothing gets written down. |
|
|
| Three alpha nodes are registered (`MAI Concept Capture Arm` / `Flush`, |
| DEC-CL-0018, and `MAI Concept Inject Delta`, DEC-CL-0020), through the pack's |
| guarded loader, so a broken alpha module cannot take the pack down. No |
| existing MAINodes behaviour or default moves. |
|
|
| ## Layering, and why it is strict |
|
|
| ``` |
| types.py CONTRACTS ONLY. Stdlib. No torch, no comfy, no H3. |
| space.py the workspace: manifests you can read, tensors you can't. |
| api.py THE VERBS. One implementation of every operation. |
| backends/ everything model-specific. base.py is the seam, h3.py is first. |
| strategies/ factorization algorithms (they arrive with their experiments). |
| |
| cli.py shell client over api.py |
| mcp.py typed agent client over api.py |
| nodes.py ComfyUI client over api.py (the capture pair, alpha) |
| ``` |
|
|
| Three surfaces, one authority. A verb that is not in `api.py` does not |
| exist, and no surface holds a rule the others cannot see. That is what makes |
| a graph, a shell and an agent interchangeable rather than three |
| reimplementations that drift. |
|
|
| `types.py` and `space.py` stay importable in a process with no torch and no |
| comfy in it, and the test suite asserts exactly that in a subprocess. The |
| point of a contract is that it is readable and writable by things that are |
| not ComfyUI. |
|
|
| ## The workspace |
|
|
| Two roots, because the two kinds of thing want different homes. |
|
|
| ``` |
| <index root> small JSON you want to browse and diff |
| SPACE.json |
| corpora/ captures/ deltas/ packs/ plans/ |
| imported/<origin space id>/... |
| <tensor root> the heavy evidence |
| <space id>/... |
| ``` |
|
|
| Defaults are `output/h3_concept` next to the renders and `<index |
| root>/tensors` for the heavy evidence (point the tensor root at a big disk |
| on a box that has one). |
| Override with `H3_CONCEPT_INDEX_DIR` and `H3_CONCEPT_TENSOR_DIR`. |
|
|
| Neither default is inside the repository. That is not tidiness: a concept |
| pack can encode a likeness, and the way that goes wrong is a research |
| artifact sitting in a working tree when somebody runs `git add -A`. |
|
|
| But the index root holds two different kinds of thing, and only one of them |
| is a result. Captures and deltas can be re-measured from a corpus and a |
| model stack. Corpora, tap specs and plans are **definitions**: they are the |
| record of which contrasts somebody chose, and no tensor reconstructs them. |
| So `space status` reports `index_root_tracked` and the corpus verbs warn |
| when the index root is not inside a git work tree. The fix is one |
| environment variable pointing at a **private** repository (or a copy of |
| `corpora/` and `plans/` into one): |
|
|
| ``` |
| export H3_CONCEPT_INDEX_DIR=~/research-private/concept_space |
| ``` |
|
|
| The default does not move (DEC-CL-0008 settled it); the warning exists |
| because losing the definitions is invisible until the day you want to run |
| the experiment again (DEC-CL-0016). |
|
|
| ### Export and import |
|
|
| An export bundles manifests and their tensors into one zip regardless of |
| which root they sat in. An import lands somebody else's space **beside** |
| yours rather than in it: |
|
|
| ``` |
| <index root>/imported/<their space id>/... |
| <tensor root>/<their space id>/... |
| ``` |
|
|
| with the origin stamped on every record. Their numbers can inform your work |
| and can never be mistaken for your own measurements. Packs marked private |
| are held back from an export unless you ask for them in as many words, and |
| every exclusion is reported with its reason — nothing is dropped silently. |
|
|
| ## Using it |
|
|
| From a shell: |
|
|
| ``` |
| python -m concept_lab.cli space init --label mine |
| python -m concept_lab.cli corpus new wave |
| python -m concept_lab.cli corpus add wave --kind video --ref alice_wave.mp4 \ |
| --label subject=alice --label motion=wave --split extract --group alice |
| python -m concept_lab.cli corpus confounds wave --target motion |
| python -m concept_lab.cli capture plan wave |
| python -m concept_lab.cli space export mine |
| ``` |
|
|
| Every command prints JSON, so a pipeline and an agent read the same bytes. |
|
|
| From an agent, over MCP: |
|
|
| ``` |
| <venv>/bin/python -m concept_lab.mcp |
| ``` |
|
|
| Same verbs, typed. Two things are deliberately absent from that surface: |
| anything that runs a model (capture costs GPU time on a shared box, so the |
| agent plans and a human launches), and exporting a private pack (a model |
| cannot prove who is asking, and export is a publishing act). An agent that |
| can measure everything and publish nothing is the right shape here. |
|
|
| ## The two checks that are cheap and worth running first |
|
|
| **`corpus confounds`** asks which other labels move exactly with the one you |
| care about. If every waving clip also smiles, then a "wave" factor is a |
| wave-and-smile factor, and no amount of solver will tell you that. The fix |
| is another clip, not another algorithm. This costs nothing and answers a |
| question that is expensive to answer after a capture. |
|
|
| **`capture plan`** costs a three-arm capture without running it: forward |
| count, tensors written, and every protocol gap the corpus carries. It says |
| plainly that it measured nothing. |
|
|
| ## Rules this subsystem tries to make structural |
|
|
| Each of these is here because a previous research program paid for it. |
|
|
| - **A delta needs a matched control.** Not "the intervention off" — a |
| control that holds every structural nuisance fixed. |
| - **Same id, different bytes is an error.** If one condition produced two |
| different results, one of the runs is not what its manifest says, and |
| keeping the newer one destroys the evidence that something is wrong. |
| - **Extraction success is not a result.** Splits are `extract`, `validate`, |
| `adversarial`, `null`, and a factor that has only seen the first one is a |
| hypothesis. |
| - **Depth and time are coordinates, not metadata.** A factor collapsed to |
| one global vector before anyone measured the layer and timestep profile |
| has thrown away the answer. |
| - **Record the stack, never infer it from a filename.** A capture without |
| its condition is a number without a condition. |
| - **A diagnostic is not a behavioural result.** A decomposition is a |
| hypothesis until it predicts output the model was not fitted on. |
| - **Nothing gets promoted quietly.** Every claim carries one of PROPOSED, |
| MEASURED, SCOPED, FAILED, RETRACTED, SUPERSEDED, OPEN. |
|
|
| ## Tests |
|
|
| ``` |
| python tests/test_concept_lab_contracts.py |
| python tests/test_concept_lab_tap.py # torch, no comfy, no GPU |
| ``` |
|
|
| Synthetic. No GPU, no models, no renders, no torch. Thirteen check groups |
| covering the import boundary, id determinism (including which fields are |
| *not* allowed to move an id, and the process launch that now belongs to |
| one), roundtrips, refusals, the collision check, confound detection, |
| export/import provenance, the H3 anchors read from the installed ComfyUI |
| source, unbuilt verbs refusing, the CLI surface, the version-control |
| warning, tensor hashing in `doctor`, and the two guards that have to fire: |
| split containment and the shape-matched control arm. |
|
|
| The tap suite is the second one and needs torch (it never imports ComfyUI): |
| six check groups over pass-through exactness, step selection, what each |
| store writes, the manifest and its id, the refusals, and the disabled arm |
| writing nothing. What it cannot check offline is the only thing that |
| matters in the end, which is why E0 exists: that a real render is |
| pixel-identical with the tap installed. |
|
|
| ## Reading order for the design |
|
|
| `__init__.py` for the layering, `types.py` for the id rules and why they are |
| shaped that way, `backends/h3.py` for the H3 anchors with their source |
| citations, `DECISIONS.md` for what has been settled and should not be |
| quietly relitigated. |
|
|
