open-classify 0.9.2 → 1.0.0

package/dist/src/classifiers.js

@@ -13,11 +13,11 @@ export const STOCK_CLASSIFIER_NAMES = [
 ];
 export const STOCK_CLASSIFIERS_DIR = findStockClassifiersDir();
 function findStockClassifiersDir() {
-    // Source runs use ../templates; built package runs use ../../templates from
-    // dist/src. Keep both so tests and the published package agree.
+    // Source runs use ../templates/stock; built package runs use ../../templates/stock
+    // from dist/src. Keep both so tests and the published package agree.
     const candidates = [
-        join(__dirname, "..", "templates"),
-        join(__dirname, "..", "..", "templates"),
+        join(__dirname, "..", "templates", "stock"),
+        join(__dirname, "..", "..", "templates", "stock"),
     ];
     return candidates.find((dir) => existsSync(dir)) ?? candidates[0];
 }
@@ -50,21 +50,28 @@ export function loadClassifierRegistry(classifiersDir = BUILTIN_CLASSIFIERS_DIR)
     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.
+// extras supplied by the caller. Sorted by dispatch_order ascending
+// (manifests without dispatch_order sort last).
 //
-// 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`.
+// Precedence rules:
+//   - Mandatory built-ins (preflight, model_tier, model_specialization,
+//     prompt_injection) always load. A user classifier with the same name
+//     as a built-in throws — to replace behaviour, use a custom RunClassifier.
+//   - User classifiers in `extraDirs` override stock classifiers of the
+//     same name. This is the "eject" pattern: `npx open-classify eject
+//     tools` copies the stock files into your project, and the runtime
+//     transparently switches to your copy.
+//   - Two user classifiers with the same name (across different extraDirs)
+//     throw — ambiguous ownership.
 export function buildClassifierRegistry(options = {}) {
-    const manifests = [
-        ...loadClassifierRegistry(BUILTIN_CLASSIFIERS_DIR),
-        ...(options.stockClassifierNames ?? []).map((name) => loadStockClassifier(name)),
-        ...(options.extraDirs ?? []).flatMap((dir) => loadClassifierRegistry(dir)),
-    ];
+    const builtIns = loadClassifierRegistry(BUILTIN_CLASSIFIERS_DIR);
+    const userClassifiers = (options.extraDirs ?? []).flatMap((dir) => loadClassifierRegistry(dir));
+    const userNames = new Set(userClassifiers.map((m) => m.name));
+    // Skip any stock classifier the user has ejected (matched by name).
+    const stockManifests = (options.stockClassifierNames ?? [])
+        .filter((name) => !userNames.has(name))
+        .map((name) => loadStockClassifier(name));
+    const manifests = [...builtIns, ...stockManifests, ...userClassifiers];
     manifests.sort((a, b) => (a.dispatch_order ?? Infinity) - (b.dispatch_order ?? Infinity));
     validateRegistry(manifests);
     const registry = manifests;
@@ -115,7 +122,7 @@ 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} — extras cannot override built-ins or other extras. Rename your classifier or run it under a different name.`);
+            throw new ClassifierManifestError(`duplicate classifier name: "${manifest.name}". A user classifier cannot override a mandatory built-in (preflight, model_tier, model_specialization, prompt_injection), and no two user classifiers may share a name. To replace a built-in's behaviour, pass a custom RunClassifier.`);
         }
         names.add(manifest.name);
     }

package/dist/src/config.d.ts

@@ -1,5 +1,5 @@
 import { type ClassifierName } from "./classifiers.js";
