### Install MCP Server with Local LLM

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Use this command to install and start the MCP server with a local LLM and embedder. Ensure Claude desktop and uv are installed.

```bash
raglite \
    --db-url duckdb:///raglite.db \
    --llm llama-cpp-python/unsloth/Qwen3-4B-GGUF/*Q4_K_M.gguf@8192 \
    --embedder llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512 \
    mcp install
```

--------------------------------

### Serve Basic Chainlit Frontend

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Start the Chainlit frontend with default configurations. This command requires the 'chainlit' extra to be installed.

```bash
raglite chainlit
```

--------------------------------

### Setup uv Virtual Environment and Pre-commit Hooks

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Use uv to create and install dependencies into a virtual environment, then activate it. Finally, install pre-commit hooks for code quality checks.

```sh
# Create and install a virtual environment
uv sync --python 3.10 --all-extras

# Activate the virtual environment
source .venv/bin/activate

# Install the pre-commit hooks
pre-commit install --install-hooks
```

--------------------------------

### Install Chainlit Frontend Extra

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Installs the chainlit extra for RAGLite, enabling the serving of a ChatGPT-like frontend. This command uses pip to install the necessary dependencies.

```bash
# Install the chainlit extra
pip install raglite[chainlit]
```

--------------------------------

### Install RAGLite with Ragas Extra

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Install RAGLite with the 'ragas' extra to add support for evaluation.

```sh
pip install raglite[ragas]
```

--------------------------------

### Serve Chainlit Frontend with Local LLM

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Launch the Chainlit frontend with a local LLM and embedder. This command starts a customizable ChatGPT-like interface.

```bash
raglite \
    --db-url duckdb:///raglite.db \
    --llm llama-cpp-python/unsloth/Qwen3-4B-GGUF/*Q4_K_M.gguf@8192 \
    --embedder llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512 \
    chainlit
```

--------------------------------

### Install llama-cpp-python Precompiled Binary

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Configure and install a specific precompiled binary for llama-cpp-python. Ensure the combination of version, Python version, accelerator, and platform is supported.

```sh
# Configure which llama-cpp-python precompiled binary to install (⚠️ not every combination is available):
LLAMA_CPP_PYTHON_VERSION=0.3.9
PYTHON_VERSION=310|311|312
ACCELERATOR=metal|cu121|cu122|cu123|cu124
PLATFORM=macosx_11_0_arm64|linux_x86_64|win_amd64

# Install llama-cpp-python:
pip install "https://github.com/abetlen/llama-cpp-python/releases/download/v$LLAMA_CPP_PYTHON_VERSION-$ACCELERATOR/llama_cpp_python-$LLAMA_CPP_PYTHON_VERSION-cp$PYTHON_VERSION-cp$PYTHON_VERSION-$PLATFORM.whl"
```

--------------------------------

### Install RAGLite with Chainlit Extra

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Install RAGLite with the 'chainlit' extra to add support for a customizable ChatGPT-like frontend.

```sh
pip install raglite[chainlit]
```

--------------------------------

### Install RAGLite

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Install the base RAGLite package using pip.

```sh
pip install raglite
```

--------------------------------

### Serve Chainlit Frontend with Default Settings

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Serves the RAGLite Chainlit frontend with default configurations. This command starts the web interface for interacting with the RAG system.

```bash
# Serve the frontend with default settings
raglite chainlit
```

--------------------------------

### Install RAGLite with Pandoc Extra

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Install RAGLite with the 'pandoc' extra to enable support for filetypes other than PDF.

```sh
pip install raglite[pandoc]
```

--------------------------------

### Install MCP Server for Claude Desktop

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Installs the RAGLite MCP server, which provides a `search_knowledge_base` tool for Claude desktop integration. This command requires the RAGLite CLI to be installed.

```bash
# Install the MCP server in Claude desktop
raglite \
    --db-url duckdb:///raglite.db \
    --llm gpt-4o-mini \
    --embedder text-embedding-3-large \
    mcp install
```

--------------------------------

### Configure RAGLite with DuckDB and llama.cpp LLM

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Example configuration for RAGLite using a local DuckDB database and a llama.cpp LLM. Specify the model path and context size.

```python
from raglite import RAGLiteConfig

# Example 'local' config with a DuckDB database and a llama.cpp LLM:
my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="llama-cpp-python/unsloth/Qwen3-8B-GGUF/*Q4_K_M.gguf@8192",
    embedder="llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512", # More than 512 tokens degrades bge-m3's performance
)
```

--------------------------------

### Install MCP Server with API-based LLM

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Configure the MCP server to use an API-based LLM. Set your API key as an environment variable or inline. Ensure credentials are provided.

```bash
export OPENAI_API_KEY=sk-...
raglite \
    --llm gpt-4o-mini \
    --embedder text-embedding-3-large \
    mcp install
```

--------------------------------

### Install RAGLite with Mistral OCR Extra

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Install RAGLite with the 'mistral-ocr' extra for high-quality document processing using Mistral OCR.

