JavaScript / TypeScript • npm jangada-ai

A jangada em JavaScript e TypeScript

O port TypeScript da lib Python, com a mesma ideia: trocar provider, modelo e chave sem mudar o resto do código, com retry e fallback por tipo de erro, structured output (Zod), tools, streaming, agentes, MCP, RAG e custo em cada resposta. Roda em Node 22+, Bun, Deno e edge.

$npm install jangada-aiPrefere Python?→

trocar-provider.ts

PythonTypeScript

import { LLM } from "jangada-ai";
// troque o provider numa linha, o resto não muda
let llm = new LLM("anthropic", "claude-sonnet-4-5");
llm = new LLM("openai",    "gpt-5");
const r = await llm.complete("Resuma {{ tema }}.");
console.log(r.text, r.cost);

Com fallback e template:

import { LLM } from "jangada-ai";
import "jangada-ai/node"; // carrega o .env do projeto

const llm = new LLM("openai", "gpt-4o-mini", {
  fallbacks: [new LLM("anthropic", "claude-haiku-4-5")],
});
const comp = await llm.complete("Olá, {{ nome }}!", { variables: { nome: "Ana" } });
console.log(comp.text, comp.usage, comp.cost);

Versão atual: 1.0.5 (npm). A constante VERSION, exportada pelo pacote, traz o mesmo número.

O que vem no pacote

O código-fonte é TypeScript. O pacote publicado é JavaScript em dois formatos, ESM (import) e CommonJS (require), com os tipos (.d.ts) junto. Funciona em projeto JS puro; em TypeScript você ganha autocompletar e checagem de tipos sem instalar @types nenhum.

Roda em Node 22 ou mais novo, Bun, Deno e runtimes edge (Cloudflare Workers, Vercel Edge). O núcleo não usa o sistema de arquivos nem módulos node:*. O que depende do Node (ler arquivo, carregar .env, subir servidor HTTP) fica no subpath jangada-ai/node.

SDKs carregados sob demanda

Os SDKs dos providers (openai, @anthropic-ai/sdk, @google/genai e outros) são peerDependencies opcionais. Você instala só os que for usar. O adapter de cada provider só é carregado na primeira chamada, e o SDK entra por await import() dentro dele. Por isso import "jangada-ai" funciona sem nenhum SDK instalado, e quem usa só a OpenAI nunca carrega o adapter da Anthropic.

Se o SDK faltar, o erro aparece na primeira chamada, com o comando de instalação na mensagem (Instale o SDK da OpenAI para usar 'openai': npm install openai). A tabela completa de peers está em Começando.

Paridade com o Python

A versão 1.0 cobre o que a lib Python faz: 11 providers, retry e fallback, structured output, tools e tools nativas, streaming, vision e documentos, transcrição, embeddings, OCR, custo, cache, guardrails, agentes, MCP, RAG, Gemini Interactions, A2A, observability e eval.

Os casos de template, classificação de erro, cálculo de custo, profiles e o catálogo de preços são gerados pela lib Python e testados no port, então os dois lados dão o mesmo resultado. O RAG usa o mesmo esquema no Postgres e no MongoDB: Python e JS podem ler e escrever no mesmo banco.

As diferenças são de linguagem: só API async, nomes em camelCase, variáveis do template num objeto, Zod no lugar de Pydantic, signal para cancelar. A lista completa está em Diferenças em relação ao Python.

Páginas desta seção

Começando:

• Começando: instalação, .env, primeira chamada em ESM e CommonJS.
• Providers: os 11 providers, chaves, apiKey, clientOptions e particularidades.
• Parâmetros: templates {{ }}, params de geração, profiles por modelo e opções de chamada.
• Diferenças em relação ao Python

Capacidades:

• Structured output: Zod, Standard Schema e JSON Schema com parse().
• Tools: tool(), loop de tool calls e tools nativas.
• Streaming: stream(), streamComplete() e cancelamento.
• Vision e documentos
• Agentes
• MCP
• RAG
• Gemini Interactions
• A2A
• Guardrails
• Observability
• Eval

Confiabilidade:

• Erros e fallback
• Custo e cache