@umituz/react-native-ai-generation-content 1.0.1

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@umituz/react-native-ai-generation-content",
+  "version": "1.0.1",
+  "description": "Provider-agnostic AI generation orchestration for React Native",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix"
+  },
+  "keywords": [
+    "react-native",
+    "ai",
+    "generation",
+    "orchestration",
+    "fal",
+    "gemini",
+    "provider-agnostic"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umituz/react-native-ai-generation-content.git"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/domain/entities/error.types.ts

@@ -0,0 +1,34 @@
+/**
+ * AI Generation Error Types
+ * Provider-agnostic error classification
+ */
+
+export enum AIErrorType {
+  NETWORK = "NETWORK",
+  RATE_LIMIT = "RATE_LIMIT",
+  AUTHENTICATION = "AUTHENTICATION",
+  VALIDATION = "VALIDATION",
+  CONTENT_POLICY = "CONTENT_POLICY",
+  SERVER = "SERVER",
+  TIMEOUT = "TIMEOUT",
+  UNKNOWN = "UNKNOWN",
+}
+
+export interface AIErrorInfo {
+  type: AIErrorType;
+  messageKey: string;
+  retryable: boolean;
+  originalError?: unknown;
+  statusCode?: number;
+}
+
+export interface AIErrorMessages {
+  [AIErrorType.NETWORK]: string;
+  [AIErrorType.RATE_LIMIT]: string;
+  [AIErrorType.AUTHENTICATION]: string;
+  [AIErrorType.VALIDATION]: string;
+  [AIErrorType.CONTENT_POLICY]: string;
+  [AIErrorType.SERVER]: string;
+  [AIErrorType.TIMEOUT]: string;
+  [AIErrorType.UNKNOWN]: string;
+}

package/src/domain/entities/generation.types.ts

@@ -0,0 +1,56 @@
+/**
+ * AI Generation Types
+ * Core types for generation workflow
+ */
+
+export type GenerationCapability =
+  | "text-to-image"
+  | "image-to-image"
+  | "text-to-video"
+  | "image-to-video"
+  | "text-to-voice"
+  | "voice-to-text";
+
+export type GenerationStatus =
+  | "idle"
+  | "preparing"
+  | "moderating"
+  | "submitting"
+  | "generating"
+  | "polling"
+  | "finalizing"
+  | "completed"
+  | "failed";
+
+export interface GenerationMetadata {
+  model?: string;
+  provider?: string;
+  capability?: GenerationCapability;
+  creditCost?: number;
+  startTime?: number;
+  endTime?: number;
+  duration?: number;
+}
+
+export interface GenerationResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  requestId?: string;
+  metadata?: GenerationMetadata;
+}
+
+export interface GenerationProgress {
+  stage: GenerationStatus;
+  progress: number;
+  message?: string;
+  eta?: number;
+}
+
+export interface GenerationRequest {
+  model: string;
+  input: Record<string, unknown>;
+  userId?: string;
+  capability?: GenerationCapability;
+  onProgress?: (progress: GenerationProgress) => void;
+}

package/src/domain/entities/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Domain Entities
+ * Core type definitions
+ */
+
+export * from "./error.types";
+export * from "./generation.types";
+export * from "./polling.types";
+export * from "./progress.types";

package/src/domain/entities/polling.types.ts

@@ -0,0 +1,38 @@
+/**
+ * Polling Types
+ * Configuration for job polling
+ */
+
+export interface PollingConfig {
+  maxAttempts: number;
+  initialIntervalMs: number;
+  maxIntervalMs: number;
+  backoffMultiplier: number;
+  maxConsecutiveErrors: number;
+}
+
+export const DEFAULT_POLLING_CONFIG: PollingConfig = {
+  maxAttempts: 60,
+  initialIntervalMs: 1000,
+  maxIntervalMs: 3000,
+  backoffMultiplier: 1.2,
+  maxConsecutiveErrors: 5,
+};
+
+export interface PollingState {
+  attempt: number;
+  lastProgress: number;
+  consecutiveErrors: number;
+  startTime: number;
+}
+
+export interface PollingOptions {
+  model: string;
+  requestId: string;
+  statusUrl?: string;
+  responseUrl?: string;
+  userId?: string;
+  jobType?: string;
+  config?: Partial<PollingConfig>;
+  onProgress?: (progress: number) => void;
+}

