platformforge 0.1.0__py3-none-any.whl

platformforge/agents/runledger.py

@@ -0,0 +1,85 @@
+"""Agent run ledger — per-run economy accounting (§117).
+
+Every agent invocation appends one row: model calls, context bytes,
+output bytes, tool calls, agents used, fanout, duration, cache reuse.
+Separate from TokenLedger (which tracks context engineering); this
+tracks *agentic* spend so quality-per-token can be compared across
+single-specialist vs coordinated strategies (§118–121).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AgentRunRow:
+    run_id: str
+    agent: str
+    mode: str = "single-specialist"     # router mode for comparability
+    model_calls: int = 0
+    context_bytes: int = 0
+    output_bytes: int = 0
+    tool_calls: int = 0
+    agents: int = 1
+    fanout: int = 0
+    duration_ms: float = 0.0
+    cache_reuse_bytes: int = 0          # §115 shared-pack reuse
+    delta_bytes: int = 0                # §116 delta-context savings
+    token_basis: str = "unknown"        # observed|estimated|unknown
+    transcript_ref: str | None = None
+    ts: float = field(default_factory=time.time)
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.token_basis not in ("observed", "estimated", "unknown"):
+            raise ValueError(f"bad token_basis {self.token_basis!r}")
+        if self.token_basis == "observed" and not self.transcript_ref:
+            raise ValueError(
+                "observed token counts require transcript_ref")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class AgentRunLedger:
+    def __init__(self, root: str | Path):
+        self.dir = Path(root) / ".platformforge" / "ledger"
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.dir / "agent-runs.jsonl"
+
+    def record(self, row: AgentRunRow) -> None:
+        with open(self.path, "a") as fh:
+            fh.write(json.dumps(row.to_dict(), default=str) + "\n")
+
+    def rows(self) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        return [json.loads(l) for l in self.path.read_text().splitlines()
+                if l.strip()]
+
+    def report(self) -> dict[str, Any]:
+        rows = self.rows()
+        def tot(k): return sum(r.get(k) or 0 for r in rows)
+        by_mode: dict[str, dict[str, Any]] = {}
+        for r in rows:
+            m = by_mode.setdefault(r.get("mode", "?"), {
+                "runs": 0, "model_calls": 0, "context_bytes": 0,
+                "tool_calls": 0, "duration_ms": 0.0,
+                "cache_reuse_bytes": 0})
+            m["runs"] += 1
+            for k in ("model_calls", "context_bytes", "tool_calls",
+                      "duration_ms", "cache_reuse_bytes"):
+                m[k] += r.get(k) or 0
+        return {"runs": len(rows), "agents_invoked": tot("agents"),
+                "model_calls": tot("model_calls"),
+                "context_bytes": tot("context_bytes"),
+                "output_bytes": tot("output_bytes"),
+                "tool_calls": tot("tool_calls"),
+                "cache_reuse_bytes": tot("cache_reuse_bytes"),
+                "delta_savings_bytes": tot("delta_bytes"),
+                "by_mode": by_mode}

platformforge/agents/runstore.py

@@ -0,0 +1,74 @@
+"""Agent run store — .platformforge/runs/ (§135–142).
+
+Append-only run records: task spec hash, router decision, agents,
+handoffs, budget, evidence refs, debates, gates, verifier, verdict.
+This is run *memory* — receipts and refs, not long-term agent memory
+(§134) and never user-specific context (§137).
+
+Resume preserves spent budget and prior evidence/decisions; it
+revalidates artifact hashes and observation freshness before
+continuing (§141–142).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from platformforge.agents.contracts import AgentRunRecord
+
+
+class RunStore:
+    def __init__(self, root: str | Path):
+        self.dir = Path(root) / ".platformforge" / "runs"
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, run_id: str) -> Path:
+        if "/" in run_id or ".." in run_id:
+            raise ValueError(f"bad run_id {run_id!r}")
+        return self.dir / f"{run_id}.json"
+
+    def save(self, record: AgentRunRecord) -> Path:
+        p = self._path(record.run_id)
+        p.write_text(json.dumps(record.to_dict(), indent=2,
+                                sort_keys=True, default=str))
+        return p
+
+    def load(self, run_id: str) -> AgentRunRecord | None:
+        p = self._path(run_id)
+        if not p.is_file():
+            return None
+        return AgentRunRecord.from_dict(json.loads(p.read_text()))
+
+    def runs(self) -> list[str]:
+        return sorted(p.stem for p in self.dir.glob("*.json"))
+
+    def resume(self, run_id: str, *, artifact_hashes: dict[str, str] |
+               None = None,
+               observation_freshness: str | None = None,
+               ) -> dict[str, Any]:
+        """§141–142 — resume preserves spent budget/decisions and
+        revalidates hashes + freshness before allowing continuation."""
+        rec = self.load(run_id)
+        if rec is None:
+            return {"resumed": False,
+                    "reason": f"no run record {run_id} — nothing to "
+                              "resume; start a new run"}
+        problems = []
+        if artifact_hashes:
+            for ref, h in artifact_hashes.items():
+                if not h:
+                    problems.append(f"{ref}: hash unreadable — "
+                                    "re-collect before resume")
+        if observation_freshness in ("stale", "superseded", "conflicted"):
+            problems.append(
+                f"observation freshness is {observation_freshness} — "
+                "re-collect runtime evidence before resume")
+        return {"resumed": not problems, "run_id": run_id,
+                "problems": problems,
+                "preserved": {"budget_spent": rec.budget.get("spent"),
+                              "evidence": list(rec.evidence),
+                              "decisions": list(rec.debates),
+                              "verdict": rec.verdict},
+                "note": "budget is never reset on resume (§141)"}

