@nextsparkjs/plugin-langchain 0.1.0-beta.1 → 0.1.0-beta.101

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/LICENSE

@@ -0,0 +1,21 @@
+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.

package/api/observability/docs.md

@@ -0,0 +1,260 @@
+# Observability API
+
+Monitor AI agent traces, spans, and performance metrics for LangChain-powered applications.
+
+## Overview
+
+The Observability API provides comprehensive monitoring for AI agents, including execution traces, detailed spans, and aggregated metrics. This API is designed for administrators to debug, analyze, and optimize AI agent performance.
+
+**Access Level:** Admin only (superadmin or developer roles)
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+**Role Requirements:**
+- `superadmin` or `developer` role required
+
+## Endpoints
+
+### List Traces
+`GET /api/langchain/observability/traces`
+
+Returns a paginated list of root traces (agent executions) with cursor-based pagination.
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| status | string | - | Filter by status: `running`, `success`, `error` |
+| agent | string | - | Filter by agent name |
+| teamId | string | - | Filter by team ID |
+| from | datetime | - | Start date filter (ISO 8601) |
+| to | datetime | - | End date filter (ISO 8601) |
+| limit | number | 50 | Results per page (max: 100) |
+| cursor | string | - | Pagination cursor (ISO timestamp) |
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "traces": [
+      {
+        "traceId": "trace_abc123",
+        "userId": "user_456",
+        "teamId": "team_789",
+        "sessionId": "sess_xyz",
+        "agentName": "customer-support-agent",
+        "agentType": "conversational",
+        "status": "success",
+        "input": "How do I reset my password?",
+        "output": "To reset your password...",
+        "startedAt": "2024-01-15T10:30:00Z",
+        "endedAt": "2024-01-15T10:30:05Z",
+        "durationMs": 5234,
+        "inputTokens": 150,
+        "outputTokens": 320,
+        "totalTokens": 470,
+        "totalCost": 0.0047,
+        "llmCalls": 2,
+        "toolCalls": 1,
+        "metadata": {},
+        "tags": ["support", "password"],
+        "createdAt": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "hasMore": true,
+    "nextCursor": "2024-01-15T10:29:00Z"
+  }
+}
+```
+
+### Get Trace Detail
+`GET /api/langchain/observability/traces/[traceId]`
+
+Returns detailed information about a specific trace, including spans and child traces.
+
+**Path Parameters:**
+- `traceId` (string, required): The trace ID
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "trace": {
+      "traceId": "trace_abc123",
+      "userId": "user_456",
+      "teamId": "team_789",
+      "sessionId": "sess_xyz",
+      "agentName": "customer-support-agent",
+      "agentType": "conversational",
+      "status": "success",
+      "input": "How do I reset my password?",
+      "output": "To reset your password...",
+      "startedAt": "2024-01-15T10:30:00Z",
+      "endedAt": "2024-01-15T10:30:05Z",
+      "durationMs": 5234,
+      "inputTokens": 150,
+      "outputTokens": 320,
+      "totalTokens": 470,
+      "totalCost": 0.0047,
+      "llmCalls": 2,
+      "toolCalls": 1,
+      "metadata": {},
+      "tags": ["support", "password"],
+      "createdAt": "2024-01-15T10:30:00Z"
+    },
+    "spans": [
+      {
+        "spanId": "span_001",
+        "traceId": "trace_abc123",
+        "name": "ChatOpenAI",
+        "type": "llm",
+        "provider": "openai",
+        "model": "gpt-4",
+        "inputTokens": 100,
+        "outputTokens": 200,
+        "status": "success",
+        "startedAt": "2024-01-15T10:30:01Z",
+        "endedAt": "2024-01-15T10:30:03Z",
+        "durationMs": 2100,
+        "depth": 0,
+        "createdAt": "2024-01-15T10:30:01Z"
+      },
+      {
+        "spanId": "span_002",
+        "traceId": "trace_abc123",
+        "name": "search_knowledge_base",
+        "type": "tool",
+        "toolName": "search_knowledge_base",
+        "toolInput": {"query": "password reset"},
+        "toolOutput": {"results": [...]},
+        "status": "success",
+        "startedAt": "2024-01-15T10:30:02Z",
+        "endedAt": "2024-01-15T10:30:02Z",
+        "durationMs": 450,
+        "depth": 1,
+        "createdAt": "2024-01-15T10:30:02Z"
+      }
+    ],
+    "childTraces": [],
+    "childSpansMap": {},
+    "parentTrace": null
+  }
+}
+```
+
+### Get Metrics
+`GET /api/langchain/observability/metrics`
+
+Returns aggregated metrics for a time period.
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| period | string | 24h | Time period: `1h`, `24h`, `7d`, `30d` |
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "period": "24h",
+    "totalTraces": 1250,
+    "successTraces": 1180,
+    "errorTraces": 70,
+    "avgLatency": 3456,
+    "totalTokens": 2450000
+  }
+}
+```
+
+## Data Models
+
+### Trace
+
+| Field | Type | Description |
+|-------|------|-------------|
+| traceId | string | Unique trace identifier |
+| userId | string | User who initiated the trace |
+| teamId | string | Team context |
+| sessionId | string | Associated conversation session (optional) |
+| agentName | string | Name of the AI agent |
+| agentType | string | Type of agent (optional) |
+| parentId | string | Parent trace ID for nested agents (optional) |
+| input | string | Input to the agent |
+| output | string | Output from the agent (optional) |
+| status | enum | `running`, `success`, `error` |
+| error | string | Error message if status is error (optional) |
+| errorType | string | Error type classification (optional) |
+| errorStack | string | Error stack trace (optional) |
+| startedAt | datetime | When the trace started |
+| endedAt | datetime | When the trace ended (optional) |
+| durationMs | number | Duration in milliseconds (optional) |
+| inputTokens | number | Input token count |
+| outputTokens | number | Output token count |
+| totalTokens | number | Total token count |
+| totalCost | number | Estimated cost in USD |
+| llmCalls | number | Number of LLM API calls |
+| toolCalls | number | Number of tool invocations |
+| metadata | object | Custom metadata |
+| tags | string[] | Tags for categorization (optional) |
+| createdAt | datetime | Record creation timestamp |
+
+### Span
+
+| Field | Type | Description |
+|-------|------|-------------|
+| spanId | string | Unique span identifier |
+| traceId | string | Parent trace ID |
+| parentSpanId | string | Parent span ID for nesting (optional) |
+| name | string | Span name |
+| type | enum | `llm`, `tool`, `chain`, `retriever` |
+| provider | string | LLM provider (e.g., openai, anthropic) (optional) |
+| model | string | Model name (optional) |
+| inputTokens | number | Input tokens for LLM spans (optional) |
+| outputTokens | number | Output tokens for LLM spans (optional) |
+| toolName | string | Tool name for tool spans (optional) |
+| toolInput | any | Tool input data (optional) |
+| toolOutput | any | Tool output data (optional) |
+| input | any | Span input (optional) |
+| output | any | Span output (optional) |
+| status | enum | `running`, `success`, `error` |
+| error | string | Error message (optional) |
+| startedAt | datetime | When the span started |
+| endedAt | datetime | When the span ended (optional) |
+| durationMs | number | Duration in milliseconds (optional) |
+| depth | number | Nesting depth level |
+| createdAt | datetime | Record creation timestamp |
+
+### Metrics
+
+| Field | Type | Description |
+|-------|------|-------------|
+| period | string | Time period queried |
+| totalTraces | number | Total number of traces |
+| successTraces | number | Traces with success status |
+| errorTraces | number | Traces with error status |
+| avgLatency | number | Average duration in milliseconds |
+| totalTokens | number | Total tokens consumed |
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Invalid period parameter |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Admin access required |
+| 404 | Trace not found |
+| 500 | Internal server error |
+
+## Related APIs
+
+- **[Sessions](/api/langchain/sessions)** - Conversation session management
+- **[Teams](/api/v1/teams)** - Team management
+- **[Users](/api/v1/users)** - User management

package/api/observability/metrics/route.ts

@@ -7,6 +7,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 
 interface MetricsRow {
@@ -24,7 +25,7 @@ const PERIOD_HOURS: Record<string, number> = {
   '30d': 24 * 30,
 }
 
-export async function GET(req: NextRequest) {
+const getHandler = async (req: NextRequest) => {
   // 1. Authenticate (superadmin only)
   const authResult = await authenticateRequest(req)
   if (!authResult.success || !authResult.user) {
@@ -108,3 +109,5 @@ export async function GET(req: NextRequest) {
     )
   }
 }
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/api/observability/presets.ts

@@ -0,0 +1,141 @@
+/**
+ * API Presets for LangChain Observability
+ *
+ * Predefined API calls for traces and metrics monitoring.
+ * Admin access required (superadmin or developer roles).
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Monitor AI traces and performance metrics',
+  presets: [
+    {
+      id: 'list-traces',
+      title: 'List Recent Traces',
+      description: 'Get the most recent AI agent traces',
+      method: 'GET',
+      params: {
+        limit: 50
+      },
+      tags: ['read', 'list', 'traces']
+    },
+    {
+      id: 'list-running',
+      title: 'List Running Traces',
+      description: 'Get all currently running agent traces',
+      method: 'GET',
+      params: {
+        status: 'running',
+        limit: 50
+      },
+      tags: ['read', 'filter', 'traces']
+    },
+    {
+      id: 'list-success',
+      title: 'List Successful Traces',
+      description: 'Get completed successful traces',
+      method: 'GET',
+      params: {
+        status: 'success',
+        limit: 50
+      },
+      tags: ['read', 'filter', 'traces']
+    },
+    {
+      id: 'list-errors',
+      title: 'List Error Traces',
+      description: 'Get traces that ended with an error',
+      method: 'GET',
+      params: {
+        status: 'error',
+        limit: 50
+      },
+      tags: ['read', 'filter', 'traces']
+    },
+    {
+      id: 'list-by-agent',
+      title: 'List by Agent',
+      description: 'Filter traces by a specific agent name',
+      method: 'GET',
+      params: {
+        agent: '{{agentName}}',
+        limit: 50
+      },
+      tags: ['read', 'filter', 'traces']
+    },
+    {
+      id: 'list-by-team',
+      title: 'List by Team',
+      description: 'Filter traces for a specific team',
+      method: 'GET',
+      params: {
+        teamId: '{{teamId}}',
+        limit: 50
+      },
+      tags: ['read', 'filter', 'traces']
+    },
+    {
+      id: 'list-by-date-range',
+      title: 'List by Date Range',
+      description: 'Filter traces within a specific time period',
+      method: 'GET',
+      params: {
+        from: '{{fromDate}}',
+        to: '{{toDate}}',
+        limit: 50
+      },
+      tags: ['read', 'filter', 'traces']
+    },
+    {
+      id: 'get-trace-detail',
+      title: 'Get Trace Detail',
+      description: 'Get detailed information about a specific trace including spans',
+      method: 'GET',
+      pathParams: {
+        traceId: '{{traceId}}'
+      },
+      tags: ['read', 'detail', 'traces']
+    },
+    {
+      id: 'get-metrics-1h',
+      title: 'Get Metrics (1 Hour)',
+      description: 'Get aggregated metrics for the last hour',
+      method: 'GET',
+      params: {
+        period: '1h'
+      },
+      tags: ['read', 'metrics']
+    },
+    {
+      id: 'get-metrics-24h',
+      title: 'Get Metrics (24 Hours)',
+      description: 'Get aggregated metrics for the last 24 hours',
+      method: 'GET',
+      params: {
+        period: '24h'
+      },
+      tags: ['read', 'metrics']
+    },
+    {
+      id: 'get-metrics-7d',
+      title: 'Get Metrics (7 Days)',
+      description: 'Get aggregated metrics for the last 7 days',
+      method: 'GET',
+      params: {
+        period: '7d'
+      },
+      tags: ['read', 'metrics']
+    },
+    {
+      id: 'get-metrics-30d',
+      title: 'Get Metrics (30 Days)',
+      description: 'Get aggregated metrics for the last 30 days',
+      method: 'GET',
+      params: {
+        period: '30d'
+      },
+      tags: ['read', 'metrics']
+    }
+  ]
+})

package/api/observability/traces/[traceId]/route.ts

@@ -7,6 +7,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 import type { Trace, Span } from '../../../../types/observability.types'
 
@@ -62,10 +63,10 @@ interface SpanRow {
   createdAt: Date
 }
 
-export async function GET(
+const getHandler = async (
   req: NextRequest,
   { params }: { params: Promise<{ traceId: string }> }
-) {
+) => {
   // 1. Authenticate (superadmin only)
   const authResult = await authenticateRequest(req)
   if (!authResult.success || !authResult.user) {
@@ -396,3 +397,5 @@ export async function GET(
     )
   }
 }
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/api/observability/traces/route.ts

@@ -7,6 +7,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 import type { Trace } from '../../../types/observability.types'
 
@@ -38,7 +39,7 @@ interface TraceRow {
   createdAt: Date
 }
 
-export async function GET(req: NextRequest) {
+const getHandler = async (req: NextRequest) => {
   // 1. Authenticate (superadmin only)
   const authResult = await authenticateRequest(req)
   if (!authResult.success || !authResult.user) {
@@ -203,3 +204,5 @@ export async function GET(req: NextRequest) {
     )
   }
 }
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/api/sessions/docs.md

@@ -0,0 +1,202 @@
+# Sessions API
+
+Manage AI conversation sessions with message history, pinning, and per-user limits.
+
+## Overview
+
+The Sessions API allows you to create, read, update, and delete AI conversation sessions. Sessions store message history for LangChain-powered chatbots and AI assistants. Each user is limited to 50 conversations per team.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+**Required Header:**
+- `x-team-id` (string): Team context for multi-tenancy
+
+## Endpoints
+
+### List Conversations
+`GET /api/langchain/sessions`
+
+Returns all conversations for the current user in the team context.
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "sessions": [
+      {
+        "sessionId": "sess_abc123",
+        "name": "Project Planning",
+        "messageCount": 24,
+        "firstMessage": "Help me plan my new project...",
+        "isPinned": true,
+        "createdAt": "2024-01-15T10:30:00Z",
+        "updatedAt": "2024-01-15T14:45:00Z"
+      }
+    ],
+    "count": 12,
+    "maxAllowed": 50
+  }
+}
+```
+
+### Get Single Conversation
+`GET /api/langchain/sessions?id=[sessionId]`
+
+Returns a specific conversation by ID.
+
+**Query Parameters:**
+- `id` (string, required): Session ID
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "sessionId": "sess_abc123",
+    "name": "Project Planning",
+    "messageCount": 24,
+    "firstMessage": "Help me plan my new project...",
+    "isPinned": true,
+    "createdAt": "2024-01-15T10:30:00Z",
+    "updatedAt": "2024-01-15T14:45:00Z"
+  }
+}
+```
+
+### Create Conversation
+`POST /api/langchain/sessions`
+
+Create a new conversation session. Limited to 50 conversations per user per team.
+
+**Request Body:**
+```json
+{
+  "name": "My New Conversation"
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "success": true,
+  "data": {
+    "sessionId": "sess_xyz789",
+    "name": "My New Conversation",
+    "createdAt": "2024-01-15T16:00:00Z"
+  }
+}
+```
+
+**Limit Reached Response (400):**
+```json
+{
+  "success": false,
+  "error": "CONVERSATION_LIMIT_REACHED",
+  "message": "Maximum of 50 conversations reached. Delete an existing conversation to create a new one.",
+  "data": {
+    "currentCount": 50,
+    "maxAllowed": 50,
+    "oldestSession": {
+      "sessionId": "sess_old123",
+      "name": "Old Conversation",
+      "updatedAt": "2024-01-01T10:00:00Z"
+    }
+  }
+}
+```
+
+### Update Conversation
+`PATCH /api/langchain/sessions`
+
+Update a conversation's name or pinned status.
+
+**Request Body:**
+```json
+{
+  "sessionId": "sess_abc123",
+  "name": "Renamed Conversation",
+  "isPinned": true
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| sessionId | string | Yes | Session ID to update |
+| name | string | No | New name for the conversation |
+| isPinned | boolean | No | Pin/unpin the conversation |
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "sessionId": "sess_abc123",
+    "name": "Renamed Conversation",
+    "messageCount": 24,
+    "firstMessage": "Help me plan my new project...",
+    "isPinned": true,
+    "createdAt": "2024-01-15T10:30:00Z",
+    "updatedAt": "2024-01-15T16:30:00Z"
+  }
+}
+```
+
+### Delete Conversation
+`DELETE /api/langchain/sessions`
+
+Delete a conversation and all its message history.
+
+**Request Body:**
+```json
+{
+  "sessionId": "sess_abc123"
+}
+```
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "message": "Conversation deleted successfully",
+  "sessionId": "sess_abc123"
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| sessionId | string | Unique session identifier |
+| name | string | User-defined conversation name |
+| messageCount | number | Number of messages in the conversation |
+| firstMessage | string | Preview of the first message |
+| isPinned | boolean | Whether the conversation is pinned |
+| createdAt | datetime | When the conversation was created |
+| updatedAt | datetime | When the conversation was last updated |
+
+## Limits
+
+| Limit | Value | Description |
+|-------|-------|-------------|
+| MAX_CONVERSATIONS | 50 | Maximum conversations per user per team |
+
+## Error Responses
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | TEAM_CONTEXT_REQUIRED | Missing x-team-id header |
+| 400 | CONVERSATION_LIMIT_REACHED | User has reached 50 conversation limit |
+| 400 | - | Session ID is required (for PATCH/DELETE) |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 404 | - | Conversation not found |
+| 500 | - | Internal server error |
+
+## Related APIs
+
+- **[Observability](/api/langchain/observability)** - Monitor AI traces and metrics
+- **[Teams](/api/v1/teams)** - Team management

package/api/sessions/presets.ts

@@ -0,0 +1,104 @@
+/**
+ * API Presets for LangChain Sessions
+ *
+ * Predefined API calls for conversation management.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage AI conversation sessions',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Conversations',
+      description: 'Get all conversations for the current user',
+      method: 'GET',
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'get-by-id',
+      title: 'Get Conversation by ID',
+      description: 'Get a specific conversation by its session ID',
+      method: 'GET',
+      params: {
+        id: '{{sessionId}}'
+      },
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      tags: ['read', 'detail']
+    },
+    {
+      id: 'create-new',
+      title: 'Create New Conversation',
+      description: 'Create a new AI conversation session',
+      method: 'POST',
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      payload: {
+        name: 'New Conversation'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'rename-conversation',
+      title: 'Rename Conversation',
+      description: 'Update the name of an existing conversation',
+      method: 'PATCH',
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      payload: {
+        sessionId: '{{sessionId}}',
+        name: '{{newName}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'pin-conversation',
+      title: 'Pin Conversation',
+      description: 'Pin a conversation to keep it at the top',
+      method: 'PATCH',
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      payload: {
+        sessionId: '{{sessionId}}',
+        isPinned: true
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'unpin-conversation',
+      title: 'Unpin Conversation',
+      description: 'Unpin a conversation',
+      method: 'PATCH',
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      payload: {
+        sessionId: '{{sessionId}}',
+        isPinned: false
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-conversation',
+      title: 'Delete Conversation',
+      description: 'Delete a conversation and all its message history',
+      method: 'DELETE',
+      headers: {
+        'x-team-id': '{{teamId}}'
+      },
+      payload: {
+        sessionId: '{{sessionId}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/api/sessions/route.ts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { dbMemoryStore, CONVERSATION_LIMITS } from '../../lib/db-memory-store'
 import { config } from '../../plugin.config'
 import type {
@@ -36,7 +37,7 @@ function toApiConversationInfo(conv: {
  * Without id: returns list of all conversations
  * With id: returns single conversation details
  */
-export async function GET(req: NextRequest) {
+const getHandler = async (req: NextRequest) => {
     // 1. Auth
     const authResult = await authenticateRequest(req)
     if (!authResult.success || !authResult.user) {
@@ -103,13 +104,15 @@ export async function GET(req: NextRequest) {
     }
 }
 
+export const GET = withRateLimitTier(getHandler, 'read')
+
 /**
  * POST - Create a new conversation
  *
  * Body:
  * - name: Optional name for the conversation
  */
-export async function POST(req: NextRequest) {
+const postHandler = async (req: NextRequest) => {
     // 1. Auth
     const authResult = await authenticateRequest(req)
     if (!authResult.success || !authResult.user) {
@@ -183,6 +186,8 @@ export async function POST(req: NextRequest) {
     }
 }
 
+export const POST = withRateLimitTier(postHandler, 'write')
+
 /**
  * PATCH - Update a conversation (rename, pin/unpin)
  *
@@ -191,7 +196,7 @@ export async function POST(req: NextRequest) {
  * - name: New name (optional)
  * - isPinned: New pin status (optional)
  */
-export async function PATCH(req: NextRequest) {
+const patchHandler = async (req: NextRequest) => {
     // 1. Auth
     const authResult = await authenticateRequest(req)
     if (!authResult.success || !authResult.user) {
@@ -262,13 +267,15 @@ export async function PATCH(req: NextRequest) {
     }
 }
 
+export const PATCH = withRateLimitTier(patchHandler, 'write')
+
 /**
  * DELETE - Delete a conversation
  *
  * Body:
  * - sessionId: Session ID to delete (required)
  */
-export async function DELETE(req: NextRequest) {
+const deleteHandler = async (req: NextRequest) => {
     // 1. Auth
     const authResult = await authenticateRequest(req)
     if (!authResult.success || !authResult.user) {
@@ -330,3 +337,5 @@ export async function DELETE(req: NextRequest) {
         )
     }
 }
+
+export const DELETE = withRateLimitTier(deleteHandler, 'write')

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.1",
+  "version": "0.1.0-beta.101",
   "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,7 +16,7 @@
     "langchain": "^0.3.0"
   },
   "peerDependencies": {
-    "@nextsparkjs/core": "workspace:*",
+    "@nextsparkjs/core": "*",
     "@tanstack/react-query": "^5.0.0",
     "lucide-react": "^0.539.0",
     "next": "^15.0.0",
@@ -24,5 +24,9 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.0.0"
+  },
+  "nextspark": {
+    "type": "plugin",
+    "name": "langchain"
   }
-}
+}