package/src/domain/entities/progress.types.ts

@@ -0,0 +1,27 @@
+/**
+ * Progress Types
+ * Progress tracking for generation stages
+ */
+
+import type { GenerationStatus } from "./generation.types";
+
+export interface ProgressStageConfig {
+  status: GenerationStatus;
+  minProgress: number;
+  maxProgress: number;
+  weight: number;
+}
+
+export const DEFAULT_PROGRESS_STAGES: ProgressStageConfig[] = [
+  { status: "preparing", minProgress: 0, maxProgress: 5, weight: 1 },
+  { status: "moderating", minProgress: 5, maxProgress: 15, weight: 1 },
+  { status: "submitting", minProgress: 15, maxProgress: 25, weight: 1 },
+  { status: "generating", minProgress: 25, maxProgress: 85, weight: 6 },
+  { status: "finalizing", minProgress: 85, maxProgress: 95, weight: 1 },
+  { status: "completed", minProgress: 95, maxProgress: 100, weight: 1 },
+];
+
+export interface ProgressConfig {
+  stages: ProgressStageConfig[];
+  estimatedDurations?: Record<string, number>;
+}

package/src/domain/interfaces/ai-provider.interface.ts

@@ -0,0 +1,76 @@
+/**
+ * AI Provider Interface
+ * Provider-agnostic interface for AI generation services
+ * Implementations: FAL, Gemini, etc.
+ */
+
+export interface AIProviderConfig {
+  apiKey: string;
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  defaultTimeoutMs?: number;
+}
+
+export interface JobSubmission {
+  requestId: string;
+  statusUrl?: string;
+  responseUrl?: string;
+}
+
+export interface JobStatus {
+  status: AIJobStatusType;
+  logs?: AILogEntry[];
+  queuePosition?: number;
+  eta?: number;
+}
+
+export type AIJobStatusType =
+  | "IN_QUEUE"
+  | "IN_PROGRESS"
+  | "COMPLETED"
+  | "FAILED";
+
+export interface AILogEntry {
+  message: string;
+  level: "info" | "warn" | "error";
+  timestamp?: string;
+}
+
+export interface SubscribeOptions<T = unknown> {
+  timeoutMs?: number;
+  onQueueUpdate?: (status: JobStatus) => void;
+  onProgress?: (progress: number) => void;
+  onResult?: (result: T) => void;
+}
+
+/**
+ * AI Provider Interface
+ * All AI providers must implement this interface
+ */
+export interface IAIProvider {
+  readonly providerId: string;
+  readonly providerName: string;
+
+  initialize(config: AIProviderConfig): void;
+  isInitialized(): boolean;
+
+  submitJob(
+    model: string,
+    input: Record<string, unknown>,
+  ): Promise<JobSubmission>;
+
+  getJobStatus(model: string, requestId: string): Promise<JobStatus>;
+
+  getJobResult<T = unknown>(model: string, requestId: string): Promise<T>;
+
+  subscribe<T = unknown>(
+    model: string,
+    input: Record<string, unknown>,
+    options?: SubscribeOptions<T>,
+  ): Promise<T>;
+
+  run<T = unknown>(model: string, input: Record<string, unknown>): Promise<T>;
+
+  reset(): void;
+}

