graphnav 0.1.0__py3-none-any.whl

codex_graph/__init__.py

@@ -0,0 +1,10 @@
+class GraphNotFoundError(Exception):
+    pass
+
+
+class CodexNotFoundError(Exception):
+    pass
+
+
+class CodexTimeoutError(Exception):
+    pass

codex_graph/cli.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from codex_graph import CodexNotFoundError, CodexTimeoutError, GraphNotFoundError
+from codex_graph.config import load_config
+from codex_graph.graph_query import load_index, query_files
+from codex_graph import runner
+
+
+def _run_mono_command(cmd: str, argv: list[str]) -> None:
+    from codex_graph import multirepo
+
+    parser = argparse.ArgumentParser(
+        prog=f"codex-graph {cmd}",
+        description={
+            "map": "Build per-service graphs and cross-service bridge notes for a monorepo",
+            "watch": "Watch for file changes and keep per-service graphs and bridge notes up-to-date",
+        }[cmd],
+    )
+    parser.add_argument("--root", default=".", metavar="PATH", help="Monorepo root directory (default: current directory)")
+    parser.add_argument("--backend", default=None, metavar="BACKEND", help="graphify LLM backend (claude|openai|gemini|deepseek|ollama)")
+    parser.add_argument("--config", default=None, metavar="PATH", help="Path to config.toml")
+    if cmd == "map":
+        parser.add_argument("--dry-run", action="store_true", help="Detect services and print the plan without invoking graphify")
+
+    args = parser.parse_args(argv)
+    cfg = load_config(args.config)
+
+    if cmd == "map":
+        rc = multirepo.run_map(
+            root=args.root,
+            mono_cfg=cfg.mono,
+            backend_override=args.backend,
+            dry_run=args.dry_run,
+        )
+    else:
+        rc = multirepo.run_watch(
+            root=args.root,
+            mono_cfg=cfg.mono,
+            backend_override=args.backend,
+        )
+    sys.exit(rc)
+
+
+def _auto_map_if_needed(cfg_path: str | None) -> None:
+    from codex_graph import multirepo
+    from codex_graph.config import load_config
+
+    cfg = load_config(cfg_path)
+    root = os.path.abspath(".")
+    services = multirepo.detect_services(root, cfg.mono.marker_files)
+    if not services:
+        return
+
+    names = ", ".join(s.name for s in services)
+    print(f"[codex-graph] Detected {len(services)} service(s): {names}")
+    print(f"[codex-graph] Running 'codex-graph map' to build knowledge graphs ...", file=sys.stderr)
+    rc = multirepo.run_map(root=root, mono_cfg=cfg.mono)
+    sys.exit(rc)
+
+
+def _run_context_command(argv: list[str]) -> None:
+    from codex_graph import multirepo
+
+    parser = argparse.ArgumentParser(
+        prog="codex-graph context",
+        description="Print a token-budgeted context pack (files + symbol locations + cross-service impact) for a coding task",
+    )
+    parser.add_argument("task", nargs="?", help="The coding task, in natural language")
+    parser.add_argument("--root", default=".", metavar="PATH", help="Repo root (default: current directory)")
+    parser.add_argument("--budget", type=int, default=None, metavar="N", help="Approx token budget for the pack")
+    parser.add_argument("--files", type=int, default=None, metavar="N", help="Max number of files to include")
+    parser.add_argument("--config", default=None, metavar="PATH", help="Path to config.toml")
+    args = parser.parse_args(argv)
+
+    task = args.task
+    if not task and not sys.stdin.isatty():
+        task = sys.stdin.read().strip()
+    if not task:
+        parser.print_help()
+        sys.exit(1)
+
+    cfg = load_config(args.config)
+    pack = multirepo.build_context_pack(
+        root=args.root,
+        task=task,
+        top_files=args.files if args.files is not None else cfg.mono.context_top_files,
+        budget_tokens=args.budget if args.budget is not None else cfg.mono.context_budget_tokens,
+        skip_patterns=cfg.graph.skip_patterns,
+    )
+    print(pack)
+    sys.exit(0)
+
+
+def _run_graph_query_command(kind: str, argv: list[str]) -> None:
+    from codex_graph import multirepo
+    from codex_graph.graph_nav import GraphNav
+
+    parser = argparse.ArgumentParser(prog=f"codex-graph {kind}")
+    parser.add_argument("term", nargs="?", help="query (find) or symbol (neighbors)")
+    parser.add_argument("--root", default=".", metavar="PATH")
+    parser.add_argument("--config", default=None, metavar="PATH")
+    args = parser.parse_args(argv)
+    if not args.term:
+        parser.print_help()
+        sys.exit(1)
+
+    cfg = load_config(args.config)
+    graph_path = multirepo._overarching_graph_path(os.path.abspath(args.root))
+    if not os.path.exists(graph_path):
+        print(f"Error: no knowledge graph at {graph_path}. Run `codex-graph map` first.", file=sys.stderr)
+        sys.exit(2)
+    nav = GraphNav(graph_path, cfg.graph.skip_patterns)
+
+    if kind == "find":
+        hits = nav.find_symbols(args.term, k=10)
+        if not hits:
+            print("(no matches)")
+        for h in hits:
+            print(f"{h['symbol']} — {h['file']}:{h['loc']}")
+    else:
+        r = nav.neighbors(args.term)
+        if not r.get("found", True):
+            print("(symbol not found)")
+            sys.exit(0)
+        print(f"{r['symbol']} defined at {r['defined_at']}")
+        if r.get("callers"):
+            print("callers:")
+            for c in r["callers"]:
+                print("  " + c)
+        if r.get("callees"):
+            print("calls:")
+            for c in r["callees"]:
+                print("  " + c)
+    sys.exit(0)
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] in ("map", "watch"):
+        _run_mono_command(sys.argv[1], sys.argv[2:])
+        return
+    if len(sys.argv) > 1 and sys.argv[1] == "context":
+        _run_context_command(sys.argv[2:])
+        return
+    if len(sys.argv) > 1 and sys.argv[1] in ("find", "neighbors"):
+        _run_graph_query_command(sys.argv[1], sys.argv[2:])
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="codex-graph",
+        description=(
+            "Codex CLI with knowledge-graph context injection for monorepos.\n\n"
+            "First-run (after pip install): just run 'codex-graph' or 'codex-graph map'\n"
+            "in your monorepo root — services are auto-detected and graphs are built.\n\n"
+            "Subcommands:\n"
+            "  map    Build per-service graphs and cross-service bridge notes\n"
+            "  watch  Keep graphs and bridge notes up-to-date as files change"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("prompt", nargs="?", help="Natural language task prompt")
+    parser.add_argument("--config", default=None, metavar="PATH", help="Path to config.toml")
+    parser.add_argument("--top-k", type=int, default=None, metavar="N", help="Number of files to inject as context")
+    parser.add_argument("--graph", default=None, metavar="PATH", help="Path to graph.json")
+    parser.add_argument("--dry-run", action="store_true", help="Print enriched prompt without calling codex")
+    parser.add_argument("--list-files", action="store_true", help="Print ranked files and scores, then exit")
+    parser.add_argument("--no-context", action="store_true", help="Pass prompt to codex with no graph context")
+
+    args = parser.parse_args()
+
+    prompt = args.prompt
+    if not prompt:
+        if sys.stdin.isatty():
+            _auto_map_if_needed(args.config)
+            parser.print_help()
+            sys.exit(1)
+        prompt = sys.stdin.read().strip()
+    if not prompt:
+        parser.print_help()
+        sys.exit(1)
+
+    cfg = load_config(args.config)
+
+    if args.top_k is not None:
+        cfg.query.top_k = args.top_k
+    if args.graph is not None:
+        cfg.graph.path = args.graph
+
+    project_root = os.path.abspath(cfg.graph.project_root)
+    graph_path = (
+        cfg.graph.path
+        if os.path.isabs(cfg.graph.path)
+        else os.path.join(os.getcwd(), cfg.graph.path)
+    )
+
+    if args.no_context:
+        ranked = []
+    else:
+        try:
+            index = load_index(graph_path, cfg.graph.skip_patterns)
+        except GraphNotFoundError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(2)
+
+        ranked = query_files(
+            prompt,
+            index,
+            cfg.query.top_k,
+            cfg.query.community_boost_weight,
+            cfg.query.bm25_k1,
+            cfg.query.bm25_b,
+        )
+
+    if args.list_files:
+        for rf in ranked:
+            print(f"{rf.score:.3f}  {rf.source_file}")
+        sys.exit(0)
+
+    if args.dry_run:
+        print(runner.build_prompt(prompt, ranked, cfg, project_root))
+        sys.exit(0)
+
+    try:
+        exit_code = runner.run(prompt, ranked, cfg, project_root)
+        sys.exit(exit_code)
+    except CodexNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(127)
+    except CodexTimeoutError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(124)
+
+
+if __name__ == "__main__":
+    main()

codex_graph/config.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+
+
+@dataclass
+class GraphConfig:
+    path: str = "graphify-out/graph.json"
+    project_root: str = "."
+    skip_patterns: list[str] = field(default_factory=lambda: ["playwright-report", "node_modules", ".git"])
+
+
+@dataclass
+class QueryConfig:
+    top_k: int = 5
+    community_boost_weight: float = 2.0
+    bm25_k1: float = 1.5
+    bm25_b: float = 0.75
+
+
+@dataclass
+class ContextConfig:
+    max_file_chars: int = 8000
+    show_scores: bool = False
+
+
+@dataclass
+class CodexConfig:
+    command: str = "codex"
+    subcommand: str = "exec"
+    extra_args: list[str] = field(default_factory=list)
+    inject_via: str = "stdin"
+    timeout_seconds: int = 300
+
+
+@dataclass
+class MonoConfig:
+    marker_files: list[str] = field(default_factory=lambda: [
+        "package.json", "pyproject.toml", "go.mod", "Cargo.toml",
+        "pom.xml", "build.gradle", "setup.py", "setup.cfg",
+        "requirements.txt", "Gemfile", "composer.json", "tsconfig.json",
+    ])
+    graphify_backend: str = "claude"
+    watch_poll_interval: float = 3.0
+    context_budget_tokens: int = 2000
+    context_top_files: int = 8
+
+
+@dataclass
+class Config:
+    graph: GraphConfig = field(default_factory=GraphConfig)
+    query: QueryConfig = field(default_factory=QueryConfig)
+    context: ContextConfig = field(default_factory=ContextConfig)
+    codex: CodexConfig = field(default_factory=CodexConfig)
+    mono: MonoConfig = field(default_factory=MonoConfig)
+
+
+def _apply_toml(cfg: Config, data: dict) -> Config:
+    if "graph" in data:
+        g = data["graph"]
+        cfg.graph = GraphConfig(
+            path=g.get("path", cfg.graph.path),
+            project_root=g.get("project_root", cfg.graph.project_root),
+            skip_patterns=g.get("skip_patterns", cfg.graph.skip_patterns),
+        )
+    if "query" in data:
+        q = data["query"]
+        cfg.query = QueryConfig(
+            top_k=q.get("top_k", cfg.query.top_k),
+            community_boost_weight=q.get("community_boost_weight", cfg.query.community_boost_weight),
+            bm25_k1=q.get("bm25_k1", cfg.query.bm25_k1),
+            bm25_b=q.get("bm25_b", cfg.query.bm25_b),
+        )
+    if "context" in data:
+        c = data["context"]
+        cfg.context = ContextConfig(
+            max_file_chars=c.get("max_file_chars", cfg.context.max_file_chars),
+            show_scores=c.get("show_scores", cfg.context.show_scores),
+        )
+    if "codex" in data:
+        cx = data["codex"]
+        cfg.codex = CodexConfig(
+            command=cx.get("command", cfg.codex.command),
+            subcommand=cx.get("subcommand", cfg.codex.subcommand),
+            extra_args=cx.get("extra_args", cfg.codex.extra_args),
+            inject_via=cx.get("inject_via", cfg.codex.inject_via),
+            timeout_seconds=cx.get("timeout_seconds", cfg.codex.timeout_seconds),
+        )
+    if "mono" in data:
+        m = data["mono"]
+        cfg.mono = MonoConfig(
+            marker_files=m.get("marker_files", cfg.mono.marker_files),
+            graphify_backend=m.get("graphify_backend", cfg.mono.graphify_backend),
+            watch_poll_interval=m.get("watch_poll_interval", cfg.mono.watch_poll_interval),
+            context_budget_tokens=m.get("context_budget_tokens", cfg.mono.context_budget_tokens),
+            context_top_files=m.get("context_top_files", cfg.mono.context_top_files),
+        )
+    return cfg
+
+
+def load_config(explicit_path: str | None = None) -> Config:
+    cfg = Config()
+
+    candidates: list[str] = []
+    if explicit_path:
+        candidates = [explicit_path]
+    else:
+        env_path = os.environ.get("CODEX_GRAPH_CONFIG")
+        if env_path:
+            candidates.append(env_path)
+        candidates.append(os.path.join(os.getcwd(), "config.toml"))
+        candidates.append(os.path.expanduser("~/.codex-graph/config.toml"))
+
+    for path in candidates:
+        if os.path.exists(path):
+            with open(path, "rb") as f:
+                data = tomllib.load(f)
+            cfg = _apply_toml(cfg, data)
+            break
+    else:
+        if explicit_path:
+            import sys
+            print(f"Warning: config file not found: {explicit_path}", file=sys.stderr)
+
+    return cfg

codex_graph/graph_nav.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+import os
+from collections import defaultdict
+
+from codex_graph.graph_query import _tokenize
+
+
+class GraphNav:
+    def __init__(self, graph_path: str, skip_patterns: list[str] | None = None):
+        with open(graph_path) as f:
+            graph = json.load(f)
+        self.skip = skip_patterns or []
+        self.id2node: dict = {}
+        self.file2ids: dict[str, list] = defaultdict(list)
+        for n in graph.get("nodes", []):
+            nid = n.get("id")
+            if nid is None:
+                continue
+            self.id2node[nid] = n
+            sf = n.get("source_file", "")
+            if sf:
+                self.file2ids[sf].append(nid)
+        self.in_edges: dict[object, list] = defaultdict(list)
+        self.out_edges: dict[object, list] = defaultdict(list)
+        for e in graph.get("links", []):
+            s, t = e.get("source"), e.get("target")
+            if s is None or t is None:
+                continue
+            rel = e.get("relation", "")
+            self.out_edges[s].append((t, rel))
+            self.in_edges[t].append((s, rel))
+
+    def _skipped(self, sf: str) -> bool:
+        return (not sf) or any(p in sf for p in self.skip)
+
+    def _loc(self, nid) -> str:
+        n = self.id2node.get(nid, {})
+        sf = n.get("source_file", "?")
+        loc = n.get("source_location", "")
+        return f"{sf}:{loc}" if loc else sf
+
+    def find_symbols(self, query: str, k: int = 8) -> list[dict]:
+        q = set(_tokenize(query))
+        if not q:
+            return []
+        scored = []
+        for n in self.id2node.values():
+            if n.get("file_type") != "code":
+                continue
+            sf = n.get("source_file", "")
+            label = n.get("label", "")
+            if self._skipped(sf) or not label:
+                continue
+            toks = set(_tokenize(label)) | set(_tokenize(os.path.basename(os.path.splitext(sf)[0])))
+            overlap = len(q & toks)
+            if overlap:
+                scored.append((overlap, label, sf, n.get("source_location", "")))
+        scored.sort(key=lambda x: -x[0])
+        return [{"symbol": l, "file": sf, "loc": loc} for _, l, sf, loc in scored[:k]]
+
+    def neighbors(self, symbol: str, k: int = 12) -> dict:
+        q = set(_tokenize(symbol))
+        best, best_ov = None, 0
+        for nid, n in self.id2node.items():
+            ov = len(q & set(_tokenize(n.get("label", ""))))
+            if ov > best_ov:
+                best, best_ov = nid, ov
+        if best is None:
+            return {"symbol": symbol, "found": False}
+        callers, callees = [], []
+        for s, rel in self.in_edges.get(best, []):
+            sn = self.id2node.get(s, {})
+            if self._skipped(sn.get("source_file", "")):
+                continue
+            callers.append(f"{sn.get('label', '?')} ({self._loc(s)}) --{rel}-->")
+        for t, rel in self.out_edges.get(best, []):
+            tn = self.id2node.get(t, {})
+            if self._skipped(tn.get("source_file", "")):
+                continue
+            callees.append(f"--{rel}--> {tn.get('label', '?')} ({self._loc(t)})")
+        return {
+            "symbol": self.id2node[best].get("label"),
+            "defined_at": self._loc(best),
+            "callers": callers[:k],
+            "callees": callees[:k],
+        }
+
+    def references_to(self, files: list[str], limit: int = 12) -> list[str]:
+        target_ids = set()
+        for sf in files:
+            target_ids.update(self.file2ids.get(sf, []))
+        seen, rows = set(), []
+        file_set = set(files)
+        for tid in target_ids:
+            tnode = self.id2node.get(tid, {})
+            for s, rel in self.in_edges.get(tid, []):
+                sn = self.id2node.get(s, {})
+                sf = sn.get("source_file", "")
+                if self._skipped(sf) or sf in file_set:
+                    continue
+                key = (sf, sn.get("source_location", ""), tnode.get("label", ""))
+                if key in seen:
+                    continue
+                seen.add(key)
+                loc = sn.get("source_location", "")
+                rows.append(
+                    f"{sf}:{loc} {sn.get('label', '?')} --{rel}--> {tnode.get('label', '?')}"
+                )
+                if len(rows) >= limit:
+                    return rows
+        return rows

codex_graph/graph_query.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+
+from codex_graph import GraphNotFoundError
+
+
+@dataclass
+class RankedFile:
+    source_file: str
+    score: float
+
+
+ALLOWED_EXTENSIONS = {
+    ".py", ".pyi", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".go", ".java", ".kt", ".kts", ".cs", ".rb", ".rs", ".php",
+    ".swift", ".scala", ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp",
+    ".hh", ".m", ".mm", ".lua", ".dart", ".ex", ".exs", ".clj",
+    ".cljs", ".groovy", ".vue", ".svelte", ".sh", ".bash", ".zsh",
+    ".pl", ".r", ".sql", ".proto", ".thrift", ".graphql", ".gql",
+    ".md", ".mdx", ".markdown", ".rst", ".txt", ".adoc",
+}
+
+GENERATED_PATTERNS = (
+    ".pb.go", ".pb.cc", ".pb.h", "_pb2.py", "_pb2.pyi", "_pb2_grpc.py",
+    "pb2_grpc", "_grpc.pb.", "genproto/", "/generated/", ".generated.",
+    ".g.dart", "_pb.dart", "/migrations/",
+)
+
+
+def _is_rankable(source_file: str) -> bool:
+    lower = source_file.lower()
+    if any(p in lower for p in GENERATED_PATTERNS):
+        return False
+    return os.path.splitext(lower)[1] in ALLOWED_EXTENSIONS
+
+
+_IDENT_RE = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z][a-z]+|[a-z]+|[A-Z]+|[0-9]+")
+
+
+def _stem(t: str) -> str:
+    if len(t) <= 4 or t.endswith("ss"):
+        return t
+    if t.endswith("ies"):
+        return t[:-3] + "y"
+    if t.endswith("es"):
+        return t[:-2]
+    if t.endswith("s"):
+        return t[:-1]
+    return t
+
+
+def _tokenize(s: str) -> list[str]:
+    toks: list[str] = []
+    for word in re.split(r"[^A-Za-z0-9]+", s):
+        if not word:
+            continue
+        for sub in (_IDENT_RE.findall(word) or [word]):
+            t = sub.lower()
+            if len(t) >= 2:
+                toks.append(_stem(t))
+    return toks
+
+
+class GraphIndex:
+    _TYPE_WEIGHT = {"rationale": 3, "document": 2, "concept": 2, "code": 1}
+
+    def __init__(self, graph_path: str, skip_patterns: list[str]):
+        with open(graph_path) as f:
+            graph = json.load(f)
+
+        nodes = graph.get("nodes", [])
+
+        self.file_tokens: dict[str, list[str]] = defaultdict(list)
+        self.file_communities: dict[str, set[int]] = defaultdict(set)
+        self.community_tokens: dict[int, set[str]] = defaultdict(set)
+
+        for n in nodes:
+            sf = n.get("source_file", "")
+            label = n.get("norm_label") or n.get("label") or ""
+            cid = n.get("community")
+            tokens = _tokenize(label)
+
+            if cid is not None:
+                self.community_tokens[cid].update(tokens)
+
+            if not sf or any(p in sf for p in skip_patterns) or not _is_rankable(sf):
+                continue
+
+            weight = self._TYPE_WEIGHT.get(n.get("file_type", "code"), 1)
+            self.file_tokens[sf].extend(tokens * weight)
+            if cid is not None:
+                self.file_communities[sf].add(cid)
+
+        for sf in list(self.file_tokens.keys()):
+            stem_path = os.path.splitext(sf)[0]
+            base_tokens = _tokenize(os.path.basename(stem_path))
+            dir_tokens = _tokenize(os.path.dirname(stem_path))
+            self.file_tokens[sf].extend(base_tokens * 6)
+            self.file_tokens[sf].extend(dir_tokens * 2)
+
+        self._N = len(self.file_tokens)
+        self._avgdl = (
+            sum(len(t) for t in self.file_tokens.values()) / max(self._N, 1)
+        )
+        self._df: dict[str, int] = defaultdict(int)
+        for tokens in self.file_tokens.values():
+            for t in set(tokens):
+                self._df[t] += 1
+
+    def _bm25(self, query_tokens: list[str], sf: str, k1: float, b: float) -> float:
+        doc = self.file_tokens.get(sf, [])
+        dl = len(doc)
+        tf_counts = Counter(doc)
+        score = 0.0
+        for t in query_tokens:
+            df = self._df.get(t)
+            if not df:
+                continue
+            idf = math.log((self._N - df + 0.5) / (df + 0.5) + 1)
+            tf = tf_counts[t]
+            tf_norm = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl / self._avgdl))
+            score += idf * tf_norm
+        return score
+
+    def _community_boost(self, query_tokens: list[str], sf: str, boost_weight: float) -> float:
+        qset = set(query_tokens)
+        best = 0.0
+        for cid in self.file_communities.get(sf, set()):
+            ctokens = self.community_tokens[cid]
+            overlap = len(qset & ctokens) / (len(qset) + 1)
+            if overlap > best:
+                best = overlap
+        return best * boost_weight
+
+    def rank(
+        self,
+        prompt: str,
+        top_k: int,
+        community_boost_weight: float,
+        bm25_k1: float,
+        bm25_b: float,
+        keep_ratio: float = 0.3,
+    ) -> list[RankedFile]:
+        qtoks = _tokenize(prompt)
+        if not qtoks:
+            return []
+        scores = {
+            sf: self._bm25(qtoks, sf, bm25_k1, bm25_b)
+            + self._community_boost(qtoks, sf, community_boost_weight)
+            for sf in self.file_tokens
+        }
+        ranked = sorted(scores.items(), key=lambda x: -x[1])
+        if not ranked or ranked[0][1] <= 0:
+            return []
+        floor = ranked[0][1] * keep_ratio
+        return [
+            RankedFile(source_file=sf, score=sc)
+            for sf, sc in ranked[:top_k]
+            if sc > 0 and sc >= floor
+        ]
+
+
+def load_index(graph_path: str, skip_patterns: list[str]) -> GraphIndex:
+    if not os.path.exists(graph_path):
+        raise GraphNotFoundError(
+            f"graph.json not found: {graph_path}\n"
+            "Run Graphify on the repo first, or set [graph] path in config.toml"
+        )
+    return GraphIndex(graph_path, skip_patterns)
+
+
+def query_files(
+    prompt: str,
+    index: GraphIndex,
+    top_k: int,
+    community_boost_weight: float = 2.0,
+    bm25_k1: float = 1.5,
+    bm25_b: float = 0.75,
+    keep_ratio: float = 0.3,
+) -> list[RankedFile]:
+    return index.rank(prompt, top_k, community_boost_weight, bm25_k1, bm25_b, keep_ratio)