open-classify 0.6.0 → 0.7.0

package/README.md

@@ -41,43 +41,53 @@ Every classifier uses the same manifest shape and emits the same output envelope
 - **Shape downstream context intentionally.** Built-in and custom classifiers can recommend tools, retrieval queries, summaries, or other context hints without passing the full conversation history back to the caller.
 - **Add another defensive layer.** The `prompt_injection` classifier surfaces instruction-override attempts. High-risk or unknown injection risk automatically sets `action: "block"`.
 
-## Install
+## Getting started
+
+Node 18+. The packaged runner uses local Ollama with `gemma4:e4b-it-q4_K_M` as the zero-config classifier model. Pluggable via `open-classify.config.json` or a custom `RunClassifier`.
+
+**1. Install**
 
 ```sh
 npm install open-classify
 ```
 
-Node 18+. The packaged runner is local Ollama and ships with `gemma4:e4b-it-q4_K_M` as the zero-config classifier model. That runner is configurable through `open-classify.config.json`; arbitrary backends are supported in code by implementing `RunClassifier`.
+**2. Scaffold**
+
+```sh
+npx open-classify init
+```
+
+This creates `open-classify.config.json` and a `classifiers/` directory in your project root. You'll see exactly what will be written and asked to confirm. Re-run safe: existing files are skipped.
 
-## Hello World
+**3. Use it**
 
 ```ts
 import { createClassifier } from "open-classify";
 
-const { classify, inspect } = createClassifier();
+const { classify } = createClassifier({
+  extraClassifierDirs: ["./classifiers"],
+});
 
 const result = await classify({
-  messages: [
-    { role: "user", text: "Can you review the attached contract?" },
-  ],
+  messages: [{ role: "user", text: "Can you review the attached contract?" }],
 });
 
-if (result.action === "block") {
-  // classification error or prompt injection — handle appropriately
-  console.error(result.block_reason, result.failed_classifiers);
-} else if (result.action === "reply") {
-  // preflight can answer this immediately — skip the downstream model
-  respondToUser(result.reply.text);
-} else {
-  // route to the downstream model
-  callDownstream(result.model_id, result.tools);
-  respondToUser(result.reply?.text); // show the ack while it works
-}
+if (result.action === "reply") respondToUser(result.reply.text);          // preflight answered it
+else if (result.action === "block") handleBlock(result.block_reason);     // injection or error
+else callDownstream(result.model_id, result.tools, result.reply?.text);   // route the real request
+```
 
-const queries = result.classifier_outputs.memory_retrieval_queries?.queries;
+**4. Activate or customize a classifier**
+
+Inside `classifiers/` you'll find four `_<name>/` directories — templates copied from the package, inactive because of the underscore prefix. To turn one on, drop the underscore:
+
+```sh
+mv classifiers/_tools classifiers/tools
 ```
 
-`createClassifier` builds the runner and loads the model catalog once. Reuse the returned `classify` and `inspect` functions across your app — every call is a plain function invocation, no re-initialization.
+Edit `manifest.json` first if you need to (e.g. trim `allowed_tools` for your app). The same underscore convention works the other way too: rename `my_classifier/` → `_my_classifier/` to take any classifier out of the active set without deleting it.
+
+To write a new classifier from scratch, drop a `<name>/manifest.json` + `<name>/prompt.md` in `classifiers/`. See [docs/adding-a-classifier.md](docs/adding-a-classifier.md).
 
 ### Classifying assistant output
 
@@ -140,26 +150,36 @@ Example result:
 
 ## Classifier model
 
-Open Classify ships with eight built-in classifiers; all use the same manifest shape. There is no distinction between "stock" and "custom" — the runtime only cares about which **reserved fields** a classifier declares.
+Every classifier — bundled or your own — uses the same two-file shape (`manifest.json` + `prompt.md`) and emits the same envelope: `{ reason, certainty, ...payload }`. Some payload fields are **reserved** (like `model_tier`, `final_reply`, `risk_level`); the aggregator knows how to consume them into the routing decision. Everything else passes through to the caller.
+
+Open Classify ships eight built-in classifiers. **Four are mandatory** — they always load, they can't be turned off, and extras can't override them. The other four ship as **templates** that `init` copies into your project as inactive (`_<name>/`); rename to activate.
 
-| Name | dispatch_order | Reserved fields | What the aggregator does with it |
-|---|---|---|---|
-| `preflight` | 10 | `final_reply`, `ack_reply` | Sets `action: "reply"` or populates `result.reply` |
-| `model_tier` | 20 | `model_tier` | Feeds the catalog resolver as a soft constraint |
-| `model_specialization` | 30 | `model_specialization` | Feeds the catalog resolver as a soft constraint |
-| `tools` | 40 | `tools` | Sets `result.tools` |
-| `prompt_injection` | 50 | `risk_level` | High-risk/unknown → `action: "block"`; suspicious → advisory |
-| `memory_retrieval_queries` | 60 | — | Passes through to `classifier_outputs` |
-| `conversation_digest` | 70 | — | Passes through |
-| `context_shift` | 80 | — | Passes through |
+| Name | dispatch_order | Reserved fields | Bundled as | What the aggregator does with it |
+|---|---|---|---|---|
+| `preflight` | 10 | `final_reply`, `ack_reply` | mandatory | Sets `action: "reply"` or populates `result.reply` |
+| `model_tier` | 20 | `model_tier` | mandatory | Feeds the catalog resolver as a soft constraint |
+| `model_specialization` | 30 | `model_specialization` | mandatory | Feeds the catalog resolver as a soft constraint |
+| `prompt_injection` | 50 | `risk_level` | mandatory | High-risk/unknown → `action: "block"`; suspicious → advisory |
+| `tools` | 40 | `tools` | template | Sets `result.tools` |
+| `memory_retrieval_queries` | 60 | — | template | Passes through to `classifier_outputs` |
+| `conversation_digest` | 70 | — | template | Passes through |
+| `context_shift` | 80 | — | template | Passes through |
 
