@nextsparkjs/plugin-ai 0.1.0-beta.1

package/.env.example

@@ -0,0 +1,79 @@
+# ============================================
+# AI PLUGIN CONFIGURATION
+# ============================================
+#
+# Copy this file to .env and configure your AI provider credentials
+# This file is loaded automatically by the AI plugin
+#
+# ============================================
+
+# ===========================
+# AI Provider Credentials
+# ===========================
+
+# Anthropic API Key for Claude models
+# Get your key from: https://console.anthropic.com/
+ANTHROPIC_API_KEY=your-anthropic-key-here
+
+# OpenAI API Key for GPT models
+# Get your key from: https://platform.openai.com/
+OPENAI_API_KEY=your-openai-key-here
+
+# ===========================
+# AI Provider Selection
+# ===========================
+
+# Use Local AI (Ollama) by default - set to false to use cloud models
+USE_LOCAL_AI=false
+
+# Default model when using cloud providers
+DEFAULT_CLOUD_MODEL=claude-sonnet-4-5-20250929
+
+# ===========================
+# Ollama Configuration (local models)
+# ===========================
+
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_DEFAULT_MODEL=llama3.2:3b
+
+# ===========================
+# AI Plugin Configuration
+# ===========================
+
+# Enable/disable the AI plugin
+AI_PLUGIN_ENABLED=true
+
+# Enable debug logging for development
+AI_PLUGIN_DEBUG=false
+
+# Default provider preference (anthropic, openai, ollama)
+AI_PLUGIN_DEFAULT_PROVIDER=anthropic
+
+# Maximum tokens for AI generation
+AI_PLUGIN_MAX_TOKENS=4000
+
+# Default temperature for AI generation (0.0-1.0)
+AI_PLUGIN_DEFAULT_TEMPERATURE=0.7
+
+# ===========================
+# Cost Tracking
+# ===========================
+
+# Enable cost tracking and monitoring
+AI_PLUGIN_COST_TRACKING_ENABLED=true
+
+# Daily cost limit (USD)
+AI_PLUGIN_DAILY_COST_LIMIT=10.00
+
+# Monthly cost limit (USD)
+AI_PLUGIN_MONTHLY_COST_LIMIT=100.00
+
+# ===========================
+# Rate Limiting
+# ===========================
+
+# Maximum requests per minute
+AI_PLUGIN_RATE_LIMIT_REQUESTS_PER_MINUTE=60
+
+# Maximum tokens per minute
+AI_PLUGIN_RATE_LIMIT_TOKENS_PER_MINUTE=50000

package/README.md

