@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/docs/02-core-concepts/01-architecture.md

@@ -0,0 +1,566 @@
+# Architecture
+
+This section explains the technical architecture of the LangChain plugin, including core patterns, data flow, and design decisions.
+
+## System Architecture
+
+### Layer Model
+
+The plugin follows a layered architecture with clear responsibilities:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                           API LAYER                                  │
+│  Theme API endpoints (e.g., /api/v1/theme/ai/chat)                  │
+├─────────────────────────────────────────────────────────────────────┤
+│                        THEME LAYER                                   │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
+│  │ Config       │  │ Agents       │  │ Tools        │              │
+│  │ Definition   │  │ (Prompts)    │  │ (CRUD ops)   │              │
+│  └──────────────┘  └──────────────┘  └──────────────┘              │
+├─────────────────────────────────────────────────────────────────────┤
+│                        PLUGIN LAYER                                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
+│  │ Agent        │  │ Memory       │  │ Provider     │              │
+│  │ Factory      │  │ Store        │  │ Factory      │              │
+│  └──────────────┘  └──────────────┘  └──────────────┘              │
+│  ┌──────────────┐  ┌──────────────┐                                │
+│  │ Tools        │  │ Message      │                                │
+│  │ Builder      │  │ Serializer   │                                │
+│  └──────────────┘  └──────────────┘                                │
+├─────────────────────────────────────────────────────────────────────┤
+│                     LANGCHAIN LAYER                                  │
+│  LangChain Core | LangGraph | Provider SDKs                        │
+├─────────────────────────────────────────────────────────────────────┤
+│                     PERSISTENCE LAYER                                │
+│  PostgreSQL (langchain_sessions table with RLS)                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Agent Factory
+
+The `createAgent()` function is the entry point for creating AI agents:
+
+```typescript
+const agent = await createAgent({
+    sessionId: 'user-123-session-1',
+    systemPrompt: 'You are a helpful assistant...',
+    tools: myTools,
+    modelConfig: {
+        provider: 'openai',
+        model: 'gpt-4o',
+        temperature: 0.3
+    },
+    context: { userId, teamId }
+})
+```
+
+**Responsibilities:**
+- Creates the LLM instance from the provider factory
+- Converts tool definitions to LangChain tools
+- Sets up the ReAct agent graph with LangGraph
+- Manages conversation memory (if context provided)
+- Provides `chat()` and `getHistory()` methods
+
+**Agent Lifecycle:**
+
+```
+createAgent()
+    │
+    ├─→ getModel(config)           # Get LLM instance
+    ├─→ buildTools(toolDefs)       # Convert to LangChain tools
+    ├─→ loadHistory(context)       # Load existing messages
+    ├─→ createReactAgent(...)      # Build LangGraph agent
+    │
+    └─→ Returns { chat, getHistory }
+```
+
+### 2. Provider Factory
+
+The provider system abstracts LLM access:
+
+```typescript
+// Provider factory map
+const providers = {
+    openai: createOpenAIModel,
+    anthropic: createAnthropicModel,
+    ollama: createOllamaModel
+}
+
+// Get model instance
+const model = getModel({ provider: 'openai', model: 'gpt-4o' })
+```
+
+**Supported Providers:**
+
+| Provider | SDK | Use Case |
+|----------|-----|----------|
+| `openai` | `@langchain/openai` | Production, high quality |
+| `anthropic` | `@langchain/anthropic` | Production, alternative |
+| `ollama` | `@langchain/ollama` | Development, local, free |
+
+**OpenAI-Compatible Servers:**
+
+The `openai` provider supports custom base URLs for compatible servers:
+
+```env
+# Use LM Studio locally
+LANGCHAIN_OPENAI_BASE_URL=http://localhost:1234/v1
+```
+
+### 3. Memory Store
+
+Conversation persistence with multi-tenancy:
+
+```typescript
+interface DbMemoryStoreContext {
+    userId: string    // User identifier
+    teamId: string    // Team identifier
+}
+
+const context = { userId: 'user-123', teamId: 'team-456' }
+
+// Get messages for a session (returns LangChain BaseMessage[])
+const messages = await memoryStore.getMessages(sessionId, context)
+
+// Add messages to session
+await memoryStore.addMessages(sessionId, newMessages, context)
+
+// Session management
+// Note: createSession auto-generates sessionId
+const { sessionId, createdAt } = await memoryStore.createSession(context, 'My Chat')
+await memoryStore.listSessions(context)
+// Note: parameter order is (sessionId, value, context)
+await memoryStore.renameSession(sessionId, 'New Name', context)
+await memoryStore.togglePinSession(sessionId, true, context)
+await memoryStore.clearSession(sessionId, context)
+```
+
+**Conversation Limits:**
+
+```typescript
+const LIMITS = {
+    MAX_CONVERSATIONS: 50,           // Per user per team
+    MAX_MESSAGES_PER_CONVERSATION: 50  // Sliding window
+}
+```
+
+### 4. Tools Builder
+
+Converts simple tool definitions to LangChain-compatible tools:
+
+```typescript
+interface ToolDefinition<T> {
+    name: string
+    description: string
+    schema: z.ZodSchema<T>
+    func: (input: T) => Promise<string>
+}
+
+// Usage
+const tools = buildTools([
+    {
+        name: 'get_weather',
+        description: 'Get current weather for a city',
+        schema: z.object({
+            city: z.string().describe('City name')
+        }),
+        func: async ({ city }) => {
+            const weather = await WeatherService.get(city)
+            return JSON.stringify(weather)
+        }
+    }
+])
+```
+
+### 5. Message Serializer
+
+Handles LangChain message serialization for database storage:
+
+```typescript
+interface SerializedMessage {
+    type: 'human' | 'ai' | 'system' | 'tool'
+    content: string
+    name?: string
+    tool_call_id?: string
+    additional_kwargs?: Record<string, unknown>
+}
+
+// Serialize for storage
+const serialized = serializeMessages(langchainMessages)
+
+// Deserialize for agent
+const messages = deserializeMessages(serialized)
+```
+
+## Data Flow
+
+### Single Agent Flow
+
+```
+┌─────────┐     ┌─────────────┐     ┌─────────────┐
+│  User   │────→│  API Route  │────→│   Agent     │
+└─────────┘     └─────────────┘     └──────┬──────┘
+                                           │
+                    ┌──────────────────────┼──────────────────────┐
+                    │                      ▼                      │
+                    │              ┌─────────────┐                │
+                    │              │    LLM      │                │
+                    │              └──────┬──────┘                │
+                    │                     │                       │
+                    │         ┌───────────┴───────────┐           │
+                    │         ▼                       ▼           │
+                    │  ┌─────────────┐         ┌─────────────┐    │
+                    │  │  Tool Call  │         │   Response  │    │
+                    │  └──────┬──────┘         └─────────────┘    │
+                    │         │                                   │
+                    │         ▼                                   │
+                    │  ┌─────────────┐                            │
+                    │  │  Service    │                            │
+                    │  │  (RLS)      │                            │
+                    │  └──────┬──────┘                            │
+                    │         │                                   │
+                    │         ▼                                   │
+                    │  ┌─────────────┐                            │
+                    │  │  Database   │                            │
+                    │  └─────────────┘                            │
+                    │                                             │
+                    │              AGENT LOOP                     │
+                    └─────────────────────────────────────────────┘
+```
+
+### Graph-Based Orchestrator Flow (Recommended)
+
+The graph-based orchestrator uses a **state machine** approach instead of ReAct loops:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         GRAPH ORCHESTRATOR                                   │
+│                                                                              │
+│   ┌─────────┐                                                                │
+│   │  START  │                                                                │
+│   └────┬────┘                                                                │
+│        │                                                                     │
+│        ▼                                                                     │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                        ROUTER NODE                                   │   │
+│   │  • Structured output (Zod validation)                               │   │
+│   │  • Intent classification: task, customer, page, greeting, unclear   │   │
+│   │  • Multi-provider compatible (OpenAI, Anthropic, Ollama)            │   │
+│   │  • Single LLM call with retry logic                                 │   │
+│   └─────────────────────────────────────────┬───────────────────────────┘   │
+│                                             │                                │
+│           ┌─────────────┬──────────────────┼──────────────────┬─────────┐   │
+│           ▼             ▼                  ▼                  ▼         ▼   │
+│   ┌───────────┐  ┌───────────┐     ┌───────────┐     ┌───────────┐  ┌────┐ │
+│   │   Task    │  │ Customer  │     │   Page    │     │ Greeting  │  │END │ │
+│   │  Handler  │  │  Handler  │     │  Handler  │     │ Handler   │  │    │ │
+│   │ (0 LLM)   │  │  (0 LLM)  │     │  (0 LLM)  │     │ (0 LLM)   │  │    │ │
+│   └─────┬─────┘  └─────┬─────┘     └─────┬─────┘     └─────┬─────┘  └────┘ │
+│         │              │                 │                 │               │
+│         └──────────────┴────────┬────────┴─────────────────┘               │
+│                                 │                                           │
+│                                 ▼                                           │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                       COMBINER NODE                                  │   │
+│   │  • Aggregates handler results                                       │   │
+│   │  • Template-based for single intent (0 LLM calls)                   │   │
+│   │  • LLM synthesis for multi-intent (1 LLM call)                      │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                 │                                           │
+│                                 ▼                                           │
+│                           ┌─────────┐                                       │
+│                           │   END   │                                       │
+│                           └─────────┘                                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Key Advantages over ReAct:**
+
+| Aspect | Graph Orchestrator | ReAct Loop |
+|--------|-------------------|------------|
+| **LLM Calls** | 1-2 per request | 50+ possible |
+| **Latency** | 2-3 seconds | 10-15+ seconds |
+| **Predictability** | Deterministic flow | Non-deterministic |
+| **Recursion Limits** | Never hit | Frequent issue |
+| **Cost** | ~$0.001/request | ~$0.05/request |
+
+> **Full Documentation**: See [Graph Orchestrator](../03-orchestration/01-graph-orchestrator.md) for complete details.
+
+### Legacy Orchestrator Flow (Deprecated)
+
+> **Note**: This approach is deprecated. Use the graph-based orchestrator instead.
+
+```
+┌─────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  User   │────→│  Orchestrator   │────→│ Routing Tools   │
+└─────────┘     └────────┬────────┘     └────────┬────────┘
+                         │                       │
+                         │    ┌──────────────────┘
+                         │    │
+                         ▼    ▼
+                ┌────────────────────────┐
+                │   Routing Decision     │
+                │   { agent, message }   │
+                └───────────┬────────────┘
+                            │
+           ┌────────────────┼────────────────┐
+           ▼                ▼                ▼
+    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+    │ Task Agent  │  │ Customer    │  │ Page Agent  │
+    │             │  │ Agent       │  │             │
+    └─────────────┘  └─────────────┘  └─────────────┘
+```
+
+## Design Patterns
+
+### Factory Pattern
+
+Used for creating agents and LLM instances:
+
+```typescript
+// Agent Factory
+const agent = await createAgent(config)
+
+// Provider Factory
+const model = getModel(modelConfig)
+
+// Helper Factory
+const helpers = createAgentHelpers(agents, defaults)
+```
+
+### Facade Pattern
+
+The memory store provides a simplified interface:
+
+```typescript
+// External interface (memoryStore)
+memoryStore.getMessages(sessionId, context)
+
+// Internal implementation (dbMemoryStore)
+dbMemoryStore.getMessages(sessionId, context)
+```
+
+### Strategy Pattern
+
+Tool factories allow themes to define custom strategies:
+
+```typescript
+// Each agent has its own tool strategy
+createTools: (context) => [
+    // Theme-specific tools
+]
+```
+
+### Template Pattern
+
+Presets provide templates for common patterns:
+
+```
+presets/
+├── lib/langchain.config.ts.preset    # Configuration template
+├── api/chat/route.ts.preset          # API endpoint template
+├── lib/tools/entity-tools.ts.preset  # Tools template
+└── agents/entity-assistant.md.preset # Prompt template
+```
+
+## Security Architecture
+
+### Multi-Tenancy
+
+All data is isolated by `userId` + `teamId`:
+
+```sql
+-- Every query includes tenant context
+SELECT * FROM langchain_sessions
+WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3
+```
+
+### Row-Level Security
+
+The database table has RLS policies:
+
+```sql
+-- Only owner can access their sessions
+CREATE POLICY langchain_sessions_policy ON langchain_sessions
+    USING (
+        "userId" = current_setting('app.user_id')::text
+        AND "teamId" = current_setting('app.team_id')::text
+    );
+```
+
+### Tool-Level Authorization
+
+Tools receive context for authorization:
+
+```typescript
+createTools: (context: ToolContext) => [
+    {
+        func: async (input) => {
+            // context.userId and context.teamId available
+            // Service calls use these for RLS
+            return TasksService.list(context.userId, input)
+        }
+    }
+]
+```
+
+## Performance Considerations
+
+### Message Limits
+
+Conversations use a sliding window to control token usage:
+
+```typescript
+// Only last 50 messages are kept
+if (messages.length > MAX_MESSAGES) {
+    messages = messages.slice(-MAX_MESSAGES)
+}
+```
+
+### No Dynamic Imports
+
+All imports are static for optimal bundling:
+
+```typescript
+// Good - static import
+import { createAgent } from '@/contents/plugins/langchain/lib/agent-factory'
+
+// Bad - dynamic import (not used)
+const agent = await import('@/contents/plugins/langchain')
+```
+
+### Caching
+
+Session data is cached in memory during agent lifetime:
+
+```typescript
+const agent = await createAgent(config)
+// First call loads from DB
+await agent.chat('Hello')
+// Subsequent calls use cached history
+await agent.chat('How are you?')
+```
+
+## Database Schema
+
+```sql
+CREATE TABLE public."langchain_sessions" (
+    id              TEXT PRIMARY KEY,
+
+    -- Multi-tenancy keys
+    "userId"        TEXT NOT NULL REFERENCES users(id),
+    "teamId"        TEXT NOT NULL REFERENCES teams(id),
+    "sessionId"     TEXT NOT NULL,
+
+    -- Metadata
+    name            TEXT DEFAULT NULL,
+    "isPinned"      BOOLEAN DEFAULT false,
+
+    -- Message storage
+    messages        JSONB NOT NULL DEFAULT '[]',
+    metadata        JSONB DEFAULT '{}',
+    "maxMessages"   INTEGER DEFAULT 50,
+    "expiresAt"     TIMESTAMPTZ DEFAULT NULL,
+
+    -- Timestamps
+    "createdAt"     TIMESTAMPTZ DEFAULT now(),
+    "updatedAt"     TIMESTAMPTZ DEFAULT now(),
+
+    UNIQUE ("userId", "teamId", "sessionId")
+);
+
+-- Performance indexes
+CREATE INDEX idx_sessions_lookup
+    ON langchain_sessions("userId", "teamId", "sessionId");
+CREATE INDEX idx_sessions_pinned
+    ON langchain_sessions("userId", "teamId", "isPinned");
+CREATE INDEX idx_sessions_updated
+    ON langchain_sessions("userId", "teamId", "updatedAt" DESC);
+```
+
+## Supporting Systems
+
+### Observability Layer
+
+End-to-end tracing for debugging and monitoring:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TRACE RECORD                              │
+│  traceId: abc-123                                           │
+│  ├─ Span: router (llm)          1200ms                      │
+│  ├─ Span: task_handler (tool)    340ms                      │
+│  └─ Span: combiner (llm)         800ms                      │
+│                                                              │
+│  Total: 2340ms | Tokens: 230 | Cost: $0.002                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **Traces**: Complete agent invocations
+- **Spans**: Individual operations (LLM calls, tool calls)
+- **Metrics**: Aggregate performance data
+- **Dashboard**: Visual debugging at `/sector7/ai-observability`
+
+> **Documentation**: [Observability](../04-advanced/01-observability.md)
+
+### Token & Cost Tracking
+
+Per-request and aggregate usage tracking:
+
+```
+LLM Request → Token Usage → Cost Calculation → Database → Analytics
+                ↓               ↓
+          inputTokens      pricing table
+          outputTokens          ↓
+                          totalCost (USD)
+```
+
+- Track input/output tokens per request
+- Calculate costs based on model pricing
+- Dashboard at `/dashboard/settings/ai-usage`
+
+> **Documentation**: [Token Tracking](../04-advanced/02-token-tracking.md)
+
+### Streaming (SSE)
+
+Real-time token-by-token responses:
+
+```
+User Request → streamChat() → SSE Response
+                   │
+                   ├─→ { type: 'token', content: 'Hello' }
+                   ├─→ { type: 'tool_start', toolName: 'list_tasks' }
+                   ├─→ { type: 'tool_end', result: [...] }
+                   └─→ { type: 'done', fullContent: '...' }
+```
+
+> **Documentation**: [Streaming](../04-advanced/03-streaming.md)
+
+### Guardrails & Security
+
+Multi-layer protection for AI interactions:
+
+```
+User Input → [Injection Check] → [PII Mask] → Agent → [Content Filter] → Response
+```
+
+- **Prompt Injection Detection**: Block manipulation attempts
+- **PII Masking**: Redact sensitive data (emails, phones, etc.)
+- **Content Filtering**: Filter inappropriate outputs
+
+> **Documentation**: [Guardrails](../04-advanced/04-guardrails.md)
+
+---
+
+## Next Steps
+
+- [Installation](../01-getting-started/02-installation.md) - Set up the plugin
+- [Configuration](../01-getting-started/03-configuration.md) - Configure agents at the theme level
+- [Graph Orchestrator](../03-orchestration/01-graph-orchestrator.md) - Modern orchestration approach
+- [Observability](../04-advanced/01-observability.md) - Tracing and debugging
+- [Token Tracking](../04-advanced/02-token-tracking.md) - Usage and cost monitoring
+- [Streaming](../04-advanced/03-streaming.md) - Real-time responses
+- [Guardrails](../04-advanced/04-guardrails.md) - Security middleware