Metadata-Version: 2.4
Name: rag-agent-2.0
Version: 0.1.0
Summary: Production-ready RAG + AI Agent platform with FastAPI, LangGraph, and OpenRouter
Project-URL: Repository, https://github.com/baneseydina/rag-agent
Author-email: baneseydina <seriegalsen9@gmail.com>
License: MIT
Keywords: fastapi,genai,langgraph,llm,openrouter,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: alembic>=1.14
Requires-Dist: asyncpg>=0.30
Requires-Dist: celery[redis]>=5.4
Requires-Dist: chromadb>=0.6
Requires-Dist: duckduckgo-search>=6.3
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: langchain-core>=0.3
Requires-Dist: langchain-openai>=0.3
Requires-Dist: langfuse<3.0,>=2.0
Requires-Dist: langgraph>=0.2
Requires-Dist: llama-index-core>=0.12
Requires-Dist: llama-index-embeddings-openai>=0.3
Requires-Dist: llama-index-vector-stores-chroma>=0.4
Requires-Dist: minio>=7.2
Requires-Dist: openai>=1.58
Requires-Dist: opentelemetry-api>=1.29
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.50b0
Requires-Dist: opentelemetry-sdk>=1.29
Requires-Dist: pillow>=11.0
Requires-Dist: prometheus-client>=0.21
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.10
Requires-Dist: pypdf>=5.1
Requires-Dist: pytesseract>=0.3
Requires-Dist: python-docx>=1.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-multipart>=0.0.12
Requires-Dist: redis>=5.2
Requires-Dist: slowapi>=0.1.9
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: structlog>=24.4
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn[standard]>=0.32
Provides-Extra: dashboard
Requires-Dist: plotly>=5.24; extra == 'dashboard'
Requires-Dist: streamlit>=1.41; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: httpx>=0.28; extra == 'dev'
Requires-Dist: locust>=2.32; extra == 'dev'
Requires-Dist: mypy==1.14.1; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff==0.9.4; extra == 'dev'
Provides-Extra: eval
Requires-Dist: datasets>=3.2; extra == 'eval'
Requires-Dist: ragas>=0.2; extra == 'eval'
Provides-Extra: finetune
Requires-Dist: torch>=2.5; extra == 'finetune'
Requires-Dist: transformers>=4.47; extra == 'finetune'
Requires-Dist: unsloth; extra == 'finetune'
Provides-Extra: guardrails
Requires-Dist: presidio-analyzer>=2.2; extra == 'guardrails'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'guardrails'
Description-Content-Type: text/markdown

# rag-agent

> Production-ready RAG + AI Agent platform — FastAPI · LangGraph · OpenRouter · ChromaDB