platformforge/agents/specialists.py

@@ -0,0 +1,73 @@
+"""Specialist machinery — the §98/§99 finding contract.
+
+Every specialist finding is a structured record — claim, status,
+evidence, coverage, freshness, confidence, limitations, next_action —
+never bare prose. `finding()` validates the shape; `grade()` demotes
+any status the evidence cannot carry (no evidence → never confirmed).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import OUTPUT_STATUSES, AgentRefusal, refusal
+from platformforge.models.base import stable_id
+
+# statuses that REQUIRE at least one evidence ref (§98 + §55)
+_EVIDENCE_STATUSES = ("confirmed", "supported", "refuted")
+
+
+def finding(agent: str, claim: str, *, status: str,
+            evidence: tuple[str, ...] = (),
+            coverage: float | None = None,
+            freshness: str = "unresolved",
+            confidence: str = "low",
+            limitations: tuple[str, ...] = (),
+            next_action: str = "") -> dict[str, Any]:
+    """One specialist finding. `status` ∈ OUTPUT_STATUSES; evidence
+    statuses with no evidence are demoted to `unsupported` with the
+    demotion recorded — never silently upgraded (§98)."""
+    if status not in OUTPUT_STATUSES:
+        return refusal(
+            AgentRefusal.HOST_CAPABILITY,
+            f"status {status!r} outside OUTPUT_STATUSES",
+            "use one of: " + ", ".join(OUTPUT_STATUSES))
+    demoted = False
+    asked = status
+    if status in _EVIDENCE_STATUSES and not evidence:
+        demoted = True
+        status = "unsupported"
+        limitations = tuple(limitations) + (
+            "demoted: status required evidence but none was cited",)
+    if coverage is not None:
+        try:
+            coverage = min(max(float(coverage), 0.0), 1.0)
+        except (TypeError, ValueError):
+            coverage = None
+    doc = {"finding_id": stable_id("PF-FND", agent, claim),
+           "agent": agent, "claim": claim, "status": status,
+           "evidence": list(evidence),
+           "coverage": coverage, "freshness": freshness,
+           "confidence": confidence,
+           "limitations": list(limitations),
+           "next_action": next_action}
+    if demoted:
+        doc["demoted_from"] = asked
+        doc["demoted"] = True
+    return doc
+
+
+def grade(findings: list[dict[str, Any]]) -> dict[str, Any]:
+    """Aggregate findings — counts per status; unsupported/absence is
+    surfaced, not hidden behind totals (§98)."""
+    by_status: dict[str, int] = {}
+    demoted = 0
+    for f in findings:
+        by_status[f.get("status", "unresolved")] = \
+            by_status.get(f.get("status", "unresolved"), 0) + 1
+        demoted += 1 if f.get("demoted") else 0
+    return {"total": len(findings), "by_status": by_status,
+            "demoted": demoted,
+            "ok": by_status.get("confirmed", 0)
+            + by_status.get("supported", 0)
+            + by_status.get("refuted", 0) > 0}

platformforge/agents/taskspec.py

@@ -0,0 +1,94 @@
+"""TaskSpec lifecycle — the deterministic `platform-task-spec-reviewer`.
+
+Review (§16) validates scope, evidence requirements, risk, rollback,
+acceptance criteria, unknowns and operation boundaries BEFORE any
+orchestration. A spec that fails review is rejected with notes; a spec
+that passes is `reviewed`, then `seal()`ed — sealed specs are
+content-hashed so the orchestrator executes exactly what was reviewed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import AgentRefusal, PlatformTaskSpec, refusal
+
+MUTATING_CAPS = ("ops.apply", "ops.approve", "federation.delegate",
+                 "change.apply", "cloud.mutate")
+
+# risk levels that force stronger governance on the spec itself
+_GOVERNED_RISK = ("high", "critical")
+
+
+def review(spec: PlatformTaskSpec,
+           reviewer: str = "platform-task-spec-reviewer") -> PlatformTaskSpec:
+    """draft → reviewed | rejected. Deterministic, explainable notes."""
+    if spec.state != "draft":
+        return spec  # only drafts are reviewed; caller sees current state
+    notes: list[str] = []
+    if not spec.intent.strip():
+        notes.append("intent is empty — nothing to plan against")
+    if not spec.acceptance_criteria:
+        notes.append("no acceptance_criteria — verifier would have "
+                     "nothing to check")
+    if not spec.evidence_requirements:
+        notes.append("no evidence_requirements — conclusions would be "
+                     "unverifiable")
+    if spec.risk in _GOVERNED_RISK:
+        if spec.rollback_requirement == "none":
+            notes.append(f"risk={spec.risk} requires a declared or "
+                         "material-bound rollback requirement")
+        missing = [c for c in MUTATING_CAPS
+                   if c not in spec.forbidden_capabilities]
+        if missing:
+            notes.append("risky spec must explicitly forbid: "
+                         + ", ".join(missing))
+    if spec.autonomy not in ("read-only", "propose", "simulate"):
+        notes.append(f"autonomy {spec.autonomy!r} outside read-only/"
+                     "propose/simulate — agents never execute")
+    if spec.budget not in ("tiny", "small", "standard", "deep",
+                           "critical"):
+        notes.append(f"unknown budget class {spec.budget!r}")
+    if not spec.domains and spec.complexity != "low":
+        notes.append("non-trivial spec with no domains — scope is "
+                     "unbounded")
+    if notes:
+        return spec.transition("rejected", reviewer=reviewer,
+                               notes=tuple(notes))
+    return spec.transition("reviewed", reviewer=reviewer,
+                           notes=(("scope/evidence/risk/rollback/"
+                                   "criteria validated"),))
+
+
+def seal(spec: PlatformTaskSpec) -> PlatformTaskSpec | dict[str, Any]:
+    """reviewed → sealed. Only sealed specs may orchestrate (§18)."""
+    if spec.state == "rejected":
+        return refusal(
+            AgentRefusal.SPEC_REJECTED,
+            "task spec was rejected: " + "; ".join(spec.review_notes),
+            "revise the spec against the review notes and re-review")
+    if spec.state != "reviewed":
+        return refusal(
+            AgentRefusal.SPEC_UNSEALED,
+            f"spec is {spec.state!r}, expected 'reviewed'",
+            "run the task-spec reviewer first")
+    return spec.transition("sealed")
+
+
+def expire(spec: PlatformTaskSpec) -> PlatformTaskSpec:
+    return spec.transition("expired")
+
+
+def require_sealed(spec: PlatformTaskSpec,
+                   complex_: bool = True) -> dict[str, Any] | None:
+    """§18 — orchestrators refuse unsealed specs for complex work.
+    Returns None when OK, else the refusal doc."""
+    if spec.state == "sealed":
+        return None
+    if not complex_ and spec.state == "reviewed":
+        return None
+    return refusal(
+        AgentRefusal.SPEC_UNSEALED,
+        f"orchestration requires a sealed TaskSpec (state={spec.state})",
+        "platformforge agents plan → review-spec → seal, then dispatch",
+        spec_state=spec.state)

