@struktur/sdk 2.0.0 → 2.1.0

package/src/strategies/utils.ts

@@ -1,4 +1,4 @@
-import type { Artifact, ExtractionEvents, Usage } from "../types";
+import type { Artifact, ExtractionEvents, Usage, TelemetryAdapter } from "../types";
 import type { DebugLogger } from "../debug/logger";
 import { batchArtifacts, type BatchOptions } from "../chunking/ArtifactBatcher";
 import { buildUserContent } from "../llm/message";
@@ -22,9 +22,44 @@ export const mergeUsage = (usages: Usage[]) => {
 export const getBatches = (
   artifacts: Artifact[],
   options: BatchOptions,
-  debug?: DebugLogger
+  debug?: DebugLogger,
+  telemetry?: TelemetryAdapter,
+  parentSpan?: { id: string; traceId: string; name: string; kind: string; startTime: number; parentId?: string }
 ) => {
-  return batchArtifacts(artifacts, { ...options, debug });
+  // Create chunking span if telemetry is enabled
+  const chunkingSpan = telemetry?.startSpan({
+    name: "struktur.chunking",
+    kind: "RETRIEVER",
+    parentSpan,
+    attributes: {
+      "chunking.artifact_count": artifacts.length,
+      "chunking.max_tokens": options.maxTokens,
+      "chunking.max_images": options.maxImages,
+    },
+  });
+  
+  const batches = batchArtifacts(artifacts, { ...options, debug });
+  
+  // Record chunking results
+  if (chunkingSpan && telemetry) {
+    batches.forEach((batch, index) => {
+      telemetry.recordEvent(chunkingSpan, {
+        type: "chunk",
+        chunkIndex: index,
+        totalChunks: batches.length,
+        tokens: batch.reduce((sum, a) => sum + (a.tokens || 0), 0),
+        images: batch.reduce((sum, a) => 
+          sum + (a.contents?.flatMap((c) => c.media || []).length || 0), 0),
+      });
+    });
+    
+    telemetry.endSpan(chunkingSpan, {
+      status: "ok",
+      output: { batchCount: batches.length },
+    });
+  }
+  
+  return batches;
 };
 
 export const extractWithPrompt = async <T>(options: {
@@ -38,6 +73,8 @@ export const extractWithPrompt = async <T>(options: {
   strict?: boolean;
   debug?: DebugLogger;
   callId?: string;
+  telemetry?: TelemetryAdapter;
+  parentSpan?: { id: string; traceId: string; name: string; kind: string; startTime: number; parentId?: string };
 }) => {
   const userContent = buildUserContent(options.user, options.artifacts);
   const result = await runWithRetries<T>({
@@ -50,6 +87,8 @@ export const extractWithPrompt = async <T>(options: {
     strict: options.strict,
     debug: options.debug,
     callId: options.callId,
+    telemetry: options.telemetry,
+    parentSpan: options.parentSpan,
   });
 
   return result;

package/src/types.ts

@@ -45,6 +45,29 @@ export type ExtractionResult<T> = {
   error?: Error;
 };
 
+/**
+ * Telemetry adapter interface for tracing extraction operations.
+ * This is a minimal interface that matches the full TelemetryAdapter from @struktur/telemetry.
+ * SDK users should import adapters from @struktur/telemetry package.
+ */
+export interface TelemetryAdapter {
+  readonly name: string;
+  readonly version: string;
+  initialize(): Promise<void>;
+  shutdown(): Promise<void>;
+  startSpan(context: {
+    name: string;
+    kind: "CHAIN" | "LLM" | "TOOL" | "AGENT" | "RETRIEVER" | "EMBEDDING" | "RERANKER";
+    parentSpan?: { id: string; traceId: string };
+    attributes?: Record<string, unknown>;
+    startTime?: number;
+  }): { id: string; traceId: string; name: string; kind: string; startTime: number; parentId?: string };
+  endSpan(span: { id: string }, result?: { status: "ok" | "error"; error?: Error; output?: unknown; latencyMs?: number }): void;
+  recordEvent(span: { id: string }, event: unknown): void;
+  setAttributes(span: { id: string }, attributes: Record<string, unknown>): void;
+  setContext(context: { sessionId?: string; userId?: string; metadata?: Record<string, unknown>; tags?: string[] }): void;
+}
+
 export type StepInfo = {
   step: number;
   total?: number;
@@ -68,19 +91,47 @@ export type TokenUsageInfo = Usage & {
 };
 
 export type RetryInfo = {
-  attempt: number;
-  maxAttempts: number;
-  reason?: string;
+	attempt: number;
+	maxAttempts: number;
+	reason?: string;
 };
 
-export type ExtractionEvents = {
-  onStep?: (info: StepInfo) => void | Promise<void>;
-  onMessage?: (info: MessageInfo) => void | Promise<void>;
-  onProgress?: (info: ProgressInfo) => void | Promise<void>;
-  onTokenUsage?: (info: TokenUsageInfo) => void | Promise<void>;
-  onRetry?: (info: RetryInfo) => void | Promise<void>;
+export type AgentToolStartInfo = {
+	toolName: string;
+	toolCallId: string;
+	args: Record<string, unknown>;
+};
+
+export type AgentToolEndInfo = {
+	toolCallId: string;
+	result?: Record<string, unknown>;
+	error?: string;
+};
+
+export type AgentMessageInfo = {
+	content: string;
+	role?: "assistant" | "user";
 };
 
+export type AgentReasoningInfo = {
+	thought: string;
+};
+
+export type AgentEvents = {
+	onAgentToolStart?: (info: AgentToolStartInfo) => void | Promise<void>;
+	onAgentToolEnd?: (info: AgentToolEndInfo) => void | Promise<void>;
+	onAgentMessage?: (info: AgentMessageInfo) => void | Promise<void>;
+	onAgentReasoning?: (info: AgentReasoningInfo) => void | Promise<void>;
+};
+
+export type ExtractionEvents = {
+	onStep?: (info: StepInfo) => void | Promise<void>;
+	onMessage?: (info: MessageInfo) => void | Promise<void>;
+	onProgress?: (info: ProgressInfo) => void | Promise<void>;
+	onTokenUsage?: (info: TokenUsageInfo) => void | Promise<void>;
+	onRetry?: (info: RetryInfo) => void | Promise<void>;
+} & AgentEvents;
+
 export type AnyJSONSchema = Record<string, unknown>;
 export type TypedJSONSchema<T> = JSONSchemaType<T>;
 
@@ -108,6 +159,12 @@ export type ExtractionOptions<T> = {
   events?: ExtractionEvents;
   debug?: DebugLogger;
   strict?: boolean;
+  /**
+   * Telemetry adapter for tracing extraction operations.
+   * Supports Phoenix (Arize), Langfuse, and other OpenTelemetry-compatible providers.
+   * Import from `@struktur/telemetry` package and pass the adapter here.
+   */
+  telemetry?: TelemetryAdapter | null;
 }
 
 export interface ExtractionStrategy<T> {