@framers/agentos 0.1.119 → 0.1.121

package/dist/api/generateSFX.js

@@ -0,0 +1,317 @@
+/**
+ * @file generateSFX.ts
+ * Provider-agnostic sound-effect generation for the AgentOS high-level API.
+ *
+ * Resolves an SFX generation provider from explicit `opts.provider`, or by
+ * probing environment variables in priority order:
+ * `ELEVENLABS_API_KEY` -> `STABILITY_API_KEY` -> `REPLICATE_API_TOKEN` ->
+ * `FAL_API_KEY` -> (local AudioGen — no key required).
+ *
+ * When multiple SFX-capable providers are configured (via env vars), the
+ * primary provider is wrapped in a {@link FallbackAudioProxy} so that a
+ * transient failure automatically retries on the next available provider.
+ *
+ * Supports an optional {@link MediaProviderPreference} to reorder or filter
+ * the fallback chain at the caller's discretion.
+ */
+import { EventEmitter } from 'events';
+import { createAudioProvider, hasAudioProviderFactory } from '../core/audio/index.js';
+import { FallbackAudioProxy } from '../core/audio/FallbackAudioProxy.js';
+import { resolveProviderChain, resolveProviderOrder, } from '../core/media/ProviderPreferences.js';
+import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { recordAgentOSUsage } from './usageLedger.js';
+import { recordAgentOSTurnMetrics, withAgentOSSpan } from '../core/observability/otel.js';
+// ---------------------------------------------------------------------------
+// SFX provider fallback chain builder
+// ---------------------------------------------------------------------------
+/**
+ * Env-var to provider-id mapping used to detect which SFX providers have
+ * credentials configured in the current environment. Order determines
+ * fallback priority (first = highest priority).
+ *
+ * The final entry (`audiogen-local`) has no env key requirement — it runs
+ * on the local machine via HuggingFace Transformers.js.
+ */
+const SFX_PROVIDER_ENV_MAP = [
+    { envKey: 'ELEVENLABS_API_KEY', providerId: 'elevenlabs-sfx' },
+    { envKey: 'STABILITY_API_KEY', providerId: 'stable-audio' },
+    { envKey: 'REPLICATE_API_TOKEN', providerId: 'replicate-audio' },
+    { envKey: 'FAL_API_KEY', providerId: 'fal-audio' },
+    { envKey: null, providerId: 'audiogen-local' },
+];
+/** Shared emitter for SFX fallback events (singleton per process). */
+const sfxFallbackEmitter = new EventEmitter();
+function emitAudioProgress(callback, status, progress, message) {
+    if (!callback)
+        return;
+    try {
+        callback({ status, progress, message });
+    }
+    catch {
+        // Progress callbacks are best-effort and must not break generation.
+    }
+}
+/**
+ * Detects the first available SFX provider from environment variables.
+ *
+ * Scans the {@link SFX_PROVIDER_ENV_MAP} in priority order and returns
+ * the first provider whose API key env var is set (or whose factory is
+ * registered with no key requirement, e.g. `audiogen-local`).
+ *
+ * @returns The provider ID and API key, or `undefined` when no SFX
+ *   provider is available.
+ */
+function autoDetectSFXProvider() {
+    const providerId = detectAvailableSFXProviders()[0];
+    if (!providerId)
+        return undefined;
+    const entry = SFX_PROVIDER_ENV_MAP.find((candidate) => candidate.providerId === providerId);
+    return {
+        providerId,
+        apiKey: entry?.envKey ? (process.env[entry.envKey] ?? '') : '',
+    };
+}
+/**
+ * Detects all SFX providers available in the current environment.
+ *
+ * @returns Provider IDs in priority order.
+ */
+function detectAvailableSFXProviders() {
+    const available = [];
+    for (const { envKey, providerId } of SFX_PROVIDER_ENV_MAP) {
+        if (!hasAudioProviderFactory(providerId))
+            continue;
+        if (envKey !== null && !process.env[envKey])
+            continue;
+        available.push(providerId);
+    }
+    return available;
+}
+/**
+ * Detects all SFX providers with valid credentials in the environment
+ * and returns their provider IDs in priority order, excluding the primary.
+ *
+ * @param primaryProviderId - The provider that was explicitly selected; it
+ *   is excluded from the fallback list since it is already first in line.
+ * @returns An array of provider IDs suitable for fallback, in priority order.
+ */
+function detectFallbackSFXProviders(primaryProviderId) {
+    const fallbacks = [];
+    for (const { envKey, providerId } of SFX_PROVIDER_ENV_MAP) {
+        if (providerId === primaryProviderId)
+            continue;
+        if (!hasAudioProviderFactory(providerId))
+            continue;
+        if (envKey !== null && !process.env[envKey])
+            continue;
+        fallbacks.push(providerId);
+    }
+    return fallbacks;
+}
+/**
+ * Resolves the API key environment variable name for a known SFX provider.
+ *
+ * @param providerId - The provider identifier.
+ * @returns The environment variable name, or a generic fallback.
+ */
+function envKeyForSFXProvider(providerId) {
+    const entry = SFX_PROVIDER_ENV_MAP.find((e) => e.providerId === providerId);
+    if (entry?.envKey)
+        return entry.envKey;
+    return `${providerId.toUpperCase().replace(/-/g, '_')}_API_KEY`;
+}
+/**
+ * Creates an {@link IAudioGenerator} for a resolved SFX provider chain,
+ * optionally wrapped in a {@link FallbackAudioProxy} when multiple
+ * SFX-capable providers are available.
+ *
+ * @param providerChain - Ordered provider IDs with the primary first and
+ *   optional fallbacks after it.
+ * @param apiKey - API key for the primary provider.
+ * @param modelId - Optional model identifier override.
+ * @returns An initialised audio provider (possibly a fallback proxy).
+ */
+async function createSFXProviderWithFallback(providerChain, apiKey, modelId, timeoutMs) {
+    if (providerChain.length === 0) {
+        throw new Error('No SFX providers available in the resolved provider chain.');
+    }
+    const [providerId, ...fallbackIds] = providerChain;
+    const primary = createAudioProvider(providerId);
+    await primary.initialize({
+        apiKey,
+        ...(modelId ? { defaultModelId: modelId } : {}),
+        ...(timeoutMs ? { timeoutMs } : {}),
+    });
+    if (fallbackIds.length === 0) {
+        return primary;
+    }
+    // Build and initialise fallback providers. Failures during init are
+    // silently skipped — the provider simply won't be part of the chain.
+    const chain = [primary];
+    for (const fbId of fallbackIds) {
+        try {
+            const entry = SFX_PROVIDER_ENV_MAP.find((e) => e.providerId === fbId);
+            const fbKey = entry?.envKey ? (process.env[entry.envKey] ?? '') : '';
+            const fb = createAudioProvider(fbId);
+            await fb.initialize({
+                apiKey: fbKey,
+                ...(timeoutMs ? { timeoutMs } : {}),
+            });
+            chain.push(fb);
+        }
+        catch {
+            // Skip providers that fail to initialise (missing creds, etc.).
+        }
+    }
+    if (chain.length <= 1) {
+        return primary;
+    }
+    return new FallbackAudioProxy(chain, sfxFallbackEmitter);
+}
+// ---------------------------------------------------------------------------
+// Main API function
+// ---------------------------------------------------------------------------
+/**
+ * Generates a sound effect using a provider-agnostic interface.
+ *
+ * Resolves provider credentials via explicit options or environment variable
+ * auto-detection, initialises the matching audio provider (optionally wrapped
+ * in a fallback chain), and returns a normalised {@link GenerateSFXResult}.
+ *
+ * @param opts - SFX generation options.
+ * @returns A promise resolving to the generation result with audio data and metadata.
+ *
+ * @example
+ * ```ts
+ * const result = await generateSFX({
+ *   prompt: 'Thunder crack followed by heavy rain on a tin roof',
+ *   durationSec: 5,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export async function generateSFX(opts) {
+    const startedAt = Date.now();
+    let metricStatus = 'ok';
+    let metricUsage;
+    let metricProviderId;
+    let metricModelId;
+    try {
+        return await withAgentOSSpan('agentos.api.generate_sfx', async (span) => {
+            // --- Resolve provider ---
+            let providerId;
+            let apiKey;
+            let providerChain;
+            if (opts.provider) {
+                providerId = opts.provider;
+                apiKey =
+                    opts.apiKey ??
+                        process.env[envKeyForSFXProvider(providerId)] ??
+                        '';
+                // Local providers don't need keys
+                if (!apiKey && providerId !== 'audiogen-local') {
+                    throw new Error(`No API key for SFX provider "${providerId}". Set ${envKeyForSFXProvider(providerId)} or pass apiKey.`);
+                }
+                let fallbackIds = detectFallbackSFXProviders(providerId);
+                if (opts.providerPreferences) {
+                    const ordered = resolveProviderOrder([providerId, ...fallbackIds], opts.providerPreferences);
+                    fallbackIds = ordered.filter((id) => id !== providerId);
+                }
+                providerChain = [providerId, ...fallbackIds];
+            }
+            else if (opts.apiKey) {
+                // Caller supplied a key but no provider — try auto-detect anyway
+                const detected = autoDetectSFXProvider();
+                providerId = detected?.providerId ?? 'elevenlabs-sfx';
+                apiKey = opts.apiKey;
+                let fallbackIds = detectFallbackSFXProviders(providerId);
+                if (opts.providerPreferences) {
+                    const ordered = resolveProviderOrder([providerId, ...fallbackIds], opts.providerPreferences);
+                    fallbackIds = ordered.filter((id) => id !== providerId);
+                }
+                providerChain = [providerId, ...fallbackIds];
+            }
+            else {
+                providerChain = resolveProviderChain(detectAvailableSFXProviders(), opts.providerPreferences);
+                if (providerChain.length === 0) {
+                    throw new Error('No SFX provider configured. Set ELEVENLABS_API_KEY, STABILITY_API_KEY, REPLICATE_API_TOKEN, or FAL_API_KEY.');
+                }
+                providerId = providerChain[0];
+                apiKey = process.env[envKeyForSFXProvider(providerId)] ?? '';
+            }
+            metricProviderId = providerId;
+            metricModelId = opts.model;
+            emitAudioProgress(opts.onProgress, 'queued', 0, `Queued SFX generation with ${providerId}.`);
+            span?.setAttribute('llm.provider', providerId);
+            if (opts.model)
+                span?.setAttribute('llm.model', opts.model);
+            // --- Create provider (with fallback chain) ---
+            const provider = await createSFXProviderWithFallback(providerChain, apiKey, opts.model, opts.timeoutMs);
+            // --- Dispatch to generateSFX ---
+            if (!provider.supports('sfx') || typeof provider.generateSFX !== 'function') {
+                throw new Error(`Provider "${providerId}" does not support SFX generation.`);
+            }
+            emitAudioProgress(opts.onProgress, 'processing', 25, `Generating SFX with ${providerId}.`);
+            const result = await provider.generateSFX({
+                prompt: opts.prompt,
+                modelId: provider instanceof FallbackAudioProxy
+                    ? undefined
+                    : (opts.model ?? provider.defaultModelId),
+                durationSec: opts.durationSec,
+                outputFormat: opts.outputFormat,
+                seed: opts.seed,
+                n: opts.n,
+                userId: opts.userId,
+                providerOptions: opts.providerOptions,
+            });
+            metricUsage = result.usage;
+            metricModelId = result.modelId;
+            span?.setAttribute('agentos.api.audio_clips_count', result.audio.length);
+            if (result.usage?.totalCostUSD !== undefined) {
+                attachUsageAttributes(span, { totalCostUSD: result.usage.totalCostUSD });
+            }
+            emitAudioProgress(opts.onProgress, 'complete', 100, 'SFX generation complete.');
+            return {
+                model: result.modelId,
+                provider: result.providerId,
+                created: result.created,
+                audio: result.audio,
+                usage: result.usage,
+            };
+        });
+    }
+    catch (error) {
+        metricStatus = 'error';
+        emitAudioProgress(opts.onProgress, 'failed', 100, error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+    finally {
+        try {
+            await recordAgentOSUsage({
+                providerId: metricProviderId,
+                modelId: metricModelId,
+                usage: metricUsage
+                    ? {
+                        totalTokens: metricUsage.totalAudioClips,
+                        costUSD: metricUsage.totalCostUSD,
+                    }
+                    : undefined,
+                options: {
+                    ...opts.usageLedger,
+                    source: opts.usageLedger?.source ?? 'generateSFX',
+                },
+            });
+        }
+        catch {
+            // Usage persistence is best-effort and should not break generation.
+        }
+        recordAgentOSTurnMetrics({
+            durationMs: Date.now() - startedAt,
+            status: metricStatus,
+            usage: toTurnMetricUsage(metricUsage
+                ? { totalCostUSD: metricUsage.totalCostUSD }
+                : undefined),
+        });
+    }
+}
+//# sourceMappingURL=generateSFX.js.map

package/dist/api/generateSFX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateSFX.js","sourceRoot":"","sources":["../../src/api/generateSFX.ts"],"names":[],"mappings":"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"}

package/dist/api/generateVideo.d.ts

@@ -0,0 +1,113 @@
+import type { VideoResult, VideoProgressEvent, VideoAspectRatio } from '../core/video/index.js';
+import { type MediaProviderPreference } from '../core/media/ProviderPreferences.js';
+import { type AgentOSUsageLedgerOptions } from './usageLedger.js';
+/**
+ * Options for a {@link generateVideo} call.
+ *
+ * At minimum, a `prompt` is required. The provider is resolved from
+ * `opts.provider`, `opts.apiKey`, or the first video-capable env var
+ * found (`RUNWAY_API_KEY` -> `REPLICATE_API_TOKEN` -> `FAL_API_KEY`).
+ */
+export interface GenerateVideoOptions {
+    /** Text prompt describing the desired video content. */
+    prompt: string;
+    /**
+     * Source image for image-to-video generation. When provided, the
+     * request is dispatched to `imageToVideo()` instead of `generateVideo()`.
+     * Accepts a raw `Buffer`.
+     */
+    image?: Buffer;
+    /**
+     * Explicit provider identifier (e.g. `"runway"`, `"replicate"`, `"fal"`).
+     * When omitted, auto-detection from environment variables is used.
+     */
+    provider?: string;
+    /**
+     * Model identifier within the provider (e.g. `"gen3a_turbo"`,
+     * `"klingai/kling-v1"`). When omitted, the provider's default model
+     * is used.
+     */
+    model?: string;
+    /** Desired output duration in seconds. */
+    durationSec?: number;
+    /** Desired aspect ratio (e.g. `"16:9"`, `"9:16"`). */
+    aspectRatio?: VideoAspectRatio;
+    /** Desired output resolution (e.g. `"1280x720"`, `"720p"`). */
+    resolution?: string;
+    /** Negative prompt describing content to avoid. */
+    negativePrompt?: string;
+    /** Random seed for reproducible generation (provider-dependent). */
+    seed?: number;
+    /**
+     * Maximum time in milliseconds to wait for generation to complete.
+     * Provider-dependent — not all providers honour client-side timeouts.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional progress callback invoked during long-running generation.
+     * Called with a {@link VideoProgressEvent} at each status transition.
+     */
+    onProgress?: (event: VideoProgressEvent) => void;
+    /** Override the provider API key instead of reading from env vars. */
+    apiKey?: string;
+    /** Override the provider base URL. */
+    baseUrl?: string;
+    /**
+     * Provider preferences for reordering or filtering the fallback chain.
+     * When supplied, the available video providers are reordered according to
+     * `preferred` and filtered by `blocked` before building the chain.
+     */
+    providerPreferences?: MediaProviderPreference;
+    /** Optional durable usage ledger configuration for accounting. */
+    usageLedger?: AgentOSUsageLedgerOptions;
+}
+/**
+ * The result returned by {@link generateVideo}.
+ *
+ * Wraps the core {@link VideoResult} with a simpler, AI-SDK-style shape.
+ */
+export interface GenerateVideoResult {
+    /** Model identifier reported by the provider. */
+    model: string;
+    /** Provider identifier (e.g. `"runway"`, `"replicate"`, `"fal"`). */
+    provider: string;
+    /** Unix timestamp (ms) when the video was created. */
+    created: number;
+    /** Array of generated video objects containing URLs or base64 data. */
+    videos: VideoResult['videos'];
+    /** Usage / billing information, if available. */
+    usage?: VideoResult['usage'];
+}
+/**
+ * Generates a video using a provider-agnostic interface.
+ *
+ * Resolves provider credentials via explicit options or environment variable
+ * auto-detection, initialises the matching video provider (optionally wrapped
+ * in a fallback chain), and returns a normalised {@link GenerateVideoResult}.
+ *
+ * When `opts.image` is provided, the request is routed to
+ * {@link IVideoGenerator.imageToVideo} for image-to-video generation.
+ * Otherwise, {@link IVideoGenerator.generateVideo} is used for text-to-video.
+ *
+ * @param opts - Video generation options.
+ * @returns A promise resolving to the generation result with video data and metadata.
+ *
+ * @example
+ * ```ts
+ * // Text-to-video
+ * const result = await generateVideo({
+ *   prompt: 'A drone flying over a misty forest at sunrise',
+ *   provider: 'runway',
+ *   durationSec: 5,
+ * });
+ * console.log(result.videos[0].url);
+ *
+ * // Image-to-video
+ * const i2v = await generateVideo({
+ *   prompt: 'Camera slowly zooms out',
+ *   image: fs.readFileSync('input.png'),
+ * });
+ * ```
+ */
+export declare function generateVideo(opts: GenerateVideoOptions): Promise<GenerateVideoResult>;
+//# sourceMappingURL=generateVideo.d.ts.map

package/dist/api/generateVideo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateVideo.d.ts","sourceRoot":"","sources":["../../src/api/generateVideo.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAoKtF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,sDAAsD;IACtD,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAE/B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAEjD,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAE9C,kEAAkE;IAClE,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,iDAAiD;IACjD,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsK5F"}