guardrail-plug-sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,48 @@
+# Guardrail Plug SDK
+
+A plug-and-play AI Auditing, Safety, and Hallucination Interception SDK. Wrap any LLM agent to intercept prompt injections, redact PII, trace reasoning, verify factual grounding against corporate knowledge bases, and block ungrounded responses in real time.
+
+## Installation
+
+```bash
+npm install guardrail-plug-sdk
+```
+
+## Quick Start
+
+Initialize the SDK and route your chat prompts through the security gateway:
+
+```typescript
+import { Guardrail } from 'guardrail-plug-sdk';
+
+const guardrail = new Guardrail({
+  endpoint: 'http://localhost:5050', // Gateway server address
+  apiKey: 'gr_sec_your_api_key_here',
+  provider: 'openrouter', // 'openrouter' | 'openai' | 'gemini' | 'ollama' | 'mock'
+  model: 'google/gemini-2.5-flash',
+  applicationName: 'HR Compliance Assistant'
+});
+
+async function askAgent(userInput: string) {
+  const response = await guardrail.chat({
+    messages: [{ role: 'user', content: userInput }],
+    groundingSource: 'web' // 'kb' (Knowledge base files) or 'web' (Real-time web search)
+  });
+
+  if (response.decision === 'BLOCKED') {
+    console.warn(`Blocked by Policy: ${response.policyExplanation}`);
+    // Output safe fallback
+    return response.text; 
+  }
+
+  console.log(`Factual Trust Score: ${response.factualTrustScore}`); // Score from 0.0 to 1.0
+  return response.text;
+}
+```
+
+## Features
+
+- **Input Interception & Redaction**: Scans prompts for PII/PHI (emails, SSNs, credit cards) and prompt injections before hitting target LLMs.
+- **Dynamic Factual Auditing**: Extracts claims and performs Natural Language Inference (NLI) audits against vector database documentation or live web citations.
+- **Trust Scoring**: Generates a deterministic mathematical Trust Score indicating the percentage of grounding.
+- **Real-Time Policy Enforcement**: Blocks or flags responses that exceed configured hallucination or safety thresholds.

package/dist/Guardrail.d.ts

@@ -18,3 +18,4 @@ export declare class Guardrail {
      */
     chat(request: SDKChatRequest): Promise<SDKChatResponse>;
 }
+//# sourceMappingURL=Guardrail.d.ts.map

package/dist/Guardrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Guardrail.d.ts","sourceRoot":"","sources":["../src/Guardrail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,eAAe,CAAS;gBAEpB,OAAO,EAAE,gBAAgB;IAYrC;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;CA8B9D"}

package/dist/Guardrail.js

@@ -47,3 +47,4 @@ export class Guardrail {
         }
     }
 }
+//# sourceMappingURL=Guardrail.js.map

package/dist/Guardrail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Guardrail.js","sourceRoot":"","sources":["../src/Guardrail.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,SAAS;IACZ,QAAQ,CAAS;IACjB,MAAM,CAAS;IACf,QAAQ,CAAS;IACjB,KAAK,CAAS;IACd,eAAe,CAAS;IAEhC,YAAY,OAAyB;QACnC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,uBAAuB,CAAC;QAC5D,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;QAC7C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;QAC5C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,iBAAiB,CAAC;QAEpE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,OAAuB;QAChC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,WAAW,EAAE;gBACxD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;iBACzC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,QAAQ,EAAE,OAAO,CAAC,QAAQ;oBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,UAAU;oBACpC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,aAAa;oBAC7C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ;oBAC3C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;oBAClC,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe;oBAChE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;iBACjC,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,CAAC,MAAM,MAAM,SAAS,EAAE,CAAC,CAAC;YACnF,CAAC;YAED,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAqB,CAAC;QAClD,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,sCAAsC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YACnE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './Guardrail.js';
 export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './Guardrail.js';
 export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -85,3 +85,4 @@ export interface ProviderConfig {
     healthStatus: 'healthy' | 'unhealthy' | 'unknown';
     latency: number;
 }
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardrail-plug-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A plug-and-play AI Auditing & Hallucination Detection SDK. Intercepts LLM inputs/outputs, verifies factual grounding against your knowledge base, and blocks or flags unverified responses.",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "scripts": {

