Paso 2.2 - Microservicio de IA (Python + FastAPI)

Objetivo: Crear una API en FastAPI que procese tickets usando un LLM via LangChain/Hugging Face, devuelva categoria y sentimiento en JSON, y actualice la fila en Supabase como processed: true.

Paso a paso

Crear el proyecto Python y el entorno virtual.
Detalle del paso 1:
1. Ubicate en la carpeta /python-api del repositorio.
2. Crear el entorno virtual:
```
python -m venv .venv
```
3. Activar el entorno virtual en PowerShell:
```
.\.venv\Scripts\Activate.ps1
```

Instalar dependencias basicas:

pip install fastapi uvicorn langchain supabase python-dotenv

Configurar variables de entorno:

SUPABASE_URL=...
SUPABASE_KEY=...
HUGGINGFACEHUB_API_TOKEN=...

Definir el endpoint POST /process-ticket que reciba el texto del ticket y un identificador de fila.
Detalle del endpoint:
1. Define un esquema de entrada con id y description.
2. Texto del ticket (description) esperado:
  - Debe ser un texto natural con el detalle del problema o solicitud.
  - Debe tener al menos 10 caracteres y no estar vacio.
  - Ejemplo: "No puedo iniciar sesion desde ayer, me da error 500."
3. Agrega la ruta en FastAPI:
```
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class TicketIn(BaseModel):
  id: str
  description: str

@app.post("/process-ticket")
def process_ticket(payload: TicketIn):
  return {"id": payload.id, "description": payload.description}
```
4. Valida que description no este vacia y retorna error 400 si falta.

Usar LangChain + Hugging Face para extraer category y sentiment en formato JSON.

Detalle del paso (extraccion con LLM):

Define un prompt que pida respuesta estricta en JSON con category y sentiment.
Configura el LLM de Hugging Face en LangChain.
Ejecuta el prompt con el texto del ticket y parsea el JSON.

from langchain.prompts import PromptTemplate
from langchain_community.llms import HuggingFaceHub

prompt = PromptTemplate(
  input_variables=["ticket"],
  template=(
    "Clasifica el ticket en JSON con keys category y sentiment. "
    "Solo JSON. Ticket: {ticket}"
  )
)

llm = HuggingFaceHub(repo_id="google/flan-t5-base")
result = llm(prompt.format(ticket=description))

Actualizar el registro en Supabase con los nuevos campos y processed: true.
Detalle del paso (actualizacion en Supabase):
1. Instancia el cliente de Supabase con URL y KEY.
2. Actualiza la fila por id con los campos category, sentiment y processed.
3. Verifica la respuesta y maneja errores si la actualizacion falla.
```
from supabase import create_client

supabase = create_client(SUPABASE_URL, SUPABASE_KEY)

data = {
  "category": category,
  "sentiment": sentiment,
  "processed": True
}

result = supabase.table("tickets").update(data).eq("id", ticket_id).execute()
```
Exponer la API y desplegarla en Render/Vercel/Railway.

Especificaciones tecnicas

Framework: FastAPI.
LLM: via LangChain usando un proveedor de Hugging Face.
Entrada: texto del ticket (y opcionalmente id de la fila).
Salida: JSON estructurado con categoria y sentimiento.
Persistencia: actualizacion en Supabase (processed = true).
Despliegue: URL publica en Render.com, Vercel o Railway.app.

Ejemplo de payload

{
  "id": "uuid-del-ticket",
  "description": "No puedo acceder a mi cuenta..."
}

Ejemplos de textos de ticket

"No puedo iniciar sesion desde ayer, el sistema muestra error 500."
"Me cobraron dos veces la suscripcion de este mes, necesito un reembolso."
"Quiero informacion sobre el plan empresarial y tiempos de implementacion."

Comparativa: LangChain + Hugging Face vs OpenAI API

