zorya-classifier 0.2.1 → 0.2.3

package/dist/entities/contracts.d.ts

@@ -1,475 +1,6 @@
-import { z } from 'zod';
-export declare const limits: Readonly<{
-    imageBytes: number;
-    imagePixels: 16777216;
-    bodyBytes: number;
-    maxClasses: 255;
-    maxImages: 9;
-}>;
-export declare const pixelRectSchema: 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;
-}>;
-export type PixelRect = z.infer<typeof pixelRectSchema>;
-export interface GridCell {
-    id: string;
-    column: number;
-    row: number;
-    region: PixelRect;
-    xId?: string;
-    yId?: string;
-    kind?: 'cell';
-}
-export interface GridPanel {
-    id: string;
-    region: PixelRect;
-    cells: readonly GridCell[];
-}
-export declare const classSchema: z.ZodObject<{
-    id: z.ZodString;
-    description: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    description: string;
-}, {
-    id: string;
-    description: string;
-}>;
-export type ClassDefinition = z.infer<typeof classSchema>;
-export declare const representationSchema: 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";
-}>]>;
-export type Representation = z.infer<typeof representationSchema>;
-export declare const classifySchema: z.ZodObject<{
-    input: z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodObject<{
-        text: z.ZodOptional<z.ZodString>;
-        image: z.ZodOptional<z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>>;
-    }, "strict", z.ZodTypeAny, {
-        text?: string | undefined;
-        image?: Uint8Array<ArrayBufferLike> | undefined;
-    }, {
-        text?: string | undefined;
-        image?: Uint8Array<ArrayBufferLike> | undefined;
-    }>, {
-        text?: string | undefined;
-        image?: Uint8Array<ArrayBufferLike> | undefined;
-    }, {
-        text?: string | undefined;
-        image?: Uint8Array<ArrayBufferLike> | undefined;
-    }>]>;
-    classes: z.ZodEffects<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        description: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        description: string;
-    }, {
-        id: string;
-        description: string;
-    }>, "many">, {
-        id: string;
-        description: string;
-    }[], {
-        id: string;
-        description: string;
-    }[]>;
-    instructions: z.ZodOptional<z.ZodString>;
-    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";
-    }>]>>;
-}, "strict", z.ZodTypeAny, {
-    input: string | {
-        text?: string | undefined;
-        image?: Uint8Array<ArrayBufferLike> | undefined;
-    };
-    classes: {
-        id: string;
-        description: string;
-    }[];
-    instructions?: string | undefined;
-    representation?: {
-        type: "vision";
-    } | {
-        type: "experimental-text";
-        profile: "text-image-v1";
-    } | undefined;
-}, {
-    input: string | {
-        text?: string | undefined;
-        image?: Uint8Array<ArrayBufferLike> | undefined;
-    };
-    classes: {
-        id: string;
-        description: string;
-    }[];
-    instructions?: string | undefined;
-    representation?: {
-        type: "vision";
-    } | {
-        type: "experimental-text";
-        profile: "text-image-v1";
-    } | undefined;
-}>;
-export type ClassifyInput = z.input<typeof classifySchema> & {
-    signal?: AbortSignal;
-};
-export declare const locateSchema: 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;
-    }>>;
-    mode: z.ZodOptional<z.ZodLiteral<"region">>;
-    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";
-    }>]>>;
-}, "strict", z.ZodTypeAny, {
-    image: Uint8Array<ArrayBufferLike>;
-    target: string;
-    exclusions: string[];
-    representation?: {
-        type: "vision";
-    } | {
-        type: "experimental-text";
-        profile: "text-image-v1";
-    } | undefined;
-    roi?: {
-        left: number;
-        top: number;
-        width: number;
-        height: number;
-    } | undefined;
-    mode?: "region" | 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?: "region" | undefined;
-}>;
-/** @experimental Unqualified coarse region search; a located grid cell is a hypothesis, not reliable whole-object geometry or proof of absence. */
-export type LocateInput = z.input<typeof locateSchema> & {
-    signal?: AbortSignal;
-};
-export type ImagePart = {
-    type: 'image_url';
-    image_url: {
-        url: string;
-        detail: 'high';
-    };
-};
-export type DecisionState = (string | ImagePart)[];
-export type ChoiceQuestion = {
-    type: 'choice';
-    rankingSize?: 1 | 4;
-    instructions: string;
-    criteria: Record<string, string>;
-};
-type NoulQuestion = {
-    type: 'noul';
-    instructions: string;
-};
-type DecisionQuestion = ChoiceQuestion | NoulQuestion;
-export type DecisionRequest = {
-    state: DecisionState;
-    questions: Record<string, DecisionQuestion>;
-};
-export interface DecisionMetadata {
-    model: string | null;
-    provider: string | null;
-    requestId: string | null;
-    durationMs: number;
-    costUsd: number | null;
-    attempts: number;
-}
-declare const choiceAnswerSchema: z.ZodObject<{
-    type: z.ZodLiteral<"choice">;
-    choice: z.ZodString;
-    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
-    confidence: z.ZodOptional<z.ZodNumber>;
-    probabilityRoundingStep: z.ZodOptional<z.ZodLiteral<0.01>>;
-}, "strip", z.ZodTypeAny, {
-    type: "choice";
-    choice: string;
-    probabilities: Record<string, number>;
-    confidence?: number | undefined;
-    probabilityRoundingStep?: 0.01 | undefined;
-}, {
-    type: "choice";
-    choice: string;
-    probabilities: Record<string, number>;
-    confidence?: number | undefined;
-    probabilityRoundingStep?: 0.01 | undefined;
-}>;
-export type ChoiceAnswer = z.infer<typeof choiceAnswerSchema>;
-export declare const decisionResultSchema: z.ZodObject<{
-    answers: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-        type: z.ZodLiteral<"choice">;
-        choice: z.ZodString;
-        probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
-        confidence: z.ZodOptional<z.ZodNumber>;
-        probabilityRoundingStep: z.ZodOptional<z.ZodLiteral<0.01>>;
-    }, "strip", z.ZodTypeAny, {
-        type: "choice";
-        choice: string;
-        probabilities: Record<string, number>;
-        confidence?: number | undefined;
-        probabilityRoundingStep?: 0.01 | undefined;
-    }, {
-        type: "choice";
-        choice: string;
-        probabilities: Record<string, number>;
-        confidence?: number | undefined;
-        probabilityRoundingStep?: 0.01 | undefined;
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"ranked-choice">;
-        ranking: z.ZodArray<z.ZodString, "many">;
-    }, "strict", z.ZodTypeAny, {
-        type: "ranked-choice";
-        ranking: string[];
-    }, {
-        type: "ranked-choice";
-        ranking: string[];
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"presence">;
-        presence: z.ZodEnum<["present", "absent", "unknown"]>;
-    }, "strict", z.ZodTypeAny, {
-        type: "presence";
-        presence: "unknown" | "present" | "absent";
-    }, {
-        type: "presence";
-        presence: "unknown" | "present" | "absent";
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"noul">;
-        noul: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "noul";
-        noul: number;
-    }, {
-        type: "noul";
-        noul: number;
-    }>]>>;
-    metadata: z.ZodObject<{
-        model: z.ZodNullable<z.ZodString>;
-        provider: z.ZodNullable<z.ZodString>;
-        requestId: z.ZodNullable<z.ZodString>;
-        durationMs: z.ZodNumber;
-        costUsd: z.ZodNullable<z.ZodNumber>;
-        attempts: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        model: string | null;
-        provider: string | null;
-        requestId: string | null;
-        durationMs: number;
-        costUsd: number | null;
-        attempts: number;
-    }, {
-        model: string | null;
-        provider: string | null;
-        requestId: string | null;
-        durationMs: number;
-        costUsd: number | null;
-        attempts: number;
-    }>;
-}, "strip", z.ZodTypeAny, {
-    answers: Record<string, {
-        type: "choice";
-        choice: string;
-        probabilities: Record<string, number>;
-        confidence?: number | undefined;
-        probabilityRoundingStep?: 0.01 | undefined;
-    } | {
-        type: "ranked-choice";
-        ranking: string[];
-    } | {
-        type: "presence";
-        presence: "unknown" | "present" | "absent";
-    } | {
-        type: "noul";
-        noul: number;
-    }>;
-    metadata: {
-        model: string | null;
-        provider: string | null;
-        requestId: string | null;
-        durationMs: number;
-        costUsd: number | null;
-        attempts: number;
-    };
-}, {
-    answers: Record<string, {
-        type: "choice";
-        choice: string;
-        probabilities: Record<string, number>;
-        confidence?: number | undefined;
-        probabilityRoundingStep?: 0.01 | undefined;
-    } | {
-        type: "ranked-choice";
-        ranking: string[];
-    } | {
-        type: "presence";
-        presence: "unknown" | "present" | "absent";
-    } | {
-        type: "noul";
-        noul: number;
-    }>;
-    metadata: {
-        model: string | null;
-        provider: string | null;
-        requestId: string | null;
-        durationMs: number;
-        costUsd: number | null;
-        attempts: number;
-    };
-}>;
-export type DecisionResult = z.infer<typeof decisionResultSchema>;
-export interface DecisionPort {
-    decide(request: DecisionRequest, signal: AbortSignal): Promise<DecisionResult>;
-}
-export interface ChoiceSelection {
-    choice: string;
-    nativeChoice: string | null;
-    probabilities: Record<string, number> | null;
-    ranking?: string[];
-    confidence?: number;
-    probabilityRoundingStep?: 0.01;
-    tied: string[];
-}
-export interface ClassificationResult extends ChoiceSelection {
-    metadata: DecisionMetadata;
-}
-export interface LocalizationMetadata {
-    image: {
-        width: number;
-        height: number;
-        coordinateSpace: 'oriented-source-pixels';
-    };
-    stages: DecisionMetadata[];
-    durationMs: number;
-    knownCostUsd: number;
-    unknownCostCount: number;
-}
-/** @experimental Outcome of unqualified spatial localization; grid regions are not semantic object boxes or masks. */
-export type LocalizationResult = ({
-    status: 'located';
-    region: PixelRect;
-    normalizedRegion: PixelRect;
-    selection: ChoiceSelection;
-    method: 'three-choice-grid-v1';
-    refinement?: RefinementResult;
-} | {
-    status: 'not-found';
-    reason: 'absent-in-evaluated-region';
-} | {
-    status: 'unknown';
-    reason: 'uncertain-presence' | 'candidate-union-empty' | 'contradictory-evidence' | 'layout-limit';
-}) & {
-    metadata: LocalizationMetadata;
-};
-/** @experimental Optional legacy region refinement with no general quality qualification. */
-export type RefinementResult = {
-    status: 'refined';
-    region: PixelRect;
-    method: string;
-} | {
-    status: 'unknown';
-    reason: string;
-};
-/** @experimental Caller-owned refinement hook; unqualified for general spatial accuracy. */
-export interface RefinementPort {
-    refine(input: {
-        image: Uint8Array;
-        target: string;
-        region: PixelRect;
-        signal: AbortSignal;
-    }): Promise<RefinementResult>;
-}
-export declare function parse<T>(schema: z.ZodType<T, z.ZodTypeDef, unknown>, value: unknown, code?: 'INVALID_INPUT' | 'INVALID_RESPONSE'): T;
-export interface RasterImage {
-    bytes: Uint8Array;
-    width: number;
-    height: number;
-}
-export interface RasterPort {
-    normalize(bytes: Uint8Array, signal: AbortSignal): Promise<RasterImage>;
-    crop(image: RasterImage, region: PixelRect, signal: AbortSignal, scale?: number): Promise<RasterImage>;
-    imageState(image: RasterImage, signal: AbortSignal): Promise<DecisionState>;
-    grid(image: RasterImage, region: PixelRect, cells: readonly GridCell[], labels: ReadonlyMap<string, string>, signal: AbortSignal): Promise<RasterImage>;
-}
-export {};
+export { limits, representationSchema, type Representation, type RasterImage, type RasterPort, } from './image.js';
+export { pixelRectSchema, type PixelRect, type GridCell, type GridPanel } from './geometry.js';
+export { classSchema, classifySchema, type ClassDefinition, type ClassifyInput, } from './classification.js';
+export { locateSchema, type LocateInput, type LocalizationMetadata, type LocalizationResult, type RefinementPort, type RefinementResult, } from './localization.js';
+export { type ImagePart, type DecisionState, type ChoiceQuestion, type DecisionRequest, type DecisionMetadata, type ChoiceAnswer, decisionResultSchema, type DecisionResult, type DecisionPort, type ChoiceSelection, type ClassificationResult, } from './decision.js';
+export { parse } from './validation.js';