```sh
pip install raglite[mistral-ocr]
```

--------------------------------

### Configure RAGLite with PostgreSQL and OpenAI LLM

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Example configuration for RAGLite using a remote PostgreSQL database and an OpenAI LLM. Ensure you have the necessary API keys and database credentials.

```python
from raglite import RAGLiteConfig

# Example 'remote' config with a PostgreSQL database and an OpenAI LLM:
my_config = RAGLiteConfig(
    db_url="postgresql://my_username:my_password@my_host:5432/my_database",
    llm="gpt-4o-mini",  # Or any LLM supported by LiteLLM
    embedder="text-embedding-3-large",  # Or any embedder supported by LiteLLM
)
```

--------------------------------

### Generate Evaluation Examples with insert_evals

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Use this function to generate synthetic question-answer pairs from indexed documents for evaluation purposes. Ensure RAGLiteConfig is properly set up with database and LLM details.

```python
from raglite import RAGLiteConfig, insert_evals

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Generate and store evaluation examples
insert_evals(
    num_evals=100,
    max_chunks_per_eval=20,
    max_workers=4,
    config=config,
)

print("Generated 100 evaluation examples")
```

--------------------------------

### Compute Optimal Query Adapter

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Computes and stores an optimal query adapter to improve retrieval quality by solving an orthogonal Procrustes problem. Requires generating evaluation examples first using `insert_evals`.

```python
from raglite import RAGLiteConfig, insert_evals, update_query_adapter

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# First, generate evaluation examples (required for query adapter)
insert_evals(num_evals=100, config=config)

# Compute and store the optimal query adapter
query_adapter = update_query_adapter(
    max_evals=4096,
    optimize_top_k=40,
    optimize_gap=0.05,
    config=config,
)

print(f"Query adapter shape: {query_adapter.shape}")
print("Query adapter is now active for all vector searches")
```

--------------------------------

### Answer Evaluation Questions with answer_evals

Source: https://context7.com/superlinear-ai/raglite/llms.txt

This function reads evaluation examples from the database and answers them using the RAG pipeline. It requires a configured RAGLiteConfig and specifies the number of evaluations to process.

```python
from raglite import RAGLiteConfig, answer_evals

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Answer evaluation questions
answered_evals_df = answer_evals(num_evals=50, config=config)

print(answered_evals_df.head())
print(f"\nColumns: {answered_evals_df.columns.tolist()}")
# Columns: ['question', 'answer', 'contexts', 'ground_truth', 'ground_truth_contexts']
```

--------------------------------

### Programmable RAG Pipeline Configuration

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Configure RAGLite for a programmable RAG pipeline, allowing manual control over the retrieval process. This example shows how to set the search method.

```python
from raglite import add_context, rag, retrieve_context, vector_search

# Choose a search method
from dataclasses import replace
my_config = replace(my_config, search_method=vector_search)  # Or `hybrid_search`, `search_and_rerank_chunks`, ...

```

--------------------------------

### Insert Documents from File Paths

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Insert documents into RAGLite by providing their file paths. RAGLite handles conversion, chunking, and embedding. Ensure the 'pandoc' extra is installed for non-PDF documents.

```python
# Insert documents given their file path
from pathlib import Path
from raglite import Document, insert_documents

documents = [
    Document.from_path(Path("On the Measure of Intelligence.pdf")),
    Document.from_path(Path("Special Relativity.pdf")),
]
insert_documents(documents, config=my_config)

```

--------------------------------

### Retrieve Chunks by ID

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Retrieve full chunk objects from the database using their IDs. This is useful after performing a search to get the complete content and metadata of relevant chunks.

```python
from raglite import RAGLiteConfig, hybrid_search, retrieve_chunks

config = RAGLiteConfig(db_url="duckdb:///raglite.db")

# First, search for relevant chunks
chunk_ids, _ = hybrid_search("machine learning basics", num_results=5, config=config)

# Retrieve the full chunk objects
chunks = retrieve_chunks(chunk_ids, config=config)

for chunk in chunks:
    print(f"Chunk ID: {chunk.id}")
    print(f"Document: {chunk.document.filename}")
    print(f"Headings: {chunk.headings}")
    print(f"Body preview: {chunk.body[:200]}...")
    print("---")
```

--------------------------------

### Configure Mistral OCR for Document Processing

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Set up Mistral OCR for enhanced document processing, including automatic image descriptions and custom image type filtering. Install the 'mistral-ocr' extra for this functionality.

```python
from raglite import RAGLiteConfig, MistralOCRConfig

my_config = RAGLiteConfig(
    document_processor=MistralOCRConfig(
        include_image_descriptions=True,  # Describe images, charts, and diagrams as text
        image_types=frozenset({"chart", "diagram", "photo", "table", "logo", "icon"}),  # Custom image categories
        exclude_image_types=frozenset({"logo", "icon"}),  # Filter out specific types from the output
    ),
)

```

--------------------------------