package/src/domain/interfaces/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Domain Interfaces
+ * Provider-agnostic contracts
+ */
+
+export * from "./ai-provider.interface";

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * @umituz/react-native-ai-generation-content
+ * Provider-agnostic AI generation orchestration
+ *
+ * Usage:
+ *   import {
+ *     providerRegistry,
+ *     generationOrchestrator,
+ *     useGeneration,
+ *   } from '@umituz/react-native-ai-generation-content';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Types & Interfaces
+// =============================================================================
+
+export type {
+  AIProviderConfig,
+  IAIProvider,
+  JobSubmission,
+  JobStatus,
+  AIJobStatusType,
+  AILogEntry,
+  SubscribeOptions,
+} from "./domain/interfaces";
+
+export {
+  AIErrorType,
+} from "./domain/entities";
+
+export type {
+  AIErrorInfo,
+  AIErrorMessages,
+  GenerationCapability,
+  GenerationStatus,
+  GenerationMetadata,
+  GenerationResult,
+  GenerationProgress,
+  GenerationRequest,
+  PollingConfig,
+  PollingState,
+  PollingOptions,
+  ProgressStageConfig,
+  ProgressConfig,
+} from "./domain/entities";
+
+export { DEFAULT_POLLING_CONFIG, DEFAULT_PROGRESS_STAGES } from "./domain/entities";
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Services
+// =============================================================================
+
+export {
+  providerRegistry,
+  generationOrchestrator,
+} from "./infrastructure/services";
+
+export type { OrchestratorConfig } from "./infrastructure/services";
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Utils
+// =============================================================================
+
+export {
+  classifyError,
+  isTransientError,
+  isPermanentError,
+  calculatePollingInterval,
+  createPollingDelay,
+  getProgressForStatus,
+  interpolateProgress,
+  createProgressTracker,
+} from "./infrastructure/utils";
+
+export type { IntervalOptions, ProgressOptions } from "./infrastructure/utils";
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
+
+export { useGeneration } from "./presentation/hooks";
+
+export type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from "./presentation/hooks";

package/src/infrastructure/services/generation-orchestrator.service.ts

@@ -0,0 +1,212 @@
+/**
+ * Generation Orchestrator Service
+ * Provider-agnostic AI generation workflow
+ */
+
+import type {
+  GenerationRequest,
+  GenerationResult,
+  GenerationProgress,
+  PollingConfig,
+} from "../../domain/entities";
+import { DEFAULT_POLLING_CONFIG } from "../../domain/entities";
+import type { IAIProvider, JobStatus } from "../../domain/interfaces";
+import { providerRegistry } from "./provider-registry.service";
+import {
+  classifyError,
+  isTransientError,
+} from "../utils/error-classifier.util";
+import { createPollingDelay } from "../utils/polling-interval.util";
+import { createProgressTracker } from "../utils/progress-calculator.util";
+
+declare const __DEV__: boolean;
+
+export interface OrchestratorConfig {
+  polling?: Partial<PollingConfig>;
+  onStatusUpdate?: (requestId: string, status: string) => Promise<void>;
+}
+
+class GenerationOrchestratorService {
+  private config: OrchestratorConfig = {};
+
+  configure(config: OrchestratorConfig): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  async generate<T = unknown>(
+    request: GenerationRequest,
+  ): Promise<GenerationResult<T>> {
+    const provider = this.getProvider();
+    const progressTracker = createProgressTracker();
+    const startTime = Date.now();
+
+    const updateProgress = (
+      stage: GenerationProgress["stage"],
+      subProgress = 0,
+    ) => {
+      const progress = progressTracker.setStatus(stage);
+      request.onProgress?.({
+        stage,
+        progress: progress + subProgress,
+      });
+    };
+
+    try {
+      updateProgress("preparing");
+
+      const submission = await provider.submitJob(request.model, request.input);
+
+      updateProgress("submitting");
+
+      if (typeof __DEV__ !== "undefined" && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.log("[Orchestrator] Job submitted:", submission.requestId);
+      }
+
+      updateProgress("generating");
+
+      const result = await this.pollForResult<T>(
+        provider,
+        request.model,
+        submission.requestId,
+        request.onProgress,
+      );
+
+      updateProgress("completed");
+
+      return {
+        success: true,
+        data: result,
+        requestId: submission.requestId,
+        metadata: {
+          model: request.model,
+          provider: provider.providerId,
+          capability: request.capability,
+          startTime,
+          endTime: Date.now(),
+          duration: Date.now() - startTime,
+        },
+      };
+    } catch (error) {
+      const errorInfo = classifyError(error);
+
+      if (typeof __DEV__ !== "undefined" && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.error("[Orchestrator] Generation failed:", errorInfo);
+      }
+
+      return {
+        success: false,
+        error: errorInfo.messageKey,
+        metadata: {
+          model: request.model,
+          provider: provider.providerId,
+          capability: request.capability,
+          startTime,
+          endTime: Date.now(),
+          duration: Date.now() - startTime,
+        },
+      };
+    }
+  }
+
+  private async pollForResult<T>(
+    provider: IAIProvider,
+    model: string,
+    requestId: string,
+    onProgress?: (progress: GenerationProgress) => void,
+  ): Promise<T> {
+    const config = {
+      ...DEFAULT_POLLING_CONFIG,
+      ...this.config.polling,
+    };
+
+    let consecutiveErrors = 0;
+
+    for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
+      await createPollingDelay(attempt, config);
+
+      try {
+        const status = await provider.getJobStatus(model, requestId);
+
+        consecutiveErrors = 0;
+
+        this.updateProgressFromStatus(status, attempt, config, onProgress);
+
+        if (status.status === "COMPLETED") {
+          return provider.getJobResult<T>(model, requestId);
+        }
+
+        if (status.status === "FAILED") {
+          throw new Error("Job failed on provider");
+        }
+
+        await this.config.onStatusUpdate?.(requestId, status.status);
+      } catch (error) {
+        if (isTransientError(error)) {
+          consecutiveErrors++;
+
+          if (consecutiveErrors >= config.maxConsecutiveErrors) {
+            throw error;
+          }
+
+          continue;
+        }
+
+        throw error;
+      }
+    }
+
+    throw new Error(
+      `Polling timeout after ${config.maxAttempts} attempts`,
+    );
+  }
+
+  private updateProgressFromStatus(
+    status: JobStatus,
+    attempt: number,
+    config: PollingConfig,
+    onProgress?: (progress: GenerationProgress) => void,
+  ): void {
+    const baseProgress = 25;
+    const maxProgress = 85;
+    const range = maxProgress - baseProgress;
+
+    let progress: number;
+
+    if (status.status === "IN_QUEUE") {
+      progress = baseProgress + range * 0.2;
+    } else if (status.status === "IN_PROGRESS") {
+      const ratio = Math.min(attempt / (config.maxAttempts * 0.7), 1);
+      progress = baseProgress + range * (0.2 + 0.6 * ratio);
+    } else {
+      progress = baseProgress;
+    }
+
+    onProgress?.({
+      stage: "generating",
+      progress: Math.round(progress),
+      eta: status.eta,
+    });
+  }
+
+  private getProvider(): IAIProvider {
+    const provider = providerRegistry.getActiveProvider();
+
+    if (!provider) {
+      throw new Error(
+        "No active AI provider. Register and set a provider first.",
+      );
+    }
+
+    if (!provider.isInitialized()) {
+      throw new Error(
+        `Provider ${provider.providerId} is not initialized.`,
+      );
+    }
+
+    return provider;
+  }
+}
+
+export const generationOrchestrator = new GenerationOrchestratorService();

