@nextsparkjs/plugin-langchain 0.1.0-beta.68 → 0.1.0-beta.73

package/.env.example

@@ -1,41 +1,73 @@
-# ===========================================
-# LangChain Plugin Configuration
-# ===========================================
+# ============================================
+# LANGCHAIN PLUGIN CONFIGURATION
+# ============================================
+#
+# Copy this file to .env and configure your LangChain settings
+# This file is loaded automatically by the LangChain plugin
+#
+# Priority: Plugin .env > Root .env > Defaults
+#
+# ============================================
 
+# ===========================
 # Plugin Settings
+# ===========================
+
+# Enable/disable the LangChain plugin
 LANGCHAIN_PLUGIN_ENABLED=true
+
+# Enable debug logging for development
 LANGCHAIN_PLUGIN_DEBUG=false
 
-# File Logging (core environment variable)
-# Logs to logger/ai/ when enabled
+# Enable file logging (logs to logger/ai/)
 LOG_ENABLED=false
 
-# ===========================================
+# ===========================
 # Ollama Configuration (Local)
-# ===========================================
-# Used by: single-agent
+# ===========================
 # No API key required - runs locally
+# Install Ollama: https://ollama.ai/download
+# Pull a model: ollama pull llama3.2:3b
 
 # Ollama server URL
 LANGCHAIN_OLLAMA_BASE_URL=http://localhost:11434
 
-# Model to use (run `ollama list` to see available models)
+# Default model (run `ollama list` to see available models)
 LANGCHAIN_OLLAMA_MODEL=llama3.2:3b
 
-# ===========================================
-# OpenAI-compatible Configuration (LM Studio)
-# ===========================================
-# Used by: orchestrator, task-assistant, customer-assistant, page-assistant
-#
-# LM Studio provides an OpenAI-compatible API on localhost.
-# 1. Start LM Studio and load a model
-# 2. Start the local server (default: http://localhost:1234/v1)
+# ===========================
+# OpenAI Configuration
+# ===========================
+# Get your key from: https://platform.openai.com/api-keys
+
+# OpenAI API Key
+OPENAI_API_KEY=your-openai-key-here
+
+# Default model for OpenAI provider
+LANGCHAIN_OPENAI_MODEL=gpt-4o-mini
+
+# OpenAI-compatible base URL (for LM Studio, local servers)
+# LM Studio: http://localhost:1234/v1
+# Leave empty for official OpenAI API
+# LANGCHAIN_OPENAI_BASE_URL=http://localhost:1234/v1
+
+# ===========================
+# Anthropic Configuration
+# ===========================
+# Get your key from: https://console.anthropic.com/
+
+# Anthropic API Key
+ANTHROPIC_API_KEY=your-anthropic-key-here
+
+# Default model for Anthropic provider
+LANGCHAIN_ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
 
-# LM Studio server URL
-LANGCHAIN_OPENAI_BASE_URL=http://localhost:1234/v1
+# ===========================
+# Feature Flags
+# ===========================
 
-# Model name as loaded in LM Studio
-LANGCHAIN_OPENAI_MODEL=your-loaded-model-name
+# Enable graph-based orchestrator (recommended for multi-agent)
+LANGCHAIN_USE_GRAPH_ORCHESTRATOR=true
 
-# API Key (LM Studio doesn't require a real key, use any string)
-OPENAI_API_KEY=lm-studio
+# Enable verbose debug output
+LANGCHAIN_DEBUG=false

package/docs/01-getting-started/03-configuration.md

@@ -687,6 +687,53 @@ Configure how structured output works for multi-provider compatibility:
 
 ## Environment Variables
 
