trelix 2.0.0

Fast, reliable code indexing and retrieval — contextual hybrid search, adaptive planning, call-graph expansion, LLM synthesis

trelix

Fast, reliable code indexing and retrieval. Given a user query and a repository, trelix finds the most relevant code — using a 3-tier adaptive query planner, contextual hybrid search (semantic + keyword + grep), call-graph expansion, reranking, and LLM synthesis.

trelix index  ./my-repo
trelix ask    ./my-repo "how does authentication work?"
trelix search ./my-repo "JWT validation"
trelix watch  ./my-repo          # real-time incremental indexing
trelix stats  ./my-repo

---

What's New in v2.0.0

Phase	Upgrade	What it adds	Impact
1	BGE-Code-v1 / Nomic CodeRankEmbed	bge-code and nomic-code embedding providers	CoIR SOTA: 81.77 avg (BGE-Code-v1)
1	Voyage Matryoshka	TRELIX_EMBEDDER_VOYAGE_OUTPUT_DIMENSIONS=512	2× faster HNSW, smaller storage
1	LLM-as-judge eval	LLMJudge.score() semantic quality measurement	0.0–1.0 retrieval quality score
2	PLAID reranker	rerank_provider=plaid via RAGatouille (trelix[plaid])	7–45× faster ColBERT quality
2	Multi-granularity indexing	TRELIX_FILE_SUMMARIES_ENABLED=true file-level LLM summaries	"Explain codebase" queries work
2	Streaming synthesis	trelix ask streams tokens live; GET /ask SSE endpoint	No more waiting for full response
3	LanceDB backend	TRELIX_STORE_BACKEND=lance (trelix[lance])	3–5× faster insert at 100k+ chunks
3	REST API	trelix serve ./repo --port 8765 (trelix[serve])	Remote deployments, web integrations

---

Features

• Tree-sitter parsing for 20+ languages — functions, classes, methods, call edges, imports
• Contextual hybrid search — contextual embeddings + contextual BM25 + grep via Reciprocal Rank Fusion
• 3-tier adaptive query planner — direct (skip retrieval) → single-step (8-intent) → multi-step decomposition
• Call-graph + import expansion — PageRank-weighted graph traversal with qualified-name precision
• Reranking — Cohere, cross-encoder, or PLAID late-interaction reranker for final precision
• LLM synthesis — trelix ask streams tokens live; GraphRAG map-reduce for large corpora
• Universal LLM client — OpenAI, Azure, Anthropic, Bedrock, Vertex AI, LiteLLM (100+ providers)
• Zero-infra default — single SQLite file (.trelix/index.db) with sqlite-vec HNSW + FTS5 BM25
• Real-time watching — trelix watch auto-indexes on every file save
• Works offline — --provider local uses sentence-transformers, no API key needed
• BGE-Code-v1 / Nomic CodeRankEmbed — CoIR SOTA embedding models (bge-code, nomic-code providers)
• Matryoshka voyage embeddings — compact 256/512-dim voyage-code-3 via TRELIX_EMBEDDER_VOYAGE_OUTPUT_DIMENSIONS
• PLAID late-interaction reranker — 7–45× faster ColBERT via RAGatouille (rerank_provider=plaid)
• Multi-granularity indexing — LLM file-level summaries alongside symbol chunks (TRELIX_FILE_SUMMARIES_ENABLED=true)
• Streaming synthesis — trelix ask streams tokens live; GET /ask SSE endpoint
• REST API — trelix serve ./repo --port 8765 exposes /search, /ask, /index, /health
• LanceDB backend — 3–5× faster vector insert at 100k+ chunks (TRELIX_STORE_BACKEND=lance)

---

Quick Start

# Install (local embeddings — no API key needed)
pip install "trelix[local]"

# Index a repository
trelix index ./my-repo

# Search for code (returns a Rich table)
trelix search ./my-repo "database connection pooling"

# Ask a question (requires OPENAI_API_KEY or AZURE_API_KEY)
trelix ask ./my-repo "how does the authentication middleware work?"

# Watch for file changes and auto-reindex
trelix watch ./my-repo

