@breadstone/archipel-mcp 0.0.54 → 0.0.56

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

@@ -0,0 +1,101 @@
+---
+title: AI Image Generation
+description: Generate and edit images through the provider-neutral Archipel image generator.
+order: 16
+---
+
+# AI Image Generation
+
+`IntelligenceImageGenerator` owns image generation and editing. Speech,
+transcription, and video use their own capability-specific generators while
+sharing Archipel's provider resolution, timeout, cancellation, error, and file
+infrastructure.
+
+Applications install only Archipel:
+
+```bash
+yarn add @breadstone/archipel-platform-intelligence
+```
+
+Provider runtimes are package-owned optional dependencies. Consumer code must
+not import `ai`, `@ai-sdk/*`, or provider clients.
+
+## Register the Provider
+
+```typescript
+import { Module } from '@nestjs/common';
+import { IntelligenceCapabilityNames, IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
+import { OPENAI_CONFIG_ENTRIES, OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/openai';
+
+@Module({
+    imports: [
+        IntelligenceModule.register({
+            configEntries: OPENAI_CONFIG_ENTRIES,
+            providerAdapters: [OpenAIIntelligenceProviderAdapter],
+            defaultModels: {
+                [IntelligenceCapabilityNames.Image]: {
+                    provider: IntelligenceProviderNames.OpenAI,
+                    model: 'gpt-image-1.5',
+                },
+            },
+            requestTimeouts: {
+                [IntelligenceCapabilityNames.Image]: 120_000,
+            },
+        }),
+    ],
+})
+export class ApplicationModule {}
+```
+
+## Generate or Edit
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IntelligenceImageGenerator } from '@breadstone/archipel-platform-intelligence';
+
+@Injectable()
+export class ProductPosterService {
+    public constructor(private readonly _images: IntelligenceImageGenerator) {}
+
+    public generate() {
+        return this._images.generate({
+            prompt: 'A clean editorial product photograph without text or logos.',
+            count: 3,
+            size: '1536x1024',
+            maxRetries: 2,
+        });
+    }
+
+    public edit(referenceImage: Uint8Array, mask: Uint8Array) {
+        return this._images.generate({
+            prompt: {
+                images: [referenceImage],
+                mask,
+                text: 'Replace the background with a neutral studio wall.',
+            },
+        });
+    }
+}
+```
+
+The result contains normalized generated files, provider, model, warnings, and
+usage. The usage contract distinguishes text input, image input, and generated
+image output tokens when the provider reports enough detail. For a text-only
+prompt, an otherwise undifferentiated input total is safely classified as text;
+for an edit request, missing modality details remain `null` rather than being
+invented. Generated bytes are not persisted by Archipel.
+
+## Safety Boundary
+
+Before calling the facade, the application must complete authentication,
+authorization, tenant ownership, AI enablement, entitlement, quota, and rate
+limit checks. It owns usage charging and persistence after success.
+
+The application must price usage by the resolved provider and model. Archipel
+does not convert token counters into money or product credits, and a missing
+counter must not be treated as zero-cost usage.
+
+Provider failures become `IntelligenceProviderError`. Invalid provider,
+capability, model, or timeout configuration fails before a remote generation
+call. The 120-second default is a total-operation bound and can be overridden
+per request.