+### ⭐ Plugin-Level Environment Configuration (Recommended)
+
+The LangChain plugin supports **plugin-level `.env` files** that take priority over root environment variables. This provides isolation and modularity for your AI configuration.
+
+#### Setup
+
+1. **Copy the example file:**
+   ```bash
+   cp contents/plugins/langchain/.env.example contents/plugins/langchain/.env
+   ```
+
+2. **Configure your settings:**
+   ```env
+   # Plugin Settings
+   LANGCHAIN_PLUGIN_ENABLED=true
+   LANGCHAIN_PLUGIN_DEBUG=false
+
+   # Ollama Configuration (Local)
+   LANGCHAIN_OLLAMA_BASE_URL=http://localhost:11434
+   LANGCHAIN_OLLAMA_MODEL=llama3.2:3b
+
+   # OpenAI Configuration (LM Studio or OpenAI API)
+   LANGCHAIN_OPENAI_BASE_URL=http://localhost:1234/v1
+   LANGCHAIN_OPENAI_MODEL=gpt-4o-mini
+   OPENAI_API_KEY=your-api-key
+   ```
+
+#### Priority System
+
+The plugin environment loader uses this priority:
+
+1. **Plugin `.env`** (`contents/plugins/langchain/.env`) - Highest priority
+2. **Root `.env`** (`/.env`) - Fallback for variables not in plugin .env
+3. **Built-in defaults** - Lowest priority
+
+This means you can:
+- Keep API keys in the root `.env` (shared across plugins)
+- Override specific settings in the plugin `.env` (isolated configuration)
+
+#### Benefits
+
+- ✅ **Isolation**: LangChain config doesn't pollute root `.env`
+- ✅ **Modularity**: Each plugin manages its own environment
+- ✅ **Security**: API keys can be scoped to specific plugins
+- ✅ **Flexibility**: Different configurations for different plugins
+- ✅ **Fallback**: Automatically uses root `.env` when plugin `.env` doesn't define a variable
+
 ### Provider Configuration
 
 ```env

package/lib/plugin-env.ts

@@ -0,0 +1,180 @@
+/**
+ * LangChain Plugin Environment Configuration (Server-Only)
+ *
+ * Uses centralized plugin environment loader from core
+ * Provides type-safe access to LangChain configuration
+ */
+
+import { getPluginEnv } from '@nextsparkjs/core/lib/plugins/env-loader'
+
+interface LangChainPluginEnvConfig {
+  // Plugin settings
+  LANGCHAIN_PLUGIN_ENABLED?: string
+  LANGCHAIN_PLUGIN_DEBUG?: string
+  LOG_ENABLED?: string
+
+  // Ollama Configuration
+  LANGCHAIN_OLLAMA_BASE_URL?: string
+  LANGCHAIN_OLLAMA_MODEL?: string
+
+  // OpenAI Configuration
+  LANGCHAIN_OPENAI_BASE_URL?: string
+  LANGCHAIN_OPENAI_MODEL?: string
+  OPENAI_API_KEY?: string
+
+  // Anthropic Configuration
+  LANGCHAIN_ANTHROPIC_MODEL?: string
+  ANTHROPIC_API_KEY?: string
+
+  // Feature Flags
+  LANGCHAIN_USE_GRAPH_ORCHESTRATOR?: string
+  LANGCHAIN_DEBUG?: string
+}
+
+class PluginEnvironment {
+  private static instance: PluginEnvironment
+  private config: LangChainPluginEnvConfig = {}
+  private loaded = false
+
+  private constructor() {
+    this.loadEnvironment()
+  }
+
+  public static getInstance(): PluginEnvironment {
+    if (!PluginEnvironment.instance) {
+      PluginEnvironment.instance = new PluginEnvironment()
+    }
+    return PluginEnvironment.instance
+  }
+
+  private loadEnvironment(forceReload: boolean = false): void {
+    if (this.loaded && !forceReload) return
+
+    try {
+      // Use centralized plugin env loader
+      const env = getPluginEnv('langchain')
+
+      this.config = {
+        // Plugin settings
+        LANGCHAIN_PLUGIN_ENABLED: env.LANGCHAIN_PLUGIN_ENABLED || 'true',
+        LANGCHAIN_PLUGIN_DEBUG: env.LANGCHAIN_PLUGIN_DEBUG || 'false',
+        LOG_ENABLED: env.LOG_ENABLED || 'false',
+
+        // Ollama Configuration
+        LANGCHAIN_OLLAMA_BASE_URL: env.LANGCHAIN_OLLAMA_BASE_URL || 'http://localhost:11434',
+        LANGCHAIN_OLLAMA_MODEL: env.LANGCHAIN_OLLAMA_MODEL || 'llama3.2:3b',
+
+        // OpenAI Configuration
+        LANGCHAIN_OPENAI_BASE_URL: env.LANGCHAIN_OPENAI_BASE_URL,
+        LANGCHAIN_OPENAI_MODEL: env.LANGCHAIN_OPENAI_MODEL || 'gpt-4o-mini',
+        OPENAI_API_KEY: env.OPENAI_API_KEY,
+
+        // Anthropic Configuration
+        LANGCHAIN_ANTHROPIC_MODEL: env.LANGCHAIN_ANTHROPIC_MODEL || 'claude-3-5-sonnet-20241022',
+        ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY,
+
+        // Feature Flags
+        LANGCHAIN_USE_GRAPH_ORCHESTRATOR: env.LANGCHAIN_USE_GRAPH_ORCHESTRATOR || 'true',
+        LANGCHAIN_DEBUG: env.LANGCHAIN_DEBUG || 'false',
+      }
+
+      this.logLoadedConfiguration()
+      this.loaded = true
+    } catch (error) {
+      console.error('[LangChain Plugin] Failed to load environment:', error)
+      this.loaded = true
+    }
+  }
+
+  private logLoadedConfiguration(): void {
+    if (process.env.NODE_ENV === 'development' && this.config.LANGCHAIN_PLUGIN_DEBUG === 'true') {
+      console.log('[LangChain Plugin] Environment Configuration:')
+      console.log('  → Plugin Settings:')
+      console.log(`    - LANGCHAIN_PLUGIN_ENABLED: ${this.config.LANGCHAIN_PLUGIN_ENABLED}`)
+      console.log(`    - LANGCHAIN_PLUGIN_DEBUG: ${this.config.LANGCHAIN_PLUGIN_DEBUG}`)
+      console.log('  → Ollama Configuration:')
+      console.log(`    - LANGCHAIN_OLLAMA_BASE_URL: ${this.config.LANGCHAIN_OLLAMA_BASE_URL}`)
+      console.log(`    - LANGCHAIN_OLLAMA_MODEL: ${this.config.LANGCHAIN_OLLAMA_MODEL}`)
+      console.log('  → OpenAI Configuration:')
+      console.log(`    - LANGCHAIN_OPENAI_BASE_URL: ${this.config.LANGCHAIN_OPENAI_BASE_URL || 'not set'}`)
+      console.log(`    - LANGCHAIN_OPENAI_MODEL: ${this.config.LANGCHAIN_OPENAI_MODEL}`)
+      console.log(`    - OPENAI_API_KEY: ${this.config.OPENAI_API_KEY ? '✓ set' : '✗ not set'}`)
+      console.log('  → Anthropic Configuration:')
+      console.log(`    - LANGCHAIN_ANTHROPIC_MODEL: ${this.config.LANGCHAIN_ANTHROPIC_MODEL}`)
+      console.log(`    - ANTHROPIC_API_KEY: ${this.config.ANTHROPIC_API_KEY ? '✓ set' : '✗ not set'}`)
+      console.log()
+    }
+  }
+
+  public getConfig(): LangChainPluginEnvConfig {
+    if (!this.loaded) {
+      this.loadEnvironment()
+    }
+    return this.config
+  }
+
+  // Helper methods
+  public isPluginEnabled(): boolean {
+    return this.getConfig().LANGCHAIN_PLUGIN_ENABLED !== 'false'
+  }
+
+  public isDebugEnabled(): boolean {
+    return this.getConfig().LANGCHAIN_PLUGIN_DEBUG === 'true' || this.getConfig().LANGCHAIN_DEBUG === 'true'
+  }
+
+  public isLogEnabled(): boolean {
+    return this.getConfig().LOG_ENABLED === 'true'
+  }
+
+  public getOllamaBaseUrl(): string {
+    return this.getConfig().LANGCHAIN_OLLAMA_BASE_URL || 'http://localhost:11434'
+  }
+
+  public getOllamaModel(): string {
+    return this.getConfig().LANGCHAIN_OLLAMA_MODEL || 'llama3.2:3b'
+  }
+
+  public getOpenAIBaseUrl(): string | undefined {
+    return this.getConfig().LANGCHAIN_OPENAI_BASE_URL
+  }
+
+  public getOpenAIModel(): string {
+    return this.getConfig().LANGCHAIN_OPENAI_MODEL || 'gpt-4o-mini'
+  }
+
+  public getOpenAIApiKey(): string | undefined {
+    return this.getConfig().OPENAI_API_KEY
+  }
+
+  public getAnthropicModel(): string {
+    return this.getConfig().LANGCHAIN_ANTHROPIC_MODEL || 'claude-3-5-sonnet-20241022'
+  }
+
+  public getAnthropicApiKey(): string | undefined {
+    return this.getConfig().ANTHROPIC_API_KEY
+  }
+
+  public isGraphOrchestratorEnabled(): boolean {
+    return this.getConfig().LANGCHAIN_USE_GRAPH_ORCHESTRATOR === 'true'
+  }
+
+  public reload(): void {
+    this.loaded = false
+    this.loadEnvironment(true)
+  }
+}
+
+export const pluginEnv = PluginEnvironment.getInstance()
+
+// Convenience exports
+export const isPluginEnabled = () => pluginEnv.isPluginEnabled()
+export const isDebugEnabled = () => pluginEnv.isDebugEnabled()
+export const isLogEnabled = () => pluginEnv.isLogEnabled()
+export const getOllamaBaseUrl = () => pluginEnv.getOllamaBaseUrl()
+export const getOllamaModel = () => pluginEnv.getOllamaModel()
+export const getOpenAIBaseUrl = () => pluginEnv.getOpenAIBaseUrl()
+export const getOpenAIModel = () => pluginEnv.getOpenAIModel()
+export const getOpenAIApiKey = () => pluginEnv.getOpenAIApiKey()
+export const getAnthropicModel = () => pluginEnv.getAnthropicModel()
+export const getAnthropicApiKey = () => pluginEnv.getAnthropicApiKey()
+export const isGraphOrchestratorEnabled = () => pluginEnv.isGraphOrchestratorEnabled()

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@nextsparkjs/plugin-langchain",
-  "version": "0.1.0-beta.68",
+  "version": "0.1.0-beta.73",
   "private": false,
   "main": "./plugin.config.ts",
   "requiredPlugins": [],
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.36.0",
+    "@anthropic-ai/sdk": "^0.71.0",
     "@langchain/anthropic": "^0.3.0",
     "@langchain/community": "^0.3.0",
     "@langchain/core": "^0.3.0",
@@ -16,17 +16,17 @@
     "langchain": "^0.3.0"
   },
   "peerDependencies": {
+    "@nextsparkjs/core": "workspace:*",
     "@tanstack/react-query": "^5.0.0",
     "lucide-react": "^0.539.0",
     "next": "^15.0.0",
     "next-intl": "^4.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "zod": "^4.0.0",
-    "@nextsparkjs/core": "0.1.0-beta.68"
+    "zod": "^4.0.0"
   },
   "nextspark": {
     "type": "plugin",
     "name": "langchain"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 NextSpark
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.