# Show index statistics
trelix stats ./my-repo

# Re-index a single file after editing
trelix update-index ./my-repo src/auth/middleware.py

# Migrate to Qdrant for large-scale deployments
trelix migrate-vectors --to qdrant --url http://localhost:6333

GitHub Actions — index in CI

Add the trelix-index-action to any workflow to build and cache the index on every push:

- uses: actions/checkout@v4
- uses: sairam0424/trelix-index-action@v1

The action handles Python setup, caching (keyed to the commit SHA), and exposes the index path as an output so downstream steps can query it directly.

---

Troubleshooting

sqlite-vec not loading (macOS)

ImportError: sqlite-vec requires SQLite ≥ 3.45 with loadable extensions

macOS ships with an old SQLite that disables loadable extensions. Fix:

brew install sqlite
# Then reinstall trelix against the Homebrew SQLite:
LDFLAGS="-L/opt/homebrew/opt/sqlite/lib" pip install --force-reinstall trelix[local]

Bedrock: ValidationException on inference profile

ValidationException: Invocation of model ID anthropic.claude-sonnet-4-6 with on-demand throughput isn't supported

Bedrock requires inference profile IDs (us.* prefix), not bare model IDs:

TRELIX_LLM_BEDROCK_PRIMARY_MODEL=us.anthropic.claude-sonnet-4-6
TRELIX_LLM_BEDROCK_FALLBACK_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0

Bedrock Cohere embeddings: ValidationException on large chunks

ValidationException: expected maxLength: 2048

Bedrock's Cohere endpoint rejects texts >2048 characters before truncation occurs. trelix pre-truncates automatically since v0.7.1. If you see this on v0.7.0, upgrade:

pip install --upgrade trelix[bedrock]

tree-sitter FutureWarning spam

Language deprecation warnings from tree-sitter 0.21.x are not yet suppressed automatically. Suppress them with:

PYTHONWARNINGS=ignore::FutureWarning trelix index .

HuggingFace token warning on local embedder

The local embedder uses sentence-transformers which checks for HF_TOKEN. This is harmless — models are cached locally after first download. Suppress with:

HF_HUB_DISABLE_SYMLINKS_WARNING=1 trelix index .

---

Installation

# Homebrew (macOS — Apple Silicon)
brew tap sairam0424/trelix
brew install trelix

# Minimal — local embeddings only (no API key)
pip install "trelix[local]"

# With OpenAI embeddings + query planner + synthesis
pip install trelix
export OPENAI_API_KEY=sk-...

# With best-quality code embeddings (Voyage AI)
pip install "trelix[voyage]"
export VOYAGE_API_KEY=...

# With local code-specialized embeddings (2B model, no API key)
pip install "trelix[local-code]"   # requires ~8GB RAM/GPU

# With Cohere reranker (best precision)
pip install "trelix[rerank]"
export COHERE_API_KEY=...

# With PLAID ColBERT late-interaction reranker
pip install "trelix[plaid]"

# With LanceDB vector backend (3-5x faster insert at 100k+ chunks)
pip install "trelix[lance]"

# With Qdrant vector backend (>500k chunk scale)
pip install "trelix[qdrant]"

# With REST API server
pip install "trelix[serve]"

# With file watcher (real-time incremental indexing)
pip install "trelix[watch]"

# LLM provider extras (v0.7.0)
pip install trelix               # OpenAI + Azure (default)
pip install "trelix[bedrock]"    # + AWS Bedrock (chat + embeddings)
pip install "trelix[anthropic]"  # + Anthropic direct
pip install "trelix[vertex]"     # + Google Vertex AI / Gemini
pip install "trelix[litellm]"    # + LiteLLM (100+ providers)
pip install "trelix[llm-all]"    # all LLM providers

# Everything
pip install "trelix[all]"

---

Configuration

All settings via environment variables or a .env file in the working directory.

LLM Provider (v0.7.0)

Switch chat provider with a single env var — no code changes required.

