clanker25/ai

Adicionar um Pacote de Provedor

Adicione um pacote completo de primeira parte @ai-sdk/<provider> que segue as interfaces atuais do provedor, as convenções do repositório, os requisitos de segurança e o processo de lançamento.

Leia as Fontes de Verdade Atuais

Antes de implementar qualquer coisa, leia:

• Adicionar novo provedor para requisitos atuais de pacote e lançamento
• Notas de desenvolvimento do provedor para nomenclatura, schemas e serialização de workflow
• Arquitetura do provedor para a abstração do provedor
• Manipulação segura de URLs quando o provedor busca polling, imagem, áudio, vídeo ou outras URLs

Use PR #18595 como um exemplo ponta a ponta recente, mas escolha o pacote de provedor atual cuja forma de API e tipos de modelo mais se assemelham ao novo provedor como referência de implementação.

Terceiros podem publicar pacotes de provedor fora deste repositório. Um novo pacote de primeira parte @ai-sdk/<provider> requer discussão prévia em uma issue. Confirme que existe concordância antes de implementar o pacote.

Descubra o Contrato da API

Antes de projetar classes de modelo, procure uma especificação oficial, versionada (OpenAPI ou Swagger) na documentação ou repositórios do provedor. Prefira especificações de primeira parte e registre a URL de origem, sua versão, data de publicação ou commit nas notas de implementação ou pull request.

Use a especificação e a documentação oficial para identificar:

• URLs base e esquemas de autenticação
• endpoints suportados, tipos de modelo e capacidades
• parâmetros de requisição e formas de resposta
• transportes de streaming e formatos de evento
• envelopes de resposta de erro
• fluxos de polling assíncrono e URL de download

Trate uma especificação OpenAPI como evidência de implementação, não como verdade inquestionável. Especificações são frequentemente incompletas para server-sent events, deltas de streaming, conteúdo polimórfico, chamadas de ferramenta, campos anuláveis e erros. Não adicione um cliente gerado ou tipos de produção gerados por padrão. Implemente tipos mínimos escritos à mão e schemas Zod, em seguida, verifique-os contra a documentação oficial e respostas de API capturadas.

Se nenhuma especificação oficial existir, derive o contrato da documentação oficial e de fixtures de resposta reais, e observe essa limitação no pull request.

Planeje a Forma do Provedor

Determine quais interfaces de modelo do AI SDK o provedor suporta, como LanguageModelV4, EmbeddingModelV4, ImageModelV4, SpeechModelV4, TranscriptionModelV4, RerankingModelV4 ou Experimental_VideoModelV4.

Antes de introduzir uma dependência, padrão de API pública ou nova abstração, leia contributing/decisions/README.md e ADRs aceitos relevantes. Prefira utilitários de provedor existentes e padrões de implementação.

Estruture o Pacote

Crie packages/<provider>/ adaptando um pacote de provedor atual e comparável. Um pacote típico contém:

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

Preserve as convenções atuais do pacote em vez de recriar a configuração da memória:

• Defina a versão do pacote do repositório exatamente como 2.0.0, sem sufixo de pré-lançamento.
• Crie CHANGELOG.md com um cabeçalho inicial # @ai-sdk/<provider>.
• Use a configuração tsdown compartilhada e o padrão de injeção de versão de pacote atual de um pacote de provedor comparável.
• Estenda ./node_modules/@vercel/ai-tsconfig/ts-library.json, ative um projeto composto e adicione referências de pacote para dependências do workspace.
• Inclua os scripts padrão de build, limpeza, type-check, teste Node e teste Edge.
• Inclua os metadados padrão de files, documentação prepack, repositório, bugs, engines e publicação de proveniência pública.
• Use workspace:* para dependências do workspace do AI SDK. Adicione @ai-sdk/test-server apenas quando os testes o utilizarem.
• Suporte ao intervalo de dependência peer do Zod 3 e Zod 4 do repositório e use zod/v4 para novos schemas de implementação.

Execute pnpm update-references após adicionar ou alterar dependências do workspace.

Implemente a Fábrica do Provedor

Siga o padrão atual de fábrica do provedor:

• Defina uma interface de provedor que estenda ProviderV4.
• Exporte create<Provider>(settings) e uma instância de provedor padrão.
• Torne o provedor chamável quando ele tiver um tipo de modelo padrão significativo e provedores comparáveis seguirem esse padrão; caso contrário, retorne um objeto de provedor.
• Defina provider.specificationVersion = 'v4'.
• Implemente os métodos de fábrica totalmente especificados exigidos por ProviderV4, como languageModel, embeddingModel e imageModel.
• Adicione aliases curtos como chat, embedding ou image apenas quando eles melhorarem a API do provedor.
• Lance NoSuchModelError em fábricas de modelo obrigatório não suportado.
• Suporte a configurações apropriadas ao provedor, como apiKey, baseURL, headers e uma implementação fetch personalizada.
• Carregue credenciais com loadApiKey ou o utilitário compartilhado apropriado, normalize URLs base configuráveis e inclua a versão do pacote no sufixo user-agent.
• Exporte a fábrica do provedor, a instância padrão, os tipos de opção pública, os tipos de ID de modelo e VERSION de src/index.ts.

Implemente Classes de Modelo

Implemente cada modelo suportado usando a interface apropriada de @ai-sdk/provider e utilitários compartilhados de @ai-sdk/provider-utils.

Os tipos e schemas de opção do provedor devem seguir as regras de nomenclatura e exportação do repositório. Campos de opção voltados ao usuário devem usar .optional() a menos que null seja significativo. Schemas de resposta devem ser mínimos, tolerar campos de provedor não utilizados e usar .nullish() onde a API pode omitir ou retornar null.

