Retrieval Augmented Generation

FastAPI-based RAG service with Postgres(database), Qdrant(vector database), Gemini OCR, and Hugging Face embeddings.

Key files:

• Docker: Dockerfile, docker-compose.yml, scripts/entrypoint.sh
• App entrypoint: app/main.py
• API router: app/api/router.py
• Alembic: alembic.ini, alembic/env.py, migrations in alembic/versions
• Project deps: pyproject.toml, uv.lock
• Environment: .env.example → copy to .env

Prerequisites

• Docker and Docker Compose
• Or Python 3.11 and uv (for manual setup)

1) Run with Docker Compose

This brings up Postgres, Qdrant, and the API. The API container installs deps using uv, runs Alembic migrations, then starts Uvicorn via scripts/entrypoint.sh.

• Prepare env:

  • cp .env.example .env
  • Edit .env (set GEMINI_API_KEY, etc.)

• Start stack:

  • docker compose up --build

• URLs:

  • API docs: http://localhost:8000/docs
  • Health: http://localhost:8000/health/
  • Postgres: localhost:5432 (inside compose use host db)
  • Qdrant: http://localhost:6333 (inside compose use host qdrant)

• Volumes (persist data/caches):

  • pg_data, qdrant_storage, app_data, hf_cache, torch_cache

Compose sets service URLs to container hostnames in docker-compose.yml (DB at db:5432, Qdrant at qdrant:6333). Migrations are run automatically on container start.

2) Manual setup with uv

Use uv to create a virtual env and install dependencies from pyproject.toml and uv.lock.

1. Install uv (one-time):

   • curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create venv and install deps:

   • uv venv
   • uv sync

3. Configure environment:

   • cp .env.example .env
   • Ensure DB/Qdrant env vars point to localhost (as in .env.example)

4. Start only infra services (Postgres + Qdrant) with Docker:

   • docker compose up -d db qdrant

5. Run Alembic migrations (uses alembic/env.py, which reads app.core.settings):

   • uv run alembic upgrade head

6. Start the API:

   • uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --loop asyncio

API will be available at:

• http://localhost:8000/docs
• http://localhost:8000/health/

Notes

• First model downloads (Hugging Face) can be large; Docker persists caches via hf_cache and torch_cache volumes.
• Qdrant collection is created at startup using vector configs from app.core.settings and initialized by app.infrastructure.qdrant.init_qdrant_on_app.
• Database engines/sessionmakers are initialized in app.infrastructure.postgres.
• Main FastAPI app with lifespan hooks is in app/main.py.