Requisitos del adaptador

Propósito Este documento establece los requisitos normativos para adaptadores compatibles con FACET. Los adaptadores son la única capa autorizada para traducir Canonical JSON a las cargas útiles específicas de proveedores como OpenAI, Anthropic, Gemini o entornos locales. Su función es mapear, no interpretar, corregir, enriquecer ni redecidir comportamientos. Los adaptadores son traductores, no colaboradores.

Principio básico Los adaptadores DEBEN ser pasivos en cuanto a comportamiento. No deben introducir lógica nueva, inferir datos faltantes, reordenar la semántica de ejecución, aplicar heurísticas específicas del proveedor de forma silenciosa ni recuperarse de estados inválidos. Toda inteligencia, validación y determinismo corresponde a las capas por encima del adaptador.

Posición arquitectónica FACET impone una arquitectura por capas: documento .facet, AST tipado, R-DAG de ejecución, Token Box Model, Canonical JSON, adaptador proveedor, payload del proveedor. Los adaptadores actúan exclusivamente sobre Canonical JSON y no deben aceptar entradas parcialmente compiladas o con forma de proveedor.

Propiedades obligatorias de los adaptadores 1 Determinismo mapeo determinista Dada una misma entrada Canonical JSON la salida del adaptador debe ser idéntica byte por byte El mapeo debe ser puro y sin estado sin aleatoriedad ni acceso a relojes o I O Los adaptadores deben comportarse como funciones referencialmente transparentes salida igual a adaptador(canonical_json)

2 No reparación semántica Los adaptadores no pueden intentar reparar restricciones del proveedor modificando la semántica Comportamientos prohibidos incluyen renombrar herramientas para ajustarse a mayúsculas del proveedor inyectar campos faltantes reordenar mensajes para reglas no documentadas dividir o fusionar llamadas a herramientas Si Canonical JSON viola una restricción del proveedor el adaptador debe fallar de forma visible la recuperación silenciosa se considera corrupción

3 Restricciones del proveedor como entradas declarativas Todas las restricciones específicas del proveedor deben declararse aguas arriba durante la compilación Ejemplos orden obligatorio de llamadas a herramientas restricciones de serialización limitaciones de streaming reglas de mayúsculas en nombres de herramientas Los adaptadores solo pueden aplicar restricciones ya resueltas en Canonical JSON No deben descubrir ni inferir restricciones dinámicamente La elección del proveedor debe ser una decisión explícita de compilación por ejemplo target=gemini o profile=strict_chat y el adaptador no debe compensar selecciones de destino incorrectas

4 Mapeo estructural uno a uno Los adaptadores deben preservar la estructura una herramienta canónica equivale a una definición de herramienta del proveedor un mensaje canónico equivale a un mensaje del proveedor los campos nulos explícitos deben permanecer explícitos Los adaptadores no deben colapsar varios mensajes expandir mensajes únicos ni eliminar campos vacíos o nulos

5 Contención de fallos El adaptador debe actuar como límite de fallo Si un proveedor rechaza una carga cambia comportamiento sin documentar o introduce breaking changes el fallo debe presentarse como un error del adaptador no debe mutar Canonical JSON ni contaminar cachés o historial Canonical JSON debe permanecer válido y reproducible

Prohibiciones explícitas Los adaptadores deben ser seguros para ejecutarse en entornos zero trust No deben realizar validación (ya realizada por el compilador) ni ejecutar comprobaciones de tipos ejecutar lentes invocar LLMs o agentes IA obtener recursos externos ni acceder a sistema de ficheros o red Los adaptadores no son motores de ejecución

Requisitos de versionado Los adaptadores deben declarar las versiones de Canonical JSON compatibles fallar en versiones incompatibles y ser por defecto no compatibles hacia adelante Esto evita interpretaciones silenciosas de contratos más nuevos

Requisitos de pruebas Todo adaptador debe incluir pruebas golden con Canonical JSON de entrada y snapshot exacto de la carga del proveedor pruebas negativas que muestren fallos deterministas ante Canonical JSON inválido y seguridad en round trip la salida del adaptador no debe afectar los hashes de reproducción canonical Las pruebas de snapshot deben ser estables entre entornos

Relación con la reproducibilidad Los adaptadores no deben comprometer las garantías de reproducibilidad que dependen exclusivamente del documento FACET entradas del documento modo de ejecución y Canonical JSON Los adaptadores quedan excluidos del contrato de reproducibilidad y son reemplazables

Razonamiento de diseño Las limitaciones intencionadas en los adaptadores persiguen prevenir vendor lock in localizar el churn de API habilitar la reproducción y auditoría a largo plazo y mantener al compilador como autoridad Cuando se permite que los adaptadores 'ayuden' el determinismo se rompe

Resumen Los adaptadores existen para responder a una sola pregunta como se expresa este Canonical JSON en el dialecto de este proveedor Cualquier función más allá de esa traducción viola el contrato

Estado Este documento define requisitos normativos para adaptadores compatibles con FACET Cualquier adaptador que viole estas reglas es no conforme por diseño

Acerca de Q2BSTUDIO Q2BSTUDIO es una empresa de desarrollo de software especializada en aplicaciones a medida y software a medida con amplia experiencia en inteligencia artificial y ciberseguridad Ofrecemos servicios de integración de inteligencia artificial para empresas y diseño de agentes IA además de soluciones de servicios cloud aws y azure mediante arquitecturas seguras y escalables Descubra también nuestras capacidades de desarrollo de aplicaciones con enfoque multicanal en aplicaciones a medida y software a medida y cómo apoyamos proyectos de servicios inteligencia de negocio con Power BI

Palabras clave aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws y azure servicios inteligencia de negocio ia para empresas agentes IA power bi