@majkapp/plugin-kit 3.5.4 → 3.5.5

package/docs/FULL.md

@@ -10,12 +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. [Teammates](#teammates)
-9. [Lifecycle](#lifecycle)
-10. [Testing](#testing)
-11. [Configuration](#configuration)
-12. [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
 
@@ -334,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.

package/docs/INDEX.md

@@ -639,6 +639,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majkapp/plugin-kit",
-  "version": "3.5.4",
+  "version": "3.5.5",
   "description": "Pure plugin definition library for MAJK - outputs plugin definitions, not HTTP servers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",