clanker25/ai

Añadir un Paquete de Proveedor

Añade un paquete de primera parte @ai-sdk/<provider> completo que siga las interfaces de proveedor actuales, las convenciones del repositorio, los requisitos de seguridad y el proceso de lanzamiento.

Leer las Fuentes de Verdad Actuales

Antes de implementar cualquier cosa, lee:

• Añadir nuevo proveedor para los requisitos actuales del paquete y lanzamiento
• Notas de desarrollo de proveedores para nomenclatura, esquemas y serialización de flujos de trabajo
• Arquitectura de proveedor para la abstracción del proveedor
• Manejo seguro de URLs cuando el proveedor obtiene URLs de sondeo, imágenes, audio, video u otras URLs

Usa PR #18595 como un ejemplo reciente de extremo a extremo, pero elige el paquete de proveedor actual cuya forma de API y tipos de modelo se asemejen más al nuevo proveedor como referencia de implementación.

Terceras partes pueden publicar paquetes de proveedor fuera de este repositorio. Un nuevo paquete de primera parte @ai-sdk/<provider> requiere discusión previa en un issue. Confirma que existe acuerdo antes de implementar el paquete.

Descubrir el Contrato de API

Antes de diseñar clases de modelo, busca una especificación oficial, versionada de OpenAPI o Swagger en la documentación o repositorios del proveedor. Prefiere especificaciones de primera parte y registra la URL fuente junto con su versión, fecha de publicación o commit en las notas de implementación o pull request.

Usa la especificación y la documentación oficial para identificar:

• URLs base y esquemas de autenticación
• endpoints compatibles, tipos de modelo y capacidades
• parámetros de solicitud y formas de respuesta
• transportes de streaming y formatos de eventos
• envolturas de respuesta de error
• flujos de sondeo asíncrono y URLs de descarga

Trata una especificación OpenAPI como evidencia de implementación, no como verdad incuestionable. Las especificaciones a menudo están incompletas para eventos enviados por el servidor, deltas de streaming, contenido polimórfico, llamadas a herramientas, campos anulables y errores. No añadas un cliente generado o tipos de producción generados por defecto. Implementa tipos escritos a mano mínimos y esquemas Zod, luego verifícalos contra la documentación oficial y las respuestas de API capturadas.

Si no existe una especificación oficial, deriva el contrato de la documentación oficial y fixtures de respuesta reales, y nota esa limitación en el pull request.

Planificar la Forma del Proveedor

Determina qué interfaces de modelo del AI SDK soporta el proveedor, como LanguageModelV4, EmbeddingModelV4, ImageModelV4, SpeechModelV4, TranscriptionModelV4, RerankingModelV4 o Experimental_VideoModelV4.

Antes de introducir una dependencia, patrón de API pública o nueva abstracción, lee contributing/decisions/README.md y los ADRs aceptados relevantes. Prefiere utilidades de proveedor existentes y patrones de implementación.

Andamiar el Paquete

Crea packages/<provider>/ adaptando un paquete de proveedor comparable actual. Un paquete típico contiene:

packages/<provider>/
├── src/
│   ├── index.ts
│   ├── version.ts
│   ├── <provider>-provider.ts
│   ├── <provider>-provider.test.ts
│   ├── <provider>-<model-type>-model.ts
│   ├── <provider>-<model-type>-model.test.ts
│   └── <provider>-<model-type>-options.ts
├── CHANGELOG.md
├── README.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── vitest.edge.config.js

Preserva las convenciones actuales del paquete en lugar de recrear la configuración de memoria:

• Establece la versión del paquete del repositorio exactamente a 2.0.0, sin sufijo de prelanzamiento.
• Crea CHANGELOG.md con un encabezado inicial # @ai-sdk/<provider>.
• Usa la configuración compartida de tsdown y el patrón actual de inyección de versión de paquete de un paquete de proveedor comparable.
• Extiende ./node_modules/@vercel/ai-tsconfig/ts-library.json, habilita un proyecto compuesto, y añade referencias de paquete para dependencias del espacio de trabajo.
• Incluye los scripts estándar de build, clean, type-check, Node test y Edge test.
• Incluye los metadatos estándar de files, documentación prepack, repository, bugs, engines y public provenance publishing.
• Usa workspace:* para dependencias del espacio de trabajo del AI SDK. Añade @ai-sdk/test-server solo cuando las pruebas lo usen.
• Soporta el rango de dependencia de pares Zod 3 y Zod 4 del repositorio y usa zod/v4 para nuevos esquemas de implementación.

