prabodha 1.0.0__py3-none-any.whl

prabodha/cli.py

@@ -0,0 +1,49 @@
+"""prabodha CLI — the H4 application surface: one entrypoint over the toolkit.
+Concept: the doctrine as a usable instrument (clean external surface, RULES R8 — the
+engineering-gloss column only). Subcommands route to the tested module CLIs.
+Source: docs/h4_plugin_architecture.md phase 1.
+Primitive: `prabodha <cmd> [args...]` -> module main(argv). Stdlib dispatch only.
+
+  prabodha lens-fit   --model M.yaml --lens L.yaml --out lens.pt [--resume]
+  prabodha lens-eval  --model M.yaml --lens-file lens.pt --exp E.yaml --out gate.json
+  prabodha lens-vis   --model M.yaml --lens-file lens.pt --prompt "..." --out page.html
+  prabodha steer      --model M.yaml --mid-lens lens.pt --exp E.yaml --out gate.json
+  prabodha research   [--menu menu.yaml] [--propose]
+  prabodha figures    (regenerate paper/HTML figures from gates)
+"""
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(__doc__)
+        raise SystemExit(0)
+    cmd, argv = sys.argv[1], sys.argv[2:]
+    if cmd == "lens-fit":
+        from prabodha.lens import fit_cli
+        sys.argv = ["fit_cli"] + argv
+        fit_cli.main()
+    elif cmd == "lens-eval":
+        from prabodha.lens import e1_cli
+        e1_cli.main(argv)
+    elif cmd == "lens-vis":
+        from prabodha.lens import vis_cli
+        vis_cli.main(argv)
+    elif cmd == "steer":
+        from prabodha.steering import e4_cli
+        e4_cli.main(argv)
+    elif cmd == "research":
+        from prabodha.efe import runner
+        runner.main(argv)
+    elif cmd == "figures":
+        import runpy
+        from pathlib import Path
+        script = Path(__file__).resolve().parents[2] / "scripts/tools/make_figures.py"
+        runpy.run_path(str(script), run_name="__main__")
+    else:
+        print(f"unknown command: {cmd}\n{__doc__}")
+        raise SystemExit(2)
+
+
+if __name__ == "__main__":
+    main()

prabodha/config.py

@@ -0,0 +1,15 @@
+"""Config loader — config over constants (CLAUDE.md).
+Concept: āgama-śāsana — the written rule governs the run.
+Primitive: YAML -> dict with required-key validation.
+"""
+from __future__ import annotations
+from pathlib import Path
+import yaml
+
+def load(path: str | Path, required: tuple[str, ...] = ()) -> dict:
+    with open(path) as f:
+        cfg = yaml.safe_load(f)
+    missing = [k for k in required if k not in cfg]
+    if missing:
+        raise KeyError(f"config {path} missing required keys: {missing}")
+    return cfg

prabodha/contracts/closure.py

@@ -0,0 +1,33 @@
+"""Dual-closure gate schema (RULES R1).
+Concept: dvāra (gate) with ubhaya-siddhi — both accomplishments required.
+Source: neo-fm five-point gate; prabhasa closure.py; scoping doc §7.
+Primitive: pydantic model serialized to gates/gate_<loop>.json.
+"""
+from __future__ import annotations
+from typing import Literal, Optional
+from pydantic import BaseModel, model_validator
+
+Verdict = Literal["pass", "fail", "pruned", "pending"]
+
+class GateSide(BaseModel):
+    verdict: Verdict
+    evidence: str
+    deviations: list[str] = []
+
+class GateReport(BaseModel):
+    loop: str
+    status: Literal["open", "closed"]
+    closed_at: Optional[str] = None
+    code_gate: GateSide
+    domain_gate: GateSide
+    signoff: str = "pending"
+
+    @model_validator(mode="after")
+    def _dual_closure(self) -> "GateReport":
+        if self.status == "closed":
+            ok = {"pass", "pruned"}
+            if not (self.code_gate.verdict in ok and self.domain_gate.verdict in ok):
+                raise ValueError("R1 violation: closed loop requires BOTH gates pass|pruned")
+            if self.domain_gate.verdict == "pruned" and not self.domain_gate.evidence:
+                raise ValueError("R5: pruned closure requires evidence (diagnosis)")
+        return self