package/src/infrastructure/services/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Infrastructure Services
+ */
+
+export { providerRegistry } from "./provider-registry.service";
+export { generationOrchestrator } from "./generation-orchestrator.service";
+export type { OrchestratorConfig } from "./generation-orchestrator.service";

package/src/infrastructure/services/provider-registry.service.ts

@@ -0,0 +1,87 @@
+/**
+ * Provider Registry Service
+ * Manages AI provider registration and selection
+ */
+
+import type { IAIProvider } from "../../domain/interfaces";
+
+declare const __DEV__: boolean;
+
+class ProviderRegistry {
+  private providers: Map<string, IAIProvider> = new Map();
+  private activeProviderId: string | null = null;
+
+  register(provider: IAIProvider): void {
+    if (this.providers.has(provider.providerId)) {
+      if (typeof __DEV__ !== "undefined" && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[ProviderRegistry] Provider ${provider.providerId} already registered`,
+        );
+      }
+      return;
+    }
+
+    this.providers.set(provider.providerId, provider);
+
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[ProviderRegistry] Registered provider: ${provider.providerId}`,
+      );
+    }
+  }
+
+  unregister(providerId: string): void {
+    if (this.activeProviderId === providerId) {
+      this.activeProviderId = null;
+    }
+    this.providers.delete(providerId);
+  }
+
+  setActiveProvider(providerId: string): void {
+    if (!this.providers.has(providerId)) {
+      throw new Error(`Provider ${providerId} is not registered`);
+    }
+    this.activeProviderId = providerId;
+
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log(`[ProviderRegistry] Active provider set to: ${providerId}`);
+    }
+  }
+
+  getActiveProvider(): IAIProvider | null {
+    if (!this.activeProviderId) {
+      return null;
+    }
+    return this.providers.get(this.activeProviderId) ?? null;
+  }
+
+  getProvider(providerId: string): IAIProvider | null {
+    return this.providers.get(providerId) ?? null;
+  }
+
+  getActiveProviderId(): string | null {
+    return this.activeProviderId;
+  }
+
+  listProviders(): Array<{ id: string; name: string; initialized: boolean }> {
+    return Array.from(this.providers.values()).map((provider) => ({
+      id: provider.providerId,
+      name: provider.providerName,
+      initialized: provider.isInitialized(),
+    }));
+  }
+
+  hasProvider(providerId: string): boolean {
+    return this.providers.has(providerId);
+  }
+
+  clear(): void {
+    this.providers.clear();
+    this.activeProviderId = null;
+  }
+}
+
+export const providerRegistry = new ProviderRegistry();

