@majkapp/plugin-kit 3.5.4 → 3.6.0

package/docs/API.md

@@ -63,6 +63,14 @@ handler: async (input, ctx) => {
   await ctx.storage.delete(key);
   await ctx.storage.clear();
 
+  // RPC - Inter-plugin communication
+  await ctx.rpc.registerService(serviceName, implementation);
+  await ctx.rpc.unregisterService(serviceName);
+  const proxy = await ctx.rpc.createProxy<T>(serviceName);
+  const callback = await ctx.rpc.createCallback!(fn, options);  // Optional
+  ctx.rpc.cleanupCallback!(callback);                            // Optional
+  const stats = ctx.rpc.getCallbackStats!();                     // Optional
+
   // MAJK APIs
   await ctx.majk.conversations.list();
   await ctx.majk.conversations.get(id);

package/docs/CONTEXT.md

@@ -351,6 +351,79 @@ Subscribe to MAJK events (conversations, todos, projects, etc.).
 })
 ```
 
+## ctx.rpc
+
+Enable inter-plugin communication with RPC services and callbacks.
+
+### Register Service
+
+Make your plugin's functions available to other plugins:
+
+```typescript
+.onLoad(async (ctx) => {
+  // Register a service that other plugins can call
+  await ctx.rpc.registerService('fileProcessor', {
+    async processFile(path: string, onProgress: (percent: number) => void): Promise<string> {
+      await onProgress(0);
+      // ... process file ...
+      await onProgress(50);
+      // ... more processing ...
+      await onProgress(100);
+      return `Processed: ${path}`;
+    }
+  });
+})
+```
+
+### Call Service with Inline Callbacks
+
+Consume services from other plugins:
+
+```typescript
+handler: async (input, ctx) => {
+  // Create proxy to another plugin's service
+  const processor = await ctx.rpc.createProxy<{
+    processFile(path: string, onProgress: (p: number) => void): Promise<string>
+  }>('fileProcessor');
+
+  // Pass callback - it just works!
+  const result = await processor.processFile('/file.txt', (progress) => {
+    ctx.logger.info(`Progress: ${progress}%`);
+  });
+
+  return { result };
+}
+```
+
+### Explicit Callbacks with Cleanup
+
+For long-lived callbacks (subscriptions, event listeners), use `createCallback()`:
+
+```typescript
+handler: async (input, ctx) => {
+  // Auto-cleanup after 10 calls
+  const callback = await ctx.rpc.createCallback!(
+    (event) => ctx.logger.info('Event:', event),
+    { maxCalls: 10 }
+  );
+  await eventService.subscribe(callback);
+
+  // Auto-cleanup after 5 seconds
+  const callback2 = await ctx.rpc.createCallback!(
+    (data) => ctx.logger.info('Data:', data),
+    { timeout: 5000 }
+  );
+  await dataStream.subscribe(callback2);
+
+  // Manual cleanup
+  const callback3 = await ctx.rpc.createCallback!((msg) => ctx.logger.info(msg));
+  // ... later
+  ctx.rpc.cleanupCallback!(callback3);
+}
+```
+
+**For comprehensive RPC patterns and best practices:** Run `npx @majkapp/plugin-kit --rpc`
+
 ## Complete Example: Dashboard Data
 
 ```typescript
@@ -495,6 +568,7 @@ test('getDashboardData aggregates MAJK data', async () => {
 
 ## Next Steps
 
+Run `npx @majkapp/plugin-kit --rpc` - Inter-plugin communication with callbacks
 Run `npx @majkapp/plugin-kit --lifecycle` - onReady and event subscriptions
 Run `npx @majkapp/plugin-kit --services` - Group functions into services
 Run `npx @majkapp/plugin-kit --testing` - Test functions with mock context

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