RAGLight

<img alt="RAGLight" height="200px" src="https://github.com/Bessouat40/RAGLight/raw/3.4.7/media/raglight.png">

RAGLight is a lightweight and modular Python library for implementing Retrieval-Augmented Generation (RAG). It enhances the capabilities of Large Language Models (LLMs) by combining document retrieval with natural language inference.

Designed for simplicity and flexibility, RAGLight provides modular components to easily integrate various LLMs, embeddings, and vector stores, making it an ideal tool for building context-aware AI solutions.

---

📚 Table of Contents

• Requirements

• Features

• Import library

• Chat with Your Documents Instantly With CLI

• Ignore Folders Feature

• Ignore Folders in Configuration Classes

• Deploy as a REST API (raglight serve)

• Start the server

• Launch the Chat UI
• Endpoints
• Configuration via environment variables

• Deploy with Docker Compose

• Environment Variables

• Providers and Databases

• LLM

• Embeddings

• Vector Store

• Quick Start

• Knowledge Base

• RAG
• Agentic RAG
• MCP Integration
• Use Custom Pipeline
• Override Default Processors
• Hybrid Search
• Qdrant Vector Store
• Query Reformulation
• Streaming Output
• Conversation History
• AWS Bedrock

• Observability with Langfuse

• Use RAGLight with Docker

• Build your image

• Run your image

---

⚠️ Requirements

Actually RAGLight supports :

• Ollama
• Google Gemini
• LMStudio
• vLLM
• OpenAI API
• Mistral API
• AWS Bedrock

If you use LMStudio, you need to have the model you want to use loaded in LMStudio. If you use AWS Bedrock, configure your AWS credentials (env vars, ~/.aws/credentials, or IAM role) — no extra install needed.

Features

• Embeddings Model Integration: Plug in your preferred embedding models (e.g., HuggingFace all-MiniLM-L6-v2) for compact and efficient vector embeddings.
• LLM Agnostic: Seamlessly integrates with different LLMs from different providers (Ollama, LMStudio, Mistral, OpenAI, Google Gemini, AWS Bedrock).
• RAG Pipeline: Combines document retrieval and language generation in a unified workflow.
• Agentic RAG Pipeline: Use Agent to improve your RAG performances.
• 🔌 MCP Integration: Add external tool capabilities (e.g. code execution, database access) via MCP servers.
• Flexible Document Support: Ingest and index various document types (e.g., PDF, TXT, DOCX, Python, Javascript, ...).
• Extensible Architecture: Easily swap vector stores, embedding models, or LLMs to suit your needs.
• 🔍 Hybrid Search (BM25 + Semantic + RRF): Combine keyword-based BM25 retrieval with dense vector search using Reciprocal Rank Fusion for best-of-both-worlds results.
• ✍️ Query Reformulation: Automatically rewrites follow-up questions into standalone queries using conversation history, improving retrieval accuracy in multi-turn conversations.
• 💬 Conversation History: Full multi-turn history supported across all providers (Ollama, OpenAI, Mistral, LMStudio, Gemini, Bedrock) with optional max_history cap.
• ⚡ Streaming Output: Token-by-token streaming via generate_streaming() on all providers — drop-in alongside generate() with no extra configuration.
• ☁️ AWS Bedrock: Use Claude, Titan, Llama and other Bedrock models for both LLM inference and embeddings.
• 📊 Langfuse Observability (v3+): Trace every RAG call end-to-end — retrieve, rerank, and generate — directly in your Langfuse dashboard.

---

Import library 🛠️

Install the base library:

pip install raglight

RAGLight uses optional extras for vector store backends, so you only install what you need:

Extra	Package installed	Notes
raglight[chroma]	chromadb	Requires a C++ compiler on Windows
raglight[qdrant]	qdrant-client	Pure Python — works on Windows without a C++ compiler
raglight[langfuse]	langfuse	Observability tracing

