@bedolla/enrivision 0.1.4 → 0.1.6

package/dist/tools/AnalyzeMediaParamParser.d.ts

@@ -0,0 +1,299 @@
+/**
+ * ANALYZE MEDIA PARAMETER PARSER
+ *
+ * Validates raw MCP tool arguments for `analyze_media`, including multipass
+ * knob ranges, so out-of-range values fail locally in Spanish instead of
+ * being silently clamped by EnriProxy.
+ *
+ * Enforced knob contract (documented in the MCP tool schema, mirrors EnriProxy `VisionAnalysisHandler`):
+ * - max_frames (or maxFrames): integer 1-20 (default 20)
+ * - analysis_mode (or analysisMode): auto|single|multipass
+ * - video.segment_seconds (or segmentSeconds, flat or nested): 5-600 seconds (default 60)
+ * - video.max_segments (or maxSegments, flat or nested): integer 1-60
+ * - video.max_frames_per_segment (or maxFramesPerSegment, flat or nested): integer 1-20 (default 8)
+ * - video.clip_start_seconds (or clipStartSeconds): 0-86400
+ * - video.clip_end_seconds (or clipEndSeconds): 0-86400, > start; duration derives as end - start
+ * - video.clip_duration_seconds (or clipDurationSeconds): (0, 86400]
+ * - audio.segment_seconds (or segmentSeconds, flat or nested): 5-600 seconds (default 60)
+ * - audio.max_segments (or maxSegments, flat or nested): integer 1-60
+ * - audio.timestamps (or audioTimestamps flat): strict boolean
+ * - document.max_pages_total (or documentMaxPages flat): integer 1-200 (default 20)
+ * - document.pages_per_batch: integer 1-200
+ * - document.max_images_per_batch: integer 0-20 (0 = no render)
+ * - document.scanned_text_threshold_chars: integer 0-5000
+ * - images.max_images_total: integer 1-500
+ * - images.images_per_batch: integer 1-20
+ * - images.max_dimension: integer 256-4096
+ * - paths[]: at most 100 entries
+ *
+ * @module tools/AnalyzeMediaParamParser
+ */
+import type { AnalyzeMediaToolParams } from "./AnalyzeMediaContract.js";
+/**
+ * Validates raw `analyze_media` tool arguments.
+ */
+export declare class AnalyzeMediaParamParser {
+    /**
+     * Honesty notes collected while parsing (reset on every `parseParams` call).
+     */
+    private parseWarnings;
+    /**
+     * Validates raw MCP tool arguments.
+     *
+     * @remarks
+     * Accepts `snake_case` and `camelCase` spellings (`max_frames` or
+     * `maxFrames`) plus EnriCode-style flat knobs (`segmentSeconds`,
+     * `maxSegments`, `maxFramesPerSegment`, `audioTimestamps`,
+     * `documentMaxPages`, `clipStartSeconds`, `clipEndSeconds`,
+     * `clipDurationSeconds`). Flat knobs win over their nested
+     * `video`/`audio`/`document` counterparts, mirroring EnriCode.
+     *
+     * @param raw - Raw tool arguments.
+     * @returns Validated parameters.
+     * @throws Error with an Spanish-first bilingual message when arguments are missing or out of range.
+     */
+    parseParams(raw: unknown): AnalyzeMediaToolParams;
+    /**
+     * Rejects differing nested video/audio segment knobs without a flat winner.
+     *
+     * @remarks
+     * Flat-over-nested precedence mirrors EnriCode: a flat `segmentSeconds` or
+     * `maxSegments` wins over both nested sections (fan-out to both is
+     * intentional; the server applies the media-matching one). Without a flat,
+     * differing nested `video` vs `audio` values for the same knob fail in
+     * Spanish and point at the flat winner, mirroring
+     * `VisionAnalyzeMediaToolInputParser` video-beats-audio conflict guards.
+     *
+     * @param flat - Top-level arguments carrying flat knob aliases.
+     * @throws Error with an Spanish-first bilingual message when nested video/audio values differ without a flat.
+     */
+    private rejectConflictingNestedSegmentKnobs;
+    /**
+     * Parses the `analysis_mode` selector accepting both spellings.
+     *
+     * @param raw - Raw selector value.
+     * @returns Validated selector or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when the value is not auto|single|multipass.
+     */
+    private parseAnalysisMode;
+    /**
+     * Parses the single `path` argument.
+     *
+     * @param raw - Raw `path` argument.
+     * @returns Trimmed path, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when the path is neither absolute nor http(s).
+     */
+    private parsePath;
+    /**
+     * Parses the continuation cursor for truncated-list reads.
+     *
+     * @param raw - Raw `cursor` argument.
+     * @returns Validated cursor, or undefined when absent.
+     * @throws Error with a Spanish-first bilingual message when present but malformed.
+     */
+    private parseCursor;
+    /**
+     * Parses the continuation start index.
+     *
+     * @param raw - Raw `offset` argument.
+     * @returns Validated offset, or undefined when absent.
+     * @throws Error with a Spanish-first bilingual message when present but not an integer >= 0.
+     */
+    private parseOffset;
+    /**
+     * Parses the multi-image `paths` argument.
+     *
+     * @remarks
+     * Blank entries are discarded (documented in the tool schema); when at
+     * least one valid entry remains, `paths` wins over `path` at execution.
+     *
+     * @param raw - Raw `paths` argument.
+     * @returns Validated paths, or undefined when absent/empty.
+     * @throws Error with an Spanish-first bilingual message when `paths` is not an array of absolute paths or http(s) URLs.
+     */
+    private parsePaths;
+    /**
+     * Parses the optional `video` tuning object with range validation.
+     *
+     * @remarks
+     * Accepts `snake_case` and `camelCase` spellings inside `video`, plus
+     * flat knobs (`clipStartSeconds`, `clipEndSeconds`, `clipDurationSeconds`,
+     * `segmentSeconds`, `maxSegments`, `maxFramesPerSegment`) with
+     * flat-over-nested precedence. When `clip_end_seconds` is present the
+     * duration derives as `fin = inicio + duración` (`duration = end - start`)
+     * and `end <= start` fails (a zero window would be dropped downstream,
+     * silently widening the analysis); otherwise an explicit `clip_duration_seconds`
+     * is used. Every clip bound lives in `0-86400` segundos (24 h). When any
+     * clip knob is present but `clip_start_seconds` is absent, the start is
+     * synthesized as `0` so the server never defaults the offset (mirrors
+     * EnriCode `VisionAnalyzeMediaRequestRecords`), and
+     * `start + duration > 86400` clamps the duration to the 24 h range with
+     * a Spanish warning in `warnings` (mirrors the proxy timeline trim);
+     * only a start already at the limit fails. A lone `clip_start_seconds`
+     * at the 86400 cap with no duration forwards untouched (server decides),
+     * mirroring EnriCode `VisionAnalyzeMediaClipWindowReader`, which likewise
+     * returns a start-only window with no warning in that case.
+     *
+     * @param raw - Raw `video` argument.
+     * @param flat - Top-level arguments carrying flat knob aliases.
+     * @param applySharedFlats - Whether shared `segmentSeconds`/`maxSegments` flats feed this section.
+     * @returns Validated video tuning, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when any knob is present but invalid or out of range.
+     */
+    private parseVideo;
+    /**
+     * Parses the optional `document` tuning object with range validation.
+     *
+     * @remarks
+     * Accepts `snake_case` and `camelCase` spellings, plus the flat
+     * `documentMaxPages` knob with flat-over-nested precedence.
+     *
+     * @param raw - Raw `document` argument.
+     * @param flat - Top-level arguments carrying flat knob aliases.
+     * @returns Validated document tuning, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when any knob is present but invalid or out of range.
+     */
+    private parseDocument;
+    /**
+     * Parses the optional `audio` tuning object with range validation.
+     *
+     * @remarks
+     * Accepts `snake_case` and `camelCase` spellings, plus the flat
+     * `audioTimestamps`, `segmentSeconds`, and `maxSegments` knobs with
+     * flat-over-nested precedence. Boolean knobs are strict: `"yes"` fails
+     * instead of being dropped silently.
+     *
+     * @param raw - Raw `audio` argument.
+     * @param flat - Top-level arguments carrying flat knob aliases.
+     * @param applySharedFlats - Whether shared `segmentSeconds`/`maxSegments` flats feed this section.
+     * @returns Validated audio tuning, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when any knob is present but invalid or out of range.
+     */
+    private parseAudio;
+    /**
+     * Parses the optional `images` tuning object with sanity validation.
+     *
+     * @param raw - Raw `images` argument.
+     * @returns Validated images tuning, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when any knob is present but invalid.
+     */
+    private parseImages;
+    /**
+     * Rejects unknown keys inside one nested tuning object with Spanish coaching.
+     *
+     * @remarks
+     * Typos (`max_pages_totall`, `segement_seconds`) must fail locally instead
+     * of being ignored silently and analyzing the whole file at full cost.
+     *
+     * @param actual - Raw nested tuning object.
+     * @param known - Accepted key spellings for the section.
+     * @param section - Section name for error messages.
+     * @throws Error with an Spanish-first bilingual message when the section carries unknown keys.
+     */
+    private throwOnUnknownKeys;
+    /**
+     * Validates one language hint against the EnriCode pattern.
+     *
+     * @param raw - Raw language value.
+     * @param fieldName - Field name for error messages.
+     * @returns Validated hint, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when the hint has an invalid shape.
+     */
+    private parseLanguageHint;
+    /**
+     * Parses an optional integer knob that must be absent or within a range.
+     *
+     * @param raw - Raw knob value.
+     * @param fieldName - Dotted field name for error messages.
+     * @param min - Inclusive minimum.
+     * @param max - Inclusive maximum.
+     * @returns Validated integer, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not an integer within range.
+     */
+    private parseBoundedInt;
+    /**
+     * Parses an optional numeric knob that must be absent or within a range.
+     *
+     * @param raw - Raw knob value.
+     * @param fieldName - Dotted field name for error messages.
+     * @param min - Inclusive minimum.
+     * @param max - Inclusive maximum.
+     * @returns Validated number, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not a number within range.
+     */
+    private parseBoundedNumber;
+    /**
+     * Parses an optional clip-window bound that must be absent or within 0-86400.
+     *
+     * @param raw - Raw knob value.
+     * @param fieldName - Dotted field name for error messages.
+     * @param min - Inclusive minimum.
+     * @param max - Inclusive maximum.
+     * @returns Validated number, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not a number within range.
+     */
+    private parseClipBound;
+    /**
+     * Parses an optional clip duration that must be absent or within (0, 86400].
+     *
+     * @param raw - Raw knob value.
+     * @returns Validated duration, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not a positive number within range.
+     */
+    private parseClipDuration;
+    /**
+     * Parses the optional requested model id for server-side dispatch affinity.
+     *
+     * @param raw - Raw `model` argument.
+     * @returns Trimmed model id, or undefined when absent/blank.
+     * @throws Error with an Spanish-first bilingual message when the model id is not a short string.
+     */
+    private parseModelHint;
+    /**
+     * Parses and validates the optional relative image region.
+     *
+     * @param raw - Raw `region` argument.
+     * @returns Validated region, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when the region is malformed or out of range.
+     */
+    private parseRegion;
+    /**
+     * Rejects oversized prompt text before any byte is uploaded.
+     *
+     * @remarks
+     * Mirrors EnriProxy `VISION_MAX_QUESTION_CHARS`/`VISION_MAX_CONTEXT_CHARS`
+     * (2000): the server 400s after upload cost, so the gate lives here.
+     *
+     * @param value - Optional prompt text.
+     * @param fieldName - `question` or `context`.
+     * @returns Prompt text, or undefined when absent.
+     * @throws Error in Spanish naming the 2000-character cap.
+     */
+    private static requireBoundedPromptText;
+}
+/**
+ * Accepted top-level argument keys (exported for the schema-parser
+ * agreement test: every key here must exist as an `inputSchema` property).
+ */
+export declare const TOP_LEVEL_KNOWN_KEYS: ReadonlySet<string>;
+/**
+ * Accepted key spellings inside the `video` tuning object (snake_case + camelCase).
+ */
+export declare const VIDEO_KNOWN_KEYS: ReadonlySet<string>;
+/**
+ * Accepted key spellings inside the `document` tuning object (snake_case + camelCase + legacy aliases).
+ */
+export declare const DOCUMENT_KNOWN_KEYS: ReadonlySet<string>;
+/**
+ * Accepted key spellings inside the `audio` tuning object (snake_case + camelCase).
+ */
+export declare const AUDIO_KNOWN_KEYS: ReadonlySet<string>;
+/**
+ * Accepted key spellings inside the `region` zoom object.
+ */
+export declare const REGION_KNOWN_KEYS: ReadonlySet<string>;
+/**
+ * Accepted key spellings inside the `images` tuning object (snake_case + camelCase).
+ */
+export declare const IMAGES_KNOWN_KEYS: ReadonlySet<string>;
+//# sourceMappingURL=AnalyzeMediaParamParser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyzeMediaParamParser.d.ts","sourceRoot":"","sources":["../../src/tools/AnalyzeMediaParamParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAeH,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,2BAA2B,CAAC;AAGnC;;GAEG;AACH,qBAAa,uBAAuB;IAClC;;OAEG;IACH,OAAO,CAAC,aAAa,CAAgB;IAErC;;;;;;;;;;;;;;OAcG;IACI,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB;IA6GxD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mCAAmC;IA6C3C;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAmBjB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IAmClB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,UAAU;IAuGlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAsDrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,UAAU;IAmClB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAyCnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAuCnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;CAWxC;AAgBD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAqCnD,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAa/C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAalD,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAQ/C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAKhD,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAOhD,CAAC"}