prabodha/contracts/trace.py

@@ -0,0 +1,44 @@
+"""Steering episode trace — the shared record consumed by app replay, Pages, and gateway.
+
+Concept: sākṣāt-darśana (direct seeing) extended to the steering episode as a whole.
+Source: paper §steering; gate_L9_alignconf.json (arm/seed semantics).
+Primitive: trace emission (pure record; no behavior).
+"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+SCHEMA_VERSION = 1
+
+
+class TraceToken(BaseModel):
+    t: int                              # decode step index (0-based)
+    token: str                          # decoded token text
+    entropy: float                      # per-token predictive entropy in nats, measured pre-write
+    gated: bool                         # True iff a sphuraṭṭā-gated write was applied at this step
+    write_norm: float | None = None     # L2 norm of the applied write (None when not gated)
+    band_topk: list[str] | None = None  # band-lens readout top-k tokens (None if not sampled at this step)
+
+
+class ReadbackResult(BaseModel):
+    verdict: str                        # "accepted" | "rejected"
+    top_m: int
+    gain: float
+    concept_rank: int | None = None
+
+
+class SteerTrace(BaseModel):
+    schema_version: int = SCHEMA_VERSION
+    model_id: str                       # e.g. "Qwen/Qwen3-4B"
+    prompt: str
+    concept: str                        # e.g. "fire"
+    arm: str                            # baseline|prefill|entropy_gated|rate_matched|continuous|trained_bridge
+    seed: int
+    alpha: float
+    tau_percentile: int
+    site_layer: int
+    tokens: list[TraceToken] = Field(default_factory=list)
+    readback: ReadbackResult | None = None
+    behavioral_hit: bool | None = None
+    gate_ref: str | None = None         # repo-relative path of the gate JSON this run fed, if any
+    created_at: str                     # ISO-8601 UTC

prabodha/efe/__init__.py

@@ -0,0 +1,7 @@
+"""prabodha.efe — auto-research: EFE selection over the experiment menu (L5).
+Concept: the selector proposes the next experiment by expected information gain per
+GPU-hour; the agent disposes (operator standing authorization 2026-07-09); gates record.
+Source: prabhasa application/efe (ported per docs/efe_port_plan.md; math preserved exactly);
+SPEC §7. Primitive: menu (configs/efe_menu.yaml) -> EFESelector.rank/select -> Proposal;
+gate_to_obs replays closed gates into beliefs; EFELedger (JSONL) makes beliefs re-entrant.
+"""

prabodha/efe/agent.py

@@ -0,0 +1,245 @@
+"""Analytic Expected-Free-Energy selector over experiment candidates.
+Concept: iccha-jnana-kriya as auto-research — wanting (pragmatic preference), knowing
+(epistemic information gain), doing (the proposed action) balanced per GPU-hour.
+Source: PORTED from prabhasa application/efe/agent.py (docs/efe_port_plan.md; likelihood
+matrix, entropy, normalise, and all EFESelector methods preserved EXACTLY — only the
+observation tier field names are generalized: bpb_tier->primary_tier, frt_tier->
+secondary_tier, since prabodha's observations are gate outcomes, not token-efficiency).
+Primitive: Candidate/Action/Observation/Proposal + EFESelector (belief/update/score/
+select/rank). Stdlib only.
+
+Original prabhasa docstring (design rationale) follows:
+Analytic Expected-Free-Energy selector over experiment candidates.
+
+State / observation discretisation
+----------------------------------
+Each candidate carries a belief over a latent **value** factor with four levels
+(``negligible, low, moderate, high``) — "how much does running this config help
+the product?". Observations are discretised tiers of the measured improvement
+over the matched baseline:
+
+  * ``bpb`` tier in 0..3 (token-efficiency gain),
+  * ``frt`` tier in 0..3 (round-trip / probe gain; optional).
+
+Actions modulate cost vs information resolution (separation by action, mirroring
+the source agent's B-matrix entropy design):
+
+  * ``smoke``   — cheap, low-information (explore),
+  * ``partial`` — moderate,
+  * ``full``    — expensive, high-information (confirm / exploit).
+
+EFE
+---
+For a candidate ``c`` and action ``a`` the Expected Free Energy is
+
+    G(c, a) = -( w_epi * epistemic(c, a) + w_prag * pragmatic(c) )
+
+* ``epistemic`` = expected information gain ~ belief entropy * action resolution,
+  divided by action cost (information per GPU-hour);
+* ``pragmatic`` = expected preference satisfaction E_b[U(value)] minus a cost
+  penalty.
+
+The selector returns the ``(candidate, action)`` minimising ``G`` (equivalently
+maximising the negative-EFE the source agent reports). EXPLORE->CONFIRM emerges:
+high-entropy candidates pull a cheap ``smoke``; high-belief candidates pull a
+``full`` run.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+VALUE_LEVELS = 4
+VALUE_LABELS = ("negligible", "low", "moderate", "high")
+# Utility of each value level (pragmatic preference; prefer high value).
+_UTILITY = (-1.0, 0.0, 1.0, 2.0)
+
+
+@dataclass(frozen=True)
+class Action:
+    """A way to run a candidate: cost (GPU-hours) and information resolution."""
+
+    name: str
+    gpu_hours: float
+    resolution: float  # 0..1; how much of the candidate's uncertainty it resolves
+
+
+# Default action set (cheap-smoke -> full-run); EXPLORE..CONFIRM spectrum.
+SMOKE = Action("smoke", gpu_hours=0.1, resolution=0.25)
+PARTIAL = Action("partial", gpu_hours=1.0, resolution=0.6)
+FULL = Action("full", gpu_hours=5.0, resolution=0.95)
+DEFAULT_ACTIONS: tuple[Action, ...] = (SMOKE, PARTIAL, FULL)
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """One experiment candidate: a knob/config change to evaluate."""
+
+    id: str
+    description: str
+    knobs: dict[str, object] = field(default_factory=dict)
+    # Optional prior nudge in 0..3 (e.g. strong prior it is "moderate" value).
+    prior_value_hint: int | None = None
+
+
+@dataclass(frozen=True)
+class Observation:
+    """Discretised measured outcome of a trial (tiers in 0..3)."""
+
+    primary_tier: int
+    secondary_tier: int | None = None
+
+    def __post_init__(self) -> None:
+        for name, v in (("primary_tier", self.primary_tier), ("secondary_tier", self.secondary_tier)):
+            if v is not None and not 0 <= v <= 3:
+                raise ValueError(f"{name} must be in 0..3, got {v}")
+
+
+@dataclass(frozen=True)
+class Proposal:
+    """The selector's recommendation for the next micro-experiment."""
+
+    candidate: Candidate
+    action: Action
+    efe: float
+    epistemic: float
+    pragmatic: float
+    belief: tuple[float, ...]
+
+
+def _normalise(weights: Sequence[float]) -> list[float]:
+    total = sum(weights)
+    if total <= 0:
+        n = len(weights)
+        return [1.0 / n] * n
+    return [w / total for w in weights]
+
+
+def _entropy(belief: Sequence[float]) -> float:
+    return -sum(p * math.log(p + 1e-12) for p in belief if p > 0)
+
+
+# Likelihood P(observed tier | latent value level). Higher value -> higher tiers.
+# Rows index latent value level (0..3), columns the observed tier (0..3).
+_LIKELIHOOD: tuple[tuple[float, ...], ...] = (
+    (0.70, 0.20, 0.07, 0.03),  # negligible
+    (0.30, 0.45, 0.20, 0.05),  # low
+    (0.07, 0.23, 0.45, 0.25),  # moderate
+    (0.03, 0.07, 0.30, 0.60),  # high
+)
+
+
+class EFESelector:
+    """Expected-Free-Energy selector over a fixed candidate set.
+
+    Beliefs are categorical over the four latent value levels, one belief per
+    candidate id, updated by Bayes rule from each observation's tiers.
+    """
+
+    def __init__(
+        self,
+        *,
+        epistemic_weight: float = 1.0,
+        pragmatic_weight: float = 1.0,
+        cost_penalty: float = 0.15,
+        actions: Sequence[Action] = DEFAULT_ACTIONS,
+    ) -> None:
+        self.epistemic_weight = float(epistemic_weight)
+        self.pragmatic_weight = float(pragmatic_weight)
+        self.cost_penalty = float(cost_penalty)
+        self.actions = tuple(actions)
+        self._beliefs: dict[str, list[float]] = {}
+
+    # -- belief management --------------------------------------------------
+    def _prior(self, candidate: Candidate) -> list[float]:
+        # Default prior: most configs are low value; nudge if a hint is given.
+        base = [0.40, 0.30, 0.20, 0.10]
+        if candidate.prior_value_hint is not None:
+            hint = max(0, min(3, candidate.prior_value_hint))
+            base = [0.1, 0.1, 0.1, 0.1]
+            base[hint] = 0.7
+        return _normalise(base)
+
+    def belief(self, candidate: Candidate) -> list[float]:
+        return list(self._beliefs.get(candidate.id, self._prior(candidate)))
+
+    def posterior(self, candidate_id: str) -> list[float] | None:
+        """The updated belief for a candidate id, or ``None`` if never observed."""
+        belief = self._beliefs.get(candidate_id)
+        return list(belief) if belief is not None else None
+
+    def update(
+        self, candidate_id: str, obs: Observation, prior: list[float] | None = None
+    ) -> list[float]:
+        """Bayesian belief update for a candidate from one observation."""
+        if prior is not None:
+            belief = prior
+        else:
+            belief = self._beliefs.get(candidate_id, [0.40, 0.30, 0.20, 0.10])
+        tiers = [obs.primary_tier] + ([obs.secondary_tier] if obs.secondary_tier is not None else [])
+        post = list(belief)
+        for tier in tiers:
+            post = [post[v] * _LIKELIHOOD[v][tier] for v in range(VALUE_LEVELS)]
+            post = _normalise(post)
+        self._beliefs[candidate_id] = post
+        return post
+
+    # -- EFE scoring --------------------------------------------------------
+    def _epistemic(self, belief: Sequence[float], action: Action) -> float:
+        """Expected info gain per GPU-hour: belief entropy * resolution / cost."""
+        return _entropy(belief) * action.resolution / max(action.gpu_hours, 1e-6)
+
+    def _pragmatic(self, belief: Sequence[float], action: Action) -> float:
+        """Expected preference satisfaction minus a cost penalty."""
+        utility = sum(p * u for p, u in zip(belief, _UTILITY, strict=True))
+        return utility - self.cost_penalty * action.gpu_hours
+
+    def score(self, candidate: Candidate, action: Action) -> Proposal:
+        belief = self.belief(candidate)
+        epi = self._epistemic(belief, action)
+        prag = self._pragmatic(belief, action)
+        efe = -(self.epistemic_weight * epi + self.pragmatic_weight * prag)
+        return Proposal(
+            candidate=candidate,
+            action=action,
+            efe=efe,
+            epistemic=epi,
+            pragmatic=prag,
+            belief=tuple(belief),
+        )
+
+    def select(
+        self,
+        candidates: Sequence[Candidate],
+        *,
+        budget_gpu_hours: float = float("inf"),
+        exclude: Sequence[str] = (),
+    ) -> Proposal:
+        """Pick the ``(candidate, action)`` minimising EFE within budget."""
+        if not candidates:
+            raise ValueError("no candidates to select from")
+        excluded = set(exclude)
+        best: Proposal | None = None
+        for cand in candidates:
+            if cand.id in excluded:
+                continue
+            for action in self.actions:
+                if action.gpu_hours > budget_gpu_hours:
+                    continue
+                prop = self.score(cand, action)
+                if best is None or prop.efe < best.efe:
+                    best = prop
+        if best is None:
+            raise ValueError("no (candidate, action) fits the GPU-hour budget")
+        return best
+
+    def rank(self, candidates: Sequence[Candidate]) -> list[Proposal]:
+        """Best action per candidate, sorted by ascending EFE (best first)."""
+        out = []
+        for cand in candidates:
+            props = [self.score(cand, a) for a in self.actions]
+            out.append(min(props, key=lambda p: p.efe))
+        out.sort(key=lambda p: p.efe)
+        return out

prabodha/efe/gate_to_obs.py

@@ -0,0 +1,34 @@
+"""gate_to_obs — discretise prabodha GateReports into EFE Observations.
+Concept: gates are the selector's senses — each closed gate becomes a tiered observation
+updating the belief about the experiment family it informs.
+Source: docs/efe_port_plan.md adaptation #2 (prabhasa observation_from_gate was M3-gate
+specific and is rewritten here for GateReport, src/prabodha/contracts/closure.py).
+Primitive: gate JSON -> primary tier 0..3 from the domain verdict and the registered
+hypotheses' value/threshold margins:
+  3 = pass with headroom (all hypotheses pass, min margin >= 1.5x threshold)
+  2 = pass (all hypotheses pass)
+  1 = near-miss fail (best failing hypothesis reached >= 80% of its threshold)
+  0 = fail (otherwise)
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from prabodha.efe.agent import Observation
+
+
+def observation_from_gate(gate_path: str | Path) -> Observation:
+    g = json.loads(Path(gate_path).read_text(encoding="utf-8"))
+    ev = json.loads(g["domain_gate"]["evidence"])
+    summary = ev["summary"]
+    if g["domain_gate"]["verdict"] == "pass":
+        ratios = [v["value"] / v["threshold"] for v in summary.values()
+                  if isinstance(v.get("threshold"), (int, float)) and v["threshold"]]
+        tier = 3 if ratios and min(ratios) >= 1.5 else 2
+    else:
+        failing = [v for v in summary.values() if not v["pass"]]
+        ratios = [v["value"] / v["threshold"] for v in failing
+                  if isinstance(v.get("threshold"), (int, float)) and v["threshold"] > 0]
+        tier = 1 if ratios and max(ratios) >= 0.8 else 0
+    return Observation(primary_tier=tier)

prabodha/efe/ledger.py

@@ -0,0 +1,53 @@
+"""ledger — append-only JSONL record of proposals, observations, spends, skips.
+Concept: anusaṃdhāna for the auto-researcher — beliefs are never stored, only re-derived
+by replaying the ledger; any fresh agent rebuilds the same selector state (stateless
+re-entry, same doctrine as the ralph loops).
+Source: prabhasa application/efe/ledger.py (record format preserved; path adapted).
+Primitive: EFELedger.log_* / records(); replay in runner.rebuild_selector.
+"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from prabodha.efe.agent import Observation, Proposal
+
+
+class EFELedger:
+    def __init__(self, path: str | Path = "research/efe_ledger.jsonl") -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _append(self, record: dict[str, Any]) -> None:
+        record["ts"] = time.time()
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record) + "\n")
+
+    def log_proposal(self, proposal: Proposal, *, budget_remaining: float) -> None:
+        self._append({"event": "propose", "candidate": proposal.candidate.id,
+                      "action": proposal.action.name, "efe": proposal.efe,
+                      "epistemic": proposal.epistemic, "pragmatic": proposal.pragmatic,
+                      "belief": list(proposal.belief),
+                      "budget_remaining": budget_remaining})
+
+    def log_observation(self, candidate_id: str, obs: Observation,
+                        posterior: list[float], *, source: str = "") -> None:
+        self._append({"event": "observe", "candidate": candidate_id,
+                      "primary_tier": obs.primary_tier,
+                      "secondary_tier": obs.secondary_tier,
+                      "posterior": posterior, "source": source})
+
+    def log_spend(self, candidate_id: str, gpu_hours: float) -> None:
+        self._append({"event": "spend", "candidate": candidate_id,
+                      "gpu_hours": gpu_hours})
+
+    def log_skip(self, candidate_id: str, reason: str) -> None:
+        self._append({"event": "skip", "candidate": candidate_id, "reason": reason})
+
+    def records(self) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        return [json.loads(line) for line in
+                self.path.read_text(encoding="utf-8").splitlines() if line.strip()]

