@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/lib/tools-builder.ts

@@ -0,0 +1,192 @@
+import { DynamicStructuredTool } from '@langchain/core/tools'
+import { z } from 'zod'
+
+export interface ToolDefinition<T extends z.ZodObject<z.ZodRawShape>> {
+    name: string
+    description: string
+    schema: T
+    func: (input: z.infer<T>) => Promise<string>
+}
+
+/**
+ * Get the Zod type name for a field (Zod v4 compatible)
+ */
+function getZodTypeName(zodField: z.ZodTypeAny): string {
+    // Zod v4: use _zod.def.type
+    const zodDef = (zodField as unknown as { _zod?: { def?: { type?: string } } })._zod
+    if (zodDef?.def?.type) {
+        return zodDef.def.type
+    }
+    // Fallback for edge cases
+    return 'unknown'
+}
+
+/**
+ * Get the inner type for optional/array types (Zod v4 compatible)
+ */
+function getInnerType(zodField: z.ZodTypeAny): z.ZodTypeAny | null {
+    const zodDef = (zodField as unknown as { _zod?: { def?: { innerType?: z.ZodTypeAny; element?: z.ZodTypeAny } } })._zod
+    // For optional types
+    if (zodDef?.def?.innerType) {
+        return zodDef.def.innerType
+    }
+    // For array types
+    if (zodDef?.def?.element) {
+        return zodDef.def.element
+    }
+    return null
+}
+
+/**
+ * Get enum values (Zod v4 compatible)
+ */
+function getEnumValues(zodField: z.ZodTypeAny): string[] | null {
+    const zodDef = (zodField as unknown as { _zod?: { def?: { entries?: Record<string, string> } } })._zod
+    if (zodDef?.def?.entries) {
+        return Object.values(zodDef.def.entries)
+    }
+    return null
+}
+
+/**
+ * Convert Zod schema to JSON Schema with explicit type: "object"
+ * LM Studio requires type: "object" at root level which zodToJsonSchema sometimes omits
+ *
+ * Zod v4 compatible implementation
+ */
+export function zodToOpenAISchema(zodSchema: z.ZodObject<z.ZodRawShape>): Record<string, unknown> {
+    const shape = zodSchema.shape
+    const properties: Record<string, unknown> = {}
+    const required: string[] = []
+
+    for (const [key, value] of Object.entries(shape)) {
+        const zodField = value as z.ZodTypeAny
+        const fieldSchema: Record<string, unknown> = {}
+
+        // Get the description if available (Zod v4 uses .description property)
+        const description = (zodField as unknown as { description?: string }).description
+        if (description) {
+            fieldSchema.description = description
+        }
+
+        // Get the type name using Zod v4 API
+        const typeName = getZodTypeName(zodField)
+
+        // Handle different Zod types
+        switch (typeName) {
+            case 'string':
+                fieldSchema.type = 'string'
+                break
+            case 'number':
+                fieldSchema.type = 'number'
+                break
+            case 'boolean':
+                fieldSchema.type = 'boolean'
+                break
+            case 'array': {
+                fieldSchema.type = 'array'
+                const elementType = getInnerType(zodField)
+                if (elementType) {
+                    const elementTypeName = getZodTypeName(elementType)
+                    if (elementTypeName === 'object') {
+                        fieldSchema.items = zodToOpenAISchema(elementType as z.ZodObject<z.ZodRawShape>)
+                    } else if (elementTypeName === 'string') {
+                        fieldSchema.items = { type: 'string' }
+                    } else {
+                        fieldSchema.items = { type: 'string' } // default fallback
+                    }
+                } else {
+                    fieldSchema.items = { type: 'string' } // default fallback
+                }
+                break
+            }
+            case 'object':
+                Object.assign(fieldSchema, zodToOpenAISchema(zodField as z.ZodObject<z.ZodRawShape>))
+                break
+            case 'optional': {
+                // Handle optional - get inner type
+                const innerType = getInnerType(zodField)
+                if (innerType) {
+                    const innerTypeName = getZodTypeName(innerType)
+                    if (innerTypeName === 'string') {
+                        fieldSchema.type = 'string'
+                    } else if (innerTypeName === 'number') {
+                        fieldSchema.type = 'number'
+                    } else if (innerTypeName === 'boolean') {
+                        fieldSchema.type = 'boolean'
+                    } else {
+                        fieldSchema.type = 'string'
+                    }
+                } else {
+                    fieldSchema.type = 'string'
+                }
+                break
+            }
+            case 'enum': {
+                fieldSchema.type = 'string'
+                const enumValues = getEnumValues(zodField)
+                if (enumValues) {
+                    fieldSchema.enum = enumValues
+                }
+                break
+            }
+            default:
+                // Default to string for unknown types
+                fieldSchema.type = 'string'
+        }
+
+        properties[key] = fieldSchema
+
+        // Check if required (not optional)
+        if (typeName !== 'optional') {
+            required.push(key)
+        }
+    }
+
+    return {
+        type: 'object',
+        properties,
+        required: required.length > 0 ? required : undefined,
+    }
+}
+
+/**
+ * Convert tool definitions to OpenAI tool format with proper type: "object"
+ * Use this for LM Studio compatibility
+ */
+export function convertToOpenAITools(definitions: ToolDefinition<z.ZodObject<z.ZodRawShape>>[]): Array<{
+    type: 'function'
+    function: {
+        name: string
+        description: string
+        parameters: Record<string, unknown>
+    }
+}> {
+    return definitions.map(def => ({
+        type: 'function' as const,
+        function: {
+            name: def.name,
+            description: def.description,
+            parameters: zodToOpenAISchema(def.schema),
+        },
+    }))
+}
+
+/**
+ * Create a LangChain tool from a definition
+ */
+export function createTool<T extends z.ZodObject<z.ZodRawShape>>(def: ToolDefinition<T>) {
+    return new DynamicStructuredTool({
+        name: def.name,
+        description: def.description,
+        schema: def.schema,
+        func: def.func,
+    })
+}
+
+/**
+ * Build multiple tools from definitions
+ */
+export function buildTools(definitions: ToolDefinition<z.ZodObject<z.ZodRawShape>>[]) {
+    return definitions.map(createTool)
+}

