platformforge 0.1.0__py3-none-any.whl

platformforge/economy/doctor.py

@@ -0,0 +1,207 @@
+"""Economy doctor (§243–250) — health checks over the ledgers.
+
+Each check inspects what actually exists (ledger rows, cache stats,
+checkpoints, pricing catalog) and reports a finding only with evidence.
+A check with no data reports `unresolved`, never a pass by absence.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from platformforge.economy.cache import CacheStore
+from platformforge.economy.checkpoint import CheckpointStore
+
+SCHEMA = "platformforge/economy-doctor/v1"
+RECEIPT_REL = Path("docs/economy-parity/VALIDATION-RECEIPT.json")
+RECEIPT_SCHEMA = "platformforge/economy-validation-receipt/v1"
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    return [json.loads(l) for l in path.read_text().splitlines()
+            if l.strip()]
+
+
+def _canonical_economy_gates(root: Path) -> set[str]:
+    """polish §9 — the canonical gate taxonomy lives in
+    scripts/validate.py; doctor derives it from the file, never from a
+    copy. Importing validate.py must not run main() — it doesn't."""
+    import importlib.util
+    spec_path = root / "scripts" / "validate.py"
+    if not spec_path.is_file():
+        return set()
+    spec = importlib.util.spec_from_file_location("pf_validate",
+                                                  spec_path)
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+    except Exception:  # noqa: BLE001 — validator unreadable = no canon
+        return set()
+    return {n for n in getattr(mod, "GATES", {})
+            if n.startswith("economy-")}
+
+
+def doctor(root: str | Path, *, now: float | None = None) -> dict[str, Any]:
+    """Run every economy health check. `ok` is true only when no check
+    produced a `warn`/`fail` — unresolved checks don't fake health."""
+    now = now if now is not None else time.time()
+    root = Path(root)
+    led = root / ".platformforge" / "ledger"
+    findings: list[dict[str, Any]] = []
+
+    def note(check: str, state: str, evidence: dict[str, Any],
+             fix: str = "") -> None:
+        findings.append({"check": check, "state": state,
+                         "evidence": evidence, "recommended_fix": fix})
+
+    # --- cache disabled ------------------------------------------------
+    store = CacheStore(root / ".platformforge" / "cache")
+    stats = store.stats()
+    if stats["entries"] == 0 and stats["hits"] == 0 and \
+            stats["misses"] == 0:
+        note("cache-enabled", "warn", {"stats": stats},
+             "cache store is empty — reuse is not happening")
+    else:
+        note("cache-enabled", "ok", {"entries": stats["entries"]})
+
+    # --- cache hit rate ------------------------------------------------
+    total = stats["hits"] + stats["misses"]
+    if total >= 10:
+        rate = stats["hits"] / total
+        note("cache-hit-rate", "warn" if rate < 0.3 else "ok",
+             {"hit_rate": round(rate, 3), "samples": total},
+             "investigate dep churn or key scope" if rate < 0.3 else "")
+    else:
+        note("cache-hit-rate", "unresolved",
+             {"samples": total, "reason": "too few lookups to judge"})
+
+    # --- context oversized ----------------------------------------------
+    econ = _read_jsonl(led / "economy.jsonl")
+    builds = [e for e in econ if e.get("tool") == "context.build"]
+    if builds:
+        biggest = max(e.get("output_bytes", 0) for e in builds)
+        note("context-size", "warn" if biggest > 100_000 else "ok",
+             {"max_context_bytes": biggest, "builds": len(builds)},
+             "narrow scope or raise detail via refs" if biggest > 100_000
+             else "")
+    else:
+        note("context-size", "unresolved", {"builds": 0})
+
+    # --- provider calls --------------------------------------------------
+    prov = _read_jsonl(led / "provider.jsonl") + [
+        e for e in econ if e.get("entry_type") == "provider"]
+    if prov:
+        calls = sum(e.get("api_calls", e.get("calls", 0)) or 0
+                    for e in prov)
+        note("provider-calls", "warn" if calls > 50 else "ok",
+             {"api_calls": calls, "entries": len(prov)},
+             "check evidence_gate — local evidence may answer")
+    else:
+        note("provider-calls", "unresolved", {"entries": 0})
+
+    # --- stale checkpoints ----------------------------------------------
+    cps = CheckpointStore(root / ".platformforge" / "checkpoints")
+    names = cps.list()
+    stale = []
+    for n in names:
+        cp = cps.load(n)
+        if cp and now - cp.created_at > 7 * 86400:
+            stale.append(n)
+    note("stale-checkpoints",
+         "warn" if stale else "ok",
+         {"checkpoints": len(names), "stale_7d": stale},
+         "gc or resume — spend may be double-counted" if stale else "")
+
+    # --- missing pricing ---------------------------------------------------
+    econ_missing = [e for e in econ
+                    if e.get("code") == "PF-ECONOMY-PRICING-MISSING" or
+                    e.get("refusal") == "PF-ECONOMY-PRICING-MISSING"]
+    note("pricing", "warn" if econ_missing else "ok",
+         {"missing_pricing_events": len(econ_missing)},
+         "declare a pricing row" if econ_missing else "")
+
+    # --- closure health (polish §41–43) ----------------------------------
+
+    # receipt freshness — bound to HEAD or HEAD~1 (receipt-only commit)
+    rcpt = root / RECEIPT_REL
+    if not rcpt.is_file():
+        note("receipt-fresh", "unresolved",
+             {"code": "PF-ECONOMY-RECEIPT-STALE", "path": str(rcpt)},
+             "generate: python scripts/validate.py --economy-receipt "
+             f"{RECEIPT_REL}")
+    else:
+        doc = json.loads(rcpt.read_text())
+        vs = doc.get("validated_sha") or ""
+        head = subprocess.run(
+            ["git", "rev-parse", "HEAD"], cwd=root,
+            capture_output=True, text=True, check=False).stdout.strip()
+        head1 = subprocess.run(
+            ["git", "rev-parse", "HEAD~1"], cwd=root,
+            capture_output=True, text=True, check=False).stdout.strip()
+        schema_ok = doc.get("schema") == RECEIPT_SCHEMA
+        if vs and head and vs in (head, head1) and schema_ok:
+            note("receipt-fresh", "ok",
+                 {"validated_sha": vs[:12], "schema": doc["schema"]})
+        else:
+            note("receipt-fresh", "warn",
+                 {"code": "PF-ECONOMY-RECEIPT-STALE",
+                  "validated_sha": vs[:12], "head": head[:12],
+                  "schema": doc.get("schema")},
+                 "receipt predates HEAD or wrong schema — regenerate "
+                 "via scripts/validate.py --economy-receipt")
+
+        # gate taxonomy — receipt gates must be canonical economy-* names
+        canon = _canonical_economy_gates(root)
+        extra = sorted(set(doc.get("gates", {})) - canon)
+        note("gate-taxonomy", "warn" if extra else "ok",
+             {"noncanonical": extra, "canonical": len(canon)},
+             "receipt carries a parallel taxonomy — regenerate from the "
+             "validator" if extra else "")
+
+        # reproduce paths — every tests/*.py referenced must exist
+        dead = [t for e in doc.get("gates", {}).values()
+                for t in re.findall(r"tests/\S+\.py",
+                                    str(e.get("reproduce") or ""))
+                if not (root / t).is_file()]
+        note("reproduce-paths", "warn" if dead else "ok",
+             {"dead_paths": dead},
+             "regenerate the receipt — test files moved" if dead else "")
+
+    # routing authority — EconomyEngine advises; routing.decide() decides
+    try:
+        from platformforge.economy.engine import EconomyEngine
+        adv = EconomyEngine(root).advice({"task_type": "analysis"})
+        marked = adv.get("schema") == "platformforge/economy-advice/v1" \
+            and adv.get("advisory") is True
+        note("routing-authority", "ok" if marked else "fail",
+             {"advice_schema": adv.get("schema"),
+              "advisory": adv.get("advisory")},
+             "EconomyEngine output lost its advisory marker — it must "
+             "never masquerade as a routing decision" if not marked
+             else "")
+    except Exception as exc:  # noqa: BLE001 — probe failure is data
+        note("routing-authority", "unresolved", {"error": str(exc)})
+
+    # QPT — quality-per-cost engine present and callable
+    try:
+        from platformforge.economy.qpt import quality_per_cost
+        probe = quality_per_cost({"quality_pass": True},
+                                 {"quality_pass": True})
+        note("qpt", "ok" if isinstance(probe, dict) else "unresolved",
+             {"callable": True})
+    except Exception as exc:  # noqa: BLE001 — probe failure is data
+        note("qpt", "unresolved", {"error": str(exc)})
+
+    states = {f["state"] for f in findings}
+    overall = ("fail" if "fail" in states else
+               "warn" if "warn" in states else
+               "unresolved" if states == {"unresolved"} else "ok")
+    return {"schema": SCHEMA, "overall": overall, "checks": findings,
+            "hint": "unresolved checks need data, not fixes"}

