open-classify 0.9.1 → 0.9.3

package/README.md

@@ -43,23 +43,21 @@ Every classifier uses the same manifest shape and emits the same output envelope
 
 ## 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**
+Prerequisites: Node 18+, [Ollama](https://ollama.com), and the default classifier model:
 
 ```sh
-npm install open-classify
+ollama pull gemma4:e4b-it-q4_K_M
 ```
 
-**2. Scaffold**
+**1. Scaffold (from your project root)**
 
 ```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.
+If the package isn't installed yet, `init` offers to add it. It writes `open-classify.config.json`, `downstream-models.json`, and a `classifiers/` directory. Re-run safe: existing files are skipped. Verify the install at any time with `npx open-classify doctor`.
 
-**3. Use it**
+**2. Use it**
 
 ```ts
 import { createClassifier } from "open-classify";
@@ -75,31 +73,29 @@ else if (result.action === "block") handleBlock(result.block_reason);     // inj
 else callDownstream(result.model_id, result.tools, result.reply?.text);   // route the real request
 ```
 
-**4. Enable or customize optional classifiers**
+`createClassifier()` looks for `open-classify.config.json` in the working directory, so the scaffolded layout works with no further wiring.
+
+**3. Enable or customize optional classifiers**
+
+Four mandatory base classifiers (`preflight`, `model_tier`, `model_specialization`, `prompt_injection`) always run from the package. Four more (`tools`, `memory_retrieval_queries`, `conversation_digest`, `context_shift`) are optional and default to off.
 
-`init` writes `open-classify.config.json`, which enables package-owned stock classifiers without copying them into your project. They default to `false` so the four mandatory base classifiers run automatically:
+You have two ways to use the optional ones:
 
 ```json
-{
-  "classifiers": {
-    "stock": {
-      "tools": false
-    }
-  }
-}
+{ "classifiers": { "stock": { "tools": true } } }
 ```
 
-Set `"tools": true` to run the package-owned stock `tools` classifier. Because it stays in `node_modules/open-classify`, `npm update open-classify` can improve its prompt later without touching your project files.
+Set the toggle to `true` to run the package-owned version. `npm update open-classify` keeps the prompt current.
 
-Inside `classifiers/` you'll also find four `_<name>/` directories — editable copies of the stock classifiers, inactive because of the underscore prefix. To customize one, keep the matching `classifiers.stock.<name>` value `false`, edit the copy, then drop the underscore:
+Or customize a local copy. `init` scaffolds editable templates in `classifiers/_<name>/` (inactive because of the underscore prefix). To take one over, keep the stock toggle off and rename the folder:
 
 ```sh
 mv classifiers/_tools classifiers/tools
 ```
 
-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 copied/custom classifier out of the active set without deleting it.
+The same convention works in reverse: rename any active classifier `<name>/` → `_<name>/` to deactivate without deleting.
 
-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).
+To write a new classifier, drop a `<name>/manifest.json` + `<name>/prompt.md` in `classifiers/`. See [docs/adding-a-classifier.md](docs/adding-a-classifier.md).
 
 ### Classifying assistant output
 
@@ -310,45 +306,20 @@ The resolver picks the cheapest model matching `model_specialization` and `model
 - Open Classify keeps whole messages only, drops oldest first to fit a 5,000-char budget, and caps history at 20 messages.
 - Unknown fields are rejected, not passed through.
 
-## Local setup
+## Configuration
 
-```sh
-npm run setup
-```
-
-Checks prerequisites (Node, npm, Ollama), confirms the base model is pulled, installs dependencies, and builds. Idempotent — safe to re-run.
-
-Optional Ollama runtime config:
+`npx open-classify init` writes a working `open-classify.config.json` for you. To customize, edit it directly — the full set of supported fields (with realistic example values) lives in [open-classify.config.example.json](open-classify.config.example.json).
 
-```sh
-cp open-classify.config.example.json open-classify.config.json
-```
-
-```json
-{
-  "runner": {
-    "provider": "ollama",
-    "defaultModel": "gemma4:e4b-it-q4_K_M",
-    "models": {
-      "model_tier": "qwen2.5:7b-instruct-q4_K_M",
-      "prompt_injection": "llama-guard3:8b",
-      "memory_retrieval_queries": "qwen2.5:7b-instruct-q4_K_M"
-    }
-  },
-  "catalog": "downstream-models.json",
-  "classifiers": {
-    "dirs": ["classifiers"],
-    "stock": {
-      "tools": false,
-      "memory_retrieval_queries": false,
-      "conversation_digest": false,
-      "context_shift": false
-    }
-  }
-}
-```
-
-`runner.provider` currently supports `"ollama"` only. `runner.defaultModel` applies to any classifier without an explicit `runner.models` entry. `runner.models` is a flat map keyed by classifier name. `classifiers.dirs` is for user-owned copied/custom classifiers; `classifiers.stock` toggles package-owned optional classifiers.
+| Field | What it controls |
+|---|---|
+| `runner.provider` | Backend. Currently `"ollama"` only. |
+| `runner.host` | Ollama host URL. Defaults to `http://127.0.0.1:11434`. |
+| `runner.defaultModel` | Classifier model used when there is no per-classifier override. |
+| `runner.options` | Ollama generation options: `temperature`, `top_p`, `seed`, `num_ctx`. |
+| `runner.models` | Per-classifier model overrides. Flat map keyed by classifier name. |
+| `catalog` | Path to the downstream model catalog (relative to the config file). |
+| `classifiers.dirs` | Directories of user-owned classifiers to load. |
+| `classifiers.stock` | Toggles for package-owned optional stock classifiers. |
 
 ## Bring your own backend
 
@@ -383,8 +354,6 @@ For the lowest-level entry points, `classifyOpenClassifyInput(input, { runClassi
 - [docs/resolver.md](docs/resolver.md) — aggregation and model resolution
 - [docs/adding-a-classifier.md](docs/adding-a-classifier.md) — author guide
 
-## Development
+## Contributing
 
-```sh
-npm test    # build + run the Node test runner suite
-```
+Clone the repo, then `npm run setup` (checks Node/Ollama, pulls the base model, installs and builds) and `npm test` (build + Node test runner). PRs welcome.

package/bin/open-classify.mjs

@@ -35,55 +35,29 @@ const TEMPLATE_DESCRIPTIONS = {
 
 const CLASSIFIERS_README = `# classifiers/
 
-Drop a folder here per classifier. Each folder needs:
+Each classifier is a folder with two files:
 
-- \`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
+- \`manifest.json\` — declares the output shape and fallback
+- \`prompt.md\` — the classification instructions
 
-## Quickstart
+The loader skips any folder whose name starts with \`_\`. That's how the
+four \`_<name>/\` templates here stay inactive until you opt in: drop the
+underscore (\`mv _tools tools\`) and the classifier runs on the next start.
 
-\`\`\`js
-import { createClassifier } from "open-classify";
+Each template mirrors a package-owned stock classifier. You have two ways
+to use them:
 
-const { classify } = createClassifier();
-\`\`\`
+1. **Enable in place** — set \`classifiers.stock.<name>: true\` in
+   \`open-classify.config.json\`. The package-owned version runs and is
+   updated by \`npm update open-classify\`.
+2. **Customize a local copy** — keep the stock toggle off, drop the
+   underscore on the template here, and edit \`prompt.md\` /
+   \`manifest.json\` to taste.
 
-Place this in your server entry point. Call \`classify(input)\` for each user message.
-\`open-classify.config.json\` wires in \`./classifiers\` automatically.
-
-## Stock classifiers
-
-\`tools\`, \`memory_retrieval_queries\`, \`conversation_digest\`, and \`context_shift\`
-ship with the package but are disabled by default in \`open-classify.config.json\`.
-Enable a package-owned stock classifier by setting it to \`true\`:
-
-\`\`\`json
-{
-  "classifiers": {
-    "stock": {
-      "tools": true
-    }
-  }
-}
-\`\`\`
-
-Package-owned stock classifiers are updated by \`npm update open-classify\`.
-
-## Customizing a stock classifier
-
-The four \`_<name>/\` directories below are editable copies of the stock classifiers.
-They are inactive because the loader skips any folder starting with \`_\`. To customize one,
-keep the matching \`classifiers.stock.<name>\` value \`false\`, edit the files, then drop 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.
+To write your own classifier, drop a new \`<name>/\` folder here with its
+own \`manifest.json\` and \`prompt.md\`. The folder name must match the
+manifest's \`name\` field. See the
+[author guide](https://github.com/taylorbayouth/open-classify/blob/main/docs/adding-a-classifier.md).
 `;
 
 const DEFAULT_CONFIG = {
@@ -186,6 +160,8 @@ function parseUninstallFlags(args) {
     yes: false,
     dryRun: false,
     force: false,
+    keepPackage: false,
+    packageManager: null,
     classifierDir: "classifiers",
   };
 
@@ -194,6 +170,9 @@ function parseUninstallFlags(args) {
     if (arg === "--yes" || arg === "-y") flags.yes = true;
     else if (arg === "--dry-run") flags.dryRun = true;
     else if (arg === "--force") flags.force = true;
+    else if (arg === "--keep-package") flags.keepPackage = true;
+    else if (arg === "--package-manager" && args[i + 1]) flags.packageManager = args[++i];
+    else if (arg.startsWith("--package-manager=")) flags.packageManager = arg.split("=")[1];
     else if (arg === "--classifier-dir" && args[i + 1]) flags.classifierDir = args[++i];
     else if (arg.startsWith("--classifier-dir=")) flags.classifierDir = arg.split("=")[1];
   }
@@ -208,9 +187,10 @@ Commands:
   init [options]    Scaffold open-classify.config.json and classifiers/ in the
                     current directory. Re-run safe: existing files are skipped.
 
-  uninstall         Remove open-classify scaffold files from the current
-                    directory. Use --force to remove the whole classifiers/
-                    directory, including active/custom classifiers.
+  uninstall         Remove the open-classify scaffold and uninstall the
+                    package. Use --force to also delete active/custom
+                    classifiers, --keep-package to leave the npm dependency
+                    in place.
 
   doctor            Check that the install, config, Ollama, and classifiers are
                     all working. Exits non-zero on failure.
@@ -231,6 +211,8 @@ Options for init:
 Options for uninstall:
   --dry-run              Preview what would be removed; don't delete anything
   --force                Remove the whole classifiers/ directory
+  --keep-package         Don't run the package manager uninstall step
+  --package-manager <m>  npm | pnpm | yarn | bun  (default: auto-detect)
   --classifier-dir <p>   Directory for classifiers  (default: ./classifiers)
   --yes, -y              Accept all prompts (CI mode)
 
@@ -389,21 +371,31 @@ async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageMan
     }
   }
 
