@od-oneapp/ai-platform 0.1.0

package/src/internal/ui-factories/types.ts

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview UI Factories Type Definitions
+ *
+ * React-agnostic types for tool UI rendering and status messages.
+ * Provides type-safe interfaces for building AI chat interfaces.
+ *
+ * @module ui-factories/types
+ */
+
+// -----------------------------------------------------------------------------
+// Tool UI Renderer Types
+// -----------------------------------------------------------------------------
+
+/** State of a tool invocation for UI rendering */
+export type ToolUIState = 'pending' | 'running' | 'complete' | 'error';
+
+/**
+ * Configuration for a single tool's UI rendering.
+ */
+export interface ToolUIConfig {
+  /** Label shown while the tool is pending or running */
+  readonly pendingLabel: string;
+  /** Function that returns the label shown when the tool completes */
+  readonly completeLabel: (result: unknown) => string;
+  /** Optional icon identifier for the tool */
+  readonly icon?: string;
+}
+
+/**
+ * Configuration for the tool UI renderer factory.
+ */
+export interface ToolUIRendererConfig {
+  /** Map of tool names to their UI configurations */
+  readonly tools: Readonly<Record<string, ToolUIConfig>>;
+  /** Fallback configuration for unknown tools */
+  readonly fallback?: Readonly<{
+    /** Label shown for unknown tools */
+    pendingLabel: string;
+    /** Optional icon for unknown tools */
+    icon?: string;
+  }>;
+}
+
+/**
+ * Result from the tool UI renderer.
+ */
+export interface ToolUIResult {
+  /** The label to display */
+  readonly label: string;
+  /** The icon identifier (if any) */
+  readonly icon?: string;
+  /** The current state */
+  readonly state: ToolUIState;
+}
+
+/**
+ * Tool UI renderer instance.
+ */
+export interface ToolUIRenderer {
+  /**
+   * Get the UI representation for a tool.
+   *
+   * @param toolName - The name of the tool
+   * @param state - The current state of the tool invocation
+   * @param result - The result of the tool (for complete state)
+   * @returns The UI result with label, icon, and state
+   */
+  getToolUI(toolName: string, state: ToolUIState, result?: unknown): ToolUIResult;
+
+  /**
+   * Check if a tool has a custom configuration.
+   *
+   * @param toolName - The name of the tool to check
+   * @returns True if the tool has a custom configuration
+   */
+  hasToolConfig(toolName: string): boolean;
+
+  /**
+   * Get all configured tool names.
+   *
+   * @returns Array of configured tool names
+   */
+  getConfiguredTools(): string[];
+}
+
+// -----------------------------------------------------------------------------
+// Status Message Types
+// -----------------------------------------------------------------------------
+
+/** Types of status messages */
+export type StatusType = 'thinking' | 'toolCalling' | 'complete' | 'error';
+
+/**
+ * Context for status message generation.
+ */
+export interface StatusContext {
+  /** The agent name (will be looked up in config.agents) */
+  readonly agent?: string;
+  /** The tool name (for toolCalling status) */
+  readonly toolName?: string;
+  /** The error object (for error status) */
+  readonly error?: Error;
+}
+
+/**
+ * Custom message configuration for status helper.
+ */
+export interface StatusMessages {
+  /** Message shown when the agent is thinking */
+  readonly thinking?: string;
+  /** Function that returns message when calling a tool */
+  readonly toolCalling?: (toolName: string) => string;
+  /** Message shown when complete */
+  readonly complete?: string;
+  /** Function that returns message for errors */
+  readonly error?: (err: Error) => string;
+}
+
+/**
+ * Configuration for the status message helper factory.
+ */
+export interface StatusMessageConfig {
+  /** Map of agent IDs to display names */
+  readonly agents?: Readonly<Record<string, string>>;
+  /** Custom status messages */
+  readonly messages?: Readonly<StatusMessages>;
+}
+
+/**
+ * Status message helper instance.
+ */
+export interface StatusMessageHelper {
+  /**
+   * Get the status message for a given status type and context.
+   *
+   * @param type - The type of status message
+   * @param context - Additional context for the message
+   * @returns The formatted status message
+   */
+  getMessage(type: StatusType, context?: StatusContext): string;
+
+  /**
+   * Get the display name for an agent.
+   *
+   * @param agentId - The agent ID to look up
+   * @returns The display name or the original ID if not found
+   */
+  getAgentDisplayName(agentId: string): string;
+}
+
+// -----------------------------------------------------------------------------
+// Tool Shimmer Manager Types
+// -----------------------------------------------------------------------------
+
+/** States that can trigger shimmer display */
+export type ShimmerState = 'tool-call' | 'tool-result' | 'thinking';
+
+/**
+ * Configuration for the tool shimmer manager factory.
+ */
+export interface ToolShimmerManagerConfig {
+  /** Debounce time in milliseconds for state changes */
+  readonly debounceMs?: number;
+  /** States that should show the shimmer */
+  readonly showShimmerDuring?: readonly ShimmerState[];
+}
+
+/**
+ * A message part for shimmer state detection.
+ */
+export interface MessagePart {
+  /** The type of the message part */
+  readonly type: string;
+  /** The state of the part (for tool invocations) */
+  readonly state?: string;
+  /** Additional data */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Tool shimmer manager instance.
+ */
+export interface ToolShimmerManager {
+  /**
+   * Determine if the shimmer should be shown based on message parts.
+   *
+   * @param parts - Array of message parts to check
+   * @returns True if shimmer should be shown
+   */
+  shouldShow(parts: readonly MessagePart[]): boolean;
+
+  /**
+   * Update internal state with new message parts.
+   * Respects debounce configuration.
+   *
+   * @param parts - Array of message parts
+   */
+  update(parts: readonly MessagePart[]): void;
+
+  /**
+   * Reset the manager state.
+   */
+  reset(): void;
+
+  /**
+   * Get the current shimmer visibility state.
+   *
+   * @returns True if shimmer is currently showing
+   */
+  isShowing(): boolean;
+}
+
+// -----------------------------------------------------------------------------
+// Default Values
+// -----------------------------------------------------------------------------
+
+/** Default debounce time for shimmer manager */
+export const DEFAULT_DEBOUNCE_MS = 100;
+
+/** Default states that show shimmer */
+export const DEFAULT_SHIMMER_STATES: readonly ShimmerState[] = ['tool-call', 'tool-result'];
+
+/** Default status messages */
+export const DEFAULT_STATUS_MESSAGES: Required<StatusMessages> = {
+  thinking: 'Thinking...',
+  toolCalling: (toolName: string) => `Using ${toolName}...`,
+  complete: 'Done',
+  error: (err: Error) => `Error: ${err.message}`,
+} as const;
+
+/** Default fallback for unknown tools */
+export const DEFAULT_TOOL_FALLBACK = {
+  pendingLabel: 'Processing...',
+  icon: 'cog',
+} as const;

package/src/models/capabilities.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Cross-provider model capability detection
+ *
+ * Provides unified capability checks that work across all providers
+ * by combining the high-level MODEL_METADATA registry with
+ * provider-specific capability data.
+ *
+ * @module @od-oneapp/ai-platform/models/capabilities
+ */
+
+import { ANTHROPIC_MODEL_GROUPS } from './providers/anthropic';
+import { OPENAI_MODEL_GROUPS } from './providers/openai';
+import { PERPLEXITY_MODEL_GROUPS } from './providers/perplexity';
+import { MODEL_METADATA, Model } from './registry';
+
+// Collect all known reasoning model IDs from provider configs
+const REASONING_MODEL_IDS = new Set<string>([
+  // Anthropic reasoning models
+  ...ANTHROPIC_MODEL_GROUPS.REASONING_MODELS,
+  // OpenAI reasoning models
+  ...OPENAI_MODEL_GROUPS.REASONING_MODELS,
+  // Perplexity reasoning models
+  ...PERPLEXITY_MODEL_GROUPS.REASONING_MODELS,
+]);
+
+// Also include any models with tier === 'reasoning' from the registry
+for (const model of Object.values(Model)) {
+  const meta = MODEL_METADATA[model as Model];
+  if (meta?.tier === 'reasoning') {
+    REASONING_MODEL_IDS.add(meta.id);
+  }
+}
+
+/**
+ * Check if a model supports reasoning/thinking capabilities.
+ *
+ * Checks both the registry (tier === 'reasoning') and provider-specific
+ * reasoning model lists (Anthropic extended thinking, OpenAI o-series, etc.).
+ *
+ * @param modelId - Provider-specific model ID string (e.g. 'claude-opus-4-20250514', 'o1')
+ * @returns true if the model has reasoning/thinking capabilities
+ *
+ * @example
+ * ```ts
+ * import { modelSupportsReasoning } from '@od-oneapp/ai-platform/models';
+ *
+ * if (modelSupportsReasoning('claude-opus-4-20250514')) {
+ *   // Enable extended thinking budget
+ * }
+ * ```
+ */
+export function modelSupportsReasoning(modelId: string): boolean {
+  return REASONING_MODEL_IDS.has(modelId);
+}
+
+/**
+ * Check if a model supports tool usage.
+ *
+ * @param modelId - Provider-specific model ID string
+ * @returns true if the model supports tools
+ */
+export function modelSupportsTools(modelId: string): boolean {
+  for (const model of Object.values(Model)) {
+    const meta = MODEL_METADATA[model as Model];
+    if (meta?.id === modelId) {
+      return meta.supportsTools;
+    }
+  }
+  // Unknown model - assume tools supported for modern models
+  return true;
+}
+
+/**
+ * Check if a model supports streaming.
+ *
+ * @param modelId - Provider-specific model ID string
+ * @returns true if the model supports streaming
+ */
+export function modelSupportsStreaming(modelId: string): boolean {
+  for (const model of Object.values(Model)) {
+    const meta = MODEL_METADATA[model as Model];
+    if (meta?.id === modelId) {
+      return meta.supportsStreaming;
+    }
+  }
+  // Unknown model - assume streaming supported for modern models
+  return true;
+}

package/src/models/index.ts

@@ -0,0 +1,16 @@
+export { Model, MODEL_METADATA, getModelId, getModelMetadata } from './registry';
+export {
+  createLanguageModel,
+  getModelsByTier,
+  getModelTier,
+  getCheapestModel,
+  estimateCost,
+  type CreateLanguageModelOptions,
+} from './provider-factory';
+export type { Gateway, ModelTier, ModelMetadata } from './types';
+
+// Cross-provider capability detection
+export { modelSupportsReasoning, modelSupportsTools, modelSupportsStreaming } from './capabilities';
+
+// Provider configurations (namespaced to avoid conflicts)
+export * from './providers';

package/src/models/provider-factory.ts

@@ -0,0 +1,229 @@
+import {
+  anthropic,
+  createAnthropic,
+  createGoogleGenerativeAI,
+  google,
+  createOpenAI,
+  openai,
+  createXai,
+  createOpenAICompatible,
+  type SDKLanguageModel,
+} from '../shared';
+
+import { type Model, getModelId, getModelMetadata, MODEL_METADATA } from './registry';
+
+import type { Gateway, ModelTier } from './types';
+
+/**
+ * Options for creating a language model instance.
+ */
+export interface CreateLanguageModelOptions {
+  /**
+   * Bypass gateway and use native provider directly
+   * @default false (uses gateway from AI_GATEWAY env var)
+   */
+  useNative?: boolean;
+}
+
+/**
+ * Creates an AI SDK LanguageModel instance for a semantic model name.
+ *
+ * By default, routes through the configured gateway (AI_GATEWAY env var).
+ * Use `useNative: true` to bypass gateway and connect directly to the provider.
+ *
+ * @param model - Semantic model name from the {@link Model} enum
+ * @param options - Optional configuration for gateway routing
+ * @returns AI SDK LanguageModel instance ready for use with generateText/streamText
+ *
+ * @example
+ * ```ts
+ * // Uses gateway (default)
+ * const model = createLanguageModel(Model.SONNET);
+ * const { text } = await generateText({ model, prompt: "Hello" });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Bypass gateway for direct provider connection
+ * const model = createLanguageModel(Model.SONNET, { useNative: true });
+ * ```
+ */
+export function createLanguageModel(
+  model: Model,
+  options?: CreateLanguageModelOptions,
+): SDKLanguageModel {
+  const modelId = getModelId(model);
+  const metadata = getModelMetadata(model);
+  const useNative = options?.useNative ?? false;
+
+  // Determine gateway from environment
+  const configuredGateway = process.env.AI_GATEWAY as Gateway | undefined;
+
+  // Use gateway by default unless useNative is true
+  if (!useNative && configuredGateway) {
+    if (configuredGateway === 'cloudflare') {
+      return getCloudflareProvider(model);
+    }
+    if (configuredGateway === 'vercel') {
+      return getVercelGatewayProvider(model);
+    }
+  }
+
+  // Native/direct provider routing
+  switch (metadata.provider) {
+    case 'anthropic':
+      return anthropic(modelId);
+    case 'openai':
+      return openai(modelId);
+    case 'google':
+      return google(modelId);
+    case 'xai':
+      return createXai()(modelId);
+    case 'perplexity': {
+      const apiKey = process.env.PERPLEXITY_API_KEY;
+      if (!apiKey) {
+        throw new Error('PERPLEXITY_API_KEY is required for Perplexity provider');
+      }
+      return createOpenAICompatible({
+        name: 'perplexity',
+        baseURL: 'https://api.perplexity.ai',
+        apiKey,
+      })(modelId);
+    }
+    default:
+      throw new Error(`Unsupported provider: ${metadata.provider}`);
+  }
+}
+
+/**
+ * Get model through Cloudflare AI Gateway
+ */
+function getCloudflareProvider(model: Model): SDKLanguageModel {
+  const modelId = getModelId(model);
+  const metadata = getModelMetadata(model);
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const gatewayName = process.env.CLOUDFLARE_AI_GATEWAY_NAME || 'ai-gateway';
+
+  if (!accountId) {
+    throw new Error('CLOUDFLARE_ACCOUNT_ID required for Cloudflare gateway');
+  }
+
+  const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayName}/${metadata.provider}`;
+
+  // Use provider-specific SDK with Cloudflare gateway URL
+  switch (metadata.provider) {
+    case 'anthropic':
+      return createAnthropic({ baseURL })(modelId);
+    case 'openai':
+      return createOpenAI({ baseURL })(modelId);
+    case 'google':
+      return createGoogleGenerativeAI({ baseURL })(modelId);
+    case 'perplexity':
+    case 'xai':
+      throw new Error(`Cloudflare gateway not supported for ${metadata.provider}`);
+    default:
+      throw new Error(`Cloudflare gateway not supported for ${metadata.provider}`);
+  }
+}
+
+/**
+ * Get model through Vercel AI Gateway
+ */
+function getVercelGatewayProvider(model: Model): SDKLanguageModel {
+  const modelId = getModelId(model);
+  const metadata = getModelMetadata(model);
+  const apiKey = process.env.AI_GATEWAY_API_KEY;
+  const baseURL = process.env.AI_GATEWAY_BASE_URL || 'https://gateway.ai.vercel.com';
+
+  if (!apiKey) {
+    throw new Error('AI_GATEWAY_API_KEY required for Vercel gateway');
+  }
+
+  // Route through Vercel gateway
+  switch (metadata.provider) {
+    case 'anthropic':
+      return createAnthropic({ baseURL, apiKey, headers: { 'x-api-key': apiKey } })(modelId);
+    case 'openai':
+      return createOpenAI({ baseURL, apiKey, headers: { 'x-api-key': apiKey } })(modelId);
+    case 'google':
+    case 'perplexity':
+    case 'xai':
+      throw new Error(`Vercel gateway not supported for ${metadata.provider}`);
+    default:
+      throw new Error(`Vercel gateway not supported for ${metadata.provider}`);
+  }
+}
+
+/**
+ * Returns all models classified under a given performance tier.
+ *
+ * @param tier - The tier to filter by (e.g., 'fast', 'balanced', 'powerful')
+ * @returns Array of Model enum values matching the tier
+ */
+export function getModelsByTier(tier: ModelTier): Model[] {
+  return Object.entries(MODEL_METADATA)
+    .filter(([, metadata]) => metadata.tier === tier)
+    .map(([model]) => model as Model);
+}
+
+/**
+ * Get the tier classification for a model
+ *
+ * @param model - Semantic model name
+ * @returns Model tier classification
+ */
+export function getModelTier(model: Model): ModelTier {
+  const metadata = getModelMetadata(model);
+  return metadata.tier;
+}
+
+/**
+ * Estimate cost for a generation based on token usage
+ *
+ * @param model - Semantic model name
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @returns Estimated cost in USD
+ */
+export function estimateCost(model: Model, inputTokens: number, outputTokens: number): number {
+  const metadata = getModelMetadata(model);
+  const inputCost = (inputTokens / 1000) * metadata.costPer1kInput;
+  const outputCost = (outputTokens / 1000) * metadata.costPer1kOutput;
+  return inputCost + outputCost;
+}
+
+/**
+ * Finds the cheapest model that satisfies the given capability requirements.
+ *
+ * @param options - Required capabilities and constraints
+ * @returns The least expensive Model matching all requirements
+ * @throws Error if no models satisfy the requirements
+ */
+export function getCheapestModel(options: {
+  supportsTools?: boolean;
+  supportsStreaming?: boolean;
+  minContextWindow?: number;
+}): Model {
+  const candidates = Object.entries(MODEL_METADATA)
+    .filter(([, metadata]) => {
+      if (options.supportsTools && !metadata.supportsTools) return false;
+      if (options.supportsStreaming && !metadata.supportsStreaming) return false;
+      if (
+        options.minContextWindow !== undefined &&
+        metadata.contextWindow < options.minContextWindow
+      )
+        return false;
+      return true;
+    })
+    .sort((a, b) => a[1].costPer1kInput - b[1].costPer1kInput);
+
+  if (candidates.length === 0) {
+    throw new Error('No models match the specified requirements');
+  }
+
+  const [model] = candidates[0] ?? [];
+  if (!model) {
+    throw new Error('No models match the specified requirements');
+  }
+  return model as Model;
+}