visual-ai-assertions 0.23.0 → 0.26.0

package/dist/index.d.cts

@@ -1,7 +1,21 @@
 import { z } from 'zod';
 
 /** Supported reasoning effort levels. */
+/**
+ * Abstract reasoning-effort hint. Each provider driver maps it to its native
+ * mechanism; levels a provider lacks clamp to its nearest tier.
+ *
+ * `minimal` is **not universally accepted**. OpenAI rejects it per-model with
+ * HTTP 400 ("Unsupported value: 'minimal' is not supported with the
+ * '<model>' model"), observed on `gpt-6-astra` and `gpt-6.1-sol`, whose
+ * supported set is low/medium/high/xhigh/max, and on `gpt-6-sol` and
+ * `gpt-6-luna`, which accept none/low/medium/high/xhigh/max. Gemini defines
+ * the tier but some models (e.g. Gemini 3.1 Pro) reject it, so Google and
+ * OpenRouter clamp it to `low` rather than send it. Use `minimal` only
+ * against an OpenAI model known to accept it; `low` is the portable floor.
+ */
 declare const ReasoningEffort: {
+    readonly MINIMAL: "minimal";
     readonly LOW: "low";
     readonly MEDIUM: "medium";
     readonly HIGH: "high";
@@ -34,16 +48,21 @@ declare const Model: {
     readonly Anthropic: {
         readonly FABLE_5_1: "claude-fable-5-1";
         readonly FABLE_5: "claude-fable-5";
+        readonly OPUS_5_5: "claude-opus-5-5";
         readonly OPUS_5: "claude-opus-5";
         readonly OPUS_4_8: "claude-opus-4-8";
         readonly OPUS_4_7: "claude-opus-4-7";
         readonly OPUS_4_6: "claude-opus-4-6";
+        readonly SONNET_5_5: "claude-sonnet-5-5";
         readonly SONNET_5: "claude-sonnet-5";
         readonly SONNET_4_6: "claude-sonnet-4-6";
         readonly HAIKU_4_5: "claude-haiku-4-5";
     };
     readonly OpenAI: {
         readonly GPT_6_ASTRA: "gpt-6-astra";
+        readonly GPT_6_1_SOL: "gpt-6.1-sol";
+        readonly GPT_6_SOL: "gpt-6-sol";
+        readonly GPT_6_LUNA: "gpt-6-luna";
         readonly GPT_5_6_SOL: "gpt-5.6-sol";
         readonly GPT_5_6_TERRA: "gpt-5.6-terra";
         readonly GPT_5_6_LUNA: "gpt-5.6-luna";
@@ -72,6 +91,7 @@ declare const Model: {
      */
     readonly OpenRouter: {
         readonly MUSE_SPARK_1_3: "meta/muse-spark-1.3";
+        readonly GROK_4_7: "x-ai/grok-4.7";
         readonly GROK_4_6: "x-ai/grok-4.6";
         readonly GROK_4_5: "x-ai/grok-4.5";
         readonly KIMI_K3: "moonshotai/kimi-k3";
@@ -80,16 +100,28 @@ declare const Model: {
         readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
         readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
         readonly GLM_5_3_FLASH: "z-ai/glm-5.3-flash";
+        readonly MIMO_V2_6_PRO: "xiaomi/mimo-v2.6-pro";
     };
 };
 /** Union of all built-in model name literals exposed by `Model`. */
 type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google] | (typeof Model.OpenRouter)[keyof typeof Model.OpenRouter];
-/** Default model selection used when a caller omits `config.model`. */
+/**
+ * Default model selection used when a caller omits `config.model`.
+ *
+ * Two of these carry constraints the older defaults did not:
+ * - `gpt-6.1-sol` rejects `reasoningEffort: "minimal"` (and `none`) with HTTP
+ *   400; `low` is the floor. See the `ReasoningEffort` note above.
+ * - `meta/muse-spark-1.3` is age-gated on OpenRouter and returns HTTP 403 until
+ *   the account completes the 18+ confirmation at
+ *   openrouter.ai/settings/preferences. It also reasons by default (~370-814
+ *   reasoning tokens per call) even with no effort configured, so cost per call
+ *   runs above what its headline rate suggests.
+ */
 declare const DEFAULT_MODELS: {
-    readonly anthropic: "claude-sonnet-4-6";
-    readonly openai: "gpt-5.6-luna";
-    readonly google: "gemini-3-flash-preview";
-    readonly openrouter: "qwen/qwen3.6-flash";
+    readonly anthropic: "claude-sonnet-5-5";
+    readonly openai: "gpt-6.1-sol";
+    readonly google: "gemini-3.8-flash";
+    readonly openrouter: "meta/muse-spark-1.3";
 };
 /** Built-in content checks available through `client.content()`. */
 declare const Content: {
@@ -178,13 +210,13 @@ declare const StatementResultSchema: z.ZodObject<{
     statement: string;
     pass: boolean;
     reasoning: string;
-    confidence?: "high" | "medium" | "low" | undefined;
+    confidence?: "low" | "medium" | "high" | undefined;
     timestampSeconds?: number | null | undefined;
 }, {
     statement: string;
     pass: boolean;
     reasoning: string;
-    confidence?: "high" | "medium" | "low" | undefined;
+    confidence?: "low" | "medium" | "high" | undefined;
     timestampSeconds?: number | null | undefined;
 }>;
 /** Outcome of a single statement evaluated by `check()`. */
@@ -303,13 +335,13 @@ declare const CheckResultSchema: z.ZodObject<{
         statement: string;
         pass: boolean;
         reasoning: string;
-        confidence?: "high" | "medium" | "low" | undefined;
+        confidence?: "low" | "medium" | "high" | undefined;
         timestampSeconds?: number | null | undefined;
     }, {
         statement: string;
         pass: boolean;
         reasoning: string;
-        confidence?: "high" | "medium" | "low" | undefined;
+        confidence?: "low" | "medium" | "high" | undefined;
         timestampSeconds?: number | null | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -325,7 +357,7 @@ declare const CheckResultSchema: z.ZodObject<{
         statement: string;
         pass: boolean;
         reasoning: string;
-        confidence?: "high" | "medium" | "low" | undefined;
+        confidence?: "low" | "medium" | "high" | undefined;
         timestampSeconds?: number | null | undefined;
     }[];
     usage?: {
@@ -350,7 +382,7 @@ declare const CheckResultSchema: z.ZodObject<{
         statement: string;
         pass: boolean;
         reasoning: string;
-        confidence?: "high" | "medium" | "low" | undefined;
+        confidence?: "low" | "medium" | "high" | undefined;
         timestampSeconds?: number | null | undefined;
     }[];
     usage?: {
@@ -368,17 +400,39 @@ declare const CheckResultSchema: z.ZodObject<{
  * Populated client-side; not part of the model's response.
  */
 interface VideoFramesMetadata {
-    /** Total number of frames sampled from the video. */
+    /** Number of frames actually sent to the model (after unchanged frames were dropped). */
     count: number;
-    /** Timestamp (seconds, from the start of the clip) of each sampled frame, in order. */
+    /** Timestamp (seconds, from the start of the clip) of each sent frame, in order. */
     timestampsSeconds: number[];
     /** Total duration of the source video in seconds. */
     durationSeconds: number;
+    /**
+     * Number of sampled frames dropped because they did not visibly change from
+     * the preceding kept frame. `0` when dedupe is disabled or nothing was dropped.
+     * See `FrameDedupeOptions`.
+     */
+    droppedUnchanged: number;
+}
+/**
+ * Metadata describing a video that was delivered to the model natively (as the
+ * video itself rather than sampled frames). Populated client-side.
+ */
+interface NativeVideoMetadata {
+    /** Total duration of the source video in seconds. */
+    durationSeconds: number;
+    /** Sampling rate requested from the provider, in frames per second. */
+    fps: number;
+    /** MIME type the video was sent as. */
+    mimeType: SupportedVideoMimeType;
+    /** Whether the bytes went inline in the request or through the provider's file upload API. */
+    delivery: "inline" | "file";
 }
 /** Result returned by `check()` and the template convenience methods. */
 type CheckResult = z.infer<typeof CheckResultSchema> & {
-    /** Present only when the input was a video. Describes which frames the model saw. */
+    /** Present only when the input was a video sampled into frames. Describes which frames the model saw. */
     frames?: VideoFramesMetadata;
+    /** Present only when the input was a video delivered natively to the provider. */
+    video?: NativeVideoMetadata;
 };
 /** Zod schema for an individual visual change reported by `compare()`. */
 declare const ChangeEntrySchema: z.ZodObject<{
@@ -514,6 +568,12 @@ declare const AskResultSchema: z.ZodObject<{
      * omitting the key, even for image inputs that were never asked to populate it.
      */
     frameReferences: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber, "many">>>;
+    /**
+     * For natively delivered video, the timestamps (seconds from the start of
+     * the clip) the model relied on to answer. The native counterpart of
+     * `frameReferences`. Nullable for the same strict-schema reason.
+     */
+    timestampReferences: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber, "many">>>;
     usage: z.ZodOptional<z.ZodObject<{
         inputTokens: z.ZodNumber;
         outputTokens: z.ZodNumber;
@@ -566,6 +626,7 @@ declare const AskResultSchema: z.ZodObject<{
         durationSeconds?: number | undefined;
     } | undefined;
     frameReferences?: number[] | null | undefined;
+    timestampReferences?: number[] | null | undefined;
 }, {
     issues: {
         priority: "critical" | "major" | "minor";
@@ -584,12 +645,18 @@ declare const AskResultSchema: z.ZodObject<{
         durationSeconds?: number | undefined;
     } | undefined;
     frameReferences?: number[] | null | undefined;
+    timestampReferences?: number[] | null | undefined;
 }>;
 /** Result returned by `ask()`. */
-type AskResult = Omit<z.infer<typeof AskResultSchema>, "frameReferences"> & {
-    /** Present only when the input was a video. Describes which frames the model saw. */
+type AskResult = Omit<z.infer<typeof AskResultSchema>, "frameReferences" | "timestampReferences"> & {
+    /** Present only when the input was a video sampled into frames. Indices into `frames.timestampsSeconds`. */
     frameReferences?: number[];
+    /** Present only when the input was a video delivered natively. Seconds from the start of the clip. */
+    timestampReferences?: number[];
+    /** Present only when the input was a video sampled into frames. Describes which frames the model saw. */
     frames?: VideoFramesMetadata;
+    /** Present only when the input was a video delivered natively to the provider. */
+    video?: NativeVideoMetadata;
 };
 /** Supported input shapes for image arguments accepted by the client. */
 type ImageInput = Buffer | Uint8Array | string;
@@ -628,6 +695,11 @@ interface FramesInput {
      * `timestampSeconds` (frame `i` maps to `i / fps` seconds). Default `1`.
      */
     fps?: number;
+    /**
+     * Drop frames that did not visibly change from the preceding kept frame
+     * before sending to the provider. Default `true`. See `FrameDedupeOptions`.
+     */
+    dedupe?: FrameDedupeOptions;
 }
 /** Supported image MIME types accepted by all providers. */
 type SupportedMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif";
@@ -794,7 +866,51 @@ interface VideoSamplingOptions {
      * Default `10`.
      */
     maxDurationSeconds?: number;
+    /**
+     * Drop sampled frames that did not visibly change from the preceding kept
+     * frame before sending to the provider. Default `true`. See `FrameDedupeOptions`.
+     * Only applies when frames are sampled; ignored for native delivery.
+     */
+    dedupe?: FrameDedupeOptions;
+    /**
+     * How the video reaches the model. Default `"auto"`. See `VideoDeliveryMode`.
+     */
+    mode?: VideoDeliveryMode;
 }
+/**
+ * How a video input is delivered to the model.
+ *
+ * - `"auto"` (default): send the video itself when the provider accepts video
+ *   natively (Google models), otherwise sample frames with ffmpeg.
+ * - `"native"`: always send the video itself. Throws `VisualAIConfigError`
+ *   when the provider has no native video support.
+ * - `"frames"`: always sample frames with ffmpeg, whatever the provider.
+ *
+ * Native delivery still probes the duration and enforces `maxDurationSeconds`
+ * before any provider call, and passes `fps` on as the provider's sampling
+ * rate. `maxFrames` and `dedupe` apply to frame sampling only. Pre-sampled
+ * `FramesInput` is always sent as frames.
+ */
+type VideoDeliveryMode = "auto" | "native" | "frames";
+/**
+ * Controls dropping of frames that did not visibly change from the previous
+ * kept frame, so a static screen does not cost input tokens for every sample.
+ *
+ * - `true` (default): drop unchanged frames using the default threshold.
+ * - `false`: send every sampled frame.
+ * - `{ threshold }`: the fraction `(0, 1]` of a frame's pixels that must differ
+ *   from the last kept frame for it to count as changed. Default `0.001` (0.1%,
+ *   roughly a 37x37 px region on a 1568x880 frame). Lower it to keep smaller
+ *   changes; raise it to ignore more.
+ *
+ * Each frame is compared against the most recently *kept* frame, so gradual
+ * drift accumulates and is eventually kept. The first frame is always kept.
+ * Pixel-level compression noise and tiny flickers such as a blinking text
+ * caret fall below the default threshold.
+ */
+type FrameDedupeOptions = boolean | {
+    threshold?: number;
+};
 /**
  * A single frame extracted from a video input. Identical in shape to
  * `NormalizedImage` so it can be passed transparently to provider drivers.
@@ -820,12 +936,14 @@ interface VisualAIClient {
      * Verifies one or more statements against a single image or video.
      *
      * Pass an image (PNG/JPEG/WebP/GIF) for a single-frame check. Pass a video
-     * (MP4/WebM/MOV/MKV file path, URL, base64, Buffer) and the client samples
-     * frames automatically; statements pass if they are true at any sampled
-     * frame, and each statement result includes the timestamp where it
-     * matched. The `frames` metadata on the result reports which timestamps
-     * the model saw. Pass a `FramesInput` (`{ frames, fps? }`) to supply
-     * pre-sampled frames directly — handled identically to a video timeline but
+     * (MP4/WebM/MOV/MKV file path, base64, Buffer) and statements pass if they
+     * are true at any point, with each statement result carrying the timestamp
+     * where it matched. On providers that accept video natively (Google models)
+     * the video itself is sent and the result's `video` metadata describes the
+     * delivery; elsewhere the client samples frames with ffmpeg and the `frames`
+     * metadata reports which timestamps the model saw. Control this with
+     * `video.mode`. Pass a `FramesInput` (`{ frames, fps? }`) to supply
+     * pre-sampled frames directly — handled identically to a sampled timeline but
      * without loading ffmpeg.
      *
      * @param input Image or video source as a buffer, URL, file path, or base64 string, or a `FramesInput` of pre-sampled frames.
@@ -855,11 +973,13 @@ interface VisualAIClient {
     /**
      * Asks an open-ended question about an image or video and returns a structured summary.
      *
-     * Video inputs are sampled into frames and analyzed as a chronological
-     * timeline. The result's `frameReferences` array surfaces which frames the
-     * model relied on for its answer. Pass a `FramesInput` (`{ frames, fps? }`)
-     * to supply pre-sampled frames directly — handled identically to a video
-     * timeline but without loading ffmpeg.
+     * Video inputs are analyzed as a chronological timeline. On providers that
+     * accept video natively (Google models) the video itself is sent and the
+     * result's `timestampReferences` array surfaces the moments the model relied
+     * on; elsewhere frames are sampled with ffmpeg and `frameReferences` indexes
+     * into `frames.timestampsSeconds`. Control this with `video.mode`. Pass a
+     * `FramesInput` (`{ frames, fps? }`) to supply pre-sampled frames directly —
+     * handled identically to a sampled timeline but without loading ffmpeg.
      *
      * @param input Image or video source as a buffer, URL, file path, or base64 string, or a `FramesInput` of pre-sampled frames.
      * @param prompt Prompt describing what to inspect in the input.
@@ -880,8 +1000,9 @@ interface VisualAIClient {
      * @param imageA Baseline image source.
      * @param imageB Candidate image source.
      * @param options Optional comparison prompt, instructions, and diff-image settings.
-     *   `gemini-3-flash-preview` generates an annotated diff image by default;
-     *   pass `{ diffImage: false }` to opt out.
+     *   Gemini flash models (`DIFF_ALLOWED_MODELS`) generate an annotated diff image
+     *   by default; pass `{ diffImage: false }` to opt out. Flash-Lite and Pro tiers
+     *   produce none even when asked.
      * @returns A structured comparison result with optional diff image metadata.
      * @throws {VisualAIImageError} When either image cannot be loaded or decoded.
      * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
@@ -1250,4 +1371,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
  */
 declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
 
-export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type Frame, type FramesInput, ImageDetail, type ImageDetailLevel, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
+export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type Frame, type FrameDedupeOptions, type FramesInput, ImageDetail, type ImageDetailLevel, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type NativeVideoMetadata, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoDeliveryMode, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };