@bedolla/enrivision 0.1.0

package/dist/tools/AnalyzeMediaTool.d.ts

@@ -0,0 +1,302 @@
+/**
+ * ANALYZE MEDIA TOOL
+ *
+ * Implements the `analyze_media` MCP tool:
+ * - Validates local file path
+ * - Streams the file to EnriProxy via resumable uploads
+ * - Triggers server-side analysis and returns text-only results
+ *
+ * @module tools/AnalyzeMediaTool
+ */
+import { type EnriProxyClient } from "../client/EnriProxyClient.js";
+/**
+ * Tool parameters for `analyze_media`.
+ */
+export interface AnalyzeMediaToolParams {
+    /**
+     * Absolute local filesystem path on the MCP host.
+     *
+     * @remarks
+     * Use `paths` to analyze multiple images in a single call.
+     */
+    readonly path?: string;
+    /**
+     * Absolute local filesystem paths 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.
+     */
+    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 (1-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.
+         */
+        readonly segmentSeconds?: number;
+        /**
+         * Maximum number of segments to analyze.
+         */
+        readonly maxSegments?: number;
+        /**
+         * Maximum frames per segment.
+         */
+        readonly maxFramesPerSegment?: number;
+    };
+    /**
+     * Optional document multipass tuning (PDF).
+     */
+    readonly document?: {
+        /**
+         * Maximum pages to analyze in total.
+         */
+        readonly maxPagesTotal?: number;
+        /**
+         * Pages per batch.
+         */
+        readonly pagesPerBatch?: number;
+        /**
+         * Maximum rendered pages per batch.
+         */
+        readonly maxImagesPerBatch?: number;
+        /**
+         * Minimum extracted text length to treat a page as textual.
+         */
+        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.
+         */
+        readonly segmentSeconds?: number;
+        /**
+         * Maximum number of audio segments to analyze.
+         */
+        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.
+         */
+        readonly maxImagesTotal?: number;
+        /**
+         * Images per batch for multipass map calls.
+         */
+        readonly imagesPerBatch?: number;
+        /**
+         * Maximum dimension for images (width/height).
+         */
+        readonly maxDimension?: number;
+    };
+}
+/**
+ * Structured result for `analyze_media`.
+ */
+export interface AnalyzeMediaToolResult extends Record<string, unknown> {
+    /**
+     * Text analysis produced by EnriProxy.
+     */
+    readonly analysis: string;
+    /**
+     * Detected media type.
+     */
+    readonly media_type: 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>;
+}
+/**
+ * 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 ms
+     * @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;
+}
+/**
+ * MCP tool that uploads and analyzes local media.
+ */
+export declare class AnalyzeMediaTool {
+    /**
+     * Tool dependencies.
+     */
+    private readonly deps;
+    /**
+     * Creates a new {@link AnalyzeMediaTool}.
+     *
+     * @param deps - Tool dependencies
+     */
+    constructor(deps: AnalyzeMediaToolDeps);
+    /**
+     * Validates raw MCP tool arguments.
+     *
+     * @param raw - Raw tool arguments
+     * @returns Validated parameters
+     */
+    parseParams(raw: unknown): AnalyzeMediaToolParams;
+    /**
+     * Executes the tool.
+     *
+     * @param params - Validated parameters
+     * @returns Tool result
+     */
+    execute(params: AnalyzeMediaToolParams): Promise<AnalyzeMediaToolResult>;
+    /**
+     * Removes internal identifiers (upload ids, routing-only values, etc.) from the
+     * extraction payload before returning it to the model.
+     *
+     * @param extraction - Raw extraction object returned by EnriProxy
+     * @returns Sanitized extraction object
+     */
+    private stripInternalExtractionFields;
+    /**
+     * Recursively strips internal fields from an unknown value.
+     *
+     * @param value - Unknown value to sanitize
+     * @returns Sanitized value
+     */
+    private stripInternalFields;
+    /**
+     * Ensures the sanitized extraction value is a plain JSON object.
+     *
+     * @param value - Sanitized value
+     * @returns Plain object
+     */
+    private asPlainObject;
+    /**
+     * Validates that a path exists and is a readable file.
+     *
+     * @param filePath - Local filesystem path
+     * @returns File size in bytes
+     */
+    private assertReadableFile;
+    /**
+     * Detects MIME type using file extension.
+     *
+     * @param filePath - File path
+     * @returns MIME type string
+     */
+    private detectMimeType;
+    /**
+     * Uploads multiple local images as a single EnriVision media-set tar archive.
+     *
+     * @remarks
+     * This avoids creating many concurrent resumable upload sessions (which are
+     * capped per API key) and enables server-side batching + reduce for large
+     * screenshot sets.
+     *
+     * @param client - EnriProxy client
+     * @param filePaths - Absolute image file paths
+     * @param timeoutMs - Request timeout per HTTP request
+     * @param clientTraceId - Client trace id for correlation
+     * @returns Upload id for the created tar session
+     */
+    private uploadImageSetAsMediaSetTar;
+    /**
+     * Uploads a file to EnriProxy in resumable chunks.
+     *
+     * @param client - EnriProxy client
+     * @param filePath - Local file path
+     * @param fileSize - Total file size in bytes
+     * @param session - Server-created session
+     * @param timeoutMs - Request timeout in milliseconds
+     * @returns Final offset
+     */
+    private uploadFileResumable;
+    /**
+     * Uploads a single chunk with retry and offset resync.
+     *
+     * @param client - EnriProxy client
+     * @param uploadId - Upload id
+     * @param offset - Expected offset
+     * @param chunk - Chunk bytes
+     * @param timeoutMs - Timeout in ms
+     * @returns New offset
+     */
+    private uploadChunkWithRetry;
+}
+//# sourceMappingURL=AnalyzeMediaTool.d.ts.map

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

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