Spaces:
Sleeping
Sleeping
| title: Mini RAG | |
| emoji: 🔎 | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # Mini RAG | |
| FastAPI mini RAG application with Supabase pgvector. | |
| # mini-RAG | |
| A lightweight Retrieval-Augmented Generation (RAG) backend built with FastAPI. | |
| Upload documents, embed them, and query them with natural language — mini-RAG handles the full pipeline from file ingestion to LLM-generated answers. | |
| --- | |
| ## What it does | |
| 1. **Upload** — accept `.txt` or `.pdf` files per project | |
| 2. **Process** — split files into overlapping text chunks stored in PostgreSQL | |
| 3. **Index** — embed chunks using an LLM provider and store vectors in a vector DB | |
| 4. **Search** — retrieve the most semantically similar chunks for any query | |
| 5. **Answer** — generate a grounded answer from retrieved chunks using an LLM | |
| --- | |
| ## Stack | |
| | Layer | Technology | | |
| |---|---| | |
| | API framework | FastAPI + Uvicorn | | |
| | Validation | Pydantic v2 | | |
| | Relational DB | PostgreSQL 18 + pgvector extension | | |
| | Vector DB | pgvector (primary) or Qdrant (alternative) | | |
| | Async DB driver | SQLAlchemy async + asyncpg | | |
| | DB migrations | Alembic | | |
| | File loading | LangChain + PyMuPDF | | |
| | LLM providers | OpenAI-compatible (OpenRouter, Ollama) · Cohere | | |
| | Reverse proxy | Nginx | | |
| | Observability | Prometheus + Grafana + node-exporter + postgres-exporter | | |
| | Containerization | Docker Compose | | |
| --- | |
| ## Repository layout | |
| ``` | |
| mini-rag/ | |
| ├── docker/ | |
| │ ├── docker-compose.yml # full 8-service stack | |
| │ ├── env/ # environment files (not committed with real keys) | |
| │ ├── minirag/ | |
| │ │ ├── Dockerfile | |
| │ │ └── entrypoint.sh # runs alembic then starts uvicorn | |
| │ ├── nginx/default.conf | |
| │ └── prometheus/prometheus.yml | |
| ├── src/ | |
| │ ├── main.py # FastAPI app, startup wiring | |
| │ ├── requirements.txt | |
| │ ├── controllers/ # business logic / service layer | |
| │ ├── helpers/config.py # settings loader | |
| │ ├── models/ # PostgreSQL models and data-access layer | |
| │ │ └── db_schemes/minirag/ # SQLAlchemy ORM schemas + Alembic migrations | |
| │ ├── routes/ # HTTP endpoints | |
| │ ├── stores/ | |
| │ │ ├── LLM/ # generation + embedding provider abstraction | |
| │ │ └── vectordb/ # vector DB provider abstraction | |
| │ ├── utils/metrics.py # Prometheus middleware | |
| │ └── assets/ | |
| │ ├── files/ # uploaded files (grouped by project_id) | |
| │ └── databases/ # local Qdrant storage (if using QDRANT backend) | |
| ├── ARCHITECTURE.md | |
| ├── setup_guide.md | |
| └── README.md | |
| ``` | |
| --- | |
| ## Quick start (Docker Compose) | |
| ### 1. Configure environment files | |
| ```bash | |
| cd docker/env | |
| cp .env.example.postgres .env.postgres | |
| cp .env.example.postgres-exporter .env.postgres-exporter | |
| cp .env.example.grafana .env.grafana | |
| cp .env.example.app .env.app | |
| ``` | |
| Edit each file. The most important one is `.env.app` — set your LLM provider keys and PostgreSQL credentials. | |
| ### 2. Start all services | |
| ```bash | |
| cd docker | |
| docker compose up -d --build | |
| ``` | |
| ### 3. Verify | |
| ``` | |
| http://localhost/docs → FastAPI Swagger UI | |
| http://localhost:9090 → Prometheus | |
| http://localhost:3000 → Grafana | |
| ``` | |
| For local dev setup (Windows + WSL 2 + Conda), see `setup_guide.md`. | |
| --- | |
| ## API overview | |
| Base URL: `http://localhost/api/v1` (via Nginx) or `http://localhost:8000/api/v1` (direct) | |
| | Method | Endpoint | Description | | |
| |---|---|---| | |
| | `GET` | `/` | Health check — returns app name and version | | |
| | `POST` | `/data/upload/{project_id}` | Upload a file into a project | | |
| | `POST` | `/data/process/{project_id}` | Split uploaded file(s) into chunks | | |
| | `POST` | `/nlp/index/push/{project_id}` | Embed chunks and push into vector DB | | |
| | `GET` | `/nlp/index/info/{project_id}` | Get vector collection metadata | | |
| | `POST` | `/nlp/index/search/{project_id}` | Semantic search over indexed chunks | | |
| | `POST` | `/nlp/index/answer/{project_id}` | Full RAG: retrieve + generate answer | | |
| --- | |
| ## End-to-end pipeline example | |
| ```bash | |
| # 1. Upload | |
| curl -X POST "http://localhost/api/v1/data/upload/1" \ | |
| -F "file=@/path/to/document.txt" | |
| # 2. Process (chunk) | |
| curl -X POST "http://localhost/api/v1/data/process/1" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"file_id":"<returned_file_id>","chunk_size":1000,"overlap_size":100,"do_reset":1}' | |
| # 3. Index (embed + store vectors) | |
| curl -X POST "http://localhost/api/v1/nlp/index/push/1" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"do_reset":1}' | |
| # 4. Ask a question | |
| curl -X POST "http://localhost/api/v1/nlp/index/answer/1" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"text":"What is this document about?","limit":5}' | |
| ``` | |
| --- | |
| ## LLM provider options | |
| ### Generation | |
| | Provider | `GENERATION_BACKEND` | Notes | | |
| |---|---|---| | |
| | OpenRouter | `OPENAI` | Remote API, no local install, set `OPENAI_API_URL=https://openrouter.ai/api/v1` | | |
| | Ollama | `OPENAI` | Local models, set `OPENAI_API_URL=http://host.docker.internal:11434/v1/` | | |
| | Cohere | `COHERE` | Set `COHERE_API_KEY` | | |
| ### Embedding | |
| | Provider | `EMBEDDING_BACKEND` | Notes | | |
| |---|---|---| | |
| | Cohere | `COHERE` | `embed-multilingual-light-v3.0` supports 100+ languages | | |
| | OpenAI | `OPENAI` | `text-embedding-3-small` (size 1536) or `text-embedding-3-large` | | |
| --- | |
| ## Vector DB options | |
| | Backend | `VECTOR_DB_BACKEND` | Notes | | |
| |---|---|---| | |
| | pgvector | `PGVECTOR` | Runs inside the PostgreSQL container, no extra service needed | | |
| | Qdrant | `QDRANT` | Separate Qdrant container, stores local files under `src/assets/databases/` | | |
| The pgvector backend creates an HNSW index automatically once a collection reaches `VECTOR_DB_INDEX_THRESHOLD` rows (default 100). | |
| --- | |
| ## Prompt language support | |
| RAG prompts are localized. Templates live in `src/stores/LLM/templates/locales/`. | |
| Supported languages out of the box: | |
| - English (`en`) | |
| - Arabic (`ar`) | |
| Set `PRIMARY_LANG` and `DEFAULT_LANG` in `.env` to control which templates are used. | |
| --- | |
| ## Observability | |
| Prometheus scrapes metrics from three sources: | |
| - FastAPI app — HTTP request counts and latencies per endpoint | |
| - Node Exporter — host CPU, memory, disk, network | |
| - Postgres Exporter — PostgreSQL connection pool, query performance, table sizes | |
| Import the standard Grafana dashboards (IDs `1860` for Node Exporter and `9628` for PostgreSQL) to get instant visibility. | |
| --- | |
| ## Key configuration variables | |
| | Variable | Default | Description | | |
| |---|---|---| | |
| | `POSTRGRES_HOST` | `pgvector` (Docker) | PostgreSQL host | | |
| | `VECTOR_DB_BACKEND` | `PGVECTOR` | `PGVECTOR` or `QDRANT` | | |
| | `GENERATION_BACKEND` | `OPENAI` | `OPENAI` or `COHERE` | | |
| | `EMBEDDING_BACKEND` | `COHERE` | `OPENAI` or `COHERE` | | |
| | `EMBEDDING_MODEL_SIZE` | `384` | Must match the model's actual output dimension | | |
| | `PRIMARY_LANG` | `en` | Prompt template language | | |
| | `VECTOR_DB_INDEX_THRESHOLD` | `100` | Rows needed before HNSW index is created | | |
| See `src/.env.example` for the full list. | |
| --- | |
| ## Known issues | |
| - `GENERATION_DEFAULT_TEMPRATURE` env key has a typo (matches the code — do not correct the env key without also updating `config.py`). | |
| - `GET /nlp/index/info/{project_id}` returns a raw provider object that needs serialization cleanup before it is fully JSON-safe. | |
| - The process endpoint success signal mentions "vectordb" even though this step only writes to PostgreSQL — it is misleading but harmless. | |
| See `Errors&Sol.txt` for specific bugs encountered and their fixes. | |
| See `ARCHITECTURE.md` for a full codebase breakdown. | |
| --- | |
| ## Security | |
| - Do not commit real API keys. Rotate any keys that appear in `.env` files before sharing this repository. | |
| - All `.env` files under `src/` are excluded by `.gitignore`. Files under `docker/env/` must be managed manually. | |
| - The Prometheus metrics endpoint is exposed at a randomized path to limit accidental public exposure. | |