wauldo 0.6.0 → 0.7.0

package/README.md

@@ -174,6 +174,7 @@ const followUp = await conv.say('Give me an example');
 - **Post-generation grounding check** — every answer verified against sources
 - **Citation validation** — detects phantom references
 - **Analytics & Insights** — track token savings, cache performance, cost per hour, and per-tenant traffic
+- **Guard method** — one-call hallucination firewall (`client.guard(text, source)` → safe/unsafe)
 - **Fact-check API** — verify any claim against any source (3 modes)
 - **Native PDF/DOCX upload** — server-side extraction with quality scoring
 - **Smart model routing** — auto-selects cheapest model that meets quality

package/dist/index.d.mts

@@ -380,6 +380,7 @@ interface VerifyCitationResponse {
     phantom_count?: number;
     processing_time_ms: number;
 }
+/** @deprecated Use GuardResponse instead */
 interface GuardResult {
     safe: boolean;
     verdict: string;
@@ -387,6 +388,30 @@ interface GuardResult {
     reason: string | null;
     confidence: number;
 }
+interface GuardClaim {
+    text: string;
+    claim_type?: string;
+    supported: boolean;
+    confidence: number;
+    confidence_label?: string;
+    verdict: string;
+    action: string;
+    reason?: string | null;
+    evidence?: string | null;
+}
+interface GuardResponse {
+    verdict: string;
+    action: string;
+    hallucination_rate: number;
+    mode: string;
+    total_claims: number;
+    supported_claims: number;
+    confidence: number;
+    claims: GuardClaim[];
+    mode_warning?: string;
+    processing_time_ms?: number;
+}
+type GuardMode = 'lexical' | 'hybrid' | 'semantic';
 interface InsightsResponse {
     tig_key: string;
     total_requests: number;
@@ -633,10 +658,27 @@ declare class HttpClient {
      */
     verifyCitation(request: VerifyCitationRequest): Promise<VerifyCitationResponse>;
     /**
-     * Verify an LLM output against a source document.
-     * Convenience wrapper around factCheck(). Returns a simple safe/unsafe result.
+     * POST /v1/fact-check — Verify text claims against source context.
+     *
+     * Guard is a hallucination firewall: checks whether LLM output is
+     * supported by source documents. Blocks wrong answers before users see them.
+     *
+     * @param text - The LLM-generated text to verify
+     * @param sourceContext - The ground-truth source document(s)
+     * @param mode - "lexical" (<1ms), "hybrid" (~50ms), or "semantic" (~500ms)
+     *
+     * @example
+     * ```typescript
+     * const result = await client.guard(
+     *   'Returns accepted within 60 days',
+     *   'Our return policy: 14 days.',
+     * );
+     * if (guardIsBlocked(result)) {
+     *   console.log('Hallucination caught:', result.claims[0]?.reason);
+     * }
+     * ```
      */
-    guard(text: string, source: string, mode?: 'lexical' | 'hybrid' | 'semantic'): Promise<GuardResult>;
+    guard(text: string, sourceContext: string, mode?: GuardMode): Promise<GuardResponse>;
     /**
      * GET /v1/insights — ROI metrics for your API key
      */
@@ -725,7 +767,7 @@ declare class MockHttpClient {
         timeoutMs?: number;
     }): Promise<UploadFileResponse>;
     factCheck(request: FactCheckRequest): Promise<FactCheckResponse>;
-    guard(text: string, source: string, mode?: string): Promise<GuardResult>;
+    guard(text: string, sourceContext: string, mode?: 'lexical' | 'hybrid' | 'semantic'): Promise<GuardResponse>;
     verifyCitation(request: VerifyCitationRequest): Promise<VerifyCitationResponse>;
     getInsights(): Promise<InsightsResponse>;
     getAnalytics(minutes?: number): Promise<AnalyticsResponse>;

package/dist/index.d.ts

@@ -380,6 +380,7 @@ interface VerifyCitationResponse {
     phantom_count?: number;
     processing_time_ms: number;
 }
+/** @deprecated Use GuardResponse instead */
 interface GuardResult {
     safe: boolean;
     verdict: string;
@@ -387,6 +388,30 @@ interface GuardResult {
     reason: string | null;
     confidence: number;
 }
+interface GuardClaim {
+    text: string;
+    claim_type?: string;
+    supported: boolean;
+    confidence: number;
+    confidence_label?: string;
+    verdict: string;
+    action: string;
+    reason?: string | null;
+    evidence?: string | null;
+}
+interface GuardResponse {
+    verdict: string;
+    action: string;
+    hallucination_rate: number;
+    mode: string;
+    total_claims: number;
+    supported_claims: number;
+    confidence: number;
+    claims: GuardClaim[];
+    mode_warning?: string;
+    processing_time_ms?: number;
+}
+type GuardMode = 'lexical' | 'hybrid' | 'semantic';
 interface InsightsResponse {
     tig_key: string;
     total_requests: number;
@@ -633,10 +658,27 @@ declare class HttpClient {
      */
     verifyCitation(request: VerifyCitationRequest): Promise<VerifyCitationResponse>;
     /**
-     * Verify an LLM output against a source document.
-     * Convenience wrapper around factCheck(). Returns a simple safe/unsafe result.
+     * POST /v1/fact-check — Verify text claims against source context.
+     *
+     * Guard is a hallucination firewall: checks whether LLM output is
+     * supported by source documents. Blocks wrong answers before users see them.
+     *
+     * @param text - The LLM-generated text to verify
+     * @param sourceContext - The ground-truth source document(s)
+     * @param mode - "lexical" (<1ms), "hybrid" (~50ms), or "semantic" (~500ms)
+     *
+     * @example
+     * ```typescript
+     * const result = await client.guard(
+     *   'Returns accepted within 60 days',
+     *   'Our return policy: 14 days.',
+     * );
+     * if (guardIsBlocked(result)) {
+     *   console.log('Hallucination caught:', result.claims[0]?.reason);
+     * }
+     * ```
      */
-    guard(text: string, source: string, mode?: 'lexical' | 'hybrid' | 'semantic'): Promise<GuardResult>;
+    guard(text: string, sourceContext: string, mode?: GuardMode): Promise<GuardResponse>;
     /**
      * GET /v1/insights — ROI metrics for your API key
      */
@@ -725,7 +767,7 @@ declare class MockHttpClient {
         timeoutMs?: number;
     }): Promise<UploadFileResponse>;
     factCheck(request: FactCheckRequest): Promise<FactCheckResponse>;
-    guard(text: string, source: string, mode?: string): Promise<GuardResult>;
+    guard(text: string, sourceContext: string, mode?: 'lexical' | 'hybrid' | 'semantic'): Promise<GuardResponse>;
     verifyCitation(request: VerifyCitationRequest): Promise<VerifyCitationResponse>;
     getInsights(): Promise<InsightsResponse>;
     getAnalytics(minutes?: number): Promise<AnalyticsResponse>;

package/dist/index.js

@@ -1200,19 +1200,34 @@ ${options.tags}\r
     return validateResponse(data, "VerifyCitationResponse");
   }
   /**
-   * Verify an LLM output against a source document.
-   * Convenience wrapper around factCheck(). Returns a simple safe/unsafe result.
+   * POST /v1/fact-check — Verify text claims against source context.
+   *
+   * Guard is a hallucination firewall: checks whether LLM output is
+   * supported by source documents. Blocks wrong answers before users see them.
+   *
+   * @param text - The LLM-generated text to verify
+   * @param sourceContext - The ground-truth source document(s)
+   * @param mode - "lexical" (<1ms), "hybrid" (~50ms), or "semantic" (~500ms)
+   *
+   * @example
+   * ```typescript
+   * const result = await client.guard(
+   *   'Returns accepted within 60 days',
+   *   'Our return policy: 14 days.',
+   * );
+   * if (guardIsBlocked(result)) {
+   *   console.log('Hallucination caught:', result.claims[0]?.reason);
+   * }
+   * ```
    */
-  async guard(text, source, mode = "lexical") {
-    const result = await this.factCheck({ text, source_context: source, mode });
-    const claim = result.claims?.[0];
-    return {
-      safe: claim?.verdict === "verified",
-      verdict: claim?.verdict ?? "rejected",
-      action: claim?.action ?? "block",
-      reason: claim?.reason ?? "no_claims",
-      confidence: claim?.confidence ?? 0
-    };
+  async guard(text, sourceContext, mode = "lexical") {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/fact-check",
+      { text, source_context: sourceContext, mode }
+    );
+    return validateResponse(data, "GuardResponse");
   }
   // ── Analytics & Insights endpoints ───────────────────────────────────
   /**
@@ -1394,14 +1409,28 @@ var MockHttpClient = class {
       processing_time_ms: 1
     };
   }
-  async guard(text, source, mode = "lexical") {
-    this.record("guard", text, source, mode);
+  async guard(text, sourceContext, mode = "lexical") {
+    this.record("guard", text, sourceContext, mode);
     return {
-      safe: true,
       verdict: "verified",
       action: "allow",
-      reason: null,
-      confidence: 0.95
+      hallucination_rate: 0,
+      mode,
+      total_claims: 1,
+      supported_claims: 1,
+      confidence: 0.95,
+      claims: [{
+        text,
+        claim_type: "Fact",
+        supported: true,
+        confidence: 0.95,
+        confidence_label: "high",
+        verdict: "verified",
+        action: "allow",
+        reason: null,
+        evidence: sourceContext
+      }],
+      processing_time_ms: 0
     };
   }
   async verifyCitation(request) {

package/dist/index.mjs

@@ -1164,19 +1164,34 @@ ${options.tags}\r
     return validateResponse(data, "VerifyCitationResponse");
   }
   /**
-   * Verify an LLM output against a source document.
-   * Convenience wrapper around factCheck(). Returns a simple safe/unsafe result.
+   * POST /v1/fact-check — Verify text claims against source context.
+   *
+   * Guard is a hallucination firewall: checks whether LLM output is
+   * supported by source documents. Blocks wrong answers before users see them.
+   *
+   * @param text - The LLM-generated text to verify
+   * @param sourceContext - The ground-truth source document(s)
+   * @param mode - "lexical" (<1ms), "hybrid" (~50ms), or "semantic" (~500ms)
+   *
+   * @example
+   * ```typescript
+   * const result = await client.guard(
+   *   'Returns accepted within 60 days',
+   *   'Our return policy: 14 days.',
+   * );
+   * if (guardIsBlocked(result)) {
+   *   console.log('Hallucination caught:', result.claims[0]?.reason);
+   * }
+   * ```
    */
-  async guard(text, source, mode = "lexical") {
-    const result = await this.factCheck({ text, source_context: source, mode });
-    const claim = result.claims?.[0];
-    return {
-      safe: claim?.verdict === "verified",
-      verdict: claim?.verdict ?? "rejected",
-      action: claim?.action ?? "block",
-      reason: claim?.reason ?? "no_claims",
-      confidence: claim?.confidence ?? 0
-    };
+  async guard(text, sourceContext, mode = "lexical") {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/fact-check",
+      { text, source_context: sourceContext, mode }
+    );
+    return validateResponse(data, "GuardResponse");
   }
   // ── Analytics & Insights endpoints ───────────────────────────────────
   /**
@@ -1358,14 +1373,28 @@ var MockHttpClient = class {
       processing_time_ms: 1
     };
   }
-  async guard(text, source, mode = "lexical") {
-    this.record("guard", text, source, mode);
+  async guard(text, sourceContext, mode = "lexical") {
+    this.record("guard", text, sourceContext, mode);
     return {
-      safe: true,
       verdict: "verified",
       action: "allow",
-      reason: null,
-      confidence: 0.95
+      hallucination_rate: 0,
+      mode,
+      total_claims: 1,
+      supported_claims: 1,
+      confidence: 0.95,
+      claims: [{
+        text,
+        claim_type: "Fact",
+        supported: true,
+        confidence: 0.95,
+        confidence_label: "high",
+        verdict: "verified",
+        action: "allow",
+        reason: null,
+        evidence: sourceContext
+      }],
+      processing_time_ms: 0
     };
   }
   async verifyCitation(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wauldo",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Official TypeScript SDK for Wauldo — Verified AI answers from your documents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",