@threaded/ai 1.0.26 → 1.0.27

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

@@ -1111,10 +1111,61 @@ var handleGoogleStream = async (response, ctx) => {
 };
 
 // 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