trelix-llama-index

LlamaIndex retriever for trelix — semantic code search using Tree-sitter AST parsing, hybrid BM25+vector search, call-graph expansion, and streaming synthesis support.

Install

pip install trelix-llama-index

Usage

from trelix_llama_index import TrelixIndexRetriever

# First index your repo (one-time)
# trelix index /path/to/repo

retriever = TrelixIndexRetriever(repo_path="/path/to/repo", k=10)
nodes = retriever.retrieve("how does authentication work?")

for node in nodes:
    print(node.node.metadata["file"], node.score)
    print(node.node.text[:200])

With LlamaIndex query engine

from llama_index.core import VectorStoreIndex
from llama_index.core.query_engine import RetrieverQueryEngine
from trelix_llama_index import TrelixIndexRetriever

retriever = TrelixIndexRetriever(repo_path="/path/to/repo", k=10)
query_engine = RetrieverQueryEngine.from_args(retriever)
response = query_engine.query("How does the authentication middleware work?")
print(response)

Streaming synthesis (v2.0.0+, enhanced v2.4.0)

from trelix_llama_index import TrelixIndexRetriever
from llama_index.core.query_engine import RetrieverQueryEngine

retriever = TrelixIndexRetriever(repo_path="/path/to/repo", k=10)
query_engine = RetrieverQueryEngine.from_args(retriever)

# Stream response token-by-token
response = query_engine.query_stream("Explain the payment flow")
for text_chunk in response:
    print(text_chunk, end="", flush=True)

Beast-mode retrieval (v2.1.0+)

v2.1.0 activates enhanced retrieval features via environment variables. Enable HyDE synthetic snippet embedding and PageRank-based symbol boosting for architecturally central symbols:

from trelix_llama_index import TrelixIndexRetriever
from llama_index.core.query_engine import RetrieverQueryEngine

# v2.1.0: Beast-mode features active via env vars
# TRELIX_RETRIEVAL_HYDE_FALLBACK=true — HyDE synthetic snippet embedding
# TRELIX_RETRIEVAL_PAGERANK_BOOST=true — boost architecturally central symbols

retriever = TrelixIndexRetriever(
    repo_path="/path/to/repo",
    k=10,
)
nodes = retriever.retrieve("how does the payment processing work?")

v2.2.0 — What's New

trelix v2.2.0 adds four intelligence upgrades. The TrelixIndexRetriever interface is unchanged — activate features via env vars.

Configuration

Provider switching (v2.0.0+)

# Use Bedrock Cohere embeddings (best retrieval, reuses AWS creds)
TRELIX_EMBEDDER_PROVIDER=bedrock-cohere trelix index /path/to/repo

# Use HuggingFace embeddings (open-source alternatives)
TRELIX_EMBEDDER_PROVIDER=huggingface HUGGINGFACE_API_KEY=hf_... trelix index /path/to/repo

# Use Voyage embeddings (specialized for code search)
TRELIX_EMBEDDER_PROVIDER=voyage VOYAGE_API_KEY=pa-... trelix index /path/to/repo

# Use local embeddings (no API key needed)
TRELIX_EMBEDDER_PROVIDER=local trelix index /path/to/repo

Graph-Enhanced Retrieval (v2.1.0+)

Enable the knowledge graph as a 4th retrieval leg for architecture-aware queries. v2.1.0 integrates beast-mode features for optimal performance:

from trelix_llama_index import TrelixIndexRetriever

# With graph-aware BFS (requires trelix[knowledge-graph])
# v2.1.0: HyDE + PageRank boost activate automatically in this mode
retriever = TrelixIndexRetriever(
    repo_path="/path/to/repo",
    k=10,
    graph_search_enabled=True,   # enables 4th BFS retrieval leg
    graph_search_depth=2,
)

nodes = retriever.retrieve("how does the auth module interact with the DB layer?")
for node in nodes:
    print(node.node.metadata.get("source"))  # file path
    print(node.score)                         # combined RRF + graph score

Install with graph support:

pip install trelix-llama-index 'trelix[knowledge-graph]'

How it works

When graph_search_enabled=True, trelix builds (or loads) a NetworkX MultiDiGraph over the indexed repository and runs a BFS expansion from the highest-degree nodes relevant to the query. Results from all four legs are fused via Reciprocal Rank Fusion (RRF):

Configuration

Environment variable alternative:

TRELIX_GRAPH_SEARCH_ENABLED=true trelix index /path/to/repo

Benchmarks (trelix repo, 4,599 nodes / 4,945 edges)

• Graph build time: 0.34 s
• Communities detected: 2,409 (Louvain algorithm)
• graph_search depth=2: 10 results from top node (degree 438)
• Full retrieval with graph enabled: 30 results (5 graph + 19 vector + 4 BM25 + 2 graph_expansion)

Breaking change (v2.0.0)

The old trelix graph <repo> <symbol> call-graph display command was renamed:

# Before (v1.x)
trelix graph ./repo MyClass

# After (v2.0.0+)
trelix call-graph ./repo MyClass

trelix graph now builds and queries the knowledge graph:

trelix graph ./repo                          # build graph, print summary
trelix graph ./repo --visualize              # open Pyvis HTML in browser
trelix graph ./repo --concepts               # run LLM concept extraction
trelix graph ./repo --json                   # emit graph stats as JSON

What's new in v2.4.0

⚠️ Breaking change — search_code MCP tool response envelope

search_code now returns a pagination envelope instead of a bare list:

{"results": [...], "next_cursor": 10, "total_available": 25}

Update any MCP client code that iterates search_code(...) directly:

# Before (v2.3.0)
for result in search_code(query="auth", repo_path="/repo"):
    ...

# After (v2.4.0)
response = search_code(query="auth", repo_path="/repo")
for result in response["results"]:
    ...
# Paginate: pass response["next_cursor"] as cursor= for the next page

FederatedRetriever TTL cache

from trelix_llama_index import TrelixIndexRetriever

# cache_ttl=120 (seconds) — SHA-256-keyed, thread-safe
retriever = TrelixIndexRetriever(repo_path="/path/to/repo", k=10, cache_ttl=120.0)

# Inspect cache stats
print(retriever.cache_stats())  # {"hits": 3, "misses": 1, "size": 1}

# Force eviction
retriever.clear_cache()

Set cache_ttl=0 to disable caching entirely. Expected ~90% hit rate for typical debugging-session query patterns.

Multi-Query Expansion observability

When multi_query_enabled=True (requires trelix>=2.3.0), each retrieval now records expansion metadata:

nodes = retriever.retrieve("how does auth work?")
# expansion_used, expansion_variants, expansion_elapsed_ms written to query_telemetry table

GitHub PR review integration

# Review a PR diff locally
trelix review --pr owner/repo#42

# Review and post findings back as a GitHub review comment
trelix review --pr owner/repo#42 --post-comments

Requires GITHUB_TOKEN env var. The TrelixIndexRetriever can be used as the retrieval backend inside DiffReviewer.

Multi-repo file watching

# Watch all indexed repos simultaneously; updates index on file changes
trelix watch-all

Deleted files are removed from the SQLite index and vector store automatically.

Config field rename

flare_max_retries replaces flare_max_iterations in RetrievalConfig. Both the new env var TRELIX_RETRIEVAL_FLARE_MAX_RETRIES and the old TRELIX_RETRIEVAL_FLARE_MAX_ITER are accepted (old name emits DeprecationWarning and will be removed in v3.0.0).

Links

• trelix on GitHub
• trelix on PyPI
• trelix-mcp — MCP server for Claude Code, Cursor, Windsurf
• trelix-langchain — LangChain retriever