apexgraph 0.1.0__py3-none-any.whl

apexgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: apexgraph
+Version: 0.1.0
+Summary: Apex-relevance subgraph retrieval for AI agents. Feed your LLM the peak of your knowledge graph, sized to a token budget.
+Project-URL: Homepage, https://github.com/alfonsomayoral/graphex
+Project-URL: Repository, https://github.com/alfonsomayoral/graphex
+Project-URL: Issues, https://github.com/alfonsomayoral/graphex/issues
+Author-email: Alfonso Mayoral <alfonsomayoral29@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-tools,bm25,cli,graphify,knowledge-graph,llm,mcp,pagerank,rag,token-budget
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: networkx>=3.2
+Requires-Dist: pathspec>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dense
+Requires-Dist: anthropic>=0.34; extra == 'dense'
+Requires-Dist: openai>=1.40; extra == 'dense'
+Provides-Extra: ts
+Requires-Dist: tree-sitter-typescript>=0.23; extra == 'ts'
+Requires-Dist: tree-sitter>=0.22; extra == 'ts'
+Provides-Extra: viz
+Requires-Dist: watchdog>=4.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Graphex
+
+**Apex-relevance subgraph retrieval for AI agents.**
+
+Feed your LLM the *peak* of your knowledge graph — sized to a token budget.
+
+[![CI](https://github.com/alfonsomayoral/graphex/actions/workflows/ci.yml/badge.svg)](https://github.com/alfonsomayoral/graphex/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+---
+
+Knowledge graphs grow large. When an agent needs context about one corner of a
+codebase, dumping the whole graph into the prompt wastes tokens and money — and
+buries the relevant nodes in noise. **Graphex scores every node against your
+query and returns the most relevant, connected subgraph that fits within a token
+budget**, ready to paste into a prompt or serve over MCP.
+
+```bash
+graphex index .                            # build a graph from your code (no LLM)
+graphex "how does auth work" --budget 4000 # retrieve the apex subgraph
+graphex serve                              # expose it to agents over MCP
+```
+
+Graphex reads the graphs produced by **graphify** and uses the rich signals
+graphify emits — edge weights, confidence, hyperedges, communities, and god
+nodes — that simpler tools throw away.
+
+## Install
+
+```bash
+uv tool install apexgraph            # or: pipx install apexgraph
+# optional extras:
+uv tool install "apexgraph[ts]"      # better TypeScript indexing (tree-sitter)
+uv tool install "apexgraph[dense]"   # OpenAI/Anthropic embedding backend
+```
+
+The PyPI distribution is `apexgraph`; the command and import name are `graphex`.
+Requires Python 3.12+.
+
+## How it works
+
+A five-stage pipeline, each stage a single-responsibility module:
+
+```
+  load ─▶ score ─▶ select ─▶ inject ─▶ render
+   │        │         │         │         │
+ multi-   BM25 →    cost-aware  source-   markdown /
+ format   PPR +     MMR under   code      json / yaml
+ loader   prior     budget      bodies
+                        ▲
+   index ───────────────┘   build a graph straight from code (no graphify)
+```
+
+**Relevance is one principled number, not a hand-tuned mix.** BM25 finds the
+nodes the query is literally about; those seed a **Personalized PageRank** walk
+that spreads relevance across the weighted graph (edge `weight × confidence`,
+plus hyperedge cliques); a light importance/god-node prior nudges genuinely
+central entities up. The query-independent half — global PageRank, the BM25
+inverted index — is precomputed once and cached, invalidated by content hash, so
+a query is just a lookup plus one walk.
+
+**Selection is a budgeted knapsack, solved as one.** Picking the highest-value
+set of nodes under a token ceiling is the 0/1 knapsack problem. Graphex selects
+by *marginal value per token* and shapes the result with two terms — an MMR
+penalty so it doesn't say the same thing twice, and a connectivity bonus so the
+result is a coherent connected subgraph, not a bag of redundant islands. An exact
+DP-knapsack mode is available for benchmarking the value ceiling.
+
+**Token accounting is honest.** A node's cost is the size of its *final rendered
+form*, including any injected source code — so `tokens_used` never lies and the
+output never overflows the budget you asked for.
+
+## Usage
+
+```bash
+# Index a project into a graphify-compatible graph.json (Python / TS / Go)
+graphex index ./src -o graph.json
+graphex index ./src --incremental          # re-index only changed files
+
+# Query (any unrecognised first arg routes here)
+graphex "session token validation" -b 2000
+graphex "auth flow" --explain               # per-node BM25 / PPR / prior breakdown
+graphex "auth flow" --inject-code           # include real function bodies, still in budget
+graphex "auth flow" --viz                   # interactive force-directed HTML
+
+# Inspect (node ids come from your indexed graph; these match examples/)
+graphex stats -g examples/sample_graph.json
+graphex explain auth_service_login -g examples/sample_graph.json
+graphex path auth_service auth_service_login -g examples/sample_graph.json
+
+# Export a context block to paste into a system prompt / CLAUDE.md
+graphex export "auth flow" -f claudemd -o CONTEXT.md
+
+# Measure quality honestly (recall@budget, not just tokens saved)
+graphex benchmark -q "auth flow" -q "db pooling" -b 1000 -b 4000
+
+# Compare two graph versions and see the change impact
+graphex diff old.json new.json --budget 2000
+```
+
+See [`examples/`](examples/) for a full walkthrough on a sample project.
+
+## MCP server
+
+Graphex speaks the Model Context Protocol over stdio (stdlib only, no SDK):
+
+```bash
+graphex serve --graph graph.json
+```
+
+It exposes four tools: `graphex_query`, `graphex_explain`, `graphex_path`,
+`graphex_stats`. Register it with Claude Code:
+
+```bash
+claude mcp add graphex -- graphex serve --graph /abs/path/to/graph.json
+```
+
+## Honest benchmarking
+
+"Tokens saved" is a vanity metric — a tool that returns nothing saves 100%.
+Graphex reports **recall@budget** alongside it: how much of the relevant set the
+budgeted subgraph actually captures. High savings with low recall means
+under-retrieval, and the benchmark makes that trade-off visible.
+
+## Development
+
+```bash
+uv sync
+uv run pytest          # test suite
+uv run ruff check .    # lint
+uv run black .         # format
+```
+
+## License
+
+MIT © Alfonso Mayoral

apexgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+graphex/__init__.py,sha256=mjenbSPSekR-ZERd5ZCgcEt1PAdsNDEDHhZmLRNOzFk,304
+graphex/audit.py,sha256=-JtFuA5Lckh2ePdVgff4MC85rZiEjQpO9mk3SKwxyYU,3696
+graphex/benchmark.py,sha256=1SSAtJ4VjfCCOZn4H142aUfA-9CQR_1Jh02UshKg3dk,10374
+graphex/budget.py,sha256=DNYgM3nkBY0zmxvRUj9wb-1-Jn1M6LwU51m4N2UmWpE,12281
+graphex/cache.py,sha256=Y2krFu3zqYuzVPWZWgWHuODAe_ZOsgeAfS9qsm-X3KM,3723
+graphex/cli.py,sha256=6qbNO00ip4UQcwiJD0F9MfokA8y8zrbq8R0b97KVrk4,23493
+graphex/diff.py,sha256=EUo8aq2KDxPcZvKTqDCyVyDnUmdA1glBOgQvuiBVuhI,6565
+graphex/exporter.py,sha256=WwrVJ7MeOhD0zfC7dOviChKPjOPgHKzTIJIFCZPiQfw,4011
+graphex/formatter.py,sha256=cB_TiCiZir4UqzCBU2EJcavvSzrboZUlIsKMKRE-kc8,10232
+graphex/ignore.py,sha256=b22Jdj5xdc7UCrQNKW2K_omHJ5z1Vg1AZd1HPP7B5FU,3294
+graphex/injector.py,sha256=vXKBQwtLUOFbjZcVCbzYWGU1pcsWIkvOgv9IQWtoIP8,7378
+graphex/loader.py,sha256=dZFv1FyO-51tH7Dc1DYmLru_DrWPuT3TA47o1_kxdjU,23514
+graphex/mcp.py,sha256=h39GgLWxSbdfuNifyke31b8SpJqmRRDNHPuIk7WiupM,16847
+graphex/models.py,sha256=1L2pBzJlhlytGrHFpLFOdO9Cl7f0DSB9IfyIkbeF0OM,10979
+graphex/scorer.py,sha256=8h3iPIHVFL7dpeAXF76iOF-pk4djE295yEemvLIzMgs,3490
+graphex/viz.py,sha256=uOJjAcIHyp6itT0xAtS4y_5Gjp__erb-tsRf3o48xEY,11938
+graphex/indexer/__init__.py,sha256=hi9JbBond8GYj3uQ3wNnD_Z59b167UBLwghiHQeq2Tg,305
+graphex/indexer/go.py,sha256=1U0oxzOWp3EJoOdMfgglNIiIZhMboBZca-IhrsxMNRM,4466
+graphex/indexer/project.py,sha256=jfhaVMJPDevxOQfHlkQ0QzMLVZIWBxMY52zkhFOIXcQ,8886
+graphex/indexer/python.py,sha256=-8s_KSRc0SOmEPP9DD_lK0fWumJUUjc3uJ2obHIgLYg,6705
+graphex/indexer/typescript.py,sha256=Ua9BxONinoOa0so4GWsD6d_OsxJV-fGb_hB0W9-LCoI,9928
+graphex/retrieval/__init__.py,sha256=zlC4ekCbuUPBSD4YFcCUrW1Hh76rVnABCLTGwzEu2uA,295
+graphex/retrieval/base.py,sha256=WSsUnnRFs4v1I1zj5NrBJn-7c-n-9_K6Jkg67HaSFJU,1002
+graphex/retrieval/bm25.py,sha256=HIsWYVsILGzAmAC0Te_7zO7xMeGawdslAcxLxoK6i08,8650
+graphex/retrieval/dense.py,sha256=C6KajmcMWkNytSXMOO1Pvl7P4bpNEt4GPRviKfXy3zg,3136
+graphex/retrieval/fusion.py,sha256=LW-b44Vskm24PQ1i56m7R-iHFSb5zCUCqn9WvCKwIHU,2535
+graphex/retrieval/ppr.py,sha256=Ai15NuFdKFVdmg_NGu2aD-CEx39FFuve7IVwC_Rab7E,8325
+apexgraph-0.1.0.dist-info/METADATA,sha256=PbEVjDz_Q-cS8VUkflEjCzWRGLhYH-MBPFf5g5JXM2g,6848
+apexgraph-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+apexgraph-0.1.0.dist-info/entry_points.txt,sha256=8EFHKOF-yAm-QT7PeQCam3OKvjZzDqXP6hy30eNBQMI,44
+apexgraph-0.1.0.dist-info/licenses/LICENSE,sha256=Q88Aj987s01Cmk0M57h7w7_6V-vRtRCTPKZVQkscY8E,1072
+apexgraph-0.1.0.dist-info/RECORD,,

apexgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

apexgraph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+graphex = graphex.cli:cli

apexgraph-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alfonso Mayoral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphex/__init__.py

@@ -0,0 +1,8 @@
+"""Graphex — apex-relevance subgraph retrieval for AI agents.
+
+Given a knowledge graph (e.g. the output of `graphify`) and a natural-language
+query, Graphex selects the highest-relevance subgraph that fits within a token
+budget, ready to inject into an LLM's context window.
+"""
+
+__version__ = "0.1.0"

graphex/audit.py

@@ -0,0 +1,111 @@
+"""Append-only query audit log.
+
+Every retrieval can be recorded as one JSON line in ``<audit_dir>/audit.jsonl``
+(default ``.graphex/audit.jsonl``). The log is *best-effort*: writing it must
+never break a query, so I/O errors are swallowed. Reading is tolerant of partial
+writes — malformed lines are skipped rather than raised on.
+
+Beyond the raw round-trip, :func:`top_nodes_from_audit` aggregates the most
+frequently selected nodes across the whole history, a cheap proxy for "what does
+this graph keep surfacing".
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from datetime import UTC, datetime
+from pathlib import Path
+
+AUDIT_DIRNAME = ".graphex"
+AUDIT_FILENAME = "audit.jsonl"
+
+# Cap on how many top nodes we persist per entry.
+_TOP_NODES_CAP = 10
+
+
+def _audit_path(audit_dir: Path | str) -> Path:
+    return Path(audit_dir) / AUDIT_FILENAME
+
+
+def log_query(
+    query: str,
+    graph_path: Path,
+    stats: dict,
+    top_nodes: list[str],
+    audit_dir: Path | str = AUDIT_DIRNAME,
+) -> None:
+    """Append one audit record for a completed query.
+
+    The record captures the query string, the graph it ran against, selection /
+    token statistics (read from ``stats`` with keys ``nodes_selected``,
+    ``nodes_total``, ``tokens_used``, ``tokens_budget``), and up to the first
+    ten ``top_nodes``. A UTC ISO-8601 ``timestamp`` is stamped automatically.
+
+    This is best-effort: the audit directory is created if missing, and any
+    :class:`OSError` raised while writing is swallowed so auditing never breaks
+    a retrieval.
+    """
+    record = {
+        "timestamp": datetime.now(UTC).isoformat(),
+        "query": query,
+        "graph": str(graph_path),
+        "nodes_selected": stats.get("nodes_selected"),
+        "nodes_total": stats.get("nodes_total"),
+        "tokens_used": stats.get("tokens_used"),
+        "tokens_budget": stats.get("tokens_budget"),
+        "top_nodes": list(top_nodes[:_TOP_NODES_CAP]),
+    }
+    try:
+        directory = Path(audit_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(record, default=str)
+        with _audit_path(directory).open("a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+    except OSError:
+        # Auditing is best-effort — never propagate I/O failures to the caller.
+        return
+
+
+def read_audit(audit_dir: Path | str = AUDIT_DIRNAME) -> list[dict]:
+    """Read and parse every audit record.
+
+    Returns an empty list if the file does not exist. Malformed lines (e.g. from
+    a partial write) are skipped rather than raised on.
+    """
+    path = _audit_path(audit_dir)
+    if not path.exists():
+        return []
+    records: list[dict] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if isinstance(obj, dict):
+            records.append(obj)
+    return records
+
+
+def top_nodes_from_audit(
+    audit_dir: Path | str = AUDIT_DIRNAME, n: int = 10
+) -> list[tuple[str, int]]:
+    """Rank node ids by how often they appear across all entries' ``top_nodes``.
+
+    Returns the ``n`` most common ``(node_id, count)`` pairs in descending order
+    of count.
+    """
+    counter: Counter[str] = Counter()
+    for record in read_audit(audit_dir):
+        top_nodes = record.get("top_nodes")
+        if not isinstance(top_nodes, list):
+            continue
+        counter.update(str(node_id) for node_id in top_nodes)
+    return counter.most_common(n)

graphex/benchmark.py

@@ -0,0 +1,297 @@
+"""Measure the *honest* value of token-budgeted graph retrieval.
+
+The temptation with a tool like Graphex is to report a single flattering number:
+"we saved 92% of your tokens!" That number is meaningless on its own — a tool
+that returns nothing saves 100% of the tokens and answers 0% of the questions.
+The only number that matters is the trade-off: what fraction of the *relevant*
+content did the budgeted subgraph actually keep, for the tokens it spent?
+
+So every ``(query, budget)`` pair is scored on two axes:
+
+1. ``token_savings`` — ``1 − tokens_used / full_graph_tokens``, where
+   ``full_graph_tokens`` is the cost of injecting the whole graph (the naive
+   baseline). Higher is cheaper. Easy to game by retrieving less.
+2. ``recall_at_budget`` — of the top-``k`` nodes by full-graph relevance (the
+   retrieval target), what fraction did the budgeted subgraph capture? Higher is
+   better. *This* is the metric that exposes under-retrieval: a tiny budget posts
+   a gorgeous ``token_savings`` and a damning ``recall_at_budget``.
+
+Read them together. Savings without recall is just throwing the answer away.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from graphex.budget import (
+    _NODE_OVERHEAD_TOKENS,
+    _node_body,
+    count_tokens,
+    select_subgraph,
+)
+from graphex.cache import CachedArtifacts, load_or_build
+from graphex.models import KnowledgeGraph
+from graphex.scorer import score_nodes
+
+DEFAULT_BUDGETS: tuple[int, ...] = (2000, 4000, 8000)
+DEFAULT_K_RELEVANT = 10
+
+
+@dataclass(slots=True)
+class BenchmarkRow:
+    """One ``(query, budget)`` measurement.
+
+    Attributes:
+        query: The query that was scored.
+        budget: The token ceiling the subgraph was selected under.
+        nodes_selected: How many nodes the budgeted subgraph kept.
+        tokens_used: Rendered token cost of the budgeted subgraph.
+        full_graph_tokens: Token cost of injecting every node (the baseline).
+        token_savings: ``1 − tokens_used / full_graph_tokens`` in ``[0, 1]``.
+        recall_at_budget: Fraction of the relevant top-k set captured, in ``[0, 1]``.
+    """
+
+    query: str
+    budget: int
+    nodes_selected: int
+    tokens_used: int
+    full_graph_tokens: int
+    token_savings: float
+    recall_at_budget: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain JSON-friendly mapping."""
+        return {
+            "query": self.query,
+            "budget": self.budget,
+            "nodes_selected": self.nodes_selected,
+            "tokens_used": self.tokens_used,
+            "full_graph_tokens": self.full_graph_tokens,
+            "token_savings": self.token_savings,
+            "recall_at_budget": self.recall_at_budget,
+        }
+
+
+@dataclass(slots=True)
+class BenchmarkResult:
+    """The full benchmark: one :class:`BenchmarkRow` per ``(query, budget)``."""
+
+    rows: list[BenchmarkRow] = field(default_factory=list)
+
+    @property
+    def mean_token_savings(self) -> float:
+        """Average ``token_savings`` across all rows (0.0 if empty)."""
+        if not self.rows:
+            return 0.0
+        return sum(r.token_savings for r in self.rows) / len(self.rows)
+
+    @property
+    def mean_recall(self) -> float:
+        """Average ``recall_at_budget`` across all rows (0.0 if empty)."""
+        if not self.rows:
+            return 0.0
+        return sum(r.recall_at_budget for r in self.rows) / len(self.rows)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a JSON-friendly dict (rows plus the aggregate means)."""
+        return {
+            "rows": [r.to_dict() for r in self.rows],
+            "mean_token_savings": self.mean_token_savings,
+            "mean_recall": self.mean_recall,
+        }
+
+
+def _full_graph_tokens(graph: KnowledgeGraph, model: str) -> int:
+    """Token cost of injecting the whole graph — the naive baseline to beat.
+
+    Computed with the *same* per-node accounting as the budgeted selection
+    (:func:`graphex.budget._node_body` + per-node overhead), so ``token_savings``
+    is a fair like-for-like comparison rather than a pessimistic one.
+    """
+    return sum(
+        count_tokens(_node_body(graph, nid, None), model) + _NODE_OVERHEAD_TOKENS
+        for nid in graph.node_ids
+    )
+
+
+def _relevant_set(scores: dict[str, float], k: int) -> set[str]:
+    """The retrieval target: the top-``k`` nodes by full-graph relevance.
+
+    Ties are broken by node id (ascending) so the set is deterministic. Nodes
+    with a non-positive score are never relevant — an empty graph (or one where
+    nothing matched) yields an empty target rather than padding with noise.
+    """
+    ranked = sorted(
+        (nid for nid, s in scores.items() if s > 0.0),
+        key=lambda nid: (-scores[nid], nid),
+    )
+    return set(ranked[:k])
+
+
+def _measure(
+    graph: KnowledgeGraph,
+    query: str,
+    budget: int,
+    scores: dict[str, float],
+    relevant: set[str],
+    full_tokens: int,
+    *,
+    model: str,
+    min_score: float,
+) -> BenchmarkRow:
+    """Score a single ``(query, budget)`` pair into a :class:`BenchmarkRow`."""
+    sub, stats = select_subgraph(graph, scores, budget, model=model, min_score=min_score)
+    tokens_used = int(stats["tokens_used"])
+
+    token_savings = 1.0 - tokens_used / full_tokens if full_tokens > 0 else 0.0
+    token_savings = max(0.0, min(1.0, token_savings))
+
+    if relevant:
+        captured = len(set(sub.node_ids) & relevant)
+        recall = captured / len(relevant)
+    else:
+        recall = 0.0
+
+    return BenchmarkRow(
+        query=query,
+        budget=budget,
+        nodes_selected=int(stats["nodes_selected"]),
+        tokens_used=tokens_used,
+        full_graph_tokens=full_tokens,
+        token_savings=round(token_savings, 4),
+        recall_at_budget=round(recall, 4),
+    )
+
+
+def run_benchmark(
+    graph: KnowledgeGraph,
+    queries: list[str],
+    budgets: list[int] | tuple[int, ...] = DEFAULT_BUDGETS,
+    *,
+    model: str = "cl100k_base",
+    k_relevant: int = DEFAULT_K_RELEVANT,
+    min_score: float = 0.0,
+    cache: CachedArtifacts | None = None,
+) -> BenchmarkResult:
+    """Benchmark budgeted retrieval over a grid of ``queries × budgets``.
+
+    For each query the full-graph relevance is scored once; the top-``k_relevant``
+    nodes define the retrieval target. Each budget then selects a subgraph and is
+    scored on ``token_savings`` and ``recall_at_budget`` against that target.
+
+    The query-independent BM25/PageRank artifacts are computed once and reused
+    across every query, so the grid costs one walk per query, not per cell.
+
+    Args:
+        graph: The knowledge graph to benchmark against.
+        queries: Free-text queries to evaluate.
+        budgets: Token ceilings to sweep (default ``(2000, 4000, 8000)``).
+        model: tiktoken encoding for token counting.
+        k_relevant: Size of the relevant top-k target set per query.
+        min_score: Drop candidates below this score before selection.
+        cache: Precomputed artifacts to reuse. Built in-memory when omitted.
+
+    Returns:
+        A :class:`BenchmarkResult` with one row per ``(query, budget)`` pair.
+    """
+    artifacts = cache if cache is not None else load_or_build(graph, use_cache=False)
+    full_tokens = _full_graph_tokens(graph, model)
+
+    rows: list[BenchmarkRow] = []
+    for query in queries:
+        scores = score_nodes(graph, query, cache=artifacts)
+        relevant = _relevant_set(scores, k_relevant)
+        for budget in budgets:
+            rows.append(
+                _measure(
+                    graph,
+                    query,
+                    budget,
+                    scores,
+                    relevant,
+                    full_tokens,
+                    model=model,
+                    min_score=min_score,
+                )
+            )
+    return BenchmarkResult(rows=rows)
+
+
+# -- formatting --------------------------------------------------------------
+
+_HEADERS: tuple[str, ...] = (
+    "query",
+    "budget",
+    "nodes",
+    "tokens_used",
+    "full_tokens",
+    "token_savings",
+    "recall@budget",
+)
+
+
+def _truncate(text: str, width: int) -> str:
+    """Clip ``text`` to ``width`` columns, marking elision with an ellipsis."""
+    if len(text) <= width:
+        return text
+    if width <= 1:
+        return text[:width]
+    return text[: width - 1] + "…"
+
+
+def format_benchmark(result: BenchmarkResult, *, max_query_width: int = 28) -> str:
+    """Render a benchmark as a plain, aligned text table.
+
+    Shows every ``(query, budget)`` row plus the aggregate means, and closes with
+    a one-line reminder that high savings with low recall means under-retrieval.
+
+    Args:
+        result: The benchmark to render.
+        max_query_width: Column width cap for the (possibly long) query text.
+
+    Returns:
+        A multi-line string ending in a newline.
+    """
+    rows = result.rows
+    cells: list[tuple[str, ...]] = []
+    for r in rows:
+        cells.append(
+            (
+                _truncate(r.query, max_query_width),
+                str(r.budget),
+                str(r.nodes_selected),
+                str(r.tokens_used),
+                str(r.full_graph_tokens),
+                f"{r.token_savings:.1%}",
+                f"{r.recall_at_budget:.1%}",
+            )
+        )
+
+    widths = [len(h) for h in _HEADERS]
+    for row in cells:
+        for i, value in enumerate(row):
+            widths[i] = max(widths[i], len(value))
+
+    def _fmt(values: tuple[str, ...] | list[str]) -> str:
+        # First column left-aligned (text); the rest right-aligned (numbers).
+        parts = [values[0].ljust(widths[0])]
+        parts.extend(values[i].rjust(widths[i]) for i in range(1, len(values)))
+        return "  ".join(parts)
+
+    sep = "  ".join("-" * w for w in widths)
+    lines: list[str] = ["Graphex retrieval benchmark", "", _fmt(_HEADERS), sep]
+    lines.extend(_fmt(row) for row in cells)
+    if not cells:
+        lines.append("(no rows)")
+    lines.append(sep)
+    lines.append(
+        f"mean token_savings: {result.mean_token_savings:.1%}   "
+        f"mean recall@budget: {result.mean_recall:.1%}"
+    )
+    lines.append("")
+    lines.append(
+        "Note: high token-savings with low recall@budget means under-retrieval — "
+        "the budget is too tight to keep the relevant nodes."
+    )
+    return "\n".join(lines) + "\n"