-  const classifierDirRel = relative(cwd, resolvedClassifierDir);
   process.stdout.write(`
 Next steps:
 
-  1. Pull the default model:
+  1. Pull the default classifier model:
+
        ollama pull ${config.runner.defaultModel}
 
-  2. Wire it into your server (example for a Node entrypoint):
-       see  ./${classifierDirRel}/README.md  →  "Quickstart"
+  2. Verify everything is wired up:
 
-  3. Verify the install:
        npx open-classify doctor
 
-  4. Run a one-shot classification against your config:
-       npx open-classify try "hello world"
+  3. Try it without writing any code:
+
+       npx open-classify try "hello"
+
+  4. Use it from your code:
+
+       import { createClassifier } from "open-classify";
+       const { classify } = createClassifier();
+       const result = await classify({
+         messages: [{ role: "user", text: "hello" }],
+       });
+
+     The factory finds open-classify.config.json in your working
+     directory and wires in the classifiers/ folder automatically.
 
 Docs:  https://github.com/taylorbayouth/open-classify#readme
 `);
@@ -562,12 +554,21 @@ function showDiffs(conflicts, cwd, classifierDir, config = DEFAULT_CONFIG) {
 // uninstall
 // ---------------------------------------------------------------------------
 
-async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
+async function runUninstall({ cwd, yes, dryRun, force, keepPackage, packageManager, classifierDir }) {
   const resolvedClassifierDir = resolve(cwd, classifierDir);
   const plan = planUninstall(cwd, { classifierDir: resolvedClassifierDir, force });
 
-  if (plan.toRemove.length === 0) {
-    process.stdout.write("Nothing to remove — no open-classify scaffold found.\n");
+  const pkgPath = join(cwd, "package.json");
+  let pkg = null;
+  if (existsSync(pkgPath)) {
+    try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch { pkg = null; }
+  }
+  const packageInstalled = pkg !== null && isOpenClassifyDep(pkg);
+  const willRemovePackage = !keepPackage && packageInstalled;
+  const pm = packageManager || detectPackageManager(cwd);
+
+  if (plan.toRemove.length === 0 && !willRemovePackage) {
+    process.stdout.write("Nothing to remove — no open-classify scaffold or dependency found.\n");
     if (plan.toSkip.length > 0) {
       process.stdout.write("\nSkipped active/custom classifier dirs:\n");
       for (const p of plan.toSkip) process.stdout.write(`  ${p}\n`);
@@ -576,8 +577,11 @@ async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
     return;
   }
 
-  process.stdout.write(`\nThe following open-classify scaffold will be removed from ${cwd}:\n\n`);
+  process.stdout.write(`\nThe following will be removed from ${cwd}:\n\n`);
   for (const p of plan.toRemove) process.stdout.write(`  ${p}\n`);
+  if (willRemovePackage) {
+    process.stdout.write(`  open-classify (via ${pm} uninstall)\n`);
+  }
 
   if (plan.toSkip.length > 0) {
     process.stdout.write("\nSkipped active/custom classifier dirs:\n");
@@ -585,6 +589,10 @@ async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
     process.stdout.write("\nUse --force to remove the whole classifiers/ directory.\n");
   }
 
+  if (keepPackage && packageInstalled) {
+    process.stdout.write("\nKeeping the open-classify package (--keep-package).\n");
+  }
+
   if (dryRun) {
     process.stdout.write("\n(dry run — nothing removed)\n");
     return;
@@ -600,8 +608,19 @@ async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
 
   process.stdout.write("\n");
   for (const action of plan.actions) action();
-  process.stdout.write("\n✓ removed open-classify scaffold\n");
-  process.stdout.write("To remove the package dependency too, run: npm uninstall open-classify\n");
+  if (plan.toRemove.length > 0) {
+    process.stdout.write("\n✓ removed open-classify scaffold\n");
+  }
+
+  if (willRemovePackage) {
+    process.stdout.write(`\n  Running: ${pm} uninstall open-classify\n\n`);
+    const result = spawnSync(pm, ["uninstall", "open-classify"], { cwd, stdio: "inherit" });
+    if (result.status !== 0) {
+      process.stderr.write(`\n✖  Package uninstall failed. Run manually: ${pm} uninstall open-classify\n`);
+      process.exit(1);
+    }
+    process.stdout.write("\n✓ removed open-classify package\n");
+  }
 }
 
 function planUninstall(cwd, { classifierDir, force }) {

package/docs/adding-a-classifier.md

@@ -1,13 +1,6 @@
 # Adding a classifier
 
-Every classifier — package-owned or your own — uses the same two-file layout. The runtime only cares about which reserved fields a classifier opts into; ownership just decides whether `npm update open-classify` can replace the prompt.
-
-There are two places a classifier can live:
-
-- **In your own app**, in a directory listed in `open-classify.config.json` under `classifiers.dirs` (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.
+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.
 
 ## 1. Create the directory
 

package/docs/manifests.md

@@ -1,16 +1,15 @@
 # Manifest reference
 
-Every classifier lives in `src/classifiers/<name>/` and contains exactly two files:
+Every classifier is a directory with exactly two files:
 
 ```
-src/classifiers/
-  _prompts/                   # shared base markdown (base.md, reason.md, confidence.md)
+classifiers/
   <classifier_name>/
     manifest.json
     prompt.md
 ```
 
-The loader skips any top-level directory whose name starts with `_` (those are shared assets, not classifiers).
+Folders whose names start with `_` are skipped by the loader — that's how the scaffolded `_<name>/` templates stay inactive until you drop the underscore.
 
 ## Fields
 
@@ -145,7 +144,7 @@ A manifest may declare both reserved fields and custom properties; they sit alon
 
 `prompt.md` is the classifier-specific instruction text. The runtime composes the system prompt at load time from:
 
-1. Shared base sections (JSON-only contract, `reason` + `certainty` rules) from `src/classifiers/_prompts/`
+1. Shared base sections (JSON-only contract, `reason` + `certainty` rules)
 2. The classifier header (name and purpose, with the purpose stated as a hard scope boundary)
 3. Auto-injected fragments for each declared reserved field (canonical enum values included, so you can't drift)
 4. Your `prompt.md`

package/open-classify.config.example.json

@@ -4,16 +4,13 @@
     "host": "http://127.0.0.1:11434",
     "defaultModel": "gemma4:e4b-it-q4_K_M",
     "options": {
-      "num_ctx": 4096,
       "temperature": 0,
       "top_p": 1,
-      "seed": 0
+      "seed": 0,
+      "num_ctx": 4096
     },
     "models": {
-      "preflight": "gemma4:e4b-it-q4_K_M",
-      "model_tier": "gemma4:e4b-it-q4_K_M",
-      "model_specialization": "gemma4:e4b-it-q4_K_M",
-      "prompt_injection": "gemma4:e4b-it-q4_K_M"
+      "prompt_injection": "llama-guard3:8b"
     }
   },
   "catalog": "downstream-models.json",

package/package.json

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