### Serve Chainlit Frontend with API-based LLM

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Deploy the Chainlit frontend using an API-based LLM. Provide API credentials via environment variables or inline.

```bash
OPENAI_API_KEY=sk-... raglite --llm gpt-4o-mini --embedder text-embedding-3-large chainlit
```

--------------------------------

### Serve Chainlit Frontend with Environment Variables

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Serves the RAGLite Chainlit frontend using environment variables for API keys, such as OPENAI_API_KEY. This is a secure way to manage credentials for cloud-based LLMs.

```bash
# With environment variables for API keys
OPENAI_API_KEY=sk-... raglite --llm gpt-4o-mini chainlit
```

--------------------------------

### Create RAG Instruction Message

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Converts a user prompt and retrieved context into a RAG instruction message. Ensure RAGLiteConfig is properly initialized.

```python
from raglite import RAGLiteConfig, retrieve_context, add_context

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

user_prompt = "Explain how attention mechanisms work in transformers"

# Retrieve relevant context
chunk_spans = retrieve_context(query=user_prompt, num_chunks=5, config=config)

# Create the RAG instruction message
rag_message = add_context(
    user_prompt=user_prompt,
    context=chunk_spans,
    config=config,
)

print(f"Role: {rag_message['role']}")
print(f"Content preview: {rag_message['content'][:500]}...")
```

--------------------------------

### Serve Chainlit Frontend with Custom Configuration

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Serves the RAGLite Chainlit frontend with custom database, LLM, and embedder configurations. This allows for tailored RAG application deployments.

```bash
# Serve with custom configuration
raglite \
    --db-url duckdb:///raglite.db \
    --llm gpt-4o-mini \
    --embedder text-embedding-3-large \
    chainlit
```

--------------------------------

### Adaptive RAG with Streaming

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Runs an adaptive RAG pipeline that streams the response and uses tool calling for knowledge base searches when needed. Initialize message history and track retrieved context.

```python
from raglite import RAGLiteConfig, rag

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Initialize message history
messages = []
messages.append({
    "role": "user",
    "content": "What are the key differences between CNNs and RNNs?"
})

# Track retrieved context
retrieved_spans = []

# Stream the RAG response
stream = rag(
    messages,
    on_retrieval=lambda spans: retrieved_spans.extend(spans),
    config=config,
)

print("Assistant: ", end="")
for token in stream:
    print(token, end="", flush=True)
print()

# Access retrieved documents
print(f"\nRetrieved {len(retrieved_spans)} context spans")
for span in retrieved_spans:
    print(f"  - {span.document.filename}")
```

--------------------------------

### Implement Full RAG Pipeline

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Advanced implementation showing granular control over search, retrieval, reranking, and context extension.

```python
# Search for chunks
from raglite import hybrid_search, keyword_search, vector_search

user_prompt = "How is intelligence measured?"
chunk_ids_vector, _ = vector_search(user_prompt, num_results=20, config=my_config)
chunk_ids_keyword, _ = keyword_search(user_prompt, num_results=20, config=my_config)
chunk_ids_hybrid, _ = hybrid_search(
    user_prompt, num_results=20, metadata_filter={"topic": "physics"}, config=my_config
)  # Filter results to only include chunks from documents with topic="physics" (works with any search method)

# Multi-value filter in one field uses OR semantics:
chunk_ids_or, _ = hybrid_search(
    user_prompt,
    num_results=20,
    metadata_filter={"domain": ["open", "music"]},
    config=my_config,
)  # Returns chunks where domain includes "open" OR "music".

# Retrieve chunks
from raglite import retrieve_chunks

chunks_hybrid = retrieve_chunks(chunk_ids_hybrid, config=my_config)

# Rerank chunks and keep the top 5 (optional, but recommended)
from raglite import rerank_chunks

chunks_reranked = rerank_chunks(user_prompt, chunks_hybrid, config=my_config)
chunks_reranked = chunks_reranked[:5]

# Extend chunks with their neighbors and group them into chunk spans
from raglite import retrieve_chunk_spans

chunk_spans = retrieve_chunk_spans(chunks_reranked, config=my_config)

# Append a RAG instruction based on the user prompt and context to the message history
from raglite import add_context

messages = []  # Or start with an existing message history
messages.append(add_context(user_prompt=user_prompt, context=chunk_spans, config=my_config))

# Stream the RAG response and append it to the message history
from raglite import rag

stream = rag(messages, config=my_config)
for update in stream:
    print(update, end="")

# Access the documents referenced in the RAG context
documents = [chunk_span.document for chunk_span in chunk_spans]
```

--------------------------------

### Optimize RAG with Query Adapter

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Improve retrieval quality by generating evals and computing an optimal query adapter.

```python
# Improve RAG with an optimal query adapter
from raglite import insert_evals, update_query_adapter

insert_evals(num_evals=100, config=my_config)
update_query_adapter(config=my_config)  # From here, every vector search will use the query adapter
```

--------------------------------

