@nextsparkjs/plugin-ai 0.1.0-beta.1

package/api/ai-history/[id]/route.ts

@@ -0,0 +1,112 @@
+/**
+ * AI History Entity Linking Endpoint
+ *
+ * PATCH /api/v1/plugin/ai/ai-history/:id
+ *
+ * Updates the relatedEntityType and relatedEntityId for an AI history record.
+ * Used to link AI operations (e.g., analyze-brief) to entities created afterward (e.g., clients).
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { auth } from '@nextsparkjs/core/lib/auth'
+import { AIHistoryService } from '@/plugins/ai/lib/ai-history-service'
+
+interface RouteParams {
+  params: Promise<{
+    id: string
+  }>
+}
+
+/**
+ * PATCH /api/v1/plugin/ai/ai-history/:id
+ * Update related entity information for an AI history record
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: RouteParams
+): Promise<NextResponse> {
+  try {
+    // Authenticate user
+    const session = await auth.api.getSession({
+      headers: request.headers
+    })
+
+    if (!session?.user) {
+      return NextResponse.json(
+        { error: 'Unauthorized' },
+        { status: 401 }
+      )
+    }
+
+    // Await params (Next.js 15 pattern for dynamic routes)
+    const { id: historyId } = await params
+
+    if (!historyId) {
+      return NextResponse.json(
+        { error: 'Missing history ID' },
+        { status: 400 }
+      )
+    }
+
+    // Parse request body
+    const body = await request.json()
+    const { relatedEntityType, relatedEntityId } = body
+
+    if (!relatedEntityType || !relatedEntityId) {
+      return NextResponse.json(
+        {
+          error: 'Missing required fields',
+          details: 'Both relatedEntityType and relatedEntityId are required'
+        },
+        { status: 400 }
+      )
+    }
+
+    // Verify the AI history record exists and belongs to this user
+    const existingRecord = await AIHistoryService.getOperation(historyId)
+
+    if (!existingRecord) {
+      return NextResponse.json(
+        { error: 'AI history record not found' },
+        { status: 404 }
+      )
+    }
+
+    if (existingRecord.userId !== session.user.id) {
+      return NextResponse.json(
+        { error: 'Forbidden - this record belongs to another user' },
+        { status: 403 }
+      )
+    }
+
+    // Update the related entity information
+    await AIHistoryService.updateRelatedEntity(
+      historyId,
+      relatedEntityType,
+      relatedEntityId
+    )
+
+    return NextResponse.json({
+      success: true,
+      message: 'AI history record linked to entity successfully',
+      data: {
+        historyId,
+        relatedEntityType,
+        relatedEntityId
+      }
+    })
+
+  } catch (error) {
+    console.error('Error updating AI history related entity:', error)
+
+    const errorMessage = error instanceof Error ? error.message : 'Failed to update AI history record'
+
+    return NextResponse.json(
+      {
+        error: 'Internal server error',
+        details: errorMessage
+      },
+      { status: 500 }
+    )
+  }
+}

package/api/embeddings/route.ts

@@ -0,0 +1,129 @@
+/**
+ * AI Embeddings Endpoint
+ *
+ * Generate text embeddings using OpenAI's text-embedding-3-small model
+ * Accessible via: /api/v1/plugin/ai/embeddings
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { validatePlugin, handleAIError } from '../../lib/core-utils'
+import { getServerPluginConfig } from '../../lib/server-env'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { embed } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+
+// Request validation schema
+const EmbeddingRequestSchema = z.object({
+  text: z.string().min(1, 'Text cannot be empty').max(50000, 'Text too long')
+})
+
+export async function POST(request: NextRequest) {
+  try {
+    // 1. Authentication
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return NextResponse.json({ error: 'Authentication required' }, { status: 401 })
+    }
+
+    // 2. Validate plugin
+    const validation = await validatePlugin()
+    if (!validation.valid) {
+      return NextResponse.json({ error: validation.error }, { status: 503 })
+    }
+
+    // 3. Parse and validate request body
+    const rawBody = await request.json()
+    const validationResult = EmbeddingRequestSchema.safeParse(rawBody)
+
+    if (!validationResult.success) {
+      return NextResponse.json({
+        error: 'Validation failed',
+        details: validationResult.error.issues
+      }, { status: 400 })
+    }
+
+    const { text } = validationResult.data
+
+    // 4. Check OpenAI API key
+    const config = await getServerPluginConfig()
+    if (!process.env.OPENAI_API_KEY) {
+      return NextResponse.json({
+        error: 'OpenAI API key not configured',
+        message: 'Add OPENAI_API_KEY to contents/plugins/ai/.env'
+      }, { status: 503 })
+    }
+
+    // 5. Generate embedding using OpenAI text-embedding-3-small (same as n8n)
+    const { embedding, usage } = await embed({
+      model: openai.embedding('text-embedding-3-small'),
+      value: text
+    })
+
+    // 6. Return response
+    return NextResponse.json({
+      success: true,
+      embedding,
+      model: 'text-embedding-3-small',
+      dimensions: embedding.length,
+      tokens: usage?.tokens || 0,
+      userId: authResult.user!.id
+    })
+
+  } catch (error) {
+    console.error('AI Embeddings error:', error)
+    const errorInfo = handleAIError(error as Error)
+    return NextResponse.json(
+      { error: errorInfo.error, message: errorInfo.message },
+      { status: errorInfo.status }
+    )
+  }
+}
+
+/**
+ * Get endpoint info
+ */
+export async function GET(): Promise<NextResponse> {
+  return NextResponse.json({
+    endpoint: '/api/v1/plugin/ai/embeddings',
+    description: 'Generate text embeddings using OpenAI',
+
+    usage: {
+      method: 'POST',
+      body: {
+        text: 'string (required) - Text to convert to embedding vector'
+      }
+    },
+
+    response: {
+      embedding: 'number[] - Vector representation (1536 dimensions)',
+      model: 'string - Model used (text-embedding-3-small)',
+      dimensions: 'number - Embedding dimensions (1536)',
+      tokens: 'number - Tokens used'
+    },
+
+    example: {
+      request: {
+        text: 'Premium wireless headphones with noise cancellation'
+      },
+      response: {
+        success: true,
+        embedding: '[1536 numbers...]',
+        model: 'text-embedding-3-small',
+        dimensions: 1536,
+        tokens: 8
+      }
+    },
+
+    model: {
+      name: 'text-embedding-3-small',
+      dimensions: 1536,
+      maxTokens: 8191,
+      cost: '$0.00002 per 1K tokens (5x cheaper than ada-002)'
+    },
+
+    setup: {
+      required: 'Add OPENAI_API_KEY to contents/plugins/ai/.env'
+    }
+  })
+}