package/src/infrastructure/utils/error-classifier.util.ts

@@ -0,0 +1,150 @@
+/**
+ * Error Classifier Utility
+ * Classifies errors for retry and user feedback decisions
+ */
+
+import { AIErrorType, type AIErrorInfo } from "../../domain/entities";
+
+const NETWORK_ERROR_PATTERNS = [
+  "network",
+  "timeout",
+  "socket",
+  "econnrefused",
+  "enotfound",
+  "fetch failed",
+  "connection",
+];
+
+const RATE_LIMIT_PATTERNS = ["rate limit", "too many requests", "429"];
+
+const AUTH_ERROR_PATTERNS = [
+  "unauthorized",
+  "authentication",
+  "invalid api key",
+  "401",
+  "403",
+];
+
+const CONTENT_POLICY_PATTERNS = [
+  "content policy",
+  "safety",
+  "moderation",
+  "inappropriate",
+  "blocked",
+];
+
+const SERVER_ERROR_PATTERNS = [
+  "internal server error",
+  "500",
+  "502",
+  "503",
+  "504",
+  "service unavailable",
+];
+
+function matchesPatterns(message: string, patterns: string[]): boolean {
+  const lowerMessage = message.toLowerCase();
+  return patterns.some((pattern) => lowerMessage.includes(pattern));
+}
+
+function getStatusCode(error: unknown): number | undefined {
+  if (error && typeof error === "object") {
+    const err = error as Record<string, unknown>;
+    if (typeof err.status === "number") return err.status;
+    if (typeof err.statusCode === "number") return err.statusCode;
+    if (err.response && typeof err.response === "object") {
+      const resp = err.response as Record<string, unknown>;
+      if (typeof resp.status === "number") return resp.status;
+    }
+  }
+  return undefined;
+}
+
+export function classifyError(error: unknown): AIErrorInfo {
+  const message = error instanceof Error ? error.message : String(error);
+  const statusCode = getStatusCode(error);
+
+  if (statusCode === 429 || matchesPatterns(message, RATE_LIMIT_PATTERNS)) {
+    return {
+      type: AIErrorType.RATE_LIMIT,
+      messageKey: "error.rateLimit",
+      retryable: true,
+      originalError: error,
+      statusCode,
+    };
+  }
+
+  if (
+    statusCode === 401 ||
+    statusCode === 403 ||
+    matchesPatterns(message, AUTH_ERROR_PATTERNS)
+  ) {
+    return {
+      type: AIErrorType.AUTHENTICATION,
+      messageKey: "error.authentication",
+      retryable: false,
+      originalError: error,
+      statusCode,
+    };
+  }
+
+  if (matchesPatterns(message, CONTENT_POLICY_PATTERNS)) {
+    return {
+      type: AIErrorType.CONTENT_POLICY,
+      messageKey: "error.contentPolicy",
+      retryable: false,
+      originalError: error,
+      statusCode,
+    };
+  }
+
+  if (matchesPatterns(message, NETWORK_ERROR_PATTERNS)) {
+    return {
+      type: AIErrorType.NETWORK,
+      messageKey: "error.network",
+      retryable: true,
+      originalError: error,
+      statusCode,
+    };
+  }
+
+  if (
+    (statusCode && statusCode >= 500) ||
+    matchesPatterns(message, SERVER_ERROR_PATTERNS)
+  ) {
+    return {
+      type: AIErrorType.SERVER,
+      messageKey: "error.server",
+      retryable: true,
+      originalError: error,
+      statusCode,
+    };
+  }
+
+  if (message.toLowerCase().includes("timeout")) {
+    return {
+      type: AIErrorType.TIMEOUT,
+      messageKey: "error.timeout",
+      retryable: true,
+      originalError: error,
+      statusCode,
+    };
+  }
+
+  return {
+    type: AIErrorType.UNKNOWN,
+    messageKey: "error.unknown",
+    retryable: false,
+    originalError: error,
+    statusCode,
+  };
+}
+
+export function isTransientError(error: unknown): boolean {
+  const info = classifyError(error);
+  return info.retryable;
+}
+
+export function isPermanentError(error: unknown): boolean {
+  return !isTransientError(error);
+}