-Reserved fields are well-known output keys with canonical JSON Schemas and prompt fragments baked into the runtime. When you declare one in your manifest, you don't have to redeclare its enum values or shape — the runtime injects them.
+The directory-naming convention (`_<name>/` = inactive) is the only on/off mechanism, and it applies equally to bundled templates and your own classifiers. No `disabled` config, no allow-lists, no flags. If a folder is in `classifiers/` without a leading underscore, it runs.
 
-## Adding a classifier
+> Need to customize `preflight`'s prompt or any other mandatory built-in? Use a custom `RunClassifier` (see [Bring your own backend](#bring-your-own-backend)) to intercept it, or fork the package.
 
-Every classifier is two files in `src/classifiers/<name>/`:
+## Adding your own classifier
 
-`manifest.json` describes the output shape and a fallback for when the classifier errors:
+The two files are:
+
+```
+classifiers/topic_tags/
+├── manifest.json
+└── prompt.md
+```
+
+`manifest.json` declares the output shape and a fallback for when the classifier errors:
 
 ```json
 {
@@ -184,31 +204,22 @@ Every classifier is two files in `src/classifiers/<name>/`:
 }
 ```
 
-`prompt.md` describes the classification rule in plain language. You don't need to write JSON examples — the runtime synthesizes one from your schema and shows it to the model — and you don't paste enum values for reserved fields. Just describe what each output key means and when to abstain:
+`prompt.md` is the classification rule in plain language. No need to write JSON examples — the runtime synthesizes one from your schema — and no need to paste enum values for reserved fields:
 
 ```markdown
 You are the topic_tags classifier.
 
 `tags` are short single-word topic labels (lowercase, no spaces). Use at most five.
 Return an empty array when no clear topic applies.
-Do not invent tags for vague or ambiguous messages.
 ```
 
-Rules:
-
-- `name` must match the directory name.
-- Reserved field names cannot appear in `output_schema.properties` — declare them in `reserved_fields` instead.
-- `fallback` requires only `reason` and `certainty`; reserved and custom required fields are exempt from the fallback check.
-- If you want hand-picked examples (preflight does this), add an `output_schema.examples` array. Each entry must validate against the composed schema at load time. Otherwise the runtime synthesizes a skeleton example for you.
-
-Consume your output:
+Consume:
 
 ```ts
-const result = await classify(input);
 const tags = result.classifier_outputs.topic_tags?.tags ?? [];
 ```
 
-See [docs/adding-a-classifier.md](docs/adding-a-classifier.md) for a full walkthrough and [docs/manifests.md](docs/manifests.md) for the field reference.
+Rules: `name` must match the directory name; reserved-field names can't appear in `output_schema.properties` (declare them under `reserved_fields` instead); `fallback` only needs `reason` and `certainty`; name collisions throw at startup. See [docs/adding-a-classifier.md](docs/adding-a-classifier.md) for the full reference.
 
 ## Using reserved fields in your own classifier
 

