@wopr-network/platform-core 1.6.0 → 1.8.0

package/dist/monetization/adapters/tts-factory.test.js

@@ -0,0 +1,129 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { createTTSAdapters, createTTSAdaptersFromEnv } from "./tts-factory.js";
+describe("createTTSAdapters", () => {
+    it("creates both adapters when all config provided", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            elevenlabsApiKey: "sk-el",
+        });
+        expect(result.adapters).toHaveLength(2);
+        expect(result.adapterMap.size).toBe(2);
+        expect(result.skipped).toHaveLength(0);
+    });
+    it("returns adapters in cost-priority order (GPU first)", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            elevenlabsApiKey: "sk-el",
+        });
+        const names = result.adapters.map((a) => a.name);
+        expect(names).toEqual(["chatterbox-tts", "elevenlabs"]);
+    });
+    it("skips chatterbox when no base URL", () => {
+        const result = createTTSAdapters({
+            elevenlabsApiKey: "sk-el",
+        });
+        expect(result.adapters).toHaveLength(1);
+        expect(result.adapters[0].name).toBe("elevenlabs");
+        expect(result.skipped).toEqual(["chatterbox-tts"]);
+    });
+    it("skips elevenlabs when no API key", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+        });
+        expect(result.adapters).toHaveLength(1);
+        expect(result.adapters[0].name).toBe("chatterbox-tts");
+        expect(result.skipped).toEqual(["elevenlabs"]);
+    });
+    it("skips elevenlabs with empty string API key", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            elevenlabsApiKey: "",
+        });
+        expect(result.adapters).toHaveLength(1);
+        expect(result.skipped).toContain("elevenlabs");
+    });
+    it("returns empty result when no config provided", () => {
+        const result = createTTSAdapters({});
+        expect(result.adapters).toHaveLength(0);
+        expect(result.adapterMap.size).toBe(0);
+        expect(result.skipped).toEqual(["chatterbox-tts", "elevenlabs"]);
+    });
+    it("all adapters support tts capability", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            elevenlabsApiKey: "sk-el",
+        });
+        for (const adapter of result.adapters) {
+            expect(adapter.capabilities).toContain("tts");
+        }
+    });
+    it("all adapters implement synthesizeSpeech", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            elevenlabsApiKey: "sk-el",
+        });
+        for (const adapter of result.adapters) {
+            expect(typeof adapter.synthesizeSpeech).toBe("function");
+        }
+    });
+    it("adapterMap keys match adapter names", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            elevenlabsApiKey: "sk-el",
+        });
+        for (const [key, adapter] of result.adapterMap) {
+            expect(key).toBe(adapter.name);
+        }
+    });
+    it("chatterbox adapter is marked self-hosted", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+        });
+        expect(result.adapters[0].selfHosted).toBe(true);
+    });
+    it("elevenlabs adapter is not marked self-hosted", () => {
+        const result = createTTSAdapters({
+            elevenlabsApiKey: "sk-el",
+        });
+        expect(result.adapters[0].selfHosted).toBeUndefined();
+    });
+    it("passes per-adapter config overrides", () => {
+        const result = createTTSAdapters({
+            chatterboxBaseUrl: "http://chatterbox:8000",
+            chatterbox: { costPerChar: 0.000001 },
+            elevenlabsApiKey: "sk-el",
+            elevenlabs: { defaultVoice: "custom-voice" },
+        });
+        expect(result.adapters).toHaveLength(2);
+    });
+});
+describe("createTTSAdaptersFromEnv", () => {
+    afterAll(() => {
+        vi.unstubAllEnvs();
+    });
+    it("reads config from environment variables", () => {
+        vi.stubEnv("CHATTERBOX_BASE_URL", "http://chatterbox:8000");
+        vi.stubEnv("ELEVENLABS_API_KEY", "env-el");
+        const result = createTTSAdaptersFromEnv();
+        expect(result.adapters).toHaveLength(2);
+        const names = result.adapters.map((a) => a.name);
+        expect(names).toEqual(["chatterbox-tts", "elevenlabs"]);
+        expect(result.skipped).toHaveLength(0);
+    });
+    it("returns empty when no env vars set", () => {
+        vi.stubEnv("CHATTERBOX_BASE_URL", "");
+        vi.stubEnv("ELEVENLABS_API_KEY", "");
+        const result = createTTSAdaptersFromEnv();
+        expect(result.adapters).toHaveLength(0);
+        expect(result.skipped).toHaveLength(2);
+    });
+    it("accepts per-adapter overrides alongside env config", () => {
+        vi.stubEnv("CHATTERBOX_BASE_URL", "http://chatterbox:8000");
+        vi.stubEnv("ELEVENLABS_API_KEY", "");
+        const result = createTTSAdaptersFromEnv({
+            chatterbox: { costPerChar: 0.000001 },
+        });
+        expect(result.adapters).toHaveLength(1);
+        expect(result.adapters[0].name).toBe("chatterbox-tts");
+    });
+});

