@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/lib/memory-store.ts

@@ -0,0 +1,168 @@
+/**
+ * Memory Store for LangChain
+ *
+ * This module provides the primary interface for conversation memory.
+ * Uses database persistence via dbMemoryStore.
+ *
+ * For new code, use dbMemoryStore directly with explicit context.
+ */
+
+import { BaseMessage, HumanMessage, AIMessage } from '@langchain/core/messages'
+import {
+    dbMemoryStore,
+    CONVERSATION_LIMITS,
+    generateSessionId,
+    type ConversationInfo,
+} from './db-memory-store'
+import type { AgentContext, SessionConfig } from '../types/langchain.types'
+
+export {
+    dbMemoryStore,
+    CONVERSATION_LIMITS,
+    generateSessionId,
+    type AgentContext,
+    type SessionConfig,
+    type ConversationInfo,
+}
+
+/**
+ * Memory store interface with context support
+ *
+ * All methods are async and require context (userId, teamId) for multi-tenancy.
+ */
+export const memoryStore = {
+    /**
+     * Get messages for a session
+     */
+    getMessages: async (
+        sessionId: string,
+        context: AgentContext
+    ): Promise<BaseMessage[]> => {
+        return dbMemoryStore.getMessages(sessionId, context)
+    },
+
+    /**
+     * Add messages to a session
+     */
+    addMessages: async (
+        sessionId: string,
+        messages: BaseMessage[],
+        context: AgentContext,
+        config?: SessionConfig
+    ): Promise<void> => {
+        return dbMemoryStore.addMessages(sessionId, messages, context, config)
+    },
+
+    /**
+     * Clear a session
+     */
+    clearSession: async (
+        sessionId: string,
+        context: AgentContext
+    ): Promise<void> => {
+        return dbMemoryStore.clearSession(sessionId, context)
+    },
+
+    /**
+     * Clean up expired sessions
+     */
+    cleanup: async (): Promise<number> => {
+        return dbMemoryStore.cleanup()
+    },
+
+    /**
+     * List all sessions for a user in a team
+     */
+    listSessions: async (
+        context: AgentContext
+    ): Promise<ConversationInfo[]> => {
+        return dbMemoryStore.listSessions(context)
+    },
+
+    /**
+     * Get full session info
+     */
+    getSession: async (
+        sessionId: string,
+        context: AgentContext
+    ): Promise<ConversationInfo | null> => {
+        return dbMemoryStore.getSession(sessionId, context)
+    },
+
+    /**
+     * Create a new session
+     */
+    createSession: async (
+        context: AgentContext,
+        name?: string
+    ): Promise<{ sessionId: string; createdAt: Date }> => {
+        return dbMemoryStore.createSession(context, name)
+    },
+
+    /**
+     * Rename a session
+     */
+    renameSession: async (
+        sessionId: string,
+        name: string,
+        context: AgentContext
+    ): Promise<void> => {
+        return dbMemoryStore.renameSession(sessionId, name, context)
+    },
+
+    /**
+     * Toggle pin status
+     */
+    togglePinSession: async (
+        sessionId: string,
+        isPinned: boolean,
+        context: AgentContext
+    ): Promise<void> => {
+        return dbMemoryStore.togglePinSession(sessionId, isPinned, context)
+    },
+
+    /**
+     * Count sessions for limit enforcement
+     */
+    countSessions: async (
+        context: AgentContext
+    ): Promise<number> => {
+        return dbMemoryStore.countSessions(context)
+    },
+
+    /**
+     * Extend session TTL (deprecated)
+     * @deprecated Sessions now have no expiration by default
+     */
+    extendSession: async (
+        sessionId: string,
+        context: AgentContext,
+        ttlHours?: number
+    ): Promise<void> => {
+        return dbMemoryStore.extendSession(sessionId, context, ttlHours)
+    },
+
+    /**
+     * Default configuration values
+     */
+    defaults: {
+        maxMessages: CONVERSATION_LIMITS.MAX_MESSAGES_PER_CONVERSATION,
+        maxConversations: CONVERSATION_LIMITS.MAX_CONVERSATIONS,
+    },
+}
+
+/**
+ * Helper function to create a HumanMessage
+ * Re-exported for use in theme code without direct @langchain imports
+ */
+export function createHumanMessage(content: string): HumanMessage {
+    return new HumanMessage(content)
+}
+
+/**
+ * Helper function to create an AIMessage
+ * Re-exported for use in theme code without direct @langchain imports
+ */
+export function createAIMessage(content: string): AIMessage {
+    return new AIMessage(content)
+}