package/bin/open-classify.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// open-classify CLI. Currently exposes a single subcommand: `init`.
+//
+// `init` scaffolds the standard project layout for a consumer:
+//   - open-classify.config.json (minimal)
+//   - classifiers/
+//     - README.md
+//     - _conversation_digest/  (templates, prefix means inactive)
+//     - _context_shift/
+//     - _memory_retrieval_queries/
+//     - _tools/
+//
+// Re-run safe: existing files are skipped, never overwritten. Use
+// `--yes` to skip the confirmation prompt (for scripted setup).
+
+import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(SCRIPT_DIR, "..");
+const TEMPLATES_DIR = join(PACKAGE_ROOT, "templates");
+
+const TEMPLATE_NAMES = ["conversation_digest", "context_shift", "memory_retrieval_queries", "tools"];
+
+const CLASSIFIERS_README = `# classifiers/
+
+Drop a folder here per classifier. Each folder needs:
+
+- \`manifest.json\` — see [open-classify docs](https://github.com/taylorbayouth/open-classify/blob/main/docs/adding-a-classifier.md)
+- \`prompt.md\` — the classifier-specific instructions
+
+## Activating templates
+
+The four \`_<name>/\` directories below are templates copied from the package — they ship inactive (the loader skips any folder starting with \`_\`). Activate one by dropping the underscore:
+
+\`\`\`sh
+mv _tools tools
+\`\`\`
+
+You probably also want to edit its \`manifest.json\` first to fit your app (e.g. trim the \`allowed_tools\` list).
+
+## Deactivating without deleting
+
+Same trick in reverse — rename \`my_classifier\` → \`_my_classifier\` to take it out of the active set without losing your work.
+`;
+
+const DEFAULT_CONFIG = {
+  runner: {
+    provider: "ollama",
+    host: "http://127.0.0.1:11434",
+    defaultModel: "gemma4:e4b-it-q4_K_M",
+  },
+  catalog: "downstream-models.json",
+};
+
+async function main() {
+  const args = process.argv.slice(2);
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === "-h" || subcommand === "--help") {
+    printHelp();
+    process.exit(subcommand ? 0 : 1);
+  }
+
+  if (subcommand === "init") {
+    const yes = args.includes("--yes") || args.includes("-y");
+    await runInit({ cwd: process.cwd(), yes });
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printHelp();
+  process.exit(1);
+}
+
+function printHelp() {
+  process.stdout.write(`open-classify — runtime CLI
+
+Commands:
+  init [--yes]    Scaffold open-classify.config.json and classifiers/ in the
+                  current directory. Re-run safe: existing files are skipped.
+
+`);
+}
+
+async function runInit({ cwd, yes }) {
+  const plan = planInit(cwd);
+
+  if (plan.toCreate.length === 0) {
+    console.log("Nothing to do — your project already has all the scaffolded files.");
+    if (plan.toSkip.length > 0) {
+      console.log("\nAlready in place:");
+      for (const p of plan.toSkip) console.log(`  ${p}`);
+    }
+    return;
+  }
+
+  console.log("This will create:");
+  for (const p of plan.toCreate) console.log(`  ${p}`);
+  if (plan.toSkip.length > 0) {
+    console.log("\nAlready exists (will skip):");
+    for (const p of plan.toSkip) console.log(`  ${p}`);
+  }
+
+  if (!yes) {
+    const proceed = await confirm("\nContinue? [Y/n] ");
+    if (!proceed) {
+      console.log("Aborted.");
+      process.exit(1);
+    }
+  }
+
+  for (const action of plan.actions) {
+    action();
+  }
+
+  console.log("\nDone. Wire it into your code:\n");
+  console.log("  import { createClassifier } from \"open-classify\";");
+  console.log("  const { classify } = createClassifier({");
+  console.log("    extraClassifierDirs: [\"./classifiers\"],");
+  console.log("  });");
+}
+
+function planInit(cwd) {
+  const toCreate = [];
+  const toSkip = [];
+  const actions = [];
+
+  const configPath = join(cwd, "open-classify.config.json");
+  if (existsSync(configPath)) {
+    toSkip.push(relative(cwd, configPath));
+  } else {
+    toCreate.push(relative(cwd, configPath));
+    actions.push(() => {
+      writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+      console.log(`wrote ${relative(cwd, configPath)}`);
+    });
+  }
+
+  const classifiersDir = join(cwd, "classifiers");
+  if (!existsSync(classifiersDir)) {
+    toCreate.push(relative(cwd, classifiersDir) + "/");
+    actions.push(() => {
+      mkdirSync(classifiersDir, { recursive: true });
+      console.log(`created ${relative(cwd, classifiersDir)}/`);
+    });
+  }
+
+  const readmePath = join(classifiersDir, "README.md");
+  if (existsSync(readmePath)) {
+    toSkip.push(relative(cwd, readmePath));
+  } else {
+    toCreate.push(relative(cwd, readmePath));
+    actions.push(() => {
+      // The classifiers dir may not yet exist when we generated the plan,
+      // but it will by the time this action runs.
+      mkdirSync(classifiersDir, { recursive: true });
+      writeFileSync(readmePath, CLASSIFIERS_README);
+      console.log(`wrote ${relative(cwd, readmePath)}`);
+    });
+  }
+
+  for (const name of TEMPLATE_NAMES) {
+    const inactivePath = join(classifiersDir, `_${name}`);
+    const activePath = join(classifiersDir, name);
+
+    if (existsSync(inactivePath) || existsSync(activePath)) {
+      // Either already scaffolded (inactive) or already activated by the
+      // consumer. Either way, leave it alone.
+      toSkip.push(relative(cwd, existsSync(activePath) ? activePath : inactivePath) + "/");
+      continue;
+    }
+
+    toCreate.push(relative(cwd, inactivePath) + "/");
+    actions.push(() => {
+      mkdirSync(classifiersDir, { recursive: true });
+      cpSync(join(TEMPLATES_DIR, name), inactivePath, { recursive: true });
+      console.log(`wrote ${relative(cwd, inactivePath)}/`);
+    });
+  }
+
+  return { toCreate, toSkip, actions };
+}
+
+function confirm(prompt) {
+  return new Promise((resolveAnswer) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const normalized = (answer || "").trim().toLowerCase();
+      resolveAnswer(normalized === "" || normalized === "y" || normalized === "yes");
+    });
+  });
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/dist/src/classifiers.d.ts

@@ -1,14 +1,21 @@
 import type { ClassifierInput } from "./types.js";
 import type { ClassifierName, ClassifierRegistry, RunClassifier } from "./manifest.js";
 import type { ClassifierOutput, RuntimeClassifierManifest } from "./stock.js";
+export declare const BUILTIN_CLASSIFIERS_DIR: string;
 export declare class ClassifierManifestError extends Error {
     constructor(message: string);
 }
+export type ClassifierModuleMap = Readonly<Record<string, RuntimeClassifierManifest>>;
+export interface ClassifierRegistryBundle {
+    readonly registry: ClassifierRegistry;
+    readonly modulesByName: ClassifierModuleMap;
+    readonly names: ReadonlyArray<string>;
+}
+export interface BuildRegistryOptions {
+    readonly extraDirs?: ReadonlyArray<string>;
+}
 export declare function loadClassifierRegistry(classifiersDir?: string): RuntimeClassifierManifest[];
-export declare const REGISTRY: ClassifierRegistry;
-export declare const CLASSIFIER_NAMES: string[];
-export declare const MODULES_BY_NAME: Record<string, RuntimeClassifierManifest>;
+export declare function buildClassifierRegistry(options?: BuildRegistryOptions): ClassifierRegistryBundle;
+export declare function validateClassifierOutput(manifest: RuntimeClassifierManifest, value: unknown, model: string): ClassifierOutput;
 export type { ClassifierName, RunClassifier };
-export type RegistryType = typeof REGISTRY;
-export declare function validateClassifierOutput(name: string, value: unknown, model: string): ClassifierOutput;
 export type { ClassifierInput };

package/dist/src/classifiers.js

@@ -4,9 +4,11 @@ import { fileURLToPath } from "node:url";
 import { buildClassifierPrompt } from "./stock-prompt.js";
 import { validateJsonClassifierManifest, validateOutputForManifest, } from "./stock-validation.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const CLASSIFIERS_DIR = join(__dirname, "classifiers");
+export const BUILTIN_CLASSIFIERS_DIR = join(__dirname, "classifiers");
 // Directories whose names start with "_" are reserved for shared assets