package/dist/monetization/index.d.ts

@@ -20,6 +20,7 @@ export { type ChatterboxTTSAdapterConfig, createChatterboxTTSAdapter } from "./a
 export { createDeepgramAdapter, type DeepgramAdapterConfig } from "./adapters/deepgram.js";
 export { createDeepSeekAdapter, type DeepSeekAdapterConfig } from "./adapters/deepseek.js";
 export { createElevenLabsAdapter, type ElevenLabsAdapterConfig } from "./adapters/elevenlabs.js";
+export { createEmbeddingsAdapters, createEmbeddingsAdaptersFromEnv, type EmbeddingsFactoryConfig, type EmbeddingsFactoryResult, } from "./adapters/embeddings-factory.js";
 export { createGeminiAdapter, type GeminiAdapterConfig } from "./adapters/gemini.js";
 export { createKimiAdapter, type KimiAdapterConfig } from "./adapters/kimi.js";
 export { getMargin, loadMarginConfig, type MarginConfig, type MarginRule, withMarginConfig, } from "./adapters/margin-config.js";
@@ -30,6 +31,8 @@ export { calculateSavings, getRatesForCapability, lookupRate, RATE_TABLE, type R
 export { createReplicateAdapter, type ReplicateAdapterConfig } from "./adapters/replicate.js";
 export { checkHealth, type FetchFn, type SelfHostedAdapterConfig } from "./adapters/self-hosted-base.js";
 export { createTextGenAdapters, createTextGenAdaptersFromEnv, type TextGenFactoryConfig, type TextGenFactoryResult, } from "./adapters/text-gen-factory.js";
+export { createTranscriptionAdapters, createTranscriptionAdaptersFromEnv, type TranscriptionFactoryConfig, type TranscriptionFactoryResult, } from "./adapters/transcription-factory.js";
+export { createTTSAdapters, createTTSAdaptersFromEnv, type TTSFactoryConfig, type TTSFactoryResult, } from "./adapters/tts-factory.js";
 export { type AdapterCapability, type AdapterResult, type EmbeddingsInput, type EmbeddingsOutput, type ImageGenerationInput, type ImageGenerationOutput, type MeterEvent, type ProviderAdapter, type TextGenerationInput, type TextGenerationOutput, type TranscriptionInput, type TranscriptionOutput, type TTSInput, type TTSOutput, withMargin, } from "./adapters/types.js";
 export { type ArbitrageRequest, ArbitrageRouter, type ArbitrageRouterConfig, type MarginRecord, type ModelProviderEntry, NoProviderAvailableError, ProviderRegistry, type ProviderRegistryConfig, type RoutingDecision, } from "./arbitrage/index.js";
 export type { BudgetCheckerConfig, BudgetCheckResult, SpendLimits } from "./budget/index.js";

package/dist/monetization/index.js

@@ -21,6 +21,8 @@ export { createChatterboxTTSAdapter } from "./adapters/chatterbox-tts.js";
 export { createDeepgramAdapter } from "./adapters/deepgram.js";
 export { createDeepSeekAdapter } from "./adapters/deepseek.js";
 export { createElevenLabsAdapter } from "./adapters/elevenlabs.js";
+// Embeddings adapter factory (WOP-2190)
+export { createEmbeddingsAdapters, createEmbeddingsAdaptersFromEnv, } from "./adapters/embeddings-factory.js";
 export { createGeminiAdapter } from "./adapters/gemini.js";
 export { createKimiAdapter } from "./adapters/kimi.js";
 // Margin config (WOP-364)
@@ -35,6 +37,10 @@ export { createReplicateAdapter } from "./adapters/replicate.js";
 export { checkHealth } from "./adapters/self-hosted-base.js";
 // Text-generation adapter factory (WOP-463)
 export { createTextGenAdapters, createTextGenAdaptersFromEnv, } from "./adapters/text-gen-factory.js";
+// Transcription adapter factory
+export { createTranscriptionAdapters, createTranscriptionAdaptersFromEnv, } from "./adapters/transcription-factory.js";
+// TTS adapter factory
+export { createTTSAdapters, createTTSAdaptersFromEnv, } from "./adapters/tts-factory.js";
 export { withMargin, } from "./adapters/types.js";
 // Arbitrage router — multi-provider routing for maximum margin (WOP-463)
 export { ArbitrageRouter, NoProviderAvailableError, ProviderRegistry, } from "./arbitrage/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/monetization/adapters/embeddings-factory.test.ts

@@ -0,0 +1,141 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createEmbeddingsAdapters, createEmbeddingsAdaptersFromEnv } from "./embeddings-factory.js";
+import * as openrouterModule from "./openrouter.js";
+
+describe("createEmbeddingsAdapters", () => {
+  it("creates adapter when API key provided", () => {
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "sk-or",
+    });
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapterMap.size).toBe(1);
+    expect(result.skipped).toHaveLength(0);
+  });
+
+  it("adapter is openrouter", () => {
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "sk-or",
+    });
+
+    expect(result.adapters[0].name).toBe("openrouter");
+  });
+
+  it("skips openrouter when no API key", () => {
+    const result = createEmbeddingsAdapters({});
+
+    expect(result.adapters).toHaveLength(0);
+    expect(result.skipped).toEqual(["openrouter"]);
+  });
+
+  it("skips adapter with empty string key", () => {
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "",
+    });
+
+    expect(result.adapters).toHaveLength(0);
+    expect(result.skipped).toContain("openrouter");
+  });
+
+  it("adapter supports embeddings capability", () => {
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "sk-or",
+    });
+
+    expect(result.adapters[0].capabilities).toContain("embeddings");
+  });
+
+  it("adapter implements embed", () => {
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "sk-or",
+    });
+
+    expect(typeof result.adapters[0].embed).toBe("function");
+  });
+
+  it("adapterMap keys match adapter names", () => {
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "sk-or",
+    });
+
+    for (const [key, adapter] of result.adapterMap) {
+      expect(key).toBe(adapter.name);
+    }
+  });
+
+  it("passes per-adapter config overrides to adapter constructor", () => {
+    const spy = vi.spyOn(openrouterModule, "createOpenRouterAdapter");
+
+    createEmbeddingsAdapters({
+      openrouterApiKey: "sk-or",
+      openrouter: { marginMultiplier: 1.5 },
+    });
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: "sk-or",
+        marginMultiplier: 1.5,
+      }),
+    );
+
+    spy.mockRestore();
+  });
+
+  it("apiKey cannot be overridden via openrouter config", () => {
+    // Ensure apiKey always comes from openrouterApiKey, not from spread
+    const result = createEmbeddingsAdapters({
+      openrouterApiKey: "sk-real",
+      openrouter: { apiKey: "sk-evil" } as never,
+    });
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0].name).toBe("openrouter");
+  });
+});
+
+describe("createEmbeddingsAdaptersFromEnv", () => {
+  beforeEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("reads key from environment variable", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", "env-or");
+
+    const result = createEmbeddingsAdaptersFromEnv();
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0].name).toBe("openrouter");
+    expect(result.skipped).toHaveLength(0);
+  });
+
+  it("returns empty when no env var set", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", "");
+
+    const result = createEmbeddingsAdaptersFromEnv();
+
+    expect(result.adapters).toHaveLength(0);
+    expect(result.skipped).toEqual(["openrouter"]);
+  });
+
+  it("passes per-adapter overrides alongside env key to adapter constructor", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", "env-or");
+    const spy = vi.spyOn(openrouterModule, "createOpenRouterAdapter");
+
+    createEmbeddingsAdaptersFromEnv({
+      openrouter: { marginMultiplier: 1.2 },
+    });
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: "env-or",
+        marginMultiplier: 1.2,
+      }),
+    );
+
+    spy.mockRestore();
+  });
+});

