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

package/templates/contents/themes/default/docs/03-ai/01-overview.md

@@ -1,211 +0,0 @@
-# AI Assistant - Overview
-
-This theme includes an AI-powered assistant that helps users manage tasks, customers, and pages through natural language.
-
-## Features
-
-### Multi-Agent Architecture
-
-The assistant uses a graph-based orchestrator that routes requests to specialized handlers:
-
-| Intent | Handler | Description |
-|--------|---------|-------------|
-| `task` | Task Handler | Manage tasks (create, update, list, delete) |
-| `customer` | Customer Handler | Manage customers (CRUD, search) |
-| `page` | Page Handler | Manage pages and blocks |
-| `greeting` | Greeting Handler | Respond to casual greetings |
-| `unclear` | Clarification | Ask for more details |
-
-### Key Capabilities
-
-- **Natural Language**: Talk to the assistant in plain English
-- **Multi-Intent**: Handle multiple requests in one message
-- **Context-Aware**: Remembers conversation history
-- **Real-Time Streaming**: See responses as they're generated
-- **Tool Execution**: Automatically executes CRUD operations
-
----
-
-## Quick Start
-
-### Accessing the Assistant
-
-The AI assistant is available at:
-
-```
-/dashboard/ai-assistant
-```
-
-### Example Interactions
-
-**Task Management:**
-```
-User: Show my tasks for this week
-Assistant: I found 5 tasks due this week...
-
-User: Create a new task to review the quarterly report
-Assistant: Done! Created task "Review quarterly report" with default settings.
-```
-
-**Customer Management:**
-```
-User: Find customers from California
-Assistant: Found 3 customers in California...
-
-User: Show me John Smith's details
-Assistant: Here are the details for John Smith...
-```
-
-**Page Management:**
-```
-User: List all published pages
-Assistant: You have 12 published pages...
-```
-
----
-
-## Configuration
-
-### Theme Configuration
-
-The AI assistant is configured in `langchain.config.ts`:
-
-```typescript
-// contents/themes/default/langchain.config.ts
-export const langchainConfig: LangChainConfig = {
-    observability: {
-        enabled: true,
-        retention: { traces: 30 },
-        sampling: { rate: 1.0, alwaysTraceErrors: true },
-        pii: { maskInputs: false, maskOutputs: false, truncateAt: 10000 },
-    },
-}
-```
-
-### Environment Variables
-
-Required environment variables:
-
-```env
-# Enable the LangChain plugin
-LANGCHAIN_PLUGIN_ENABLED=true
-
-# Choose your LLM provider
-LANGCHAIN_OLLAMA_MODEL=qwen2.5:7b        # For local development
-# OR
-OPENAI_API_KEY=sk-...                     # For production
-LANGCHAIN_OPENAI_MODEL=gpt-4o-mini
-
-# Enable graph orchestrator (recommended)
-LANGCHAIN_USE_GRAPH_ORCHESTRATOR=true
-```
-
----
-
-## Architecture
-
-### Graph Orchestrator
-
-The theme uses the graph-based orchestrator for efficient multi-intent handling:
-
-```
-User Message → Router → Handlers → Combiner → Response
-                 │
-                 ├─→ Task Handler (0 LLM calls)
-                 ├─→ Customer Handler (0 LLM calls)
-                 ├─→ Page Handler (0 LLM calls)
-                 └─→ Greeting Handler (0 LLM calls)
-```
-
-**Benefits:**
-- 1-2 LLM calls per request (vs 50+ with ReAct)
-- 2-3 second response time
-- No recursion limit issues
-- ~$0.001 per request
-
-### Available Agents
-
-| Agent | Purpose | Tools |
-|-------|---------|-------|
-| `orchestrator` | Main entry point | Intent routing |
-| `task-assistant` | Task management | Task CRUD |
-| `customer-assistant` | Customer management | Customer CRUD |
-| `page-assistant` | Page/block management | Page CRUD |
-| `single-agent` | Unified agent | All tools |
-
----
-
-## Monitoring
-
-### Token Usage Dashboard
-
-Track AI usage at:
-
-```
-/dashboard/settings/ai-usage
-```
-
-Shows:
-- Total tokens used
-- Cost breakdown by model
-- Daily usage charts
-- Request counts
-
-### Observability Dashboard (Admin)
-
-For superadmins, detailed traces at:
-
-```
-/sector7/ai-observability
-```
-
-Shows:
-- Request traces with timing
-- Individual LLM/tool spans
-- Error debugging
-- Performance metrics
-
----
-
-## Security
-
-### Built-in Protections
-
-The assistant includes guardrails for:
-
-- **Prompt Injection Detection**: Blocks manipulation attempts
-- **PII Masking**: Redacts sensitive data in traces
-- **Content Filtering**: Filters inappropriate outputs
-
-### Data Isolation
-
-All data is isolated by user and team through Row-Level Security (RLS).
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-**Assistant not responding:**
-1. Check `LANGCHAIN_PLUGIN_ENABLED=true`
-2. Verify LLM provider is configured
-3. Check browser console for errors
-
-**Slow responses:**
-1. Enable graph orchestrator: `LANGCHAIN_USE_GRAPH_ORCHESTRATOR=true`
-2. Use faster model (gpt-4o-mini, claude-3-haiku)
-3. Check network latency to LLM provider
-
-**Wrong tool called:**
-1. Be more specific in your request
-2. Try rephrasing the question
-3. Check agent prompts for clarity
-
----
-
-## Related Documentation
-
-- [Plugin Overview](../../../plugins/langchain/docs/01-overview.md)
-- [Graph Orchestrator](../../../plugins/langchain/docs/11-graph-orchestrator.md)
-- [Configuration](../../../plugins/langchain/docs/04-configuration.md)