-// (e.g. `_prompts/`) and are not loaded as classifiers.
+// (e.g. `_prompts/`) and are not loaded as classifiers. Consumers can use
+// the same convention in their own classifier directories: rename a
+// classifier to `_<name>/` to deactivate it without deleting it.
 const SHARED_DIRECTORY_PREFIX = "_";
 export class ClassifierManifestError extends Error {
     constructor(message) {
@@ -14,7 +16,10 @@ export class ClassifierManifestError extends Error {
         this.name = "ClassifierManifestError";
     }
 }
-export function loadClassifierRegistry(classifiersDir = CLASSIFIERS_DIR) {
+// Load all classifier manifests under a single directory. Used internally to
+// load the built-ins and each extra directory; callers wanting the merged
+// registry should use `buildClassifierRegistry()` instead.
+export function loadClassifierRegistry(classifiersDir = BUILTIN_CLASSIFIERS_DIR) {
     if (!existsSync(classifiersDir)) {
         throw new ClassifierManifestError(`classifier directory not found: ${classifiersDir}`);
     }
@@ -26,11 +31,29 @@ export function loadClassifierRegistry(classifiersDir = CLASSIFIERS_DIR) {
             continue;
         manifests.push(loadClassifierManifest(join(classifiersDir, entry.name)));
     }
-    // Lower dispatch_order runs first. Classifiers without dispatch_order sort
-    // last (treated as +Infinity) — useful for "run me whenever there's a slot".
+    return manifests;
+}
+// Build a complete classifier registry from the bundled built-ins plus any
+// extra directories supplied by the caller. Sorts by dispatch_order
+// ascending (manifests without dispatch_order sort last). Rejects duplicate
+// names.
+//
+// Mandatory built-ins (preflight, model_tier, model_specialization,
+// prompt_injection) always load. Extras with the same name as a built-in
+// throw — there's no override mechanism. Customise by editing the bundled
+// manifest in your own fork, or replace behaviour entirely with a custom
+// `runClassifier`.
+export function buildClassifierRegistry(options = {}) {
+    const manifests = [
+        ...loadClassifierRegistry(BUILTIN_CLASSIFIERS_DIR),
+        ...(options.extraDirs ?? []).flatMap((dir) => loadClassifierRegistry(dir)),
+    ];
     manifests.sort((a, b) => (a.dispatch_order ?? Infinity) - (b.dispatch_order ?? Infinity));
     validateRegistry(manifests);
-    return manifests;
+    const registry = manifests;
+    const modulesByName = Object.fromEntries(manifests.map((m) => [m.name, m]));
+    const names = manifests.map((m) => m.name);
+    return { registry, modulesByName, names };
 }
 function loadClassifierManifest(classifierDir) {
     const manifestPath = join(classifierDir, "manifest.json");
@@ -69,18 +92,11 @@ function validateRegistry(manifests) {
     const names = new Set();
     for (const manifest of manifests) {
         if (names.has(manifest.name)) {
-            throw new ClassifierManifestError(`duplicate classifier name: ${manifest.name}`);
+            throw new ClassifierManifestError(`duplicate classifier name: ${manifest.name} — extras cannot override built-ins or other extras. Rename your classifier or run it under a different name.`);
         }
         names.add(manifest.name);
     }
 }
-export const REGISTRY = loadClassifierRegistry();
-export const CLASSIFIER_NAMES = REGISTRY.map((m) => m.name);
-export const MODULES_BY_NAME = Object.fromEntries(REGISTRY.map((m) => [m.name, m]));
-export function validateClassifierOutput(name, value, model) {
-    const manifest = MODULES_BY_NAME[name];
-    if (!manifest) {
-        throw new ClassifierManifestError(`unknown classifier: ${name}`);
-    }
-    return validateOutputForManifest(manifest, value, { classifier: name, model });
+export function validateClassifierOutput(manifest, value, model) {
+    return validateOutputForManifest(manifest, value, { classifier: manifest.name, model });
 }

package/dist/src/classify.d.ts

@@ -1,4 +1,4 @@
-import { type RunClassifier } from "./classifiers.js";
+import { ClassifierManifestError, type ClassifierRegistryBundle, type RunClassifier } from "./classifiers.js";
 import { type OpenClassifyConfig } from "./config.js";
 import type { Catalog, InspectResult, PipelineResult } from "./manifest.js";
 import type { OpenClassifyInput } from "./types.js";
@@ -11,10 +11,12 @@ export type Inspector = (input: OpenClassifyInput, options?: {
 export interface OpenClassify {
     readonly classify: Classifier;
     readonly inspect: Inspector;
+    readonly registry: ClassifierRegistryBundle;
 }
 export interface CreateClassifierOptions {
     runClassifier?: RunClassifier;
     catalog?: Catalog;
+    extraClassifierDirs?: ReadonlyArray<string>;
     config?: OpenClassifyConfig;
     configPath?: string;
     catalogPath?: string;
@@ -27,3 +29,4 @@ export interface CreateClassifierOptions {
     maxConcurrency?: number;
 }
 export declare function createClassifier(options?: CreateClassifierOptions): OpenClassify;
+export { ClassifierManifestError };

package/dist/src/classify.js

@@ -1,9 +1,11 @@
-// High-level facade for the pipeline. Builds the runner and catalog once,
-// then returns two functions — classify() for the user-input/routing pass
-// and inspect() for the assistant-output lean pass. Backend-agnostic: pass a
-// custom `runClassifier` to bypass the bundled Ollama runner entirely.
+// High-level facade for the pipeline. Builds the runner, registry, and
+// catalog once, then returns two functions — classify() for the
+// user-input/routing pass and inspect() for the assistant-output lean pass.
+// 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 { buildClassifierRegistry, ClassifierManifestError, } from "./classifiers.js";
+import { classifierModelsFromConfig, loadOpenClassifyConfig, OpenClassifyConfigError, } from "./config.js";
 import { assertOllamaResources, createOllamaClassifierRunner, OLLAMA_DEFAULT_CATALOG_PATH, } from "./ollama.js";
 import { classifyOpenClassifyInput, inspectOpenClassifyInput, } from "./pipeline.js";
 export function createClassifier(options = {}) {
@@ -12,6 +14,20 @@ export function createClassifier(options = {}) {
             optional: options.configPath === undefined &&
                 process.env.OPEN_CLASSIFY_CONFIG === undefined,
         });
+    const registryBundle = buildClassifierRegistry({
+        extraDirs: options.extraClassifierDirs,
+    });
+    // Cross-check `runner.models` keys against the loaded registry so a typo
+    // or stale reference fails fast at construction time instead of being
+    // silently ignored by the runner.
+    if (fileConfig?.runner?.models !== undefined) {
+        const known = new Set(registryBundle.names);
+        for (const name of Object.keys(fileConfig.runner.models)) {
+            if (!known.has(name)) {
+                throw new OpenClassifyConfigError(`runner.models.${name} is not a loaded classifier (loaded: ${registryBundle.names.join(", ")})`);
+            }
+        }
+    }
     // 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.
@@ -19,6 +35,7 @@ export function createClassifier(options = {}) {
     const needsResourceCheck = ownsRunner && !options.skipResourceCheck;
     const runClassifier = options.runClassifier ??
         createOllamaClassifierRunner({
+            modulesByName: registryBundle.modulesByName,
             host: fileConfig?.runner?.host,
             defaultModel: fileConfig?.runner?.defaultModel,
             models: classifierModelsFromConfig(fileConfig),
@@ -43,6 +60,7 @@ export function createClassifier(options = {}) {
         return classifyOpenClassifyInput(input, {
             runClassifier,
             catalog,
+            registry: registryBundle.registry,
             classifierTimeoutMs: options.classifierTimeoutMs,
             classifierRetryCount: options.classifierRetryCount,
             maxConcurrency: options.maxConcurrency,
@@ -53,11 +71,15 @@ export function createClassifier(options = {}) {
         await ensureResources();
         return inspectOpenClassifyInput(input, {
             runClassifier,
+            registry: registryBundle.registry,
             classifierTimeoutMs: options.classifierTimeoutMs,
             classifierRetryCount: options.classifierRetryCount,
             maxConcurrency: options.maxConcurrency,
             signal: callOptions?.signal,
         });
     };
-    return { classify, inspect };
+    return { classify, inspect, registry: registryBundle };
 }
+// Re-export so callers can `import { ClassifierManifestError } from "open-classify"`
+// and catch directory/name collision errors from createClassifier().
+export { ClassifierManifestError };

package/dist/src/config.d.ts

@@ -1,4 +1,4 @@
-import { type ClassifierName } from "./classifiers.js";
+import type { ClassifierName } from "./classifiers.js";
 export declare const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify.config.json";
 export interface OpenClassifyConfig {
     readonly runner?: OllamaRunnerConfig;

package/dist/src/config.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from "node:fs";
-import { CLASSIFIER_NAMES } from "./classifiers.js";
 import { isRecord } from "./validation.js";
 export const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify.config.json";
 export class OpenClassifyConfigError extends Error {
@@ -81,12 +80,8 @@ function validateModels(value, path) {
     if (!isRecord(value)) {
         throwConfig(path, "runner.models must be an object");
     }
-    const allowed = new Set(CLASSIFIER_NAMES);
     const out = {};
     for (const [name, model] of Object.entries(value)) {
-        if (!allowed.has(name)) {
-            throwConfig(path, `runner.models.${name} is not a known classifier`);
-        }
         out[name] = requireString(model, path, `runner.models.${name}`);
     }
     return out;

package/dist/src/ollama.d.ts

@@ -1,13 +1,11 @@
-import { type ClassifierName, type RunClassifier } from "./classifiers.js";
+import { type ClassifierModuleMap, type ClassifierName, type RunClassifier } from "./classifiers.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;
-export declare const OLLAMA_REQUIRED_PARALLELISM: number;
 export declare const OLLAMA_DEFAULT_CATALOG_PATH = "downstream-models.json";
 export declare const OLLAMA_CONTEXT_LENGTH = 4096;
 export declare const OLLAMA_MIN_TOTAL_MEMORY_BYTES: number;
 export declare const OLLAMA_MIN_AVAILABLE_MEMORY_BYTES: number;
-export declare const OLLAMA_CLASSIFIER_MODELS: Record<ClassifierName, string | null>;
 export interface OllamaOptions {
     temperature?: number;
     top_p?: number;
@@ -15,14 +13,15 @@ export interface OllamaOptions {
     num_ctx?: number;
 }
 export interface OllamaClassifierRunnerConfig {
+    modulesByName: ClassifierModuleMap;
+    minTotalMemoryBytes?: number;
+    minAvailableMemoryBytes?: number;
     host?: string;
     defaultModel?: string;
     models?: Partial<Record<ClassifierName, string | null>>;
     options?: OllamaOptions;
     fetch?: typeof fetch;
     skipResourceCheck?: boolean;
-    minAvailableMemoryBytes?: number;
-    minTotalMemoryBytes?: number;
 }
 export declare class OllamaClassifierError extends Error {
     readonly classifier: ClassifierName;
@@ -36,7 +35,7 @@ export declare class OllamaResourceError extends Error {
     readonly minAvailableMemoryBytes: number;
     constructor(totalMemoryBytes: number, availableMemoryBytes: number, minTotalMemoryBytes: number, minAvailableMemoryBytes: number);
 }
-export declare function createOllamaClassifierRunner(config?: OllamaClassifierRunnerConfig): RunClassifier;
+export declare function createOllamaClassifierRunner(config: OllamaClassifierRunnerConfig): RunClassifier;
 export declare function assertOllamaResources(options?: {
     minTotalMemoryBytes?: number;
     minAvailableMemoryBytes?: number;

package/dist/src/ollama.js

@@ -10,12 +10,11 @@
 // `classifyOpenClassifyInput` — you don't have to use this module at all.
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { CLASSIFIER_NAMES, MODULES_BY_NAME, validateClassifierOutput, } from "./classifiers.js";
+import { validateClassifierOutput, } from "./classifiers.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";
 export const OLLAMA_BASE_MODEL_NATIVE_CONTEXT_LENGTH = 131_072;
-export const OLLAMA_REQUIRED_PARALLELISM = CLASSIFIER_NAMES.length;
 export const OLLAMA_DEFAULT_CATALOG_PATH = "downstream-models.json";
 /*
  * Gemma 4 E4B's native context is 131,072 tokens (128K). The reference local
@@ -28,7 +27,6 @@ export const OLLAMA_MIN_TOTAL_MEMORY_BYTES = 16 * 1024 * 1024 * 1024;
 export const OLLAMA_MIN_AVAILABLE_MEMORY_BYTES = 16 * 1024 * 1024 * 1024;
 const ESTIMATED_CHARS_PER_TOKEN = 3;
 const execFileAsync = promisify(execFile);
-export const OLLAMA_CLASSIFIER_MODELS = Object.fromEntries(CLASSIFIER_NAMES.map((name) => [name, null]));
 export class OllamaClassifierError extends Error {
     classifier;
     model;
@@ -45,7 +43,7 @@ export class OllamaResourceError extends Error {
     minTotalMemoryBytes;
     minAvailableMemoryBytes;
     constructor(totalMemoryBytes, availableMemoryBytes, minTotalMemoryBytes, minAvailableMemoryBytes) {
-        super(`Ollama resource check failed: ${formatBytes(totalMemoryBytes)} total and ${formatBytes(availableMemoryBytes)} available; ${formatBytes(minTotalMemoryBytes)} total and ${formatBytes(minAvailableMemoryBytes)} available required for ${OLLAMA_REQUIRED_PARALLELISM} parallel classifiers`);
+        super(`Ollama resource check failed: ${formatBytes(totalMemoryBytes)} total and ${formatBytes(availableMemoryBytes)} available; ${formatBytes(minTotalMemoryBytes)} total and ${formatBytes(minAvailableMemoryBytes)} available required to run classifiers in parallel`);
         this.name = "OllamaResourceError";
         this.totalMemoryBytes = totalMemoryBytes;
         this.availableMemoryBytes = availableMemoryBytes;
@@ -56,7 +54,11 @@ export class OllamaResourceError extends Error {
 // Build a `RunClassifier` bound to a specific Ollama host + model selection.
 // The resource check is lazy and runs once per runner — the first classifier
 // invocation pays for it; subsequent ones reuse the same promise.
-export function createOllamaClassifierRunner(config = {}) {
+export function createOllamaClassifierRunner(config) {
+    if (!config?.modulesByName) {
+        throw new Error("createOllamaClassifierRunner requires `modulesByName` from buildClassifierRegistry()");
+    }
+    const modulesByName = config.modulesByName;
     const host = trimTrailingSlash(config.host ?? OLLAMA_DEFAULT_HOST);
     const fetchImpl = config.fetch ?? fetch;
     const models = config.models ?? {};
@@ -76,9 +78,13 @@ export function createOllamaClassifierRunner(config = {}) {
             });
             await resourceCheck;
         }
+        const manifest = modulesByName[name];
+        if (manifest === undefined) {
+            throw new OllamaClassifierError(name, defaultModel, `unknown classifier "${name}" — not present in registry`);
+        }
         const configuredModel = models[name];
         const model = configuredModel ?? defaultModel;
-        return runOllamaClassifier(name, input, signal, fetchImpl, host, model, options, configuredModel === undefined && !hasDefaultModelOverride);
+        return runOllamaClassifier(manifest, input, signal, fetchImpl, host, model, options, configuredModel === undefined && !hasDefaultModelOverride);
     };
 }
 export async function assertOllamaResources(options = {}) {
@@ -90,10 +96,10 @@ export async function assertOllamaResources(options = {}) {
         throw new OllamaResourceError(totalMemoryBytes, availableMemoryBytes, minTotalMemoryBytes, minAvailableMemoryBytes);
     }
 }
-async function runOllamaClassifier(name, input, signal, fetchImpl, host, model, options, allowManifestModel) {
-    const module_ = MODULES_BY_NAME[name];
-    const systemPrompt = module_.systemPrompt;
-    const configuredBaseModel = module_.backend?.ollama?.base_model;
+async function runOllamaClassifier(manifest, input, signal, fetchImpl, host, model, options, allowManifestModel) {
+    const name = manifest.name;
+    const systemPrompt = manifest.systemPrompt;
+    const configuredBaseModel = manifest.backend?.ollama?.base_model;
     if (allowManifestModel && configuredBaseModel) {
         model = configuredBaseModel;
     }
@@ -137,7 +143,7 @@ async function runOllamaClassifier(name, input, signal, fetchImpl, host, model,
     }
     const parsed = parseJsonObject(content, name, model);
     try {
-        return validateClassifierOutput(name, parsed, model);
+        return validateClassifierOutput(manifest, parsed, model);
     }
     catch (error) {
         if (error instanceof ClassifierValidationError) {

package/dist/src/pipeline.d.ts

@@ -1,5 +1,5 @@
 import { type RunClassifier } from "./classifiers.js";
-import type { Catalog, InspectResult, PipelineResult } from "./manifest.js";
+import type { Catalog, ClassifierRegistry, InspectResult, PipelineResult } from "./manifest.js";
 import type { OpenClassifyInput } from "./types.js";
 export declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 15000;
 export declare const DEFAULT_CLASSIFIER_RETRY_COUNT = 1;
@@ -10,6 +10,7 @@ export declare class OpenClassifyNormalizationError extends Error {
 export interface ClassifyOptions {
     runClassifier: RunClassifier;
     catalog: Catalog;
+    registry: ClassifierRegistry;
     classifierTimeoutMs?: number;
     classifierRetryCount?: number;
     maxConcurrency?: number;
@@ -17,6 +18,7 @@ export interface ClassifyOptions {
 }
 export interface InspectOptions {
     runClassifier: RunClassifier;
+    registry: ClassifierRegistry;
     classifierTimeoutMs?: number;
     classifierRetryCount?: number;
     maxConcurrency?: number;

package/dist/src/pipeline.js

@@ -1,5 +1,4 @@
 import { assembleResult, buildPublicOutputs } from "./aggregator.js";
-import { MODULES_BY_NAME, REGISTRY, } from "./classifiers.js";
 import { normalizeOpenClassifyInput, toClassifierInput } from "./input.js";
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 15_000;
 export const DEFAULT_CLASSIFIER_RETRY_COUNT = 1;
@@ -12,7 +11,7 @@ export class OpenClassifyNormalizationError extends Error {
 }
 export async function classifyOpenClassifyInput(input, options) {
     const { request, results, failedClassifiers } = await runPipeline(input, "user", options);
-    const reg = filteredRegistry("user");
+    const reg = filteredRegistry(options.registry, "user");
     const assembled = assembleResult({
         registry: reg,
         results,
@@ -26,7 +25,7 @@ export async function classifyOpenClassifyInput(input, options) {
 }
 export async function inspectOpenClassifyInput(input, options) {
     const { request, results } = await runPipeline(input, "assistant", options);
-    const reg = filteredRegistry("assistant");
+    const reg = filteredRegistry(options.registry, "assistant");
     const lastMsg = request.messages[request.messages.length - 1];
     return {
         target_message_hash: request.target_message_hash,
@@ -56,19 +55,19 @@ async function runPipeline(input, role, options) {
     const classifierTimeoutMs = options.classifierTimeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS;
     const classifierRetryCount = options.classifierRetryCount ?? DEFAULT_CLASSIFIER_RETRY_COUNT;
     const maxConcurrency = resolveMaxConcurrency(options.maxConcurrency);
-    const registry = filteredRegistry(role);
+    const registry = filteredRegistry(options.registry, role);
     const queue = registry.map((m) => m.name);
     try {
         const settled = await runWithConcurrency(queue, maxConcurrency, controller.signal, (name) => runClassifierWithRetry(name, classifierInput, options.runClassifier, controller.signal, classifierTimeoutMs, classifierRetryCount));
-        const { results, failedClassifiers } = collectResults(settled);
+        const { results, failedClassifiers } = collectResults(registry, settled);
         return { request, results, failedClassifiers };
     }
     finally {
         options.signal?.removeEventListener("abort", abortFromOptions);
     }
 }
-function filteredRegistry(role) {
-    return REGISTRY.filter((m) => roleAppliesTo(m.appliesTo, role));
+function filteredRegistry(registry, role) {
+    return registry.filter((m) => roleAppliesTo(m.appliesTo, role));
 }
 function roleAppliesTo(appliesTo, role) {
     return appliesTo === "both" || appliesTo === role;
@@ -107,12 +106,18 @@ async function runWithConcurrency(names, maxConcurrency, signal, start) {
     await Promise.all(Array.from({ length: workerCount }, () => worker()));
     return results;
 }
-function collectResults(settled) {
+function collectResults(registry, settled) {
+    const fallbackByName = new Map();
+    for (const m of registry)
+        fallbackByName.set(m.name, m.fallback);
     const results = {};
     const failedClassifiers = [];
     for (const s of settled) {
-        const manifest = MODULES_BY_NAME[s.name];
-        results[s.name] = s.ok ? s.value : manifest.fallback;
+        const fallback = fallbackByName.get(s.name);
+        if (fallback === undefined) {
+            throw new Error(`pipeline: classifier "${s.name}" missing from registry`);
+        }
+        results[s.name] = s.ok ? s.value : fallback;
         if (!s.ok)
             failedClassifiers.push(s.name);
     }

package/docs/adding-a-classifier.md

@@ -1,20 +1,27 @@
 # Adding a classifier
 
-Every classifier — reserved-field-bearing or pure custom — uses the same two-file layout. There is no separate "stock" vs "custom" distinction; the runtime only cares about which reserved fields a classifier opts into.
+Every classifier — bundled or your own — uses the same two-file layout. There is no separate "stock" vs "custom" distinction; the runtime only cares about which reserved fields a classifier opts into.
+
+There are two places a classifier can live:
+
+- **In your own app**, in a directory you pass to `extraClassifierDirs` (almost always `./classifiers/` after `npx open-classify init`). This is the right path when you've installed Open Classify as a dependency.
+- **In this repo**, under `src/classifiers/<name>/`. Only do this when you're contributing a new mandatory built-in back to Open Classify.
+
+Either way, the layout and contract are identical.
 
 ## 1. Create the directory
 
 ```
-src/classifiers/<name>/
+classifiers/<name>/
 ├── manifest.json
 └── prompt.md
 ```
 
-The directory name must match `manifest.json`'s `name` field. Top-level directories starting with `_` (like `_prompts/`) are reserved for shared assets and skipped by the loader.
+The directory name must match `manifest.json`'s `name` field. Directories starting with `_` are skipped by the loader — that's the deactivation mechanism (`_topic_tags/` is inert; rename to `topic_tags/` to activate).
 
 ## 2. Write the manifest
 
-Minimal example — a pure-custom classifier that emits tags. You don't need to provide JSON examples; the runtime synthesizes one from your schema and shows it to the model.
+Minimal example — a pure-custom classifier that emits tags. The runtime synthesizes a JSON example from your schema, so you don't need to write one.
 
 ```json
 {
@@ -39,8 +46,6 @@ Minimal example — a pure-custom classifier that emits tags. You don't need to
 }
 ```
 
-If your classifier's behavior is nuanced enough that hand-picked examples would help the model (preflight is one), add an `output_schema.examples` array. The runtime validates each example against the composed schema at load time, so a broken example fails the build.
-
 To also influence routing, opt into a reserved field:
 
 ```json
@@ -73,6 +78,7 @@ Rules:
 - `reason` and `certainty` are added to the composed schema by the runtime — don't declare them.
 - `fallback` must validate against the composed schema. Only `reason` and `certainty` are required in fallback; reserved fields and `output_schema.required` fields are exempt (a "no signal" fallback usually omits them).
 - `output_schema.examples` (JSON Schema standard) must validate against the composed schema at load time, so a broken example fails the build, not the model call.
+- **Name collisions throw.** Extras cannot override the mandatory built-ins (`preflight`, `model_tier`, `model_specialization`, `prompt_injection`). To customize one of those, use a custom `RunClassifier` to intercept it (see "Replacing the backend" below).
 
 See [manifests.md](manifests.md) for the full field list.
 
@@ -90,24 +96,37 @@ Do not invent tags for vague or ambiguous messages.
 
 Don't paste enum values for reserved fields — the runtime injects them with canonical wording so they never drift from `src/enums.ts`.
 
-## 4. Build and test
+## 4. Use it
 
-```sh
-npm run build   # validates the manifest, composes the schema, copies assets
-npm test
-```
+After `npx open-classify init`, your `classifiers/` directory already exists. Drop your folder in and point `createClassifier` at the parent dir:
 
-If the manifest is malformed, the loader throws `ClassifierManifestError` with the path and a specific reason.
+```ts
+import { createClassifier } from "open-classify";
 
-## 5. Consume the output
+const { classify } = createClassifier({
+  extraClassifierDirs: ["./classifiers"],
+});
+
+const result = await classify({
+  messages: [{ role: "user", text: "Can you review the attached contract?" }],
+});
 
-```ts
-const { classify } = createClassifier({ catalog });
-const result = await classify(input);
 const tags = result.classifier_outputs.topic_tags?.tags ?? [];
 ```
 
-`classifier_outputs[name]` includes all payload fields plus `reason` (string) and `certainty` (float).
+> Production tip: `"./classifiers"` resolves against `process.cwd()`, which is fine for `npm start` but breaks if the process launches from a different directory. For long-running services, resolve absolutely via `fileURLToPath(import.meta.url) + path.resolve(...)`.
+
+If the manifest is malformed, `createClassifier` throws `ClassifierManifestError` at startup with the path and a specific reason — typos fail loud.
+
+## Activating one of the bundled templates
+
+`npx open-classify init` copies four templates (`tools`, `memory_retrieval_queries`, `conversation_digest`, `context_shift`) into your `classifiers/` directory as `_<name>/` — inactive because of the underscore prefix. To turn one on:
+
+```sh
+mv classifiers/_tools classifiers/tools
+```
+
+Edit `manifest.json` first if you need to (`tools` in particular ships with an opinionated `allowed_tools` list you'll almost certainly want to tailor). The reverse works on any classifier: rename `<name>/` → `_<name>/` to deactivate without deleting.
 
 ## Targeting the assistant response
 
@@ -134,7 +153,7 @@ The built-in `prompt_injection` ships tagged `"both"` so it runs on both sides.
 
 ## Choosing the classifier model
 
-For apps and OSS installs, prefer `open-classify.config.json`:
+In `open-classify.config.json`:
 
 ```json
 {
@@ -148,9 +167,9 @@ For apps and OSS installs, prefer `open-classify.config.json`:
 }
 ```
 
-`runner.defaultModel` applies to every classifier without an override. `runner.models` is a flat map keyed by classifier name — there is no separate stock/custom split.
+`runner.defaultModel` applies to every classifier without an override. `runner.models` is a flat map keyed by classifier name — works for built-ins, templates, and your own.
 
-Classifier manifests may also carry an Ollama hint for packaged classifiers:
+Classifier manifests may also carry an Ollama hint:
 
 ```json
 {
@@ -162,15 +181,17 @@ Config file and function options take precedence over manifest hints.
 
 ## Replacing the backend
 
-For full backend control, implement your own `RunClassifier` and pass it to `classifyOpenClassifyInput`:
+For full backend control — including replacing a mandatory built-in like `preflight` — implement your own `RunClassifier` and pass it to `createClassifier`:
 
 ```ts
-import { classifyOpenClassifyInput, loadCatalog } from "open-classify";
+import { createClassifier, type RunClassifier } from "open-classify";
 
 const runClassifier: RunClassifier = async (name, input, signal) => {
-  // call OpenAI, Anthropic, a remote service, etc.
-  // return a ClassifierOutput matching the classifier's composed schema.
+  if (name === "preflight") {
+    // call OpenAI / Anthropic / your own logic; return a ClassifierOutput.
+  }
+  // …handle other classifiers, or delegate to the Ollama runner you imported.
 };
 
-await classifyOpenClassifyInput(input, { runClassifier, catalog: loadCatalog(...) });
+const { classify } = createClassifier({ runClassifier });
 ```

package/open-classify.config.example.json

@@ -13,9 +13,7 @@
       "preflight": "gemma4:e4b-it-q4_K_M",
       "model_tier": "gemma4:e4b-it-q4_K_M",
       "model_specialization": "gemma4:e4b-it-q4_K_M",
-      "tools": "gemma4:e4b-it-q4_K_M",
-      "prompt_injection": "gemma4:e4b-it-q4_K_M",
-      "memory_retrieval_queries": "gemma4:e4b-it-q4_K_M"
+      "prompt_injection": "gemma4:e4b-it-q4_K_M"
     }
   },
   "catalog": "downstream-models.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-classify",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Manifest-driven classifier runtime for routing user messages to downstream AI models",
   "license": "MIT",
   "author": "Taylor Bayouth",
@@ -29,11 +29,16 @@
       "default": "./dist/src/index.js"
     }
   },
+  "bin": {
+    "open-classify": "./bin/open-classify.mjs"
+  },
   "files": [
+    "bin",
     "dist/src",
     "docs",
     "downstream-models.json",
     "open-classify.config.example.json",
+    "templates",
     "LICENSE",
     "README.md"
   ],