package/src/monetization/adapters/embeddings-factory.ts

@@ -0,0 +1,77 @@
+/**
+ * Embeddings adapter factory — instantiates all available embeddings adapters
+ * from environment config and returns them ready to register.
+ *
+ * Only adapters with valid config are created. The factory never touches
+ * the database — it returns plain ProviderAdapter instances that the caller
+ * registers with an ArbitrageRouter or AdapterSocket.
+ *
+ * Priority order (cheapest first, when all adapters available):
+ *   self-hosted-embeddings (GPU, cheapest — not yet implemented)
+ *   → OpenRouter ($0.02/1M tokens via text-embedding-3-small)
+ */
+
+import { createOpenRouterAdapter, type OpenRouterAdapterConfig } from "./openrouter.js";
+import type { ProviderAdapter } from "./types.js";
+
+/** Top-level factory config. Only providers with an API key are instantiated. */
+export interface EmbeddingsFactoryConfig {
+  /** OpenRouter API key. Omit or empty string to skip. */
+  openrouterApiKey?: string;
+  /** Per-adapter config overrides */
+  openrouter?: Omit<Partial<OpenRouterAdapterConfig>, "apiKey">;
+}
+
+/** Result of the factory — adapters + metadata for observability. */
+export interface EmbeddingsFactoryResult {
+  /** All instantiated adapters, ordered by cost priority (cheapest first). */
+  adapters: ProviderAdapter[];
+  /** Map of adapter name → ProviderAdapter for direct registration. */
+  adapterMap: Map<string, ProviderAdapter>;
+  /** Names of providers that were skipped (missing config). */
+  skipped: string[];
+}
+
+/**
+ * Create embeddings adapters from the provided config.
+ *
+ * Returns only adapters whose API key is present and non-empty.
+ * Order matches arbitrage priority: cheapest first.
+ */
+export function createEmbeddingsAdapters(config: EmbeddingsFactoryConfig): EmbeddingsFactoryResult {
+  const adapters: ProviderAdapter[] = [];
+  const skipped: string[] = [];
+
+  // OpenRouter — $0.02/1M tokens (text-embedding-3-small via OpenAI)
+  if (config.openrouterApiKey) {
+    adapters.push(createOpenRouterAdapter({ ...config.openrouter, apiKey: config.openrouterApiKey }));
+  } else {
+    skipped.push("openrouter");
+  }
+
+  // Future: self-hosted-embeddings will go BEFORE openrouter (GPU tier, cheapest)
+
+  const adapterMap = new Map<string, ProviderAdapter>();
+  for (const adapter of adapters) {
+    adapterMap.set(adapter.name, adapter);
+  }
+
+  return { adapters, adapterMap, skipped };
+}
+
+/**
+ * Create embeddings adapters from environment variables.
+ *
+ * Reads API keys from:
+ *   - OPENROUTER_API_KEY
+ *
+ * Accepts optional per-adapter overrides.
+ */
+export function createEmbeddingsAdaptersFromEnv(
+  overrides?: Omit<EmbeddingsFactoryConfig, "openrouterApiKey">,
+): EmbeddingsFactoryResult {
+  return createEmbeddingsAdapters({
+    openrouterApiKey: process.env.OPENROUTER_API_KEY,
+    ...overrides,
+  });
+}

