> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/recipes/rag-over-a-codebase.md).

# RAG over a codebase

Index a codebase into Telys — chunk files, add them with path and line metadata, retrieve with natural-language search, and hand the results to an LLM.

Run RAG over source code entirely on your machine — proprietary code never leaves it. Telys' lexical multigram embedder is strong at natural-language-to-code retrieval ("where do we validate the session token?" → the right function). The loop:

1. **Chunk** files into overlapping line windows.
2. **Add** each chunk with `add_texts`, carrying `path`, `start_line`, and `lang` as metadata.
3. **Retrieve** with `search_text`, optionally filtered by language or file.
4. **Assemble** the hits into a prompt for an LLM.

{% hint style="info" %}
Install with `pipx install telys`, sign in with `telys login`, then verify with `telys runtime verify` — the embedder needs the native kernel from the verified runtime. See [Install Telys](https://docs.telys.ai/start-here/install.md).
{% endhint %}

## Why lexical multigram for code

Dense sentence embedders are tuned for prose. Code is full of identifiers, snake\_case, camelCase, and punctuation that dense models tokenize poorly. `AlgentaMultigramEmbedder` concatenates L2-normalized unigram, bigram, and trigram hashes, so `parse invoice date` lands near `def parse_invoice_date(...)` on substring and token overlap. Use it for natural-language-to-code retrieval on-device. See [Lexical vs dense embeddings](https://docs.telys.ai/understand-telys/lexical-vs-dense.md) and [AlgentaMultigramEmbedder](https://docs.telys.ai/embeddings/multigram.md).

## Chunk and index

Chunk by fixed line windows with a small overlap, so a symbol split across a boundary stays retrievable. Store enough metadata to point back at the source.

{% code title="index\_codebase.py" lineNumbers="true" %}

```python
from pathlib import Path

from telys import Telys, Eq
from telys.embedding import AlgentaMultigramEmbedder

EXTS = {".py": "python", ".ts": "typescript", ".go": "go", ".rs": "rust", ".md": "markdown"}
WINDOW, OVERLAP = 40, 10  # lines per chunk, lines of overlap


def chunk_file(path: Path):
    lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
    step = WINDOW - OVERLAP
    for start in range(0, max(1, len(lines)), step):
        body = "\n".join(lines[start:start + WINDOW])
        if body.strip():
            yield start + 1, body  # 1-based start line


def build_index(repo: str, store: str = "./code-index", name: str = "code"):
    emb = AlgentaMultigramEmbedder()
    telys = Telys(store)
    col = telys.create_collection(
        name,
        dim=emb.profile.dimension,
        partition_by="repo",                 # one partition per repository
        embedder=emb,
        filter_columns=("path", "lang", "start_line", "text"),  # round-trip via with_metadata; filter on path/lang
    )

    texts, ids, metas = [], [], []
    for path in Path(repo).rglob("*"):
        lang = EXTS.get(path.suffix)
        if not lang or not path.is_file():
            continue
        rel = str(path.relative_to(repo))
        for start_line, body in chunk_file(path):
            texts.append(body)
            ids.append(f"{rel}:{start_line}")
            metas.append({
                "repo": name,
                "path": rel,
                "lang": lang,
                "start_line": start_line,
                "text": body,           # keep the chunk so we can rebuild context
            })

    # Insert in batches to bound memory, then commit once.
    for i in range(0, len(texts), 512):
        col.add_texts(texts[i:i + 512], ids[i:i + 512], metas[i:i + 512])
    col.save()
    print(f"indexed {len(texts)} chunks from {name}")
    return telys, col


if __name__ == "__main__":
    build_index(repo=".")
```

{% endcode %}

## Retrieve for a question

Retrieval is one `search_text` call. Pass `with_metadata=True` so each hit carries the `path`, `start_line`, and stored `text` you need to cite and build the prompt. Add `Eq` to scope to one language or file.

{% code title="retrieve.py" lineNumbers="true" %}

```python
from telys import Telys, Eq
from telys.embedding import AlgentaMultigramEmbedder


def retrieve(question: str, store: str = "./code-index", name: str = "code",
             top_k: int = 8, lang: str | None = None):
    emb = AlgentaMultigramEmbedder()
    col = Telys(store).open_collection(name, embedder=emb)
    res = col.search_text(
        question,
        top_k=top_k,
        where=Eq("lang", lang) if lang else None,
        with_metadata=True,
    )
    return [
        {"path": m["path"], "line": m["start_line"], "score": s, "text": m["text"]}
        for s, m in zip(res["scores"], res["metadata"])
    ]


def build_prompt(question: str, hits: list[dict]) -> str:
    blocks = [f"# {h['path']}:{h['line']}\n{h['text']}" for h in hits]
    context = "\n\n".join(blocks)
    return (
        "You are a codebase assistant. Answer using ONLY the snippets below, "
        "and cite each claim as path:line.\n\n"
        f"{context}\n\nQuestion: {question}"
    )


if __name__ == "__main__":
    hits = retrieve("where do we validate the session token?", lang="python")
    for h in hits:
        print(f"{h['score']:.3f}  {h['path']}:{h['line']}")
    prompt = build_prompt("where do we validate the session token?", hits)
    # Hand `prompt` to your LLM — see "Use with OpenAI & Anthropic".
```

{% endcode %}

{% hint style="warning" %}
`Eq` is the only filter Telys ships — no `And`/`Or`/`In`/range operators. To combine a language and a path constraint, fold both into one key at index time (for example `repo` = `scope_key(project, lang)`) and filter on that single key. See [Filter results](https://docs.telys.ai/working-with-data/filter-results.md) and [Filters (Eq)](https://docs.telys.ai/reference/filters.md).
{% endhint %}

## What you will see

Indexing prints the chunk count. Retrieval prints ranked source locations, the token-validation function highest:

```
indexed 1843 chunks from code
0.774  src/auth/session.py:41
0.520  src/auth/tokens.py:12
0.331  tests/test_session.py:88
```

`build_prompt` assembles those snippets into a citable context block for a chat model.

## Scaling to large repositories

For tens of thousands of chunks, build the IVF index after loading to keep searches fast at high recall. `build_ivf` is a no-op below its `min_rows` threshold, so calling it unconditionally is safe:

```python
col.build_ivf(min_rows=20000, target_recall=0.98)
col.save()
```

See [Build the IVF index](https://docs.telys.ai/working-with-data/build-ivf-index.md) and [Search internals (IVF)](https://docs.telys.ai/understand-telys/search-internals-ivf.md).

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Batch ingestion</strong></td><td>Ingest large corpora efficiently and commit once.</td><td><a href="https://docs.telys.ai/recipes/batch-ingestion.md">Batch ingestion</a></td></tr><tr><td><strong>Use with OpenAI &#x26; Anthropic</strong></td><td>Feed retrieved snippets to a chat model.</td><td><a href="https://docs.telys.ai/recipes/with-openai-anthropic.md">OpenAI &amp; Anthropic</a></td></tr><tr><td><strong>Build the IVF index</strong></td><td>Keep large-collection search fast at high recall.</td><td><a href="https://docs.telys.ai/working-with-data/build-ivf-index.md">Build IVF index</a></td></tr></tbody></table>
