@devilsdev/rag-guardrails 3.8.0 → 3.8.2

package/dist/index.cjs

@@ -184,7 +184,7 @@ var require_injection_detector = __commonJS({
         // Chat-template role markers: "system:" as a line prefix, [system],
         // <|im_start|>system, [INST], <<SYS>>, "### system".
         id: "role-marker",
-        pattern: /(?:^|\n)\s*(?:system|assistant|developer)\s*:|\[\s*(?:system|inst)\s*\]|<\|?\s*(?:im_start|system)\s*\|?>|<<\s*sys\s*>>|#{2,}\s*(?:system|instruction)s?\b/
+        pattern: /(?:^|\n)\s*(?:system|assistant|developer)\s*:|\[\s*(?:system|inst)\s*\]|<\|?\s*(?:im_start|system)\s*\|?>|<<\s*sys\s*>>|(?<!#)#{2,}\s*(?:system|instruction)s?\b/
       },
       {
         id: "dan",
@@ -256,7 +256,7 @@ var require_detectors = __commonJS({
     var { detectInjection } = require_injection_detector();
     var KINDS = ["injection", "pii"];
     var DEFAULT_PII_PATTERNS = {
-      email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+      email: /(?<![a-zA-Z0-9._%+-])[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
       phone: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,
       ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
       creditCard: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g
@@ -1040,12 +1040,20 @@ code{background:var(--chip);padding:1px 5px;border-radius:4px;font-size:13px}`;
   }
 });
 
+// scoped:@devilsdev/rag-core|retrieval/access-fields.js
+var require_access_fields = __commonJS({
+  "scoped:@devilsdev/rag-core|retrieval/access-fields.js"(exports2, module2) {
+    module2.exports = require("@devilsdev/rag-core")[Symbol.for("@devilsdev/rag-core/internal")]("retrieval/access-fields.js");
+  }
+});
+
 // src/guardrails/retrieval-guard.js
 var require_retrieval_guard = __commonJS({
   "src/guardrails/retrieval-guard.js"(exports2, module2) {
     "use strict";
     var { EventEmitter } = require("events");
     var { detectInjection } = require_injection_detector();
+    var { NO_ACCESS } = require_access_fields();
     var {
       resolveDetectors,
       runDetectorsSync,
@@ -1173,17 +1181,15 @@ var require_retrieval_guard = __commonJS({
             }
           }
           if (!dominated && this.config.enforceACL) {
-            const userPermissions = context.userPermissions || [];
-            const restriction = result.requiredRole ?? result.acl ?? doc.requiredRole ?? doc.acl;
-            const requiredRoles = restriction ? [].concat(restriction) : null;
-            if (requiredRoles && requiredRoles.length > 0) {
-              const hasAccess = requiredRoles.some(
-                (role) => userPermissions.includes(role)
-              );
-              if (!hasAccess) {
-                dominated = true;
-                reasons.acl = (reasons.acl || 0) + 1;
-              }
+            const userPermissions = permissionsOf(context.userPermissions).filter(
+              (role) => role !== NO_ACCESS
+            );
+            const hasAccess = restrictionsOf(result).every(
+              (roles) => roles.some((role) => userPermissions.includes(role))
+            );
+            if (!hasAccess) {
+              dominated = true;
+              reasons.acl = (reasons.acl || 0) + 1;
             }
           }
           dropped[i] = dominated;
@@ -1247,6 +1253,28 @@ var require_retrieval_guard = __commonJS({
         result.content || result.text || result.pageContent || doc.content || doc.text || ""
       );
     }
+    function restrictionsOf(result) {
+      if (!result || typeof result !== "object") return [];
+      const lists = [];
+      for (const source of [result, result.metadata, result.doc]) {
+        if (!source || typeof source !== "object") continue;
+        for (const key of ["requiredRole", "acl"]) {
+          const value = source[key];
+          if (value === void 0 || value === null || value === "") continue;
+          const roles = [].concat(value);
+          if (roles.length > 0) lists.push(roles);
+        }
+      }
+      return lists;
+    }
+    function permissionsOf(value) {
+      if (typeof value === "string") return [value];
+      if (Array.isArray(value)) return value;
+      if (value && typeof value[Symbol.iterator] === "function") {
+        return Array.from(value);
+      }
+      return [];
+    }
     module2.exports = { RetrievalGuard, DEFAULT_CONFIG };
   }
 });
@@ -1489,6 +1517,13 @@ var require_post_generation_guard = __commonJS({
   }
 });
 
+// scoped:@devilsdev/rag-core|utils/run-abort.js
+var require_run_abort = __commonJS({
+  "scoped:@devilsdev/rag-core|utils/run-abort.js"(exports2, module2) {
+    module2.exports = require("@devilsdev/rag-core")[Symbol.for("@devilsdev/rag-core/internal")]("utils/run-abort.js");
+  }
+});
+
 // src/guardrails/guardrails-pipeline.js
 var require_guardrails_pipeline = __commonJS({
   "src/guardrails/guardrails-pipeline.js"(exports2, module2) {
@@ -1498,6 +1533,7 @@ var require_guardrails_pipeline = __commonJS({
     var { RetrievalGuard } = require_retrieval_guard();
     var { PostGenerationGuard } = require_post_generation_guard();
     var { detectedText } = require_detectors();
+    var { createRunAbort } = require_run_abort();
     var DEFAULT_CONFIG = {
       preRetrieval: {},
       // PreRetrievalGuard options, or false to disable
@@ -1508,12 +1544,79 @@ var require_guardrails_pipeline = __commonJS({
       strict: false
       // If true, block on any guard failure; if false, warn and continue
     };
+    var DEFAULT_MAX_STREAM_CHARS = 1e6;
+    var RETRIEVAL_SKIPPED_REASON = "retrieval guard could not run: the wrapped pipeline neither called filterResults nor returned results; answer withheld";
     function summarizeFilter(filterOutput) {
       return {
         ...filterOutput,
         removed: filterOutput.removed.map((doc) => ({ id: doc.id }))
       };
     }
+    function isAsyncIterable(value) {
+      return value != null && typeof value === "object" && typeof value[Symbol.asyncIterator] === "function";
+    }
+    function withheldSummary(guardrails) {
+      const out = { ...guardrails };
+      if (out.preRetrieval) {
+        const { sanitizedQuery, injection, ...rest } = out.preRetrieval;
+        out.preRetrieval = {
+          ...rest,
+          ...injection && {
+            injection: {
+              detected: injection.detected,
+              matches: (injection.matches || []).map((m) => ({ id: m && m.id }))
+            }
+          }
+        };
+      }
+      if (out.retrieval && Array.isArray(out.retrieval.results)) {
+        const { results, ...rest } = out.retrieval;
+        out.retrieval = {
+          ...rest,
+          removed: (rest.removed || []).map((doc) => ({ id: doc && doc.id }))
+        };
+      }
+      if (out.postGeneration) {
+        out.postGeneration = { ...out.postGeneration, sanitizedOutput: "" };
+      }
+      return out;
+    }
+    function withheld(error, guardrails) {
+      return { success: false, error, guardrails: withheldSummary(guardrails) };
+    }
+    async function collectStream(source, { signal, timeout, maxChars }) {
+      const iterator = source[Symbol.asyncIterator]();
+      const run = createRunAbort({ timeout, signal });
+      let text = "";
+      let done = null;
+      let overflow = false;
+      try {
+        for (; ; ) {
+          const next = await run.race(iterator.next());
+          if (next.done) break;
+          const chunk = next.value;
+          text += typeof chunk === "string" ? chunk : String((chunk && chunk.token) ?? "");
+          if (chunk && typeof chunk === "object" && chunk.done) {
+            const { token, ...rest } = chunk;
+            done = rest;
+            break;
+          }
+          if (text.length > maxChars) {
+            overflow = true;
+            break;
+          }
+        }
+      } catch (error) {
+        if (iterator.return) Promise.resolve(iterator.return()).catch(() => {
+        });
+        throw error;
+      } finally {
+        run.cleanup();
+      }
+      if (iterator.return) await Promise.resolve(iterator.return()).catch(() => {
+      });
+      return { text, done, overflow };
+    }
     function withReasons(message, check) {
       const issues = check && check.issues || [];
       if (issues.length === 0) return message;
@@ -1545,6 +1648,12 @@ var require_guardrails_pipeline = __commonJS({
       /**
        * Run the full guarded pipeline.
        *
+       * With `options.stream` and a post-generation guard, the token stream is
+       * buffered, checked and redacted as a whole, then released as an async
+       * iterable: one token chunk with the sanitized answer, then a done chunk
+       * carrying the redacted citations/evaluation and the `guardrails` summary.
+       * A strict-mode block yields only a done chunk with `success: false`.
+       *
        * @param {object} input - Pipeline input
        * @param {string} input.query - The user query
        * @param {Float32Array} [input.queryVector] - Optional precomputed query vector
@@ -1553,6 +1662,7 @@ var require_guardrails_pipeline = __commonJS({
        * @returns {Promise<object>} Pipeline result with guardrails metadata attached
        */
       async run(input) {
+        const startedAt = Date.now();
         const guardrails = {
           preRetrieval: null,
           retrieval: null,
@@ -1568,14 +1678,13 @@ var require_guardrails_pipeline = __commonJS({
           );
           this.emit("preRetrieval", guardrails.preRetrieval);
           if (!guardrails.preRetrieval.safe && this.config.strict) {
-            return {
-              success: false,
-              error: withReasons(
+            return withheld(
+              withReasons(
                 "Pre-retrieval guard blocked query",
                 guardrails.preRetrieval
               ),
               guardrails
-            };
+            );
           }
           query = guardrails.preRetrieval.sanitizedQuery;
         }
@@ -1595,10 +1704,11 @@ var require_guardrails_pipeline = __commonJS({
           query,
           options: { ...input.options, citations: true, ...filterOptions }
         });
+        const streaming = isAsyncIterable(result);
         if (this.retrievalGuard && preGenerationFilter) {
           guardrails.retrieval = summarizeFilter(preGenerationFilter);
           this.emit("retrieval", guardrails.retrieval);
-        } else if (this.retrievalGuard && result.results) {
+        } else if (this.retrievalGuard && !streaming && result && Array.isArray(result.results)) {
           guardrails.retrieval = summarizeFilter(
             await this.retrievalGuard.filterAsync(
               result.results,
@@ -1609,12 +1719,29 @@ var require_guardrails_pipeline = __commonJS({
           this.emit("retrieval", guardrails.retrieval);
           result.results = guardrails.retrieval.results;
           if (guardrails.retrieval.metadata.reasons.acl) {
-            return {
-              success: false,
-              error: "Retrieval guard removed access-controlled documents after generation; answer withheld",
+            return withheld(
+              "Retrieval guard removed access-controlled documents after generation; answer withheld",
               guardrails
-            };
+            );
+          }
+        } else if (this.retrievalGuard && this._retrievalChecksActive() && result && (streaming || result.answer || this.retrievalGuard.config.enforceACL && result.success !== false)) {
+          guardrails.retrieval = {
+            skipped: true,
+            reason: RETRIEVAL_SKIPPED_REASON
+          };
+          if (this.retrievalGuard.config.enforceACL || this.config.strict) {
+            return withheld(RETRIEVAL_SKIPPED_REASON, guardrails);
           }
+          this._warnRetrievalSkipped();
+        }
+        if (streaming && this.postGuard) {
+          return this._releaseStream(result, {
+            guardrails,
+            callOptions,
+            signal,
+            timeout: this._remainingTimeout(input, startedAt),
+            docs: preGenerationFilter ? preGenerationFilter.results : void 0
+          });
         }
         if (this.postGuard && result.answer) {
           guardrails.postGeneration = await this.postGuard.checkAsync(
@@ -1624,14 +1751,13 @@ var require_guardrails_pipeline = __commonJS({
           );
           this.emit("postGeneration", guardrails.postGeneration);
           if (!guardrails.postGeneration.safe && this.config.strict) {
-            return {
-              success: false,
-              error: withReasons(
+            return withheld(
+              withReasons(
                 "Post-generation guard flagged output",
                 guardrails.postGeneration
               ),
               guardrails
-            };
+            );
           }
           result.answer = guardrails.postGeneration.sanitizedOutput;
           const found = detectedText(guardrails.postGeneration);
@@ -1641,6 +1767,109 @@ var require_guardrails_pipeline = __commonJS({
         result.guardrails = guardrails;
         return result;
       }
+      /**
+       * Whether the retrieval guard has a check that needs documents.
+       * @private
+       */
+      _retrievalChecksActive() {
+        const c = this.retrievalGuard.config;
+        return Boolean(
+          c.enforceACL || c.detectInjection || c.minRelevanceScore > 0 || c.maxAgeDays > 0
+        );
+      }
+      /**
+       * Milliseconds left of the caller's options.timeout, or undefined.
+       * @private
+       */
+      _remainingTimeout(input, startedAt) {
+        const t = input.options && input.options.timeout;
+        if (typeof t !== "number" || !(t > 0)) return void 0;
+        return Math.max(1, t - (Date.now() - startedAt));
+      }
+      /** @private One warning per pipeline instance. */
+      _warnRetrievalSkipped() {
+        if (this._warnedRetrievalSkipped) return;
+        this._warnedRetrievalSkipped = true;
+        process.emitWarning(
+          "GuardrailsPipeline: the retrieval guard was skipped because the wrapped pipeline neither called options.filterResults nor returned results. Call options.filterResults before generating, or return results.",
+          { code: "RAG_GUARDRAILS_RETRIEVAL_SKIPPED" }
+        );
+      }
+      /**
+       * Collect a token stream, run the post-generation guard on the whole
+       * answer and return an async iterable that yields the sanitized answer as
+       * one token chunk and then the done chunk. A blocked answer yields no
+       * tokens, only a done chunk with the error.
+       *
+       * @private
+       */
+      async _releaseStream(source, { guardrails, callOptions, signal, timeout, docs }) {
+        const limit = this.postGuard.config.maxResponseLength;
+        const maxChars = limit > 0 ? limit : DEFAULT_MAX_STREAM_CHARS;
+        const { text, done, overflow } = await collectStream(source, {
+          signal,
+          timeout,
+          maxChars
+        });
+        let tokenChunk = null;
+        let doneChunk;
+        if (!text) {
+          doneChunk = { ...done, token: "", done: true, guardrails };
+        } else {
+          const check = await this.postGuard.checkAsync(
+            text,
+            done && done.results || docs,
+            callOptions
+          );
+          if (overflow && check.safe) {
+            check.safe = false;
+            check.sanitizedOutput = check.sanitizedOutput.slice(0, maxChars);
+            check.issues.push(
+              `Output exceeds maximum length of ${maxChars} characters`
+            );
+          }
+          guardrails.postGeneration = check;
+          this.emit("postGeneration", check);
+          if (!check.safe && this.config.strict) {
+            doneChunk = {
+              token: "",
+              done: true,
+              ...withheld(
+                withReasons("Post-generation guard flagged output", check),
+                guardrails
+              ),
+              ...done && done.timing && { timing: done.timing }
+            };
+          } else {
+            const found = detectedText(check);
+            const { citations, evaluation, ...rest } = done || {};
+            doneChunk = {
+              ...rest,
+              token: "",
+              done: true,
+              ...citations !== void 0 && {
+                citations: this._redactDeep(citations, found)
+              },
+              ...evaluation !== void 0 && {
+                evaluation: this._redactDeep(evaluation, found)
+              },
+              guardrails
+            };
+            if (check.sanitizedOutput) {
+              tokenChunk = { token: check.sanitizedOutput, done: false };
+            }
+          }
+        }
+        const stream = (async function* released() {
+          if (tokenChunk) yield tokenChunk;
+          yield doneChunk;
+        })();
+        Object.defineProperty(stream, "guardrails", {
+          value: doneChunk.guardrails,
+          enumerable: false
+        });
+        return stream;
+      }
       /**
        * Citations and evaluation details copy sentences from the raw answer, so
        * scrub every string in them with the same PII patterns as the answer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-guardrails",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "description": "Guardrails for RAG: prompt-injection detection and pre-retrieval, retrieval and post-generation guards.",
   "keywords": [
     "rag",
@@ -42,6 +42,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@devilsdev/rag-core": "3.8.0"
+    "@devilsdev/rag-core": "3.8.2"
   }
 }