pre-reasoning 2.5.2__tar.gz → 2.5.4__tar.gz

{pre_reasoning-2.5.2 → pre_reasoning-2.5.4}/MANIFEST.in

@@ -1,5 +1,7 @@
-include pre_reasoning/checkpoints/*.safetensors
-exclude checkpoints/*.pt
+include pre_reasoning/checkpoints/*.safetensors
+include derive_expert/weights/*.safetensors
+exclude checkpoints/*.pt
+exclude derive_expert/weights/*.pt
 prune __pycache__
 global-exclude *.py[cod]
 global-exclude .DS_Store

{pre_reasoning-2.5.2/pre_reasoning.egg-info → pre_reasoning-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pre-reasoning
-Version: 2.5.2
+Version: 2.5.4
 Summary: 3M-parameter neural pre-reasoning engine for grounding LLMs before they answer.
 Author: Luis Lozano, Dr. Shannon (Mia Labs AI co-researcher), Mia Labs
 License-Expression: MIT
@@ -25,9 +25,9 @@ Dynamic: license-file
 
 # Pre-Reasoning
 
-Pre-Reasoning is a Mia Labs structural analysis engine that grounds an LLM before it answers. It uses a 3M-parameter neural model (V3) to surface dependencies, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.
+Pre-Reasoning is a Mia Labs structural analysis engine that grounds an LLM before it answers. It uses a 3M-parameter neural perception model plus a bundled tiny derive expert to surface dependencies, derived assumptions, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.
 
-The engine ships with bundled safetensors weights and torch -- install and run, no downloads needed.
+The engine ships with bundled weights and declares its torch dependency -- install and run, no model download needed.
 
 ## What It Does
 
@@ -39,6 +39,8 @@ Given natural-language problem text, the engine returns:
 - CYCLES: circular dependencies that cannot be solved sequentially
 - CONFLICTS: competing positions or incompatible entities
 - REQUIREMENTS: numeric or threshold requirements
+- DERIVED ASSUMPTIONS: transitive dependency assumptions inferred by the tiny derive expert
+- BLOCK OUTPUT: direct and derived structural blocks used by the graph reasoner
 
 ## Install
 
@@ -59,6 +61,7 @@ from pre_reasoning import analyze, pulse
 
 result = analyze("Frontend depends on API. API depends on Auth.")
 print(result["trace"])
+print(result["derived_assumptions"])
 
 check = pulse(
     "Frontend depends on API. API depends on Auth.",
@@ -93,9 +96,11 @@ These are product-research notes, not benchmark claims.
 
 ```text
 User text
-  -> V3 neural perception (3M params, safetensors)
+  -> neural perception (3M params, safetensors)
   -> neural findings converted to structural blocks
-  -> V2 heuristic graph analysis
+  -> tiny derive expert infers transitive assumptions
+  -> derived assumptions appended as dependency blocks
+  -> graph reasoning
   -> structural trace
 ```
 
@@ -104,19 +109,24 @@ User text
 | Path | Purpose |
 |---|---|
 | `pre_reasoning/` | Installable Python package and CLI entry point |
-| `pre_reasoning/inference.py` | 3M-parameter V3 neural perception layer |
-| `pre_reasoning/heuristic.py` | Deterministic graph-reasoning core (fallback) |
-| `pre_reasoning/pre_reasoning_v2_5.py` | v2.5 orchestrator: V3 neural + heuristic |
-| `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` | Bundled V3 weights (11MB) |
+| `pre_reasoning/inference.py` | 3M-parameter neural perception layer |
+| `pre_reasoning/heuristic.py` | Graph-reasoning core |
+| `pre_reasoning/pre_reasoning_v2_5_2.py` | Default v2.5.4 engine: neural perception + derive expert + graph reasoning |
+| `pre_reasoning/pre_reasoning_v2_5.py` | Legacy v2.5 engine: neural perception + graph reasoning |
+| `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` | Bundled model weights (11MB) |
+| `derive_expert/` | Tiny derive expert used for transitive-closure enrichment |
+| `derive_expert/weights/thin_expert_d128L3.safetensors` | Bundled derive expert weights (2.5MB) |
 | `examples/` | Runnable usage examples |
 | `tests/` | Pytest suite |
 | `skill/SKILL.md` | Agent skill descriptor for model adoption |
-| `CLAUDE.md` | Optional Claude Code hooks configuration |
+| `hooks/` | Claude Code before/after hooks for enforced pre-reasoning |
+| `INSTALL.md` | Manual install and hook setup guide |
+| `CLAUDE.md` | Claude Code adoption and grounding-hook guide |
 | `WHY_TRACES_WORK.md` | Literature connection, 9 cited papers |
 
 ## Weights Policy
 
-The raw training checkpoint is not part of the release. The package bundles `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors`, a weights-only inference artifact. It ships no training metadata: no optimizer state, LR schedules, step counters, RNG state, training config, or raw checkpoint provenance.
+The raw training checkpoint is not part of the release. The package bundles `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` for neural perception and `derive_expert/weights/thin_expert_d128L3.safetensors` for the tiny derive expert. These are inference artifacts. They ship no optimizer state, LR schedules, step counters, RNG state, training config, or raw checkpoint provenance.
 
 ## License
 

{pre_reasoning-2.5.2 → pre_reasoning-2.5.4}/README.md

@@ -1,8 +1,8 @@
 # Pre-Reasoning
 
-Pre-Reasoning is a Mia Labs structural analysis engine that grounds an LLM before it answers. It uses a 3M-parameter neural model (V3) to surface dependencies, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.
-
-The engine ships with bundled safetensors weights and torch -- install and run, no downloads needed.
+Pre-Reasoning is a Mia Labs structural analysis engine that grounds an LLM before it answers. It uses a 3M-parameter neural perception model plus a bundled tiny derive expert to surface dependencies, derived assumptions, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.
+
+The engine ships with bundled weights and declares its torch dependency -- install and run, no model download needed.
 
 ## What It Does
 
@@ -12,8 +12,10 @@ Given natural-language problem text, the engine returns:
 - UNLOCK SEQUENCE: a dependency-aware resolution order
 - PARALLEL WORK: independent items that can proceed now
 - CYCLES: circular dependencies that cannot be solved sequentially
-- CONFLICTS: competing positions or incompatible entities
-- REQUIREMENTS: numeric or threshold requirements
+- CONFLICTS: competing positions or incompatible entities
+- REQUIREMENTS: numeric or threshold requirements
+- DERIVED ASSUMPTIONS: transitive dependency assumptions inferred by the tiny derive expert
+- BLOCK OUTPUT: direct and derived structural blocks used by the graph reasoner
 
 ## Install
 
@@ -32,8 +34,9 @@ pip install -e .
 ```python
 from pre_reasoning import analyze, pulse
 
-result = analyze("Frontend depends on API. API depends on Auth.")
-print(result["trace"])
+result = analyze("Frontend depends on API. API depends on Auth.")
+print(result["trace"])
+print(result["derived_assumptions"])
 
 check = pulse(
     "Frontend depends on API. API depends on Auth.",
@@ -67,31 +70,38 @@ These are product-research notes, not benchmark claims.
 ## Architecture
 
 ```text
-User text
-  -> V3 neural perception (3M params, safetensors)
-  -> neural findings converted to structural blocks
-  -> V2 heuristic graph analysis
-  -> structural trace
-```
+User text
+  -> neural perception (3M params, safetensors)
+  -> neural findings converted to structural blocks
+  -> tiny derive expert infers transitive assumptions
+  -> derived assumptions appended as dependency blocks
+  -> graph reasoning
+  -> structural trace
+```
 
 ## File Map
 
 | Path | Purpose |
 |---|---|
 | `pre_reasoning/` | Installable Python package and CLI entry point |
-| `pre_reasoning/inference.py` | 3M-parameter V3 neural perception layer |
-| `pre_reasoning/heuristic.py` | Deterministic graph-reasoning core (fallback) |
-| `pre_reasoning/pre_reasoning_v2_5.py` | v2.5 orchestrator: V3 neural + heuristic |
-| `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` | Bundled V3 weights (11MB) |
-| `examples/` | Runnable usage examples |
-| `tests/` | Pytest suite |
-| `skill/SKILL.md` | Agent skill descriptor for model adoption |
-| `CLAUDE.md` | Optional Claude Code hooks configuration |
-| `WHY_TRACES_WORK.md` | Literature connection, 9 cited papers |
+| `pre_reasoning/inference.py` | 3M-parameter neural perception layer |
+| `pre_reasoning/heuristic.py` | Graph-reasoning core |
+| `pre_reasoning/pre_reasoning_v2_5_2.py` | Default v2.5.4 engine: neural perception + derive expert + graph reasoning |
+| `pre_reasoning/pre_reasoning_v2_5.py` | Legacy v2.5 engine: neural perception + graph reasoning |
+| `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` | Bundled model weights (11MB) |
+| `derive_expert/` | Tiny derive expert used for transitive-closure enrichment |
+| `derive_expert/weights/thin_expert_d128L3.safetensors` | Bundled derive expert weights (2.5MB) |
+| `examples/` | Runnable usage examples |
+| `tests/` | Pytest suite |
+| `skill/SKILL.md` | Agent skill descriptor for model adoption |
+| `hooks/` | Claude Code before/after hooks for enforced pre-reasoning |
+| `INSTALL.md` | Manual install and hook setup guide |
+| `CLAUDE.md` | Claude Code adoption and grounding-hook guide |
+| `WHY_TRACES_WORK.md` | Literature connection, 9 cited papers |
 
 ## Weights Policy
 
-The raw training checkpoint is not part of the release. The package bundles `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors`, a weights-only inference artifact. It ships no training metadata: no optimizer state, LR schedules, step counters, RNG state, training config, or raw checkpoint provenance.
+The raw training checkpoint is not part of the release. The package bundles `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` for neural perception and `derive_expert/weights/thin_expert_d128L3.safetensors` for the tiny derive expert. These are inference artifacts. They ship no optimizer state, LR schedules, step counters, RNG state, training config, or raw checkpoint provenance.
 
 ## License
 

pre_reasoning-2.5.4/derive_expert/__init__.py

@@ -0,0 +1,36 @@
+"""
+derive-expert
+=============
+
+Transitive-closure / assumption-derivation with the bundled ThinExpert NN.
+
+Quick start::
+
+    from derive_expert import derive_assumptions, derive_report, strategy_available
+
+    print(strategy_available())
+    # {'nn': True, 'bfs': False, 'error': None}
+
+    pairs = derive_assumptions([("auth", "session"), ("session", "dashboard")])
+    # [('auth', 'dashboard')]
+
+    report = derive_report([("A", "B"), ("B", "C"), ("C", "D")])
+    # {'derived': [('A','C'),('A','D'),('B','D')], 'strategy': 'nn', ...}
+
+See derive_expert.core for full documentation.
+"""
+
+from derive_expert.core import (
+    derive_assumptions,
+    derive_report,
+    strategy_available,
+)
+
+__all__ = [
+    "derive_assumptions",
+    "derive_report",
+    "strategy_available",
+]
+
+__version__ = "0.1.0"
+__author__  = "Mia Labs / Dr. Shannon"

pre_reasoning-2.5.4/derive_expert/core.py

@@ -0,0 +1,276 @@
+"""
+derive_expert.core
+==================
+
+Public API for the derive-expert package.
+
+NN STRATEGY
+-----------
+The package uses ThinExpert, a 625K-param causal transformer, 6/6 on its
+benchmark bar set. Torch and bundled safetensors weights are required. There is no
+availability fallback: if the NN cannot load or the graph exceeds the model's
+10-entity window, public derive calls fail visibly.
+
+The surrounding pre-reasoning engine feeds the expert small 2-hop windows and
+uses exact graph traversal only as a verifier/guard for those windows, not as a
+replacement for a missing expert.
+
+Public surface
+--------------
+    derive_assumptions(edges)  -> list[tuple[str, str]]
+    derive_report(edges)       -> dict
+    strategy_available()       -> dict   (probe without running inference)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Locate bundled weights
+# ---------------------------------------------------------------------------
+_WEIGHTS_PATH = Path(__file__).resolve().parent / "weights" / "thin_expert_d128L3.safetensors"
+
+
+# ---------------------------------------------------------------------------
+# Lazy NN model singleton
+# ---------------------------------------------------------------------------
+_nn_model = None          # ThinExpert instance or None
+_nn_load_attempted = False
+
+
+def _try_load_nn():
+    """
+    Load ThinExpert once. Torch and bundled safetensors weights are required;
+    failures are raised instead of silently changing strategy.
+    """
+    global _nn_model, _nn_load_attempted
+    if _nn_load_attempted:
+        if _nn_model is None:
+            raise RuntimeError("derive-expert: NN load was attempted but no model is available")
+        return
+    _nn_load_attempted = True
+
+    from derive_expert.model import TORCH_AVAILABLE, ThinExpert
+    if not TORCH_AVAILABLE:
+        raise RuntimeError("derive-expert: torch is required for ThinExpert")
+
+    if not _WEIGHTS_PATH.exists():
+        raise FileNotFoundError(f"derive-expert: weights not found at {_WEIGHTS_PATH}")
+
+    from safetensors.torch import load_file
+    m = ThinExpert()
+    sd = load_file(str(_WEIGHTS_PATH), device="cpu")
+    m.load_state_dict(sd)
+    m.eval()
+    _nn_model = m
+    param_count = sum(p.numel() for p in m.parameters())
+    logger.info(
+        "derive-expert: ThinExpert loaded (%s params) from %s",
+        f"{param_count:,}",
+        _WEIGHTS_PATH,
+    )
+
+
+# ---------------------------------------------------------------------------
+# NN path (uses loaded ThinExpert)
+# ---------------------------------------------------------------------------
+
+def _nn_derive(
+    int_edges: List[Tuple[int, int]],
+    n_entities: int,
+    direct_set: Set[Tuple[int, int]],
+    id_to_name: Dict[int, str],
+) -> Tuple[List[Tuple[str, str]], str]:
+    """
+    Run NN inference and return (derived_pairs_str, strategy_label).
+    """
+    from derive_expert.model import (
+        BOS, ENT_OFFSET, SEP,
+        free_run, parse_output,
+    )
+
+    edge_toks = [
+        tok
+        for a, b in sorted(int_edges)
+        for tok in (ENT_OFFSET + a, ENT_OFFSET + b)
+    ]
+    inp = [BOS] + edge_toks + [SEP]
+
+    gen = free_run(_nn_model, inp, device="cpu")
+    has_derived, derived_int_pairs = parse_output(gen)
+
+    if not has_derived:
+        return [], "nn"
+
+    result: List[Tuple[str, str]] = []
+    for a, b in sorted(derived_int_pairs):
+        if (a, b) not in direct_set and a in id_to_name and b in id_to_name:
+            result.append((id_to_name[a], id_to_name[b]))
+
+    return result, "nn"
+
+
+# ---------------------------------------------------------------------------
+# Shared edge-parsing helper
+# ---------------------------------------------------------------------------
+
+def _parse_edges(
+    edges: List[Tuple[str, str]],
+) -> Tuple[
+    List[Tuple[int, int]],
+    int,
+    Set[Tuple[int, int]],
+    Dict[int, str],
+]:
+    """
+    Map string entity names to contiguous integer ids.
+
+    Returns:
+        int_edges, n_entities, direct_set, id_to_name
+    """
+    seen: Dict[str, int] = {}
+    ordered: List[str] = []
+    for src, tgt in edges:
+        for name in (src, tgt):
+            if name not in seen:
+                seen[name] = len(seen)
+                ordered.append(name)
+
+    n_entities = len(seen)
+    id_to_name = {i: name for i, name in enumerate(ordered)}
+
+    int_edges: List[Tuple[int, int]] = []
+    direct_set: Set[Tuple[int, int]] = set()
+    for src, tgt in edges:
+        a, b = seen[src], seen[tgt]
+        int_edges.append((a, b))
+        direct_set.add((a, b))
+
+    return int_edges, n_entities, direct_set, id_to_name
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def derive_assumptions(
+    edges: List[Tuple[str, str]],
+) -> List[Tuple[str, str]]:
+    """
+    Given directed dependency edges as (src_name, tgt_name) string tuples,
+    return the transitively implied (a, c) pairs reachable in >=2 hops that
+    are NOT already direct edges.
+
+    NN STRATEGY:
+      - ThinExpert (learned, ~625K params) is required.
+      - The graph must fit the model's 10-entity window.
+      - No availability fallback is used.
+
+    Args:
+        edges: e.g. [("auth", "session"), ("session", "dashboard")]
+               Order within the list does not matter.
+
+    Returns:
+        Sorted list of (src_name, tgt_name) derived pairs.
+        Returns [] for an empty graph or a graph with no multi-hop paths.
+
+    Examples:
+        >>> derive_assumptions([("A","B"), ("B","C")])
+        [('A', 'C')]
+        >>> derive_assumptions([])
+        []
+        >>> derive_assumptions([("A","B"), ("A","C"), ("B","D"), ("C","D")])
+        [('A', 'D')]
+    """
+    if not edges:
+        return []
+
+    int_edges, n_entities, direct_set, id_to_name = _parse_edges(edges)
+
+    from derive_expert.model import N_ENTITIES as MODEL_CAP
+
+    if n_entities > MODEL_CAP:
+        raise ValueError(
+            f"derive-expert: {n_entities} entities exceeds ThinExpert cap of {MODEL_CAP}"
+        )
+
+    _try_load_nn()
+    result, _ = _nn_derive(int_edges, n_entities, direct_set, id_to_name)
+
+    return result
+
+
+def derive_report(
+    edges: List[Tuple[str, str]],
+) -> Dict:
+    """
+    Like derive_assumptions(), but returns a richer dict so the caller can
+    inspect which strategy was used and basic stats.
+
+    Returns a dict with keys:
+        derived   : list[tuple[str, str]]  — the derived pairs
+        strategy  : str                    — "nn" | "none"
+        n_entities: int                    — number of distinct named entities
+        n_direct  : int                    — number of direct edges supplied
+        n_derived : int                    — len(derived)
+
+    Examples:
+        >>> derive_report([("A","B"), ("B","C")])
+        {'derived': [('A', 'C')], 'strategy': 'nn', 'n_entities': 3, 'n_direct': 2, 'n_derived': 1}
+    """
+    if not edges:
+        return {
+            "derived":    [],
+            "strategy":   "none",
+            "n_entities": 0,
+            "n_direct":   0,
+            "n_derived":  0,
+        }
+
+    int_edges, n_entities, direct_set, id_to_name = _parse_edges(edges)
+
+    from derive_expert.model import N_ENTITIES as MODEL_CAP
+
+    if n_entities > MODEL_CAP:
+        raise ValueError(
+            f"derive-expert: {n_entities} entities exceeds ThinExpert cap of {MODEL_CAP}"
+        )
+
+    _try_load_nn()
+    derived, strategy = _nn_derive(int_edges, n_entities, direct_set, id_to_name)
+
+    return {
+        "derived":    derived,
+        "strategy":   strategy,
+        "n_entities": n_entities,
+        "n_direct":   len(int_edges),
+        "n_derived":  len(derived),
+    }
+
+
+def strategy_available() -> Dict[str, bool]:
+    """
+    Probe whether ThinExpert can load.
+
+    Returns:
+        {
+            "nn":  True/False  — torch installed + weights found
+            "bfs": False       — no availability fallback
+        }
+    """
+    error = None
+    try:
+        _try_load_nn()
+    except Exception as exc:
+        error = str(exc)
+    return {
+        "nn":  _nn_model is not None,
+        "bfs": False,
+        "error": error,
+    }

pre_reasoning-2.5.4/derive_expert/model.py

@@ -0,0 +1,186 @@
+"""
+derive_expert.model
+===================
+
+ThinExpert — a tiny causal transformer (d=128, L=3, H=4, ~625K params) trained
+to solve the transitive-closure / assumption-derivation task over up to 10 named
+entities.
+
+Architecture is fixed to match the WINNER checkpoint
+(thin_expert_d128L3.safetensors).
+Do NOT change any constant here without retraining.
+
+This module is intentionally free of public API surface — use derive_expert.core.
+
+Constants:
+    D_MODEL=128, N_LAYERS=3, N_HEADS=4
+    VOCAB=16  (PAD=0 BOS=1 EOS=2 SEP=3 HAS_YES=4 HAS_NO=5 ENT_OFFSET=6)
+    N_ENTITIES=10  (model hard limit)
+    MAX_SEQ=200, MAX_GEN=150
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+# ---------------------------------------------------------------------------
+# Attempt torch import. core.py requires this to be available for public
+# derive calls; stubs below only keep import errors explicit and controlled.
+# ---------------------------------------------------------------------------
+try:
+    import torch
+    import torch.nn as nn
+    _TORCH_OK = True
+except ImportError:
+    _TORCH_OK = False
+
+# ── Model constants (must match checkpoint exactly) ─────────────────────────
+D_MODEL    = 128
+N_LAYERS   = 3
+N_HEADS    = 4
+DROPOUT    = 0.0
+
+PAD        = 0
+BOS        = 1
+EOS        = 2
+SEP        = 3
+HAS_YES    = 4
+HAS_NO     = 5
+ENT_OFFSET = 6
+N_ENTITIES = 10          # hard model cap
+VOCAB      = ENT_OFFSET + N_ENTITIES  # 16
+
+MAX_SEQ    = 200
+MAX_GEN    = 150
+
+# Exported so core.py can reference them without importing torch directly
+__all__ = [
+    "ThinExpert", "Block",
+    "free_run", "parse_output",
+    "TORCH_AVAILABLE",
+    "D_MODEL", "N_LAYERS", "N_HEADS",
+    "PAD", "BOS", "EOS", "SEP", "HAS_YES", "HAS_NO",
+    "ENT_OFFSET", "N_ENTITIES", "VOCAB",
+    "MAX_SEQ", "MAX_GEN",
+]
+
+TORCH_AVAILABLE: bool = _TORCH_OK
+
+
+if _TORCH_OK:
+    class Block(nn.Module):
+        """Single causal self-attention + FFN block."""
+
+        def __init__(self) -> None:
+            super().__init__()
+            self.ln1  = nn.LayerNorm(D_MODEL)
+            self.ln2  = nn.LayerNorm(D_MODEL)
+            self.attn = nn.MultiheadAttention(
+                D_MODEL, N_HEADS, dropout=DROPOUT, batch_first=True
+            )
+            self.ff = nn.Sequential(
+                nn.Linear(D_MODEL, D_MODEL * 4),
+                nn.GELU(),
+                nn.Linear(D_MODEL * 4, D_MODEL),
+            )
+
+        def forward(self, x: "torch.Tensor") -> "torch.Tensor":
+            T    = x.size(1)
+            mask = torch.triu(torch.full((T, T), float("-inf"), device=x.device), 1)
+            h    = self.ln1(x)
+            h, _ = self.attn(h, h, h, attn_mask=mask, is_causal=False)
+            x    = x + h
+            return x + self.ff(self.ln2(x))
+
+    class ThinExpert(nn.Module):
+        """
+        Causal transformer for transitive-closure inference.
+
+        Input token sequence:
+            [BOS] <edge_pairs sorted> [SEP]
+        where each edge (a, b) is encoded as two tokens:
+            ENT_OFFSET+a  ENT_OFFSET+b
+
+        Output greedy-decoded sequence:
+            HAS_YES <derived_pair_tokens...>   -- if derived pairs exist
+            HAS_NO                              -- if no derived pairs
+
+        Instantiate then call load_state_dict with the bundled checkpoint.
+        """
+
+        def __init__(self) -> None:
+            super().__init__()
+            self.tok    = nn.Embedding(VOCAB, D_MODEL, padding_idx=PAD)
+            self.pos    = nn.Embedding(MAX_SEQ, D_MODEL)
+            self.blocks = nn.Sequential(*[Block() for _ in range(N_LAYERS)])
+            self.ln     = nn.LayerNorm(D_MODEL)
+            self.head   = nn.Linear(D_MODEL, VOCAB, bias=False)
+
+        def forward(self, ids: "torch.Tensor") -> "torch.Tensor":
+            """ids: (1, T) int64  ->  logits: (1, T, VOCAB)"""
+            T = ids.size(1)
+            x = self.tok(ids) + self.pos(torch.arange(T, device=ids.device))
+            x = self.blocks(x)
+            x = self.ln(x)
+            return self.head(x)
+
+    @torch.no_grad()
+    def free_run(model: ThinExpert, inp_ids: List[int], device: str = "cpu") -> List[int]:
+        """
+        Greedy autoregressive decode.
+
+        Args:
+            model:   loaded ThinExpert in eval mode
+            inp_ids: integer token list [BOS, ...edge tokens..., SEP]
+            device:  'cpu' (always — GPU optional, not required)
+
+        Returns:
+            List of generated token ids (excluding EOS / stopping token).
+        """
+        ids = torch.tensor(inp_ids, dtype=torch.long, device=device).unsqueeze(0)
+        gen: List[int] = []
+        for _ in range(MAX_GEN):
+            logits = model(ids)[0, -1]
+            nxt    = logits.argmax().item()
+            if nxt == EOS or ids.size(1) >= MAX_SEQ - 1:
+                break
+            gen.append(nxt)
+            ids = torch.cat([ids, torch.tensor([[nxt]], device=device)], 1)
+        return gen
+
+    def parse_output(gen: List[int]):
+        """
+        Parse greedy-decoded token list.
+
+        Returns:
+            (has_derived: bool, derived_pairs: set of (int, int))
+            Pairs are integer entity indices (0-based, not token ids).
+        """
+        if not gen:
+            return False, set()
+        detected = gen[0] == HAS_YES
+        pairs: set = set()
+        if detected:
+            i = 1
+            while i + 1 < len(gen):
+                a = gen[i]     - ENT_OFFSET
+                b = gen[i + 1] - ENT_OFFSET
+                if 0 <= a < N_ENTITIES and 0 <= b < N_ENTITIES:
+                    pairs.add((a, b))
+                i += 2
+        return detected, pairs
+
+else:
+    # Stub classes so `from derive_expert.model import ThinExpert` never raises
+    # ImportError. core.py checks TORCH_AVAILABLE and raises a clear error.
+    class Block:  # type: ignore[no-redef]
+        pass
+
+    class ThinExpert:  # type: ignore[no-redef]
+        pass
+
+    def free_run(*args, **kwargs):  # type: ignore[misc]
+        raise RuntimeError("torch not installed; NN path unavailable")
+
+    def parse_output(*args, **kwargs):  # type: ignore[misc]
+        raise RuntimeError("torch not installed; NN path unavailable")