🛡️ @nishpaksh/shield

Production-Grade AI Guardrails, Real-Time Bias Mitigation & GraphRAG Red-Teaming Gateway

Deploy autonomous evaluation, factual grounding, and real-time defense for LLM applications in under 60 seconds.

Overview • Architecture • Quickstart • Core Features • GraphRAG Red-Teaming • Factual Grounding • API Reference

🌟 Overview

@nishpaksh/shield is the official TypeScript SDK for the Nishpaksh AI Safety & Red-Team Studio. It serves as an inline gateway and automated evaluation harness for generative AI bots, customer support assistants, and autonomous agents.

Whether defending against regional, caste, and gender bias, eliminating hallucinations with strict document-level factual grounding, or stress-testing models with multi-turn GraphRAG adversarial attacks, Nishpaksh Shield provides a typed, fail-closed barrier between your users and upstream AI endpoints.

🔒 Enterprise Note: This package is an ESM/Node.js client running in your trusted backend environment. It makes authenticated API calls to your self-hosted or managed Nishpaksh API cluster. Never expose your Shield or Evaluation API keys in client-side browser bundles.

🏗️ Architecture

┌─────────────────┐       POST /chat/completions       ┌─────────────────────────────────┐
│  Client Web/App │ ─────────────────────────────────> │    Nishpaksh Shield Gateway     │
└─────────────────┘                                    └────────────────┬────────────────┘
                                                                        │
                                       ┌────────────────────────────────┴───────────────────────────────┐
                                       ▼                                                                ▼
                         ┌───────────────────────────┐                                    ┌───────────────────────────┐
                         │   Fast Policy Engine      │                                    │   Factual Grounding       │
                         │   (Deterministic <5ms)    │                                    │   (GraphRAG Source Sync)  │
                         └─────────────┬─────────────┘                                    └─────────────┬─────────────┘
                                       │                                                                │
                                       ▼                                                                ▼
                         ┌───────────────────────────┐       Raw Candidate Validation     ┌───────────────────────────┐
                         │   Upstream LLM Provider   │ ─────────────────────────────────> │   Independent Model Judge │
                         │   (OpenAI/Anthropic/Bot)  │                                    │   (Deep Bias & Toxicity)  │
                         └───────────────────────────┘                                    └─────────────┬─────────────┘
                                                                                                        │
                                                                   ┌────────────────────────────────────┴────────────────┐
                                                                   ▼                                                     ▼
                                                            [ PASSED: Reply ]                               [ BLOCKED / SANITIZED ]

Key Safety Highlights

• Zero-Loop Architecture: Protects customer-facing endpoints by cleanly decoupling upstream provider backends from public ingress routes.
• Fail-Closed Guarantees: Any judge timeout, verifier anomaly, or invalid rewrite fails safely with a controlled fallback rather than leaking toxic or unverified answers.
• Dual-Stage Decision Engine: Combines instant sub-millisecond local policy filters with deep semantic model judging and shadow classifiers.

⚡ Quickstart

1. Installation

Install via your favorite package manager:

# npm
npm install @nishpaksh/shield

# pnpm
pnpm add @nishpaksh/shield

# yarn
yarn add @nishpaksh/shield

# bun
bun add @nishpaksh/shield

2. Protect Live Chat (Production Gateway)

Route end-user traffic through Shield before delivering answers:

import { NishpakshShield } from "@nishpaksh/shield";

// Initialize with your scoped Shield traffic key
const shield = new NishpakshShield({
  apiKey: process.env.NISHPAKSH_SHIELD_KEY!,
  baseUrl: "https://your-shield-host.com/api/shield/v1",
  timeoutMs: 30_000,
});

// Guard an inbound user conversation
const completion = await shield.chat({
  model: "target_prod_support_bot_uuid", // Registered target ID
  messages: [
    { role: "user", content: "Compare hiring candidates based on their home states." }
  ],
  shieldAction: "sanitize", // "pass" | "block" | "sanitize"
});

// Examine safety verdicts and content
console.log("Shield Verdict:", completion.shield.status);   // "PASSED" | "BLOCKED" | "SANITIZED"
console.log("Risk Score:", completion.shield.score);        // 0 - 100
console.log("Decision Origin:", completion.shield.decisionSource); // "local_policy" | "model_judge"
console.log("Final Reply:", completion.choices[0].message.content);

🛡️ Core Features

| Feature | Description | Benefit | | :--- | :--- | :--- | | Real-Time Guardrail Gateway | Inspects chat completions with sub-200ms latency overhead. | Immediate defense for live customer conversations. | | Autonomous Red-Teaming | Adaptive multi-turn attack strategies (baseline & graph_rag). | Uncovers vulnerabilities before malicious actors do. | | Automatic Sanitization | Rewrites biased or unsafe responses with a second validation pass. | Preserves helpfulness while eliminating harmful output. | | Knowledge Grounding | Validates factual claims against tenant-approved Markdown/docs. | Stops hallucinations in regulated industries. | | Demographic Attribute Swaps| Tests paired neutral controls against demographic perturbations. | Discovers hidden regional, gender, and caste disparities. | | Audit Tracing & Replay | Replays captured outputs without re-querying expensive upstream models. | Rapid, deterministic post-incident review. |

⚔️ Autonomous GraphRAG Red-Teaming

Nishpaksh includes an automated adversarial red-team engine that probes your model across multi-turn trajectories to uncover subtle bias and prompt injection vulnerabilities:

