ai.matey.utils 0.2.0

package/dist/types/streaming-modes.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Streaming Mode Conversion Utilities
+ *
+ * This module handles conversion between delta and accumulated streaming modes.
+ * Use these utilities when you need to transform IR stream chunks between formats.
+ *
+ * For general stream operations (map, filter, collect), see ./streaming.ts
+ *
+ * @example Converting stream modes
+ * ```typescript
+ * import { convertStreamMode, createAccumulatorState } from 'ai.matey.utils';
+ *
+ * const converter = createAccumulatorState();
+ * const accumulated = await convertStreamMode(deltaStream, 'accumulated', { converter });
+ * ```
+ *
+ * @module streaming-modes
+ */
+import type { IRChatStream, StreamContentChunk } from 'ai.matey.types';
+import type { StreamMode, StreamConversionOptions, StreamingConfig } from 'ai.matey.types';
+/**
+ * Stream accumulator state for tracking accumulated content.
+ */
+export interface StreamAccumulatorState {
+    /**
+     * Full accumulated text so far.
+     */
+    accumulated: string;
+    /**
+     * Number of chunks processed.
+     */
+    chunkCount: number;
+    /**
+     * Last chunk sequence number (for validation).
+     */
+    lastSequence: number;
+}
+/**
+ * Create a new stream accumulator state.
+ */
+export declare function createAccumulatorState(): StreamAccumulatorState;
+/**
+ * Detect the streaming mode of a content chunk.
+ *
+ * @param chunk Content chunk to inspect
+ * @returns Detected streaming mode
+ */
+export declare function detectChunkMode(chunk: StreamContentChunk): StreamMode;
+/**
+ * Check if a chunk needs conversion to target mode.
+ *
+ * @param chunk Content chunk to check
+ * @param targetMode Desired streaming mode
+ * @param preserveIfMatch Whether to skip conversion if already in target mode
+ * @returns true if conversion is needed
+ */
+export declare function needsConversion(chunk: StreamContentChunk, targetMode: StreamMode, preserveIfMatch?: boolean): boolean;
+/**
+ * Convert IR stream to target streaming mode.
+ *
+ * This function transforms an IR stream to use the specified streaming mode:
+ * - Delta mode: Only incremental deltas
+ * - Accumulated mode: Full text in each chunk
+ *
+ * @param stream Source IR stream
+ * @param options Conversion options
+ * @returns Converted IR stream
+ *
+ * @example
+ * ```typescript
+ * // Convert to accumulated mode
+ * const accumulated = convertStreamMode(deltaStream, { mode: 'accumulated' });
+ *
+ * // Convert to delta mode
+ * const delta = convertStreamMode(accumulatedStream, { mode: 'delta' });
+ * ```
+ */
+export declare function convertStreamMode(stream: IRChatStream, options?: StreamConversionOptions): IRChatStream;
+/**
+ * Convert a single content chunk to target mode.
+ *
+ * @param chunk Source content chunk
+ * @param targetMode Target streaming mode
+ * @param state Accumulator state (updated in place)
+ * @param transform Optional transform function
+ * @returns Converted content chunk
+ */
+export declare function convertChunkMode(chunk: StreamContentChunk, targetMode: StreamMode, state: StreamAccumulatorState, transform?: (text: string) => string): StreamContentChunk;
+/**
+ * Get effective streaming mode from cascading configuration.
+ *
+ * Priority order (highest to lowest):
+ * 1. Request-level streamMode
+ * 2. Conversion options mode
+ * 3. Streaming config mode
+ * 4. Default ('delta')
+ *
+ * @param requestMode Stream mode from request
+ * @param conversionMode Stream mode from conversion options
+ * @param config Streaming configuration
+ * @returns Effective streaming mode
+ */
+export declare function getEffectiveStreamMode(requestMode?: StreamMode, conversionMode?: StreamMode, config?: StreamingConfig): StreamMode;
+/**
+ * Merge streaming configurations with priority.
+ *
+ * @param configs Configuration objects in priority order (first wins)
+ * @returns Merged configuration
+ */
+export declare function mergeStreamingConfig(...configs: (StreamingConfig | undefined)[]): Required<StreamingConfig>;
+/**
+ * Ensure all chunks in a stream have a specific mode.
+ *
+ * If chunks don't have the required format, converts them.
+ *
+ * @param stream Source stream
+ * @param mode Required mode
+ * @returns Stream with all chunks in required mode
+ */
+export declare function ensureStreamMode(stream: IRChatStream, mode: StreamMode): IRChatStream;
+/**
+ * Add accumulated field to all content chunks (dual-mode streaming).
+ *
+ * Useful for backends that want to provide both delta and accumulated.
+ *
+ * @param stream Source stream (delta-only)
+ * @returns Stream with both delta and accumulated in content chunks
+ */
+export declare function addAccumulatedToStream(stream: IRChatStream): IRChatStream;
+/**
+ * Strip accumulated field from all content chunks (delta-only streaming).
+ *
+ * Useful for reducing bandwidth when accumulated isn't needed.
+ *
+ * @param stream Source stream
+ * @returns Stream with only delta in content chunks
+ */
+export declare function stripAccumulatedFromStream(stream: IRChatStream): IRChatStream;
+//# sourceMappingURL=streaming-modes.d.ts.map