package/src/infrastructure/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Infrastructure Utils
+ */
+
+export * from "./error-classifier.util";
+export * from "./polling-interval.util";
+export * from "./progress-calculator.util";

package/src/infrastructure/utils/polling-interval.util.ts

@@ -0,0 +1,43 @@
+/**
+ * Polling Interval Calculator
+ * Calculates polling intervals with exponential backoff
+ */
+
+import {
+  DEFAULT_POLLING_CONFIG,
+  type PollingConfig,
+} from "../../domain/entities";
+
+export interface IntervalOptions {
+  attempt: number;
+  config?: Partial<PollingConfig>;
+}
+
+export function calculatePollingInterval(options: IntervalOptions): number {
+  const { attempt, config } = options;
+  const {
+    initialIntervalMs = DEFAULT_POLLING_CONFIG.initialIntervalMs,
+    maxIntervalMs = DEFAULT_POLLING_CONFIG.maxIntervalMs,
+    backoffMultiplier = DEFAULT_POLLING_CONFIG.backoffMultiplier,
+  } = config ?? {};
+
+  if (attempt === 0) {
+    return 0;
+  }
+
+  const interval = initialIntervalMs * Math.pow(backoffMultiplier, attempt - 1);
+  return Math.min(interval, maxIntervalMs);
+}
+
+export function createPollingDelay(
+  attempt: number,
+  config?: Partial<PollingConfig>,
+): Promise<void> {
+  const interval = calculatePollingInterval({ attempt, config });
+
+  if (interval === 0) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => setTimeout(resolve, interval));
+}

package/src/infrastructure/utils/progress-calculator.util.ts

@@ -0,0 +1,76 @@
+/**
+ * Progress Calculator Utility
+ * Calculates progress based on generation stage
+ */
+
+import type { GenerationStatus } from "../../domain/entities";
+import {
+  DEFAULT_PROGRESS_STAGES,
+  type ProgressStageConfig,
+} from "../../domain/entities";
+
+export interface ProgressOptions {
+  status: GenerationStatus;
+  stages?: ProgressStageConfig[];
+  subProgress?: number;
+}
+
+export function getProgressForStatus(options: ProgressOptions): number {
+  const { status, stages = DEFAULT_PROGRESS_STAGES, subProgress = 0 } = options;
+
+  const stage = stages.find((s) => s.status === status);
+
+  if (!stage) {
+    return 0;
+  }
+
+  const range = stage.maxProgress - stage.minProgress;
+  const adjustedProgress = stage.minProgress + range * (subProgress / 100);
+
+  return Math.round(adjustedProgress);
+}
+
+export function interpolateProgress(
+  startTime: number,
+  estimatedDurationMs: number,
+  minProgress: number,
+  maxProgress: number,
+): number {
+  const elapsed = Date.now() - startTime;
+  const ratio = Math.min(elapsed / estimatedDurationMs, 1);
+
+  const eased = 1 - Math.pow(1 - ratio, 2);
+
+  const progress = minProgress + (maxProgress - minProgress) * eased;
+  return Math.round(progress);
+}
+
+export function createProgressTracker(stages?: ProgressStageConfig[]) {
+  const effectiveStages = stages ?? DEFAULT_PROGRESS_STAGES;
+  let currentStatus: GenerationStatus = "idle";
+  let stageStartTime = Date.now();
+
+  return {
+    setStatus(status: GenerationStatus): number {
+      currentStatus = status;
+      stageStartTime = Date.now();
+      return getProgressForStatus({ status, stages: effectiveStages });
+    },
+
+    getProgress(subProgress = 0): number {
+      return getProgressForStatus({
+        status: currentStatus,
+        stages: effectiveStages,
+        subProgress,
+      });
+    },
+
+    getCurrentStatus(): GenerationStatus {
+      return currentStatus;
+    },
+
+    getElapsedTime(): number {
+      return Date.now() - stageStartTime;
+    },
+  };
+}