Criterio	LangChain + Hugging Face	OpenAI API
Disponibilidad 🌍	Modelos abiertos y privados en Hub	Acceso via API con cuenta
Costos 💰	Puede ser gratuito con limites	Pago por uso
Calidad 📈	Depende del modelo elegido	Alta consistencia en clasificacion
Control 🛠️	Mayor control del modelo	Servicio gestionado
Latencia ⏱️	Variable segun proveedor	Generalmente estable
Privacidad 🔒	Opciones de despliegue propio	Datos pasan por API externa
Facilidad ⚡	Mas configuracion inicial	Integracion directa
Escalabilidad 🚀	Depende del hosting	Alta escalabilidad gestionada

Por que elegir LangChain + Hugging Face

Necesitas modelos abiertos o auto-hospedados.
Buscas mas control sobre el modelo y el despliegue.
Prefieres optimizar costos con opciones gratuitas o mixtas.

Por que elegir OpenAI API

Quieres alta calidad y consistencia con poca configuracion.
Necesitas velocidad de implementacion y mantenimiento minimo.
Prefieres un servicio gestionado y escalable.

Glosario de terminos

#	Termino	Definicion
1	Endpoint	Un endpoint es una ruta expuesta por una API para recibir solicitudes HTTP. En practicas de la industria se describe con contratos REST usando metodos como POST y codigos de respuesta estandar (200, 400, 500). Debe documentarse con OpenAPI/Swagger, incluir validacion de payload, autenticar cuando aplique y responder en JSON consistente. En este proyecto, POST /process-ticket recibe id y description y devuelve la salida estructurada.
2	LLM	LLM significa Large Language Model, un modelo entrenado para comprender y generar texto. En la industria se usa para clasificacion, extraccion y resumen, con practicas de control como prompts estrictos, validacion de salida y limites de tokens. Se recomienda registrar el modelo, version, proveedor y parametros para trazabilidad. En este caso el LLM analiza el ticket y devuelve category y sentiment en JSON.
3	Prompt	Un prompt es la instruccion textual que guia al modelo para producir una salida especifica. En estandares de la industria se redacta de forma clara, con formato esperado, ejemplos y restricciones como “solo JSON”. Tambien se aplican tecnicas de prompt engineering y validacion posterior para reducir alucinaciones. Para este microservicio, el prompt exige keys category y sentiment y evita texto extra.
4	RLS	RLS es Row Level Security, un mecanismo de Postgres para aplicar politicas por fila. En practicas empresariales se define con reglas explícitas de lectura y escritura, usando roles y claims de autenticacion. Permite exponer datos por API minimizando riesgos y cumpliendo principios de minimo privilegio. En Supabase, RLS se habilita por tabla y se acompana de politicas que permiten solo las operaciones necesarias.
5	Supabase	Supabase es una plataforma backend con Postgres administrado, autenticacion, almacenamiento y APIs REST/Realtime. En estandares de la industria se utiliza para acelerar prototipos manteniendo buenas practicas de seguridad, como uso de service keys en backend y anon keys en frontend. Para este proyecto, Supabase almacena la tabla tickets, soporta actualizaciones y habilita realtime para el dashboard.
6	LangChain	LangChain es un framework para orquestar LLMs, prompts y cadenas de procesamiento. En el estandar de la industria se usa para modularizar prompts, manejar memoria, parsear salidas y conectar herramientas. Facilita mantener trazabilidad del prompt y separar la logica del proveedor de modelo. En este flujo, LangChain ayuda a construir el prompt JSON y a invocar el modelo de Hugging Face de forma consistente.
7	Hugging Face	Hugging Face es un hub de modelos y una plataforma para ejecutar inferencia. En la industria se usa para acceder a modelos abiertos, comparar rendimiento y desplegar endpoints. Permite seleccionar modelos adecuados segun costo, latencia y calidad. Para este microservicio, se usa un modelo compatible con LangChain, con token de API y limites definidos, devolviendo la clasificacion en formato JSON.

Ejemplo de respuesta

{
  "category": "Tecnico",
  "sentiment": "Negativo",
  "processed": true
}

Entregable: URL publica de la API y codigo fuente dentro de /python-api.

Volver al indice