package/dist/types/streaming-modes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-modes.d.ts","sourceRoot":"","sources":["../../src/streaming-modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAO3F;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,sBAAsB,CAM/D;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CAarE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,kBAAkB,EACzB,UAAU,EAAE,UAAU,EACtB,eAAe,UAAO,GACrB,OAAO,CAuBT;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAuB,iBAAiB,CACtC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,uBAA4B,GACpC,YAAY,CAuCd;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,kBAAkB,EACzB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,sBAAsB,EAC7B,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACnC,kBAAkB,CAwBpB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,CAAC,EAAE,UAAU,EACxB,cAAc,CAAC,EAAE,UAAU,EAC3B,MAAM,CAAC,EAAE,eAAe,GACvB,UAAU,CAEZ;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,OAAO,EAAE,CAAC,eAAe,GAAG,SAAS,CAAC,EAAE,GAC1C,QAAQ,CAAC,eAAe,CAAC,CAsB3B;AAMD;;;;;;;;GAQG;AACH,wBAAuB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,YAAY,CAE5F;AAED;;;;;;;GAOG;AACH,wBAAuB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAehF;AAED;;;;;;;GAOG;AACH,wBAAuB,0BAA0B,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CASpF"}

package/dist/types/streaming.d.ts

@@ -0,0 +1,384 @@
+/**
+ * General Stream Utilities
+ *
+ * This module provides general-purpose stream transformation utilities.
+ * Use these for mapping, filtering, collecting, and error handling in streams.
+ *
+ * For delta/accumulated mode conversion, see ./streaming-modes.ts
+ *
+ * @example Accumulating stream content
+ * ```typescript
+ * import { createStreamAccumulator, accumulateChunk } from 'ai.matey.utils';
+ *
+ * const accumulator = createStreamAccumulator();
+ * for await (const chunk of stream) {
+ *   const updated = accumulateChunk(accumulator, chunk);
+ *   console.log('Accumulated so far:', updated.content);
+ * }
+ * ```
+ *
+ * @module streaming
+ */
+import type { IRChatStream, IRStreamChunk, StreamContentChunk, StreamDoneChunk, StreamErrorChunk, IRMessage, IRChatResponse, IRMetadata, IRUsage, FinishReason } from 'ai.matey.types';
+/**
+ * Accumulated stream state.
+ */
+export interface StreamAccumulator {
+    content: string;
+    role: 'assistant';
+    sequence: number;
+    metadata?: Partial<IRMetadata>;
+}
+/**
+ * Create a new stream accumulator.
+ *
+ * @returns Empty accumulator
+ */
+export declare function createStreamAccumulator(): StreamAccumulator;
+/**
+ * Accumulate a stream chunk.
+ *
+ * @param accumulator Current accumulator state
+ * @param chunk Stream chunk to accumulate
+ * @returns Updated accumulator
+ */
+export declare function accumulateChunk(accumulator: StreamAccumulator, chunk: IRStreamChunk): StreamAccumulator;
+/**
+ * Convert accumulated state to IR message.
+ *
+ * @param accumulator Stream accumulator
+ * @returns IR message
+ */
+export declare function accumulatorToMessage(accumulator: StreamAccumulator): IRMessage;
+/**
+ * Convert accumulated state and done chunk to IR response.
+ *
+ * @param accumulator Stream accumulator
+ * @param doneChunk Done chunk with finish reason and usage
+ * @param requestMetadata Original request metadata
+ * @returns IR chat response
+ */
+export declare function accumulatorToResponse(accumulator: StreamAccumulator, doneChunk: StreamDoneChunk, requestMetadata: IRMetadata): IRChatResponse;
+/**
+ * Transform stream chunks.
+ *
+ * @param stream Original stream
+ * @param transformer Transform function
+ * @returns Transformed stream
+ */
+export declare function transformStream(stream: IRChatStream, transformer: (chunk: IRStreamChunk) => IRStreamChunk | null): IRChatStream;
+/**
+ * Filter stream chunks.
+ *
+ * @param stream Original stream
+ * @param predicate Filter predicate
+ * @returns Filtered stream
+ */
+export declare function filterStream(stream: IRChatStream, predicate: (chunk: IRStreamChunk) => boolean): IRChatStream;
+/**
+ * Map stream chunks.
+ *
+ * @param stream Original stream
+ * @param mapper Mapping function
+ * @returns Mapped stream
+ */
+export declare function mapStream<T>(stream: IRChatStream, mapper: (chunk: IRStreamChunk) => T): AsyncGenerator<T, void, undefined>;
+/**
+ * Tap into stream without modifying it.
+ *
+ * @param stream Original stream
+ * @param callback Function to call for each chunk
+ * @returns Same stream
+ */
+export declare function tapStream(stream: IRChatStream, callback: (chunk: IRStreamChunk) => void | Promise<void>): IRChatStream;
+/**
+ * Collect all chunks from a stream.
+ *
+ * @param stream Stream to collect
+ * @returns Array of all chunks
+ */
+export declare function collectStream(stream: IRChatStream): Promise<IRStreamChunk[]>;
+/**
+ * Collect stream into a complete response.
+ *
+ * @param stream Stream to collect
+ * @param requestMetadata Original request metadata
+ * @returns Complete IR response
+ */
+export declare function streamToResponse(stream: IRChatStream, requestMetadata: IRMetadata): Promise<IRChatResponse>;
+/**
+ * Collect just the content text from a stream.
+ *
+ * @param stream Stream to collect
+ * @returns Complete text content
+ */
+export declare function streamToText(stream: IRChatStream): Promise<string>;
+/**
+ * Split a stream into multiple consumers.
+ *
+ * @param stream Original stream
+ * @param consumerCount Number of consumers
+ * @returns Array of streams, one per consumer
+ */
+export declare function splitStream(stream: IRChatStream, consumerCount: number): IRChatStream[];
+/**
+ * Wrap stream with error handling.
+ *
+ * @param stream Original stream
+ * @param onError Error handler
+ * @returns Wrapped stream
+ */
+export declare function catchStreamErrors(stream: IRChatStream, onError: (error: Error) => IRStreamChunk | null): IRChatStream;
+/**
+ * Add timeout to stream.
+ *
+ * @param stream Original stream
+ * @param timeoutMs Timeout in milliseconds
+ * @param onTimeout Callback when timeout occurs
+ * @returns Stream with timeout
+ */
+export declare function streamWithTimeout(stream: IRChatStream, timeoutMs: number, onTimeout: () => IRStreamChunk): IRChatStream;
+/**
+ * Check if a chunk is a content chunk.
+ */
+export declare function isContentChunk(chunk: IRStreamChunk): chunk is StreamContentChunk;
+/**
+ * Check if a chunk is a done chunk.
+ */
+export declare function isDoneChunk(chunk: IRStreamChunk): chunk is StreamDoneChunk;
+/**
+ * Check if a chunk is an error chunk.
+ */
+export declare function isErrorChunk(chunk: IRStreamChunk): chunk is StreamErrorChunk;
+/**
+ * Get content deltas from stream.
+ *
+ * @param stream Stream to process
+ * @returns Stream of just content deltas
+ */
+export declare function getContentDeltas(stream: IRChatStream): AsyncGenerator<string, void, undefined>;
+/**
+ * Convert an IR stream to a simple text iterator.
+ * Yields content deltas as strings and throws on errors.
+ *
+ * @example
+ * ```typescript
+ * for await (const text of streamToTextIterator(stream)) {
+ *   process.stdout.write(text);
+ * }
+ * ```
+ */
+export declare function streamToTextIterator(stream: IRChatStream): AsyncGenerator<string, void, undefined>;
+/**
+ * Validate chunk sequence numbers.
+ *
+ * Detects gaps or out-of-order chunks in a stream.
+ *
+ * @param chunks Array of chunks to validate
+ * @returns Validation result
+ */
+export interface SequenceValidationResult {
+    valid: boolean;
+    gaps: number[];
+    duplicates: number[];
+    outOfOrder: boolean;
+    expectedNext: number;
+}
+export declare function validateChunkSequence(chunks: IRStreamChunk[]): SequenceValidationResult;
+/**
+ * Create a validating stream wrapper.
+ *
+ * Validates chunk sequences and throws errors on invalid streams.
+ *
+ * @param stream Original stream
+ * @param options Validation options
+ * @returns Validated stream
+ */
+export interface StreamValidationOptions {
+    /**
+     * Throw error on sequence gaps.
+     * @default true
+     */
+    strictSequence?: boolean;
+    /**
+     * Throw error on duplicate sequences.
+     * @default true
+     */
+    rejectDuplicates?: boolean;
+    /**
+     * Maximum allowed gap before error.
+     * @default 0
+     */
+    maxGap?: number;
+    /**
+     * Callback for validation warnings.
+     */
+    onWarning?: (message: string) => void;
+}
+export declare function validateStream(stream: IRChatStream, options?: StreamValidationOptions): IRChatStream;
+/**
+ * Assemble stream chunks into a complete message.
+ *
+ * Alternative to streamToResponse that returns just the assembled message.
+ *
+ * @param stream Stream to assemble
+ * @returns Assembled message text
+ */
+export declare function assembleStreamChunks(stream: IRChatStream): Promise<string>;
+/**
+ * Create an error chunk.
+ *
+ * Helper for creating properly formatted error chunks.
+ *
+ * @param code Error code
+ * @param message Error message
+ * @param sequence Sequence number
+ * @param details Optional error details
+ * @returns Error chunk
+ */
+export declare function createStreamError(code: string, message: string, sequence: number, details?: Record<string, unknown>): StreamErrorChunk;
+/**
+ * Add backpressure control to stream.
+ *
+ * Buffers chunks and allows consumer to control flow.
+ *
+ * @param stream Original stream
+ * @param bufferSize Maximum buffer size before pausing
+ * @returns Stream with backpressure control
+ */
+export declare function streamWithBackpressure(stream: IRChatStream, bufferSize?: number): IRChatStream;
+/**
+ * Rate limit stream chunks.
+ *
+ * Ensures chunks are yielded at a maximum rate.
+ *
+ * @param stream Original stream
+ * @param chunksPerSecond Maximum chunks per second
+ * @returns Rate-limited stream
+ */
+export declare function rateLimitStream(stream: IRChatStream, chunksPerSecond: number): IRChatStream;
+/**
+ * Rich result from collecting a stream.
+ * Provides content, message, all chunks, and metadata.
+ */
+export interface CollectedStream {
+    /**
+     * Full accumulated text content.
+     */
+    readonly content: string;
+    /**
+     * The final message.
+     */
+    readonly message: IRMessage;
+    /**
+     * All chunks received.
+     */
+    readonly chunks: readonly IRStreamChunk[];
+    /**
+     * Finish reason from done chunk.
+     */
+    readonly finishReason: FinishReason;
+    /**
+     * Token usage if provided.
+     */
+    readonly usage?: IRUsage;
+    /**
+     * Request ID from start chunk.
+     */
+    readonly requestId?: string;
+}
+/**
+ * Collect a stream into a rich result with content, message, and metadata.
+ *
+ * @example
+ * ```typescript
+ * const stream = backend.executeStream(request);
+ * const result = await collectStreamFull(stream);
+ * console.log(result.content);
+ * console.log('Tokens:', result.usage?.totalTokens);
+ * ```
+ */
+export declare function collectStreamFull(stream: IRChatStream): Promise<CollectedStream>;
+/**
+ * Options for processing a stream with callbacks.
+ */
+export interface ProcessStreamOptions {
+    /**
+     * Called for each content chunk.
+     */
+    readonly onContent?: (delta: string, accumulated: string) => void;
+    /**
+     * Called when stream starts.
+     */
+    readonly onStart?: (requestId: string) => void;
+    /**
+     * Called when stream ends.
+     */
+    readonly onDone?: (result: CollectedStream) => void;
+    /**
+     * Called on error.
+     */
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Process a stream with callbacks while also returning the collected result.
+ *
+ * @example
+ * ```typescript
+ * const result = await processStream(stream, {
+ *   onContent: (delta) => process.stdout.write(delta),
+ *   onDone: () => console.log('\nDone!'),
+ * });
+ * ```
+ */
+export declare function processStream(stream: IRChatStream, options?: ProcessStreamOptions): Promise<CollectedStream>;
+/**
+ * Convert an IR stream to a line-by-line iterator.
+ * Buffers content and yields complete lines.
+ *
+ * @example
+ * ```typescript
+ * for await (const line of streamToLines(stream)) {
+ *   console.log('Line:', line);
+ * }
+ * ```
+ */
+export declare function streamToLines(stream: IRChatStream): AsyncGenerator<string, void, undefined>;
+/**
+ * Create a throttled version of a stream that limits how often chunks are yielded.
+ * Batches content chunks that arrive faster than the interval.
+ * Unlike rateLimitStream, this merges content chunks rather than delaying them.
+ *
+ * @param stream - The source stream
+ * @param intervalMs - Minimum milliseconds between yields
+ *
+ * @example
+ * ```typescript
+ * // Update UI at most every 50ms
+ * for await (const chunk of throttleStream(stream, 50)) {
+ *   updateUI(chunk);
+ * }
+ * ```
+ */
+export declare function throttleStream(stream: IRChatStream, intervalMs: number): IRChatStream;
+/**
+ * Split a stream into multiple streams that can be consumed independently.
+ * Each returned stream receives all chunks from the source.
+ * Alias for splitStream with a simpler interface.
+ *
+ * @param stream - The source stream
+ * @param count - Number of streams to create
+ *
+ * @example
+ * ```typescript
+ * const [stream1, stream2] = teeStream(originalStream, 2);
+ *
+ * // Consume independently
+ * const [result1, result2] = await Promise.all([
+ *   collectStreamFull(stream1),
+ *   processStream(stream2, { onContent: console.log }),
+ * ]);
+ * ```
+ */
+export declare function teeStream(stream: IRChatStream, count?: number): IRChatStream[];
+//# sourceMappingURL=streaming.d.ts.map

package/dist/types/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/streaming.ts"],"names":[],"mappings":"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"}

package/dist/types/structured-output.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Structured Output with Zod
+ *
+ * This module provides utilities for working with Zod schemas for structured LLM outputs.
+ * It includes:
+ * - Schema to tool definition conversion
+ * - Runtime validation
+ * - Type-safe object generation
+ * - Streaming with partial objects
+ *
+ * **IMPORTANT**: This module requires the optional peer dependency `zod` to be installed.
+ * Install it with: `npm install zod`
+ */
+/**
+ * OpenAI-compatible tool definition format
+ */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JSONSchema;
+    };
+}
+/**
+ * JSON Schema representation (subset used for tool definitions)
+ */
+export interface JSONSchema {
+    type: string;
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema;
+    enum?: string[];
+    required?: string[];
+    description?: string;
+}
+/**
+ * PII match information
+ */
+export interface PIIMatch {
+    type: string;
+    value: string;
+    start: number;
+    end: number;
+}
+/**
+ * PII detection result
+ */
+export interface PIIDetectionResult {
+    detected: boolean;
+    matches: PIIMatch[];
+}
+/**
+ * PII pattern configuration
+ */
+export interface PIIPattern {
+    type: string;
+    pattern: RegExp;
+    replacement: string;
+}
+/**
+ * Validation result
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: any[];
+};
+/**
+ * Convert a Zod schema to an OpenAI tool definition
+ *
+ * @param schema - Zod schema to convert
+ * @param name - Function name for the tool
+ * @param description - Description of what the tool does
+ * @returns OpenAI-compatible tool definition
+ */
+export declare function schemaToToolDefinition(schema: any, // Using any to avoid importing z.ZodType
+name?: string, description?: string): ToolDefinition;
+/**
+ * Validate data against a Zod schema
+ *
+ * @param data - Data to validate
+ * @param schema - Zod schema to validate against
+ * @returns Validation result with typed data or errors
+ */
+export declare function validateWithSchema<T = any>(data: unknown, schema: any): ValidationResult<T>;
+/**
+ * Default PII patterns for detection
+ */
+export declare const DEFAULT_PII_PATTERNS: PIIPattern[];
+/**
+ * Default prompt injection patterns
+ */
+export declare const DEFAULT_INJECTION_PATTERNS: RegExp[];
+/**
+ * Detect PII in text
+ */
+export declare function detectPII(text: string, patterns?: PIIPattern[]): PIIDetectionResult;
+/**
+ * Redact PII from text
+ */
+export declare function redactPII(text: string, patterns?: PIIPattern[]): string;
+/**
+ * Detect prompt injection attempts
+ */
+export declare function detectPromptInjection(text: string, patterns?: RegExp[]): boolean;
+/**
+ * Sanitize text by removing control characters
+ */
+export declare function sanitizeText(text: string): string;
+/**
+ * Options for generateObject
+ */
+export interface GenerateObjectOptions<T = any> {
+    schema: T;
+    prompt: string;
+    model?: string;
+    temperature?: number;
+    maxRetries?: number;
+}
+/**
+ * Result from generateObject
+ */
+export interface GenerateObjectResult<T> {
+    object: T;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string;
+}
+/**
+ * Options for streamObject
+ */
+export interface StreamObjectOptions<T = any> {
+    schema: T;
+    prompt: string;
+    model?: string;
+    onPartial?: (partial: Partial<T>) => void;
+}
+/**
+ * Create a generateObject function bound to a Bridge instance
+ *
+ * This is a factory function that creates a generateObject implementation
+ * that uses the provided Bridge for making LLM calls.
+ */
+export declare function createGenerateObject(bridge: any): <T = any>(options: GenerateObjectOptions) => Promise<GenerateObjectResult<T>>;
+/**
+ * Create a streamObject function bound to a Bridge instance
+ *
+ * This is a factory function that creates a streamObject implementation
+ * that uses the provided Bridge for making streaming LLM calls.
+ */
+export declare function createStreamObject(bridge: any): <T = any>(options: StreamObjectOptions) => AsyncGenerator<Partial<T>, T>;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/types/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../../src/structured-output.ts"],"names":[],"mappings":"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"}