RAG Cars Advisor

RAG Cars Advisor, tambien presentado en la interfaz como "Que Auto Comprar", es un asistente conversacional para apoyar la compra y comparacion de vehiculos. El sistema responde preguntas en lenguaje natural sobre modelos, versiones, equipamiento, seguridad, consumo y caracteristicas tecnicas usando documentos automotrices indexados en Qdrant y respuestas generadas con Groq.

El proyecto combina una aplicacion web en Next.js, una API FastAPI, un motor RAG con FastEmbed/Qdrant/Groq, un pipeline de ingesta de PDFs con LlamaParse, una demo tecnica en Streamlit y despliegues opcionales con Docker, AWS Batch y S3.

Stack Tecnologico

Frontend

• Next.js 14 con App Router.
• React 18.
• TypeScript.
• Tailwind CSS con configuracion local.
• Componentes UI propios en frontend/components/ui.
• lucide-react y react-icons para iconografia.
• Supabase JS client para autenticacion e historial de chats, si esta configurado.
• Fuente Plus Jakarta Sans mediante next/font/google.

No hay una dependencia shadcn/ui instalada en frontend/package.json; el proyecto usa componentes propios con una organizacion similar en frontend/components/ui.

Backend

• Python.
• FastAPI.
• Uvicorn.
• Pydantic.
• python-dotenv.

IA / RAG

• LlamaParse / llama-cloud-services para parseo de PDFs.
• FastEmbed con BAAI/bge-m3 por defecto.
• Qdrant local o Qdrant Cloud como base vectorial.
• Groq para generacion de respuestas.

Infraestructura y herramientas

• Docker para API e indexador.
• AWS Batch y S3 opcionales para ingesta.
• Streamlit como demo tecnica local.

Estructura del Repositorio

RAG_Cars/
|-- frontend/
|   |-- app/                 # Rutas Next.js: /, /chat, /login, /register
|   |-- components/          # Componentes landing, chat, auth, theme y UI
|   |-- constants/           # Textos, rutas y configuracion de UI
|   |-- hooks/               # Hooks de auth, chat y threads
|   |-- lib/                 # Entorno y cliente Supabase
|   |-- public/              # Assets estaticos de Next.js
|   |-- services/            # Clientes HTTP y servicios frontend
|   |-- types/               # Tipos TypeScript
|   |-- utils/               # Utilidades compartidas
|   |-- package.json
|   |-- next.config.mjs
|   |-- tailwind.config.ts
|   `-- tsconfig.json
|-- backend/
|   |-- api.py               # API FastAPI
|   |-- rag_router.py        # Orquestador de consultas RAG
|   |-- rag.py
|   |-- query_engine.py
|   |-- requirements.txt
|   `-- Dockerfile.api
|-- ingestion/
|   |-- loader.py            # Parseo, chunking, embeddings e indexacion
|   |-- jobs/
|   |   `-- index_aws_batch.py
|   `-- Dockerfile
|-- streamlit/
|   `-- streamlit_app.py
|-- docs/
|-- data/
|-- infra/
|-- DEPLOY_NEXTJS.md
|-- PROJECT_OVERVIEW.md
|-- README.md
`-- .env.example

Requisitos Previos

• Node.js 18+.
• npm.
• Python 3.12 recomendado.
• Docker opcional.
• Una API key de Groq para usar el chat RAG.
• Una API key de Llama Cloud si se van a parsear PDFs.
• Qdrant local o Qdrant Cloud.
• Supabase opcional para login, registro e historial de conversaciones.

Instalacion

Frontend Next.js

cd frontend
npm install

Crear frontend/.env.local si se usa el frontend con backend o Supabase:

BACKEND_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_API_BASE_URL=
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Puedes usar .env.example como base para crear un .env en la raiz del repositorio.

Comandos del Frontend

Los scripts reales estan definidos en frontend/package.json:

cd frontend
npm run dev
npm run build
npm run start
npm run lint
npm run test:unit

Uso esperado:

• npm run dev: levanta Next.js en modo desarrollo, normalmente en http://localhost:3000.
• npm run build: genera el build de produccion de Next.js.
• npm run start: sirve el build de produccion generado por Next.js.
• npm run lint: ejecuta validacion TypeScript con tsc --noEmit --incremental false.
• npm run test:unit: ejecuta pruebas unitarias TypeScript con Playwright Test.

El frontend corre con Next.js y el build de produccion lo gestiona Next.js.

Pruebas

Frontend

cd frontend
npm run test:unit

Backend

python -m unittest discover -s tests -v

Ejecucion Local

1. Backend API

cd backend
.venv\Scripts\activate
uvicorn api:app --reload --host 0.0.0.0 --port 8000

Endpoints principales:

GET  /health
POST /api/chat

