dentate 0.1.0__py3-none-any.whl

dentate/__init__.py

@@ -0,0 +1,10 @@
+"""Cortex Dentate — RLVR + distillation training over Gauntlet verifiable rewards.
+
+P0 scaffold: typed config + model registry + CLI surface. Training loops (SFT/GKD/DPO/GRPO/online) land in
+P1+ (see PLAN.md and docs/). Three tiers (docs/ARCHITECTURE.md): a 1–5B trainable *student* (default
+Qwen3-4B-2507), a local *teacher* (default Gemma 4 ⇄ Qwen3-MoE) for bulk sampling + on-policy distillation,
+and an API *oracle* that authors/judges. Reward = R1 verifiable (the reused Gauntlet composite — one source
+of truth, no metric drift) ⊕ R2 reference (masking) ⊕ R3 AI-feedback (oracle RLAIF/PRM, gated inside R1).
+"""
+
+__version__ = "0.0.0"

dentate/_deps.py

@@ -0,0 +1,38 @@
+"""Thread-safe access to the heavy third-party deps dentate imports lazily.
+
+`transformers` builds its public namespace lazily: its package `__init__` runs a few hundred lines and
+only as its LAST statement swaps `sys.modules["transformers"]` for the `_LazyModule` that resolves
+`AutoTokenizer` & friends. A second thread running `from transformers import AutoTokenizer` inside that
+window finds the half-built module already in `sys.modules`, misses the attribute, and dies with
+
+    ImportError: cannot import name 'AutoTokenizer' from 'transformers'
+
+Dentate hits that window routinely, because it imports transformers off the main thread from more than
+one place at once: the dashboard resolves examples in FastAPI's threadpool (the Analysis tab requests the
+`train` and `eval` splits concurrently) and `RunManager` trains in background threads. Measured on
+transformers 4.57.3, 8 threads racing a cold `from transformers import AutoTokenizer` fail 5 times.
+
+So every dentate-side transformers import goes through `hf()`, which serializes the package build. The
+lock is only ever contended on the first call; afterwards it is an uncontended acquire around attribute
+lookups on an already-built module.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+_LOCK = threading.Lock()
+
+
+def hf(*names: str) -> tuple[Any, ...]:
+    """`from transformers import <names>`, serialized against the lazy-init race described above.
+
+    Import-site replacement, so it unpacks exactly like the statement it replaces::
+
+        (AutoTokenizer,) = hf("AutoTokenizer")
+        AutoModelForCausalLM, AutoTokenizer = hf("AutoModelForCausalLM", "AutoTokenizer")
+    """
+    with _LOCK:
+        import transformers  # noqa: PLC0415 — heavy dep, deliberately deferred to this single site
+        return tuple(getattr(transformers, name) for name in names)

dentate/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Concrete non-backend adapters: fake oracle/teacher plus experiment tracking."""
+
+from .oracle import FakeOracle
+from .teacher import FakeTeacher
+from .tracking import NullTracker, TrackerError, WandbTracker, make_tracker
+
+__all__ = ["FakeOracle", "FakeTeacher", "NullTracker", "TrackerError", "WandbTracker", "make_tracker"]

dentate/adapters/oracle/__init__.py

@@ -0,0 +1,5 @@
+"""Oracle adapters — the API judge/author tier. `FakeOracle` for dev/test; Anthropic adapter lands in P3."""
+
+from .fake import FakeOracle
+
+__all__ = ["FakeOracle"]

dentate/adapters/oracle/fake.py