[![CI](https://github.com/SeydinaBANE/rag-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/SeydinaBANE/rag-agent/actions/workflows/ci.yml)
[![CD](https://github.com/SeydinaBANE/rag-agent/actions/workflows/cd.yml/badge.svg)](https://github.com/SeydinaBANE/rag-agent/actions/workflows/cd.yml)
[![codecov](https://codecov.io/gh/SeydinaBANE/rag-agent/branch/main/graph/badge.svg)](https://codecov.io/gh/SeydinaBANE/rag-agent)
[![Python](https://img.shields.io/badge/python-3.12-blue?logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## Quickstart

```bash
cp .env.example .env        # add your OPENROUTER_API_KEY
make install                # install deps + pre-commit hooks
make up                     # start all services (Docker)
make migrate                # create DB schema
uv run rag-agent create-key mykey   # create first API key
make dev                    # FastAPI on :8000  →  /docs for Swagger
```

## Architecture

```mermaid
graph TB
    Client -->|X-API-Key| Auth

    subgraph API ["FastAPI :8000"]
        Auth["Auth\n(api_keys table)"]
        Chat["/chat"]
        Agent["/agent\nLangGraph"]
        ReAct["/agent/run\nReAct + SSE"]
        Ingest["/ingest"]
        OCR["/ocr"]
    end

    Auth --> Chat & Agent & ReAct & Ingest & OCR

    subgraph Services
        Guard["Guardrails\nPII · Toxicity"]
        Cache["Semantic Cache\n(Redis, sim > 0.92)"]
        Retriever["Hybrid Retriever\nDense + BM25 + RRF\n+ Cross-encoder"]
        LLM["LLM Client\n(OpenRouter)"]
        Langfuse["Langfuse Tracing"]
    end

    Chat --> Guard --> Cache
    Cache -->|miss| Retriever
    Retriever --> LLM --> Langfuse

    Agent --> Retriever
    ReAct -->|tool_call| WebSearch & RAGSearch

    Ingest -->|async| Celery

    subgraph Storage
        PG[("PostgreSQL\napi_keys · documents")]
        Redis[("Redis\ncache · sessions · Celery")]
        Chroma[("ChromaDB\nvectors")]
        MinIO[("MinIO\nraw files")]
    end

    Auth --> PG
    Cache --> Redis
    Retriever --> Chroma
    Celery --> Chroma & MinIO
```

## API

All endpoints require `X-API-Key` header. See [docs/api.md](docs/api.md) for full request/response reference.

| Endpoint | Method | Description |
|---|---|---|
| `/api/v1/chat` | POST | RAG question answering |
| `/api/v1/chat/stream` | GET | Streaming SSE tokens |
| `/api/v1/agent` | POST | LangGraph agent (grade → web fallback → hallucination check) |
| `/api/v1/agent/run` | POST | ReAct multi-step agent (sync) |
| `/api/v1/agent/run/stream` | GET | ReAct agent with SSE step-by-step |
| `/api/v1/agent/run/sessions/{id}` | GET | Session history |
| `/api/v1/agent/run/sessions/{id}` | DELETE | Clear session |
| `/api/v1/ingest/file` | POST | Upload PDF/DOCX/TXT (async, max 50 MB) |
| `/api/v1/ingest/text` | POST | Ingest raw text |
| `/api/v1/jobs/{id}` | GET | Celery task status |
| `/api/v1/ocr/extract` | POST | Image → structured JSON extraction |
| `/api/v1/ocr/extract/url` | POST | OCR from URL |
| `/api/v1/ocr/schemas` | GET | List supported document types |
| `/api/v1/keys` | POST | Create API key |
| `/api/v1/keys` | GET | List active keys |
| `/api/v1/keys/{id}` | DELETE | Revoke key |
| `/health` | GET | Health check |
| `/metrics` | GET | Prometheus metrics |
| `/docs` | GET | Swagger UI (dev only) |

## Services

| Service | URL | Credentials |
|---|---|---|
| FastAPI | http://localhost:8000 | — |
| ChromaDB | http://localhost:8001 | — |
| MinIO Console | http://localhost:9001 | minioadmin / minioadmin |
| Langfuse | http://localhost:3000 | — |
| Grafana | http://localhost:3001 | admin / admin |
| n8n | http://localhost:5678 | admin / admin |
| Prometheus | http://localhost:9090 | — |

## Key commands

```bash
make test-unit        # fast unit tests (no Docker)
make test             # full suite with coverage (min 80%)
make lint             # ruff + mypy strict
make format           # ruff format + autofix
make eval             # Ragas quality evaluation (requires qa_dataset.json)
make eval-ocr         # OCR accuracy eval → reports/ocr_eval_latest.json
make load             # Locust load test (10 users, 30s)
make worker           # Celery worker (required for async ingest)
make dashboard        # Streamlit admin UI on :8501
make clean            # remove __pycache__, caches, htmlcov
```

## Documentation

- [docs/api.md](docs/api.md) — full API reference with request/response examples
- [docs/finetune.md](docs/finetune.md) — fine-tuning guide (LoRA/QLoRA via Unsloth)
- [docs/bruno/](docs/bruno/) — Bruno API collection for manual endpoint testing
