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

package/dist/index.d.cts

@@ -0,0 +1,262 @@
+import { ArtifactType } from '@reaatech/media-pipeline-mcp-core';
+import { ArtifactStore } from '@reaatech/media-pipeline-mcp-storage';
+
+interface ProviderInput {
+    operation: string;
+    params: Record<string, unknown>;
+    config: Record<string, unknown>;
+}
+interface ProviderOutput {
+    data: Buffer | ReadableStream;
+    mimeType: string;
+    metadata: Record<string, unknown>;
+    costUsd?: number;
+    durationMs?: number;
+}
+interface ProviderHealth {
+    healthy: boolean;
+    latency?: number;
+    error?: string;
+}
+interface CostEstimate {
+    costUsd: number;
+    currency: string;
+    breakdown?: Array<{
+        component: string;
+        costUsd: number;
+    }>;
+    estimatedDurationMs?: number;
+}
+interface CacheConfig {
+    mode: 'use' | 'refresh' | 'skip';
+    ttlSeconds?: number;
+    scope?: 'global' | 'tenant';
+}
+interface CacheEntry {
+    key: string;
+    artifactIds: string[];
+    outputs: Record<string, unknown>;
+    costUsd: number;
+    createdAt: string;
+    expiresAt: string;
+    hitCount: number;
+}
+interface ProviderCacheConfig {
+    deterministicParams: string[];
+    nonDeterministicParams: string[];
+    normalize: (inputs: Record<string, unknown>) => Record<string, unknown>;
+}
+interface WebhookPayload {
+    jobId: string;
+    status: 'completed' | 'failed' | 'progress';
+    output?: unknown;
+    pct?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+type RouterStrategy = 'first-success' | 'cheapest-acceptable' | 'fastest';
+interface RouteCandidate {
+    provider: string;
+    model: string;
+    maxQueueMs?: number;
+    maxUsd?: number;
+    inputOverrides?: Record<string, unknown>;
+    weight?: number;
+}
+interface RouteConfig {
+    strategy: RouterStrategy;
+    candidates: RouteCandidate[];
+    timeoutMs?: number;
+    healthTtlMs?: number;
+}
+interface RouteRejection {
+    candidate: RouteCandidate;
+    reason: 'over-budget' | 'unhealthy' | 'queue-full' | 'error' | 'cancelled' | 'fastest-ineligible';
+    detail?: string;
+}
+interface RouteDecision {
+    selected: RouteCandidate;
+    rejected: RouteRejection[];
+    estimate?: CostEstimate;
+    reason: string;
+    decidedAtMs: number;
+}
+type MeshFormat = 'glb' | 'fbx' | 'obj' | 'usdz' | 'ply';
+interface MeshGenInput {
+    prompt?: string;
+    sourceArtifactId?: string;
+    format: MeshFormat;
+    polyBudget?: number;
+    topology?: 'quads' | 'tris';
+    texture?: TextureConfig;
+    animated?: boolean;
+}
+interface TextureConfig {
+    enabled: boolean;
+    pbr?: boolean;
+    resolution?: 512 | 1024 | 2048 | 4096;
+    unwrap?: 'auto' | 'preserve-source';
+}
+interface MeshOutput {
+    artifactId: string;
+    format: MeshFormat;
+    polyCount: number;
+    hasTextures: boolean;
+    hasAnimation: boolean;
+    bboxMeters?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface PricingUnit {
+    perUnit: number;
+    unit?: string;
+}
+interface PricingEntry {
+    input: PricingUnit;
+    output?: PricingUnit;
+    expectedDurationMs?: number;
+    /** Optional per-step cost multiplier (e.g. Stability's diffusion steps). */
+    perStep?: number;
+}
+/** `pricing[operation][model] => PricingEntry`. */
+type PricingTable = Record<string, Record<string, PricingEntry>>;
+interface MediaProviderLike {
+    readonly name: string;
+    readonly supportedOperations: string[];
+    estimateCost(input: ProviderInput): Promise<CostEstimate>;
+    execute(input: ProviderInput): Promise<ProviderOutput>;
+    healthCheck?(): Promise<ProviderHealth>;
+    supportsStreaming?: ReadonlySet<string>;
+    supportsWebhooks?: boolean;
+    webhookSignatureKey?(): Promise<string>;
+    parseWebhookPayload?(headers: Record<string, string>, body: string): Promise<WebhookPayload>;
+}
+
+declare abstract class MediaProvider {
+    abstract readonly name: string;
+    abstract readonly supportedOperations: string[];
+    /** F2: per-provider cache config. Subclasses override to declare deterministic & non-deterministic params. */
+    static cacheConfig: ProviderCacheConfig;
+    /** F4/F5: cost estimation from public pricing */
+    abstract estimateCost(input: ProviderInput): Promise<CostEstimate>;
+    /** F6: set of operations that support streaming; absent = no streaming */
+    supportsStreaming?: ReadonlySet<string>;
+    /** F7: whether this provider supports webhook callbacks */
+    supportsWebhooks?: boolean;
+    /** F7: derive the signature key for webhook verification */
+    webhookSignatureKey?(): Promise<string>;
+    /** F7: parse an incoming webhook payload */
+    parseWebhookPayload?(headers: Record<string, string>, body: string): Promise<WebhookPayload>;
+    protected storage?: ArtifactStore;
+    protected retryConfig: {
+        maxRetries: number;
+        baseDelay: number;
+        maxDelay: number;
+    };
+    /** F2: in-memory cache store */
+    protected cacheStore: Map<string, CacheEntry>;
+    setStorage(storage: ArtifactStore): void;
+    healthCheck?(): Promise<ProviderHealth>;
+    abstract execute(input: ProviderInput): Promise<ProviderOutput>;
+    /**
+     * 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.
+     */
+    executeWithCache(input: ProviderInput, cacheConfig?: CacheConfig): Promise<ProviderOutput>;
+    /** Per-plan defaults when caller omits cacheConfig (F2 §"Backwards-compat" table). */
+    protected defaultCacheConfigForOperation(input: ProviderInput): CacheConfig;
+    /**
+     * 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.
+     */
+    protected computeCacheKey(input: ProviderInput, cacheConfig?: CacheConfig): string;
+    /**
+     * 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).
+     */
+    private filterDeterministic;
+    /** F2: canonical JSON: sorted keys, no whitespace, no trailing zeros */
+    protected canonicalJson(obj: unknown): string;
+    /** F2: strip trailing zeros from numbers */
+    private canonicalNumber;
+    executeWithRetry(input: ProviderInput): Promise<ProviderOutput>;
+    private executeWithRetryImpl;
+    protected isNonRetryableError(error: unknown): boolean;
+    protected generateArtifactId(): string;
+    storeArtifact(data: Buffer | ReadableStream, type: ArtifactType, mimeType: string, metadata: Record<string, unknown>, sourceStep?: string): Promise<string>;
+}
+declare function defineProvider<T extends MediaProvider>(providerClass: new (...args: unknown[]) => T): new (...args: unknown[]) => T;
+
+declare class RouterNoCandidatesError extends Error {
+    readonly code = "ROUTER_NO_CANDIDATES";
+    constructor();
+}
+declare class RouterAllCandidatesFailedError extends Error {
+    readonly code = "ROUTER_ALL_CANDIDATES_FAILED";
+    readonly rejections: RouteRejection[];
+    constructor(rejections: RouteRejection[]);
+}
+interface RouterContext {
+    estimateCost(candidate: RouteCandidate, inputs: ProviderInput): Promise<CostEstimate>;
+    health(candidate: RouteCandidate): Promise<{
+        healthy: boolean;
+        latencyMs?: number;
+        queueDepth?: number;
+    }>;
+    execute(candidate: RouteCandidate, inputs: ProviderInput, signal: AbortSignal): Promise<ProviderOutput>;
+    /**
+     * Expected duration in ms for this candidate's pricing tier. Sourced from per-provider
+     * pricing.json. Return undefined when unknown — that disqualifies the candidate from
+     * `fastest` (the strategy needs an upper bound to enforce its <5s rule).
+     */
+    expectedDurationMs?(candidate: RouteCandidate, inputs: ProviderInput): number | undefined;
+    /**
+     * Per-candidate queue depth from a fresh probe. If absent, the queue check is skipped.
+     * Most providers don't expose queue depth; fal does.
+     */
+    queueMs?(candidate: RouteCandidate): Promise<number | undefined>;
+}
+declare class Router {
+    private ctx;
+    private healthCache;
+    constructor(ctx: RouterContext);
+    route(config: RouteConfig, inputs: ProviderInput): Promise<{
+        decision: RouteDecision;
+        output: ProviderOutput;
+    }>;
+    /**
+     * 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.
+     */
+    private cachedHealth;
+    /** Merge candidate-specific input overrides into the step inputs. */
+    private applyInputOverrides;
+    private routeFirstSuccess;
+    private routeCheapestAcceptable;
+    private routeFastest;
+}
+
+export { type CacheConfig, type CacheEntry, type CostEstimate, MediaProvider, type MediaProviderLike, type MeshFormat, type MeshGenInput, type MeshOutput, type PricingEntry, type PricingTable, type PricingUnit, type ProviderCacheConfig, type ProviderHealth, type ProviderInput, type ProviderOutput, type RouteCandidate, type RouteConfig, type RouteDecision, type RouteRejection, Router, RouterAllCandidatesFailedError, type RouterContext, RouterNoCandidatesError, type RouterStrategy, type TextureConfig, type WebhookPayload, defineProvider };

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+import { ArtifactType } from '@reaatech/media-pipeline-mcp-core';
+import { ArtifactStore } from '@reaatech/media-pipeline-mcp-storage';
+
+interface ProviderInput {
+    operation: string;
+    params: Record<string, unknown>;
+    config: Record<string, unknown>;
+}
+interface ProviderOutput {
+    data: Buffer | ReadableStream;
+    mimeType: string;
+    metadata: Record<string, unknown>;
+    costUsd?: number;
+    durationMs?: number;
+}
+interface ProviderHealth {
+    healthy: boolean;
+    latency?: number;
+    error?: string;
+}
+interface CostEstimate {
+    costUsd: number;
+    currency: string;
+    breakdown?: Array<{
+        component: string;
+        costUsd: number;
+    }>;
+    estimatedDurationMs?: number;
+}
+interface CacheConfig {
+    mode: 'use' | 'refresh' | 'skip';
+    ttlSeconds?: number;
+    scope?: 'global' | 'tenant';
+}
+interface CacheEntry {
+    key: string;
+    artifactIds: string[];
+    outputs: Record<string, unknown>;
+    costUsd: number;
+    createdAt: string;
+    expiresAt: string;
+    hitCount: number;
+}
+interface ProviderCacheConfig {
+    deterministicParams: string[];
+    nonDeterministicParams: string[];
+    normalize: (inputs: Record<string, unknown>) => Record<string, unknown>;
+}
+interface WebhookPayload {
+    jobId: string;
+    status: 'completed' | 'failed' | 'progress';
+    output?: unknown;
+    pct?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+type RouterStrategy = 'first-success' | 'cheapest-acceptable' | 'fastest';
+interface RouteCandidate {
+    provider: string;
+    model: string;
+    maxQueueMs?: number;
+    maxUsd?: number;
+    inputOverrides?: Record<string, unknown>;
+    weight?: number;
+}
+interface RouteConfig {
+    strategy: RouterStrategy;
+    candidates: RouteCandidate[];
+    timeoutMs?: number;
+    healthTtlMs?: number;
+}
+interface RouteRejection {
+    candidate: RouteCandidate;
+    reason: 'over-budget' | 'unhealthy' | 'queue-full' | 'error' | 'cancelled' | 'fastest-ineligible';
+    detail?: string;
+}
+interface RouteDecision {
+    selected: RouteCandidate;
+    rejected: RouteRejection[];
+    estimate?: CostEstimate;
+    reason: string;
+    decidedAtMs: number;
+}
+type MeshFormat = 'glb' | 'fbx' | 'obj' | 'usdz' | 'ply';
+interface MeshGenInput {
+    prompt?: string;
+    sourceArtifactId?: string;
+    format: MeshFormat;
+    polyBudget?: number;
+    topology?: 'quads' | 'tris';
+    texture?: TextureConfig;
+    animated?: boolean;
+}
+interface TextureConfig {
+    enabled: boolean;
+    pbr?: boolean;
+    resolution?: 512 | 1024 | 2048 | 4096;
+    unwrap?: 'auto' | 'preserve-source';
+}
+interface MeshOutput {
+    artifactId: string;
+    format: MeshFormat;
+    polyCount: number;
+    hasTextures: boolean;
+    hasAnimation: boolean;
+    bboxMeters?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface PricingUnit {
+    perUnit: number;
+    unit?: string;
+}
+interface PricingEntry {
+    input: PricingUnit;
+    output?: PricingUnit;
+    expectedDurationMs?: number;
+    /** Optional per-step cost multiplier (e.g. Stability's diffusion steps). */
+    perStep?: number;
+}
+/** `pricing[operation][model] => PricingEntry`. */
+type PricingTable = Record<string, Record<string, PricingEntry>>;
+interface MediaProviderLike {
+    readonly name: string;
+    readonly supportedOperations: string[];
+    estimateCost(input: ProviderInput): Promise<CostEstimate>;
+    execute(input: ProviderInput): Promise<ProviderOutput>;
+    healthCheck?(): Promise<ProviderHealth>;
+    supportsStreaming?: ReadonlySet<string>;
+    supportsWebhooks?: boolean;
+    webhookSignatureKey?(): Promise<string>;
+    parseWebhookPayload?(headers: Record<string, string>, body: string): Promise<WebhookPayload>;
+}
+
+declare abstract class MediaProvider {
+    abstract readonly name: string;
+    abstract readonly supportedOperations: string[];
+    /** F2: per-provider cache config. Subclasses override to declare deterministic & non-deterministic params. */
+    static cacheConfig: ProviderCacheConfig;
+    /** F4/F5: cost estimation from public pricing */
+    abstract estimateCost(input: ProviderInput): Promise<CostEstimate>;
+    /** F6: set of operations that support streaming; absent = no streaming */
+    supportsStreaming?: ReadonlySet<string>;
+    /** F7: whether this provider supports webhook callbacks */
+    supportsWebhooks?: boolean;
+    /** F7: derive the signature key for webhook verification */
+    webhookSignatureKey?(): Promise<string>;
+    /** F7: parse an incoming webhook payload */
+    parseWebhookPayload?(headers: Record<string, string>, body: string): Promise<WebhookPayload>;
+    protected storage?: ArtifactStore;
+    protected retryConfig: {
+        maxRetries: number;
+        baseDelay: number;
+        maxDelay: number;
+    };
+    /** F2: in-memory cache store */
+    protected cacheStore: Map<string, CacheEntry>;
+    setStorage(storage: ArtifactStore): void;
+    healthCheck?(): Promise<ProviderHealth>;
+    abstract execute(input: ProviderInput): Promise<ProviderOutput>;
+    /**
+     * 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.
+     */
+    executeWithCache(input: ProviderInput, cacheConfig?: CacheConfig): Promise<ProviderOutput>;
+    /** Per-plan defaults when caller omits cacheConfig (F2 §"Backwards-compat" table). */
+    protected defaultCacheConfigForOperation(input: ProviderInput): CacheConfig;
+    /**
+     * 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.
+     */
+    protected computeCacheKey(input: ProviderInput, cacheConfig?: CacheConfig): string;
+    /**
+     * 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).
+     */
+    private filterDeterministic;
+    /** F2: canonical JSON: sorted keys, no whitespace, no trailing zeros */
+    protected canonicalJson(obj: unknown): string;
+    /** F2: strip trailing zeros from numbers */
+    private canonicalNumber;
+    executeWithRetry(input: ProviderInput): Promise<ProviderOutput>;
+    private executeWithRetryImpl;
+    protected isNonRetryableError(error: unknown): boolean;
+    protected generateArtifactId(): string;
+    storeArtifact(data: Buffer | ReadableStream, type: ArtifactType, mimeType: string, metadata: Record<string, unknown>, sourceStep?: string): Promise<string>;
+}
+declare function defineProvider<T extends MediaProvider>(providerClass: new (...args: unknown[]) => T): new (...args: unknown[]) => T;
+
+declare class RouterNoCandidatesError extends Error {
+    readonly code = "ROUTER_NO_CANDIDATES";
+    constructor();
+}
+declare class RouterAllCandidatesFailedError extends Error {
+    readonly code = "ROUTER_ALL_CANDIDATES_FAILED";
+    readonly rejections: RouteRejection[];
+    constructor(rejections: RouteRejection[]);
+}
+interface RouterContext {
+    estimateCost(candidate: RouteCandidate, inputs: ProviderInput): Promise<CostEstimate>;
+    health(candidate: RouteCandidate): Promise<{
+        healthy: boolean;
+        latencyMs?: number;
+        queueDepth?: number;
+    }>;
+    execute(candidate: RouteCandidate, inputs: ProviderInput, signal: AbortSignal): Promise<ProviderOutput>;
+    /**
+     * Expected duration in ms for this candidate's pricing tier. Sourced from per-provider
+     * pricing.json. Return undefined when unknown — that disqualifies the candidate from
+     * `fastest` (the strategy needs an upper bound to enforce its <5s rule).
+     */
+    expectedDurationMs?(candidate: RouteCandidate, inputs: ProviderInput): number | undefined;
+    /**
+     * Per-candidate queue depth from a fresh probe. If absent, the queue check is skipped.
+     * Most providers don't expose queue depth; fal does.
+     */
+    queueMs?(candidate: RouteCandidate): Promise<number | undefined>;
+}
+declare class Router {
+    private ctx;
+    private healthCache;
+    constructor(ctx: RouterContext);
+    route(config: RouteConfig, inputs: ProviderInput): Promise<{
+        decision: RouteDecision;
+        output: ProviderOutput;
+    }>;
+    /**
+     * 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.
+     */
+    private cachedHealth;
+    /** Merge candidate-specific input overrides into the step inputs. */
+    private applyInputOverrides;
+    private routeFirstSuccess;
+    private routeCheapestAcceptable;
+    private routeFastest;
+}
+
+export { type CacheConfig, type CacheEntry, type CostEstimate, MediaProvider, type MediaProviderLike, type MeshFormat, type MeshGenInput, type MeshOutput, type PricingEntry, type PricingTable, type PricingUnit, type ProviderCacheConfig, type ProviderHealth, type ProviderInput, type ProviderOutput, type RouteCandidate, type RouteConfig, type RouteDecision, type RouteRejection, Router, RouterAllCandidatesFailedError, type RouterContext, RouterNoCandidatesError, type RouterStrategy, type TextureConfig, type WebhookPayload, defineProvider };