@majkapp/plugin-kit 3.5.3 → 3.5.5

package/docs/FULL.md

@@ -10,11 +10,13 @@ Comprehensive reference for @majkapp/plugin-kit covering all features and patter
 4. [Screens](#screens)
 5. [Generated Hooks](#generated-hooks)
 6. [Context API](#context-api)
-7. [Services](#services)
-8. [Lifecycle](#lifecycle)
-9. [Testing](#testing)
-10. [Configuration](#configuration)
-11. [Best Practices](#best-practices)
+7. [AI API](#ai-api)
+8. [Services](#services)
+9. [Teammates](#teammates)
+10. [Lifecycle](#lifecycle)
+11. [Testing](#testing)
+12. [Configuration](#configuration)
+13. [Best Practices](#best-practices)
 
 ## Quick Start
 
@@ -333,6 +335,147 @@ await ctx.majk.mcpServers.get(id);
 const subscription = await ctx.majk.eventBus.subscribeAll(handler);
 ```
 
+## AI API
+
+Access AI providers and language models with a unified, provider-agnostic interface.
+
+### Basic Usage
+
+```typescript
+// Get default LLM
+const llm = ctx.majk.ai.getDefaultLLM();
+
+// Send a prompt
+const result = await llm.prompt({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant' },
+    { role: 'user', content: 'What is TypeScript?' }
+  ],
+  temperature: 0.7,
+  maxTokens: 500
+});
+
+console.log(result.content);
+console.log(`Tokens used: ${result.usage?.totalTokens}`);
+```
+
+### Provider Management
+
+```typescript
+// List all providers
+const providers = ctx.majk.ai.listProviders();
+for (const provider of providers) {
+  console.log(`${provider.name}: ${provider.capabilities}`);
+}
+
+// Get specific provider
+const bedrock = ctx.majk.ai.getProvider('bedrock');
+if (bedrock) {
+  const claude = bedrock.getLLM('anthropic.claude-3-5-sonnet-20241022-v2:0');
+}
+
+// Query by capability
+const imageProviders = ctx.majk.ai.getProvidersWithCapability('imageGeneration');
+
+// Check status
+const status = await ctx.majk.ai.getProviderStatus('bedrock');
+console.log(`Available: ${status.available}, Authenticated: ${status.authenticated}`);
+```
+
+### Streaming Responses
+
+```typescript
+const stream = llm.promptStream({
+  messages: [{ role: 'user', content: 'Tell me a story' }]
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === 'content_delta') {
+    process.stdout.write(chunk.content);
+  }
+}
+```
+
+### Structured JSON Output
+
+```typescript
+const result = await llm.promptForJson({
+  messages: [
+    { role: 'user', content: 'Analyze sentiment: "This is amazing!"' }
+  ],
+  schema: {
+    type: 'object',
+    properties: {
+      sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+      confidence: { type: 'number' }
+    },
+    required: ['sentiment', 'confidence']
+  }
+});
+
+console.log(result.sentiment); // Type-safe access
+```
+
+### Advanced Features
+
+```typescript
+// Function calling
+const result = await llm.functionCall({
+  messages: [{ role: 'user', content: 'What is the weather?' }],
+  functions: [{
+    name: 'getWeather',
+    description: 'Get weather for a location',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: { type: 'string' }
+      }
+    }
+  }]
+});
+
+// Image generation (if provider supports it)
+const imageProviders = ctx.majk.ai.getProvidersWithCapability('imageGeneration');
+if (imageProviders.length > 0) {
+  const image = await imageProviders[0].generateImage?.({
+    prompt: 'A beautiful sunset',
+    size: '1024x1024'
+  });
+}
+
+// Text embeddings (if provider supports it)
+const embedding = await provider.generateEmbedding?.('Some text to embed');
+
+// Audio transcription (if provider supports it)
+const transcription = await provider.transcribeAudio?.({
+  audio: audioBuffer,
+  format: 'mp3'
+});
+```
+
+### Error Handling
+
+```typescript
+import { AIProviderError } from '@majkapp/plugin-kit';
+
+try {
+  const result = await llm.prompt({ messages });
+} catch (error) {
+  if (error instanceof AIProviderError) {
+    console.error(`AI Error [${error.code}]: ${error.message}`);
+
+    if (error.code === 'RATE_LIMIT_EXCEEDED') {
+      // Handle rate limiting
+    }
+    if (error.code === 'AUTHENTICATION_FAILED') {
+      // Handle auth errors
+    }
+  }
+}
+```
+
+For complete AI documentation, run: `npx @majkapp/plugin-kit --ai`
+
 ## Services
 
 Group related functions together.
@@ -379,6 +522,91 @@ Group related functions together.
 .endService()
 ```
 
+## Teammates
+
+Define AI agents that users can interact with.
+
+### Auto-Generated Default Teammate
+
+Every plugin automatically gets a default teammate with access to ALL functions.
+
+**Default Behavior**:
+- Name: `"<Plugin Name> Expert"`
+- ID: Same as package name (e.g., `"@majk/my-plugin"`)
+- Functions: ALL plugin functions
+- System Prompt: Generic (customizable)
+
+### Custom Instructions
+
+```typescript
+.instructions(`You are an expert assistant for My Plugin.
+
+Your capabilities:
+- Function 1 using func1
+- Function 2 using func2
+
+When helping users:
+1. Explain what you're doing
+2. Present results clearly
+3. Suggest next steps`)
+```
+
+### Disable Default Teammate
+
+```typescript
+.noDefaultTeammate()
+```
+
+### Custom Teammates
+
+```typescript
+.teamMember([
+  {
+    id: 'viewer',
+    name: 'Viewer (Read-Only)',
+    systemPrompt: 'You are a read-only assistant...',
+    expertise: ['Data Viewing'],
+    skills: {
+      primary: ['Query'],
+      secondary: [],
+      languages: [],
+      frameworks: [],
+      tools: []
+    },
+    personality: {
+      workStyle: 'methodical',
+      codeStyle: 'concise',
+      reviewStyle: 'pragmatic',
+      communicationStyle: 'explanatory'
+    },
+    metadata: {
+      totalTasks: 0,
+      successfulTasks: 0,
+      projectHistory: [],
+      codeStats: {
+        linesWritten: 0,
+        filesModified: 0,
+        testsWritten: 0,
+        reviewsPassed: 0,
+        commitsCreated: 0
+      }
+    },
+    mcpServerIds: [],
+    functions: [
+      'getData',       // Simple: current plugin
+      'searchData',
+      {                // Advanced: cross-plugin
+        pluginId: '@other/plugin',
+        serviceName: '@other/plugin:all',
+        functionName: 'otherFunc'
+      }
+    ]
+  }
+])
+```
+
+See `npx @majkapp/plugin-kit --teammates` for complete guide.
+
 ## Lifecycle
 
 Initialize and clean up resources.

package/docs/INDEX.md

@@ -639,7 +639,9 @@ Run `npx @majkapp/plugin-kit --functions` - Deep dive into function patterns
 Run `npx @majkapp/plugin-kit --screens` - Screen configuration details
 Run `npx @majkapp/plugin-kit --hooks` - Generated hooks reference
 Run `npx @majkapp/plugin-kit --context` - ctx.majk and ctx.logger APIs
+Run `npx @majkapp/plugin-kit --ai` - AI providers and LLMs
 Run `npx @majkapp/plugin-kit --services` - Service grouping patterns
+Run `npx @majkapp/plugin-kit --teammates` - AI teammates and agents
 Run `npx @majkapp/plugin-kit --lifecycle` - onReady and cleanup
 Run `npx @majkapp/plugin-kit --testing` - Complete testing guide
 Run `npx @majkapp/plugin-kit --config` - vite.config.js and project setup