@breadstone/archipel-mcp 0.0.43 → 0.0.45

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

@@ -6,7 +6,7 @@ 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.
+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.
 
 ---
 
@@ -23,31 +23,41 @@ Install the AI SDK provider package for the model you want to use:
 | **OpenAI**     | `@ai-sdk/openai`    |
 | **Anthropic**  | `@ai-sdk/anthropic` |
 | **Google**     | `@ai-sdk/google`    |
-| **Grok (xAI)** | `@ai-sdk/openai`    |
+| **Grok (xAI)** | `@ai-sdk/xai`       |
 
 ```bash
 # Example: OpenAI
 yarn add @ai-sdk/openai
-```
 
-> Grok uses the OpenAI-compatible endpoint, so it shares the `@ai-sdk/openai` package.
+# Example: Grok / xAI
+yarn add @ai-sdk/xai
+```
 
 ---
 
 ## Module Registration
 
-Import `IntelligenceModule` into your application module. It exposes `IntelligenceTextGenerator` and `IntelligenceCapabilityRegistry` as shared providers.
+Import `IntelligenceModule` into your application module. It exposes `IntelligenceTextGenerator` and `IntelligenceToolRegistry` as shared providers.
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
+import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
+import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
 
 @Module({
-  imports: [IntelligenceModule],
+  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
@@ -71,7 +81,7 @@ INTELLIGENCE_BASE_URL=              # optional — override for custom endpoints
 | `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 |
+| `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:
 
@@ -79,7 +89,7 @@ Each provider resolves its API key and base URL from dedicated environment varia
 # Provider-specific keys (optional — fallback from INTELLIGENCE_API_KEY)
 OPENAI_API_KEY=sk-...
 ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_GENERATIVE_AI_API_KEY=AI...
+GOOGLE_API_KEY=AI...
 GROK_API_KEY=xai-...
 ```
 
@@ -91,8 +101,8 @@ 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';
+import type { Prompt } from 'ai';
+import { IntelligenceTextGenerator, type IIntelligenceTextCompletion } from '@breadstone/archipel-platform-intelligence';
 
 @Injectable()
 export class SummaryService {
@@ -103,8 +113,8 @@ export class SummaryService {
   }
 
   public async summarize(content: string): Promise<string> {
-    const prompt: IIntelligencePrompt = {
-      systemPrompt: 'You are a concise summarizer. Respond with a short summary.',
+    const prompt: Prompt = {
+      system: 'You are a concise summarizer. Respond with a short summary.',
       messages: [{ role: 'user', content: content }],
     };
 
@@ -117,18 +127,12 @@ export class SummaryService {
 
 ### Prompt Structure
 
-A prompt consists of an optional system prompt and an ordered array of messages:
+A prompt uses the native AI SDK `Prompt` type. Use either a string prompt or a full message array:
 
 ```typescript
-interface IIntelligencePrompt {
-  readonly systemPrompt: string | null;
-  readonly messages: ReadonlyArray<IIntelligencePromptMessage>;
-}
-
-interface IIntelligencePromptMessage {
-  readonly role: 'user' | 'assistant' | 'system';
-  readonly content: string;
-}
+type Prompt =
+  | { readonly system?: string; readonly prompt: string }
+  | { readonly system?: string; readonly messages: Array<ModelMessage> };
 ```
 
 ### Per-Request Overrides
@@ -144,13 +148,15 @@ const completion = await this._textGenerator.generateText(prompt, {
 
 ### Completion Response
 
-The response includes the generated text, the provider/model used, and optional token usage telemetry:
+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;
 }
 
@@ -168,8 +174,8 @@ interface IIntelligenceCompletionUsage {
 Build multi-turn conversations by passing the full message history:
 
 ```typescript
-const prompt: IIntelligencePrompt = {
-  systemPrompt: 'You are a helpful fitness coach.',
+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.' },
@@ -182,124 +188,405 @@ const completion = await this._textGenerator.generateText(prompt);
 
 ---
 
-## Capability System
+## Tool Registration
 
-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.
+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.
 
-### Defining a Capability
+```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;
+}
 
-Implement the `IIntelligenceCapability` interface:
+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}`,
+      }),
+    });
+  }
+}
+
+@Module({
+  imports: [
+    IntelligenceModule.register({
+      providerLoaders: {
+        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
+      },
+      tools: [WorkoutRecommendationTool],
+    }),
+  ],
+})
+export class WorkoutModule {}
+```
+
+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:
 
 ```typescript
-import type {
-  IIntelligenceCapability,
-  IIntelligenceCapabilityMetadata,
-  IIntelligenceCapabilityPayload,
-  IIntelligenceCapabilityResult,
-  IIntelligenceContext,
-  IIntelligenceIntent,
-} from '@breadstone/archipel-platform-intelligence';
+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';
 
-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;
+@Module({
+  imports: [
+    IntelligenceModule.register({
+      providerLoaders: {
+        [IntelligenceProviderNames.OpenAI]: loadOpenAILanguageModel,
+      },
+      tools: [createOpenAIWebSearchTool({ searchContextSize: 'medium' })],
+    }),
+  ],
+})
+export class SearchModule {}
+```
+
+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
+
+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.
+
+```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;
   }
 
-  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' } }],
-    };
+  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,
+      },
+    );
   }
 }
 ```
 
-### Registering Capabilities
+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.
 
-Use `IntelligenceCapabilityRegistrarBase` to auto-register capabilities when a module initializes:
+### 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 {
-  IntelligenceCapabilityRegistrarBase,
-  IntelligenceCapabilityRegistry,
-} from '@breadstone/archipel-platform-intelligence';
-import type { IIntelligenceCapability } from '@breadstone/archipel-platform-intelligence';
+  createOpenAICodeInterpreterTool,
+  createOpenAICustomTool,
+  createOpenAIImageGenerationTool,
+  createOpenAIToolSearchTool,
+} from '@breadstone/archipel-platform-intelligence/providers/openai/tools';
 
 @Injectable()
-export class WorkoutCapabilityRegistrar extends IntelligenceCapabilityRegistrarBase {
-  constructor(registry: IntelligenceCapabilityRegistry) {
-    super(registry);
+export class OpenAIToolRecipeService {
+  private readonly _textGenerator: IntelligenceTextGenerator;
+
+  public constructor(textGenerator: IntelligenceTextGenerator) {
+    this._textGenerator = textGenerator;
   }
 
-  protected getCapabilities(): ReadonlyArray<IIntelligenceCapability> {
-    return [new WorkoutRecommendationCapability()];
+  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,
+        },
+      },
+    );
   }
-}
-```
 
-Register the registrar as a provider in your feature module:
+  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,
+        },
+      },
+    );
+  }
 
-```typescript
-import { Module } from '@nestjs/common';
-import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
+  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 },
+            },
+          }),
+        },
+      },
+    );
+  }
 
