agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/knowledge/report.py

@@ -0,0 +1,32 @@
+"""Result types for ADR/knowledge ingestion (feat-010)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class KnowledgeStats(BaseModel):
+    """Outcome of one ``KnowledgeIngestor.ingest`` run."""
+
+    decisions_indexed: int = 0
+    governs_resolved: int = 0  # GOVERNS edges created from unambiguous mentions
+    mentions_unresolved: int = 0  # mentions seen but not linked (unknown/ambiguous)
+    docs_indexed: int = 0  # general doc files ingested (doc_globs, feat-010)
+    describes_resolved: int = 0  # DESCRIBES edges created from doc mentions
+    commits_indexed: int = 0  # commit messages ingested as DocChunks (feat-010)
+
+
+class DecisionInfo(BaseModel):
+    """One decision, for ``CodeGraph.decisions`` / ``ckg decisions`` / the
+    ``ckg_decisions`` tool."""
+
+    id: str
+    adr_id: str
+    title: str
+    status: str
+    date: str
+    path: str
+    governs: list[str] = Field(default_factory=list)  # node ids this decision governs
+
+    def to_dict(self) -> dict[str, object]:
+        return self.model_dump()

agentforge_graph/main.py

@@ -0,0 +1,21 @@
+# AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:c05d490b5a1c
+"""Entry point for the ``ckg`` / ``agentforge-graph`` console script.
+
+Dispatches to the CKG command-line interface (``ckg index`` today;
+``serve-mcp`` and friends land with feat-008). Engine config is read from
+``ckg.yaml``; framework config from ``agentforge.yaml``.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from agentforge_graph.cli import main as cli_main
+
+
+def main() -> None:
+    sys.exit(cli_main())
+
+
+if __name__ == "__main__":
+    main()

agentforge_graph/providers.py

