DeepRepo - Local RAG Engine

A production-grade Python library for performing RAG (Retrieval Augmented Generation) on local codebases with multiple AI provider support.

# Features

• Raw Python Implementation: No heavy frameworks (LangChain/LlamaIndex), no external Vector DBs
• Multiple AI Providers: Supports Ollama (local), HuggingFace, OpenAI, Anthropic, and Gemini
• MCP Server Support: Integrate with Cursor, Claude Desktop, Antigravity, and other MCP clients
• Decorator-Based Plugin System: Easy provider registration and extensibility
• Vector Store: NumPy-powered cosine similarity with JSON persistence
• RESTful API: FastAPI service for easy integration
• Docker Ready: Full containerization for deployment

# Quick Start

# # Installation

cd deeprepo_core
pip install -e .

See INSTALLATION.md for detailed setup instructions for each provider.

# # Basic Usage

from deeprepo import DeepRepoClient

#  Initialize with Ollama (FREE, local) - same provider for both embeddings and LLM
client = DeepRepoClient(provider_name="ollama")

#  Or use different providers for embeddings and LLM
#  Example: OpenAI for embeddings, Anthropic for LLM
client = DeepRepoClient(
    embedding_provider_name="openai",
    llm_provider_name="anthropic"
)

#  Ingest documents
result = client.ingest("/path/to/your/code")
print(f"Ingested {result['chunks_processed']} chunks")

#  Query with RAG
response = client.query("How does authentication work?")
print(response['answer'])
print(f"Sources: {response['sources']}")

# Supported AI Providers

| Provider | Cost | Speed | Best For |
|- -- -- -- -- -|- -- -- -|- -- -- --|- -- -- -- -- -|
| Ollama | FREE | Fast | Local development, privacy, offline work |
| HuggingFace | FREE* | Medium | Cloud-based, no local setup |
| OpenAI | Paid | Very Fast | Production, best quality |
| Anthropic | Paid | Very Fast | Production, excellent reasoning |
| Gemini | FREE* | Medium | Testing, Google ecosystem |

*Free tier with rate limits

# # Provider Examples

#  Same provider for both embeddings and LLM
#  Ollama (Recommended - FREE and unlimited)
client = DeepRepoClient(provider_name="ollama")

#  HuggingFace (FREE tier)
client = DeepRepoClient(provider_name="huggingface")

#  OpenAI (Paid, best quality)
client = DeepRepoClient(provider_name="openai")

#  Anthropic (Paid, excellent reasoning)
#  Note: Anthropic doesn't have embeddings API, so use with another provider
client = DeepRepoClient(
    embedding_provider_name="openai",  #  Use OpenAI for embeddings
    llm_provider_name="anthropic"     #  Use Anthropic for LLM
)

#  Gemini (Free tier, limited)
client = DeepRepoClient(provider_name="gemini")

#  Mix and match providers
#  Example: Use free HuggingFace for embeddings, paid OpenAI for LLM
client = DeepRepoClient(
    embedding_provider_name="huggingface",
    llm_provider_name="openai"
)

# Architecture

deeprepo_core/
├── src/deeprepo/
│   ├── client.py       #  Main facade
│   ├── storage.py      #  Vector store (JSON + NumPy)
│   ├── ingestion.py    #  File scanning & chunking
│   ├── interfaces.py   #  Abstract base classes
│   ├── registry.py     #  Decorator-based registry
│   ├── mcp/            #  MCP server for AI assistants
│   │   ├── server.py       #  FastMCP server
│   │   └── README.md       #  MCP documentation
│   └── providers/
│       ├── ollama_v.py      #  Ollama (local, FREE)
│       ├── huggingface_v.py #  HuggingFace (cloud, FREE)
│       ├── openai_v.py      #  OpenAI (paid)
│       ├── anthropic_v.py   #  Anthropic (paid)
│       └── gemini_v.py      #  Gemini (free tier)

# # Design Patterns

• Repository Pattern: VectorStore decouples storage from application logic
• Strategy Pattern: LLMProvider and EmbeddingProvider abstract interfaces
• Registry Pattern: @register_llm decorator for dynamic provider discovery
• Singleton Pattern: FastAPI lifespan loads client once at startup

# MCP Server (AI Assistant Integration)

DeepRepo can be used as an MCP (Model Context Protocol) server, enabling integration with AI assistants like Cursor, Claude Desktop, and Antigravity.

# # Install MCP Dependencies

pip install deeprepo[mcp]

# # Run the MCP Server

#  Using CLI command
deeprepo-mcp

#  Or as Python module
python -m deeprepo.mcp.server

# # Configure Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "deeprepo": {
      "command": "python",
      "args": ["-m", "deeprepo.mcp.server"],
      "env": {
        "LLM_PROVIDER": "ollama"
      }
    }
  }
}

Using separate providers:

{
  "mcpServers": {
    "deeprepo": {
      "command": "python",
      "args": ["-m", "deeprepo.mcp.server"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "LLM_PROVIDER": "anthropic",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

# # Available MCP Tools

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| ingest_codebase | Ingest a directory into the vector store |
| query_codebase | Query the knowledge base with RAG |
| search_similar | Find similar code without LLM |
| get_stats | Get vector store statistics |
| clear_history | Clear conversation history |

See deeprepo_core/src/deeprepo/mcp/README.md for detailed MCP configuration.

# REST API

Start the FastAPI server:

export OPENAI_API_KEY=your-key  #  or use Ollama (no key needed)
uvicorn web_app.main:app - -reload

# # API Endpoints

| Method | Endpoint | Description |
|- -- -- -- -|- -- -- -- -- -|- -- -- -- -- -- --|
| GET | / | Health check |
| GET | /stats | Get vector store statistics |
| POST | /ingest | Ingest documents from a directory |
| POST | /chat | Query with RAG |
| POST | /clear-history | Clear conversation history |

# # API Examples

#  Ingest documents
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/code"}'

#  Query
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "What does this code do?"}'

# Docker Deployment

docker-compose up - -build

The service will be available at http://localhost:8000.

# Provider Comparison

# # Ollama (Recommended for Most Users)

• 100% FREE and unlimited
• Runs locally (privacy + offline)
• Fast (no network latency)
• Requires ~4GB disk space
• Setup: Install Ollama app, pull models

# # HuggingFace

• FREE tier (300 requests/hour)
• No local installation
• Latest open-source models
• Rate limits on free tier
• Setup: Get free API key

# # OpenAI

• Best quality responses
• Very fast and reliable
• Production-ready
• Paid (~$0.001 per query)
• Setup: Get API key, add payment method

# # Anthropic

• Excellent reasoning and long context
• Very fast and reliable
• Production-ready
• Paid (~$0.003 per query)
• Setup: Get API key, add payment method
• Important: Anthropic does NOT provide a dedicated embeddings API
• Recommended: Use Anthropic for LLM with another provider (OpenAI, HuggingFace) for embeddings

# # Gemini

• FREE tier available
• Very limited (15 requests/minute)
• Not recommended for production
• Setup: Get free API key

# Configuration

# # Environment Variables

| Variable | Description | Required For |
|- -- -- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -- -- -|
| HUGGINGFACE_API_KEY or HF_TOKEN | HuggingFace API token | HuggingFace provider |
| OPENAI_API_KEY | OpenAI API key | OpenAI provider |
| ANTHROPIC_API_KEY | Anthropic API key | Anthropic provider |
| GEMINI_API_KEY | Google Gemini API key | Gemini provider |

# # Switching Providers

#  Same provider for both embeddings and LLM (backward compatible)
client = DeepRepoClient(
    provider_name="ollama",  #  or "huggingface", "openai", "anthropic", "gemini"
    storage_path="vectors.json"
)

#  Different providers for embeddings and LLM
client = DeepRepoClient(
    embedding_provider_name="openai",    #  Provider for embeddings
    llm_provider_name="anthropic",      #  Provider for LLM
    storage_path="vectors.json"
)

Or use environment variables:

#  Single provider (backward compatible)
export LLM_PROVIDER=ollama
python your_script.py

#  Separate providers
export EMBEDDING_PROVIDER=openai
export LLM_PROVIDER=anthropic
python your_script.py

Common Use Cases:

• Anthropic for LLM: Since Anthropic doesn't have embeddings, pair it with OpenAI or HuggingFace
• Cost optimization: Use free HuggingFace for embeddings, paid OpenAI for LLM
• Performance: Use fast OpenAI for embeddings, powerful Anthropic for LLM

# Testing

Professional test suite with unit and integration tests.

# # Quick Start

#  Run all unit tests (fast, no API keys needed)
pytest tests/unit/ -v

#  Run with coverage
pytest tests/unit/ - -cov=deeprepo - -cov-report=html

#  Run all tests including integration
pytest tests/ -v

# # Test Structure

• Unit Tests (tests/unit/) - Fast, isolated, no external dependencies

  • test_storage.py - Vector store and cosine similarity
  • test_ingestion.py - File scanning and text chunking
  • test_client.py - Client interface and initialization

• Integration Tests (tests/integration/) - End-to-end testing

  • test_document.py - Document processing pipeline
  • test_all_providers.py - Manual provider verification

# # Manual Provider Testing

#  Test specific providers
python tests/integration/test_all_providers.py ollama
python tests/integration/test_all_providers.py huggingface openai

See tests/README.md for detailed testing documentation.

# Documentation

• INSTALLATION.md - Detailed installation and setup for each provider
• PROJECT_SPEC.MD - Complete project architecture and specifications

# Development

# # Adding a New Provider

1. Create a new file in src/deeprepo/providers/
2. Implement EmbeddingProvider and LLMProvider interfaces
3. Use @register_embedding and @register_llm decorators
4. The provider will be auto-discovered!

Example:

from deeprepo.interfaces import EmbeddingProvider, LLMProvider
from deeprepo.registry import register_embedding, register_llm

@register_embedding("my_provider")
class MyEmbeddingProvider(EmbeddingProvider):
    def embed(self, text: str) -> list[float]:
        #  Your implementation
        pass

@register_llm("my_provider")
class MyLLM(LLMProvider):
    def generate(self, prompt: str, context: str = None) -> str:
        #  Your implementation
        pass

# License

MIT License - see LICENSE file for details

# Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# Support

For issues, questions, or feature requests, please open an issue on GitHub.

Built for developers who want full control over their RAG pipelines