docs: formalizar Principio 11 - estandares modernos de APIs (FastAPI/Pydantic) e integracion asincrona con LLMs

This commit is contained in:
2026-10-16 17:04:21 -03:00
parent e1cc2d1212
commit 76647e228b
16 changed files with 115 additions and 16 deletions
+24 -1
View File
@@ -49,4 +49,27 @@ La asignación de reservas de aulas debe validar en tiempo real e impedir de for
### 10. Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`)
- **Prohibición de Cierre con Errores**: Es estrictamente inadmisible declarar una tarea, plan o sprint como "terminado", "completado" o "finalizado" si existen errores en el código, advertencias críticas de tipado, o problemas reportados por el analizador estático / terminal (`@[current_problems]`).
- **Remediación Mandatoria Previa**: Toda tarea se considera incompleta por definición hasta que el agente verifique activamente y repare al 100% todos los errores de sintaxis, imports, resolución de módulos, estrechamiento de tipos (type narrowing) y accesos a `NoneType`.
- **Quality Gate Infranqueable**: Ningún commit, bump de versión o despliegue a producción puede ser ejecutado mientras existan problemas o errores no resueltos en `@[current_problems]`.
- **Quality Gate Infranqueable**: Ningún commit, bump de versión o despliegue a producción puede ser ejecutado mientras existan problemas o errores no resueltos en `@[current_problems]`.
### 11. Estándares Modernos de APIs, Contratos Fuertes (FastAPI / Pydantic) e Integración con Modelos de IA (LLMs)
- **Arquitectura Modular y Separación de Responsabilidades**:
- Prohibido el código monolítico o ubicar lógica de negocio en el frontend o en archivos únicos de arranque.
- Estructuración estricta en 4 capas desacopladas:
1. **Entrada / Bootstrap (`main.py`)**: Inicialización de la aplicación y registro de routers.
2. **Rutas y Controladores (`routers/`)**: Agrupación de endpoints por dominio con prefijos (`prefix="/..."`) y etiquetas (`tags=["..."]`) para OpenAPI/Swagger limpio.
3. **Contratos y Validación (`schemas/` o `schemas.py`)**: Definición de esquemas de datos de entrada/salida mediante `pydantic.BaseModel`.
4. **Capa de Persistencia / Almacenamiento (`storage.py` / `models/`)**: Conexión a bases de datos y persistencia desacoplada.
- **Tipado Fuerte y Contratos con Pydantic**:
- Toda entrada (Body) debe heredar de `BaseModel` con validaciones explícitas usando `Field` (`min_length`, `max_length`, `gt`, `ge`, regex).
- Manejo diferenciado de parámetros: Path Parameters (obligatorios en la URL) y Query Parameters (opcionales con valores tipados por defecto).
- Manejo de errores de validación automático (422 Unprocessable Entity con detalle preciso del atributo).
- **Semántica HTTP y Excepciones Controladas**:
- Uso estricto de códigos HTTP: `201 Created` para creación vía POST, `200 OK` para consultas/actualizaciones, `204 No Content` para borrados sin cuerpo.
- Prohibido retornar valores nulos (`null`) o respuestas vacías ante fallos lógicos: siempre levantar excepciones controladas (`HTTPException`) con código de estado semántico (ej. `404 Not Found` con `detail="Recurso no encontrado"`, `400 Bad Request`, `409 Conflict`).
- **Documentación Interactiva Automática**:
- Los contratos de API deben exponerse de forma nativa vía Swagger UI (`/docs`), permitiendo pruebas interactivas en vivo (*Try it out*) y visualización de esquemas.
- **Integración Asíncrona con Modelos de Lenguaje (LLMs) y Asistente en la App**:
- **Pestaña en Configuración Global**: La aplicación debe disponer en su configuración global de una pestaña dedicada a la configuración del Asistente de IA (URL del proveedor/servidor local, modelo, timeout, token y activación).
- **Cliente HTTP Asíncrono no Bloqueante**: Utilizar exclusivamente clientes asíncronos (`httpx.AsyncClient` con `async def` y `await`) para conectar con motores de inferencia locales (Ollama, llama.cpp, vLLM) o externos sin bloquear el bucle de eventos ni los hilos del servidor.
- **Configuración de Timeouts Generosos**: Configurar tiempos de espera adecuados para LLMs (ej. timeout por defecto de 600 segundos para dar soporte a inferencias locales en GPU/VRAM compartida).
- **Formato Estándar de Roles**: Toda comunicación con modelos de lenguaje debe emplear el estándar de historial estructurado por roles (`{"role": "system" | "user" | "assistant", "content": "..."}`).