npm - @breadstone/archipel-mcp - Versions diffs - 0.0.54 → 0.0.55 - Mend

@breadstone/archipel-mcp 0.0.54 → 0.0.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (208) hide show

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

@@ -1,687 +1,156 @@
 ---
-title: AI Text Generation
-description: Generate text completions with multi-provider support for OpenAI, Anthropic, Google Gemini, and Grok using a unified configuration layer.
+title: AI Language Generation
+description: Generate text and structured output, stream results, use tools, and create agents without leaking provider SDKs.
 order: 15
 ---
-# AI Text Generation
+# AI Language Generation
-This guide covers text generation with `platform-intelligence`: choosing an AI provider, configuring the module, generating completions, streaming responses, and registering class-based or provider-native AI SDK tools.
+`IntelligenceLanguageGenerator` is the provider-neutral language facade. It
+owns plain text, schema-constrained objects, streaming, tool execution, result
+normalization, retries, cancellation, and timeouts.
-For versioned feature prompts with typed inputs, structured output schemas,
-execution policy, and a NestJS executor, start with
-[Intelligence Prompts Warm-up](./intelligence-prompts-warm-up).
-For server-owned, bidirectional audio and text connections, use the separate
-[AI Realtime Voice](./ai-realtime-voice) guide. Realtime sessions have a
-different transport, lifecycle, persistence, and metering model from request-
-or response-scoped text generation.
----
-## Installation
+Consumer applications depend only on Archipel:
 ```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/xai`       |
