@od-oneapp/ai-platform 0.1.0

package/src/generative-ui/index.ts

@@ -0,0 +1,82 @@
+import 'server-only';
+
+/**
+ * @fileoverview Generative UI Module (server-only barrel).
+ * @module @od-oneapp/ai-platform/generative-ui
+ *
+ * AI-driven dynamic interface generation with enterprise governance.
+ *
+ * **Important — Server/Client boundary:**
+ * This barrel re-exports `stream.ts` which depends on `node:crypto` via the
+ * audit logger. It is therefore **server-only**.
+ *
+ * Client code (e.g., `'use client'` components) should use the subpath exports:
+ * - `@od-oneapp/ai-platform/generative-ui/types` — all type definitions (client-safe)
+ * - `@od-oneapp/ai-platform/generative-ui/catalog` — catalog factory (client-safe)
+ * - `@od-oneapp/ai-platform/generative-ui/registry` — Zod registry (client-safe)
+ *
+ * Core capabilities:
+ * - **Catalog**: Define and manage available UI components with entitlement filtering
+ * - **Registry**: Runtime Zod validation of AI-generated component props
+ * - **Stream**: Build streaming configs for generative UI with budget guards and audit
+ * - **Types**: Full type system for UI trees, elements, and enterprise extensions
+ *
+ * Architecture:
+ * - ai-platform owns: catalog definition, prompt generation, streaming config, governance
+ * - uni-ui owns: `<GenerativeUIRenderer>` component, component mapping, visual rendering
+ *
+ * @example
+ * ```ts
+ * // Server-side (route handlers, server actions):
+ * import {
+ *   createEnterpriseCatalog,
+ *   createComponentRegistry,
+ *   createGenerativeUIStreamConfig,
+ *   BASE_CATALOG_COMPONENTS,
+ *   BASE_COMPONENT_SCHEMAS,
+ * } from '@od-oneapp/ai-platform/generative-ui';
+ *
+ * // Client-side ('use client' components):
+ * import type { UITree, UIElement } from '@od-oneapp/ai-platform/generative-ui/types';
+ * ```
+ */
+
+// Types
+export type {
+  UIElement,
+  UITree,
+  UITreeMetadata,
+  PropSchema,
+  CatalogComponent,
+  ComponentCategory,
+  EnterpriseCatalogConfig,
+  EnterpriseCatalog,
+  UITreeValidationResult,
+  UITreeValidationError,
+  GenerativeUIStreamConfig,
+  GenerativeUIStreamResult,
+  UITreeDeltaStreamPart,
+  UseGenerativeUIConfig,
+  UseGenerativeUIReturn,
+  GenerativeUIAuditEntry,
+} from './types';
+
+// Catalog
+export { BASE_CATALOG_COMPONENTS, createEnterpriseCatalog } from './catalog';
+
+// Registry
+export {
+  BASE_COMPONENT_SCHEMAS,
+  createComponentRegistry,
+  type RegisteredComponentName,
+  type ComponentRegistry,
+} from './registry';
+
+// Stream
+export {
+  createGenerativeUIStreamConfig,
+  validatePartialTree,
+  estimateGenerativeUICost,
+  GENERATIVE_UI_BUDGET_MULTIPLIER,
+  type GenerativeUIStreamOutput,
+} from './stream';

