Metadata-Version: 2.5
Name: trelix-llama-index
Version: 3.1.2
Summary: LlamaIndex retriever for trelix code intelligence
Project-URL: Homepage, https://github.com/sairam0424/trelix
Author: Trelix Contributors
License: MIT License
        
        Copyright (c) 2025 Trelix Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agent,code-intelligence,code-search,llama-index,llamaindex,llm,rag,retriever
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: llama-index-core>=0.10.0
Requires-Dist: trelix>=3.0.0
Description-Content-Type: text/markdown

# trelix-llama-index

LlamaIndex retriever for [trelix](https://github.com/sairam0424/trelix) — semantic code search using Tree-sitter AST parsing, hybrid BM25+vector search, call-graph expansion, and streaming synthesis support.

## Install

```bash
pip install trelix-llama-index
```

## Usage

```python
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

```python
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)

```python
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:

```python
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.

| Feature | Env var | Benefit for LlamaIndex users |
|---------|---------|------------------------------|
| Agentic loop | `TRELIX_RETRIEVAL_AGENTIC=true` | Multi-hop retrieval for complex queries |
| SPLADE-Code | `TRELIX_RETRIEVAL_SPARSE=true` | Better recall on identifier-heavy queries |
| Block indexing | `TRELIX_CHUNKER_MULTI_GRANULARITY=true` | Precise sub-function retrieval |
| Taint analysis | `trelix taint (CLI)` | Security flow detection in indexed repos |

## Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `TRELIX_EMBEDDER_PROVIDER` | `local` | Embedding provider: `local` \| `openai` \| `azure` \| `bedrock-cohere` \| `bedrock-titan` \| `huggingface` \| `voyage` |
| `OPENAI_API_KEY` | — | Required for `openai` provider |
| `AZURE_API_KEY` | — | Required for `azure` provider |
| `AWS_ACCESS_KEY_ID` | — | Required for Bedrock providers |
| `HUGGINGFACE_API_KEY` | — | Required for `huggingface` provider |
| `VOYAGE_API_KEY` | — | Required for `voyage` provider |

## Provider switching (v2.0.0+)

```bash
# 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:

```python
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:

```bash
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):

| Retrieval leg | Technique |
|---------------|-----------|
| Vector | Semantic embedding similarity |
| BM25 | Keyword / TF-IDF |
| Call-graph expansion | Symbol → caller/callee traversal |
| **Graph BFS** *(new)* | **Knowledge-graph breadth-first search** |

### Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `graph_search_enabled` | `False` | Enable the graph BFS retrieval leg (opt-in, zero impact when off) |
| `graph_search_depth` | `2` | BFS depth from seed nodes |
| `graph_search_max_results` | `15` | Maximum nodes returned from graph leg before RRF |

Environment variable alternative:

```bash
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:

```bash
# 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:

```bash
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:

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

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

```python
# 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

```python
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:

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

### GitHub PR review integration

```bash
# 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

```bash
# 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](https://github.com/sairam0424/trelix)
- [trelix on PyPI](https://pypi.org/project/trelix/)
- [trelix-mcp](https://pypi.org/project/trelix-mcp/) — MCP server for Claude Code, Cursor, Windsurf
- [trelix-langchain](https://pypi.org/project/trelix-langchain/) — LangChain retriever
