@breadstone/archipel-mcp 0.0.15 → 0.0.16

package/data/guides/ai-text-generation.md

@@ -0,0 +1,385 @@
+---
+title: AI Text Generation
+description: Generate text completions with multi-provider support for OpenAI, Anthropic, Google Gemini, and Grok using a unified configuration layer.
+order: 15
+---
+
+# AI Text Generation
+
+This guide covers text generation with `platform-intelligence`: choosing an AI provider, configuring the module, generating completions, registering custom capabilities, and building intent-based orchestration.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-intelligence
+```
+
+Install the AI SDK provider package for the model you want to use:
+
+| Provider       | Package             |
+| -------------- | ------------------- |
+| **OpenAI**     | `@ai-sdk/openai`    |
+| **Anthropic**  | `@ai-sdk/anthropic` |
+| **Google**     | `@ai-sdk/google`    |
+| **Grok (xAI)** | `@ai-sdk/openai`    |
+
+```bash
+# Example: OpenAI
+yarn add @ai-sdk/openai
+```
+
+> Grok uses the OpenAI-compatible endpoint, so it shares the `@ai-sdk/openai` package.
+
+---
+
+## Module Registration
+
+Import `IntelligenceModule` into your application module. It exposes `IntelligenceTextGenerator` and `IntelligenceCapabilityRegistry` as shared providers.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
+
+@Module({
+  imports: [IntelligenceModule],
+})
+export class AppModule {}
+```
+
+---
+
+## Configuration
+
+All intelligence settings are read from environment variables via `ConfigService`. No direct `process.env` access is needed.
+
+```env
+INTELLIGENCE_PROVIDER=openai
+INTELLIGENCE_MODEL=gpt-4o-mini
+INTELLIGENCE_API_KEY=sk-...
+INTELLIGENCE_TEMPERATURE=0.7
+INTELLIGENCE_TOP_P=1
+INTELLIGENCE_MAX_OUTPUT_TOKENS=1024
+INTELLIGENCE_BASE_URL=              # optional — override for custom endpoints
+```
+
+### Supported Providers
+
+| `INTELLIGENCE_PROVIDER` | Default model              | Notes                              |
+| ----------------------- | -------------------------- | ---------------------------------- |
+| `openai`                | `gpt-4o-mini`              | OpenAI API                         |
+| `anthropic`             | `claude-sonnet-4-20250514` | Anthropic API                      |
+| `google`                | `gemini-2.0-flash`         | Google Gemini API                  |
+| `grok`                  | `grok-3-mini-fast`         | xAI Grok via OpenAI-compatible API |
+
+Each provider resolves its API key and base URL from dedicated environment variables when the generic `INTELLIGENCE_API_KEY` is not set:
+
+```env
+# Provider-specific keys (optional — fallback from INTELLIGENCE_API_KEY)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_GENERATIVE_AI_API_KEY=AI...
+GROK_API_KEY=xai-...
+```
+
+---
+
+## Generating Text
+
+Inject `IntelligenceTextGenerator` to generate completions:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';
+import type { IIntelligencePrompt } from '@breadstone/archipel-platform-intelligence';
+
+@Injectable()
+export class SummaryService {
+  private readonly _textGenerator: IntelligenceTextGenerator;
+
+  constructor(textGenerator: IntelligenceTextGenerator) {
+    this._textGenerator = textGenerator;
+  }
+
+  public async summarize(content: string): Promise<string> {
+    const prompt: IIntelligencePrompt = {
+      systemPrompt: 'You are a concise summarizer. Respond with a short summary.',
+      messages: [{ role: 'user', content: content }],
+    };
+
+    const completion = await this._textGenerator.generateText(prompt);
+
+    return completion.text;
+  }
+}
+```
+
+### Prompt Structure
+
+A prompt consists of an optional system prompt and an ordered array of messages:
+
+```typescript
+interface IIntelligencePrompt {
+  readonly systemPrompt: string | null;
+  readonly messages: ReadonlyArray<IIntelligencePromptMessage>;
+}
+
+interface IIntelligencePromptMessage {
+  readonly role: 'user' | 'assistant' | 'system';
+  readonly content: string;
+}
+```
+
+### Per-Request Overrides
+
+Override generation parameters for individual requests without changing the global configuration:
+
+```typescript
+const completion = await this._textGenerator.generateText(prompt, {
+  temperature: 0.2, // more deterministic
+  maxOutputTokens: 256, // shorter responses
+});
+```
+
+### Completion Response
+
+The response includes the generated text, the provider/model used, and optional token usage telemetry:
+
+```typescript
+interface IIntelligenceTextCompletion {
+  readonly text: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly usage: IIntelligenceCompletionUsage | null;
+}
+
+interface IIntelligenceCompletionUsage {
+  readonly promptTokens: number | null;
+  readonly completionTokens: number | null;
+  readonly totalTokens: number | null;
+}
+```
+
+---
+
+## Multi-Turn Conversations
+
+Build multi-turn conversations by passing the full message history:
+
+```typescript
+const prompt: IIntelligencePrompt = {
+  systemPrompt: 'You are a helpful fitness coach.',
+  messages: [
+    { role: 'user', content: 'What should I eat before a workout?' },
+    { role: 'assistant', content: 'A balanced meal with carbs and protein about 2 hours before.' },
+    { role: 'user', content: 'Can you give me a specific example?' },
+  ],
+};
+
+const completion = await this._textGenerator.generateText(prompt);
+```
+
+---
+
+## Capability System
+
+The intelligence module includes a capability registry that lets you build intent-based orchestration. Capabilities are domain-specific handlers that respond to classified user intents.
+
+### Defining a Capability
+
+Implement the `IIntelligenceCapability` interface:
+
+```typescript
+import type {
+  IIntelligenceCapability,
+  IIntelligenceCapabilityMetadata,
+  IIntelligenceCapabilityPayload,
+  IIntelligenceCapabilityResult,
+  IIntelligenceContext,
+  IIntelligenceIntent,
+} from '@breadstone/archipel-platform-intelligence';
+
+export class WorkoutRecommendationCapability implements IIntelligenceCapability {
+  public readonly metadata: IIntelligenceCapabilityMetadata = {
+    id: 'workout-recommendation',
+    name: 'Workout Recommendation',
+    description: 'Recommends workouts based on user preferences.',
+    priority: 10,
+    intentName: 'recommend_workout',
+  };
+
+  public canHandle(intent: IIntelligenceIntent, _context: IIntelligenceContext): boolean {
+    return intent.name === 'recommend_workout' && intent.confidence >= 0.7;
+  }
+
+  public async execute(payload: IIntelligenceCapabilityPayload): Promise<IIntelligenceCapabilityResult> {
+    // Use payload.intent, payload.context, payload.userMessage
+    return {
+      messages: [{ content: 'Here is your personalized workout plan...', metadata: null }],
+      artifacts: [],
+      followUps: [{ id: 'adjust', label: 'Adjust difficulty', payload: { action: 'adjust' } }],
+    };
+  }
+}
+```
+
+### Registering Capabilities
+
+Use `IntelligenceCapabilityRegistrarBase` to auto-register capabilities when a module initializes:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import {
+  IntelligenceCapabilityRegistrarBase,
+  IntelligenceCapabilityRegistry,
+} from '@breadstone/archipel-platform-intelligence';
+import type { IIntelligenceCapability } from '@breadstone/archipel-platform-intelligence';
+
+@Injectable()
+export class WorkoutCapabilityRegistrar extends IntelligenceCapabilityRegistrarBase {
+  constructor(registry: IntelligenceCapabilityRegistry) {
+    super(registry);
+  }
+
+  protected getCapabilities(): ReadonlyArray<IIntelligenceCapability> {
+    return [new WorkoutRecommendationCapability()];
+  }
+}
+```
+
+Register the registrar as a provider in your feature module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
+
+@Module({
+  imports: [IntelligenceModule],
+  providers: [WorkoutCapabilityRegistrar],
+})
+export class WorkoutModule {}
+```
+
+### Resolving Capabilities at Runtime
+
+Use the registry to find the best-matching capability for a classified intent:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IntelligenceCapabilityRegistry } from '@breadstone/archipel-platform-intelligence';
+import type {
+  IIntelligenceCapabilityResult,
+  IIntelligenceContext,
+  IIntelligenceIntent,
+} from '@breadstone/archipel-platform-intelligence';
+
+@Injectable()
+export class ChatOrchestrator {
+  private readonly _registry: IntelligenceCapabilityRegistry;
+
+  constructor(registry: IntelligenceCapabilityRegistry) {
+    this._registry = registry;
+  }
+
+  public async handle(
+    intent: IIntelligenceIntent,
+    context: IIntelligenceContext,
+    userMessage: string,
+  ): Promise<IIntelligenceCapabilityResult | null> {
+    const capability = this._registry.resolve(intent, context);
+    if (!capability) {
+      return null; // No matching capability — fall back to generic response
+    }
+
+    return capability.execute({ intent, context, userMessage });
+  }
+}
+```
+
+Capabilities are resolved by priority (lowest number first). If multiple capabilities can handle the same intent, the one with the highest priority (lowest value) wins.
+
+---
+
+## Inspecting Configuration
+
+Retrieve the resolved provider configuration at runtime:
+
+```typescript
+const config = this._textGenerator.getConfiguration();
+console.log(config.provider); // 'openai'
+console.log(config.model); // 'gpt-4o-mini'
+```
+
+---
+
+## Error Handling
+
+`IntelligenceTextGenerator` wraps all provider errors in `IntelligenceProviderError`, which includes `provider`, `model`, and `retryable` metadata. The generator automatically retries retryable failures (e.g. transient network errors) with exponential backoff before giving up.
+
+### Timeout & Retry Defaults
+
+| Setting     | Default  | Description                                                 |
+| ----------- | -------- | ----------------------------------------------------------- |
+| `timeoutMs` | `30000`  | Abort the provider request after this many milliseconds     |
+| Max retries | `2`      | Retryable errors are retried up to 2 times                  |
+| Backoff     | 1s → 4s  | Exponential backoff with a 4-second cap between retries     |
+
+Override the timeout per call:
+
+```typescript
+const result = await this._textGenerator.generateText(prompt, {
+  timeoutMs: 15_000, // 15-second timeout for this call
+});
+```
+
+### Catching Errors
+
+```typescript
+import { IntelligenceProviderError } from '@breadstone/archipel-platform-intelligence';
+
+try {
+  const result = await this._textGenerator.generateText(prompt);
+  return result.text;
+} catch (error) {
+  if (error instanceof IntelligenceProviderError) {
+    this._logger.error(`Provider ${error.provider}/${error.model} failed`, {
+      retryable: error.retryable,
+      message: error.message,
+    });
+  }
+  return 'Sorry, I could not generate a response right now.';
+}
+```
+
+If an AI SDK provider package is not installed, the error message clearly states which package is missing.
+
+---
+
+## Architecture Overview
+
+```
+┌────────────────────────────────────┐
+│         IntelligenceModule         │
+│                                    │
+│  ┌──────────────────────────────┐  │
+│  │  IntelligenceTextGenerator   │──┼── generateText(prompt, options?)
+│  │  (ConfigService → provider)  │  │
+│  └──────────────────────────────┘  │
+│                                    │
+│  ┌──────────────────────────────┐  │
+│  │  IntelligenceCapability      │──┼── resolve(intent, context)
+│  │  Registry                    │  │   register(capability)
+│  └──────────────────────────────┘  │
+└────────────────────────────────────┘
+         │                │
+         ▼                ▼
+  ┌─────────────┐  ┌──────────────┐
+  │ Provider     │  │ Feature      │
+  │ Loaders      │  │ Capabilities │
+  │ (OpenAI,     │  │ (custom      │
+  │  Anthropic,  │  │  handlers)   │
+  │  Google,     │  │              │
+  │  Grok)       │  │              │
+  └─────────────┘  └──────────────┘
+```

