@framers/agentos 0.9.34 → 0.9.36

package/dist/io/segmentation/consumers/maskToEditMask.js

@@ -0,0 +1,32 @@
+/**
+ * Combine one or more segmentation masks into a single mask Buffer suitable for
+ * `editImage()`'s `mask` input (white = edit region, black = keep).
+ *
+ * @param masks one mask or many (unioned)
+ * @param opts.target `'object'` (default) edits the masked object; `'background'`
+ *   inverts so everything except the object is edited.
+ * @param opts.width/height optional canvas size; defaults to the first mask's.
+ */
+export async function maskToEditMask(masks, opts = {}) {
+    const sharp = (await import('sharp')).default;
+    const list = Array.isArray(masks) ? masks : [masks];
+    if (list.length === 0)
+        throw new Error('maskToEditMask requires at least one mask.');
+    const first = await sharp(list[0].mask).metadata();
+    const width = opts.width ?? first.width ?? 0;
+    const height = opts.height ?? first.height ?? 0;
+    if (width <= 0 || height <= 0) {
+        throw new Error('maskToEditMask: could not determine mask dimensions; pass opts.width and opts.height.');
+    }
+    const layers = await Promise.all(list.map(async (m) => ({
+        input: await sharp(m.mask).resize(width, height, { fit: 'fill' }).greyscale().png().toBuffer(),
+        blend: 'screen', // white-on-black union
+    })));
+    let composed = sharp({ create: { width, height, channels: 3, background: { r: 0, g: 0, b: 0 } } })
+        .composite(layers)
+        .greyscale();
+    if (opts.target === 'background')
+        composed = composed.negate();
+    return composed.png().toBuffer();
+}
+//# sourceMappingURL=maskToEditMask.js.map

package/dist/io/segmentation/consumers/maskToEditMask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maskToEditMask.js","sourceRoot":"","sources":["../../../../src/io/segmentation/consumers/maskToEditMask.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAkC,EAClC,OAA8E,EAAE;IAEhF,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAErF,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAChD,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACrB,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;QAC9F,KAAK,EAAE,QAAiB,EAAE,uBAAuB;KAClD,CAAC,CAAC,CACJ,CAAC;IAEF,IAAI,QAAQ,GAAG,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;SAC/F,SAAS,CAAC,MAAM,CAAC;SACjB,SAAS,EAAE,CAAC;IAEf,IAAI,IAAI,CAAC,MAAM,KAAK,YAAY;QAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC/D,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;AACnC,CAAC"}

