open-classify 0.1.0

package/dist/src/stock-validation.js

@@ -0,0 +1,329 @@
+import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, SECURITY_DECISION_VALUES, } from "./enums.js";
+import { Ajv } from "ajv/dist/ajv.js";
+import { STOCK_CLASSIFIER_NAMES } from "./stock.js";
+import { ensureNoDuplicates, isRecord, requireConfidence, requireEnum, requireNonEmptyStringMaxLength, requireNonNegativeSafeInteger, requireString, requireStringArray, throwInvalid, } from "./validation.js";
+export const STOCK_REASON_MAX_CHARS = 120;
+export const STOCK_REPLY_MAX_CHARS = 200;
+export const STOCK_TOOL_ID_MAX_CHARS = 64;
+export const STOCK_TOOL_DESCRIPTION_MAX_CHARS = 240;
+export const STOCK_MANIFEST_NAME_MAX_CHARS = 80;
+export const STOCK_MANIFEST_VERSION_MAX_CHARS = 40;
+export const STOCK_MANIFEST_PURPOSE_MAX_CHARS = 400;
+const STOCK_SAFETY_RISK_LEVEL_VALUES = [
+    "normal",
+    "suspicious",
+    "high_risk",
+    "unknown",
+];
+const MANIFEST_KIND_VALUES = ["stock", "custom"];
+const ajv = new Ajv({ allErrors: true, strict: false });
+const COMMON_MANIFEST_KEYS = [
+    "kind",
+    "name",
+    "version",
+    "purpose",
+    "order",
+    "fallback",
+    "backend",
+];
+const STOCK_MANIFEST_KEYS = [
+    ...COMMON_MANIFEST_KEYS,
+    "tools",
+];
+const CUSTOM_MANIFEST_KEYS = [
+    ...COMMON_MANIFEST_KEYS,
+    "output_schema",
+];
+export function validateJsonClassifierManifest(value, model = "manifest") {
+    if (!isRecord(value)) {
+        throwInvalid("manifest", model, "manifest must be a JSON object");
+    }
+    const kind = requireEnum(value.kind, MANIFEST_KIND_VALUES, "manifest", model, "kind");
+    return kind === "stock"
+        ? validateStockManifest(value, model)
+        : validateCustomManifest(value, model);
+}
+function validateStockManifest(value, model) {
+    ensureAllowedObjectKeys(value, STOCK_MANIFEST_KEYS, "manifest", model, "manifest");
+    const name = requireEnum(value.name, STOCK_CLASSIFIER_NAMES, "manifest", model, "name");
+    const base = validateManifestCommon(value, model);
+    const tools = value.tools === undefined
+        ? undefined
+        : validateTools(value.tools, model);
+    if (name !== "tools" && tools !== undefined) {
+        throwInvalid("manifest", model, "tools is only supported on the tools classifier");
+    }
+    const fallback = validateStockOutputForName(name, value.fallback, model, tools);
+    return {
+        kind: "stock",
+        name,
+        ...base,
+        fallback,
+        ...(tools === undefined ? {} : { tools }),
+    };
+}
+function validateCustomManifest(value, model) {
+    ensureAllowedObjectKeys(value, CUSTOM_MANIFEST_KEYS, "manifest", model, "manifest");
+    const name = requireNonEmptyStringMaxLength(value.name, "manifest", model, "name", STOCK_MANIFEST_NAME_MAX_CHARS);
+    if (STOCK_CLASSIFIER_NAMES.includes(name)) {
+        throwInvalid("manifest", model, `custom classifier name "${name}" collides with a stock classifier`);
+    }
+    const base = validateManifestCommon(value, model);
+    if (value.output_schema === undefined) {
+        throwInvalid("manifest", model, "output_schema is required for custom classifiers");
+    }
+    const outputSchema = value.output_schema;
+    compileOutputSchema(outputSchema, "manifest", model);
+    const fallback = validateCustomOutput(value.fallback, name, model, outputSchema);
+    return {
+        kind: "custom",
+        name,
+        ...base,
+        fallback,
+        output_schema: outputSchema,
+    };
+}
+function validateManifestCommon(value, model) {
+    const version = requireNonEmptyStringMaxLength(value.version, "manifest", model, "version", STOCK_MANIFEST_VERSION_MAX_CHARS);
+    const purpose = requireNonEmptyStringMaxLength(value.purpose, "manifest", model, "purpose", STOCK_MANIFEST_PURPOSE_MAX_CHARS);
+    const order = requireNonNegativeSafeInteger(value.order, "manifest", model, "order");
+    return {
+        version,
+        purpose,
+        order,
+        ...(value.backend === undefined ? {} : { backend: validateBackend(value.backend, model) }),
+    };
+}
+export function validateOutputForManifest(manifest, value, context) {
+    if (manifest.kind === "stock") {
+        return validateStockOutputForName(manifest.name, value, context.model, manifest.tools);
+    }
+    return validateCustomOutput(value, context.classifier, context.model, manifest.output_schema);
+}
+function validateStockOutputForName(name, value, model, tools) {
+    if (!isRecord(value)) {
+        throwInvalid(name, model, "output must be a JSON object");
+    }
+    switch (name) {
+        case "preflight":
+            return validatePreflightOutput(value, model);
+        case "routing":
+            return validateTierRoutingOutput(value, model);
+        case "model_specialization":
+            return validateModelSpecializationOutput(value, model);
+        case "tools":
+            return validateToolsOutput(value, model, tools?.map((tool) => tool.id));
+        case "security":
+            return validateSecurityOutput(value, model);
+        default: {
+            const _exhaustive = name;
+            void _exhaustive;
+            throwInvalid("manifest", model, `unknown stock classifier name`);
+        }
+    }
+}
+function validateMetadata(value, classifier, model) {
+    return {
+        ...(value.reason === undefined
+            ? {}
+            : { reason: truncateText(requireString(value.reason, classifier, model, "reason"), STOCK_REASON_MAX_CHARS) }),
+        ...(value.confidence === undefined
+            ? {}
+            : { confidence: requireConfidence(value.confidence, classifier, model) }),
+    };
+}
+function validatePreflightOutput(value, model) {
+    ensureAllowedObjectKeys(value, ["reason", "confidence", "final_reply", "ack_reply"], "preflight", model, "output");
+    if (value.final_reply !== undefined && value.ack_reply !== undefined) {
+        throwInvalid("preflight", model, "final_reply and ack_reply are mutually exclusive");
+    }
+    const meta = validateMetadata(value, "preflight", model);
+    return {
+        ...meta,
+        ...(value.final_reply === undefined
+            ? {}
+            : { final_reply: validateReplySignal(value.final_reply, "preflight", model, "final_reply") }),
+        ...(value.ack_reply === undefined
+            ? {}
+            : { ack_reply: validateReplySignal(value.ack_reply, "preflight", model, "ack_reply") }),
+    };
+}
+function validateReplySignal(value, classifier, model, field) {
+    if (!isRecord(value)) {
+        throwInvalid(classifier, model, `${field} must be an object`);
+    }
+    ensureAllowedObjectKeys(value, ["reply"], classifier, model, field);
+    const reply = requireString(value.reply, classifier, model, `${field}.reply`);
+    if (reply.trim().length === 0) {
+        throwInvalid(classifier, model, `${field}.reply must not be empty`);
+    }
+    if (reply.length > STOCK_REPLY_MAX_CHARS) {
+        throwInvalid(classifier, model, `${field}.reply must be ${STOCK_REPLY_MAX_CHARS} characters or fewer`);
+    }
+    return { reply };
+}
+function validateTierRoutingOutput(value, model) {
+    ensureAllowedObjectKeys(value, ["reason", "confidence", "model_tier"], "routing", model, "output");
+    const meta = validateMetadata(value, "routing", model);
+    const modelTier = normalizeOptionalEnumValue(value.model_tier);
+    return {
+        ...meta,
+        ...(modelTier === undefined
+            ? {}
+            : { model_tier: requireEnum(modelTier, DOWNSTREAM_MODEL_TIER_VALUES, "routing", model, "model_tier") }),
+    };
+}
+function validateModelSpecializationOutput(value, model) {
+    ensureAllowedObjectKeys(value, ["reason", "confidence", "specialization"], "model_specialization", model, "output");
+    const meta = validateMetadata(value, "model_specialization", model);
+    const specialization = normalizeOptionalEnumValue(value.specialization);
+    return {
+        ...meta,
+        ...(specialization === undefined
+            ? {}
+            : { specialization: requireEnum(specialization, MODEL_SPECIALIZATION_VALUES, "model_specialization", model, "specialization") }),
+    };
+}
+function normalizeOptionalEnumValue(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "string" && value.trim().length === 0) {
+        return undefined;
+    }
+    return value;
+}
+function validateToolsOutput(value, model, configuredTools) {
+    ensureAllowedObjectKeys(value, ["reason", "confidence", "tools"], "tools", model, "output");
+    const meta = validateMetadata(value, "tools", model);
+    const tools = requireStringArray(value.tools, "tools", model, "tools").map(normalizeTool);
+    ensureNoDuplicates(tools, "tools", model, "tools");
+    if (configuredTools) {
+        const allowed = new Set(configuredTools);
+        for (const tool of tools) {
+            if (!allowed.has(tool)) {
+                throwInvalid("tools", model, `tools includes unsupported tool ${tool}`);
+            }
+        }
+    }
+    return { ...meta, tools };
+}
+function validateSecurityOutput(value, model) {
+    ensureAllowedObjectKeys(value, ["reason", "confidence", "decision", "risk_level", "signals"], "security", model, "output");
+    const meta = validateMetadata(value, "security", model);
+    const decision = value.decision === undefined
+        ? undefined
+        : requireEnum(value.decision, SECURITY_DECISION_VALUES, "security", model, "decision");
+    const riskLevel = requireEnum(value.risk_level, STOCK_SAFETY_RISK_LEVEL_VALUES, "security", model, "risk_level");
+    const signals = requireStringArray(value.signals, "security", model, "signals");
+    ensureNoDuplicates(signals, "security", model, "signals");
+    if ((riskLevel === "normal" || riskLevel === "unknown") && signals.length > 0) {
+        throwInvalid("security", model, `${riskLevel} risk_level must not include signals`);
+    }
+    if (riskLevel !== "normal" && riskLevel !== "unknown" && signals.length === 0) {
+        throwInvalid("security", model, "elevated risk_level must include at least one signal");
+    }
+    if (decision === "block" && riskLevel !== "high_risk") {
+        throwInvalid("security", model, "decision block requires high_risk risk_level");
+    }
+    if (decision === "allow" && riskLevel === "high_risk") {
+        throwInvalid("security", model, "decision allow must not use high_risk risk_level");
+    }
+    return {
+        ...meta,
+        ...(decision === undefined ? {} : { decision }),
+        risk_level: riskLevel,
+        signals,
+    };
+}
+function validateCustomOutput(value, classifier, model, schema) {
+    if (!isRecord(value)) {
+        throwInvalid(classifier, model, "output must be a JSON object");
+    }
+    ensureAllowedObjectKeys(value, ["reason", "confidence", "output"], classifier, model, "output");
+    if (value.output === undefined) {
+        throwInvalid(classifier, model, "output is required for custom classifiers");
+    }
+    const meta = validateMetadata(value, classifier, model);
+    validateWithSchema(value.output, schema, classifier, model, "output");
+    return { ...meta, output: value.output };
+}
+function validateTools(value, model) {
+    if (!Array.isArray(value)) {
+        throwInvalid("manifest", model, "tools must be an array");
+    }
+    const out = value.map((item, index) => {
+        if (!isRecord(item)) {
+            throwInvalid("manifest", model, `tools[${index}] must be an object`);
+        }
+        return {
+            id: requireNonEmptyStringMaxLength(item.id, "manifest", model, `tools[${index}].id`, STOCK_TOOL_ID_MAX_CHARS),
+            description: requireNonEmptyStringMaxLength(item.description, "manifest", model, `tools[${index}].description`, STOCK_TOOL_DESCRIPTION_MAX_CHARS),
+        };
+    });
+    ensureNoDuplicates(out.map((item) => item.id), "manifest", model, "tools[].id");
+    return out;
+}
+function validateBackend(value, model) {
+    if (!isRecord(value))
+        throwInvalid("manifest", model, "backend must be an object");
+    ensureAllowedObjectKeys(value, ["ollama"], "manifest", model, "backend");
+    if (value.ollama === undefined)
+        return {};
+    if (!isRecord(value.ollama)) {
+        throwInvalid("manifest", model, "backend.ollama must be an object");
+    }
+    ensureAllowedObjectKeys(value.ollama, ["base_model"], "manifest", model, "backend.ollama");
+    return {
+        ollama: {
+            ...(value.ollama.base_model === undefined
+                ? {}
+                : { base_model: requireString(value.ollama.base_model, "manifest", model, "backend.ollama.base_model") }),
+        },
+    };
+}
+function ensureAllowedObjectKeys(value, allowedKeys, classifier, model, path) {
+    const allowed = new Set(allowedKeys);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throwInvalid(classifier, model, `${path}.${key} is not a supported field`);
+        }
+    }
+}
+function compileOutputSchema(schema, classifier, model) {
+    try {
+        ajv.compile(schema);
+    }
+    catch (error) {
+        throwInvalid(classifier, model, `output_schema is invalid JSON Schema: ${errorMessage(error)}`);
+    }
+}
+export function validateWithSchema(value, schema, classifier, model, path) {
+    const validate = ajv.compile(schema);
+    if (!validate(value)) {
+        const message = ajv.errorsText(validate.errors, { dataVar: path });
+        throwInvalid(classifier, model, message);
+    }
+}
+function normalizeTool(tool) {
+    const aliases = {
+        browser: "web",
+        browsing: "web",
+        internet: "web",
+        web_browsing: "web",
+        web_search: "web",
+    };
+    return aliases[tool] ?? tool;
+}
+function truncateText(text, maxChars) {
+    return text.length <= maxChars ? text : text.slice(0, maxChars).trimEnd();
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function validateClassifierOutputWithManifest(value, options) {
+    return validateOutputForManifest(options.manifest, value, {
+        classifier: options.classifier,
+        model: options.model,
+    });
+}

package/dist/src/stock.d.ts

@@ -0,0 +1,101 @@
+import type { DownstreamModelTier, ModelSpecialization, SecurityDecision } from "./enums.js";
+export interface StockClassifierMessageInput {
+    readonly role: "user" | "assistant";
+    readonly text: string;
+}
+export interface StockClassifierInput {
+    readonly messages: ReadonlyArray<StockClassifierMessageInput>;
+}
+export interface FinalReplySignal {
+    readonly reply: string;
+}
+export interface AckReplySignal {
+    readonly reply: string;
+}
+export interface RoutingSignal {
+    readonly model_tier?: DownstreamModelTier;
+    readonly specialization?: ModelSpecialization;
+}
+export interface TierSignal {
+    readonly model_tier?: DownstreamModelTier;
+}
+export interface SpecializationSignal {
+    readonly specialization?: ModelSpecialization;
+}
+export interface ToolsSignal {
+    readonly tools: ReadonlyArray<string>;
+}
+export interface SafetySignal {
+    readonly decision?: SecurityDecision;
+    readonly risk_level: "normal" | "suspicious" | "high_risk" | "unknown";
+    readonly signals: ReadonlyArray<string>;
+}
+export interface ClassifierOutputMetadata {
+    readonly reason?: string;
+    readonly confidence?: number;
+}
+export interface PreflightClassifierOutput extends ClassifierOutputMetadata {
+    readonly final_reply?: FinalReplySignal;
+    readonly ack_reply?: AckReplySignal;
+}
+export type RoutingClassifierOutput = TierSignal & ClassifierOutputMetadata;
+export type ModelSpecializationClassifierOutput = SpecializationSignal & ClassifierOutputMetadata;
+export type ToolsClassifierOutput = ToolsSignal & ClassifierOutputMetadata;
+export type SecurityClassifierOutput = SafetySignal & ClassifierOutputMetadata;
+export interface CustomClassifierOutputValue extends ClassifierOutputMetadata {
+    readonly output: unknown;
+}
+export interface StockClassifierOutputs {
+    readonly preflight: PreflightClassifierOutput;
+    readonly routing: RoutingClassifierOutput;
+    readonly model_specialization: ModelSpecializationClassifierOutput;
+    readonly tools: ToolsClassifierOutput;
+    readonly security: SecurityClassifierOutput;
+}
+export declare const STOCK_CLASSIFIER_NAMES: readonly ["preflight", "routing", "model_specialization", "tools", "security"];
+export type StockClassifierName = (typeof STOCK_CLASSIFIER_NAMES)[number];
+export type StockClassifierOutput = StockClassifierOutputs[StockClassifierName];
+export type ClassifierOutput = StockClassifierOutput | CustomClassifierOutputValue;
+export interface ToolDefinition {
+    readonly id: string;
+    readonly description: string;
+}
+interface ManifestCommon {
+    readonly version: string;
+    readonly purpose: string;
+    readonly order: number;
+    readonly backend?: {
+        readonly ollama?: {
+            readonly base_model?: string;
+        };
+    };
+}
+export interface StockJsonManifest<Name extends StockClassifierName = StockClassifierName> extends ManifestCommon {
+    readonly kind: "stock";
+    readonly name: Name;
+    readonly fallback: StockClassifierOutputs[Name];
+    readonly tools?: ReadonlyArray<ToolDefinition>;
+}
+export interface CustomJsonManifest extends ManifestCommon {
+    readonly kind: "custom";
+    readonly name: string;
+    readonly fallback: CustomClassifierOutputValue;
+    readonly output_schema: unknown;
+}
+export type JsonClassifierManifest = StockJsonManifest | CustomJsonManifest;
+export interface RuntimeStockManifest<Name extends StockClassifierName = StockClassifierName> extends StockJsonManifest<Name> {
+    readonly systemPrompt: string;
+}
+export interface RuntimeCustomManifest extends CustomJsonManifest {
+    readonly systemPrompt: string;
+}
+export type RuntimeClassifierManifest = RuntimeStockManifest | RuntimeCustomManifest;
+export declare function isStockManifest(manifest: RuntimeClassifierManifest): manifest is RuntimeStockManifest;
+export declare function isCustomManifest(manifest: RuntimeClassifierManifest): manifest is RuntimeCustomManifest;
+export interface CustomClassifierOutput {
+    readonly classifier: string;
+    readonly reason?: string;
+    readonly confidence?: number;
+    readonly output: unknown;
+}
+export {};

package/dist/src/stock.js

@@ -0,0 +1,14 @@
+export const STOCK_CLASSIFIER_NAMES = [
+    "preflight",
+    "routing",
+    "model_specialization",
+    "tools",
+    "security",
+];
+// Helper: narrow a manifest to its stock kind for callers that know the name.
+export function isStockManifest(manifest) {
+    return manifest.kind === "stock";
+}
+export function isCustomManifest(manifest) {
+    return manifest.kind === "custom";
+}

package/dist/src/types.d.ts

@@ -0,0 +1,34 @@
+export type ConversationMessageRole = "user" | "assistant";
+export interface ConversationMessageInput {
+    role?: ConversationMessageRole;
+    text: string;
+}
+export interface OpenClassifyInput {
+    /**
+     * Chronological message history ending with the message to classify.
+     *
+     * Callers should send the context they already have. Open Classify classifies
+     * only the final message and uses earlier messages as context. Normalization
+     * walks backward from the final message, keeps newest whole context messages
+     * while the classifier payload budget allows, and caps the retained history to
+     * 20 messages. It never slices message text.
+     */
+    messages: ConversationMessageInput[];
+}
+export interface NormalizedOpenClassifyInput {
+    messages: ConversationMessageInput[];
+    text: string;
+    target_message_hash: string;
+}
+export interface ClassifierInput {
+    text: string;
+    messages: ConversationMessageInput[];
+    target_message_hash: string;
+}
+export type ClassifierFallbackReason = "error" | "timeout";
+export interface ClassifierRunStatus {
+    ok: boolean;
+    source: "model" | "fallback";
+    reason?: ClassifierFallbackReason;
+    error?: string;
+}

package/dist/src/types.js

@@ -0,0 +1,6 @@
+// Shared input + run-status types. Classifier manifests and stock output
+// validation define classifier-specific runtime contracts; pipeline result
+// types live in `src/manifest.ts`. This file is intentionally small: it should
+// only hold the contract for what callers send in and the operational metadata
+// every classifier carries alongside its verdict.
+export {};

package/dist/src/ui-server.d.ts

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