Move source library into src/; repoint module, tool, and README paths

README.md

@@ -78,14 +78,14 @@ for a, c in [(0, 0), (0, 1), (1, 0), (1, 1)]:
 Run the full circuit verification suite against any variant:
 
 ```bash
-python eval_all.py variants/                              # 18 fitness variants (machines skipped)
-python eval_all.py neural_computer.safetensors            # the canonical file
-python eval_all.py --cpu-program variants/                # also run an assembled
+python src/eval_all.py variants/                              # 18 fitness variants (machines skipped)
+python src/eval_all.py neural_computer.safetensors            # the canonical file
+python src/eval_all.py --cpu-program variants/                # also run an assembled
                                                           # program through the
                                                           # threshold-gated CPU
 ```
 
-`eval_all.py` reads each variant's manifest, runs a gate-level fitness suite (13,900–15,900 tests per variant covering Boolean, arithmetic, ALU, control, modular, error-detection, threshold, and float circuits, including end-to-end evaluation of the composed float pipelines from the shipped wiring metadata — see the Verification table), and optionally executes a small assembled program through a manifest-sized threshold CPU plus a chained 16- or 32-bit ALU sequence on wider variants.
+`src/eval_all.py` reads each variant's manifest, runs a gate-level fitness suite (13,900–15,900 tests per variant covering Boolean, arithmetic, ALU, control, modular, error-detection, threshold, and float circuits, including end-to-end evaluation of the composed float pipelines from the shipped wiring metadata — see the Verification table), and optionally executes a small assembled program through a manifest-sized threshold CPU plus a chained 16- or 32-bit ALU sequence on wider variants.
 
 For an interactive walkthrough that exercises Boolean gates, the 8-bit ALU, mod-5 divisibility, and a CPU loop end-to-end:
 
@@ -294,10 +294,10 @@ The build tool emits one of 51 functionally distinct configurations: three data-
 Auto-generated filename: `neural_{alu|computer}{BITS}[_{MEMORY}].safetensors`. Custom address widths via `-a N` produce `_addrN`.
 
 ```bash
-python build.py --bits 32 --apply all              # neural_computer32.safetensors
-python build.py --bits 8 -m none --apply all       # neural_alu8.safetensors
-python build.py --bits 16 -m small --apply all     # neural_computer16_small.safetensors
-python build.py --bits 32 -a 6 --apply all         # neural_computer32_addr6.safetensors
+python src/build.py --bits 32 --apply all              # neural_computer32.safetensors
+python src/build.py --bits 8 -m none --apply all       # neural_alu8.safetensors
+python src/build.py --bits 16 -m small --apply all     # neural_computer16_small.safetensors
+python src/build.py --bits 32 -a 6 --apply all         # neural_computer32_addr6.safetensors
 ```
 
 To regenerate every named variant in one pass:
@@ -306,21 +306,21 @@ To regenerate every named variant in one pass:
 python tools/build_all.py
 ```
 
-This populates `variants/` with all 18 builds, quantizes each one to the smallest signed integer dtype that exactly represents its weights (~4× reduction in tensor data, with file size dominated by the safetensors header on the smaller profiles), verifies the strictly ternary weight invariant (`--ternary --strict`, so a build with any non-ternary weight fails loudly), stamps the `weight_quantization` metadata field, and runs `eval.py` on each as a sanity check.
+This populates `variants/` with all 18 builds, quantizes each one to the smallest signed integer dtype that exactly represents its weights (~4× reduction in tensor data, with file size dominated by the safetensors header on the smaller profiles), verifies the strictly ternary weight invariant (`--ternary --strict`, so a build with any non-ternary weight fails loudly), stamps the `weight_quantization` metadata field, and runs `src/eval.py` on each as a sanity check.
 
 The quantizer is also available standalone:
 
 ```bash
