@od-oneapp/ai-platform 0.1.0

package/src/internal/ui-factories/artifact-factory.ts

@@ -0,0 +1,667 @@
+/**
+ * Artifact Factory Pattern
+ *
+ * Factory pattern for creating streamable artifacts in AI responses.
+ * Supports multi-stage progressive loading and type-safe artifact streaming.
+ *
+ * @module @od-oneapp/ai-platform/internal/ui-factories/artifact-factory
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Artifact types supported by the factory
+ */
+export type ArtifactType =
+  | 'code'
+  | 'document'
+  | 'image'
+  | 'chart'
+  | 'table'
+  | 'diagram'
+  | 'markdown'
+  | 'html'
+  | 'json'
+  | 'custom';
+
+/**
+ * Artifact loading stage
+ */
+export type ArtifactStage =
+  | 'initializing'
+  | 'loading'
+  | 'processing'
+  | 'rendering'
+  | 'complete'
+  | 'error';
+
+/**
+ * Base artifact interface
+ */
+export interface Artifact<T = unknown> {
+  /** Unique artifact ID */
+  id: string;
+  /** Artifact type */
+  type: ArtifactType;
+  /** Display title */
+  title: string;
+  /** Current loading stage */
+  stage: ArtifactStage;
+  /** Progress percentage (0-100) */
+  progress: number;
+  /** The artifact content */
+  content: T;
+  /** Creation timestamp */
+  createdAt: Date;
+  /** Last update timestamp */
+  updatedAt: Date;
+  /** Optional metadata */
+  metadata?: Record<string, unknown>;
+  /** Error if stage is 'error' */
+  error?: string;
+}
+
+/**
+ * Code artifact
+ */
+export interface CodeArtifact extends Artifact<string> {
+  type: 'code';
+  language: string;
+  filename?: string;
+  highlightLines?: number[];
+}
+
+/**
+ * Document artifact
+ */
+export interface DocumentArtifact extends Artifact<string> {
+  type: 'document';
+  format: 'markdown' | 'html' | 'plain';
+  wordCount?: number;
+}
+
+/**
+ * Chart artifact
+ */
+export interface ChartArtifact extends Artifact<ChartData> {
+  type: 'chart';
+  chartType: 'line' | 'bar' | 'pie' | 'scatter' | 'area';
+}
+
+export interface ChartData {
+  labels: string[];
+  datasets: Array<{
+    label: string;
+    data: number[];
+    color?: string;
+  }>;
+}
+
+/**
+ * Table artifact
+ */
+export interface TableArtifact extends Artifact<TableData> {
+  type: 'table';
+  sortable?: boolean;
+  filterable?: boolean;
+}
+
+export interface TableData {
+  headers: string[];
+  rows: unknown[][];
+  totalRows?: number;
+}
+
+/**
+ * Diagram artifact (mermaid, etc.)
+ */
+export interface DiagramArtifact extends Artifact<string> {
+  type: 'diagram';
+  diagramType: 'mermaid' | 'plantuml' | 'graphviz';
+}
+
+/**
+ * Artifact update event
+ */
+export interface ArtifactUpdate<T = unknown> {
+  artifactId: string;
+  stage?: ArtifactStage;
+  progress?: number;
+  content?: Partial<T>;
+  metadata?: Record<string, unknown>;
+  error?: string;
+}
+
+/**
+ * Artifact stream chunk
+ */
+export interface ArtifactStreamChunk {
+  type: 'artifact-start' | 'artifact-update' | 'artifact-complete' | 'artifact-error';
+  artifactId: string;
+  data: unknown;
+  timestamp: number;
+}
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+export const ArtifactTypeSchema = z.enum([
+  'code',
+  'document',
+  'image',
+  'chart',
+  'table',
+  'diagram',
+  'markdown',
+  'html',
+  'json',
+  'custom',
+]);
+
+export const ArtifactStageSchema = z.enum([
+  'initializing',
+  'loading',
+  'processing',
+  'rendering',
+  'complete',
+  'error',
+]);
+
+export const ArtifactSchema = z.object({
+  id: z.string(),
+  type: ArtifactTypeSchema,
+  title: z.string(),
+  stage: ArtifactStageSchema,
+  progress: z.number().min(0).max(100),
+  content: z.unknown(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  error: z.string().optional(),
+});
+
+// ============================================================================
+// Artifact Factory
+// ============================================================================
+
+/**
+ * Factory options
+ */
+export interface ArtifactFactoryOptions {
+  /** ID generator function */
+  generateId?: () => string;
+  /** Default metadata */
+  defaultMetadata?: Record<string, unknown>;
+  /** Auto-progress update interval */
+  progressInterval?: number;
+}
+
+/**
+ * Create an artifact factory
+ *
+ * @example
+ * ```typescript
+ * const factory = createArtifactFactory();
+ *
+ * // Create a code artifact
+ * const codeArtifact = factory.createCode({
+ *   title: 'Example Code',
+ *   language: 'typescript',
+ *   content: 'const x = 1;',
+ * });
+ *
+ * // Stream artifact updates
+ * for await (const update of factory.streamArtifact(artifact, generateContent)) {
+ *   // Send to client
+ * }
+ * ```
+ */
+export function createArtifactFactory(options: ArtifactFactoryOptions = {}) {
+  const {
+    generateId = () => `artifact_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+    defaultMetadata = {},
+  } = options;
+
+  function createBase<T>(
+    type: ArtifactType,
+    title: string,
+    content: T,
+    extra: Record<string, unknown> = {},
+  ): Artifact<T> {
+    const now = new Date();
+    return {
+      id: generateId(),
+      type,
+      title,
+      stage: 'initializing',
+      progress: 0,
+      content,
+      createdAt: now,
+      updatedAt: now,
+      metadata: { ...defaultMetadata },
+      ...extra,
+    };
+  }
+
+  return {
+    /**
+     * Create a code artifact
+     */
+    createCode(params: {
+      title: string;
+      language: string;
+      content?: string;
+      filename?: string;
+      highlightLines?: number[];
+    }): CodeArtifact {
+      return createBase('code', params.title, params.content || '', {
+        language: params.language,
+        filename: params.filename,
+        highlightLines: params.highlightLines,
+      }) as CodeArtifact;
+    },
+
+    /**
+     * Create a document artifact
+     */
+    createDocument(params: {
+      title: string;
+      format?: 'markdown' | 'html' | 'plain';
+      content?: string;
+    }): DocumentArtifact {
+      return createBase('document', params.title, params.content || '', {
+        format: params.format || 'markdown',
+      }) as DocumentArtifact;
+    },
+
+    /**
+     * Create a chart artifact
+     */
+    createChart(params: {
+      title: string;
+      chartType: ChartArtifact['chartType'];
+      data?: ChartData;
+    }): ChartArtifact {
+      return createBase('chart', params.title, params.data || { labels: [], datasets: [] }, {
+        chartType: params.chartType,
+      }) as ChartArtifact;
+    },
+
+    /**
+     * Create a table artifact
+     */
+    createTable(params: {
+      title: string;
+      headers?: string[];
+      rows?: unknown[][];
+      sortable?: boolean;
+      filterable?: boolean;
+    }): TableArtifact {
+      return createBase(
+        'table',
+        params.title,
+        { headers: params.headers || [], rows: params.rows || [] },
+        { sortable: params.sortable, filterable: params.filterable },
+      ) as TableArtifact;
+    },
+
+    /**
+     * Create a diagram artifact
+     */
+    createDiagram(params: {
+      title: string;
+      diagramType: DiagramArtifact['diagramType'];
+      content?: string;
+    }): DiagramArtifact {
+      return createBase('diagram', params.title, params.content || '', {
+        diagramType: params.diagramType,
+      }) as DiagramArtifact;
+    },
+
+    /**
+     * Create a generic artifact
+     */
+    create<T>(params: {
+      type: ArtifactType;
+      title: string;
+      content: T;
+      metadata?: Record<string, unknown>;
+    }): Artifact<T> {
+      const artifact = createBase(params.type, params.title, params.content);
+      if (params.metadata) {
+        artifact.metadata = { ...artifact.metadata, ...params.metadata };
+      }
+      return artifact;
+    },
+
+    /**
+     * Update an artifact
+     */
+    update<T>(artifact: Artifact<T>, update: ArtifactUpdate<T>): Artifact<T> {
+      return {
+        ...artifact,
+        stage: update.stage ?? artifact.stage,
+        progress: update.progress ?? artifact.progress,
+        content:
+          update.content !== undefined
+            ? typeof artifact.content === 'object'
+              ? { ...artifact.content, ...update.content }
+              : (update.content as T)
+            : artifact.content,
+        metadata: update.metadata
+          ? { ...artifact.metadata, ...update.metadata }
+          : artifact.metadata,
+        error: update.error,
+        updatedAt: new Date(),
+      };
+    },
+
+    /**
+     * Stream artifact content with progressive updates
+     */
+    async *streamArtifact<T>(
+      artifact: Artifact<T>,
+      contentGenerator: AsyncIterable<Partial<T> | string>,
+      options: {
+        stageProgression?: ArtifactStage[];
+        updateInterval?: number;
+      } = {},
+    ): AsyncGenerator<ArtifactStreamChunk> {
+      const {
+        stageProgression = ['initializing', 'loading', 'processing', 'rendering', 'complete'],
+        updateInterval = 100,
+      } = options;
+
+      const currentArtifact = { ...artifact };
+      let chunkCount = 0;
+      let stageIndex = 0;
+
+      // Emit start
+      yield {
+        type: 'artifact-start',
+        artifactId: artifact.id,
+        data: currentArtifact,
+        timestamp: Date.now(),
+      };
+
+      try {
+        for await (const chunk of contentGenerator) {
+          chunkCount++;
+
+          // Update content
+          if (typeof chunk === 'string' && typeof currentArtifact.content === 'string') {
+            currentArtifact.content = (currentArtifact.content + chunk) as T;
+          } else if (typeof chunk === 'object') {
+            currentArtifact.content =
+              typeof currentArtifact.content === 'object'
+                ? ({ ...currentArtifact.content, ...chunk } as T)
+                : (chunk as T);
+          }
+
+          // Progress stage
+          if (stageIndex < stageProgression.length - 1) {
+            const progressPerStage = 100 / stageProgression.length;
+            if (currentArtifact.progress >= (stageIndex + 1) * progressPerStage) {
+              stageIndex++;
+              currentArtifact.stage = stageProgression[stageIndex] ?? currentArtifact.stage;
+            }
+          }
+
+          // Emit update
+          if (chunkCount % updateInterval === 0 || chunkCount === 1) {
+            currentArtifact.progress = Math.min(95, currentArtifact.progress + Math.random() * 5);
+            currentArtifact.updatedAt = new Date();
+
+            yield {
+              type: 'artifact-update',
+              artifactId: artifact.id,
+              data: {
+                stage: currentArtifact.stage,
+                progress: currentArtifact.progress,
+                content: currentArtifact.content,
+              },
+              timestamp: Date.now(),
+            };
+          }
+        }
+
+        // Complete
+        currentArtifact.stage = 'complete';
+        currentArtifact.progress = 100;
+        currentArtifact.updatedAt = new Date();
+
+        yield {
+          type: 'artifact-complete',
+          artifactId: artifact.id,
+          data: currentArtifact,
+          timestamp: Date.now(),
+        };
+      } catch (error) {
+        currentArtifact.stage = 'error';
+        currentArtifact.error = error instanceof Error ? error.message : String(error);
+        currentArtifact.updatedAt = new Date();
+
+        yield {
+          type: 'artifact-error',
+          artifactId: artifact.id,
+          data: {
+            error: currentArtifact.error,
+            stage: currentArtifact.stage,
+          },
+          timestamp: Date.now(),
+        };
+      }
+    },
+
+    /**
+     * Create a multi-stage artifact stream
+     */
+    async *streamMultiStage<T>(
+      artifact: Artifact<T>,
+      stages: Array<{
+        name: ArtifactStage;
+        duration: number;
+        generator?: () => AsyncIterable<Partial<T>>;
+      }>,
+    ): AsyncGenerator<ArtifactStreamChunk> {
+      const currentArtifact = { ...artifact };
+      const totalDuration = stages.reduce((sum, s) => sum + s.duration, 0);
+      let elapsedDuration = 0;
+
+      yield {
+        type: 'artifact-start',
+        artifactId: artifact.id,
+        data: currentArtifact,
+        timestamp: Date.now(),
+      };
+
+      try {
+        for (const stage of stages) {
+          currentArtifact.stage = stage.name;
+          const stageStartProgress = (elapsedDuration / totalDuration) * 100;
+          const stageEndProgress = ((elapsedDuration + stage.duration) / totalDuration) * 100;
+
+          if (stage.generator) {
+            for await (const chunk of stage.generator()) {
+              if (typeof currentArtifact.content === 'object') {
+                currentArtifact.content = { ...currentArtifact.content, ...chunk } as T;
+              }
+
+              currentArtifact.progress = Math.min(
+                stageEndProgress,
+                currentArtifact.progress + (stageEndProgress - stageStartProgress) * 0.1,
+              );
+              currentArtifact.updatedAt = new Date();
+
+              yield {
+                type: 'artifact-update',
+                artifactId: artifact.id,
+                data: {
+                  stage: currentArtifact.stage,
+                  progress: currentArtifact.progress,
+                  content: currentArtifact.content,
+                },
+                timestamp: Date.now(),
+              };
+            }
+          } else {
+            // Simulate progress for stages without generators
+            const steps = Math.ceil(stage.duration / 100);
+            const progressPerStep = (stageEndProgress - stageStartProgress) / steps;
+
+            for (let i = 0; i < steps; i++) {
+              await new Promise(resolve => setTimeout(resolve, 100));
+              currentArtifact.progress = Math.min(
+                stageEndProgress,
+                currentArtifact.progress + progressPerStep,
+              );
+              currentArtifact.updatedAt = new Date();
+
+              yield {
+                type: 'artifact-update',
+                artifactId: artifact.id,
+                data: {
+                  stage: currentArtifact.stage,
+                  progress: currentArtifact.progress,
+                },
+                timestamp: Date.now(),
+              };
+            }
+          }
+
+          elapsedDuration += stage.duration;
+        }
+
+        currentArtifact.stage = 'complete';
+        currentArtifact.progress = 100;
+        currentArtifact.updatedAt = new Date();
+
+        yield {
+          type: 'artifact-complete',
+          artifactId: artifact.id,
+          data: currentArtifact,
+          timestamp: Date.now(),
+        };
+      } catch (error) {
+        currentArtifact.stage = 'error';
+        currentArtifact.error = error instanceof Error ? error.message : String(error);
+
+        yield {
+          type: 'artifact-error',
+          artifactId: artifact.id,
+          data: { error: currentArtifact.error },
+          timestamp: Date.now(),
+        };
+      }
+    },
+  };
+}
+
+// ============================================================================
+// Artifact Registry
+// ============================================================================
+
+/**
+ * Registry for managing multiple artifacts
+ */
+export function createArtifactRegistry() {
+  const artifacts = new Map<string, Artifact>();
+  const listeners = new Map<string, Set<(artifact: Artifact) => void>>();
+
+  return {
+    register<T>(artifact: Artifact<T>): void {
+      artifacts.set(artifact.id, artifact as Artifact);
+    },
+
+    get<T>(id: string): Artifact<T> | undefined {
+      return artifacts.get(id) as Artifact<T> | undefined;
+    },
+
+    update<T>(id: string, update: ArtifactUpdate<T>): Artifact<T> | undefined {
+      const artifact = artifacts.get(id);
+      if (!artifact) return undefined;
+
+      const updated = {
+        ...artifact,
+        ...update,
+        content:
+          update.content !== undefined
+            ? typeof artifact.content === 'object'
+              ? { ...artifact.content, ...update.content }
+              : update.content
+            : artifact.content,
+        updatedAt: new Date(),
+      } as Artifact<T>;
+
+      artifacts.set(id, updated as Artifact);
+
+      // Notify listeners
+      listeners.get(id)?.forEach(listener => {
+        listener(updated as Artifact);
+      });
+
+      return updated;
+    },
+
+    delete(id: string): boolean {
+      listeners.delete(id);
+      return artifacts.delete(id);
+    },
+
+    list(): Artifact[] {
+      return Array.from(artifacts.values());
+    },
+
+    subscribe(id: string, listener: (artifact: Artifact) => void): () => void {
+      let set = listeners.get(id);
+      if (!set) {
+        set = new Set();
+        listeners.set(id, set);
+      }
+      set.add(listener);
+
+      return () => {
+        listeners.get(id)?.delete(listener);
+      };
+    },
+
+    clear(): void {
+      artifacts.clear();
+      listeners.clear();
+    },
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Convert artifact stream to data stream format
+ */
+export async function* artifactToDataStream(
+  artifactStream: AsyncIterable<ArtifactStreamChunk>,
+): AsyncGenerator<string> {
+  for await (const chunk of artifactStream) {
+    yield `data: ${JSON.stringify(chunk)}\n\n`;
+  }
+}
+
+/**
+ * Parse artifact from data stream
+ */
+export function parseArtifactChunk(data: string): ArtifactStreamChunk | null {
+  try {
+    if (data.startsWith('data: ')) {
+      return JSON.parse(data.slice(6)) as ArtifactStreamChunk;
+    }
+    return JSON.parse(data) as ArtifactStreamChunk;
+  } catch {
+    return null;
+  }
+}