package/dist/io/segmentation/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module io/segmentation/errors
+ * Typed error classes for the segmentation surface. Callers can catch by class
+ * to branch on the failure cause.
+ */
+import type { SegmentationMode } from './types.js';
+/**
+ * Thrown before any network call when the resolved provider does not support
+ * the requested prompt mode.
+ */
+export declare class SegmentationModeNotSupportedError extends Error {
+    /** The provider that was asked to segment. */
+    readonly providerId: string;
+    /** The unsupported mode. */
+    readonly mode: SegmentationMode;
+    constructor(providerId: string, mode: SegmentationMode);
+}
+/** Thrown when zero or more than one prompt mode is supplied. */
+export declare class InvalidSegmentationPromptError extends Error {
+    constructor(message: string);
+}
+/** Discriminates the kind of provider-level failure. */
+export type SegmentationErrorCode = 'provider_failed' | 'timeout' | 'invalid_request';
+/** Wraps provider/network failures and poll timeouts. */
+export declare class SegmentationProviderError extends Error {
+    /** Failure category. */
+    readonly code: SegmentationErrorCode;
+    /** Underlying cause, when one exists. */
+    readonly cause?: unknown;
+    constructor(message: string, code: SegmentationErrorCode, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/io/segmentation/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/io/segmentation/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;GAGG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,8CAA8C;IAC9C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,4BAA4B;IAC5B,SAAgB,IAAI,EAAE,gBAAgB,CAAC;gBAE3B,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB;CAMvD;AAED,iEAAiE;AACjE,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,OAAO,EAAE,MAAM;CAI5B;AAED,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAEtF,yDAAyD;AACzD,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,wBAAwB;IACxB,SAAgB,IAAI,EAAE,qBAAqB,CAAC;IAC5C,yCAAyC;IACzC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,KAAK,CAAC,EAAE,OAAO;CAM1E"}

package/dist/io/segmentation/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Thrown before any network call when the resolved provider does not support
+ * the requested prompt mode.
+ */
+export class SegmentationModeNotSupportedError extends Error {
+    constructor(providerId, mode) {
+        super(`Segmentation mode "${mode}" is not supported by provider "${providerId}".`);
+        this.name = 'SegmentationModeNotSupportedError';
+        this.providerId = providerId;
+        this.mode = mode;
+    }
+}
+/** Thrown when zero or more than one prompt mode is supplied. */
+export class InvalidSegmentationPromptError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidSegmentationPromptError';
+    }
+}
+/** Wraps provider/network failures and poll timeouts. */
+export class SegmentationProviderError extends Error {
+    constructor(message, code, cause) {
+        super(message);
+        this.name = 'SegmentationProviderError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/io/segmentation/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/io/segmentation/errors.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,OAAO,iCAAkC,SAAQ,KAAK;IAM1D,YAAY,UAAkB,EAAE,IAAsB;QACpD,KAAK,CAAC,sBAAsB,IAAI,mCAAmC,UAAU,IAAI,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,mCAAmC,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACvD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAKD,yDAAyD;AACzD,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAMlD,YAAY,OAAe,EAAE,IAA2B,EAAE,KAAe;QACvE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/io/segmentation/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module io/segmentation
+ * Public barrel for the image segmentation surface.
+ */
+export * from './types.js';
+export * from './errors.js';
+export { resolveSegmentationMode } from './resolveMode.js';
+export { computeMaskBbox } from './maskGeometry.js';
+export { ReplicateSegmentationProvider } from './providers/ReplicateSegmentationProvider.js';
+export { resolveSegmentationProvider, registerSegmentationProvider, resetSegmentationProviders, } from './SegmentationProviderRegistry.js';
+export { maskToEditMask } from './consumers/maskToEditMask.js';
+export { cropRegion } from './consumers/cropRegion.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/io/segmentation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/io/segmentation/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AAC7F,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/io/segmentation/index.js

@@ -0,0 +1,13 @@
+/**
+ * @module io/segmentation
+ * Public barrel for the image segmentation surface.
+ */
+export * from './types.js';
+export * from './errors.js';
+export { resolveSegmentationMode } from './resolveMode.js';
+export { computeMaskBbox } from './maskGeometry.js';
+export { ReplicateSegmentationProvider } from './providers/ReplicateSegmentationProvider.js';
+export { resolveSegmentationProvider, registerSegmentationProvider, resetSegmentationProviders, } from './SegmentationProviderRegistry.js';
+export { maskToEditMask } from './consumers/maskToEditMask.js';
+export { cropRegion } from './consumers/cropRegion.js';
+//# sourceMappingURL=index.js.map

package/dist/io/segmentation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/segmentation/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AAC7F,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/io/segmentation/maskGeometry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module io/segmentation/maskGeometry
+ */
+import type { SegmentationBox } from './types.js';
+/**
+ * Compute the tight bounding box of the white (luma >= 128) pixels in a mask.
+ * Returns `null` when the mask has no white pixels.
+ *
+ * sharp is loaded lazily, matching the guarded dynamic-import pattern used by
+ * the vision pipeline (src/io/vision/VisionPipeline.ts).
+ */
+export declare function computeMaskBbox(maskPng: Buffer): Promise<SegmentationBox | null>;
+//# sourceMappingURL=maskGeometry.d.ts.map

package/dist/io/segmentation/maskGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maskGeometry.d.ts","sourceRoot":"","sources":["../../../src/io/segmentation/maskGeometry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAwBtF"}

package/dist/io/segmentation/maskGeometry.js

@@ -0,0 +1,37 @@
+/**
+ * Compute the tight bounding box of the white (luma >= 128) pixels in a mask.
+ * Returns `null` when the mask has no white pixels.
+ *
+ * sharp is loaded lazily, matching the guarded dynamic-import pattern used by
+ * the vision pipeline (src/io/vision/VisionPipeline.ts).
+ */
+export async function computeMaskBbox(maskPng) {
+    const sharp = (await import('sharp')).default;
+    const { data, info } = await sharp(maskPng)
+        .greyscale()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    const { width, height, channels } = info;
+    let minX = width;
+    let minY = height;
+    let maxX = -1;
+    let maxY = -1;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            if (data[(y * width + x) * channels] >= 128) {
+                if (x < minX)
+                    minX = x;
+                if (y < minY)
+                    minY = y;
+                if (x > maxX)
+                    maxX = x;
+                if (y > maxY)
+                    maxY = y;
+            }
+        }
+    }
+    if (maxX < 0)
+        return null;
+    return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+}
+//# sourceMappingURL=maskGeometry.js.map