# Switch chat provider (one env var)
TRELIX_LLM_PROVIDER=bedrock     # Claude sonnet-4-6 default, haiku fallback
TRELIX_LLM_PROVIDER=azure       # Azure OpenAI (existing .env unchanged)
TRELIX_LLM_PROVIDER=anthropic   # Direct Anthropic API

# Switch embedding provider
TRELIX_EMBEDDER_PROVIDER=bedrock-cohere  # Cohere 1024-dim (best retrieval)
TRELIX_EMBEDDER_PROVIDER=bedrock-titan   # Titan v2 (256/512/1024 dims)
TRELIX_EMBEDDER_PROVIDER=azure           # Azure text-embedding-3-large (default)

Variable	Default	Description
TRELIX_LLM_PROVIDER	openai	openai | azure | anthropic | bedrock | vertex | litellm
TRELIX_LLM_MODEL	gpt-4o	Chat model override
TRELIX_LLM_BEDROCK_PRIMARY_MODEL	us.anthropic.claude-sonnet-4-6	Bedrock primary model
TRELIX_LLM_BEDROCK_FALLBACK_MODEL	us.anthropic.claude-haiku-4-5-20251001-v1:0	Bedrock fallback on ValidationException
ANTHROPIC_API_KEY	—	Anthropic API key (trelix[anthropic])
GOOGLE_CLOUD_PROJECT	—	Google Cloud project (trelix[vertex])
GOOGLE_API_KEY	—	Google AI Studio API key (trelix[vertex])
AWS_ACCESS_KEY_ID	—	AWS credentials (trelix[bedrock])
AWS_SECRET_ACCESS_KEY	—	AWS credentials (trelix[bedrock])
AWS_REGION	us-east-1	AWS region (trelix[bedrock])

Embedding Providers

Variable	Default	Description
TRELIX_EMBEDDER_PROVIDER	local	local | openai | azure | voyage | local-code | bge-code | nomic-code | bedrock-titan | bedrock-cohere
OPENAI_API_KEY	—	OpenAI API key
OPENAI_MODEL	gpt-4o	Chat model for planner + synthesis
AZURE_API_KEY	—	Azure OpenAI API key
AZURE_ENDPOINT	—	Azure OpenAI endpoint URL
VOYAGE_API_KEY	—	Voyage AI API key (trelix[voyage])
TRELIX_EMBEDDER_VOYAGE_MODEL	voyage-code-3	Voyage model name
COHERE_API_KEY	—	Cohere reranker API key

Contextual Chunking (v0.4.0)

Variable	Default	Description
TRELIX_CHUNKER_CONTEXTUAL	false	Enable LLM context summary per chunk
TRELIX_CHUNKER_CONTEXTUAL_MODEL	gpt-4o-mini	Model for generating summaries
TRELIX_CHUNKER_CONTEXTUAL_MAX_TOKENS	100	Max tokens per context summary

Vector Store (v0.4.0 / v2.0.0)

Variable	Default	Description
TRELIX_STORE_BACKEND	sqlite	sqlite | qdrant | lance
TRELIX_STORE_HNSW	true	Enable HNSW index (sqlite backend)
TRELIX_STORE_HNSW_M	16	HNSW M parameter
TRELIX_STORE_HNSW_EF_SEARCH	50	HNSW ef_search at query time
QDRANT_URL	http://localhost:6333	Qdrant server URL
QDRANT_API_KEY	—	Qdrant API key (cloud)
QDRANT_COLLECTION	trelix	Qdrant collection name

Multi-Granularity Indexing (v2.0.0)

Variable	Default	Description
TRELIX_FILE_SUMMARIES_ENABLED	false	Generate LLM file-level summaries alongside symbol chunks (RAPTOR-inspired)
TRELIX_FILE_SUMMARIES_MODEL	gpt-4o-mini	Model for generating file-level summaries

Reranking

Variable	Default	Description
TRELIX_RETRIEVAL_RERANK_PROVIDER	—	cohere | cross-encoder | plaid
TRELIX_RETRIEVAL_PLAID_MODEL	colbert-ir/colbertv2.0	RAGatouille PLAID model (trelix[plaid])

REST API (v2.0.0)

Start the REST server:

