@od-oneapp/ai-platform 0.1.0

package/src/output/errors.ts

@@ -0,0 +1,108 @@
+/**
+ * NoObjectGeneratedError helpers and recovery strategies.
+ */
+
+import { NoObjectGeneratedError } from '../shared';
+
+export type NoObjectCause = 'no-object' | 'unknown';
+
+export interface NoObjectErrorInfo {
+  cause: NoObjectCause;
+  message: string;
+  text?: string;
+  usage?: Record<string, number>;
+}
+
+export interface HandleNoObjectOptions<T> {
+  fallback?: T | ((info: NoObjectErrorInfo) => T);
+  onError?: (info: NoObjectErrorInfo) => void;
+}
+
+export interface HandleNoObjectResult<T> {
+  handled: boolean;
+  result?: T;
+  error?: Error;
+  info?: NoObjectErrorInfo;
+}
+
+export interface NoObjectHandlerConfig<T> extends HandleNoObjectOptions<T> {
+  throwOnUnhandled?: boolean;
+}
+
+export type NoObjectHandler<T> = (error: unknown) => HandleNoObjectResult<T>;
+
+export interface StreamErrorHandlerOptions {
+  fallbackText?: string;
+  onError?: (info: NoObjectErrorInfo) => void;
+}
+
+export const ErrorRecoveryStrategies = {
+  fallback: <T>(fallback: T): HandleNoObjectOptions<T> => ({ fallback }),
+  ignore: <T>(): HandleNoObjectOptions<T> => ({}),
+};
+
+export function isNoObjectGeneratedError(error: unknown): error is NoObjectGeneratedError {
+  return NoObjectGeneratedError.isInstance(error);
+}
+
+export function handleNoObjectGenerated<T>(
+  error: NoObjectGeneratedError,
+  options: HandleNoObjectOptions<T> = {},
+): HandleNoObjectResult<T> {
+  const info: NoObjectErrorInfo = {
+    cause: 'no-object',
+    message: error.message,
+    text: error.text,
+    usage: error.usage as Record<string, number> | undefined,
+  };
+
+  options.onError?.(info);
+
+  if (options.fallback !== undefined) {
+    const value =
+      typeof options.fallback === 'function'
+        ? (options.fallback as (details: NoObjectErrorInfo) => T)(info)
+        : options.fallback;
+    return { handled: true, result: value, info };
+  }
+
+  return { handled: false, error };
+}
+
+export function createNoObjectHandler<T>(
+  config: NoObjectHandlerConfig<T> = {},
+): NoObjectHandler<T> {
+  return (error: unknown) => {
+    if (!isNoObjectGeneratedError(error)) {
+      return {
+        handled: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+
+    const result = handleNoObjectGenerated(error, config);
+    if (!result.handled && config.throwOnUnhandled) {
+      throw error;
+    }
+    return result;
+  };
+}
+
+export function createStreamErrorHandler(options: StreamErrorHandlerOptions = {}) {
+  return (error: unknown): string => {
+    if (isNoObjectGeneratedError(error)) {
+      const info: NoObjectErrorInfo = {
+        cause: 'no-object',
+        message: error.message,
+        text: error.text,
+        usage: error.usage as Record<string, number> | undefined,
+      };
+      options.onError?.(info);
+      return options.fallbackText ?? error.text ?? '';
+    }
+
+    return options.fallbackText ?? '';
+  };
+}
+
+export { NoObjectGeneratedError };

package/src/output/factories.ts

@@ -0,0 +1,392 @@
+/**
+ * @fileoverview Output API factories for structured output generation.
+ * @module @od-oneapp/ai-platform/output
+ */
+
+import { logWarn } from '@repo/shared/logs';
+import { z, type ZodType } from 'zod';
+
+import { Output, generateObject, streamObject, NoObjectGeneratedError } from '../shared';
+
+import type { SDKLanguageModelV3 } from '../shared';
+
+/**
+ * Creates a typed object output configuration.
+ *
+ * @param schema - Zod schema for the output
+ * @returns Output configuration for use with streamText/generateText
+ *
+ * @example
+ * ```ts
+ * const PersonOutput = createObjectOutput(z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * }));
+ *
+ * const result = await streamText({
+ *   model,
+ *   prompt: 'Extract person info',
+ *   output: PersonOutput,
+ * });
+ * ```
+ */
+export function createObjectOutput<T extends ZodType>(schema: T): ReturnType<typeof Output.object> {
+  return Output.object({ schema });
+}
+
+/**
+ * Creates a typed array output configuration with element streaming.
+ *
+ * @param schema - Zod schema for array elements
+ * @returns Output configuration for array streaming
+ *
+ * @example
+ * ```ts
+ * const TodosOutput = createArrayOutput(z.object({
+ *   task: z.string(),
+ *   done: z.boolean(),
+ * }));
+ *
+ * const result = await streamText({
+ *   model,
+ *   prompt: 'List todos',
+ *   output: TodosOutput,
+ * });
+ *
+ * // Stream individual elements
+ * for await (const todo of result.output.elementStream) {
+ *   console.log('Got todo:', todo);
+ * }
+ * ```
+ */
+export function createArrayOutput<T extends ZodType>(schema: T): ReturnType<typeof Output.array> {
+  return Output.array({ element: schema });
+}
+
+/**
+ * Creates a choice output for classification tasks using Zod enum.
+ *
+ * @param values - Array of valid choices
+ * @returns Zod enum schema for use with generateObject
+ *
+ * @example
+ * ```ts
+ * const SentimentSchema = createChoiceSchema(['positive', 'negative', 'neutral'] as const);
+ *
+ * const { object } = await generateObject({
+ *   model,
+ *   schema: z.object({ sentiment: SentimentSchema }),
+ *   prompt: 'Classify sentiment: "I love this!"',
+ * });
+ * // object.sentiment === 'positive'
+ * ```
+ */
+export function createChoiceSchema<T extends readonly [string, ...string[]]>(values: T) {
+  return z.enum(values);
+}
+
+/**
+ * Structured output helper that generates a single object.
+ *
+ * @param model - Language model to use
+ * @param schema - Zod schema for output
+ * @param prompt - Generation prompt
+ * @returns Generated object matching schema
+ */
+export async function generateStructuredObject<T extends ZodType>(
+  model: SDKLanguageModelV3,
+  schema: T,
+  prompt: string,
+) {
+  const { object } = await generateObject({
+    model,
+    schema,
+    prompt,
+  });
+  return object as z.infer<T>;
+}
+
+/**
+ * Structured output helper that streams an object.
+ *
+ * @param model - Language model to use
+ * @param schema - Zod schema for output
+ * @param prompt - Generation prompt
+ * @returns Stream result with partial object stream
+ */
+export function streamStructuredObject<T extends ZodType>(
+  model: SDKLanguageModelV3,
+  schema: T,
+  prompt: string,
+) {
+  return streamObject({
+    model,
+    schema,
+    prompt,
+  });
+}
+
+/**
+ * Schema builder utilities for common patterns.
+ */
+export const SchemaBuilders = {
+  /**
+   * Creates a schema for a list of items with metadata.
+   */
+  listWithMeta<T extends ZodType>(itemSchema: T) {
+    return z.object({
+      items: z.array(itemSchema),
+      total: z.number(),
+      hasMore: z.boolean().optional(),
+    });
+  },
+
+  /**
+   * Creates a schema for a result with optional error.
+   */
+  resultOrError<T extends ZodType>(successSchema: T) {
+    return z.discriminatedUnion('success', [
+      z.object({ success: z.literal(true), data: successSchema }),
+      z.object({ success: z.literal(false), error: z.string() }),
+    ]);
+  },
+
+  /**
+   * Creates a schema for classification with confidence.
+   */
+  classificationWithConfidence<T extends readonly string[]>(categories: T) {
+    return z.object({
+      category: z.enum(categories as unknown as [string, ...string[]]),
+      confidence: z.number().min(0).max(1),
+      reasoning: z.string().optional(),
+    });
+  },
+
+  /**
+   * Creates a schema for extracted entities.
+   */
+  entities<T extends Record<string, ZodType>>(entitySchemas: T) {
+    return z.object({
+      entities: z.object(entitySchemas),
+      raw: z.string().optional(),
+    });
+  },
+
+  /**
+   * Creates a schema for a step-by-step plan.
+   */
+  plan() {
+    return z.object({
+      steps: z.array(
+        z.object({
+          step: z.number(),
+          action: z.string(),
+          reasoning: z.string().optional(),
+          dependencies: z.array(z.number()).optional(),
+        }),
+      ),
+      summary: z.string(),
+    });
+  },
+};
+
+// -----------------------------------------------------------------------------
+// NoObjectGeneratedError Handling
+// -----------------------------------------------------------------------------
+
+/**
+ * Result of safe structured generation with error info.
+ */
+export interface SafeGenerateResult<T> {
+  success: boolean;
+  object?: T;
+  partialObject?: Partial<T>;
+  error?: NoObjectGeneratedError | Error;
+  text?: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/**
+ * Safe structured object generation with NoObjectGeneratedError handling.
+ * Returns a result object instead of throwing.
+ *
+ * @example
+ * ```typescript
+ * const result = await safeGenerateObject({
+ *   model,
+ *   schema: z.object({ name: z.string() }),
+ *   prompt: 'Extract name from: Hello!',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.object.name);
+ * } else {
+ *   console.log('Failed:', result.error?.message);
+ *   console.log('Raw text:', result.text);
+ * }
+ * ```
+ */
+export async function safeGenerateObject<T extends ZodType>(
+  options: Parameters<typeof generateObject<T>>[0],
+): Promise<SafeGenerateResult<z.infer<T>>> {
+  try {
+    const { object, usage } = await generateObject(options);
+    const usageRecord = (usage ?? {}) as unknown as {
+      promptTokens?: number;
+      completionTokens?: number;
+      totalTokens?: number;
+    };
+    return {
+      success: true,
+      object: object as z.infer<T>,
+      usage: {
+        promptTokens: usageRecord.promptTokens ?? 0,
+        completionTokens: usageRecord.completionTokens ?? 0,
+        totalTokens: usageRecord.totalTokens ?? 0,
+      },
+    };
+  } catch (error) {
+    if (error instanceof NoObjectGeneratedError) {
+      logWarn(`[safeGenerateObject] No object generated: ${error.message}`);
+      const errorUsage = error.usage as Record<string, number> | undefined;
+      const possiblePartial = (error as unknown as { partialObject?: unknown }).partialObject;
+      const partialObject =
+        typeof possiblePartial === 'object' && possiblePartial !== null
+          ? (possiblePartial as Partial<z.infer<T>>)
+          : (extractPartialFromError<z.infer<T>>(error) ?? undefined);
+      return {
+        success: false,
+        error,
+        text: error.text,
+        partialObject,
+        usage: errorUsage
+          ? {
+              promptTokens: errorUsage.promptTokens ?? 0,
+              completionTokens: errorUsage.completionTokens ?? 0,
+              totalTokens: errorUsage.totalTokens ?? 0,
+            }
+          : undefined,
+      };
+    }
+
+    // Re-throw non-NoObjectGeneratedError
+    return {
+      success: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}
+
+/**
+ * Generate object with fallback value on failure.
+ *
+ * @example
+ * ```typescript
+ * const person = await generateObjectWithFallback({
+ *   model,
+ *   schema: z.object({ name: z.string(), age: z.number() }),
+ *   prompt: 'Extract person info',
+ *   fallback: { name: 'Unknown', age: 0 },
+ * });
+ * ```
+ */
+export async function generateObjectWithFallback<T extends ZodType>(
+  options: Parameters<typeof generateObject<T>>[0] & {
+    fallback: z.infer<T>;
+  },
+): Promise<z.infer<T>> {
+  const { fallback, ...generateOptions } = options;
+  // Cast to fix SDK type incompatibility
+  const result = await safeGenerateObject(
+    generateOptions as Parameters<typeof generateObject<T>>[0],
+  );
+
+  if (result.success && result.object !== undefined) {
+    return result.object as z.infer<T>;
+  }
+
+  logWarn(`[generateObjectWithFallback] Using fallback value`);
+  return fallback;
+}
+
+/**
+ * Generate object with retry on failure.
+ *
+ * @example
+ * ```typescript
+ * const person = await generateObjectWithRetry({
+ *   model,
+ *   schema: z.object({ name: z.string() }),
+ *   prompt: 'Extract name',
+ *   maxRetries: 3,
+ *   onRetry: (attempt, error) => console.log(`Retry ${attempt}:`, error.message),
+ * });
+ * ```
+ */
+export async function generateObjectWithRetry<T extends ZodType>(
+  options: Parameters<typeof generateObject<T>>[0] & {
+    maxRetries?: number;
+    retryDelay?: number;
+    onRetry?: (attempt: number, error: Error) => void;
+  },
+): Promise<z.infer<T>> {
+  const { maxRetries = 3, retryDelay = 1000, onRetry, ...generateOptions } = options;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    // Cast to fix SDK type incompatibility
+    const result = await safeGenerateObject(
+      generateOptions as Parameters<typeof generateObject<T>>[0],
+    );
+
+    if (result.success && result.object !== undefined) {
+      return result.object as z.infer<T>;
+    }
+
+    lastError = result.error ?? new Error('Unknown error');
+
+    if (attempt < maxRetries) {
+      onRetry?.(attempt + 1, lastError);
+      await new Promise(resolve => setTimeout(resolve, retryDelay * (attempt + 1)));
+    }
+  }
+
+  throw lastError ?? new Error('Failed to generate object after retries');
+}
+
+/**
+ * Check if an error is a NoObjectGeneratedError.
+ */
+export function isNoObjectGeneratedError(error: unknown): error is NoObjectGeneratedError {
+  return error instanceof NoObjectGeneratedError;
+}
+
+/**
+ * Extract partial data from NoObjectGeneratedError.
+ * Attempts to parse partial JSON from the raw text.
+ */
+export function extractPartialFromError<T>(error: NoObjectGeneratedError): Partial<T> | null {
+  const { text } = error;
+  if (!text) return null;
+
+  // Try to find JSON-like content
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return null;
+
+  try {
+    return JSON.parse(jsonMatch[0]) as Partial<T>;
+  } catch {
+    return null;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Re-export NoObjectGeneratedError for convenience
+// -----------------------------------------------------------------------------
+
+export { NoObjectGeneratedError };

package/src/output/index.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Output API factories for structured output generation.
+ * @module @od-oneapp/ai-platform/output
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createObjectOutput,
+ *   createArrayOutput,
+ *   createChoiceOutput,
+ *   SchemaBuilders,
+ *   // Element streaming
+ *   streamArrayElements,
+ *   // Error handling
+ *   safeGenerateObject,
+ * } from '@od-oneapp/ai-platform/output';
+ *
+ * // Object output
+ * const PersonOutput = createObjectOutput(z.object({ name: z.string() }));
+ *
+ * // Array output with element streaming
+ * const TodosOutput = createArrayOutput(z.object({ task: z.string() }));
+ *
+ * // Choice/enum output
+ * const SentimentOutput = createChoiceOutput(['positive', 'negative', 'neutral']);
+ *
+ * // Schema builders for common patterns
+ * const ClassificationSchema = SchemaBuilders.classificationWithConfidence(['spam', 'ham']);
+ * ```
+ */
+
+export {
+  createObjectOutput,
+  createArrayOutput,
+  createChoiceSchema,
+  generateStructuredObject,
+  streamStructuredObject,
+  SchemaBuilders,
+  // NoObjectGeneratedError handling
+  safeGenerateObject,
+  generateObjectWithFallback,
+  generateObjectWithRetry,
+} from './factories';
+
+// Element streaming
+export {
+  streamElements,
+  streamElementsWithProgress,
+  streamElementsInBatches,
+  createElementStreamer,
+  collectElements,
+  // withElementStream composable wrapper
+  withElementStream,
+  collectFromElementStream,
+  type ElementStreamEvent,
+  type ElementStreamOptions,
+  type ElementStreamResult,
+  type PartialElementStreamOptions,
+  type BatchedElementStreamOptions,
+  type WithElementStreamConfig,
+  type ExperimentalOutputStreamResult,
+} from './element-stream';
+
+// Output validation
+export {
+  createOutputValidator,
+  createStrictValidator,
+  createPartialValidator,
+  isOutputValidationError,
+  OutputValidationError,
+  type OutputValidatorConfig,
+  type ValidationErrorStrategy,
+  type RetryContext,
+  type PartialValidationResult,
+  type OutputValidator,
+} from './validator';
+
+// NoObjectGeneratedError utilities (extended)
+export {
+  // Re-export from errors module
+  NoObjectGeneratedError,
+  isNoObjectGeneratedError,
+  handleNoObjectGenerated,
+  createNoObjectHandler,
+  createStreamErrorHandler,
+  ErrorRecoveryStrategies,
+  // Types
+  type NoObjectCause,
+  type NoObjectErrorInfo,
+  type HandleNoObjectOptions,
+  type HandleNoObjectResult,
+  type NoObjectHandlerConfig,
+  type NoObjectHandler,
+  type StreamErrorHandlerOptions,
+} from './errors';
+
+// Multimodal output (audio, speech, transcription)
+export * as multimodal from "./multimodal";