@od-oneapp/ai-platform 0.1.0

package/src/generative-ui/types.ts

@@ -0,0 +1,376 @@
+/**
+ * @fileoverview Generative UI type definitions.
+ * @module @od-oneapp/ai-platform/generative-ui
+ *
+ * Type-safe definitions for AI-generated user interfaces:
+ * - UI tree structure for dynamic component assembly
+ * - Catalog entry types for component registration
+ * - Enterprise extensions for governance and audit
+ * - Stream part types for real-time UI generation
+ *
+ * @example
+ * ```ts
+ * import type {
+ *   UIElement,
+ *   UITree,
+ *   CatalogComponent,
+ *   GenerativeUIConfig,
+ * } from '@od-oneapp/ai-platform/generative-ui';
+ * ```
+ */
+
+import type { UserTier } from "../governance/entitlements";
+
+// ---------------------------------------------------------------------------
+// Core UI Tree Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single element in the generative UI tree.
+ * Maps 1:1 to a registered catalog component.
+ *
+ * @example
+ * ```ts
+ * const element: UIElement = {
+ *   type: 'MetricCard',
+ *   props: { label: 'Revenue', value: '$1.2M', trend: 'up' },
+ *   children: [],
+ * };
+ * ```
+ */
+export interface UIElement {
+  /** Component type name from the catalog (e.g., 'Card', 'Chart', 'MetricCard'). */
+  readonly type: string;
+
+  /** Props to pass to the component. Validated against catalog schema. */
+  readonly props: Record<string, unknown>;
+
+  /** Nested child elements (recursive tree). */
+  readonly children?: readonly UIElement[];
+
+  /** Unique element ID for reconciliation during streaming updates. */
+  readonly id?: string;
+}
+
+/**
+ * Root of a generative UI tree.
+ * Contains metadata and the element tree for rendering.
+ */
+export interface UITree {
+  /** Schema version for forward compatibility. */
+  readonly version: '1.0';
+
+  /** Root element of the UI tree. */
+  readonly root: UIElement;
+
+  /** Metadata about the generation. */
+  readonly metadata?: UITreeMetadata;
+}
+
+/**
+ * Metadata attached to a generated UI tree.
+ * Used for audit, caching, and observability.
+ */
+export interface UITreeMetadata {
+  /** Model that generated this tree. */
+  readonly modelId?: string;
+
+  /** Prompt that triggered generation. */
+  readonly promptHash?: string;
+
+  /** Generation timestamp (ISO 8601). */
+  readonly generatedAt?: string;
+
+  /** Total token cost of generation. */
+  readonly tokenCost?: number;
+
+  /** Components used in this tree (for analytics). */
+  readonly componentsUsed?: readonly string[];
+
+  /** User tier at time of generation (for entitlement audit). */
+  readonly userTier?: UserTier;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog Component Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema definition for a catalog component's props.
+ * Uses a simplified JSON Schema subset for prompt generation.
+ */
+export interface PropSchema {
+  /** Property name. */
+  readonly name: string;
+
+  /** JSON Schema type (string, number, boolean, array, object). */
+  readonly type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+
+  /** Human-readable description for the LLM. */
+  readonly description: string;
+
+  /** Whether the prop is required. */
+  readonly required?: boolean;
+
+  /** Allowed literal values (enum constraint). */
+  readonly enum?: readonly (string | number | boolean)[];
+
+  /** Default value if not specified. */
+  readonly default?: unknown;
+}
+
+/**
+ * A component registered in the generative UI catalog.
+ * The LLM uses catalog entries to understand which components are available.
+ */
+export interface CatalogComponent {
+  /** Unique component name (PascalCase, e.g., 'MetricCard'). */
+  readonly name: string;
+
+  /** Short description for the LLM system prompt. */
+  readonly description: string;
+
+  /** Prop schema for validation and prompt generation. */
+  readonly props: readonly PropSchema[];
+
+  /** Whether this component accepts children. */
+  readonly acceptsChildren?: boolean;
+
+  /** Category for grouping in prompts (e.g., 'layout', 'data', 'chart', 'action'). */
+  readonly category: ComponentCategory;
+
+  /** Minimum user tier required to use this component. */
+  readonly minTier?: UserTier;
+
+  /** Tags for searchability. */
+  readonly tags?: readonly string[];
+}
+
+/** Component categories for catalog organization. */
+export type ComponentCategory =
+  | 'layout'
+  | 'data'
+  | 'chart'
+  | 'metric'
+  | 'action'
+  | 'feedback'
+  | 'navigation'
+  | 'media';
+
+// ---------------------------------------------------------------------------
+// Enterprise Catalog Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for creating an enterprise generative UI catalog.
+ */
+export interface EnterpriseCatalogConfig {
+  /** Base catalog components to include. */
+  readonly components: readonly CatalogComponent[];
+
+  /** Enable entitlement-based component filtering. */
+  readonly enableEntitlementFiltering?: boolean;
+
+  /** Enable audit logging for every catalog access. */
+  readonly enableAuditLogging?: boolean;
+
+  /** Custom component validator (runs before prompt generation). */
+  readonly validateComponent?: (component: CatalogComponent) => boolean;
+
+  /** Maximum components to include in a single prompt (to limit token cost). */
+  readonly maxComponentsInPrompt?: number;
+}
+
+/**
+ * An enterprise catalog with governance extensions.
+ */
+export interface EnterpriseCatalog {
+  /** All registered components. */
+  readonly components: readonly CatalogComponent[];
+
+  /** Get components filtered by user entitlements. */
+  getComponentsForTier(tier: UserTier): readonly CatalogComponent[];
+
+  /** Get a single component by name. */
+  getComponent(name: string): CatalogComponent | undefined;
+
+  /** Generate the system prompt section describing available components. */
+  generatePromptSection(tier: UserTier): string;
+
+  /** Validate a UI tree against the catalog. */
+  validateTree(tree: UITree, tier: UserTier): UITreeValidationResult;
+}
+
+/**
+ * Result of validating a UI tree against the catalog.
+ */
+export interface UITreeValidationResult {
+  /** Whether the tree is valid. */
+  readonly valid: boolean;
+
+  /** Validation errors (empty if valid). */
+  readonly errors: readonly UITreeValidationError[];
+}
+
+/**
+ * A single validation error in a UI tree.
+ */
+export interface UITreeValidationError {
+  /** Path to the invalid element (e.g., 'root.children[0].children[2]'). */
+  readonly path: string;
+
+  /** Error message. */
+  readonly message: string;
+
+  /** Error severity. */
+  readonly severity: 'error' | 'warning';
+}
+
+// ---------------------------------------------------------------------------
+// Stream Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for creating a generative UI stream.
+ */
+export interface GenerativeUIStreamConfig {
+  /** Model ID to use for generation. */
+  readonly modelId?: string;
+
+  /** User tier for entitlement filtering. */
+  readonly userTier: UserTier;
+
+  /** User ID for audit logging. */
+  readonly userId: string;
+
+  /** Enterprise catalog to use. */
+  readonly catalog: EnterpriseCatalog;
+
+  /** Budget guard configuration. */
+  readonly budgetGuard?: {
+    readonly maxTokens?: number;
+    readonly maxCost?: number;
+  };
+
+  /** Stream smoothing configuration. */
+  readonly smoothing?: {
+    readonly delayInMs?: number;
+  };
+
+  /** Additional system prompt context. */
+  readonly systemPromptSuffix?: string;
+
+  /** Abort signal for cancellation. */
+  readonly abortSignal?: AbortSignal;
+}
+
+/**
+ * Result of a generative UI stream.
+ */
+export interface GenerativeUIStreamResult {
+  /** Async iterator of partial UI trees. */
+  readonly partialTreeStream: AsyncIterable<Partial<UITree>>;
+
+  /** Promise that resolves to the final complete tree. */
+  readonly finalTree: Promise<UITree>;
+
+  /** Token usage after completion. */
+  readonly usage: Promise<{
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+  }>;
+}
+
+/**
+ * Data stream part for UI tree deltas.
+ * Sent via `dataStream.write()` during streaming.
+ */
+export interface UITreeDeltaStreamPart {
+  readonly type: 'data-uiTreeDelta';
+  readonly data: string; // JSON-serialized Partial<UITree>
+}
+
+// ---------------------------------------------------------------------------
+// Client Hook Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the useGenerativeUI client hook.
+ */
+export interface UseGenerativeUIConfig {
+  /** API endpoint for generative UI requests. */
+  readonly api?: string;
+
+  /** Callback when a new tree is received. */
+  readonly onTree?: (tree: UITree) => void;
+
+  /** Callback on error. */
+  readonly onError?: (error: Error) => void;
+
+  /** Callback when generation finishes. */
+  readonly onFinish?: (tree: UITree) => void;
+}
+
+/**
+ * Return type of the useGenerativeUI client hook.
+ */
+export interface UseGenerativeUIReturn {
+  /** Current (possibly partial) UI tree. */
+  readonly tree: UITree | null;
+
+  /** Whether a UI tree is being generated. */
+  readonly isGenerating: boolean;
+
+  /** Trigger generation with a prompt. */
+  generate(prompt: string): void;
+
+  /** Abort the current generation. */
+  abort(): void;
+
+  /** Last error, if any. */
+  readonly error: Error | null;
+}
+
+// ---------------------------------------------------------------------------
+// Audit Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Audit entry for a generative UI operation.
+ */
+export interface GenerativeUIAuditEntry {
+  /** User who triggered the generation. */
+  readonly userId: string;
+
+  /** User's tier at time of generation. */
+  readonly userTier: UserTier;
+
+  /** Prompt that triggered generation (hashed for privacy). */
+  readonly promptHash: string;
+
+  /** Components used in the generated tree. */
+  readonly componentsUsed: readonly string[];
+
+  /** Number of elements in the tree. */
+  readonly elementCount: number;
+
+  /** Token usage. */
+  readonly tokenUsage: {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+  };
+
+  /** Cost in USD. */
+  readonly costUsd: number;
+
+  /** Whether any components were filtered by entitlements. */
+  readonly componentsFiltered: readonly string[];
+
+  /** Validation result of the generated tree. */
+  readonly validationPassed: boolean;
+
+  /** Generation timestamp (ISO 8601). */
+  readonly timestamp: string;
+}

package/src/governance/audit/audit-logger.ts

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Audit Logger Implementation
+ * Audit Logger Implementation
+ * Creates immutable, cryptographically signed audit trail
+ */
+
+import { logInfo, logWarn } from '@repo/shared/logs';
+
+import { generateSignature, hashInput } from '../../server/cache/crypto';
+import { POLICY_VERSION } from '../versioning';
+
+import { validateAuditEntry } from './audit-schema';
+
+import type { AuditEntry, AuditLogger, AuditQueryFilter } from '../types';
+
+/**
+ * In-memory audit logger (for development)
+ * In production, replace with persistent storage (PostgreSQL, Redis, S3)
+ */
+class InMemoryAuditLogger implements AuditLogger {
+  private entries: AuditEntry[] = [];
+  private readonly maxEntries: number;
+
+  constructor(maxEntries: number = 10000) {
+    this.maxEntries = maxEntries;
+  }
+
+  async log(entry: Omit<AuditEntry, 'timestamp' | 'signature'>): Promise<void> {
+    const timestamp = new Date().toISOString();
+
+    // Create entry with timestamp
+    const entryWithTimestamp = {
+      ...entry,
+      timestamp,
+    };
+
+    // Generate signature
+    const signature = await generateSignature(entryWithTimestamp);
+
+    // Complete entry
+    const completeEntry: AuditEntry = {
+      ...entryWithTimestamp,
+      signature,
+    };
+
+    // Validate
+    validateAuditEntry(completeEntry);
+
+    // Store (append-only)
+    this.entries.push(completeEntry);
+
+    // Enforce retention limit (in production, use proper archival)
+    if (this.entries.length > this.maxEntries) {
+      this.entries.shift(); // Remove oldest
+    }
+
+    // Log to console in development
+    if (process.env.NODE_ENV === 'development') {
+      logInfo('[AUDIT]', {
+        action: completeEntry.action,
+        actor: completeEntry.actor,
+        timestamp: completeEntry.timestamp,
+      });
+    }
+  }
+
+  async query(filter: AuditQueryFilter): Promise<AuditEntry[]> {
+    // Clone entries to prevent external mutation
+    let results = this.entries.map(entry => structuredClone(entry));
+
+    // Filter by actor
+    if (filter.actor) {
+      results = results.filter(e => e.actor === filter.actor);
+    }
+
+    // Filter by action
+    if (filter.action) {
+      results = results.filter(e => e.action === filter.action);
+    }
+
+    // Filter by date range
+    const { startDate, endDate } = filter;
+    if (startDate) {
+      results = results.filter(e => new Date(e.timestamp) >= startDate);
+    }
+    if (endDate) {
+      results = results.filter(e => new Date(e.timestamp) <= endDate);
+    }
+
+    // Apply limit
+    const limit = filter.limit ?? 100;
+    return results.slice(0, limit);
+  }
+
+  /**
+   * Get all entries (for development/testing)
+   */
+  async getAll(): Promise<AuditEntry[]> {
+    // Return deep clones to prevent external mutation
+    return this.entries.map(entry => structuredClone(entry));
+  }
+
+  /**
+   * Clear all entries (for testing only)
+   */
+  async clear(): Promise<void> {
+    this.entries = [];
+  }
+}
+
+/**
+ * Console-only audit logger (for demos)
+ */
+class ConsoleAuditLogger implements AuditLogger {
+  async log(entry: Omit<AuditEntry, 'timestamp' | 'signature'>): Promise<void> {
+    const timestamp = new Date().toISOString();
+    const signature = await generateSignature({ ...entry, timestamp });
+
+    const completeEntry = {
+      ...entry,
+      timestamp,
+      signature,
+    };
+
+    logInfo('[AUDIT LOG]', { entry: completeEntry });
+  }
+
+  async query(filter: AuditQueryFilter): Promise<AuditEntry[]> {
+    void filter;
+    logWarn('[AUDIT] ConsoleAuditLogger does not support querying');
+    return [];
+  }
+}
+
+/**
+ * Create an audit logger instance
+ */
+export function createAuditLogger(type: 'memory' | 'console' = 'memory'): AuditLogger {
+  switch (type) {
+    case 'console':
+      return new ConsoleAuditLogger();
+    case 'memory':
+    default:
+      return new InMemoryAuditLogger();
+  }
+}
+
+/**
+ * Global audit logger instance
+ */
+let globalLogger: AuditLogger | null = null;
+
+/**
+ * Get or create global audit logger
+ */
+export function getAuditLogger(): AuditLogger {
+  if (!globalLogger) {
+    globalLogger = createAuditLogger('memory');
+  }
+  return globalLogger;
+}
+
+/**
+ * Set global audit logger
+ */
+export function setAuditLogger(logger: AuditLogger): void {
+  globalLogger = logger;
+}
+
+/**
+ * Helper to log a generation event
+ */
+export async function logGeneration(
+  actor: string,
+  input: string,
+  output: unknown,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  const logger = getAuditLogger();
+  const input_hash = await hashInput(input);
+
+  await logger.log({
+    actor,
+    action: 'generation',
+    input_hash,
+    output_snapshot: output,
+    policy_version: POLICY_VERSION,
+    metadata,
+  });
+}
+
+/**
+ * Helper to log a tool call event
+ */
+export async function logToolCall(
+  actor: string,
+  toolName: string,
+  args: unknown,
+  result: unknown,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  const logger = getAuditLogger();
+  const input_hash = await hashInput(JSON.stringify(args));
+
+  await logger.log({
+    actor,
+    action: 'tool_call',
+    input_hash,
+    output_snapshot: {
+      tool: toolName,
+      args,
+      result,
+    },
+    policy_version: POLICY_VERSION,
+    metadata,
+  });
+}
+
+/**
+ * Helper to log a redaction event
+ */
+export async function logRedaction(
+  actor: string,
+  detections: unknown,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  const logger = getAuditLogger();
+
+  await logger.log({
+    actor,
+    action: 'redaction',
+    input_hash: 'n/a', // Don't hash PHI
+    output_snapshot: {
+      detections,
+    },
+    policy_version: POLICY_VERSION,
+    metadata,
+  });
+}

package/src/governance/audit/audit-schema.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Audit entry schemas and validation
+ * Audit entry schemas and validation
+ * Ensures structured, machine-readable audit logs for FDA/SOC2
+ */
+
+import { z } from 'zod';
+
+/**
+ * Audit action types
+ */
+export const AuditActionSchema = z.enum([
+  'generation',
+  'generative_ui',
+  'tool_call',
+  'redaction',
+  'policy_check',
+  'abac_decision',
+  'approval_request',
+  'approval_granted',
+  'approval_denied',
+]);
+
+/**
+ * ABAC decision schema
+ */
+export const ABACDecisionSchema = z.object({
+  allowed: z.boolean(),
+  reason: z.string().optional(),
+  conditions: z.array(z.string()).optional(),
+  policyId: z.string(),
+});
+
+/**
+ * Core audit entry schema
+ */
+export const AuditEntrySchema = z.object({
+  id: z.string().optional(), // Generated by logger
+  timestamp: z.string(), // ISO 8601
+  actor: z.string(), // User/Agent ID
+  action: AuditActionSchema,
+  input_hash: z.string(), // SHA-256 hash
+  output_snapshot: z.unknown(), // Flexible structured output
+  policy_version: z.string(),
+  abac_decision: ABACDecisionSchema.optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  signature: z.string(), // HMAC signature
+});
+
+/**
+ * Audit query filter schema
+ */
+export const AuditQueryFilterSchema = z.object({
+  actor: z.string().optional(),
+  action: AuditActionSchema.optional(),
+  startDate: z.date().optional(),
+  endDate: z.date().optional(),
+  limit: z.number().positive().max(1000).default(100),
+  offset: z.number().nonnegative().default(0),
+});
+
+/**
+ * Type exports
+ */
+export type AuditAction = z.infer<typeof AuditActionSchema>;
+export type ABACDecision = z.infer<typeof ABACDecisionSchema>;
+export type AuditEntry = z.infer<typeof AuditEntrySchema>;
+export type AuditQueryFilter = z.infer<typeof AuditQueryFilterSchema>;
+
+/**
+ * Validate audit entry
+ */
+export function validateAuditEntry(entry: unknown): AuditEntry {
+  return AuditEntrySchema.parse(entry);
+}
+
+/**
+ * Validate query filter
+ */
+export function validateQueryFilter(filter: unknown): AuditQueryFilter {
+  return AuditQueryFilterSchema.parse(filter);
+}

package/src/governance/audit/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Audit Logging
+ * @module governance/audit
+ */
+export * from './audit-logger';
+export * from './audit-schema';