package/lib/message-serializer.ts

@@ -0,0 +1,110 @@
+/**
+ * Message Serializer for LangChain
+ *
+ * Handles serialization/deserialization of LangChain BaseMessage objects
+ * to/from JSON for database storage.
+ */
+
+import {
+    BaseMessage,
+    HumanMessage,
+    AIMessage,
+    SystemMessage,
+    ToolMessage,
+} from '@langchain/core/messages'
+
+/**
+ * Serialized message format for database storage
+ */
+export interface SerializedMessage {
+    type: 'human' | 'ai' | 'system' | 'tool'
+    content: string
+    name?: string
+    additional_kwargs?: Record<string, unknown>
+    response_metadata?: Record<string, unknown>
+    tool_call_id?: string
+}
+
+/**
+ * Serialize LangChain messages to JSON-compatible format
+ */
+export function serializeMessages(messages: BaseMessage[]): SerializedMessage[] {
+    return messages.map((msg) => {
+        // Convert content to string (it might be complex objects)
+        const content = typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content)
+
+        const serialized: SerializedMessage = {
+            type: msg._getType() as SerializedMessage['type'],
+            content,
+        }
+
+        if (msg.name) {
+            serialized.name = msg.name
+        }
+
+        if (msg.additional_kwargs && Object.keys(msg.additional_kwargs).length > 0) {
+            serialized.additional_kwargs = msg.additional_kwargs
+        }
+
+        // AIMessage has response_metadata
+        if (msg._getType() === 'ai' && (msg as AIMessage).response_metadata) {
+            serialized.response_metadata = (msg as AIMessage).response_metadata
+        }
+
+        // ToolMessage has tool_call_id
+        if (msg._getType() === 'tool' && (msg as ToolMessage).tool_call_id) {
+            serialized.tool_call_id = (msg as ToolMessage).tool_call_id
+        }
+
+        return serialized
+    })
+}
+
+/**
+ * Deserialize JSON messages back to LangChain BaseMessage objects
+ */
+export function deserializeMessages(serialized: SerializedMessage[]): BaseMessage[] {
+    return serialized.map((msg) => {
+        switch (msg.type) {
+            case 'human':
+                return new HumanMessage({
+                    content: msg.content,
+                    name: msg.name,
+                    additional_kwargs: msg.additional_kwargs,
+                })
+
+            case 'ai':
+                return new AIMessage({
+                    content: msg.content,
+                    name: msg.name,
+                    additional_kwargs: msg.additional_kwargs,
+                    response_metadata: msg.response_metadata,
+                })
+
+            case 'system':
+                return new SystemMessage({
+                    content: msg.content,
+                    name: msg.name,
+                    additional_kwargs: msg.additional_kwargs,
+                })
+
+            case 'tool':
+                return new ToolMessage({
+                    content: msg.content,
+                    tool_call_id: msg.tool_call_id || '',
+                    name: msg.name,
+                    additional_kwargs: msg.additional_kwargs,
+                })
+
+            default:
+                // Fallback to HumanMessage for unknown types
+                return new HumanMessage({
+                    content: msg.content,
+                    name: msg.name,
+                    additional_kwargs: msg.additional_kwargs,
+                })
+        }
+    })
+}

package/lib/prompt-renderer.ts