-python quantize.py path/to/file.safetensors           # in-place
-python quantize.py variants/                          # whole directory
-python quantize.py model.safetensors -o quantized.safetensors
-python quantize.py file.safetensors --ternary         # push toward {-1, 0, 1} weights
-python quantize.py file.safetensors --ternary --strict  # error if any weight is non-ternary
+python src/quantize.py path/to/file.safetensors           # in-place
+python src/quantize.py variants/                          # whole directory
+python src/quantize.py model.safetensors -o quantized.safetensors
+python src/quantize.py file.safetensors --ternary         # push toward {-1, 0, 1} weights
+python src/quantize.py file.safetensors --ternary --strict  # error if any weight is non-ternary
 ```
 
 Every weight and bias tensor in the canonical model fits in `int8`. The eval pipeline promotes weights to `float32` on load, so integer storage is exact and transparent.
 
-**Ternary mode.** `build.py` emits only ternary weights: identity buffers are `weight=1, bias=-1` (`H(x - 1)`), and the comparators, modular detectors, and division stages that previously required positional weights up to ±2³¹ are bit-cascaded multi-layer equivalents. With `--ternary`, the quantizer verifies this and repairs legacy files: it rewrites historical single-input `weight=±2` buffers as `weight=±1` with the bias adjusted to preserve the heaviside output for binary inputs (`H(2x - 1) ≡ H(x - 1)`), and rebuilds pre-bit-cascade modular detectors (moduli already in bit-cascade form are left untouched, routing metadata included). `--strict` fails if any weight tensor remains non-ternary. Every shipped file carries the metadata field `weight_quantization: ternary`; a repaired file with remaining violations would be stamped `ternary_partial`.
+**Ternary mode.** `src/build.py` emits only ternary weights: identity buffers are `weight=1, bias=-1` (`H(x - 1)`), and the comparators, modular detectors, and division stages that previously required positional weights up to ±2³¹ are bit-cascaded multi-layer equivalents. With `--ternary`, the quantizer verifies this and repairs legacy files: it rewrites historical single-input `weight=±2` buffers as `weight=±1` with the bias adjusted to preserve the heaviside output for binary inputs (`H(2x - 1) ≡ H(x - 1)`), and rebuilds pre-bit-cascade modular detectors (moduli already in bit-cascade form are left untouched, routing metadata included). `--strict` fails if any weight tensor remains non-ternary. Every shipped file carries the metadata field `weight_quantization: ternary`; a repaired file with remaining violations would be stamped `ternary_partial`.
 
 ---
 
@@ -347,7 +347,7 @@ Every weight and bias tensor in the canonical model fits in `int8`. The eval pip
 
 The 8-bit arithmetic and ALU tests use strategic sampling rather than the full 65,536-case sweep because exhaustive coverage at 8-bit is feasible but not necessary given that the circuits are constructed gate-by-gate. The 16-bit and 32-bit arithmetic tests sample edge cases only; full exhaustive coverage at those widths is infeasible without specialized hardware.
 
-`eval_all.py` runs the unified suite. Exit code is the number of failing variants (0 means all pass). **Testing is evaluation, not rebuilding**: `python eval_all.py variants/` scores all 18 fitness variants against the shipped weights in about two minutes (~6 s each, the composed float netlists evaluated in `NetlistEvaluator`'s leveled mode) and cleanly skips the four standalone machines. Rebuilding the models (`tools/build_all.py`, ~50 min for all 18) is a separate step, needed only when the circuit constructions in `build.py` change; routine verification never rebuilds. The batched evaluator is population-safe: every chained intermediate (carry, borrow, mux select) is computed per population slot, so `tools/prune_weights.py`'s parallel fitness screens are exact rather than slot-0 approximations.
+`src/eval_all.py` runs the unified suite. Exit code is the number of failing variants (0 means all pass). **Testing is evaluation, not rebuilding**: `python src/eval_all.py variants/` scores all 18 fitness variants against the shipped weights in about two minutes (~6 s each, the composed float netlists evaluated in `NetlistEvaluator`'s leveled mode) and cleanly skips the four standalone machines. Rebuilding the models (`tools/build_all.py`, ~50 min for all 18) is a separate step, needed only when the circuit constructions in `src/build.py` change; routine verification never rebuilds. The batched evaluator is population-safe: every chained intermediate (carry, borrow, mux select) is computed per population slot, so `tools/prune_weights.py`'s parallel fitness screens are exact rather than slot-0 approximations.
 
 ---
 
@@ -360,11 +360,11 @@ The minimal member of the family: a Turing-complete computer with **no instructi
 - Circuits (all wiring shipped as `.inputs` metadata): an 8-bit two's-complement subtractor, the branch neuron, a `PC + 3` incrementer, a branch mux, and the packed 256-row memory.
 
 ```bash
