@framers/agentos 0.1.119 → 0.1.121

package/dist/core/audio/providers/StableAudioProvider.js

@@ -0,0 +1,192 @@
+/**
+ * @module core/audio/providers/StableAudioProvider
+ *
+ * Audio generation provider for the Stability AI Stable Audio API.
+ *
+ * Stable Audio generates both music and sound effects from text prompts
+ * using the Stable Audio Open model. The API is synchronous: a single
+ * POST request returns audio data directly (no queue or polling).
+ *
+ * ## Supported models
+ *
+ * | Model ID                   | Description                        |
+ * |----------------------------|------------------------------------|
+ * | `stable-audio-open-1.0`    | Stable Audio Open 1.0 — default    |
+ *
+ * ## API flow (synchronous)
+ *
+ * 1. **Generate** — `POST ${baseURL}/audio/generate` with prompt, duration,
+ *    and output format. Returns audio data directly in the response body.
+ *
+ * ## Authentication
+ *
+ * Requires a `STABILITY_API_KEY`. Sent as `Authorization: Bearer ${apiKey}`.
+ *
+ * @see {@link IAudioGenerator} for the provider interface contract.
+ */
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Audio generation provider connecting to the Stability AI Stable Audio API.
+ *
+ * Implements a synchronous request pattern: a single POST request returns
+ * the generated audio data directly. Supports both music and SFX generation.
+ *
+ * @implements {IAudioGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new StableAudioProvider();
+ * await provider.initialize({ apiKey: process.env.STABILITY_API_KEY! });
+ *
+ * const result = await provider.generateMusic({
+ *   prompt: 'Upbeat electronic dance track with heavy bass',
+ *   durationSec: 30,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export class StableAudioProvider {
+    constructor() {
+        /** @inheritdoc */
+        this.providerId = 'stable-audio';
+        /** @inheritdoc */
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    async initialize(config) {
+        const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+        if (!apiKey) {
+            throw new Error('Stable Audio provider requires apiKey (STABILITY_API_KEY).');
+        }
+        this._config = {
+            apiKey,
+            baseURL: typeof config.baseURL === 'string' && config.baseURL.trim()
+                ? config.baseURL.trim()
+                : 'https://api.stability.ai/v2beta',
+            defaultModelId: typeof config.defaultModelId === 'string' && config.defaultModelId.trim()
+                ? config.defaultModelId.trim()
+                : 'stable-audio-open-1.0',
+        };
+        this.defaultModelId = this._config.defaultModelId;
+        this.isInitialized = true;
+    }
+    // -------------------------------------------------------------------------
+    // Generation
+    // -------------------------------------------------------------------------
+    /**
+     * Generate music from a text prompt using the Stability AI audio endpoint.
+     *
+     * @param request - Music generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error.
+     */
+    async generateMusic(request) {
+        if (!this.isInitialized) {
+            throw new Error('Stable Audio provider is not initialized. Call initialize() first.');
+        }
+        return this._generate(request.prompt, request.durationSec, request.modelId);
+    }
+    /**
+     * Generate a sound effect from a text prompt using the Stability AI audio endpoint.
+     *
+     * @param request - SFX generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error.
+     */
+    async generateSFX(request) {
+        if (!this.isInitialized) {
+            throw new Error('Stable Audio provider is not initialized. Call initialize() first.');
+        }
+        return this._generate(request.prompt, request.durationSec, request.modelId);
+    }
+    // -------------------------------------------------------------------------
+    // Capability query
+    // -------------------------------------------------------------------------
+    /**
+     * Stable Audio supports both music and SFX generation.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` for both `'music'` and `'sfx'`.
+     */
+    supports(capability) {
+        return capability === 'music' || capability === 'sfx';
+    }
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    async shutdown() {
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Send a synchronous audio generation request to the Stability AI API.
+     *
+     * The API returns audio data directly in the response body (no queue or
+     * polling required). The response is treated as a binary blob and converted
+     * to a base64-encoded string.
+     *
+     * @param prompt - Text description of the desired audio.
+     * @param durationSec - Desired duration in seconds.
+     * @param modelId - Optional model override.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If the HTTP request fails.
+     * @internal
+     */
+    async _generate(prompt, durationSec, modelId) {
+        const model = modelId || this.defaultModelId || 'stable-audio-open-1.0';
+        const url = `${this._config.baseURL}/audio/generate`;
+        const body = {
+            prompt,
+            output_format: 'mp3',
+        };
+        if (durationSec !== undefined)
+            body.duration = durationSec;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this._config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Stable Audio generation failed (${response.status}): ${errorText}`);
+        }
+        // The API returns raw audio bytes. Convert to base64 for the result envelope.
+        const arrayBuffer = await response.arrayBuffer();
+        const base64 = Buffer.from(arrayBuffer).toString('base64');
+        return {
+            created: Math.floor(Date.now() / 1000),
+            modelId: model,
+            providerId: this.providerId,
+            audio: [{
+                    base64,
+                    mimeType: 'audio/mpeg',
+                    durationSec,
+                    providerMetadata: {},
+                }],
+            usage: {
+                totalAudioClips: 1,
+            },
+        };
+    }
+}
+//# sourceMappingURL=StableAudioProvider.js.map

package/dist/core/audio/providers/StableAudioProvider.js.map

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

package/dist/core/audio/providers/SunoProvider.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @module core/audio/providers/SunoProvider
+ *
+ * Music generation provider for the Suno AI model via Replicate.
+ *
+ * Suno is hosted on Replicate and accessed through the predictions API
+ * using the submit-then-poll pattern. This provider is music-only; it
+ * does not support sound effect generation.
+ *
+ * ## API flow (Replicate submit-poll)
+ *
+ * 1. **Create prediction** — `POST ${baseURL}/predictions` with
+ *    `Prefer: wait=60`. If the model finishes within 60 seconds the
+ *    response already contains the output.
+ * 2. **Poll** (if needed) — `GET prediction.urls.get` until `status` is
+ *    `succeeded`, `failed`, or `canceled`.
+ * 3. **Result** — `output` is the audio URL (string or first array element).
+ *
+ * ## Authentication
+ *
+ * Requires a `SUNO_API_KEY` or `REPLICATE_API_TOKEN`. Sent as
+ * `Authorization: Token ${apiKey}`.
+ *
+ * @see {@link IAudioGenerator} for the provider interface contract.
+ * @see {@link ReplicateVideoProvider} for the video counterpart using
+ *   the same Replicate pattern.
+ */
+import type { IAudioGenerator } from '../IAudioGenerator.js';
+import type { MusicGenerateRequest, SFXGenerateRequest, AudioResult } from '../types.js';
+/**
+ * Configuration for the Suno music generation provider.
+ *
+ * @example
+ * ```typescript
+ * const config: SunoProviderConfig = {
+ *   apiKey: process.env.SUNO_API_KEY ?? process.env.REPLICATE_API_TOKEN!,
+ * };
+ * ```
+ */
+export interface SunoProviderConfig {
+    /**
+     * Replicate API token. Sent as `Authorization: Token ${apiKey}`.
+     * Accepts either SUNO_API_KEY or REPLICATE_API_TOKEN.
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Replicate API. Override for testing or proxy setups.
+     * @default 'https://api.replicate.com/v1'
+     */
+    baseURL?: string;
+    /**
+     * Default model to use when the request doesn't specify one.
+     * @default 'suno-ai/suno'
+     */
+    defaultModelId?: string;
+    /**
+     * Milliseconds between prediction status polls.
+     * @default 5000
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum milliseconds to wait for generation before timing out.
+     * @default 300000
+     */
+    timeoutMs?: number;
+}
+/**
+ * Music generation provider connecting to the Suno AI model on Replicate.
+ *
+ * Follows the Replicate submit-then-poll pattern: create a prediction with
+ * `Prefer: wait=60`, then poll if the model takes longer than the wait window.
+ *
+ * @implements {IAudioGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new SunoProvider();
+ * await provider.initialize({ apiKey: process.env.REPLICATE_API_TOKEN! });
+ *
+ * const result = await provider.generateMusic({
+ *   prompt: 'A jazzy lo-fi hip hop beat with warm piano chords',
+ *   durationSec: 60,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export declare class SunoProvider implements IAudioGenerator {
+    /** @inheritdoc */
+    readonly providerId = "suno";
+    /** @inheritdoc */
+    isInitialized: boolean;
+    /** @inheritdoc */
+    defaultModelId?: string;
+    /** Internal resolved configuration. */
+    private _config;
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    initialize(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate music from a text prompt using the Suno model on Replicate.
+     *
+     * Creates a prediction, waits for synchronous completion (up to 60s), then
+     * polls if still in progress.
+     *
+     * @param request - Music generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    generateMusic(request: MusicGenerateRequest): Promise<AudioResult>;
+    /**
+     * SFX generation is not supported by the Suno model.
+     *
+     * @throws {Error} Always throws — use an SFX-capable provider instead.
+     */
+    generateSFX(_request: SFXGenerateRequest): Promise<AudioResult>;
+    /**
+     * Suno supports music generation only.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` only for `'music'`; `false` for `'sfx'`.
+     */
+    supports(capability: 'music' | 'sfx'): boolean;
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Create a prediction and wait for it to complete.
+     *
+     * Uses `Prefer: wait=60` to get synchronous completion for fast models.
+     * Falls back to polling if the prediction hasn't completed within the
+     * wait window.
+     *
+     * @param model - Model identifier (e.g. 'suno-ai/suno').
+     * @param input - Model input parameters.
+     * @returns The completed prediction object.
+     *
+     * @throws {Error} If prediction creation fails, the prediction fails,
+     *   is canceled, or times out.
+     * @internal
+     */
+    private _runPrediction;
+    /**
+     * Create a new prediction via `POST /predictions`.
+     *
+     * @param model - Model identifier.
+     * @param input - Model input parameters.
+     * @returns The prediction response (may or may not be completed).
+     *
+     * @throws {Error} If the HTTP request fails.
+     * @internal
+     */
+    private _createPrediction;
+    /**
+     * Poll a prediction URL until it reaches a terminal state.
+     *
+     * @param url - The `prediction.urls.get` URL to poll.
+     * @returns The completed prediction object.
+     *
+     * @throws {Error} If polling fails or times out.
+     * @internal
+     */
+    private _pollPrediction;
+    /**
+     * Build an {@link AudioResult} from a completed Replicate prediction.
+     *
+     * @param prediction - The succeeded prediction object.
+     * @param model - Model ID used for the generation.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If no audio URL could be extracted from the output.
+     * @internal
+     */
+    private _buildResult;
+}
+//# sourceMappingURL=SunoProvider.d.ts.map

package/dist/core/audio/providers/SunoProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SunoProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/audio/providers/SunoProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMzF;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAa,YAAW,eAAe;IAClD,kBAAkB;IAClB,SAAgB,UAAU,UAAU;IAEpC,kBAAkB;IACX,aAAa,UAAS;IAE7B,kBAAkB;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IAE/B,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAAkH;IAMjI;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkChE;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBxE;;;;OAIG;IACG,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAUrE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO;IAI9C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B;;;;;;;;;;;;;;OAcG;YACW,cAAc;IAyB5B;;;;;;;;;OASG;YACW,iBAAiB;IA2B/B;;;;;;;;OAQG;YACW,eAAe;IAgC7B;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;CAuBrB"}