TinyRag 🚀

A lightweight, powerful Python library for Retrieval-Augmented Generation (RAG) that works locally without API keys. Features advanced codebase indexing, multiple document formats, and flexible vector storage backends.

🎯 Perfect for developers who need RAG capabilities without complexity or mandatory cloud dependencies.

🌟 Key Features

🚀 Works Locally - No API Keys Required

• 🧠 Local Embeddings: Uses all-MiniLM-L6-v2 by default
• 🔍 Direct Search: Query documents without LLM costs
• ⚡ Zero Setup: Works immediately after installation

📚 Advanced Document Processing

• 📄 Multi-Format: PDF, DOCX, CSV, TXT, and raw text
• 💻 Code Intelligence: Function-level indexing for 7+ programming languages
• 🧵 Multithreading: Parallel processing for faster indexing
• 📊 Chunking Strategies: Smart text segmentation

🗄️ Flexible Storage Options

• 🔌 Multiple Backends: Memory, Pickle, Faiss, ChromaDB
• 💾 Persistence: Automatic or manual data saving
• ⚡ Performance: Choose speed vs. memory trade-offs
• 🔧 Configuration: Customizable for any use case

💬 Optional AI Integration

• 🤖 Custom System Prompts: Tailor AI behavior for your domain
• 🔗 Provider Support: OpenAI, Azure, Anthropic, local models
• 💰 Cost Control: Use only when needed
• 🎯 RAG-Powered Chat: Contextual AI responses

🚀 Quick Start

💡 New to TinyRag? Check out our comprehensive 📖 Documentation with step-by-step guides!

Installation

# Basic installation
pip install tinyrag

# With all optional dependencies
pip install tinyrag[all]

# Specific vector stores
pip install tinyrag[faiss]    # High performance
pip install tinyrag[chroma]   # Persistent storage
pip install tinyrag[docs]     # Document processing

Usage Examples

🏃‍♂️ 30-Second Example (No API Key Required)

from tinyrag import TinyRag

# 1. Create TinyRag instance
rag = TinyRag()

# 2. Add your content  
rag.add_documents([
    "TinyRag makes RAG simple and powerful.",
    "docs/user_guide.pdf",
    "research_papers/"
])

# 3. Search your content
results = rag.query("How does TinyRag work?", k=3)
for text, score in results:
    print(f"Score: {score:.2f} - {text[:100]}...")

Output:

Score: 0.89 - TinyRag makes RAG simple and powerful.
Score: 0.76 - TinyRag is a lightweight Python library for...
Score: 0.72 - The system processes documents using semantic...

🤖 AI-Powered Chat (Optional)

from tinyrag import Provider, TinyRag

# Set up AI provider
provider = Provider(
    api_key="sk-your-openai-key",
    model="gpt-4"
)

# Create smart assistant
rag = TinyRag(
    provider=provider,
    system_prompt="You are a helpful technical assistant."
)

# Add knowledge base
rag.add_documents(["technical_docs/", "api_guides/"])
rag.add_codebase("src/")  # Index your codebase

# Get intelligent answers
response = rag.chat("How do I implement user authentication?")
print(response)
# AI response based on your specific docs and code!

📖 Complete Documentation

📚 Full Documentation - Comprehensive guides from beginner to expert

🚀 Getting Started

• Quick Start - 5-minute introduction
• Installation - Complete setup guide
• Basic Usage - Core features without AI

🔧 Core Features

• Document Processing - PDF, DOCX, CSV, TXT
• Codebase Indexing - Function-level code search
• Vector Stores - Choose the right storage
• Search & Query - Similarity search techniques

🤖 AI Integration

• System Prompts - Customize AI behavior
• Chat Functionality - Build conversations
• Provider Configuration - AI model setup

---

🔧 Core API Reference

Provider Class

from tinyrag import Provider

# 🆓 No API key needed - works locally
provider = Provider(embedding_model="default")

# 🤖 With AI capabilities
provider = Provider(
    api_key="sk-your-key",
    model="gpt-4",                           # GPT-4, GPT-3.5, local models
    embedding_model="text-embedding-ada-002", # or "default" for local
    base_url="https://api.openai.com/v1"     # OpenAI, Azure, custom
)

TinyRag Class

from tinyrag import TinyRag

# 🎛️ Choose your vector store
rag = TinyRag(
    provider=provider,               # Optional: for AI chat
    vector_store="faiss",           # memory, pickle, faiss, chromadb
    chunk_size=500,                 # Text chunk size
    max_workers=4,                  # Parallel processing
    system_prompt="Custom prompt"   # AI behavior
)

🗄️ Vector Store Comparison

Store	Performance	Persistence	Memory	Dependencies	Best For
Memory	⚡ Fast	❌ None	📈 High	✅ None	Development, testing
Pickle	🐌 Fair	💾 Manual	📊 Medium	✅ Minimal	Simple projects
Faiss	🚀 Excellent	💾 Manual	📉 Low	📦 faiss-cpu	Large datasets, speed
ChromaDB	⚡ Good	🔄 Auto	📊 Medium	📦 chromadb	Production, features