@@ -0,0 +1,529 @@
+# AI Plugin
+
+Plugin empresarial de IA con soporte multi-modelo, generación de contenido, y características de seguridad. Diseñado para integrarse dinámicamente con el sistema de entidades y plugins.
+
+## Características
+
+### 🤖 Soporte Multi-Modelo
+- **Locales**: Ollama, LM Studio, LocalAI
+- **Cloud**: OpenAI, Anthropic, Groq
+- **Selección automática** basada en casos de uso
+- **Fallback estratégico** cuando los modelos no están disponibles
+
+### 🎯 Generación de Contenido
+- **Templates flexibles** para diferentes tipos de contenido
+- **Optimización por plataforma** (Twitter, Instagram, LinkedIn, etc.)
+- **Generación de variantes** automática
+- **Sugerencias basadas en IA**
+
+### 🛡️ Características de Seguridad
+- **Detección de PII** automática
+- **Filtros de contenido** tóxico
+- **Enmascaramiento de datos** sensibles
+- **Cumplimiento GDPR/CCPA**
+
+### 💰 Gestión de Costos
+- **Seguimiento de tokens** en tiempo real
+- **Estimación de costos** por solicitud
+- **Límites de cuota** configurables
+- **Rate limiting** dinámico
+
+### 🔌 Integración con Entidades
+- **Procesamiento dinámico** de cualquier tipo de entidad
+- **Análisis automático** de contenido
+- **Mejora inteligente** de datos
+- **Sugerencias contextuales**
+
+## Instalación y Configuración
+
+### ⭐ Nuevo: Variables de Entorno a Nivel de Plugin
+
+**¡Ahora puedes configurar el plugin con variables de entorno específicas!**
+
+1. **Copia el archivo de ejemplo:**
+   ```bash
+   cp contents/plugins/ai/.env.example contents/plugins/ai/.env
+   ```
+
+2. **Configura tus claves API:**
+   ```env
+   # API Keys
+   ANTHROPIC_API_KEY=sk-ant-api03-tu_clave_anthropic
+   OPENAI_API_KEY=sk-tu_clave_openai
+
+   # Configuración del Plugin
+   AI_PLUGIN_ENABLED=true
+   AI_PLUGIN_DEBUG=false
+   AI_PLUGIN_DEFAULT_PROVIDER=ollama
+
+   # Ollama (Modelos Locales)
+   OLLAMA_BASE_URL=http://localhost:11434
+   OLLAMA_DEFAULT_MODEL=llama3.2:3b
+
+   # Gestión de Costos
+   AI_PLUGIN_COST_TRACKING_ENABLED=true
+   AI_PLUGIN_DAILY_COST_LIMIT=10.00
+   AI_PLUGIN_MONTHLY_COST_LIMIT=100.00
+   ```
+
+### Ventajas de la Configuración a Nivel de Plugin
+
+- ✅ **Aislamiento**: Configuración específica del plugin sin contaminar `.env` principal
+- ✅ **Modularidad**: Cada plugin maneja sus propias variables de entorno
+- ✅ **Seguridad**: Las claves API están contenidas en el ámbito del plugin
+- ✅ **Flexibilidad**: Diferentes plugins pueden usar diferentes claves API
+- ✅ **Fallback**: Recurre a variables de entorno del sistema si no existe `.env` del plugin
+
+### Variables de Entorno del Sistema (Método Anterior)
+
+También puedes usar variables de entorno globales:
+
+```env
+# OpenAI
+OPENAI_API_KEY=tu_clave_openai
+
+# Anthropic
+ANTHROPIC_API_KEY=tu_clave_anthropic
+
+# Groq
+GROQ_API_KEY=tu_clave_groq
+
+# Configuración local (opcional)
+OLLAMA_BASE_URL=http://localhost:11434
+LM_STUDIO_BASE_URL=http://localhost:1234
+```
+
+### Configuración del Plugin
+
+El plugin se registra automáticamente en el sistema y carga su configuración desde:
+
+1. **Primera prioridad**: `contents/plugins/ai/.env` (archivo específico del plugin)
+2. **Segunda prioridad**: Variables de entorno del sistema (`process.env`)
+3. **Tercera prioridad**: Valores por defecto incorporados
+
+## Uso
+
+### 1. Componentes React
+
+#### AIProvider
+Proveedor de contexto para toda la funcionalidad de IA:
+
+\`\`\`tsx
+import { AIProvider } from '@/contents/plugins/ai/components/AIProvider'
+
+function App() {
+  return (
+    <AIProvider
+      userId="user123"
+      preferLocal={false}
+      autoSelect={true}
+    >
+      <YourApp />
+    </AIProvider>
+  )
+}
+\`\`\`
+
+#### AIChat
+Interfaz de chat con IA integrada:
+
+\`\`\`tsx
+import { AIChat } from '@/contents/plugins/ai/components/AIChat'
+
+function ChatPage() {
+  return (
+    <AIChat
+      entityContext={{
+        type: 'task',
+        id: 'task_123',
+        data: { title: 'Proyecto importante' }
+      }}
+      contentType="custom"
+      showModelSelector={true}
+      onEntityProcessed={(result) => {
+        console.log('Entidad procesada:', result)
+      }}
+    />
+  )
+}
+\`\`\`
+
+#### ContentGenerator
+Generador de contenido con templates:
+
+\`\`\`tsx
+import { ContentGenerator } from '@/contents/plugins/ai/components/ContentGenerator'
+
+function ContentPage() {
+  return (
+    <ContentGenerator
+      defaultContentType="social"
+      showTemplates={true}
+      autoSuggestions={true}
+      onContentGenerated={(content) => {
+        console.log('Contenido generado:', content)
+      }}
+    />
+  )
+}
+\`\`\`
+
+### 2. Hooks
+
+#### useAI
+Hook principal para funcionalidad de IA:
+
+\`\`\`tsx
+import { useAI } from '@/contents/plugins/ai/hooks/useAI'
+
+function MyComponent() {
+  const ai = useAI({
+    userId: 'user123',
+    autoCheck: true
+  })
+
+  const handleGenerate = async () => {
+    const result = await ai.generateText('Escribe un email profesional')
+    console.log(result)
+  }
+
+  const handleAnalyze = async () => {
+    const analysis = await ai.analyze('Este es mi contenido')
+    console.log(analysis)
+  }
+
+  return (
+    <div>
+      <button onClick={handleGenerate}>Generar</button>
+      <button onClick={handleAnalyze}>Analizar</button>
+    </div>
+  )
+}
+\`\`\`
+
+#### useContentGeneration
+Hook especializado para generación de contenido:
+
+\`\`\`tsx
+import { useContentGeneration } from '@/contents/plugins/ai/hooks/useContentGeneration'
+
+function ContentComponent() {
+  const content = useContentGeneration({
+    defaultContentType: 'blog',
+    autoSuggestions: true
+  })
+
+  const handleGenerate = async () => {
+    const result = await content.generateContent(
+      'Escribe sobre tecnología',
+      {
+        platform: 'linkedin',
+        tone: 'profesional',
+        audience: 'desarrolladores'
+      }
+    )
+    console.log(result)
+  }
+
+  return <button onClick={handleGenerate}>Generar Contenido</button>
+}
+\`\`\`
+
+### 3. API REST
+
+#### ⭐ Nuevo: Generar Contenido Multi-Proveedor
+
+**Usando Anthropic Claude (configuración del plugin):**
+\`\`\`bash
+POST /api/plugin/ai/generate
+Content-Type: application/json
+
+{
+  "prompt": "Explica la computación cuántica en términos simples",
+  "model": "claude-3-5-haiku-20241022",
+  "contentType": "blog",
+  "maxTokens": 500
+}
+\`\`\`
+
+**Usando OpenAI GPT (configuración del plugin):**
+\`\`\`bash
+POST /api/plugin/ai/generate
+Content-Type: application/json
+
+{
+  "prompt": "Escribe una función para invertir una cadena",
+  "model": "gpt-4o-mini",
+  "contentType": "analysis",
+  "temperature": 0.3
+}
+\`\`\`
+
+**Usando Ollama Local (sin clave API requerida):**
+\`\`\`bash
+POST /api/plugin/ai/generate
+Content-Type: application/json
+
+{
+  "prompt": "Crea una publicación en redes sociales sobre sostenibilidad",
+  "model": "llama3.2:3b",
+  "contentType": "social"
+}
+\`\`\`
+
+**Respuesta con seguimiento de costos en tiempo real:**
+\`\`\`json
+{
+  "success": true,
+  "data": {
+    "content": "Contenido generado aquí...",
+    "model": "claude-3-5-haiku-20241022",
+    "provider": "anthropic",
+    "isLocal": false,
+    "tokens": {
+      "input": 25,
+      "output": 150,
+      "total": 175
+    },
+    "cost": 0.000194,
+    "metadata": {
+      "costBreakdown": {
+        "inputTokens": 25,
+        "outputTokens": 150,
+        "inputCost": 0.00000625,
+        "outputCost": 0.0001875,
+        "totalCost": 0.000194
+      }
+    }
+  }
+}
+\`\`\`
+
+#### Información de Capacidades
+\`\`\`bash
+GET /api/plugin/ai/generate
+\`\`\`
+
+#### Generar Contenido (Método Anterior)
+\`\`\`bash
+POST /api/v1/ai/generate
+Content-Type: application/json
+
+{
+  "prompt": "Escribe un tweet sobre IA",
+  "contentType": "social",
+  "platform": "twitter",
+  "tone": "casual"
+}
+\`\`\`
+
+#### Analizar Contenido
+\`\`\`bash
+POST /api/v1/ai/analyze
+Content-Type: application/json
+
+{
+  "content": "Este es mi contenido para analizar",
+  "analysisType": "comprehensive"
+}
+\`\`\`
+
+#### Procesar Entidad
+\`\`\`bash
+POST /api/v1/ai/entity
+Content-Type: application/json
+
+{
+  "entityType": "task",
+  "entityId": "task_123",
+  "action": "analyze",
+  "prompt": "Analiza esta tarea y sugiere mejoras"
+}
+\`\`\`
+
+### 4. Integración Directa con AIAPI
+
+Para uso directo desde el código del servidor:
+
+\`\`\`tsx
+import { AIAPI } from '@/contents/plugins/ai/lib/ai-api'
+
+// Generación simple
+const text = await AIAPI.generateText('Hola mundo')
+
+// Generación avanzada
+const response = await AIAPI.generateContentAdvanced({
+  prompt: 'Escribe un artículo',
+  systemPrompt: 'Eres un experto escritor',
+  options: {
+    contentType: 'blog',
+    temperature: 0.7
+  }
+})
+
+// Procesamiento de entidades
+const result = await AIAPI.processEntity(
+  'user',
+  { name: 'Juan', email: 'juan@example.com' },
+  'analyze'
+)
+
+// Verificación de seguridad
+const safety = await AIAPI.isContentSafe('Este contenido')
+\`\`\`
+
+## Arquitectura
+
+### Estructura de Archivos
+\`\`\`
+contents/plugins/ai/
+├── plugin.config.ts          # Configuración principal del plugin
+├── types/
+│   └── ai.types.ts           # Definiciones de tipos TypeScript
+├── lib/
+│   ├── ai-api.ts            # API exportable principal
+│   ├── ai-core.ts           # Funcionalidad core de IA
+│   ├── model-selector.ts    # Selección de modelos
+│   ├── prompts.ts           # Sistema de prompts modulares
+│   ├── safety.ts            # Características de seguridad
+│   ├── cost-tracker.ts      # Seguimiento de costos
+│   └── rate-limiter.ts      # Rate limiting
+├── hooks/
+│   ├── useAI.ts             # Hook principal de IA
+│   ├── useContentGeneration.ts # Hook de generación
+│   └── useModelSelection.ts  # Hook de selección de modelos
+├── components/
+│   ├── AIProvider.tsx       # Proveedor de contexto React
+│   ├── AIChat.tsx           # Componente de chat
+│   ├── ContentGenerator.tsx # Generador de contenido
+│   ├── ModelSelector.tsx    # Selector de modelos
+│   └── UsageMonitor.tsx     # Monitor de uso
+└── api/
+    └── endpoints.ts         # Endpoints dinámicos de API
+\`\`\`
+
+### Flujo de Datos
+
+1. **Configuración**: El plugin se registra automáticamente en el sistema
+2. **Inicialización**: Los modelos y servicios se configuran al activar
+3. **Solicitud**: Los usuarios pueden usar componentes, hooks, o API
+4. **Procesamiento**: Las solicitudes pasan por el AI Core
+5. **Seguridad**: Se aplican filtros de contenido y PII
+6. **Modelo**: Se selecciona el modelo óptimo automáticamente
+7. **Generación**: Se ejecuta la solicitud de IA
+8. **Respuesta**: Se devuelve el contenido procesado
+9. **Seguimiento**: Se registran métricas y costos
+
+### Integración con Entidades
+
+El plugin puede procesar cualquier tipo de entidad dinámicamente:
+
+\`\`\`tsx
+// Para tareas
+await AIAPI.processEntity('task', taskData, 'analyze')
+
+// Para usuarios
+await AIAPI.processEntity('user', userData, 'enhance')
+
+// Para posts
+await AIAPI.processEntity('post', postData, 'summarize')
+
+// Para proyectos
+await AIAPI.processEntity('project', projectData, 'suggest')
+\`\`\`
+
+### Endpoints Dinámicos
+
+El sistema de endpoints se adapta automáticamente:
+
+- \`/api/v1/ai/\` → Info del plugin
+- \`/api/v1/ai/generate\` → Generación de contenido
+- \`/api/v1/ai/analyze\` → Análisis de contenido
+- \`/api/v1/ai/enhance\` → Mejora de contenido
+- \`/api/v1/ai/entity\` → Procesamiento de entidades
+- \`/api/v1/ai/models\` → Modelos disponibles
+- \`/api/v1/ai/usage\` → Estadísticas de uso
+- \`/api/v1/ai/health\` → Estado del plugin
+
+## Casos de Uso
+
+### 1. Asistente de Tareas
+Analiza y mejora tareas automáticamente:
+
+\`\`\`tsx
+const enhancedTask = await AIAPI.processEntity(
+  'task',
+  { title: 'Hacer algo', description: 'Pendiente' },
+  'enhance'
+)
+\`\`\`
+
+### 2. Generación de Contenido Social
+Crea contenido optimizado para diferentes plataformas:
+
+\`\`\`tsx
+const tweetContent = await content.generateContent(
+  'Lanzamiento de producto',
+  { platform: 'twitter', tone: 'emocionante' }
+)
+\`\`\`
+
+### 3. Chat con Contexto de Entidad
+Chat que entiende el contexto de entidades específicas:
+
+\`\`\`tsx
+<AIChat
+  entityContext={{
+    type: 'project',
+    id: 'project_456',
+    data: projectData
+  }}
+/>
+\`\`\`
+
+### 4. Análisis de Contenido
+Analiza contenido para obtener insights:
+
+\`\`\`tsx
+const analysis = await ai.analyze(content, 'comprehensive')
+// Retorna: legibilidad, sentimiento, temas, SEO, etc.
+\`\`\`
+
+## Contribución
+
+Para extender el plugin:
+
+1. **Nuevos Modelos**: Agrega configuraciones en \`model-selector.ts\`
+2. **Nuevos Endpoints**: Registra en \`endpoints.ts\`
+3. **Nuevos Tipos de Contenido**: Extiende \`prompts.ts\`
+4. **Nuevos Componentes**: Agrega en \`components/\`
+5. **Nuevos Hooks**: Implementa en \`hooks/\`
+
+## Seguridad y Privacidad
+
+- **Datos sensibles**: Se enmascaran automáticamente
+- **Contenido tóxico**: Se filtra antes del procesamiento
+- **Logs**: No se almacenan datos de usuario
+- **Cumplimiento**: Compatible con GDPR y CCPA
+- **Rate limiting**: Previene abuso del sistema
+
+## Monitoreo y Métricas
+
+El plugin incluye monitoreo completo:
+
+- **Uso por usuario**: Tokens, costos, solicitudes
+- **Rendimiento**: Tiempo de respuesta, tasa de éxito
+- **Modelos**: Popularidad, efectividad
+- **Errores**: Seguimiento y alertas
+- **Cuotas**: Límites diarios y mensuales
+
+## Soporte
+
+Para problemas o preguntas:
+
+1. Revisa los logs del plugin en la consola
+2. Verifica la configuración de variables de entorno
+3. Confirma que los modelos estén disponibles
+4. Chequea los límites de cuota y rate limiting
+
+El plugin está diseñado para ser completamente flexible y extensible, integrándose perfectamente con el sistema de entidades dinámicas.

package/api/README.md

@@ -0,0 +1,65 @@
+# AI Plugin - Generate Endpoint
+
+Simple AI assistant endpoint for general assistance.
+
+## Usage
+
+**Endpoint:** `POST /api/plugin/ai/generate`
+
+**Body:**
+```json
+{
+  "prompt": "Your question or request",
+  "model": "llama3.2:3b",
+  "maxTokens": 1000,
+  "temperature": 0.7
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "response": "AI response here...",
+  "model": "llama3.2:3b",
+  "provider": "ollama",
+  "isLocal": true,
+  "cost": 0,
+  "tokens": { "input": 15, "output": 42, "total": 57 },
+  "userId": "user_123"
+}
+```
+
+## Examples
+
+### Basic Chat
+```bash
+curl -X POST /api/plugin/ai/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Explain machine learning in simple terms"}'
+```
+
+### With Custom Model
+```bash
+curl -X POST /api/plugin/ai/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "Write a short poem about coding",
+    "model": "claude-3-5-haiku-20241022",
+    "maxTokens": 200
+  }'
+```
+
+## Available Models
+
+- **Local (Free):** 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
+
+## Authentication
+
+Requires session authentication or API key with appropriate scope.
+
+## Custom Endpoints
+
+For specialized use cases, copy this endpoint to your `app/api/` directory and modify as needed. See `examples/app-api-examples/` for templates.