@@ -0,0 +1,62 @@
+"""FakeOracle — a deterministic stand-in for the API oracle (author / solve / judge / decompose).
+
+It is a *strong* judge: it knows the task target (the tasks were generated here), so its R3 scores and rankings
+are meaningful learning signal — exactly the RLAIF setup, minus the API cost. Optional `noise` simulates an
+imperfect judge so the reward-model-distillation drift checks have something to detect.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Sequence
+
+from ...domain.types import Rollout, Task, Verdict
+from ...util import parse_wrapped, similarity, stable_seed
+
+
+class FakeOracle:
+    """Implements the `Oracle` port."""
+
+    def __init__(self, noise: float = 0.0, seed: int = 0) -> None:
+        self.noise = noise
+        self.seed = seed
+
+    def author(self, seed: int, domain: str) -> Task:
+        # Lazy import to avoid an adapters→tasks import at module load.
+        if domain == "synthetic":
+            from ...tasks.synthetic import SyntheticTasks
+
+            return SyntheticTasks().sample(1, seed)[0]
+        from ...tasks.masking import MaskingTasks
+
+        return MaskingTasks(domain=domain).sample(1, seed)[0]
+
+    def solve(self, task: Task) -> Rollout:
+        """An expert trace (for SeqKD/RAFT warm-start) — the oracle solves it correctly."""
+        completion = f"<out>{task.target}</out>" if task.target is not None else ""
+        return Rollout(task_id=task.id, prompt=task.prompt, completion=completion, policy_version=-1,
+                       meta={"role": "oracle"})
+
+    def judge(self, task: Task, rollouts: Sequence[Rollout]) -> list[Verdict]:
+        scores = [self._quality(task, r, i) for i, r in enumerate(rollouts)]
+        order = sorted(range(len(rollouts)), key=lambda i: scores[i], reverse=True)
+        rank_of = {i: rank for rank, i in enumerate(order)}
+        return [Verdict(score=round(scores[i], 4), rank=rank_of[i]) for i in range(len(rollouts))]
+
+    def decompose(self, task: Task) -> list[str]:
+        if task.steps:
+            return list(task.steps)
+        if task.target:
+            return [s for s in task.target.split("\n") if s] or [task.target]
+        return [task.prompt[:24]]
+
+    def _quality(self, task: Task, rollout: Rollout, idx: int) -> float:
+        inner = parse_wrapped(rollout.completion, "out")
+        if inner is None:
+            return 0.0
+        r1 = 1.0 if inner == task.target else 0.0
+        quality = 0.5 * r1 + 0.5 * similarity(inner, task.target or "")
+        if self.noise:
+            rng = random.Random(stable_seed("judge", self.seed, task.id, idx))
+            quality += (rng.random() * 2 - 1) * self.noise
+        return min(1.0, max(0.0, quality))

dentate/adapters/teacher/__init__.py

@@ -0,0 +1,5 @@
+"""Teacher adapters — the local bulk-sampler / GKD source. `FakeTeacher` for dev/test; MLX teacher in P3.5."""
+
+from .fake import FakeTeacher
+
+__all__ = ["FakeTeacher"]

dentate/adapters/teacher/fake.py

@@ -0,0 +1,27 @@
+"""FakeTeacher — a competent *local* model: bulk-samples candidates and exposes logprobs (enabling GKD).
+
+Implemented by reusing `FakeBackend` at a fixed high skill, so the teacher is just a strong, logprob-exposing
+policy — which is exactly what a local teacher is. The API oracle, by contrast, has no logprobs (FakeOracle).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ...backends.fake import FakeBackend, Solver
+from ...domain.types import Policy, Rollout, Task
+
+
+class FakeTeacher:
+    """Implements the `Teacher` port."""
+
+    def __init__(self, solver: Solver, model_key: str = "gemma-4", skill: float = 0.85, group_size: int = 4) -> None:
+        self.model_key = model_key
+        self._backend = FakeBackend(solver, group_size=group_size)
+        self._policy = Policy(model_key=model_key, version=0, params={"skill": skill})
+
+    def sample(self, tasks: Sequence[Task], n: int = 1, seed: int = 0) -> list[list[Rollout]]:
+        return self._backend.generate(self._policy, [t.prompt for t in tasks], n=n, seed=seed)
+
+    def logprobs(self, prompt: str, completion: str) -> list[float]:
+        return self._backend.logprobs(self._policy, prompt, completion)

dentate/adapters/tracking/__init__.py

@@ -0,0 +1,6 @@
+"""Experiment trackers — `NullTracker` (tests) and a fail-loud W&B tracker via `make_tracker`."""
+
+from .null import NullTracker
+from .wandb import TrackerError, WandbTracker, make_tracker
+
+__all__ = ["NullTracker", "TrackerError", "WandbTracker", "make_tracker"]

dentate/adapters/tracking/null.py

@@ -0,0 +1,19 @@
+"""A no-op tracker — the default in tests and when W&B is disabled/absent."""
+
+from __future__ import annotations
+
+
+class NullTracker:
+    """Implements the `Tracker` port; drops everything. Usable as a context manager."""
+
+    def log(self, metrics: dict[str, float], step: int | None = None) -> None:
+        return None
+
+    def summary(self, data: dict[str, float]) -> None:
+        return None
+
+    def __enter__(self) -> NullTracker:
+        return self
+
+    def __exit__(self, *exc: object) -> bool:
+        return False

dentate/adapters/tracking/wandb.py

