zorya-classifier 0.2.1 → 0.2.2

package/README.md

@@ -6,7 +6,7 @@ Provider-independent text/image classification for Node.js and TypeScript, with
 
 Use an explicitly configured image-capable model through a supported adapter, or implement the small `DecisionPort` for another protocol. OpenRouter is an optional adapter, not a mandatory service. A more capable model may help on a task, but model strength does not guarantee a monotonic accuracy improvement. Compatibility and quality vary; see the exact [tested models/results](docs/vision-results.md), [acceptance](docs/acceptance.md), and historical [Jev baseline](docs/results.md).
 
-[Русское руководство](docs/README.ru.md) · [API](docs/api.md) · [Architecture](docs/architecture.md) · [Benchmarks](docs/benchmarks.md)
+[Русское руководство](docs/README.ru.md) · [API](docs/api.md) · [Architecture](docs/architecture.md) · [Архитектура (RU)](docs/architecture.ru.md) · [Разработка (RU)](docs/development.ru.md) · [Benchmarks](docs/benchmarks.md)
 
 Version 0.2 adds region-seeded segmentation, mask-derived bounds and optional transparent cutouts, with a closed completeness check and one bounded mask expansion. See the [usage guide](docs/v02-usage.md) for contracts, backend ownership and CLI.
 
