@nextsparkjs/core 0.1.0-beta.1

package/dist/templates/contents/plugins/langchain/migrations/003_observability.sql

@@ -0,0 +1,257 @@
+-- Migration: 003_observability.sql
+-- Description: LangChain observability (traces, spans, metrics tracking)
+-- Date: 2025-12-22
+
+-- ============================================
+-- TABLE: Traces (Main trace records)
+-- ============================================
+DROP TABLE IF EXISTS public."langchain_traces" CASCADE;
+
+CREATE TABLE IF NOT EXISTS public."langchain_traces" (
+  -- Primary key
+  id              TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+
+  -- Unique trace identifier
+  "traceId"       TEXT NOT NULL UNIQUE,
+
+  -- Relational fields (multi-tenancy)
+  "userId"        TEXT NOT NULL REFERENCES "users"(id) ON DELETE CASCADE,
+  "teamId"        TEXT NOT NULL REFERENCES "teams"(id) ON DELETE CASCADE,
+  "sessionId"     TEXT,
+
+  -- Agent information
+  "agentName"     TEXT NOT NULL,
+  "agentType"     TEXT,
+  "parentId"      TEXT,
+
+  -- Input/Output (truncatable content)
+  input           TEXT,
+  output          TEXT,
+
+  -- Status and error tracking
+  status          TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'success', 'error')),
+  error           TEXT,
+  "errorType"     TEXT,
+  "errorStack"    TEXT,
+
+  -- Timing information
+  "startedAt"     TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "endedAt"       TIMESTAMPTZ,
+  "durationMs"    INTEGER,
+
+  -- Token usage and cost
+  "inputTokens"   INTEGER DEFAULT 0,
+  "outputTokens"  INTEGER DEFAULT 0,
+  "totalTokens"   INTEGER DEFAULT 0,
+  "totalCost"     DECIMAL(12, 6) DEFAULT 0,
+
+  -- Call counts
+  "llmCalls"      INTEGER DEFAULT 0,
+  "toolCalls"     INTEGER DEFAULT 0,
+
+  -- Additional metadata
+  metadata        JSONB DEFAULT '{}'::jsonb,
+  tags            TEXT[],
+
+  -- System fields
+  "createdAt"     TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ============================================
+-- COMMENTS: Traces Table
+-- ============================================
+COMMENT ON TABLE  public."langchain_traces"                 IS 'LangChain agent invocation traces for observability';
+COMMENT ON COLUMN public."langchain_traces".id              IS 'Unique row identifier';
+COMMENT ON COLUMN public."langchain_traces"."traceId"       IS 'Unique trace identifier (gen by tracer)';
+COMMENT ON COLUMN public."langchain_traces"."userId"        IS 'User who triggered the agent invocation';
+COMMENT ON COLUMN public."langchain_traces"."teamId"        IS 'Team context for multi-tenancy';
+COMMENT ON COLUMN public."langchain_traces"."sessionId"     IS 'Optional session identifier';
+COMMENT ON COLUMN public."langchain_traces"."agentName"     IS 'Name of the agent that was invoked';
+COMMENT ON COLUMN public."langchain_traces"."agentType"     IS 'Type/category of agent';
+COMMENT ON COLUMN public."langchain_traces"."parentId"      IS 'Parent trace ID for nested agent calls';
+COMMENT ON COLUMN public."langchain_traces".input           IS 'Agent input (truncated if too long)';
+COMMENT ON COLUMN public."langchain_traces".output          IS 'Agent output (truncated if too long)';
+COMMENT ON COLUMN public."langchain_traces".status          IS 'Trace status: running, success, error';
+COMMENT ON COLUMN public."langchain_traces".error           IS 'Error message if failed';
+COMMENT ON COLUMN public."langchain_traces"."errorType"     IS 'Error type/category';
+COMMENT ON COLUMN public."langchain_traces"."errorStack"    IS 'Error stack trace';
+COMMENT ON COLUMN public."langchain_traces"."startedAt"     IS 'Trace start timestamp';
+COMMENT ON COLUMN public."langchain_traces"."endedAt"       IS 'Trace end timestamp';
+COMMENT ON COLUMN public."langchain_traces"."durationMs"    IS 'Total duration in milliseconds';
+COMMENT ON COLUMN public."langchain_traces"."inputTokens"   IS 'Total input tokens across all LLM calls';
+COMMENT ON COLUMN public."langchain_traces"."outputTokens"  IS 'Total output tokens across all LLM calls';
+COMMENT ON COLUMN public."langchain_traces"."totalTokens"   IS 'Total tokens (input + output)';
+COMMENT ON COLUMN public."langchain_traces"."totalCost"     IS 'Total cost in USD';
+COMMENT ON COLUMN public."langchain_traces"."llmCalls"      IS 'Number of LLM calls in trace';
+COMMENT ON COLUMN public."langchain_traces"."toolCalls"     IS 'Number of tool calls in trace';
+COMMENT ON COLUMN public."langchain_traces".metadata        IS 'Additional trace metadata';
+COMMENT ON COLUMN public."langchain_traces".tags            IS 'Tags for filtering and categorization';
+COMMENT ON COLUMN public."langchain_traces"."createdAt"     IS 'Record creation timestamp';
+COMMENT ON COLUMN public."langchain_traces"."updatedAt"     IS 'Record last update timestamp';
+
+-- ============================================
+-- INDEXES: Traces Table
+-- ============================================
+CREATE INDEX IF NOT EXISTS idx_traces_trace_id            ON public."langchain_traces"("traceId");
+CREATE INDEX IF NOT EXISTS idx_traces_user_id             ON public."langchain_traces"("userId");
+CREATE INDEX IF NOT EXISTS idx_traces_team_id             ON public."langchain_traces"("teamId");
+CREATE INDEX IF NOT EXISTS idx_traces_team_time           ON public."langchain_traces"("teamId", "startedAt" DESC);
+CREATE INDEX IF NOT EXISTS idx_traces_status              ON public."langchain_traces"(status) WHERE status != 'success';
+CREATE INDEX IF NOT EXISTS idx_traces_agent               ON public."langchain_traces"("agentName", "startedAt" DESC);
+CREATE INDEX IF NOT EXISTS idx_traces_parent_id           ON public."langchain_traces"("parentId") WHERE "parentId" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_traces_session             ON public."langchain_traces"("sessionId") WHERE "sessionId" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_traces_created_at          ON public."langchain_traces"("createdAt" DESC);
+CREATE INDEX IF NOT EXISTS idx_traces_user_created_at     ON public."langchain_traces"("userId", "createdAt" DESC);
+
+-- ============================================
+-- TRIGGER: Traces updatedAt
+-- ============================================
+DROP TRIGGER IF EXISTS langchain_traces_set_updated_at ON public."langchain_traces";
+CREATE TRIGGER langchain_traces_set_updated_at
+BEFORE UPDATE ON public."langchain_traces"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- ============================================
+-- TABLE: Spans (Individual operations)
+-- ============================================
+CREATE TABLE IF NOT EXISTS public."langchain_spans" (
+  -- Primary key
+  id             TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+
+  -- Unique span identifier
+  "spanId"       TEXT NOT NULL UNIQUE,
+
+  -- Relational fields
+  "traceId"      TEXT NOT NULL REFERENCES public."langchain_traces"("traceId") ON DELETE CASCADE,
+  "parentSpanId" TEXT,
+
+  -- Span information
+  name           TEXT NOT NULL,
+  type           TEXT NOT NULL CHECK (type IN ('llm', 'tool', 'chain', 'retriever')),
+
+  -- LLM-specific fields
+  provider       TEXT,
+  model          TEXT,
+  "inputTokens"  INTEGER,
+  "outputTokens" INTEGER,
+
+  -- Tool-specific fields
+  "toolName"     TEXT,
+  "toolInput"    JSONB,
+  "toolOutput"   JSONB,
+
+  -- Generic input/output
+  input          JSONB,
+  output         JSONB,
+
+  -- Status and error tracking
+  status         TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'success', 'error')),
+  error          TEXT,
+
+  -- Timing information
+  "startedAt"    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "endedAt"      TIMESTAMPTZ,
+  "durationMs"   INTEGER,
+
+  -- Hierarchy depth
+  depth          INTEGER DEFAULT 0,
+
+  -- System fields
+  "createdAt"    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ============================================
+-- COMMENTS: Spans Table
+-- ============================================
+COMMENT ON TABLE  public."langchain_spans"               IS 'Individual operations (spans) within LangChain traces';
+COMMENT ON COLUMN public."langchain_spans".id            IS 'Unique row identifier';
+COMMENT ON COLUMN public."langchain_spans"."spanId"      IS 'Unique span identifier';
+COMMENT ON COLUMN public."langchain_spans"."traceId"     IS 'Parent trace identifier';
+COMMENT ON COLUMN public."langchain_spans"."parentSpanId" IS 'Parent span ID for nested operations';
+COMMENT ON COLUMN public."langchain_spans".name          IS 'Span name/description';
+COMMENT ON COLUMN public."langchain_spans".type          IS 'Span type: llm, tool, chain, retriever';
+COMMENT ON COLUMN public."langchain_spans".provider      IS 'LLM provider (openai, anthropic, etc)';
+COMMENT ON COLUMN public."langchain_spans".model         IS 'LLM model name';
+COMMENT ON COLUMN public."langchain_spans"."inputTokens" IS 'Input tokens (LLM spans)';
+COMMENT ON COLUMN public."langchain_spans"."outputTokens" IS 'Output tokens (LLM spans)';
+COMMENT ON COLUMN public."langchain_spans"."toolName"    IS 'Tool name (tool spans)';
+COMMENT ON COLUMN public."langchain_spans"."toolInput"   IS 'Tool input data (tool spans)';
+COMMENT ON COLUMN public."langchain_spans"."toolOutput"  IS 'Tool output data (tool spans)';
+COMMENT ON COLUMN public."langchain_spans".input         IS 'Generic span input';
+COMMENT ON COLUMN public."langchain_spans".output        IS 'Generic span output';
+COMMENT ON COLUMN public."langchain_spans".status        IS 'Span status: running, success, error';
+COMMENT ON COLUMN public."langchain_spans".error         IS 'Error message if failed';
+COMMENT ON COLUMN public."langchain_spans"."startedAt"   IS 'Span start timestamp';
+COMMENT ON COLUMN public."langchain_spans"."endedAt"     IS 'Span end timestamp';
+COMMENT ON COLUMN public."langchain_spans"."durationMs"  IS 'Span duration in milliseconds';
+COMMENT ON COLUMN public."langchain_spans".depth         IS 'Nesting depth in span tree';
+COMMENT ON COLUMN public."langchain_spans"."createdAt"   IS 'Record creation timestamp';
+COMMENT ON COLUMN public."langchain_spans"."updatedAt"   IS 'Record last update timestamp';
+
+-- ============================================
+-- INDEXES: Spans Table
+-- ============================================
+CREATE INDEX IF NOT EXISTS idx_spans_span_id          ON public."langchain_spans"("spanId");
+CREATE INDEX IF NOT EXISTS idx_spans_trace_id         ON public."langchain_spans"("traceId");
+CREATE INDEX IF NOT EXISTS idx_spans_trace_time       ON public."langchain_spans"("traceId", "startedAt");
+CREATE INDEX IF NOT EXISTS idx_spans_parent_id        ON public."langchain_spans"("parentSpanId") WHERE "parentSpanId" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_spans_type             ON public."langchain_spans"(type);
+CREATE INDEX IF NOT EXISTS idx_spans_provider_model   ON public."langchain_spans"(provider, model) WHERE type = 'llm';
+CREATE INDEX IF NOT EXISTS idx_spans_tool_name        ON public."langchain_spans"("toolName") WHERE type = 'tool';
+CREATE INDEX IF NOT EXISTS idx_spans_created_at       ON public."langchain_spans"("createdAt" DESC);
+
+-- ============================================
+-- TRIGGER: Spans updatedAt
+-- ============================================
+DROP TRIGGER IF EXISTS langchain_spans_set_updated_at ON public."langchain_spans";
+CREATE TRIGGER langchain_spans_set_updated_at
+BEFORE UPDATE ON public."langchain_spans"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- ============================================
+-- RLS: Traces Table (Superadmin sees all)
+-- ============================================
+ALTER TABLE public."langchain_traces" ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "langchain_traces_owner_access"     ON public."langchain_traces";
+DROP POLICY IF EXISTS "langchain_traces_superadmin_access" ON public."langchain_traces";
+
+-- Users can view their own traces
+CREATE POLICY "langchain_traces_owner_access"
+ON public."langchain_traces"
+FOR ALL TO authenticated
+USING ("userId" = public.get_auth_user_id());
+
+-- Superadmins can view all traces
+CREATE POLICY "langchain_traces_superadmin_access"
+ON public."langchain_traces"
+FOR ALL TO authenticated
+USING (public.is_superadmin());
+
+-- ============================================
+-- RLS: Spans Table (Inherit from traces)
+-- ============================================
+ALTER TABLE public."langchain_spans" ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "langchain_spans_owner_access"     ON public."langchain_spans";
+DROP POLICY IF EXISTS "langchain_spans_superadmin_access" ON public."langchain_spans";
+
+-- Users can view spans from their own traces
+CREATE POLICY "langchain_spans_owner_access"
+ON public."langchain_spans"
+FOR ALL TO authenticated
+USING (
+  EXISTS (
+    SELECT 1 FROM public."langchain_traces" t
+    WHERE t."traceId" = "langchain_spans"."traceId"
+      AND t."userId" = public.get_auth_user_id()
+  )
+);
+
+-- Superadmins can view all spans
+CREATE POLICY "langchain_spans_superadmin_access"
+ON public."langchain_spans"
+FOR ALL TO authenticated
+USING (public.is_superadmin());