package/src/presentation/hooks/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Presentation Hooks
+ */
+
+export { useGeneration } from "./use-generation";
+export type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from "./use-generation";

package/src/presentation/hooks/use-generation.ts

@@ -0,0 +1,112 @@
+/**
+ * useGeneration Hook
+ * React hook for AI generation with progress tracking
+ */
+
+import { useState, useCallback, useRef } from "react";
+import type {
+  GenerationRequest,
+  GenerationResult,
+  GenerationProgress,
+  GenerationCapability,
+} from "../../domain/entities";
+import { generationOrchestrator } from "../../infrastructure/services";
+
+export interface UseGenerationOptions {
+  model: string;
+  capability?: GenerationCapability;
+  onSuccess?: <T>(result: GenerationResult<T>) => void;
+  onError?: (error: string) => void;
+  onProgress?: (progress: GenerationProgress) => void;
+}
+
+export interface UseGenerationReturn<T = unknown> {
+  generate: (input: Record<string, unknown>, userId?: string) => Promise<void>;
+  result: GenerationResult<T> | null;
+  progress: GenerationProgress | null;
+  isGenerating: boolean;
+  error: string | null;
+  reset: () => void;
+}
+
+export function useGeneration<T = unknown>(
+  options: UseGenerationOptions,
+): UseGenerationReturn<T> {
+  const [result, setResult] = useState<GenerationResult<T> | null>(null);
+  const [progress, setProgress] = useState<GenerationProgress | null>(null);
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const abortRef = useRef(false);
+
+  const handleProgress = useCallback(
+    (prog: GenerationProgress) => {
+      if (abortRef.current) return;
+      setProgress(prog);
+      options.onProgress?.(prog);
+    },
+    [options],
+  );
+
+  const generate = useCallback(
+    async (input: Record<string, unknown>, userId?: string) => {
+      abortRef.current = false;
+      setIsGenerating(true);
+      setError(null);
+      setResult(null);
+      setProgress({ stage: "preparing", progress: 0 });
+
+      try {
+        const request: GenerationRequest = {
+          model: options.model,
+          input,
+          userId,
+          capability: options.capability,
+          onProgress: handleProgress,
+        };
+
+        const genResult = await generationOrchestrator.generate<T>(request);
+
+        if (abortRef.current) return;
+
+        setResult(genResult);
+
+        if (genResult.success) {
+          options.onSuccess?.(genResult);
+        } else if (genResult.error) {
+          setError(genResult.error);
+          options.onError?.(genResult.error);
+        }
+      } catch (err) {
+        if (abortRef.current) return;
+
+        const errorMessage =
+          err instanceof Error ? err.message : "error.unknown";
+        setError(errorMessage);
+        options.onError?.(errorMessage);
+      } finally {
+        if (!abortRef.current) {
+          setIsGenerating(false);
+        }
+      }
+    },
+    [options, handleProgress],
+  );
+
+  const reset = useCallback(() => {
+    abortRef.current = true;
+    setResult(null);
+    setProgress(null);
+    setIsGenerating(false);
+    setError(null);
+  }, []);
+
+  return {
+    generate,
+    result,
+    progress,
+    isGenerating,
+    error,
+    reset,
+  };
+}