platformforge 0.1.0__py3-none-any.whl

platformforge/agents/__init__.py

@@ -0,0 +1,156 @@
+"""Agent layer — canonical roster, contracts, host mirrors, referee,
+playbooks, orchestration machinery (cycle5.1).
+
+Agents propose; they never mutate. Every host mirror (.claude/, .agents/,
+.codex/, .devin/, agents/) is GENERATED from this roster — never
+hand-edited. Deterministic engines remain the authority; agents
+interpret, coordinate, review, verify and explain.
+"""
+
+from platformforge.agents.bench import run_agent_bench
+from platformforge.agents.contextpack import (
+    AgentContextPack,
+    build_pack,
+    delta_pack,
+)
+from platformforge.agents.contracts import (
+    ACCESS_TIERS,
+    BUDGET_CLASSES,
+    MODEL_TIERS,
+    OUTPUT_STATUSES,
+    ROLES,
+    ROUTING_MODES,
+    TASK_STATES,
+    WRITE_SCOPES,
+    AgentHandoff,
+    AgentRefusal,
+    AgentRunEnvelope,
+    AgentRunRecord,
+    Debate,
+    DebatePosition,
+    PlatformTaskSpec,
+    envelope_for,
+    refusal,
+)
+from platformforge.agents.coordinators import (
+    COORDINATOR_LOOPS,
+    collect,
+    coordinator_loop,
+    dispatch_plan,
+)
+from platformforge.agents.critic import adversarial_review, pre_mortem
+from platformforge.agents.debate import run_debate
+from platformforge.agents.executors import (
+    EXECUTORS,
+    pf_extract,
+    pf_graph_build,
+    pf_inventory,
+    pf_judge,
+    pf_reconcile,
+    pf_simulate,
+    pf_synthesize,
+    pf_verify,
+)
+from platformforge.agents.guardian import release_review
+from platformforge.agents.orchestrator import (
+    DagNode,
+    OrchestrationPlan,
+    build_dag,
+    checkpoint,
+    load_loops,
+    prepare,
+    resume,
+    validate_dag,
+)
+from platformforge.agents.planner import plan
+from platformforge.agents.playbook import playbook
+from platformforge.agents.referee import referee
+from platformforge.agents.reviewers import (
+    OPS_SAFETY_CHECKLIST,
+    architecture_review,
+    ops_safety_review,
+    privacy_review,
+    security_review,
+)
+from platformforge.agents.roster import AGENTS, AgentSpec, coordinator_for, resolve
+from platformforge.agents.runledger import AgentRunLedger, AgentRunRow
+from platformforge.agents.runstore import RunStore
+from platformforge.agents.specialists import finding, grade
+from platformforge.agents.taskspec import (
+    expire,
+    require_sealed,
+    review,
+    seal,
+)
+from platformforge.agents.verifier import verify_run
+
+__all__ = [
+    "ACCESS_TIERS",
+    "AGENTS",
+    "BUDGET_CLASSES",
+    "COORDINATOR_LOOPS",
+    "EXECUTORS",
+    "MODEL_TIERS",
+    "OPS_SAFETY_CHECKLIST",
+    "OUTPUT_STATUSES",
+    "ROLES",
+    "ROUTING_MODES",
+    "TASK_STATES",
+    "WRITE_SCOPES",
+    "AgentContextPack",
+    "AgentHandoff",
+    "AgentRefusal",
+    "AgentRunEnvelope",
+    "AgentRunLedger",
+    "AgentRunRecord",
+    "AgentRunRow",
+    "AgentSpec",
+    "DagNode",
+    "Debate",
+    "DebatePosition",
+    "OrchestrationPlan",
+    "PlatformTaskSpec",
+    "RunStore",
+    "adversarial_review",
+    "architecture_review",
+    "build_dag",
+    "build_pack",
+    "checkpoint",
+    "collect",
+    "coordinator_for",
+    "coordinator_loop",
+    "delta_pack",
+    "dispatch_plan",
+    "envelope_for",
+    "expire",
+    "finding",
+    "grade",
+    "load_loops",
+    "ops_safety_review",
+    "pf_extract",
+    "pf_graph_build",
+    "pf_inventory",
+    "pf_judge",
+    "pf_reconcile",
+    "pf_simulate",
+    "pf_synthesize",
+    "pf_verify",
+    "plan",
+    "playbook",
+    "pre_mortem",
+    "prepare",
+    "privacy_review",
+    "referee",
+    "refusal",
+    "release_review",
+    "require_sealed",
+    "resolve",
+    "resume",
+    "review",
+    "run_agent_bench",
+    "run_debate",
+    "seal",
+    "security_review",
+    "validate_dag",
+    "verify_run",
+]