package/src/monetization/adapters/rate-table.test.ts

@@ -138,6 +138,13 @@ describe("getRatesForCapability", () => {
     expect(rates.map((r) => r.tier)).toContain("premium");
   });
 
+  it("returns premium-only for transcription (no standard tier yet)", () => {
+    const rates = getRatesForCapability("transcription");
+    expect(rates).toHaveLength(1);
+    expect(rates[0].tier).toBe("premium");
+    expect(rates[0].provider).toBe("deepgram");
+  });
+
   it("returns empty array for non-existent capability", () => {
     const rates = getRatesForCapability("image-generation" as unknown as AdapterCapability);
     expect(rates).toHaveLength(0);
@@ -178,7 +185,8 @@ describe("calculateSavings", () => {
   });
 
   it("returns zero when capability has no standard tier", () => {
-    const savings = calculateSavings("image-generation" as unknown as AdapterCapability, 1000);
+    // Transcription only has premium (deepgram) — no self-hosted whisper yet
+    const savings = calculateSavings("transcription", 1000);
     expect(savings).toBe(0);
   });
 

package/src/monetization/adapters/rate-table.ts

@@ -83,9 +83,35 @@ export const RATE_TABLE: RateEntry[] = [
     effectivePrice: 0.0000013, // = costPerUnit * margin ($1.30 per 1M tokens)
   },
 
+  // Transcription - Speech-to-Text
+  // NOTE: No self-hosted whisper adapter yet — only premium (deepgram) available.
+  // When self-hosted-whisper lands, add a standard tier entry here.
+  {
+    capability: "transcription",
+    tier: "premium",
+    provider: "deepgram",
+    costPerUnit: 0.0000717, // $0.0043/min = $0.0000717/sec
+    billingUnit: "per-second",
+    margin: 1.3, // 30% — dashboard default; runtime uses getMargin()
+    effectivePrice: 0.00009321, // = costPerUnit * margin ($93.21 per 1M seconds ≈ $5.59 per 1M minutes)
+  },
+
+  // Embeddings
+  // NOTE: No self-hosted embeddings adapter yet — only premium (openrouter) available.
+  // When self-hosted-embeddings lands, add a standard tier entry here.
+  {
+    capability: "embeddings",
+    tier: "premium",
+    provider: "openrouter",
+    costPerUnit: 0.00000002, // $0.02 per 1M tokens (text-embedding-3-small via OpenRouter)
+    billingUnit: "per-token",
+    margin: 1.3, // 30% — dashboard default; runtime uses getMargin()
+    effectivePrice: 0.000000026, // = costPerUnit * margin ($0.026 per 1M tokens)
+  },
+
   // Future self-hosted adapters will add more entries here:
-  // - transcription: self-hosted-whisper (standard) vs deepgram (premium)
-  // - embeddings: self-hosted-embeddings (standard) vs openrouter (premium)
+  // - transcription: self-hosted-whisper (standard) — when GPU adapter exists
+  // - embeddings: self-hosted-embeddings (standard) — when GPU adapter exists
   // - image-generation: self-hosted-sdxl (standard) vs replicate (premium)
 ];
 

package/src/monetization/adapters/transcription-factory.test.ts

@@ -0,0 +1,110 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { createTranscriptionAdapters, createTranscriptionAdaptersFromEnv } from "./transcription-factory.js";
+
+describe("createTranscriptionAdapters", () => {
+  it("creates deepgram adapter when API key provided", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "sk-dg",
+    });
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapterMap.size).toBe(1);
+    expect(result.skipped).toHaveLength(0);
+  });
+
+  it("returns deepgram as only adapter", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "sk-dg",
+    });
+
+    expect(result.adapters[0].name).toBe("deepgram");
+  });
+
+  it("skips deepgram when no API key", () => {
+    const result = createTranscriptionAdapters({});
+
+    expect(result.adapters).toHaveLength(0);
+    expect(result.skipped).toEqual(["deepgram"]);
+  });
+
+  it("skips deepgram with empty string API key", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "",
+    });
+
+    expect(result.adapters).toHaveLength(0);
+    expect(result.skipped).toContain("deepgram");
+  });
+
+  it("adapter supports transcription capability", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "sk-dg",
+    });
+
+    expect(result.adapters[0].capabilities).toContain("transcription");
+  });
+
+  it("adapter implements transcribe", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "sk-dg",
+    });
+
+    expect(typeof result.adapters[0].transcribe).toBe("function");
+  });
+
+  it("adapterMap keys match adapter names", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "sk-dg",
+    });
+
+    for (const [key, adapter] of result.adapterMap) {
+      expect(key).toBe(adapter.name);
+    }
+  });
+
+  it("passes per-adapter config overrides", () => {
+    const result = createTranscriptionAdapters({
+      deepgramApiKey: "sk-dg",
+      deepgram: { costPerMinute: 0.005, defaultModel: "nova-2-general" },
+    });
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0].name).toBe("deepgram");
+  });
+});
+
+describe("createTranscriptionAdaptersFromEnv", () => {
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("reads API keys from environment variables", () => {
+    vi.stubEnv("DEEPGRAM_API_KEY", "env-dg");
+
+    const result = createTranscriptionAdaptersFromEnv();
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0].name).toBe("deepgram");
+    expect(result.skipped).toHaveLength(0);
+  });
+
+  it("returns empty when no env vars set", () => {
+    vi.stubEnv("DEEPGRAM_API_KEY", "");
+
+    const result = createTranscriptionAdaptersFromEnv();
+
+    expect(result.adapters).toHaveLength(0);
+    expect(result.skipped).toHaveLength(1);
+  });
+
+  it("accepts per-adapter overrides alongside env keys", () => {
+    vi.stubEnv("DEEPGRAM_API_KEY", "env-dg");
+
+    const result = createTranscriptionAdaptersFromEnv({
+      deepgram: { marginMultiplier: 1.5 },
+    });
+
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0].name).toBe("deepgram");
+  });
+});

