jangada-ai 0.0.0 → 1.0.0

package/README.md

@@ -1,18 +1,46 @@
 # jangada (JS/TS)
 
 Camada fina e adaptável sobre os SDKs de LLM, em TypeScript. Troque provider,
-modelo e chave sem mudar o resto do código.
+modelo e chave sem mudar o resto do código, com retry e fallback por tipo de
+erro, structured output com Zod, tools, streaming e custo em cada resposta.
 
 Port da lib Python [`jangada-ai`](https://pypi.org/project/jangada-ai/).
 Documentação: [docs.jangada.dev.br](https://docs.jangada.dev.br).
 
-> Em desenvolvimento. A primeira versão publicada será a `0.1.0`.
+> Versão 1.0.0: paridade com a lib Python (providers, tools, MCP, agentes, RAG, eval, A2A e mais).
 
 ```bash
 npm install jangada-ai
+npm install openai              # e/ou @anthropic-ai/sdk, @google/genai, zod
 ```
 
-Roda em Node 22+, Bun, Deno e runtimes edge (Cloudflare Workers, Vercel Edge).
+Roda em Node 22+, Bun, Deno e runtimes edge. O núcleo não usa `fs`; leitura de
+arquivo e `.env` ficam em `jangada-ai/node`.
+
+```ts
+import { LLM } from "jangada-ai";
+import "jangada-ai/node"; // carrega o .env
+
+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.cost);
+```
+
+Providers: `openai`, `azure`, `groq`, `openrouter`, `deepseek`, `anthropic`,
+`gemini`, `vertex`, `bedrock`, `mistral`, `ollama`.
+
+Subpaths: `jangada-ai/node` (arquivos, `.env`, `serveMcp`, `serveA2a`),
+`jangada-ai/mcp`, `jangada-ai/rag`, `jangada-ai/eval`, `jangada-ai/prebuilt` e
+`jangada-ai/a2a`. Exemplos em [`examples/`](examples/).
+
+## Desenvolvimento
+
+```bash
+npm run check       # lint + tipos + testes + build
+npm run test:live   # APIs reais (precisa das chaves no ambiente)
+```
 
 ## Licença
 

package/dist/anthropic-BlqXqf9N.js

@@ -0,0 +1,555 @@
+import { _ as UnsupportedError, d as ProviderError, l as OutputValidationError, m as ServerError, s as LLMError, v as classify } from "./errors-hp-4UePr.js";
+import { s as splitMcp } from "./client-BFoano5Y.js";
+import { d as imageBase64, s as Completion, u as ToolCall } from "./context-C7qrmHGJ.js";
+import { c as NativeTool, i as splitTools } from "./version-CrHu1Pq_.js";
+import { n as applyProfile, t as Provider } from "./base-8WLtVj6O.js";
+// src/providers/anthropic.ts
+/**
+* Provider Anthropic (Claude): texto, vision, tools, tools nativas (server tools),
+* streaming e structured output por tool-forcing. SDK: `@anthropic-ai/sdk`
+* (peer dependency opcional).
+*
+* Structured output força uma ferramenta `extract` cujo `input_schema` é o JSON
+* Schema. Nos modelos que REJEITAM forced tool use (Opus 5.5, Sonnet 5.5, Fable 5.1,
+* Mythos 5.1) cai para `tool_choice: auto` + strict tool use, a migração oficial.
+*
+* MCP remoto: `mcpServers` com `MCPServer` vai na Messages API (`mcp_servers` +
+* `mcp_toolset`, header beta `mcp-client-2025-11-20`). Sessão client-side não dá.
+*
+* Espelha `jangada_ai/providers/anthropic.py`.
+*/
+const THINKING_KEY = "anthropic_thinking_blocks";
+const CONTENT_KEY = "anthropic_content";
+const CONTAINER_KEY = "anthropic_container";
+const MAX_PAUSE = 5;
+const MCP_BETA = "mcp-client-2025-11-20";
+const NATIVE_VERSIONS = {
+	web_search: ["web_search_20250305", "web_search"],
+	web_fetch: ["web_fetch_20250910", "web_fetch"],
+	code_execution: ["code_execution_20250825", "code_execution"]
+};
+const NATIVE_OPTS = {
+	maxUses: "max_uses",
+	allowedDomains: "allowed_domains",
+	blockedDomains: "blocked_domains",
+	userLocation: "user_location"
+};
+const PLAIN_BLOCKS = /* @__PURE__ */ new Set([
+	"text",
+	"tool_use",
+	"thinking",
+	"redacted_thinking"
+]);
+const NO_FORCED_TOOLS = /(?:opus-5[.-]5|sonnet-5[.-]5|fable-5[.-]1|mythos-5[.-]1)/;
+function get(obj, key) {
+	return obj !== null && typeof obj === "object" ? obj[key] : void 0;
+}
+function n(v) {
+	return typeof v === "number" && Number.isInteger(v) ? v : 0;
+}
+/** strict tool use exige `additionalProperties: false` em todo objeto (não mexe em `required`). */
+function strictSchema(node) {
+	if (Array.isArray(node)) return node.map(strictSchema);
+	if (node && typeof node === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(node)) out[k] = strictSchema(v);
+		if (out.type === "object" && !("additionalProperties" in out)) out.additionalProperties = false;
+		return out;
+	}
+	return node;
+}
+/** Bloco da resposta como objeto simples, reenviável exatamente como veio. */
+function dumpBlock(b) {
+	return JSON.parse(JSON.stringify(b));
+}
+function systemText(content) {
+	if (typeof content === "string") return content;
+	return content.map((p) => p.type === "text" ? p.text : "").filter(Boolean).join("\n");
+}
+var AnthropicProvider = class AnthropicProvider extends Provider {
+	name = "anthropic";
+	envKey = "ANTHROPIC_API_KEY";
+	nativeToolKinds = /* @__PURE__ */ new Set([
+		"web_search",
+		"web_fetch",
+		"code_execution"
+	]);
+	nativeToolPassthrough = true;
+	nativeToolAliases = ["claude"];
+	supportsMcp = true;
+	async buildClient() {
+		let mod;
+		try {
+			mod = await import("@anthropic-ai/sdk");
+		} catch (e) {
+			throw new Error("Instale o SDK da Anthropic: npm install @anthropic-ai/sdk", { cause: e });
+		}
+		return new mod.default({
+			apiKey: this.resolveApiKey(),
+			...this.clientOptions
+		});
+	}
+	content(content) {
+		if (typeof content === "string") return content;
+		const blocks = [];
+		let thinking = [];
+		for (const p of content) if (p.type === "text") {
+			if (p.text) blocks.push({
+				type: "text",
+				text: p.text
+			});
+		} else if (p.type === "image") blocks.push({
+			type: "image",
+			source: {
+				type: "base64",
+				media_type: p.mimeType,
+				data: imageBase64(p)
+			}
+		});
+		else if (p.type === "tool_call") {
+			if (!thinking.length) thinking = [...p.metadata?.[THINKING_KEY] ?? []];
+			blocks.push({
+				type: "tool_use",
+				id: p.id,
+				name: p.name,
+				input: p.args
+			});
+		} else if (p.type === "tool_result") blocks.push({
+			type: "tool_result",
+			tool_use_id: p.toolCallId,
+			content: p.content,
+			...p.isError ? { is_error: true } : {}
+		});
+		return [...thinking, ...blocks];
+	}
+	split(messages) {
+		const system = messages.filter((m) => m.role === "system").map((m) => systemText(m.content)).filter(Boolean).join("\n\n") || void 0;
+		const convo = [];
+		for (const m of messages) {
+			if (m.role === "system") continue;
+			const brutos = m.metadata?.[CONTENT_KEY];
+			if (m.role === "assistant" && brutos?.length) {
+				convo.push({
+					role: "assistant",
+					content: [...brutos]
+				});
+				continue;
+			}
+			convo.push({
+				role: m.role === "tool" ? "user" : m.role,
+				content: this.content(m.content)
+			});
+		}
+		return {
+			system,
+			convo
+		};
+	}
+	/** Canônico → nativo: stop → stop_sequences; seed não existe na Anthropic. */
+	translate(params) {
+		const map = {
+			maxTokens: "max_tokens",
+			topP: "top_p",
+			topK: "top_k",
+			stop: "stop_sequences"
+		};
+		const out = {};
+		for (const [k, v] of Object.entries(params)) {
+			if (v === void 0 || v === null || k === "seed") continue;
+			const key = map[k] ?? k;
+			out[key] = key === "stop_sequences" && typeof v === "string" ? [v] : v;
+		}
+		return out;
+	}
+	formatTools(tools) {
+		const { functions, natives } = splitTools(tools);
+		const out = functions.map((t) => ({
+			name: t.name,
+			description: t.description,
+			input_schema: t.parameters
+		}));
+		for (const nt of natives) out.push(this.nativeTool(nt));
+		return out;
+	}
+	/** NativeTool canônica → server tool da Messages API. */
+	nativeTool(nt) {
+		if (nt.kind === "native") return nt.spec;
+		const raw = nt.optsFor("anthropic");
+		const o = {};
+		for (const [k, v] of Object.entries(raw)) o[NATIVE_OPTS[k] ?? k] = v;
+		const [tipoPadrao, nome] = NATIVE_VERSIONS[nt.kind];
+		const tipo = o.version ?? tipoPadrao;
+		delete o.version;
+		delete o.container;
+		if (o.files !== void 0) throw new UnsupportedError("codeExecution({ files }) não existe na Anthropic: envie os arquivos como blocos container_upload (Files API) na mensagem.", { provider: this.name });
+		const loc = o.user_location;
+		if (loc && typeof loc === "object" && !("type" in loc)) o.user_location = {
+			type: "approximate",
+			...loc
+		};
+		if (o.allowed_domains && o.blocked_domains) throw new UnsupportedError(`${nt.kind}: a Anthropic não aceita allowedDomains e blockedDomains juntos (400). Use só um.`, { provider: this.name });
+		return {
+			type: tipo,
+			name: nome,
+			...o
+		};
+	}
+	/** Container do code_execution: o explícito ou o último do histórico. */
+	static containerFrom(messages, tools) {
+		for (const t of tools) if (t instanceof NativeTool && t.kind === "code_execution") {
+			const explicito = t.options.container;
+			if (typeof explicito === "string" && explicito) return explicito;
+			for (const m of [...messages].reverse()) {
+				const cid = m.metadata?.[CONTAINER_KEY];
+				if (typeof cid === "string" && cid) return cid;
+			}
+		}
+	}
+	static toolChoice(tc) {
+		if (tc === "required" || tc === "any") return { type: "any" };
+		if (tc === "auto" || tc === "none") return { type: tc };
+		if (typeof tc === "string") return {
+			type: "tool",
+			name: tc
+		};
+		return tc;
+	}
+	forbidsForcedTools() {
+		return NO_FORCED_TOOLS.test(this.model ?? "");
+	}
+	kwargs(messages, options) {
+		const { system, convo } = this.split(messages);
+		const native = applyProfile(this.name, this.model, this.translate(options.params), this.profileModel ? { profileModel: this.profileModel } : void 0).params;
+		native.max_tokens ??= 8192;
+		const kw = {
+			model: this.model,
+			messages: convo,
+			...native
+		};
+		if (system) kw.system = system;
+		const tools = options.tools;
+		if (tools?.length) {
+			kw.tools = this.formatTools(tools);
+			if (options.toolChoice !== void 0 && options.toolChoice !== null) {
+				const tc = AnthropicProvider.toolChoice(options.toolChoice);
+				if (this.forbidsForcedTools() && (tc.type === "any" || tc.type === "tool")) throw new UnsupportedError(`${this.model} não suporta forced tool use (toolChoice=${JSON.stringify(options.toolChoice)}): a API retorna 400. Use toolChoice 'auto' (com strict tool use, se quiser garantir o schema) ou structured output via parse().`, { provider: this.name });
+				kw.tool_choice = tc;
+			}
+			const container = AnthropicProvider.containerFrom(messages, tools);
+			if (container) kw.container = container;
+		}
+		if (options.mcpServers?.length) this.applyMcp(kw, options.mcpServers);
+		return kw;
+	}
+	/**
+	* MCP remoto via Messages API (server-side, beta). Sessão client-side não dá.
+	* Allowlist no shape `mcp-client-2025-11-20`: `default_config` desabilitado e cada
+	* tool permitida habilitada em `configs`.
+	*/
+	applyMcp(kw, mcpServers) {
+		const { remote, sessions } = splitMcp(mcpServers);
+		if (sessions.length) throw new UnsupportedError("Anthropic só aceita MCP remoto por URL (passe MCPServer). Para MCP client-side (sessão), use o Gemini ou MCPClient + runAgent.", { provider: this.name });
+		kw.mcp_servers = remote.map((s) => ({
+			type: "url",
+			url: s.url,
+			name: s.name,
+			...s.authorizationToken ? { authorization_token: s.authorizationToken } : {}
+		}));
+		const toolsets = remote.map((s) => ({
+			type: "mcp_toolset",
+			mcp_server_name: s.name,
+			...s.allowedTools?.length ? {
+				default_config: { enabled: false },
+				configs: Object.fromEntries(s.allowedTools.map((t) => [t, { enabled: true }]))
+			} : {}
+		}));
+		kw.tools = [...kw.tools ?? [], ...toolsets];
+	}
+	/** Opções da requisição: `signal` e, com MCP, o header beta. */
+	reqOptions(options) {
+		const o = { signal: options.signal };
+		if (options.mcpServers?.length) o.headers = { "anthropic-beta": MCP_BETA };
+		return o;
+	}
+	static thinkingBlocks(content) {
+		const out = [];
+		for (const b of content) {
+			const tipo = get(b, "type");
+			if (tipo === "thinking") out.push({
+				type: "thinking",
+				thinking: get(b, "thinking") ?? "",
+				signature: get(b, "signature") ?? ""
+			});
+			else if (tipo === "redacted_thinking") out.push({
+				type: "redacted_thinking",
+				data: get(b, "data") ?? ""
+			});
+		}
+		return out;
+	}
+	completion(resp) {
+		try {
+			return this.buildCompletion(resp);
+		} catch (e) {
+			if (e instanceof LLMError) throw e;
+			throw new ProviderError(`[${this.name}] resposta em formato inesperado: ${e instanceof Error ? `${e.name}: ${e.message}` : e}`, {
+				provider: this.name,
+				original: e
+			});
+		}
+	}
+	buildCompletion(resp) {
+		const content = get(resp, "content");
+		if (!Array.isArray(content)) throw new ServerError(`[${this.name}] resposta sem conteúdo (content=${content}).`, { provider: this.name });
+		const text = content.map((b) => get(b, "type") === "text" ? get(b, "text") ?? "" : "").join("");
+		const toolCalls = content.filter((b) => get(b, "type") === "tool_use" && get(b, "name")).map((b) => new ToolCall(String(get(b, "id") ?? ""), String(get(b, "name")), { ...get(b, "input") ?? {} }));
+		const thinking = AnthropicProvider.thinkingBlocks(content);
+		if (thinking.length && toolCalls[0]) toolCalls[0].metadata[THINKING_KEY] = thinking;
+		const { citations, serverCalls, preservar } = AnthropicProvider.nativeOutputs(content);
+		const meta = {};
+		if (preservar) meta[CONTENT_KEY] = content.map(dumpBlock);
+		const cid = get(get(resp, "container"), "id");
+		if (typeof cid === "string" && cid) meta[CONTAINER_KEY] = cid;
+		let usage = null;
+		const u = get(resp, "usage");
+		if (u) {
+			const cacheWrite = n(get(u, "cache_creation_input_tokens"));
+			const cacheRead = n(get(u, "cache_read_input_tokens"));
+			usage = {
+				inputTokens: n(get(u, "input_tokens")) + cacheWrite + cacheRead,
+				outputTokens: n(get(u, "output_tokens"))
+			};
+			if (cacheRead) usage.cacheReadTokens = cacheRead;
+			if (cacheWrite) usage.cacheWriteTokens = cacheWrite;
+			const stu = get(u, "server_tool_use");
+			if (stu) {
+				const reqs = {};
+				const ws = n(get(stu, "web_search_requests"));
+				const wf = n(get(stu, "web_fetch_requests"));
+				if (ws) reqs.web_search = ws;
+				if (wf) reqs.web_fetch = wf;
+				if (Object.keys(reqs).length) usage.serverToolRequests = reqs;
+			}
+		}
+		const stop = get(resp, "stop_reason") ?? null;
+		return new Completion({
+			text,
+			model: this.model,
+			provider: this.name,
+			raw: resp,
+			usage,
+			toolCalls,
+			finishReason: stop === "max_tokens" ? "length" : stop,
+			citations,
+			serverToolCalls: serverCalls,
+			metadata: meta
+		});
+	}
+	/**
+	* Citações dos blocos de texto + execuções de server tools (`server_tool_use`
+	* casado com o `*_tool_result` pelo `tool_use_id`). `preservar` diz se o turno
+	* tem blocos que precisam voltar intactos no histórico.
+	*/
+	static nativeOutputs(content) {
+		const citations = [];
+		const calls = /* @__PURE__ */ new Map();
+		const ordem = [];
+		let preservar = false;
+		let pos = 0;
+		for (const b of content) {
+			const tipo = get(b, "type");
+			if (tipo === "text") {
+				const txt = get(b, "text") ?? "";
+				const cits = get(b, "citations") ?? [];
+				if (cits.length) preservar = true;
+				for (const c of cits) {
+					const ct = String(get(c, "type") ?? "");
+					citations.push({
+						url: get(c, "url") ?? null,
+						title: get(c, "title") ?? null,
+						citedText: get(c, "cited_text") ?? null,
+						start: pos,
+						end: pos + txt.length,
+						source: ct.includes("web") ? "web" : ct || null
+					});
+				}
+				pos += txt.length;
+				continue;
+			}
+			if (typeof tipo === "string" && PLAIN_BLOCKS.has(tipo)) continue;
+			preservar = true;
+			if (tipo === "server_tool_use") {
+				const id = get(b, "id") ?? null;
+				const stc = {
+					type: get(b, "name") || "server_tool",
+					input: get(b, "input"),
+					id
+				};
+				calls.set(id ?? String(calls.size), stc);
+				ordem.push(stc);
+			} else if (typeof tipo === "string" && tipo.endsWith("_tool_result")) {
+				const alvoId = get(b, "tool_use_id");
+				const saida = dumpBlock(b).content;
+				const alvo = alvoId ? calls.get(alvoId) : void 0;
+				if (alvo) alvo.output = saida;
+				else ordem.push({
+					type: tipo.slice(0, -12),
+					output: saida,
+					id: alvoId ?? null
+				});
+			}
+		}
+		return {
+			citations,
+			serverCalls: ordem,
+			preservar
+		};
+	}
+	static mergeUsage(total, resp) {
+		const u = get(resp, "usage");
+		if (!u) return;
+		for (const k of [
+			"input_tokens",
+			"output_tokens",
+			"cache_creation_input_tokens",
+			"cache_read_input_tokens"
+		]) total[k] = (total[k] ?? 0) + n(get(u, k));
+		const stu = get(u, "server_tool_use");
+		for (const k of ["web_search_requests", "web_fetch_requests"]) total[k] = (total[k] ?? 0) + n(get(stu, k));
+	}
+	/** Resposta final com o conteúdo de TODAS as rodadas e o usage somado. */
+	static finalAfterPause(resp, acum, total) {
+		if (!acum.length) return resp;
+		AnthropicProvider.mergeUsage(total, resp);
+		return {
+			content: [...acum, ...get(resp, "content") ?? []],
+			usage: {
+				input_tokens: total.input_tokens ?? 0,
+				output_tokens: total.output_tokens ?? 0,
+				cache_creation_input_tokens: total.cache_creation_input_tokens ?? 0,
+				cache_read_input_tokens: total.cache_read_input_tokens ?? 0,
+				server_tool_use: {
+					web_search_requests: total.web_search_requests ?? 0,
+					web_fetch_requests: total.web_fetch_requests ?? 0
+				}
+			},
+			stop_reason: get(resp, "stop_reason"),
+			container: get(resp, "container"),
+			raw_last: resp
+		};
+	}
+	static continueAfterPause(kw, resp) {
+		const content = (get(resp, "content") ?? []).map(dumpBlock);
+		return {
+			...kw,
+			messages: [...kw.messages, {
+				role: "assistant",
+				content
+			}]
+		};
+	}
+	async complete(messages, options) {
+		const client = await this.client();
+		let kw = this.kwargs(messages, options);
+		const acum = [];
+		const total = {};
+		let resp;
+		for (let i = 0; i <= MAX_PAUSE; i++) {
+			try {
+				resp = await client.messages.create(kw, this.reqOptions(options));
+			} catch (e) {
+				throw this.err(e, options);
+			}
+			if (get(resp, "stop_reason") !== "pause_turn") break;
+			acum.push(...get(resp, "content") ?? []);
+			AnthropicProvider.mergeUsage(total, resp);
+			kw = AnthropicProvider.continueAfterPause(kw, resp);
+		}
+		return this.completion(AnthropicProvider.finalAfterPause(resp, acum, total));
+	}
+	toolKwargs(messages, schema, options) {
+		const kw = this.kwargs(messages, {
+			...options,
+			tools: void 0,
+			toolChoice: void 0,
+			mcpServers: void 0
+		});
+		const extract = {
+			name: "extract",
+			description: `Retorne um objeto ${schema.name} estruturado.`,
+			input_schema: schema.jsonSchema
+		};
+		if (this.forbidsForcedTools()) {
+			extract.strict = true;
+			extract.input_schema = strictSchema(extract.input_schema);
+			kw.tool_choice = { type: "auto" };
+		} else kw.tool_choice = {
+			type: "tool",
+			name: "extract"
+		};
+		kw.tools = [extract];
+		delete kw.thinking;
+		return kw;
+	}
+	async parse(messages, schema, options) {
+		const client = await this.client();
+		const kw = this.toolKwargs(messages, schema, options);
+		let resp;
+		try {
+			resp = await client.messages.create(kw, { signal: options.signal });
+		} catch (e) {
+			throw this.err(e, options);
+		}
+		const comp = this.completion(resp);
+		Provider.checkTruncation(comp, this.name);
+		const toolUse = (get(resp, "content") ?? []).find((b) => get(b, "type") === "tool_use");
+		if (!toolUse) throw new OutputValidationError(`[${this.name}] o modelo não devolveu o objeto estruturado (stop_reason=${JSON.stringify(comp.finishReason ?? "sem tool_use")}): ${JSON.stringify(comp.text.slice(0, 200))}`, { provider: this.name });
+		const input = get(toolUse, "input");
+		comp.text = JSON.stringify(input);
+		comp.parsed = await schema.validate(input);
+		comp.toolCalls = [];
+		return comp;
+	}
+	async *stream(messages, options) {
+		for await (const ev of this.streamEvents(messages, options)) if (ev.type === "text") yield ev.text;
+	}
+	async *streamEvents(messages, options) {
+		const client = await this.client();
+		let kw = this.kwargs(messages, options);
+		const acum = [];
+		const total = {};
+		let resp;
+		for (let i = 0; i <= MAX_PAUSE; i++) {
+			try {
+				const s = client.messages.stream(kw, this.reqOptions(options));
+				for await (const ev of s) {
+					if (get(ev, "type") !== "content_block_delta") continue;
+					const delta = get(ev, "delta");
+					if (get(delta, "type") === "text_delta") {
+						const t = get(delta, "text");
+						if (typeof t === "string" && t) yield {
+							type: "text",
+							text: t
+						};
+					}
+				}
+				resp = await s.finalMessage();
+			} catch (e) {
+				throw this.err(e, options);
+			}
+			if (get(resp, "stop_reason") !== "pause_turn") break;
+			acum.push(...get(resp, "content") ?? []);
+			AnthropicProvider.mergeUsage(total, resp);
+			kw = AnthropicProvider.continueAfterPause(kw, resp);
+		}
+		yield {
+			type: "done",
+			text: "",
+			completion: this.completion(AnthropicProvider.finalAfterPause(resp, acum, total))
+		};
+	}
+	err(e, options) {
+		return options.signal?.aborted ? e : classify(e, this.name);
+	}
+};
+export { AnthropicProvider };