@@ -0,0 +1,36 @@
+"""Generic model-provider registry: a config provider-name → builder callable.
+
+Mirrors the storage driver registry (``store/registry.py``) for the model layer
+(embedders, judges, summarizers). Built-in providers are registered in each
+role's ``_BUILTINS`` map; third-party providers register out-of-tree via
+entry-point groups, so they install as ``pip install`` + one config line with no
+core change.
+
+Engine-shared, deterministic — must not import ``agentforge`` (ADR-0001). Only
+stdlib ``importlib.metadata`` is used here.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from typing import cast
+
+
+class ProviderNotFound(ValueError):
+    """Raised when a config provider name matches no built-in and no entry point."""
+
+
+def resolve_provider[T](name: str, builtins: dict[str, T], group: str, *, role: str) -> T:
+    """Return the builder registered for ``name`` — a built-in first, otherwise an
+    entry point in ``group``. Raises ``ProviderNotFound`` (listing the built-ins
+    and the entry-point group) when nothing matches."""
+    if name in builtins:
+        return builtins[name]
+    for ep in entry_points(group=group):
+        if ep.name == name:
+            return cast(T, ep.load())
+    known = sorted(builtins)
+    raise ProviderNotFound(
+        f"unknown {role} provider {name!r}; built-in providers: {known} "
+        f"(third-party providers register under the {group!r} entry-point group)"
+    )

agentforge_graph/repomap/__init__.py

@@ -0,0 +1,14 @@
+"""agentforge_graph.repomap — Aider-style budget-aware repo map (feat-007).
+
+Personalized PageRank over the symbol graph → token-budgeted signature
+summary. Deterministic, LLM-free; imports nothing from ``agentforge``
+(ADR-0001).
+"""
+
+from __future__ import annotations
+
+from .rank import RankedSymbol
+from .render import render_map
+from .repomap import RepoMap
+
+__all__ = ["RankedSymbol", "RepoMap", "render_map"]

agentforge_graph/repomap/rank.py

@@ -0,0 +1,161 @@
+"""Rank symbols by structural importance: project a provenance-weighted
+symbol→symbol digraph (CALLS/REFERENCES/INHERITS) and run (personalized)
+PageRank — Aider's recipe. Deterministic and LLM-free.
+
+PageRank is a small dependency-free power iteration (networkx's `pagerank`
+pulls in scipy/numpy, which we don't want in the engine for a 20-line algo).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+
+from pydantic import BaseModel
+
+from agentforge_graph.core import EdgeKind, GraphQuery, NodeKind, Source, SymbolID
+from agentforge_graph.store import Store
+
+_RANK_EDGES = [EdgeKind.CALLS, EdgeKind.REFERENCES, EdgeKind.INHERITS]
+_ALL = 10_000_000
+
+
+class RankedSymbol(BaseModel):
+    id: str
+    name: str
+    kind: NodeKind
+    path: str
+    rank: float
+    signature: str
+
+
+def _edge_weight(weights: dict[str, float], source: Source) -> float:
+    return weights.get(source.value, 0.5)
+
+
+def _is_private_name(name: str) -> bool:
+    """A leading-underscore name is private — except dunders (``__init__``,
+    ``__call__``), which are public protocol surface."""
+    return name.startswith("_") and not (name.startswith("__") and name.endswith("__"))
+
+
+def _is_private_module(path: str) -> bool:
+    """A ``_``-prefixed module is internal (``_compat.py``, ``_winconsole.py``).
+    ``__init__`` is the package root — the de-facto public surface, not private."""
+    stem = path.rsplit("/", 1)[-1].split(".", 1)[0]
+    return stem.startswith("_") and stem != "__init__"
+
+
+def _privacy_multiplier(name: str, path: str, public_bias: float) -> float:
+    """ENH-007: a display-rank weight (not a filter) that demotes clearly-private
+    symbols. ``public_bias`` in [0, 1]; 0 disables. Private → ``1 - public_bias``."""
+    if public_bias <= 0.0:
+        return 1.0
+    if _is_private_name(name) or _is_private_module(path):
+        return max(0.0, 1.0 - public_bias)
+    return 1.0
+
+
+def _pagerank(
+    nodes: list[str],
+    out_edges: dict[str, dict[str, float]],
+    damping: float,
+    personalization: dict[str, float] | None,
+    max_iter: int = 100,
+    tol: float = 1e-9,
+) -> dict[str, float]:
+    n = len(nodes)
+    if n == 0:
+        return {}
+    if personalization and sum(personalization.values()) > 0:
+        total = sum(personalization.values())
+        teleport = {nid: personalization.get(nid, 0.0) / total for nid in nodes}
+    else:
+        teleport = {nid: 1.0 / n for nid in nodes}
+    rank = {nid: 1.0 / n for nid in nodes}
+    out_sum = {src: sum(dsts.values()) for src, dsts in out_edges.items()}
+    for _ in range(max_iter):
+        nxt = {nid: (1.0 - damping) * teleport[nid] for nid in nodes}
+        dangling = sum(rank[nid] for nid in nodes if out_sum.get(nid, 0.0) == 0.0)
+        for nid in nodes:
+            nxt[nid] += damping * dangling * teleport[nid]
+        for src, dsts in out_edges.items():
+            total = out_sum[src]
+            if total == 0.0:
+                continue
+            share = damping * rank[src] / total
+            for dst, weight in dsts.items():
+                nxt[dst] += share * weight
+        err = sum(abs(nxt[nid] - rank[nid]) for nid in nodes)
+        rank = nxt
+        if err < tol:
+            break
+    return rank
+
+
+async def rank_symbols(
+    store: Store,
+    kinds: list[NodeKind],
+    damping: float,
+    edge_weights: dict[str, float],
+    focus: Sequence[str] | None = None,
+    scope: str | None = None,
+    public_bias: float = 0.0,
+) -> list[RankedSymbol]:
+    nodes = (await store.graph.query(GraphQuery(kinds=kinds, limit=_ALL))).nodes
+    if scope is not None:
+        nodes = [n for n in nodes if SymbolID.parse(n.id).path.startswith(scope)]
+    by_id = {n.id: n for n in nodes}
+    if not by_id:
+        return []
+
+    out_edges: dict[str, dict[str, float]] = defaultdict(dict)
+    for node in nodes:
+        for edge in await store.graph.adjacent(node.id, _RANK_EDGES, "out"):
+            if edge.dst not in by_id:
+                continue
+            w = _edge_weight(edge_weights, edge.provenance.source)
+            out_edges[edge.src][edge.dst] = out_edges[edge.src].get(edge.dst, 0.0) + w
+
+    personalization = None
+    if focus:
+        focus_ids = _expand_focus(focus, set(by_id))
+        if focus_ids:
+            personalization = {nid: (1.0 if nid in focus_ids else 0.0) for nid in by_id}
+
+    scores = _pagerank(list(by_id), dict(out_edges), damping, personalization)
+    ranked = []
+    for node in nodes:
+        path = SymbolID.parse(node.id).path
+        # ENH-007: bias the *display* rank toward the public API. Applied after
+        # PageRank so the graph propagation is unchanged — private hubs still
+        # pass their centrality on; they just sort lower themselves.
+        rank = scores.get(node.id, 0.0) * _privacy_multiplier(node.name, path, public_bias)
+        ranked.append(
+            RankedSymbol(
+                id=node.id,
+                name=node.name,
+                kind=node.kind,
+                path=path,
+                rank=rank,
+                signature=str(node.attrs.get("signature", "")),
+            )
+        )
+    ranked.sort(key=lambda r: (-r.rank, r.id))  # id tiebreak for determinism
+    return ranked
+
+
+def _expand_focus(focus: Sequence[str], ids: set[str]) -> set[str]:
+    matched: set[str] = set()
+    paths: set[str] = set()
+    for f in focus:
+        if f in ids:
+            matched.add(f)
+        else:
+            paths.add(f)
+    if paths:
+        for nid in ids:
+            p = SymbolID.parse(nid).path
+            if any(p == fp or p.startswith(fp) for fp in paths):
+                matched.add(nid)
+    return matched

agentforge_graph/repomap/render.py

@@ -0,0 +1,55 @@
+"""Pack ranked symbols into a token budget, grouped by file (files ordered by
+their top symbol's rank). Whole signature lines only; a final note reports how
+many symbols fell below the budget — never a silent cap."""
+
+from __future__ import annotations
+
+from agentforge_graph.chunking import estimate_tokens
+
+from .rank import RankedSymbol
+
+
+def render_map(
+    ranked: list[RankedSymbol],
+    budget_tokens: int,
+    summaries: dict[str, str] | None = None,
+) -> str:
+    summaries = summaries or {}
+    by_file: dict[str, list[RankedSymbol]] = {}
+    order: list[str] = []
+    for r in ranked:
+        if r.path not in by_file:
+            by_file[r.path] = []
+            order.append(r.path)
+        by_file[r.path].append(r)
+
+    lines: list[str] = []
+    emitted = 0
+    full = False
+
+    def fits(extra: list[str]) -> bool:
+        # measure the whole accumulated content (estimate_tokens is non-additive)
+        return estimate_tokens("\n".join(lines + extra)) <= budget_tokens
+
+    for path in order:
+        if full:
+            break
+        header = f"{path}:"
+        # a one-line file summary (feat-012) under the header, when present
+        summary = summaries.get(path)
+        head: list[str] = [header, f"  # {summary}"] if summary else [header]
+        started = False
+        for r in by_file[path]:
+            line = f"  {r.signature or f'{r.name}(...)'}"
+            trial = [line] if started else [*head, line]
+            if not fits(trial):
+                full = True
+                break
+            lines.extend(trial)
+            started = True
+            emitted += 1
+
+    remaining = len(ranked) - emitted
+    if remaining > 0:
+        lines.append(f"… {remaining} more symbols below the budget")
+    return "\n".join(lines)

agentforge_graph/repomap/repomap.py

@@ -0,0 +1,66 @@
+"""``RepoMap`` facade: ranked symbols (structured) + a budget-packed text map."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from agentforge_graph.config import RepoMapConfig
+from agentforge_graph.core import EdgeKind, GraphQuery, NodeKind, SymbolID
+from agentforge_graph.store import Store
+
+from .rank import RankedSymbol, rank_symbols
+from .render import render_map
+
+
+class RepoMap:
+    def __init__(self, store: Store, config: RepoMapConfig) -> None:
+        self.store = store
+        self.config = config
+
+    def _kinds(self, override: list[NodeKind] | None) -> list[NodeKind]:
+        return override if override is not None else [NodeKind(k) for k in self.config.kinds]
+
+    async def ranked_symbols(
+        self, k: int = 100, focus: Sequence[str] | None = None
+    ) -> list[RankedSymbol]:
+        ranked = await rank_symbols(
+            self.store,
+            self._kinds(None),
+            self.config.damping,
+            self.config.edge_weights,
+            focus,
+            public_bias=self.config.public_bias,
+        )
+        return ranked[:k]
+
+    async def render(
+        self,
+        budget_tokens: int | None = None,
+        focus: Sequence[str] | None = None,
+        scope: str | None = None,
+        kinds: list[NodeKind] | None = None,
+    ) -> str:
+        budget = budget_tokens if budget_tokens is not None else self.config.default_budget
+        ranked = await rank_symbols(
+            self.store,
+            self._kinds(kinds),
+            self.config.damping,
+            self.config.edge_weights,
+            focus,
+            scope,
+            public_bias=self.config.public_bias,
+        )
+        return render_map(ranked, budget, await self._file_summaries())
+
+    async def _file_summaries(self) -> dict[str, str]:
+        """path -> file summary text (feat-012), when summaries have been run."""
+        nodes = (
+            await self.store.graph.query(GraphQuery(kinds=[NodeKind.SUMMARY], limit=10**9))
+        ).nodes
+        out: dict[str, str] = {}
+        for n in nodes:
+            if str(n.attrs.get("level")) != "file":
+                continue
+            for e in await self.store.graph.adjacent(n.id, [EdgeKind.SUMMARIZES], "out"):
+                out[SymbolID.parse(e.dst).path] = str(n.attrs.get("text", ""))
+        return out

agentforge_graph/retrieve/__init__.py

@@ -0,0 +1,21 @@
+"""agentforge_graph.retrieve — hybrid retrieval (feat-006).
+
+Vector entry → typed graph expansion → provenance-weighted merge, as one
+typed call. Deterministic and LLM-free in the retrieval path; imports
+nothing from ``agentforge`` (ADR-0001).
+"""
+
+from __future__ import annotations
+
+from .pack import ContextItem, ContextPack
+from .rerank import NoopReranker, Reranker
+from .retriever import Mode, Retriever
+
+__all__ = [
+    "ContextItem",
+    "ContextPack",
+    "Retriever",
+    "Mode",
+    "Reranker",
+    "NoopReranker",
+]

agentforge_graph/retrieve/pack.py

@@ -0,0 +1,76 @@
+"""The retrieval result: a ranked, deduped, connected context pack.
+
+``render`` packs highest-score items first, emits whole code blocks (never
+splits a chunk), and degrades an over-budget item to its signature line.
+``to_dict`` is the structured form feat-008 tools return.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from agentforge_graph.chunking import estimate_tokens
+from agentforge_graph.core import NodeKind, Source
+
+
+class ContextItem(BaseModel):
+    id: str  # symbol or chunk id
+    kind: NodeKind
+    name: str
+    score: float
+    path: str
+    span: tuple[int, int] | None = None
+    code: str | None = None  # chunk text, rendered verbatim
+    provenance: Source
+    why: list[str] = Field(default_factory=list)  # trace of how it was included
+    # feat-009: denormalised churn/authorship, present only when the temporal
+    # layer has mined this symbol (introduced/last_changed/churn_*/top_authors).
+    temporal: dict[str, Any] | None = None
+
+    def signature(self) -> str:
+        loc = f":{self.span[0]}-{self.span[1]}" if self.span else ""
+        return f"{self.path}{loc}  {self.name} ({self.kind.value})  score={self.score:.2f}"
+
+    def block(self) -> str:
+        if self.code:
+            return f"# {self.signature()}\n{self.code}"
+        return self.signature()
+
+
+class ContextPack(BaseModel):
+    query: str | None = None
+    symbol: str | None = None
+    mode: str = "context"
+    items: list[ContextItem] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+    def render(self, budget_tokens: int) -> str:
+        out: list[str] = []
+        used = 0
+        dropped = 0
+        for item in self.items:  # already score-sorted
+            block = item.block()
+            cost = estimate_tokens(block)
+            if used + cost <= budget_tokens:
+                out.append(block)
+                used += cost
+                continue
+            sig = item.signature()  # degrade to a signature instead of splitting
+            sig_cost = estimate_tokens(sig)
+            if used + sig_cost <= budget_tokens:
+                out.append(sig)
+                used += sig_cost
+            else:
+                dropped += 1
+        footer: list[str] = []
+        if dropped:
+            footer.append(f"… {dropped} more item(s) omitted (token budget)")
+        footer.extend(self.notes)
+        if footer:
+            out.append("\n".join(footer))
+        return "\n\n".join(out)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump()