video-context-mcp-server 1.1.5 → 1.2.0

package/dist/services/redactionDetector.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Redaction Detector
+ * AI-assisted sensitive region detection in video frames.
+ * Samples frames, sends to a vision provider, and parses JSON detections.
+ */
+import { z } from 'zod';
+import type { RedactionRegion } from '../types/redaction.js';
+/** Full detection response from the AI provider. */
+export declare const detectionResponseSchema: z.ZodObject<{
+    frames: z.ZodArray<z.ZodObject<{
+        frameIndex: z.ZodNumber;
+        timestampSec: z.ZodNumber;
+        detections: z.ZodArray<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
+            label: z.ZodString;
+            confidence: z.ZodNumber;
+            box: z.ZodOptional<z.ZodObject<{
+                left: z.ZodNumber;
+                top: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DetectionResponse = z.infer<typeof detectionResponseSchema>;
+export interface FrameDetection {
+    label: string;
+    confidence: number;
+    box: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    reason?: string;
+}
+/**
+ * Supported detection categories inferred from a user's natural-language intent.
+ * Using an allowlist prevents prompt-injection: raw user text is NEVER
+ * interpolated into the AI prompt.
+ */
+export type DetectionCategory = 'credentials' | 'pii' | 'infrastructure' | 'financial' | 'general';
+/**
+ * Classify a free-text intent string into one of the allowed detection
+ * categories.  Returns 'general' when no specific category is recognised.
+ * Raw user text is never forwarded to the AI prompt.
+ */
+export declare function classifyIntent(intent: string): DetectionCategory;
+/** Return the sampling/confidence defaults for a given intent category. */
+export declare function getDetectionDefaults(category: DetectionCategory): {
+    sampleIntervalSeconds: number;
+    maxFrames: number;
+    minConfidence: number;
+};
+export interface SamplingOptions {
+    /** Interval between sampled frames in seconds. Default: 5. */
+    sampleIntervalSeconds?: number;
+    /** Maximum number of frames to sample. Default: 20. */
+    maxFrames?: number;
+    /** Video duration in seconds. */
+    duration: number;
+}
+export declare function computeSampleTimestamps(options: SamplingOptions): number[];
+/**
+ * Options for running AI-assisted detection.
+ */
+export interface DetectionOptions {
+    /** Path to the video file. */
+    videoPath: string;
+    /** Video metadata. */
+    duration: number;
+    width: number;
+    height: number;
+    /** Sampling configuration. */
+    sampling?: SamplingOptions;
+    /** Minimum confidence threshold (0–1). Detections below this are dropped. Default: 0.5. */
+    minConfidence?: number;
+    /** Extra padding in pixels to expand each detected region. Default: 10. */
+    paddingPixels?: number;
+    /** Custom instructions to append to the detection prompt. */
+    customInstructions?: string;
+    /** Intent category inferred from the user's natural-language request. When set,
+     *  the detection system prompt and sampling defaults are tuned for that category. */
+    intentCategory?: DetectionCategory;
+    /** AI provider client to use for detection. */
+    provider: DetectionProvider;
+}
+/**
+ * Provider-agnostic interface for vision-based detection.
+ * Each AI client expects images as { data: string; mimeType: string }[].
+ */
+export interface DetectionProvider {
+    analyzeImages(images: Array<{
+        data: string;
+        mimeType: string;
+    }>, prompt: string): Promise<string>;
+}
+/**
+ * Detection statistics returned alongside detected regions.
+ */
+export interface DetectionResult {
+    /** Confidence-filtered pixel-coordinate regions (before consolidation). */
+    regions: RedactionRegion[];
+    /** Number of frames that were sampled and sent to the AI provider. */
+    sampledFrames: number;
+    /** Total number of raw detections returned by the provider (before confidence filtering). */
+    rawDetectionsCount: number;
+}
+/**
+ * Run AI-assisted detection on a video.
+ *
+ * 1. Extract evenly-spaced frames
+ * 2. Convert frames to base64
+ * 3. Send to the AI provider for analysis
+ * 4. Parse and validate the JSON response
+ * 5. Convert normalized coordinates to pixel coordinates
+ * 6. Filter by confidence threshold
+ * 7. Apply padding expansion
+ *
+ * @returns Detection result with regions, frame count, and raw detection count
+ */
+export declare function detectSensitiveRegions(options: DetectionOptions): Promise<DetectionResult>;
+export declare function parseDetectionResponse(responseText: string, videoWidth?: number, videoHeight?: number): DetectionResponse;
+export declare function convertDetectionsToRegions(response: DetectionResponse, videoWidth: number, videoHeight: number, timestamps: number[], minConfidence: number, paddingPixels: number): RedactionRegion[];
+/**
+ * Merge overlapping detections across frames into consolidated regions.
+ * Uses simple label + proximity matching (no full IOU in v1).
+ */
+export declare function mergeDetections(regions: RedactionRegion[], proximityThreshold?: number): RedactionRegion[];
+/**
+ * Internal track representing a persistent detection across time.
+ */
+interface DetectionTrack {
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    startTime: number;
+    endTime: number;
+    confidence: number;
+    frameCount: number;
+}
+/**
+ * Group detections into temporal tracks across adjacent sampled frames.
+ *
+ * Uses IOU overlap and label similarity to merge boxes that represent the
+ * same persistent secret across time. Treats persistent detections in
+ * roughly the same area as one track.
+ *
+ * @param regions - Flat list of per-frame detections (already converted to pixels)
+ * @param iouThreshold - Minimum IOU to consider two boxes the same track (default: 0.3)
+ * @param sampleInterval - Seconds between sampled frames (used for gap-filling)
+ * @returns Consolidated tracks with stable time ranges
+ */
+export declare function groupDetectionsIntoTracks(regions: RedactionRegion[], iouThreshold?: number, sampleInterval?: number): DetectionTrack[];
+/**
+ * Convert temporal tracks into a final `RedactionPlan` with time ranges.
+ *
+ * - Start time: detection timestamp minus half the sample interval
+ * - End time: last detection timestamp plus half the sample interval
+ * - Clamp to video duration
+ * - Merge short gaps between nearby detections
+ * - Expand boxes slightly to absorb tiny camera/UI shifts
+ *
+ * @param tracks - Grouped detection tracks
+ * @param videoDuration - Total video duration in seconds
+ * @param sampleInterval - Seconds between sampled frames
+ * @param paddingPixels - Extra padding to expand each region
+ * @param videoWidth - Video width for clamping
+ * @param videoHeight - Video height for clamping
+ * @returns Final consolidated redaction regions
+ */
+export declare function tracksToRedactionPlan(tracks: DetectionTrack[], videoDuration: number, sampleInterval: number, paddingPixels: number, videoWidth: number, videoHeight: number): RedactionRegion[];
+/**
+ * Full consolidation pipeline: raw detections → stable redaction regions.
+ *
+ * 1. Group detections into temporal tracks (IOU + label matching)
+ * 2. Convert tracks to time-bounded regions
+ * 3. Expand boxes and clamp to video bounds
+ *
+ * This replaces the simpler `mergeDetections()` for AI-mode detection.
+ */
+export declare function consolidateDetections(regions: RedactionRegion[], videoDuration: number, sampleInterval: number, paddingPixels: number, videoWidth: number, videoHeight: number, iouThreshold?: number): RedactionRegion[];
+export {};
+//# sourceMappingURL=redactionDetector.d.ts.map

package/dist/services/redactionDetector.d.ts.map

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