@breadstone/archipel-mcp 0.0.54 → 0.0.56

package/data/packages/platform-intelligence/index.md

@@ -1,627 +1,86 @@
 ---
-title: platform-intelligence
-description: Multi-provider AI text generation, streaming, realtime voice, metering, and tool calling.
-order: 16
-tags: [intelligence, ai, openai, anthropic, google, grok, text-generation, streaming, realtime, voice, metering, tool-calling, health]
-package: '@breadstone/archipel-platform-intelligence'
+title: Platform Intelligence
+description: Provider-neutral language, embedding, image, speech, transcription, video, reranking, realtime, agent, file, and skill infrastructure for NestJS.
 ---
 
-# platform-intelligence
-
-Multi-provider AI library supporting text generation and server-owned realtime voice sessions through OpenAI, Anthropic, Google Generative AI, and Grok. Tool orchestration is delegated to the AI SDK through native and provider-defined tool definitions, `toolChoice`, `activeTools`, and `stopWhen`. Advanced use cases can pass native AI SDK prompts, request-level models, provider options, headers, telemetry, output settings, and step hooks through the platform generator.
-
-**Package:** `@breadstone/archipel-platform-intelligence`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Reusable Prompts
-
-Use `intelligencePrompt()` to keep a prompt's identity, version, schemas,
-instructions, messages, and execution requirements in one pure definition.
-Bind already prepared feature data with `.with(...)` and execute the resulting
-invocation through the NestJS `IntelligencePromptExecutor`.
-
-For a guided first implementation, see
-[Intelligence Prompts Warm-up](/guides/intelligence-prompts-warm-up).
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { z } from 'zod';
-import {
-  intelligencePrompt,
-  IntelligencePromptExecutor,
-} from '@breadstone/archipel-platform-intelligence';
-
-const DuplicateDetectionPrompt = intelligencePrompt({
-  name: 'crm.duplicate-detection',
-  version: 1,
-  mode: 'object',
-  inputSchema: z.object({
-    sourceId: z.number().int(),
-    candidateIds: z.array(z.number().int()),
-  }),
-  outputSchema: z.object({
-    scores: z.array(z.object({
-      id: z.number().int(),
-      score: z.number().min(0).max(100),
-    })),
-  }),
-  system: () => [
-    'Score duplicate candidates using only the supplied fields.',
-    'Do not infer facts from missing data.',
-  ],
-  messages: ({ input }) => [
-    { role: 'user', content: JSON.stringify(input) },
-  ],
-  execution: {
-    options: { temperature: 0, maxOutputTokens: 800 },
-    model: { strategy: 'automatic' },
-    requiredCapabilities: ['structuredOutput'],
-  },
-});
-
-export function duplicateDetectionPrompt(sourceId: number, candidateIds: ReadonlyArray<number>) {
-  return DuplicateDetectionPrompt.with({ sourceId, candidateIds });
-}
-
-@Injectable()
-export class DuplicateDetectionService {
-  public constructor(private readonly prompts: IntelligencePromptExecutor) {}
-
-  public async score(sourceId: number, candidateIds: ReadonlyArray<number>) {
-    const execution = await this.prompts.execute(
-      duplicateDetectionPrompt(sourceId, candidateIds),
-    );
-
-    return execution.output.scores;
-  }
-}
+# Platform Intelligence
+
+Applications depend on Archipel capability facades and register only the
+provider subpaths they use. Provider SDKs, ESM loading, model construction,
+timeouts, retries, and error normalization stay inside the package.
+
+```mermaid
+flowchart LR
+  App["Application services"] --> Facades["Archipel capability facades"]
+  Facades --> Registry["Provider registry"]
+  Registry --> Port["IntelligenceProviderAdapterPort"]
+  Port --> OpenAI["/provider/openai"]
+  Port --> Anthropic["/provider/anthropic"]
+  Port --> Google["/provider/google"]
+  Port --> Grok["/provider/grok"]
+  Port --> MiMo["/provider/mimo"]
+  Port --> Gateway["/provider/gateway"]
 ```
 