package/src/monetization/adapters/transcription-factory.ts

@@ -0,0 +1,79 @@
+/**
+ * Transcription adapter factory — instantiates all available STT adapters
+ * from environment config and returns them ready to register.
+ *
+ * Only adapters with valid config are created. The factory never touches
+ * the database — it returns plain ProviderAdapter instances that the caller
+ * registers with an ArbitrageRouter or AdapterSocket.
+ *
+ * Priority order (cheapest first, when all adapters available):
+ *   self-hosted-whisper (GPU, cheapest) → Deepgram ($0.0043/min, third-party)
+ *
+ * NOTE: Self-hosted Whisper adapter doesn't exist yet. When it does, it
+ * will slot in as the GPU tier (cheapest) ahead of Deepgram.
+ */
+
+import { createDeepgramAdapter, type DeepgramAdapterConfig } from "./deepgram.js";
+import type { ProviderAdapter } from "./types.js";
+
+/** Top-level factory config. Only providers with an API key are instantiated. */
+export interface TranscriptionFactoryConfig {
+  /** Deepgram API key. Omit or empty string to skip. */
+  deepgramApiKey?: string;
+  /** Per-adapter config overrides */
+  deepgram?: Omit<Partial<DeepgramAdapterConfig>, "apiKey">;
+}
+
+/** Result of the factory — adapters + metadata for observability. */
+export interface TranscriptionFactoryResult {
+  /** All instantiated adapters, ordered by cost priority (cheapest first). */
+  adapters: ProviderAdapter[];
+  /** Map of adapter name → ProviderAdapter for direct registration. */
+  adapterMap: Map<string, ProviderAdapter>;
+  /** Names of providers that were skipped (no API key). */
+  skipped: string[];
+}
+
+/**
+ * Create transcription adapters from the provided config.
+ *
+ * Returns only adapters whose API key is present and non-empty.
+ * Order matches arbitrage priority: cheapest first.
+ */
+export function createTranscriptionAdapters(config: TranscriptionFactoryConfig): TranscriptionFactoryResult {
+  const adapters: ProviderAdapter[] = [];
+  const skipped: string[] = [];
+
+  // Deepgram — $0.0043/min (Nova-2 wholesale)
+  if (config.deepgramApiKey) {
+    adapters.push(createDeepgramAdapter({ apiKey: config.deepgramApiKey, ...config.deepgram }));
+  } else {
+    skipped.push("deepgram");
+  }
+
+  // Future: self-hosted-whisper will go BEFORE deepgram (GPU tier, cheapest)
+
+  const adapterMap = new Map<string, ProviderAdapter>();
+  for (const adapter of adapters) {
+    adapterMap.set(adapter.name, adapter);
+  }
+
+  return { adapters, adapterMap, skipped };
+}
+
+/**
+ * Create transcription adapters from environment variables.
+ *
+ * Reads API keys from:
+ *   - DEEPGRAM_API_KEY
+ *
+ * Accepts optional per-adapter overrides.
+ */
+export function createTranscriptionAdaptersFromEnv(
+  overrides?: Omit<TranscriptionFactoryConfig, "deepgramApiKey">,
+): TranscriptionFactoryResult {
+  return createTranscriptionAdapters({
+    deepgramApiKey: process.env.DEEPGRAM_API_KEY,
+    ...overrides,
+  });
+}