@bitfab/sdk 0.25.0 → 0.26.0

package/dist/index.cjs

@@ -587,7 +587,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.generated.ts
-var __version__ = "0.25.0";
+var __version__ = "0.26.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -4093,10 +4093,105 @@ var BitfabFunction = class {
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     return this.client.withSpan(this.traceFunctionKey, options, fn);
   }
+  /**
+   * Get a Vercel AI SDK language-model middleware bound to this function's key.
+   *
+   * Equivalent to `client.getVercelAiMiddleware(key)` but reuses the key bound
+   * on this handle, so an outer `withSpan` root and the middleware-traced model
+   * calls share one key without repeating the string. With a matching key, the
+   * outer span is the replayable root and the model-call spans nest beneath it.
+   *
+   * Nesting is captured when the model is called, so keep the
+   * `generateText` / `streamText` call inside this handle's `withSpan`; the
+   * middleware object itself can be created anywhere.
+   *
+   * ```typescript
+   * const chatTurn = client.getFunction("chat-turn");
+   * const runChatTurn = chatTurn.withSpan(
+   *   { type: "agent", finalize: finalizers.aiSdk },
+   *   (messages) => streamText({ model, messages }),
+   * );
+   * const model = wrapLanguageModel({
+   *   model: openai("gpt-4o"),
+   *   middleware: chatTurn.getVercelAiMiddleware(),
+   * });
+   * ```
+   *
+   * @returns A Vercel AI SDK middleware configured for this client and key
+   */
+  getVercelAiMiddleware() {
+    return this.client.getVercelAiMiddleware(this.traceFunctionKey);
+  }
+  /**
+   * Get a Claude Agent SDK handler bound to this function's key.
+   *
+   * Equivalent to `client.getClaudeAgentHandler(key)` but reuses the key bound
+   * on this handle, so an outer `withSpan` root and the handler share one key
+   * without repeating the string. With a matching key, the outer span is the
+   * replayable root and every handler span nests beneath it.
+   *
+   * Use the handler inside this handle's `withSpan` body so its spans capture
+   * the enclosing root; framework calls made with no active span record their
+   * own root instead.
+   *
+   * ```typescript
+   * const pipeline = client.getFunction("my-agent");
+   * const tracedRun = pipeline.withSpan({ type: "agent" }, async (prompt) => {
+   *   const handler = pipeline.getClaudeAgentHandler();
+   *   const options = handler.instrumentOptions({ model: "claude-sonnet-4-6" });
+   *   for await (const msg of handler.wrapQuery(query({ prompt, options }))) { ... }
+   * });
+   * ```
+   *
+   * @returns A Claude Agent SDK handler configured for this client and key
+   */
+  getClaudeAgentHandler() {
+    return this.client.getClaudeAgentHandler(this.traceFunctionKey);
+  }
+  /**
+   * Get a LangGraph/LangChain callback handler bound to this function's key.
+   *
+   * Equivalent to `client.getLangGraphCallbackHandler(key)` but reuses the key
+   * bound on this handle, so an outer `withSpan` root and the handler share one
+   * key without repeating the string. With a matching key, the outer span is
+   * the replayable root and the LangGraph spans nest beneath it.
+   *
+   * Use the handler inside this handle's `withSpan` body so its spans capture
+   * the enclosing root; framework calls made with no active span record their
+   * own root instead.
+   *
+   * ```typescript
+   * const pipeline = client.getFunction("my-pipeline");
+   * const tracedRun = pipeline.withSpan({ type: "agent" }, async (query) => {
+   *   const handler = pipeline.getLangGraphCallbackHandler();
+   *   return agent.invoke({ messages: [...] }, { callbacks: [handler] });
+   * });
+   * ```
+   *
+   * @returns A LangGraph/LangChain callback handler for this client and key
+   */
+  getLangGraphCallbackHandler() {
+    return this.client.getLangGraphCallbackHandler(this.traceFunctionKey);
+  }
+  /**
+   * Alias of {@link getLangGraphCallbackHandler} — LangChain and LangGraph
+   * share one callback system, so the same bound handler serves both.
+   *
+   * @returns A LangChain callback handler for this client and key
+   */
+  getLangChainCallbackHandler() {
+    return this.client.getLangChainCallbackHandler(this.traceFunctionKey);
+  }
   /**
    * Wrap a BAML client method to automatically capture prompt and LLM metadata.
    * Delegates to the parent client's wrapBAML method.
    *
+   * Unlike the other methods on this handle, `wrapBAML` does NOT use the bound
+   * key: it opens no span of its own. It enriches the *current* span (via
+   * `getCurrentSpan().setPrompt()` / `addContext()`), so call it inside a
+   * function wrapped by this handle's `withSpan` — the bound key keys that
+   * wrapper, and the BAML prompt/metadata attach to it.
+   *
    * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
    * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
    * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form