platformforge/economy/engine.py

@@ -0,0 +1,158 @@
+"""Economy engine — escalation policy + report over the token ledger.
+
+Order: cache → parser → index → rule → graph → local composition →
+cheap model → strong model → multi-agent. The engine decides the cheapest
+class that can answer a request, and reports *measured* consumption.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from platformforge.tokensave.ledger import LedgerEntry, TokenLedger
+
+COST_ORDER = [
+    "cache", "parser", "index", "rule", "graph", "local-composition",
+    "cheap-model", "strong-model", "multi-agent",
+]
+DETERMINISTIC_CLASSES = {"cache", "parser", "index", "rule", "graph",
+                         "local-composition"}
+
+
+@dataclass
+class CostClass:
+    name: str
+    deterministic: bool
+    needs_model: bool
+
+
+# §34 — execution strategies, cheapest first.
+STRATEGIES = ("deterministic-only", "deterministic-plus-compose",
+              "single-specialist", "multi-specialist", "coordinated",
+              "review-required", "refuse")
+
+# polish §22–26 — EconomyEngine output is an economic *recommendation*
+# (EconomyAdvice), never a routing decision. The canonical authority is
+# routing/decision.py::decide(); orchestration refuses anything without
+# the platformforge/routing-decision/v1 schema.
+SCHEMA_ADVICE = "platformforge/economy-advice/v1"
+
+# §35 — capability requirements, provider-agnostic. The host maps these to
+# models; the core never names a provider.
+CAPABILITY_REQS = ("fast", "cheap", "coding", "reasoning", "long-context",
+                   "review", "structured-output")
+
+
+class EconomyEngine:
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self.ledger = TokenLedger(root)
+
+    def advice(self, signal: dict[str, Any]) -> dict[str, Any]:
+        """§33 — economic recommendation = f(task, deterministic reach,
+        evidence, risk, criticality, complexity, budgets, history).
+
+        Deterministic reach is checked FIRST: a task the engines can answer
+        never escalates to a model. Evidence gaps refuse rather than spend.
+
+        The output is an `economy-advice/v1` advisory — it informs a
+        RoutingRequest's signal but is NEVER a routing decision. The
+        canonical authority is `routing/decision.py::decide()`
+        (polish §22–26).
+        """
+        risk = signal.get("risk", "low")
+        complexity = signal.get("complexity", "low")
+        evidence_ready = signal.get("evidence_available", True)
+        blast = signal.get("blast_radius", "local")
+        security = signal.get("security_sensitive", False)
+        task_type = signal.get("task_type", "analysis")
+
+        base = self.cheapest_sufficient(
+            signal.get("question_kind", task_type), evidence_ready)
+        if base["cost_class"] == "unresolved":
+            return {"schema": SCHEMA_ADVICE, "advisory": True,
+                    "strategy": "refuse", "reason": base["reason"],
+                    "capability_requirements": []}
+        if base["deterministic"]:
+            return {"schema": SCHEMA_ADVICE, "advisory": True,
+                    "strategy": "deterministic-only",
+                    "cost_class": base["cost_class"], "reason": base["reason"],
+                    "capability_requirements": ["fast", "cheap"]}
+        caps = ["structured-output"]
+        if task_type in ("review", "incident") or security:
+            caps.append("review")
+        if complexity == "high" or blast in ("platform", "org"):
+            caps.extend(["reasoning", "long-context"])
+        if risk in ("high", "critical") or security:
+            strat = "review-required" if evidence_ready else "refuse"
+            reason = ("high risk/security-sensitive requires review"
+                      if evidence_ready else "insufficient evidence")
+        elif task_type == "incident" or blast in ("platform", "org"):
+            strat, reason = "coordinated", "cross-domain blast radius"
+        elif len(signal.get("domains", [])) > 1:
+            strat, reason = "multi-specialist", "multiple domains"
+        elif complexity in ("medium", "high"):
+            strat, reason = "single-specialist", "single-domain depth"
+        else:
+            strat, reason = "deterministic-plus-compose", "compose over facts"
+        return {"schema": SCHEMA_ADVICE, "advisory": True,
+                "strategy": strat, "reason": reason,
+                "capability_requirements": caps,
+                "cost_class": {"coordinated": "multi-agent",
+                               "multi-specialist": "multi-agent",
+                               "review-required": "strong-model",
+                               "single-specialist": "cheap-model",
+                               "deterministic-plus-compose": "local-composition",
+                               }[strat]}
+
+    def strategy(self, signal: dict[str, Any]) -> dict[str, Any]:
+        """Deprecated alias for `advice()` (polish §26 — kept for
+        compat; the semantic name is EconomyAdvice)."""
+        return self.advice(signal)
+
+    def compare(self, signal: dict[str, Any],
+                strategies: list[str] | None = None) -> dict[str, Any]:
+        """§36 — champion/challenger shadow mode. Runs the strategy picker
+        per named strategy and records both projections in the ledger; it
+        never enables one automatically."""
+        strategies = strategies or ["single-specialist", "coordinated"]
+        projections = {}
+        for s in strategies:
+            proj = self.strategy(signal)
+            proj["forced_strategy"] = s
+            projections[s] = proj
+            self.ledger.record(LedgerEntry(
+                operation="economy.compare",
+                token_basis="unknown",
+                extra={"signal": signal, "strategy": s,
+                       "projection": proj, "shadow": True}))
+        return {"mode": "shadow", "strategies": projections,
+                "note": "shadow comparison — no strategy auto-enabled"}
+
+    def cheapest_sufficient(self, question_kind: str,
+                            evidence_ready: bool = True) -> dict[str, Any]:
+        """Which cost class can answer? Deterministic wherever possible."""
+        deterministic_answers = {
+            "lint", "rule-check", "inventory", "diff", "drift", "graph-query",
+            "impact", "policy", "budget-check", "freshness", "scorecard",
+            "slo-calc", "redaction", "compaction", "routing",
+        }
+        if question_kind in deterministic_answers:
+            cls = {"lint": "rule", "rule-check": "rule", "inventory": "index",
+                   "diff": "parser", "drift": "graph", "graph-query": "graph",
+                   "impact": "graph", "policy": "rule", "budget-check": "cache",
+                   "freshness": "index", "scorecard": "local-composition",
+                   "slo-calc": "rule", "redaction": "parser",
+                   "compaction": "parser", "routing": "rule"}[question_kind]
+            return {"cost_class": cls, "deterministic": True,
+                    "reason": "answerable without a model"}
+        if not evidence_ready:
+            return {"cost_class": "unresolved", "deterministic": False,
+                    "reason": "insufficient evidence — refuse, don't spend a model"}
+        return {"cost_class": "cheap-model", "deterministic": False,
+                "reason": "requires composition beyond deterministic reach"}
+
+    def report(self) -> dict[str, Any]:
+        return {"cost_order": COST_ORDER, "ledger": self.ledger.report()}

platformforge/economy/envelope.py

@@ -0,0 +1,61 @@
+"""Context envelopes — the measured payload IS the consumed payload.
+
+Cycle 2.1 §34–50: the bytes a judge/model actually receives are the bytes
+the estimator counts. `serialize()` is the single canonical serializer for
+both the full and the optimized context, so `measured == evaluated` by
+construction. Deterministic working sets (facts the local engine reads)
+are `kind="deterministic"` and are never counted as model tokens unless
+someone serializes them into a `kind="model"` envelope.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.tokensave.estimate import estimate_tokens
+
+
+@dataclass
+class ContextEnvelope:
+    """Serializable context payload.
+
+    kind: "model" (would be sent to a model/agent) | "deterministic"
+          (local engine working set — not token spend).
+    """
+    kind: str = "model"
+    files: list[dict[str, Any]] = field(default_factory=list)
+    facts: list[dict[str, Any]] = field(default_factory=list)
+    findings: list[dict[str, Any]] = field(default_factory=list)
+    rules: list[str] = field(default_factory=list)
+    graph: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"kind": self.kind, "files": self.files, "facts": self.facts,
+                "findings": self.findings, "rules": self.rules,
+                "graph": self.graph, "metadata": self.metadata}
+
+    def serialize(self) -> bytes:
+        """Canonical wire format — one serializer for every envelope kind."""
+        return json.dumps(self.to_dict(), sort_keys=True,
+                          separators=(",", ":"), default=str).encode()
+
+    @property
+    def byte_size(self) -> int:
+        return len(self.serialize())
+
+    @property
+    def estimated_tokens(self) -> int:
+        """Local estimate — labeled `estimated`, never `observed`."""
+        return estimate_tokens(self.serialize())
+
+    def ledger_fields(self) -> dict[str, Any]:
+        """Fields for TokenLedger rows (§42)."""
+        if self.kind == "deterministic":
+            return {"deterministic_input_bytes": self.byte_size,
+                    "deterministic_fact_count": len(self.facts)}
+        return {"model_context_bytes": self.byte_size,
+                "model_context_tokens": self.estimated_tokens,
+                "deterministic_fact_count": 0}