package/lib/tracer-callbacks.ts

@@ -0,0 +1,342 @@
+/**
+ * LangChain Tracing Callback Handler
+ *
+ * Captures LangChain events (LLM calls, tool executions, chain steps)
+ * and creates spans for observability.
+ */
+
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base'
+import type { Serialized } from '@langchain/core/load/serializable'
+import { tracer } from './tracer'
+import type { SpanContext } from '../types/observability.types'
+
+interface TracingCallbackHandlerOptions {
+  context: { userId: string; teamId: string }
+  traceId: string
+  /** Model name to use when LangChain doesn't provide it in callbacks */
+  modelName?: string
+}
+
+/**
+ * Callback handler that creates spans for LangChain events
+ */
+export class TracingCallbackHandler extends BaseCallbackHandler {
+  name = 'tracing_callback_handler'
+
+  private context: { userId: string; teamId: string }
+  private traceId: string
+  private spans: Map<string, SpanContext>
+  private parentSpans: Map<string, string>
+  private modelName?: string
+
+  // Counters for LLM and tool calls
+  private _llmCallCount = 0
+  private _toolCallCount = 0
+
+  // Track pending async operations to ensure all callbacks complete
+  private pendingOperations: Promise<void>[] = []
+
+  constructor(options: TracingCallbackHandlerOptions) {
+    super()
+    this.context = options.context
+    this.traceId = options.traceId
+    this.modelName = options.modelName
+    this.spans = new Map()
+    this.parentSpans = new Map()
+  }
+
+  /**
+   * Track an async operation for later flushing
+   */
+  private trackOperation(promise: Promise<void>): void {
+    this.pendingOperations.push(promise)
+    // Clean up completed promises periodically
+    promise.finally(() => {
+      const index = this.pendingOperations.indexOf(promise)
+      if (index > -1) {
+        this.pendingOperations.splice(index, 1)
+      }
+    })
+  }
+
+  /**
+   * Wait for all pending operations to complete
+   * Call this before getCounts() to ensure accurate counts
+   */
+  async flush(): Promise<void> {
+    // Wait for all pending operations with a timeout
+    const timeout = new Promise<void>((resolve) => setTimeout(resolve, 5000))
+    await Promise.race([
+      Promise.all(this.pendingOperations),
+      timeout,
+    ])
+  }
+
+  /**
+   * Get the count of LLM and tool calls
+   */
+  getCounts(): { llmCalls: number; toolCalls: number } {
+    return {
+      llmCalls: this._llmCallCount,
+      toolCalls: this._toolCallCount,
+    }
+  }
+
+  /**
+   * LLM Events
+   */
+
+  async handleLLMStart(
+    llm: Serialized,
+    prompts: string[],
+    runId: string,
+    parentRunId?: string
+  ): Promise<void> {
+    const operation = (async () => {
+      try {
+        const provider = llm.id?.[llm.id.length - 1] || 'unknown'
+        // Extract model name from various possible locations (expanded for Ollama compatibility)
+        const llmAny = llm as any
+
+        const model =
+          // Standard locations
+          llmAny.kwargs?.model ||
+          llmAny.kwargs?.model_name ||
+          llmAny.kwargs?.modelName ||
+          llmAny.kwargs?.model_id ||
+          llmAny.model ||
+          llmAny.model_name ||
+          llmAny.modelName ||
+          // Ollama-specific locations
+          llmAny.kwargs?.configuration?.model ||
+          llmAny.kwargs?.options?.model ||
+          llmAny.lc_kwargs?.model ||
+          // ChatOllama specific
+          llmAny.kwargs?.base_url && llmAny.kwargs?.model ||
+          // Last resort: try to extract from id array
+          (Array.isArray(llm.id) && llm.id.find((id: string) => id.includes(':') || id.includes('-'))) ||
+          // Use model name passed from config (fallback for providers like Ollama)
+          this.modelName ||
+          'unknown'
+        const depth = parentRunId ? (this.spans.get(parentRunId)?.depth || 0) + 1 : 0
+
+        const spanContext = await tracer.startSpan(this.context, this.traceId, {
+          name: `LLM: ${model}`,
+          type: 'llm',
+          provider,
+          model,
+          parentSpanId: parentRunId ? this.parentSpans.get(parentRunId) : undefined,
+          depth,
+          input: { prompts },
+        })
+
+        if (spanContext) {
+          this.spans.set(runId, spanContext)
+          if (parentRunId) {
+            this.parentSpans.set(runId, spanContext.spanId)
+          }
+        }
+      } catch (error) {
+        console.error('[TracingCallbackHandler] handleLLMStart error:', error)
+      }
+    })()
+    this.trackOperation(operation)
+    await operation
+  }
+
+  async handleLLMEnd(output: any, runId: string): Promise<void> {
+    // Increment counter immediately (synchronously) to avoid race condition
+    this._llmCallCount++
+
+    const operation = (async () => {
+      try {
+        const spanContext = this.spans.get(runId)
+        if (!spanContext) return
+
+        // Extract token usage from output
+        const usage = output.llmOutput?.tokenUsage || {}
+        const tokens = {
+          input: usage.promptTokens || usage.input_tokens || 0,
+          output: usage.completionTokens || usage.output_tokens || 0,
+        }
+
+        await tracer.endSpan(this.context, this.traceId, spanContext.spanId, {
+          output: {
+            generations: output.generations?.map((gen: any) => gen.text || gen.message?.content),
+          },
+          tokens: tokens.input || tokens.output ? tokens : undefined,
+        })
+
+        this.spans.delete(runId)
+        this.parentSpans.delete(runId)
+      } catch (error) {
+        console.error('[TracingCallbackHandler] handleLLMEnd error:', error)
+      }
+    })()
+    this.trackOperation(operation)
+  }
+
+  async handleLLMError(error: Error, runId: string): Promise<void> {
+    try {
+      const spanContext = this.spans.get(runId)
+      if (!spanContext) return
+
+      await tracer.endSpan(this.context, this.traceId, spanContext.spanId, {
+        error,
+      })
+
+      this.spans.delete(runId)
+      this.parentSpans.delete(runId)
+    } catch (err) {
+      console.error('[TracingCallbackHandler] handleLLMError error:', err)
+    }
+  }
+
+  /**
+   * Tool Events
+   */
+
+  async handleToolStart(
+    tool: Serialized,
+    input: string,
+    runId: string,
+    parentRunId?: string
+  ): Promise<void> {
+    try {
+      const toolName = tool.id?.[tool.id.length - 1] || 'unknown'
+      const depth = parentRunId ? (this.spans.get(parentRunId)?.depth || 0) + 1 : 0
+
+      const spanContext = await tracer.startSpan(this.context, this.traceId, {
+        name: `Tool: ${toolName}`,
+        type: 'tool',
+        toolName,
+        parentSpanId: parentRunId ? this.parentSpans.get(parentRunId) : undefined,
+        depth,
+        input: { toolInput: input },
+      })
+
+      if (spanContext) {
+        this.spans.set(runId, spanContext)
+        if (parentRunId) {
+          this.parentSpans.set(runId, spanContext.spanId)
+        }
+      }
+    } catch (error) {
+      console.error('[TracingCallbackHandler] handleToolStart error:', error)
+    }
+  }
+
+  async handleToolEnd(output: string, runId: string): Promise<void> {
+    // Increment counter immediately (synchronously) to avoid race condition
+    this._toolCallCount++
+
+    const operation = (async () => {
+      try {
+        const spanContext = this.spans.get(runId)
+        if (!spanContext) return
+
+        await tracer.endSpan(this.context, this.traceId, spanContext.spanId, {
+          toolOutput: output,
+        })
+
+        this.spans.delete(runId)
+        this.parentSpans.delete(runId)
+      } catch (error) {
+        console.error('[TracingCallbackHandler] handleToolEnd error:', error)
+      }
+    })()
+    this.trackOperation(operation)
+  }
+
+  async handleToolError(error: Error, runId: string): Promise<void> {
+    try {
+      const spanContext = this.spans.get(runId)
+      if (!spanContext) return
+
+      await tracer.endSpan(this.context, this.traceId, spanContext.spanId, {
+        error,
+      })
+
+      this.spans.delete(runId)
+      this.parentSpans.delete(runId)
+    } catch (err) {
+      console.error('[TracingCallbackHandler] handleToolError error:', err)
+    }
+  }
+
+  /**
+   * Chain Events
+   */
+
+  async handleChainStart(
+    chain: Serialized,
+    inputs: Record<string, unknown>,
+    runId: string,
+    parentRunId?: string
+  ): Promise<void> {
+    try {
+      const chainName = chain.id?.[chain.id.length - 1] || 'unknown'
+      const depth = parentRunId ? (this.spans.get(parentRunId)?.depth || 0) + 1 : 0
+
+      const spanContext = await tracer.startSpan(this.context, this.traceId, {
+        name: `Chain: ${chainName}`,
+        type: 'chain',
+        parentSpanId: parentRunId ? this.parentSpans.get(parentRunId) : undefined,
+        depth,
+        input: inputs,
+      })
+
+      if (spanContext) {
+        this.spans.set(runId, spanContext)
+        if (parentRunId) {
+          this.parentSpans.set(runId, spanContext.spanId)
+        }
+      }
+    } catch (error) {
+      console.error('[TracingCallbackHandler] handleChainStart error:', error)
+    }
+  }
+
+  async handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void> {
+    try {
+      const spanContext = this.spans.get(runId)
+      if (!spanContext) return
+
+      await tracer.endSpan(this.context, this.traceId, spanContext.spanId, {
+        output: outputs,
+      })
+
+      this.spans.delete(runId)
+      this.parentSpans.delete(runId)
+    } catch (error) {
+      console.error('[TracingCallbackHandler] handleChainEnd error:', error)
+    }
+  }
+
+  async handleChainError(error: Error, runId: string): Promise<void> {
+    try {
+      const spanContext = this.spans.get(runId)
+      if (!spanContext) return
+
+      await tracer.endSpan(this.context, this.traceId, spanContext.spanId, {
+        error,
+      })
+
+      this.spans.delete(runId)
+      this.parentSpans.delete(runId)
+    } catch (err) {
+      console.error('[TracingCallbackHandler] handleChainError error:', err)
+    }
+  }
+}
+
+/**
+ * Factory function to create tracing callbacks
+ */
+export function createTracingCallbacks(
+  context: { userId: string; teamId: string },
+  traceId: string,
+  modelName?: string
+): TracingCallbackHandler {
+  return new TracingCallbackHandler({ context, traceId, modelName })
+}