@nextsparkjs/plugin-langchain 0.1.0-beta.42 → 0.1.0-beta.45

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/plugin-langchain",
-  "version": "0.1.0-beta.42",
+  "version": "0.1.0-beta.45",
   "private": false,
   "main": "./plugin.config.ts",
   "requiredPlugins": [],
@@ -23,7 +23,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.0.0",
-    "@nextsparkjs/core": "0.1.0-beta.42"
+    "@nextsparkjs/core": "0.1.0-beta.45"
   },
   "nextspark": {
     "type": "plugin",