Metadata-Version: 2.4
Name: ultimaterag
Version: 0.1.1
Summary: A modular, production-ready Retrieval-Augmented Generation (RAG) platform with multi-vector database support
Author-email: Matrixxboy <matrix.utsav.lankapati@gmail.com>
License: MIT
Project-URL: Homepage, https://theultimaterag.vercel.app/
Project-URL: Documentation, https://theultimaterag.vercel.app/docs
Project-URL: Source, https://github.com/Matrixxboy/TheUnltimateRAG
Project-URL: Issues, https://github.com/Matrixxboy/TheUnltimateRAG/issues
Keywords: rag,llm,ai,fastapi,langchain,vector-database,retrieval-augmented-generation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: FastAPI
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: langchain>=0.1.10
Requires-Dist: langchain-core>=0.1.28
Requires-Dist: langchain-community>=0.0.25
Requires-Dist: langchain-openai>=0.0.8
Requires-Dist: langchain-text-splitters>=0.0.1
Requires-Dist: chromadb>=0.4.24
Requires-Dist: pgvector>=0.2.5
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: redis>=5.0.0
Requires-Dist: openai>=1.13.0
Requires-Dist: tiktoken>=0.6.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

<div align="center">

# 🚀 TUG (TheUltimateRAG)

### A Modular, Production-Ready Foundation for Next-Generation AI Applications

Build scalable, secure, and intelligent RAG (Retrieval-Augmented Generation) systems without reinventing the wheel.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.109.0+-009688.svg?style=flat&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![LangChain](https://img.shields.io/badge/LangChain-Integration-orange)](https://www.langchain.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

🔗 **Official Website & Documentation**  
👉 https://ultimaterag.vercel.app/

[Key Features](#-key-features) •
[Architecture](#-system-architecture) •
[Getting Started](#-getting-started) •
[Visualizer](#-rag-visualizer-gui) •
[API](#-api-endpoints) •
[Contributing](#-contributing)

</div>

---

## 📖 What is TUG (TheUltimateRAG)?

**TUG (TheUltimateRAG)** is a **real-world, production-grade RAG framework**, not just another tutorial or demo project.

It is designed to solve common problems developers face when moving from simple prototypes to **scalable AI systems**, such as:

- Multi-user data separation
- Long-term memory handling
- Organizational knowledge sharing
- Clean, modular architecture

Whether you’re building:

- A **corporate knowledge assistant**
- A **legal or research AI**
- A **personal second-brain**
- Or a **multi-tenant SaaS AI platform**

👉 **TUG (TheUltimateRAG) gives you a strong, extensible backend foundation.**

For a complete walkthrough, architecture deep-dives, and usage examples,  
📘 **visit the official documentation:**  
**https://ultimaterag.vercel.app/**

# 🔐 Environment Configuration for TheUltimateRAG

To run **TheUltimateRAG** correctly, you must create and configure a `.env` file.  
This file stores environment-specific settings such as API keys, database configs, and runtime options.

The project uses **Pydantic Settings + python-dotenv**, so all variables defined in `.env` are automatically loaded at startup.

---

## 📁 Step 1: Create the `.env` File

At the **root of the project**, create a file named:

```bash
.env
```

---

## ⚙️ Step 2: Required & Optional Environment Variables

Below is a **complete reference** of supported environment variables, grouped by purpose.

You only need to configure the parts relevant to your setup.

---

## 🧩 Core Application Settings

```env
APP_NAME=TheUltimateRAG
APP_ENV=development        # development | production
DEBUG=true
```

| Variable   | Description               |
| ---------- | ------------------------- |
| `APP_NAME` | Application name          |
| `APP_ENV`  | Runtime environment       |
| `DEBUG`    | Enable/disable debug logs |

---

## 🤖 LLM & Embedding Providers

```env
LLM_PROVIDER=openai        # openai | ollama | anthropic
EMBEDDING_PROVIDER=openai # openai | ollama | huggingface
MODEL_NAME=gpt-3.5-turbo
```

| Variable             | Description              |
| -------------------- | ------------------------ |
| `LLM_PROVIDER`       | LLM backend to use       |
| `EMBEDDING_PROVIDER` | Embedding model provider |
| `MODEL_NAME`         | Chat model name          |

---

## 🔑 API Keys (Required Based on Provider)

### OpenAI

```env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
```

### Anthropic

```env
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
```

> ⚠️ **Note:**
> If `LLM_PROVIDER` or `EMBEDDING_PROVIDER` is set to `openai`,
> `OPENAI_API_KEY` **must be provided**, otherwise a warning will be shown.

---

## 🧠 Ollama Configuration (Local Models)

```env
OLLAMA_BASE_URL=http://localhost:11434
```

Use this only if you are running **Ollama locally**.

---

## 🗂️ Vector Database Configuration

### ChromaDB (Default – Local)

```env
VECTOR_DB_TYPE=chroma
VECTOR_DB_PATH=./chroma_db_data
EMBEDDING_DIMENSION=1536
```

### PostgreSQL + PGVector

```env
VECTOR_DB_TYPE=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=vector_db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
```

| Variable              | Description                 |
| --------------------- | --------------------------- |
| `VECTOR_DB_TYPE`      | `chroma` or `postgres`      |
| `VECTOR_DB_PATH`      | Local ChromaDB storage path |
| `EMBEDDING_DIMENSION` | Vector embedding size       |

---

## 🧠 Memory & Conversation Storage (Redis)

```env
MEMORY_WINDOW_SIZE=10
MEMORY_WINDOW_LIMIT=10

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_USER=default
REDIS_PASSWORD=
```

The system automatically builds the Redis connection URL internally.

---

## 🔄 How `.env` Is Loaded

The project uses:

- `python-dotenv`
- `pydantic-settings`

```python
load_dotenv()
settings = Settings()
```

So no manual loading is required.

---

## ✅ Minimal `.env` (Quick Start)

If you want to get started **quickly**, this is enough:

```env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
LLM_PROVIDER=openai
EMBEDDING_PROVIDER=openai
VECTOR_DB_TYPE=chroma
```

---

## ⚠️ Important Notes

- **Do NOT commit `.env` to Git**
- Add `.env` to `.gitignore`
- Use different `.env` files for dev & prod if needed

---

## 📘 Need More Help?

For advanced configuration, architecture details, and examples, visit:

👉 **[https://theultimaterag.vercel.app/](https://theultimaterag.vercel.app/)**

---
