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
+22 -1
View File
@@ -270,6 +270,27 @@ Memoria del proyecto entre sesiones para la rama `dev`.
- **Validación Automatizada**:
- 52/52 tests pasando en verde al 100% (`pytest tests -v`).
- **Sprint v3.5.7: Principio 11 de la Constitución — Estándares Modernos de APIs (FastAPI/Pydantic) e Integración con Modelos de IA (LLMs)**:
- **Arquitectura Modular en 4 Capas**:
- Desacople estricto: `main.py` (bootstrap/registro), `routers/` (endpoints agrupados por dominio con prefijos y tags para Swagger), `schemas/` (contratos con Pydantic `BaseModel`), `storage.py` (acceso a persistencia). Prohibida la lógica de negocio en el frontend o en archivos monolíticos.
- **Tipado Fuerte y Validación Pydantic**:
- Uso obligatorio de `Field` para validaciones declarativas (`min_length`, `max_length`, `gt`, `ge`, regex).
- Distinción estricta de Path Parameters (obligatorios) y Query Parameters (opcionales tipados con defaults).
- Manejo y respuesta automática de error `422 Unprocessable Entity` detallando el campo exacto.
- **Semántica HTTP y Excepciones Controladas**:
- Uso de códigos de estado HTTP semánticos (`201 Created` en POST, `200 OK`, `204 No Content`).
- Prohibido retornar `null` o respuestas vacías ante fallos: levantar `HTTPException` controladas con detalle descriptivo (404, 400, 409).
- **Documentación Interactiva Automática**:
- Contratos OpenAPI expuestos en `/docs` (Swagger UI) con capacidades de prueba en vivo (*Try it out*).
- **Integración Asíncrona con Modelos de IA Locales (LLMs) & Asistente Virtual**:
- **Pestaña en Configuración Global**: Planificada en `ROADMAP.md` y UI administrativa para configurar URL del servidor local (Ollama, llama.cpp), modelo, token y timeout para el futuro asistente virtual de la app.
- **Cliente Asíncrono no Bloqueante**: Uso mandatorio de `httpx.AsyncClient` con `async def` / `await` para inferencias concurrentes sin bloquear el servidor.
- **Timeout Generoso**: Configurar timeout de 600 segundos previendo carga de modelos en VRAM o prompts extensos.
- **Formato Estándar de Roles**: Historial estructurado bajo `role: "system" | "user" | "assistant"` y `content: prompt`.
- **Actualización Documental Completa**:
- Sincronizados `docs/constitution.md` (Principio 11), `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.opencode/agents/` (`coordinator.md`, `planner.md`, `implementer.md`, `reviewer.md`), `ROADMAP.md` (Fase 7) y `MEMORY.md`.
## Próximos pasos
1. Monitorear los inicios de sesión delegados en producción con cuentas docentes y estudiantiles.
2. Continuar con el roadmap hacia la Fase 6 de hardening y orquestación de servicios en Docker.
2. Implementar la pestaña de Asistente IA en la Configuración Global administrativa (`ROADMAP.md` Fase 7).
3. Continuar con el roadmap hacia la Fase 6 de hardening y orquestación de servicios en Docker.