@beingmartinbmc/ojas 0.2.0

package/dist/raksha/hallucination-detectors.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Built-in `HallucinationDetector` implementations.
+ *
+ * These detectors are deliberately **dep-free and runtime-fast**. They
+ * are not state-of-the-art; their purpose is to give Ojas users a
+ * sensible default and a working contract so they can later plug in
+ * heavier ML-backed detectors (encoder grounding models, LLM judges)
+ * via the same interface.
+ *
+ * Three detectors are shipped:
+ *
+ *   1. **`BestOfNInconsistencyDetector`** (black-box consistency)
+ *      Scores how much the agent's output disagrees with alternative
+ *      samples of the same prompt. We use a character-shingle Jaccard
+ *      distance rather than embeddings so we don't need ML. Risk =
+ *      mean pairwise distance from `output` to each sample, clamped
+ *      to [0, 1].
+ *
+ *   2. **`ClaimLevelDetector`** (long-text grounding)
+ *      Splits `output` into sentence-claims, then for each claim
+ *      measures n-gram overlap with each `context` item. A claim is
+ *      "unsupported" when its best-match overlap is below a
+ *      threshold. Risk = fraction of unsupported claims, weighted by
+ *      claim length.
+ *
+ *   3. **`AbstentionDetector`** (refusal recognition)
+ *      Treats appropriate abstention as a **positive** signal: if
+ *      the output is mostly hedging / refusal, returns low risk and
+ *      `abstention: true`. The caller can then route the task to a
+ *      stronger model rather than penalising the abstention.
+ *
+ * Composition: callers wanting an ensemble can wrap these via
+ * `EnsembleHallucinationDetector` (also shipped).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnsembleHallucinationDetector = exports.AbstentionDetector = exports.ClaimLevelDetector = exports.BestOfNInconsistencyDetector = void 0;
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function clamp01(v) {
+    if (!Number.isFinite(v))
+        return 0;
+    return Math.max(0, Math.min(1, v));
+}
+/** Normalise text for matching: lowercase, collapse whitespace, strip ASCII punct. */
+function normalize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[\p{P}\p{S}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Build the set of character shingles of length `k` from `text`. */
+function charShingles(text, k = 4) {
+    const norm = normalize(text);
+    if (norm.length <= k)
+        return new Set([norm]);
+    const out = new Set();
+    for (let i = 0; i <= norm.length - k; i += 1) {
+        out.add(norm.slice(i, i + k));
+    }
+    return out;
+}
+/** Jaccard similarity between two sets. */
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter += 1;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 1 : inter / union;
+}
+/**
+ * Split a paragraph into rough sentence claims. We don't ship a real
+ * sentence segmenter — that would be heavy. The split is good enough
+ * for the n-gram grounding check below; pathological cases (lots of
+ * abbreviations) just produce slightly fragmented claims, which still
+ * score correctly because the n-gram overlap is local.
+ */
+function splitClaims(text) {
+    return text
+        .split(/(?<=[.!?])\s+(?=[A-Z\d])/g)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+class BestOfNInconsistencyDetector {
+    name = 'bestofn/n-gram-jaccard';
+    policy;
+    constructor(policy = {}) {
+        this.policy = {
+            shingleK: policy.shingleK ?? 4,
+            minSamples: policy.minSamples ?? 2,
+        };
+    }
+    async detect(input) {
+        const samples = input.samples ?? [];
+        if (samples.length < this.policy.minSamples) {
+            return {
+                riskScore: 0,
+                confidence: 0.05,
+                detectedBy: this.name,
+                reasons: [
+                    `BestOfNInconsistencyDetector requires ${this.policy.minSamples}+ samples; got ${samples.length}. ` +
+                        'Score is meaningless without alternative generations to compare against.',
+                ],
+            };
+        }
+        const outputShingles = charShingles(input.output, this.policy.shingleK);
+        let distSum = 0;
+        let distMax = 0;
+        for (const s of samples) {
+            const sShingles = charShingles(s, this.policy.shingleK);
+            const sim = jaccard(outputShingles, sShingles);
+            const dist = 1 - sim;
+            distSum += dist;
+            if (dist > distMax)
+                distMax = dist;
+        }
+        const meanDist = distSum / samples.length;
+        return {
+            riskScore: clamp01(meanDist),
+            // Confidence rises with sample size, saturating around n=10.
+            confidence: clamp01(samples.length / 10),
+            detectedBy: this.name,
+            reasons: [
+                `Mean pairwise character-shingle Jaccard distance from output to ${samples.length} samples = ${meanDist.toFixed(3)} (max = ${distMax.toFixed(3)}).`,
+            ],
+        };
+    }
+}
+exports.BestOfNInconsistencyDetector = BestOfNInconsistencyDetector;
+class ClaimLevelDetector {
+    name = 'claim-level/n-gram-grounding';
+    policy;
+    constructor(policy = {}) {
+        this.policy = {
+            shingleK: policy.shingleK ?? 4,
+            groundingThreshold: policy.groundingThreshold ?? 0.25,
+        };
+    }
+    async detect(input) {
+        const context = input.context ?? [];
+        if (context.length === 0) {
+            return {
+                riskScore: 0,
+                confidence: 0.05,
+                detectedBy: this.name,
+                reasons: [
+                    'ClaimLevelDetector requires at least one context item to ground claims against. Score is meaningless without context.',
+                ],
+            };
+        }
+        const ctxShingles = context.map((c, i) => ({ idx: `ctx-${i}`, shingles: charShingles(c, this.policy.shingleK) }));
+        const claims = splitClaims(input.output);
+        if (claims.length === 0) {
+            return {
+                riskScore: 0,
+                confidence: 0.05,
+                detectedBy: this.name,
+                reasons: ['Output produced no parseable claims; treating as null-output, no risk.'],
+            };
+        }
+        const claimAssessments = [];
+        let unsupportedWeight = 0;
+        let totalWeight = 0;
+        for (const claim of claims) {
+            const claimShingles = charShingles(claim, this.policy.shingleK);
+            // Best overlap = the highest fraction of claim shingles found in any single context item.
+            let bestOverlap = 0;
+            let bestIdx;
+            for (const { idx, shingles } of ctxShingles) {
+                if (claimShingles.size === 0)
+                    continue;
+                let inter = 0;
+                for (const sh of claimShingles)
+                    if (shingles.has(sh))
+                        inter += 1;
+                const overlap = inter / claimShingles.size;
+                if (overlap > bestOverlap) {
+                    bestOverlap = overlap;
+                    bestIdx = idx;
+                }
+            }
+            const claimRisk = clamp01(1 - bestOverlap / this.policy.groundingThreshold);
+            const weight = Math.max(1, claim.length);
+            totalWeight += weight;
+            if (bestOverlap < this.policy.groundingThreshold) {
+                unsupportedWeight += weight;
+            }
+            claimAssessments.push({
+                claim,
+                riskScore: claimRisk,
+                groundedIn: bestIdx ? [bestIdx] : [],
+            });
+        }
+        const overallRisk = totalWeight === 0 ? 0 : unsupportedWeight / totalWeight;
+        const unsupportedCount = claimAssessments.filter((c) => c.riskScore >= 1).length;
+        return {
+            riskScore: clamp01(overallRisk),
+            confidence: clamp01(claims.length / 5), // saturates around 5 claims
+            detectedBy: this.name,
+            reasons: [
+                `${unsupportedCount}/${claims.length} claim(s) had best-match grounding overlap below ${this.policy.groundingThreshold.toFixed(2)} against ${context.length} context item(s).`,
+            ],
+            claims: claimAssessments,
+        };
+    }
+}
+exports.ClaimLevelDetector = ClaimLevelDetector;
+// ─── 3. AbstentionDetector ───────────────────────────────────────────────────
+/**
+ * Canonical abstention / hedging phrasings. Conservative — we'd rather
+ * miss a hedge than mistake a substantive answer for one. English-only
+ * by design (matches the rest of Raksha's regex set).
+ */
+const ABSTENTION_PATTERNS = [
+    /\bi (?:do not|don't|cannot|can't|won't) (?:know|determine|tell|say|answer|verify)\b/i,
+    /\bi'?m not (?:sure|certain|confident|able)\b/i,
+    /\b(?:unable to|not able to) (?:answer|determine|confirm|verify|provide)\b/i,
+    /\binsufficient (?:context|information|data|evidence)\b/i,
+    /\b(?:no|not enough) (?:context|information|evidence) (?:to|provided)\b/i,
+    /\bi need more (?:context|information|details)\b/i,
+    /\bplease provide (?:more|additional) (?:context|details|information)\b/i,
+    /\b(?:cannot|can'?t) (?:find|locate) (?:this|that|the answer|relevant)\b/i,
+    /\bi (?:do not|don't) have (?:access to|enough information)\b/i,
+];
+class AbstentionDetector {
+    name = 'abstention/canonical-hedges';
+    policy;
+    constructor(policy = {}) {
+        this.policy = {
+            minAbstentionFraction: policy.minAbstentionFraction ?? 0.15,
+        };
+    }
+    async detect(input) {
+        const text = input.output;
+        if (text.length === 0) {
+            return {
+                riskScore: 0,
+                confidence: 1,
+                detectedBy: this.name,
+                reasons: ['Empty output — trivially an abstention.'],
+                abstention: true,
+            };
+        }
+        let matchedChars = 0;
+        const reasons = [];
+        for (const re of ABSTENTION_PATTERNS) {
+            const m = re.exec(text);
+            if (m) {
+                matchedChars += m[0].length;
+                reasons.push(`Matched abstention pattern: "${m[0]}".`);
+            }
+        }
+        const fraction = matchedChars / text.length;
+        const isAbstention = fraction >= this.policy.minAbstentionFraction;
+        return {
+            // Abstention is a *low-risk* signal: the agent is being honest.
+            // Risk = 1 - fraction so a fuller abstention gets a lower risk.
+            riskScore: isAbstention ? clamp01(1 - fraction) : 0,
+            confidence: isAbstention ? 0.9 : 0.05,
+            detectedBy: this.name,
+            reasons: isAbstention
+                ? reasons
+                : ['Output does not appear to be an abstention.'],
+            abstention: isAbstention,
+        };
+    }
+}
+exports.AbstentionDetector = AbstentionDetector;
+class EnsembleHallucinationDetector {
+    name;
+    entries;
+    constructor(entries) {
+        if (entries.length === 0) {
+            throw new Error('EnsembleHallucinationDetector requires at least one entry.');
+        }
+        this.entries = entries.map((e) => ({
+            detector: e.detector,
+            weight: e.weight ?? 1,
+        }));
+        this.name = `ensemble[${this.entries.map((e) => e.detector.name).join(',')}]`;
+    }
+    async detect(input) {
+        const assessments = await Promise.all(this.entries.map(async (e) => ({
+            assessment: await e.detector.detect(input),
+            weight: e.weight,
+        })));
+        // Short-circuit: any detector that confidently flags abstention wins.
+        const abstaining = assessments.find((a) => a.assessment.abstention && a.assessment.confidence >= 0.5);
+        if (abstaining) {
+            return {
+                riskScore: abstaining.assessment.riskScore,
+                confidence: abstaining.assessment.confidence,
+                detectedBy: this.name,
+                reasons: [
+                    'Ensemble short-circuited on abstention.',
+                    ...abstaining.assessment.reasons,
+                ],
+                abstention: true,
+            };
+        }
+        // Weighted average: each detector's contribution is `weight * confidence`.
+        let weightSum = 0;
+        let riskSum = 0;
+        const reasons = [];
+        for (const a of assessments) {
+            const effective = a.weight * a.assessment.confidence;
+            weightSum += effective;
+            riskSum += effective * a.assessment.riskScore;
+            reasons.push(`[${a.assessment.detectedBy}] risk=${a.assessment.riskScore.toFixed(3)} conf=${a.assessment.confidence.toFixed(2)} weight=${a.weight}`);
+        }
+        const overallRisk = weightSum === 0 ? 0 : riskSum / weightSum;
+        // Ensemble confidence: mean of individual confidences (NOT weighted
+        // by weight — every detector's voice counts toward calibration).
+        const overallConfidence = assessments.reduce((s, a) => s + a.assessment.confidence, 0) / assessments.length;
+        return {
+            riskScore: clamp01(overallRisk),
+            confidence: clamp01(overallConfidence),
+            detectedBy: this.name,
+            reasons,
+        };
+    }
+}
+exports.EnsembleHallucinationDetector = EnsembleHallucinationDetector;
+//# sourceMappingURL=hallucination-detectors.js.map

package/dist/raksha/hallucination-detectors.js.map

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

package/dist/raksha/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Ojas Raksha (ओजस रक्षा) — AI Immune Defense System
+ *
+ * Detects harmful cognitive inputs, protects instruction hierarchy,
+ * and quarantines prompt injection / memory poisoning attempts.
+ */
+import { ContextItem, DefenseHealth, DefensePolicy, HallucinationAssessment, HallucinationDetector, HallucinationDetectorInput, HealthEvent, HealthRecommendation, PromptInjectionClassifier, PromptInjectionDetector, ThreatAssessment } from '../types';
+import type { RakshaStateSnapshot } from '../persistence/types';
+export declare function normalizeForScan(content: string): string;
+export declare function expandBase64(content: string): string | null;
+export interface RakshaOptions {
+    /**
+     * Hallucination detector for `Raksha.detectHallucination()`. Defaults
+     * to an ensemble of `BestOfNInconsistencyDetector + ClaimLevelDetector
+     * + AbstentionDetector`. The ensemble short-circuits on confident
+     * abstention and weights each detector by its self-reported
+     * confidence — so a consistency detector that received no samples
+     * does not pollute the score.
+     *
+     * Plug in heavier ML-backed external detectors by implementing
+     * `HallucinationDetector` and passing them here.
+     */
+    hallucinationDetector?: HallucinationDetector;
+    /**
+     * Detector stack used by `scanItem()` for input-side prompt injection
+     * and unsafe-instruction detection. Defaults to rule patterns plus a
+     * deterministic semantic-intent detector for policy laundering.
+     */
+    promptInjectionDetector?: PromptInjectionDetector;
+    /**
+     * Async ML-backed classifiers for prompt injection. Run *after* the
+     * deterministic detector stack; the highest probability across all
+     * classifiers and the rule-based score wins. This lets Raksha catch
+     * attacks that bypass regex/pattern detectors (roleplay, recursive
+     * obfuscation, indirect multi-document injection).
+     */
+    classifiers?: PromptInjectionClassifier[];
+}
+/**
+ * Default detector — the ensemble that Raksha uses if the caller did
+ * not supply one. Exported so callers can compose with their own
+ * detectors via `EnsembleHallucinationDetector`.
+ */
+export declare function defaultHallucinationDetector(): HallucinationDetector;
+export declare function defaultPromptInjectionDetector(): PromptInjectionDetector;
+export declare class Raksha {
+    private policy;
+    private assessments;
+    private events;
+    private readonly hallucinationDetector;
+    private readonly promptInjectionDetector;
+    private readonly classifiers;
+    constructor(policy?: Partial<DefensePolicy>, options?: RakshaOptions);
+    /**
+     * Name of the configured hallucination detector. Useful for telemetry
+     * and report stamping so operators know which detector produced the
+     * `riskScore` they're seeing.
+     */
+    getHallucinationDetectorName(): string;
+    getPromptInjectionDetectorName(): string;
+    /**
+     * Score an agent's **output** for hallucination risk, optionally
+     * grounded in retrieved context and/or compared against alternative
+     * samples of the same prompt. Returns the detector's assessment with
+     * a wrapper that:
+     *   - guards against thrown errors (detectors are expected not to
+     *     throw, but we defence-in-depth);
+     *   - emits a `hallucination_detected` Pulse event when risk is high
+     *     AND confidence is non-trivial (so we don't emit noise for
+     *     no-signal calls).
+     *
+     * The emission threshold is the same `warnThreshold` Raksha uses for
+     * input-side prompt-injection assessments, for consistency.
+     */
+    detectHallucination(input: HallucinationDetectorInput, opts?: {
+        agentId?: string;
+    }): Promise<{
+        assessment: HallucinationAssessment;
+        event?: HealthEvent;
+    }>;
+    private validatePolicy;
+    private enforceRetention;
+    /**
+     * Pure threat-scan: scores an item and returns the assessment (plus a quarantine
+     * event if applicable). Does NOT touch internal state. Use this for read-only
+     * checks like MCP `ojas_scan_for_injection` so that simply evaluating
+     * candidate content never pollutes defense health.
+     *
+     * Bypass-reduction pipeline applied before regex matching:
+     *   1. `normalizeForScan(content)` — NFKC + zero-width strip + homoglyph fold.
+     *      Catches `іgnore previous instructions` (Cyrillic), `i\u200Bgnore`,
+     *      and full-width "ＩＧＮＯＲＥ".
+     *   2. `expandBase64(normalized)` — decodes base64-looking tokens once
+     *      (non-recursive, bounded) and concatenates the decoded text for a
+     *      second-pass scan. Catches the canonical
+     *      `aWdub3JlIHByZXZpb3VzIGluc3RydWN0aW9ucw==` bypass.
+     *
+     * Detection is a deterministic detector stack, not a security boundary.
+     * See `docs/KNOWN_FAILURES.md` for what remains (indirect, multi-turn,
+     * and novel semantic injection outside the current detector rules).
+     */
+    scanItem(item: ContextItem, opts?: {
+        agentId?: string;
+    }): {
+        assessment: ThreatAssessment;
+        event?: HealthEvent;
+    };
+    /**
+     * Async variant of `scanItem` that also runs any configured ML classifiers.
+     * The final riskScore is the max of the deterministic detector score and
+     * the highest classifier probability. Quarantine is re-evaluated after
+     * the merge so a classifier can elevate a below-threshold item into
+     * quarantine.
+     */
+    scanItemAsync(item: ContextItem, opts?: {
+        agentId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        assessment: ThreatAssessment;
+        event?: HealthEvent;
+    }>;
+    /** Whether this Raksha instance has async classifiers configured. */
+    hasClassifiers(): boolean;
+    /**
+     * Recording variant: scans the item AND appends the assessment (and any event)
+     * to internal state so it contributes to future defense health. Use this when
+     * the scan represents real agent intake; use `scanItem` for read-only checks.
+     */
+    assessItem(item: ContextItem, opts?: {
+        agentId?: string;
+    }): ThreatAssessment;
+    /**
+     * Async recording variant used when classifiers are configured.
+     */
+    assessItemAsync(item: ContextItem, opts?: {
+        agentId?: string;
+        signal?: AbortSignal;
+    }): Promise<ThreatAssessment>;
+    defendContext(items: ContextItem[], opts?: {
+        agentId?: string;
+    }): {
+        safe: ContextItem[];
+        quarantined: ContextItem[];
+        assessments: ThreatAssessment[];
+        events: HealthEvent[];
+    };
+    /**
+     * Async version of `defendContext` that runs ML classifiers on each item.
+     */
+    defendContextAsync(items: ContextItem[], opts?: {
+        agentId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        safe: ContextItem[];
+        quarantined: ContextItem[];
+        assessments: ThreatAssessment[];
+        events: HealthEvent[];
+    }>;
+    assess(): DefenseHealth;
+    recommend(): HealthRecommendation[];
+    getEvents(): readonly Readonly<HealthEvent>[];
+    getAssessments(): readonly Readonly<ThreatAssessment>[];
+    exportState(): RakshaStateSnapshot;
+    importState(snapshot: Partial<RakshaStateSnapshot> | undefined): void;
+    getPolicy(): DefensePolicy;
+    updatePolicy(updates: Partial<DefensePolicy>): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/raksha/index.d.ts.map

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