zorya-classifier 0.0.0-stage → 0.2.0

package/dist/entities/representation.d.ts

@@ -0,0 +1,225 @@
+import type { DecisionState, GridCell, PixelRect, RasterImage } from './contracts.js';
+import { z } from 'zod';
+/** Canonical oriented RGBA8. Alpha remains meaningful; transparent is not black. */
+export interface RgbaRaster {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    format: 'rgba8';
+}
+export interface RepresentationView {
+    id: string;
+    role: 'source' | 'crop' | 'grid';
+    image: RasterImage;
+    sourceRegion: PixelRect;
+    grid?: {
+        cells: readonly GridCell[];
+        labels: ReadonlyMap<string, string>;
+    };
+}
+export interface RepresentationMetadata {
+    profile: string;
+    bytes: number;
+    views: {
+        id: string;
+        sourceRegion: PixelRect;
+        width: number;
+        height: number;
+        scaleX: number;
+        scaleY: number;
+        content?: PixelRect;
+    }[];
+}
+/** Prepare once for the entire decision request, including all candidate views. */
+export interface ImageRepresentationPort {
+    prepare(input: {
+        source: RasterImage;
+        views: readonly RepresentationView[];
+        signal: AbortSignal;
+    }): Promise<{
+        state: DecisionState;
+        metadata: RepresentationMetadata;
+    }>;
+}
+export declare const representationLimits: Readonly<{
+    totalBytes: number;
+    partCharacters: 64000;
+    maxSide: 64;
+    maxViews: 9;
+}>;
+export declare const preparedTextSchema: z.ZodObject<{
+    state: z.ZodArray<z.ZodString, "many">;
+    metadata: z.ZodObject<{
+        profile: z.ZodString;
+        bytes: z.ZodNumber;
+        views: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            sourceRegion: z.ZodObject<{
+                left: z.ZodNumber;
+                top: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            }, {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            }>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            scaleX: z.ZodNumber;
+            scaleY: z.ZodNumber;
+            content: z.ZodOptional<z.ZodObject<{
+                left: z.ZodNumber;
+                top: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            }, {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            width: number;
+            height: number;
+            id: string;
+            sourceRegion: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            };
+            scaleX: number;
+            scaleY: number;
+            content?: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            } | undefined;
+        }, {
+            width: number;
+            height: number;
+            id: string;
+            sourceRegion: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            };
+            scaleX: number;
+            scaleY: number;
+            content?: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            } | undefined;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        profile: string;
+        bytes: number;
+        views: {
+            width: number;
+            height: number;
+            id: string;
+            sourceRegion: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            };
+            scaleX: number;
+            scaleY: number;
+            content?: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            } | undefined;
+        }[];
+    }, {
+        profile: string;
+        bytes: number;
+        views: {
+            width: number;
+            height: number;
+            id: string;
+            sourceRegion: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            };
+            scaleX: number;
+            scaleY: number;
+            content?: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            } | undefined;
+        }[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    metadata: {
+        profile: string;
+        bytes: number;
+        views: {
+            width: number;
+            height: number;
+            id: string;
+            sourceRegion: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            };
+            scaleX: number;
+            scaleY: number;
+            content?: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            } | undefined;
+        }[];
+    };
+    state: string[];
+}, {
+    metadata: {
+        profile: string;
+        bytes: number;
+        views: {
+            width: number;
+            height: number;
+            id: string;
+            sourceRegion: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            };
+            scaleX: number;
+            scaleY: number;
+            content?: {
+                left: number;
+                top: number;
+                width: number;
+                height: number;
+            } | undefined;
+        }[];
+    };
+    state: string[];
+}>;

package/dist/entities/representation.js