### Evaluate Retrieval and Generation

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Use Ragas to evaluate the performance of retrieval and generation steps.

```python
# Evaluate retrieval and generation
from raglite import answer_evals, evaluate, insert_evals

insert_evals(num_evals=100, config=my_config)
answered_evals_df = answer_evals(num_evals=10, config=my_config)
evaluation_df = evaluate(answered_evals_df, config=my_config)
```

--------------------------------

### Create Document from Text Content

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Create a Document instance directly from text or Markdown content. This is useful for in-memory data or when file conversion is not needed. Custom metadata can be attached.

```python
from raglite import Document

content = """
# Machine Learning Fundamentals

## Introduction
Machine learning is a subset of artificial intelligence that enables systems
to learn and improve from experience without being explicitly programmed.

## Key Concepts
- Supervised Learning
- Unsupervised Learning
- Reinforcement Learning
"""

document = Document.from_text(
    content,
    id="ml-fundamentals-doc",
    filename="ml_fundamentals.md",
    author="Jane Smith",
    topic="education",
    domain=["technology", "AI"],
)

print(f"Document ID: {document.id}")
print(f"Content preview: {document.content[:100]}...")
```

--------------------------------

### Configure RAGLite with DuckDB and Llama.cpp

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Configure RAGLite for local use with DuckDB as the database and Llama.cpp models for LLM and embedding. Adjust the LLM and embedder paths as needed.

```python
# Local config with DuckDB and llama.cpp models
local_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="llama-cpp-python/unsloth/Qwen3-8B-GGUF/*Q4_K_M.gguf@8192",
    embedder="llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512",
)
```

--------------------------------

### Naming Conventions: Full Words vs Abbreviations

Source: https://github.com/superlinear-ai/raglite/blob/main/AGENTS.md

Use full words for variable and function names to ensure clarity, reserving abbreviations only for universally recognized terms.

```python
max_capacity = 9000
state_index = 0
time_series_component = ...
response_buffer = []

def calculate_average(values: Iterable[float]) -> float: ...
```

```python
max_cap = 9000
state_idx = 0
ts_comp = ...
resp_buf = []

def calc_avg(vals: Iterable[float]) -> float: ...
```

--------------------------------

### Configure SSH Agent

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Configure your SSH agent to automatically load keys and use the keychain for authentication. This is a prerequisite for secure Git operations.

```sh
cat << EOF >> ~/.ssh/config

Host *
  AddKeysToAgent yes
  IgnoreUnknown UseKeychain
  UseKeychain yes
  ForwardAgent yes
EOF
```

--------------------------------

### Insert Documents from Text

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Creates and inserts documents directly from plain text strings, optionally assigning a topic. Ensure the Document class and insert_documents function are imported.

```python
from raglite import Document, insert_documents

text_docs = [
    Document.from_text("# Guide to Python\nPython is a versatile language...", topic="programming"),
    Document.from_text("# Data Science Basics\nData science combines...", topic="data"),
]

# Assuming 'config' is already defined
# insert_documents(text_docs, config=config)
```

--------------------------------

### Adaptive RAG Pipeline

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Implement an adaptive RAG pipeline that automatically decides whether to retrieve context based on prompt complexity. The `on_retrieval` callback can be used to access retrieved chunk spans.

```python
from raglite import rag

# Create a user message
messages = []  # Or start with an existing message history
messages.append({
    "role": "user",
    "content": "How is intelligence measured?"
})

# Adaptively decide whether to retrieve and then stream the response
chunk_spans = []
stream = rag(messages, on_retrieval=lambda x: chunk_spans.extend(x), config=my_config)
for update in stream:
    print(update, end="")

# Access the documents referenced in the RAG context
documents = [chunk_span.document for chunk_span in chunk_spans]

```

--------------------------------

### Create Document from File Path

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Create a Document instance from a file path using RAGLite. The system automatically converts supported file types to Markdown and extracts metadata. You can add custom metadata like author and topic.

```python
from pathlib import Path
from raglite import RAGLiteConfig, Document

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Create document from PDF with automatic conversion
document = Document.from_path(
    Path("research_paper.pdf"),
    config=config,
    author="John Doe",
    topic="machine learning",
    year=2024,
)

print(f"Document ID: {document.id}")
print(f"Filename: {document.filename}")
print(f"Metadata: {document.metadata_}")
```

--------------------------------

### Configure RAGLite with PostgreSQL and OpenAI

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Configure RAGLite for remote use with PostgreSQL as the database and OpenAI's GPT-4o-mini as the LLM. Specify embedder, chunk size, and vector search distance metric.

```python
from raglite import RAGLiteConfig

# Remote config with PostgreSQL and OpenAI
remote_config = RAGLiteConfig(
    db_url="postgresql://username:password@host:5432/database",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
    chunk_max_size=2048,
    vector_search_distance_metric="cosine",
)
```

--------------------------------

### Programmable RAG Pipeline - Manual Control

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Provides full control over the RAG pipeline by manually orchestrating each step: search, retrieve chunks, rerank, group into spans, create instruction, and stream response. Ensure RAGLiteConfig is initialized.