Para desarrollo con Next.js, configura CORS_ALLOW_ORIGINS con el origen del frontend:

CORS_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

2. Frontend Next.js

cd frontend
npm run dev

Abrir:

http://localhost:3000

Rutas principales:

• /: landing page.
• /chat: experiencia de chat.
• /login: inicio de sesion.
• /register: registro.

3. Streamlit

cd streamlit
streamlit run streamlit_app.py

Streamlit se usa como demo tecnica para probar indexacion y consultas RAG localmente.

4. Ingesta / Indexacion

cd ingestion
python loader.py

Estructura esperada de PDFs:

MARCAS/
  kia/
    k3/
      ficha.pdf
  toyota/
    corolla/
      catalogo.pdf

Variables de Entorno

El archivo .env.example contiene una base actualizada. Las variables mas importantes son:

Variable	Uso	Obligatoria
GROQ_API_KEY	API key para generar respuestas con Groq.	Si se usa el chat RAG
GROQ_MODEL	Modelo LLM usado por Groq.	No
LLAMA_CLOUD_API_KEY	API key para parsear PDFs con LlamaParse.	Si se indexan PDFs
QDRANT_URL	URL de Qdrant remoto.	No si se usa Qdrant local
QDRANT_API_KEY	API key de Qdrant remoto.	Si Qdrant remoto la requiere
QDRANT_COLLECTION	Nombre de la coleccion vectorial.	No
QDRANT_PATH	Ruta local para Qdrant embebido.	No
FASTEMBED_MODEL_NAME	Modelo de embeddings.	No
MARCAS_ROOT	Ruta local donde estan los PDFs fuente.	Si se indexa localmente
RAG_CARS_DATA_DIR	Ruta de salida para Markdown parseado.	No
CORS_ALLOW_ORIGINS	Origenes permitidos por la API FastAPI.	No
BACKEND_API_BASE_URL	URL del backend FastAPI consumida por el proxy de Next.js.	No
NEXT_PUBLIC_API_BASE_URL	URL publica opcional para llamar directo al backend desde el navegador.	No
NEXT_PUBLIC_SUPABASE_URL	URL publica del proyecto Supabase.	Si se usa auth/chat history
NEXT_PUBLIC_SUPABASE_ANON_KEY	Llave anon publica de Supabase.	Si se usa auth/chat history
ENABLE_S3_SYNC	Activa sincronizacion con S3.	Solo para ingesta AWS/S3
AWS_REGION	Region AWS para S3/AWS Batch.	Si se usa AWS
AWS_S3_BUCKET	Bucket S3 para Bronze/Silver/Gold.	Si se usa AWS/S3

Flujo Funcional

1. El usuario entra a la landing de Next.js en /.
2. Para consultar el asistente entra a /chat.
3. Si Supabase esta configurado, el frontend valida la sesion y puede persistir conversaciones.
4. El frontend envia la pregunta a POST /api/chat en Next.js.
5. FastAPI llama al router RAG.
6. El motor RAG genera embeddings con FastEmbed y recupera contexto desde Qdrant.
7. Groq genera una respuesta con el contexto recuperado.
8. La API devuelve answer, route, sources y hits.
9. El frontend muestra la respuesta y guarda historial si Supabase esta disponible.

Docker

Ejecuta estos comandos desde la raiz del repositorio.

Backend API

docker build -f backend/Dockerfile.api -t rag-cars-api .
docker run --rm -p 8000:8000 --env-file .env rag-cars-api

Ingestion / Indexing

docker build -f ingestion/Dockerfile -t rag-cars-indexer .
docker run --rm --env-file .env rag-cars-indexer

Deploy del Frontend

El frontend es una aplicacion Next.js ubicada en frontend/. Para actualizar un deploy antiguo del frontend, revisa DEPLOY_NEXTJS.md.

Configuracion base:

• Framework preset: Next.js.
• Install command: npm install.
• Build command: npm run build.
• Start command, si la plataforma lo pide: npm run start.
• Output directory: no configurar manualmente en plataformas que detectan Next.js.

Estado del Proyecto

Estado actual:

• La API FastAPI expone endpoints de salud y chat.
• El frontend Next.js implementa landing, login, registro y chat.
• El pipeline de ingesta procesa PDFs y los indexa en Qdrant.
• Streamlit funciona como demo tecnica.
• Docker esta disponible para API e ingesta.

Trabajo pendiente recomendado:

• Agregar pruebas automatizadas.
• Versionar migraciones Supabase si el entorno requiere recrearlas.
• Consolidar observabilidad y manejo de errores.
• Completar archivos de infraestructura reproducible si aplica.
• Documentar el contrato completo de API.

Licencia

Licencia no especificada en el repositorio. Antes de publicar o distribuir este proyecto, agrega un archivo LICENSE con la licencia correspondiente.