-python build.py --apply subleq          # -> variants/neural_subleq8.safetensors
-python machines.py subleq               # exhaustive datapath + lockstep programs
+python src/build.py --apply subleq          # -> variants/neural_subleq8.safetensors
+python src/machines.py subleq               # exhaustive datapath + lockstep programs
 ```
 
-`machines.py subleq` evaluates the datapath **from the shipped wiring metadata** over all 65,536 operand pairs (result and branch decision both exhaustive), checks the PC mux, and runs a program suite (clear, negate-copy, add-by-double-negation, countdown loop) in full-state lockstep against a reference emulator. Third-party SUBLEQ toolchains target this machine directly once the `0xFF` halt convention is mapped.
+`src/machines.py subleq` evaluates the datapath **from the shipped wiring metadata** over all 65,536 operand pairs (result and branch decision both exhaustive), checks the PC mux, and runs a program suite (clear, negate-copy, add-by-double-negation, countdown loop) in full-state lockstep against a reference emulator. Third-party SUBLEQ toolchains target this machine directly once the `0xFF` halt convention is mapped.
 
 ---
 
@@ -382,10 +382,10 @@ The most capable member: a RISC-V CPU whose entire datapath is ternary threshold
 Signed comparisons ride the unsigned bit-cascade with sign bits complemented through NOT gates; SLL uses the barrel shifter, SRL is bit-reversal wiring over it, SRA a gate mux over the complement form. Instruction decode, immediate extraction, register-file indexing, and PC sequencing are fixed wiring, per the family convention.
 
 ```bash
-python build.py --apply rv32                            # build the file
-python quantize.py variants/neural_rv32.safetensors --ternary --strict
-python machines.py rv32                                 # eight-program lockstep suite
-python machines.py rv32-c                               # stock-compiler C, end to end
+python src/build.py --apply rv32                            # build the file
+python src/quantize.py variants/neural_rv32.safetensors --ternary --strict
+python src/machines.py rv32                                 # eight-program lockstep suite
+python src/machines.py rv32-c                               # stock-compiler C, end to end
 ```
 
 **Running compiled C.** `machines.py rv32-c` compiles a freestanding C program (gcd, Fibonacci, insertion sort; `rv32im`, so real `mul`/`rem`) with an unmodified clang rv32im toolchain, loads the relocatable object with an in-repo loader (no external linker — it resolves the R_RISCV relocations of one translation unit and lays the sections out flat), executes it on the threshold CPU, and checks the return value against the value computed natively. The program retires in ~300 instructions and matches exactly. Stock `rv32im` toolchains (gcc, clang, rustc) emit this ISA. Unfinished float work — subnormals, FMA, and the FCVT rounding-mode field — is tracked in `todo.md`.
@@ -439,9 +439,9 @@ write is gated by NOT halt), so iterating past HALT is harmless.
   conductance mismatch (bit-exact through σ_G = 0.10).
 
 ```bash
-python matrix8.py build          # compile + save variants/neural_matrix8.safetensors
-python matrix8.py verify         # exhaustive equality vs the gate graph and integer reference
-python matrix8.py analog         # margin measurement + read-noise + conductance-mismatch sweeps
+python src/matrix8.py build          # compile + save variants/neural_matrix8.safetensors
+python src/matrix8.py verify         # exhaustive equality vs the gate graph and integer reference
+python src/matrix8.py analog         # margin measurement + read-noise + conductance-mismatch sweeps
 ```
 
 Because the transition is a fixed matrix stack proven equal to the gate-graph
@@ -486,9 +486,9 @@ The equality is machine-checked rather than observed on one run:
   closing the loop across two generations.
 
 ```bash
