@breadstone/archipel-mcp 0.0.54 → 0.0.56

package/data/guides/health-indicators.md

@@ -51,11 +51,11 @@ Every health indicator implements this contract:
 
 ```typescript
 interface IHealthIndicator {
-  /** Unique key identifying this indicator in the health response. */
-  readonly key: string;
+    /** Unique key identifying this indicator in the health response. */
+    readonly key: string;
 
-  /** Run the health check and return a Terminus HealthIndicatorResult. */
-  check(): HealthIndicatorResult | Promise<HealthIndicatorResult>;
+    /** Run the health check and return a Terminus HealthIndicatorResult. */
+    check(): HealthIndicatorResult | Promise<HealthIndicatorResult>;
 }
 ```
 
@@ -63,37 +63,40 @@ interface IHealthIndicator {
 
 All 12 platform libraries provide a health indicator via their `/health` subpath:
 
-| Library | Subpath Import | Class | Key | Check Behavior |
-| ------- | -------------- | ----- | --- | -------------- |
-| `platform-database` | `@breadstone/archipel-platform-database/health` | `DatabaseHealthIndicator` | `database` | Prisma `SELECT 1` ping |
-| `platform-blob-storage` | `@breadstone/archipel-platform-blob-storage/health` | `BlobHealthIndicator` | `blob` | HTTP ping to blob URL (or `disabled` if unconfigured) |
-| `platform-mailing` | `@breadstone/archipel-platform-mailing/health` | `MailHealthIndicator` | `mail` | Validates mail host, user, and port config |
-| `platform-caching` | `@breadstone/archipel-platform-caching/health` | `CachingHealthIndicator` | `caching` | Always `up` |
-| `platform-queue` | `@breadstone/archipel-platform-queue/health` | `QueueHealthIndicator` | `queue` | Always `up` |
-| `platform-payments` | `@breadstone/archipel-platform-payments/health` | `PaymentHealthIndicator` | `payment` | Calls `PaymentClientPort.ping()` to verify provider connectivity |
-| `platform-esigning` | `@breadstone/archipel-platform-esigning/health` | `EsigningHealthIndicator` | `esigning` | Calls `EsigningClientPort.ping()` to verify provider connectivity, reports `providerId` |
-| `platform-intelligence` | `@breadstone/archipel-platform-intelligence/health` | `IntelligenceHealthIndicator` | `intelligence` | Resolves text configuration and reports registered realtime providers plus active session count |
-| `platform-analytics` | `@breadstone/archipel-platform-analytics/health` | `AnalyticsHealthIndicator` | `analytics` | Calls `AnalyticsClientPort.ping()` to verify provider readiness |
-| `platform-telemetry` | `@breadstone/archipel-platform-telemetry/health` | `TelemetryHealthIndicator` | `telemetry` | Checks `OtelSdkHolder.isInitialized` for SDK presence |
-| `platform-authentication` | `@breadstone/archipel-platform-authentication/health` | `AuthenticationHealthIndicator` | `authentication` | Always `up` |
-| `platform-mcp` | `@breadstone/archipel-platform-mcp/health` | `McpHealthIndicator` | `mcp` | Checks tool/resource/prompt registry counts, reports breakdown |
+| Library                   | Subpath Import                                        | Class                           | Key              | Check Behavior                                                                          |
+| ------------------------- | ----------------------------------------------------- | ------------------------------- | ---------------- | --------------------------------------------------------------------------------------- |
+| `platform-database`       | `@breadstone/archipel-platform-database/health`       | `DatabaseHealthIndicator`       | `database`       | Prisma `SELECT 1` ping                                                                  |
+| `platform-blob-storage`   | `@breadstone/archipel-platform-blob-storage/health`   | `BlobHealthIndicator`           | `blob`           | HTTP ping to blob URL (or `disabled` if unconfigured)                                   |
+| `platform-mailing`        | `@breadstone/archipel-platform-mailing/health`        | `MailHealthIndicator`           | `mail`           | Validates mail host, user, and port config                                              |
+| `platform-caching`        | `@breadstone/archipel-platform-caching/health`        | `CachingHealthIndicator`        | `caching`        | Always `up`                                                                             |
+| `platform-queue`          | `@breadstone/archipel-platform-queue/health`          | `QueueHealthIndicator`          | `queue`          | Always `up`                                                                             |
+| `platform-payments`       | `@breadstone/archipel-platform-payments/health`       | `PaymentHealthIndicator`        | `payment`        | Calls `PaymentClientPort.ping()` to verify provider connectivity                        |
+| `platform-esigning`       | `@breadstone/archipel-platform-esigning/health`       | `EsigningHealthIndicator`       | `esigning`       | Calls `EsigningClientPort.ping()` to verify provider connectivity, reports `providerId` |
+| `platform-intelligence`   | `@breadstone/archipel-platform-intelligence/health`   | `IntelligenceHealthIndicator`   | `intelligence`   | Runs a bounded provider probe and reports capability plus realtime state                |
+| `platform-analytics`      | `@breadstone/archipel-platform-analytics/health`      | `AnalyticsHealthIndicator`      | `analytics`      | Calls `AnalyticsClientPort.ping()` to verify provider readiness                         |
+| `platform-telemetry`      | `@breadstone/archipel-platform-telemetry/health`      | `TelemetryHealthIndicator`      | `telemetry`      | Checks `OtelSdkHolder.isInitialized` for SDK presence                                   |
+| `platform-authentication` | `@breadstone/archipel-platform-authentication/health` | `AuthenticationHealthIndicator` | `authentication` | Always `up`                                                                             |
+| `platform-mcp`            | `@breadstone/archipel-platform-mcp/health`            | `McpHealthIndicator`            | `mcp`            | Checks tool/resource/prompt registry counts, reports breakdown                          |
 
 ### Indicator Categories
 
 **Active checks** — perform a real probe:
+
 - `DatabaseHealthIndicator` — executes a SQL ping
 - `BlobHealthIndicator` — sends an HTTP request to the blob URL
 - `MailHealthIndicator` — validates configuration values
 - `PaymentHealthIndicator` — calls `PaymentClientPort.ping()` (adapters can override for real API calls)
 - `EsigningHealthIndicator` — calls `EsigningClientPort.ping()` (adapters can override for real API calls)
+- `IntelligenceHealthIndicator` — probes the default language provider with an independent three-second timeout
 - `AnalyticsHealthIndicator` — calls `AnalyticsClientPort.ping()` (adapters can override for SDK readiness checks)
 
 **State checks** — inspect in-memory state (zero-cost, no I/O):
-- `IntelligenceHealthIndicator` — resolves configured provider/model data and reports process-local realtime provider and session state
+
 - `TelemetryHealthIndicator` — checks whether the OpenTelemetry SDK has been initialized
 - `McpHealthIndicator` — verifies at least one tool/resource/prompt handler is registered
 
 **Stub checks** — always report `up`:
+
 - `CachingHealthIndicator`, `QueueHealthIndicator`, `AuthenticationHealthIndicator`
 
 ## Quick Start
@@ -111,15 +114,10 @@ import { PaymentHealthIndicator } from '@breadstone/archipel-platform-payments/h
 import { CachingHealthIndicator } from '@breadstone/archipel-platform-caching/health';
 
 @Module({
-  imports: [
-    // ... your feature modules
-    HealthModule.withIndicators([
-      DatabaseHealthIndicator,
-      MailHealthIndicator,
-      PaymentHealthIndicator,
-      CachingHealthIndicator,
-    ]),
-  ],
+    imports: [
+        // ... your feature modules
+        HealthModule.withIndicators([DatabaseHealthIndicator, MailHealthIndicator, PaymentHealthIndicator, CachingHealthIndicator]),
+    ],
 })
 export class AppModule {}
 ```
@@ -134,12 +132,12 @@ import { HealthOrchestrator } from '@breadstone/archipel-platform-health';
 
 @Controller('health')
 export class HealthController {
-  constructor(private readonly _health: HealthOrchestrator) {}
+    constructor(private readonly _health: HealthOrchestrator) {}
 
-  @Get()
-  public async check() {
-    return this._health.check();
-  }
+    @Get()
+    public async check() {
+        return this._health.check();
+    }
 }
 ```
 
@@ -147,25 +145,27 @@ export class HealthController {
 
 ```json
 {
-  "status": "ok",
-  "details": {
-    "database": { "status": "up" },
-    "mail": { "status": "up" },
-    "payment": { "status": "up" },
-    "caching": { "status": "up" },
-    "intelligence": {
-      "status": "up",
-      "provider": "openai",
-      "model": "gpt-4o-mini",
-      "realtime": {
-        "enabled": true,
-        "providers": ["openai", "google"],
-        "activeSessions": 2
-      }
-    },
-    "mcp": { "status": "up", "tools": 5, "resources": 2, "prompts": 1 },
-    "telemetry": { "status": "up", "sdkInitialized": true }
-  }
+    "status": "ok",
+    "details": {
+        "database": { "status": "up" },
+        "mail": { "status": "up" },
+        "payment": { "status": "up" },
+        "caching": { "status": "up" },
+        "intelligence": {
+            "status": "up",
+            "providerStatus": "operational",
+            "provider": "openai",
+            "model": "gpt-5.4-mini",
+            "failureCode": null,
+            "realtime": {
+                "enabled": true,
+                "providers": ["openai", "google"],
+                "activeSessions": 2
+            }
+        },
+        "mcp": { "status": "up", "tools": 5, "resources": 2, "prompts": 1 },
+        "telemetry": { "status": "up", "sdkInitialized": true }
+    }
 }
 ```
 
@@ -173,15 +173,19 @@ When a provider is not registered (e.g., no `PaymentClientPort` injected), the i
 
 ```json
 {
-  "payment": { "status": "up", "disabled": true }
+    "payment": { "status": "up", "disabled": true }
 }
 ```
 
-When a ping fails, the indicator reports `down` with error details:
+When an intelligence probe fails unexpectedly, the indicator reports a stable
+failure code without leaking provider transport details:
 
 ```json
 {
-  "payment": { "status": "down", "error": "ECONNREFUSED" }
+    "intelligence": {
+        "status": "down",
+        "failureCode": "INTELLIGENCE_HEALTH_CHECK_FAILED"
+    }
 }
 ```
 
@@ -196,21 +200,18 @@ import type { HealthIndicatorResult } from '@nestjs/terminus';
 
 @Injectable()
 export class SearchHealthIndicator implements IHealthIndicator {
-  public readonly key = 'search';
+    public readonly key = 'search';
 
-  public check(): HealthIndicatorResult<'search'> {
-    return { search: { status: 'up' } };
-  }
+    public check(): HealthIndicatorResult<'search'> {
+        return { search: { status: 'up' } };
+    }
 }
 ```
 
 Register it alongside built-in indicators:
 
 ```typescript
-HealthModule.withIndicators([
-  DatabaseHealthIndicator,
-  SearchHealthIndicator,
-]);
+HealthModule.withIndicators([DatabaseHealthIndicator, SearchHealthIndicator]);
 ```
 
 ## Tree-Shaking
@@ -221,9 +222,9 @@ Health indicators are **not** included in the main library entry point. They are
 
 Each health indicator requires these optional peer dependencies:
 
-| Package | Notes |
-| ------- | ----- |
+| Package                                | Notes                                           |
+| -------------------------------------- | ----------------------------------------------- |
 | `@breadstone/archipel-platform-health` | `IHealthIndicator` interface and `HealthModule` |
-| `@nestjs/terminus` | `HealthIndicatorResult` type |
+| `@nestjs/terminus`                     | `HealthIndicatorResult` type                    |
 
 Both are listed as optional peer dependencies in each library's `package.json`.

package/data/guides/index.md

@@ -61,7 +61,8 @@ Practical guides for working with Archipel packages in your NestJS application.
 | Guide                                    | What you'll learn                                                                                               |
 | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
 | [Intelligence Prompts Warm-up](./intelligence-prompts-warm-up) | Define, bind, execute, validate, and test reusable text and structured prompts.                              |
-| [AI Text Generation](./ai-text-generation) | Multi-provider text completions, streaming, native AI SDK tools, and per-request model options.                   |
+| [AI Language Generation](./ai-text-generation) | Provider-neutral text, structured output, streaming, tools, agents, and per-request model policy.              |
+| [AI Image Generation](./ai-image-generation) | Provider-neutral image generation with tree-shakable provider model loaders.                                   |
 | [AI Realtime Voice](./ai-realtime-voice) | Server-owned live audio/text sessions, interaction modes, durable streaming, metering, and explicit recovery. |
 | [MCP Server](./mcp-server)               | Build MCP servers with tools, resources, and prompts for AI agent integration.                                |