@@ -0,0 +1,53 @@
+"""Weights & Biases tracker. Disabled tracking uses `NullTracker`; requested W&B failures are explicit."""
+
+from __future__ import annotations
+
+from ...config import WandbSpec
+from ...domain.ports import Tracker
+from ...errors import TrackerError
+from .null import NullTracker
+
+__all__ = ["TrackerError", "WandbTracker", "make_tracker"]
+
+
+class WandbTracker:
+    """Implements the `Tracker` port over a live W&B run. `wandb` is imported lazily (only on use)."""
+
+    def __init__(self, spec: WandbSpec) -> None:
+        try:
+            import wandb  # noqa: PLC0415 (lazy by design — keep wandb out of the import graph)
+        except ImportError as exc:
+            raise TrackerError("W&B tracking was requested, but `wandb` is not importable") from exc
+
+        self._run = wandb.init(
+            project=spec.project, entity=spec.entity, group=spec.run_group or None,
+            tags=list(spec.tags) or None,
+        )
+
+    @property
+    def url(self) -> str | None:
+        """The live W&B run URL (stored in the manifest's links for cross-dashboard navigation)."""
+        return getattr(self._run, "url", None)
+
+    def log(self, metrics: dict[str, float], step: int | None = None) -> None:
+        self._run.log(metrics, step=step)
+
+    def summary(self, data: dict[str, float]) -> None:
+        for key, value in data.items():
+            self._run.summary[key] = value
+
+    def __enter__(self) -> WandbTracker:
+        return self
+
+    def __exit__(self, *exc: object) -> bool:
+        self._run.finish()
+        return False
+
+
+def make_tracker(spec: WandbSpec) -> Tracker:
+    """Return a live W&B tracker, or a `NullTracker` when tracking is disabled."""
+    if not spec.enabled:
+        return NullTracker()
+    if spec.report_to != "wandb":
+        raise TrackerError(f"unsupported tracker {spec.report_to!r}; known: wandb")
+    return WandbTracker(spec)

dentate/agent.py

@@ -0,0 +1,76 @@
+"""Agentic tool-calling loop — lets a capable checkpoint use the sandbox tools, then answer.
+
+Protocol (model-agnostic text form, works without native tool-calling support): to call a tool the model emits
+    <tool_call>{"name": "python", "arguments": {"code": "..."}}</tool_call>
+and stops; it receives a `<tool_result>…</tool_result>` turn and continues; a turn with no tool_call is the final
+answer. `run_agent` drives this against a `generate(messages) -> str` callable and a `Sandbox`, yielding events
+the API streams to the UI (assistant text, tool_call, tool_result + workspace files, done / step-limit).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Iterator
+
+from .sandbox import TOOLS, Sandbox, dispatch
+
+_CALL_RE = re.compile(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", re.DOTALL)
+
+
+def system_prompt() -> str:
+    lines = [
+        "You are an agent that can use tools running in a sandboxed workspace. To call a tool, output EXACTLY:",
+        '<tool_call>{"name": "<tool>", "arguments": { ... }}</tool_call>',
+        "then stop and wait. You will receive <tool_result>…</tool_result>; then continue. When you have the",
+        "answer, reply normally WITHOUT a tool_call. Prefer writing files for anything the user should keep.",
+        "",
+        "Available tools:",
+    ]
+    lines += [f"- {t['name']}({', '.join(t['arguments'])}): {t['description']}" for t in TOOLS]
+    return "\n".join(lines)
+
+
+def strip_tool_calls(text: str) -> str:
+    """Remove the raw <tool_call> markers from a turn for display (the UI shows a tool card instead)."""
+    return _CALL_RE.sub("", text or "").strip()
+
+
+def parse_tool_call(text: str) -> dict | None:
+    """Extract the first well-formed <tool_call> object, or None (a normal final answer)."""
+    m = _CALL_RE.search(text or "")
+    if not m:
+        return None
+    try:
+        obj = json.loads(m.group(1))
+    except json.JSONDecodeError:
+        return None
+    if isinstance(obj, dict) and isinstance(obj.get("name"), str):
+        args = obj.get("arguments")
+        return {"name": obj["name"], "arguments": args if isinstance(args, dict) else {}}
+    return None
+
+
+def run_agent(generate: Callable[[list[dict]], str], sandbox: Sandbox, messages: list[dict],
+              *, max_steps: int = 6) -> Iterator[dict]:
+    """Drive the tool-calling loop. Yields event dicts; terminates on a tool-free turn or `max_steps`."""
+    base_system = next((m.get("content", "") for m in messages if m.get("role") == "system"), "")
+    sys_msg = {"role": "system", "content": (base_system + "\n\n" + system_prompt()).strip()}
+    convo: list[dict] = [sys_msg, *[m for m in messages if m.get("role") != "system"]]
+
+    for step in range(max_steps):
+        text = generate(convo)
+        call = parse_tool_call(text)
+        yield {"type": "assistant", "text": text, "step": step}
+        convo.append({"role": "assistant", "content": text})
+        if not call:
+            yield {"type": "done"}
+            return
+        yield {"type": "tool_call", "name": call["name"], "arguments": call["arguments"], "step": step}
+        result = dispatch(sandbox, call["name"], call["arguments"])
+        yield {"type": "tool_result", "name": call["name"], "ok": result.ok,
+               "output": result.as_text(), "files": result.files, "step": step}
+        convo.append({"role": "user", "content": f"<tool_result>\n{result.as_text()}\n</tool_result>"})
+
+    yield {"type": "tool_limit", "max_steps": max_steps}
+    yield {"type": "done"}