@threaded/ai 1.0.25 → 1.0.27

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:platform.openai.com)",
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:ai.google.dev)",
+      "WebFetch(domain:docs.x.ai)",
+      "WebFetch(domain:docs.cloud.google.com)",
+      "WebFetch(domain:latenode.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:docs.aimlapi.com)"
+    ]
+  }
+}

package/.lore

@@ -0,0 +1,65 @@
+-- core pattern --
+
+everything is built on compose/scope/model. compose chains steps, scope isolates context, model calls an LLM.
+
+```js
+const workflow = compose(
+  scope({ system: "...", tools: [...] }, model({ model: "openai/gpt-4o" }))
+)
+const ctx = await workflow("user message")
+```
+
+-- key setup --
+
+must call setKeys() before any model() call, or set env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY)
+
+```js
+import { setKeys } from "@threaded/ai"
+setKeys({ openai: process.env.OPENAI_API_KEY })
+```
+
+-- model naming --
+
+always "provider/model-name": openai/gpt-4o, anthropic/claude-sonnet-4-5-20250929, google/gemini-2.5-flash, xai/grok-4-1-fast-non-reasoning. no prefix defaults to huggingface.
+
+-- structured output --
+
+pass schema (zod or json schema) to model(). response comes back as JSON in lastResponse.content. claude wraps it in markdown code fences - strip them before JSON.parse.
+
+```js
+function extractResult(ctx) {
+  const last = ctx.history?.findLast(m => m.role === 'assistant')
+  if (!last?.content) return null
+  let text = typeof last.content === 'string' ? last.content : last.content[0]?.text || ''
+  const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/)
+  if (fenced) text = fenced[1]
+  return JSON.parse(text.trim())
+}
+```
+
+-- pitfalls --
+
+do NOT use Inherit.Nothing - it drops the user prompt entirely. use Inherit.Conversation (default) instead.
+
+until: noToolsCalled() loops can cause runaway API calls (5-6+ per invocation). use maxCalls() on tools to limit.
+
+silent scopes run analysis without polluting chat history but still accumulate token usage on ctx.usage.
+
+events are local only in the scope where stream callback is set. nested silent scopes with their own stream get their own events.
+
+-- rate limiting --
+
+anthropic tier 1 has very low limits (30K input tokens/min). when using anthropic, add delays between calls and use maxCalls() aggressively. 90s backoff on rate limit errors.
+
+-- token usage --
+
+ctx.usage accumulates across all model() calls, tool loops, and nested scopes. always available after workflow completes:
+{ promptTokens, completionTokens, totalTokens }
+
+-- integration patterns --
+
+SSE streaming: pass stream callback in scope config, write events to res as `data: ${JSON.stringify(event)}\n\n`
+
+tool approval: use toolConfig.requireApproval + approvalCallback for gating dangerous tool execution in web UIs
+
+MCP tools: createMCPTools(client) converts MCP server tools to native format. tools are prefixed with server name.

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   IMAGE_EDIT_MODEL_SCHEMA: () => IMAGE_EDIT_MODEL_SCHEMA,
   IMAGE_MODEL_SCHEMA: () => IMAGE_MODEL_SCHEMA,
   Inherit: () => Inherit,
+  addUsage: () => addUsage,
   appendToLastRequest: () => appendToLastRequest,
   compose: () => compose,
   convertMCPSchemaToToolSchema: () => convertMCPSchemaToToolSchema,
@@ -222,6 +223,11 @@ var maxCalls = (toolConfig, maxCalls2) => ({
   ...toolConfig,
   _maxCalls: maxCalls2
 });
+var addUsage = (existing, promptTokens, completionTokens, totalTokens) => ({
+  promptTokens: (existing?.promptTokens || 0) + promptTokens,
+  completionTokens: (existing?.completionTokens || 0) + completionTokens,
+  totalTokens: (existing?.totalTokens || 0) + totalTokens
+});
 
 // src/embed.ts
 var modelCache = /* @__PURE__ */ new Map();