package/dist/templates/contents/plugins/langchain/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "plugin-langchain",
+    "version": "2.0.0",
+    "private": true,
+    "dependencies": {
+        "langchain": "^0.3.0",
+        "@langchain/core": "^0.3.0",
+        "@langchain/community": "^0.3.0",
+        "@langchain/ollama": "^0.1.0",
+        "@langchain/openai": "^0.3.0",
+        "@langchain/anthropic": "^0.3.0",
+        "@langchain/langgraph": "^0.2.0",
+        "@anthropic-ai/sdk": "^0.36.0",
+        "zod": "^3.23.0",
+        "handlebars": "^4.7.0"
+    }
+}

package/dist/templates/contents/plugins/langchain/plugin.config.ts

@@ -0,0 +1,170 @@
+import type { PluginConfig } from '@nextsparkjs/core/types/plugin'
+import type { LLMProvider } from './types/langchain.types'
+
+/**
+ * LangChain Plugin Configuration
+ *
+ * Environment variables:
+ * - LANGCHAIN_PLUGIN_ENABLED: Enable/disable the plugin
+ * - LANGCHAIN_PLUGIN_DEBUG: Enable debug console logging
+ *
+ * File logging:
+ * - LOG_ENABLED: Enable file logging (core environment variable)
+ *
+ * Ollama (local):
+ * - LANGCHAIN_OLLAMA_BASE_URL: Ollama server URL (default: http://localhost:11434)
+ * - LANGCHAIN_OLLAMA_MODEL: Ollama model (default: llama3.2:3b)
+ *
+ * OpenAI-compatible (LM Studio, LocalAI, etc.):
+ * - LANGCHAIN_OPENAI_BASE_URL: Server URL (e.g., http://localhost:1234/v1)
+ * - LANGCHAIN_OPENAI_MODEL: Model name
+ * - OPENAI_API_KEY: API key (use "lm-studio" for local servers)
+ */
+export const config = {
+    enabled: process.env.LANGCHAIN_PLUGIN_ENABLED === 'true',
+    debug: process.env.LANGCHAIN_PLUGIN_DEBUG === 'true',
+
+    /** Default provider when not specified per-agent */
+    defaultProvider: (process.env.LANGCHAIN_DEFAULT_PROVIDER || 'ollama') as LLMProvider,
+
+    /** Default temperature for all providers */
+    defaultTemperature: 0.1,
+
+    /** Provider-specific configurations */
+    providers: {
+        openai: {
+            apiKey: process.env.OPENAI_API_KEY,
+            baseUrl: process.env.LANGCHAIN_OPENAI_BASE_URL,
+            model: process.env.LANGCHAIN_OPENAI_MODEL || 'gpt-4o-mini',
+            temperature: 0.1,
+        },
+        anthropic: {
+            apiKey: process.env.ANTHROPIC_API_KEY,
+            model: process.env.LANGCHAIN_ANTHROPIC_MODEL || 'claude-3-5-sonnet-20241022',
+            temperature: 0.1,
+        },
+        ollama: {
+            baseUrl: process.env.LANGCHAIN_OLLAMA_BASE_URL || 'http://localhost:11434',
+            model: process.env.LANGCHAIN_OLLAMA_MODEL || 'llama3.2:3b',
+            temperature: 0.1,
+        },
+    },
+}
+
+/**
+ * Validate that required configuration exists for a provider
+ * @throws Error if required configuration is missing
+ */
+export function validateProviderConfig(provider: LLMProvider): void {
+    switch (provider) {
+        case 'openai':
+            if (!config.providers.openai.apiKey) {
+                throw new Error(
+                    'OPENAI_API_KEY environment variable is required when using OpenAI provider. ' +
+                    'Get your API key at https://platform.openai.com/api-keys'
+                )
+            }
+            break
+        case 'anthropic':
+            if (!config.providers.anthropic.apiKey) {
+                throw new Error(
+                    'ANTHROPIC_API_KEY environment variable is required when using Anthropic provider. ' +
+                    'Get your API key at https://console.anthropic.com/settings/keys'
+                )
+            }
+            break
+        case 'ollama':
+            // Ollama doesn't require API key (local)
+            break
+        default:
+            throw new Error(`Unsupported provider: ${provider}. Supported: openai, anthropic, ollama`)
+    }
+}
+
+/**
+ * Check if a provider is available (has required credentials)
+ */
+export function isProviderAvailable(provider: LLMProvider): boolean {
+    switch (provider) {
+        case 'openai':
+            return !!config.providers.openai.apiKey
+        case 'anthropic':
+            return !!config.providers.anthropic.apiKey
+        case 'ollama':
+            return true // Ollama is always "available" (local)
+        default:
+            return false
+    }
+}
+
+/**
+ * Get list of available providers (those with valid configuration)
+ */
+export function getAvailableProviders(): LLMProvider[] {
+    return (['openai', 'anthropic', 'ollama'] as LLMProvider[]).filter(isProviderAvailable)
+}
+
+/**
+ * LangChain Plugin Config
+ *
+ * Provides AI agent capabilities with:
+ * - Multiple LLM providers (OpenAI, Anthropic, Ollama)
+ * - Tool system for extending agent capabilities
+ * - Session-based memory for conversation continuity
+ * - Per-agent model configuration for themes
+ *
+ * ## Usage in Themes
+ *
+ * Import directly from the lib files (NOT from plugin.config.ts to avoid circular deps):
+ *
+ * ```typescript
+ * import { createAgent } from '@/plugins/langchain/lib/agent-factory'
+ * import { buildTools, type ToolDefinition } from '@/plugins/langchain/lib/tools-builder'
+ * import { memoryStore } from '@/plugins/langchain/lib/memory-store'
+ * import { getModel } from '@/plugins/langchain/lib/providers'
+ *
+ * // Use default provider (from env or plugin config)
+ * const agent = await createAgent({
+ *     sessionId: 'unique-session-id',
+ *     systemPrompt: 'You are a helpful assistant...',
+ *     tools: myTools,
+ * })
+ *
+ * // Use specific provider and model
+ * const agent = await createAgent({
+ *     sessionId: 'unique-session-id',
+ *     systemPrompt: 'You are a helpful assistant...',
+ *     tools: myTools,
+ *     modelConfig: {
+ *         provider: 'openai',
+ *         model: 'gpt-4o',
+ *         temperature: 0.3,
+ *     },
+ * })
+ *
+ * const response = await agent.chat('Hello!')
+ * ```
+ */
+export const langchainPluginConfig: PluginConfig = {
+    name: 'langchain',
+    displayName: 'LangChain Agent Framework',
+    version: '2.0.0',
+    description: 'Create AI agents with tools, memory, and customizable behavior. Supports OpenAI, Anthropic, and Ollama.',
+    enabled: config.enabled,
+    dependencies: [],
+
+    hooks: {
+        onLoad: async () => {
+            if (config.debug) {
+                console.log('[LangChain Plugin] Loaded')
+                console.log('[LangChain Plugin] Default Provider:', config.defaultProvider)
+                console.log('[LangChain Plugin] OpenAI configured:', !!config.providers.openai.apiKey)
+                console.log('[LangChain Plugin] Anthropic configured:', !!config.providers.anthropic.apiKey)
+                console.log('[LangChain Plugin] Ollama URL:', config.providers.ollama.baseUrl)
+                console.log('[LangChain Plugin] Ollama Model:', config.providers.ollama.model)
+            }
+        }
+    }
+}
+
+export default langchainPluginConfig

