JavaScript / TypeScript

npm install jangada-ai

import { LLM } from "jangada-ai";
import "jangada-ai/node"; // loads the project's .env (OPENAI_API_KEY...)

const llm = new LLM("openai", "gpt-4o-mini");
const comp = await llm.complete("Explain what a jangada is in one sentence.");
console.log(comp.text, comp.usage, comp.cost);

const { LLM } = require("jangada-ai");

new LLM("anthropic", "claude-sonnet-4-5");
new LLM("gemini", "gemini-2.5-flash");
new LLM("groq", "openai/gpt-oss-20b");

const llm = new LLM("openai", "gpt-4o-mini", {
  system: "You support {{ company }}.",
  temperature: 0.3,
  maxRetries: 2, // 429, 5xx and timeouts retry on the same model
  fallbacks: [new LLM("anthropic", "claude-haiku-4-5")], // then another provider
});

const comp = await llm.complete("Hi, I'm {{ name }}.", {
  variables: { company: "Fresh Bread Bakery", name: "Ana" },
});

import * as z from "zod";

const Person = z.object({ name: z.string(), age: z.number().int() }).meta({ title: "Person" });
const comp = await llm.parse("Ana is 30 years old.", Person);
comp.parsed; // { name: "Ana", age: 30 }

import { tool } from "jangada-ai";

const weather = tool({
  name: "weather",
  description: "Current temperature in a city",
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ city, temperature: 31 }),
});

const comp = await llm.complete("How is the weather in Recife?", { tools: [weather] });
for (const call of comp.toolCalls) {
  const args = await weather.parseArgs(call.args);
  const result = call.result(await weather.execute(args));
  // send back: history = [..., comp.assistantMessage(), { role: "tool", content: [result] }]
}

for await (const chunk of llm.stream("Count to 5.")) process.stdout.write(chunk);

for await (const ev of llm.streamComplete("A fun fact about Recife.")) {
  if (ev.type === "text") process.stdout.write(ev.text);
  else console.log(ev.completion.cost); // full response: toolCalls, usage, cost
}

import { readImage } from "jangada-ai/node";

await llm.complete("Describe the image.", { images: [await readImage("photo.jpg")] });
await llm.complete("And this one?", { images: ["https://example.com/photo.png"] });

import { Agent, Squad, tool } from "jangada-ai";

const support = new Agent(llm, { role: "Support", tools: [weather] });
const r = await support.run("What's the weather in Recife?");
console.log(r.text, r.cost, r.toolTrace);

const researcher = new Agent(llm, { role: "Researcher", goal: "list short facts" });
const writer = new Agent(llm, { role: "Writer", goal: "write one sentence" });
await new Squad([researcher, writer]).run("jangadas in Ceará");

import { MCPClient, runAgent } from "jangada-ai/mcp";
import { serveMcp } from "jangada-ai/node";

// serve jangada tools as an MCP server
const srv = await serveMcp([weather], { transport: "http", port: 3333 });

// consume an MCP server
await using mcp = await new MCPClient({ url: "https://my-mcp/mcp" }).connect();
const r = await runAgent(llm, "Use the server tools.", { client: mcp });

import { RAG, vectorStore } from "jangada-ai/rag";

const store = vectorStore(process.env.DATABASE_URL); // postgresql://, mongodb:// or "memory"
const rag = new RAG(new LLM("openai", "text-embedding-3-small"), store, { chat: llm });
await rag.syncTexts(["The bakery opens at 6am.", "We accept PIX."], { documentId: "faq" });
const answer = await rag.ask("How can I pay?");

import { serveA2a } from "jangada-ai/node";
await serveA2a(support, { port: 4000 }); // Agent Card at /.well-known/agent-card.json

import { Dataset, Evaluator, evaluate } from "jangada-ai/eval";
const res = await evaluate(dataset, (ex) => llm.complete(ex.inputs.q), [
  Evaluator.fn("exact", (out, ref) => out.text.trim() === ref),
]);