```python
from dataclasses import replace
from raglite import (
    RAGLiteConfig,
    hybrid_search,
    retrieve_chunks,
    rerank_chunks,
    retrieve_chunk_spans,
    add_context,
    rag,
)

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

user_prompt = "How does batch normalization improve neural network training?"

# Step 1: Search for relevant chunks
chunk_ids, _ = hybrid_search(
    user_prompt,
    num_results=20,
    metadata_filter={"topic": "deep learning"},
    config=config,
)

# Step 2: Retrieve full chunk objects
chunks = retrieve_chunks(chunk_ids, config=config)

# Step 3: Rerank chunks
reranked_chunks = rerank_chunks(user_prompt, chunks, config=config)[:5]

# Step 4: Group into chunk spans with neighbors
chunk_spans = retrieve_chunk_spans(reranked_chunks, neighbors=(-1, 1), config=config)

# Step 5: Create RAG instruction
messages = []
messages.append(add_context(user_prompt=user_prompt, context=chunk_spans, config=config))

# Step 6: Stream the response
stream = rag(messages, config=config)
response = ""
for token in stream:
    response += token
    print(token, end="", flush=True)
print()

# Access source documents
documents = [span.document for span in chunk_spans]
print(f"\nSources: {[doc.filename for doc in documents]}")
```

--------------------------------

### Configure RAGLite with Self-Query Enabled

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Enable self-query functionality in RAGLite by setting `self_query=True` in the `RAGLiteConfig`. This allows the LLM to automatically generate and apply metadata filters.

```python
my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
    self_query=True,  # Enable self-query
)
```

--------------------------------

### Run MCP Server Manually

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Manually runs the RAGLite MCP server with specified database, LLM, and embedder configurations. This is useful for custom integrations or testing.

```bash
# Run the MCP server manually
raglite \
    --db-url duckdb:///raglite.db \
    --llm llama-cpp-python/unsloth/Qwen3-4B-GGUF/*Q4_K_M.gguf@8192 \
    --embedder llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512 \
    mcp run
```

--------------------------------

### Configure RAGLite with Remote Reranker

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Configure RAGLite with a remote API-based reranker, such as one from Cohere. Requires an API key.

```python
from rerankers import Reranker

# Example remote API-based reranker:
my_config = RAGLiteConfig(
    db_url="postgresql://my_username:my_password@my_host:5432/my_database"
    reranker=Reranker("rerank-v3.5", model_type="cohere", api_key=COHERE_API_KEY, verbose=0)  # Multilingual
)
```

--------------------------------

### Expand Document Metadata with LLM

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Uses an LLM to automatically extract and expand document metadata based on content. Define the metadata fields and their expected types/descriptions.

```python
from typing import Annotated, Literal
from pydantic import Field
from raglite import RAGLiteConfig, Document, expand_document_metadata, insert_documents

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

documents = [
    Document.from_text("# Deep Learning Tutorial\nNeural networks are..."),
    Document.from_text("# SQL Database Guide\nRelational databases store..."),
]

metadata_fields = {
    "title": Annotated[str, Field(..., description="Document title")],
    "author": Annotated[str, Field(..., description="Primary author name")],
    "topics": Annotated[
        list[Literal["AI", "Databases", "Web", "Security"]],
        Field(..., description="Key themes covered"),
    ],
}

enriched_docs = list(expand_document_metadata(
    documents,
    metadata_fields,
    config=config,
))

for doc in enriched_docs:
    print(f"Title: {doc.metadata_.get('title')}")
    print(f"Topics: {doc.metadata_.get('topics')}")

insert_documents(enriched_docs, config=config)
```

--------------------------------

### Search, Rerank, and Group into Spans Pipeline

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Execute a full RAG pipeline including search, reranking, and grouping results into contiguous chunk spans. This provides contextually rich spans for generation.

```python
from raglite import RAGLiteConfig, hybrid_search, search_and_rerank_chunk_spans

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    embedder="text-embedding-3-large",
)

# Full pipeline: search -> rerank -> group into spans
chunk_spans = search_and_rerank_chunk_spans(
    query="how does attention mechanism work in transformers",
    num_results=5,
    oversample=4,
    neighbors=(-1, 1),
    search=hybrid_search,
    config=config,
)

for span in chunk_spans:
    print(f"Document: {span.document.filename}")
    print(f"XML representation:\n{span.to_xml(index=1)[:500]}...")
```

--------------------------------

### Evaluate RAG Performance with evaluate

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Evaluates the quality of RAG answers using the Ragas evaluation framework. This involves first answering evaluation questions and then passing the results to the evaluate function.

```python
from raglite import RAGLiteConfig, answer_evals, evaluate

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Answer evals and evaluate
answered_evals_df = answer_evals(num_evals=20, config=config)
evaluation_df = evaluate(answered_evals_df, config=config)

print("Evaluation Results:")
print(evaluation_df)
# Metrics include: answer_relevancy, faithfulness, context_precision, etc.
```