-@Module({
-  imports: [IntelligenceModule],
-  providers: [WorkoutCapabilityRegistrar],
-})
-export class WorkoutModule {}
+  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,
+        },
+      },
+    );
+  }
+}
 ```
 
-### Resolving Capabilities at Runtime
+`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.
 
-Use the registry to find the best-matching capability for a classified intent:
+### Outdoor Order Weather Risk Example
+
+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`.
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { IntelligenceCapabilityRegistry } from '@breadstone/archipel-platform-intelligence';
-import type {
-  IIntelligenceCapabilityResult,
-  IIntelligenceContext,
-  IIntelligenceIntent,
+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> {
+  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) => this.loadOutdoorOrders(input.date),
+    });
+  }
+
+  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 ChatOrchestrator {
-  private readonly _registry: IntelligenceCapabilityRegistry;
+export class OutdoorOrderRiskAnalysisService {
+  private readonly _textGenerator: IntelligenceTextGenerator;
 
-  constructor(registry: IntelligenceCapabilityRegistry) {
-    this._registry = registry;
+  public constructor(textGenerator: IntelligenceTextGenerator) {
+    this._textGenerator = textGenerator;
   }
 
-  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 });
+  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 {}
 ```
 
-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.
+Use AI SDK request options to constrain tool use per call:
 
-> **Capacity limit:** The registry enforces a maximum of **500** registered capabilities. Attempts to exceed this limit are logged as warnings and silently ignored.
+```typescript
+const completion = await this._textGenerator.generateText(prompt, {
+  toolChoice: 'auto',
+  activeTools: ['recommendWorkout'],
+});
+```
+
+> **Capacity limit:** The registry enforces a maximum of **128** registered tools.
+
+---
+
+## Streaming Text
+
+`streamText()` uses the same provider configuration and registered tools as `generateText()` and returns the native AI SDK stream result.
+
+```typescript
+const stream = await this._textGenerator.streamText(prompt, {
+  activeTools: ['recommendWorkout'],
+  stopWhen: stepCountIs(3),
+});
+
+return stream.toUIMessageStreamResponse();
+```
 
 ---
 
@@ -325,7 +612,7 @@ Two additional error classes handle configuration and validation failures:
 | ---------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
 | `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 SDK package         |
+| `IntelligenceConfigurationError`   | `INTELLIGENCE_CONFIGURATION`  | Unsupported provider, missing API key, or missing provider loader     |
 
 ### Timeout & Retry Defaults
 
@@ -362,7 +649,7 @@ try {
 }
 ```
 
-If an AI SDK provider package is not installed, the error message clearly states which package is missing.
+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.
 
 ---
 
@@ -372,16 +659,20 @@ If an AI SDK provider package is not installed, the error message clearly states
 flowchart TB
   subgraph IntelligenceModule[IntelligenceModule]
     TextGenerator[IntelligenceTextGenerator\nConfigService -> provider]
-    CapabilityRegistry[IntelligenceCapability Registry]
+    ToolRegistry[IntelligenceToolRegistry]
   end
 
   GenerateText["generateText(prompt, options?)"]
-  ResolveCapability["resolve(intent, context)\nregister(capability)"]
-  ProviderLoaders[Provider Loaders\nOpenAI, Anthropic, Google, Grok]
-  FeatureCapabilities[Feature Capabilities\ncustom handlers]
+  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
-  CapabilityRegistry --> ResolveCapability
+  TextGenerator --> StreamText
+  ToolRegistry --> ResolveTools
   TextGenerator --> ProviderLoaders
-  CapabilityRegistry --> FeatureCapabilities
+  ToolRegistry --> FeatureTools
+  GenerateText --> ToolRegistry
+  StreamText --> ToolRegistry
 ```