@@ -0,0 +1,94 @@
+/**
+ * Prompt Renderer for LangChain
+ *
+ * Renders system prompts using Handlebars templates.
+ * Allows themes to inject dynamic context data into agent prompts.
+ *
+ * @example
+ * // Template with variables
+ * const template = 'Hello {{user.name}} from {{company.name}}!'
+ * const context = { user: { name: 'John' }, company: { name: 'Acme' } }
+ * const result = renderPrompt(template, context)
+ * // => 'Hello John from Acme!'
+ *
+ * @example
+ * // Template with conditionals
+ * const template = `
+ * {{#if isAdmin}}
+ * You have admin privileges.
+ * {{else}}
+ * You are a regular user.
+ * {{/if}}
+ * `
+ *
+ * @example
+ * // Template with loops
+ * const template = `
+ * Recent items:
+ * {{#each items}}
+ * - {{this.name}}: {{this.status}}
+ * {{/each}}
+ * `
+ */
+
+import Handlebars from 'handlebars'
+import type { AgentContext } from '../types/langchain.types'
+import { config } from '../plugin.config'
+
+/**
+ * Check if a template contains Handlebars syntax
+ */
+export function hasTemplateVariables(template: string): boolean {
+    // Match {{ }} patterns (Handlebars syntax)
+    return /\{\{[^}]+\}\}/.test(template)
+}
+
+/**
+ * Render a prompt template with context data
+ *
+ * Uses Handlebars for template rendering, supporting:
+ * - Variables: {{key}}, {{nested.key}}
+ * - Conditionals: {{#if condition}}...{{/if}}
+ * - Loops: {{#each items}}...{{/each}}
+ * - Built-in helpers: {{#unless}}, {{#with}}, etc.
+ *
+ * @param template - The prompt template (may contain Handlebars syntax)
+ * @param context - The context data to inject into the template
+ * @returns Rendered prompt string
+ */
+export function renderPrompt(template: string, context: AgentContext): string {
+    // If no template variables, return as-is (optimization)
+    if (!hasTemplateVariables(template)) {
+        return template
+    }
+
+    try {
+        const compiled = Handlebars.compile(template, {
+            // Strict mode: throw error if variable is not found
+            strict: false,
+            // Don't escape HTML (prompts are not rendered in browser)
+            noEscape: true,
+        })
+
+        return compiled(context)
+    } catch (error) {
+        // Log error and return original template if rendering fails
+        if (config.debug) {
+            console.error('[PromptRenderer] Failed to render template:', error)
+        }
+        return template
+    }
+}
+
+/**
+ * Pre-compile a template for performance (optional)
+ * Use when rendering the same template multiple times
+ */
+export function compilePrompt(template: string): (context: AgentContext) => string {
+    const compiled = Handlebars.compile(template, {
+        strict: false,
+        noEscape: true,
+    })
+
+    return (context: AgentContext) => compiled(context)
+}

package/lib/providers.ts

