Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/geremyjampiersalasgarcia-eng/Caso_Practico_Semillero_IA/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through a complete local deployment of Mesa de Ayuda IA — from cloning the repository to chatting with all five AI agents in your browser. Follow the steps in order and you should have a fully working system in approximately 10 minutes.
Start-up order is strict. The services must be started in the exact sequence described below. Starting the backend before Docker is ready, or skipping the ingestion step, will cause connection errors or a "collection not found" error from ChromaDB. Do not skip or reorder the steps.

​
Steps

1

Clone the repository

Clone the project from GitHub and enter the root directory:
git clone https://github.com/geremyjampiersalasgarcia-eng/Caso_Practico_Semillero_IA.git
cd Caso_Practico_Semillero_IA
2

Get a Google Gemini API Key

All LLM inference and embedding generation use Google Gemini, which requires an API key. The free tier is sufficient for local development.
  1. Go to https://aistudio.google.com/apikey
  2. Sign in with a Google account
  3. Click Create API key and copy the generated key
Keep this key handy — you will paste it into the .env file in the next step.
3

Configure environment variables

Copy the provided template and open the new file for editing:
cd backend
cp .env.example .env
# Windows: copy .env.example .env
Open backend/.env and fill in your values. The critical fields are shown below:
# --- Google Gemini API ---
GOOGLE_API_KEY=your_api_key_here

# --- LLM Configuration ---
LLM_MODEL_NAME=gemini-flash-lite-latest
EMBEDDING_MODEL_NAME=models/gemini-embedding-001
LLM_TEMPERATURE=0.1

# --- ChromaDB ---
CHROMA_PERSIST_DIR=data/chroma_db

# --- RAG Configuration ---
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
RETRIEVAL_TOP_K=4

# --- Database (PostgreSQL via Docker) ---
DATABASE_URL=postgresql://mesa_ayuda_user:[email protected]:5433/mesa_ayuda_db
The .env file is listed in .gitignore — your API key will never be committed to version control.
4

Start PostgreSQL and Phoenix with Docker

From the project root directory (not inside backend/ or frontend/), start the database and observability containers:
# Run from Caso_Practico_Semillero_IA/ (the root)
docker-compose up -d postgres phoenix
Wait until both containers are Healthy, not just Running. You can check status with:
docker ps
PostgreSQL has a built-in health check (pg_isready) that confirms it is accepting connections. Allow 5–10 seconds after the up command before proceeding.
5

Install Python dependencies and start the backend

Create a virtual environment, install all dependencies, and launch the FastAPI server:
cd backend

# Create and activate virtual environment
python -m venv venv

# Activate (Linux / macOS)
source venv/bin/activate

# Activate (Windows)
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the backend server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
On first start, SQLAlchemy automatically creates all required tables in PostgreSQL — no manual migrations needed. You will see log lines confirming this:
Iniciando aplicación. Creando tablas en base de datos si no existen...
Registrando agentes del sistema...
Aplicación iniciada correctamente
The following tables are created automatically:
TableDescription
conversationsChat session history (IDs and auto-generated titles)
messagesIndividual messages, RAG sources, and Base64 image attachments
oportunidadesCRM opportunity records written by the Action Agent
audit_logsPer-request telemetry: intent, agents invoked, latency
Leave this terminal running. Open a new terminal for the next step.
6

Ingest documents into ChromaDB

In a new terminal (with the backend still running in the previous one), run the ingestion script from the backend/ directory:
cd backend

# Activate your virtual environment if not already active
source venv/bin/activate   # Linux/macOS
# .\venv\Scripts\activate  # Windows

python scripts/ingest.py
This script reads the three knowledge-base documents from data/raw/, splits them into chunks, generates embeddings via Gemini, and stores each document in its own ChromaDB collection:
DocumentChromaDB Collection
01_Catalogo_Productos_Precios.txtcol_catalogo
02_Politicas_Comerciales_Descuentos_Credito.txtcol_politicas
03_Proceso_Ventas_CRM.txtcol_proceso_ventas
The script clears existing collections before re-indexing, so you can safely re-run it if you update the source documents.
7

Start the frontend

In a third terminal, install Node.js dependencies and start the Next.js development server:
cd frontend
npm install
npm run dev
Open http://localhost:3000 in your browser. You should see the Mesa de Ayuda IA chat interface ready to use.

​
Active services

Once all steps are complete, the following services are running:
ServiceURLDescription
Backend APIhttp://localhost:8000/docsInteractive Swagger UI for all REST endpoints
Frontend UIhttp://localhost:3000Next.js chat interface
Phoenix Observabilityhttp://localhost:6006LangGraph traces, token usage, and per-agent latency
PostgreSQLlocalhost:5433Database (accessible via any PostgreSQL client)
Gemini free-tier rate limit: The free tier of Google AI Studio allows 15 requests per minute (RPM). Because LangGraph fires multiple Gemini API calls per user question (classification → routing → one or more agent responses → consolidation), you can hit this limit quickly. If you see an HTTP 429 error, simply wait 10–15 seconds before sending your next question. This is expected behavior on the free tier.

Build docs developers (and LLMs) love

Get started for freeTalk to us