open-classify 0.1.2 → 0.2.0

package/README.md

@@ -54,16 +54,15 @@ Node 18+. The packaged runner is local Ollama and ships with `gemma4:e4b-it-q4_K
 ## Hello World
 
 ```ts
-import { classifyWithOllama, loadCatalog } from "open-classify";
+import { createClassifier } from "open-classify";
 
-const result = await classifyWithOllama(
-  {
-    messages: [
-      { role: "user", text: "Can you review the attached contract?" },
-    ],
-  },
-  { catalog: loadCatalog("downstream-models.json") },
-);
+const classify = createClassifier();
+
+const result = await classify({
+  messages: [
+    { role: "user", text: "Can you review the attached contract?" },
+  ],
+});
 
 if (result.action === "route") {
   // result.downstream.model_id is a concrete model from your catalog.
@@ -72,6 +71,8 @@ if (result.action === "route") {
 }
 ```
 
+`createClassifier` builds the runner and loads the model catalog once. Reuse the returned `classify` function across your app — every call is a plain function invocation, no re-initialization.
+
 ## What you get back
 
 Every call returns a `PipelineResult` with one of three `action` values:
@@ -217,7 +218,7 @@ The resolver picks the cheapest model matching `specialization` and `tier`, rela
 
 ## Input contract
 
-`classifyWithOllama({ messages })` — that's the whole input.
+`classify({ messages })` — that's the whole input.
 
 - `messages` is chronological, oldest to newest, and must end with the user message you want classified.
 - Open Classify keeps whole messages only, drops oldest first to fit a 5,000-char budget, and caps history at 20 messages.
@@ -275,7 +276,19 @@ type RunClassifier = (
 ) => Promise<ClassifierOutput>;
 ```
 
-Pass any `RunClassifier` to `classifyOpenClassifyInput(input, { runClassifier, catalog })` to back classifiers with OpenAI, Anthropic, a remote service, or anything else. This is a code-level extension point, separate from the Ollama-only config file runner.
+Pass any `RunClassifier` to `createClassifier` to back classifiers with OpenAI, Anthropic, a remote service, or anything else. The factory takes care of catalog loading and pipeline wiring; you only own the per-classifier call.
+
+```ts
+import { createClassifier, type RunClassifier } from "open-classify";
+
+const runClassifier: RunClassifier = async (name, input, signal) => {
+  // call your provider of choice, return a ClassifierOutput
+};
+
+const classify = createClassifier({ runClassifier });
+```
+
+For the lowest-level entry point, `classifyOpenClassifyInput(input, { runClassifier, catalog })` skips the factory entirely.
 
 ## Further reading
 

package/dist/src/classifiers/custom/context_shift/manifest.json

@@ -0,0 +1,31 @@
+{
+  "kind": "custom",
+  "name": "context_shift",
+  "version": "1.0.0",
+  "purpose": "Classify whether the latest message continues, branches from, returns to, or starts a conversation thread.",
+  "order": 80,
+  "fallback": {
+    "reason": "Classifier failed; context relationship is ambiguous.",
+    "certainty": "no_signal",
+    "output": {
+      "decision": "ambiguous"
+    }
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["decision"],
+    "properties": {
+      "decision": {
+        "type": "string",
+        "enum": [
+          "same_active_thread",
+          "related_branch",
+          "return_to_prior_thread",
+          "new_thread",
+          "ambiguous"
+        ]
+      }
+    }
+  }
+}

package/dist/src/classifiers/custom/context_shift/prompt.md

@@ -0,0 +1,12 @@
+You are the context_shift classifier for an AI assistant routing system.
+
+`output.decision` describes how the final user message relates to the visible conversation history.
+
+Use `same_active_thread` when the final message directly continues, clarifies, corrects, or asks for the next step on the active topic.
+Use `related_branch` when it starts a distinct subtask or angle that still depends on the active topic.
+Use `return_to_prior_thread` when it resumes an earlier visible topic after the active topic changed.
+Use `new_thread` when it starts a materially independent topic that does not rely on the visible conversation history.
+Use `ambiguous` when the visible history is insufficient to choose one of the other labels.
+
+Do not infer hidden conversations, saved memories, external thread ids, or user intent that is not visible in the provided messages.
+Certainty should reflect confidence in the chosen label; `ambiguous` may have high certainty when ambiguity is the correct judgment.

package/dist/src/classifiers/stock/prompts/tools-output.md

@@ -1,7 +1,11 @@
 Emit the tools verdict as top-level fields:
 
+- reason: required compressed justification, 120 characters or fewer
+- certainty: required certainty tag from the shared certainty enum
 - tools: array of allowed tool ids
 
 {{allowed_tools}}
 
 An empty tools array means no downstream tools are required.
+
+Shape: {"reason":"...","certainty":"strong","tools":["workspace"]}.

package/dist/src/classify.d.ts

@@ -0,0 +1,22 @@
+import { type RunClassifier } from "./classifiers.js";
+import { type OpenClassifyConfig } from "./config.js";
+import type { AggregatorConfig, Catalog, PipelineResult } from "./manifest.js";
+import type { OpenClassifyInput } from "./types.js";
+export type Classifier = (input: OpenClassifyInput, options?: {
+    signal?: AbortSignal;
+}) => Promise<PipelineResult>;
+export interface CreateClassifierOptions {
+    runClassifier?: RunClassifier;
+    catalog?: Catalog;
+    config?: OpenClassifyConfig;
+    configPath?: string;
+    catalogPath?: string;
+    skipResourceCheck?: boolean;
+    minAvailableMemoryBytes?: number;
+    minTotalMemoryBytes?: number;
+    fetch?: typeof fetch;
+    classifierTimeoutMs?: number;
+    classifierRetryCount?: number;
+    aggregator?: AggregatorConfig;
+}
+export declare function createClassifier(options?: CreateClassifierOptions): Classifier;

package/dist/src/classify.js

@@ -0,0 +1,50 @@
+// High-level facade for the pipeline. Builds the runner and catalog once,
+// then returns a closure callers can invoke many times without re-loading
+// config or the catalog from disk. Backend-agnostic: pass a custom
+// `runClassifier` to bypass the bundled Ollama runner entirely.
+import { loadCatalog } from "./catalog.js";
+import { classifierModelsFromConfig, loadOpenClassifyConfig, } from "./config.js";
+import { assertOllamaResources, createOllamaClassifierRunner, OLLAMA_DEFAULT_CATALOG_PATH, } from "./ollama.js";
+import { classifyOpenClassifyInput } from "./pipeline.js";
+export function createClassifier(options = {}) {
+    const fileConfig = options.config ??
+        loadOpenClassifyConfig(options.configPath, {
+            optional: options.configPath === undefined &&
+                process.env.OPEN_CLASSIFY_CONFIG === undefined,
+        });
+    // When we own the runner, hoist the resource check to the wrapper so a
+    // failure surfaces as a top-level rejection — the per-classifier fallback
+    // path would otherwise mask it as five "classifier failed" entries.
+    const ownsRunner = options.runClassifier === undefined;
+    const needsResourceCheck = ownsRunner && !options.skipResourceCheck;
+    const runClassifier = options.runClassifier ??
+        createOllamaClassifierRunner({
+            host: fileConfig?.runner?.host,
+            defaultModel: fileConfig?.runner?.defaultModel,
+            models: classifierModelsFromConfig(fileConfig),
+            options: fileConfig?.runner?.options,
+            skipResourceCheck: needsResourceCheck ? true : options.skipResourceCheck,
+            fetch: options.fetch,
+        });
+    const catalog = options.catalog ??
+        loadCatalog(options.catalogPath ?? fileConfig?.catalog ?? OLLAMA_DEFAULT_CATALOG_PATH);
+    const aggregator = options.aggregator ?? fileConfig?.aggregator;
+    let resourceCheck;
+    return async (input, callOptions) => {
+        if (needsResourceCheck) {
+            resourceCheck ??= assertOllamaResources({
+                minTotalMemoryBytes: options.minTotalMemoryBytes,
+                minAvailableMemoryBytes: options.minAvailableMemoryBytes,
+            });
+            await resourceCheck;
+        }
+        return classifyOpenClassifyInput(input, {
+            runClassifier,
+            catalog,
+            classifierTimeoutMs: options.classifierTimeoutMs,
+            classifierRetryCount: options.classifierRetryCount,
+            aggregator,
+            signal: callOptions?.signal,
+        });
+    };
+}

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./aggregator.js";
 export * from "./catalog.js";
 export * from "./classifiers.js";
+export * from "./classify.js";
 export * from "./config.js";
 export * from "./enums.js";
 export * from "./input.js";

package/dist/src/index.js

@@ -6,6 +6,7 @@
 export * from "./aggregator.js";
 export * from "./catalog.js";
 export * from "./classifiers.js";
+export * from "./classify.js";
 export * from "./config.js";
 export * from "./enums.js";
 export * from "./input.js";

package/dist/src/ollama.d.ts

@@ -1,8 +1,4 @@
 import { type ClassifierName, type RunClassifier } from "./classifiers.js";
-import { type OpenClassifyConfig } from "./config.js";
-import { classifyOpenClassifyInput } from "./pipeline.js";
-import type { AggregatorConfig, Catalog } from "./manifest.js";
-import type { OpenClassifyInput } from "./types.js";
 export declare const OLLAMA_DEFAULT_HOST = "http://localhost:11434";
 export declare const OLLAMA_BASE_MODEL = "gemma4:e4b-it-q4_K_M";
 export declare const OLLAMA_BASE_MODEL_NATIVE_CONTEXT_LENGTH = 131072;
@@ -28,13 +24,6 @@ export interface OllamaClassifierRunnerConfig {
     minAvailableMemoryBytes?: number;
     minTotalMemoryBytes?: number;
 }
-export interface ClassifyWithOllamaConfig extends OllamaClassifierRunnerConfig {
-    catalog?: Catalog;
-    catalogPath?: string;
-    configPath?: string;
-    openClassifyConfig?: OpenClassifyConfig;
-    aggregator?: AggregatorConfig;
-}
 export declare class OllamaClassifierError extends Error {
     readonly classifier: ClassifierName;
     readonly model: string;
@@ -52,4 +41,3 @@ export declare function assertOllamaResources(options?: {
     minTotalMemoryBytes?: number;
     minAvailableMemoryBytes?: number;
 }): Promise<void>;
-export declare function classifyWithOllama(input: OpenClassifyInput, config?: ClassifyWithOllamaConfig): ReturnType<typeof classifyOpenClassifyInput>;

package/dist/src/ollama.js

@@ -10,10 +10,7 @@
 // `classifyOpenClassifyInput` — you don't have to use this module at all.
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { loadCatalog } from "./catalog.js";
 import { CLASSIFIER_NAMES, MODULES_BY_NAME, validateClassifierOutput, } from "./classifiers.js";
-import { classifierModelsFromConfig, loadOpenClassifyConfig, } from "./config.js";
-import { classifyOpenClassifyInput } from "./pipeline.js";
 import { ClassifierValidationError, isRecord, } from "./validation.js";
 export const OLLAMA_DEFAULT_HOST = "http://localhost:11434";
 export const OLLAMA_BASE_MODEL = "gemma4:e4b-it-q4_K_M";
@@ -93,40 +90,6 @@ export async function assertOllamaResources(options = {}) {
         throw new OllamaResourceError(totalMemoryBytes, availableMemoryBytes, minTotalMemoryBytes, minAvailableMemoryBytes);
     }
 }
-export async function classifyWithOllama(input, config = {}) {
-    const fileConfig = config.openClassifyConfig ?? loadOpenClassifyConfig(config.configPath, {
-        optional: config.configPath === undefined && process.env.OPEN_CLASSIFY_CONFIG === undefined,
-    });
-    const runnerFileConfig = fileConfig?.runner;
-    const runnerConfig = {
-        ...config,
-        host: config.host ?? runnerFileConfig?.host,
-        defaultModel: config.defaultModel ?? runnerFileConfig?.defaultModel,
-        models: {
-            ...classifierModelsFromConfig(fileConfig),
-            ...config.models,
-        },
-        options: {
-            ...runnerFileConfig?.options,
-            ...config.options,
-        },
-    };
-    if (!runnerConfig.skipResourceCheck) {
-        await assertOllamaResources({
-            minTotalMemoryBytes: runnerConfig.minTotalMemoryBytes,
-            minAvailableMemoryBytes: runnerConfig.minAvailableMemoryBytes,
-        });
-        Object.assign(runnerConfig, {
-            skipResourceCheck: true,
-        });
-    }
-    const catalog = config.catalog ?? loadCatalog(config.catalogPath ?? fileConfig?.catalog ?? OLLAMA_DEFAULT_CATALOG_PATH);
-    return classifyOpenClassifyInput(input, {
-        runClassifier: createOllamaClassifierRunner(runnerConfig),
-        catalog,
-        aggregator: config.aggregator ?? fileConfig?.aggregator,
-    });
-}
 async function runOllamaClassifier(name, input, signal, fetchImpl, host, model, options, allowManifestModel) {
     const module_ = MODULES_BY_NAME[name];
     const systemPrompt = module_.systemPrompt;

package/docs/adding-a-classifier.md

@@ -77,7 +77,8 @@ If the manifest is malformed, the loader throws `ClassifierManifestError` with t
 ## 5. Consume the output
 
 ```ts
-const result = await classifyWithOllama(input, { catalog });
+const classify = createClassifier({ catalog });
+const result = await classify(input);
 if (result.action === "route") {
   const tags = result.classifier_outputs.topic_tags?.tags ?? [];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-classify",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Manifest-driven classifier runtime for routing user messages to downstream AI models",
   "license": "MIT",
   "author": "Taylor Bayouth",