pip install "raglight[qdrant]"           # Qdrant only (Windows-friendly)
pip install "raglight[chroma]"           # ChromaDB only
pip install "raglight[chroma,qdrant]"    # both
pip install "raglight[qdrant,langfuse]"  # Qdrant + observability

---

Chat with Your Documents Instantly With CLI 💬

For the quickest and easiest way to get started, RAGLight provides an interactive command-line wizard. It will guide you through every step, from selecting your documents to chatting with them, without writing a single line of Python. Prerequisite: Ensure you have a local LLM service like Ollama running.

Just run this one command in your terminal:

raglight chat

You can also launch the Agentic RAG wizard with:

raglight agentic-chat

The wizard will guide you through the setup process. Here is what it looks like:

<img alt="RAGLight" src="https://github.com/Bessouat40/RAGLight/raw/3.4.7/media/cli.png">

The wizard will ask you for:

• 📂 Data Source: The path to your local folder containing the documents.
• 🚫 Ignore Folders: Configure which folders to exclude during indexing (e.g., .venv, node_modules, __pycache__).
• 💾 Vector Database: Where to store the indexed data and what to name it.
• 🧠 Embeddings Model: Which model to use for understanding your documents.
• 🤖 Language Model (LLM): Which LLM to use for generating answers.

After configuration, it will automatically index your documents and start a chat session.

Ignore Folders Feature 🚫

RAGLight automatically excludes common directories that shouldn't be indexed, such as:

• Virtual environments (.venv, venv, env)
• Node.js dependencies (node_modules)
• Python cache files (__pycache__)
• Build artifacts (build, dist, target)
• IDE files (.vscode, .idea)
• And many more...

You can customize this list during the CLI setup or use the default configuration. This ensures that only relevant code and documentation are indexed, improving performance and reducing noise in your search results.

Ignore Folders in Configuration Classes 🚫

The ignore folders feature is also available in all configuration classes, allowing you to specify which directories to exclude during indexing:

• RAGConfig: Use ignore_folders parameter to exclude folders during RAG pipeline indexing
• AgenticRAGConfig: Use ignore_folders parameter to exclude folders during AgenticRAG pipeline indexing
• VectorStoreConfig: Use ignore_folders parameter to exclude folders during vector store operations

All configuration classes use Settings.DEFAULT_IGNORE_FOLDERS as the default value, but you can override this with your custom list:

# Example: Custom ignore folders for any configuration
custom_ignore_folders = [
    ".venv",
    "venv",
    "node_modules",
    "__pycache__",
    ".git",
    "build",
    "dist",
    "temp_files",  # Your custom folders
    "cache"
]

# Use in any configuration class
config = RAGConfig(
    llm=Settings.DEFAULT_LLM,
    provider=Settings.OLLAMA,
    ignore_folders=custom_ignore_folders  # Override default
)

See the complete example in examples/ignore_folders_config_example.py for all configuration types.

---

Deploy as a REST API (raglight serve) 🌐

raglight serve starts a FastAPI server configured entirely via environment variables — no Python code required.

Start the server

raglight serve

Options :

--host      Host to bind (default: 0.0.0.0)
--port      Port to listen on (default: 8000)
--reload    Enable auto-reload for development (default: false)
--workers   Number of worker processes (default: 1)
--ui        Launch the Streamlit chat UI alongside the API (default: false)
--ui-port   Port for the Streamlit UI (default: 8501)

Example :

RAGLIGHT_LLM_MODEL=mistral-small-latest \
RAGLIGHT_LLM_PROVIDER=Mistral \
raglight serve --port 8080

Langfuse tracing example:

LANGFUSE_HOST=http://localhost:3000 \
LANGFUSE_PUBLIC_KEY=pk-lf-... \
LANGFUSE_SECRET_KEY=sk-lf-... \
raglight serve

Langfuse tracing is enabled automatically when LANGFUSE_HOST (or LANGFUSE_BASE_URL), LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are all set in the environment. Requires pip install "raglight[langfuse]".

Launch the Chat UI 💬

Add --ui to start a Streamlit chat interface alongside the REST API — no extra setup required:

raglight serve --ui

Address	Service
http://localhost:8000	REST API + Swagger (/docs)
http://localhost:8501	Streamlit chat UI

The UI lets you: - Chat with your documents — full conversation history, markdown rendering - Upload files directly from the browser (PDF, TXT, code…) - Ingest a directory by providing a path on the server machine - Switch LLM on the fly — the sidebar's ⚙️ Model settings panel lets you change provider, model, and API base URL without restarting the server (AWSBedrock and GoogleGemini included)

Use --ui-port to change the Streamlit port:

raglight serve --ui --port 8000 --ui-port 3000

Both processes share the same configuration (env vars) and are terminated together when you stop the server.

Endpoints

Method	Path	Body	Response
GET	/health	—	{"status": "ok"}
POST	/generate	{"question": "..."}	{"answer": "..."}
POST	/ingest	{"data_path": "...", "file_paths": [...], "github_url": "...", "github_branch": "main"}	{"message": "..."}
POST	/ingest/upload	multipart/form-data — field files (one or more files)	{"message": "..."}
GET	/collections	—	{"collections": [...]}
GET	/config	—	{"llm_provider": "...", "llm_model": "...", "llm_api_base": "..."}
POST	/config	{"llm_provider": "...", "llm_model": "...", "llm_api_base": "..."}	{"llm_provider": "...", "llm_model": "...", "llm_api_base": "..."}

The interactive API documentation (Swagger UI) is automatically available at http://localhost:8000/docs.

Examples with curl

# Health check
curl http://localhost:8000/health

# Ask a question
curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"question": "What is RAGLight?"}'

# Ingest a local folder
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"data_path": "./my_documents"}'

# Ingest a GitHub repository
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"github_url": "https://github.com/Bessouat40/RAGLight", "github_branch": "main"}'

# Upload files directly (multipart)
curl -X POST http://localhost:8000/ingest/upload \
  -F "files=@./rapport.pdf" \
  -F "files=@./notes.txt"

# List collections
curl http://localhost:8000/collections

Configuration via environment variables

All server settings are read from RAGLIGHT_* environment variables. Copy examples/serve_example/.env.example to .env and adjust the values.

Variable	Default	Description
RAGLIGHT_LLM_MODEL	llama3	LLM model name
RAGLIGHT_LLM_PROVIDER	Ollama	LLM provider (Ollama, Mistral, OpenAI, LmStudio, GoogleGemini)
RAGLIGHT_LLM_API_BASE	http://localhost:11434	LLM API base URL
RAGLIGHT_EMBEDDINGS_MODEL	all-MiniLM-L6-v2	Embeddings model name
RAGLIGHT_EMBEDDINGS_PROVIDER	HuggingFace	Embeddings provider (HuggingFace, Ollama, OpenAI, GoogleGemini)
RAGLIGHT_EMBEDDINGS_API_BASE	http://localhost:11434	Embeddings API base URL
RAGLIGHT_DB	Chroma	Vector store backend (Chroma or Qdrant)
RAGLIGHT_PERSIST_DIR	./raglight_db	Local persistence directory (used when RAGLIGHT_DB_HOST is not set)
RAGLIGHT_COLLECTION	default	Collection name
RAGLIGHT_K	5	Number of documents retrieved per query
RAGLIGHT_SYSTEM_PROMPT	(default prompt)	Custom system prompt for the LLM
RAGLIGHT_DB_HOST	—	Remote vector store host (leave unset for local on-disk storage)
RAGLIGHT_DB_PORT	—	Remote vector store port
RAGLIGHT_API_TIMEOUT	300	Request timeout in seconds for the Streamlit UI (increase for slow models)

Deploy with Docker Compose

The quickest way to deploy in production :

cd examples/serve_example
cp .env.example .env   # edit values as needed
docker-compose up

The docker-compose.yml uses extra_hosts: host.docker.internal:host-gateway so the container can reach an Ollama instance running on the host machine.

---

Environment Variables

You can set sev