zorya-classifier 0.0.0-stage → 0.1.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,11 @@
+# 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.
+
+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,128 @@
-# 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.
+Provider-independent text/image classification and coarse-to-fine object localization for Node.js and TypeScript. MIT application code. **Native decision models are the primary integration**, with Luna Decisions as the main example; ordinary vision language models are also supported without a native classification API.
+
+Use any image-capable instruction-following model through an OpenAI-compatible API, or implement the small `DecisionPort` for another protocol. OpenRouter is an optional adapter, not a mandatory service. Model compatibility and accuracy 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)
+
+## 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.
+
+## Quickstart: 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. 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`.
+
+## 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. Optional segmentation/refinement is a caller-owned `RefinementPort`.
+
+See [CONTRIBUTING](CONTRIBUTING.md), [SECURITY](SECURITY.md), [NOTICE](NOTICE.md), and [LICENSE](LICENSE).

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,14 @@
+import type { ClassificationResult, ClassifyInput, DecisionPort, LocalizationResult, LocateInput, RefinementPort } from '../entities/contracts.js';
+export interface ClassifierOptions {
+    decision: DecisionPort;
+    timeoutMs?: number;
+    concurrency?: number;
+    maxQueue?: number;
+    refinement?: RefinementPort;
+}
+export interface Classifier {
+    classify(input: ClassifyInput): Promise<ClassificationResult>;
+    locate(input: LocateInput): Promise<LocalizationResult>;
+    dispose(): Promise<void>;
+}
+export declare function createClassifier(options: ClassifierOptions): Classifier;

package/dist/app/create-classifier.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { classifySchema, locateSchema, parse } from '../entities/contracts.js';
+import { ClassifierError } from '../entities/errors.js';
+import { createSharpRaster } from '../infrastructure/raster.js';
+import { classifyInput } from '../processes/classify.js';
+import { locateInput } from '../processes/locate.js';
+import { OperationGate } from '../shared/gate.js';
+import { OperationScope } from '../shared/scope.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),
+});
+function signalOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (!(value instanceof AbortSignal))
+        throw new ClassifierError('INVALID_INPUT', 'signal must be an AbortSignal');
+    return value;
+}
+export function createClassifier(options) {
+    if (!options || typeof options.decision?.decide !== 'function')
+        throw new ClassifierError('INVALID_INPUT', 'A DecisionPort is required');
+    const config = parse(configSchema, {
+        timeoutMs: options.timeoutMs,
+        concurrency: options.concurrency,
+        maxQueue: options.maxQueue,
+    });
+    const gate = new OperationGate(config.concurrency, config.maxQueue);
+    const raster = createSharpRaster();
+    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;
+    }
+    return {
+        async classify(input) {
+            if (disposed)
+                throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+            gate.assertAvailable();
+            if (!input || typeof input !== 'object')
+                throw new ClassifierError('INVALID_INPUT', 'Expected classify input object');
+            const { signal, ...rest } = input;
+            const parent = signalOf(signal);
+            const parsed = parse(classifySchema, rest);
+            const media = typeof parsed.input === 'string'
+                ? parsed.input
+                : {
+                    ...parsed.input,
+                    ...(parsed.input.image === undefined
+                        ? {}
+                        : { image: new Uint8Array(parsed.input.image) }),
+                };
+            return run(parent, (s) => classifyInput({ ...parsed, input: media }, options.decision, raster, s));
+        },
+        async locate(input) {
+            if (disposed)
+                throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+            gate.assertAvailable();
+            if (!input || typeof input !== 'object')
+                throw new ClassifierError('INVALID_INPUT', 'Expected locate input object');
+            const { signal, ...rest } = input;
+            const parent = signalOf(signal);
+            const parsed = parse(locateSchema, rest);
+            const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
+            return run(parent, (s) => locateInput(snapshot, options.decision, raster, s, options.refinement));
+        },
+        async dispose() {
+            disposed = true;
+            for (const scope of owned.keys())
+                scope.abort();
+            await Promise.allSettled(owned.values());
+        },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { createClassifier } from './index.js';
+import { createCliDecision } from './app/cli-route.js';
+async function main() {
+    const [command, value, target] = process.argv.slice(2);
+    if (command === '--help' || !command) {
+        console.log('zorya-classifier classify-text <text> <classes.json>\nzorya-classifier classify-image <image> <classes.json>\nzorya-classifier locate <image> <target>\nSet ZORYA_MODEL. Default ZORYA_MODE=decisions; use chat for ordinary vision models/custom chat endpoints. OpenRouter: OPENROUTER_API_KEY + ZORYA_PROVIDER. Direct: ZORYA_ENDPOINT + optional ZORYA_API_KEY. Optional ZORYA_REASONING_EFFORT and ZORYA_RESPONSE_FORMAT. One classify request; up to three locate requests.');
+        return;
+    }
+    if (!['classify-text', 'classify-image', 'locate'].includes(command) || !value || !target)
+        throw new Error('Invalid arguments; use --help');
+    const client = createClassifier({ decision: createCliDecision(process.env) });
+    try {
+        if (command === 'locate')
+            console.log(JSON.stringify(await client.locate({ image: await readFile(value), target }), null, 2));
+        else {
+            const { z } = await import('zod');
+            const { classSchema } = await import('./entities/contracts.js');
+            const unknownClasses = JSON.parse(await readFile(target, 'utf8'));
+            const classes = z.array(classSchema).parse(unknownClasses);
+            const input = command === 'classify-text' ? value : { image: await readFile(value) };
+            console.log(JSON.stringify(await client.classify({ input, classes }), null, 2));
+        }
+    }
+    finally {
+        await client.dispose();
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : 'Command failed');
+    process.exitCode = 1;
+});