package/src/generative-ui/registry.ts

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview Generative UI Component Registry.
+ * @module @od-oneapp/ai-platform/generative-ui
+ *
+ * Maps catalog component names to type-safe prop schemas (Zod).
+ * Used for runtime validation of AI-generated UI trees before rendering.
+ *
+ * @example
+ * ```ts
+ * import { createComponentRegistry, BASE_COMPONENT_SCHEMAS } from '@od-oneapp/ai-platform/generative-ui';
+ *
+ * const registry = createComponentRegistry(BASE_COMPONENT_SCHEMAS);
+ * const parsed = registry.parseProps('MetricCard', rawProps);
+ * ```
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Schema Definitions
+// ---------------------------------------------------------------------------
+
+/** Zod schema for each base catalog component's props. */
+export const BASE_COMPONENT_SCHEMAS = {
+  // Layout
+  Card: z.object({
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    variant: z.enum(['default', 'outlined', 'elevated']).default('default'),
+  }),
+
+  Grid: z.object({
+    columns: z.number().int().min(1).max(6).default(2),
+    gap: z.enum(['sm', 'md', 'lg']).default('md'),
+  }),
+
+  Stack: z.object({
+    direction: z.enum(['vertical', 'horizontal']).default('vertical'),
+    gap: z.enum(['sm', 'md', 'lg']).default('md'),
+    align: z.enum(['start', 'center', 'end', 'stretch']).default('stretch'),
+  }),
+
+  Section: z.object({
+    heading: z.string(),
+    description: z.string().optional(),
+  }),
+
+  // Data
+  DataTable: z.object({
+    headers: z.array(z.string()),
+    rows: z.array(z.array(z.union([z.string(), z.number(), z.boolean()]))),
+    caption: z.string().optional(),
+    striped: z.boolean().default(true),
+  }),
+
+  List: z.object({
+    items: z.array(z.string()),
+    ordered: z.boolean().default(false),
+  }),
+
+  Badge: z.object({
+    label: z.string(),
+    variant: z.enum(['default', 'success', 'warning', 'error', 'info']).default('default'),
+  }),
+
+  KeyValue: z.object({
+    label: z.string(),
+    value: z.string(),
+  }),
+
+  // Charts
+  BarChart: z.object({
+    data: z.array(z.object({ label: z.string(), value: z.number() })),
+    title: z.string().optional(),
+    orientation: z.enum(['vertical', 'horizontal']).default('vertical'),
+    color: z.enum(['primary', 'secondary', 'success', 'warning', 'error']).default('primary'),
+  }),
+
+  LineChart: z.object({
+    data: z.array(
+      z.union([
+        z.object({
+          x: z.union([z.string(), z.number()]),
+          y: z.number(),
+          label: z.string().optional(),
+          value: z.number().optional(),
+        }),
+        z.object({
+          label: z.string(),
+          value: z.number(),
+          x: z.union([z.string(), z.number()]).optional(),
+          y: z.number().optional(),
+        }),
+      ]),
+    ),
+    title: z.string().optional(),
+    xLabel: z.string().optional(),
+    yLabel: z.string().optional(),
+  }),
+
+  PieChart: z.object({
+    data: z.array(z.object({ label: z.string(), value: z.number() })),
+    title: z.string().optional(),
+    donut: z.boolean().default(false),
+  }),
+
+  AreaChart: z.object({
+    data: z.array(z.object({ x: z.union([z.string(), z.number()]), y: z.number() })),
+    title: z.string().optional(),
+    stacked: z.boolean().default(false),
+  }),
+
+  // Metrics
+  MetricCard: z.object({
+    label: z.string(),
+    value: z.string(),
+    trend: z.enum(['up', 'down', 'stable']).optional(),
+    trendValue: z.string().optional(),
+    sentiment: z.enum(['positive', 'negative', 'neutral', 'warning']).default('neutral'),
+  }),
+
+  ProgressBar: z.object({
+    label: z.string(),
+    value: z.number().min(0).max(100),
+    max: z.number().min(1).default(100),
+    variant: z.enum(['default', 'success', 'warning', 'error']).default('default'),
+  }),
+
+  StatGroup: z.object({
+    stats: z.array(z.object({ label: z.string(), value: z.string() })),
+  }),
+
+  // Actions
+  CallToAction: z.object({
+    label: z.string(),
+    description: z.string().optional(),
+    action: z.string(),
+    variant: z.enum(['primary', 'secondary', 'outline']).default('primary'),
+  }),
+
+  // Feedback
+  Alert: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    severity: z.enum(['info', 'success', 'warning', 'error']).default('info'),
+  }),
+
+  StatusBadge: z.object({
+    label: z.string(),
+    status: z.enum(['online', 'offline', 'busy', 'away', 'error']),
+  }),
+} as const satisfies Record<string, z.ZodType>;
+
+/** Component name union type derived from the schema registry. */
+export type RegisteredComponentName = keyof typeof BASE_COMPONENT_SCHEMAS;
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime component registry for prop validation.
+ *
+ * Wraps Zod schemas and provides parse/safeParse/lookup methods for
+ * validating AI-generated component props before rendering.
+ */
+export interface ComponentRegistry {
+  /**
+   * Parse and validate props for a component. Returns validated props or throws.
+   *
+   * @param componentName - PascalCase component name from the catalog.
+   * @param rawProps - Raw props object from AI output.
+   * @returns Validated props with defaults applied.
+   * @throws {Error} If the component is unknown.
+   * @throws {z.ZodError} If props fail validation.
+   */
+  parseProps(componentName: string, rawProps: unknown): Record<string, unknown>;
+
+  /**
+   * Safe parse that returns a result object instead of throwing.
+   *
+   * @param componentName - PascalCase component name from the catalog.
+   * @param rawProps - Raw props object from AI output.
+   * @returns Result with `success`, `data` (on success), or `error` (on failure).
+   */
+  safeParseProps(
+    componentName: string,
+    rawProps: unknown,
+  ): {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: z.ZodError;
+  };
+
+  /**
+   * Check if a component is registered.
+   *
+   * @param name - Component name to look up.
+   * @returns `true` if the component has a registered schema.
+   */
+  hasComponent(name: string): boolean;
+
+  /**
+   * Get all registered component names.
+   *
+   * @returns Readonly array of component names.
+   */
+  getComponentNames(): readonly string[];
+}
+
+/**
+ * Creates a component registry from Zod schemas.
+ *
+ * @param schemas - Map of component name → Zod schema.
+ * @returns ComponentRegistry instance.
+ *
+ * @example
+ * ```ts
+ * const registry = createComponentRegistry(BASE_COMPONENT_SCHEMAS);
+ *
+ * // Validate props from AI output
+ * const props = registry.parseProps('MetricCard', {
+ *   label: 'Revenue',
+ *   value: '$1.2M',
+ *   trend: 'up',
+ * });
+ * ```
+ */
+export function createComponentRegistry(schemas: Record<string, z.ZodType>): ComponentRegistry {
+  const schemaMap = new Map(Object.entries(schemas));
+
+  return {
+    parseProps(componentName: string, rawProps: unknown): Record<string, unknown> {
+      const schema = schemaMap.get(componentName);
+      if (!schema) {
+        throw new Error(
+          `Unknown component: '${componentName}'. Registered: ${[...schemaMap.keys()].join(', ')}`,
+        );
+      }
+      return schema.parse(rawProps) as Record<string, unknown>;
+    },
+
+    safeParseProps(componentName: string, rawProps: unknown) {
+      const schema = schemaMap.get(componentName);
+      if (!schema) {
+        return {
+          success: false,
+          error: new z.ZodError([
+            {
+              code: 'custom',
+              path: ['type'],
+              message: `Unknown component: '${componentName}'`,
+            },
+          ]),
+        };
+      }
+
+      const result = schema.safeParse(rawProps);
+      if (result.success) {
+        return { success: true, data: result.data as Record<string, unknown> };
+      }
+      return { success: false, error: result.error };
+    },
+
+    hasComponent(name: string): boolean {
+      return schemaMap.has(name);
+    },
+
+    getComponentNames(): readonly string[] {
+      return [...schemaMap.keys()];
+    },
+  };
+}