platformforge/agents/bench.py

@@ -0,0 +1,61 @@
+"""Agentic strategy benchmark (§118–121, §197–198).
+
+Six fixed tasks routed under each strategy mode. What we measure NOW
+is deterministic: agents dispatched, fanout, budget class, DAG depth —
+the *cost side*. Quality claims (correctness, evidence recall, false
+positives) only become measurable when AgentRunLedger has real run
+rows; this bench never fabricates those — it reports `measured` vs
+`projected` honestly (§119: do not assume multi-agent is better —
+prove it, with data, not vibes).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.routing import TaskSignal, route
+
+# §198 — the benchmark task set, fixed.
+BENCH_TASKS: dict[str, TaskSignal] = {
+    "terraform-review": TaskSignal(task_type="review", domains=["iac"],
+                                   complexity="low", risk="low"),
+    "k8s-drift": TaskSignal(task_type="analysis", domains=["k8s"],
+                            complexity="medium"),
+    "aws-security": TaskSignal(task_type="review", domains=["aws"],
+                               security_sensitive=True, risk="high"),
+    "incident": TaskSignal(task_type="incident", domains=["k8s", "sre"],
+                           incident_status="active", risk="high"),
+    "fleet-optimization": TaskSignal(task_type="analysis",
+                                     domains=["fleet", "finops"],
+                                     optimization=True,
+                                     fleet_scope=True),
+    "platform-audit": TaskSignal(task_type="analysis",
+                                 domains=["iac", "k8s", "aws",
+                                          "security", "finops"],
+                                 complexity="high"),
+}
+
+
+def run_agent_bench() -> dict[str, Any]:
+    """Projected cost per task per mode — honest projection, not a
+    measured-quality claim. Real quality comparison lands in the run
+    ledger once runs exist (§118–121)."""
+    per_task: dict[str, Any] = {}
+    for name, sig in BENCH_TASKS.items():
+        got = route(sig)
+        n_agents = (len(got["specialists"]) + len(got["reviewers"])
+                    + bool(got["coordinator"]) + bool(got["verifier"]))
+        per_task[name] = {
+            "mode": got["mode"], "budget": got["budget"],
+            "agents": n_agents, "specialists": len(got["specialists"]),
+            "reviewers": len(got["reviewers"]),
+            "dag_stages": len(got["dag"]),
+            "verifier": bool(got["verifier"]),
+            "measured": "projected",
+            "note": "cost projection from router output — quality "
+                    "comparison needs real run rows (§119)"}
+    return {"tasks": per_task, "strategies_compared":
+            ["deterministic", "single-specialist", "multi-specialist",
+             "coordinated", "debate"],
+            "verdict": "benchmark is projection-only until run ledger "
+                       "has observed rows — no quality claim made"}

platformforge/agents/contextpack.py

@@ -0,0 +1,137 @@
+"""AgentContextPack — the bounded, measured payload an agent receives
+(§109–116). Never the whole repository: task summary + relevant evidence
++ graph neighborhood + rules + knowledge refs + recent operations +
+open questions, fitted to the run's budget class.
+
+A pack is immutable once built. Follow-up agents receive
+`previous_hash + delta` instead of a re-shipped context (§116) — the
+shared evidence section is reused by reference, not re-sent.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.tokensave.estimate import estimate_tokens
+
+
+def _canon(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      default=str).encode()
+
+
+@dataclass
+class AgentContextPack:
+    """§110/111 — everything an agent needs, nothing it doesn't."""
+    task_summary: str = ""
+    evidence: list[dict[str, Any]] = field(default_factory=list)
+    graph_neighborhood: dict[str, Any] = field(default_factory=dict)
+    rules: list[dict[str, Any]] = field(default_factory=list)
+    knowledge_refs: list[str] = field(default_factory=list)
+    recent_operations: list[dict[str, Any]] = field(default_factory=list)
+    open_questions: list[str] = field(default_factory=list)
+    budget_class: str = "standard"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"task_summary": self.task_summary,
+                "evidence": self.evidence,
+                "graph_neighborhood": self.graph_neighborhood,
+                "rules": self.rules,
+                "knowledge_refs": self.knowledge_refs,
+                "recent_operations": self.recent_operations,
+                "open_questions": self.open_questions,
+                "budget_class": self.budget_class}
+
+    def serialize(self) -> bytes:
+        return _canon(self.to_dict())
+
+    @property
+    def byte_size(self) -> int:
+        return len(self.serialize())
+
+    @property
+    def estimated_tokens(self) -> int:
+        return estimate_tokens(self.serialize())
+
+    @property
+    def content_hash(self) -> str:
+        """Content-address — handoffs carry this, not the body (§73)."""
+        return hashlib.sha256(self.serialize()).hexdigest()[:16]
+
+    def fits(self, max_context_bytes: int) -> dict[str, Any]:
+        """Measured bytes vs the run's context ceiling — no guessing."""
+        return {"context_bytes": self.byte_size,
+                "max_context_bytes": max_context_bytes,
+                "fits": self.byte_size <= max_context_bytes,
+                "estimated_tokens": self.estimated_tokens,
+                "hash": self.content_hash}
+
+
+def build_pack(task_summary: str, *, evidence=None, graph_neighborhood=None,
+               rules=None, knowledge_refs=None, recent_operations=None,
+               open_questions=None, budget_class: str = "standard",
+               max_context_bytes: int | None = None,
+               ) -> dict[str, Any]:
+    """Assemble a pack, dropping *optional* sections first when it
+    exceeds the byte ceiling. Evidence and open questions are
+    essential — a pack that can't carry them reports `fits: False`
+    rather than silently truncating."""
+    optional_order = ["recent_operations", "knowledge_refs",
+                      "graph_neighborhood", "rules"]
+    pack = AgentContextPack(
+        task_summary=task_summary, evidence=list(evidence or []),
+        graph_neighborhood=dict(graph_neighborhood or {}),
+        rules=list(rules or []),
+        knowledge_refs=list(knowledge_refs or []),
+        recent_operations=list(recent_operations or []),
+        open_questions=list(open_questions or []),
+        budget_class=budget_class)
+    dropped = []
+    if max_context_bytes:
+        for section in optional_order:
+            if pack.byte_size <= max_context_bytes:
+                break
+            cur = getattr(pack, section)
+            setattr(pack, section, {} if isinstance(cur, dict) else [])
+            dropped.append(section)
+    fit = pack.fits(max_context_bytes or 2**63)
+    return {"pack": pack.to_dict(), "hash": pack.content_hash,
+            "context_bytes": pack.byte_size,
+            "estimated_tokens": pack.estimated_tokens,
+            "dropped_optional": dropped,
+            "fits": fit["fits"],
+            "note": ("essential content (evidence + open questions) exceeds "
+                     "budget — narrow the task, don't truncate"
+                     if not fit["fits"] else "ok")}
+
+
+def delta_pack(previous_hash: str, previous: dict[str, Any],
+               current: AgentContextPack) -> dict[str, Any]:
+    """§116 — follow-up context: previous hash + only what changed."""
+    prev = previous or {}
+    cur = current.to_dict()
+    delta: dict[str, Any] = {}
+    for key, cur_v in cur.items():
+        if key == "budget_class":
+            continue
+        prev_v = prev.get(key)
+        if prev_v == cur_v:
+            continue
+        if isinstance(cur_v, list) and isinstance(prev_v, list):
+            prev_set = {json.dumps(i, sort_keys=True, default=str)
+                        for i in prev_v}
+            delta[key] = [i for i in cur_v
+                          if json.dumps(i, sort_keys=True, default=str)
+                          not in prev_set]
+        else:
+            delta[key] = cur_v
+    delta_bytes = len(_canon(delta))
+    full_bytes = current.byte_size
+    return {"base_hash": previous_hash, "delta": delta,
+            "delta_bytes": delta_bytes, "full_bytes": full_bytes,
+            "reused_bytes": max(0, full_bytes - delta_bytes),
+            "savings_pct": round(100 * (1 - delta_bytes / full_bytes), 1)
+            if full_bytes else 0.0}