Adicione provedores de IA e bancos vetoriais a um framework modular de IA em Rust

## Mude só o que foi pedido e não faça commit sem pedido - Leia a implementação, os manifestos, os testes e a documentação pública existentes antes de alterar o código. - Mantenha cada mudança dentro do escopo solicitado pelo usuário. - Prefira traits, builders, módulos e tipos de erro existentes a abstrações paralelas. - Não adicione TODOs, stubs, comportamentos provisórios nem APIs públicas especulativas. - Não faça commits, stage, push, crie branches nem abra pull requests, a menos que o usuário solicite explicitamente. - Preserve mudanças não relacionadas feitas pelo usuário e trabalhe com segurança ao redor de uma árvore de trabalho suja. - Evite refatorações não relacionadas, mesmo quando um design próximo puder ser melhorado. - Diferencie a política para colaboradores das regras de engenharia específicas do repositório e siga ambas. - Pare quando faltar a intenção de produto necessária ou uma autorização externa. ## Mantenha coerentes os crates e os feature flags em todo o workspace - Mantenha o crate de fachada pública, o crate central, as integrações complementares, as macros derive, os exemplos e os testes em suas funções estabelecidas. - Faça a fachada reexportar as APIs centrais e expor crates complementares opcionais por meio de feature flags. - Verifique o manifesto do workspace e as exportações da fachada antes de alterar features públicas, integrações ou caminhos de módulos. - Coloque integrações de provedores e bancos vetoriais em crates complementares, salvo quando uma forte razão arquitetural exigir que pertençam ao núcleo. - Mantenha exemplos do workspace separados de exemplos por crate e de testes de integração. - Ao adicionar um crate complementar, atualize conforme aplicável a dependência raiz, a feature, a reexportação da fachada, os exemplos, o README e a documentação do crate. - Garanta que as combinações de features sejam compiladas sem expor módulos indisponíveis. - Mantenha a documentação pública sincronizada entre a fachada e os crates complementares afetados. - Não descreva um caminho de módulo nem uma feature até que o código e os manifestos os confirmem. ## Construa sobre os traits comuns em vez de versões por provedor - Construa integrações sobre os traits centrais do framework para conclusão, embeddings, índices vetoriais e ferramentas invocáveis. - Não crie alternativas específicas de um provedor para um trait existente que abranja vários provedores. - Siga o padrão de builder estabelecido para tipos públicos configuráveis. - Mantenha a construção fluente e tipada, concluindo-a somente após uma etapa explícita de build. - Use uma arquitetura genérica de cliente que separe extensões do provedor do transporte HTTP subjacente. - Declare explicitamente as capacidades do provedor para que comportamentos não suportados falhem em tempo de compilação. - Represente capacidades ausentes com um tipo marcador deliberado, não com suposições em tempo de execução. - Preserve as relações de tipo de API key entre os builders do provedor e os aliases públicos de cliente. - Mantenha os tipos de request e response específicos do provedor atrás de limites de conversão. ## Mantenha o código assíncrono compartilhado funcionando em WebAssembly - Preserve o suporte a WebAssembly em traits, futures, erros e integrações compartilhados. - Use as abstrações de compatibilidade do framework no lugar de limites `Send` e `Sync` brutos quando os targets forem diferentes. - Use o tipo boxed-future portável designado para futures retornados dinamicamente. - Aplique limites nativos de segurança entre threads apenas aos targets que os suportem. - Mantenha os erros boxed do WebAssembly livres de limites exclusivos de plataformas nativas que não sejam suportados. - Teste as assinaturas de tipo nativas e voltadas a WebAssembly após alterar traits compartilhados. - Evite adicionar uma dependência ou API que exclua silenciosamente um target suportado. - Mantenha a compilação condicional em um escopo estreito e explique a diferença entre targets. - Garanta que APIs de provedores, bancos vetoriais e hooks usem o mesmo contrato de portabilidade. ## Use tipos de erro explícitos e documente cada nova API pública - Não use `String` como tipo de erro para uma nova API falível. - Defina enums de erro explícitos e preserve detalhes úteis da resposta do provedor por meio dos helpers de erro do framework. - Prefira `?` e conversões significativas a perder manualmente o contexto do erro. - Use `unwrap()` ou `expect()` somente quando a impossibilidade for óbvia a partir da invariante ao redor. - Adicione documentação de item a cada novo tipo, função, trait e método públicos. - Adicione documentação de módulo a cada novo módulo público. - Mantenha os exemplos alinhados às APIs reais, constantes de modelos, caminhos de módulos e feature flags. - Marque exemplos como não executáveis quando exigirem credenciais ou serviços externos. - Atualize os arquivos README e a documentação no nível do crate sempre que o comportamento público mudar. ## Adicione um novo provedor de IA seguindo o mais parecido que já existe - Estude o provedor existente mais próximo antes de implementar ou modificar outro. - Adicione tipos de extensão e builder do provedor, a implementação do provedor e uma declaração explícita de capacidades. - Ofereça construção a partir de valores de ambiente e valores diretos quando o framework expuser ambos os caminhos. - Mantenha os aliases públicos de cliente e builder coerentes com o tipo de API key do builder do provedor. - Use tipos explícitos de marcador de credencial ou autenticação e oculte na depuração valores que contenham credenciais. - Converta requests do framework para o formato real do provedor e responses de volta para tipos do framework. - Adicione streaming somente quando o provedor realmente o suportar e preserve erros do provedor por meio dos helpers padrão. - Siga as convenções estabelecidas de telemetria e os traits de extensão. - Não invente campos de request ou response ausentes na API real do provedor. - Adicione testes ou exemplos focados que comprovem o comportamento suportado. ## Integre um banco vetorial com filtros reais e resultados de busca claros - Coloque uma integração de banco vetorial em um crate complementar, salvo quando sua presença no núcleo for justificada. - Implemente tanto a busca que retorna resultados quanto a busca que retorna somente identificadores. - Use um tipo de filtro que reflita as capacidades reais de filtragem do backend. - Retorne as variantes de erro do banco vetorial do framework em vez de erros de texto improvisados. - Aplique os mesmos limites assíncronos portáveis usados pelo framework central. - Mantenha explícitas as conversões de pontuação, documento, identificador e metadados. - Defina a ordenação, o limite, o resultado vazio e o comportamento diante de erros do backend. - Teste filtros, ordem de classificação, limites de resultados, registros ausentes e falhas de conversão. - Documente as features, credenciais, índices e configurações externas necessárias sem incorporar segredos. ## Defina as ações permitidas para cada evento de hook - Modele hooks como observadores e orientadores do ciclo de vida com escopo por execução. - Passe um contexto de execução a cada evento, incluindo identidade da execução, turno, modo streaming, identidade do agente e estado temporário compartilhado. - Dê a cada evento seu próprio tipo de ação para que combinações não suportadas falhem em tempo de compilação. - Permita que hooks de chamada de conclusão alterem um request ou interrompam o processamento. - Permita que hooks de chamada e resultado de ferramenta reescrevam valores para hooks posteriores, com skip ou stop como ações terminais onde definido. - Represente o tratamento de chamadas de ferramenta inválidas com opções explícitas de fail, retry, repair, skip e stop. - Limite eventos somente de observação a continue ou stop. - Registre hooks de observação antes dos hooks de orientação quando ações stop interromperem antecipadamente a pilha. - Documente quais ações transformam dados, quais os acumulam e quais encerram o processamento. ## Combine hooks empilhados do mesmo jeito com e sem streaming - Preserve a semântica de composição específica de cada evento quando hooks forem aninhados ou empilhados. - Mescle alterações de requests de conclusão na ordem de registro. - Anexe contexto extra, faça uma mesclagem rasa de parâmetros adicionais e calcule a interseção dos conjuntos de ferramentas ativas. - Aplique a regra de último autor apenas aos campos escalares e de histórico documentados e avise quando uma sobrescrita for relevante. - Restrinja cada alteração de request a um turno; nunca permita que ela persista por acidente. - Encadeie as reescritas de chamadas e resultados de ferramentas em todos os hooks posteriores. - Pare de avaliar a pilha imediatamente quando uma ação terminal exigir. - Faça as superfícies com streaming e sem streaming compartilharem o mesmo controlador de ciclo de vida. - Teste um comportamento idêntico dos hooks pelos pontos de entrada com streaming e sem streaming. - Adicione testes de composição para pilhas aninhadas, conflitos de mesclagem, cadeias de reescrita, skip e stop. ## Escolha o menor teste de regressão e use cassettes gravados para chamadas ao provedor - Adicione cobertura de regressão no menor escopo confiável. - Prefira um teste unitário junto da implementação para defeitos isolados de conversão ou lógica. - Use testes de provedor apoiados por cassettes quando o comportamento depender do tráfego de requests e responses do provedor. - Use testes live ignorados somente quando a reprodução determinística por cassette não puder representar o comportamento. - Leia o guia de testes do repositório antes de adicionar, atualizar, gravar ou reproduzir testes de provedores. - Reproduza cassettes por padrão para que testes normais não exijam credenciais do provedor. - Mantenha a execução dos testes focada no provedor e no comportamento alterados. - Cubra comportamentos com streaming e sem streaming quando ambas as superfícies existirem. - Preserve o modo de falha original na asserção de regressão. ## Grave cassettes só para o teste alvo e confira se não há segredos - Trate o modo de gravação como uma operação externa, com credenciais e que sobrescreve arquivos. - Exija a credencial relevante do provedor antes de gravar e nunca a exponha na saída. - Grave somente o teste do provedor em questão para minimizar mudanças não relacionadas nos fixtures. - Inspecione manualmente cada diff de cassette antes de apresentá-lo ou fazer commit. - Rejeite fixtures que contenham API keys, credenciais bearer, cookies, identificadores de conta ou outros valores sensíveis. - Remova mudanças não relacionadas de requests e responses em vez de aceitar um fixture ruidoso. - Mantenha verificações automáticas de limpeza e segurança ativadas, mas não as trate como substitutas da inspeção. - Preserve dados de reprodução determinísticos enquanto oculta segredos e metadados instáveis. - Nunca sobrescreva fixtures apenas para fazer um teste com falha passar sem explicar a mudança de comportamento. ## Rode verificações do escopo menor ao maior e informe o que ficou sem verificar - Execute primeiro as menores verificações úteis e depois amplie conforme o escopo e o risco afetados. - Formate o workspace e execute lints em todos os targets e features afetados. - Execute testes focados antes de testes amplos do workspace. - Gere a documentação sem dependências quando APIs públicas ou documentos mudarem. - Verifique a compatibilidade nativa e com WebAssembly quando limites ou futures compartilhados mudarem. - Confirme que os campos de transmissão do provedor correspondam à API real e que os diffs de cassette não contenham segredos. - Confirme que a semântica dos hooks seja idêntica nas superfícies com streaming e sem streaming. - Não declare a conclusão enquanto uma verificação obrigatória estiver falhando. - Se um comando não puder ser executado, explique o motivo e informe exatamente o que permanece sem verificação. - Relate as superfícies alteradas, as verificações executadas, os resultados observados, os riscos residuais e o escopo deliberadamente excluído.