trelix serve ./my-repo --port 8765

Endpoint	Method	Description
/health	GET	Health check
/search	POST	Hybrid code search
/ask	GET	Streaming synthesis (SSE)
/index	POST	Index or re-index the repository

Retrieval Tuning

Variable	Default	Description
TRELIX_RETRIEVAL_CONTEXT_TOKEN_BUDGET	12000	Max context tokens sent to LLM
TRELIX_RETRIEVAL_GRAPH_RAG	true	Enable GraphRAG map-reduce synthesis
TRELIX_RETRIEVAL_GRAPH_RAG_THRESHOLD_TOKENS	8000	Token threshold to activate GraphRAG
TRELIX_RETRIEVAL_GRAPH_RAG_THRESHOLD_RESULTS	20	Result count threshold to activate GraphRAG
TRELIX_PARSE_WORKERS	4	Parallel threads for parsing phase

See .env.example for the full reference.

---

Supported Languages

Code (Tree-sitter AST)

Python, TypeScript/TSX, JavaScript/JSX, Go, Java, Rust, C, C++, C#, Kotlin, Ruby

.NET / Razor

Razor Components (.razor), Razor MVC Views (.cshtml), MSBuild projects (.csproj)

Config (key-path extraction)

JSON/JSONC, TOML, YAML (multi-document)

Markup

Markdown (heading sections), HTML (custom elements), CSS/SCSS

---

Embedding Providers

Provider	Model	Dim	CoIR Score	Notes
local	all-MiniLM-L6-v2	384	baseline	No API key, CPU
local-code	SFR-Embedding-Code-2B_R	4096	67.41	No API key, ~8GB RAM/GPU
bge-code	BAAI/bge-code-v1	768	81.77	CoIR SOTA 2025, pip install trelix[bge-code]
nomic-code	nomic-ai/nomic-embed-code	768	—	No new deps (uses sentence-transformers), included in trelix[local]
openai	text-embedding-3-large	3072	~45	Best general-purpose
azure	text-embedding-3-large	3072	~45	Azure-hosted OpenAI
voyage	voyage-code-3	1024	56.26	Best API-based code model
bedrock-titan	amazon.titan-embed-text-v2:0	256/512/1024	—	AWS Bedrock, configurable dims
bedrock-cohere	cohere.embed-english-v3	1024	—	AWS Bedrock, asymmetric doc/query

CoIR benchmark scores from archersama.github.io/coir (ACL 2025).

voyage-code-3 Matryoshka: Set TRELIX_EMBEDDER_VOYAGE_OUTPUT_DIMENSIONS=512 for 2× faster HNSW search with minimal quality loss.

---

How it works

flowchart TD
    subgraph INDEXING["INDEXING — trelix index"]
        A[Repository] --> B[FileWalker]
        B --> C[Tree-sitter Parser: 20 languages]
        C --> D[ContextualChunker: LLM summary + breadcrumb]
        D --> E[Embedder: voyage / local-code / openai / azure / bedrock / local]
        E --> F[(sqlite-vec HNSW or Qdrant)]
        C --> G[(SQLite: symbols, call_graph, FTS5 BM25)]
    end

    subgraph RETRIEVAL["RETRIEVAL — trelix search / ask"]
        H[User Query] --> I[AdaptiveRouter: direct / 8-intent / multi-step]
        I --> J[Vector Search: HyDE + ANN]
        I --> K[Contextual BM25: FTS5 + summaries]
        I --> L[Grep Search: exact / regex]
        J --> M[RRF Fusion k=60]
        K --> M
        L --> M
        M --> N[Graph Expansion: call_graph + imports + types]
        N --> O[Reranker: Cohere / cross-encoder]
        O --> P[Context Assembler: greedy / breadth_first]
        P --> Q{Context size?}
        Q -->|8k tokens or less| R[Direct LLM Synthesis]
        Q -->|more than 8k tokens| S[GraphRAG Map-Reduce]
    end

    F --> J
    G --> K
    G --> L
    G --> N

Indexing phases

