@reaatech/media-pipeline-mcp-provider-core 0.3.0

package/dist/index.js

@@ -0,0 +1,498 @@
+// src/base-provider.ts
+import { createHash } from "crypto";
+var MediaProvider = class {
+  /** F2: per-provider cache config. Subclasses override to declare deterministic & non-deterministic params. */
+  static cacheConfig = {
+    deterministicParams: [],
+    nonDeterministicParams: [],
+    normalize: (inputs) => {
+      const normalized = {};
+      for (const [key, value] of Object.entries(inputs)) {
+        if (typeof value === "string") {
+          normalized[key] = value.trim().replace(/\s+/g, " ");
+        } else {
+          normalized[key] = value;
+        }
+      }
+      return normalized;
+    }
+  };
+  /** F6: set of operations that support streaming; absent = no streaming */
+  supportsStreaming;
+  /** F7: whether this provider supports webhook callbacks */
+  supportsWebhooks;
+  storage;
+  retryConfig = {
+    maxRetries: 3,
+    baseDelay: 1e3,
+    maxDelay: 3e4
+  };
+  /** F2: in-memory cache store */
+  cacheStore = /* @__PURE__ */ new Map();
+  setStorage(storage) {
+    this.storage = storage;
+  }
+  /**
+   * F2: execute with optional caching layer.
+   *
+   * Resolves cacheConfig:
+   *   - explicit cacheConfig wins
+   *   - else fall back to `defaultCacheConfigForOperation(input)` (per-op default; plan §F2)
+   *
+   * Mode semantics:
+   *   - 'skip'    — bypass cache entirely (no read, no write).
+   *   - 'use'     — read first; on miss, execute and store.
+   *   - 'refresh' — always execute and store the fresh result (replace any existing entry).
+   *
+   * Key formula:
+   *   sha256(provider :: modelId :: modelVersion :: scopeTag :: canonicalJson(deterministicInputs))
+   *   where deterministicInputs = normalize(input.params filtered by ProviderCacheConfig.deterministicParams).
+   *   When deterministicParams is empty (provider didn't override), all params participate.
+   */
+  async executeWithCache(input, cacheConfig) {
+    const effective = cacheConfig ?? this.defaultCacheConfigForOperation(input);
+    if (effective.mode === "skip") {
+      return this.execute(input);
+    }
+    const cacheKey = this.computeCacheKey(input, effective);
+    if (effective.mode === "use") {
+      const cached = this.cacheStore.get(cacheKey);
+      if (cached) {
+        const expires = new Date(cached.expiresAt).getTime();
+        if (expires > Date.now()) {
+          cached.hitCount++;
+          const out = ProviderOutputFromCacheEntry(cached, cached.outputs);
+          return {
+            ...out,
+            costUsd: 0,
+            metadata: { ...out.metadata ?? {}, cached: true, originalCostUsd: cached.costUsd }
+          };
+        }
+        this.cacheStore.delete(cacheKey);
+      }
+    }
+    const result = await this.execute(input);
+    const ttl = effective.ttlSeconds ?? 2592e3;
+    this.cacheStore.set(cacheKey, {
+      key: cacheKey,
+      artifactIds: [],
+      outputs: result,
+      costUsd: result.costUsd ?? 0,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      expiresAt: new Date(Date.now() + ttl * 1e3).toISOString(),
+      hitCount: 0
+    });
+    return result;
+  }
+  /** Per-plan defaults when caller omits cacheConfig (F2 §"Backwards-compat" table). */
+  defaultCacheConfigForOperation(input) {
+    const op = input.operation;
+    const seed = input.params?.seed;
+    if (typeof seed === "number" && seed < 0) {
+      return { mode: "skip" };
+    }
+    if (op === "audio.tts") {
+      return { mode: "skip" };
+    }
+    if (op === "image.generate" || op === "audio.stt" || op === "document.extract") {
+      return { mode: "use" };
+    }
+    return { mode: "skip" };
+  }
+  /**
+   * F2: cache key — provider :: modelId :: modelVersion :: scopeTag :: deterministic-only inputs.
+   *
+   * `modelId` is read from input.params.model (or input.config.model); `modelVersion` from
+   * input.params.model_version (or model_id when it embeds a version like 'flux-pro-1.1').
+   * Scope tag: 'global' or `tenant:<id>` based on cacheConfig.scope. Tenant scope requires
+   * a tenantId on input.config; absence falls back to 'global' with a warning.
+   */
+  computeCacheKey(input, cacheConfig) {
+    const params = input.params;
+    const config = input.config;
+    const modelId = String(params?.model ?? config?.model ?? "unknown");
+    const modelVersion = String(
+      params?.model_version ?? params?.modelVersion ?? config?.model_version ?? "v0"
+    );
+    const providerCacheConfig = this.constructor.cacheConfig;
+    const filtered = this.filterDeterministic(params, providerCacheConfig);
+    const normalized = providerCacheConfig.normalize(filtered);
+    let scopeTag = "global";
+    if (cacheConfig?.scope === "tenant") {
+      const tenantId = config?.tenantId;
+      if (typeof tenantId === "string" && tenantId.length > 0) {
+        scopeTag = `tenant:${tenantId}`;
+      } else {
+        scopeTag = "tenant:UNKNOWN";
+      }
+    }
+    const hash = createHash("sha256");
+    hash.update(this.name);
+    hash.update("::");
+    hash.update(modelId);
+    hash.update("::");
+    hash.update(modelVersion);
+    hash.update("::");
+    hash.update(scopeTag);
+    hash.update("::");
+    hash.update(input.operation);
+    hash.update("::");
+    hash.update(this.canonicalJson(normalized));
+    return hash.digest("hex");
+  }
+  /**
+   * Drop params not in `deterministicParams`. If the list is empty (provider didn't override),
+   * fall back to "all params except those in `nonDeterministicParams`" — and if both lists are
+   * empty, hash every param (legacy behavior).
+   */
+  filterDeterministic(params, pcc) {
+    if (!params) return {};
+    if (pcc.deterministicParams.length > 0) {
+      const out = {};
+      for (const k of pcc.deterministicParams) {
+        if (k in params) out[k] = params[k];
+      }
+      return out;
+    }
+    if (pcc.nonDeterministicParams.length > 0) {
+      const out = {};
+      const skip = new Set(pcc.nonDeterministicParams);
+      for (const [k, v] of Object.entries(params)) {
+        if (!skip.has(k)) out[k] = v;
+      }
+      return out;
+    }
+    return params;
+  }
+  /** F2: canonical JSON: sorted keys, no whitespace, no trailing zeros */
+  canonicalJson(obj) {
+    if (obj === null || obj === void 0) return "null";
+    if (typeof obj === "string") return JSON.stringify(obj);
+    if (typeof obj === "number") return this.canonicalNumber(obj);
+    if (typeof obj === "boolean") return obj ? "true" : "false";
+    if (Array.isArray(obj)) {
+      const items = obj.map((item) => this.canonicalJson(item));
+      return `[${items.join(",")}]`;
+    }
+    if (typeof obj === "object") {
+      const keys = Object.keys(obj).sort();
+      const pairs = keys.map(
+        (k) => `${this.canonicalJson(k)}:${this.canonicalJson(obj[k])}`
+      );
+      return `{${pairs.join(",")}}`;
+    }
+    return String(obj);
+  }
+  /** F2: strip trailing zeros from numbers */
+  canonicalNumber(n) {
+    const s = n.toFixed(10);
+    const trimmed = s.replace(/\.?0+$/, "");
+    return trimmed;
+  }
+  async executeWithRetry(input) {
+    return this.executeWithRetryImpl(input);
+  }
+  async executeWithRetryImpl(input) {
+    let lastError;
+    for (let attempt = 0; attempt < this.retryConfig.maxRetries; attempt++) {
+      try {
+        if (attempt > 0) {
+          const delay = Math.min(
+            this.retryConfig.baseDelay * 2 ** (attempt - 1),
+            this.retryConfig.maxDelay
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        return await this.executeWithCache(input);
+      } catch (error) {
+        lastError = error;
+        if (this.isNonRetryableError(error)) {
+          throw error;
+        }
+      }
+    }
+    throw lastError;
+  }
+  isNonRetryableError(error) {
+    const message = error.message.toLowerCase();
+    return message.includes("authentication") || message.includes("unauthorized") || message.includes("validation") || message.includes("invalid api key");
+  }
+  generateArtifactId() {
+    return `artifact-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+  async storeArtifact(data, type, mimeType, metadata, sourceStep) {
+    if (!this.storage) {
+      throw new Error("Storage not configured for provider");
+    }
+    const id = this.generateArtifactId();
+    const uri = await this.storage.put(id, data, {
+      id,
+      type,
+      mimeType,
+      metadata,
+      sourceStep
+    });
+    return uri;
+  }
+};
+function ProviderOutputFromCacheEntry(_entry, outputs) {
+  return outputs;
+}
+function defineProvider(providerClass) {
+  return providerClass;
+}
+
+// src/router.ts
+var RouterNoCandidatesError = class extends Error {
+  code = "ROUTER_NO_CANDIDATES";
+  constructor() {
+    super("No candidates provided for routing");
+    this.name = "RouterNoCandidatesError";
+  }
+};
+var RouterAllCandidatesFailedError = class extends Error {
+  code = "ROUTER_ALL_CANDIDATES_FAILED";
+  rejections;
+  constructor(rejections) {
+    super("All routing candidates failed");
+    this.name = "RouterAllCandidatesFailedError";
+    this.rejections = rejections;
+  }
+};
+var RouterFastestIneligibleError = class extends Error {
+  code = "ROUTER_FASTEST_INELIGIBLE";
+  ineligibleCandidates;
+  constructor(ineligible) {
+    super(
+      `'fastest' strategy requires all candidates to declare expectedDurationMs < 5000; ${ineligible.length} candidate(s) failed this check`
+    );
+    this.name = "RouterFastestIneligibleError";
+    this.ineligibleCandidates = ineligible;
+  }
+};
+var FASTEST_MAX_DURATION_MS = 5e3;
+var DEFAULT_HEALTH_TTL_MS = 3e4;
+var Router = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  healthCache = /* @__PURE__ */ new Map();
+  async route(config, inputs) {
+    if (config.candidates.length === 0) {
+      throw new RouterNoCandidatesError();
+    }
+    if (config.strategy === "fastest") {
+      const ineligible = [];
+      for (const c of config.candidates) {
+        const dur = this.ctx.expectedDurationMs?.(c, inputs);
+        if (dur === void 0 || dur >= FASTEST_MAX_DURATION_MS) {
+          ineligible.push(c);
+        }
+      }
+      if (ineligible.length > 0) {
+        throw new RouterFastestIneligibleError(ineligible);
+      }
+    }
+    switch (config.strategy) {
+      case "first-success":
+        return this.routeFirstSuccess(config, inputs);
+      case "cheapest-acceptable":
+        return this.routeCheapestAcceptable(config, inputs);
+      case "fastest":
+        return this.routeFastest(config, inputs);
+      default: {
+        const _exhaustive = config.strategy;
+        throw new Error(`Unknown router strategy: ${_exhaustive}`);
+      }
+    }
+  }
+  /**
+   * Cached health probe. Cache key is provider+model so we share the result across
+   * routes that mention the same candidate. TTL defaults to 30s; per-route override
+   * via RouteConfig.healthTtlMs.
+   */
+  async cachedHealth(candidate, ttlMs) {
+    const cacheKey = `${candidate.provider}::${candidate.model}`;
+    const now = Date.now();
+    const existing = this.healthCache.get(cacheKey);
+    if (existing && existing.expiresAtMs > now) {
+      return existing.result;
+    }
+    const result = await this.ctx.health(candidate);
+    this.healthCache.set(cacheKey, { result, expiresAtMs: now + ttlMs });
+    return result;
+  }
+  /** Merge candidate-specific input overrides into the step inputs. */
+  applyInputOverrides(candidate, inputs) {
+    if (!candidate.inputOverrides) return inputs;
+    return {
+      ...inputs,
+      params: { ...inputs.params, ...candidate.inputOverrides }
+    };
+  }
+  async routeFirstSuccess(config, inputs) {
+    const rejections = [];
+    for (const candidate of config.candidates) {
+      if (candidate.maxQueueMs !== void 0 && this.ctx.queueMs) {
+        const queue = await this.ctx.queueMs(candidate);
+        if (queue !== void 0 && queue > candidate.maxQueueMs) {
+          rejections.push({
+            candidate,
+            reason: "queue-full",
+            detail: `Queue ${queue}ms > max ${candidate.maxQueueMs}ms`
+          });
+          continue;
+        }
+      }
+      const controller = new AbortController();
+      const timer = config.timeoutMs ? setTimeout(() => controller.abort(), config.timeoutMs) : void 0;
+      try {
+        const resolved = this.applyInputOverrides(candidate, inputs);
+        const output = await this.ctx.execute(candidate, resolved, controller.signal);
+        clearTimeout(timer);
+        return {
+          decision: {
+            selected: candidate,
+            rejected: rejections,
+            reason: "first-success: candidate succeeded",
+            decidedAtMs: Date.now()
+          },
+          output
+        };
+      } catch (error) {
+        clearTimeout(timer);
+        rejections.push({
+          candidate,
+          reason: "error",
+          detail: error.message
+        });
+      }
+    }
+    throw new RouterAllCandidatesFailedError(rejections);
+  }
+  async routeCheapestAcceptable(config, inputs) {
+    const rejections = [];
+    const healthTtl = config.healthTtlMs ?? DEFAULT_HEALTH_TTL_MS;
+    const results = await Promise.all(
+      config.candidates.map(async (candidate) => {
+        const resolved = this.applyInputOverrides(candidate, inputs);
+        const [estimate, healthResult, queueMs] = await Promise.all([
+          this.ctx.estimateCost(candidate, resolved),
+          this.cachedHealth(candidate, healthTtl),
+          candidate.maxQueueMs !== void 0 && this.ctx.queueMs ? this.ctx.queueMs(candidate) : Promise.resolve(void 0)
+        ]);
+        return { candidate, estimate, health: healthResult, queueMs, resolved };
+      })
+    );
+    const valid = [];
+    for (const r of results) {
+      if (!r.health.healthy) {
+        rejections.push({
+          candidate: r.candidate,
+          reason: "unhealthy",
+          detail: "Health check failed"
+        });
+        continue;
+      }
+      if (r.candidate.maxUsd !== void 0 && r.estimate.costUsd > r.candidate.maxUsd) {
+        rejections.push({
+          candidate: r.candidate,
+          reason: "over-budget",
+          detail: `Estimate ${r.estimate.costUsd} > max ${r.candidate.maxUsd}`
+        });
+        continue;
+      }
+      if (r.candidate.maxQueueMs !== void 0 && r.queueMs !== void 0 && r.queueMs > r.candidate.maxQueueMs) {
+        rejections.push({
+          candidate: r.candidate,
+          reason: "queue-full",
+          detail: `Queue ${r.queueMs}ms > max ${r.candidate.maxQueueMs}ms`
+        });
+        continue;
+      }
+      valid.push(r);
+    }
+    if (valid.length === 0) {
+      throw new RouterAllCandidatesFailedError(rejections);
+    }
+    valid.sort((a, b) => {
+      const costDelta = a.estimate.costUsd - b.estimate.costUsd;
+      if (costDelta !== 0) return costDelta;
+      return (b.candidate.weight ?? 1) - (a.candidate.weight ?? 1);
+    });
+    const best = valid[0];
+    const controller = new AbortController();
+    const timer = config.timeoutMs ? setTimeout(() => controller.abort(), config.timeoutMs) : void 0;
+    try {
+      const output = await this.ctx.execute(best.candidate, best.resolved, controller.signal);
+      clearTimeout(timer);
+      return {
+        decision: {
+          selected: best.candidate,
+          rejected: rejections,
+          estimate: best.estimate,
+          reason: "cheapest-acceptable: lowest cost among healthy candidates",
+          decidedAtMs: Date.now()
+        },
+        output
+      };
+    } catch (error) {
+      clearTimeout(timer);
+      rejections.push({
+        candidate: best.candidate,
+        reason: "error",
+        detail: error.message
+      });
+      throw new RouterAllCandidatesFailedError(rejections);
+    }
+  }
+  async routeFastest(config, inputs) {
+    const rejections = [];
+    const controller = new AbortController();
+    const eligible = config.candidates;
+    const timer = config.timeoutMs ? setTimeout(() => controller.abort(), config.timeoutMs) : void 0;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let remaining = eligible.length;
+      for (const candidate of eligible) {
+        const resolved = this.applyInputOverrides(candidate, inputs);
+        this.ctx.execute(candidate, resolved, controller.signal).then((output) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          controller.abort();
+          resolve({
+            decision: {
+              selected: candidate,
+              rejected: rejections,
+              reason: "fastest: first candidate to complete",
+              decidedAtMs: Date.now()
+            },
+            output
+          });
+        }).catch((error) => {
+          if (settled) return;
+          rejections.push({
+            candidate,
+            reason: "error",
+            detail: error.message
+          });
+          remaining--;
+          if (remaining === 0) {
+            settled = true;
+            clearTimeout(timer);
+            reject(new RouterAllCandidatesFailedError(rejections));
+          }
+        });
+      }
+    });
+  }
+};
+export {
+  MediaProvider,
+  Router,
+  RouterAllCandidatesFailedError,
+  RouterNoCandidatesError,
+  defineProvider
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@reaatech/media-pipeline-mcp-provider-core",
+  "version": "0.3.0",
+  "description": "Abstract base class and shared interfaces for all media provider implementations",
+  "license": "MIT",
+  "author": "Rick Somers <rick@reaatech.com> (https://reaatech.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reaatech/media-pipeline-mcp.git",
+    "directory": "packages/provider-core"
+  },
+  "homepage": "https://github.com/reaatech/media-pipeline-mcp/tree/main/packages/provider-core#readme",
+  "bugs": {
+    "url": "https://github.com/reaatech/media-pipeline-mcp/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@reaatech/media-pipeline-mcp-storage": "0.3.0",
+    "@reaatech/media-pipeline-mcp-core": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist"
+  }
+}