open-classify 0.2.0 → 0.5.0

package/dist/src/stock-prompt.js

@@ -1,63 +1,183 @@
+// Prompt builder.
+//
+// Every classifier's system prompt is composed at load time from:
+//
+//   1. Shared base sections (JSON-only contract, reason + certainty rules)
+//   2. The classifier header (name and purpose)
+//   3. Auto-injected fragments for each declared reserved field — these
+//      include the canonical enum values, so the LLM cannot drift even if
+//      the manifest author forgets to enumerate them in prompt.md
+//   4. The classifier's own `prompt.md`
+//   5. JSON example(s) of a complete output: either the manifest's
+//      `output_schema.examples`, or a synthesized skeleton derived from the
+//      schema if none were provided
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { RESERVED_FIELDS, } from "./reserved-fields.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const STOCK_PROMPTS_DIR = join(__dirname, "classifiers", "stock", "prompts");
-export function buildStockClassifierPrompt(manifest) {
+const SHARED_PROMPTS_DIR = join(__dirname, "classifiers", "_prompts");
+export function buildClassifierPrompt(args) {
+    const { manifest, reservedFields, appliesTo, classifierPromptText } = args;
     const sections = [
-        promptMarkdown("base.md"),
-        promptMarkdown("reason.md"),
-        promptMarkdown("confidence.md"),
-        renderTemplate(promptMarkdown("classifier-header.md"), {
-            classifier_name: manifest.name,
-            classifier_purpose: manifest.purpose,
-        }),
+        readShared("base.md"),
+        readShared("reason.md"),
+        readShared("confidence.md"),
+        renderHeader(manifest.name, manifest.purpose),
     ];
-    if (manifest.kind === "stock") {
-        sections.push(stockSection(manifest));
+    if (appliesTo === "both") {
+        sections.push("Target role: the final message may be from the user or the assistant. Inspect whichever role the input declares and classify accordingly.");
     }
-    else {
-        sections.push(promptMarkdown("custom-output.md"));
+    else if (appliesTo === "assistant") {
+        sections.push("Target role: the final message is the assistant's reply. Classify the assistant message, not a user request.");
     }
+    if (reservedFields.length > 0) {
+        sections.push(renderReservedFieldsSection(reservedFields, manifest.allowed_tools));
+    }
+    if (classifierPromptText.trim().length > 0) {
+        sections.push("Classifier guidance:\n" + classifierPromptText.trim());
+    }
+    sections.push(renderExamplesSection(manifest, reservedFields));
     return sections.join("\n\n");
 }
-function stockSection(manifest) {
-    return renderTemplate(promptMarkdown(`${manifest.name}.md`), {
-        allowed_tools: renderAllowedTools(manifest.tools),
-        preflight_output: promptMarkdown("preflight-output.md"),
-        routing_output: promptMarkdown("routing-output.md"),
-        prompt_injection_output: promptMarkdown("prompt-injection-output.md"),
-        specialty: promptMarkdown("specialty.md"),
-        tier: promptMarkdown("tier.md"),
-        tools_output: promptMarkdown("tools-output.md"),
-    });
-}
-function renderAllowedTools(tools) {
-    if (!tools || tools.length === 0) {
-        return "No downstream tools are available.";
-    }
+function renderHeader(name, purpose) {
+    return [
+        `Classifier: ${name}`,
+        `Purpose: ${purpose}`,
+        "Treat the stated purpose as a hard scope boundary.",
+        "Emit only outputs that directly serve that purpose, and do not infer adjacent judgments that belong to other classifiers.",
+    ].join("\n");
+}
+function renderReservedFieldsSection(reservedFields, allowedTools) {
+    const context = { allowed_tools: allowedTools };
+    const fragments = reservedFields.map((name) => RESERVED_FIELDS[name].promptFragment(context));
     return [
-        "Allowed tool ids:",
+        "Reserved fields you may emit at the top level of your JSON output:",
         "",
-        ...tools.map((tool) => `- ${tool.id}: ${tool.description}`),
+        ...fragments,
+        "",
+        "Omit any reserved field when you have no signal — the runtime will drop low-certainty values regardless.",
+    ].join("\n");
+}
+function renderExamplesSection(manifest, reservedFields) {
+    const fromSchema = readManifestExamples(manifest);
+    const examples = fromSchema && fromSchema.length > 0
+        ? fromSchema
+        : [synthesizeExample(manifest, reservedFields)];
+    const rendered = examples.map((example, index) => `Example ${index + 1}: ${JSON.stringify(example)}`);
+    return [
+        "Output shape (return one JSON object matching this shape):",
+        "",
+        ...rendered,
     ].join("\n");
 }
-function promptMarkdown(filename) {
-    return readFileSync(join(STOCK_PROMPTS_DIR, filename), "utf8").trim();
+function readManifestExamples(manifest) {
+    const schema = manifest.output_schema;
+    if (schema === undefined || typeof schema !== "object" || schema === null) {
+        return undefined;
+    }
+    const examples = schema.examples;
+    if (!Array.isArray(examples))
+        return undefined;
+    return examples;
 }
-function renderTemplate(template, slots) {
-    let rendered = template;
-    for (let pass = 0; pass < 5; pass += 1) {
-        const next = rendered.replace(/\{\{([a-z_]+)\}\}/g, (match, name) => {
-            const value = slots[name];
-            if (value === undefined) {
-                throw new Error(`missing prompt slot: ${match}`);
+// ─── Schema-based example synthesis ─────────────────────────────────────────
+//
+// When a manifest omits `output_schema.examples`, the runtime fills in a
+// representative JSON skeleton so the LLM always sees the full output shape.
+// The author only has to describe each field in plain language in prompt.md.
+function synthesizeExample(manifest, reservedFields) {
+    const example = {
+        reason: "<short reason for this verdict>",
+        certainty: "strong",
+    };
+    for (const field of reservedFields) {
+        example[field] = synthesizeReservedFieldValue(field, manifest.allowed_tools);
+    }
+    const schema = manifest.output_schema;
+    if (schema !== undefined && typeof schema === "object" && schema !== null) {
+        const properties = schema.properties;
+        if (properties !== null && typeof properties === "object" && !Array.isArray(properties)) {
+            for (const [key, subSchema] of Object.entries(properties)) {
+                example[key] = synthesizeValue(subSchema);
             }
-            return value;
-        });
-        if (next === rendered)
-            return rendered;
-        rendered = next;
+        }
+    }
+    return example;
+}
+function synthesizeReservedFieldValue(field, allowedTools) {
+    const subSchema = RESERVED_FIELDS[field].subSchema({ allowed_tools: allowedTools });
+    return synthesizeValue(subSchema);
+}
+function synthesizeValue(schema) {
+    if (schema === null || typeof schema !== "object")
+        return "<value>";
+    const s = schema;
+    // Honor explicit examples or const values when the schema author provided
+    // them — they're the most accurate hint about what's expected.
+    if (Array.isArray(s.examples) && s.examples.length > 0)
+        return s.examples[0];
+    if (s.const !== undefined)
+        return s.const;
+    if (Array.isArray(s.enum) && s.enum.length > 0)
+        return s.enum[0];
+    const type = Array.isArray(s.type) ? s.type[0] : s.type;
+    switch (type) {
+        case "string":
+            return synthesizeString(s);
+        case "integer":
+            return clampInteger(s);
+        case "number":
+            return clampNumber(s);
+        case "boolean":
+            return true;
+        case "array":
+            return synthesizeArray(s);
+        case "object":
+            return synthesizeObject(s);
+        default:
+            // Schema without an explicit type — fall back to a string placeholder.
+            return "<value>";
     }
-    throw new Error("prompt template slots are nested too deeply");
+}
+function synthesizeString(schema) {
+    const placeholder = "<text>";
+    const min = typeof schema.minLength === "number" ? schema.minLength : 1;
+    if (placeholder.length >= min)
+        return placeholder;
+    return placeholder.padEnd(min, "x");
+}
+function clampInteger(schema) {
+    if (typeof schema.minimum === "number")
+        return schema.minimum;
+    if (typeof schema.maximum === "number")
+        return schema.maximum;
+    return 0;
+}
+function clampNumber(schema) {
+    if (typeof schema.minimum === "number")
+        return schema.minimum;
+    if (typeof schema.maximum === "number")
+        return schema.maximum;
+    return 0;
+}
+function synthesizeArray(schema) {
+    const min = typeof schema.minItems === "number" ? schema.minItems : 0;
+    if (min === 0)
+        return [];
+    const itemSchema = schema.items;
+    return Array.from({ length: min }, () => synthesizeValue(itemSchema));
+}
+function synthesizeObject(schema) {
+    const out = {};
+    const properties = schema.properties;
+    if (properties !== null && typeof properties === "object" && !Array.isArray(properties)) {
+        for (const [key, sub] of Object.entries(properties)) {
+            out[key] = synthesizeValue(sub);
+        }
+    }
+    return out;
+}
+function readShared(filename) {
+    return readFileSync(join(SHARED_PROMPTS_DIR, filename), "utf8").trim();
 }

package/dist/src/stock-validation.d.ts

@@ -1,21 +1,20 @@
-import type { JsonClassifierManifest, ClassifierOutput } from "./stock.js";
-export declare const STOCK_REASON_MAX_CHARS = 120;
-export declare const STOCK_REPLY_MAX_CHARS = 200;
-export declare const STOCK_TOOL_ID_MAX_CHARS = 64;
-export declare const STOCK_TOOL_DESCRIPTION_MAX_CHARS = 240;
-export declare const STOCK_MANIFEST_NAME_MAX_CHARS = 80;
-export declare const STOCK_MANIFEST_VERSION_MAX_CHARS = 40;
-export declare const STOCK_MANIFEST_PURPOSE_MAX_CHARS = 400;
-export declare function validateJsonClassifierManifest(value: unknown, model?: string): JsonClassifierManifest;
-export interface ValidateOutputContext {
-    readonly classifier: string;
-    readonly model: string;
+import type { AppliesTo, ClassifierOutput, JsonClassifierManifest, RuntimeClassifierManifest } from "./stock.js";
+import { type ReservedFieldName } from "./reserved-fields.js";
+export declare const REASON_MAX_CHARS = 120;
+export declare const TOOL_ID_MAX_CHARS = 64;
+export declare const TOOL_DESCRIPTION_MAX_CHARS = 240;
+export declare const MANIFEST_NAME_MAX_CHARS = 80;
+export declare const MANIFEST_VERSION_MAX_CHARS = 40;
+export declare const MANIFEST_PURPOSE_MAX_CHARS = 400;
+export interface ManifestLoadResult {
+    readonly manifest: JsonClassifierManifest;
+    readonly reservedFields: ReadonlyArray<ReservedFieldName>;
+    readonly composedOutputSchema: unknown;
+    readonly appliesTo: AppliesTo;
 }
-export declare function validateOutputForManifest(manifest: JsonClassifierManifest, value: unknown, context: ValidateOutputContext): ClassifierOutput;
-export declare function validateWithSchema(value: unknown, schema: unknown, classifier: string, model: string, path: string): void;
-export interface LegacyValidateOptions {
+export declare function validateJsonClassifierManifest(value: unknown, model?: string): ManifestLoadResult;
+export interface ValidateOutputContext {
     readonly classifier: string;
     readonly model: string;
-    readonly manifest: JsonClassifierManifest;
 }
-export declare function validateClassifierOutputWithManifest(value: unknown, options: LegacyValidateOptions): ClassifierOutput;
+export declare function validateOutputForManifest(manifest: RuntimeClassifierManifest, value: unknown, context: ValidateOutputContext): ClassifierOutput;