Phase	What	Parallelism
1 — Parse	Tree-sitter AST traversal per file	ThreadPoolExecutor (parse_workers=4)
2 — Write	Symbol + chunk insertion, parent_id remapping	Sequential (DB consistency)
3 — Embed	Async batch embedding, up to 4 concurrent API calls	asyncio.gather + Semaphore(4)
4 — Resolve	Cross-file call edges (qualified-name priority), imports, type edges	Sequential

Adaptive Query Router (v0.4.0)

Tier	Trigger	Behavior
1 — Direct	Simple factual patterns (what is X, define X)	Skip retrieval, answer from LLM directly
2 — Single-step	Default for most code queries	8-intent classification → retrieval strategy
3 — Multi-step	Complex multi-part queries (walk me through..., end-to-end flow)	LLM decomposes into 2-3 sub-queries, merged results

8 retrieval intents (Tier 2)

Intent	Legs	Graph expansion	Assembly
symbol_lookup	grep + BM25 + vector	call (depth 1)	greedy
file_overview	file-direct	none	greedy
feature_flow	vector + BM25	call+import (depth 2)	greedy
project_overview	file-direct	none	greedy
comparison	all 3	call+import (depth 1)	greedy
config_lookup	file-direct + grep	none	greedy
dependency_map	vector + BM25	import forward (depth 2)	breadth_first
blast_radius	grep + vector + BM25	import reverse (depth 1)	breadth_first

Store layout

Single SQLite file (.trelix/index.db) — zero external infrastructure by default.

Table	Purpose
files	Indexed files with SHA-256 hash for incremental updates
symbols	Extracted symbols with line spans and context_summary (v0.4.0)
call_graph	Directed call edges with callee_type_hint for precision (v0.4.0)
imports	File-level import edges
type_edges	Inheritance / implements / trait edges
chunks	Embeddable text (context header + summary + symbol body)
symbols_fts	FTS5 virtual table for BM25 (indexes context summaries in v0.4.0)
vec_chunks	sqlite-vec HNSW vector table (or Qdrant in v0.4.0)

---

Eval Results

Recall@5 on mini_repo (10 queries, local provider)

Provider: local (sentence-transformers all-MiniLM-L6-v2, no API key)

Query	Expected file	Result
how does authentication work	auth.py	PASS
user repository get by id	user.py	PASS
hash password function	utils.py	PASS
login method	auth.py	PASS
validate token	auth.py	PASS
User dataclass	user.py	PASS
main entry point	main.py	PASS
delete user	user.py	PASS
verify password	utils.py	PASS
create user	user.py	PASS

Recall@5: 10/10 = 100%

Run the full eval harness (v0.4.0)

# Quick eval (mini_repo, 10 queries)
make eval

# Full eval (trelix-self, 50 queries, MRR + Recall@1/5/10 + NDCG@10)
make eval-full

---

Integrations

trelix works across the AI developer ecosystem:

Integration	Install	Usage
MCP (Claude Code, Cursor, Windsurf, Continue.dev)	pip install trelix-mcp	claude mcp add trelix -- trelix-mcp
LangChain	pip install trelix-langchain	TrelixRetriever(repo_path=".")
LlamaIndex	pip install trelix-llama-index	TrelixIndexRetriever(repo_path=".")
GitHub Action	uses: sairam0424/trelix-index-action@v1	Auto-index on push
Homebrew (macOS)	brew tap sairam0424/trelix	brew install trelix

MCP Quick Setup

pip install trelix-mcp
claude mcp add trelix -- trelix-mcp

LangChain Quick Setup

from trelix_langchain import TrelixRetriever
retriever = TrelixRetriever(repo_path="/path/to/repo")
docs = retriever.invoke("how does authentication work?")

---

Development

git clone https://github.com/sairam0424/trelix
cd trelix
make install-dev
make test        # 929 unit + 16 integration tests
make lint
make eval        # recall eval on mini_repo
make eval-full   # full 50-query MRR/NDCG eval (requires Azure/OpenAI)
make binary      # build dist/trelix standalone binary via PyInstaller

See CONTRIBUTING.md for the full guide including how to add a new language parser.

---

License

MIT — see LICENSE.