open-classify 0.1.0

package/dist/src/ui-server.js

@@ -0,0 +1,250 @@
+// A tiny dev/demo HTTP server backing the bundled UI. Two responsibilities:
+//   1. Serve the static UI from `./ui` (HTML, CSS, JS).
+//   2. Run a classification over Server-Sent Events at /api/classify-stream.
+//
+// The SSE event vocabulary the UI listens for:
+//   pipeline_started        — pipeline boot, includes the classifier list
+//   pipeline_phase          — coarse phase ("normalizing" / "resource_check" /
+//                             "running"); useful for progress UI
+//   classifier_started      — a specific classifier is now running
+//   classifier_completed    — that classifier returned a model result
+//   classifier_failed       — that classifier threw without being aborted
+//   classifier_aborted      — early-exit short-circuit cancelled this classifier
+//   classifier_timed_out    — the per-classifier timeout fired
+//   pipeline_completed      — final PipelineResult payload
+//   pipeline_failed         — pipeline-level error (normalization, etc.)
+//
+// This server is intentionally minimal — no auth, no rate limiting, binds to
+// 127.0.0.1 by default. It is not meant for production.
+import { createReadStream, existsSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, normalize } from "node:path";
+import { loadCatalog } from "./catalog.js";
+import { CLASSIFIER_NAMES, REGISTRY } from "./classifiers.js";
+import { classifierModelsFromConfig, loadOpenClassifyConfig, } from "./config.js";
+import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, SECURITY_DECISION_VALUES, SECURITY_RISK_LEVEL_VALUES, SECURITY_SIGNAL_VALUES, } from "./enums.js";
+import { createOllamaClassifierRunner, OLLAMA_CONTEXT_LENGTH, OLLAMA_DEFAULT_CATALOG_PATH, OLLAMA_MIN_AVAILABLE_MEMORY_BYTES, OLLAMA_MIN_TOTAL_MEMORY_BYTES, OLLAMA_REQUIRED_PARALLELISM, } from "./ollama.js";
+import { classifyOpenClassifyInput } from "./pipeline.js";
+// Served at GET /api/enums so the UI never needs to duplicate shared enum values.
+const CLASSIFIER_ENUMS = {
+    downstream_model_tier: [...DOWNSTREAM_MODEL_TIER_VALUES],
+    model_specialization: [...MODEL_SPECIALIZATION_VALUES],
+    security_decision: [...SECURITY_DECISION_VALUES],
+    security_risk_level: [...SECURITY_RISK_LEVEL_VALUES],
+    security_signal: [...SECURITY_SIGNAL_VALUES],
+};
+const CLASSIFIER_METADATA = REGISTRY.map((classifier) => ({
+    name: classifier.name,
+    kind: classifier.kind,
+    version: classifier.version,
+    purpose: classifier.purpose,
+    order: classifier.order,
+    ...("tools" in classifier ? { tools: classifier.tools ?? [] } : {}),
+}));
+const PORT = Number(process.env.OPEN_CLASSIFY_UI_PORT ?? 4317);
+const HOST = process.env.OPEN_CLASSIFY_UI_HOST ?? "127.0.0.1";
+const UI_DIR = join(process.cwd(), "ui");
+const OPEN_CLASSIFY_CONFIG = loadOpenClassifyConfig(undefined, {
+    optional: process.env.OPEN_CLASSIFY_CONFIG === undefined,
+});
+const CATALOG_PATH = process.env.OPEN_CLASSIFY_CATALOG_PATH ??
+    OPEN_CLASSIFY_CONFIG?.catalog ??
+    OLLAMA_DEFAULT_CATALOG_PATH;
+const MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+};
+const server = createServer((request, response) => {
+    void route(request, response);
+});
+server.listen(PORT, HOST, () => {
+    console.log(`Open Classify UI running at http://${HOST}:${PORT}/`);
+});
+async function route(request, response) {
+    const startedAt = Date.now();
+    console.log(`[req] ${request.method} ${request.url}`);
+    try {
+        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+        if (request.method === "POST" && url.pathname === "/api/classify-stream") {
+            await classifyStream(request, response);
+            console.log(`[req] ${request.method} ${request.url} stream ended in ${Date.now() - startedAt}ms`);
+            return;
+        }
+        if (request.method === "GET" && url.pathname === "/api/enums") {
+            sendJson(response, CLASSIFIER_ENUMS);
+            return;
+        }
+        if (request.method === "GET" && url.pathname === "/api/classifiers") {
+            sendJson(response, { classifiers: CLASSIFIER_METADATA });
+            return;
+        }
+        if (request.method === "GET") {
+            serveStatic(url.pathname, response);
+            return;
+        }
+        sendJson(response, { error: "method not allowed" }, 405);
+    }
+    catch (error) {
+        console.error(`[req] ${request.method} ${request.url} failed:`, error);
+        sendJson(response, { error: errorMessage(error) }, 500);
+    }
+}
+async function classifyStream(request, response) {
+    response.writeHead(200, {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-cache, no-transform",
+        connection: "keep-alive",
+        "x-accel-buffering": "no",
+    });
+    response.flushHeaders();
+    // Disable Nagle so each event flushes immediately. SSE is interactive;
+    // batching kills the "live" feel.
+    request.socket.setNoDelay(true);
+    let closed = false;
+    const clientAbortController = new AbortController();
+    const abortForClientClose = () => {
+        closed = true;
+        clientAbortController.abort(new Error("SSE client disconnected"));
+    };
+    response.on("close", () => {
+        abortForClientClose();
+    });
+    response.on("error", () => {
+        abortForClientClose();
+    });
+    const send = (event, data) => {
+        if (closed || response.writableEnded || response.destroyed) {
+            console.warn(`[sse] dropped ${event} (closed=${closed} ended=${response.writableEnded})`);
+            return;
+        }
+        const ok = response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        console.log(`[sse] -> ${event}${data?.name ? ` ${data.name}` : ""}${ok ? "" : " [backpressure]"}`);
+    };
+    // SSE comment heartbeat. Some intermediaries (proxies, load balancers)
+    // close idle connections; a tiny ping every 5s keeps the stream warm.
+    // The leading `:` makes browsers ignore the line as a comment.
+    const heartbeat = setInterval(() => {
+        if (closed || response.writableEnded || response.destroyed) {
+            return;
+        }
+        response.write(`: ping ${Date.now()}\n\n`);
+    }, 5000);
+    try {
+        const input = (await readJsonBody(request));
+        const baseRunner = createOllamaClassifierRunner({
+            host: OPEN_CLASSIFY_CONFIG?.runner?.host,
+            defaultModel: OPEN_CLASSIFY_CONFIG?.runner?.defaultModel,
+            models: classifierModelsFromConfig(OPEN_CLASSIFY_CONFIG),
+            options: OPEN_CLASSIFY_CONFIG?.runner?.options,
+        });
+        const runClassifier = async (name, classifierInput, signal) => {
+            send("classifier_started", { name, started_at: Date.now() });
+            try {
+                const result = await baseRunner(name, classifierInput, signal);
+                send("classifier_completed", { name, result, completed_at: Date.now() });
+                return result;
+            }
+            catch (error) {
+                console.error(`[classifier] ${name} threw:`, error);
+                if (signal.aborted) {
+                    send(isTimeoutAbort(name, signal) ? "classifier_timed_out" : "classifier_aborted", {
+                        name,
+                        reason: errorMessage(signal.reason ?? error),
+                        completed_at: Date.now(),
+                    });
+                }
+                else {
+                    send("classifier_failed", {
+                        name,
+                        error: errorMessage(error),
+                        completed_at: Date.now(),
+                    });
+                }
+                throw error;
+            }
+        };
+        send("pipeline_started", {
+            classifiers: CLASSIFIER_NAMES,
+            started_at: Date.now(),
+        });
+        send("pipeline_phase", { phase: "normalizing" });
+        send("pipeline_phase", {
+            phase: "resource_check",
+            required_parallelism: OLLAMA_REQUIRED_PARALLELISM,
+            context_length: OLLAMA_CONTEXT_LENGTH,
+            min_total_memory_bytes: OLLAMA_MIN_TOTAL_MEMORY_BYTES,
+            min_available_memory_bytes: OLLAMA_MIN_AVAILABLE_MEMORY_BYTES,
+        });
+        send("pipeline_phase", { phase: "running" });
+        const result = await classifyOpenClassifyInput(input, {
+            runClassifier,
+            catalog: loadCatalog(CATALOG_PATH),
+            signal: clientAbortController.signal,
+        });
+        send("pipeline_completed", result);
+    }
+    catch (error) {
+        console.error("[pipeline] failed:", error);
+        send("pipeline_failed", { error: errorMessage(error) });
+    }
+    finally {
+        clearInterval(heartbeat);
+        closed = true;
+        if (!response.writableEnded && !response.destroyed) {
+            response.end();
+        }
+    }
+}
+// Distinguishes a timeout-driven abort from a pipeline early-exit abort, so
+// the UI can show the right state. We sniff the abort reason's message
+// because that's the only signal the pipeline gives us — it doesn't tag
+// reasons with a structured discriminator.
+function isTimeoutAbort(name, signal) {
+    return errorMessage(signal.reason).includes(`${name} classifier timed out`);
+}
+function serveStatic(pathname, response) {
+    const requestedPath = pathname === "/" ? "/index.html" : pathname;
+    // Two-layer path-traversal guard: strip leading `../` segments from the
+    // normalized path, then double-check the resolved file is still inside
+    // UI_DIR. The redundancy is intentional — defense in depth on a static
+    // file server is cheap.
+    const safePath = normalize(requestedPath).replace(/^(\.\.[/\\])+/, "");
+    const filePath = join(UI_DIR, safePath);
+    if (!filePath.startsWith(UI_DIR) || !existsSync(filePath)) {
+        sendJson(response, { error: "not found" }, 404);
+        return;
+    }
+    response.writeHead(200, {
+        "content-type": MIME_TYPES[extname(filePath)] ?? "application/octet-stream",
+        "cache-control": "no-store",
+    });
+    createReadStream(filePath).on("error", () => response.destroy()).pipe(response);
+}
+function sendJson(response, data, status = 200) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+    response.end(JSON.stringify(data));
+}
+// 512 KiB cap matches the input contract (5,000-char message budget plus
+// generous slack for history). Big enough for any legitimate
+// classification request, small enough to not be a DoS vector.
+async function readJsonBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.byteLength;
+        if (size > 512 * 1024) {
+            throw new Error("request body is too large");
+        }
+        chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/src/validation.d.ts