@@ -0,0 +1,33 @@
+import { pixelRectSchema } from './contracts.js';
+import { z } from 'zod';
+export const representationLimits = Object.freeze({
+    totalBytes: 64 * 1024,
+    partCharacters: 64000,
+    maxSide: 64,
+    maxViews: 9,
+});
+export const preparedTextSchema = z
+    .object({
+    state: z.array(z.string().min(1).max(representationLimits.partCharacters)).min(1).max(64),
+    metadata: z
+        .object({
+        profile: z.string().min(1).max(128),
+        bytes: z.number().int().nonnegative().max(representationLimits.totalBytes),
+        views: z
+            .array(z
+            .object({
+            id: z.string().min(1).max(256),
+            sourceRegion: pixelRectSchema,
+            width: z.number().int().positive().max(16384),
+            height: z.number().int().positive().max(16384),
+            scaleX: z.number().finite().positive(),
+            scaleY: z.number().finite().positive(),
+            content: pixelRectSchema.optional(),
+        })
+            .strict())
+            .min(1)
+            .max(representationLimits.maxViews),
+    })
+        .strict(),
+})
+    .strict();

package/dist/entities/segmentation-metadata.d.ts

@@ -0,0 +1,11 @@
+/** Diagnostic native scores are uncalibrated finite values, not probabilities. */
+export interface SegmentationMetadata {
+    method: string;
+    backend: string;
+    durationMs: number;
+    input: {
+        width: number;
+        height: number;
+    };
+    qualityScore?: number;
+}

package/dist/entities/segmentation-metadata.js

@@ -0,0 +1 @@
+export {};

package/dist/entities/segmentation-verification.d.ts

@@ -0,0 +1,30 @@
+import type { ChoiceSelection, DecisionMetadata, PixelRect, RasterImage } from './contracts.js';
+import type { RgbaRaster } from './representation.js';
+/** A containment check for the same visible instance identified by the original seed. */
+export interface SegmentationBoxCheckInput {
+    image: RgbaRaster;
+    region: PixelRect;
+    seedRegion: PixelRect;
+    roi: PixelRect;
+    target: string;
+    exclusions: readonly string[];
+    signal: AbortSignal;
+}
+export type SegmentationBoxVerdict = 'complete' | 'needs-expansion' | 'unknown';
+export interface SegmentationBoxCheckResult {
+    verdict: SegmentationBoxVerdict;
+    selection: ChoiceSelection;
+    metadata: DecisionMetadata;
+}
+export interface SegmentationBoxCheckPort {
+    check(input: SegmentationBoxCheckInput): Promise<SegmentationBoxCheckResult>;
+}
+/** Full oriented source with the actual mask box and a seed anchor; no generated geometry. */
+export interface SegmentationBoxPresentationPort {
+    render(input: SegmentationBoxCheckInput): Promise<RasterImage>;
+}
+/** Containment evidence is separate from the correctness of individual mask pixels. */
+export interface SegmentationVerification {
+    checks: SegmentationBoxCheckResult[];
+    expansion: 'not-needed' | 'unsupported' | 'no-enclosing-mask' | 'rejected-mask' | 'expanded';
+}

package/dist/entities/segmentation-verification.js

@@ -0,0 +1 @@
+export {};

package/dist/entities/segmentation.d.ts