Todas as classes de modelo devem implementar o contrato de serialização de workflow descrito em Notas de desenvolvimento do provedor:

• torne os cabeçalhos de configuração do modelo opcionais
• adicione métodos estáticos WORKFLOW_SERIALIZE e WORKFLOW_DESERIALIZE
• use serializeModel, serializeModelOptions ou o padrão existente correspondente
• garanta que a autenticação e outras funções não serializáveis possam ser restauradas a partir das opções de requisição ou do ambiente do workflow

Manipule Respostas, Erros e URLs com Segurança

• Nunca use JSON.parse em código de produção. Use parseJSON ou safeParseJSON de @ai-sdk/provider-utils.
• Valide respostas bem-sucedidas e com falha com schemas mínimos e manipuladores de resposta compartilhados, como createJsonResponseHandler e createJsonErrorResponseHandler.
• Introduza uma subclasse AISDKError personalizada apenas quando o pacote precisar de um novo tipo de erro público do SDK; falhas HTTP comuns do provedor devem usar o tratamento de erro de API compartilhado.
• Defina validateUrl explicitamente em cada chamada getFromApi.
• Use validateUrl: true quando o host ou esquema da URL vier de uma resposta do provedor, e false quando for derivado de uma URL base configurada pelo desenvolvedor.
• Use trustedOrigin para URLs de resposta legítimas que podem apontar para um endpoint privado ou auto-hospedado configurado.
• Use credentialedOrigin quando as credenciais podem ser enviadas no primeiro salto, para que sejam retidas de URLs fora da origem e redirecionamentos.

Leia Manipulação segura de URLs antes de implementar qualquer fluxo de polling ou URL de download fornecida pelo provedor.

Teste Contra o Contrato Real

Adicione testes focados para:

• padrões do provedor, configurações personalizadas, aliases de fábrica e tipos de modelo não suportados
• serialização de requisição e parsing de resposta
• eventos de streaming, uso, motivos de finalização, avisos, chamadas de ferramenta e metadados do provedor onde suportado
• parsing de resposta de erro e respostas malformadas
• serialização e desserialização de workflow
• decisões de confiança de URL para polling ou downloads
• runtimes Node.js e Edge

Use respostas reais do provedor como fixtures quando prático. Leia a skill de fixture de resposta de API de captura antes de capturá-las. Apare fixtures superdimensionadas apenas quando isso não alterar sua semântica.

Adicione Exemplos e Integração com o Repositório

Leia a skill de exemplo de AI Functions antes de adicionar exemplos.

Para cada tipo de modelo suportado, coloque o exemplo de entrada em:

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

Coloque exemplos adicionais no mesmo diretório do provedor com nomes descritivos em kebab-case.ts. Não crie arquivos de provedor planos como src/generate-text/<provider>.ts.

Atualize também os pontos de integração relevantes do repositório:

• adicione @ai-sdk/<provider> a examples/ai-functions/package.json
• adicione sua referência de projeto a examples/ai-functions/tsconfig.json
• adicione as credenciais necessárias a examples/ai-functions/.env.example
• adicione nomes de credenciais à configuração de ambiente raiz turbo.json quando necessário
• execute pnpm update-references para atualizar as referências TypeScript da raiz e do pacote

Execute exemplos representativos contra a API real e confirme o comportamento de streaming e não streaming quando suportado.

Adicione Documentação do Pacote e do Provedor

• Escreva o README.md do pacote com instalação, autenticação, configuração, modelos suportados e uso básico.
• Adicione content/providers/01-ai-sdk-providers/<último número + 10>-<provider>.mdx com configuração, capacidades do modelo, opções do provedor e exemplos.
• Configure o script de prepack da documentação do pacote para incluir essa página do provedor.

Prepare o Lançamento

Crie um changeset major para o novo pacote do provedor. O pacote do repositório permanece em 2.0.0 simples; não adicione -beta, -canary ou outro sufixo de pré-lançamento.

Antes do primeiro lançamento automatizado, coordene com a equipe de TI da Vercel para inicializar um pacote @ai-sdk/<provider> vazio no npm em 0.0.0 e configurar seu Trusted Publisher. Siga Inicializando um novo pacote @ai-sdk/*. A versão temporária de bootstrap no npm é separada da versão do pacote do repositório.

Quando main estiver em modo de pré-lançamento, não faça backport do novo pacote para uma branch estável vX.Y.

Verifique a Mudança Completa

Execute, no 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

Execute também os novos exemplos com as credenciais do provedor necessárias. Execute o build raiz quando alterações em pacotes compartilhados ou configuração de build o tornarem relevante.

Checklist de Conclusão

• Pacote de primeira parte aprovado em uma issue
• Especificação OpenAPI oficial revisada, ou sua ausência documentada
• Especificação da API verificada contra documentação e respostas reais
• Implementação de provedor atual comparável selecionada
• Pacote do repositório criado na versão 2.0.0
• Configuração de pacote, TypeScript, build, teste, proveniência e documentação adicionada
• Fábrica do provedor implementa ProviderV4
• Classes de modelo suportadas e tipos de opção pública implementados
• Serialização de workflow implementada para cada classe de modelo
• Parsing de resposta, tratamento de erro e busca de URL seguem as regras de segurança do repositório
• Testes Node e Edge passam com fixtures de resposta representativas
• Exemplos aninhados de AI Functions adicionados e executados com sucesso
• Dependências de exemplo, referências TypeScript, variáveis de ambiente e configuração do Turbo atualizadas
• README e documentação do provedor adicionados
• Changeset major adicionado
• Pacote npm e Trusted Publisher inicializados coordenados
• Build do pacote, testes, type-check completo e verificações do repositório aprovados