zorya-classifier 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zorya Classifier contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,13 @@
+# Notices and provenance
+
+Zorya Classifier application code is MIT. The library derives the bounded grid geometry, prompt concepts and lifecycle practices from Zorya Games' screen-locator service, source snapshot `97fca38ef027f0c83c63bd069248e6299619abd2`. Extraction changes are recorded in docs/provenance.json; the old application's private history is not included.
+
+Models, hosted APIs, Jev and OpenRouter are third-party services; each selected backend retains its own terms. Their software/model/API rights are not granted by this MIT license. Users provide their own credentials and pay the provider. There is no affiliation claim.
+
+Direct runtime dependencies: Zod 3.25.76 (MIT), Sharp 0.34.5 (Apache-2.0). Sharp's separately installed native packages contain libvips and other libraries with their own notices, including LGPL terms; preserve the notices shipped with those packages when redistributing them. npm resolves and installs them separately; this archive does not bundle their binaries.
+
+The 0.2 optional MobileSAM adapter requires separately installed ONNX Runtime Node 1.23.2 (MIT) and separately obtained pinned Acly/MobileSAM ONNX assets. The archived MobileSAM model license is Apache-2.0. The explicit GrabCut adapter uses the separately obtained OpenCV 4.13.0 JS asset under its archived Apache-2.0 license. These assets and native binaries are not bundled or downloaded on import. See docs/evidence/v02/segmentation/provenance for license texts, source revision and artifact hashes. The library's MIT license does not replace these third-party licenses.
+
+Optional benchmark photographs are CC BY 2.0, Open Images annotations CC BY 4.0, and newly authored text fixtures MIT. Preserve benchmarks/corpus/ATTRIBUTION.md and each asset's attribution. Photographs and bulk upstream annotation CSVs are downloaded separately and excluded from the npm archive and source release archive.
+
+The public result JSON under docs/evidence also includes derived Open Images bounding-box annotations. These annotations remain CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); source: Open Images V7, https://storage.googleapis.com/openimages/web/index.html. Reference coordinates were normalized/joined for evaluation. Photo pixels are not included there.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# Zorya Classifier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/zorya-classifier)](https://www.npmjs.com/package/zorya-classifier)
+
+Provider-independent text/image classification and coarse-to-fine object localization for Node.js and TypeScript. MIT application code. The library never selects or connects a model for you: create a client with an explicit `DecisionPort`, either injected by your application or built with an adapter you configure. The model and provider shown in examples are examples, not defaults. Ordinary vision language models and native decision APIs are both supported.
+
+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)
+
+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.
+
+The [frozen 80-case evaluation](docs/evidence/v02/region-seeded-heldout-v3/README.md) passed its predeclared admission criteria, but localization remains limited: 26/60 positive seed hits and 8/60 complete object boxes; no false seeds or cutouts on 20 negatives. Eight of 30 reference masks reached IoU 0.8, three failed and 19 had no predicted mask. These results describe one explicit caller-configured Luna/OpenAI + MobileSAM recipe, not every model or game.
+
+Six experimental encodings for text-only models were also tested on fresh photos and real UI captures. None qualified for image localization; see the [measured comparison](docs/evidence/v02/fresh-text/README.md). They remain research code rather than an advertised replacement for a vision model.
+
+## Install
+
+Node.js 22.12+ is required. Source: [zoomplus/zorya-classifier](https://github.com/zoomplus/zorya-classifier). Package: [zorya-classifier](https://www.npmjs.com/package/zorya-classifier).
+
+```sh
+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.
+
+## Example: Luna Decisions
+
+This example uses the typed **Decisions API** with genuine Choice probabilities. Model and provider are explicit; there are no automatic retries or fallbacks. It illustrates one integration and is not a library default. Jev is optional and is not used by this example.
+
+```ts
+import { createClassifier } from 'zorya-classifier'
+import { createOpenRouterDecisions } from 'zorya-classifier/openrouter'
+
+const apiKey = process.env.OPENROUTER_API_KEY
+if (!apiKey) throw new Error('Set OPENROUTER_API_KEY')
+const client = createClassifier({
+  decision: createOpenRouterDecisions({
+    apiKey,
+    model: 'openai/gpt-6-luna-decisions',
+    provider: 'openai',
+  }),
+})
+try {
+  const result = await client.classify({
+    input: 'Where is my order?',
+    classes: [
+      { id: 'delivery', description: 'Delivery or tracking questions' },
+      { id: 'other', description: 'All other requests' },
+    ],
+  })
+  console.log(result.choice, result.probabilities)
+} finally {
+  await client.dispose()
+}
+```
+
+For an image: `input: { image: await readFile('photo.jpg'), text: 'Which class fits?' }` with `readFile` from `node:fs/promises`. Define 2–255 distinct class IDs/descriptions and an explicit `none`/`other` class if needed. The API selects one class; it does not discover an unknown taxonomy or enumerate all objects.
+
+Native Choices retain the provider distribution and select a maximum; ties use supplied class order. There is no universal0.8 cutoff across competing classes.
+
+## Ordinary vision models are also supported
+
+Use the same `createClassifier` with `createOpenRouterVision` from `zorya-classifier/openrouter`, for example `{ apiKey, model: 'openai/gpt-6-luna', provider: 'openai', reasoningEffort: 'none' }`. This adapter uses ordinary chat completions. Choose prompt/JSON-object/JSON-schema mode to match server support.
+
+Ordinary chat models return a closed ranking, **not manufactured probabilities**. `choice` is its first ID, `ranking` contains the returned ordered IDs, and `probabilities` / `nativeChoice` are `null`. Invalid IDs, duplicates, missing answers, refusals, truncation and malformed JSON fail validation. A valid structured answer is still not proof of factual correctness. Classification/final selection request one ranked ID; spatial beam stages request four. These rank-only results remain distinct from native probability-valued results.
+
+## Direct providers and local servers
+
+There is no OpenRouter account requirement for this entry point:
+
+```ts
+import { createClassifier } from 'zorya-classifier'
+import { createOpenAICompatibleVision } from 'zorya-classifier/openai-compatible'
+
+const endpoint = process.env.VISION_CHAT_ENDPOINT
+const model = process.env.VISION_MODEL
+if (!endpoint || !model) throw new Error('Set your server endpoint and deployed model ID')
+const apiKey = process.env.VISION_API_KEY
+const client = createClassifier({
+  decision: createOpenAICompatibleVision({
+    endpoint,
+    model,
+    ...(apiKey ? { apiKey } : {}),
+  }),
+})
+try {
+  console.log(
+    await client.classify({
+      input: 'Please refund my purchase',
+      classes: [
+        { id: 'refund', description: 'A request for money back' },
+        { id: 'other', description: 'All other messages' },
+      ],
+    }),
+  )
+} finally {
+  await client.dispose()
+}
+```
+
+Supply the **full trusted chat-completions URL**, such as your local `http://localhost:8000/v1/chat/completions`, and the actual deployed model ID. Anonymous local servers can omit the key; custom headers support other authentication. These are integration examples, not a claim that every provider/model has been live-qualified. Other wire protocols can implement the exported `DecisionPort`. Keep keys on a trusted server, outside frontend bundles and Git.
+
+## Locate an object
+
+With either configured client:
+
+```ts
+const result = await client.locate({
+  image: await readFile('photo.jpg'),
+  target: 'a red backpack on the chair',
+})
+if (result.status === 'located') console.log(result.region)
+```
+
+`region` uses EXIF-oriented source pixels. It is a selected grid cell containing a hypothesized object fragment, not a tight box, segmentation mask or object-center guarantee. `unknown` is distinct from absence; transport/protocol errors throw `ClassifierError`.
+
+The locator uses up to three sequential calls: coarse 4×4 regions, fine grids in four padded regions, then four enlarged candidates. Coordinates come from code, never free-form model coordinates. Ordinary-model rankings select candidates; independent present/absent/unknown answers govern abstention. Multiple matching physical instances are allowed; one candidate is returned. Localization requires the model/endpoint to accept multiple images per call (up to nine); single-image-only endpoints can still support `classify`.
+
+## Extract a mask-derived object
+
+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`](examples/extract-object.ts). The classifier and segmenter are separately caller-owned and both must be disposed.
+
+## Development and limits
+
+```sh
+npm ci --ignore-scripts
+npm run prepare
+npm run check
+npm run pack:check
+npm run format:check
+```
+
+CLI uses explicit `ZORYA_MODEL` and defaults to `ZORYA_MODE=decisions`. OpenRouter also requires `ZORYA_PROVIDER` and `OPENROUTER_API_KEY`. For ordinary models set `ZORYA_MODE=chat`; direct chat servers use `ZORYA_ENDPOINT` and an optional separate `ZORYA_API_KEY`. Run `zorya-classifier --help` for commands.
+
+Tests are offline. Examples, CLI and explicitly authorized model benchmarks make paid calls. Default operation limits: 45-second absolute timeout, two active operations, sixteen waiters, bounded image/request/response sizes. Honor cancellation and call `dispose` on shutdown. The library has no import-time network request, hidden model switching or automatic retry.
+
+A model must understand the input, follow instructions and produce the checked answer shape. JSON Schema/JSON-object modes are opt-in when the chosen endpoint supports them; prompt-only mode does not require structured-output support. No universal accuracy, calibration or sub-second guarantee is asserted. Legacy region refinement uses `RefinementPort`; the 0.2 explicit `extract` workflow uses a caller-owned `SegmentationPort`.
+
+See [CONTRIBUTING](CONTRIBUTING.md), [SECURITY](SECURITY.md), [NOTICE](NOTICE.md), and [LICENSE](LICENSE).

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+declare const schema: z.ZodObject<{
+    command: z.ZodEnum<["classify-text", "classify-image", "locate", "extract"]>;
+    value: z.ZodString;
+    target: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<["region", "whole-object"]>>;
+    output: z.ZodOptional<z.ZodString>;
+    backend: z.ZodOptional<z.ZodEnum<["mobile-sam", "grabcut"]>>;
+    encoder: z.ZodOptional<z.ZodString>;
+    decoder: z.ZodOptional<z.ZodString>;
+    opencv: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodEnum<["cpu", "dml"]>>;
+}, "strict", z.ZodTypeAny, {
+    value: string;
+    target: string;
+    command: "classify-text" | "classify-image" | "locate" | "extract";
+    mode?: "region" | "whole-object" | undefined;
+    provider?: "cpu" | "dml" | undefined;
+    output?: string | undefined;
+    backend?: "mobile-sam" | "grabcut" | undefined;
+    encoder?: string | undefined;
+    decoder?: string | undefined;
+    opencv?: string | undefined;
+}, {
+    value: string;
+    target: string;
+    command: "classify-text" | "classify-image" | "locate" | "extract";
+    mode?: "region" | "whole-object" | undefined;
+    provider?: "cpu" | "dml" | undefined;
+    output?: string | undefined;
+    backend?: "mobile-sam" | "grabcut" | undefined;
+    encoder?: string | undefined;
+    decoder?: string | undefined;
+    opencv?: string | undefined;
+}>;
+type CliArguments = z.infer<typeof schema>;
+export declare function parseCliArguments(args: string[]): CliArguments | {
+    command: 'help';
+};
+export {};

package/dist/app/cli-arguments.js

@@ -0,0 +1,67 @@
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { parse } from '../entities/contracts.js';
+import { ClassifierError } from '../entities/errors.js';
+const schema = z
+    .object({
+    command: z.enum(['classify-text', 'classify-image', 'locate', 'extract']),
+    value: z.string().min(1),
+    target: z.string().min(1),
+    mode: z.enum(['region', 'whole-object']).optional(),
+    output: z.string().min(1).optional(),
+    backend: z.enum(['mobile-sam', 'grabcut']).optional(),
+    encoder: z.string().min(1).optional(),
+    decoder: z.string().min(1).optional(),
+    opencv: z.string().min(1).optional(),
+    provider: z.enum(['cpu', 'dml']).optional(),
+})
+    .strict();
+export function parseCliArguments(args) {
+    let raw;
+    try {
+        raw = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                mode: { type: 'string' },
+                output: { type: 'string' },
+                backend: { type: 'string' },
+                encoder: { type: 'string' },
+                decoder: { type: 'string' },
+                opencv: { type: 'string' },
+                provider: { type: 'string' },
+            },
+        });
+    }
+    catch {
+        throw new ClassifierError('INVALID_INPUT', 'Invalid CLI arguments; use --help');
+    }
+    if (raw.values['help'] || raw.positionals.length === 0)
+        return { command: 'help' };
+    if (raw.positionals.length !== 3)
+        throw new ClassifierError('INVALID_INPUT', 'Expected command, input and target/classes; use --help');
+    const { help: _help, ...values } = raw.values;
+    const parsed = parse(schema, {
+        ...values,
+        command: raw.positionals[0],
+        value: raw.positionals[1],
+        target: raw.positionals[2],
+    });
+    const nativeFlags = ['backend', 'encoder', 'decoder', 'opencv', 'provider', 'output'];
+    if (parsed.command !== 'extract' && nativeFlags.some((key) => parsed[key] !== undefined))
+        throw new ClassifierError('INVALID_INPUT', 'Native/output flags apply only to extract');
+    if (parsed.mode !== undefined && !['locate', 'extract'].includes(parsed.command))
+        throw new ClassifierError('INVALID_INPUT', 'Mode applies only to image localization');
+    if (parsed.command === 'extract') {
+        if (!parsed.output || !parsed.backend || parsed.mode === 'region')
+            throw new ClassifierError('INVALID_INPUT', 'extract requires --output and explicit --backend, and uses whole-object mode');
+        if (parsed.backend === 'mobile-sam' && (!parsed.encoder || !parsed.decoder || parsed.opencv))
+            throw new ClassifierError('INVALID_INPUT', 'mobile-sam requires --encoder and --decoder');
+        if (parsed.backend === 'grabcut' &&
+            (!parsed.opencv || parsed.encoder || parsed.decoder || parsed.provider))
+            throw new ClassifierError('INVALID_INPUT', 'grabcut requires --opencv; model/provider flags do not apply');
+    }
+    return parsed;
+}

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

@@ -0,0 +1,3 @@
+import type { DecisionPort } from '../entities/contracts.js';
+/** CLI composition only; no environment reads or network activity during import. */
+export declare function createCliDecision(environment: NodeJS.ProcessEnv): DecisionPort;

package/dist/app/cli-route.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { createOpenAICompatibleVision } from '../openai-compatible.js';
+import { createOpenRouterVision, createOpenRouterDecisions } from '../openrouter.js';
+/** CLI composition only; no environment reads or network activity during import. */
+export function createCliDecision(environment) {
+    const model = environment['ZORYA_MODEL'];
+    if (!model)
+        throw new Error('Set ZORYA_MODEL to your explicit model ID');
+    const reasoning = environment['ZORYA_REASONING_EFFORT'];
+    const reasoningEffort = reasoning
+        ? z.enum(['none', 'minimal', 'low', 'medium', 'high']).parse(reasoning)
+        : undefined;
+    const format = environment['ZORYA_RESPONSE_FORMAT'];
+    const responseFormat = format
+        ? z.enum(['prompt', 'json-object', 'json-schema']).parse(format)
+        : undefined;
+    const common = {
+        model,
+        ...(reasoningEffort ? { reasoningEffort } : {}),
+        ...(responseFormat ? { responseFormat } : {}),
+    };
+    const mode = z.enum(['decisions', 'chat']).parse(environment['ZORYA_MODE'] || 'decisions');
+    const endpoint = environment['ZORYA_ENDPOINT'];
+    if (endpoint) {
+        if (mode !== 'chat')
+            throw new Error('Custom chat-completions endpoint requires ZORYA_MODE=chat');
+        // Never forward a pre-existing OpenRouter credential to a custom endpoint.
+        const apiKey = environment['ZORYA_API_KEY'];
+        return createOpenAICompatibleVision({ endpoint, ...common, ...(apiKey ? { apiKey } : {}) });
+    }
+    const apiKey = environment['OPENROUTER_API_KEY'], provider = environment['ZORYA_PROVIDER'];
+    if (!apiKey || !provider)
+        throw new Error('OpenRouter mode requires OPENROUTER_API_KEY and ZORYA_PROVIDER; direct mode uses ZORYA_ENDPOINT and optional ZORYA_API_KEY');
+    if (mode === 'decisions') {
+        if (reasoningEffort || responseFormat)
+            throw new Error('Reasoning and response-format options apply only to ZORYA_MODE=chat');
+        return createOpenRouterDecisions({ apiKey, provider, model });
+    }
+    return createOpenRouterVision({ apiKey, provider, ...common });
+}

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

@@ -0,0 +1,33 @@
+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;
+    refinement?: RefinementPort;
+    /** Caller-owned; classifier disposal never disposes a shared segmenter. */
+    segmentation?: SegmentationPort;
+    /** Optional caller-owned containment checker; by default reuses the injected decision port. */
+    segmentationBoxCheck?: SegmentationBoxCheckPort;
+    /** Explicit, caller-owned pixel-mask proposal strategy for whole-object operations. */
+    objectProposals?: ObjectProposalPort;
+}
+export interface Classifier {
+    classify(input: ClassifyInput): Promise<ClassificationResult>;
+    locate(input: WholeObjectLocateInput): Promise<WholeObjectLocalizationResult>;
+    locate(input: LocateInput): Promise<LocalizationResult>;
+    locate(input: AnyLocateInput): Promise<LocalizationResult | WholeObjectLocalizationResult>;
+    extract(input: ExtractInput): Promise<ExtractionResult>;
+    dispose(): Promise<void>;
+}
+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;