package/dist/templates/contents/plugins/langchain/presets/lib/langchain.config.ts.preset

@@ -0,0 +1,142 @@
+/**
+ * ============================================================================
+ * LANGCHAIN CONFIGURATION PRESET
+ * ============================================================================
+ *
+ * This is a preset template for LangChain plugin configuration.
+ * Copy this file to your theme's lib/langchain/langchain.config.ts
+ *
+ * Path: contents/themes/{your-theme}/lib/langchain/langchain.config.ts
+ *
+ * ============================================================================
+ */
+
+import type { ObservabilityConfig } from '@/contents/plugins/langchain/types/observability.types'
+import type {
+  ThemeLangChainConfig,
+  AgentDefinition,
+  AgentContext,
+} from '@/contents/plugins/langchain/types/langchain.types'
+import { createAgentHelpers } from '@/contents/plugins/langchain/lib/agent-helpers'
+
+// TODO: Import your tool factories
+// import { createTaskTools } from './tools/tasks'
+// import { createCustomerTools } from './tools/customers'
+
+// ============================================================================
+// OBSERVABILITY CONFIGURATION
+// ============================================================================
+
+export interface LangChainObservabilityConfig {
+  /** Observability configuration */
+  observability: ObservabilityConfig
+}
+
+export const observabilityConfig: LangChainObservabilityConfig = {
+  observability: {
+    /** Enable observability tracing */
+    enabled: true,
+
+    /** Data retention settings */
+    retention: {
+      /** Days to keep trace data */
+      traces: 30,
+    },
+
+    /** Sampling configuration */
+    sampling: {
+      /** Sample rate (0.0-1.0) - 1.0 = 100% */
+      rate: 1.0,
+      /** Always trace errors regardless of sample rate */
+      alwaysTraceErrors: true,
+    },
+
+    /** PII and content processing */
+    pii: {
+      /** Mask inputs for PII (email, phone, card, SSN patterns) */
+      maskInputs: false,
+      /** Mask outputs for PII */
+      maskOutputs: false,
+      /** Truncate content at this length (characters) */
+      truncateAt: 10000,
+    },
+  },
+}
+
+// ============================================================================
+// AGENT DEFINITIONS
+// ============================================================================
+
+/**
+ * Define your agents here.
+ *
+ * Each agent has:
+ * - provider: LLM provider (ollama, openai, anthropic)
+ * - model: Model name (optional for ollama - uses LANGCHAIN_OLLAMA_MODEL env)
+ * - temperature: Creativity level (0-1)
+ * - createTools: Factory function that returns tools for this agent
+ * - systemPrompt: Name of the .md file in lib/langchain/agents/ folder
+ * - description: What this agent does (documentation)
+ * - sessionConfig: (optional) Memory customization (TTL, maxMessages)
+ * - enrichContext: (optional) Fetch runtime data for prompt templates
+ */
+export const AGENTS: Record<string, AgentDefinition> = {
+  // Example: Single unified agent
+  'single-agent': {
+    provider: 'ollama',
+    // model: uses LANGCHAIN_OLLAMA_MODEL from .env
+    temperature: 0.3,
+    description: 'Unified agent with access to all entity tools',
+    systemPrompt: 'single-agent', // loads from lib/langchain/agents/single-agent.md
+    createTools: (context: AgentContext) => [
+      // TODO: Add your tools here
+      // ...createTaskTools(context),
+    ],
+  },
+
+  // Example: Orchestrator for multi-agent routing
+  // 'orchestrator': {
+  //   provider: 'anthropic',
+  //   model: 'claude-3-haiku-20240307',
+  //   temperature: 0.1,
+  //   description: 'Routes to specialized agents',
+  //   systemPrompt: 'orchestrator',
+  //   createTools: () => createOrchestratorTools(),
+  // },
+}
+
+// ============================================================================
+// THEME CONFIG (for plugin compatibility)
+// ============================================================================
+
+export const langchainConfig: ThemeLangChainConfig = {
+  defaultProvider: 'ollama',
+  defaultTemperature: 0.3,
+  agents: AGENTS,
+}
+
+// ============================================================================
+// HELPERS (from plugin factory)
+// ============================================================================
+
+/**
+ * Helper functions created from the plugin's factory.
+ * These provide convenient access to agent configuration.
+ */
+const helpers = createAgentHelpers(AGENTS, {
+  provider: langchainConfig.defaultProvider,
+  model: langchainConfig.defaultModel,
+  temperature: langchainConfig.defaultTemperature,
+})
+
+// Re-export individual helpers for convenience
+export const {
+  getAgentConfig,
+  getAgentModelConfig,
+  getAgentTools,
+  getAgentPromptName,
+  getAgentSessionConfig,
+  getAgentEnrichContext,
+  hasAgent,
+  getAgentNames,
+} = helpers