package/dist/io/segmentation/maskGeometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maskGeometry.js","sourceRoot":"","sources":["../../../src/io/segmentation/maskGeometry.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAe;IACnD,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC;SACxC,SAAS,EAAE;SACX,GAAG,EAAE;SACL,QAAQ,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACzC,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IACd,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,GAAG,EAAE,CAAC;gBAC5C,IAAI,CAAC,GAAG,IAAI;oBAAE,IAAI,GAAG,CAAC,CAAC;gBACvB,IAAI,CAAC,GAAG,IAAI;oBAAE,IAAI,GAAG,CAAC,CAAC;gBACvB,IAAI,CAAC,GAAG,IAAI;oBAAE,IAAI,GAAG,CAAC,CAAC;gBACvB,IAAI,CAAC,GAAG,IAAI;oBAAE,IAAI,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;AAC/E,CAAC"}

package/dist/io/segmentation/providers/ReplicateSegmentationProvider.d.ts

@@ -0,0 +1,29 @@
+import type { ISegmentationProvider, SegmentationMode, SegmentationRequest, SegmentationResult } from '../types.js';
+export declare class ReplicateSegmentationProvider implements ISegmentationProvider {
+    readonly providerId = "replicate";
+    isInitialized: boolean;
+    defaultModelId?: string;
+    private keyPool;
+    private readonly versionCache;
+    initialize(config: Record<string, unknown>): Promise<void>;
+    supportedModes(): ReadonlyArray<SegmentationMode>;
+    segment(request: SegmentationRequest): Promise<SegmentationResult>;
+    /**
+     * Build the Replicate `input` object for the request's mode. Field names
+     * target the v1 output contract; confirm per chosen model in the smoke step.
+     */
+    private buildInput;
+    private headers;
+    private runPrediction;
+    /**
+     * Resolve a model id to a concrete version hash. An explicit
+     * `owner/name:version` pin is used directly; a bare `owner/name` is looked up
+     * via the model API for its latest version (cached per provider instance).
+     */
+    private resolveVersion;
+    private extractMaskRefs;
+    private fetchMaskBytes;
+    private decodeMasks;
+    private imageDimensions;
+}
+//# sourceMappingURL=ReplicateSegmentationProvider.d.ts.map

package/dist/io/segmentation/providers/ReplicateSegmentationProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplicateSegmentationProvider.d.ts","sourceRoot":"","sources":["../../../../src/io/segmentation/providers/ReplicateSegmentationProvider.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,qBAAqB,EAErB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAsBrB,qBAAa,6BAA8B,YAAW,qBAAqB;IACzE,SAAgB,UAAU,eAAe;IAClC,aAAa,UAAS;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAEpD,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAahE,cAAc,IAAI,aAAa,CAAC,gBAAgB,CAAC;IAO3C,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6DxE;;;OAGG;IACH,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,OAAO;YAID,aAAa;IAqC3B;;;;OAIG;YACW,cAAc;IA6B5B,OAAO,CAAC,eAAe;YAcT,cAAc;YAWd,WAAW;YAwBX,eAAe;CAK9B"}

package/dist/io/segmentation/providers/ReplicateSegmentationProvider.js

