@framers/agentos 0.1.120 → 0.1.121

package/dist/api/analyzeVideo.js

@@ -0,0 +1,136 @@
+import { VideoAnalyzer } from '../core/video/VideoAnalyzer.js';
+import { createVisionPipeline } from '../core/vision/index.js';
+import { recordAgentOSUsage } from './usageLedger.js';
+import { recordAgentOSTurnMetrics, withAgentOSSpan } from '../core/observability/otel.js';
+async function createAutoSpeechToTextProvider() {
+    if (process.env.OPENAI_API_KEY) {
+        const { OpenAIWhisperSpeechToTextProvider } = await import('../speech/providers/OpenAIWhisperSpeechToTextProvider.js');
+        return new OpenAIWhisperSpeechToTextProvider({
+            apiKey: process.env.OPENAI_API_KEY,
+        });
+    }
+    if (process.env.DEEPGRAM_API_KEY) {
+        const { DeepgramBatchSTTProvider } = await import('../speech/providers/DeepgramBatchSTTProvider.js');
+        return new DeepgramBatchSTTProvider({
+            apiKey: process.env.DEEPGRAM_API_KEY,
+        });
+    }
+    if (process.env.ASSEMBLYAI_API_KEY) {
+        const { AssemblyAISTTProvider } = await import('../speech/providers/AssemblyAISTTProvider.js');
+        return new AssemblyAISTTProvider({
+            apiKey: process.env.ASSEMBLYAI_API_KEY,
+        });
+    }
+    if (process.env.AZURE_SPEECH_KEY && process.env.AZURE_SPEECH_REGION) {
+        const { AzureSpeechSTTProvider } = await import('../speech/providers/AzureSpeechSTTProvider.js');
+        return new AzureSpeechSTTProvider({
+            key: process.env.AZURE_SPEECH_KEY,
+            region: process.env.AZURE_SPEECH_REGION,
+        });
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Main API function
+// ---------------------------------------------------------------------------
+/**
+ * Analyses a video and returns structured understanding results.
+ *
+ * Creates a {@link VideoAnalyzer} (backed by auto-detected
+ * VisionPipeline + STT when available), dispatches the analysis
+ * request, and returns a normalised {@link AnalyzeVideoResult}.
+ *
+ * @param opts - Video analysis options.
+ * @returns A promise resolving to the analysis result with description,
+ *   scenes, objects, text, and optional RAG indexing metadata.
+ *
+ * @example
+ * ```ts
+ * const analysis = await analyzeVideo({
+ *   videoUrl: 'https://example.com/demo.mp4',
+ *   prompt: 'What products are shown in this video?',
+ *   transcribeAudio: true,
+ *   descriptionDetail: 'detailed',
+ * });
+ * console.log(analysis.description);
+ * for (const scene of analysis.scenes ?? []) {
+ *   console.log(`[${scene.startSec}s] ${scene.description}`);
+ * }
+ * ```
+ */
+export async function analyzeVideo(opts) {
+    const startedAt = Date.now();
+    let metricStatus = 'ok';
+    if (!opts.videoUrl && !opts.videoBuffer) {
+        throw new Error('Either videoUrl or videoBuffer is required for video analysis.');
+    }
+    try {
+        return await withAgentOSSpan('agentos.api.analyze_video', async (span) => {
+            if (opts.model)
+                span?.setAttribute('llm.model', opts.model);
+            const [visionPipeline, sttProvider] = await Promise.all([
+                createVisionPipeline(opts.model
+                    ? { cloudModel: opts.model }
+                    : undefined),
+                opts.transcribeAudio === false
+                    ? Promise.resolve(undefined)
+                    : createAutoSpeechToTextProvider(),
+            ]);
+            if (sttProvider) {
+                span?.setAttribute('agentos.api.stt_provider', sttProvider.id);
+            }
+            const analyzer = new VideoAnalyzer({
+                visionPipeline,
+                ...(sttProvider ? { sttProvider } : {}),
+            });
+            const result = await analyzer.analyze({
+                video: opts.videoBuffer ?? opts.videoUrl,
+                prompt: opts.prompt,
+                sceneThreshold: opts.sceneThreshold,
+                transcribeAudio: opts.transcribeAudio,
+                descriptionDetail: opts.descriptionDetail,
+                maxFrames: opts.maxFrames,
+                maxScenes: opts.maxScenes,
+                indexForRAG: opts.indexForRAG,
+                onProgress: opts.onProgress,
+            });
+            span?.setAttribute('agentos.api.scene_count', result.scenes.length);
+            return {
+                description: result.summary,
+                scenes: result.scenes,
+                durationSec: result.durationSec,
+                model: opts.model,
+                provider: 'agentos-video-analyzer',
+                text: result.fullTranscript ? [result.fullTranscript] : undefined,
+                fullTranscript: result.fullTranscript,
+                ragChunkIds: result.ragChunkIds,
+                providerMetadata: {
+                    ...result.metadata,
+                    sttProviderId: sttProvider?.id,
+                },
+            };
+        });
+    }
+    catch (error) {
+        metricStatus = 'error';
+        throw error;
+    }
+    finally {
+        try {
+            await recordAgentOSUsage({
+                options: {
+                    ...opts.usageLedger,
+                    source: opts.usageLedger?.source ?? 'analyzeVideo',
+                },
+            });
+        }
+        catch {
+            // Usage persistence is best-effort.
+        }
+        recordAgentOSTurnMetrics({
+            durationMs: Date.now() - startedAt,
+            status: metricStatus,
+        });
+    }
+}
+//# sourceMappingURL=analyzeVideo.js.map

package/dist/api/analyzeVideo.js.map

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

package/dist/api/detectScenes.d.ts

@@ -0,0 +1,82 @@
+import type { Frame, SceneBoundary, SceneDetectionMethod } from '../core/vision/types.js';
+/**
+ * Options for a {@link detectScenes} call.
+ *
+ * At minimum, a `frames` async iterable must be provided. All other
+ * options are optional and map to {@link SceneDetectorConfig} fields.
+ */
+export interface DetectScenesOptions {
+    /**
+     * Async iterable of decoded video frames in time order.
+     * Each frame must contain a raw RGB pixel buffer, a timestamp,
+     * and a sequential index.
+     */
+    frames: AsyncIterable<Frame>;
+    /**
+     * Detection methods to use. Multiple methods are combined by
+     * taking the maximum diff score across all methods.
+     * @default ['histogram', 'ssim']
+     */
+    methods?: SceneDetectionMethod[];
+    /**
+     * Diff score threshold above which a frame transition is classified
+     * as a hard cut. Applied to histogram chi-squared distance (0-1).
+     * @default 0.3
+     */
+    hardCutThreshold?: number;
+    /**
+     * Diff score threshold for gradual transitions (dissolves, fades).
+     * Transitions with scores between this and `hardCutThreshold`
+     * are classified as gradual cuts.
+     * @default 0.15
+     */
+    gradualThreshold?: number;
+    /**
+     * Minimum scene duration in seconds. Scene boundaries that would
+     * create scenes shorter than this are suppressed.
+     * @default 1.0
+     */
+    minSceneDurationSec?: number;
+    /**
+     * CLIP embedding provider for semantic scene detection.
+     * Only used when `methods` includes `'clip'`.
+     * @default 'local'
+     */
+    clipProvider?: 'local' | 'openai';
+}
+/**
+ * Detects scene boundaries in a stream of video frames.
+ *
+ * Creates a {@link SceneDetector} with the supplied configuration and
+ * yields {@link SceneBoundary} objects as visual discontinuities are
+ * detected. The generator completes when the input frame stream is
+ * exhausted.
+ *
+ * Suitable for both pre-recorded video (extract frames via ffmpeg, then
+ * pipe as an async iterable) and live streams (webcam, security camera,
+ * screen capture).
+ *
+ * @param opts - Scene detection options including the frame source.
+ * @returns An AsyncGenerator yielding scene boundaries as they are detected.
+ *
+ * @example
+ * ```ts
+ * // Pre-recorded video
+ * const boundaries: SceneBoundary[] = [];
+ * for await (const boundary of detectScenes({ frames: extractFrames('video.mp4') })) {
+ *   console.log(`Scene ${boundary.index} at ${boundary.startTimeSec}s (${boundary.cutType})`);
+ *   boundaries.push(boundary);
+ * }
+ *
+ * // Live webcam with custom thresholds
+ * for await (const boundary of detectScenes({
+ *   frames: webcamFrameStream,
+ *   hardCutThreshold: 0.4,
+ *   minSceneDurationSec: 2.0,
+ * })) {
+ *   console.log(`Motion detected at ${boundary.startTimeSec}s`);
+ * }
+ * ```
+ */
+export declare function detectScenes(opts: DetectScenesOptions): AsyncGenerator<SceneBoundary>;
+//# sourceMappingURL=detectScenes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"detectScenes.d.ts","sourceRoot":"","sources":["../../src/api/detectScenes.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EAEb,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAMjC;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAE7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAEjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACnC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAuB,YAAY,CACjC,IAAI,EAAE,mBAAmB,GACxB,cAAc,CAAC,aAAa,CAAC,CAY/B"}

package/dist/api/detectScenes.js

@@ -0,0 +1,67 @@
+/**
+ * @file detectScenes.ts
+ * Provider-agnostic scene detection for the AgentOS high-level API.
+ *
+ * Creates a {@link SceneDetector} with the supplied configuration and
+ * returns an AsyncGenerator that yields {@link SceneBoundary} objects
+ * as visual discontinuities are detected in the frame stream.
+ *
+ * This is the high-level companion to the lower-level
+ * {@link SceneDetector.detectScenes} method. It handles construction
+ * and configuration so callers only need to supply frames and optional
+ * thresholds.
+ */
+import { SceneDetector } from '../core/vision/SceneDetector.js';
+// ---------------------------------------------------------------------------
+// Main API function
+// ---------------------------------------------------------------------------
+/**
+ * Detects scene boundaries in a stream of video frames.
+ *
+ * Creates a {@link SceneDetector} with the supplied configuration and
+ * yields {@link SceneBoundary} objects as visual discontinuities are
+ * detected. The generator completes when the input frame stream is
+ * exhausted.
+ *
+ * Suitable for both pre-recorded video (extract frames via ffmpeg, then
+ * pipe as an async iterable) and live streams (webcam, security camera,
+ * screen capture).
+ *
+ * @param opts - Scene detection options including the frame source.
+ * @returns An AsyncGenerator yielding scene boundaries as they are detected.
+ *
+ * @example
+ * ```ts
+ * // Pre-recorded video
+ * const boundaries: SceneBoundary[] = [];
+ * for await (const boundary of detectScenes({ frames: extractFrames('video.mp4') })) {
+ *   console.log(`Scene ${boundary.index} at ${boundary.startTimeSec}s (${boundary.cutType})`);
+ *   boundaries.push(boundary);
+ * }
+ *
+ * // Live webcam with custom thresholds
+ * for await (const boundary of detectScenes({
+ *   frames: webcamFrameStream,
+ *   hardCutThreshold: 0.4,
+ *   minSceneDurationSec: 2.0,
+ * })) {
+ *   console.log(`Motion detected at ${boundary.startTimeSec}s`);
+ * }
+ * ```
+ */
+export async function* detectScenes(opts) {
+    const config = {};
+    if (opts.methods !== undefined)
+        config.methods = opts.methods;
+    if (opts.hardCutThreshold !== undefined)
+        config.hardCutThreshold = opts.hardCutThreshold;
+    if (opts.gradualThreshold !== undefined)
+        config.gradualThreshold = opts.gradualThreshold;
+    if (opts.minSceneDurationSec !== undefined)
+        config.minSceneDurationSec = opts.minSceneDurationSec;
+    if (opts.clipProvider !== undefined)
+        config.clipProvider = opts.clipProvider;
+    const detector = new SceneDetector(config);
+    yield* detector.detectScenes(opts.frames);
+}
+//# sourceMappingURL=detectScenes.js.map

package/dist/api/detectScenes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectScenes.js","sourceRoot":"","sources":["../../src/api/detectScenes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AA+DhE,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,YAAY,CACjC,IAAyB;IAEzB,MAAM,MAAM,GAAwB,EAAE,CAAC;IAEvC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9D,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS;QAAE,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;IACzF,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS;QAAE,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;IACzF,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS;QAAE,MAAM,CAAC,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC;IAClG,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;QAAE,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IAE7E,MAAM,QAAQ,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAE3C,KAAK,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5C,CAAC"}

package/dist/api/generateImage.d.ts

@@ -1,4 +1,5 @@
 import type { GeneratedImage, ImageGenerationResult, ImageProviderOptionBag, ImageResponseFormat, ImageBackground, ImageModality, ImageOutputFormat } from '../core/images/IImageProvider.js';
+import { type MediaProviderPreference } from '../core/media/ProviderPreferences.js';
 import { type AgentOSUsageLedgerOptions } from './usageLedger.js';
 /**
  * Options for a {@link generateImage} call.
@@ -50,6 +51,12 @@ export interface GenerateImageOptions {
     negativePrompt?: string;
     /** Arbitrary provider-specific options not covered by the standard fields. */
     providerOptions?: ImageProviderOptionBag | Record<string, unknown>;
+    /**
+     * Provider preferences for reordering or filtering the fallback chain.
+     * When supplied, the available image providers are reordered according to
+     * `preferred` and filtered by `blocked` before building the chain.
+     */
+    providerPreferences?: MediaProviderPreference;
     /** Optional durable usage ledger configuration for helper-level accounting. */
     usageLedger?: AgentOSUsageLedgerOptions;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"generateImage.d.ts","sourceRoot":"","sources":["../../src/api/generateImage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,iBAAiB,EAClB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAGtF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,wEAAwE;IACxE,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,qEAAqE;IACrE,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnE,+EAA+E;IAC/E,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,qEAAqE;IACrE,KAAK,CAAC,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsG5F"}
+{"version":3,"file":"generateImage.d.ts","sourceRoot":"","sources":["../../src/api/generateImage.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAEV,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,iBAAiB,EAClB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAiHtF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,wEAAwE;IACxE,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,qEAAqE;IACrE,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnE;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C,+EAA+E;IAC/E,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,qEAAqE;IACrE,KAAK,CAAC,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4H5F"}

package/dist/api/generateImage.js

@@ -5,12 +5,121 @@
  * Parses a `provider:model` string, resolves media-provider credentials, and
  * dispatches the request to the appropriate image provider implementation
  * (e.g. OpenAI DALL-E, Stability AI, Replicate).
+ *
+ * When multiple image-capable providers are configured (via env vars), the
+ * primary provider is wrapped in a {@link FallbackImageProxy} so that a
+ * transient failure automatically retries on the next available provider.
  */
-import { createImageProvider } from '../core/images/index.js';
+import { EventEmitter } from 'events';
+import { createImageProvider, hasImageProviderFactory } from '../core/images/index.js';
+import { FallbackImageProxy } from '../core/images/FallbackImageProxy.js';
 import { resolveModelOption, resolveMediaProvider } from './model.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';
+// ---------------------------------------------------------------------------
+// Image provider fallback chain builder
+// ---------------------------------------------------------------------------
+/**
+ * Env-var to provider-id mapping used to detect which image providers have
+ * credentials configured in the current environment.  Order determines
+ * fallback priority (first = highest priority).
+ */
+const IMAGE_PROVIDER_ENV_MAP = [
+    { envKey: 'OPENAI_API_KEY', providerId: 'openai' },
+    { envKey: 'STABILITY_API_KEY', providerId: 'stability' },
+    { envKey: 'REPLICATE_API_TOKEN', providerId: 'replicate' },
+    { envKey: 'BFL_API_KEY', providerId: 'bfl' },
+    { envKey: 'FAL_API_KEY', providerId: 'fal' },
+    { envKey: 'OPENROUTER_API_KEY', providerId: 'openrouter' },
+    { envKey: 'STABLE_DIFFUSION_LOCAL_BASE_URL', providerId: 'stable-diffusion-local' },
+];
+/** Shared emitter for image fallback events (singleton per process). */
+const imageFallbackEmitter = new EventEmitter();
+/**
+ * Detects all image 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 the first in line.
+ * @returns An array of provider IDs suitable for fallback, in priority order.
+ */
+function detectFallbackImageProviders(primaryProviderId) {
+    const fallbacks = [];
+    for (const { envKey, providerId } of IMAGE_PROVIDER_ENV_MAP) {
+        if (providerId === primaryProviderId)
+            continue;
+        if (!process.env[envKey])
+            continue;
+        if (!hasImageProviderFactory(providerId))
+            continue;
+        fallbacks.push(providerId);
+    }
+    return fallbacks;
+}
+/**
+ * Detects all image providers with valid credentials in the environment.
+ *
+ * @returns Provider IDs in priority order.
+ */
+function detectAvailableImageProviders() {
+    const available = [];
+    for (const { envKey, providerId } of IMAGE_PROVIDER_ENV_MAP) {
+        if (!process.env[envKey])
+            continue;
+        if (!hasImageProviderFactory(providerId))
+            continue;
+        available.push(providerId);
+    }
+    return available;
+}
+/**
+ * Creates an {@link IImageProvider} for the resolved primary provider,
+ * optionally wrapped in a {@link FallbackImageProxy} when an ordered
+ * provider chain contains additional image-capable fallbacks.
+ *
+ * @param resolved - The primary resolved provider credentials.
+ * @param providerChain - Optional ordered provider IDs with the primary first.
+ * @returns An initialised image provider (possibly a fallback proxy).
+ */
+async function createImageProviderWithFallback(resolved, providerChain) {
+    const primary = createImageProvider(resolved.providerId);
+    await primary.initialize({
+        apiKey: resolved.apiKey,
+        baseURL: resolved.baseUrl,
+        defaultModelId: resolved.modelId,
+    });
+    const fallbackIds = providerChain
+        ? providerChain.filter((id) => id !== resolved.providerId)
+        : detectFallbackImageProviders(resolved.providerId);
+    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 { modelId: fallbackModelId } = resolveModelOption({ provider: fbId }, 'image');
+            const fbResolved = resolveMediaProvider(fbId, fallbackModelId);
+            const fb = createImageProvider(fbId);
+            await fb.initialize({
+                apiKey: fbResolved.apiKey,
+                baseURL: fbResolved.baseUrl,
+                defaultModelId: fbResolved.modelId,
+            });
+            chain.push(fb);
+        }
+        catch {
+            // Skip providers that fail to initialise (missing creds, etc.).
+        }
+    }
+    if (chain.length <= 1) {
+        return primary;
+    }
+    return new FallbackImageProxy(chain, imageFallbackEmitter);
+}
 /**
  * Generates one or more images using a provider-agnostic `provider:model` string.
  *
@@ -38,7 +147,25 @@ export async function generateImage(opts) {
     let metricModelId;
     try {
         return await withAgentOSSpan('agentos.api.generate_image', async (span) => {
-            const { providerId, modelId } = resolveModelOption(opts, 'image');
+            let providerChain;
+            let providerId;
+            let modelId;
+            if (!opts.provider && !opts.model) {
+                providerChain = resolveProviderChain(detectAvailableImageProviders(), opts.providerPreferences);
+                if (providerChain.length === 0) {
+                    throw new Error('No image provider configured. Set OPENAI_API_KEY, STABILITY_API_KEY, REPLICATE_API_TOKEN, BFL_API_KEY, FAL_API_KEY, OPENROUTER_API_KEY, or STABLE_DIFFUSION_LOCAL_BASE_URL.');
+                }
+                ({ providerId, modelId } = resolveModelOption({ provider: providerChain[0] }, 'image'));
+            }
+            else {
+                ({ providerId, modelId } = resolveModelOption(opts, 'image'));
+                let fallbackIds = detectFallbackImageProviders(providerId);
+                if (opts.providerPreferences) {
+                    const ordered = resolveProviderOrder([providerId, ...fallbackIds], opts.providerPreferences);
+                    fallbackIds = ordered.filter((id) => id !== providerId);
+                }
+                providerChain = [providerId, ...fallbackIds];
+            }
             const resolved = resolveMediaProvider(providerId, modelId, {
                 apiKey: opts.apiKey,
                 baseUrl: opts.baseUrl,
@@ -47,14 +174,11 @@ export async function generateImage(opts) {
             metricModelId = resolved.modelId;
             span?.setAttribute('llm.provider', resolved.providerId);
             span?.setAttribute('llm.model', resolved.modelId);
-            const provider = createImageProvider(resolved.providerId);
-            await provider.initialize({
-                apiKey: resolved.apiKey,
-                baseURL: resolved.baseUrl,
-                defaultModelId: resolved.modelId,
-            });
+            const provider = await createImageProviderWithFallback(resolved, providerChain);
             const result = await provider.generateImage({
-                modelId: resolved.modelId,
+                modelId: provider instanceof FallbackImageProxy
+                    ? undefined
+                    : resolved.modelId,
                 prompt: opts.prompt,
                 modalities: opts.modalities,
                 n: opts.n,

package/dist/api/generateImage.js.map

@@ -1 +1 @@
-{"version":3,"file":"generateImage.js","sourceRoot":"","sources":["../../src/api/generateImage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAU9D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAkC,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AA0E1F;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAA0B;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,YAAY,GAAmB,IAAI,CAAC;IACxC,IAAI,WAA2C,CAAC;IAChD,IAAI,gBAAoC,CAAC;IACzC,IAAI,aAAiC,CAAC;IAEtC,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,4BAA4B,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACxE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAClE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,UAAU,EAAE,OAAO,EAAE;gBACzD,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC,CAAC;YACH,gBAAgB,GAAG,QAAQ,CAAC,UAAU,CAAC;YACvC,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC;YAEjC,IAAI,EAAE,YAAY,CAAC,cAAc,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;YACxD,IAAI,EAAE,YAAY,CAAC,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAElD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC1D,MAAM,QAAQ,CAAC,UAAU,CAAC;gBACxB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,cAAc,EAAE,QAAQ,CAAC,OAAO;aACjC,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC;gBAC1C,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,CAAC,EAAE,IAAI,CAAC,CAAC;gBACT,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;gBACzC,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,eAAe,EAAE,IAAI,CAAC,eAAe;aACtC,CAAC,CAAC;YAEH,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,IAAI,EAAE,YAAY,CAAC,0BAA0B,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACrE,qBAAqB,CAAC,IAAI,EAAE;gBAC1B,YAAY,EAAE,MAAM,CAAC,KAAK,EAAE,YAAY;gBACxC,gBAAgB,EAAE,MAAM,CAAC,KAAK,EAAE,gBAAgB;gBAChD,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,WAAW;gBACtC,YAAY,EAAE,MAAM,CAAC,KAAK,EAAE,YAAY;aACzC,CAAC,CAAC;YAEH,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,OAAO;gBACrB,QAAQ,EAAE,MAAM,CAAC,UAAU;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,YAAY,GAAG,OAAO,CAAC;QACvB,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,kBAAkB,CAAC;gBACvB,UAAU,EAAE,gBAAgB;gBAC5B,OAAO,EAAE,aAAa;gBACtB,KAAK,EAAE,WAAW;oBAChB,CAAC,CAAC;wBACE,YAAY,EAAE,WAAW,CAAC,YAAY;wBACtC,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;wBAC9C,WAAW,EAAE,WAAW,CAAC,WAAW;wBACpC,OAAO,EAAE,WAAW,CAAC,YAAY;qBAClC;oBACH,CAAC,CAAC,SAAS;gBACb,OAAO,EAAE;oBACP,GAAG,IAAI,CAAC,WAAW;oBACnB,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,eAAe;iBACpD;aACF,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,iFAAiF;QACnF,CAAC;QACD,wBAAwB,CAAC;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAClC,MAAM,EAAE,YAAY;YACpB,KAAK,EAAE,iBAAiB,CACtB,WAAW;gBACT,CAAC,CAAC;oBACE,YAAY,EAAE,WAAW,CAAC,YAAY;oBACtC,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;oBAC9C,WAAW,EAAE,WAAW,CAAC,WAAW;oBACpC,YAAY,EAAE,WAAW,CAAC,YAAY;iBACvC;gBACH,CAAC,CAAC,SAAS,CACd;SACF,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}
+{"version":3,"file":"generateImage.js","sourceRoot":"","sources":["../../src/api/generateImage.ts"],"names":[],"mappings":"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"}

package/dist/api/generateMusic.d.ts

@@ -0,0 +1,98 @@
+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 generateMusic} call.
+ *
+ * At minimum, a `prompt` is required. The provider is resolved from
+ * `opts.provider`, `opts.apiKey`, or the first music-capable env var found
+ * (`SUNO_API_KEY` -> `STABILITY_API_KEY` -> `REPLICATE_API_TOKEN` ->
+ * `FAL_API_KEY` -> local MusicGen).
+ */
+export interface GenerateMusicOptions {
+    /** Text prompt describing the desired musical composition. */
+    prompt: string;
+    /**
+     * Explicit provider identifier (e.g. `"suno"`, `"stable-audio"`, `"musicgen-local"`).
+     * When omitted, auto-detection from environment variables is used.
+     */
+    provider?: string;
+    /**
+     * Model identifier within the provider (e.g. `"suno-v3.5"`,
+     * `"stable-audio-open-1.0"`). When omitted, the provider's default
+     * model is used.
+     */
+    model?: string;
+    /** Desired output duration in seconds. Provider limits vary. */
+    durationSec?: number;
+    /** Negative prompt describing musical elements to avoid. */
+    negativePrompt?: string;
+    /** 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 generateMusic}.
+ *
+ * Wraps the core {@link AudioResult} with a simpler, AI-SDK-style shape.
+ */
+export interface GenerateMusicResult {
+    /** Model identifier reported by the provider. */
+    model: string;
+    /** Provider identifier (e.g. `"suno"`, `"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 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 declare function generateMusic(opts: GenerateMusicOptions): Promise<GenerateMusicResult>;
+//# sourceMappingURL=generateMusic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generateMusic.d.ts","sourceRoot":"","sources":["../../src/api/generateMusic.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;AAyKtF;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,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,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,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,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAoJ5F"}