package/api/generate/route.ts

@@ -0,0 +1,160 @@
+/**
+ * AI Generate Endpoint
+ *
+ * Simple AI assistant endpoint - generic and helpful
+ * Accessible via: /api/plugin/ai/generate
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { selectModel, calculateCost, validatePlugin, extractTokens, handleAIError } from '../../lib/core-utils'
+import { getServerPluginConfig } from '../../lib/server-env'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { generateText } from 'ai'
+import { saveExampleSafely } from '../../lib/save-example'
+import { z } from 'zod'
+
+// Simple, generic system prompt
+const SYSTEM_PROMPT = `You are a helpful AI assistant. Provide accurate, helpful, and well-structured responses. Be concise but thorough, and always aim to be useful to the person asking.`
+
+// Request validation schema
+const GenerateRequestSchema = z.object({
+  prompt: z.string().min(1, 'Prompt cannot be empty').max(10000, 'Prompt too long'),
+  model: z.string().optional(),
+  maxTokens: z.number().min(1).max(10000).optional(),
+  temperature: z.number().min(0).max(1).optional(),
+  saveExample: z.boolean().optional().default(false)
+})
+
+export async function POST(request: NextRequest) {
+  try {
+    // 1. Authentication
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return NextResponse.json({ error: 'Authentication required' }, { status: 401 })
+    }
+
+    // 2. Validate plugin
+    const validation = await validatePlugin()
+    if (!validation.valid) {
+      return NextResponse.json({ error: validation.error }, { status: 503 })
+    }
+
+    // 3. Get default configuration from environment
+    const config = await getServerPluginConfig()
+
+    // 4. Parse and validate request body
+    const rawBody = await request.json()
+    const validationResult = GenerateRequestSchema.safeParse(rawBody)
+
+    if (!validationResult.success) {
+      return NextResponse.json({
+        error: 'Validation failed',
+        details: validationResult.error.issues
+      }, { status: 400 })
+    }
+
+    const {
+      prompt,
+      model = config.defaultModel,
+      maxTokens = config.maxTokens,
+      temperature = config.defaultTemperature,
+      saveExample = false
+    } = validationResult.data
+
+    // 5. Select model
+    const selectedModel = await selectModel(model)
+
+    // 6. Generate AI response
+    const result = await generateText({
+      model: selectedModel.model,
+      system: SYSTEM_PROMPT,
+      prompt,
+      maxOutputTokens: maxTokens,
+      temperature
+    })
+
+    // 7. Calculate metrics
+    const tokens = extractTokens(result)
+    const cost = calculateCost(tokens, selectedModel.costConfig)
+
+    // 8. Save example if requested (opt-in)
+    if (saveExample) {
+      await saveExampleSafely(
+        {
+          prompt,
+          response: result.text,
+          model: selectedModel.modelName,
+          status: 'completed',
+          metadata: {
+            tokens: tokens.total,
+            cost,
+            provider: selectedModel.provider,
+            isLocal: selectedModel.isLocal
+          }
+        },
+        authResult.user!.id
+      )
+    }
+
+    // 9. Return response
+    return NextResponse.json({
+      success: true,
+      response: result.text,
+      model: selectedModel.modelName,
+      provider: selectedModel.provider,
+      isLocal: selectedModel.isLocal,
+      cost,
+      tokens,
+      userId: authResult.user!.id,
+      exampleSaved: saveExample
+    })
+
+  } catch (error) {
+    console.error('AI Generate error:', error)
+    const errorInfo = handleAIError(error as Error)
+    return NextResponse.json(
+      { error: errorInfo.error, message: errorInfo.message },
+      { status: errorInfo.status }
+    )
+  }
+}
+
+/**
+ * Get endpoint info
+ */
+export async function GET(): Promise<NextResponse> {
+  const config = await getServerPluginConfig()
+
+  return NextResponse.json({
+    endpoint: '/api/plugin/ai/generate',
+    description: 'Simple AI assistant endpoint',
+
+    usage: {
+      method: 'POST',
+      body: {
+        prompt: 'string (required) - Your question or request',
+        model: `string (optional, default: ${config.defaultModel}) - AI model to use`,
+        maxTokens: `number (optional, default: ${config.maxTokens}) - Max response length`,
+        temperature: `number (optional, default: ${config.defaultTemperature}) - Response creativity (0-1)`,
+        saveExample: 'boolean (optional, default: false) - Save interaction as example (opt-in, data will be sanitized)'
+      }
+    },
+
+    example: {
+      prompt: 'Explain quantum computing in simple terms',
+      model: config.defaultModel
+    },
+
+    models: {
+      local: ['llama3.2:3b', 'llama3.2', 'llama3.1', 'qwen2.5', 'mistral'],
+      openai: ['gpt-4o', 'gpt-4o-mini', 'gpt-3.5-turbo'],
+      anthropic: ['claude-3-5-sonnet-20241022', 'claude-3-5-haiku-20241022']
+    },
+
+    setup: {
+      local: `ollama serve && ollama pull ${config.ollamaDefaultModel}`,
+      openai: 'Add OPENAI_API_KEY to contents/plugins/ai/.env',
+      anthropic: 'Add ANTHROPIC_API_KEY to contents/plugins/ai/.env'
+    }
+  })
+}

