trelix 0.7.1

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 v0.7.0 — Universal LLM Factory

Upgrade	What it adds	Impact
Universal LLM Factory	TrelixChatClient ABC — complete(), stream(), tool_call()	Switch providers with one env var
Bedrock Chat	AWS Bedrock Converse API — sonnet-4-6 default, haiku fallback	No external API key beyond AWS
Bedrock Embeddings	Titan v2 (256/512/1024 dims) + Cohere embed-english-v3	Best retrieval quality on Bedrock
Anthropic Direct	Claude 3.5/4 via Anthropic API	Direct API without AWS routing
Vertex AI / Gemini	Google Vertex AI + LiteLLM (100+ providers)	Any provider in one line
Contextual Chunking	LLM summary prepended to each chunk	67% retrieval failure reduction
Voyage / local-code	voyage-code-3 or SFR-Embedding-Code-2B_R	+49% quality vs Ada-002 on CoIR

---

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 or cross-encoder reranker for final precision
• LLM synthesis — trelix ask with 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

---

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.

---

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 Qdrant vector backend (>500k chunk scale)
pip install "trelix[qdrant]"

# 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 | 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)

Variable	Default	Description
TRELIX_STORE_BACKEND	sqlite	sqlite | qdrant
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

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
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).

---

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.