@od-oneapp/ai-platform 0.1.0

package/src/models/providers/xai.ts

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview xAI Grok provider configuration
+ *
+ * Provider-specific model IDs, option helpers, capability detection,
+ * and metadata extraction for xAI Grok models.
+ *
+ * All AI SDK imports come from the shared module.
+ *
+ * @module @od-oneapp/ai-platform/models/providers/xai
+ */
+
+import { createXai, xai } from '../../shared';
+
+import type { SDKSharedV3ProviderMetadata } from '../../shared';
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+interface GenerationResult {
+  sources?: Array<{
+    url: string;
+    title: string;
+    snippet: string;
+    publishedDate?: string;
+    author?: string;
+  }>;
+  providerOptions?: SDKSharedV3ProviderMetadata;
+}
+
+interface XAISourceItem {
+  url: string;
+  title: string;
+  snippet: string;
+  publishedDate?: string;
+  author?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Re-export provider
+// ---------------------------------------------------------------------------
+
+export { createXai, xai as grok };
+
+/** Image generation support via xAI. */
+export const grokImage = xai.image;
+
+// ---------------------------------------------------------------------------
+// Model IDs
+// ---------------------------------------------------------------------------
+
+/** Single source of truth for xAI Grok model IDs. */
+export const GROK_MODEL_IDS = {
+  GROK_4: 'grok-4',
+  GROK_3: 'grok-3',
+  GROK_3_LATEST: 'grok-3-latest',
+  GROK_3_FAST: 'grok-3-fast',
+  GROK_3_FAST_LATEST: 'grok-3-fast-latest',
+  GROK_3_MINI: 'grok-3-mini',
+  GROK_3_MINI_LATEST: 'grok-3-mini-latest',
+  GROK_3_MINI_FAST: 'grok-3-mini-fast',
+  GROK_3_MINI_FAST_LATEST: 'grok-3-mini-fast-latest',
+  GROK_2: 'grok-2',
+  GROK_2_LATEST: 'grok-2-latest',
+  GROK_2_1212: 'grok-2-1212',
+  GROK_2_VISION: 'grok-2-vision',
+  GROK_2_VISION_LATEST: 'grok-2-vision-latest',
+  GROK_2_VISION_1212: 'grok-2-vision-1212',
+  GROK_CODE_FAST_1: 'grok-code-fast-1',
+  GROK_BETA: 'grok-beta',
+  GROK_VISION_BETA: 'grok-vision-beta',
+  GROK_2_IMAGE: 'grok-2-image',
+} as const;
+
+/** Model groups for categorization. */
+export const GROK_MODEL_GROUPS = {
+  REASONING_EFFORT_MODELS: [
+    GROK_MODEL_IDS.GROK_3_MINI,
+    GROK_MODEL_IDS.GROK_3_MINI_LATEST,
+    GROK_MODEL_IDS.GROK_3_MINI_FAST,
+    GROK_MODEL_IDS.GROK_3_MINI_FAST_LATEST,
+    GROK_MODEL_IDS.GROK_CODE_FAST_1,
+  ] as const,
+  VISION_MODELS: [
+    GROK_MODEL_IDS.GROK_2_VISION,
+    GROK_MODEL_IDS.GROK_2_VISION_LATEST,
+    GROK_MODEL_IDS.GROK_2_VISION_1212,
+    GROK_MODEL_IDS.GROK_VISION_BETA,
+  ] as const,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Model capabilities (xAI-unique features only)
+// ---------------------------------------------------------------------------
+
+const GROK_MODEL_CAPABILITIES: Record<string, GrokModelCapabilities> = {
+  [GROK_MODEL_IDS.GROK_4]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_3]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_3_LATEST]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_3_FAST]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_3_FAST_LATEST]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2_LATEST]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2_1212]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2_VISION]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2_VISION_LATEST]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2_VISION_1212]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_BETA]: { liveSearch: true, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_3_MINI]: { liveSearch: true, reasoningEffort: true },
+  [GROK_MODEL_IDS.GROK_3_MINI_LATEST]: { liveSearch: true, reasoningEffort: true },
+  [GROK_MODEL_IDS.GROK_3_MINI_FAST]: { liveSearch: true, reasoningEffort: true },
+  [GROK_MODEL_IDS.GROK_3_MINI_FAST_LATEST]: { liveSearch: true, reasoningEffort: true },
+  [GROK_MODEL_IDS.GROK_CODE_FAST_1]: { liveSearch: true, reasoningEffort: true },
+  [GROK_MODEL_IDS.GROK_VISION_BETA]: { liveSearch: false, reasoningEffort: false },
+  [GROK_MODEL_IDS.GROK_2_IMAGE]: { liveSearch: false, reasoningEffort: false },
+};
+
+// ---------------------------------------------------------------------------
+// Option helpers
+// ---------------------------------------------------------------------------
+
+/** Configure xAI Live Search parameters. */
+export function withSearchParameters(
+  options: {
+    mode?: 'auto' | 'on' | 'off';
+    returnCitations?: boolean;
+    fromDate?: string;
+    toDate?: string;
+    maxSearchResults?: number;
+    sources?: Array<WebSearchSource | XSearchSource | NewsSearchSource | RSSSearchSource>;
+  } = {},
+) {
+  return {
+    xai: {
+      searchParameters: {
+        mode: options.mode ?? 'auto',
+        returnCitations: options.returnCitations ?? true,
+        fromDate: options.fromDate,
+        toDate: options.toDate,
+        maxSearchResults: options.maxSearchResults ?? 20,
+        sources: options.sources ?? ['web', 'x'],
+      },
+    },
+  };
+}
+
+/** Convenience helper for multi-source search. */
+export function withSearchSources(
+  ...sources: Array<WebSearchSource | XSearchSource | NewsSearchSource | RSSSearchSource>
+) {
+  return withSearchParameters({ mode: 'on', returnCitations: true, sources });
+}
+
+/** Configure reasoning effort for mini models. */
+export function withReasoningEffort(effort: 'low' | 'high') {
+  return { xai: { reasoningEffort: effort } };
+}
+
+// ---------------------------------------------------------------------------
+// Capability detection
+// ---------------------------------------------------------------------------
+
+/** Check if model supports Live Search. */
+export function supportsLiveSearch(modelId: string): boolean {
+  return GROK_MODEL_CAPABILITIES[modelId]?.liveSearch ?? false;
+}
+
+/** Check if model supports reasoning effort control. */
+export function supportsReasoningEffort(modelId: string): boolean {
+  return GROK_MODEL_CAPABILITIES[modelId]?.reasoningEffort ?? false;
+}
+
+/** Check if model supports vision input. */
+export function supportsVision(modelId: string): boolean {
+  return GROK_MODEL_GROUPS.VISION_MODELS.includes(
+    modelId as (typeof GROK_MODEL_GROUPS.VISION_MODELS)[number],
+  );
+}
+
+/** Check if model supports image generation. */
+export function supportsImageGeneration(modelId: string): boolean {
+  return modelId === GROK_MODEL_IDS.GROK_2_IMAGE;
+}
+
+// ---------------------------------------------------------------------------
+// Metadata extraction
+// ---------------------------------------------------------------------------
+
+/** Extract search sources from xAI responses. */
+export function extractSources(result: GenerationResult): XAISource[] {
+  if (!result?.sources) return [];
+  return result.sources.map((source: XAISourceItem) => ({
+    url: source.url ?? '',
+    title: source.title,
+    snippet: source.snippet,
+    sourceType: 'url' as const,
+  }));
+}
+
+/** Extract search metadata from xAI responses. */
+export function extractSearchMetadata(result: GenerationResult): XAISearchMetadata | null {
+  const xaiMeta = result?.providerOptions?.xai;
+  if (!xaiMeta || typeof xaiMeta !== 'object' || Array.isArray(xaiMeta)) return null;
+
+  const meta = xaiMeta;
+  const { search } = meta;
+  if (!search || typeof search !== 'object' || Array.isArray(search)) return null;
+
+  const searchData = search;
+  return {
+    queriesUsed: typeof searchData.queriesUsed === 'number' ? searchData.queriesUsed : 0,
+    sourcesFound: typeof searchData.sourcesFound === 'number' ? searchData.sourcesFound : 0,
+    searchTime: typeof searchData.searchTime === 'number' ? searchData.searchTime : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Web search source configuration. */
+export interface WebSearchSource {
+  type: 'web';
+  country?: string;
+  allowedWebsites?: string[];
+  excludedWebsites?: string[];
+  safeSearch?: boolean;
+}
+
+/** X (Twitter) search source configuration. */
+export interface XSearchSource {
+  type: 'x';
+  xHandles: string[];
+}
+
+/** News search source configuration. */
+interface NewsSearchSource {
+  type: 'news';
+  country?: string;
+  excludedWebsites?: string[];
+  safeSearch?: boolean;
+}
+
+/** RSS search source configuration. */
+interface RSSSearchSource {
+  type: 'rss';
+  links: string[];
+}
+
+/** Source from xAI search results. */
+export interface XAISource {
+  url: string;
+  title?: string;
+  snippet?: string;
+  sourceType: 'url';
+}
+
+/** Search metadata from xAI responses. */
+export interface XAISearchMetadata {
+  queriesUsed: number;
+  sourcesFound: number;
+  searchTime: number;
+}
+
+/** xAI-unique model capabilities. */
+export interface GrokModelCapabilities {
+  liveSearch: boolean;
+  reasoningEffort: boolean;
+}

package/src/models/registry.ts

@@ -0,0 +1,208 @@
+import type { ModelMetadata } from './types';
+
+/**
+ * Semantic model names - use these in code, not provider-specific IDs
+ */
+export enum Model {
+  // Anthropic
+  OPUS = 'opus',
+  SONNET = 'sonnet',
+  HAIKU = 'haiku',
+
+  // OpenAI
+  GPT_4_TURBO = 'gpt-4-turbo',
+  GPT_4O = 'gpt-4o',
+  GPT_4O_MINI = 'gpt-4o-mini',
+  O1_PREVIEW = 'o1-preview',
+  O1_PRO = 'o1-pro',
+
+  // Google
+  GEMINI_15_FLASH = 'gemini-1.5-flash',
+  GEMINI_15_PRO = 'gemini-1.5-pro',
+  GEMINI_20_FLASH = 'gemini-2.0-flash',
+
+  // X AI
+  GROK_BETA = 'grok-beta',
+
+  // Perplexity
+  PERPLEXITY = 'perplexity',
+}
+
+/**
+ * Model ID mapping - provider-specific IDs
+ * Update here when model versions change
+ */
+const MODEL_IDS: Record<Model, string> = {
+  // Anthropic
+  [Model.OPUS]: 'claude-opus-4-20250514',
+  [Model.SONNET]: 'claude-sonnet-4-20250514',
+  [Model.HAIKU]: 'claude-haiku-4-20250514',
+
+  // OpenAI
+  [Model.GPT_4_TURBO]: 'gpt-4-turbo',
+  [Model.GPT_4O]: 'gpt-4o',
+  [Model.GPT_4O_MINI]: 'gpt-4o-mini',
+  [Model.O1_PREVIEW]: 'o1-preview',
+  [Model.O1_PRO]: 'o1-pro',
+
+  // Google
+  [Model.GEMINI_15_FLASH]: 'gemini-1.5-flash',
+  [Model.GEMINI_15_PRO]: 'gemini-1.5-pro',
+  [Model.GEMINI_20_FLASH]: 'gemini-2.0-flash-exp',
+
+  // X AI
+  [Model.GROK_BETA]: 'grok-beta',
+
+  // Perplexity
+  [Model.PERPLEXITY]: 'perplexity-sonar',
+};
+
+/**
+ * Model metadata registry
+ */
+export const MODEL_METADATA: Record<Model, ModelMetadata> = {
+  [Model.OPUS]: {
+    id: MODEL_IDS[Model.OPUS],
+    provider: 'anthropic',
+    tier: 'powerful',
+    contextWindow: 200_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 15,
+    costPer1kOutput: 75,
+  },
+  [Model.SONNET]: {
+    id: MODEL_IDS[Model.SONNET],
+    provider: 'anthropic',
+    tier: 'balanced',
+    contextWindow: 200_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 3,
+    costPer1kOutput: 15,
+  },
+  [Model.HAIKU]: {
+    id: MODEL_IDS[Model.HAIKU],
+    provider: 'anthropic',
+    tier: 'fast',
+    contextWindow: 200_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 0.8,
+    costPer1kOutput: 4,
+  },
+  [Model.GPT_4_TURBO]: {
+    id: MODEL_IDS[Model.GPT_4_TURBO],
+    provider: 'openai',
+    tier: 'powerful',
+    contextWindow: 128_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 10,
+    costPer1kOutput: 30,
+  },
+  [Model.GPT_4O]: {
+    id: MODEL_IDS[Model.GPT_4O],
+    provider: 'openai',
+    tier: 'balanced',
+    contextWindow: 128_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 2.5,
+    costPer1kOutput: 10,
+  },
+  [Model.GPT_4O_MINI]: {
+    id: MODEL_IDS[Model.GPT_4O_MINI],
+    provider: 'openai',
+    tier: 'fast',
+    contextWindow: 128_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 0.15,
+    costPer1kOutput: 0.6,
+  },
+  [Model.O1_PREVIEW]: {
+    id: MODEL_IDS[Model.O1_PREVIEW],
+    provider: 'openai',
+    tier: 'reasoning',
+    contextWindow: 128_000,
+    supportsTools: false,
+    supportsStreaming: false,
+    costPer1kInput: 15,
+    costPer1kOutput: 60,
+  },
+  [Model.O1_PRO]: {
+    id: MODEL_IDS[Model.O1_PRO],
+    provider: 'openai',
+    tier: 'reasoning',
+    contextWindow: 128_000,
+    supportsTools: false,
+    supportsStreaming: false,
+    costPer1kInput: 60,
+    costPer1kOutput: 240,
+  },
+  [Model.GEMINI_15_FLASH]: {
+    id: MODEL_IDS[Model.GEMINI_15_FLASH],
+    provider: 'google',
+    tier: 'fast',
+    contextWindow: 1_000_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 0.075,
+    costPer1kOutput: 0.3,
+  },
+  [Model.GEMINI_15_PRO]: {
+    id: MODEL_IDS[Model.GEMINI_15_PRO],
+    provider: 'google',
+    tier: 'balanced',
+    contextWindow: 2_000_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 1.25,
+    costPer1kOutput: 5,
+  },
+  [Model.GEMINI_20_FLASH]: {
+    id: MODEL_IDS[Model.GEMINI_20_FLASH],
+    provider: 'google',
+    tier: 'fast',
+    contextWindow: 1_000_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 0.075,
+    costPer1kOutput: 0.3,
+  },
+  [Model.GROK_BETA]: {
+    id: MODEL_IDS[Model.GROK_BETA],
+    provider: 'xai',
+    tier: 'balanced',
+    contextWindow: 128_000,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 5,
+    costPer1kOutput: 15,
+  },
+  [Model.PERPLEXITY]: {
+    id: MODEL_IDS[Model.PERPLEXITY],
+    provider: 'perplexity',
+    tier: 'balanced',
+    contextWindow: 127_072,
+    supportsTools: true,
+    supportsStreaming: true,
+    costPer1kInput: 1,
+    costPer1kOutput: 1,
+  },
+};
+
+/**
+ * Get provider-specific model ID
+ */
+export function getModelId(model: Model): string {
+  return MODEL_IDS[model];
+}
+
+/**
+ * Get model metadata
+ */
+export function getModelMetadata(model: Model): ModelMetadata {
+  return MODEL_METADATA[model];
+}

package/src/models/routing/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Routing module for intent classification and model selection.
+ * @module @od-oneapp/ai-platform/routing
+ *
+ * @example
+ * ```ts
+ * import { createIntentRouter, createModelRouter, DEFAULT_MODELS } from '@od-oneapp/ai-platform/routing';
+ *
+ * // Intent-based routing
+ * const intentRouter = createIntentRouter({
+ *   routes: [
+ *     { id: 'search', description: 'Search queries' },
+ *     { id: 'create', description: 'Content creation' },
+ *   ],
+ *   defaultRoute: 'search',
+ * });
+ *
+ * // Cost-based model routing
+ * const modelRouter = createModelRouter({ models: DEFAULT_MODELS });
+ * const decision = await modelRouter.route(fastModel, 'complex analysis task');
+ * ```
+ */
+
+export {
+  IntentSchema,
+  ModelTierSchema,
+  TaskComplexitySchema,
+  type Intent,
+  type RouteDefinition,
+  type RouterConfig,
+  type ModelTier,
+  type ModelRoutingDecision,
+  type ModelConfig,
+  type TaskComplexity,
+  type ComplexityAssessment,
+} from './types';
+
+export { createIntentRouter, createKeywordRouter } from './intent-router';
+
+export {
+  createModelRouter,
+  executeWithTieredModels,
+  DEFAULT_MODELS,
+  type ModelRouterConfig,
+} from './model-router';

package/src/models/routing/intent-router.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Intent router using AI SDK Output API for classification.
+ * @module @od-oneapp/ai-platform/routing
+ */
+
+import { z } from 'zod';
+
+import { generateObject } from '../../shared';
+
+import type { Intent, RouteDefinition, RouterConfig } from './types';
+import type { SDKLanguageModelV3 } from '../../shared';
+
+/**
+ * Creates an intent router that classifies user queries into predefined routes.
+ *
+ * @param config - Router configuration with routes and defaults
+ * @returns Router function
+ *
+ * @example
+ * ```ts
+ * const router = createIntentRouter({
+ *   routes: [
+ *     { id: 'search', description: 'Search for information' },
+ *     { id: 'create', description: 'Create new content' },
+ *   ],
+ *   defaultRoute: 'search',
+ * });
+ *
+ * const result = await router.classify(model, 'Find me some docs');
+ * // { route: 'search', intent: { intent: 'search', confidence: 0.95 } }
+ * ```
+ */
+export function createIntentRouter<T extends string>(config: RouterConfig<T>) {
+  const { routes, defaultRoute, confidenceThreshold = 0.5 } = config;
+
+  // Build route descriptions for the prompt
+  const routeDescriptions = routes
+    .map(
+      r =>
+        `- ${r.id}: ${r.description}${r.keywords ? ` (keywords: ${r.keywords.join(', ')})` : ''}`,
+    )
+    .join('\n');
+
+  const routeIds = routes.map(r => r.id);
+
+  /**
+   * Classifies a query into one of the configured routes.
+   */
+  async function classify(
+    model: SDKLanguageModelV3,
+    query: string,
+  ): Promise<{ route: T; intent: Intent }> {
+    const ClassificationSchema = z.object({
+      route: z.enum(routeIds as [T, ...T[]]),
+      confidence: z.number().min(0).max(1),
+      entities: z.record(z.string(), z.unknown()).optional(),
+      reasoning: z.string().optional(),
+    });
+
+    const { object } = await generateObject({
+      model,
+      schema: ClassificationSchema,
+      prompt: `Classify the following query into one of these routes:
+
+${routeDescriptions}
+
+Query: "${query}"
+
+Respond with the most appropriate route, confidence (0-1), and any extracted entities.`,
+    });
+
+    // Check confidence threshold
+    const selectedRoute = object.confidence >= confidenceThreshold ? object.route : defaultRoute;
+
+    return {
+      route: selectedRoute,
+      intent: {
+        intent: object.route,
+        confidence: object.confidence,
+        entities: object.entities,
+        suggestedAction: object.route,
+      },
+    };
+  }
+
+  /**
+   * Routes a query and optionally executes the handler.
+   */
+  async function route(
+    model: SDKLanguageModelV3,
+    query: string,
+  ): Promise<{ route: T; intent: Intent; result?: unknown }> {
+    const classification = await classify(model, query);
+    const routeDef = routes.find(r => r.id === classification.route);
+
+    if (routeDef?.handler) {
+      const result = await routeDef.handler(classification.intent);
+      return { ...classification, result };
+    }
+
+    return classification;
+  }
+
+  /**
+   * Gets a route definition by ID.
+   */
+  function getRoute(id: T): RouteDefinition<T> | undefined {
+    return routes.find(r => r.id === id);
+  }
+
+  return {
+    classify,
+    route,
+    getRoute,
+    routes,
+    defaultRoute,
+  };
+}
+
+/**
+ * Simple keyword-based router for fast, deterministic routing.
+ * Falls back to default when no keywords match.
+ *
+ * @param config - Router configuration
+ * @returns Synchronous router function
+ */
+export function createKeywordRouter<T extends string>(config: RouterConfig<T>) {
+  const { routes, defaultRoute } = config;
+
+  function classify(query: string): { route: T; confidence: number } {
+    const lowerQuery = query.toLowerCase();
+
+    for (const routeDef of routes) {
+      if (routeDef.keywords?.some(kw => lowerQuery.includes(kw.toLowerCase()))) {
+        return { route: routeDef.id, confidence: 1.0 };
+      }
+    }
+
+    return { route: defaultRoute, confidence: 0.5 };
+  }
+
+  return { classify };
+}