@@ -0,0 +1,226 @@
+import { ChatOllama } from '@langchain/ollama'
+import { ChatOpenAI } from '@langchain/openai'
+import { ChatAnthropic } from '@langchain/anthropic'
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
+import { config, validateProviderConfig, isProviderAvailable, getAvailableProviders } from '../plugin.config'
+import type { ModelConfig, LLMProvider } from '../types/langchain.types'
+
+/**
+ * Create an OpenAI model instance
+ *
+ * @param modelConfig - Optional configuration overrides
+ * @returns ChatOpenAI instance
+ *
+ * @example
+ * // Use defaults from env
+ * const model = createOpenAIModel()
+ *
+ * // Use specific model
+ * const model = createOpenAIModel({ model: 'gpt-4o' })
+ *
+ * // Use with temperature
+ * const model = createOpenAIModel({ model: 'gpt-4o', temperature: 0.7 })
+ *
+ * // Use with LM Studio (local OpenAI-compatible server)
+ * const model = createOpenAIModel({
+ *     model: 'local-model',
+ *     options: {
+ *         baseUrl: 'http://localhost:1234/v1',
+ *         apiKey: 'lm-studio'  // LM Studio doesn't need real key
+ *     }
+ * })
+ */
+export function createOpenAIModel(modelConfig?: Partial<ModelConfig>): ChatOpenAI {
+    // Determine baseUrl:
+    // - If options.baseUrl is explicitly set to undefined, force real OpenAI API
+    // - If options.baseUrl is set to a string, use that
+    // - Otherwise, fall back to env var
+    const explicitlyUndefined = modelConfig?.options && 'baseUrl' in modelConfig.options && modelConfig.options.baseUrl === undefined
+    const baseUrl = explicitlyUndefined ? undefined : (modelConfig?.options?.baseUrl || config.providers.openai.baseUrl)
+
+    // Skip API key validation if using custom baseUrl (e.g., LM Studio)
+    const isLocalServer = !!baseUrl
+    if (!isLocalServer) {
+        validateProviderConfig('openai')
+    }
+
+    const chatOpenAI = new ChatOpenAI({
+        openAIApiKey: modelConfig?.options?.apiKey || config.providers.openai.apiKey || 'lm-studio',
+        modelName: modelConfig?.model || config.providers.openai.model,
+        temperature: modelConfig?.temperature ?? config.providers.openai.temperature,
+        maxTokens: modelConfig?.maxTokens,
+        configuration: baseUrl ? { baseURL: baseUrl } : undefined,
+        // LM Studio compatibility: disable strict tool calling which requires specific JSON Schema format
+        supportsStrictToolCalling: false,
+        // Enable verbose mode in debug to see what's sent to API
+        verbose: config.debug,
+    })
+
+    return chatOpenAI
+}
+
+/**
+ * Create an Anthropic model instance
+ *
+ * @param modelConfig - Optional configuration overrides
+ * @returns ChatAnthropic instance
+ *
+ * @example
+ * // Use defaults from env
+ * const model = createAnthropicModel()
+ *
+ * // Use specific model
+ * const model = createAnthropicModel({ model: 'claude-3-opus-20240229' })
+ */
+export function createAnthropicModel(modelConfig?: Partial<ModelConfig>): ChatAnthropic {
+    validateProviderConfig('anthropic')
+
+    return new ChatAnthropic({
+        anthropicApiKey: modelConfig?.options?.apiKey || config.providers.anthropic.apiKey,
+        modelName: modelConfig?.model || config.providers.anthropic.model,
+        temperature: modelConfig?.temperature ?? config.providers.anthropic.temperature,
+        maxTokens: modelConfig?.maxTokens,
+    })
+}
+
+/**
+ * Create an Ollama model instance (local)
+ *
+ * @param modelConfig - Optional configuration overrides
+ * @returns ChatOllama instance
+ *
+ * @example
+ * // Use defaults from env
+ * const model = createOllamaModel()
+ *
+ * // Use specific model
+ * const model = createOllamaModel({ model: 'llama3.2:3b' })
+ *
+ * // Use custom Ollama server
+ * const model = createOllamaModel({
+ *     model: 'qwen2.5:7b',
+ *     options: { baseUrl: 'http://192.168.1.100:11434' }
+ * })
+ */
+export function createOllamaModel(modelConfig?: Partial<ModelConfig>): ChatOllama {
+    return new ChatOllama({
+        baseUrl: modelConfig?.options?.baseUrl || config.providers.ollama.baseUrl,
+        model: modelConfig?.model || config.providers.ollama.model,
+        temperature: modelConfig?.temperature ?? config.providers.ollama.temperature,
+    })
+}
+
+/**
+ * Provider factory map
+ */
+const providerFactories: Record<LLMProvider, (cfg?: Partial<ModelConfig>) => BaseChatModel> = {
+    openai: createOpenAIModel,
+    anthropic: createAnthropicModel,
+    ollama: createOllamaModel,
+}
+
+/**
+ * Create a model instance based on configuration
+ *
+ * This is the main factory function for creating LLM instances.
+ * It selects the appropriate provider and applies configuration.
+ *
+ * @param modelConfig - Optional model configuration. If not provided, uses plugin defaults.
+ * @returns A LangChain chat model instance
+ *
+ * @example
+ * // Use plugin defaults (from env vars)
+ * const model = getModel()
+ *
+ * // Use specific provider with default model
+ * const model = getModel({ provider: 'openai' })
+ *
+ * // Use specific provider and model
+ * const model = getModel({ provider: 'anthropic', model: 'claude-3-opus-20240229' })
+ *
+ * // Use with temperature override
+ * const model = getModel({ provider: 'openai', model: 'gpt-4o', temperature: 0.7 })
+ *
+ * // Use Ollama with custom server
+ * const model = getModel({
+ *     provider: 'ollama',
+ *     model: 'qwen2.5:7b',
+ *     options: { baseUrl: 'http://192.168.1.100:11434' }
+ * })
+ */
+export function getModel(modelConfig?: Partial<ModelConfig>): BaseChatModel {
+    const provider = modelConfig?.provider || config.defaultProvider
+
+    const factory = providerFactories[provider]
+    if (!factory) {
+        throw new Error(
+            `Unsupported provider: ${provider}. ` +
+            `Supported providers: ${Object.keys(providerFactories).join(', ')}`
+        )
+    }
+
+    if (config.debug) {
+        const model = modelConfig?.model || config.providers[provider]?.model || 'default'
+        console.log(`[LangChain] Creating model - Provider: ${provider}, Model: ${model}`)
+    }
+
+    return factory(modelConfig)
+}
+
+/**
+ * Structured output method types supported by LangChain
+ */
+export type StructuredOutputMethod = 'functionCalling' | 'jsonMode' | 'jsonSchema'
+
+/**
+ * Determine the best structured output method for a given provider configuration
+ *
+ * Different providers/servers have different capabilities:
+ * - OpenAI API: Supports all methods (functionCalling is best)
+ * - Anthropic: Uses tool use (functionCalling)
+ * - Ollama: Supports functionCalling for most models
+ * - LM Studio (OpenAI-compatible): Only supports jsonSchema
+ *
+ * @param modelConfig - The model configuration being used
+ * @returns The recommended structured output method
+ *
+ * @example
+ * const method = getStructuredOutputMethod({ provider: 'openai' })
+ * const structuredModel = model.withStructuredOutput(schema, { method })
+ */
+export function getStructuredOutputMethod(modelConfig?: Partial<ModelConfig>): StructuredOutputMethod {
+    const provider = modelConfig?.provider || config.defaultProvider
+
+    // Check if using OpenAI provider with custom baseUrl (LM Studio, LocalAI, etc.)
+    if (provider === 'openai') {
+        // Check if baseUrl is explicitly set to undefined (force real OpenAI API)
+        const explicitlyUndefined = modelConfig?.options && 'baseUrl' in modelConfig.options && modelConfig.options.baseUrl === undefined
+        const baseUrl = explicitlyUndefined ? undefined : (modelConfig?.options?.baseUrl || config.providers.openai.baseUrl)
+
+        if (baseUrl) {
+            // Local OpenAI-compatible servers (LM Studio) use jsonSchema
+            if (config.debug) {
+                console.log('[LangChain] Using jsonSchema method for local OpenAI-compatible server')
+            }
+            return 'jsonSchema'
+        }
+        // Real OpenAI API - use functionCalling (most reliable)
+        return 'functionCalling'
+    }
+
+    // Anthropic - uses tool use which maps to functionCalling
+    if (provider === 'anthropic') {
+        return 'functionCalling'
+    }
+
+    // Ollama - most models support function calling
+    if (provider === 'ollama') {
+        return 'functionCalling'
+    }
+
+    // Default fallback
+    return 'functionCalling'
+}
+
+// Re-export utility functions from plugin.config for convenience
+export { isProviderAvailable, getAvailableProviders }