ai.matey.frontend 0.2.0 → 0.3.0

package/dist/types/adapters/anthropic.d.ts

@@ -10,7 +10,50 @@ import type { FrontendAdapter, AdapterMetadata } from 'ai.matey.types';
 import type { IRChatRequest, IRChatResponse, IRChatStream } from 'ai.matey.types';
 import type { StreamConversionOptions } from 'ai.matey.types';
 /**
- * Anthropic message content block.
+ * Anthropic content block type supporting text, images, and tool usage.
+ *
+ * Claude uses a structured content block format where each piece of content
+ * is represented as an object with a discriminated `type` field. This enables
+ * multimodal messages mixing text, images, and tool interactions.
+ *
+ * @see AnthropicMessage
+ * @see https://docs.anthropic.com/en/api/messages
+ *
+ * @example
+ * ```typescript
+ * // Text block
+ * const text: AnthropicContentBlock = {
+ *   type: 'text',
+ *   text: 'Hello, Claude!'
+ * };
+ *
+ * // Image from URL
+ * const imageUrl: AnthropicContentBlock = {
+ *   type: 'image',
+ *   source: {
+ *     type: 'url',
+ *     url: 'https://example.com/photo.jpg'
+ *   }
+ * };
+ *
+ * // Base64 image
+ * const imageB64: AnthropicContentBlock = {
+ *   type: 'image',
+ *   source: {
+ *     type: 'base64',
+ *     media_type: 'image/jpeg',
+ *     data: '/9j/4AAQSkZJRg...'
+ *   }
+ * };
+ *
+ * // Tool use request
+ * const toolUse: AnthropicContentBlock = {
+ *   type: 'tool_use',
+ *   id: 'toolu_123',
+ *   name: 'get_weather',
+ *   input: { location: 'San Francisco' }
+ * };
+ * ```
  */
 export type AnthropicContentBlock = {
     type: 'text';
@@ -30,49 +73,191 @@ export type AnthropicContentBlock = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | {
+        type: 'text';
+        text: string;
+    }[];
+    is_error?: boolean;
 };
 /**
- * Anthropic message.
+ * Anthropic message structure in a conversation.
+ *
+ * Claude messages support only 'user' and 'assistant' roles. System messages
+ * are handled separately via the `system` parameter at the request level.
+ * Content can be a simple string or an array of structured blocks.
+ *
+ * @see AnthropicContentBlock
+ * @see AnthropicRequest
  */
 export interface AnthropicMessage {
+    /** Message role - only 'user' or 'assistant' (system is separate) */
     role: 'user' | 'assistant';
+    /** Message content - simple string or array of content blocks for multimodal */
     content: string | AnthropicContentBlock[];
 }
 /**
- * Anthropic Messages API request.
+ * Anthropic Messages API request structure.
+ *
+ * Defines all parameters for making a request to Claude via Anthropic's Messages API.
+ * Key differences from OpenAI: system message is a separate parameter (not in messages),
+ * max_tokens is required, and supports top_k sampling parameter.
+ *
+ * @see AnthropicMessage
+ * @see AnthropicResponse
+ * @see https://docs.anthropic.com/en/api/messages
+ *
+ * @example
+ * ```typescript
+ * const request: AnthropicRequest = {
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   max_tokens: 1024,
+ *   messages: [
+ *     { role: 'user', content: 'Hello, Claude!' }
+ *   ],
+ *   system: 'You are a helpful assistant.',
+ *   temperature: 0.7
+ * };
+ * ```
  */
 export interface AnthropicRequest {
+    /** Model ID (e.g., 'claude-3-5-sonnet-20241022', 'claude-3-opus-20240229') */
     model: string;
+    /** Array of conversation messages (user and assistant only) */
     messages: AnthropicMessage[];
+    /** System prompt/instructions (separate from messages array) */
     system?: string;
+    /** Maximum tokens to generate - REQUIRED by Anthropic API */
     max_tokens: number;
+    /** Sampling temperature 0-1. Higher = more random. Default 1 */
     temperature?: number;
+    /** Nucleus sampling parameter 0-1. Alternative to temperature */
     top_p?: number;
+    /** Top-K sampling parameter. Only sample from top K tokens */
     top_k?: number;
+    /** Stop sequences - generation stops when encountered */
     stop_sequences?: string[];
+    /** Enable streaming responses via Server-Sent Events */
     stream?: boolean;
+    /** Optional metadata for tracking and abuse prevention */
     metadata?: {
+        /** User identifier for abuse monitoring */
         user_id?: string;
     };
+    /** Tools Claude may use */
+    tools?: Array<{
+        name: string;
+        description?: string;
+        input_schema: Record<string, unknown>;
+    }>;
+    /** Controls how Claude uses tools */
+    tool_choice?: {
+        type: 'auto';
+    } | {
+        type: 'any';
+    } | {
+        type: 'none';
+    } | {
+        type: 'tool';
+        name: string;
+    };
 }
 /**
- * Anthropic Messages API response.
+ * Anthropic Messages API response structure.
+ *
+ * Contains the complete response from Claude including the generated content,
+ * stop reason, and token usage. Content is always returned as an array of
+ * structured blocks, even for simple text responses.
+ *
+ * @see AnthropicRequest
+ * @see AnthropicContentBlock
+ * @see https://docs.anthropic.com/en/api/messages
+ *
+ * @example
+ * ```typescript
+ * const response: AnthropicResponse = {
+ *   id: 'msg_123',
+ *   type: 'message',
+ *   role: 'assistant',
+ *   content: [
+ *     { type: 'text', text: 'Hello! How can I help you today?' }
+ *   ],
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   stop_reason: 'end_turn',
+ *   usage: {
+ *     input_tokens: 12,
+ *     output_tokens: 8
+ *   }
+ * };
+ * ```
  */
 export interface AnthropicResponse {
+    /** Unique identifier for this message */
     id: string;
+    /** Object type - always 'message' for Messages API */
     type: 'message';
+    /** Role of the responder - always 'assistant' */
     role: 'assistant';
+    /** Array of content blocks (even for simple text responses) */
     content: AnthropicContentBlock[];
+    /** Model that generated the response */
     model: string;
+    /** Reason generation stopped: 'end_turn' (natural), 'max_tokens', 'stop_sequence', 'tool_use', or null */
     stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | null;
+    /** The actual stop sequence matched (if stop_reason is 'stop_sequence') */
     stop_sequence?: string | null;
+    /** Token usage statistics */
     usage: {
+        /** Number of tokens in the input/prompt */
         input_tokens: number;
+        /** Number of tokens in the output/completion */
         output_tokens: number;
     };
 }
 /**
- * Anthropic SSE stream event.
+ * Anthropic streaming event types via Server-Sent Events.
+ *
+ * Claude uses a more complex streaming protocol than OpenAI, with distinct
+ * events for different stages: message start, content block start/delta/stop,
+ * and message completion. This enables fine-grained control over streaming
+ * display and supports tool use streaming.
+ *
+ * Event flow:
+ * 1. `message_start` - Stream begins with metadata
+ * 2. `content_block_start` - Each content block (text/tool) starts
+ * 3. `content_block_delta` - Incremental content for the block
+ * 4. `content_block_stop` - Block is complete
+ * 5. `message_delta` - Final metadata (stop reason, usage)
+ * 6. `message_stop` - Stream ends
+ *
+ * @see AnthropicRequest
+ * @see AnthropicResponse
+ * @see https://docs.anthropic.com/en/api/messages-streaming
+ *
+ * @example
+ * ```typescript
+ * // Message start event
+ * const start: AnthropicStreamEvent = {
+ *   type: 'message_start',
+ *   message: { id: 'msg_123', model: 'claude-3-5-sonnet-20241022' }
+ * };
+ *
+ * // Text delta event
+ * const delta: AnthropicStreamEvent = {
+ *   type: 'content_block_delta',
+ *   index: 0,
+ *   delta: { type: 'text_delta', text: 'Hello' }
+ * };
+ *
+ * // Completion event
+ * const done: AnthropicStreamEvent = {
+ *   type: 'message_delta',
+ *   delta: { stop_reason: 'end_turn' },
+ *   usage: { output_tokens: 42 }
+ * };
+ * ```
  */
 export type AnthropicStreamEvent = {
     type: 'message_start';
@@ -118,17 +303,78 @@ export type AnthropicStreamEvent = {
 export declare class AnthropicFrontendAdapter implements FrontendAdapter<AnthropicRequest, AnthropicResponse, AnthropicStreamEvent> {
     readonly metadata: AdapterMetadata;
     /**
-     * Convert Anthropic request to Universal IR.
+     * Convert Anthropic Messages API request to Universal IR format.
+     *
+     * This method transforms an Anthropic-formatted request into the standardized
+     * Intermediate Representation (IR) format. It handles Anthropic's unique system
+     * message format (separate from messages array) by converting it to IR's
+     * in-messages format, and maps Anthropic-specific parameters like top_k.
+     *
+     * @param request - Anthropic Messages API request
+     * @returns Promise resolving to IR chat request
+     * @throws {AdapterConversionError} If conversion fails
+     *
+     * @example
+     * ```typescript
+     * const adapter = new AnthropicFrontendAdapter();
+     * const irRequest = await adapter.toIR({
+     *   model: 'claude-3-5-sonnet-20241022',
+     *   max_tokens: 1024,
+     *   messages: [{ role: 'user', content: 'Hello!' }],
+     *   system: 'You are a helpful assistant'
+     * });
+     * ```
      */
     toIR(request: AnthropicRequest): Promise<IRChatRequest>;
     /**
-     * Convert Universal IR response to Anthropic format.
+     * Convert Universal IR response back to Anthropic Messages API format.
+     *
+     * This method transforms the standardized IR response into the format
+     * expected by Anthropic's Messages API. It handles message conversion,
+     * stop reason mapping, and usage statistics formatting specific to
+     * Anthropic's response structure.
+     *
+     * @param response - Universal IR chat response
+     * @returns Promise resolving to Anthropic Messages API response
+     * @throws {AdapterConversionError} If conversion fails
+     *
+     * @example
+     * ```typescript
+     * const adapter = new AnthropicFrontendAdapter();
+     * const anthropicResponse = await adapter.fromIR(irResponse);
+     * console.log(anthropicResponse.content[0].text);
+     * ```
      */
     fromIR(response: IRChatResponse): Promise<AnthropicResponse>;
     /**
-     * Convert Universal IR stream to Anthropic SSE format.
+     * Convert Universal IR stream to Anthropic Server-Sent Events (SSE) format.
+     *
+     * This async generator method transforms a stream of IR chunks into
+     * Anthropic-formatted streaming events. It handles stream mode conversion,
+     * tracks message metadata, and emits properly formatted SSE events
+     * compatible with Anthropic's streaming API including message_start,
+     * content_block_delta, and message_stop events.
+     *
+     * @param stream - Universal IR chat stream
+     * @param options - Optional stream conversion options (stream mode, etc.)
+     * @yields Anthropic-formatted streaming events
+     * @throws {AdapterConversionError} If stream conversion fails
+     *
+     * @example
+     * ```typescript
+     * const adapter = new AnthropicFrontendAdapter();
+     * for await (const event of adapter.fromIRStream(irStream)) {
+     *   if (event.type === 'content_block_delta') {
+     *     console.log(event.delta.text);
+     *   }
+     * }
+     * ```
      */
     fromIRStream(stream: IRChatStream, options?: StreamConversionOptions): AsyncGenerator<AnthropicStreamEvent, void, undefined>;
+    /**
+     * Convert Anthropic tool_choice to IR toolChoice.
+     */
+    private convertToolChoiceToIR;
     /**
      * Convert Anthropic message to IR message.
      */

package/dist/types/adapters/anthropic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/adapters/anthropic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,YAAY,EAIb,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAQ9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7F,GACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC9E;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEN;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAE3B,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IAEd,+DAA+D;IAC/D,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAE7B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IAEnB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE;QACT,2CAA2C;QAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvC,CAAC,CAAC;IAEH,qCAAqC;IACrC,WAAW,CAAC,EACR;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,GACf;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IAEX,sDAAsD;IACtD,IAAI,EAAE,SAAS,CAAC;IAEhB,iDAAiD;IACjD,IAAI,EAAE,WAAW,CAAC;IAElB,+DAA+D;IAC/D,OAAO,EAAE,qBAAqB,EAAE,CAAC;IAEjC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IAEd,0GAA0G;IAC1G,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,IAAI,CAAC;IAE7E,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,6BAA6B;IAC7B,KAAK,EAAE;QACL,2CAA2C;QAC3C,YAAY,EAAE,MAAM,CAAC;QAErB,gDAAgD;QAChD,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,qBAAqB,CAAA;CAAE,GACpF;IACE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EACD;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GACpC;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,GACD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9D,KAAK,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAClC,GACD;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAMhE;;GAEG;AACH,qBAAa,wBAAyB,YAAW,eAAe,CAC9D,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,CACrB;IACC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAehC;IAEF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;IAyDvD;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmC5D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,YAAY,CACjB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAChC,cAAc,CAAC,oBAAoB,EAAE,IAAI,EAAE,SAAS,CAAC;IAqIxD;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAwD/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuD5B;;OAEG;IACH,OAAO,CAAC,eAAe;CAcxB"}

package/dist/types/adapters/chrome-ai.d.ts

@@ -8,18 +8,113 @@
 import type { FrontendAdapter, AdapterMetadata } from 'ai.matey.types';
 import type { IRChatRequest, IRChatResponse, IRStreamChunk } from 'ai.matey.types';
 import type { StreamConversionOptions } from 'ai.matey.types';
+/**
+ * Chrome AI request structure for browser-based AI.
+ *
+ * Chrome's built-in AI uses a simple prompt-based format without message arrays.
+ * Only available in Chrome 129+ with AI features enabled.
+ *
+ * @see ChromeAIResponse
+ * @see https://developer.chrome.com/docs/ai/built-in
+ *
+ * @example
+ * ```typescript
+ * const request: ChromeAIRequest = {
+ *   prompt: 'Explain quantum computing',
+ *   temperature: 0.7,
+ *   topK: 40
+ * };
+ * ```
+ */
 export interface ChromeAIRequest {
+    /** Text prompt (no message array format) */
     prompt: string;
+    /** Sampling temperature parameter */
     temperature?: number;
+    /** Top-K sampling parameter */
     topK?: number;
 }
+/**
+ * Chrome AI response structure.
+ *
+ * Simple text-only response from Chrome's built-in AI. No usage statistics
+ * or additional metadata since it runs locally in the browser.
+ *
+ * @see ChromeAIRequest
+ *
+ * @example
+ * ```typescript
+ * const response: ChromeAIResponse = {
+ *   text: 'Quantum computing uses quantum mechanics...'
+ * };
+ * ```
+ */
 export interface ChromeAIResponse {
+    /** Generated text response */
     text: string;
 }
 export declare class ChromeAIFrontendAdapter implements FrontendAdapter<ChromeAIRequest, ChromeAIResponse> {
     readonly metadata: AdapterMetadata;
+    /**
+     * Convert Chrome AI request to Universal IR format.
+     *
+     * This method transforms a Chrome AI-formatted request into the standardized
+     * Intermediate Representation (IR) format. Chrome AI uses a simple prompt-based
+     * format, so this converts the single prompt string into a user message within
+     * the IR message array structure.
+     *
+     * @param request - Chrome AI request with prompt and optional parameters
+     * @returns Promise resolving to IR chat request
+     *
+     * @example
+     * ```typescript
+     * const adapter = new ChromeAIFrontendAdapter();
+     * const irRequest = await adapter.toIR({
+     *   prompt: 'What is the capital of France?',
+     *   temperature: 0.7,
+     *   topK: 40
+     * });
+     * ```
+     */
     toIR(request: ChromeAIRequest): Promise<IRChatRequest>;
+    /**
+     * Convert Universal IR response back to Chrome AI format.
+     *
+     * This method transforms the standardized IR response into the format
+     * expected by Chrome AI's interface. It extracts the text content from
+     * the IR message and returns it in Chrome AI's simple `{ text }` format.
+     *
+     * @param response - Universal IR chat response
+     * @returns Promise resolving to Chrome AI response
+     *
+     * @example
+     * ```typescript
+     * const adapter = new ChromeAIFrontendAdapter();
+     * const chromeResponse = await adapter.fromIR(irResponse);
+     * console.log(chromeResponse.text);
+     * ```
+     */
     fromIR(response: IRChatResponse): Promise<ChromeAIResponse>;
+    /**
+     * Convert Universal IR stream to Chrome AI streaming format.
+     *
+     * This async generator method transforms a stream of IR chunks into
+     * Chrome AI's simple text streaming format. It yields raw text strings
+     * (no JSON wrapping, no SSE format) and supports stream mode conversion
+     * through options (delta, full, or text-only modes).
+     *
+     * @param stream - Universal IR chat stream
+     * @param options - Optional stream conversion options (stream mode, etc.)
+     * @yields Raw text strings
+     *
+     * @example
+     * ```typescript
+     * const adapter = new ChromeAIFrontendAdapter();
+     * for await (const textChunk of adapter.fromIRStream(irStream)) {
+     *   console.log(textChunk); // Raw text like "Hello" or " world"
+     * }
+     * ```
+     */
     fromIRStream(stream: AsyncGenerator<IRStreamChunk>, options?: StreamConversionOptions): AsyncGenerator<string>;
 }
 //# sourceMappingURL=chrome-ai.d.ts.map

package/dist/types/adapters/chrome-ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chrome-ai.d.ts","sourceRoot":"","sources":["../../../src/adapters/chrome-ai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,uBAAwB,YAAW,eAAe,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAChG,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAWhC;IAEF,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAetD,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAMpD,YAAY,CACjB,MAAM,EAAE,cAAc,CAAC,aAAa,CAAC,EACrC,OAAO,CAAC,EAAE,uBAAuB,GAChC,cAAc,CAAC,MAAM,CAAC;CAU1B"}
+{"version":3,"file":"chrome-ai.d.ts","sourceRoot":"","sources":["../../../src/adapters/chrome-ai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IAEf,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,uBAAwB,YAAW,eAAe,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAChG,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAWhC;IAEF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAetD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM3D;;;;;;;;;;;;;;;;;;;OAmBG;IACI,YAAY,CACjB,MAAM,EAAE,cAAc,CAAC,aAAa,CAAC,EACrC,OAAO,CAAC,EAAE,uBAAuB,GAChC,cAAc,CAAC,MAAM,CAAC;CAU1B"}

package/dist/types/adapters/gemini.d.ts

@@ -9,8 +9,43 @@
 import type { FrontendAdapter, AdapterMetadata } from 'ai.matey.types';
 import type { IRChatRequest, IRChatResponse, IRStreamChunk } from 'ai.matey.types';
 import type { StreamConversionOptions } from 'ai.matey.types';
+/**
+ * Gemini content structure for messages.
+ *
+ * Google Gemini uses a unique `parts` array format where each message contains
+ * an array of content parts. Each part can be text or inline data (images).
+ * Role is either 'user' or 'model' (Gemini calls the assistant 'model').
+ *
+ * @see GeminiRequest
+ * @see https://ai.google.dev/api/rest/v1/Content
+ *
+ * @example
+ * ```typescript
+ * // Text-only message
+ * const textContent: GeminiContent = {
+ *   role: 'user',
+ *   parts: [{ text: 'Hello, Gemini!' }]
+ * };
+ *
+ * // Multimodal message with image
+ * const multimodalContent: GeminiContent = {
+ *   role: 'user',
+ *   parts: [
+ *     { text: 'What is in this image?' },
+ *     {
+ *       inlineData: {
+ *         mimeType: 'image/jpeg',
+ *         data: 'base64-encoded-image-data...'
+ *       }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
 export interface GeminiContent {
+    /** Message role - 'user' or 'model' (Gemini's term for assistant) */
     role: 'user' | 'model';
+    /** Array of content parts - can mix text and inline data (images) */
     parts: Array<{
         text: string;
     } | {
@@ -20,36 +55,171 @@ export interface GeminiContent {
         };
     }>;
 }
+/**
+ * Google Gemini API request structure.
+ *
+ * Defines parameters for making a request to Google's Gemini API. Key differences
+ * from other providers: uses `contents` (plural) for messages, `systemInstruction`
+ * for system prompts, and generation parameters in a nested `generationConfig` object.
+ * Temperature range is 0-1 (not 0-2 like some other providers).
+ *
+ * @see GeminiContent
+ * @see GeminiResponse
+ * @see https://ai.google.dev/api/rest/v1/models/generateContent
+ *
+ * @example
+ * ```typescript
+ * const request: GeminiRequest = {
+ *   contents: [
+ *     {
+ *       role: 'user',
+ *       parts: [{ text: 'Explain quantum computing' }]
+ *     }
+ *   ],
+ *   systemInstruction: {
+ *     parts: [{ text: 'You are a helpful physics teacher.' }]
+ *   },
+ *   generationConfig: {
+ *     temperature: 0.7,
+ *     maxOutputTokens: 1024
+ *   }
+ * };
+ * ```
+ */
 export interface GeminiRequest {
+    /** Array of conversation contents (user and model messages) */
     contents: GeminiContent[];
+    /** System instruction/prompt (separate from contents) */
     systemInstruction?: {
         parts: Array<{
             text: string;
         }>;
     };
+    /** Generation parameters nested in config object */
     generationConfig?: {
+        /** Sampling temperature 0-1 (Gemini uses 0-1, not 0-2) */
         temperature?: number;
+        /** Nucleus sampling parameter 0-1 */
         topP?: number;
+        /** Top-K sampling parameter */
         topK?: number;
+        /** Maximum tokens to generate */
         maxOutputTokens?: number;
+        /** Stop sequences - generation stops when encountered */
         stopSequences?: string[];
     };
 }
+/**
+ * Google Gemini API response structure.
+ *
+ * Contains the response from Gemini including generated content, finish reason,
+ * and token usage. Gemini can return multiple candidates (alternative completions)
+ * though typically only one is returned. Finish reasons include safety-related
+ * stops unique to Gemini.
+ *
+ * @see GeminiRequest
+ * @see GeminiContent
+ * @see https://ai.google.dev/api/rest/v1/GenerateContentResponse
+ *
+ * @example
+ * ```typescript
+ * const response: GeminiResponse = {
+ *   candidates: [
+ *     {
+ *       content: {
+ *         role: 'model',
+ *         parts: [{ text: 'Quantum computing uses quantum mechanics...' }]
+ *       },
+ *       finishReason: 'STOP'
+ *     }
+ *   ],
+ *   usageMetadata: {
+ *     promptTokenCount: 15,
+ *     candidatesTokenCount: 120,
+ *     totalTokenCount: 135
+ *   }
+ * };
+ * ```
+ */
 export interface GeminiResponse {
+    /** Array of candidate responses (usually just one) */
     candidates: Array<{
+        /** Generated content from the model */
         content: GeminiContent;
+        /** Reason generation stopped: 'STOP' (natural), 'MAX_TOKENS', 'SAFETY', 'RECITATION', 'OTHER' */
         finishReason: 'STOP' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' | 'OTHER';
     }>;
+    /** Token usage statistics */
     usageMetadata?: {
+        /** Number of tokens in the prompt */
         promptTokenCount: number;
+        /** Number of tokens in all candidates */
         candidatesTokenCount: number;
+        /** Total tokens used (prompt + candidates) */
         totalTokenCount: number;
     };
 }
 export declare class GeminiFrontendAdapter implements FrontendAdapter<GeminiRequest, GeminiResponse> {
     readonly metadata: AdapterMetadata;
+    /**
+     * Convert Google Gemini API request to Universal IR format.
+     *
+     * This method transforms a Gemini-formatted request into the standardized
+     * Intermediate Representation (IR) format. It handles Gemini's unique
+     * content structure (parts array), converts 'model' role to 'assistant',
+     * and adjusts temperature values (Gemini uses 0-1, IR uses 0-2).
+     *
+     * @param request - Google Gemini API request
+     * @returns Promise resolving to IR chat request
+     *
+     * @example
+     * ```typescript
+     * const adapter = new GeminiFrontendAdapter();
+     * const irRequest = await adapter.toIR({
+     *   contents: [{ role: 'user', parts: [{ text: 'Hello!' }] }],
+     *   generationConfig: { temperature: 0.7 }
+     * });
+     * ```
+     */
     toIR(request: GeminiRequest): Promise<IRChatRequest>;
+    /**
+     * Convert Universal IR response back to Google Gemini API format.
+     *
+     * This method transforms the standardized IR response into the format
+     * expected by Gemini's API. It converts 'assistant' role back to 'model',
+     * structures content as parts array, and maps finish reasons to Gemini's
+     * specific format (STOP, MAX_TOKENS, OTHER).
+     *
+     * @param response - Universal IR chat response
+     * @returns Promise resolving to Gemini API response
+     *
+     * @example
+     * ```typescript
+     * const adapter = new GeminiFrontendAdapter();
+     * const geminiResponse = await adapter.fromIR(irResponse);
+     * console.log(geminiResponse.candidates[0].content.parts[0].text);
+     * ```
+     */
     fromIR(response: IRChatResponse): Promise<GeminiResponse>;
+    /**
+     * Convert Universal IR stream to Google Gemini Server-Sent Events format.
+     *
+     * This async generator method transforms a stream of IR chunks into
+     * Gemini-formatted SSE responses. It yields Server-Sent Event strings
+     * with the "data: " prefix containing JSON candidates with parts array.
+     *
+     * @param stream - Universal IR chat stream
+     * @param _options - Optional stream conversion options (currently unused)
+     * @yields Server-Sent Event formatted strings
+     *
+     * @example
+     * ```typescript
+     * const adapter = new GeminiFrontendAdapter();
+     * for await (const sseData of adapter.fromIRStream(irStream)) {
+     *   console.log(sseData); // "data: {...}\n\n"
+     * }
+     * ```
+     */
     fromIRStream(stream: AsyncGenerator<IRStreamChunk>, _options?: StreamConversionOptions): AsyncGenerator<string>;
 }
 //# sourceMappingURL=gemini.d.ts.map