@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/lib/tracer.ts

@@ -0,0 +1,350 @@
+/**
+ * LangChain Tracer Service
+ *
+ * Core tracing service for LangChain agent observability.
+ * Tracks traces (agent invocations) and spans (individual operations).
+ */
+
+import { randomUUID } from 'crypto'
+import { queryWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db'
+import type {
+  ObservabilityConfig,
+  TraceContext,
+  SpanContext,
+  StartTraceOptions,
+  EndTraceOptions,
+  StartSpanOptions,
+  EndSpanOptions,
+  ContentType,
+} from '../types/observability.types'
+
+/**
+ * Tracer service singleton
+ */
+class Tracer {
+  private config: ObservabilityConfig | null = null
+
+  /**
+   * Initialize tracer with configuration
+   * MUST be called by theme before using tracer
+   */
+  init(config: ObservabilityConfig): void {
+    this.config = config
+  }
+
+  /**
+   * Check if tracer has been initialized
+   */
+  isInitialized(): boolean {
+    return this.config !== null
+  }
+
+  /**
+   * Check if tracing should occur based on configuration
+   * Considers enabled flag and sampling rate
+   */
+  shouldTrace(isError = false): boolean {
+    if (!this.config) {
+      return false
+    }
+
+    if (!this.config.enabled) {
+      return false
+    }
+
+    // Always trace errors if configured
+    if (isError && this.config.sampling.alwaysTraceErrors) {
+      return true
+    }
+
+    // Apply sampling rate
+    return Math.random() < this.config.sampling.rate
+  }
+
+  /**
+   * Start a new trace
+   */
+  async startTrace(
+    context: { userId: string; teamId: string },
+    agentName: string,
+    input: string,
+    options?: StartTraceOptions
+  ): Promise<TraceContext | null> {
+    if (!this.shouldTrace()) {
+      return null
+    }
+
+    const traceId = randomUUID()
+    const processedInput = this.processContent(input, 'input')
+
+    try {
+      await mutateWithRLS(
+        `INSERT INTO public."langchain_traces" (
+          "traceId",
+          "userId",
+          "teamId",
+          "sessionId",
+          "agentName",
+          "agentType",
+          "parentId",
+          input,
+          status,
+          metadata,
+          tags,
+          "startedAt"
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, now())`,
+        [
+          traceId,
+          context.userId,
+          context.teamId,
+          options?.sessionId || null,
+          agentName,
+          options?.agentType || null,
+          options?.parentId || null,
+          processedInput,
+          'running',
+          JSON.stringify(options?.metadata || {}),
+          options?.tags || [],
+        ],
+        context.userId
+      )
+
+      return {
+        traceId,
+        userId: context.userId,
+        teamId: context.teamId,
+        sessionId: options?.sessionId,
+        agentName,
+      }
+    } catch (error) {
+      console.error('[Tracer] Failed to start trace:', error)
+      return null
+    }
+  }
+
+  /**
+   * End a trace
+   */
+  async endTrace(
+    context: { userId: string; teamId: string },
+    traceId: string,
+    options: EndTraceOptions
+  ): Promise<void> {
+    try {
+      const status = options.error ? 'error' : 'success'
+      const processedOutput = options.output
+        ? this.processContent(options.output, 'output')
+        : null
+
+      // Extract error details
+      let errorMessage: string | null = null
+      let errorType: string | null = null
+      let errorStack: string | null = null
+
+      if (options.error) {
+        if (options.error instanceof Error) {
+          errorMessage = options.error.message
+          errorType = options.error.name
+          errorStack = options.error.stack || null
+        } else {
+          errorMessage = String(options.error)
+        }
+      }
+
+      await mutateWithRLS(
+        `UPDATE public."langchain_traces"
+         SET
+           output = $1,
+           status = $2,
+           error = $3,
+           "errorType" = $4,
+           "errorStack" = $5,
+           "endedAt" = now(),
+           "durationMs" = EXTRACT(EPOCH FROM (now() - "startedAt")) * 1000,
+           "inputTokens" = $6,
+           "outputTokens" = $7,
+           "totalTokens" = $8,
+           "totalCost" = $9,
+           "llmCalls" = $10,
+           "toolCalls" = $11,
+           metadata = COALESCE(metadata, '{}'::jsonb) || $12::jsonb
+         WHERE "traceId" = $13`,
+        [
+          processedOutput,
+          status,
+          errorMessage,
+          errorType,
+          errorStack,
+          options.tokens?.input || 0,
+          options.tokens?.output || 0,
+          options.tokens?.total || 0,
+          options.cost || 0,
+          options.llmCalls || 0,
+          options.toolCalls || 0,
+          JSON.stringify(options.metadata || {}),
+          traceId,
+        ],
+        context.userId
+      )
+    } catch (error) {
+      console.error('[Tracer] Failed to end trace:', error)
+    }
+  }
+
+  /**
+   * Start a span within a trace
+   */
+  async startSpan(
+    context: { userId: string; teamId: string },
+    traceId: string,
+    options: StartSpanOptions
+  ): Promise<SpanContext | null> {
+    if (!this.config?.enabled) {
+      return null
+    }
+
+    const spanId = randomUUID()
+    const depth = options.depth || 0
+
+    try {
+      await mutateWithRLS(
+        `INSERT INTO public."langchain_spans" (
+          "spanId",
+          "traceId",
+          "parentSpanId",
+          name,
+          type,
+          provider,
+          model,
+          "toolName",
+          input,
+          status,
+          depth,
+          "startedAt"
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, now())`,
+        [
+          spanId,
+          traceId,
+          options.parentSpanId || null,
+          options.name,
+          options.type,
+          options.provider || null,
+          options.model || null,
+          options.toolName || null,
+          options.input ? JSON.stringify(options.input) : null,
+          'running',
+          depth,
+        ],
+        context.userId
+      )
+
+      return {
+        spanId,
+        traceId,
+        parentSpanId: options.parentSpanId,
+        name: options.name,
+        type: options.type,
+        depth,
+        startedAt: new Date(),
+      }
+    } catch (error) {
+      console.error('[Tracer] Failed to start span:', error)
+      return null
+    }
+  }
+
+  /**
+   * End a span
+   */
+  async endSpan(
+    context: { userId: string; teamId: string },
+    traceId: string,
+    spanId: string,
+    options: EndSpanOptions
+  ): Promise<void> {
+    try {
+      const status = options.error ? 'error' : 'success'
+      const errorMessage = options.error
+        ? options.error instanceof Error
+          ? options.error.message
+          : String(options.error)
+        : null
+
+      await mutateWithRLS(
+        `UPDATE public."langchain_spans"
+         SET
+           output = $1,
+           "toolInput" = $2,
+           "toolOutput" = $3,
+           status = $4,
+           error = $5,
+           "inputTokens" = $6,
+           "outputTokens" = $7,
+           "endedAt" = now(),
+           "durationMs" = EXTRACT(EPOCH FROM (now() - "startedAt")) * 1000
+         WHERE "traceId" = $8 AND "spanId" = $9`,
+        [
+          options.output ? JSON.stringify(options.output) : null,
+          options.toolInput ? JSON.stringify(options.toolInput) : null,
+          options.toolOutput ? JSON.stringify(options.toolOutput) : null,
+          status,
+          errorMessage,
+          options.tokens?.input || null,
+          options.tokens?.output || null,
+          traceId,
+          spanId,
+        ],
+        context.userId
+      )
+    } catch (error) {
+      console.error('[Tracer] Failed to end span:', error)
+    }
+  }
+
+  /**
+   * Process content for storage: truncate and optionally mask PII
+   */
+  processContent(content: string, type: ContentType): string {
+    if (!this.config) {
+      return content.slice(0, 10000) // Default truncation
+    }
+
+    const { pii } = this.config
+
+    // Apply PII masking if configured
+    let processed = content
+    if (
+      (type === 'input' && pii.maskInputs) ||
+      (type === 'output' && pii.maskOutputs)
+    ) {
+      // Simple PII masking patterns
+      // Email addresses
+      processed = processed.replace(
+        /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+        '[EMAIL]'
+      )
+      // Phone numbers (various formats)
+      processed = processed.replace(
+        /\b(\+\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+        '[PHONE]'
+      )
+      // Credit card numbers (basic pattern)
+      processed = processed.replace(
+        /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+        '[CARD]'
+      )
+      // SSN (US format)
+      processed = processed.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN]')
+    }
+
+    // Truncate to configured length
+    if (processed.length > pii.truncateAt) {
+      processed = processed.slice(0, pii.truncateAt) + '...[truncated]'
+    }
+
+    return processed
+  }
+}
+
+// Export singleton instance
+export const tracer = new Tracer()

package/migrations/001_langchain_memory.sql

@@ -0,0 +1,83 @@
+-- Migration: 001_langchain_memory.sql
+-- Description: LangChain conversation memory persistence with multi-conversation support
+-- Date: 2025-12-20
+
+-- ============================================
+-- TABLE
+-- ============================================
+CREATE TABLE IF NOT EXISTS public."langchain_sessions" (
+  -- Primary key
+  id           TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+
+  -- Relational fields (multi-tenancy)
+  "userId"     TEXT NOT NULL REFERENCES public."users"(id) ON DELETE CASCADE,
+  "teamId"     TEXT NOT NULL REFERENCES public."teams"(id) ON DELETE CASCADE,
+  "sessionId"  TEXT NOT NULL,
+
+  -- Conversation fields
+  name         TEXT DEFAULT NULL,
+  "isPinned"   BOOLEAN NOT NULL DEFAULT false,
+
+  -- Memory fields
+  messages     JSONB NOT NULL DEFAULT '[]'::jsonb,
+  metadata     JSONB DEFAULT '{}'::jsonb,
+  "maxMessages" INTEGER NOT NULL DEFAULT 50,
+  "expiresAt"   TIMESTAMPTZ DEFAULT NULL,
+
+  -- System fields
+  "createdAt"   TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"   TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- Unique constraint for multi-tenant session lookup
+  CONSTRAINT langchain_sessions_unique_session UNIQUE ("userId", "teamId", "sessionId")
+);
+
+-- ============================================
+-- COMMENTS (Documentation)
+-- ============================================
+COMMENT ON TABLE  public."langchain_sessions"               IS 'LangChain conversation memory persistence with multi-conversation support';
+COMMENT ON COLUMN public."langchain_sessions".id            IS 'Unique row identifier';
+COMMENT ON COLUMN public."langchain_sessions"."userId"      IS 'Owner user ID';
+COMMENT ON COLUMN public."langchain_sessions"."teamId"      IS 'Team context for multi-tenancy';
+COMMENT ON COLUMN public."langchain_sessions"."sessionId"   IS 'Application-level session identifier (format: {userId}-{timestamp})';
+COMMENT ON COLUMN public."langchain_sessions".name          IS 'User-friendly conversation name (auto-generated from first message if not set)';
+COMMENT ON COLUMN public."langchain_sessions"."isPinned"    IS 'Whether this conversation is pinned to top of list';
+COMMENT ON COLUMN public."langchain_sessions".messages      IS 'Serialized LangChain BaseMessage array';
+COMMENT ON COLUMN public."langchain_sessions".metadata      IS 'Optional session metadata (agent type, etc)';
+COMMENT ON COLUMN public."langchain_sessions"."maxMessages" IS 'Sliding window limit for this session (default: 50)';
+COMMENT ON COLUMN public."langchain_sessions"."expiresAt"   IS 'TTL expiration timestamp (NULL = no expiration)';
+COMMENT ON COLUMN public."langchain_sessions"."createdAt"   IS 'Row creation timestamp';
+COMMENT ON COLUMN public."langchain_sessions"."updatedAt"   IS 'Last update timestamp';
+
+-- ============================================
+-- TRIGGER updatedAt
+-- ============================================
+DROP TRIGGER IF EXISTS langchain_sessions_set_updated_at ON public."langchain_sessions";
+CREATE TRIGGER langchain_sessions_set_updated_at
+BEFORE UPDATE ON public."langchain_sessions"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- ============================================
+-- INDEXES
+-- ============================================
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_user_id      ON public."langchain_sessions"("userId");
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_team_id      ON public."langchain_sessions"("teamId");
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_session_id   ON public."langchain_sessions"("sessionId");
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_lookup       ON public."langchain_sessions"("userId", "teamId", "sessionId");
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_expires_at   ON public."langchain_sessions"("expiresAt");
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_pinned       ON public."langchain_sessions"("userId", "teamId", "isPinned");
+CREATE INDEX IF NOT EXISTS idx_langchain_sessions_updated      ON public."langchain_sessions"("userId", "teamId", "updatedAt" DESC);
+
+-- ============================================
+-- RLS (Row Level Security)
+-- ============================================
+ALTER TABLE public."langchain_sessions" ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "langchain_sessions_owner_policy" ON public."langchain_sessions";
+
+-- Owner can perform all operations on their own sessions
+CREATE POLICY "langchain_sessions_owner_policy"
+ON public."langchain_sessions"
+FOR ALL TO authenticated
+USING ("userId" = public.get_auth_user_id())
+WITH CHECK ("userId" = public.get_auth_user_id());

package/migrations/002_token_usage.sql

@@ -0,0 +1,127 @@
+-- Migration: 002_token_usage.sql
+-- Description: Token usage tracking with cost calculation and daily aggregation
+-- Date: 2025-12-22
+
+-- ============================================
+-- TABLE: Token Usage Tracking
+-- ============================================
+CREATE TABLE IF NOT EXISTS public."langchain_token_usage" (
+  -- Primary key
+  id              TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+
+  -- Relational fields (multi-tenancy)
+  "userId"        TEXT NOT NULL REFERENCES public."users"(id) ON DELETE CASCADE,
+  "teamId"        TEXT NOT NULL REFERENCES public."teams"(id) ON DELETE CASCADE,
+  "sessionId"     TEXT,
+
+  -- Model information
+  provider        TEXT NOT NULL,
+  model           TEXT NOT NULL,
+
+  -- Token counts
+  "inputTokens"   INTEGER NOT NULL DEFAULT 0,
+  "outputTokens"  INTEGER NOT NULL DEFAULT 0,
+  "totalTokens"   INTEGER NOT NULL DEFAULT 0,
+
+  -- Cost (USD, 6 decimal precision)
+  "inputCost"     DECIMAL(12, 6) NOT NULL DEFAULT 0,
+  "outputCost"    DECIMAL(12, 6) NOT NULL DEFAULT 0,
+  "totalCost"     DECIMAL(12, 6) NOT NULL DEFAULT 0,
+
+  -- Metadata
+  "agentName"     TEXT,
+  metadata        JSONB DEFAULT '{}'::jsonb,
+
+  -- System fields
+  "createdAt"     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ============================================
+-- COMMENTS (Documentation)
+-- ============================================
+COMMENT ON TABLE  public."langchain_token_usage"               IS 'Token usage tracking for LangChain agents with cost calculation';
+COMMENT ON COLUMN public."langchain_token_usage".id            IS 'Unique row identifier';
+COMMENT ON COLUMN public."langchain_token_usage"."userId"      IS 'User who triggered the AI request';
+COMMENT ON COLUMN public."langchain_token_usage"."teamId"      IS 'Team context for multi-tenancy';
+COMMENT ON COLUMN public."langchain_token_usage"."sessionId"   IS 'Optional link to langchain_sessions table';
+COMMENT ON COLUMN public."langchain_token_usage".provider      IS 'Model provider (openai, anthropic, ollama)';
+COMMENT ON COLUMN public."langchain_token_usage".model         IS 'Specific model used (gpt-4o, claude-3-5-sonnet, etc)';
+COMMENT ON COLUMN public."langchain_token_usage"."inputTokens" IS 'Number of input/prompt tokens consumed';
+COMMENT ON COLUMN public."langchain_token_usage"."outputTokens" IS 'Number of output/completion tokens generated';
+COMMENT ON COLUMN public."langchain_token_usage"."totalTokens" IS 'Total tokens (input + output)';
+COMMENT ON COLUMN public."langchain_token_usage"."inputCost"   IS 'Cost for input tokens in USD';
+COMMENT ON COLUMN public."langchain_token_usage"."outputCost"  IS 'Cost for output tokens in USD';
+COMMENT ON COLUMN public."langchain_token_usage"."totalCost"   IS 'Total cost in USD';
+COMMENT ON COLUMN public."langchain_token_usage"."agentName"   IS 'Name of the agent that was used';
+COMMENT ON COLUMN public."langchain_token_usage".metadata      IS 'Additional metadata (tools used, execution time, etc)';
+COMMENT ON COLUMN public."langchain_token_usage"."createdAt"   IS 'Timestamp when the usage was recorded';
+
+-- ============================================
+-- INDEXES
+-- ============================================
+CREATE INDEX IF NOT EXISTS idx_token_usage_user_team          ON public."langchain_token_usage"("userId", "teamId");
+CREATE INDEX IF NOT EXISTS idx_token_usage_created_at         ON public."langchain_token_usage"("createdAt");
+CREATE INDEX IF NOT EXISTS idx_token_usage_session_id         ON public."langchain_token_usage"("sessionId") WHERE "sessionId" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_token_usage_provider_model     ON public."langchain_token_usage"(provider, model);
+CREATE INDEX IF NOT EXISTS idx_token_usage_user_created_at    ON public."langchain_token_usage"("userId", "createdAt" DESC);
+
+-- ============================================
+-- RLS (Row Level Security)
+-- ============================================
+ALTER TABLE public."langchain_token_usage" ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "langchain_token_usage_owner_select" ON public."langchain_token_usage";
+DROP POLICY IF EXISTS "langchain_token_usage_owner_insert" ON public."langchain_token_usage";
+
+-- Users can view their own usage
+CREATE POLICY "langchain_token_usage_owner_select"
+ON public."langchain_token_usage"
+FOR SELECT TO authenticated
+USING ("userId" = public.get_auth_user_id());
+
+-- Users can insert their own usage records
+CREATE POLICY "langchain_token_usage_owner_insert"
+ON public."langchain_token_usage"
+FOR INSERT TO authenticated
+WITH CHECK ("userId" = public.get_auth_user_id());
+
+-- ============================================
+-- MATERIALIZED VIEW: Daily Aggregation
+-- ============================================
+CREATE MATERIALIZED VIEW IF NOT EXISTS public."langchain_usage_daily" AS
+SELECT
+  "userId",
+  "teamId",
+  provider,
+  model,
+  DATE("createdAt") as date,
+  SUM("inputTokens")::bigint as "inputTokens",
+  SUM("outputTokens")::bigint as "outputTokens",
+  SUM("totalTokens")::bigint as "totalTokens",
+  SUM("totalCost")::numeric(12, 6) as "totalCost",
+  COUNT(*)::bigint as "requestCount"
+FROM public."langchain_token_usage"
+GROUP BY "userId", "teamId", provider, model, DATE("createdAt");
+
+-- Unique index for CONCURRENTLY refresh
+CREATE UNIQUE INDEX IF NOT EXISTS idx_usage_daily_unique
+ON public."langchain_usage_daily"("userId", "teamId", provider, model, date);
+
+-- Comment on materialized view
+COMMENT ON MATERIALIZED VIEW public."langchain_usage_daily" IS 'Daily aggregated token usage for dashboard performance';
+
+-- ============================================
+-- FUNCTION: Refresh Materialized View
+-- ============================================
+CREATE OR REPLACE FUNCTION public.refresh_langchain_usage_daily()
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  REFRESH MATERIALIZED VIEW CONCURRENTLY public."langchain_usage_daily";
+END;
+$$;
+
+COMMENT ON FUNCTION public.refresh_langchain_usage_daily() IS 'Refresh the daily usage materialized view (call periodically via cron)';