package/data/guides/analytics-and-error-tracking.md

@@ -0,0 +1,189 @@
+---
+title: Analytics & Error Tracking
+description: Capture errors, messages, and user context with Sentry, Application Insights, Datadog, or a custom provider.
+order: 14
+---
+
+# Analytics & Error Tracking
+
+This guide covers error tracking and analytics with `platform-analytics`: choosing a provider, capturing exceptions, recording breadcrumbs, and setting user context.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-analytics
+```
+
+---
+
+## Choose a Provider
+
+`platform-analytics` abstracts error tracking and analytics behind an `AnalyticsClientPort`. Supported providers:
+
+| Provider                 | When to use                                  |
+| ------------------------ | -------------------------------------------- |
+| **Sentry**               | Full-featured error tracking and performance |
+| **Application Insights** | Azure-native monitoring                      |
+| **Datadog**              | Infrastructure + APM monitoring              |
+| **Noop**                 | Development / testing — discards all events  |
+
+---
+
+## Module Registration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { AnalyticsModule } from '@breadstone/archipel-platform-analytics';
+import { SentryAnalyticsClient } from './adapters/SentryAnalyticsClient';
+import { SENTRY_CONFIG_ENTRIES } from './env';
+
+@Module({
+  imports: [
+    AnalyticsModule.register({
+      analyticsClient: SentryAnalyticsClient,
+      configEntries: [...SENTRY_CONFIG_ENTRIES],
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Implementing the Client Port
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import {
+  AnalyticsClientPort,
+  AnalyticsLevel,
+  type IAnalyticsUser,
+  type IAnalyticsBreadcrumb,
+} from '@breadstone/archipel-platform-analytics';
+import * as Sentry from '@sentry/node';
+
+@Injectable()
+export class SentryAnalyticsClient extends AnalyticsClientPort {
+  public captureException(error: Error, context?: Record<string, unknown>): void {
+    Sentry.captureException(error, { extra: context });
+  }
+
+  public captureMessage(message: string, level: AnalyticsLevel): void {
+    Sentry.captureMessage(message, level);
+  }
+
+  public setUser(user: IAnalyticsUser): void {
+    Sentry.setUser({ id: user.id, email: user.email });
+  }
+
+  public addBreadcrumb(breadcrumb: IAnalyticsBreadcrumb): void {
+    Sentry.addBreadcrumb({
+      category: breadcrumb.category,
+      message: breadcrumb.message,
+      level: breadcrumb.level,
+      data: breadcrumb.data,
+    });
+  }
+}
+```
+
+---
+
+## Capturing Errors
+
+Inject `AnalyticsClientPort` to capture exceptions with full context:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';
+
+@Injectable()
+export class PaymentService {
+  private readonly _analytics: AnalyticsClientPort;
+
+  constructor(analytics: AnalyticsClientPort) {
+    this._analytics = analytics;
+  }
+
+  public async processPayment(orderId: string): Promise<void> {
+    try {
+      // ... payment logic
+    } catch (error) {
+      this._analytics.captureException(error as Error, {
+        orderId,
+        action: 'processPayment',
+      });
+      throw error;
+    }
+  }
+}
+```
+
+---
+
+## User Context
+
+Set user context early in the request lifecycle (e.g., via a middleware or interceptor) so all captured events include user information:
+
+```typescript
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';
+import type { IAuthSubject } from '@breadstone/archipel-platform-authentication';
+
+@Injectable()
+export class AnalyticsUserMiddleware implements NestMiddleware {
+  private readonly _analytics: AnalyticsClientPort;
+
+  constructor(analytics: AnalyticsClientPort) {
+    this._analytics = analytics;
+  }
+
+  public use(req: Request, _res: Response, next: NextFunction): void {
+    const user = req.user as IAuthSubject | undefined;
+
+    if (user) {
+      this._analytics.setUser({
+        id: user.id,
+        email: user.email ?? undefined,
+      });
+    }
+
+    next();
+  }
+}
+```
+
+---
+
+## Breadcrumbs
+
+Breadcrumbs are a trail of events leading up to an error. They help you understand what happened before a crash:
+
+```typescript
+this._analytics.addBreadcrumb({
+  category: 'payment',
+  message: 'Checkout session created',
+  level: 'info',
+  data: { orderId, provider: 'stripe' },
+});
+```
+
+---
+
+## Development Tips
+
+- Use the **Noop** provider during local development and testing to avoid sending events to production analytics.
+- Set `isGlobal: true` in the module registration so `AnalyticsClientPort` is available everywhere without re-importing.
+- Combine with `platform-telemetry` for metrics. Use analytics for error tracking and telemetry for performance monitoring.
+- Map domain errors to known categories in your analytics context to group related issues.
+
+---
+
+## Next Steps
+
+- See the [Telemetry & Observability](/guides/telemetry-and-observability) guide for metrics and tracing
+- Browse the [platform-analytics API reference](/packages/platform-analytics/api/) for complete method signatures