platformforge/economy/fleetpack.py

@@ -0,0 +1,86 @@
+"""Cycle 5 Phase L — FleetContextPack (§213–219).
+
+Never load the full fleet into model context (§214). Hierarchical
+summary layers with per-layer budgets (§217–219): org → fleet →
+cluster → resource detail, drill-down on demand (§218). Selection is
+signal-driven (§216), deterministic, never an LLM call (§224–226).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+SELECTION_SIGNALS = ("task_scope", "fleet_scope", "team", "environment",
+                     "recent_changes", "risk", "hotspots",
+                     "graph_centrality", "incidents", "cost_anomaly")
+LAYERS = ("organization", "fleet", "cluster", "resource")
+
+# per-layer token budget defaults — cheapest sufficient first (§219)
+DEFAULT_BUDGETS = {"organization": 200, "fleet": 400, "cluster": 800,
+                   "resource": 1600}
+
+
+def _est_tokens(obj: Any) -> int:
+    return max(1, len(json.dumps(obj, sort_keys=True,
+                                 default=str)) // 4)
+
+
+def fleet_context_pack(signals: dict[str, Any],
+                       org_summary: dict[str, Any] | None = None,
+                       fleet_summaries: list[dict[str, Any]] | None = None,
+                       cluster_details: list[dict[str, Any]] | None = None,
+                       resource_details: list[dict[str, Any]] | None = None,
+                       budgets: dict[str, int] | None = None
+                       ) -> dict[str, Any]:
+    """§215–219 — build the pack bottom-up *within budget*.
+
+    Layers fill cheapest-first; overflow is reported as `deferred`
+    (drill-down handles it later — §218), never silently truncated.
+    """
+    b = {**DEFAULT_BUDGETS, **(budgets or {})}
+    pack: dict[str, Any] = {
+        "schema": "platformforge/fleet-context-pack/v1",
+        "selection_signals": {k: signals[k] for k in SELECTION_SIGNALS
+                              if k in signals},
+        "layers": {}, "deferred": [], "budgets": b}
+    sources = {"organization": org_summary,
+               "fleet": fleet_summaries or [],
+               "cluster": cluster_details or [],
+               "resource": resource_details or []}
+    used = 0
+    for layer in LAYERS:
+        data = sources[layer]
+        items = data if isinstance(data, list) else ([data] if data else [])
+        kept, deferred = [], 0
+        for item in items:
+            cost = _est_tokens(item)
+            if used + cost <= b[layer]:
+                kept.append(item)
+                used += cost
+            else:
+                deferred += 1
+        pack["layers"][layer] = {"items": kept, "tokens": sum(
+            _est_tokens(i) for i in kept)}
+        if deferred:
+            pack["deferred"].append({"layer": layer, "count": deferred,
+                                     "drill_down": True})
+    pack["total_tokens"] = used
+    pack["full_fleet_loaded"] = False      # §214 — by construction
+    return pack
+
+
+def drill_down(pack: dict[str, Any], layer: str,
+               items: list[dict[str, Any]],
+               budget: int = 1600) -> dict[str, Any]:
+    """§218 — expand one layer on demand, still budgeted."""
+    kept, cost, deferred = [], 0, 0
+    for item in items:
+        t = _est_tokens(item)
+        if cost + t <= budget:
+            kept.append(item)
+            cost += t
+        else:
+            deferred += 1
+    return {"layer": layer, "items": kept, "tokens": cost,
+            "deferred": deferred}