@framers/agentos 0.1.119 → 0.1.121

package/dist/api/generateMusic.js

@@ -0,0 +1,319 @@
+/**
+ * @file generateMusic.ts
+ * Provider-agnostic music generation for the AgentOS high-level API.
+ *
+ * Resolves a music generation provider from explicit `opts.provider`, or by
+ * probing environment variables in priority order:
+ * `SUNO_API_KEY` -> `STABILITY_API_KEY` -> `REPLICATE_API_TOKEN` ->
+ * `FAL_API_KEY` -> (local MusicGen — no key required).
+ *
+ * When multiple music-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';
+// ---------------------------------------------------------------------------
+// Music provider fallback chain builder
+// ---------------------------------------------------------------------------
+/**
+ * Env-var to provider-id mapping used to detect which music providers have
+ * credentials configured in the current environment. Order determines
+ * fallback priority (first = highest priority).
+ *
+ * The final entry (`musicgen-local`) has no env key requirement — it runs
+ * on the local machine via HuggingFace Transformers.js.
+ */
+const MUSIC_PROVIDER_ENV_MAP = [
+    { envKey: 'SUNO_API_KEY', providerId: 'suno' },
+    { envKey: 'UDIO_API_KEY', providerId: 'udio' },
+    { envKey: 'STABILITY_API_KEY', providerId: 'stable-audio' },
+    { envKey: 'REPLICATE_API_TOKEN', providerId: 'replicate-audio' },
+    { envKey: 'FAL_API_KEY', providerId: 'fal-audio' },
+    { envKey: null, providerId: 'musicgen-local' },
+];
+/** Shared emitter for music fallback events (singleton per process). */
+const musicFallbackEmitter = 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 music provider from environment variables.
+ *
+ * Scans the {@link MUSIC_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. `musicgen-local`).
+ *
+ * @returns The provider ID and API key, or `undefined` when no music
+ *   provider is available.
+ */
+function autoDetectMusicProvider() {
+    const providerId = detectAvailableMusicProviders()[0];
+    if (!providerId)
+        return undefined;
+    const entry = MUSIC_PROVIDER_ENV_MAP.find((candidate) => candidate.providerId === providerId);
+    return {
+        providerId,
+        apiKey: entry?.envKey ? (process.env[entry.envKey] ?? '') : '',
+    };
+}
+/**
+ * Detects all music providers available in the current environment.
+ *
+ * @returns Provider IDs in priority order.
+ */
+function detectAvailableMusicProviders() {
+    const available = [];
+    for (const { envKey, providerId } of MUSIC_PROVIDER_ENV_MAP) {
+        if (!hasAudioProviderFactory(providerId))
+            continue;
+        if (envKey !== null && !process.env[envKey])
+            continue;
+        available.push(providerId);
+    }
+    return available;
+}
+/**
+ * Detects all music 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 detectFallbackMusicProviders(primaryProviderId) {
+    const fallbacks = [];
+    for (const { envKey, providerId } of MUSIC_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 music provider.
+ *
+ * @param providerId - The provider identifier.
+ * @returns The environment variable name, or a generic fallback.
+ */
+function envKeyForMusicProvider(providerId) {
+    const entry = MUSIC_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 music provider chain,
+ * optionally wrapped in a {@link FallbackAudioProxy} when multiple
+ * music-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 createMusicProviderWithFallback(providerChain, apiKey, modelId, timeoutMs) {
+    if (providerChain.length === 0) {
+        throw new Error('No music 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 = MUSIC_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, musicFallbackEmitter);
+}
+// ---------------------------------------------------------------------------
+// Main API function
+// ---------------------------------------------------------------------------
+/**
+ * Generates music 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 GenerateMusicResult}.
+ *
+ * @param opts - Music generation options.
+ * @returns A promise resolving to the generation result with audio data and metadata.
+ *
+ * @example
+ * ```ts
+ * const result = await generateMusic({
+ *   prompt: 'Upbeat lo-fi hip hop beat with vinyl crackle and mellow piano',
+ *   durationSec: 60,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export async function generateMusic(opts) {
+    const startedAt = Date.now();
+    let metricStatus = 'ok';
+    let metricUsage;
+    let metricProviderId;
+    let metricModelId;
+    try {
+        return await withAgentOSSpan('agentos.api.generate_music', async (span) => {
+            // --- Resolve provider ---
+            let providerId;
+            let apiKey;
+            let providerChain;
+            if (opts.provider) {
+                providerId = opts.provider;
+                apiKey =
+                    opts.apiKey ??
+                        process.env[envKeyForMusicProvider(providerId)] ??
+                        '';
+                // Local providers don't need keys
+                if (!apiKey && providerId !== 'musicgen-local') {
+                    throw new Error(`No API key for music provider "${providerId}". Set ${envKeyForMusicProvider(providerId)} or pass apiKey.`);
+                }
+                let fallbackIds = detectFallbackMusicProviders(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 = autoDetectMusicProvider();
+                providerId = detected?.providerId ?? 'suno';
+                apiKey = opts.apiKey;
+                let fallbackIds = detectFallbackMusicProviders(providerId);
+                if (opts.providerPreferences) {
+                    const ordered = resolveProviderOrder([providerId, ...fallbackIds], opts.providerPreferences);
+                    fallbackIds = ordered.filter((id) => id !== providerId);
+                }
+                providerChain = [providerId, ...fallbackIds];
+            }
+            else {
+                providerChain = resolveProviderChain(detectAvailableMusicProviders(), opts.providerPreferences);
+                if (providerChain.length === 0) {
+                    throw new Error('No music provider configured. Set SUNO_API_KEY, STABILITY_API_KEY, REPLICATE_API_TOKEN, or FAL_API_KEY.');
+                }
+                providerId = providerChain[0];
+                apiKey = process.env[envKeyForMusicProvider(providerId)] ?? '';
+            }
+            metricProviderId = providerId;
+            metricModelId = opts.model;
+            emitAudioProgress(opts.onProgress, 'queued', 0, `Queued music 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 createMusicProviderWithFallback(providerChain, apiKey, opts.model, opts.timeoutMs);
+            if (!provider.supports('music')) {
+                throw new Error(`Provider "${providerId}" does not support music generation.`);
+            }
+            emitAudioProgress(opts.onProgress, 'processing', 25, `Generating music with ${providerId}.`);
+            // --- Dispatch to generateMusic ---
+            const result = await provider.generateMusic({
+                prompt: opts.prompt,
+                modelId: provider instanceof FallbackAudioProxy
+                    ? undefined
+                    : (opts.model ?? provider.defaultModelId),
+                durationSec: opts.durationSec,
+                negativePrompt: opts.negativePrompt,
+                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, 'Music 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 ?? 'generateMusic',
+                },
+            });
+        }
+        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=generateMusic.js.map

package/dist/api/generateMusic.js.map

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

package/dist/api/generateSFX.d.ts

@@ -0,0 +1,96 @@
+import type { AudioResult, AudioOutputFormat, AudioProgressEvent } from '../core/audio/types.js';
+import { type MediaProviderPreference } from '../core/media/ProviderPreferences.js';
+import { type AgentOSUsageLedgerOptions } from './usageLedger.js';
+/**
+ * Options for a {@link generateSFX} call.
+ *
+ * At minimum, a `prompt` is required. The provider is resolved from
+ * `opts.provider`, `opts.apiKey`, or the first SFX-capable env var found
+ * (`ELEVENLABS_API_KEY` -> `STABILITY_API_KEY` -> `REPLICATE_API_TOKEN` ->
+ * `FAL_API_KEY` -> local AudioGen).
+ */
+export interface GenerateSFXOptions {
+    /** Text prompt describing the desired sound effect. */
+    prompt: string;
+    /**
+     * Explicit provider identifier (e.g. `"elevenlabs-sfx"`, `"stable-audio"`,
+     * `"audiogen-local"`). When omitted, auto-detection from environment
+     * variables is used.
+     */
+    provider?: string;
+    /**
+     * Model identifier within the provider. When omitted, the provider's
+     * default model is used.
+     */
+    model?: string;
+    /** Desired output duration in seconds. SFX clips are typically 1-15s. */
+    durationSec?: number;
+    /** Output audio format (e.g. `"mp3"`, `"wav"`). Defaults to provider default. */
+    outputFormat?: AudioOutputFormat;
+    /** Random seed for reproducible generation (provider-dependent). */
+    seed?: number;
+    /**
+     * Maximum time in milliseconds to wait for generation to complete.
+     * Provider-dependent — polling providers enforce this directly.
+     */
+    timeoutMs?: number;
+    /** Number of audio clips to generate. Defaults to 1. */
+    n?: number;
+    /**
+     * Optional progress callback invoked during long-running generation.
+     * Called with an {@link AudioProgressEvent} at each status transition.
+     */
+    onProgress?: (event: AudioProgressEvent) => void;
+    /** Override the provider API key instead of reading from env vars. */
+    apiKey?: string;
+    /** Optional user identifier forwarded to the provider for billing. */
+    userId?: string;
+    /** Arbitrary provider-specific options. */
+    providerOptions?: Record<string, unknown>;
+    /**
+     * Provider preferences for reordering or filtering the fallback chain.
+     * When supplied, the available 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 generateSFX}.
+ *
+ * Wraps the core {@link AudioResult} with a simpler, AI-SDK-style shape.
+ */
+export interface GenerateSFXResult {
+    /** Model identifier reported by the provider. */
+    model: string;
+    /** Provider identifier (e.g. `"elevenlabs-sfx"`, `"stable-audio"`). */
+    provider: string;
+    /** Unix timestamp (seconds) when the audio was created. */
+    created: number;
+    /** Array of generated audio objects containing URLs or base64 data. */
+    audio: AudioResult['audio'];
+    /** Usage / billing information, if available. */
+    usage?: AudioResult['usage'];
+}
+/**
+ * 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 declare function generateSFX(opts: GenerateSFXOptions): Promise<GenerateSFXResult>;
+//# sourceMappingURL=generateSFX.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generateSFX.d.ts","sourceRoot":"","sources":["../../src/api/generateSFX.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAwKtF;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,iFAAiF;IACjF,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAEjC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wDAAwD;IACxD,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAEjD,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1C;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAE9C,kEAAkE;IAClE,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqJtF"}