RAGLight CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
make install          # uv pip install -r pyproject.toml

# Run all tests
make test             # PYTHONPATH=src python3 -m unittest -v

# Run a single test module
PYTHONPATH=src python3 -m unittest tests.tests_rag.test_rag_pipeline

# Format code
uv run black .

Python >= 3.12 required. Uses uv as package manager.

Architecture

RAGLight is a modular RAG library built around the Builder pattern for pipeline composition. The core abstraction is a LangGraph StateGraph (retrieve → generate) that orchestrates embeddings, vector store, and LLM.

Data flow

FolderSource / GitHubSource
    → DocumentProcessorFactory (PDF / Code / Text / VLM-PDF)
    → EmbeddingsModel.embed_documents()
    → VectorStore.ingest()

Query → VectorStore.similarity_search() → [CrossEncoder rerank] → LLM.generate() → Answer

Key abstractions (all use ABC + strategy pattern)

Abstraction	Location	Implementations
LLM	src/raglight/llm/llm.py	Ollama, LMStudio, Mistral, OpenAI, Gemini
EmbeddingsModel	src/raglight/embeddings/embeddings_model.py	HuggingFace, Ollama, OpenAI, Gemini
VectorStore	src/raglight/vectorstore/vector_store.py	ChromaVS (raglight[chroma]), QdrantVS (raglight[qdrant])
DocumentProcessor	src/raglight/document_processing/document_processor.py	PDF, Code, Text, VLM-PDF

Extending the library

• New LLM: extend LLM, implement load() + generate(input: Dict) -> str, register in builder.py with_llm()
• New embeddings: extend EmbeddingsModel, implement load() + embed_documents() + embed_query(), register in builder.py with_embeddings()
• New vector store: extend VectorStore, implement abstract methods, register in builder.py with_vector_store()
• New document processor: extend DocumentProcessor, implement process(), register in DocumentProcessorFactory.get_processor()