Ejecuta pnpm update-references después de añadir o cambiar dependencias del espacio de trabajo.

Implementar la Fábrica del Proveedor

Sigue el patrón actual de fábrica del proveedor:

• Define una interfaz de proveedor que extienda ProviderV4.
• Exporta create<Provider>(settings) y una instancia de proveedor por defecto.
• Haz que el proveedor sea invocable cuando tenga un tipo de modelo por defecto significativo y los proveedores comparables sigan ese patrón; de lo contrario, devuelve un objeto de proveedor.
• Establece provider.specificationVersion = 'v4'.
• Implementa los métodos de fábrica completamente especificados requeridos por ProviderV4, como languageModel, embeddingModel e imageModel.
• Añade alias cortos como chat, embedding o image solo cuando mejoren la API del proveedor.
• Lanza NoSuchModelError desde fábricas de modelos requeridos no soportados.
• Soporta configuraciones apropiadas para el proveedor como apiKey, baseURL, headers y una implementación fetch personalizada.
• Carga credenciales con loadApiKey o la utilidad compartida apropiada, normaliza URLs base configurables e incluye la versión del paquete en el sufijo user-agent.
• Exporta la fábrica del proveedor, la instancia por defecto, los tipos de opciones públicas, los tipos de ID de modelo y VERSION desde src/index.ts.

Implementar Clases de Modelo

Implementa cada modelo soportado usando la interfaz apropiada de @ai-sdk/provider y las utilidades compartidas de @ai-sdk/provider-utils.

Los tipos de opciones y esquemas del proveedor deben seguir las reglas de nomenclatura y exportación del repositorio. Los campos de opciones orientados al usuario deben usar .optional() a menos que null sea significativo. Los esquemas de respuesta deben ser mínimos, tolerar campos de proveedor no utilizados y usar .nullish() donde la API pueda omitir o devolver null.

Todas las clases de modelo deben implementar el contrato de serialización de flujo de trabajo descrito en Notas de desarrollo de proveedores:

• hacer que los encabezados de configuración del modelo sean opcionales
• añadir métodos estáticos WORKFLOW_SERIALIZE y WORKFLOW_DESERIALIZE
• usar serializeModel, serializeModelOptions o el patrón existente coincidente
• asegurar que la autenticación y otras funciones no serializables puedan restaurarse desde las opciones de solicitud o el entorno del flujo de trabajo

Manejar Respuestas, Errores y URLs de Forma Segura

• Nunca uses JSON.parse en código de producción. Usa parseJSON o safeParseJSON de @ai-sdk/provider-utils.
• Valida respuestas exitosas y fallidas con esquemas mínimos y manejadores de respuesta compartidos como createJsonResponseHandler y createJsonErrorResponseHandler.
• Introduce una subclase AISDKError personalizada solo cuando el paquete necesite un nuevo tipo de error de SDK público; los fallos HTTP de proveedor ordinarios deben usar el manejo de errores de API compartido.
• Establece validateUrl explícitamente en cada llamada a getFromApi.
• Usa validateUrl: true cuando el host o esquema de la URL provenga de una respuesta del proveedor, y false cuando se derive de una URL base configurada por el desarrollador.
• Usa trustedOrigin para URLs de respuesta legítimas que puedan apuntar a un endpoint privado o autohospedado configurado.
• Usa credentialedOrigin cuando las credenciales puedan enviarse en el primer salto, para que se retengan de URLs fuera de origen y redirecciones.

Lee Manejo seguro de URLs antes de implementar cualquier flujo de sondeo o URL de descarga proporcionada por el proveedor.

Probar Contra el Contrato Real

Añade pruebas enfocadas para:

• valores por defecto del proveedor, configuraciones personalizadas, alias de fábrica y tipos de modelo no soportados
• serialización de solicitudes y análisis de respuestas
• eventos de streaming, uso, razones de finalización, advertencias, llamadas a herramientas y metadatos del proveedor donde sea compatible
• análisis de respuestas de error y respuestas malformadas
• serialización y deserialización de flujo de trabajo
• decisiones de confianza de URL para sondeo o descargas
• tiempos de ejecución Node.js y Edge

Usa respuestas reales del proveedor como fixtures cuando sea práctico. Lee la habilidad de fixture de respuesta de API de captura antes de capturarlas. Recorta fixtures demasiado grandes solo cuando hacerlo no cambie su semántica.

Añadir Ejemplos e Integración del Repositorio

Lee la habilidad de ejemplo de AI Functions antes de añadir ejemplos.

Para cada tipo de modelo soportado, coloca el ejemplo de entrada en:

examples/ai-functions/src/<function>/<provider>/basic.ts

Coloca ejemplos adicionales en el mismo directorio del proveedor con nombres kebab-case.ts descriptivos. No crees archivos de proveedor planos como src/generate-text/<provider>.ts.

También actualiza los puntos de integración relevantes del repositorio:

• añade @ai-sdk/<provider> a examples/ai-functions/package.json
• añade su referencia de proyecto a examples/ai-functions/tsconfig.json
• añade las credenciales requeridas a examples/ai-functions/.env.example
• añade los nombres de las credenciales a la configuración de entorno raíz de turbo.json cuando sea necesario
• ejecuta pnpm update-references para actualizar las referencias de TypeScript raíz y del paquete

Ejecuta ejemplos representativos contra la API real y confirma el comportamiento tanto de no streaming como de streaming cuando sea compatible.

Añadir Documentación del Paquete y del Proveedor

• Escribe el README.md del paquete con instalación, autenticación, configuración, modelos soportados y uso básico.
• Añade content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx con configuración, capacidades del modelo, opciones del proveedor y ejemplos.
• Configura el script de documentación prepack del paquete para incluir esa página de proveedor.

Preparar el Lanzamiento

Crea un changeset mayor para el nuevo paquete de proveedor. El paquete del repositorio permanece en 2.0.0 simple; no añadas -beta, -canary u otro sufijo de prelanzamiento.

Antes del primer lanzamiento automatizado, coordina con el equipo de Vercel IT para iniciar un paquete @ai-sdk/<provider> vacío en npm en 0.0.0 y configurar su Trusted Publisher. Sigue Iniciando un nuevo paquete @ai-sdk/*. La versión de bootstrap npm temporal es separada de la versión del paquete del repositorio.

Cuando main esté en modo de prelanzamiento, no hagas backport del nuevo paquete a una rama vX.Y estable.

Verificar el Cambio Completo

Ejecuta, como mínimo:

pnpm --filter @ai-sdk/<provider> build
pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/<provider> type-check
pnpm type-check:full
pnpm check

También ejecuta los nuevos ejemplos con las credenciales de proveedor requeridas. Ejecuta la build raíz cuando los cambios en paquetes compartidos o la configuración de build lo hagan relevante.

Lista de Verificación de Finalización

• Paquete de primera parte aprobado en un issue
• Especificación OpenAPI oficial revisada, o su ausencia documentada
• Especificación de API verificada contra documentación y respuestas reales
• Implementación de proveedor comparable actual seleccionada
• Paquete del repositorio creado en la versión 2.0.0
• Paquete, TypeScript, build, test, procedencia y configuración de documentación añadidos
• Fábrica de proveedor implementa ProviderV4
• Clases de modelo compatibles y tipos de opciones públicas implementados
• Serialización de flujo de trabajo implementada para cada clase de modelo
• Análisis de respuestas, manejo de errores y obtención de URLs siguen las reglas de seguridad del repositorio
• Pruebas de Node y Edge pasan con fixtures de respuesta representativos
• Ejemplos anidados de AI Functions añadidos y ejecutados exitosamente
• Dependencias de ejemplo, referencias de TypeScript, variables de entorno y configuración de Turbo actualizadas
• README y documentación del proveedor añadidos
• Changeset mayor añadido
• Bootstrap de paquete npm y Trusted Publisher coordinado
• Build del paquete, pruebas, verificación de tipos completa y comprobaciones del repositorio pasan