--------------------------------

### Expand Document Metadata

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Enhance document metadata before insertion using Pydantic models for structured fields. This allows for more precise filtering during retrieval.

```python
from typing import Annotated
from pydantic import Field
from raglite import expand_document_metadata

# Expand the documents' metadata.
metadata_fields = {
    "title": Annotated[str, Field(..., description="Document title.")],
    "author": Annotated[str, Field(..., description="Primary author.")],
    "topics": Annotated[list[Literal["A", "B", "C"]], Field(..., description="Key themes.")],
}
documents = list(expand_document_metadata(documents, metadata_fields, config=my_config))

# Insert documents given their text/plain or text/markdown content
insert_documents(documents, config=my_config)

```

--------------------------------

### retrieve_context

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Retrieves context for RAG using the configured search method.

```APIDOC
## retrieve_context

### Description
Retrieves context for RAG pipelines and returns chunk spans.

### Parameters
- **query** (str) - Required - The search query.
- **num_chunks** (int) - Required - Number of chunks to retrieve.
- **config** (RAGLiteConfig) - Required - Configuration object.

### Response
- **chunk_spans** (list) - List of retrieved chunk spans.
```

--------------------------------

### Async Adaptive RAG with Streaming

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Asynchronous version of the RAG function for use in async applications. It streams the response and can track retrieved context via a callback.

```python
import asyncio
from raglite import RAGLiteConfig, async_rag

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

async def run_async_rag():
    messages = [{"role": "user", "content": "Explain gradient descent in simple terms"}]
    retrieved_spans = []

    print("Assistant: ", end="")
    async for token in async_rag(
        messages,
        on_retrieval=lambda spans: retrieved_spans.extend(spans),
        config=config,
    ):
        print(token, end="", flush=True)
    print()

    return retrieved_spans

# Run the async function
spans = asyncio.run(run_async_rag())
```

--------------------------------

### Search and Rerank Chunks Pipeline

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Combine search and reranking into a single operation for convenience. This pipeline first searches for chunks and then reranks them to provide the most relevant results.

```python
from raglite import RAGLiteConfig, hybrid_search, search_and_rerank_chunks

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    embedder="text-embedding-3-large",
)

# Search, rerank, and get top chunks in one call
chunks = search_and_rerank_chunks(
    query="explain convolutional neural networks",
    num_results=5,
    oversample=4,
    search=hybrid_search,
    config=config,
)

for chunk in chunks:
    print(f"Document: {chunk.document.filename}")
    print(f"Content: {chunk.body[:200]}...")
```

--------------------------------

### Insert Documents with Parallel Processing

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Inserts documents into the database using parallel processing for efficiency. Specify the number of workers and configuration.

```python
from raglite import Document, insert_documents

# Assuming 'config' is already defined
# insert_documents(documents, max_workers=4, config=config)
```

--------------------------------

### Hybrid Search with Custom Weights and Metadata Filter

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Perform a hybrid search combining vector and keyword search with custom weights. Apply a metadata filter to narrow down results to specific domains.

```python
chunk_ids, scores = hybrid_search(
    query="database indexing strategies",
    num_results=5,
    oversample=4,
    vector_search_weight=0.6,
    keyword_search_weight=0.4,
    metadata_filter={"domain": ["databases", "performance"]},
    config=config,
)

print(f"Found {len(chunk_ids)} chunks via hybrid search")
```

--------------------------------

### Configure RAGLite with Local Rerankers

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Configure RAGLite with local cross-encoder rerankers, specifying different models for English and other languages. This is the default behavior.

```python
from rerankers import Reranker

# Example local cross-encoder reranker per language (this is the default):
my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    reranker={
        "en": Reranker("ms-marco-MiniLM-L-12-v2", model_type="flashrank", verbose=0),  # English
        "other": Reranker("ms-marco-MultiBERT-L-12", model_type="flashrank", verbose=0),  # Other languages
    }
)
```

--------------------------------

### Retrieve and Stream RAG Response

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Basic workflow for retrieving context, updating message history, and streaming a response.

```python
user_prompt = "How is intelligence measured?"
chunk_spans = retrieve_context(
    query=user_prompt, 
    num_chunks=5, 
    metadata_filter={"author": "Einstein"},  # Optional: filter by metadata
    config=my_config
)

# Append a RAG instruction based on the user prompt and context to the message history
messages = []  # Or start with an existing message history
messages.append(add_context(user_prompt=user_prompt, context=chunk_spans, config=my_config))

# Stream the RAG response and append it to the message history
stream = rag(messages, config=my_config)
for update in stream:
    print(update, end="")

# Access the documents referenced in the RAG context
documents = [chunk_span.document for chunk_span in chunk_spans]
```

--------------------------------

### Retrieve RAG Context with Chunk Spans

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Retrieve context for Retrieval-Augmented Generation (RAG) using the configured search method. This function returns chunk spans, which are contiguous sequences of chunks from the same document, suitable for feeding into an LLM.