@@ -0,0 +1,159 @@
+import type { LocalizationMetadata, LocalizationResult, PixelRect } from './contracts.js';
+import type { RgbaRaster } from './representation.js';
+import type { ObjectBounds, WholeObjectFailure, WholeObjectLocated } from './whole-object.js';
+import { z } from 'zod';
+import type { SegmentationMetadata } from './segmentation-metadata.js';
+import type { SegmentationVerification } from './segmentation-verification.js';
+export type { SegmentationMetadata } from './segmentation-metadata.js';
+export declare const extractSchema: z.ZodObject<{
+    image: z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+    target: z.ZodString;
+    exclusions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    roi: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }>>;
+    representation: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"vision">;
+    }, "strict", z.ZodTypeAny, {
+        type: "vision";
+    }, {
+        type: "vision";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"experimental-text">;
+        profile: z.ZodLiteral<"text-image-v1">;
+    }, "strict", z.ZodTypeAny, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }>]>>;
+    boxTolerancePx: z.ZodDefault<z.ZodNumber>;
+    maxExtentPasses: z.ZodDefault<z.ZodNumber>;
+} & {
+    mode: z.ZodOptional<z.ZodLiteral<"whole-object">>;
+}, "strict", z.ZodTypeAny, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    exclusions: string[];
+    boxTolerancePx: number;
+    maxExtentPasses: number;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    mode?: "whole-object" | undefined;
+}, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+    exclusions?: string[] | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    mode?: "whole-object" | undefined;
+    boxTolerancePx?: number | undefined;
+    maxExtentPasses?: number | undefined;
+}>;
+export type ExtractInput = z.input<typeof extractSchema> & {
+    signal?: AbortSignal;
+};
+export interface BinaryMask {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    format: 'binary-u8';
+}
+export interface SegmentationInput {
+    image: RgbaRaster;
+    seedRegion: PixelRect;
+    /** A seed prompt identifies the instance on the full image; wholeRegion then limits search. */
+    prompt?: 'whole-region' | 'seed-region';
+    wholeRegion: PixelRect;
+    bounds: ObjectBounds;
+    roi: PixelRect;
+    target: string;
+    exclusions: readonly string[];
+    completeness: 'visible-object' | 'boundary-limited';
+    signal: AbortSignal;
+}
+export type SegmentationResult = {
+    status: 'segmented';
+    mask: BinaryMask;
+    metadata: SegmentationMetadata;
+} | {
+    status: 'unknown';
+    reason: string;
+    metadata: SegmentationMetadata;
+};
+/** Caller-owned. settle joins physical work; dispose closes this adapter only. */
+export interface SegmentationPort {
+    segment(input: SegmentationInput): Promise<SegmentationResult>;
+    /** Optional actual enclosing mask on the full source; previousMask is full-source binary-u8. */
+    expand?(input: SegmentationInput, previousMask: BinaryMask): Promise<SegmentationResult>;
+    settle(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export type ExtractionResult = {
+    status: 'extracted';
+    location: WholeObjectLocated;
+    png: Uint8Array;
+    mask: BinaryMask;
+    region: PixelRect;
+    /** Centre of the mask-derived source-space bounding rectangle. */
+    center: {
+        x: number;
+        y: number;
+    };
+    offset: {
+        x: number;
+        y: number;
+    };
+    segmentation: SegmentationMetadata;
+    verification?: SegmentationVerification;
+} | WholeObjectFailure | {
+    status: 'unknown';
+    reason: 'segmentation-uncertain';
+    location: WholeObjectLocated;
+    segmentation: SegmentationMetadata;
+    verification?: SegmentationVerification;
+} | {
+    status: 'unknown';
+    reason: 'segmentation-uncertain';
+    /** The original grid result remains a seed, never an inferred object box. */
+    seedLocation: Extract<LocalizationResult, {
+        status: 'located';
+    }>;
+    metadata: LocalizationMetadata;
+    segmentation: SegmentationMetadata;
+    verification?: SegmentationVerification;
+};

package/dist/entities/segmentation.js

@@ -0,0 +1,5 @@
+import { wholeObjectSchema } from './whole-object.js';
+import { z } from 'zod';
+export const extractSchema = wholeObjectSchema.extend({
+    mode: z.literal('whole-object').optional(),
+});

package/dist/entities/whole-object.d.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import type { SegmentationMetadata } from './segmentation-metadata.js';
+import type { SegmentationVerification } from './segmentation-verification.js';
+import type { LocalizationMetadata, LocalizationResult, LocateInput, PixelRect } from './contracts.js';
+export declare const wholeObjectSchema: z.ZodObject<{
+    image: z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+    target: z.ZodString;
+    exclusions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    roi: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }>>;
+    representation: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"vision">;
+    }, "strict", z.ZodTypeAny, {
+        type: "vision";
+    }, {
+        type: "vision";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"experimental-text">;
+        profile: z.ZodLiteral<"text-image-v1">;
+    }, "strict", z.ZodTypeAny, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }>]>>;
+} & {
+    mode: z.ZodLiteral<"whole-object">;
+    boxTolerancePx: z.ZodDefault<z.ZodNumber>;
+    maxExtentPasses: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    exclusions: string[];
+    mode: "whole-object";
+    boxTolerancePx: number;
+    maxExtentPasses: number;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+}, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    mode: "whole-object";
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+    exclusions?: string[] | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    boxTolerancePx?: number | undefined;
+    maxExtentPasses?: number | undefined;
+}>;
+export type RegionLocateInput = LocateInput;
+export type WholeObjectLocateInput = z.input<typeof wholeObjectSchema> & {
+    signal?: AbortSignal;
+};
+export type AnyLocateInput = RegionLocateInput | WholeObjectLocateInput;
+export interface BoundaryInterval {
+    start: number;
+    endExclusive: number;
+}
+export interface ObjectBounds {
+    left: BoundaryInterval;
+    right: BoundaryInterval;
+    top: BoundaryInterval;
+    bottom: BoundaryInterval;
+}
+type LocalizationFailure = Exclude<LocalizationResult, {
+    status: 'located';
+}>;
+export interface WholeObjectLocated {
+    status: 'located';
+    kind: 'whole-object';
+    region: PixelRect;
+    normalizedRegion: PixelRect;
+    seedRegion: PixelRect;
+    bounds: ObjectBounds;
+    completeness: 'visible-object' | 'boundary-limited';
+    method: 'grid-object-extent-v1' | 'pixel-mask-proposals-v1' | 'region-segmentation-v1' | 'region-checked-segmentation-v1';
+    /** Available when the bounds have been derived from actual segmented foreground. */
+    center?: {
+        x: number;
+        y: number;
+    };
+    /** Present only for the explicitly configured, caller-owned mask proposal workflow. */
+    proposalMetadata?: SegmentationMetadata;
+    verification?: SegmentationVerification;
+    metadata: LocalizationMetadata;
+}
+export type WholeObjectFailure = LocalizationFailure | {
+    status: 'unknown';
+    reason: 'instance-ambiguous' | 'extent-uncertain' | 'extent-inconsistent' | 'representation-limit' | 'segmentation-uncertain';
+    metadata: LocalizationMetadata;
+    verification?: SegmentationVerification;
+};
+export type WholeObjectLocalizationResult = WholeObjectLocated | WholeObjectFailure;
+export {};

