agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/enrich/governs_enricher.py

@@ -0,0 +1,152 @@
+"""``DecisionGovernsInferencer`` (feat-010 follow-up) — the optional LLM pass that
+proposes ``GOVERNS`` edges for ADRs whose prose names no code.
+
+Only decisions with **zero parsed** ``GOVERNS`` edges are considered (the LLM
+fills the gap the deterministic parser left; it never overrides parsed links).
+Each considered decision's prose is matched against the repo's candidate symbols
+under a ``budget_usd`` cap (the framework ``BudgetPolicy``); matches above the
+confidence floor become ``GOVERNS`` edges with honest ``llm`` provenance. Re-run
+is idempotent — a considered decision's prior ``llm`` GOVERNS are cleared first
+(safe: it has no parsed GOVERNS to clobber). Off by default; ``ckg enrich
+--decisions`` runs it. Framework-layer (ADR-0001: ``enrich`` may import
+``agentforge``).
+"""
+
+from __future__ import annotations
+
+from agentforge_core.production.budget import BudgetPolicy
+from agentforge_core.production.exceptions import BudgetExceeded
+
+from agentforge_graph.core import (
+    Edge,
+    EdgeKind,
+    GraphQuery,
+    GraphStore,
+    Node,
+    NodeKind,
+    Provenance,
+)
+
+from .governs import GovernsCandidate, GovernsMatcher
+from .report import GovernsReport
+
+_ALL = 10_000_000
+_CANDIDATE_KINDS = {NodeKind.CLASS, NodeKind.FUNCTION, NodeKind.METHOD}
+
+
+class DecisionGovernsInferencer:
+    version = "infer-governs@1"  # bump on prompt change → re-infer
+
+    def __init__(
+        self,
+        repo: str,
+        matcher: GovernsMatcher,
+        *,
+        confidence_floor: float = 0.7,
+        budget_usd: float = 1.0,
+        max_candidates: int = 60,
+        commit: str = "",
+    ) -> None:
+        self.repo = repo
+        self.matcher = matcher
+        self.confidence_floor = confidence_floor
+        self.budget_usd = budget_usd
+        self.max_candidates = max(1, max_candidates)
+        self.commit = commit
+
+    async def enrich(self, store: GraphStore) -> GovernsReport:
+        report = GovernsReport()
+        nodes = (await store.query(GraphQuery(limit=_ALL))).nodes
+        decisions = [n for n in nodes if n.kind is NodeKind.DECISION]
+        report.decisions_total = len(decisions)
+        if not decisions:
+            return report
+
+        candidates = self._candidates(nodes)
+        report.candidates = len(candidates)
+        if not candidates:
+            return report
+
+        # only decisions the deterministic parser left ungoverned (no parsed link)
+        targets: list[Node] = []
+        for d in decisions:
+            govs = await store.adjacent(d.id, [EdgeKind.GOVERNS], "out")
+            if not any(e.provenance.source == "parsed" for e in govs):
+                targets.append(d)
+        report.decisions_considered = len(targets)
+        if not targets:
+            return report
+
+        budget = BudgetPolicy(usd=self.budget_usd, max_tokens=10**12, max_iterations=10**12)
+        facts: list[Node | Edge] = []
+        inferred_ids: list[str] = []
+        for d in targets:
+            try:
+                budget.check()
+            except BudgetExceeded:
+                report.budget_tripped = True
+                break
+            text = await self._decision_text(store, d.id)
+            before = self.matcher.cost_usd
+            matches = await self.matcher.match(d.attrs.get("title", d.name), text, candidates)
+            budget.commit(self.matcher.cost_usd - before)
+            report.cost_usd = round(self.matcher.cost_usd, 6)
+            inferred_ids.append(d.id)
+            for m in matches:
+                if m.confidence < self.confidence_floor:
+                    continue
+                prov = Provenance.llm(self.version, round(m.confidence, 4), self.commit)
+                facts.append(
+                    Edge(
+                        src=d.id,
+                        dst=m.symbol_id,
+                        kind=EdgeKind.GOVERNS,
+                        attrs={"confidence": round(m.confidence, 4), "rationale": m.rationale},
+                        provenance=prov,
+                    )
+                )
+                report.governs_inferred += 1
+
+        # idempotent re-infer: drop considered decisions' prior llm GOVERNS, then
+        # write the new ones. Safe because a considered decision has no *parsed*
+        # GOVERNS, so this never removes a deterministic link.
+        if inferred_ids:
+            await store.clear_outgoing(inferred_ids, EdgeKind.GOVERNS)
+        if facts:
+            await store.add(facts)
+        return report
+
+    def _candidates(self, nodes: list[Node]) -> list[GovernsCandidate]:
+        """Deterministic, bounded candidate set: in-repo Class/Function/Method
+        symbols sorted by id, capped. (Repo-map-ranked candidates are a refinement.)"""
+        out: list[GovernsCandidate] = []
+        for n in sorted(nodes, key=lambda z: z.id):
+            if n.kind not in _CANDIDATE_KINDS:
+                continue
+            from agentforge_graph.core import SymbolID
+
+            ps = SymbolID.parse(n.id)
+            out.append(
+                GovernsCandidate(
+                    symbol_id=n.id,
+                    name=n.name,
+                    kind=n.kind.value,
+                    signature=str(n.attrs.get("signature", "")),
+                    path=ps.path,
+                )
+            )
+            if len(out) >= self.max_candidates:
+                break
+        return out
+
+    @staticmethod
+    async def _decision_text(store: GraphStore, decision_id: str) -> str:
+        """The decision's prose — its DocChunk bodies, in order, bounded."""
+        chunks = [
+            n
+            for n in await store.neighbors(decision_id, [EdgeKind.CONTAINS], depth=1)
+            if n.kind is NodeKind.DOC_CHUNK
+        ]
+        chunks.sort(key=lambda n: int(n.attrs.get("seq", 0)))
+        parts = [f"{n.attrs.get('heading', '')}\n{n.attrs.get('text', '')}".strip() for n in chunks]
+        return "\n\n".join(p for p in parts if p)[:6000]