```python
from raglite import RAGLiteConfig, retrieve_context

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Retrieve context for a question
chunk_spans = retrieve_context(
    query="What are the benefits of using transformers in NLP?",
    num_chunks=10,
    config=config,
)

print(f"Retrieved {len(chunk_spans)} context spans")
for span in chunk_spans:
    print(f"  From: {span.document.filename}")
    print(f"  Preview: {span.content[:100]}...")
```

--------------------------------

### Keyword Search (BM25)

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Performs BM25 keyword search using the database's full-text search capabilities. Supports basic search and search with metadata filters.

```python
from raglite import RAGLiteConfig, keyword_search

config = RAGLiteConfig(db_url="duckdb:///raglite.db")

# Basic keyword search
chunk_ids, scores = keyword_search(
    query="neural network backpropagation",
    num_results=10,
    config=config,
)

print(f"Found {len(chunk_ids)} chunks via keyword search")

# Keyword search with metadata filter
chunk_ids, scores = keyword_search(
    query="gradient descent optimization",
    num_results=5,
    metadata_filter={"category": "tutorial"},
    config=config,
)
```

--------------------------------

### Hybrid Search

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Combines vector and keyword search using Reciprocal Rank Fusion (RRF). Allows for improved retrieval quality by leveraging both semantic and keyword matching. Default weights are 75% vector and 25% keyword.

```python
from raglite import RAGLiteConfig, hybrid_search

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    embedder="text-embedding-3-large",
)

# Hybrid search with default weights (75% vector, 25% keyword)
chunk_ids, scores = hybrid_search(
    query="explain transformer architecture attention mechanism",
    num_results=10,
    config=config,
)
```

--------------------------------

### retrieve_chunks

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Retrieves full chunk objects from the database given their IDs.

```APIDOC
## retrieve_chunks

### Description
Fetches full chunk objects from the database based on a provided list of IDs.

### Parameters
- **chunk_ids** (list) - Required - List of chunk IDs to retrieve.
- **config** (RAGLiteConfig) - Required - Configuration object.

### Response
- **chunks** (list) - List of chunk objects.
```

--------------------------------

### Configure Document Processing with Mistral OCR

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Configure RAGLite to use Mistral OCR for document processing, including image descriptions and specific image type filtering. This enhances OCR accuracy for complex documents.

```python
from raglite import RAGLiteConfig, MistralOCRConfig

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
    document_processor=MistralOCRConfig(
        include_image_descriptions=True,
        image_types=frozenset({"chart", "diagram", "photo", "table", "logo", "icon"}),
        exclude_image_types=frozenset({"logo", "icon"}),
    ),
)
```

--------------------------------

### Code Structure: Inlining vs Indirection

Source: https://github.com/superlinear-ai/raglite/blob/main/AGENTS.md

Inline logic to avoid unnecessary indirection unless a variable or function is referenced three or more times.

```python
if len(items) > 0 and all(item.is_valid for item in items):
    process_batch(items)

def total(items: Iterable[Item]) -> float:
    return sum(item.price * item.quantity for item in items)
```

```python
has_items = len(items) > 0
all_valid = all(item.is_valid for item in items)
if has_items and all_valid:
    process_batch(items)

def total(items: Iterable[Item]) -> float:
    def _item_cost(item: Item) -> float:
        return item.price * item.quantity
    return sum(_item_cost(item) for item in items)
```

--------------------------------

### Search Operations

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Functions for performing vector, keyword, and hybrid searches.

```APIDOC
## vector_search

### Description
Performs approximate nearest neighbor vector search using the database's native vector index.

### Parameters
- **query** (str) - Required - Search query string.
- **num_results** (int) - Required - Number of results to return.
- **config** (RAGLiteConfig) - Required - Configuration object.
- **metadata_filter** (dict) - Optional - Metadata filter for search results.

## keyword_search

### Description
Performs BM25 keyword search using the database's full-text search capabilities.

### Parameters
- **query** (str) - Required - Search query string.
- **num_results** (int) - Required - Number of results to return.
- **config** (RAGLiteConfig) - Required - Configuration object.
- **metadata_filter** (dict) - Optional - Metadata filter for search results.

## hybrid_search

### Description
Combines vector search and keyword search using Reciprocal Rank Fusion (RRF).

### Parameters
- **query** (str) - Required - Search query string.
- **num_results** (int) - Required - Number of results to return.
- **config** (RAGLiteConfig) - Required - Configuration object.
```

--------------------------------

### Configure RAGLite with a Custom Reranker

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Configure RAGLite to use a custom reranker, such as Cohere's Reranker V3.5. Ensure you provide your API key for the reranker service.

```python
# Config with custom reranker
from rerankers import Reranker

config_with_reranker = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
    reranker=Reranker("rerank-v3.5", model_type="cohere", api_key="YOUR_API_KEY"),
)
```

--------------------------------

