substrai-guardrailgraph 0.1.0

package/dist/checks/cost.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in cost limiting check.
+ */
+import { Action } from "../core/actions";
+import { Check } from "../core/check";
+export interface CostCheckOptions {
+    maxTokensPerRequest?: number;
+    maxCostPerRequest?: number;
+    costPer1kInputTokens?: number;
+    action?: Action;
+    threshold?: number;
+    name?: string;
+}
+export declare function costCheck(options?: CostCheckOptions): Check;

package/dist/checks/cost.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Built-in cost limiting check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.costCheck = costCheck;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+function costCheck(options = {}) {
+    const { maxTokensPerRequest = 4000, maxCostPerRequest = 0.10, costPer1kInputTokens = 0.00025, action = actions_1.Action.BLOCK, threshold = 0.5, name = "cost-limit", } = options;
+    return new check_1.Check((text) => {
+        const estimatedTokens = Math.max(1, Math.floor(text.length / 4));
+        const estimatedCost = (estimatedTokens / 1000) * costPer1kInputTokens;
+        const tokenExceeded = estimatedTokens > maxTokensPerRequest;
+        const costExceeded = estimatedCost > maxCostPerRequest;
+        const detected = tokenExceeded || costExceeded;
+        return {
+            detected,
+            confidence: detected ? 1.0 : 0.0,
+            estimatedTokens,
+            estimatedCostUsd: estimatedCost,
+            maxTokens: maxTokensPerRequest,
+            maxCostUsd: maxCostPerRequest,
+            tokenExceeded,
+            costExceeded,
+        };
+    }, { name, action, threshold });
+}

package/dist/checks/index.d.ts

@@ -0,0 +1,5 @@
+export { piiCheck, PiiCheckOptions } from "./pii";
+export { toxicityCheck, ToxicityCheckOptions } from "./toxicity";
+export { topicCheck, TopicCheckOptions } from "./topics";
+export { injectionCheck, InjectionCheckOptions } from "./injection";
+export { costCheck, CostCheckOptions } from "./cost";

package/dist/checks/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.costCheck = exports.injectionCheck = exports.topicCheck = exports.toxicityCheck = exports.piiCheck = void 0;
+var pii_1 = require("./pii");
+Object.defineProperty(exports, "piiCheck", { enumerable: true, get: function () { return pii_1.piiCheck; } });
+var toxicity_1 = require("./toxicity");
+Object.defineProperty(exports, "toxicityCheck", { enumerable: true, get: function () { return toxicity_1.toxicityCheck; } });
+var topics_1 = require("./topics");
+Object.defineProperty(exports, "topicCheck", { enumerable: true, get: function () { return topics_1.topicCheck; } });
+var injection_1 = require("./injection");
+Object.defineProperty(exports, "injectionCheck", { enumerable: true, get: function () { return injection_1.injectionCheck; } });
+var cost_1 = require("./cost");
+Object.defineProperty(exports, "costCheck", { enumerable: true, get: function () { return cost_1.costCheck; } });

package/dist/checks/injection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in prompt injection detection check.
+ */
+import { Action } from "../core/actions";
+import { Check } from "../core/check";
+export interface InjectionCheckOptions {
+    sensitivity?: "low" | "medium" | "high";
+    action?: Action;
+    threshold?: number;
+    name?: string;
+}
+export declare function injectionCheck(options?: InjectionCheckOptions): Check;

