Añade proveedores de IA y almacenes vectoriales a un framework modular de IA en Rust

## Cambia solo lo pedido y no hagas commit salvo que te lo pidan - Lee la implementación, los manifiestos, las pruebas y la documentación pública existentes antes de cambiar el código. - Mantén cada cambio dentro del alcance solicitado por el usuario. - Prefiere los traits, builders, módulos y tipos de error existentes frente a abstracciones paralelas. - No añadas TODO, stubs, comportamientos provisionales ni API públicas especulativas. - No hagas commits, prepares cambios, hagas push, crees ramas ni abras pull requests salvo que el usuario lo solicite explícitamente. - Conserva los cambios no relacionados del usuario y trabaja con seguridad alrededor de un árbol de trabajo sucio. - Evita refactorizaciones no relacionadas aunque un diseño cercano pueda mejorarse. - Distingue la política para colaboradores de las reglas de ingeniería propias del repositorio y cumple ambas. - Detente cuando falte la intención de producto necesaria o una autorización externa. ## Mantén coherentes los crates y los feature flags en todo el workspace - Mantén el crate de fachada pública, el crate central, las integraciones complementarias, las macros derive, los ejemplos y las pruebas en sus funciones establecidas. - Haz que la fachada reexporte las API centrales y exponga crates complementarios opcionales mediante feature flags. - Revisa el manifiesto del workspace y las exportaciones de la fachada antes de cambiar features públicas, integraciones o rutas de módulos. - Coloca las integraciones de proveedores y almacenes vectoriales en crates complementarios salvo que una razón arquitectónica sólida exija incluirlas en el núcleo. - Mantén separados los ejemplos del workspace, los ejemplos de cada crate y las pruebas de integración. - Al añadir un crate complementario, actualiza según corresponda la dependencia raíz, la feature, la reexportación de la fachada, los ejemplos, el README y la documentación del crate. - Asegúrate de que las combinaciones de features compilen sin exponer módulos no disponibles. - Mantén sincronizada la documentación pública entre la fachada y los crates complementarios afectados. - No describas una ruta de módulo ni una feature hasta que el código y los manifiestos la confirmen. ## Construye sobre los traits comunes en lugar de versiones por proveedor - Construye las integraciones sobre los traits centrales del framework para completado, embeddings, índices vectoriales y herramientas invocables. - No crees alternativas específicas de un proveedor para un trait existente que abarca varios proveedores. - Sigue el patrón de builder establecido para los tipos públicos configurables. - Mantén la construcción fluida y tipada, y complétala solo tras un paso de build explícito. - Usa una arquitectura de cliente genérica que separe las extensiones del proveedor del transporte HTTP subyacente. - Declara explícitamente las capacidades del proveedor para que los comportamientos no compatibles fallen durante la compilación. - Representa las capacidades ausentes mediante un tipo marcador deliberado, no mediante conjeturas en tiempo de ejecución. - Conserva las relaciones de tipos de API key entre los builders del proveedor y los aliases de cliente públicos. - Mantén los tipos de request y response propios del proveedor detrás de límites de conversión. ## Mantén el código asíncrono compartido funcionando en WebAssembly - Conserva la compatibilidad con WebAssembly en los traits, futures, errores e integraciones compartidos. - Usa las abstracciones de compatibilidad del framework en lugar de límites `Send` y `Sync` sin procesar cuando los targets difieran. - Usa el tipo boxed-future portable designado para los futures devueltos dinámicamente. - Aplica límites nativos de seguridad entre hilos solo en los targets que los admitan. - Mantén los errores boxed de WebAssembly libres de límites exclusivos de plataformas nativas que no sean compatibles. - Prueba las firmas de tipos nativas y las orientadas a WebAssembly después de cambiar traits compartidos. - Evita añadir una dependencia o API que excluya silenciosamente un target compatible. - Mantén la compilación condicional en un ámbito reducido y explica la diferencia entre targets. - Asegúrate de que las API de proveedores, almacenes vectoriales y hooks utilicen el mismo contrato de portabilidad. ## Usa tipos de error explícitos y documenta cada API pública nueva - No uses `String` como tipo de error para una nueva API falible. - Define enums de error explícitos y conserva los detalles útiles de las respuestas del proveedor mediante los helpers de error del framework. - Prefiere `?` y conversiones significativas frente a perder manualmente el contexto del error. - Usa `unwrap()` o `expect()` solo cuando la imposibilidad resulte evidente por la invariante circundante. - Añade documentación de elemento a cada nuevo tipo, función, trait y método públicos. - Añade documentación de módulo a cada nuevo módulo público. - Mantén los ejemplos alineados con las API reales, las constantes de modelos, las rutas de módulos y las feature flags. - Marca los ejemplos como no ejecutables cuando requieran credenciales o servicios externos. - Actualiza los archivos README y la documentación de nivel de crate siempre que cambie el comportamiento público. ## Añade un nuevo proveedor de IA siguiendo el más parecido que ya existe - Estudia el proveedor existente más parecido antes de implementar o modificar otro. - Añade los tipos de extensión y builder del proveedor, la implementación del proveedor y una declaración explícita de capacidades. - Admite la construcción desde valores del entorno y valores directos cuando el framework exponga ambas rutas. - Mantén los aliases públicos de cliente y builder coherentes con el tipo de API key del builder del proveedor. - Usa tipos explícitos de marcador de credencial o autenticación y oculta en debug los valores que contengan credenciales. - Convierte los requests del framework al formato real del proveedor y las responses de vuelta a los tipos del framework. - Añade streaming solo cuando el proveedor lo admita realmente y conserva los errores del proveedor mediante los helpers estándar. - Sigue las convenciones de telemetría y los traits de extensión establecidos. - No inventes campos de request o response que no existan en la API real del proveedor. - Añade pruebas o ejemplos enfocados que demuestren el comportamiento compatible. ## Integra un almacén vectorial con filtros reales y resultados de búsqueda claros - Coloca una integración de almacén vectorial en un crate complementario salvo que se justifique su pertenencia al núcleo. - Implementa tanto la búsqueda que devuelve resultados como la búsqueda que devuelve solo identificadores. - Usa un tipo de filtro que refleje las capacidades reales de filtrado del backend. - Devuelve las variantes de error del almacén vectorial del framework en lugar de errores de texto improvisados. - Aplica los mismos límites asíncronos portables que utiliza el framework central. - Mantén explícitas las conversiones de puntuación, documento, identificador y metadatos. - Define el orden, el límite, el resultado vacío y el comportamiento ante errores del backend. - Prueba los filtros, el orden de clasificación, los límites de resultados, los registros ausentes y los fallos de conversión. - Documenta las features, credenciales, índices y configuración externa necesarios sin incrustar secretos. ## Define las acciones permitidas para cada evento de hook - Modela los hooks como observadores y orientadores del ciclo de vida con alcance por ejecución. - Pasa un contexto de ejecución a cada evento, incluida la identidad de ejecución, el turno, el modo streaming, la identidad del agente y el estado temporal compartido. - Proporciona a cada evento su propio tipo de acción para que las combinaciones no compatibles fallen durante la compilación. - Permite que los hooks de llamada de completado modifiquen un request o detengan el procesamiento. - Permite que los hooks de llamada y resultado de herramientas reescriban valores para hooks posteriores, con skip o stop como acciones terminales donde se definan. - Representa la gestión de llamadas de herramienta no válidas mediante opciones explícitas de fail, retry, repair, skip y stop. - Limita los eventos de solo observación a continue o stop. - Registra los hooks de observación antes que los de orientación cuando las acciones stop cortocircuiten la pila. - Documenta qué acciones transforman datos, cuáles los acumulan y cuáles terminan el procesamiento. ## Combina los hooks apilados igual con y sin streaming - Conserva la semántica de composición específica de cada evento cuando los hooks estén anidados o apilados. - Fusiona las modificaciones de requests de completado en orden de registro. - Anexa contexto adicional, fusiona superficialmente los parámetros adicionales e interseca los conjuntos de herramientas activas. - Aplica el criterio de último escritor solo a los campos escalares e históricos documentados y avisa cuando una sobrescritura sea relevante. - Limita cada modificación de request a un turno; nunca permitas que persista por accidente. - Encadena las reescrituras de llamadas y resultados de herramientas en todos los hooks posteriores. - Deja de evaluar la pila inmediatamente cuando lo exija una acción terminal. - Haz que las superficies con streaming y sin streaming compartan el mismo controlador de ciclo de vida. - Prueba un comportamiento idéntico de los hooks mediante los puntos de entrada con streaming y sin streaming. - Añade pruebas de composición para pilas anidadas, conflictos de fusión, cadenas de reescritura, skip y stop. ## Elige la prueba de regresión más pequeña y usa cassettes grabados para las llamadas al proveedor - Añade cobertura de regresión en el ámbito fiable más pequeño. - Prefiere una prueba unitaria junto a la implementación para defectos aislados de conversión o lógica. - Usa pruebas de proveedor respaldadas por cassettes cuando el comportamiento dependa del tráfico de requests y responses del proveedor. - Usa pruebas live ignoradas solo cuando una reproducción determinista mediante cassette no pueda representar el comportamiento. - Lee la guía de pruebas del repositorio antes de añadir, actualizar, grabar o reproducir pruebas de proveedores. - Reproduce cassettes de forma predeterminada para que las pruebas normales no necesiten credenciales del proveedor. - Limita la ejecución de pruebas al proveedor y al comportamiento que se estén modificando. - Cubre el comportamiento con streaming y sin streaming cuando existan ambas superficies. - Conserva el modo de fallo original en la aserción de regresión. ## Graba cassettes solo para la prueba objetivo y revisa que no contengan secretos - Trata el modo de grabación como una operación externa, con credenciales y que sobrescribe archivos. - Exige la credencial correspondiente del proveedor antes de grabar y nunca la expongas en la salida. - Graba solo la prueba del proveedor objetivo para minimizar cambios no relacionados en los fixtures. - Inspecciona manualmente cada diff de cassette antes de presentarlo o hacer commit. - Rechaza fixtures que contengan API keys, credenciales bearer, cookies, identificadores de cuenta u otros valores sensibles. - Elimina los cambios no relacionados de requests y responses en lugar de aceptar un fixture ruidoso. - Mantén activadas las comprobaciones automáticas de limpieza y seguridad, pero no las trates como sustituto de la inspección. - Conserva datos de reproducción deterministas mientras ocultas secretos y metadatos inestables. - Nunca sobrescribas fixtures solo para hacer pasar una prueba fallida sin explicar el cambio de comportamiento. ## Ejecuta comprobaciones de menor a mayor alcance e informa lo que no se pudo verificar - Ejecuta primero las comprobaciones útiles más pequeñas y amplía después según el alcance y el riesgo afectados. - Formatea el workspace y ejecuta los lints en todos los targets y features afectados. - Ejecuta pruebas enfocadas antes que pruebas amplias del workspace. - Genera la documentación sin dependencias cuando cambien las API públicas o los documentos. - Verifica la compatibilidad nativa y con WebAssembly cuando cambien límites o futures compartidos. - Confirma que los campos del protocolo del proveedor coincidan con la API real y que los diffs de cassette no contengan secretos. - Confirma que la semántica de los hooks coincida en las superficies con streaming y sin streaming. - No declares la finalización mientras falle una comprobación obligatoria. - Si un comando no puede ejecutarse, explica por qué e indica exactamente qué queda sin verificar. - Informa de las superficies modificadas, las comprobaciones ejecutadas, los resultados observados, los riesgos residuales y el alcance excluido deliberadamente.