agentforge_graph/enrich/heuristics.py

@@ -0,0 +1,224 @@
+"""Stage-1 structural pattern heuristics (feat-012) — deterministic, no LLM.
+
+Cheap rules nominate *candidate* patterns for a symbol from its structure (name,
+methods, and graph neighbourhood). Recall over precision here: the LLM judge
+(stage 2) confirms or rejects each nomination, so a spurious candidate costs one
+judge call, while a missed one is never recovered. Framework-free and
+golden-tested. Each candidate carries ``evidence`` strings the judge must weigh,
+so the verdict cites structure (spec §8).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+from agentforge_graph.core import EdgeKind, GraphStore, Node, NodeKind, SymbolID
+
+# CRUD-ish method names that signal a Repository/DAO.
+_CRUD = {
+    "get",
+    "find",
+    "save",
+    "add",
+    "create",
+    "delete",
+    "remove",
+    "update",
+    "list",
+    "all",
+    "fetch",
+    "insert",
+    "query",
+    "load",
+    "store",
+}
+_FACTORY_VERBS = ("create", "make", "build", "new", "from_", "of")
+_OBSERVER_METHODS = {"notify", "subscribe", "unsubscribe", "update", "register", "emit"}
+
+# Role hints keyed by a name/base **suffix** → the pattern it nominates. Applied
+# to a class's own name and to its base classes (ENH-001).
+_ROLE_SUFFIXES: tuple[tuple[tuple[str, ...], str], ...] = (
+    (("Repository", "Repo", "DAO", "Store"), "Repository"),
+    (("Service", "UseCase", "Interactor"), "Service"),
+    (("Controller", "Resource", "Handler", "View"), "Controller"),
+    (("Factory",), "Factory"),
+    (("Builder",), "Builder"),
+    (("Strategy", "Policy"), "Strategy"),
+    (("Adapter",), "Adapter"),
+    (("Facade",), "Facade"),
+    (("Decorator",), "Decorator"),
+    (("Observer", "Listener", "Subscriber"), "Observer"),
+)
+# Extra name suffixes considered only in `recall="broad"` mode.
+_BROAD_SUFFIXES: tuple[tuple[tuple[str, ...], str], ...] = (
+    (("Manager", "Provider", "Engine", "Coordinator"), "Service"),
+    (("Gateway", "Client", "Wrapper", "Proxy"), "Adapter"),
+)
+# Base classes that don't imply an implementable role (skip for the Strategy
+# "implements an interface" broad signal).
+_TRIVIAL_BASES = {
+    "object",
+    "Exception",
+    "BaseException",
+    "BaseModel",
+    "Enum",
+    "StrEnum",
+    "IntEnum",
+    "Protocol",
+    "Generic",
+    "ABC",
+    "Dict",
+    "List",
+    "Set",
+    "Tuple",
+    "NamedTuple",
+    "TypedDict",
+    "dict",
+    "list",
+    "set",
+    "tuple",
+}
+_CLASS_BASES_RE = re.compile(r"class\s+\w+\s*\(([^)]*)\)")
+
+
+def _base_names(signature: str) -> list[str]:
+    """Base classes parsed from a class signature line (``class X(A, b.C):`` →
+    ``["A", "C"]``). Avoids needing INHERITS edges in the graph (ENH-001)."""
+    m = _CLASS_BASES_RE.search(signature)
+    if not m:
+        return []
+    bases: list[str] = []
+    for part in m.group(1).split(","):
+        part = part.strip()
+        if not part or "=" in part:  # skip metaclass=… / keyword bases
+            continue
+        leaf = part.split(".")[-1].split("[")[0].strip()  # abc.ABC→ABC, Generic[T]→Generic
+        if leaf[:1].isalpha():
+            bases.append(leaf)
+    return bases
+
+
+@dataclass
+class Candidate:
+    """A symbol nominated for one or more patterns, with the structure the judge
+    needs (so it doesn't re-query the graph)."""
+
+    symbol_id: str
+    name: str
+    kind: str
+    signature: str
+    methods: list[tuple[str, str]]  # (name, signature)
+    patterns: list[str] = field(default_factory=list)
+    evidence: list[str] = field(default_factory=list)
+
+
+def _suffix(name: str, *suffixes: str) -> bool:
+    low = name.lower()
+    return any(low.endswith(s.lower()) for s in suffixes)
+
+
+Recall = Literal["conservative", "broad"]
+
+
+class PatternHeuristics:
+    """Nominate candidate patterns for code symbols by structure. ``recall``
+    controls breadth: ``conservative`` (default) is name + base-class + shape
+    signals; ``broad`` also nominates extra name suffixes and ABC
+    implementations (more judge calls, higher recall) — ENH-001."""
+
+    def __init__(self, recall: Recall = "conservative") -> None:
+        self.recall = recall
+
+    async def nominate(self, store: GraphStore, symbol_ids: list[str]) -> list[Candidate]:
+        out: list[Candidate] = []
+        for sid in symbol_ids:
+            node = await store.get(sid)
+            if node is None or node.kind not in (NodeKind.CLASS, NodeKind.FUNCTION):
+                continue
+            methods = await self._methods(store, node.id) if node.kind is NodeKind.CLASS else []
+            cand = Candidate(
+                symbol_id=node.id,
+                name=node.name,
+                kind=node.kind.value,
+                signature=str(node.attrs.get("signature", "")),
+                methods=methods,
+            )
+            if node.kind is NodeKind.CLASS:
+                await self._class_patterns(store, cand)
+            else:
+                self._function_patterns(cand)
+            if cand.patterns:
+                out.append(cand)
+        return out
+
+    async def _methods(self, store: GraphStore, class_id: str) -> list[tuple[str, str]]:
+        methods: list[tuple[str, str]] = []
+        for edge in await store.adjacent(class_id, [EdgeKind.CONTAINS], "out"):
+            m = await store.get(edge.dst)
+            if m is not None and m.kind is NodeKind.METHOD:
+                methods.append((m.name, str(m.attrs.get("signature", ""))))
+        return methods
+
+    @staticmethod
+    def _nominate(c: Candidate, pattern: str, evidence: str) -> None:
+        if pattern not in c.patterns:
+            c.patterns.append(pattern)
+        c.evidence.append(evidence)
+
+    async def _class_patterns(self, store: GraphStore, c: Candidate) -> None:
+        names = {m.lower() for m, _ in c.methods}
+        crud = sorted(names & _CRUD)
+        bases = _base_names(c.signature)
+
+        # --- name-suffix signals ---
+        for suffixes, pattern in _ROLE_SUFFIXES:
+            if _suffix(c.name, *suffixes):
+                self._nominate(c, pattern, f"name ends with a {pattern} suffix ({c.name})")
+
+        # --- base-class signals (subclass of a role-named ABC) — ENH-001 ---
+        for base in bases:
+            for suffixes, pattern in _ROLE_SUFFIXES:
+                if _suffix(base, *suffixes):
+                    self._nominate(c, pattern, f"inherits {base} (a {pattern})")
+
+        # --- shape signals ---
+        if len(crud) >= (1 if self.recall == "broad" else 2):
+            self._nominate(c, "Repository", f"has CRUD-shaped methods: {', '.join(crud)}")
+        if any(m.lower().startswith(_FACTORY_VERBS) for m, _ in c.methods):
+            self._nominate(c, "Factory", "factory-verb methods (create/make/build/…)")
+        if "build" in names and any(
+            m.lower().startswith(("with_", "set_", "add_")) for m, _ in c.methods
+        ):
+            self._nominate(c, "Builder", "a build() method with fluent with_/set_ methods")
+        if "get_instance" in names or "instance" in names:
+            self._nominate(c, "Singleton", "get_instance/instance accessor")
+        if names & _OBSERVER_METHODS:
+            self._nominate(c, "Observer", "observer-shaped methods (notify/subscribe/…)")
+
+        behaviour = [m for m, _ in c.methods if not m.startswith("__")]
+        if not behaviour and (c.methods or _suffix(c.name, "DTO", "Dto", "ValueObject", "VO")):
+            tag = "DTO" if _suffix(c.name, "DTO", "Dto") else "ValueObject"
+            self._nominate(c, tag, "data-only class (no behaviour methods)")
+
+        # --- broad mode: extra suffixes + ABC-implementation as Strategy ---
+        if self.recall == "broad":
+            for suffixes, pattern in _BROAD_SUFFIXES:
+                if _suffix(c.name, *suffixes):
+                    self._nominate(c, pattern, f"name ends with {pattern}-ish suffix ({c.name})")
+            implementable = [b for b in bases if b not in _TRIVIAL_BASES]
+            if implementable and behaviour:
+                self._nominate(c, "Strategy", f"implements interface(s) {', '.join(implementable)}")
+
+    def _function_patterns(self, c: Candidate) -> None:
+        low = c.name.lower()
+        if low.startswith(_FACTORY_VERBS) and not low.startswith("__"):
+            c.patterns.append("Factory")
+            c.evidence.append(f"factory-verb function name ({c.name})")
+
+
+def class_and_function_ids(nodes: list[Node]) -> list[str]:
+    """Symbol ids eligible for pattern tagging (Class/Function), stable order."""
+    kinds = {NodeKind.CLASS, NodeKind.FUNCTION}
+    return sorted(n.id for n in nodes if n.kind in kinds and SymbolID.parse(n.id).descriptor)

agentforge_graph/enrich/judge.py

@@ -0,0 +1,63 @@
+"""The pattern judge interface (feat-012) — stage 2.
+
+A ``PatternJudge`` confirms or rejects a stage-1 ``Candidate``'s nominated
+patterns, returning a ``Verdict`` per pattern with confidence + rationale. The
+interface is injectable (the Embedder/FakeEmbedder pattern): the live
+``BedrockClaudeJudge`` (``bedrock.py``) is the only model-calling class, while
+``ScriptedJudge`` keeps the whole enricher deterministic and testable.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+from .heuristics import Candidate
+
+
+class Verdict(BaseModel):
+    pattern: str
+    is_match: bool
+    confidence: float = Field(ge=0.0, le=1.0)
+    rationale: str = ""
+
+
+@runtime_checkable
+class PatternJudge(Protocol):
+    async def judge(self, candidate: Candidate) -> list[Verdict]: ...
+
+    @property
+    def cost_usd(self) -> float:
+        """Cumulative USD spent so far (0 for the scripted judge)."""
+        ...
+
+
+ScriptFn = Callable[[Candidate], list[Verdict]]
+
+
+class ScriptedJudge:
+    """Deterministic judge for tests. Drive it with a function, or with the
+    default that confirms every nominated pattern at a fixed confidence. An
+    optional ``per_call_usd`` lets a test exercise the budget breaker."""
+
+    def __init__(self, fn: ScriptFn | None = None, per_call_usd: float = 0.0) -> None:
+        self._fn = fn or self._confirm_all
+        self._per_call_usd = per_call_usd
+        self._cost = 0.0
+
+    @staticmethod
+    def _confirm_all(candidate: Candidate) -> list[Verdict]:
+        return [
+            Verdict(pattern=p, is_match=True, confidence=0.9, rationale="scripted")
+            for p in candidate.patterns
+        ]
+
+    async def judge(self, candidate: Candidate) -> list[Verdict]:
+        self._cost += self._per_call_usd
+        return self._fn(candidate)
+
+    @property
+    def cost_usd(self) -> float:
+        return self._cost

agentforge_graph/enrich/registry.py

@@ -0,0 +1,133 @@
+"""Resolve enrichment models (pattern judge + summarizer) from ``EnrichConfig``
+via the provider registry.
+
+A single ``enrich.provider`` name selects both roles. Built-ins (``bedrock``,
+``anthropic``, ``scripted``) are registered below; third-party providers register
+out-of-tree under the ``agentforge_graph.judge_providers`` /
+``…summarizer_providers`` entry-point groups (``pip install`` + one
+``enrich.provider`` line, no core change). ``bedrock`` (boto3) and ``anthropic``
+(the anthropic SDK) are imported lazily so the scripted/offline path needs
+neither. ``anthropic`` is the direct Anthropic-API path for non-AWS users
+(ENH-003 phase 2). ``scripted`` is the deterministic, credential-free provider
+for CI and local runs without a model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from agentforge_graph.config import EnrichConfig
+from agentforge_graph.providers import resolve_provider
+
+from .governs import GovernsMatcher
+from .judge import PatternJudge
+from .summarizer import Summarizer
+
+JUDGE_GROUP = "agentforge_graph.judge_providers"
+SUMMARIZER_GROUP = "agentforge_graph.summarizer_providers"
+GOVERNS_GROUP = "agentforge_graph.governs_matcher_providers"
+
+JudgeBuilder = Callable[[EnrichConfig], PatternJudge]
+SummarizerBuilder = Callable[[EnrichConfig], Summarizer]
+GovernsMatcherBuilder = Callable[[EnrichConfig], GovernsMatcher]
+
+
+def _build_scripted_judge(cfg: EnrichConfig) -> PatternJudge:
+    from .judge import ScriptedJudge
+
+    return ScriptedJudge()
+
+
+def _build_bedrock_judge(cfg: EnrichConfig) -> PatternJudge:
+    from .bedrock import BedrockClaudeJudge  # lazy: only needs boto3 on this path
+
+    return BedrockClaudeJudge(cfg.model, cfg.region, cfg.assume_role_arn or None)
+
+
+def _build_anthropic_judge(cfg: EnrichConfig) -> PatternJudge:
+    from .anthropic import AnthropicClaudeJudge  # lazy: only needs the anthropic SDK here
+
+    return AnthropicClaudeJudge(
+        cfg.model, api_key_env=cfg.api_key_env or "ANTHROPIC_API_KEY", base_url=cfg.base_url
+    )
+
+
+def _build_scripted_summarizer(cfg: EnrichConfig) -> Summarizer:
+    from .summarizer import ScriptedSummarizer
+
+    return ScriptedSummarizer()
+
+
+def _build_bedrock_summarizer(cfg: EnrichConfig) -> Summarizer:
+    from .bedrock_summarizer import BedrockClaudeSummarizer  # lazy: boto3 on this path
+
+    return BedrockClaudeSummarizer(cfg.model, cfg.region, cfg.assume_role_arn or None)
+
+
+def _build_anthropic_summarizer(cfg: EnrichConfig) -> Summarizer:
+    from .anthropic import AnthropicClaudeSummarizer  # lazy: anthropic SDK on this path
+
+    return AnthropicClaudeSummarizer(
+        cfg.model, api_key_env=cfg.api_key_env or "ANTHROPIC_API_KEY", base_url=cfg.base_url
+    )
+
+
+def _build_scripted_governs_matcher(cfg: EnrichConfig) -> GovernsMatcher:
+    from .governs import ScriptedMatcher
+
+    return ScriptedMatcher()
+
+
+def _build_bedrock_governs_matcher(cfg: EnrichConfig) -> GovernsMatcher:
+    from .bedrock_client import BedrockClient  # lazy: boto3 only on this path
+    from .governs import ClaudeGovernsMatcher
+
+    client = BedrockClient(cfg.model, cfg.region, cfg.assume_role_arn or None)
+    return ClaudeGovernsMatcher(client, cfg.model)
+
+
+def _build_anthropic_governs_matcher(cfg: EnrichConfig) -> GovernsMatcher:
+    from .anthropic_client import AnthropicClient  # lazy: anthropic SDK only here
+    from .governs import ClaudeGovernsMatcher
+
+    client = AnthropicClient(cfg.model, cfg.api_key_env or "ANTHROPIC_API_KEY", cfg.base_url)
+    return ClaudeGovernsMatcher(client, client.model)
+
+
+_JUDGE_BUILTINS: dict[str, JudgeBuilder] = {
+    "bedrock": _build_bedrock_judge,
+    "anthropic": _build_anthropic_judge,
+    "scripted": _build_scripted_judge,
+}
+_SUMMARIZER_BUILTINS: dict[str, SummarizerBuilder] = {
+    "bedrock": _build_bedrock_summarizer,
+    "anthropic": _build_anthropic_summarizer,
+    "scripted": _build_scripted_summarizer,
+}
+_GOVERNS_BUILTINS: dict[str, GovernsMatcherBuilder] = {
+    "bedrock": _build_bedrock_governs_matcher,
+    "anthropic": _build_anthropic_governs_matcher,
+    "scripted": _build_scripted_governs_matcher,
+}
+
+
+def judge_from_config(cfg: EnrichConfig) -> PatternJudge:
+    """Construct the ``PatternJudge`` selected by ``cfg.provider`` via the registry."""
+    builder = resolve_provider(cfg.provider, _JUDGE_BUILTINS, JUDGE_GROUP, role="judge")
+    return builder(cfg)
+
+
+def summarizer_from_config(cfg: EnrichConfig) -> Summarizer:
+    """Construct the ``Summarizer`` selected by ``cfg.provider`` via the registry."""
+    builder = resolve_provider(
+        cfg.provider, _SUMMARIZER_BUILTINS, SUMMARIZER_GROUP, role="summarizer"
+    )
+    return builder(cfg)
+
+
+def governs_matcher_from_config(cfg: EnrichConfig) -> GovernsMatcher:
+    """Construct the ``GovernsMatcher`` selected by ``cfg.provider`` (feat-010)."""
+    builder = resolve_provider(
+        cfg.provider, _GOVERNS_BUILTINS, GOVERNS_GROUP, role="governs_matcher"
+    )
+    return builder(cfg)

agentforge_graph/enrich/report.py

@@ -0,0 +1,60 @@
+"""Result types for LLM enrichment (feat-012)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class EnrichReport(BaseModel):
+    """Outcome of one ``PatternTagEnricher.enrich`` run."""
+
+    candidates: int = 0  # symbols the heuristics nominated
+    judged: int = 0  # candidates sent to the judge
+    tagged: int = 0  # TAGGED edges written (confirmed, above floor)
+    cost_usd: float = 0.0
+    budget_tripped: bool = False
+    by_pattern: dict[str, int] = Field(default_factory=dict)
+
+
+class TaggedInfo(BaseModel):
+    """One symbol's pattern tag, for ``CodeGraph.tagged`` / ``ckg_explain``."""
+
+    symbol_id: str
+    pattern: str
+    confidence: float
+    rationale: str
+
+    def to_dict(self) -> dict[str, object]:
+        return self.model_dump()
+
+
+class SummaryReport(BaseModel):
+    """Outcome of one ``SummaryEnricher.enrich`` run."""
+
+    files_summarized: int = 0
+    repo_summarized: bool = False
+    cost_usd: float = 0.0
+    budget_tripped: bool = False
+
+
+class GovernsReport(BaseModel):
+    """Outcome of one ``DecisionGovernsInferencer.enrich`` run (feat-010)."""
+
+    decisions_total: int = 0  # Decision nodes in the graph
+    decisions_considered: int = 0  # those with zero *parsed* GOVERNS (the LLM gap)
+    candidates: int = 0  # symbols offered to the matcher
+    governs_inferred: int = 0  # llm GOVERNS edges written (above the floor)
+    cost_usd: float = 0.0
+    budget_tripped: bool = False
+
+
+class SummaryInfo(BaseModel):
+    """One summary, for ``CodeGraph.summaries`` / ``ckg_explain``."""
+
+    target: str  # the symbol/file/repo node id it summarizes
+    level: str
+    text: str
+    path: str
+
+    def to_dict(self) -> dict[str, object]:
+        return self.model_dump()

agentforge_graph/enrich/summarizer.py

@@ -0,0 +1,62 @@
+"""The summarizer interface (feat-012 summaries) — injectable like PatternJudge.
+
+``BedrockClaudeSummarizer`` is the live adapter; ``ScriptedSummarizer`` keeps the
+bottom-up enricher (ordering, embedding, budget, idempotency) deterministic in
+CI with no model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+@dataclass
+class FileContext:
+    path: str
+    symbols: list[tuple[str, str]] = field(default_factory=list)  # (name, signature)
+    imports: list[str] = field(default_factory=list)
+
+
+class Summary(BaseModel):
+    text: str
+    model: str = ""
+
+
+@runtime_checkable
+class Summarizer(Protocol):
+    async def summarize_file(self, ctx: FileContext, max_words: int) -> Summary: ...
+
+    async def summarize_repo(
+        self, repo: str, file_summaries: list[tuple[str, str]], max_words: int
+    ) -> Summary: ...
+
+    @property
+    def cost_usd(self) -> float: ...
+
+
+FileFn = Callable[[FileContext], str]
+
+
+class ScriptedSummarizer:
+    """Deterministic summarizer for tests. The default derives a stable string
+    from the context; pass ``fn`` to script file summaries."""
+
+    def __init__(self, fn: FileFn | None = None) -> None:
+        self._fn = fn or (lambda ctx: f"summary of {ctx.path} ({len(ctx.symbols)} symbols)")
+        self._cost = 0.0
+
+    async def summarize_file(self, ctx: FileContext, max_words: int) -> Summary:
+        return Summary(text=self._fn(ctx), model="scripted")
+
+    async def summarize_repo(
+        self, repo: str, file_summaries: list[tuple[str, str]], max_words: int
+    ) -> Summary:
+        return Summary(text=f"repo {repo}: {len(file_summaries)} files", model="scripted")
+
+    @property
+    def cost_usd(self) -> float:
+        return self._cost