-The schemas use the AI SDK `FlexibleSchema` contract. Object mode requires an
-output schema and uses AI SDK 7 `Output.object()`; text mode has no output
-schema and returns a string. Input and completed object output are validated at
-runtime.
-
-Native AI SDK settings work with the default policy. Applications that declare
-provider-neutral quality, reasoning, latency, preferred models, or fixed model
-identifiers register an `IntelligencePromptPolicyPort` adapter through
-`IntelligenceModule.register({ promptPolicyAdapter })`. Execution results
-contain requested and effective policy, provider, model, usage, reasoning, and
-invocation metadata for application-owned billing and auditing.
-
----
-
-## Realtime Voice
-
-Archipel owns the upstream provider WebSocket and exposes normalized audio,
-text, transcription, response, and tool events through
-`IntelligenceRealtimeSessionPort`. The consuming backend can place its normal
-authentication, authorization, tenant isolation, persistence, and client
-WebSocket in front of this port. Provider credentials and short-lived tokens
-never need to reach the browser.
-
-The complete application integration is documented in
-[AI Realtime Voice](/guides/ai-realtime-voice); the reusable ownership,
-durability, and recovery rules are documented in the
-[Realtime Session Pattern](/patterns/realtime-session-pattern).
-
-The implementation uses the experimental realtime model contract in Vercel AI
-SDK 7. OpenAI, Google, and xAI are loaded through Archipel provider subpaths;
-consuming applications do not import the official OpenAI SDK or make direct
-provider calls.
-
-```typescript
-import { Injectable, Module } from '@nestjs/common';
-import {
-  IntelligenceModule,
-  IntelligenceProviderNames,
-} from '@breadstone/archipel-platform-intelligence';
-import {
-  IntelligenceRealtimeMeteringPort,
-  IntelligenceRealtimeSessionFactory,
-  type IntelligenceRealtimeMeteringEvent,
-} from '@breadstone/archipel-platform-intelligence/realtime';
-import { loadOpenAIRealtimeModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import { loadGoogleRealtimeModel } from '@breadstone/archipel-platform-intelligence/providers/google';
-import { loadGrokRealtimeModel } from '@breadstone/archipel-platform-intelligence/providers/grok';
-
-@Injectable()
-export class RealtimeMeteringAdapter extends IntelligenceRealtimeMeteringPort {
-  public async report(event: IntelligenceRealtimeMeteringEvent): Promise<void> {
-    await persistIdempotently(event.eventId, event);
-  }
-}
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      validateOnModuleInit: false,
-      realtime: {
-        providerLoaders: {
-          [IntelligenceProviderNames.OpenAI]: loadOpenAIRealtimeModel,
-          [IntelligenceProviderNames.Google]: loadGoogleRealtimeModel,
-          [IntelligenceProviderNames.Grok]: loadGrokRealtimeModel,
-        },
-        meteringAdapter: RealtimeMeteringAdapter,
-        meteringIntervalMs: 30_000,
-      },
-    }),
-  ],
-})
-export class RealtimeModule {}
-
-@Injectable()
-export class RealtimeConsultationService {
-  public constructor(private readonly sessions: IntelligenceRealtimeSessionFactory) {}
-
-  public async open(consultationId: string): Promise<void> {
-    const session = await this.sessions.createSession({
-      sessionId: consultationId,
-      model: 'gpt-realtime',
-      sessionConfiguration: {
-        instructions: 'Transcribe the consultation and answer concisely.',
-        inputAudioFormat: { type: 'audio/pcm', rate: 24_000 },
-        inputAudioTranscription: {},
-        outputModalities: ['text', 'audio'],
-        turnDetection: { type: 'server-vad' },
-      },
-      onEvent: forwardToAuthenticatedClient,
-    });
-
-    await session.connect();
-  }
-}
-```
-
-| Provider | Archipel loader | Example model |
-| --- | --- | --- |
-| OpenAI | `loadOpenAIRealtimeModel` | `gpt-realtime` |
-| Google | `loadGoogleRealtimeModel` | `gemini-3.1-flash-live-preview` |
-| xAI / Grok | `loadGrokRealtimeModel` | `grok-voice-latest` |
-
-### Metering and audit
-
-The application-supplied `IntelligenceRealtimeMeteringPort` receives four
-idempotently identifiable event types:
-
-| Event | Meaning |
-| --- | --- |
-| `session-started` | One upstream provider connection opened |
-| `billing-interval` | Elapsed provider-independent usage, every 30 seconds by default and once more for the final partial interval |
-| `provider-usage` | Exact token and modality counts when present in the raw provider event |
-| `session-ended` | Connection duration and close reason |
-
-An application can debit its own token ledger and append its AI audit log in
-the same transaction keyed by `eventId`. Time-based charging remains available
-when a provider omits exact usage; exact token usage remains available for cost
-reconciliation when reported.
-
-### Failure and persistence rules
-
-- Provider token requests and WebSocket setup are capped at five seconds and
-  transient token creation is retried at most twice.
-- Inbound, outbound, metering, and WebSocket buffers are bounded.
-- Normalized events preserve provider wire order.
-- Nest shutdown closes all owned sessions and flushes metering.
-- Archipel does not silently reconnect a lost provider conversation because a
-  new connection has different conversational state.
-- The consuming application must persist audio chunks and transcript progress
-  durably before acknowledging them, then reconstruct context when it opens a
-  replacement provider session.
-
----
-
-## Provider Subpaths
-
-Import only the providers you need:
-
-| Provider  | Subpath                                                          |
-| --------- | ---------------------------------------------------------------- |
-| OpenAI    | `@breadstone/archipel-platform-intelligence/providers/openai`    |
-| Anthropic | `@breadstone/archipel-platform-intelligence/providers/anthropic` |
-| Google    | `@breadstone/archipel-platform-intelligence/providers/google`    |
-| Grok      | `@breadstone/archipel-platform-intelligence/providers/grok`      |
-
-Provider-native tool wrappers are exported through matching `/tools` subpaths, for example `@breadstone/archipel-platform-intelligence/providers/grok/tools`.
-
----
-
-## Tool Registration
-
-Tools can be normal Nest providers or direct `IIntelligenceTool` instances. Register classes for custom application tools, or register provider-native wrappers from provider subpaths.
-
-```typescript
-import { Injectable, Module } from '@nestjs/common';
-import { tool, type Tool } from 'ai';
-import { z } from 'zod';
-import { IntelligenceModule, IntelligenceProviderNames, IntelligenceToolBase } from '@breadstone/archipel-platform-intelligence';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-
-interface ICustomerSearchInput {
-  readonly query: string;
-}
-
-interface ICustomerSearchOutput {
-  readonly customers: ReadonlyArray<string>;
-}
-
-@Injectable()
-export class CustomerSearchTool extends IntelligenceToolBase<ICustomerSearchInput, ICustomerSearchOutput> {
-  public override get name(): string {
-    return 'searchCustomers';
-  }
-
-  public override get tool(): Tool<ICustomerSearchInput, ICustomerSearchOutput> {
-    return tool({
-      description: 'Searches customers by name, email, or company.',
-      inputSchema: z.object({
-        query: z.string().describe('Customer search query'),
-      }),
-      execute: async (input) => ({ customers: [input.query] }),
-    });
-  }
-}
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [CustomerSearchTool],
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### Provider-Native Tools
-
-Provider SDKs expose built-in tools such as web search, file search, code execution, and URL context. Archipel exports wrappers from provider subpaths so each tool is compatible with `IIntelligenceTool` without importing unused provider SDKs from the root entry.
-
-```typescript
-import { Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import { createOpenAIWebSearchTool } from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [createOpenAIWebSearchTool({ searchContextSize: 'medium' })],
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-Provider-native wrappers cover OpenAI web search, file search, code interpreter, image generation, shell, MCP, and tool search; Google Search, Enterprise Web Search, URL Context, Code Execution, File Search, Maps, and Vertex RAG Store; versioned Anthropic web search, web fetch, code execution, bash, text editor, computer, memory, tool search, and advisor tools; and Grok web search, X search, file search, code execution, MCP, image understanding, and X-video understanding.
-
-The detailed AI text generation guide includes OpenAI recipes for spreadsheet analysis with Code Interpreter, image generation with generated files, deferred tool loading via Tool Search, and grammar-constrained custom tools. In the currently installed OpenAI SDK, `customTool()` constrains provider output but does not run a local `execute` callback; use a normal `tool()` when local execution is required.
-
-### Native AI SDK Passthrough
-
-`generateText()` and `streamText()` accept native AI SDK `Prompt` objects directly. The options intentionally extend the native AI SDK call options, so provider-specific features can flow through even when Archipel has no dedicated wrapper for them.
-
-The configured platform model is used by default. For exact AI SDK model factories, pass `model` per request. When every call provides a native model, set `validateOnModuleInit: false` to skip startup validation of platform provider configuration.
-
-```typescript
-import { openai } from '@ai-sdk/openai';
-import { Injectable, Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      validateOnModuleInit: false,
-    }),
-  ],
-})
-export class RawAiSdkModule {}
-
-@Injectable()
-export class RawAiSdkRecipeService {
-  public constructor(private readonly _textGenerator: IntelligenceTextGenerator) {}
-
-  public async answerWithNativeOptions(): Promise<string> {
-    const completion = await this._textGenerator.generateText(
-      {
-        system: 'Answer concisely and include assumptions.',
-        prompt: 'Compare the operational risks of outdoor work tomorrow.',
-      },
-      {
-        model: openai.responses('gpt-5'),
-        headers: { 'x-use-case': 'outdoor-risk' },
-        providerOptions: {
-          openai: {
-            reasoningEffort: 'medium',
-          },
-        },
-        seed: 42,
-      },
-    );
-
-    return completion.text;
-  }
-}
-```
-
-### Outdoor Order Weather Risk Example
-
-Use a class-based application tool for tenant data and a provider-native web search tool for current weather context. Set `INTELLIGENCE_PROVIDER=openai` and `INTELLIGENCE_MODEL=gpt-5` in configuration when this flow should use GPT-5.
-
-```typescript
-import { Injectable, Module } from '@nestjs/common';
-import { stepCountIs, tool, type Tool } from 'ai';
-import { z } from 'zod';
-import {
-  IntelligenceModule,
-  IntelligenceProviderNames,
-  IntelligenceTextGenerator,
-  IntelligenceToolBase,
-  type IIntelligenceTextCompletion,
-} from '@breadstone/archipel-platform-intelligence';
-import { OpenAIIntelligenceToolNames, loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import { createOpenAIWebSearchTool } from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
-
-interface IOutdoorOrderLookupInput {
-  readonly date: string;
-}
-
-interface IOutdoorOrderLookupOutput {
-  readonly date: string;
-  readonly orders: ReadonlyArray<{
-    readonly id: string;
-    readonly location: string;
-    readonly scheduledAt: string;
-    readonly outdoorWork: boolean;
-  }>;
-}
-
-@Injectable()
-export class OutdoorOrdersTool extends IntelligenceToolBase<IOutdoorOrderLookupInput, IOutdoorOrderLookupOutput> {
-  public override get name(): string {
-    return 'get_outdoor_orders';
-  }
-
-  public override get tool(): Tool<IOutdoorOrderLookupInput, IOutdoorOrderLookupOutput> {
-    return tool({
-      description: 'Returns outdoor field orders for the current tenant and date.',
-      inputSchema: z.object({
-        date: z.string().describe('Date in YYYY-MM-DD format'),
-      }),
-      execute: async (input: IOutdoorOrderLookupInput) => ({
-        date: input.date,
-        orders: [
-          {
-            id: 'ord_4711',
-            location: 'Berlin',
-            scheduledAt: `${input.date}T08:00:00+02:00`,
-            outdoorWork: true,
-          },
-        ],
-      }),
-    });
-  }
-}
-
-@Injectable()
-export class OutdoorOrderRiskAnalysisService {
-  public constructor(private readonly _textGenerator: IntelligenceTextGenerator) {}
-
-  public async analyseOutdoorOrders(date: string): Promise<{ readonly text: string; readonly sources: IIntelligenceTextCompletion['sources'] }> {
-    const result = await this._textGenerator.generateText(
-      {
-        system: 'You assess weather-related risks for tenant outdoor field orders.',
-        messages: [{ role: 'user', content: `Review outdoor field orders for ${date} and flag weather-related risks.` }],
-      },
-      {
-        toolChoice: 'auto',
-        activeTools: ['get_outdoor_orders', OpenAIIntelligenceToolNames.WebSearch],
-        stopWhen: stepCountIs(3),
-      },
-    );
-
-    return {
-      text: result.text,
-      sources: result.sources,
-    };
-  }
-}
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [
-        OutdoorOrdersTool,
-        createOpenAIWebSearchTool({
-          externalWebAccess: true,
-          searchContextSize: 'medium',
-          filters: { allowedDomains: ['dwd.de'] },
-        }),
-      ],
-    }),
-  ],
-  providers: [OutdoorOrderRiskAnalysisService],
-})
-export class OutdoorOrderRiskAnalysisModule {}
-```
-
----
-
-## Text Generation
-
-Inject `IntelligenceTextGenerator` and call `generateText()`:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import type { Prompt } from 'ai';
-import { IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';
-
-@Injectable()
-export class SummaryService {
-  constructor(private readonly _textGenerator: IntelligenceTextGenerator) {}
-
-  async summarize(content: string): Promise<string> {
-    const prompt: Prompt = {
-      system: 'You are a concise summarizer.',
-      messages: [{ role: 'user', content }],
-    };
-
-    const result = await this._textGenerator.generateText(prompt, {
-      temperature: 0.3,
-      toolChoice: 'auto',
-    });
-
-    return result.text;
-  }
-}
-```
-
----
-
-## Streaming
-`streamText()` uses the same registered tools and returns the native AI SDK stream result.
-
-```typescript
-const stream = await this._textGenerator.streamText(prompt, {
-  activeTools: ['searchCustomers'],
-  stopWhen: stepCountIs(3),
-});
-
-return stream.toUIMessageStreamResponse();
-```
-
----
-
-## Environment Variables
-
-| Variable                         | Description                  | Required           |
-| -------------------------------- | ---------------------------- | ------------------ |
-| `OPENAI_API_KEY`                 | OpenAI API key               | If using OpenAI    |
-| `ANTHROPIC_API_KEY`              | Anthropic API key            | If using Anthropic |
-| `GOOGLE_API_KEY`                 | Google Generative AI API key | If using Google    |
-| `GROK_API_KEY`                   | Grok / xAI API key           | If using Grok      |
-
----
-
-## Timeout & Retry
-
-All `generateText()` calls include built-in resilience:
-
-| Setting     | Default  | Description                                              |
-| ----------- | -------- | -------------------------------------------------------- |
-| `timeoutMs` | `30000`  | Abort the provider request after this many milliseconds  |
-| Max retries | `2`      | Retryable errors are retried with exponential backoff    |
-| Backoff     | 1s → 4s  | Exponential with a 4-second cap                          |
-
-Override the timeout per call via the options parameter:
-
-```typescript
-const result = await this._textGenerator.generateText(prompt, {
-  timeoutMs: 15_000,
-});
-```
-
-All errors are wrapped in `IntelligenceProviderError` with `provider`, `model`, and `retryable` metadata.
-
----
-
-## Error Handling
-
-The library provides domain error classes for different failure scenarios:
-
-| Error class                        | Code                          | When thrown                                                           |
-| ---------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
-| `IntelligenceProviderError`        | `INTELLIGENCE_PROVIDER`       | Provider SDK failures during text generation                          |
-| `IntelligenceRealtimeError`        | Realtime phase metadata       | Configuration, token, connect, send, receive, metering, or close failures |
-| `IntelligenceValidationError`      | `INTELLIGENCE_VALIDATION`     | Invalid generation parameters (temperature, topP, maxOutputTokens)    |
-| `IntelligenceConfigurationError`   | `INTELLIGENCE_CONFIGURATION`  | Unsupported provider, missing API key, or missing provider loader     |
-
-```typescript
-import {
-  IntelligenceProviderError,
-  IntelligenceValidationError,
-  IntelligenceConfigurationError,
-} from '@breadstone/archipel-platform-intelligence';
-```
-
----
-
-## Lifecycle
-
-`IntelligenceTextGenerator` implements `OnModuleInit` and validates the provider configuration plus registered provider loader eagerly at startup. Missing API keys, unsupported providers, or missing loaders throw `IntelligenceConfigurationError` before the first request is processed. `IntelligenceRealtimeSessionFactory` implements `OnModuleDestroy`, closes all owned provider WebSockets, and flushes queued metering on shutdown.
-
-Set `validateOnModuleInit: false` for a realtime-only module because that option
-controls eager text-model initialization. When text and realtime are both
-used, register the language-model loaders and keep the default eager
-validation.
-
----
-
-## Tool Registry Limits
-
-`IntelligenceToolRegistry` enforces a maximum of **128** registered tools. Attempts to register beyond this limit throw `IntelligenceValidationError` to prevent unbounded memory growth.
-
----
-
-## Health Check
-
-The `IntelligenceHealthIndicator` verifies that provider configuration can be resolved and reports registered realtime providers plus active session count. If neither text nor realtime infrastructure is available, it reports `disabled: true`. Import it from the `/health` subpath:
-
-```typescript
-import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
-import { IntelligenceHealthIndicator } from '@breadstone/archipel-platform-intelligence/health';
-import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-    }),
-    HealthModule.withIndicators([IntelligenceHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `intelligence` | `up` when provider configuration resolves, else `down`; includes realtime readiness when registered | `@Optional() IntelligenceTextGenerator`, `@Optional() IntelligenceRealtimeSessionFactory` |
-
----
-
-## API Reference
-
-See the full [API documentation](./api/) for all exported types, interfaces, and classes.
+## Providers
+
+| Provider          | Import subpath         | Configuration entries       |
+| ----------------- | ---------------------- | --------------------------- |
+| OpenAI            | `/provider/openai`     | `OPENAI_CONFIG_ENTRIES`     |
+| Anthropic         | `/provider/anthropic`  | `ANTHROPIC_CONFIG_ENTRIES`  |
+| Google            | `/provider/google`     | `GOOGLE_CONFIG_ENTRIES`     |
+| xAI / Grok        | `/provider/grok`       | `GROK_CONFIG_ENTRIES`       |
+| Xiaomi MiMo       | `/provider/mimo`       | `MIMO_CONFIG_ENTRIES`       |
+| Vercel AI Gateway | `/provider/gateway`    | `AI_GATEWAY_CONFIG_ENTRIES` |
+
+OpenAI, Anthropic, Google, Grok, and MiMo also expose provider-owned tools from
+their `/tools` subpaths. Provider-specific environment keys are exported only
+from the corresponding provider entrypoint; the package root stays
+provider-neutral. Provider entrypoints do not re-export tool factories, so
+provider tools remain a separate opt-in runtime boundary.
+
+The standard package test target first runs the Nx package build and then the
+provider-entrypoint and generator-topology contract tests. The build compiles
+every declared subpath, while the tests keep package exports, TypeScript paths,
+provider-local barrels, optional provider dependencies, and the
+provider-neutral root surface synchronized.
+
+## Capability Surface
+
+| Surface                              | Responsibility                                 |
+| ------------------------------------ | ---------------------------------------------- |
+| `IntelligenceLanguageGenerator`      | Text, structured output, streams, and tools    |
+| `IntelligenceEmbeddingGenerator`     | Single and batch embeddings                    |
+| `IntelligenceImageGenerator`         | Image generation and editing                   |
+| `IntelligenceSpeechGenerator`        | Text-to-speech generation                      |
+| `IntelligenceTranscriptionGenerator` | Bounded and live transcription                 |
+| `IntelligenceVideoGenerator`         | Text/image-to-video generation                 |
+| `IntelligenceReranker`               | Provider-neutral semantic ranking              |
+| `IntelligenceRealtimeSessionFactory` | Server-owned bidirectional audio/text sessions |
+| `IntelligenceAgentFactory`           | Bounded reusable tool-loop agents              |
+| `IntelligenceProviderAssetUploader`  | Provider files and skills                      |
+| `IntelligenceProviderDiagnostics`    | Bounded provider/model probes                  |
+
+## Normalized Usage
+
+Capability results use `IIntelligenceUsage` to transport provider-reported
+input, output, total, cache-read, cache-write, reasoning, and text/image/audio
+modality counters. Missing counters are `null`, not zero. Image generation
+reconciles the normalized result with provider metadata so text input, image
+input, and generated image output remain separately accountable when the
+provider exposes them.
+
+Archipel deliberately does not assign monetary prices or application billing
+units. Consumers persist and price the normalized usage according to their own
+provider, model, currency, entitlement, and audit policies.
+
+OpenAI video uses an internal asynchronous create/poll/download bridge because
+the OpenAI AI SDK provider does not expose a video-model handle. The bridge is
+owned by `/provider/openai`; applications continue to use the provider-neutral
+`IntelligenceVideoGenerator` contract. The current OpenAI Videos API and Sora
+2 models are scheduled to shut down on September 24, 2026, so their eventual
+replacement remains isolated to that provider entry point.
+
+See the [package README](https://github.com/RueDeRennes/archipel/tree/main/libs/platform-intelligence)
+for registration and migration examples and the generated API pages for
+contract details.