-python constructor8.py build     # emit variants/neural_subleq8io.safetensors
-python constructor8.py verify    # host soundness + codec round-trip + constructor on all 3 backends
-python constructor8.py self      # full self-reproduction on the threshold matrices, then gen-2 boot
+python src/constructor8.py build     # emit variants/neural_subleq8io.safetensors
+python src/constructor8.py verify    # host soundness + codec round-trip + constructor on all 3 backends
+python src/constructor8.py self      # full self-reproduction on the threshold matrices, then gen-2 boot
 ```
 
 A program running on the processor emits the exact tensor file that defines
@@ -672,15 +672,16 @@ Loss components: BCE on output bits, BCE on extracted A and B bits (2× weight),
 neural_computer.safetensors         canonical model (32-bit, 64 KB, ~8.61M params)
 variants/                           18 fitness variants + 4 standalone machines
                                     (neural_subleq8, neural_rv32, neural_matrix8, neural_subleq8io)
-build.py                            generator (one safetensors per invocation; also `subleq`, `rv32`)
-quantize.py                         min integer dtypes + ternary verification/repair
-eval.py                             gate-level fitness suite, NetlistEvaluator, float oracles, reference CPU
-eval_all.py                         variant-agnostic harness + manifest-sized threshold CPU
-machines.py                         neural_subleq8 + neural_rv32 runtimes, references, assemblers,
-                                    RV32 object loader, and the test suites (subleq / rv32 / rv32-c)
-matrix8.py                          compiles the CPU to a recurrent ternary matrix stack; the
-                                    exhaustive equality suite and the analog crossbar simulation
-constructor8.py                     the neural_subleq8io host, the recipe codec, and the universal
+src/                                the library (run scripts as `python src/<name>.py`)
+  ├── build.py                      generator (one safetensors per invocation; also `subleq`, `rv32`)
+  ├── quantize.py                   min integer dtypes + ternary verification/repair
+  ├── eval.py                       gate-level fitness suite, NetlistEvaluator, float oracles, reference CPU
+  ├── eval_all.py                   variant-agnostic harness + manifest-sized threshold CPU
+  ├── machines.py                   neural_subleq8 + neural_rv32 runtimes, references, assemblers,
+  │                                 RV32 object loader, and the test suites (subleq / rv32 / rv32-c)
+  ├── matrix8.py                    compiles the CPU to a recurrent ternary matrix stack; the
+  │                                 exhaustive equality suite and the analog crossbar simulation
+  └── constructor8.py               the neural_subleq8io host, the recipe codec, and the universal
                                     constructor / self-reproduction suite
 tools/                              build_all.py (build + quantize + verify every profile),
                                     cpu_programs.py (assembler + CPU program suite), test_cpu.py

build.py → src/build.py

@@ -112,7 +112,7 @@ from safetensors import safe_open
 from safetensors.torch import save_file
 
 
-MODEL_DIR = Path(__file__).resolve().parent
+MODEL_DIR = Path(__file__).resolve().parent.parent  # repo root; this module lives in src/
 
 
 def get_model_path(bits: int = 8, memory_profile: str = None, addr_bits: int = None) -> Path:
@@ -140,7 +140,7 @@ def get_model_path(bits: int = 8, memory_profile: str = None, addr_bits: int = N
 
 
 MODEL_PATH = MODEL_DIR / "neural_computer8.safetensors"
-MANIFEST_PATH = Path(__file__).resolve().parent / "tensors.txt"
+MANIFEST_PATH = Path(__file__).resolve().parent.parent / "tensors.txt"
 
 DEFAULT_ADDR_BITS = 16
 DEFAULT_MEM_BYTES = 1 << DEFAULT_ADDR_BITS
@@ -4074,7 +4074,7 @@ def _load_routing_table() -> Dict[str, Any]:
     global _ROUTING_TABLE_CACHE
     if _ROUTING_TABLE_CACHE is not None:
         return _ROUTING_TABLE_CACHE
-    path = Path(__file__).parent / "routing" / "routing.json"
+    path = Path(__file__).parent.parent / "routing" / "routing.json"
     if not path.exists():
         _ROUTING_TABLE_CACHE = {}
         return _ROUTING_TABLE_CACHE

constructor8.py → src/constructor8.py

@@ -58,7 +58,7 @@ from safetensors.torch import save_file
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-REPO = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # repo root; this module lives in src/
 MODEL_PATH = os.path.join(REPO, "variants", "neural_subleq8io.safetensors")
 
 from matrix8 import Net, compile_net  # machine-1 compiler, reused verbatim

eval.py → src/eval.py

@@ -30,7 +30,7 @@ import torch
 from safetensors import safe_open
 
 
-MODEL_PATH = os.path.join(os.path.dirname(__file__), "neural_computer.safetensors")
+MODEL_PATH = os.path.join(os.path.dirname(os.path.dirname(__file__)), "neural_computer.safetensors")  # repo root; this module lives in src/
 
 
 @dataclass
@@ -433,7 +433,7 @@ def run_smoke_test() -> int:
           f"LOOP={final.mem[0x0109]}, cycles={cycles}")
 
     print("Running threshold-weight implementation (GenericThresholdCPU, 1 KB)...")
-    path = os.path.join(os.path.dirname(__file__), "variants",
+    path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "variants",
                         "neural_computer8_small.safetensors")
     tensors = {}
     with safe_open(path, framework="pt") as f:

machines.py → src/machines.py

@@ -209,7 +209,7 @@ def load(obj: bytes, base: int = 0, mem_size: int = 65536,
 # ============================================================================
 # neural_rv32: assembler, reference emulator, threshold runtime
 # ============================================================================
-RV32_MODEL = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+RV32_MODEL = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
                      "variants", "neural_rv32.safetensors")
 MASK32 = 0xFFFFFFFF
 MMIO_CONSOLE = 0xFF00
@@ -1092,7 +1092,7 @@ class Rv32ThresholdCPU:
 # ============================================================================
 # neural_subleq8: threshold runtime, reference, assembler
 # ============================================================================
-SUBLEQ_MODEL = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+SUBLEQ_MODEL = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
                      "variants", "neural_subleq8.safetensors")
 HALT_PC = 0xFF
 

matrix8.py → src/matrix8.py

@@ -62,7 +62,7 @@ from safetensors.torch import save_file
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-REPO = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # repo root; this module lives in src/
 MODEL_PATH = os.path.join(REPO, "variants", "neural_matrix8.safetensors")
 GATE_MODEL_PATH = os.path.join(REPO, "variants", "neural_computer8_registers.safetensors")
 

tools/build_all.py

@@ -52,7 +52,7 @@ def build_variant(bits: int, profile: str) -> Path:
     out = OUT_DIR / variant_filename(bits, profile)
     shutil.copy2(SEED, out)
     cmd = [
-        sys.executable, str(ROOT / "build.py"),
+        sys.executable, str(ROOT / "src" / "build.py"),
         "--bits", str(bits),
         "-m", profile,
         "--apply",
@@ -71,7 +71,7 @@ def quantize_variant(path: Path) -> tuple[int, int]:
     dtype, verifies the strictly ternary weight invariant, and stamps the
     weight_quantization metadata field. Returns (bytes_before, bytes_after).
     """
-    rc, log = run([sys.executable, str(ROOT / "quantize.py"), str(path),
+    rc, log = run([sys.executable, str(ROOT / "src" / "quantize.py"), str(path),
                    "--ternary", "--strict"], timeout=300)
     if rc != 0:
         raise RuntimeError(f"quantize failed for {path.name}:\n{log[-800:]}")
@@ -108,7 +108,7 @@ def measure_variant(path: Path) -> dict:
 def eval_variant(path: Path, device: str = "cpu", timeout: int = 600) -> dict:
     """Run eval.py against a variant and parse fitness."""
     cmd = [
-        sys.executable, str(ROOT / "eval.py"),
+        sys.executable, str(ROOT / "src" / "eval.py"),
         "--model", str(path),
         "--device", device,
         "--quiet",

tools/play.py

@@ -26,7 +26,7 @@ import torch
 from safetensors import safe_open
 
 REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # this file lives in tools/
-sys.path.insert(0, REPO)
+sys.path.insert(0, os.path.join(REPO, "src"))   # eval_all lives in src/
 
 # Reuse the variant-aware CPU runtime from eval_all.py
 from eval_all import GenericThresholdCPU, builtin_program

tools/prune_weights.py

@@ -13,7 +13,7 @@ import time
 import torch
 from safetensors.torch import save_file
 
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))  # repo root
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))  # src/ at repo root
 from eval import BatchedFitnessEvaluator, create_population, load_model
 
 torch.manual_seed(0)

tools/test_cpu.py

@@ -21,7 +21,7 @@ import torch
 from safetensors import safe_open
 
 REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # this file lives in tools/
-sys.path.insert(0, REPO)                    # eval_all lives at the repo root
+sys.path.insert(0, os.path.join(REPO, "src"))   # eval_all lives in src/
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))  # cpu_programs is a sibling
 from eval_all import GenericThresholdCPU, get_manifest
 from cpu_programs import SUITE