package/dist/entities/whole-object.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import { locateSchema } from './contracts.js';
+export const wholeObjectSchema = locateSchema.extend({
+    mode: z.literal('whole-object'),
+    boxTolerancePx: z.number().int().min(1).max(64).default(8),
+    maxExtentPasses: z.number().int().min(1).max(3).default(3),
+});

package/dist/features/choice-beam-layout.d.ts

@@ -0,0 +1,18 @@
+import type { PixelRect } from '../entities/contracts.js';
+import type { ChoiceAnswer as CategoricalAnswer, GridCell, GridPanel as GridDecisionPanel } from '../entities/contracts.js';
+type ChoiceMap = Pick<CategoricalAnswer, 'choice' | 'probabilities'> | {
+    choice: string;
+    ranking: readonly string[];
+};
+type PanelGeometry = Pick<GridDecisionPanel, 'id' | 'region' | 'cells'>;
+type RankedCell = {
+    cell: GridCell;
+    probability: number | null;
+};
+/** Native Choice is validated by its consumer; this helper never normalizes raw probabilities. */
+export declare function rankChoiceBeamCells(cells: readonly GridCell[], answer: ChoiceMap): RankedCell[];
+/** S7 coarse first pass owns every requested source pixel once, including tiny or narrow ROIs. */
+export declare function choiceBeamFirstCells(region: PixelRect): GridCell[];
+/** Four independent padded source ROIs; an impossible bounded layout returns no panels. */
+export declare function choiceBeamPanels(region: PixelRect, coarseCells: readonly GridCell[], answer: ChoiceMap, accuracyPx: number): PanelGeometry[];
+export {};