package/src/generative-ui/stream.ts

@@ -0,0 +1,324 @@
+import 'server-only';
+
+/**
+ * @fileoverview Generative UI Stream (server-only).
+ * @module @od-oneapp/ai-platform/generative-ui/stream
+ *
+ * Creates AI SDK streams that produce generative UI trees.
+ * Integrates with budget guards, entitlements, and audit logging
+ * from the governance domain.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createGenerativeUIStream,
+ *   createEnterpriseCatalog,
+ *   BASE_CATALOG_COMPONENTS,
+ * } from '@od-oneapp/ai-platform/generative-ui';
+ *
+ * const catalog = createEnterpriseCatalog({
+ *   components: BASE_CATALOG_COMPONENTS,
+ *   enableEntitlementFiltering: true,
+ * });
+ *
+ * const { partialTreeStream, finalTree } = await createGenerativeUIStream({
+ *   userTier: 'pro',
+ *   userId: 'user-123',
+ *   catalog,
+ *   budgetGuard: { maxTokens: 10_000 },
+ * }, 'Show me a revenue dashboard');
+ *
+ * for await (const partial of partialTreeStream) {
+ *   // Stream partial UI tree to client
+ *   dataStream.write({ type: 'data-uiTreeDelta', data: JSON.stringify(partial) });
+ * }
+ * ```
+ */
+
+import { getAuditLogger } from '../governance/audit/audit-logger';
+import { calculateCost } from '../streaming/control/budget-guard';
+
+import type {
+  EnterpriseCatalog,
+  GenerativeUIAuditEntry,
+  GenerativeUIStreamConfig,
+  UITree,
+} from './types';
+import type { UserTier } from "../governance/entitlements";
+
+// ---------------------------------------------------------------------------
+// Prompt Construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the system prompt for generative UI generation.
+ * Includes the catalog description, output format instructions,
+ * and any additional context.
+ */
+function buildGenerativeUISystemPrompt(
+  catalog: EnterpriseCatalog,
+  config: GenerativeUIStreamConfig,
+): string {
+  const catalogSection = catalog.generatePromptSection(config.userTier);
+
+  return [
+    'You are a UI generation assistant. Given a user request, you produce a JSON UITree',
+    'that composes available components into a meaningful interface.',
+    '',
+    'Rules:',
+    '1. ONLY use components listed below. Do not invent new component types.',
+    '2. Return valid JSON matching the UITree schema exactly.',
+    '3. Use layout components (Card, Grid, Stack, Section) to organize content.',
+    '4. Choose the most appropriate visualization for the data described.',
+    '5. Keep the tree depth under 5 levels.',
+    '6. Each element must have a "type" and "props" field.',
+    '7. Children are optional and must be an array of UIElement objects.',
+    '',
+    catalogSection,
+    '',
+    config.systemPromptSuffix ?? '',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Tree Utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Counts the total number of elements in a UI tree.
+ */
+function countElements(tree: Partial<UITree>): number {
+  if (!tree.root) return 0;
+
+  function count(element: { children?: readonly unknown[] }): number {
+    let total = 1;
+    if (element.children) {
+      for (const child of element.children) {
+        if (child && typeof child === 'object') {
+          total += count(child as { children?: readonly unknown[] });
+        }
+      }
+    }
+    return total;
+  }
+
+  return count(tree.root);
+}
+
+/**
+ * Extracts all component type names used in a tree.
+ */
+function extractComponentNames(tree: Partial<UITree>): string[] {
+  if (!tree.root) return [];
+
+  const names = new Set<string>();
+
+  function walk(element: { type?: string; children?: readonly unknown[] }): void {
+    if (element.type) names.add(element.type);
+    if (element.children) {
+      for (const child of element.children) {
+        if (child && typeof child === 'object') {
+          walk(child as { type?: string; children?: readonly unknown[] });
+        }
+      }
+    }
+  }
+
+  walk(tree.root);
+  return [...names];
+}
+
+// ---------------------------------------------------------------------------
+// Stream Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of creating a generative UI stream configuration.
+ * Provides the system prompt for the LLM call and an audit function
+ * to log the completed generation.
+ */
+export interface GenerativeUIStreamOutput {
+  /** System prompt containing catalog description and generation rules. */
+  readonly systemPrompt: string;
+
+  /**
+   * Log the completed generation to the audit trail.
+   *
+   * @param finalTree - The fully-generated UI tree.
+   * @param usage - Token usage from the LLM response.
+   * @param promptHash - SHA-256 hash of the user prompt (e.g. `sha256:abc123`).
+   * @returns Resolves when the audit entry has been written.
+   */
+  logAudit(
+    finalTree: UITree,
+    usage: { promptTokens: number; completionTokens: number; totalTokens: number },
+    promptHash: string,
+  ): Promise<void>;
+}
+
+/**
+ * Creates the configuration for a generative UI stream.
+ *
+ * This function prepares the system prompt and validation/audit utilities.
+ * The actual `streamText()` or `streamObject()` call is made by the caller
+ * (typically in a route handler) to avoid coupling to specific AI SDK patterns.
+ *
+ * @param config - Stream configuration with catalog, user info, and budget.
+ * @returns System prompt and audit utilities.
+ *
+ * @example
+ * ```ts
+ * import { streamText, Output } from 'ai';
+ *
+ * const { systemPrompt, logAudit } = createGenerativeUIStreamConfig({
+ *   userTier: 'pro',
+ *   userId: 'user-123',
+ *   catalog,
+ * });
+ *
+ * const { partialOutputStream } = streamText({
+ *   model: myModel,
+ *   system: systemPrompt,
+ *   prompt: userRequest,
+ *   output: Output.object({ schema: uiTreeSchema }),
+ * });
+ *
+ * // After streaming completes:
+ * await logAudit(finalTree, usage, 'sha256:abc123...');
+ * ```
+ */
+export function createGenerativeUIStreamConfig(
+  config: GenerativeUIStreamConfig,
+): GenerativeUIStreamOutput {
+  const systemPrompt = buildGenerativeUISystemPrompt(config.catalog, config);
+
+  // Get components filtered for this tier (to detect entitlement filtering).
+  // Only compute the diff when filtering is actually enabled; otherwise
+  // no components are being withheld.
+  const allComponents = config.catalog.components;
+  const tierComponents = config.catalog.getComponentsForTier(config.userTier);
+  const filteredComponents: string[] =
+    tierComponents.length < allComponents.length
+      ? allComponents
+          .filter(c => !new Set(tierComponents.map(t => t.name)).has(c.name))
+          .map(c => c.name)
+      : [];
+
+  return {
+    systemPrompt,
+
+    async logAudit(
+      finalTree: UITree,
+      usage: { promptTokens: number; completionTokens: number; totalTokens: number },
+      promptHash: string,
+    ): Promise<void> {
+      const costUsd = calculateCost(
+        {
+          promptTokens: usage.promptTokens,
+          completionTokens: usage.completionTokens,
+          totalTokens: usage.totalTokens,
+        },
+        config.modelId ?? 'gpt-4o',
+      );
+
+      const componentsUsed = extractComponentNames(finalTree);
+      const elementCount = countElements(finalTree);
+
+      // Validate the tree
+      const validation = config.catalog.validateTree(finalTree, config.userTier);
+
+      const auditEntry: GenerativeUIAuditEntry = {
+        userId: config.userId,
+        userTier: config.userTier,
+        promptHash,
+        componentsUsed,
+        elementCount,
+        tokenUsage: usage,
+        costUsd,
+        componentsFiltered: filteredComponents,
+        validationPassed: validation.valid,
+        timestamp: new Date().toISOString(),
+      };
+
+      const logger = getAuditLogger();
+      await logger.log({
+        actor: config.userId,
+        action: 'generative_ui',
+        input_hash: auditEntry.promptHash,
+        output_snapshot: auditEntry,
+        policy_version: '1.0',
+        metadata: {
+          componentsUsed,
+          elementCount,
+          costUsd,
+          userTier: config.userTier,
+          validationPassed: validation.valid,
+        },
+      });
+    },
+  };
+}
+
+/**
+ * Validates and enriches a partial UI tree received from streaming.
+ * Applies the catalog's validation rules and adds metadata.
+ *
+ * @param partialTree - Partial tree from AI output stream.
+ * @param catalog - Enterprise catalog for validation.
+ * @param tier - User tier for entitlement checking.
+ * @returns Validated partial tree, or null if fatally invalid.
+ */
+export function validatePartialTree(
+  partialTree: Partial<UITree>,
+  catalog: EnterpriseCatalog,
+  _tier: UserTier,
+): { tree: Partial<UITree>; warnings: string[] } {
+  const warnings: string[] = [];
+
+  if (!partialTree.root) {
+    warnings.push('Partial tree has no root element');
+    return { tree: partialTree, warnings };
+  }
+
+  // Validate component types exist in catalog
+  const names = extractComponentNames(partialTree);
+  for (const name of names) {
+    if (!catalog.getComponent(name)) {
+      warnings.push(`Unknown component '${name}' in tree`);
+    }
+  }
+
+  return { tree: partialTree, warnings };
+}
+
+/**
+ * Budget multiplier for generative UI vs standard text.
+ * JSON trees are approximately 2-3x more verbose than markdown.
+ * Use this to adjust budget limits for generative UI requests.
+ */
+export const GENERATIVE_UI_BUDGET_MULTIPLIER = 2.5;
+
+/**
+ * Estimates the token cost of generating a UI tree for budget pre-flight.
+ *
+ * @param componentCount - Approximate number of components expected.
+ * @param modelId - Model to estimate cost for.
+ * @returns Estimated cost in USD.
+ */
+export function estimateGenerativeUICost(
+  componentCount: number,
+  modelId: string = 'gpt-4o',
+): number {
+  // Rough heuristic: ~200 output tokens per component, ~500 prompt tokens for catalog
+  const estimatedPromptTokens = 500 + componentCount * 50; // catalog grows with components
+  const estimatedOutputTokens = componentCount * 200;
+
+  return calculateCost(
+    {
+      promptTokens: estimatedPromptTokens,
+      completionTokens: estimatedOutputTokens,
+      totalTokens: estimatedPromptTokens + estimatedOutputTokens,
+    },
+    modelId,
+  );
+}