package/templates/contents/themes/default/docs/03-ai/02-customization.md

@@ -1,436 +0,0 @@
-# AI Assistant - Customization
-
-This guide covers how to customize and extend the AI assistant for your specific needs.
-
-## Creating Custom Tools
-
-### Tool Structure
-
-Tools are defined with a name, description, schema, and function:
-
-```typescript
-// contents/themes/default/lib/langchain/tools/my-entity.ts
-
-import { z } from 'zod'
-import type { ToolDefinition } from '@/contents/plugins/langchain/types/langchain.types'
-import type { ToolContext } from '@/contents/plugins/langchain/types/langchain.types'
-import { MyEntityService } from '@/contents/themes/default/entities/my-entity/my-entity.service'
-
-export function createMyEntityTools(context: ToolContext): ToolDefinition<any>[] {
-    return [
-        {
-            name: 'list_my_entities',
-            description: 'List all my entities for the current user',
-            schema: z.object({
-                limit: z.number().optional().describe('Maximum number of results'),
-                status: z.string().optional().describe('Filter by status'),
-            }),
-            func: async ({ limit, status }) => {
-                const entities = await MyEntityService.list(context.userId, {
-                    limit: limit || 10,
-                    status,
-                })
-                return JSON.stringify(entities)
-            },
-        },
-        {
-            name: 'create_my_entity',
-            description: 'Create a new entity',
-            schema: z.object({
-                name: z.string().describe('Entity name'),
-                description: z.string().optional().describe('Entity description'),
-            }),
-            func: async ({ name, description }) => {
-                const entity = await MyEntityService.create(context.userId, {
-                    name,
-                    description,
-                })
-                return JSON.stringify(entity)
-            },
-        },
-    ]
-}
-```
-
-### Tool Best Practices
-
-1. **Clear Descriptions**: The LLM reads descriptions to decide which tool to use
-2. **Zod Schemas**: Use `.describe()` for parameter documentation
-3. **JSON Output**: Always return `JSON.stringify()` results
-4. **Context Usage**: Use `context.userId` and `context.teamId` for data isolation
-
----
-
-## Creating Custom Agents
-
-### Agent Definition
-
-Define agents in the theme's langchain configuration:
-
-```typescript
-// contents/themes/default/lib/langchain/agents.config.ts
-
-import type { AgentDefinition, AgentContext } from '@/contents/plugins/langchain/types/langchain.types'
-import { createMyEntityTools } from './tools/my-entity'
-
-export const CUSTOM_AGENTS: Record<string, AgentDefinition> = {
-    'my-entity-assistant': {
-        provider: 'ollama',        // or 'openai', 'anthropic'
-        temperature: 0.3,
-        description: 'Specialized agent for my entity management',
-        systemPrompt: 'my-entity-assistant',  // loads agents/my-entity-assistant.md
-        createTools: (context: AgentContext) => createMyEntityTools(context),
-    },
-}
-```
-
-### System Prompt
-
-Create the agent's system prompt:
-
-```markdown
-<!-- contents/themes/default/lib/langchain/agents/my-entity-assistant.md -->
-
-You are a helpful assistant specialized in managing entities.
-
-## Your Capabilities
-- List entities with filters
-- Create new entities
-- Update existing entities
-- Delete entities
-
-## Guidelines
-1. Always confirm destructive actions before proceeding
-2. Format lists in a readable way
-3. Ask clarifying questions when the request is ambiguous
-4. Be concise but helpful
-
-## Available Tools
-- `list_my_entities`: Get entities with optional filters
-- `create_my_entity`: Create a new entity
-```
-
----
-
-## Adding Graph Handlers
-
-### Handler Structure
-
-For the graph orchestrator, add custom handlers:
-
-```typescript
-// contents/themes/default/lib/langchain/handlers/my-entity-handler.ts
-
-import type { OrchestratorState, HandlerResult } from '@/contents/plugins/langchain/lib/graph/types'
-import { MyEntityService } from '@/contents/themes/default/entities/my-entity/my-entity.service'
-
-export async function myEntityHandler(
-    state: OrchestratorState
-): Promise<Partial<OrchestratorState>> {
-    const context = state.context
-    const intent = state.intents.find(i => i.type === 'my_entity')
-
-    if (!intent) {
-        return {}
-    }
-
-    try {
-        // Determine action from intent parameters
-        const action = intent.parameters?.action || 'list'
-
-        let result: HandlerResult
-
-        switch (action) {
-            case 'list':
-                const entities = await MyEntityService.list(context.userId, {})
-                result = {
-                    handler: 'my_entity',
-                    success: true,
-                    data: entities,
-                    message: `Found ${entities.length} entities`,
-                }
-                break
-
-            case 'create':
-                const newEntity = await MyEntityService.create(context.userId, {
-                    name: intent.parameters?.name,
-                })
-                result = {
-                    handler: 'my_entity',
-                    success: true,
-                    data: newEntity,
-                    message: `Created entity "${newEntity.name}"`,
-                }
-                break
-
-            default:
-                result = {
-                    handler: 'my_entity',
-                    success: false,
-                    error: `Unknown action: ${action}`,
-                }
-        }
-
-        return {
-            handlerResults: [...state.handlerResults, result],
-            completedHandlers: [...state.completedHandlers, 'my_entity'],
-        }
-    } catch (error) {
-        return {
-            handlerResults: [
-                ...state.handlerResults,
-                {
-                    handler: 'my_entity',
-                    success: false,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                },
-            ],
-            completedHandlers: [...state.completedHandlers, 'my_entity'],
-        }
-    }
-}
-```
-
-### Router Integration
-
-Update the router to recognize your new intent:
-
-```typescript
-// The router uses structured output to classify intents
-// Add your intent type to the schema:
-
-const intentSchema = z.object({
-    type: z.enum([
-        'task',
-        'customer',
-        'page',
-        'my_entity',  // Add your intent
-        'greeting',
-        'unclear',
-    ]),
-    confidence: z.number(),
-    parameters: z.object({
-        action: z.string().optional(),
-        // Add entity-specific parameters
-    }).optional(),
-})
-```
-
----
-
-## Customizing Prompts
-
-### Template Variables
-
-System prompts support Handlebars templates:
-
-```markdown
-<!-- agents/my-assistant.md -->
-
-You are assisting {{user.name}} with their {{team.name}} account.
-
-{{#if user.isAdmin}}
-As an admin, you can also manage team settings.
-{{/if}}
-
-Today's date is {{today}}.
-```
-
-### Context Enrichment
-
-Provide data for templates:
-
-```typescript
-'my-assistant': {
-    provider: 'openai',
-    systemPrompt: 'my-assistant',
-    enrichContext: async ({ userId, teamId }) => {
-        const user = await UsersService.getById(userId)
-        const team = await TeamsService.getById(teamId)
-        return {
-            userId,
-            teamId,
-            user: { name: user.name, isAdmin: user.role === 'admin' },
-            team: { name: team.name },
-            today: new Date().toLocaleDateString(),
-        }
-    },
-}
-```
-
----
-
-## UI Integration
-
-### Using the Chat Hook
-
-```typescript
-import { useStreamingChat } from '@/contents/plugins/langchain/hooks/useStreamingChat'
-
-function MyAIChat() {
-    const {
-        isStreaming,
-        streamContent,
-        error,
-        sendMessage,
-        cancelStream,
-    } = useStreamingChat({
-        sessionId: 'my-session-id',
-        agentName: 'my-entity-assistant',
-        onComplete: (fullContent, tokenUsage) => {
-            console.log('Response complete:', fullContent)
-            console.log('Tokens used:', tokenUsage)
-        },
-        onError: (error) => {
-            console.error('Chat error:', error)
-        },
-    })
-
-    return (
-        <div>
-            {isStreaming && <TypingIndicator content={streamContent} />}
-            <button onClick={() => sendMessage('Show my entities')}>
-                Send
-            </button>
-            {isStreaming && (
-                <button onClick={cancelStream}>Cancel</button>
-            )}
-        </div>
-    )
-}
-```
-
-### Token Usage Hook
-
-```typescript
-import { useTokenUsage } from '@/contents/plugins/langchain/hooks/useTokenUsage'
-
-function UsageDisplay() {
-    const { data, isLoading } = useTokenUsage({ period: '30d' })
-
-    if (isLoading) return <Loading />
-
-    return (
-        <div>
-            <p>Tokens: {data.totalTokens.toLocaleString()}</p>
-            <p>Cost: ${data.totalCost.toFixed(2)}</p>
-        </div>
-    )
-}
-```
-
----
-
-## Testing
-
-### Testing Tools
-
-```typescript
-// tests/langchain/my-entity-tools.test.ts
-
-import { createMyEntityTools } from '../lib/langchain/tools/my-entity'
-
-describe('My Entity Tools', () => {
-    const context = { userId: 'test-user', teamId: 'test-team' }
-
-    it('should list entities', async () => {
-        const tools = createMyEntityTools(context)
-        const listTool = tools.find(t => t.name === 'list_my_entities')
-
-        const result = await listTool.func({ limit: 5 })
-        const parsed = JSON.parse(result)
-
-        expect(Array.isArray(parsed)).toBe(true)
-    })
-})
-```
-
-### Testing Handlers
-
-```typescript
-// tests/langchain/my-entity-handler.test.ts
-
-import { myEntityHandler } from '../lib/langchain/handlers/my-entity-handler'
-
-describe('My Entity Handler', () => {
-    it('should handle list intent', async () => {
-        const state = {
-            context: { userId: 'test-user', teamId: 'test-team' },
-            intents: [{ type: 'my_entity', parameters: { action: 'list' } }],
-            handlerResults: [],
-            completedHandlers: [],
-        }
-
-        const result = await myEntityHandler(state)
-
-        expect(result.completedHandlers).toContain('my_entity')
-        expect(result.handlerResults[0].success).toBe(true)
-    })
-})
-```
-
----
-
-## Best Practices
-
-### 1. Keep Handlers Simple
-
-Handlers should do minimal work (0 LLM calls):
-
-```typescript
-// Good: Direct service call
-const data = await Service.list(userId)
-
-// Bad: Additional LLM call in handler
-const agent = await createAgent(...)
-const result = await agent.chat(...)
-```
-
-### 2. Use Structured Output
-
-For router customization, use Zod schemas for type-safe output:
-
-```typescript
-const schema = z.object({
-    intent: z.enum(['task', 'customer', 'my_entity']),
-    confidence: z.number().min(0).max(1),
-})
-```
-
-### 3. Handle Errors Gracefully
-
-Always return meaningful error messages:
-
-```typescript
-try {
-    const result = await riskyOperation()
-    return { success: true, data: result }
-} catch (error) {
-    return {
-        success: false,
-        error: `Failed to process: ${error.message}`,
-    }
-}
-```
-
-### 4. Document Your Tools
-
-Clear descriptions help the LLM choose correctly:
-
-```typescript
-{
-    name: 'search_products',
-    description: 'Search products by name, category, or price range. ' +
-                 'Use this when the user wants to find specific products. ' +
-                 'Returns up to 20 matching products.',
-    // ...
-}
-```
-
----
-
-## Related Documentation
-
-- [Plugin Tools Guide](../../../plugins/langchain/docs/06-tools.md)
-- [Graph Orchestrator](../../../plugins/langchain/docs/11-graph-orchestrator.md)
-- [Agent Configuration](../../../plugins/langchain/docs/04-configuration.md)