@@ -0,0 +1,235 @@
+/**
+ * @module io/segmentation/providers/ReplicateSegmentationProvider
+ *
+ * Hosted segmentation via Replicate. Geometric prompts (points/box/automatic)
+ * route to a SAM2 model; text prompts route to a GroundedSAM model. Contains
+ * its own minimal predict/poll cycle (no dependency on the image provider).
+ */
+import { ApiKeyPool } from '../../../core/providers/ApiKeyPool.js';
+import { getImageProviderOptions } from '../../media/images/IImageProvider.js';
+import { SegmentationProviderError, SegmentationModeNotSupportedError } from '../errors.js';
+import { computeMaskBbox } from '../maskGeometry.js';
+const REPLICATE_BASE = 'https://api.replicate.com/v1';
+/** Default SAM2 model for geometric prompts. Verify/adjust in the smoke step. */
+const DEFAULT_SAM_MODEL = 'meta/sam-2';
+/** Default GroundedSAM model for text prompts. Verify/adjust in the smoke step. */
+const DEFAULT_GROUNDED_SAM_MODEL = 'schananas/grounded_sam';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class ReplicateSegmentationProvider {
+    constructor() {
+        this.providerId = 'replicate';
+        this.isInitialized = false;
+        this.versionCache = new Map();
+    }
+    async initialize(config) {
+        const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+        if (!apiKey) {
+            throw new SegmentationProviderError('Replicate segmentation provider requires apiKey.', 'provider_failed');
+        }
+        this.keyPool = new ApiKeyPool(apiKey);
+        this.defaultModelId =
+            typeof config.defaultModelId === 'string' && config.defaultModelId.trim()
+                ? config.defaultModelId.trim()
+                : DEFAULT_SAM_MODEL;
+        this.isInitialized = true;
+    }
+    supportedModes() {
+        // Hosted Replicate v1: GroundedSAM (text) + SAM2 automatic ("segment
+        // everything"). Coordinate prompts (points/box) have no clean hosted
+        // single-image model and await a coordinate-capable provider.
+        return ['text', 'automatic'];
+    }
+    async segment(request) {
+        if (!this.isInitialized) {
+            throw new SegmentationProviderError('Replicate segmentation provider is not initialized.', 'provider_failed');
+        }
+        if (!this.supportedModes().includes(request.mode)) {
+            throw new SegmentationModeNotSupportedError(this.providerId, request.mode);
+        }
+        const startedAt = Date.now();
+        const providerOptions = getImageProviderOptions(this.providerId, request.providerOptions);
+        const isText = request.mode === 'text';
+        const modelId = request.modelId
+            || (isText
+                ? (providerOptions?.groundedSamModelId ?? DEFAULT_GROUNDED_SAM_MODEL)
+                : (providerOptions?.samModelId ?? this.defaultModelId ?? DEFAULT_SAM_MODEL));
+        const input = this.buildInput(request, providerOptions);
+        let prediction;
+        try {
+            prediction = await this.runPrediction(modelId, input, providerOptions);
+        }
+        catch (err) {
+            if (err instanceof SegmentationProviderError)
+                throw err;
+            throw new SegmentationProviderError(`Replicate segmentation request failed: ${err.message}`, 'provider_failed', err);
+        }
+        if (prediction.status === 'failed') {
+            throw new SegmentationProviderError(`Replicate segmentation failed: ${prediction.error ?? 'unknown error'}`, 'provider_failed');
+        }
+        if (prediction.status === 'canceled') {
+            throw new SegmentationProviderError('Replicate segmentation was canceled.', 'provider_failed');
+        }
+        const { width, height } = await this.imageDimensions(request.image);
+        let masks = await this.decodeMasks(prediction.output);
+        if (typeof request.minScore === 'number')
+            masks = masks.filter((m) => m.score >= request.minScore);
+        if (typeof request.maxMasks === 'number')
+            masks = masks.slice(0, request.maxMasks);
+        masks = masks.map((m, i) => ({
+            ...m,
+            index: i,
+            // GroundedSAM output carries no per-mask label; fall back to the phrase.
+            label: m.label ?? (request.mode === 'text' ? request.prompt : undefined),
+        }));
+        return {
+            masks,
+            width,
+            height,
+            providerId: this.providerId,
+            modelId,
+            promptMode: request.mode,
+            usage: { totalMasks: masks.length },
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    /**
+     * Build the Replicate `input` object for the request's mode. Field names
+     * target the v1 output contract; confirm per chosen model in the smoke step.
+     */
+    buildInput(request, providerOptions) {
+        const imageDataUrl = `data:image/png;base64,${request.image.toString('base64')}`;
+        const input = { image: imageDataUrl, ...(providerOptions?.input ?? {}) };
+        if (request.mode === 'text') {
+            // GroundedSAM uses `mask_prompt` for the open-vocabulary phrase.
+            input.mask_prompt = request.prompt;
+        }
+        // `automatic` mode: the SAM2 model segments everything from `image` alone.
+        // Tuning params (points_per_side, pred_iou_thresh, stability_score_thresh,
+        // use_m2m) flow through providerOptions.replicate.input.
+        return input;
+    }
+    headers() {
+        return { Authorization: `Token ${this.keyPool.next()}`, 'Content-Type': 'application/json' };
+    }
+    async runPrediction(modelId, input, providerOptions) {
+        const pollIntervalMs = providerOptions?.pollIntervalMs ?? 1000;
+        const timeoutMs = providerOptions?.timeoutMs ?? 120000;
+        // Create the prediction through the version endpoint, which serves both
+        // official and community models. The version-less /models/.../predictions
+        // endpoint only serves official models and 404s for community ones.
+        const version = await this.resolveVersion(modelId);
+        const res = await fetch(`${REPLICATE_BASE}/predictions`, {
+            method: 'POST', headers: this.headers(), body: JSON.stringify({ version, input }),
+        });
+        if (!res.ok) {
+            throw new SegmentationProviderError(`Replicate returned ${res.status}: ${await res.text()}`, 'provider_failed');
+        }
+        let prediction = (await res.json());
+        const deadline = Date.now() + timeoutMs;
+        while (prediction.status
+            && !['succeeded', 'failed', 'canceled'].includes(prediction.status)
+            && prediction.urls?.get) {
+            if (Date.now() > deadline) {
+                throw new SegmentationProviderError('Replicate segmentation timed out.', 'timeout');
+            }
+            await sleep(pollIntervalMs);
+            const pollRes = await fetch(prediction.urls.get, { headers: this.headers() });
+            if (!pollRes.ok) {
+                throw new SegmentationProviderError(`Replicate poll returned ${pollRes.status}.`, 'provider_failed');
+            }
+            prediction = (await pollRes.json());
+        }
+        return prediction;
+    }
+    /**
+     * Resolve a model id to a concrete version hash. An explicit
+     * `owner/name:version` pin is used directly; a bare `owner/name` is looked up
+     * via the model API for its latest version (cached per provider instance).
+     */
+    async resolveVersion(modelId) {
+        const colon = modelId.indexOf(':');
+        if (colon >= 0)
+            return modelId.slice(colon + 1);
+        const cached = this.versionCache.get(modelId);
+        if (cached)
+            return cached;
+        // Require exactly "owner/name" (both non-empty) before building the model
+        // URL, so a malformed override can't produce a "models//name" path.
+        const parts = modelId.split('/');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new SegmentationProviderError(`Invalid modelId "${modelId}": expected "owner/model" or "owner/model:version".`, 'invalid_request');
+        }
+        const res = await fetch(`${REPLICATE_BASE}/models/${modelId}`, { headers: this.headers() });
+        if (!res.ok) {
+            throw new SegmentationProviderError(`Failed to resolve model "${modelId}": ${res.status}`, 'provider_failed');
+        }
+        const data = (await res.json());
+        const version = data.latest_version?.id;
+        if (!version) {
+            throw new SegmentationProviderError(`Model "${modelId}" has no published version.`, 'provider_failed');
+        }
+        this.versionCache.set(modelId, version);
+        return version;
+    }
+    extractMaskRefs(output) {
+        if (Array.isArray(output))
+            return output;
+        if (output && typeof output === 'object') {
+            const o = output;
+            // meta/sam-2 automatic output: { combined_mask, individual_masks: [...] }
+            if (Array.isArray(o.individual_masks))
+                return o.individual_masks;
+            if (Array.isArray(o.masks))
+                return o.masks;
+            if (typeof o.mask === 'string')
+                return [o.mask];
+            if (typeof o.combined_mask === 'string')
+                return [o.combined_mask];
+        }
+        if (typeof output === 'string')
+            return [output];
+        return [];
+    }
+    async fetchMaskBytes(url) {
+        if (url.startsWith('data:')) {
+            return Buffer.from(url.substring(url.indexOf(',') + 1), 'base64');
+        }
+        const res = await fetch(url, { headers: this.headers() });
+        if (!res.ok) {
+            throw new SegmentationProviderError(`Failed to download mask: ${res.status}`, 'provider_failed');
+        }
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async decodeMasks(output) {
+        const refs = this.extractMaskRefs(output);
+        const masks = [];
+        for (let i = 0; i < refs.length; i++) {
+            const ref = refs[i];
+            const url = typeof ref === 'string' ? ref : ref.mask;
+            if (typeof url !== 'string')
+                continue;
+            const png = await this.fetchMaskBytes(url);
+            const bbox = typeof ref === 'object' && Array.isArray(ref.box) && ref.box.length === 4
+                ? { x: ref.box[0], y: ref.box[1], width: ref.box[2] - ref.box[0], height: ref.box[3] - ref.box[1] }
+                : await computeMaskBbox(png);
+            if (!bbox)
+                continue;
+            masks.push({
+                mask: png,
+                bbox,
+                score: typeof ref === 'object' && typeof ref.score === 'number' ? ref.score : 1,
+                label: typeof ref === 'object' && typeof ref.label === 'string' ? ref.label : undefined,
+                index: i,
+            });
+        }
+        return masks;
+    }
+    async imageDimensions(image) {
+        const sharp = (await import('sharp')).default;
+        const meta = await sharp(image).metadata();
+        return { width: meta.width ?? 0, height: meta.height ?? 0 };
+    }
+}
+//# sourceMappingURL=ReplicateSegmentationProvider.js.map

package/dist/io/segmentation/providers/ReplicateSegmentationProvider.js.map

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

package/dist/io/segmentation/resolveMode.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module io/segmentation/resolveMode
+ */
+import type { SegmentOptions, SegmentationMode } from './types.js';
+/**
+ * Determine the single active prompt mode from the options.
+ *
+ * A mode counts as "set" when: `prompt` is a non-empty (trimmed) string,
+ * `points` is a non-empty array, `box` is present, or `automatic === true`.
+ *
+ * @throws {InvalidSegmentationPromptError} when zero or more than one is set.
+ */
+export declare function resolveSegmentationMode(opts: SegmentOptions): SegmentationMode;
+//# sourceMappingURL=resolveMode.d.ts.map

package/dist/io/segmentation/resolveMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveMode.d.ts","sourceRoot":"","sources":["../../../src/io/segmentation/resolveMode.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnE;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAkB9E"}

package/dist/io/segmentation/resolveMode.js

@@ -0,0 +1,28 @@
+import { InvalidSegmentationPromptError } from './errors.js';
+/**
+ * Determine the single active prompt mode from the options.
+ *
+ * A mode counts as "set" when: `prompt` is a non-empty (trimmed) string,
+ * `points` is a non-empty array, `box` is present, or `automatic === true`.
+ *
+ * @throws {InvalidSegmentationPromptError} when zero or more than one is set.
+ */
+export function resolveSegmentationMode(opts) {
+    const modes = [];
+    if (typeof opts.prompt === 'string' && opts.prompt.trim().length > 0)
+        modes.push('text');
+    if (Array.isArray(opts.points) && opts.points.length > 0)
+        modes.push('points');
+    if (opts.box)
+        modes.push('box');
+    if (opts.automatic === true)
+        modes.push('automatic');
+    if (modes.length === 0) {
+        throw new InvalidSegmentationPromptError('segment() requires exactly one prompt mode: set one of prompt, points, box, or automatic.');
+    }
+    if (modes.length > 1) {
+        throw new InvalidSegmentationPromptError(`segment() accepts exactly one prompt mode, received: ${modes.join(', ')}.`);
+    }
+    return modes[0];
+}
+//# sourceMappingURL=resolveMode.js.map

package/dist/io/segmentation/resolveMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveMode.js","sourceRoot":"","sources":["../../../src/io/segmentation/resolveMode.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAoB;IAC1D,MAAM,KAAK,GAAuB,EAAE,CAAC;IACrC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzF,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/E,IAAI,IAAI,CAAC,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAErD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,8BAA8B,CACtC,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,8BAA8B,CACtC,wDAAwD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}