💡 Recommendation: Start with memory for development, use faiss for production performance.

🔧 Essential Methods

# 📄 Document Management
rag.add_documents(["file.pdf", "text"])   # Add any documents
rag.add_codebase("src/")                   # Index code functions
rag.clear_documents()                      # Reset everything

# 🔍 Search & Query (No AI needed)
results = rag.query("search term", k=5)   # Find similar content
code = rag.query("auth function")          # Search code too

# 🤖 AI Chat (Optional)
response = rag.chat("Explain this code")   # Get AI answers
rag.set_system_prompt("Be helpful")        # Customize AI

# 💾 Persistence
rag.save_vector_store("my_data.pkl")       # Save your work
rag.load_vector_store("my_data.pkl")       # Load it back

📖 Complete API Reference - Full method documentation

💻 Code Intelligence

TinyRag indexes your codebase at the function level for intelligent code search:

🌐 Supported Languages

Language	Extensions	Detection
Python	.py	def function_name
JavaScript	.js, .ts	function name(), const name =
Java	.java	public/private type name()
C/C++	.c, .cpp, .h	return_type function_name()
Go	.go	func functionName()
Rust	.rs	fn function_name()
PHP	.php	function functionName()

🔍 Code Search Examples

# Index your entire project
rag.add_codebase("my_app/")

# Find authentication code
auth_code = rag.query("user authentication login")

# Database functions
db_code = rag.query("database query SELECT")

# API endpoints
api_code = rag.query("REST API endpoint")

# Get AI explanations (with API key)
response = rag.chat("How does user authentication work?")
# AI analyzes your actual code and explains it!

💡 Learn More - Advanced code search techniques

⚙️ Configuration Examples

🚀 Performance Optimized

# Large datasets, maximum speed
rag = TinyRag(
    vector_store="faiss",
    chunk_size=800,
    max_workers=8  # Parallel processing
)

💾 Production Setup

# Persistent, multi-user ready
rag = TinyRag(
    provider=provider,
    vector_store="chromadb",
    vector_store_config={
        "collection_name": "company_docs",
        "persist_directory": "/data/vectors/"
    }
)

🤖 Custom AI Assistant

# Domain-specific AI behavior
rag = TinyRag(
    provider=provider,
    system_prompt="""You are a senior software engineer.
    Provide detailed technical explanations with code examples."""
)

🔧 Full Configuration Guide - All options explained

📦 Installation

🎯 Choose Your Setup

# 🚀 Quick start (works immediately)
pip install tinyrag

# ⚡ High performance (recommended)
pip install tinyrag[faiss]

# 📄 Document processing (PDF, DOCX)
pip install tinyrag[docs]

# 🗄️ Production database
pip install tinyrag[chroma]

# 🎁 Everything included
pip install tinyrag[all]

🔧 What Each Option Includes

Option	Includes	Use Case
Base	Memory store, local embeddings	Development, testing
[faiss]	+ High-performance search	Large datasets
[docs]	+ PDF/DOCX processing	Document analysis
[chroma]	+ Persistent database	Production apps
[all]	+ Everything	Full features

💡 Installation Guide - Detailed setup instructions

🎯 Real-World Use Cases

🏢 Business Applications

• 📋 Customer Support: Query company docs and policies
• 📚 Knowledge Management: Searchable internal documentation
• 🔍 Research Tools: Semantic search through research papers
• 📊 Report Analysis: Find insights across business reports

👨‍💻 Developer Tools

• 🔧 Code Documentation: Auto-generate code explanations
• 🔍 Legacy Code Explorer: Understand large codebases
• 📖 API Assistant: Query technical documentation
• 🧪 Testing Helper: Find relevant test patterns

🎓 Educational & Research

• 📚 Study Assistant: Query textbooks and notes
• 📝 Writing Helper: Research paper analysis
• 🧠 Learning Companion: Personalized explanations
• 📊 Data Analysis: Explore datasets semantically

💡 See Complete Examples - Production-ready applications

---

🛠️ Contributing

We welcome contributions! Here's how to get started:

# 1. Fork and clone
git clone https://github.com/Kenosis01/TinyRag.git
cd TinyRag

# 2. Install development dependencies  
pip install -e ".[all,dev]"

# 3. Run tests
python -m pytest

# 4. Make your changes and submit a PR!

📋 Development Setup

• Python 3.7+ required
• Core dependencies: sentence-transformers, requests, numpy
• Optional: faiss-cpu, chromadb, PyPDF2, python-docx

🔧 Development Guide - Detailed contributor guidelines

🤝 Community & Support

📞 Get Help

• 📖 Complete Documentation - Comprehensive guides
• 🐛 GitHub Issues - Bug reports & feature requests
• 💬 Discussions - Community Q&A
• 📋 FAQ - Common questions answered

🎉 Show Your Support

• ⭐ Star this repo if TinyRag helps you!
• 🐦 Share on Twitter - spread the word
• ☕ Buy me a coffee - support development
• 🤝 Contribute - help make TinyRag better

---

📄 License

MIT License - see LICENSE for details.

---