@cendor/guardrails 0.2.0 → 0.4.0

package/dist/semantic.js

@@ -68,6 +68,33 @@ export function groundedness(embed, sources, opts = {}) {
     };
     return defineGuardrail(check, { name, stage, timeout, onError: resolveOnError(action, onError) });
 }
+/**
+ * Trip when the payload is semantically close to a **custom category** you define by example — the
+ * local, `$0` counterpart to Azure Content Safety's *rapid custom categories* (description + examples
+ * → embedding search), with no cloud call and no training step. Trips when the payload's max cosine
+ * similarity to any example is **at or above** `threshold`, recording `metadata.category` /
+ * `metadata.score`; catches paraphrases `keywordDeny` misses. Defaults to `action:'flag'` (a tuned
+ * heuristic — calibrate before you block). No catch-rate claim; empty `examples` never trips.
+ *
+ * `embed(text)` is **bring-your-own** — a local sentence-transformer, a hosted endpoint, or e.g. a
+ * transformers.js pipeline. (There is no zero-config `localEmbedder` in TS yet — model2vec is
+ * Python-only; parity 🚧.)
+ */
+export function customCategory(category, examples, embed, opts = {}) {
+    const { threshold = 0.8, stage = 'input', action = 'flag', name = `custom_category:${category}`, timeout, onError, } = opts;
+    const exampleVecs = lazyVectors(embed, [...examples]);
+    const check = (payload, _ctx) => {
+        const vecs = exampleVecs();
+        if (vecs.length === 0)
+            return null;
+        const query = [...embed(payloadText(payload))];
+        const best = vecs.reduce((m, v) => Math.max(m, cosine(query, v)), Number.NEGATIVE_INFINITY);
+        if (best < threshold)
+            return null;
+        return new Verdict(action, `custom category ${JSON.stringify(category)}: sim ${best.toFixed(2)} >= ${threshold}`, null, { category, score: Math.round(best * 1e4) / 1e4 });
+    };
+    return defineGuardrail(check, { name, stage, timeout, onError: resolveOnError(action, onError) });
+}
 /**
  * Trip when the payload's max cosine similarity to any denied-topic exemplar is **at or above**
  * `threshold` — steer an agent off subjects it must never engage. The reason names the closest topic

package/dist/semantic.js.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cendor/guardrails",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A local-first gate for LLM apps: define a check — keyword, regex, URL, length, JSON-schema — attach it to a stage (input, tool call, tool output, output). Deterministic, microsecond, $0, and every decision is audit-grade evidence.",
   "type": "module",
   "license": "Apache-2.0",