package/src/Guardrail.ts

@@ -0,0 +1,63 @@
+import { SDKChatRequest, SDKChatResponse } from './types.js';
+
+export interface GuardrailOptions {
+  endpoint?: string;
+  apiKey: string;
+  provider?: 'openai' | 'gemini' | 'ollama' | 'mock' | string;
+  model?: string;
+  applicationName?: string;
+}
+
+export class Guardrail {
+  private endpoint: string;
+  private apiKey: string;
+  private provider: string;
+  private model: string;
+  private applicationName: string;
+
+  constructor(options: GuardrailOptions) {
+    this.endpoint = options.endpoint || 'http://localhost:5050';
+    this.apiKey = options.apiKey;
+    this.provider = options.provider || 'openai';
+    this.model = options.model || 'gpt-4o-mini';
+    this.applicationName = options.applicationName || 'SDK Application';
+
+    if (!this.apiKey) {
+      throw new Error('[Guardrail SDK] Initialisation Error: API Key (apiKey) is required.');
+    }
+  }
+
+  /**
+   * Routes chat completions through the Guardrail Middleware Gateway
+   */
+  async chat(request: SDKChatRequest): Promise<SDKChatResponse> {
+    try {
+      const response = await fetch(`${this.endpoint}/api/chat`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          messages: request.messages,
+          userId: request.userId || 'sdk_user',
+          sessionId: request.sessionId || 'sdk_session',
+          provider: request.provider || this.provider,
+          model: request.model || this.model,
+          applicationName: request.applicationName || this.applicationName,
+          metadata: request.metadata || {}
+        })
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Guardrail Middleware Error [${response.status}]: ${errorText}`);
+      }
+
+      return await response.json() as SDKChatResponse;
+    } catch (err: any) {
+      console.error('[Guardrail SDK] Chat Request Failed:', err.message);
+      throw err;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './Guardrail.js';
+export * from './types.js';

package/src/types.ts

@@ -0,0 +1,97 @@
+export interface Message {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+export interface SDKChatRequest {
+  messages: Message[];
+  userId?: string;
+  sessionId?: string;
+  provider?: string;
+  model?: string;
+  applicationName?: string;
+  metadata?: Record<string, any>;
+  groundingSource?: 'kb' | 'web';
+}
+
+export interface Citation {
+  citationId: string;
+  documentId: string;
+  documentName: string;
+  content: string;
+  score: number;
+}
+
+export interface Claim {
+  claim: string;
+  status: 'SUPPORTED' | 'PARTIALLY_SUPPORTED' | 'UNSUPPORTED';
+  explanation: string;
+  citationId?: string;
+}
+
+export interface PolicyResult {
+  decision: 'APPROVED' | 'FLAGGED' | 'BLOCKED';
+  violatedRules: string[];
+  explanation: string;
+}
+
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface Metrics {
+  totalLatencyMs: number;
+  llmLatencyMs: number;
+  ragLatencyMs: number;
+  verificationLatencyMs: number;
+  tokenUsage: TokenUsage;
+  costUsd: number;
+}
+
+export interface SDKChatResponse {
+  auditId: string;
+  text: string;
+  decision: 'APPROVED' | 'FLAGGED' | 'BLOCKED';
+  hallucinationScore: number;
+  factualTrustScore: number; // 0.0 to 1.0 grounding metric
+  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  citations: Citation[];
+  claims: Claim[];
+  policyExplanation: string;
+  metrics: Metrics;
+  rawThinking?: string;
+  thinkingClaims?: Claim[];
+  rawResponseBeforeBlock?: string;
+}
+
+export interface UploadedDocument {
+  id: string;
+  name: string;
+  type: string;
+  uploadedAt: string;
+  size: number;
+  status: 'indexing' | 'indexed' | 'failed';
+  version: number;
+  owner?: string;
+}
+
+export interface DocumentChunk {
+  id: string;
+  documentId: string;
+  documentName: string;
+  content: string;
+  embedding?: number[];
+  metadata?: Record<string, any>;
+}
+
+export interface ProviderConfig {
+  providerId: string;
+  name: string;
+  enabled: boolean;
+  defaultModel: string;
+  apiKey?: string;
+  healthStatus: 'healthy' | 'unhealthy' | 'unknown';
+  latency: number;
+}