### Rerank Chunks with Cross-Encoder

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Rerank retrieved chunks using a cross-encoder for improved relevance. This is typically done after an initial search to refine the ordering of results.

```python
from raglite import RAGLiteConfig, hybrid_search, rerank_chunks

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    embedder="text-embedding-3-large",
)

# Search for a larger set of chunks
chunk_ids, _ = hybrid_search(
    "explain how gradient descent works",
    num_results=20,
    config=config,
)

# Rerank and keep top results
query = "explain how gradient descent works"
reranked_chunks = rerank_chunks(query, chunk_ids, config=config)[:5]

for i, chunk in enumerate(reranked_chunks):
    print(f"Rank {i+1}: {chunk.document.filename}")
    print(f"  Content: {chunk.body[:150]}...")
```

--------------------------------

### Insert Documents into Database

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Insert documents into the RAGLite database. This process includes automatic chunking, embedding, and indexing. The function supports parallel processing for efficiency when handling multiple documents.

```python
from pathlib import Path
from raglite import RAGLiteConfig, Document, insert_documents

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
)

# Insert documents from files
documents = [
    Document.from_path(Path("doc1.pdf"), config=config, category="research"),
    Document.from_path(Path("doc2.pdf"), config=config, category="tutorial"),
]


```

--------------------------------

### Insert Documents from Text Content

Source: https://github.com/superlinear-ai/raglite/blob/main/README.md

Insert documents into RAGLite using their text content. Metadata such as author, topic, and year can be attached during insertion.

```python
# Insert documents given their text/plain or text/markdown content
content = """
# ON THE ELECTRODYNAMICS OF MOVING BODIES
## By A. EINSTEIN  June 30, 1905
It is known that Maxwell...
"""
documents = [
    Document.from_text(content, author="Einstein", topic="physics", year=1905)
]
insert_documents(documents, config=my_config)

```

--------------------------------

### Document Management Operations

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Functions for inserting, deleting, and metadata enrichment of documents.

```APIDOC
## insert_documents

### Description
Inserts documents into the database with optional parallel processing.

### Parameters
- **documents** (list) - Required - List of Document objects to insert.
- **max_workers** (int) - Optional - Number of parallel workers.
- **config** (RAGLiteConfig) - Required - Configuration object.

## delete_documents

### Description
Removes documents and all associated chunks and embeddings from the database by ID.

### Parameters
- **document_ids** (list) - Required - List of document IDs to delete.
- **config** (RAGLiteConfig) - Required - Configuration object.
- **invalidate_query_adapter** (bool) - Optional - Whether to recompute query adapter after deletion.

## delete_documents_by_metadata

### Description
Removes all documents matching a metadata filter from the database.

### Parameters
- **filter** (dict) - Required - Metadata key-value pairs to match.
- **config** (RAGLiteConfig) - Required - Configuration object.
- **invalidate_query_adapter** (bool) - Optional - Whether to recompute query adapter after deletion.

## expand_document_metadata

### Description
Uses an LLM to automatically extract and expand document metadata based on content analysis.

### Parameters
- **documents** (list) - Required - List of Document objects.
- **metadata_fields** (dict) - Required - Pydantic fields defining metadata structure.
- **config** (RAGLiteConfig) - Required - Configuration object.
```

--------------------------------

### Retrieve Chunk Spans with Neighboring Context

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Group chunks into contiguous spans from the same document. Optionally extend these spans with neighboring chunks to provide broader context.

```python
from raglite import RAGLiteConfig, hybrid_search, retrieve_chunk_spans

config = RAGLiteConfig(db_url="duckdb:///raglite.db")

# Search for relevant chunks
chunk_ids, _ = hybrid_search("database optimization techniques", num_results=10, config=config)

# Retrieve chunk spans with neighboring context
chunk_spans = retrieve_chunk_spans(
    chunk_ids,
    neighbors=(-1, 1),  # Include 1 chunk before and after
    config=config,
)

for span in chunk_spans:
    print(f"Document: {span.document.filename}")
    print(f"Chunks in span: {len(span.chunks)}")
    print(f"Content: {span.content[:300]}...")
    print("---")
```

--------------------------------

### Vector Search

Source: https://context7.com/superlinear-ai/raglite/llms.txt

Performs approximate nearest neighbor (ANN) vector search. Supports basic search and search with metadata filters. Ensure the embedder is configured.

```python
from raglite import RAGLiteConfig, vector_search

config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    embedder="text-embedding-3-large",
)

# Basic vector search
chunk_ids, scores = vector_search(
    query="How do neural networks learn?",
    num_results=10,
    config=config,
)

print(f"Found {len(chunk_ids)} chunks")
for chunk_id, score in zip(chunk_ids, scores):
    print(f"  Chunk {chunk_id}: similarity={score:.4f}")

# Vector search with metadata filter
chunk_ids, scores = vector_search(
    query="machine learning algorithms",
    num_results=5,
    metadata_filter={"topic": "AI", "year": 2024},
    config=config,
)
```