@@ -533,7 +539,8 @@ var callOpenAI = async (config, ctx) => {
   const body = {
     model: model2,
     messages,
-    stream: !!ctx.stream
+    stream: !!ctx.stream,
+    ...ctx.stream && { stream_options: { include_usage: true } }
   };
   if (schema) {
     body.response_format = {
@@ -578,7 +585,8 @@ var callOpenAI = async (config, ctx) => {
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage: addUsage(ctx.usage, data.usage?.prompt_tokens || 0, data.usage?.completion_tokens || 0, data.usage?.total_tokens || 0)
   };
 };
 var handleOpenAIStream = async (response, ctx) => {
@@ -587,6 +595,7 @@ var handleOpenAIStream = async (response, ctx) => {
   let fullContent = "";
   let toolCalls = [];
   let buffer = "";
+  let streamUsage = null;
   try {
     while (true) {
       if (ctx.abortSignal?.aborted) {
@@ -604,6 +613,9 @@ var handleOpenAIStream = async (response, ctx) => {
           if (!data) continue;
           try {
             const parsed = JSON.parse(data);
+            if (parsed.usage) {
+              streamUsage = parsed.usage;
+            }
             const delta = parsed.choices?.[0]?.delta;
             if (delta?.content) {
               fullContent += delta.content;
@@ -629,10 +641,15 @@ var handleOpenAIStream = async (response, ctx) => {
   if (toolCalls.length > 0) {
     msg.tool_calls = toolCalls;
   }
+  const usage = addUsage(ctx.usage, streamUsage?.prompt_tokens || 0, streamUsage?.completion_tokens || 0, streamUsage?.total_tokens || 0);
+  if (ctx.stream && streamUsage) {
+    ctx.stream({ type: "usage", usage });
+  }
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage
   };
 };
 
@@ -768,10 +785,13 @@ Return only the JSON object, no other text or formatting.`;
       }
     ];
   }
+  const inputTokens = data.usage?.input_tokens || 0;
+  const outputTokens = data.usage?.output_tokens || 0;
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage: addUsage(ctx.usage, inputTokens, outputTokens, inputTokens + outputTokens)
   };
 };
 var handleAnthropicStream = async (response, ctx) => {
@@ -780,6 +800,8 @@ var handleAnthropicStream = async (response, ctx) => {
   let fullContent = "";
   const toolCalls = [];
   let buffer = "";
+  let inputTokens = 0;
+  let outputTokens = 0;
   try {
     while (true) {
       if (ctx.abortSignal?.aborted) {
@@ -796,6 +818,12 @@ var handleAnthropicStream = async (response, ctx) => {
           if (!data) continue;
           try {
             const parsed = JSON.parse(data);
+            if (parsed.type === "message_start" && parsed.message?.usage) {
+              inputTokens = parsed.message.usage.input_tokens || 0;
+            }
+            if (parsed.type === "message_delta" && parsed.usage) {
+              outputTokens = parsed.usage.output_tokens || 0;
+            }
             if (parsed.type === "content_block_delta" && parsed.delta?.text) {
               fullContent += parsed.delta.text;
               if (ctx.stream) {
@@ -835,10 +863,15 @@ var handleAnthropicStream = async (response, ctx) => {
   if (toolCalls.length > 0) {
     msg.tool_calls = toolCalls.map(({ index, ...tc }) => tc);
   }
+  const usage = addUsage(ctx.usage, inputTokens, outputTokens, inputTokens + outputTokens);
+  if (ctx.stream && (inputTokens || outputTokens)) {
+    ctx.stream({ type: "usage", usage });
+  }
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage
   };
 };
 
@@ -991,10 +1024,12 @@ var callGoogle = async (config, ctx) => {
   if (toolCalls.length > 0) {
     msg.tool_calls = toolCalls;
   }
+  const um = data.usageMetadata;
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage: addUsage(ctx.usage, um?.promptTokenCount || 0, um?.candidatesTokenCount || 0, um?.totalTokenCount || 0)
   };
 };
 var handleGoogleStream = async (response, ctx) => {
@@ -1003,6 +1038,7 @@ var handleGoogleStream = async (response, ctx) => {
   let fullContent = "";
   const toolCalls = [];
   let buffer = "";
+  let usageMetadata = null;
   try {
     while (true) {
       if (ctx.abortSignal?.aborted) {
@@ -1019,6 +1055,9 @@ var handleGoogleStream = async (response, ctx) => {
           if (!data) continue;
           try {
             const parsed = JSON.parse(data);
+            if (parsed.usageMetadata) {
+              usageMetadata = parsed.usageMetadata;
+            }
             const candidate = parsed.candidates?.[0];
             const parts = candidate?.content?.parts || [];
             for (const part of parts) {
@@ -1058,18 +1097,75 @@ var handleGoogleStream = async (response, ctx) => {
   if (toolCalls.length > 0) {
     msg.tool_calls = toolCalls;
   }
+  const um = usageMetadata;
+  const usage = addUsage(ctx.usage, um?.promptTokenCount || 0, um?.candidatesTokenCount || 0, um?.totalTokenCount || 0);
+  if (ctx.stream && um) {
+    ctx.stream({ type: "usage", usage });
+  }
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage
   };
 };
 
 // src/providers/huggingface.ts
+var modelCache2 = /* @__PURE__ */ new Map();
+var formatMessages = (instructions, history) => {
+  const messages = [];
+  if (instructions) {
+    messages.push({ role: "system", content: instructions });
+  }
+  for (const msg of history) {
+    messages.push({ role: msg.role, content: msg.content });
+  }
+  return messages;
+};
 var callHuggingFace = async (config, ctx) => {
-  throw new Error(
-    "Hugging Face provider not yet implemented. Use openai/, anthropic/, or google/ prefixes."
-  );
+  const { model: model2, instructions, schema } = config;
+  const { pipeline } = await import("@huggingface/transformers");
+  if (!modelCache2.has(model2)) {
+    const generator2 = await pipeline("text-generation", model2, {
+      dtype: "q4f16"
+    });
+    modelCache2.set(model2, generator2);
+  }
+  const generator = modelCache2.get(model2);
+  const messages = formatMessages(instructions, ctx.history);
+  if (schema) {
+    const schemaMsg = messages.find((m) => m.role === "system");
+    const schemaInstructions = [
+      "you must respond with valid JSON matching this schema:",
+      JSON.stringify(schema.schema, null, 2),
+      "respond ONLY with the JSON object, no other text."
+    ].join("\n");
+    if (schemaMsg) {
+      schemaMsg.content += "\n\n" + schemaInstructions;
+    } else {
+      messages.unshift({ role: "system", content: schemaInstructions });
+    }
+  }
+  const output = await generator(messages, {
+    max_new_tokens: 2048,
+    do_sample: false
+  });
+  const generatedMessages = output[0].generated_text;
+  const lastMessage = generatedMessages.at(-1);
+  const content = lastMessage?.content || "";
+  const msg = {
+    role: "assistant",
+    content
+  };
+  if (ctx.stream) {
+    ctx.stream({ type: "content", content });
+  }
+  return {
+    ...ctx,
+    lastResponse: msg,
+    history: [...ctx.history, msg],
+    usage: addUsage(ctx.usage, 0, 0, 0)
+  };
 };
 
 // src/providers/xai.ts
@@ -1110,7 +1206,8 @@ var callXAI = async (config, ctx) => {
   const body = {
     model: model2,
     messages,
-    stream: !!ctx.stream
+    stream: !!ctx.stream,
+    ...ctx.stream && { stream_options: { include_usage: true } }
   };
   if (schema) {
     body.response_format = {
@@ -1155,7 +1252,8 @@ var callXAI = async (config, ctx) => {
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage: addUsage(ctx.usage, data.usage?.prompt_tokens || 0, data.usage?.completion_tokens || 0, data.usage?.total_tokens || 0)
   };
 };
 var handleXAIStream = async (response, ctx) => {
@@ -1164,6 +1262,7 @@ var handleXAIStream = async (response, ctx) => {
   let fullContent = "";
   let toolCalls = [];
   let buffer = "";
+  let streamUsage = null;
   try {
     while (true) {
       if (ctx.abortSignal?.aborted) {
@@ -1181,6 +1280,9 @@ var handleXAIStream = async (response, ctx) => {
           if (!data) continue;
           try {
             const parsed = JSON.parse(data);
+            if (parsed.usage) {
+              streamUsage = parsed.usage;
+            }
             const delta = parsed.choices?.[0]?.delta;
             if (delta?.content) {
               fullContent += delta.content;
@@ -1206,10 +1308,15 @@ var handleXAIStream = async (response, ctx) => {
   if (toolCalls.length > 0) {
     msg.tool_calls = toolCalls;
   }
+  const usage = addUsage(ctx.usage, streamUsage?.prompt_tokens || 0, streamUsage?.completion_tokens || 0, streamUsage?.total_tokens || 0);
+  if (ctx.stream && streamUsage) {
+    ctx.stream({ type: "usage", usage });
+  }
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage
   };
 };
 
@@ -1242,7 +1349,8 @@ var callLocal = async (config, ctx) => {
   const body = {
     model: model2,
     messages,
-    stream: !!ctx.stream
+    stream: !!ctx.stream,
+    ...ctx.stream && { stream_options: { include_usage: true } }
   };
   if (schema) {
     body.response_format = {
@@ -1290,7 +1398,8 @@ var callLocal = async (config, ctx) => {
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage: addUsage(ctx.usage, data.usage?.prompt_tokens || 0, data.usage?.completion_tokens || 0, data.usage?.total_tokens || 0)
   };
 };
 var handleLocalStream = async (response, ctx) => {
@@ -1299,6 +1408,7 @@ var handleLocalStream = async (response, ctx) => {
   let fullContent = "";
   let toolCalls = [];
   let buffer = "";
+  let streamUsage = null;
   try {
     while (true) {
       if (ctx.abortSignal?.aborted) {
@@ -1316,6 +1426,9 @@ var handleLocalStream = async (response, ctx) => {
           if (!data) continue;
           try {
             const parsed = JSON.parse(data);
+            if (parsed.usage) {
+              streamUsage = parsed.usage;
+            }
             const delta = parsed.choices?.[0]?.delta;
             if (delta?.content) {
               fullContent += delta.content;
@@ -1341,10 +1454,15 @@ var handleLocalStream = async (response, ctx) => {
   if (toolCalls.length > 0) {
     msg.tool_calls = toolCalls;
   }
+  const usage = addUsage(ctx.usage, streamUsage?.prompt_tokens || 0, streamUsage?.completion_tokens || 0, streamUsage?.total_tokens || 0);
+  if (ctx.stream && streamUsage) {
+    ctx.stream({ type: "usage", usage });
+  }
   return {
     ...ctx,
     lastResponse: msg,
-    history: [...ctx.history, msg]
+    history: [...ctx.history, msg],
+    usage
   };
 };
 
@@ -1861,6 +1979,7 @@ var scopeContext = (config, ctx) => {
   }
   scopedCtx.stream = ctx.stream;
   scopedCtx.abortSignal = ctx.abortSignal;
+  scopedCtx.usage = ctx.usage;
   if (config.tools) {
     const toolDefinitions = config.tools.map(toolConfigToToolDefinition);
     const toolExecutors = config.tools.reduce(
@@ -1914,7 +2033,8 @@ var scope = (config, ...steps) => {
       history: config.silent ? ctx.history : scopedCtx.history,
       lastResponse: config.silent ? ctx.lastResponse : scopedCtx.lastResponse,
       lastRequest: config.silent ? ctx.lastRequest : scopedCtx.lastRequest,
-      stopReason: config.silent ? ctx.stopReason : scopedCtx.stopReason
+      stopReason: config.silent ? ctx.stopReason : scopedCtx.stopReason,
+      usage: scopedCtx.usage
     };
   };
 };
@@ -1976,6 +2096,7 @@ var rateLimited = (config) => (fn) => {
   IMAGE_EDIT_MODEL_SCHEMA,
   IMAGE_MODEL_SCHEMA,
   Inherit,
+  addUsage,
   appendToLastRequest,
   compose,
   convertMCPSchemaToToolSchema,