prabodha/efe/lint.py

@@ -0,0 +1,44 @@
+"""lint — cycle-integrity checks over the EFE ledger (the staleness invariant as CODE).
+Concept: review #10's rule, adopted as loop law — a disposition may only execute the
+LATEST proposal; if new observations land after a proposal, it is STALE and must be
+re-proposed; divergences are legal only as explicit ledgered events with reasons.
+Source: contracts/L6_cycles.md loop mechanics; review #10 (d); journal 2026-07-10.
+Primitive: lint_cycles(records) -> list of violations (empty = clean). Historical
+divergences before the law's adoption are grandfathered via the cutoff timestamp.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def lint_cycles(records: list[dict[str, Any]], *, adopted_ts: float = 0.0,
+                menu_sources: set[str] | frozenset[str] = frozenset()) -> list[str]:
+    """Check: every run-sourced observe (source set, and not a menu replay echo — pass the
+    menu's declared replay gates as menu_sources) must be preceded by either (a) a propose
+    for the SAME candidate, or (b) a ledgered divergence event naming it."""
+    violations: list[str] = []
+    last_propose: str | None = None
+    last_divergence: str | None = None
+    for rec in records:
+        ev = rec.get("event")
+        if ev == "propose":
+            last_propose = rec["candidate"]
+        elif ev == "divergence":
+            last_divergence = rec["candidate"]
+        elif (ev == "observe" and rec.get("source")
+              and rec.get("source") not in menu_sources):
+            cand = rec["candidate"]
+            if rec.get("ts", 0) < adopted_ts:
+                continue  # grandfathered (pre-law history)
+            if cand != last_propose and cand != last_divergence:
+                violations.append(
+                    f"run observation for '{cand}' (source={rec['source']}) executed "
+                    f"without a matching proposal or ledgered divergence "
+                    f"(last propose: {last_propose!r})")
+            last_divergence = None
+    return violations
+
+
+def log_divergence(ledger, candidate_id: str, reason: str) -> None:
+    """Explicit, auditable divergence from the selector's latest proposal."""
+    ledger._append({"event": "divergence", "candidate": candidate_id, "reason": reason})

prabodha/efe/runner.py

@@ -0,0 +1,124 @@
+"""runner — rebuild the selector from menu + gates + ledger; propose the next experiment.
+Concept: the proposing half of the auto-research loop. Beliefs are seeded by replaying the
+menu's `replay` gates (what we HAVE seen) and any ledger observations, then EFE ranks the
+menu within the remaining budget. Disposition is the agent's (standing authorization);
+every proposal and disposition lands in the ledger.
+Source: prabhasa application/efe/runner.py pattern; docs/efe_port_plan.md phase 2/3.
+Primitive: build_from_configs -> (selector, candidates, budget); propose_next; CLI prints
+the ranked menu (python -m prabodha.efe.runner --menu configs/efe_menu.yaml).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from prabodha.config import load
+from prabodha.efe.agent import Action, Candidate, EFESelector, Proposal
+from prabodha.efe.gate_to_obs import observation_from_gate
+from prabodha.efe.ledger import EFELedger
+
+
+def build_from_configs(menu_path: str | Path, *, ledger: EFELedger | None = None,
+                       root: str | Path = ".") -> tuple[EFESelector, list[Candidate], float, dict[str, Action]]:
+    menu = load(menu_path, required=("candidates", "budget_gpu_hours"))
+    root = Path(root)
+    selector = EFESelector()
+    candidates: list[Candidate] = []
+    actions_by_id: dict[str, Action] = {}
+    for c in menu["candidates"]:
+        cand = Candidate(id=c["id"], description=c["description"],
+                         knobs=dict(c.get("knobs", {})),
+                         prior_value_hint=c.get("prior_value_hint"))
+        candidates.append(cand)
+        if "cost_gpu_hours" in c:
+            # review #7 P0: composite as-registered cost replaces the generic ladder
+            actions_by_id[cand.id] = Action("as-registered",
+                                            gpu_hours=float(c["cost_gpu_hours"]),
+                                            resolution=float(c.get("resolution", 0.6)))
+        # replay closed gates into this candidate's belief (prior -> posterior)
+        for gate in c.get("replay", []):
+            gp = root / gate
+            if not gp.exists():
+                continue
+            obs = observation_from_gate(gp)
+            post = selector.update(cand.id, obs, prior=selector.belief(cand))
+            if ledger is not None:
+                ledger.log_observation(cand.id, obs, post, source=str(gate))
+    # ledger replay: observations from RUNS (sources not among the menu's declared replay
+    # gates — those were already seeded above; without this, a completed run's observation
+    # is silently lost and the selector re-proposes it. Found live in cycle 2.)
+    menu_sources = {g for c in menu["candidates"] for g in c.get("replay", [])}
+    if ledger is not None:
+        from prabodha.efe.agent import Observation
+        for rec in ledger.records():
+            if rec.get("event") == "observe" and rec.get("source", "") not in menu_sources:
+                selector.update(rec["candidate"],
+                                Observation(primary_tier=rec["primary_tier"],
+                                            secondary_tier=rec.get("secondary_tier")))
+    # budget scope: a menu's budget is debited ONLY by spends on ITS candidates
+    # (the ledger is program-global and spans menu generations — found live in cycle 7)
+    menu_ids = {c["id"] for c in menu["candidates"]}
+    spent = sum(r["gpu_hours"] for r in (ledger.records() if ledger else [])
+                if r.get("event") == "spend" and r.get("candidate") in menu_ids)
+    budget = float(menu["budget_gpu_hours"]) - spent
+    return selector, candidates, budget, actions_by_id
+
+
+def propose_next(menu_path: str | Path, *, ledger: EFELedger,
+                 root: str | Path = ".") -> Proposal:
+    selector, candidates, budget, actions = build_from_configs(menu_path, ledger=ledger,
+                                                               root=root)
+    # consumption rule: a candidate whose registered question already has a RUN-sourced
+    # observation is consumed — re-running it verbatim has no marginal value; follow-ups
+    # are new menu entries. (Cycle-3 live finding: a tier-3 result raises pragmatic value
+    # and the raw EFE wants to re-run its winner.)
+    menu = load(menu_path, required=("candidates",))
+    menu_sources = {g for c in menu["candidates"] for g in c.get("replay", [])}
+    consumed = {rec["candidate"] for rec in ledger.records()
+                if rec.get("event") == "observe"
+                and rec.get("source", "") not in menu_sources and rec.get("source")}
+    blocked = {c["id"]: c["blocked"] for c in menu["candidates"] if c.get("blocked")}
+    best: Proposal | None = None
+    for cand in candidates:
+        act = actions.get(cand.id)
+        if cand.id in blocked:
+            if not any(r.get("event") == "skip" and r.get("candidate") == cand.id
+                       for r in ledger.records()):
+                ledger.log_skip(cand.id, f"blocked: {blocked[cand.id]}")
+            continue
+        if act is None or act.gpu_hours > budget or cand.id in consumed:
+            continue
+        prop = selector.score(cand, act)
+        if best is None or prop.efe < best.efe:
+            best = prop
+    if best is None:
+        raise ValueError("no candidate fits the remaining budget")
+    ledger.log_proposal(best, budget_remaining=budget)
+    return best
+
+
+def main(argv=None) -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--menu", default="configs/efe_menu.yaml")
+    ap.add_argument("--ledger", default="research/efe_ledger.jsonl")
+    ap.add_argument("--propose", action="store_true",
+                    help="log the top proposal to the ledger (else just print the ranking)")
+    a = ap.parse_args(argv)
+    ledger = EFELedger(a.ledger)
+    selector, candidates, budget, actions = build_from_configs(a.menu, ledger=None)
+    print(f"budget remaining: {budget:.2f} GPU-h; ranked menu (best first):")
+    ranked = sorted((selector.score(c, actions[c.id]) for c in candidates
+                     if c.id in actions), key=lambda p: p.efe)
+    for p in ranked:
+        b = ", ".join(f"{x:.2f}" for x in p.belief)
+        print(f"  {p.candidate.id:20s} action={p.action.name:7s} EFE={p.efe:+.3f} "
+              f"epi={p.epistemic:.3f} prag={p.pragmatic:+.3f} belief=[{b}]")
+    if a.propose:
+        prop = propose_next(a.menu, ledger=ledger)
+        print(json.dumps({"proposed": prop.candidate.id, "action": prop.action.name,
+                          "efe": round(prop.efe, 4)}))
+
+
+if __name__ == "__main__":
+    main()

prabodha/lens/__init__.py

@@ -0,0 +1,10 @@
+"""prabodha.lens — public API for lens operations (fit, eval, vis).
+
+Concept: ārambha (inception; the public gate to the instrument).
+Source: docs/jspace_pratyabhijna_scoping.md; RULES R8 (public surface).
+Primitive: public fit/eval/vis functions; internal modules for CLI dispatch.
+"""
+
+from .public_api import fit, eval, vis
+
+__all__ = ["fit", "eval", "vis"]