@nextsparkjs/core 0.1.0-beta.2 → 0.1.0-beta.4

package/templates/contents/plugins/langchain/docs/02-core-concepts/01-architecture.md

@@ -1,566 +0,0 @@
-# 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