@friskai/frisk-js 0.3.0 → 0.3.1

package/dist/adapters/langchain/frisk-callback-handler.d.ts

@@ -1,5 +1,7 @@
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import type { Serialized } from '@langchain/core/load/serializable';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { LLMResult } from '@langchain/core/outputs';
 import type { ChainValues } from '@langchain/core/utils/types';
 import { FriskSession } from '../../core/frisk-session';
 import { FriskSDKLoggingOptions } from '../../logging';
@@ -10,7 +12,12 @@ export type LangchainToolCallStatus = 'error' | 'success';
  *
  * This handler integrates with LangChain's callback system to automatically
  * manage tracing spans for Frisk sessions. It initializes tracing when a
- * root chain starts and ends tracing when the root chain completes.
+ * root chain starts and ends tracing when the root chain completes, and opens
+ * operation, LLM-call, and tool-call spans for the runs nested under it.
+ *
+ * Every span is keyed by the LangChain run id that owns it, so a child span
+ * nests under whatever span its `parentRunId` owns rather than all hanging off
+ * the session root.
  *
  * @example
  * ```typescript
@@ -33,6 +40,7 @@ export declare class FriskCallbackHandler extends BaseCallbackHandler {
     name: string;
     private session;
     private spansByRunId;
+    private llmCallSpanIdByToolCallId;
     private frisk;
     private logger;
     constructor({ session, frisk, logging, }: {
@@ -42,7 +50,10 @@ export declare class FriskCallbackHandler extends BaseCallbackHandler {
     });
     /**
      * Called at the start of a Chain run.
-     * Initializes tracing for root chains (those without a parent).
+     *
+     * Root chains (no parent) initialize tracing; nested chains open an operation
+     * span parented under their parent run's span. Either way the resulting span
+     * is registered by run id.
      *
      * NOTE: The official documentation and source code types state that `parentRunId` is the 8th argument to this method, but this isn't true.
      * In practice, `parentRunId` is the 4th argument. This may be a documentation bug or an issue with the types, but we need to use the correct argument position to get the parent run ID.
@@ -50,14 +61,80 @@ export declare class FriskCallbackHandler extends BaseCallbackHandler {
     handleChainStart(_chain: Serialized, inputs: ChainValues, runId: string, parentRunId?: string): void;
     /**
      * Called at the end of a Chain run.
-     * Ends tracing when the root chain completes.
+     *
+     * Ends tracing when the root chain completes (closing any spans still open
+     * and clearing the registries); otherwise ends the operation span for the run.
      */
     handleChainEnd(_outputs: ChainValues, runId: string, _parentRunId?: string, _tags?: string[], _kwargs?: {
         inputs?: Record<string, unknown>;
     }): void;
+    /**
+     * Called at the start of a Chat Model run. Opens an LLM call span and records
+     * the prompt messages it is being asked to respond to.
+     */
+    handleChatModelStart(_llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string): void;
+    /**
+     * Called at the start of a (completion) LLM run. Opens an LLM call span and
+     * records the raw prompt strings.
+     */
+    handleLLMStart(_llm: Serialized, prompts: string[], runId: string, parentRunId?: string): void;
+    /**
+     * Called at the end of an LLM/Chat Model run. Records responses and requested
+     * tool calls, then closes the LLM call span.
+     */
+    handleLLMEnd(output: LLMResult, runId: string): void;
+    /**
+     * Called when an LLM/Chat Model run errors. Records the error, then closes the
+     * LLM call span.
+     */
+    handleLLMError(err: Error, runId: string): void;
     handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleToolEnd(output: any, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
     handleToolError(err: Error, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
+    /**
+     * Return the span tracked for `parentRunId`, or null when there isn't one.
+     *
+     * Because every span (session root included) is registered by its run id, a
+     * child created under `parentRunId` nests under whatever span that run owns.
+     * Null lets the session fall back to the root span.
+     */
+    private resolveParentSpan;
+    /**
+     * Open (or return the existing) LLM call span for `runId`, parented under its
+     * parent run's span. Closed at handleLLMEnd/handleLLMError.
+     */
+    private openLlmCallSpan;
+    /**
+     * `JSON.stringify` that never throws out of a callback. On failure (circular
+     * structures, BigInt values, etc.) it reports via `captureError` and returns
+     * null so the attribute is simply omitted rather than breaking the host
+     * LangChain run.
+     */
+    private safeJsonStringify;
+    /**
+     * Collect the trailing prompt messages from the most recent message batch.
+     *
+     * Walks the last message list backwards, collecting each message until (and
+     * excluding) the last AIMessage (`type === "ai"`) — i.e. everything the model
+     * is being asked to respond to since its previous turn, including any
+     * ToolMessage results. Returns them in chronological order as `{type, content}`
+     * objects; ToolMessage entries additionally carry a `metadata` field of
+     * `{tool_name, tool_call_id}`.
+     */
+    private getPromptMessages;
+    /**
+     * Record responses and announced tool calls on the LLM call span for `runId`,
+     * then end it. Shared by handleLLMEnd and handleLLMError; `err` is recorded on
+     * the span before it ends.
+     */
+    private finalizeLlmCall;
+    /**
+     * Stamp a tool-call span with the span id of the LLM call that announced it,
+     * then drop the mapping entry so it doesn't grow unbounded over a session.
+     */
+    private stampLlmCallSpanId;
+    /** Pop the span for `runId` from the registry and end it. */
+    private endSpan;
     private closeToolCallSpan;
 }
 //# sourceMappingURL=frisk-callback-handler.d.ts.map

package/dist/adapters/langchain/frisk-callback-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frisk-callback-handler.d.ts","sourceRoot":"","sources":["../../../src/adapters/langchain/frisk-callback-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAkB,MAAM,0BAA0B,CAAA;AAEvE,OAAO,EAEL,sBAAsB,EAEvB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAqB,SAAQ,mBAAmB;IAC3D,IAAI,SAAyB;IAE7B,OAAO,CAAC,OAAO,CAAc;IAE7B,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,MAAM,CAAW;gBAEb,EACV,OAAO,EACP,KAAK,EACL,OAAO,GACR,EAAE;QACD,OAAO,EAAE,YAAY,CAAA;QACrB,KAAK,EAAE,cAAc,CAAA;QACrB,OAAO,CAAC,EAAE,sBAAsB,CAAA;KACjC;IAWD;;;;;;OAMG;IACH,gBAAgB,CACd,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI;IAUP;;;OAGG;IACH,cAAc,CACZ,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACjC,GACA,IAAI;IAOD,eAAe,CACnB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAiCV,aAAa,CACjB,MAAM,EAAE,GAAG,EACX,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,IAAI,CAAC;IAuBV,eAAe,CACnB,GAAG,EAAE,KAAK,EACV,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,IAAI,CAAC;IAqBhB,OAAO,CAAC,iBAAiB;CAwB1B"}
+{"version":3,"file":"frisk-callback-handler.d.ts","sourceRoot":"","sources":["../../../src/adapters/langchain/frisk-callback-handler.ts"],"names":[],"mappings":"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"}