package/dist/templates/contents/plugins/langchain/presets/templates/sector7/ai-observability/[traceId]/page.tsx

@@ -0,0 +1,91 @@
+'use client'
+
+/**
+ * AI Observability Trace Detail Page Preset
+ *
+ * Shows detailed view of a specific trace with its spans.
+ * Configurable basePath allows use at any URL (e.g., /superadmin/ai-observability/{traceId})
+ */
+
+import { useRouter } from 'next/navigation'
+import { useTraceDetail } from '@/plugins/langchain/hooks/observability/useTraceDetail'
+import { TraceDetail } from '@/plugins/langchain/components/observability/TraceDetail'
+
+interface TraceDetailPagePresetProps {
+  traceId: string
+  enabled?: boolean
+  /** Base path for navigation (e.g., '/superadmin/ai-observability') */
+  basePath?: string
+}
+
+export function TraceDetailPagePreset({
+  traceId,
+  enabled = true,
+  basePath = '/superadmin/ai-observability'
+}: TraceDetailPagePresetProps) {
+  const router = useRouter()
+  const { data, isLoading, isError } = useTraceDetail(traceId)
+
+  const handleBack = () => {
+    router.push(basePath)
+  }
+
+  const handleSelectChildTrace = (childTraceId: string) => {
+    router.push(`${basePath}/${childTraceId}`)
+  }
+
+  const handleSelectParentTrace = (parentTraceId: string) => {
+    router.push(`${basePath}/${parentTraceId}`)
+  }
+
+  if (!enabled) {
+    return (
+      <div className="container py-6">
+        <p className="text-muted-foreground">Observability is disabled.</p>
+      </div>
+    )
+  }
+
+  if (isLoading) {
+    return (
+      <div className="container py-6">
+        <div className="text-center py-12">
+          <p className="text-muted-foreground">Loading trace...</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (isError || !data) {
+    return (
+      <div className="container py-6">
+        <div className="text-center py-12">
+          <p className="text-destructive">Failed to load trace</p>
+          <button
+            onClick={handleBack}
+            className="mt-4 text-primary hover:underline"
+          >
+            Back to traces
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="container py-6">
+      <TraceDetail
+        trace={data.trace}
+        spans={data.spans}
+        childTraces={data.childTraces}
+        childSpansMap={data.childSpansMap}
+        parentTrace={data.parentTrace}
+        onBack={handleBack}
+        onSelectChildTrace={handleSelectChildTrace}
+        onSelectParentTrace={handleSelectParentTrace}
+      />
+    </div>
+  )
+}
+
+export default TraceDetailPagePreset