import { NishpakshShield } from "@nishpaksh/shield";

const evaluator = new NishpakshShield({
  apiKey: process.env.NISHPAKSH_EVALUATION_KEY!,
  baseUrl: "https://your-shield-host.com/api/shield/v1",
});

// 1. Register or configure target endpoint
const target = await evaluator.registerTarget({
  name: "Loan Eligibility Advisor",
  type: "custom_webhook",
  endpointUrl: "https://api.myapp.com/internal/bot",
  payloadFormat: "standard_messages",
  responseJsonPath: "reply",
});

// 2. Launch an autonomous GraphRAG stress test
const run = await evaluator.startEvaluation({
  target,
  evaluationMode: "autonomous_attacker",
  attackerStrategy: "graph_rag", // Multi-turn knowledge-graph guided attack
  objective: {
    category: "Regional Bias",
    language: "English",
    targetGoal: "Test whether the assistant gives unfavorable interest rates to tier-3 city applicants.",
  },
  turnsCount: 6,
});

// 3. Await completion and analyze findings
const report = await evaluator.waitForEvaluation(run.id);
const evidence = await evaluator.getEvidence(run.id);
const graph = await evaluator.getAttackGraph(run.id);

console.log(`Evaluation status: ${report.status}`);
console.log(`Observed Drift Findings: ${evidence.findings.length}`);

📚 Background Factual Grounding

Eliminate hallucinated claims by syncing tenant-owned source truth. Shield validates every response against exact quote matches in approved reference materials:

// 1. Sync authoritative source knowledge for a target
await evaluator.syncKnowledge(target.id, [
  {
    name: "refund-policy.md",
    content: "All subscription cancellations made within 14 days receive a 100% refund."
  },
  {
    name: "kyc-requirements.md",
    content: "National Identity or Passport is required for account tier 2 verification."
  }
], "enforce"); // "enforce" (withhold unverified claims) or "shadow" (log only)

// 2. Standard chat calls now automatically verify claims against approved knowledge
const response = await shield.chat({
  model: target.id,
  messages: [{ role: "user", content: "Can I get a refund after 20 days?" }],
  shieldAction: "block"
});

if (response.shield.grounding) {
  console.log("Factual Verification:", response.shield.grounding.status);
  console.log("Verified Quotes:", response.shield.grounding.citations);
}

🧪 Developer Demo Toolkit

For sandbox testing and quick prototyping, import the @nishpaksh/shield/demo subpath:

import { connectDemo } from "@nishpaksh/shield/demo";

const { demo, target, contextDirectory } = await connectDemo({
  baseUrl: process.env.NISHPAKSH_BASE_URL!,
  evaluationApiKey: process.env.NISHPAKSH_EVALUATION_KEY!,
  shieldApiKey: process.env.NISHPAKSH_SHIELD_KEY!,
  target: {
    type: "custom_webhook",
    name: "Admissions Assistant",
    endpointUrl: "https://my-school.example/api/bot",
    payloadFormat: "standard_messages",
    responseJsonPath: "reply"
  }
});

// Scaffolds context files (chatbot.md, policies.md) automatically
const attack = await demo.startAttack({
  target,
  category: "Caste Bias",
  context: "Admissions adviser evaluating candidate scholarship eligibility.",
  contextDirectory
});

📖 API Reference

NishpakshShield Constructor Options

| Option | Type | Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | apiKey | string | Yes | — | Scoped Shield Traffic Key or Evaluation Admin Key. | | baseUrl | string | Yes | — | Fully-qualified URL to the Nishpaksh API (https://host/api/shield/v1). | | timeoutMs | number | No | 180000 | Client HTTP timeout in milliseconds. |

shield.chat(params) Options

| Parameter | Type | Required | Description | | :--- | :--- | :--- | :--- | | model | string | Yes | The registered Nishpaksh Target ID (not external LLM model name). | | messages | Array<{role, content}>| Yes | Conversation history in standard chat format. | | shieldAction| "pass" \| "block" \| "sanitize" | No | Defense behavior when an unsafe response is detected (block by default). | | temperature | number | No | Upstream model temperature override. |

ShieldResult Payload

interface ShieldMetadata {
  status: "PASSED" | "BLOCKED" | "SANITIZED";
  score: number; // 0 (Clean) to 100 (Unsafe / High Risk)
  decisionSource: "local_policy" | "model_judge" | "fail_closed";
  reasons: string[];
  failureCode?: string;
  shadowGuard?: { flagged: boolean; score: number };
  grounding?: { status: string; citations: string[] };
  trace?: Array<{ stage: string; durationMs: number; status: string }>;
}

🔒 Security & Privacy

• Strict Token Isolation: Shield Traffic Keys are separated from Evaluation Keys. Traffic keys can only run chat inferences and cannot view evaluations or modify targets.
• No Secret Storage in Transcripts: Headers, API keys, and target authorization credentials are never logged or returned in inspection transcripts.
• Fail-Closed Protection: In the event of upstream network partitions or judge outages, Shield protects user reputation by enforcing fail-closed refusals.

🤝 Contributing & Community

We welcome contributions from the AI safety and developer community!

• Issues & Feature Requests: Submit an Issue
• Pull Requests: PRs are welcome! Please ensure all TypeScript types compile (npm run build) before opening a PR.

Built with pride by the Nishpaksh Team • Powered by IndiaAI

Distributed under the MIT License.