-```bash
-# Example: OpenAI
-yarn add @ai-sdk/openai
-# Example: Grok / xAI
-yarn add @ai-sdk/xai
-```
----
-## Module Registration
-Import `IntelligenceModule` into your application module. It exposes `IntelligenceTextGenerator` and `IntelligenceToolRegistry` as shared providers.
+## Registration
 ```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 {}
-```
-Register only the provider loaders you install. The root entry does not import provider SDK packages.
----
-## Configuration
-All intelligence settings are read from environment variables via `ConfigService`. No direct `process.env` access is needed.
-```dotenv
-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`              | xAI Grok API                       |
-Each provider resolves its API key and base URL from dedicated environment variables when the generic `INTELLIGENCE_API_KEY` is not set:
-```dotenv
-# Provider-specific keys (optional — fallback from INTELLIGENCE_API_KEY)
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_API_KEY=AI...
-GROK_API_KEY=xai-...
-```
----
-## Generating Text
-Inject `IntelligenceTextGenerator` to generate completions:
-```typescript
-import { Injectable } from '@nestjs/common';
-import type { Prompt } from 'ai';
-import { IntelligenceTextGenerator, type IIntelligenceTextCompletion } 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: Prompt = {
-      system: '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 uses the native AI SDK `Prompt` type. Use either a string prompt or a full message array:
-```typescript
-type Prompt =
-  | { readonly system?: string; readonly prompt: string }
-  | { readonly system?: string; readonly messages: Array<ModelMessage> };
-```
-### 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, provider-native sources, generated files, and optional token usage telemetry:
-```typescript
-interface IIntelligenceTextCompletion {
-  readonly text: string;
-  readonly provider: string;
-  readonly model: string;
-  readonly sources: ReadonlyArray<LanguageModelV3Source>;
-  readonly files: ReadonlyArray<GeneratedFile>;
-  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: Prompt = {
-  system: '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);
-```
----
-## Tool Registration
-The intelligence module uses native AI SDK tools. Define a class that exposes a `name` and a native `Tool`, or register provider-native tool 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 IWorkoutInput {
-  readonly goal: string;
-}
-interface IWorkoutOutput {
-  readonly recommendation: string;
-}
-@Injectable()
-export class WorkoutRecommendationTool extends IntelligenceToolBase<IWorkoutInput, IWorkoutOutput> {
-  public override get name(): string {
-    return 'recommendWorkout';
-  }
-  public override get tool(): Tool<IWorkoutInput, IWorkoutOutput> {
-    return tool({
-      description: 'Recommends a workout plan for a user goal.',
-      inputSchema: z.object({
-        goal: z.string().describe('The user fitness goal'),
-      }),
-      execute: async (input) => ({
-        recommendation: `Workout plan for ${input.goal}`,
-      }),
-    });
-  }
-}
+import {
+  IntelligenceCapabilityNames,
+  IntelligenceModule,
+  IntelligenceProviderNames,
+} from '@breadstone/archipel-platform-intelligence';
+import { AnthropicIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/anthropic';
+import { OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/openai';
 @Module({
   imports: [
     IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
+      providerAdapters: [
+        new OpenAIIntelligenceProviderAdapter(),
+        new AnthropicIntelligenceProviderAdapter(),
+      ],
+      defaultModels: {
+        [IntelligenceCapabilityNames.Language]: {
+          provider: IntelligenceProviderNames.OpenAI,
+          model: 'gpt-5.4-mini',
+        },
       },
-      tools: [WorkoutRecommendationTool],
     }),
   ],
 })
-export class WorkoutModule {}
+export class ApplicationModule {}
 ```
-Provider-defined AI SDK tools are available through tree-shakable provider subpaths. They return `IIntelligenceTool` instances and can be placed directly in the `tools` array:
+## Text and Objects
 ```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';
+const completion = await language.generateText(
+  {
+    system: 'Answer using the supplied application context only.',
+    prompt: 'Summarize the open tasks.',
+  },
+  {
+    maxOutputTokens: 800,
+    maxRetries: 2,
+  },
+);
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      providerLoaders: {
-        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
-      },
-      tools: [createOpenAIWebSearchTool({ searchContextSize: 'medium' })],
-    }),
-  ],
-})
-export class SearchModule {}
+const structured = await language.generateObject(
+  { prompt: 'Classify the customer request.' },
+  z.object({
+    category: z.enum(['billing', 'technical', 'other']),
+    urgency: z.enum(['low', 'normal', 'high']),
+  }),
+);
 ```
-OpenAI, Google, Anthropic, and Grok provider subpaths expose wrappers for their built-in web search, file search, code execution, URL context, shell, MCP, X search, image/video understanding, and versioned tool families where supported by the underlying SDK.
-### Native AI SDK Passthrough
+Applications can provide a model override as
+`{ provider: string, model: string }`. They never construct a provider-native
+model.
-Archipel is not intended to be a closed subset of the AI SDK. `IntelligenceTextGenerator.generateText()` and `streamText()` accept native AI SDK `Prompt` objects directly. Their options extend the native AI SDK call options, while Archipel still contributes provider configuration, registered tool merging, timeout defaults, logging, and normalized completion metadata.
-Use the native AI SDK prompt shape for prompt strings, multimodal `ModelMessage` arrays, system-message arrays, or other prompt forms supported by the AI SDK.
+## Streaming
 ```typescript
-import { openai } from '@ai-sdk/openai';
-import { Injectable, Module } from '@nestjs/common';
-import { IntelligenceModule, IntelligenceTextGenerator, type IIntelligenceTextCompletion } from '@breadstone/archipel-platform-intelligence';
-@Module({
-  imports: [
-    IntelligenceModule.register({
-      validateOnModuleInit: false,
-    }),
-  ],
-})
-export class RawAiSdkModule {}
-@Injectable()
-export class RawAiSdkRecipeService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-  public constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
+const stream = await language.streamText({ prompt: 'Explain the result.' });
-  public async generateWithNativeAiSdkOptions(): Promise<IIntelligenceTextCompletion> {
-    return 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,
-      },
-    );
-  }
+for await (const delta of stream.textStream) {
+  sendToAuthenticatedClient(delta);
 }
-```
-If every request passes a native AI SDK model, `validateOnModuleInit: false` avoids requiring platform provider configuration at startup. If no `model` option is supplied, the configured provider loader and `INTELLIGENCE_PROVIDER` / `INTELLIGENCE_MODEL` values still define the model.
-### Additional OpenAI Tool Recipes
-The same pattern works for other provider-defined OpenAI tools. Register the provider tool wrapper on the module when it is available to the whole use case, or pass request-specific tools through `generateText()` when the tool needs request data such as a `fileId`.
-```typescript
-import { Injectable } from '@nestjs/common';
-import { stepCountIs, tool } from 'ai';
-import { z } from 'zod';
-import { IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';
-import { OpenAIIntelligenceToolNames } from '@breadstone/archipel-platform-intelligence/providers/openai';
-import {
-  createOpenAICodeInterpreterTool,
-  createOpenAICustomTool,
-  createOpenAIImageGenerationTool,
-  createOpenAIToolSearchTool,
-} from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
-@Injectable()
-export class OpenAIToolRecipeService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-  public constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-  public async analyseSpreadsheet(fileId: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        system: 'You analyze uploaded spreadsheets and explain unusual values clearly.',
-        messages: [
-          {
-            role: 'user',
-            content: 'Analyze the file, detect unusual values, and summarize the most important findings as a table.',
-          },
-        ],
-      },
-      {
-        activeTools: [OpenAIIntelligenceToolNames.CodeInterpreter],
-        tools: {
-          [OpenAIIntelligenceToolNames.CodeInterpreter]: createOpenAICodeInterpreterTool({
-            container: { fileIds: [fileId] },
-          }).tool,
-        },
-      },
-    );
-  }
-  public async generateIllustration(description: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        prompt: description,
-      },
-      {
-        activeTools: [OpenAIIntelligenceToolNames.ImageGeneration],
-        tools: {
-          [OpenAIIntelligenceToolNames.ImageGeneration]: createOpenAIImageGenerationTool({
-            quality: 'medium',
-            size: '1024x1024',
-          }).tool,
-        },
-      },
-    );
-  }
-  public async answerWithDeferredTools(prompt: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        prompt: prompt,
-      },
-      {
-        stopWhen: stepCountIs(10),
-        tools: {
-          [OpenAIIntelligenceToolNames.ToolSearch]: createOpenAIToolSearchTool().tool,
-          get_birthdays: tool({
-            description: 'Returns employee birthdays in a date range.',
-            inputSchema: z.object({
-              from: z.string(),
-              to: z.string(),
-            }),
-            execute: async (input) => ({ from: input.from, to: input.to, employees: [] }),
-            providerOptions: {
-              openai: { deferLoading: true },
-            },
-          }),
-          search_orders: tool({
-            description: 'Searches orders using domain-specific filters.',
-            inputSchema: z.object({
-              query: z.string(),
-            }),
-            execute: async (input) => ({ query: input.query, orders: [] }),
-            providerOptions: {
-              openai: { deferLoading: true },
-            },
-          }),
-        },
-      },
-    );
-  }
-  public async createReadOnlyReportQuery(prompt: string): Promise<IIntelligenceTextCompletion> {
-    return this._textGenerator.generateText(
-      {
-        system: 'Create only read-only reporting queries. The query must start with SELECT.',
-        messages: [{ role: 'user', content: prompt }],
-      },
-      {
-        toolChoice: 'required',
-        stopWhen: stepCountIs(3),
-        activeTools: ['report_query'],
-        tools: {
-          report_query: createOpenAICustomTool({
-            name: 'report_query',
-            description: 'Create a strictly read-only reporting query.',
-            format: {
-              type: 'grammar',
-              syntax: 'regex',
-              definition: 'SELECT .+',
-            },
-          }).tool,
-        },
-      },
-    );
-  }
-}
+const finalText = await stream.text;
+const usage = await stream.usage;
 ```
-`generateIllustration()` can return generated images through `completion.files`, while web search results are exposed through `completion.sources`. The platform keeps the AI SDK tool objects intact, so provider-specific options such as `container.fileIds`, `deferLoading`, grammar formats, and image settings still pass through to OpenAI. With the currently installed OpenAI SDK, `customTool()` supports grammar-constrained provider output but not a local `execute` callback; run parser, allowlist, and tenant filtering before executing any generated query, or model that execution as a normal `tool()` when local execution is required.
-### Outdoor Order Weather Risk Example
+`streamObject()` exposes partial structured output and a validated final object.
+All stream iterables and result promises normalize provider failures as
+`IntelligenceProviderError`.
-This is the Archipel equivalent of using one application tool together with OpenAI web search. The model is selected through configuration, for example `INTELLIGENCE_PROVIDER=openai` and `INTELLIGENCE_MODEL=gpt-5`; the use case only depends on `IntelligenceTextGenerator`.
+## Application Tools
 ```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 IOutdoorOrder {
-  readonly id: string;
-  readonly location: string;
-  readonly scheduledAt: string;
-  readonly outdoorWork: boolean;
-}
-interface IOutdoorOrderLookupOutput {
-  readonly date: string;
-  readonly orders: ReadonlyArray<IOutdoorOrder>;
-}
-@Injectable()
-export class OutdoorOrdersTool extends IntelligenceToolBase<IOutdoorOrderLookupInput, IOutdoorOrderLookupOutput> {
+export class CustomerSearchTool extends IntelligenceToolBase<
+  ICustomerSearchInput,
+  ReadonlyArray<ICustomerSummary>
+> {
   public override get name(): string {
-    return 'get_outdoor_orders';
+    return 'customer_search';
   }
-  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'),
+  public override get tool() {
+    return defineIntelligenceTool({
+      description: 'Searches customers visible to the authenticated tenant.',
+      inputSchema: createIntelligenceJsonSchema<ICustomerSearchInput>({
+        type: 'object',
+        properties: { query: { type: 'string' } },
+        required: ['query'],
+        additionalProperties: false,
       }),
-      execute: async (input: IOutdoorOrderLookupInput) => this.loadOutdoorOrders(input.date),
+      execute: async ({ query }) => this._customers.search(query),
     });
   }
-  private async loadOutdoorOrders(date: string): Promise<IOutdoorOrderLookupOutput> {
-    return {
-      date: date,
-      orders: [
-        {
-          id: 'ord_4711',
-          location: 'Berlin',
-          scheduledAt: `${date}T08:00:00+02:00`,
-          outdoorWork: true,
-        },
-      ],
-    };
-  }
 }
-@Injectable()
-export class OutdoorOrderRiskAnalysisService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-  public constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-  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 {}
-```
-Use AI SDK request options to constrain tool use per call:
-```typescript
-const completion = await this._textGenerator.generateText(prompt, {
-  toolChoice: 'auto',
-  activeTools: ['recommendWorkout'],
-});
 ```
-> **Capacity limit:** The registry enforces a maximum of **128** registered tools.
+Register tools through `IntelligenceModule.register({ tools: [...] })`. Use
+`activeToolNames` to constrain a call and `maxSteps` to bound the tool loop.
+Tool authorization remains application-owned and must fail closed before data
+or side effects are exposed.
----
+Provider-owned tools are imported from Archipel provider `/tools` subpaths.
+They are represented by opaque Archipel definitions; their native SDK types do
+not cross into the application.
-## Streaming Text
+## Agents
-`streamText()` uses the same provider configuration and registered tools as `generateText()` and returns the native AI SDK stream result.
+`IntelligenceAgentFactory.create()` builds a reusable bounded agent on the same
+language facade:
 ```typescript
-const stream = await this._textGenerator.streamText(prompt, {
-  activeTools: ['recommendWorkout'],
-  stopWhen: stepCountIs(3),
+const agent = agents.create({
+  name: 'researcher',
+  instructions: 'Use approved sources and report uncertainty.',
+  activeToolNames: ['web_search', 'document_search'],
+  maxSteps: 6,
 });
-return stream.toUIMessageStreamResponse();
+const answer = await agent.generate({ prompt: question });
 ```
----
+Agents do not create a second provider abstraction. They compose language,
+tools, model policy, and step limits already owned by Archipel.
-## Inspecting Configuration
+## Results and Failures
-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'
-```
+Language completions expose provider, model, text, typed output, finish reason,
+reasoning text, normalized sources and files, tool calls/results, warnings, and
+usage. The default total-operation timeout is 30 seconds.
----
-## 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.
-Two additional error classes handle configuration and validation failures:
-| Error class                        | Code                          | When thrown                                                           |
-| ---------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
-| `IntelligenceProviderError`        | `INTELLIGENCE_PROVIDER`       | Provider SDK failures during text generation                          |
-| `IntelligenceValidationError`      | `INTELLIGENCE_VALIDATION`     | Invalid generation parameters (temperature, topP, maxOutputTokens)    |
-| `IntelligenceConfigurationError`   | `INTELLIGENCE_CONFIGURATION`  | Unsupported provider, missing API key, or missing provider loader     |
-### 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 no loader is registered for the configured provider, startup fails with a clear configuration error. If a provider subpath is imported without its AI SDK peer package installed, the application fails at that import boundary instead of pulling the provider through the root package.
----
-## Architecture Overview
-```mermaid
-flowchart TB
-  subgraph IntelligenceModule[IntelligenceModule]
-    TextGenerator[IntelligenceTextGenerator\nConfigService -> provider]
-    ToolRegistry[IntelligenceToolRegistry]
-  end
-  GenerateText["generateText(prompt, options?)"]
-  StreamText["streamText(prompt, options?)"]
-  ResolveTools["toToolSet()\nregister(tool)"]
-  ProviderLoaders[Registered Provider Loaders\nproviders/openai, providers/anthropic, providers/google, providers/grok]
-  FeatureTools[Feature Tools\nnative AI SDK tools]
-  TextGenerator --> GenerateText
-  TextGenerator --> StreamText
-  ToolRegistry --> ResolveTools
-  TextGenerator --> ProviderLoaders
-  ToolRegistry --> FeatureTools
-  GenerateText --> ToolRegistry
-  StreamText --> ToolRegistry
-```
+Provider failures use `IntelligenceProviderError`; invalid prompts and options
+use `IntelligenceValidationError`; missing adapters or capability defaults use
+`IntelligenceConfigurationError`.