package/dist/checks/injection.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Built-in prompt injection detection check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectionCheck = injectionCheck;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+const INJECTION_PATTERNS = [
+    {
+        name: "instruction_override",
+        patterns: [
+            /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?|rules?)/i,
+            /disregard\s+(all\s+)?(previous|prior|above)/i,
+            /forget\s+(everything|all|your)\s+(instructions?|rules?|training)/i,
+            /override\s+(your|the|all)\s+(instructions?|rules?|constraints?)/i,
+            /new\s+instructions?\s*:/i,
+        ],
+        severity: 0.95,
+        category: "override",
+    },
+    {
+        name: "role_manipulation",
+        patterns: [
+            /you\s+are\s+now\s+(?:a\s+)?(?:DAN|evil|unrestricted|jailbroken)/i,
+            /pretend\s+(?:you\s+are|to\s+be)\s+(?:a\s+)?(?:different|evil|unrestricted)/i,
+            /act\s+as\s+(?:if|though)\s+you\s+(?:have\s+)?no\s+(?:rules|restrictions|limits)/i,
+            /enter\s+(?:DAN|developer|admin|god)\s+mode/i,
+        ],
+        severity: 0.9,
+        category: "role_play",
+    },
+    {
+        name: "system_prompt_extraction",
+        patterns: [
+            /(?:show|reveal|display|print|output)\s+(?:me\s+)?(?:your|the)\s+(?:system\s+)?(?:prompt|instructions)/i,
+            /what\s+(?:are|is)\s+your\s+(?:system\s+)?(?:prompt|instructions|rules)/i,
+            /repeat\s+(?:your|the)\s+(?:system\s+)?(?:prompt|instructions)\s+(?:back|verbatim)/i,
+        ],
+        severity: 0.8,
+        category: "extraction",
+    },
+    {
+        name: "delimiter_injection",
+        patterns: [
+            /<\/?system>/i,
+            /\[\/?INST\]/i,
+            /```\s*system/i,
+            /<\|(?:im_start|im_end|system|endoftext)\|>/i,
+        ],
+        severity: 0.85,
+        category: "delimiter",
+    },
+];
+function injectionCheck(options = {}) {
+    const { sensitivity = "high", action = actions_1.Action.BLOCK, threshold = 0.6, name = "prompt-injection", } = options;
+    const thresholdMap = { low: 0.9, medium: 0.75, high: 0.6 };
+    const sensitivityThreshold = thresholdMap[sensitivity] || 0.75;
+    return new check_1.Check((text) => {
+        const matches = [];
+        let maxSeverity = 0;
+        for (const group of INJECTION_PATTERNS) {
+            for (const pattern of group.patterns) {
+                if (pattern.test(text)) {
+                    matches.push({ name: group.name, category: group.category, severity: group.severity });
+                    maxSeverity = Math.max(maxSeverity, group.severity);
+                    break;
+                }
+            }
+        }
+        const detected = maxSeverity >= sensitivityThreshold;
+        return {
+            detected,
+            confidence: maxSeverity,
+            matches,
+            matchCount: matches.length,
+            categories: [...new Set(matches.map((m) => m.category))],
+        };
+    }, { name, action, threshold });
+}

package/dist/checks/pii.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in PII detection and redaction check.
+ */
+import { Action } from "../core/actions";
+import { Check } from "../core/check";
+export interface PiiCheckOptions {
+    entityTypes?: string[];
+    redactionChar?: string;
+    sensitivity?: string;
+    action?: Action;
+    threshold?: number;
+    name?: string;
+}
+export declare function piiCheck(options?: PiiCheckOptions): Check;

package/dist/checks/pii.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Built-in PII detection and redaction check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.piiCheck = piiCheck;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+const PII_PATTERNS = {
+    SSN: /\b\d{3}-\d{2}-\d{4}\b/g,
+    PHONE: /\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    EMAIL: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    CREDIT_CARD: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+    IP_ADDRESS: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    DATE_OF_BIRTH: /\b(?:0[1-9]|1[0-2])[/-](?:0[1-9]|[12]\d|3[01])[/-](?:19|20)\d{2}\b/g,
+};
+function detectPii(text, entityTypes) {
+    const entities = [];
+    const patterns = entityTypes
+        ? Object.entries(PII_PATTERNS).filter(([k]) => entityTypes.includes(k))
+        : Object.entries(PII_PATTERNS);
+    for (const [type, pattern] of patterns) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            entities.push({
+                type,
+                value: match[0],
+                start: match.index,
+                end: match.index + match[0].length,
+                confidence: 0.95,
+            });
+        }
+    }
+    return entities.sort((a, b) => a.start - b.start);
+}
+function redactText(text, entities) {
+    let result = text;
+    const sorted = [...entities].sort((a, b) => b.start - a.start);
+    for (const entity of sorted) {
+        result = result.slice(0, entity.start) + `[${entity.type}]` + result.slice(entity.end);
+    }
+    return result;
+}
+function piiCheck(options = {}) {
+    const { entityTypes, action = actions_1.Action.REDACT, threshold = 0.5, name = "pii-detection" } = options;
+    return new check_1.Check((text) => {
+        const entities = detectPii(text, entityTypes);
+        if (entities.length === 0) {
+            return { detected: false, confidence: 0 };
+        }
+        const maxConfidence = Math.max(...entities.map((e) => e.confidence));
+        const redacted = redactText(text, entities);
+        return {
+            detected: true,
+            confidence: maxConfidence,
+            entities: entities.map((e) => ({ type: e.type, value: e.value })),
+            redactedText: redacted,
+            entityCount: entities.length,
+            entityTypes: [...new Set(entities.map((e) => e.type))],
+        };
+    }, { name, action, threshold });
+}

package/dist/checks/topics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in topic restriction check.
+ */
+import { Action } from "../core/actions";
+import { Check } from "../core/check";
+export interface TopicCheckOptions {
+    blockedTopics?: string[];
+    allowedTopics?: string[];
+    mode?: "blocklist" | "allowlist";
+    action?: Action;
+    threshold?: number;
+    name?: string;
+}
+export declare function topicCheck(options?: TopicCheckOptions): Check;

package/dist/checks/topics.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Built-in topic restriction check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topicCheck = topicCheck;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+function topicCheck(options = {}) {
+    const { blockedTopics = [], allowedTopics = [], mode = "blocklist", action = actions_1.Action.BLOCK, threshold = 0.5, name = "topic-restriction", } = options;
+    return new check_1.Check((text) => {
+        const textLower = text.toLowerCase();
+        if (mode === "blocklist") {
+            const matched = blockedTopics.filter((t) => textLower.includes(t.toLowerCase()));
+            return {
+                detected: matched.length > 0,
+                confidence: matched.length > 0 ? 1.0 : 0.0,
+                matchedTopics: matched,
+                mode: "blocklist",
+            };
+        }
+        else {
+            const matched = allowedTopics.filter((t) => textLower.includes(t.toLowerCase()));
+            if (matched.length > 0) {
+                return { detected: false, confidence: 0, matchedTopics: matched, mode: "allowlist" };
+            }
+            return {
+                detected: true,
+                confidence: 0.8,
+                matchedTopics: [],
+                mode: "allowlist",
+                reason: "Content does not match any allowed topic",
+            };
+        }
+    }, { name, action, threshold });
+}

package/dist/checks/toxicity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in toxicity detection check.
+ */
+import { Action } from "../core/actions";
+import { Check } from "../core/check";
+export interface ToxicityCheckOptions {
+    categories?: string[];
+    threshold?: number;
+    action?: Action;
+    name?: string;
+}
+export declare function toxicityCheck(options?: ToxicityCheckOptions): Check;

package/dist/checks/toxicity.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Built-in toxicity detection check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toxicityCheck = toxicityCheck;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+const TOXICITY_KEYWORDS = {
+    hate: ["hate", "racist", "bigot", "supremacist", "inferior race", "ethnic slur", "discrimination"],
+    violence: ["kill", "murder", "attack", "bomb", "shoot", "stab", "assault", "destroy", "weapon", "explosive"],
+    sexual: ["explicit", "pornographic", "nude", "sexual act"],
+    self_harm: ["suicide", "self-harm", "cut myself", "end my life", "kill myself", "overdose"],
+    harassment: ["threaten", "bully", "stalk", "intimidate", "harass", "doxx", "blackmail"],
+};
+const CATEGORY_WEIGHTS = {
+    hate: 0.9,
+    violence: 0.95,
+    sexual: 0.7,
+    self_harm: 1.0,
+    harassment: 0.85,
+};
+function toxicityCheck(options = {}) {
+    const { categories, threshold = 0.7, action = actions_1.Action.BLOCK, name = "toxicity", } = options;
+    const activeCategories = categories || Object.keys(TOXICITY_KEYWORDS);
+    return new check_1.Check((text) => {
+        const textLower = text.toLowerCase();
+        const categoryScores = {};
+        const matchedTerms = {};
+        for (const category of activeCategories) {
+            const keywords = TOXICITY_KEYWORDS[category] || [];
+            const matches = keywords.filter((kw) => textLower.includes(kw));
+            if (matches.length > 0) {
+                const weight = CATEGORY_WEIGHTS[category] || 0.8;
+                categoryScores[category] = Math.min(matches.length / 3.0, 1.0) * weight;
+                matchedTerms[category] = matches;
+            }
+            else {
+                categoryScores[category] = 0;
+            }
+        }
+        const overallScore = Math.max(...Object.values(categoryScores), 0);
+        return {
+            detected: overallScore >= threshold,
+            confidence: overallScore,
+            categoryScores,
+            matchedTerms,
+        };
+    }, { name, action, threshold });
+}

package/dist/core/actions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Action definitions for guardrail check outcomes.
+ */
+export declare enum Action {
+    PASS = "pass",
+    BLOCK = "block",
+    REDACT = "redact",
+    FLAG_FOR_REVIEW = "flag_for_review",
+    LOG = "log"
+}
+export declare function isBlocking(action: Action): boolean;
+export declare function isModifying(action: Action): boolean;

package/dist/core/actions.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Action definitions for guardrail check outcomes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Action = void 0;
+exports.isBlocking = isBlocking;
+exports.isModifying = isModifying;
+var Action;
+(function (Action) {
+    Action["PASS"] = "pass";
+    Action["BLOCK"] = "block";
+    Action["REDACT"] = "redact";
+    Action["FLAG_FOR_REVIEW"] = "flag_for_review";
+    Action["LOG"] = "log";
+})(Action || (exports.Action = Action = {}));
+function isBlocking(action) {
+    return action === Action.BLOCK;
+}
+function isModifying(action) {
+    return action === Action.REDACT;
+}

package/dist/core/check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The Check class and check() factory — turns functions into guardrail checks.
+ */
+import { Action } from "./actions";
+import { CheckContext } from "./context";
+import { CheckResult } from "./result";
+export type CheckFunction = (text: string, context?: CheckContext) => CheckFunctionResult | Promise<CheckFunctionResult>;
+export type CheckFunctionResult = {
+    detected: boolean;
+    confidence: number;
+    redactedText?: string;
+    [key: string]: any;
+} | boolean;
+export interface CheckOptions {
+    name?: string;
+    action?: Action;
+    threshold?: number;
+    description?: string;
+    tags?: string[];
+    dependsOn?: string[];
+    timeoutMs?: number;
+}
+export declare class Check {
+    readonly name: string;
+    readonly action: Action;
+    readonly threshold: number;
+    readonly description: string;
+    readonly tags: string[];
+    readonly dependsOn: string[];
+    readonly timeoutMs?: number;
+    private readonly fn;
+    constructor(fn: CheckFunction, options?: CheckOptions);
+    execute(text: string, context?: CheckContext): Promise<CheckResult>;
+    executeSync(text: string, context?: CheckContext): CheckResult;
+    private normalizeResult;
+}
+/**
+ * Factory function to create a Check instance.
+ */
+export declare function check(options?: CheckOptions): (fn: CheckFunction) => Check;

package/dist/core/check.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * The Check class and check() factory — turns functions into guardrail checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Check = void 0;
+exports.check = check;
+const actions_1 = require("./actions");
+const context_1 = require("./context");
+class Check {
+    constructor(fn, options = {}) {
+        this.fn = fn;
+        this.name = options.name || fn.name || "unnamed-check";
+        this.action = options.action || actions_1.Action.BLOCK;
+        this.threshold = options.threshold ?? 0.5;
+        this.description = options.description || "";
+        this.tags = options.tags || [];
+        this.dependsOn = options.dependsOn || [];
+        this.timeoutMs = options.timeoutMs;
+    }
+    async execute(text, context) {
+        const start = Date.now();
+        const ctx = context || (0, context_1.createContext)();
+        try {
+            const raw = await this.fn(text, ctx);
+            const result = this.normalizeResult(raw);
+            result.latencyMs = Date.now() - start;
+            return result;
+        }
+        catch (err) {
+            return {
+                name: this.name,
+                detected: false,
+                confidence: 0,
+                action: actions_1.Action.PASS,
+                details: {},
+                latencyMs: Date.now() - start,
+                error: `Check failed: ${err.message || err}`,
+            };
+        }
+    }
+    executeSync(text, context) {
+        // For sync contexts, we run the function directly if it's not async
+        const start = Date.now();
+        const ctx = context || (0, context_1.createContext)();
+        try {
+            const raw = this.fn(text, ctx);
+            if (raw instanceof Promise) {
+                throw new Error("Cannot run async check synchronously. Use execute() instead.");
+            }
+            const result = this.normalizeResult(raw);
+            result.latencyMs = Date.now() - start;
+            return result;
+        }
+        catch (err) {
+            return {
+                name: this.name,
+                detected: false,
+                confidence: 0,
+                action: actions_1.Action.PASS,
+                details: {},
+                latencyMs: Date.now() - start,
+                error: `Check failed: ${err.message || err}`,
+            };
+        }
+    }
+    normalizeResult(raw) {
+        if (typeof raw === "boolean") {
+            return {
+                name: this.name,
+                detected: raw,
+                confidence: raw ? 1.0 : 0.0,
+                action: raw ? this.action : actions_1.Action.PASS,
+                details: {},
+                latencyMs: 0,
+            };
+        }
+        const detected = raw.detected && raw.confidence >= this.threshold;
+        const { detected: _d, confidence: _c, redactedText, ...rest } = raw;
+        return {
+            name: this.name,
+            detected,
+            confidence: raw.confidence,
+            action: detected ? this.action : actions_1.Action.PASS,
+            details: rest,
+            latencyMs: 0,
+            redactedText: redactedText,
+        };
+    }
+}
+exports.Check = Check;
+/**
+ * Factory function to create a Check instance.
+ */
+function check(options = {}) {
+    return (fn) => {
+        return new Check(fn, {
+            ...options,
+            name: options.name || fn.name?.replace(/_/g, "-") || "unnamed-check",
+        });
+    };
+}

package/dist/core/context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Check execution context — provides runtime info to checks.
+ */
+export interface CheckContext {
+    pipelineName: string;
+    environment: string;
+    config: Record<string, any>;
+    metadata: Record<string, any>;
+    shared: Record<string, any>;
+}
+export declare function createContext(partial?: Partial<CheckContext>): CheckContext;

package/dist/core/context.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Check execution context — provides runtime info to checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContext = createContext;
+function createContext(partial) {
+    return {
+        pipelineName: "",
+        environment: "dev",
+        config: {},
+        metadata: {},
+        shared: {},
+        ...partial,
+    };
+}

package/dist/core/pipeline.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pipeline builder and DAG executor — the orchestration engine.
+ */
+import { Check } from "./check";
+import { CheckContext } from "./context";
+import { PipelineResult } from "./result";
+export interface PipelineOptions {
+    name?: string;
+    checks?: Check[];
+    packs?: Array<{
+        checks: Check[];
+    } | Check[]>;
+    mode?: "fail-closed" | "fail-open" | "log-only";
+    timeoutMs?: number;
+    onBlock?: (result: PipelineResult) => void;
+    onFlag?: (result: PipelineResult) => void;
+    onPass?: (result: PipelineResult) => void;
+    parallel?: boolean;
+    metadata?: Record<string, any>;
+}
+export declare class Pipeline {
+    readonly name: string;
+    checks: Check[];
+    readonly mode: string;
+    readonly timeoutMs: number;
+    readonly onBlock?: (result: PipelineResult) => void;
+    readonly onFlag?: (result: PipelineResult) => void;
+    readonly onPass?: (result: PipelineResult) => void;
+    readonly parallel: boolean;
+    readonly metadata: Record<string, any>;
+    constructor(options?: PipelineOptions);
+    addCheck(check: Check): this;
+    removeCheck(name: string): this;
+    run(text: string, context?: CheckContext, metadata?: Record<string, any>): Promise<PipelineResult>;
+    private buildExecutionPlan;
+    private determineFinalAction;
+}
+/**
+ * Create a guardrail pipeline.
+ */
+export declare function pipeline(options?: PipelineOptions): Pipeline;

package/dist/core/pipeline.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Pipeline builder and DAG executor — the orchestration engine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pipeline = void 0;
+exports.pipeline = pipeline;
+const actions_1 = require("./actions");
+const context_1 = require("./context");
+class Pipeline {
+    constructor(options = {}) {
+        this.name = options.name || "default";
+        this.checks = [];
+        this.mode = options.mode || "fail-closed";
+        this.timeoutMs = options.timeoutMs || 5000;
+        this.onBlock = options.onBlock;
+        this.onFlag = options.onFlag;
+        this.onPass = options.onPass;
+        this.parallel = options.parallel !== false;
+        this.metadata = options.metadata || {};
+        // Register checks
+        if (options.checks) {
+            for (const c of options.checks) {
+                this.addCheck(c);
+            }
+        }
+        // Register packs
+        if (options.packs) {
+            for (const pack of options.packs) {
+                const packChecks = Array.isArray(pack) ? pack : pack.checks;
+                for (const c of packChecks) {
+                    this.addCheck(c);
+                }
+            }
+        }
+    }
+    addCheck(check) {
+        this.checks.push(check);
+        return this;
+    }
+    removeCheck(name) {
+        this.checks = this.checks.filter((c) => c.name !== name);
+        return this;
+    }
+    async run(text, context, metadata) {
+        const start = Date.now();
+        const ctx = context || (0, context_1.createContext)({ pipelineName: this.name });
+        if (metadata) {
+            Object.assign(ctx.metadata, metadata);
+        }
+        // Build execution layers
+        const layers = this.buildExecutionPlan();
+        const allResults = [];
+        let currentText = text;
+        let blocked = false;
+        for (const layer of layers) {
+            if (blocked && this.mode === "fail-closed")
+                break;
+            let layerResults;
+            if (this.parallel && layer.length > 1) {
+                layerResults = await Promise.all(layer.map((check) => check.execute(currentText, ctx)));
+            }
+            else {
+                layerResults = [];
+                for (const check of layer) {
+                    const result = await check.execute(currentText, ctx);
+                    layerResults.push(result);
+                }
+            }
+            for (const result of layerResults) {
+                allResults.push(result);
+                if (result.detected && result.action === actions_1.Action.REDACT && result.redactedText) {
+                    currentText = result.redactedText;
+                }
+                if (result.detected && (0, actions_1.isBlocking)(result.action) && this.mode !== "log-only") {
+                    blocked = true;
+                }
+            }
+        }
+        const finalAction = this.determineFinalAction(allResults);
+        const allowed = this.mode === "log-only" ? true : !blocked;
+        const pipelineResult = {
+            allowed,
+            action: finalAction,
+            checkResults: allResults,
+            modifiedText: currentText !== text ? currentText : undefined,
+            originalText: text,
+            totalLatencyMs: Date.now() - start,
+            pipelineName: this.name,
+            metadata: this.metadata,
+        };
+        // Fire callbacks
+        if (!allowed && this.onBlock)
+            this.onBlock(pipelineResult);
+        else if (allResults.some((r) => r.detected && r.action === actions_1.Action.FLAG_FOR_REVIEW) &&
+            this.onFlag) {
+            this.onFlag(pipelineResult);
+        }
+        else if (allowed && this.onPass) {
+            this.onPass(pipelineResult);
+        }
+        return pipelineResult;
+    }
+    buildExecutionPlan() {
+        if (this.checks.length === 0)
+            return [];
+        const checkMap = new Map(this.checks.map((c) => [c.name, c]));
+        const inDegree = new Map(this.checks.map((c) => [c.name, 0]));
+        const dependents = new Map();
+        for (const c of this.checks) {
+            for (const dep of c.dependsOn) {
+                if (checkMap.has(dep)) {
+                    inDegree.set(c.name, (inDegree.get(c.name) || 0) + 1);
+                    const deps = dependents.get(dep) || [];
+                    deps.push(c.name);
+                    dependents.set(dep, deps);
+                }
+            }
+        }
+        const layers = [];
+        let ready = [...inDegree.entries()]
+            .filter(([_, deg]) => deg === 0)
+            .map(([name]) => name);
+        while (ready.length > 0) {
+            layers.push(ready.map((name) => checkMap.get(name)));
+            const nextReady = [];
+            for (const name of ready) {
+                for (const depName of dependents.get(name) || []) {
+                    const newDeg = (inDegree.get(depName) || 1) - 1;
+                    inDegree.set(depName, newDeg);
+                    if (newDeg === 0)
+                        nextReady.push(depName);
+                }
+            }
+            ready = nextReady;
+        }
+        return layers;
+    }
+    determineFinalAction(results) {
+        const severity = {
+            [actions_1.Action.BLOCK]: 4,
+            [actions_1.Action.FLAG_FOR_REVIEW]: 3,
+            [actions_1.Action.REDACT]: 2,
+            [actions_1.Action.LOG]: 1,
+            [actions_1.Action.PASS]: 0,
+        };
+        let maxAction = actions_1.Action.PASS;
+        let maxSeverity = 0;
+        for (const result of results) {
+            if (result.detected) {
+                const s = severity[result.action] || 0;
+                if (s > maxSeverity) {
+                    maxSeverity = s;
+                    maxAction = result.action;
+                }
+            }
+        }
+        return maxAction;
+    }
+}
+exports.Pipeline = Pipeline;
+/**
+ * Create a guardrail pipeline.
+ */
+function pipeline(options = {}) {
+    return new Pipeline(options);
+}

package/dist/core/result.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Result types for check execution and pipeline outcomes.
+ */
+import { Action } from "./actions";
+export interface CheckResult {
+    name: string;
+    detected: boolean;
+    confidence: number;
+    action: Action;
+    details: Record<string, any>;
+    latencyMs: number;
+    redactedText?: string;
+    error?: string;
+}
+export interface PipelineResult {
+    allowed: boolean;
+    action: Action;
+    checkResults: CheckResult[];
+    modifiedText?: string;
+    originalText?: string;
+    totalLatencyMs: number;
+    pipelineName: string;
+    metadata: Record<string, any>;
+}
+export declare function createCheckResult(partial: Partial<CheckResult> & {
+    name: string;
+}): CheckResult;
+export declare function createPipelineResult(partial: Partial<PipelineResult>): PipelineResult;

package/dist/core/result.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Result types for check execution and pipeline outcomes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCheckResult = createCheckResult;
+exports.createPipelineResult = createPipelineResult;
+const actions_1 = require("./actions");
+function createCheckResult(partial) {
+    return {
+        detected: false,
+        confidence: 0,
+        action: actions_1.Action.PASS,
+        details: {},
+        latencyMs: 0,
+        ...partial,
+    };
+}
+function createPipelineResult(partial) {
+    return {
+        allowed: true,
+        action: actions_1.Action.PASS,
+        checkResults: [],
+        totalLatencyMs: 0,
+        pipelineName: "",
+        metadata: {},
+        ...partial,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GuardrailGraph — Composable AI safety pipeline framework.
+ *
+ * @packageDocumentation
+ */
+export { Action, isBlocking, isModifying } from "./core/actions";
+export { Check, check, CheckOptions, CheckFunction, CheckFunctionResult } from "./core/check";
+export { Pipeline, pipeline, PipelineOptions } from "./core/pipeline";
+export { CheckResult, PipelineResult, createCheckResult, createPipelineResult } from "./core/result";
+export { CheckContext, createContext } from "./core/context";
+export { piiCheck, PiiCheckOptions } from "./checks/pii";
+export { toxicityCheck, ToxicityCheckOptions } from "./checks/toxicity";
+export { topicCheck, TopicCheckOptions } from "./checks/topics";
+export { injectionCheck, InjectionCheckOptions } from "./checks/injection";
+export { costCheck, CostCheckOptions } from "./checks/cost";
+export * as hipaa from "./packs/hipaa";
+export * as financial from "./packs/financial";
+export { GuardrailMiddleware, MiddlewareOptions, wrapLlmCall } from "./middleware";

package/dist/index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * GuardrailGraph — Composable AI safety pipeline framework.
+ *
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapLlmCall = exports.GuardrailMiddleware = exports.financial = exports.hipaa = exports.costCheck = exports.injectionCheck = exports.topicCheck = exports.toxicityCheck = exports.piiCheck = exports.createContext = exports.createPipelineResult = exports.createCheckResult = exports.pipeline = exports.Pipeline = exports.check = exports.Check = exports.isModifying = exports.isBlocking = exports.Action = void 0;
+// Core
+var actions_1 = require("./core/actions");
+Object.defineProperty(exports, "Action", { enumerable: true, get: function () { return actions_1.Action; } });
+Object.defineProperty(exports, "isBlocking", { enumerable: true, get: function () { return actions_1.isBlocking; } });
+Object.defineProperty(exports, "isModifying", { enumerable: true, get: function () { return actions_1.isModifying; } });
+var check_1 = require("./core/check");
+Object.defineProperty(exports, "Check", { enumerable: true, get: function () { return check_1.Check; } });
+Object.defineProperty(exports, "check", { enumerable: true, get: function () { return check_1.check; } });
+var pipeline_1 = require("./core/pipeline");
+Object.defineProperty(exports, "Pipeline", { enumerable: true, get: function () { return pipeline_1.Pipeline; } });
+Object.defineProperty(exports, "pipeline", { enumerable: true, get: function () { return pipeline_1.pipeline; } });
+var result_1 = require("./core/result");
+Object.defineProperty(exports, "createCheckResult", { enumerable: true, get: function () { return result_1.createCheckResult; } });
+Object.defineProperty(exports, "createPipelineResult", { enumerable: true, get: function () { return result_1.createPipelineResult; } });
+var context_1 = require("./core/context");
+Object.defineProperty(exports, "createContext", { enumerable: true, get: function () { return context_1.createContext; } });
+// Built-in checks
+var pii_1 = require("./checks/pii");
+Object.defineProperty(exports, "piiCheck", { enumerable: true, get: function () { return pii_1.piiCheck; } });
+var toxicity_1 = require("./checks/toxicity");
+Object.defineProperty(exports, "toxicityCheck", { enumerable: true, get: function () { return toxicity_1.toxicityCheck; } });
+var topics_1 = require("./checks/topics");
+Object.defineProperty(exports, "topicCheck", { enumerable: true, get: function () { return topics_1.topicCheck; } });
+var injection_1 = require("./checks/injection");
+Object.defineProperty(exports, "injectionCheck", { enumerable: true, get: function () { return injection_1.injectionCheck; } });
+var cost_1 = require("./checks/cost");
+Object.defineProperty(exports, "costCheck", { enumerable: true, get: function () { return cost_1.costCheck; } });
+// Industry packs
+exports.hipaa = __importStar(require("./packs/hipaa"));
+exports.financial = __importStar(require("./packs/financial"));
+// Middleware
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "GuardrailMiddleware", { enumerable: true, get: function () { return middleware_1.GuardrailMiddleware; } });
+Object.defineProperty(exports, "wrapLlmCall", { enumerable: true, get: function () { return middleware_1.wrapLlmCall; } });

package/dist/middleware/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Middleware layer — integrate guardrails with any LLM provider.
+ */
+import { Pipeline } from "../core/pipeline";
+import { CheckContext } from "../core/context";
+import { PipelineResult } from "../core/result";
+export interface MiddlewareOptions {
+    pipeline: Pipeline;
+    applyTo?: "input" | "output" | "both";
+    onBlockResponse?: string;
+}
+export declare class GuardrailMiddleware {
+    private pipeline;
+    private applyTo;
+    private onBlockResponse;
+    constructor(options: MiddlewareOptions);
+    processInput(text: string, context?: CheckContext): Promise<PipelineResult>;
+    processOutput(text: string, context?: CheckContext): Promise<PipelineResult>;
+    wrap<T extends (text: string, ...args: any[]) => any>(llmCall: T): (text: string, ...args: any[]) => Promise<{
+        blocked: boolean;
+        response: string;
+        guardrailResult: PipelineResult;
+    } | {
+        blocked: boolean;
+        response: string;
+        guardrailResult?: undefined;
+    }>;
+}
+export declare function wrapLlmCall<T extends (text: string, ...args: any[]) => any>(llmCall: T, pipeline: Pipeline, applyTo?: "input" | "output" | "both"): (text: string, ...args: any[]) => Promise<{
+    blocked: boolean;
+    response: string;
+    guardrailResult: PipelineResult;
+} | {
+    blocked: boolean;
+    response: string;
+    guardrailResult?: undefined;
+}>;

package/dist/middleware/index.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Middleware layer — integrate guardrails with any LLM provider.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardrailMiddleware = void 0;
+exports.wrapLlmCall = wrapLlmCall;
+const actions_1 = require("../core/actions");
+class GuardrailMiddleware {
+    constructor(options) {
+        this.pipeline = options.pipeline;
+        this.applyTo = options.applyTo || "both";
+        this.onBlockResponse = options.onBlockResponse || "I cannot process this request due to content policy.";
+    }
+    async processInput(text, context) {
+        if (this.applyTo === "input" || this.applyTo === "both") {
+            return this.pipeline.run(text, context);
+        }
+        return { allowed: true, action: actions_1.Action.PASS, checkResults: [], totalLatencyMs: 0, pipelineName: this.pipeline.name, metadata: {} };
+    }
+    async processOutput(text, context) {
+        if (this.applyTo === "output" || this.applyTo === "both") {
+            return this.pipeline.run(text, context);
+        }
+        return { allowed: true, action: actions_1.Action.PASS, checkResults: [], totalLatencyMs: 0, pipelineName: this.pipeline.name, metadata: {} };
+    }
+    wrap(llmCall) {
+        const middleware = this;
+        return async (text, ...args) => {
+            const inputResult = await middleware.processInput(text);
+            if (!inputResult.allowed) {
+                return { blocked: true, response: middleware.onBlockResponse, guardrailResult: inputResult };
+            }
+            const effectiveText = inputResult.modifiedText || text;
+            const llmResponse = await llmCall(effectiveText, ...args);
+            const responseText = typeof llmResponse === "string" ? llmResponse : String(llmResponse);
+            const outputResult = await middleware.processOutput(responseText);
+            if (!outputResult.allowed) {
+                return { blocked: true, response: middleware.onBlockResponse, guardrailResult: outputResult };
+            }
+            return { blocked: false, response: outputResult.modifiedText || responseText };
+        };
+    }
+}
+exports.GuardrailMiddleware = GuardrailMiddleware;
+function wrapLlmCall(llmCall, pipeline, applyTo = "both") {
+    const middleware = new GuardrailMiddleware({ pipeline, applyTo });
+    return middleware.wrap(llmCall);
+}

package/dist/packs/financial.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Financial Compliance Pack — SOX guardrails.
+ */
+import { Check } from "../core/check";
+export interface FinancialPack {
+    checks: Check[];
+}
+export declare function sox(): FinancialPack;

package/dist/packs/financial.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Financial Compliance Pack — SOX guardrails.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sox = sox;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+const FINANCIAL_ADVICE_KEYWORDS = [
+    "you should invest", "buy this stock", "sell your",
+    "guaranteed returns", "financial advice", "investment recommendation",
+    "i recommend buying", "this stock will", "market prediction",
+    "insider tip", "sure thing", "can't lose",
+];
+const INSIDER_KEYWORDS = [
+    "insider information", "non-public", "material information",
+    "before the announcement", "confidential deal", "merger talks",
+    "earnings surprise", "undisclosed", "tip from",
+];
+function financialAdviceDetection() {
+    return new check_1.Check((text) => {
+        const textLower = text.toLowerCase();
+        const matched = FINANCIAL_ADVICE_KEYWORDS.filter((kw) => textLower.includes(kw));
+        if (matched.length === 0)
+            return { detected: false, confidence: 0 };
+        return {
+            detected: true,
+            confidence: Math.min(matched.length / 2.0, 1.0),
+            matchedKeywords: matched,
+            category: "financial_advice",
+        };
+    }, { name: "financial-advice-detection", action: actions_1.Action.BLOCK, threshold: 0.6 });
+}
+function insiderInfoDetection() {
+    return new check_1.Check((text) => {
+        const textLower = text.toLowerCase();
+        const matched = INSIDER_KEYWORDS.filter((kw) => textLower.includes(kw));
+        if (matched.length === 0)
+            return { detected: false, confidence: 0 };
+        return {
+            detected: true,
+            confidence: Math.min(matched.length / 2.0, 1.0),
+            matchedKeywords: matched,
+            category: "insider_information",
+        };
+    }, { name: "insider-info-detection", action: actions_1.Action.BLOCK, threshold: 0.7 });
+}
+function soxAuditLogging() {
+    return new check_1.Check((text) => ({
+        detected: true,
+        confidence: 1.0,
+        auditRecord: { timestamp: Date.now(), textLength: text.length, framework: "SOX" },
+    }), { name: "sox-audit-log", action: actions_1.Action.LOG, threshold: 0 });
+}
+function sox() {
+    return {
+        checks: [financialAdviceDetection(), insiderInfoDetection(), soxAuditLogging()],
+    };
+}

package/dist/packs/hipaa.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HIPAA Compliance Pack — healthcare AI safety guardrails.
+ */
+import { Check } from "../core/check";
+export interface HipaaPack {
+    checks: Check[];
+}
+export declare function full(): HipaaPack;
+export declare function basic(): HipaaPack;

package/dist/packs/hipaa.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * HIPAA Compliance Pack — healthcare AI safety guardrails.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.full = full;
+exports.basic = basic;
+const actions_1 = require("../core/actions");
+const check_1 = require("../core/check");
+const pii_1 = require("../checks/pii");
+const MEDICAL_CLAIM_KEYWORDS = [
+    "you have", "you are diagnosed", "your diagnosis is",
+    "i recommend", "you should take", "prescribe",
+    "your condition", "treatment plan", "prognosis",
+    "medical advice", "clinical recommendation",
+];
+function phiDetection() {
+    return (0, pii_1.piiCheck)({
+        entityTypes: ["SSN", "PHONE", "EMAIL", "DATE_OF_BIRTH", "IP_ADDRESS"],
+        action: actions_1.Action.REDACT,
+        name: "phi-detection",
+    });
+}
+function medicalClaimDetection() {
+    return new check_1.Check((text) => {
+        const textLower = text.toLowerCase();
+        const matched = MEDICAL_CLAIM_KEYWORDS.filter((kw) => textLower.includes(kw));
+        if (matched.length === 0) {
+            return { detected: false, confidence: 0 };
+        }
+        return {
+            detected: true,
+            confidence: Math.min(matched.length / 3.0, 1.0),
+            matchedClaims: matched,
+            claimCount: matched.length,
+        };
+    }, { name: "medical-claim-detection", action: actions_1.Action.FLAG_FOR_REVIEW, threshold: 0.6 });
+}
+function auditLogging() {
+    return new check_1.Check((text) => ({
+        detected: true,
+        confidence: 1.0,
+        auditRecord: { timestamp: Date.now(), textLength: text.length, action: "logged" },
+    }), { name: "hipaa-audit-log", action: actions_1.Action.LOG, threshold: 0 });
+}
+function full() {
+    return {
+        checks: [phiDetection(), medicalClaimDetection(), auditLogging()],
+    };
+}
+function basic() {
+    return {
+        checks: [phiDetection(), auditLogging()],
+    };
+}

package/dist/packs/index.d.ts

@@ -0,0 +1,2 @@
+export * as hipaa from "./hipaa";
+export * as financial from "./financial";

package/dist/packs/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.financial = exports.hipaa = void 0;
+exports.hipaa = __importStar(require("./hipaa"));
+exports.financial = __importStar(require("./financial"));

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "substrai-guardrailgraph",
+  "version": "0.1.0",
+  "description": "Composable AI safety pipeline framework with industry compliance packs (HIPAA, SOX, GDPR, FedRAMP)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/tests/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai-safety",
+    "guardrails",
+    "llm",
+    "compliance",
+    "hipaa",
+    "sox",
+    "gdpr",
+    "serverless",
+    "aws-lambda",
+    "dag",
+    "pipeline",
+    "pii",
+    "toxicity",
+    "prompt-injection"
+  ],
+  "author": "Gaurav Kumar Sinha <gaurav@substrai.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/substrai/guardrailgraph"
+  },
+  "homepage": "https://github.com/substrai/guardrailgraph",
+  "bugs": {
+    "url": "https://github.com/substrai/guardrailgraph/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}