@veroq/sdk 2.0.0 → 2.1.0

package/dist/esm/shield.d.ts

@@ -0,0 +1,108 @@
+/**
+ * VeroQ Prompt Shield — One-line verification for any LLM output.
+ *
+ * @example
+ * ```typescript
+ * import { shield } from "@veroq/sdk";
+ *
+ * const result = await shield("NVIDIA reported $22B in Q4 revenue");
+ * console.log(result.trustScore);    // 0.73
+ * console.log(result.isTrusted);     // false
+ * console.log(result.corrections);   // [{claim, correction, confidence}]
+ * console.log(result.verifiedText);  // text with corrections inline
+ *
+ * // Wrap any LLM call
+ * const response = await openai.chat.completions.create({...});
+ * const verified = await shield(response.choices[0].message.content);
+ * ```
+ */
+export interface ShieldOptions {
+    /** Source identifier (e.g., "gpt-4o", "claude-3") */
+    source?: string;
+    /** Agent ID for memory integration */
+    agentId?: string;
+    /** Max claims to extract (1-10, default 5) */
+    maxClaims?: number;
+    /** API key override */
+    apiKey?: string;
+    /** If true, throws VeroqError when claims are contradicted */
+    blockIfUntrusted?: boolean;
+}
+export interface ShieldClaim {
+    text: string;
+    category: string;
+    verdict: string;
+    confidence: number;
+    correction: string | null;
+    receiptId: string | null;
+    evidenceChain: Array<{
+        source: string;
+        position: string;
+        snippet: string;
+    }>;
+}
+export declare class ShieldResult {
+    /** Original text (truncated) */
+    readonly text: string;
+    /** Source identifier */
+    readonly source: string;
+    /** All extracted claims with verdicts */
+    readonly claims: ShieldClaim[];
+    /** Number of claims extracted */
+    readonly claimsExtracted: number;
+    /** Number of claims verified */
+    readonly claimsVerified: number;
+    /** Number of claims supported */
+    readonly claimsSupported: number;
+    /** Number of claims contradicted */
+    readonly claimsContradicted: number;
+    /** Overall trust score (0-1) */
+    readonly trustScore: number;
+    /** Overall verdict */
+    readonly overallVerdict: string;
+    /** Summary */
+    readonly summary: string;
+    /** Credits used */
+    readonly creditsUsed: number;
+    /** Processing time in ms */
+    readonly processingTimeMs: number;
+    /** Full original text (before server truncation) */
+    private readonly _fullText;
+    constructor(raw: Record<string, any>, fullText?: string);
+    /** True if no claims were contradicted */
+    get isTrusted(): boolean;
+    /** Corrections for contradicted claims */
+    get corrections(): Array<{
+        claim: string;
+        correction: string;
+        confidence: number;
+    }>;
+    /** Text with contradicted claims annotated */
+    get verifiedText(): string;
+    /** Verification receipt IDs */
+    get receiptIds(): string[];
+}
+/**
+ * Shield any LLM output with VeroQ verification.
+ *
+ * Extracts claims, verifies each against evidence, returns trust score
+ * with corrections for any contradicted claims.
+ *
+ * @example
+ * ```typescript
+ * import { shield } from "@veroq/sdk";
+ *
+ * // Basic
+ * const result = await shield("NVIDIA's Q4 revenue exceeded $22B");
+ * console.log(result.trustScore, result.corrections);
+ *
+ * // With options
+ * const result = await shield(llmOutput, {
+ *   source: "gpt-4o",
+ *   agentId: "my-bot",
+ *   blockIfUntrusted: true,
+ * });
+ * ```
+ */
+export declare function shield(text: string, options?: ShieldOptions): Promise<ShieldResult>;
+//# sourceMappingURL=shield.d.ts.map

package/dist/esm/shield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shield.d.ts","sourceRoot":"","sources":["../../src/shield.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED,qBAAa,YAAY;IACvB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,gCAAgC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iCAAiC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,cAAc;IACd,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mBAAmB;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM;IAwBvD,0CAA0C;IAC1C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,0CAA0C;IAC1C,IAAI,WAAW,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAIlF;IAED,8CAA8C;IAC9C,IAAI,YAAY,IAAI,MAAM,CAQzB;IAED,+BAA+B;IAC/B,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;CACF;AAYD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuC7F"}

package/dist/esm/shield.js