@@ -22,7 +22,7 @@ Node.js 22.12+ is required. Source: [zoomplus/zorya-classifier](https://github.c
 npm install zorya-classifier
 ```
 
-The release archive also installs with `npm install ./zorya-classifier-0.1.0.tgz`. Runtime dependencies are Zod and Sharp; model weights, Electron, a database and background services are not included. Optional local segmentation backends and their model assets are a separate responsibility of the caller; the library does not download or choose them.
+The release archive also installs with `npm install ./zorya-classifier-0.2.0.tgz` (filename follows `package.json` version; not a claim of a newly published release). Runtime dependencies are Zod and Sharp; model weights, Electron, a database and background services are not included. Optional local segmentation backends and their model assets are a separate responsibility of the caller; the library does not download or choose them.
 
 ## Capability and status
 
@@ -135,7 +135,7 @@ The locator uses up to three sequential calls: coarse 4×4 regions, fine grids i
 
 ## Extract a mask-derived object (experimental)
 
-Extraction and caller-owned segmentation are experimental and unqualified. For a visible object box, center, or transparent cutout, use `extract` with an explicitly configured caller-owned segmenter. The existing region locator supplies a seed; the segmenter receives that seed while processing the full oriented source image. The library derives the returned box and center from actual mask pixels. After segmentation, the caller's decision port checks the original image with the mask-derived box and seed anchor. An incomplete box permits one enclosing-mask correction and one recheck; unresolved results remain unknown. This adds one or two closed checks to the normal region requests, without model-generated coordinates or an extent search. See the [0.2 usage guide](docs/v02-usage.md) and runnable [`extract-object.ts`](https://github.com/zoomplus/zorya-classifier/blob/main/examples/extract-object.ts). The classifier and segmenter are separately caller-owned and both must be disposed.
+Extraction and caller-owned segmentation are experimental and unqualified. For a visible object box, center, or transparent cutout, use `extract` with an explicitly configured caller-owned segmenter. The existing region locator supplies a seed; the segmenter receives that seed while processing the full oriented source image. The library derives the returned box and center from actual mask pixels only. After segmentation, the caller's decision port checks the full source with the mask-derived box and original seed anchor: `complete` yields the result (optional cutout); `needs-expansion` allows at most one enclosing-mask expansion and one final check (a final `complete` can still produce the result); unresolved checks, missing expansion support, no valid enclosing mask, or a failed final check yield `unknown` with no second expansion. Crops, resize and padding preserve source/mask alignment; box-check rendering uses injected `RasterPort.imageState` on the full canvas. This adds one or two closed checks to the normal region requests, without model-generated coordinates or an extent search. See the [0.2 usage guide](docs/v02-usage.md) and runnable [`extract-object.ts`](https://github.com/zoomplus/zorya-classifier/blob/main/examples/extract-object.ts). The classifier and segmenter are separately caller-owned and both must be disposed.
 
 ## Development and limits
 

package/dist/app/classifier-config.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { ObjectProposalPort } from '../entities/object-proposals.js';
+import type { SegmentationPort } from '../entities/segmentation.js';
+import type { ClassifierOptions } from './classifier-contracts.js';
+declare const configSchema: z.ZodObject<{
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    maxQueue: z.ZodDefault<z.ZodNumber>;
+    maxInputBytes: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeoutMs: number;
+    concurrency: number;
+    maxQueue: number;
+    maxInputBytes: number;
+}, {
+    timeoutMs?: number | undefined;
+    concurrency?: number | undefined;
+    maxQueue?: number | undefined;
+    maxInputBytes?: number | undefined;
+}>;
+export type ClassifierRuntimeConfig = z.infer<typeof configSchema>;
+type ValidatedClassifierPorts = {
+    segmenter: SegmentationPort | undefined;
+    objectProposals: ObjectProposalPort | undefined;
+};
+export declare function validateClassifierOptions(options: ClassifierOptions): {
+    config: ClassifierRuntimeConfig;
+    ports: ValidatedClassifierPorts;
+};
+export {};

package/dist/app/classifier-config.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { parse } from '../entities/contracts.js';
+import { ClassifierError } from '../entities/errors.js';
+const configSchema = z.object({
+    timeoutMs: z.number().int().min(1).max(120000).default(45000),
+    concurrency: z.number().int().min(1).max(4).default(2),
+    maxQueue: z.number().int().min(0).max(32).default(16),
+    maxInputBytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(256 * 1024 * 1024)
+        .default(64 * 1024 * 1024),
+});
+export function validateClassifierOptions(options) {
+    if (!options || typeof options.decision?.decide !== 'function')
+        throw new ClassifierError('INVALID_INPUT', 'A DecisionPort is required');
+    const segmenter = options.segmentation;
+    const objectProposals = options.objectProposals;
+    if (segmenter !== undefined &&
+        (!segmenter ||
+            typeof segmenter.segment !== 'function' ||
+            (segmenter.expand !== undefined && typeof segmenter.expand !== 'function') ||
+            typeof segmenter.settle !== 'function' ||
+            typeof segmenter.dispose !== 'function'))
+        throw new ClassifierError('INVALID_INPUT', 'segmentation must implement SegmentationPort');
+    if (options.segmentationBoxCheck !== undefined &&
+        (!options.segmentationBoxCheck || typeof options.segmentationBoxCheck.check !== 'function'))
+        throw new ClassifierError('INVALID_INPUT', 'segmentationBoxCheck must implement its check port');
+    if (objectProposals !== undefined &&
+        (!objectProposals ||
+            typeof objectProposals.propose !== 'function' ||
+            typeof objectProposals.settle !== 'function' ||
+            typeof objectProposals.dispose !== 'function'))
+        throw new ClassifierError('INVALID_INPUT', 'objectProposals must implement ObjectProposalPort');
+    const config = parse(configSchema, {
+        timeoutMs: options.timeoutMs,
+        concurrency: options.concurrency,
+        maxQueue: options.maxQueue,
+        maxInputBytes: options.maxInputBytes,
+    });
+    return {
+        config,
+        ports: { segmenter, objectProposals },
+    };
+}

package/dist/app/classifier-contracts.d.ts

@@ -0,0 +1,32 @@
+import type { ClassificationResult, ClassifyInput, DecisionPort, LocalizationResult, LocateInput, RefinementPort } from '../entities/contracts.js';
+import type { ExtractInput, ExtractionResult, SegmentationPort } from '../entities/segmentation.js';
+import type { ObjectProposalPort } from '../entities/object-proposals.js';
+import type { SegmentationBoxCheckPort } from '../entities/segmentation-verification.js';
+import type { AnyLocateInput, WholeObjectLocateInput, WholeObjectLocalizationResult } from '../entities/whole-object.js';
+export interface ClassifierOptions {
+    decision: DecisionPort;
+    timeoutMs?: number;
+    concurrency?: number;
+    maxQueue?: number;
+    maxInputBytes?: number;
+    /** @experimental Optional legacy region refinement; unqualified for general use. */
+    refinement?: RefinementPort;
+    /** Caller-owned; classifier disposal never disposes a shared segmenter. @experimental Unqualified segmentation adapter. */
+    segmentation?: SegmentationPort;
+    /** Optional caller-owned containment checker; by default reuses the injected decision port. @experimental Unqualified box-check override. */
+    segmentationBoxCheck?: SegmentationBoxCheckPort;
+    /** Explicit, caller-owned pixel-mask proposal strategy for whole-object operations. @experimental Unqualified proposal path. */
+    objectProposals?: ObjectProposalPort;
+}
+export interface Classifier {
+    classify(input: ClassifyInput): Promise<ClassificationResult>;
+    /** @experimental Unqualified spatial localization; see {@link LocateInput} and {@link WholeObjectLocateInput}. */
+    locate(input: WholeObjectLocateInput): Promise<WholeObjectLocalizationResult>;
+    /** @experimental Unqualified coarse region search; returns a hypothesized grid cell. */
+    locate(input: LocateInput): Promise<LocalizationResult>;
+    /** @experimental Unqualified spatial localization. */
+    locate(input: AnyLocateInput): Promise<LocalizationResult | WholeObjectLocalizationResult>;
+    /** @experimental Region-seeded extraction; unqualified for general mask or object accuracy. */
+    extract(input: ExtractInput): Promise<ExtractionResult>;
+    dispose(): Promise<void>;
+}

package/dist/app/classifier-contracts.js

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

package/dist/app/classifier-representation.d.ts

@@ -0,0 +1,5 @@
+import type { Representation } from '../entities/contracts.js';
+import type { ImageRepresentationPort } from '../entities/representation.js';
+export declare function createClassifierRepresentation(experimental: ImageRepresentationPort | undefined): {
+    representationFor(value: Representation | undefined): ImageRepresentationPort | undefined;
+};

package/dist/app/classifier-representation.js

@@ -0,0 +1,33 @@
+import { ClassifierError } from '../entities/errors.js';
+import { preparedTextSchema, representationLimits } from '../entities/representation.js';
+import { parse } from '../entities/contracts.js';
+export function createClassifierRepresentation(experimental) {
+    const textRepresentation = experimental
+        ? {
+            async prepare(input) {
+                const result = parse(preparedTextSchema, await experimental.prepare(input), 'INVALID_RESPONSE');
+                const bytes = result.state.reduce((sum, part) => sum + Buffer.byteLength(part, 'utf8'), 0);
+                if (bytes > representationLimits.totalBytes || bytes !== result.metadata.bytes)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Representation byte accounting is inconsistent');
+                return {
+                    state: result.state,
+                    metadata: {
+                        ...result.metadata,
+                        views: result.metadata.views.map(({ content, ...view }) => ({
+                            ...view,
+                            ...(content === undefined ? {} : { content }),
+                        })),
+                    },
+                };
+            },
+        }
+        : undefined;
+    function representationFor(value) {
+        if (value?.type !== 'experimental-text')
+            return undefined;
+        if (!textRepresentation)
+            throw new ClassifierError('UNSUPPORTED', 'No text-image profile has passed release qualification yet');
+        return textRepresentation;
+    }
+    return { representationFor };
+}

package/dist/app/classifier-runtime.d.ts

@@ -0,0 +1,7 @@
+import type { ClassifierRuntimeConfig } from './classifier-config.js';
+export declare function parseOperationSignal(value: unknown): AbortSignal | undefined;
+export declare function createClassifierRuntime(config: ClassifierRuntimeConfig): {
+    dispose: () => Promise<void>;
+    assertAcceptingOperations: () => void;
+    withOwnedInput: <TSnapshot, TResult>(byteCount: number, parentSignal: AbortSignal | undefined, snapshotFactory: () => TSnapshot, task: (snapshot: TSnapshot, signal: AbortSignal) => Promise<TResult>) => Promise<TResult>;
+};

package/dist/app/classifier-runtime.js

@@ -0,0 +1,71 @@
+import { ClassifierError } from '../entities/errors.js';
+import { OperationGate } from '../shared/gate.js';
+import { OperationScope } from '../shared/scope.js';
+import { InputBudget } from '../shared/input-budget.js';
+export function parseOperationSignal(value) {
+    if (value === undefined)
+        return undefined;
+    if (!(value instanceof AbortSignal))
+        throw new ClassifierError('INVALID_INPUT', 'signal must be an AbortSignal');
+    return value;
+}
+export function createClassifierRuntime(config) {
+    const gate = new OperationGate(config.concurrency, config.maxQueue);
+    const inputBudget = new InputBudget(config.maxInputBytes);
+    const owned = new Map();
+    let disposed = false;
+    async function run(signal, task) {
+        if (disposed)
+            throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+        const scope = new OperationScope(config.timeoutMs, signal);
+        const job = (async () => {
+            let acquired = false;
+            try {
+                await gate.acquire(scope.signal);
+                acquired = true;
+                scope.guard();
+                const result = await task(scope.signal);
+                scope.guard();
+                return result;
+            }
+            catch (error) {
+                scope.guard();
+                throw error;
+            }
+            finally {
+                if (acquired)
+                    gate.release();
+                scope.dispose();
+                owned.delete(scope);
+            }
+        })();
+        owned.set(scope, job);
+        return job;
+    }
+    async function dispose() {
+        disposed = true;
+        for (const scope of owned.keys())
+            scope.abort();
+        await Promise.allSettled(owned.values());
+    }
+    function assertAcceptingOperations() {
+        if (disposed)
+            throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+        gate.assertAvailable();
+    }
+    async function withOwnedInput(byteCount, parentSignal, snapshotFactory, task) {
+        const release = inputBudget.reserve(byteCount);
+        try {
+            const snapshot = snapshotFactory();
+            return await run(parentSignal, (signal) => task(snapshot, signal));
+        }
+        finally {
+            release();
+        }
+    }
+    return {
+        dispose,
+        assertAcceptingOperations,
+        withOwnedInput,
+    };
+}

package/dist/app/classifier-spatial.d.ts

@@ -0,0 +1,31 @@
+import type { DecisionPort, RasterPort } from '../entities/contracts.js';
+import type { CutoutRasterPort } from '../entities/cutout-raster.js';
+import type { BoundaryViewPort } from '../entities/boundary-view.js';
+import type { ObjectProposalPort, ObjectProposalPresentationPort } from '../entities/object-proposals.js';
+import type { ImageRepresentationPort } from '../entities/representation.js';
+import type { ExtractInput, ExtractionResult, SegmentationPort } from '../entities/segmentation.js';
+import type { SegmentationBoxCheckPort } from '../entities/segmentation-verification.js';
+import type { WholeObjectLocateInput, WholeObjectLocalizationResult } from '../entities/whole-object.js';
+import type { WholeObjectIntervalPolicy } from '../processes/whole-object.js';
+type ClassifierSpatialDeps = {
+    getDecision: () => DecisionPort;
+    raster: RasterPort;
+    cutoutRaster: CutoutRasterPort;
+    segmenter: SegmentationPort | undefined;
+    boxCheck: SegmentationBoxCheckPort | undefined;
+    proposalDependencies: {
+        decision: DecisionPort;
+        raster: RasterPort;
+        image: CutoutRasterPort;
+        proposals: ObjectProposalPort;
+        presentation: ObjectProposalPresentationPort;
+    } | undefined;
+    boundaryView: BoundaryViewPort | undefined;
+    intervalPolicy: WholeObjectIntervalPolicy | undefined;
+};
+export declare function createClassifierSpatial(deps: ClassifierSpatialDeps): {
+    locateWhole: (input: Omit<WholeObjectLocateInput, "signal">, signal: AbortSignal, representation: ImageRepresentationPort | undefined) => Promise<WholeObjectLocalizationResult>;
+    extractRegion: (input: Omit<ExtractInput, "signal">, signal: AbortSignal, representation: ImageRepresentationPort | undefined) => Promise<ExtractionResult>;
+    extractWithProposals: (snapshot: Omit<ExtractInput, "signal">, signal: AbortSignal, representation: ImageRepresentationPort | undefined) => Promise<ExtractionResult>;
+};
+export {};

package/dist/app/classifier-spatial.js

@@ -0,0 +1,78 @@
+import { ClassifierError } from '../entities/errors.js';
+import { locateWholeObjectInput } from '../processes/whole-object.js';
+import { locateInput } from '../processes/locate.js';
+import { extractFromRegion } from '../processes/extract-from-region.js';
+import { extractObject } from '../processes/extract.js';
+import { locateFromProposals } from '../processes/proposal-location.js';
+export function createClassifierSpatial(deps) {
+    const { getDecision, raster, cutoutRaster, segmenter, boxCheck, proposalDependencies, boundaryView, intervalPolicy, } = deps;
+    function extractRegion(input, signal, representation) {
+        if (!segmenter || !boxCheck)
+            throw new ClassifierError('UNSUPPORTED', 'Region extraction requires a SegmentationPort');
+        if (representation)
+            throw new ClassifierError('UNSUPPORTED', 'Checked segmentation requires vision input');
+        return extractFromRegion({ ...input, signal }, {
+            raster,
+            image: cutoutRaster,
+            segmenter,
+            boxCheck,
+            locateRegion: (source, { signal: operationSignal, ...request }) => locateInput({ ...request, image: source.bytes }, getDecision(), raster, operationSignal, undefined, representation),
+        });
+    }
+    async function locateWhole(input, signal, representation) {
+        if (segmenter) {
+            const result = await extractRegion(input, signal, representation);
+            if (result.status === 'extracted')
+                return result.location;
+            if (result.status === 'unknown' && result.reason === 'segmentation-uncertain')
+                return {
+                    status: 'unknown',
+                    reason: 'segmentation-uncertain',
+                    metadata: 'metadata' in result ? result.metadata : result.location.metadata,
+                    ...(result.verification ? { verification: result.verification } : {}),
+                };
+            return result;
+        }
+        if (proposalDependencies) {
+            if (representation)
+                throw new ClassifierError('UNSUPPORTED', 'Mask proposal selection requires vision input');
+            return (await locateFromProposals(input, proposalDependencies, signal)).location;
+        }
+        return locateWholeObjectInput(input, getDecision(), raster, signal, representation, boundaryView, intervalPolicy);
+    }
+    function extractWithProposals(snapshot, signal, representation) {
+        let prepared;
+        const selectedMask = {
+            async segment() {
+                if (!prepared?.mask || !prepared.segmentation)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Proposal selection omitted its mask');
+                return {
+                    status: 'segmented',
+                    mask: prepared.mask,
+                    metadata: prepared.segmentation,
+                };
+            },
+            async settle() { },
+            async dispose() { },
+        };
+        return extractObject({ ...snapshot, mode: 'whole-object', signal }, {
+            raster,
+            image: cutoutRaster,
+            segmenter: selectedMask,
+            locateWhole: async (source, { signal: requestSignal, ...request }) => {
+                const wholeInput = {
+                    ...request,
+                    mode: 'whole-object',
+                    image: source.bytes,
+                };
+                if (!proposalDependencies)
+                    throw new ClassifierError('UNSUPPORTED', 'ObjectProposalPort is required');
+                if (representation)
+                    throw new ClassifierError('UNSUPPORTED', 'Mask proposal selection requires vision input');
+                prepared = await locateFromProposals(wholeInput, proposalDependencies, requestSignal);
+                return prepared.location;
+            },
+        });
+    }
+    return { locateWhole, extractRegion, extractWithProposals };
+}

package/dist/app/cli-arguments.d.ts

@@ -14,8 +14,8 @@ declare const schema: z.ZodObject<{
     value: string;
     target: string;
     command: "classify-text" | "classify-image" | "locate" | "extract";
-    mode?: "region" | "whole-object" | undefined;
     provider?: "cpu" | "dml" | undefined;
+    mode?: "region" | "whole-object" | undefined;
     output?: string | undefined;
     backend?: "mobile-sam" | "grabcut" | undefined;
     encoder?: string | undefined;
@@ -25,8 +25,8 @@ declare const schema: z.ZodObject<{
     value: string;
     target: string;
     command: "classify-text" | "classify-image" | "locate" | "extract";
-    mode?: "region" | "whole-object" | undefined;
     provider?: "cpu" | "dml" | undefined;
+    mode?: "region" | "whole-object" | undefined;
     output?: string | undefined;
     backend?: "mobile-sam" | "grabcut" | undefined;
     encoder?: string | undefined;

package/dist/app/create-classifier.d.ts

@@ -1,38 +1,8 @@
-import type { ClassificationResult, ClassifyInput, DecisionPort, LocalizationResult, LocateInput, RefinementPort } from '../entities/contracts.js';
-import type { AnyLocateInput, WholeObjectLocateInput, WholeObjectLocalizationResult } from '../entities/whole-object.js';
 import type { WholeObjectIntervalPolicy } from '../processes/whole-object.js';
 import type { ImageRepresentationPort } from '../entities/representation.js';
-import type { ExtractInput, ExtractionResult, SegmentationPort } from '../entities/segmentation.js';
 import type { BoundaryViewPort } from '../entities/boundary-view.js';
-import type { ObjectProposalPort } from '../entities/object-proposals.js';
-import type { SegmentationBoxCheckPort } from '../entities/segmentation-verification.js';
-export interface ClassifierOptions {
-    decision: DecisionPort;
-    timeoutMs?: number;
-    concurrency?: number;
-    maxQueue?: number;
-    maxInputBytes?: number;
-    /** @experimental Optional legacy region refinement; unqualified for general use. */
-    refinement?: RefinementPort;
-    /** Caller-owned; classifier disposal never disposes a shared segmenter. @experimental Unqualified segmentation adapter. */
-    segmentation?: SegmentationPort;
-    /** Optional caller-owned containment checker; by default reuses the injected decision port. @experimental Unqualified box-check override. */
-    segmentationBoxCheck?: SegmentationBoxCheckPort;
-    /** Explicit, caller-owned pixel-mask proposal strategy for whole-object operations. @experimental Unqualified proposal path. */
-    objectProposals?: ObjectProposalPort;
-}
-export interface Classifier {
-    classify(input: ClassifyInput): Promise<ClassificationResult>;
-    /** @experimental Unqualified spatial localization; see {@link LocateInput} and {@link WholeObjectLocateInput}. */
-    locate(input: WholeObjectLocateInput): Promise<WholeObjectLocalizationResult>;
-    /** @experimental Unqualified coarse region search; returns a hypothesized grid cell. */
-    locate(input: LocateInput): Promise<LocalizationResult>;
-    /** @experimental Unqualified spatial localization. */
-    locate(input: AnyLocateInput): Promise<LocalizationResult | WholeObjectLocalizationResult>;
-    /** @experimental Region-seeded extraction; unqualified for general mask or object accuracy. */
-    extract(input: ExtractInput): Promise<ExtractionResult>;
-    dispose(): Promise<void>;
-}
+import type { Classifier, ClassifierOptions } from './classifier-contracts.js';
+export type { Classifier, ClassifierOptions } from './classifier-contracts.js';
 export declare function createClassifier(options: ClassifierOptions): Classifier;
-/** Internal benchmark composition. No research codec is exported by the npm entry points. */
-export declare function createResearchClassifier(options: ClassifierOptions, experimental?: ImageRepresentationPort, boundaryView?: BoundaryViewPort, intervalPolicy?: WholeObjectIntervalPolicy): Classifier;
+/** Internal composition seam for benchmark helpers; not re-exported from public entry points. */
+export declare function composeClassifier(options: ClassifierOptions, experimental?: ImageRepresentationPort, boundaryView?: BoundaryViewPort, intervalPolicy?: WholeObjectIntervalPolicy): Classifier;