RAG Foundation Reference 🚀

A comprehensive reference implementation for Retrieval-Augmented Generation (RAG) systems with advanced memory, intelligent caching, and extensible tools architecture. This foundation provides a solid base for building production-ready RAG applications.

🎯 Main Features

🧠 Intelligent Memory

• Episodic Memory: Stores specific interactions and conversation context
• Semantic Memory: Maintains structured and conceptual knowledge
• Procedural Memory: Learns patterns and behavioral rules

⚡ Multi-Level Cache

• Embeddings Cache: Stores vectors for fast reuse
• Semantic Cache: Groups similar queries for optimized responses
• Query Cache: Instant responses for repeated queries

🔍 Advanced Hybrid Retrieval

• Dense + Sparse: Combines semantic and keyword search
• Re-ranking: Improves relevance with specialized models
• Graph RAG: Knowledge graph navigation

🛠️ Tools System

• Function Calling: Native integration with modern LLMs
• Extensible Tools: Easy creation of custom tools
• Secure Execution: Tool validation and sandboxing

📋 System Components

📁 src/
├── 🔧 core/              # Main engine and abstractions
├── 🧠 memory/            # Persistent memory system
├── 🔍 retrieval/         # Retrieval strategies
├── 💾 cache/             # Cache systems
├── 🤖 llm/              # LLM integrations
├── 📊 vectorstore/       # Vector stores
├── 🔌 embeddings/        # Embedding providers
├── 📈 evaluation/        # Metrics and evaluation
└── 🌐 api/              # REST API and WebSocket

🚀 Quick Installation

1. Clone and setup

git clone git@github.com:carlosparra/RAGFoundationReference.git
cd RAGFoundationReference
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\\Scripts\\activate  # Windows

2. Install dependencies

pip install -e .
# For development:
pip install -e ".[dev]"
# For advanced evaluation:
pip install -e ".[evaluation]"
# For premium providers:
pip install -e ".[premium]"

3. Configure environment variables

cp .env.example .env
# Edit .env with your API keys

⚙️ Configuration

Basic Configuration (config/settings.yaml)

llm:
  provider: "openai"
  model: "gpt-4-turbo"
  temperature: 0.1

vectorstore:
  provider: "chroma"
  collection_name: "knowledge_base"

memory:
  enabled: true
  provider: "hybrid"
  retention_days: 30

cache:
  enabled: true
  embedding:
    provider: "redis"
    ttl: 86400

Supported Providers

🤖 LLMs

• OpenAI: GPT-4, GPT-3.5-turbo
• Anthropic: Claude-3 Sonnet/Opus
• Cohere: Command-R+
• Local: Ollama, vLLM

📊 Vector Stores

• Chroma: For development and prototyping
• Pinecone: For scalable production
• Weaviate: For complex cases
• Qdrant: For high performance
• FAISS: For local use

🧠 Embeddings

• OpenAI: text-embedding-3-large
• HuggingFace: Sentence Transformers
• Cohere: embed-multilingual

🏗️ Basic Usage

Initialize RAG Engine

from src import RAGEngine, ConfigManager

# Load configuration
config = ConfigManager()
rag = RAGEngine(config)
await rag.initialize()

# Add documents
documents = [
    Document(
        id="doc1",
        content="Python is a programming language...",
        metadata={"source": "tutorial", "topic": "programming"}
    )
]
await rag.add_documents(documents)

Perform Queries

# Simple query
response = await rag.query(
    "What is Python?",
    session_id="user123"
)

print(response.answer)
print(f"Confidence: {response.confidence}")
print(f"Sources: {len(response.sources)}")

Using Tools

# Register custom tool
def search_web(query: str, limit: int = 5):
    \"\"\"Search information on the web\"\"\"
    # Your implementation here
    return {"results": [...]}

rag.tool_manager.register_function_as_tool(
    search_web,
    tool_type=ToolType.WEB_SCRAPING
)

# The LLM can now use this tool automatically

🔧 Customization

Create Custom Retriever

from src.core.interfaces import BaseRetriever

class CustomRetriever(BaseRetriever):
    async def retrieve(self, query, top_k=10, **kwargs):
        # Your retrieval logic
        return documents

Create LLM Provider

from src.core.interfaces import BaseLLM

class CustomLLM(BaseLLM):
    async def generate(self, prompt, **kwargs):
        # Your LLM implementation
        return response

Add Advanced Tools

class DatabaseTool(BaseTool):
    @property
    def definition(self):
        return ToolDefinition(
            name="query_database",
            description="SQL database query",
            parameters=[
                ToolParameter("sql", "string", "Query SQL", required=True)
            ],
            tool_type=ToolType.DATABASE
        )

    async def execute(self, sql: str):
        # Execute query safely
        return ToolResult(success=True, result=data)

📊 Evaluation and Monitoring

Automatic Metrics

# Configure evaluation
config.set("evaluation.enabled", True)
config.set("evaluation.metrics", [
    "faithfulness",
    "answer_relevancy",
    "context_precision"
])

# Metrics are calculated automatically

Production Monitoring

# Performance metrics
metrics = await rag.get_metrics()
print(f"P95 Latency: {metrics['latency_p95']}")
print(f"Cache Hit Rate: {metrics['cache_hit_rate']}")
print(f"Token Usage: {metrics['token_usage']}")

🚀 Production Deploy

Docker

# Build image
docker build -t rag-foundation .

# Run with configuration
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $(pwd)/data:/app/data \
  rag-foundation

API REST

# Start server
python scripts/start_api.py

# Query via REST
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?", "session_id": "123"}'

🏗️ Architecture for Specialization

This structure is designed to be cloned and specialized:

For Customer Support Chatbot

# Specialize memory for tickets and history
config.set("memory.episodic.retention_days", 90)
config.set("memory.semantic.customer_profiles", True)

# Specific tools
rag.tools.register(CRMTool())
rag.tools.register(TicketTool())

For Technical Documentation System

# Optimize for code search
config.set("retrieval.strategy", "graph")
config.set("documents.chunk_size", 2048)

# Development tools
rag.tools.register(CodeSearchTool())
rag.tools.register(GitHubTool())

For Data Analysis

# Cache optimized for datasets
config.set("cache.enabled", True)
config.set("cache.embedding.max_size", 1000000)

# Analysis tools
rag.tools.register(SQLTool())
rag.tools.register(PandasTool())

🤝 Contributing

1. Fork the project
2. Create feature branch (git checkout -b feature/new-feature)
3. Commit changes (git commit -am 'Add new feature')
4. Push to branch (git push origin feature/new-feature)
5. Create Pull Request

📄 Licencia

MIT License - see LICENSE for details.

🙏 Acknowledgments

• LangChain community for base abstractions
• RAGAS and LlamaIndex projects for evaluation inspiration
• Open source community for embeddings and vector stores

---

RAG Foundation Reference - Your complete guide to building robust and scalable RAG systems 🚀