package/docs/01-getting-started/01-introduction.md

@@ -0,0 +1,237 @@
+# AI Plugin Introduction
+
+## Overview
+
+The **AI Plugin** is a versatile, multi-provider AI utility system that brings powerful artificial intelligence capabilities to your SaaS application. Unlike monolithic AI solutions, this plugin provides **core utilities and example implementations** that you can extend and customize for your specific needs.
+
+**Philosophy:**
+- **Utility-First** - Provides reusable functions, not rigid solutions
+- **Provider-Agnostic** - Supports OpenAI, Anthropic, and Ollama (local)
+- **Extensible** - Build custom endpoints using provided utilities
+- **Production-Ready** - Includes history tracking, cost calculation, and error handling
+
+## Multi-Provider Support
+
+### Supported Providers
+
+**OpenAI**
+- Models: GPT-4o, GPT-4o Mini, GPT-3.5 Turbo
+- Best for: Production deployments, highest quality responses
+- Cost: Pay per token (~$0.00015-0.0025 per 1K input tokens)
+
+**Anthropic**
+- Models: Claude 3.5 Sonnet, Claude 3.5 Haiku
+- Best for: Complex reasoning, long context windows
+- Cost: Pay per token (~$0.00025-0.003 per 1K input tokens)
+
+**Ollama (Local)**
+- Models: Llama 3.2, Llama 3.1, Qwen 2.5, Mistral, Gemma 2
+- Best for: Development, privacy-sensitive applications, cost-free inference
+- Cost: Free (runs on your hardware)
+
+## Key Use Cases
+
+### 1. Content Generation
+
+Generate high-quality content for various purposes:
+- **Marketing Copy** - Product descriptions, ad copy, landing pages
+- **Blog Posts** - Articles, tutorials, documentation
+- **Email Campaigns** - Personalized emails, newsletters
+- **Social Media** - Posts, captions, engagement content
+
+**Already in use for:** Content creation workflows, automated copywriting
+
+### 2. AI-Powered Auditing
+
+Analyze and audit content using AI:
+- **Content Analysis** - Quality checks, tone analysis, compliance
+- **Data Validation** - Structured data extraction and verification
+- **Report Generation** - Automated insights and summaries
+- **Quality Assurance** - Consistency checks across content
+
+**Already in use for:** Content auditing workflows, quality control
+
+### 3. Semantic Search with Embeddings
+
+Enable meaning-based search and recommendations:
+- **Semantic Search** - Find content by meaning, not just keywords
+- **Content Recommendations** - Similar content suggestions
+- **Similarity Matching** - Duplicate detection, content clustering
+- **RAG (Retrieval Augmented Generation)** - Context-aware AI responses
+
+**Already in use for:** Embedding generation for search systems
+
+### 4. Custom AI Workflows
+
+Build specialized AI features:
+- **Classification** - Categorize content, sentiment analysis
+- **Summarization** - Extract key points from long text
+- **Translation** - Multi-language support
+- **Custom Analysis** - Domain-specific AI operations
+
+## Architecture
+
+### Core Components
+
+```
+contents/plugins/ai/
+├── lib/
+│   ├── core-utils.ts           # Core utility functions
+│   ├── ai-history-service.ts   # History tracking
+│   └── server-env.ts            # Configuration
+│
+├── api/
+│   ├── generate/               # Text generation endpoint
+│   ├── embeddings/             # Embeddings endpoint
+│   └── ai-history/             # History management
+│
+├── entities/
+│   └── ai-history/             # AI History entity
+│
+├── types/
+│   └── ai.types.ts             # TypeScript types
+│
+└── plugin.config.ts            # Plugin configuration
+```
+
+### Core Utilities (`core-utils.ts`)
+
+**Primary Functions:**
+- `selectModel()` - Automatically select and configure AI models
+- `calculateCost()` - Track token usage and costs
+- `validatePlugin()` - Ensure plugin is properly configured
+- `extractTokens()` - Extract token usage from AI responses
+- `handleAIError()` - Consistent error handling across providers
+- `COST_CONFIG` - Up-to-date pricing for all models
+
+### Example Endpoints
+
+**`/api/plugin/ai/generate`**
+- General-purpose text generation
+- Supports all providers and models
+- Includes cost tracking and history
+- Flexible system prompts and parameters
+
+**`/api/plugin/ai/embeddings`**
+- Generate semantic embeddings
+- Uses OpenAI text-embedding-3-small (1536 dimensions)
+- Optimized for search and recommendations
+
+### History Tracking System
+
+**AI History Entity** tracks every AI operation:
+- **Audit Trail** - Complete record of all AI interactions
+- **Cost Tracking** - Token usage and estimated costs
+- **Performance Monitoring** - Response times and success rates
+- **Entity Linking** - Connect AI operations to application entities
+- **Metadata Support** - Store custom operation data
+
+### Vercel AI SDK Integration
+
+Built on the [Vercel AI SDK](https://sdk.vercel.ai/):
+- **Unified API** - Consistent interface across providers
+- **Streaming Support** - Real-time response streaming
+- **Type Safety** - Full TypeScript support
+- **Error Handling** - Robust error management
+
+## Versatility and Extensibility
+
+### Why This Plugin is Different
+
+**Not a Chatbot Plugin:**
+- Doesn't force you into a specific UI or chat interface
+- Provides building blocks, not finished products
+- You decide how to use AI in your application
+
+**Utility-Based Design:**
+- Import core functions into your own endpoints
+- Build custom workflows using provided utilities
+- Extend with your own logic and business rules
+
+### Building Custom Endpoints
+
+```typescript
+// Your custom endpoint using plugin utilities
+import { selectModel, calculateCost, extractTokens } from '@/contents/plugins/ai/lib/core-utils'
+import { generateText } from 'ai'
+
+export async function POST(request: Request) {
+  // Your custom logic here
+  const { prompt, model } = await request.json()
+  
+  // Use plugin utilities
+  const selectedModel = await selectModel(model)
+  const result = await generateText({
+    model: selectedModel.model,
+    prompt: `Custom system prompt\n\n${prompt}`
+  })
+  
+  const tokens = extractTokens(result)
+  const cost = calculateCost(tokens, selectedModel.costConfig)
+  
+  return Response.json({
+    response: result.text,
+    cost,
+    tokens
+  })
+}
+```
+
+## Real-World Applications
+
+### Content Generation Platform
+
+**Use Case:** Automated marketing content creation
+**Implementation:** Custom endpoint using `generate` with specialized prompts
+**Result:** 10x faster content production with consistent quality
+
+### AI-Powered CMS
+
+**Use Case:** Content auditing and quality control
+**Implementation:** Analysis workflows using custom prompts and history tracking
+**Result:** Automated quality checks across thousands of content pieces
+
+### Semantic Product Search
+
+**Use Case:** E-commerce search by description
+**Implementation:** Embeddings generation + vector database integration
+**Result:** Customers find products by describing what they want
+
+## Getting Started
+
+### Quick Setup
+
+1. **Enable Plugin** - Activate in theme configuration
+2. **Configure Provider** - Set up API keys or Ollama
+3. **Test Endpoint** - Try the generate endpoint
+4. **Build Custom Features** - Use utilities for your use cases
+
+### Next Steps
+
+- **[Installation](./02-installation.md)** - Set up the plugin
+- **[Configuration](./03-configuration.md)** - Configure providers and settings
+- **[Text Generation](../02-features/01-text-generation.md)** - Start generating content
+- **[Core Utilities](../04-advanced-usage/01-core-utilities.md)** - Build custom endpoints
+
+## Key Features Summary
+
+✅ **Multi-Provider Support** - OpenAI, Anthropic, Ollama  
+✅ **Text Generation** - Flexible content creation  
+✅ **Embeddings** - Semantic search capabilities  
+✅ **History Tracking** - Complete audit trail  
+✅ **Cost Calculation** - Automatic usage tracking  
+✅ **Error Handling** - Robust error management  
+✅ **TypeScript** - Full type safety  
+✅ **Extensible** - Build custom endpoints  
+✅ **Production-Ready** - Used in real applications
+
+## Philosophy
+
+This plugin is designed for developers who want:
+- **Control** - Build exactly what you need
+- **Flexibility** - Choose your provider and model
+- **Simplicity** - Clean utilities without bloat
+- **Performance** - Efficient, well-tested code
+- **Maintainability** - Clear patterns and documentation
+
+It's not a black box. It's a toolkit.