@@ -0,0 +1,17 @@
+export declare class ClassifierValidationError extends Error {
+    readonly classifier: string;
+    readonly model: string;
+    constructor(classifier: string, model: string, message: string);
+}
+export declare function throwInvalid(classifier: string, model: string, message: string): never;
+export declare function requireString(value: unknown, classifier: string, model: string, path: string): string;
+export declare function requireBoolean(value: unknown, classifier: string, model: string, path: string): boolean;
+export declare function requireNonNegativeSafeInteger(value: unknown, classifier: string, model: string, path: string): number;
+export declare function requireStringArray(value: unknown, classifier: string, model: string, path: string): string[];
+export declare function requireStringMaxLength(value: unknown, classifier: string, model: string, path: string, maxChars: number): string;
+export declare function requireNonEmptyStringMaxLength(value: unknown, classifier: string, model: string, path: string, maxChars: number): string;
+export declare function requireEnum<const Values extends readonly string[]>(value: unknown, values: Values, classifier: string, model: string, path: string): Values[number];
+export declare function requireConfidence(value: unknown, classifier: string, model: string, path?: string): number;
+export declare function ensureExactKeys(value: Record<string, unknown>, keys: readonly string[], classifier: string, model: string): void;
+export declare function ensureNoDuplicates(values: string[], classifier: string, model: string, path: string): void;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/src/validation.js

