systemRAG

Monorepo de RAG (Retrieval-Augmented Generation): backend FastAPI con ChromaDB, recuperación híbrida (semántica + BM25), conectores a Google Drive y base para Microsoft Graph; frontend Next.js 14 con NextAuth (Google) y playground de chat con streaming, citas y traces.

Arquitectura

Capa	Rol
frontend/	Dashboard, login de usuario (NextAuth), chat → llama al API FastAPI
backend/	OAuth Drive/Graph, ingesta, embeddings (OpenAI), vector store, /chat/completions

Importante: el login con Google del dashboard (NextAuth en :3000) y el OAuth del conector Drive (FastAPI en :8000) son flujos distintos; en Google Cloud puedes usar el mismo cliente OAuth aplicación web añadiendo las dos URIs de redirección.

Requisitos

• Python 3.11+ (recomendado)
• Node.js LTS (18+)
• Cuenta OpenAI con API habilitada y facturación/créditos si aplica (embeddings + chat)
• Proyecto Google Cloud con APIs OAuth configuradas (para Drive y/o login NextAuth)

Configuración

1. Copia el ejemplo y ajusta valores reales (no subas .env al repositorio):

   cp .env.example .env

2. Variables principales (ver comentarios en .env.example):

   • Backend: OPENAI_API_KEY, CORS, credenciales Google/Microsoft para conectores, GOOGLE_REDIRECT_URI → http://localhost:8000/auth/google/callback
   • Frontend / NextAuth: NEXTAUTH_SECRET, NEXTAUTH_URL, NEXT_PUBLIC_BACKEND_URL, GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (o variantes *_FRONTEND), URI de callback → http://localhost:3000/api/auth/callback/google

3. Google Cloud → Credenciales → Cliente OAuth (aplicación web) — URI de redirección autorizados:

   • http://localhost:3000/api/auth/callback/google (NextAuth)
   • http://localhost:8000/auth/google/callback (conector Drive)

4. El frontend fusiona variables desde la raíz del repo (next.config.js lee ../.env y ../.env.local), así puedes centralizar secretos en un solo .env en desarrollo.

Instalación

Backend

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

Frontend

cd frontend
npm install

Desde la raíz del monorepo también:

npm run install:frontend

Ejecución en desarrollo

Terminal 1 — API (desde backend/):

cd backend
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

O desde la raíz:

npm run dev:backend

En Windows puedes usar backend/run-dev.ps1 o start-backend.ps1 .

Terminal 2 — Next.js (desde frontend/):

cd frontend
npm run dev

O desde la raíz:

npm run dev:frontend

Atajos Windows: start-frontend.ps1 (añade Node al PATH típico).

• Frontend: http://localhost:3000
• Backend: http://localhost:8000 — health check: GET /health

Tras cambiar .env, reinicia ambos procesos.

Endpoints útiles (backend)

Método	Ruta	Descripción
GET	/health	Estado del servicio
POST	/chat/completions	Chat RAG (JSON o SSE según stream)
—	/auth/google/*	OAuth conector Google Drive
POST	/ingest/cloud	Ingesta desde Google Drive / OneDrive (requiere conexión OAuth previa)

Estructura del repositorio

systemRAG/
├── backend/           # FastAPI, RAG engine, Chroma, conectores
│   ├── app/
│   │   ├── api/routes/
│   │   ├── rag/
│   │   ├── vectorstore/
│   │   └── core/
│   └── requirements.txt
├── frontend/          # Next.js 14 (App Router), NextAuth
│   └── src/
├── .env.example       # Plantilla de variables (copiar a .env)
├── package.json       # Scripts dev:backend / dev:frontend
└── README.md

Los datos persistentes de Chroma suelen guardarse en el directorio configurado por CHROMA_PERSIST_DIR (por defecto chroma_data relativo al proceso del backend).

Solución de problemas

Síntoma	Comprobación
invalid_client (Google)	Client ID/Secret reales; ID con forma ….apps.googleusercontent.com
redirect_uri_mismatch	Coincidencia exacta de URI en Google Cloud; http vs https; localhost vs 127.0.0.1
OpenAI 401	OPENAI_API_KEY válida; prioridad de variables de entorno del sistema sobre .env
OpenAI 429 / cuota	Límites y billing en platform.openai.com
CORS	BACKEND_CORS_ORIGINS y origen del navegador alineados

Licencia

Sin licencia explícita en el repositorio; añade un archivo LICENSE si publicas el proyecto.