platformforge/agents/uniqueness.py

@@ -0,0 +1,115 @@
+"""Agent fan-out economy (§117–129): uniqueness audit + selective
+agentics helpers.
+
+Per-run audit measures who actually contributed — unique vs duplicated
+vs refuted vs discarded contribution (§118). An agent that adds nothing
+is a candidate for routing reduction (§119) — a recommendation, never
+auto-applied (§115). No leaderboard: agents are graded as contribution
+records, not ranked as people (§120).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class AgentContribution:
+    agent: str
+    contribution_ids: list[str] = field(default_factory=list)
+    # finding/artifact ids the agent uniquely produced
+    refuted: list[str] = field(default_factory=list)
+    discarded: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentUniqueness:
+    """§117 — per-run fanout audit."""
+    run_id: str = ""
+    agents_invoked: list[str] = field(default_factory=list)
+    unique_contribution: dict[str, list[str]] = field(default_factory=dict)
+    duplicated_contribution: dict[str, list[str]] = field(
+        default_factory=dict)
+    refuted_contribution: dict[str, list[str]] = field(default_factory=dict)
+    discarded_contribution: dict[str, list[str]] = field(
+        default_factory=dict)
+    findings: list[dict[str, Any]] = field(default_factory=list)
+
+    def audit(self, contributions: list[AgentContribution]
+              ) -> AgentUniqueness:
+        """Classify each agent's output ids: an id claimed by ≥2 agents is
+        duplicated for the later claimants; refuted/discarded buckets come
+        from the contribution rows themselves."""
+        seen: dict[str, str] = {}
+        for c in contributions:
+            self.agents_invoked.append(c.agent)
+            unique, dup = [], []
+            for cid in c.contribution_ids:
+                if cid in seen:
+                    dup.append(cid)
+                else:
+                    seen[cid] = c.agent
+                    unique.append(cid)
+            if unique:
+                self.unique_contribution[c.agent] = unique
+            if dup:
+                self.duplicated_contribution[c.agent] = dup
+            if c.refuted:
+                self.refuted_contribution[c.agent] = list(c.refuted)
+            if c.discarded:
+                self.discarded_contribution[c.agent] = list(c.discarded)
+            if not unique and not c.refuted and not c.discarded \
+                    and not dup:
+                self.findings.append({
+                    "waste_type": "unused_agent", "agent": c.agent,
+                    "confidence": "high",
+                    "evidence": "invoked with zero contribution ids",
+                    "recommended_fix": "review routing rule — candidate "
+                                       "for fanout reduction"})
+            elif not unique and (dup or c.refuted or c.discarded):
+                self.findings.append({
+                    "waste_type": "unused_agent", "agent": c.agent,
+                    "confidence": "medium",
+                    "evidence": "all contribution ids duplicated, "
+                                "refuted or discarded",
+                    "recommended_fix": "routing review — contribution "
+                                       "overlapped entirely"})
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["agents_invoked_count"] = len(self.agents_invoked)
+        d["unique_ratio"] = (
+            sum(len(v) for v in self.unique_contribution.values()) /
+            max(1, sum(len(v) for v in self.unique_contribution.values())
+                + sum(len(v) for v in self.duplicated_contribution.values())))
+        return d
+
+
+# §123 — selective agentics policy (data, not judgment).
+def suggested_fanout(task_type: str, domains: list[str], risk: str,
+                     conflict: bool = False) -> dict[str, Any]:
+    """simple → ≤1 specialist; cross-domain → multi; conflict/high-risk
+    → debate/review. Mirrors the Router V2 policy as an economy check."""
+    if conflict or risk in ("high", "critical"):
+        mode, agents = "debate-or-review", 3
+    elif len(domains) > 1:
+        mode, agents = "multi-specialist", min(len(domains), 4)
+    elif task_type in ("lint", "inventory", "policy", "diff"):
+        mode, agents = "deterministic", 0
+    else:
+        mode, agents = "single-specialist", 1
+    return {"mode": mode, "suggested_max_agents": agents,
+            "reason": "§123 selective agentics"}
+
+
+def fanout_verdict(envelope_check: dict[str, Any], requested_agents: int,
+                   max_agents: int | None) -> dict[str, Any]:
+    """§122/§246 — fanout may never exceed the envelope's hard limit."""
+    if max_agents is not None and requested_agents > max_agents:
+        return {"refusal": "PF-ECONOMY-BUDGET-EXHAUSTED",
+                "reason": f"fanout {requested_agents} > max_agents "
+                          f"{max_agents}",
+                "dimension": "fanout"}
+    return {"decision": "ok", "fanout": requested_agents}

