From 8b49db4a6ff8a24890b369593ff5acd259f2e2c3 Mon Sep 17 00:00:00 2001
From: shrimbly <falloon.willie@gmail.com>
Date: Fri, 9 Jan 2026 15:36:48 +1300
Subject: [PATCH] feat(01-02): create provider abstraction interfaces

Add provider abstraction layer in src/lib/providers/types.ts:
- ProviderModel interface for normalized model metadata
- ModelCapability union type for model capabilities
- GenerationInput/GenerationOutput interfaces for unified I/O
- ProviderInterface contract for provider implementations

This establishes the interface contract that all providers
(Gemini, Replicate, fal.ai) will implement in Phase 2.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/lib/providers/types.ts | 129 +++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 src/lib/providers/types.ts

diff --git a/src/lib/providers/types.ts b/src/lib/providers/types.ts
new file mode 100644
index 00000000..8a64220c
--- /dev/null
+++ b/src/lib/providers/types.ts
@@ -0,0 +1,129 @@
+/**
+ * Provider Abstraction Types
+ *
+ * Defines the interface contract for all AI providers (Gemini, Replicate, fal.ai).
+ * Each provider implements ProviderInterface to enable uniform access to different
+ * AI services for model discovery and generation.
+ */
+
+import { ProviderType } from "@/types";
+
+/**
+ * Model capabilities - what operations a model can perform
+ */
+export type ModelCapability =
+  | "text-to-image"
+  | "image-to-image"
+  | "text-to-video"
+  | "image-to-video";
+
+/**
+ * Represents a model from any provider with normalized metadata
+ */
+export interface ProviderModel {
+  /** Provider-specific model ID (e.g., "stability-ai/sdxl" for Replicate) */
+  id: string;
+  /** Human-readable display name */
+  name: string;
+  /** Model description, may be null */
+  description: string | null;
+  /** Which provider this model belongs to */
+  provider: ProviderType;
+  /** What capabilities this model supports */
+  capabilities: ModelCapability[];
+  /** Thumbnail/cover image URL for UI display */
+  coverImage?: string;
+  /** Optional pricing information */
+  pricing?: {
+    type: "per-run" | "per-second";
+    amount: number;
+    currency: string;
+  };
+}
+
+/**
+ * Unified input format for generation across all providers
+ */
+export interface GenerationInput {
+  /** The model to use for generation */
+  model: ProviderModel;
+  /** Text prompt for the generation */
+  prompt: string;
+  /** Input images as base64 data URLs or HTTP URLs */
+  images?: string[];
+  /** Model-specific parameters (varies by provider/model) */
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Unified output format for generation results
+ */
+export interface GenerationOutput {
+  /** Whether the generation succeeded */
+  success: boolean;
+  /** Generated outputs (images or videos) */
+  outputs?: Array<{
+    /** Type of output */
+    type: "image" | "video";
+    /** Base64 data URL of the output */
+    data: string;
+    /** Original URL if applicable (e.g., from provider CDN) */
+    url?: string;
+  }>;
+  /** Error message if success is false */
+  error?: string;
+}
+
+/**
+ * Contract that all provider implementations must fulfill.
+ * Enables uniform access to model discovery and generation across
+ * different AI service providers.
+ */
+export interface ProviderInterface {
+  /** Provider identifier matching ProviderType */
+  id: ProviderType;
+  /** Human-readable provider name */
+  name: string;
+
+  // --- Model Discovery ---
+
+  /**
+   * List all available models from this provider
+   */
+  listModels(): Promise<ProviderModel[]>;
+
+  /**
+   * Get a specific model by ID
+   * @param modelId - The provider-specific model ID
+   * @returns The model or null if not found
+   */
+  getModel(modelId: string): Promise<ProviderModel | null>;
+
+  /**
+   * Search for models matching a query
+   * @param query - Search query string
+   * @returns Matching models
+   */
+  searchModels(query: string): Promise<ProviderModel[]>;
+
+  // --- Generation ---
+
+  /**
+   * Generate content using the specified model
+   * @param input - Generation input with model, prompt, and optional images/parameters
+   * @returns Generation result with outputs or error
+   */
+  generate(input: GenerationInput): Promise<GenerationOutput>;
+
+  // --- Utilities ---
+
+  /**
+   * Check if this provider is configured with a valid API key
+   */
+  isConfigured(): boolean;
+
+  /**
+   * Get the API key for this provider (null if not configured)
+   */
+  getApiKey(): string | null;
+}