# Qualidot AI Gateway - FastAPI Template

## Metadatos

- **Autor:** Alan Ivan Sánchez Gómez  
- **Revisor:** Francisco Pineda
- **Proyecto:** Qualidot
- **Versión:** 1.0
- **Fecha de creación:** 12/03/2026
- **Última actualización:** 14/03/2026
- **Lenguaje:** Python 3.12+
- **Tipo:** Microservicio  
- **Dominio:** IA / NLP / Audio / Visión / Multimodal  
- **Estado:** Desarrollo (MVP Funcional)

---

## Descripción General

Este microservicio es una **Template de FastAPI** diseñada para el consumo de modelos de IA (OpenAI, AssemblyAI, etc.). Su característica principal es la **homologación de respuestas**: sin importar el proveedor utilizado, el cliente siempre recibe los resultados en un formato estándar de Qualidot.

---

## Objetivo

- **Estandarización:** Proveer una base sólida para integrar nuevos modelos de IA rápidamente.
- **Evaluación:** Facilitar el testing de modelos mediante Postman con una estructura de datos predecible.
- **Escalabilidad:** Separar la lógica de negocio de los proveedores externos mediante el uso de adaptadores.

---

## Cambios a Implementar

- Agregar endpoints para procesamiento de texto, imagen y video.
- Mejorar la gestión de errores y mensajes de validación.
- Implementar autenticación y autorización (JWT o API Key).
- Añadir pruebas unitarias y de integración.
- Optimizar el manejo de archivos temporales y recursos.
- Agregar ejemplos de uso y scripts de automatización para testing.

---

## Arquitectura / Flujo

Entrada (Postman/Client)
     ↓
Validación (Check de extensión y peso del archivo)
     ↓
Preprocesamiento (Creación de archivos temporales / Seek(0))
     ↓
Modelo(s) IA (Adaptadores de OpenAI, AssemblyAI, etc.)
     ↓
Postprocesamiento (Mapeo a esquema homologado StandardTranscriptionResult)
     ↓
Salida (Respuesta JSON estandarizada)

## Estructura del proyecto
Para mantener el orden y evitar errores de importación circular, el proyecto se organiza de la siguiente manera:

fastApiTemplate/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── endpoints/      # Definición de rutas y routers
│   │           ├── audio/      # Endpoints específicos de procesamiento de audio
│   │           ├── image/      # (Pendiente) Procesamiento de visión
│   │           ├── video/      # (Pendiente) Procesamiento de video
│   │           └── router.py   # Router maestro que unifica los módulos
│   ├── core/
│   │   └── config.py           # Configuración central (Settings y Pydantic-settings)
│   ├── schemas/                # Contratos de datos (Pydantic Models)
│   ├── services/               # Adaptadores y lógica con proveedores de IA
│   ├── utilities/              # Helpers (Validaciones, conversiones de audio)
│   └── main.py                 # Punto de entrada de la aplicación
├── .env                        # Credenciales y API Keys (No trackeado en Git)
├── requirements.txt            # Dependencias del proyecto
└── docs.md                     # Documentación técnica