@@ -0,0 +1,132 @@
+/**
+ * VeroQ Prompt Shield — One-line verification for any LLM output.
+ *
+ * @example
+ * ```typescript
+ * import { shield } from "@veroq/sdk";
+ *
+ * const result = await shield("NVIDIA reported $22B in Q4 revenue");
+ * console.log(result.trustScore);    // 0.73
+ * console.log(result.isTrusted);     // false
+ * console.log(result.corrections);   // [{claim, correction, confidence}]
+ * console.log(result.verifiedText);  // text with corrections inline
+ *
+ * // Wrap any LLM call
+ * const response = await openai.chat.completions.create({...});
+ * const verified = await shield(response.choices[0].message.content);
+ * ```
+ */
+import { VeroqClient } from "./client.js";
+import { VeroqError } from "./errors.js";
+export class ShieldResult {
+    constructor(raw, fullText) {
+        this._fullText = fullText || raw.text || "";
+        this.text = raw.text || "";
+        this.source = raw.source || "unknown";
+        this.claims = (raw.claims || []).map((c) => ({
+            text: c.text,
+            category: c.category,
+            verdict: c.verdict,
+            confidence: c.confidence || 0,
+            correction: c.correction || null,
+            receiptId: c.receipt_id || null,
+            evidenceChain: c.evidence_chain || [],
+        }));
+        this.claimsExtracted = raw.claims_extracted || 0;
+        this.claimsVerified = raw.claims_verified || 0;
+        this.claimsSupported = raw.claims_supported || 0;
+        this.claimsContradicted = raw.claims_contradicted || 0;
+        this.trustScore = raw.overall_confidence || 0;
+        this.overallVerdict = raw.overall_verdict || "unknown";
+        this.summary = raw.summary || "";
+        this.creditsUsed = raw.credits_used || 0;
+        this.processingTimeMs = raw.processing_time_ms || 0;
+    }
+    /** True if no claims were contradicted */
+    get isTrusted() {
+        return this.claimsContradicted === 0;
+    }
+    /** Corrections for contradicted claims */
+    get corrections() {
+        return this.claims
+            .filter(c => c.verdict === "contradicted" && c.correction)
+            .map(c => ({ claim: c.text, correction: c.correction, confidence: c.confidence }));
+    }
+    /** Text with contradicted claims annotated */
+    get verifiedText() {
+        let result = this._fullText;
+        for (const c of this.claims) {
+            if (c.verdict === "contradicted" && c.correction && result.includes(c.text)) {
+                result = result.replace(c.text, `[CORRECTED: ${c.correction.slice(0, 200)}]`);
+            }
+        }
+        return result;
+    }
+    /** Verification receipt IDs */
+    get receiptIds() {
+        return this.claims.map(c => c.receiptId).filter((id) => !!id);
+    }
+}
+// Module-level client
+let _client = null;
+function getClient(apiKey) {
+    if (!_client || apiKey) {
+        _client = new VeroqClient({ apiKey });
+    }
+    return _client;
+}
+/**
+ * Shield any LLM output with VeroQ verification.
+ *
+ * Extracts claims, verifies each against evidence, returns trust score
+ * with corrections for any contradicted claims.
+ *
+ * @example
+ * ```typescript
+ * import { shield } from "@veroq/sdk";
+ *
+ * // Basic
+ * const result = await shield("NVIDIA's Q4 revenue exceeded $22B");
+ * console.log(result.trustScore, result.corrections);
+ *
+ * // With options
+ * const result = await shield(llmOutput, {
+ *   source: "gpt-4o",
+ *   agentId: "my-bot",
+ *   blockIfUntrusted: true,
+ * });
+ * ```
+ */
+export async function shield(text, options = {}) {
+    if (!text || text.trim().length < 20) {
+        return new ShieldResult({
+            text: text || "",
+            claims: [],
+            claims_extracted: 0,
+            overall_confidence: 1.0,
+            overall_verdict: "no_claims",
+            summary: "Text too short to extract verifiable claims.",
+        });
+    }
+    const client = getClient(options.apiKey);
+    const raw = await client.verifyOutput(text, {
+        source: options.source,
+        maxClaims: options.maxClaims,
+    });
+    // Store to memory if agentId provided
+    if (options.agentId && raw.claims?.length) {
+        client.memoryStore(options.agentId, `shield:${text.slice(0, 50).replace(/\s+/g, "_")}`, {
+            trust_score: raw.overall_confidence,
+            verdict: raw.overall_verdict,
+            claims_extracted: raw.claims_extracted,
+            claims_contradicted: raw.claims_contradicted,
+        }, { category: "verification", queryText: text.slice(0, 200) }).catch(() => { });
+    }
+    const result = new ShieldResult(raw, text);
+    if (options.blockIfUntrusted && !result.isTrusted) {
+        throw new VeroqError(`Shield blocked: ${result.claimsContradicted} of ${result.claimsExtracted} claims contradicted. ` +
+            `Corrections: ${result.corrections.map(c => c.claim.slice(0, 80)).join("; ")}`);
+    }
+    return result;
+}
+//# sourceMappingURL=shield.js.map

package/dist/esm/shield.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veroq/sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "VeroQ TypeScript SDK — the verified intelligence layer for AI agents",
   "type": "module",
   "main": "./dist/cjs/index.js",