open-classify 0.6.0 → 0.8.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