@@ -0,0 +1,127 @@
+// Backend-neutral validation helpers used by every classifier module's
+// `validate` function. These exist because hand-rolled validation gives us
+// precise error messages and full control over the failure mode, without
+// pulling in a dependency.
+//
+// Each helper takes the value, the classifier name, the backend model id
+// (for error messages), and a JSON path. On failure it throws a
+// `ClassifierValidationError` — backends catch that boundary and convert it
+// to their own error type if they want a richer one (e.g. the Ollama runner
+// wraps it as `OllamaClassifierError`).
+// Thrown by every helper here. Carries the classifier name and the backend
+// model id so backend-specific runners can wrap or report cleanly.
+export class ClassifierValidationError extends Error {
+    classifier;
+    model;
+    constructor(classifier, model, message) {
+        super(message);
+        this.name = "ClassifierValidationError";
+        this.classifier = classifier;
+        this.model = model;
+    }
+}
+export function throwInvalid(classifier, model, message) {
+    throw new ClassifierValidationError(classifier, model, `${classifier} classifier returned invalid output: ${message}`);
+}
+export function requireString(value, classifier, model, path) {
+    if (typeof value !== "string") {
+        throwInvalid(classifier, model, `${path} must be a string`);
+    }
+    return value;
+}
+export function requireBoolean(value, classifier, model, path) {
+    if (typeof value !== "boolean") {
+        throwInvalid(classifier, model, `${path} must be a boolean`);
+    }
+    return value;
+}
+export function requireNonNegativeSafeInteger(value, classifier, model, path) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throwInvalid(classifier, model, `${path} must be a non-negative safe integer`);
+    }
+    return value;
+}
+export function requireStringArray(value, classifier, model, path) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throwInvalid(classifier, model, `${path} must be an array of strings`);
+    }
+    return value;
+}
+export function requireStringMaxLength(value, classifier, model, path, maxChars) {
+    const text = requireString(value, classifier, model, path);
+    if (text.length > maxChars) {
+        throwInvalid(classifier, model, `${path} must be ${maxChars} characters or fewer`);
+    }
+    return text;
+}
+export function requireNonEmptyStringMaxLength(value, classifier, model, path, maxChars) {
+    const text = requireStringMaxLength(value, classifier, model, path, maxChars);
+    if (text.trim().length === 0) {
+        throwInvalid(classifier, model, `${path} must not be empty`);
+    }
+    return text;
+}
+export function requireEnum(value, values, classifier, model, path) {
+    if (typeof value !== "string" || !values.includes(value)) {
+        throwInvalid(classifier, model, `${path} has an unsupported value`);
+    }
+    return value;
+}
+// `confidence` must be a finite number in [0, 1]. Required on every
+// classifier output (ClassifierResultBase); fallback shapes use 0.
+export function requireConfidence(value, classifier, model, path = "confidence") {
+    const confidence = normalizeConfidence(value);
+    if (typeof confidence !== "number" ||
+        !Number.isFinite(confidence) ||
+        confidence < 0 ||
+        confidence > 1) {
+        throwInvalid(classifier, model, `${path} must be a number between 0 and 1 inclusive`);
+    }
+    return confidence;
+}
+function normalizeConfidence(value) {
+    if (typeof value === "number") {
+        return value > 1 && value <= 100 ? value / 100 : value;
+    }
+    if (typeof value !== "string")
+        return value;
+    const text = value.trim().toLowerCase();
+    if (text === "")
+        return value;
+    if (text.endsWith("%")) {
+        const percent = Number(text.slice(0, -1).trim());
+        return Number.isFinite(percent) ? percent / 100 : value;
+    }
+    const numeric = Number(text);
+    if (Number.isFinite(numeric)) {
+        return numeric > 1 && numeric <= 100 ? numeric / 100 : numeric;
+    }
+    if (text === "high")
+        return 0.9;
+    if (text === "medium")
+        return 0.5;
+    if (text === "low")
+        return 0.2;
+    return value;
+}
+export function ensureExactKeys(value, keys, classifier, model) {
+    const expected = new Set(keys);
+    for (const key of Object.keys(value)) {
+        if (!expected.has(key)) {
+            throwInvalid(classifier, model, `${key} is not a supported field`);
+        }
+    }
+    for (const key of keys) {
+        if (!(key in value)) {
+            throwInvalid(classifier, model, `${key} is required`);
+        }
+    }
+}
+export function ensureNoDuplicates(values, classifier, model, path) {
+    if (new Set(values).size !== values.length) {
+        throwInvalid(classifier, model, `${path} must not include duplicates`);
+    }
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/open-classify.config.example.json

@@ -0,0 +1,24 @@
+{
+  "runner": {
+    "provider": "ollama",
+    "host": "http://127.0.0.1:11434",
+    "defaultModel": "gemma4:e4b-it-q4_K_M",
+    "options": {
+      "num_ctx": 4096,
+      "temperature": 0
+    },
+    "models": {
+      "stock": {
+        "preflight": "gemma4:e4b-it-q4_K_M",
+        "routing": "gemma4:e4b-it-q4_K_M",
+        "model_specialization": "gemma4:e4b-it-q4_K_M",
+        "tools": "gemma4:e4b-it-q4_K_M",
+        "security": "gemma4:e4b-it-q4_K_M"
+      },
+      "custom": {
+        "memory_retrieval_queries": "gemma4:e4b-it-q4_K_M"
+      }
+    }
+  },
+  "catalog": "downstream-models.json"
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "open-classify",
+  "version": "0.1.0",
+  "description": "Manifest-driven classifier runtime for routing user messages to downstream AI models",
+  "license": "MIT",
+  "author": "Taylor Bayouth",
+  "homepage": "https://github.com/taylorbayouth/open-classify#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbayouth/open-classify.git"
+  },
+  "bugs": {
+    "url": "https://github.com/taylorbayouth/open-classify/issues"
+  },
+  "keywords": [
+    "classifier",
+    "llm",
+    "routing",
+    "ollama",
+    "gemma",
+    "ai",
+    "agent",
+    "prompt-injection"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "open-classify.config.example.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc && node scripts/copy-classifier-assets.mjs",
+    "setup": "node scripts/setup.mjs",
+    "start": "node scripts/start.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "ui": "npm run build && node dist/src/ui-server.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  }
+}