-export declare const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify.config.json";
+export declare const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify/config.json";
 export interface OpenClassifyConfig {
     readonly runner?: OllamaRunnerConfig;
     readonly catalog?: string;
@@ -7,7 +7,7 @@ export interface OpenClassifyConfig {
 }
 export interface OpenClassifyClassifierConfig {
     readonly dirs?: ReadonlyArray<string>;
-    readonly stock?: Readonly<Record<string, boolean>>;
+    readonly stock?: ReadonlyArray<string>;
 }
 export interface OllamaRunnerConfig {
     readonly provider: "ollama";

package/dist/src/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { STOCK_CLASSIFIER_NAMES } from "./classifiers.js";
 import { isRecord } from "./validation.js";
-export const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify.config.json";
+export const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify/config.json";
 export class OpenClassifyConfigError extends Error {
     constructor(message) {
         super(message);
@@ -30,9 +30,7 @@ export function classifierDirsFromConfig(config) {
     return config?.classifiers?.dirs ?? [];
 }
 export function stockClassifierNamesFromConfig(config) {
-    return Object.entries(config?.classifiers?.stock ?? {})
-        .filter(([, enabled]) => enabled)
-        .map(([name]) => name);
+    return config?.classifiers?.stock ?? [];
 }
 export function validateOpenClassifyConfig(value, path = "open-classify config") {
     if (!isRecord(value)) {
@@ -56,7 +54,7 @@ function validateClassifiers(value, path) {
         ...(value.dirs === undefined ? {} : { dirs: validateStringArray(value.dirs, path, "classifiers.dirs") }),
         ...(value.stock === undefined
             ? {}
-            : { stock: validateBooleanMap(value.stock, path, "classifiers.stock", STOCK_CLASSIFIER_NAMES) }),
+            : { stock: validateEnumArray(value.stock, path, "classifiers.stock", STOCK_CLASSIFIER_NAMES) }),
     };
 }
 function validateRunner(value, path) {
@@ -116,20 +114,24 @@ function validateStringArray(value, path, field) {
     }
     return value.map((item, index) => requireString(item, path, `${field}[${index}]`));
 }
-function validateBooleanMap(value, path, field, allowedKeys) {
-    if (!isRecord(value)) {
-        throwConfig(path, `${field} must be an object`);
+function validateEnumArray(value, path, field, allowedValues) {
+    if (!Array.isArray(value)) {
+        throwConfig(path, `${field} must be an array`);
     }
-    const allowed = allowedKeys === undefined ? undefined : new Set(allowedKeys);
-    const out = {};
-    for (const [name, enabled] of Object.entries(value)) {
-        if (allowed !== undefined && !allowed.has(name)) {
-            throwConfig(path, `${field}.${name} is not supported (available: ${[...allowed].join(", ")})`);
+    const allowed = new Set(allowedValues);
+    const seen = new Set();
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        const name = requireString(item, path, `${field}[${i}]`);
+        if (!allowed.has(name)) {
+            throwConfig(path, `${field}[${i}] "${name}" is not supported (available: ${[...allowed].join(", ")})`);
         }
-        if (typeof enabled !== "boolean") {
-            throwConfig(path, `${field}.${name} must be a boolean`);
+        if (seen.has(name)) {
+            throwConfig(path, `${field}[${i}] "${name}" is listed more than once`);
         }
-        out[name] = enabled;
+        seen.add(name);
+        out.push(name);
     }
     return out;
 }

package/docs/adding-a-classifier.md

@@ -1,11 +1,11 @@
 # Adding a classifier
 
-Every classifier uses the same two-file layout. Drop a folder into a directory listed under `classifiers.dirs` in `open-classify.config.json` (defaults to `./classifiers/` after `npx open-classify init`) and the runtime picks it up on the next start.
+Every classifier uses the same two-file layout. Drop a folder into a directory listed under `classifiers.dirs` in `open-classify/config.json` (defaults to `open-classify/classifiers/` after `npx open-classify init`) and the runtime picks it up on the next start.
 
 ## 1. Create the directory
 
 ```
-classifiers/<name>/
+open-classify/classifiers/<name>/
 ├── manifest.json
 └── prompt.md
 ```
@@ -71,7 +71,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).
+- **Name collisions throw.** A user classifier cannot override a mandatory built-in (`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.
 
@@ -87,11 +87,11 @@ Return an empty array when no clear topic applies.
 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`.
+Don't paste enum values for reserved fields — the runtime injects them with canonical wording so they never drift from the source enums.
 
 ## 4. Use it
 
-After `npx open-classify init`, your `classifiers/` directory already exists and `open-classify.config.json` points at it. Drop your folder there and call `createClassifier()`:
+After `npx open-classify init`, `open-classify/classifiers/` exists and `open-classify/config.json` points at it. Drop your folder there and call `createClassifier()`:
 
 ```ts
 import { createClassifier } from "open-classify";
@@ -105,31 +105,32 @@ const result = await classify({
 const tags = result.classifier_outputs.topic_tags?.tags ?? [];
 ```
 
-`classifiers.dirs` entries resolve relative to the config file, so the scaffold keeps working even if your server starts from a different current working directory.
+`classifiers.dirs` entries resolve relative to the config file, so the scaffold keeps working even when your server starts from a different working directory.
 
 If the manifest is malformed, `createClassifier` throws `ClassifierManifestError` at startup with the path and a specific reason — typos fail loud.
 
 ## Enabling or customizing optional stock classifiers
 
-`tools`, `memory_retrieval_queries`, `conversation_digest`, and `context_shift` ship as package-owned optional stock classifiers. Enable one in `open-classify.config.json` if you want package updates to keep improving its prompt:
+`tools`, `memory_retrieval_queries`, `conversation_digest`, and `context_shift` ship as package-owned optional stock classifiers. They're off by default. To enable one, list it in `open-classify/config.json`:
 
 ```json
 {
   "classifiers": {
-    "stock": {
-      "tools": true
-    }
+    "dirs": ["classifiers"],
+    "stock": ["tools"]
   }
 }
 ```
 
-`npx open-classify init` also copies editable templates into your `classifiers/` directory as `_<name>/` — inactive because of the underscore prefix. To customize one, keep the matching `classifiers.stock.<name>` value `false`, edit the copy, then turn it on:
+The package-owned prompt is used, and `npm update open-classify` keeps it current.
+
+When you want to take a stock classifier over and edit it:
 
 ```sh
-mv classifiers/_tools classifiers/tools
+npx open-classify eject 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 copied/custom classifier: rename `<name>/` → `_<name>/` to deactivate without deleting.
+That copies the stock files into `open-classify/classifiers/tools/`. The runtime transparently switches to your local copy (no config change needed; a local classifier with the same name as a stock classifier always wins). `npm update` won't touch the files. To revert, delete the folder.
 
 ## Targeting the assistant response
 
@@ -156,7 +157,7 @@ The built-in `prompt_injection` ships tagged `"both"` so it runs on both sides.
 
 ## Choosing the classifier model
 
-In `open-classify.config.json`:
+In `open-classify/config.json`:
 
 ```json
 {

package/docs/manifests.md

@@ -9,7 +9,7 @@ classifiers/
     prompt.md
 ```
 
-Folders whose names start with `_` are skipped by the loader — that's how the scaffolded `_<name>/` templates stay inactive until you drop the underscore.
+Folders whose names start with `_` are skipped by the loader — handy if you want to deactivate a classifier without deleting it.
 
 ## Fields
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-classify",
-  "version": "0.9.2",
+  "version": "1.0.0",
   "description": "Manifest-driven classifier runtime for routing user messages to downstream AI models",
   "license": "MIT",
   "author": "Taylor Bayouth",
@@ -36,9 +36,8 @@
     "bin",
     "dist/src",
     "docs",
-    "downstream-models.json",
-    "open-classify.config.example.json",
     "templates",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],

package/templates/scaffold/open-classify/README.md

@@ -0,0 +1,46 @@
+# open-classify/
+
+Everything Open Classify reads at runtime lives in this folder:
+
+- `config.json` — runtime configuration (Ollama host, model, classifier dirs)
+- `downstream-models.json` — catalog of models the aggregator can route to
+- `classifiers/` — your own classifiers, plus any stock classifiers you've
+  ejected for customization
+
+To remove Open Classify entirely:
+
+```sh
+rm -rf open-classify/
+npm uninstall open-classify
+```
+
+## Stock classifiers
+
+Open Classify ships four optional stock classifiers (`tools`,
+`memory_retrieval_queries`, `conversation_digest`, `context_shift`) that
+live inside the `open-classify` package. Enable one by listing its name
+in `config.json`:
+
+```json
+{
+  "classifiers": {
+    "dirs": ["classifiers"],
+    "stock": ["tools"]
+  }
+}
+```
+
+The package-owned prompt is used, and `npm update open-classify` keeps it
+current. When you need to take a stock classifier over and edit it:
+
+```sh
+npx open-classify eject tools
+```
+
+That copies the stock files into `classifiers/tools/`. From that point on,
+the runtime uses your local copy and `npm update` leaves it alone. A local
+classifier always wins on name, so eject works whether or not `tools` is
+listed in `classifiers.stock`. Delete the folder to revert.
+
+See the [author guide](https://github.com/taylorbayouth/open-classify/blob/main/docs/adding-a-classifier.md)
+for writing your own classifier from scratch.

package/templates/scaffold/open-classify/classifiers/README.md

@@ -0,0 +1,22 @@
+# classifiers/
+
+Drop a folder here per classifier. Each folder needs two files:
+
+- `manifest.json` — declares the output shape and a fallback
+- `prompt.md` — the classification instructions
+
+The folder name must match the manifest's `name` field. The runtime picks
+up every classifier here on the next start.
+
+To customize one of the four stock classifiers (`tools`,
+`memory_retrieval_queries`, `conversation_digest`, `context_shift`):
+
+```sh
+npx open-classify eject tools
+```
+
+That copies the stock files into `classifiers/tools/`. You own them from
+then on — `npm update open-classify` won't touch them.
+
+See the [author guide](https://github.com/taylorbayouth/open-classify/blob/main/docs/adding-a-classifier.md)
+for the full manifest reference.

package/templates/scaffold/open-classify/config.json

@@ -0,0 +1,12 @@
+{
+  "runner": {
+    "provider": "ollama",
+    "host": "http://127.0.0.1:11434",
+    "defaultModel": "gemma4:e4b-it-q4_K_M"
+  },
+  "catalog": "downstream-models.json",
+  "classifiers": {
+    "dirs": ["classifiers"],
+    "stock": []
+  }
+}

package/open-classify.config.example.json

@@ -1,26 +0,0 @@
-{
-  "runner": {
-    "provider": "ollama",
-    "host": "http://127.0.0.1:11434",
-    "defaultModel": "gemma4:e4b-it-q4_K_M",
-    "options": {
-      "temperature": 0,
-      "top_p": 1,
-      "seed": 0,
-      "num_ctx": 4096
-    },
-    "models": {
-      "prompt_injection": "llama-guard3:8b"
-    }
-  },
-  "catalog": "downstream-models.json",
-  "classifiers": {
-    "dirs": ["classifiers"],
-    "stock": {
-      "tools": false,
-      "memory_retrieval_queries": false,
-      "conversation_digest": false,
-      "context_shift": false
-    }
-  }
-}