platformforge/agents/verifier.py

@@ -0,0 +1,106 @@
+"""platform-verifier machinery — independent closure check (§19–21).
+
+The verifier is deterministic and INDEPENDENT: the component that
+produced a conclusion cannot be its sole verifier. It maps acceptance
+criteria → evidence, checks coverage/freshness claims, recomputes
+receipts, and returns a verdict with a receipt — it never upgrades a
+claim the evidence doesn't carry.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import AgentRefusal, AgentRunRecord, refusal
+from platformforge.models.base import stable_id
+
+PRODUCER_ROLES = ("orchestrator", "planner", "coordinator",
+                  "specialist", "executor", "critic")
+
+
+def verify_run(record: AgentRunRecord,
+               *, spec: Any | None = None,
+               producers: tuple[str, ...] | None = None,
+               evidence_index: dict[str, Any] | None = None,
+               verifier: str = "platform-verifier") -> dict[str, Any]:
+    """Check a run record before closure.
+
+    record          the run under review
+    spec            the sealed PlatformTaskSpec (acceptance criteria)
+    producers       agents that produced the run's outputs
+    evidence_index  fact_id → fact doc (for existence/freshness checks)
+    """
+    # default producers = run agents minus the verifier itself — the
+    # verifier appears in record.agents as a DAG participant, but it is
+    # only independent if it produced none of the conclusions
+    producers = tuple(producers) if producers is not None else tuple(
+        a for a in record.agents if a != verifier)
+    problems: list[str] = []
+
+    # §21/§183 — independence: a producer cannot be the sole verifier
+    if verifier in producers:
+        return refusal(
+            AgentRefusal.SELF_VERIFICATION,
+            f"{verifier} produced this run and cannot verify it",
+            "assign a verifier that is not in the producer set",
+            producers=list(producers))
+    if record.verifier and record.verifier in producers:
+        return refusal(
+            AgentRefusal.INDEPENDENCE_FAILED,
+            f"declared verifier {record.verifier} is in the producer "
+            "set", "verify with an agent that produced no output here")
+
+    # §20 — criteria → evidence map
+    criteria = list(getattr(spec, "acceptance_criteria", ()) or ())
+    ev_index = evidence_index or {}
+    evidence = [e for e in record.evidence
+                if not ev_index or e in ev_index]
+    missing_ev = [e for e in record.evidence if e not in ev_index] \
+        if ev_index else []
+    unmapped = []
+    if criteria:
+        # a criterion is satisfied if any evidence or finding addresses
+        # it — deterministic check: evidence must exist at all
+        for c in criteria:
+            if not evidence:
+                unmapped.append(c)
+    if unmapped:
+        problems.append("criteria with no evidence: "
+                        + "; ".join(unmapped))
+    for f in getattr(spec, "evidence_requirements", ()) or ():
+        if not evidence and "coverage" not in f:
+            problems.append(f"evidence requirement unmet: {f}")
+
+    # freshness check when the index carries it
+    stale = [eid for eid, f in ev_index.items()
+             if isinstance(f, dict)
+             and f.get("freshness", {}).get("status")
+             in ("stale", "deprecated", "superseded")]
+    if stale:
+        problems.append("stale evidence cited: " + ", ".join(sorted(stale)))
+
+    verdict = "confirmed"
+    if problems:
+        verdict = "unresolved"
+    elif record.verdict in ("refuted", "unsupported"):
+        verdict = record.verdict  # never upgrade a refuted producer output
+    elif not evidence and record.evidence:
+        verdict = "unsupported"
+    elif not evidence:
+        verdict = "unresolved"
+    receipt_id = stable_id("PF-VRF", record.run_id, verdict)
+    out = {"verdict": verdict, "receipt": {
+        "receipt_id": receipt_id, "run_id": record.run_id,
+        "task_spec_hash": record.task_spec_hash,
+        "verifier": verifier,
+        "producers": list(producers),
+        "evidence_count": len(evidence),
+        "missing_evidence_refs": missing_ev,
+        "problems": problems}}
+    if verdict == "unresolved" and not evidence:
+        out.update(refusal(AgentRefusal.NO_EVIDENCE,
+                           "run closed with no verifiable evidence",
+                           "collect evidence for the declared criteria "
+                           "and re-verify"))
+        out["receipt"]["problems"] = problems
+    return out

platformforge/aiplat/__init__.py

@@ -0,0 +1,4 @@
+"""Cycle 5 — AI Platform Awareness: GPU/accelerator/model-serving
+platform concerns (§187–201). Detection + capacity + cost awareness;
+unit economics only with a real denominator; never terminates anything.
+"""