package/dist/entities/contracts.js

@@ -1,97 +1,6 @@
-import { z } from 'zod';
-import { ClassifierError } from './errors.js';
-export const limits = Object.freeze({
-    imageBytes: 16 * 1024 * 1024,
-    imagePixels: 16_777_216,
-    bodyBytes: 32 * 1024 * 1024,
-    maxClasses: 255,
-    maxImages: 9,
-});
-export const pixelRectSchema = z
-    .object({
-    left: z.number().int().nonnegative().safe(),
-    top: z.number().int().nonnegative().safe(),
-    width: z.number().int().positive().max(16384),
-    height: z.number().int().positive().max(16384),
-})
-    .strict();
-export const classSchema = z
-    .object({
-    id: z
-        .string()
-        .min(1)
-        .max(128)
-        .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
-    description: z.string().trim().min(1).max(300),
-})
-    .strict();
-const imageSchema = z
-    .custom((value) => value instanceof Uint8Array)
-    .refine((v) => v.byteLength > 0 && v.byteLength <= limits.imageBytes, 'Expected 1..16MiB image bytes');
-export const representationSchema = z.discriminatedUnion('type', [
-    z.object({ type: z.literal('vision') }).strict(),
-    z.object({ type: z.literal('experimental-text'), profile: z.literal('text-image-v1') }).strict(),
-]);
-const mediaInputSchema = z
-    .object({ text: z.string().trim().min(1).max(32000).optional(), image: imageSchema.optional() })
-    .strict()
-    .refine((v) => v.text !== undefined || v.image !== undefined, 'Provide text or image');
-export const classifySchema = z
-    .object({
-    input: z.union([z.string().trim().min(1).max(32000), mediaInputSchema]),
-    classes: z
-        .array(classSchema)
-        .min(2)
-        .max(limits.maxClasses)
-        .refine((v) => new Set(v.map((c) => c.id)).size === v.length, 'Class IDs must be unique'),
-    instructions: z.string().trim().min(1).max(4000).optional(),
-    representation: representationSchema.optional(),
-})
-    .strict();
-export const locateSchema = z
-    .object({
-    image: imageSchema,
-    target: z.string().trim().min(1).max(2000),
-    exclusions: z.array(z.string().trim().min(1).max(500)).max(16).default([]),
-    roi: pixelRectSchema.optional(),
-    mode: z.literal('region').optional(),
-    representation: representationSchema.optional(),
-})
-    .strict();
-const choiceAnswerSchema = z.object({
-    type: z.literal('choice'),
-    choice: z.string(),
-    probabilities: z.record(z.number().finite().min(0).max(1)),
-    confidence: z.number().finite().min(0).max(1).optional(),
-    probabilityRoundingStep: z.literal(0.01).optional(),
-});
-const answersSchema = z.record(z.discriminatedUnion('type', [
-    choiceAnswerSchema,
-    z
-        .object({
-        type: z.literal('ranked-choice'),
-        ranking: z.array(z.string().min(1).max(128)).min(1).max(4),
-    })
-        .strict(),
-    z
-        .object({ type: z.literal('presence'), presence: z.enum(['present', 'absent', 'unknown']) })
-        .strict(),
-    z.object({ type: z.literal('noul'), noul: z.number().finite().min(0).max(1) }),
-]));
-const metadataSchema = z.object({
-    model: z.string().nullable(),
-    provider: z.string().nullable(),
-    requestId: z.string().nullable(),
-    durationMs: z.number().finite().nonnegative(),
-    costUsd: z.number().finite().nonnegative().nullable(),
-    attempts: z.number().int().positive(),
-});
-export const decisionResultSchema = z.object({ answers: answersSchema, metadata: metadataSchema });
-export function parse(schema, value, code = 'INVALID_INPUT') {
-    const result = schema.safeParse(value);
-    if (!result.success)
-        throw new ClassifierError(code, 'Schema validation failed', {
-            paths: result.error.issues.map((v) => v.path.join('.')),
-        });
-    return result.data;
-}
+export { limits, representationSchema, } from './image.js';
+export { pixelRectSchema } from './geometry.js';
+export { classSchema, classifySchema, } from './classification.js';
+export { locateSchema, } from './localization.js';
+export { decisionResultSchema, } from './decision.js';
+export { parse } from './validation.js';