Index a codebase directory for semantic search.

Walks the directory, extracts semantic code chunks using AST analysis,
embeds them locally with sentence-transformers, and stores in a vector index.
Subsequent calls skip unchanged files (incremental updates).

Args:
    path: Absolute path to the codebase root directory.
    force: If True, re-index all files even if unchanged.
    watch: If True, start a background watcher for live sync on file changes.
           Not supported with cloud providers (openai, voyage, gemini).
    provider: Embedding provider to use. One of: 'local' (default), 'openai',
              'voyage', 'gemini'. Cloud providers require the corresponding
              env var (VECGREP_OPENAI_KEY, VECGREP_VOYAGE_KEY, VECGREP_GEMINI_KEY)
              and optional dependency (pip install 'vecgrep[openai]' etc.).
              Once set, switching providers requires force=True to rebuild the index.

Returns:
    Summary: files indexed, chunks added, files skipped.

Semantically search an indexed codebase for code relevant to a query.

Embeds the query and performs cosine similarity search against indexed
code chunks, returning the most semantically relevant snippets with
file paths and line numbers.

If the codebase is not yet indexed, it will be indexed automatically first.

Args:
    query: Natural language description of what you're looking for.
           E.g. "how does authentication work", "database connection setup"
    path: Absolute path to the codebase root directory.
    top_k: Number of results to return (default 8, max 20).
    min_score: Minimum cosine similarity score to include a result (default 0.35).
               Results below this threshold are filtered out as noise. Set to 0.0
               to disable filtering.

Returns:
    Formatted list of matching code chunks with file:line references and
    similarity scores.

Get the status of the vector index for a codebase.

Args:
    path: Absolute path to the codebase root directory.

Returns:
    Index statistics: file count, chunk count, last indexed time, disk usage.

Build (or rebuild) a knowledge graph for a codebase.

Walks the directory using the same skip rules as index_codebase, extracts
structural nodes (files, functions, classes) and edges (contains, calls,
imports, inherits) using tree-sitter, and persists the graph to disk.

This is independent of the vector index — you can run index_graph before
or after index_codebase.

Args:
    path: Absolute path to the codebase root directory.
    force: If True, rebuild the graph even if one already exists.

Returns:
    Summary: node count, edge count, files processed.

Search the knowledge graph for nodes matching a query.

Performs keyword matching over node labels (function names, class names,
file names) and returns the most relevant structural nodes with their
source locations and relationship degree.

The codebase graph must be built first with index_graph.

Args:
    query: Keywords to search for (e.g. "VectorStore", "auth login").
    path: Absolute path to the codebase root directory.
    limit: Maximum number of results to return (default 20).

Returns:
    Matching nodes with kind, source location, and connectivity degree.

Return structural neighbors of a graph node.

Shows which functions call this node, which it calls, what it imports,
what it contains, and what it inherits from — up to *depth* hops away.

Use search_graph first to find the exact node ID.

Args:
    node_id: Node ID or label substring (e.g. "vectorstore_search" or "search").
    path: Absolute path to the codebase root directory.
    depth: Number of hops to traverse (1 = direct edges only, default 1).

Returns:
    Categorised list of neighboring nodes with their source locations.

Semantic vector search re-ranked by knowledge graph proximity.

Combines vector similarity (cosine) with structural graph proximity
(BFS distance from query-matched graph nodes). The final score is:

    score = alpha * vector_score + (1 - alpha) * graph_score

Both vector and graph scores are normalised to [0, 1] before blending.
Requires both index_codebase and index_graph to have been run.

Args:
    query: Natural language description of what you're looking for.
    path: Absolute path to the codebase root directory.
    top_k: Number of results to return (default 8, max 20).
    alpha: Weight of vector score vs graph score (0.0 = graph only,
           1.0 = vector only, default 0.6).
    min_score: Minimum blended score threshold (default 0.0).

Returns:
    Formatted list of code chunks ranked by blended score.