@bedolla/enrivision 0.1.5 → 0.1.7

package/dist/tools/AnalyzeMediaContract.d.ts

@@ -0,0 +1,462 @@
+/**
+ * ANALYZE MEDIA CONTRACT
+ *
+ * Public parameter, result, and dependency contracts for the
+ * `analyze_media` MCP tool. The facade (`AnalyzeMediaTool`) re-exports
+ * these types so external import sites keep working.
+ *
+ * @module tools/AnalyzeMediaContract
+ */
+import type { EnriProxyClient } from "../client/EnriProxyClient.js";
+/**
+ * Shared upload and batching limits for the `analyze_media` MCP tool.
+ *
+ * @remarks
+ * Parity note vs EnriCode `vision.analyze_media` (single-file tool):
+ * - EnriCode-only (no MCP equivalent, by design): `attachmentIndex`,
+ *   `attachmentId`, and the required-`question` rule. EnriVision accepts
+ *   `path`/`paths` only and `question` stays optional.
+ * - EnriVision extras (intentional, not bugs): `paths[]` multi-image sets
+ *   packed as one `application/vnd.enrivision.media-set+tar` archive for
+ *   server-side batching + reduce, `images.*` tuning, and the
+ *   `document.pages_per_batch/max_images_per_batch/scanned_text_threshold_chars`
+ *   multipass knobs beyond EnriCode.
+ * - EnriVision validates strictly with Spanish-first bilingual errors (ES first,
+ *   EN second) and fails (EnriCode coerces
+ *   and clamps silently); flat aliases (camelCase plus snake_case) are
+ *   accepted with flat-over-nested precedence, mirroring EnriCode. Flat
+ *   `segmentSeconds`/`maxSegments` win over nested `video`/`audio` values;
+ *   differing nested `video` vs `audio` values without a flat fail locally.
+ *   Nested `document.documentMaxPages` and `audio.audioTimestamps` (plus
+ *   `audio_timestamps`) are accepted like EnriCode; exponents (`"1e3"`)
+ *   are rejected on all three surfaces.
+ */
+export declare const ANALYZE_MEDIA_LIMITS: {
+    /**
+     * Maximum accepted upload size in bytes (4 GiB, mirrors EnriProxy).
+     */
+    readonly maxUploadBytes: number;
+    /**
+     * Maximum chunk size in bytes per upload request (server value capped).
+     *
+     * @remarks
+     * 16 MiB mirrors EnriProxy (`UploadSessionService` default) and EnriCode
+     * `MAX_CHUNK_SIZE_BYTES`: 4 GiB needs ~256 PATCH instead of ~512.
+     */
+    readonly maxChunkBytes: number;
+    /**
+     * Maximum entries accepted in `paths[]` before materializing downloads.
+     */
+    readonly maxPathsCount: 100;
+    /**
+     * Maximum prompt characters accepted for `question`/`context` (mirrors
+     * EnriProxy `VISION_MAX_QUESTION_CHARS`/`VISION_MAX_CONTEXT_CHARS`):
+     * oversized prompts fail fast here, before any byte is uploaded.
+     */
+    readonly maxPromptChars: 2000;
+    /**
+     * Maximum clip-window bound in seconds (0-86400, 24 h).
+     */
+    readonly maxClipSeconds: 86400;
+    /**
+     * Maximum characters of server analysis text forwarded to the model.
+     */
+    readonly maxAnalysisTextChars: 30000;
+    /**
+     * Maximum characters of analysis text kept inside `structuredContent`.
+     *
+     * @remarks
+     * MCP delivers the whole result in one JSON frame, so the full payload is
+     * truncated here too (with `analysis_truncated` + `analysis_total_chars`):
+     * small clients pay parse/memory cost regardless of text truncation.
+     * Budgeted in code points (not UTF-8 bytes) on purpose: MCP hosts parse
+     * JSON into UTF-16 strings, and seam-safe slicing must never split
+     * surrogate pairs. This diverges knowingly from EnriCode's 256 KiB byte
+     * envelope: astral-heavy analyses ship more wire bytes here, but never
+     * more characters, and `analysis_total_chars` keeps the cut honest.
+     */
+    readonly maxStructuredContentAnalysisChars: 262144;
+    /**
+     * Code points of the structured analysis budget kept at the start.
+     *
+     * @remarks
+     * The remainder (`maxStructuredContentAnalysisChars` minus this head)
+     * is kept at the end: conclusions live at the tail of long analyses,
+     * so head-only truncation would drop exactly what small models need.
+     */
+    readonly maxStructuredContentAnalysisHeadChars: 200000;
+    /**
+     * Maximum serialized characters of `extraction` kept inside
+     * `structuredContent` (512 KiB).
+     *
+     * @remarks
+     * Multipass timelines can grow without bound; past this cap long strings
+     * are head+tail cut (shape preserved) instead of shipping megabytes of
+     * metadata to small MCP clients. Code points, like the analysis budget
+     * above; the 32768 per-string cap stays wider than EnriCode's 16 KiB
+     * field cap because MCP has no separate byte envelope to absorb the
+     * remainder (the shape-preserving cut is the only bound).
+     */
+    readonly maxStructuredContentExtractionChars: 524288;
+    /**
+     * Maximum characters kept per string when bounding `extraction`.
+     */
+    readonly maxBoundExtractionStringChars: 32768;
+    /**
+     * Unary analyze timeout for `analysis_mode: "single"` (10 min, mirrors
+     * EnriCode `ANALYZE_TIMEOUT_MS` and the EnriProxy single-pass stage budget).
+     *
+     * @remarks
+     * The operator `ENRIVISION_TIMEOUT_MS` still caps it via `Math.min`.
+     */
+    readonly singleAnalyzeTimeoutMs: number;
+    /**
+     * Unary analyze timeout for `analysis_mode: "multipass"` and `"auto"`
+     * (20 min, mirrors EnriCode `MULTIPASS_ANALYZE_TIMEOUT_MS` and the server
+     * multipass wall-clock budget).
+     *
+     * @remarks
+     * `auto` shares the multipass budget because the server may escalate to
+     * multipass (long videos, scanned PDFs over the page threshold) and the
+     * client cannot know upfront. The operator `ENRIVISION_TIMEOUT_MS` still
+     * caps it via `Math.min`.
+     */
+    readonly multipassAnalyzeTimeoutMs: number;
+    /**
+     * Budget for the fail-open vision-capability probe (`GET
+     * `/v1/account/models`, 15 s, mirrors EnriCode).
+     */
+    readonly visionProbeTimeoutMs: 15000;
+    /**
+     * Time-to-live for cached vision-capability verdicts (5 min, mirrors EnriCode
+     * `PROBE_CACHE_TTL_MS`).
+     */
+    readonly visionProbeCacheTtlMs: number;
+};
+/**
+ * Machine-readable error codes surfaced in `structuredContent` on MCP tool errors.
+ *
+ * @remarks
+ * Reuses the EnriCode `VisionAnalyzeMediaErrorMapper` vocabulary so OpenAI-compatible
+ * third-party clients can branch programmatically (retryable 429/5xx and timeouts vs
+ * terminal input/auth errors vs aborts) instead of parsing human text.
+ */
+export declare const ANALYZE_MEDIA_ERROR_CODES: {
+    /**
+     * Caller-side argument or tuning error (400/422 from the proxy included): never retry unchanged.
+     */
+    readonly inputInvalid: "ENRICODE_ERR_TOOL_INPUT_INVALID";
+    /**
+     * Server-side or transport execution failure: retry only when `retryable` is true.
+     */
+    readonly executionFailed: "ENRICODE_ERR_TOOL_EXECUTION_FAILED";
+    /**
+     * Analysis or upload deadline exceeded: retry with a smaller scope once.
+     */
+    readonly executionTimeout: "ENRICODE_ERR_TOOL_EXECUTION_TIMEOUT";
+    /**
+     * Caller-cancelled request: do not retry automatically.
+     */
+    readonly executionAborted: "ENRICODE_ERR_TOOL_EXECUTION_ABORTED";
+};
+/**
+ * One machine-readable MCP error code (see {@link ANALYZE_MEDIA_ERROR_CODES}).
+ */
+export type AnalyzeMediaErrorCode = (typeof ANALYZE_MEDIA_ERROR_CODES)[keyof typeof ANALYZE_MEDIA_ERROR_CODES];
+/**
+ * Relative image region for native-resolution zoom (images only).
+ */
+export interface ImageRegion {
+    /**
+     * Relative horizontal coordinate of the top-left corner (0 = left edge).
+     */
+    readonly x: number;
+    /**
+     * Relative vertical coordinate of the top-left corner (0 = top edge).
+     */
+    readonly y: number;
+    /**
+     * Relative width (1 = full width).
+     */
+    readonly width: number;
+    /**
+     * Relative height (1 = full height).
+     */
+    readonly height: number;
+}
+/**
+ * Tool parameters for `analyze_media`.
+ */
+export interface AnalyzeMediaToolParams {
+    /**
+     * Absolute local filesystem path on the MCP host, or one http(s) URL to
+     * download (bounded, temporary) and analyze.
+     *
+     * @remarks
+     * Use `paths` to analyze multiple images in a single call. When `paths`
+     * carries at least one valid entry, `path` is ignored.
+     */
+    readonly path?: string;
+    /**
+     * Absolute local filesystem paths or http(s) URLs on the MCP host.
+     *
+     * @remarks
+     * When provided, EnriVision uploads the files as a single media-set archive
+     * (resumable, up to 4GB) and triggers server-side batching + reduce.
+     *
+     * This is intended for many UI screenshots / photo sets. Blank entries are
+     * discarded; when at least one valid entry remains, `path` is ignored.
+     */
+    readonly paths?: ReadonlyArray<string>;
+    /**
+     * Optional analysis hint (ui, diagram, chart, error, code, meeting, tutorial, photo).
+     */
+    readonly context?: string;
+    /**
+     * Optional explicit user question.
+     */
+    readonly question?: string;
+    /**
+     * Preferred response language code (e.g., "es", "en").
+     */
+    readonly language?: string;
+    /**
+     * Optional max frames override for videos (integer 1-20, default 20).
+     */
+    readonly maxFrames?: number;
+    /**
+     * Optional override for transcription on videos.
+     */
+    readonly transcribe?: boolean;
+    /**
+     * Optional transcription language hint for Whisper.
+     */
+    readonly transcriptionLanguage?: string;
+    /**
+     * Optional analysis mode selector (auto|single|multipass).
+     */
+    readonly analysisMode?: "auto" | "single" | "multipass";
+    /**
+     * Optional video multipass tuning.
+     */
+    readonly video?: {
+        /**
+         * Optional clip start offset in seconds for targeted video analysis.
+         *
+         * @remarks
+         * Use this when the question references a specific timestamp to avoid
+         * scanning the full timeline.
+         */
+        readonly clipStartSeconds?: number;
+        /**
+         * Optional clip duration in seconds for targeted video analysis.
+         *
+         * @remarks
+         * Use together with {@link clipStartSeconds} to analyze only a time window.
+         */
+        readonly clipDurationSeconds?: number;
+        /**
+         * Segment duration in seconds (5-600, default 60).
+         */
+        readonly segmentSeconds?: number;
+        /**
+         * Maximum number of segments to analyze (integer 1-60, mirrors EnriProxy).
+         */
+        readonly maxSegments?: number;
+        /**
+         * Maximum frames per segment (integer 1-20, default 8).
+         */
+        readonly maxFramesPerSegment?: number;
+    };
+    /**
+     * Optional document multipass tuning (PDF).
+     */
+    readonly document?: {
+        /**
+         * Maximum pages to analyze in total (integer 1-200, default 20, mirrors EnriProxy).
+         */
+        readonly maxPagesTotal?: number;
+        /**
+         * Pages per batch (integer 1-200, mirrors EnriProxy).
+         */
+        readonly pagesPerBatch?: number;
+        /**
+         * Maximum rendered pages per batch (integer 0-20, 0 = no render, mirrors EnriProxy).
+         */
+        readonly maxImagesPerBatch?: number;
+        /**
+         * Minimum extracted text length to treat a page as textual (integer 0-5000, mirrors EnriProxy).
+         */
+        readonly scannedTextThresholdChars?: number;
+    };
+    /**
+     * Optional audio multipass tuning.
+     */
+    readonly audio?: {
+        /**
+         * Whether to include timestamped segments in audio extraction.
+         */
+        readonly timestamps?: boolean;
+        /**
+         * Segment duration in seconds for audio multipass (5-600, default 60).
+         */
+        readonly segmentSeconds?: number;
+        /**
+         * Maximum number of audio segments to analyze (integer 1-60, mirrors EnriProxy).
+         */
+        readonly maxSegments?: number;
+    };
+    /**
+     * Optional image-set multipass tuning.
+     *
+     * @remarks
+     * Used only when analyzing multiple images via `paths`.
+     */
+    readonly images?: {
+        /**
+         * Maximum number of images to analyze in total (integer 1-500, mirrors EnriProxy).
+         */
+        readonly maxImagesTotal?: number;
+        /**
+         * Images per batch for multipass map calls (integer 1-20, mirrors EnriProxy).
+         */
+        readonly imagesPerBatch?: number;
+        /**
+         * Maximum dimension for images (width/height, integer 256-4096, mirrors EnriProxy).
+         */
+        readonly maxDimension?: number;
+    };
+    /**
+     * Optional requested model id for server-side dispatch affinity.
+     *
+     * @remarks
+     * Mirrors EnriCode `requestedModelId`: EnriProxy preserves the active
+     * model before fallbacks (including the Muse Spark image-count reroute).
+     * Omitted (or `ENRIVISION_MODEL`) means auto-dispatch. Unknown keys
+     * inside tuning objects are rejected, never ignored.
+     */
+    readonly model?: string;
+    /**
+     * Optional relative region of the analyzed image for native-resolution zoom.
+     *
+     * @remarks
+     * Normalized [0,1] coordinates over the original image (0,0 = top-left
+     * corner). Use the boxes returned in `elements` of a previous analysis of
+     * the same image; never invent coordinates.
+     */
+    readonly region?: ImageRegion;
+    /**
+     * Opaque continuation cursor from a truncated response
+     * (`segment_summaries_cursor` or `transcription_segments_cursor`).
+     *
+     * @remarks
+     * Continuation mode: no file is uploaded or analyzed; the call only
+     * reads the next window of a previously truncated list. `path`/`paths`
+     * are ignored while `cursor` is present.
+     */
+    readonly cursor?: string;
+    /**
+     * Start index for a continuation read (defaults to the response
+     * `next_offset`).
+     */
+    readonly offset?: number;
+    /**
+     * Maximum entries to read in one continuation window (1-100; defaults to
+     * the server window size).
+     */
+    readonly continuationLimit?: number;
+    /**
+     * Parser-generated honesty notes (Spanish-first bilingual, e.g., a clamped clip window).
+     *
+     * @remarks
+     * Present only when parsing adjusted a requested value: `execute` copies
+     * these into the result so the model always sees what changed instead of
+     * analyzing a silently different window.
+     */
+    readonly warnings?: ReadonlyArray<string>;
+}
+/**
+ * One grounded element box returned by an image analysis.
+ */
+export interface AnalyzeMediaElementBox {
+    /**
+     * Short label naming the grounded element.
+     */
+    readonly label: string;
+    /**
+     * Original-relative [0,1] box that can be echoed back as `region`.
+     */
+    readonly box: ImageRegion;
+}
+/**
+ * Structured result for `analyze_media`.
+ */
+export interface AnalyzeMediaToolResult extends Record<string, unknown> {
+    /**
+     * Text analysis produced by EnriProxy.
+     */
+    readonly analysis: string;
+    /**
+     * Grounded element boxes for image analyses (original-relative [0,1]).
+     */
+    readonly elements?: ReadonlyArray<AnalyzeMediaElementBox>;
+    /**
+     * Detected media type.
+     */
+    readonly media_type: string;
+    /**
+     * Parser-generated honesty notes (Spanish-first bilingual, e.g., a clamped clip window).
+     *
+     * @remarks
+     * Copied from the validated params by `execute`: adjustments made before
+     * any upload stay visible to the model in both the text output and the
+     * structured content.
+     */
+    readonly warnings?: ReadonlyArray<string>;
+    /**
+     * Extraction metadata returned by the server.
+     *
+     * @remarks
+     * This metadata is intended for debugging and transparency (e.g., duration,
+     * selected frames, warnings). Internal identifiers like upload ids are
+     * stripped to avoid leaking implementation details into the model context.
+     */
+    readonly extraction: Record<string, unknown>;
+}
+/**
+ * Execution options for {@link AnalyzeMediaTool.execute}.
+ */
+export interface AnalyzeMediaExecutionOptions {
+    /**
+     * Cancellation signal (e.g., the MCP request `extra.signal`); aborts URL
+     * downloads, uploads, and the analysis request with a Spanish error.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Dependencies for {@link AnalyzeMediaTool}.
+ */
+export interface AnalyzeMediaToolDeps {
+    /**
+     * Creates an EnriProxy client with a base URL, API key, and timeout.
+     *
+     * @param serverUrl - EnriProxy URL.
+     * @param apiKey - EnriProxy API key.
+     * @param timeoutMs - Timeout in milliseconds.
+     * @returns Client instance.
+     */
+    readonly createClient: (serverUrl: string, apiKey: string, timeoutMs: number) => EnriProxyClient;
+    /**
+     * Default EnriProxy server URL.
+     */
+    readonly defaultServerUrl: string;
+    /**
+     * Default EnriProxy API key.
+     */
+    readonly defaultApiKey: string;
+    /**
+     * Default timeout in milliseconds.
+     */
+    readonly defaultTimeoutMs: number;
+}
+//# sourceMappingURL=AnalyzeMediaContract.d.ts.map

package/dist/tools/AnalyzeMediaContract.d.ts.map

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

package/dist/tools/AnalyzeMediaContract.js

@@ -0,0 +1,161 @@
+/**
+ * ANALYZE MEDIA CONTRACT
+ *
+ * Public parameter, result, and dependency contracts for the
+ * `analyze_media` MCP tool. The facade (`AnalyzeMediaTool`) re-exports
+ * these types so external import sites keep working.
+ *
+ * @module tools/AnalyzeMediaContract
+ */
+/**
+ * Shared upload and batching limits for the `analyze_media` MCP tool.
+ *
+ * @remarks
+ * Parity note vs EnriCode `vision.analyze_media` (single-file tool):
+ * - EnriCode-only (no MCP equivalent, by design): `attachmentIndex`,
+ *   `attachmentId`, and the required-`question` rule. EnriVision accepts
+ *   `path`/`paths` only and `question` stays optional.
+ * - EnriVision extras (intentional, not bugs): `paths[]` multi-image sets
+ *   packed as one `application/vnd.enrivision.media-set+tar` archive for
+ *   server-side batching + reduce, `images.*` tuning, and the
+ *   `document.pages_per_batch/max_images_per_batch/scanned_text_threshold_chars`
+ *   multipass knobs beyond EnriCode.
+ * - EnriVision validates strictly with Spanish-first bilingual errors (ES first,
+ *   EN second) and fails (EnriCode coerces
+ *   and clamps silently); flat aliases (camelCase plus snake_case) are
+ *   accepted with flat-over-nested precedence, mirroring EnriCode. Flat
+ *   `segmentSeconds`/`maxSegments` win over nested `video`/`audio` values;
+ *   differing nested `video` vs `audio` values without a flat fail locally.
+ *   Nested `document.documentMaxPages` and `audio.audioTimestamps` (plus
+ *   `audio_timestamps`) are accepted like EnriCode; exponents (`"1e3"`)
+ *   are rejected on all three surfaces.
+ */
+export const ANALYZE_MEDIA_LIMITS = {
+    /**
+     * Maximum accepted upload size in bytes (4 GiB, mirrors EnriProxy).
+     */
+    maxUploadBytes: 4 * 1024 * 1024 * 1024,
+    /**
+     * Maximum chunk size in bytes per upload request (server value capped).
+     *
+     * @remarks
+     * 16 MiB mirrors EnriProxy (`UploadSessionService` default) and EnriCode
+     * `MAX_CHUNK_SIZE_BYTES`: 4 GiB needs ~256 PATCH instead of ~512.
+     */
+    maxChunkBytes: 16 * 1024 * 1024,
+    /**
+     * Maximum entries accepted in `paths[]` before materializing downloads.
+     */
+    maxPathsCount: 100,
+    /**
+     * Maximum prompt characters accepted for `question`/`context` (mirrors
+     * EnriProxy `VISION_MAX_QUESTION_CHARS`/`VISION_MAX_CONTEXT_CHARS`):
+     * oversized prompts fail fast here, before any byte is uploaded.
+     */
+    maxPromptChars: 2000,
+    /**
+     * Maximum clip-window bound in seconds (0-86400, 24 h).
+     */
+    maxClipSeconds: 86400,
+    /**
+     * Maximum characters of server analysis text forwarded to the model.
+     */
+    maxAnalysisTextChars: 30000,
+    /**
+     * Maximum characters of analysis text kept inside `structuredContent`.
+     *
+     * @remarks
+     * MCP delivers the whole result in one JSON frame, so the full payload is
+     * truncated here too (with `analysis_truncated` + `analysis_total_chars`):
+     * small clients pay parse/memory cost regardless of text truncation.
+     * Budgeted in code points (not UTF-8 bytes) on purpose: MCP hosts parse
+     * JSON into UTF-16 strings, and seam-safe slicing must never split
+     * surrogate pairs. This diverges knowingly from EnriCode's 256 KiB byte
+     * envelope: astral-heavy analyses ship more wire bytes here, but never
+     * more characters, and `analysis_total_chars` keeps the cut honest.
+     */
+    maxStructuredContentAnalysisChars: 262144,
+    /**
+     * Code points of the structured analysis budget kept at the start.
+     *
+     * @remarks
+     * The remainder (`maxStructuredContentAnalysisChars` minus this head)
+     * is kept at the end: conclusions live at the tail of long analyses,
+     * so head-only truncation would drop exactly what small models need.
+     */
+    maxStructuredContentAnalysisHeadChars: 200000,
+    /**
+     * Maximum serialized characters of `extraction` kept inside
+     * `structuredContent` (512 KiB).
+     *
+     * @remarks
+     * Multipass timelines can grow without bound; past this cap long strings
+     * are head+tail cut (shape preserved) instead of shipping megabytes of
+     * metadata to small MCP clients. Code points, like the analysis budget
+     * above; the 32768 per-string cap stays wider than EnriCode's 16 KiB
+     * field cap because MCP has no separate byte envelope to absorb the
+     * remainder (the shape-preserving cut is the only bound).
+     */
+    maxStructuredContentExtractionChars: 524288,
+    /**
+     * Maximum characters kept per string when bounding `extraction`.
+     */
+    maxBoundExtractionStringChars: 32768,
+    /**
+     * Unary analyze timeout for `analysis_mode: "single"` (10 min, mirrors
+     * EnriCode `ANALYZE_TIMEOUT_MS` and the EnriProxy single-pass stage budget).
+     *
+     * @remarks
+     * The operator `ENRIVISION_TIMEOUT_MS` still caps it via `Math.min`.
+     */
+    singleAnalyzeTimeoutMs: 10 * 60 * 1000,
+    /**
+     * Unary analyze timeout for `analysis_mode: "multipass"` and `"auto"`
+     * (20 min, mirrors EnriCode `MULTIPASS_ANALYZE_TIMEOUT_MS` and the server
+     * multipass wall-clock budget).
+     *
+     * @remarks
+     * `auto` shares the multipass budget because the server may escalate to
+     * multipass (long videos, scanned PDFs over the page threshold) and the
+     * client cannot know upfront. The operator `ENRIVISION_TIMEOUT_MS` still
+     * caps it via `Math.min`.
+     */
+    multipassAnalyzeTimeoutMs: 20 * 60 * 1000,
+    /**
+     * Budget for the fail-open vision-capability probe (`GET
+     * `/v1/account/models`, 15 s, mirrors EnriCode).
+     */
+    visionProbeTimeoutMs: 15_000,
+    /**
+     * Time-to-live for cached vision-capability verdicts (5 min, mirrors EnriCode
+     * `PROBE_CACHE_TTL_MS`).
+     */
+    visionProbeCacheTtlMs: 5 * 60 * 1000,
+};
+/**
+ * Machine-readable error codes surfaced in `structuredContent` on MCP tool errors.
+ *
+ * @remarks
+ * Reuses the EnriCode `VisionAnalyzeMediaErrorMapper` vocabulary so OpenAI-compatible
+ * third-party clients can branch programmatically (retryable 429/5xx and timeouts vs
+ * terminal input/auth errors vs aborts) instead of parsing human text.
+ */
+export const ANALYZE_MEDIA_ERROR_CODES = {
+    /**
+     * Caller-side argument or tuning error (400/422 from the proxy included): never retry unchanged.
+     */
+    inputInvalid: "ENRICODE_ERR_TOOL_INPUT_INVALID",
+    /**
+     * Server-side or transport execution failure: retry only when `retryable` is true.
+     */
+    executionFailed: "ENRICODE_ERR_TOOL_EXECUTION_FAILED",
+    /**
+     * Analysis or upload deadline exceeded: retry with a smaller scope once.
+     */
+    executionTimeout: "ENRICODE_ERR_TOOL_EXECUTION_TIMEOUT",
+    /**
+     * Caller-cancelled request: do not retry automatically.
+     */
+    executionAborted: "ENRICODE_ERR_TOOL_EXECUTION_ABORTED",
+};
+//# sourceMappingURL=AnalyzeMediaContract.js.map

package/dist/tools/AnalyzeMediaContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyzeMediaContract.js","sourceRoot":"","sources":["../../src/tools/AnalyzeMediaContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC;;OAEG;IACH,cAAc,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI;IACtC;;;;;;OAMG;IACH,aAAa,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IAC/B;;OAEG;IACH,aAAa,EAAE,GAAG;IAClB;;;;OAIG;IACH,cAAc,EAAE,IAAI;IACpB;;OAEG;IACH,cAAc,EAAE,KAAK;IACrB;;OAEG;IACH,oBAAoB,EAAE,KAAK;IAC3B;;;;;;;;;;;;OAYG;IACH,iCAAiC,EAAE,MAAM;IACzC;;;;;;;OAOG;IACH,qCAAqC,EAAE,MAAM;IAC7C;;;;;;;;;;;OAWG;IACH,mCAAmC,EAAE,MAAM;IAC3C;;OAEG;IACH,6BAA6B,EAAE,KAAK;IACpC;;;;;;OAMG;IACH,sBAAsB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IACtC;;;;;;;;;;OAUG;IACH,yBAAyB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IACzC;;;OAGG;IACH,oBAAoB,EAAE,MAAM;IAC5B;;;OAGG;IACH,qBAAqB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;CAC5B,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC;;OAEG;IACH,YAAY,EAAE,iCAAiC;IAC/C;;OAEG;IACH,eAAe,EAAE,oCAAoC;IACrD;;OAEG;IACH,gBAAgB,EAAE,qCAAqC;IACvD;;OAEG;IACH,gBAAgB,EAAE,qCAAqC;CAC/C,CAAC"}

package/dist/tools/AnalyzeMediaExtractionSanitizer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ANALYZE MEDIA EXTRACTION SANITIZER
+ *
+ * Strips routing-only internals from the EnriProxy extraction payload before
+ * it reaches the model. Only upload identifiers, provider-routing identities,
+ * and secret-bearing keys are removed: coverage metadata that EnriProxy
+ * intentionally returns (`detected_media_type`, `analysis_mode_*`,
+ * `multipass`, `models`, `strategy`, `warnings`, `frame_count`, `timeline`)
+ * is preserved so the model can report honest coverage (missing frames).
+ *
+ * Key matching is separator-insensitive (`-`, `_`, `.` stripped): hyphenated
+ * spellings such as `api-key` or `access-token` match like `api_key`.
+ *
+ * @module tools/AnalyzeMediaExtractionSanitizer
+ */
+/**
+ * Sanitizes EnriProxy extraction payloads for model consumption.
+ */
+export declare class AnalyzeMediaExtractionSanitizer {
+    /**
+     * Removes internal identifiers from the extraction payload.
+     *
+     * @param extraction - Raw extraction object returned by EnriProxy.
+     * @returns Sanitized plain extraction object.
+     */
+    sanitize(extraction: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Recursively strips internal fields from an unknown value.
+     *
+     * @param value - Unknown value to sanitize.
+     * @returns Sanitized value.
+     */
+    private stripInternalFields;
+}
+//# sourceMappingURL=AnalyzeMediaExtractionSanitizer.d.ts.map

package/dist/tools/AnalyzeMediaExtractionSanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyzeMediaExtractionSanitizer.d.ts","sourceRoot":"","sources":["../../src/tools/AnalyzeMediaExtractionSanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoIH;;GAEG;AACH,qBAAa,+BAA+B;IAC1C;;;;;OAKG;IACI,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ7E;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CA0D5B"}