wauldo 0.4.0 → 0.6.0

package/README.md

@@ -1,82 +1,152 @@
-# Wauldo TypeScript SDK
+<h1 align="center">Wauldo TypeScript SDK</h1>
 
-[![npm](https://img.shields.io/npm/v/wauldo.svg)](https://npmjs.com/package/wauldo)
-[![Downloads](https://img.shields.io/npm/dm/wauldo.svg)](https://npmjs.com/package/wauldo)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+<p align="center">
+  <strong>Verified AI answers from your documents — or no answer at all.</strong>
+</p>
 
-> **Verified AI answers from your documents.** Every response includes source citations, confidence scores, and an audit trail — or we don't answer at all.
+<p align="center">
+  Most RAG APIs guess. Wauldo verifies.
+</p>
 
-Official TypeScript SDK for the [Wauldo API](https://wauldo.com) — the AI inference layer with smart model routing, zero hallucinations, and standalone fact-checking.
+<p align="center">
+  <b>0% hallucination</b> &nbsp;|&nbsp; 83% accuracy &nbsp;|&nbsp; 61 eval tasks &nbsp;|&nbsp; 14 LLMs tested
+</p>
 
-## Why Wauldo?
+<p align="center">
+  <a href="https://npmjs.com/package/wauldo"><img src="https://img.shields.io/npm/v/wauldo.svg" alt="npm" /></a>&nbsp;
+  <a href="https://npmjs.com/package/wauldo"><img src="https://img.shields.io/npm/dm/wauldo.svg" alt="Downloads" /></a>&nbsp;
+  <img src="https://img.shields.io/badge/TypeScript-5.0+-blue.svg" alt="TypeScript" />&nbsp;
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT" />
+</p>
 
-- **Native PDF & DOCX Upload** — upload files directly, server-side text extraction with document quality scoring
-- **Citation Verify API** — detect uncited sentences, phantom citations, and measure coverage ratio. No LLM needed
-- **Fact-Check API** — verify any claim against source with 3 modes (lexical, hybrid, semantic). Get verdict, action, and structured reason
-- **Zero hallucinations** — every answer is verified against source documents
-- **Smart model routing** — auto-selects the cheapest model that meets quality (save 40-80% on AI costs)
-- **One API, 7+ providers** — OpenAI, Anthropic, Google, Qwen, Meta, Mistral, DeepSeek with automatic fallback
-- **OpenAI-compatible** — swap your `baseUrl`, keep your existing code
-- **Full audit trail** — confidence score, grounded status, model used, latency on every response
-- **Zero dependencies** — uses Node 18+ built-in APIs (fetch, ReadableStream)
+<p align="center">
+  <a href="https://wauldo.com/demo">Demo</a> &bull;
+  <a href="https://wauldo.com/docs">Docs</a> &bull;
+  <a href="https://rapidapi.com/binnewzzin/api/smart-rag-api">Free API Key</a> &bull;
+  <a href="https://dev.to/wauldo/how-we-achieved-0-hallucination-rate-in-our-rag-api-with-benchmarks-4g54">Benchmarks</a>
+</p>
+
+---
+
+## Try it locally (no server needed)
+
+```bash
+npm install wauldo
+```
+
+```typescript
+import { MockHttpClient } from 'wauldo';
+
+const client = new MockHttpClient();
+
+// Upload, query, fact-check — all offline
+await client.ragUpload('Refund policy allows returns within 60 days.', 'policy.txt');
+const result = await client.ragQuery('What is the refund policy?');
+console.log(result.answer); // "Mock answer for: What is the refund policy?"
+
+const check = await client.factCheck({
+  text: 'Returns accepted within 30 days.',
+  source_context: 'Refund policy allows returns within 60 days.',
+});
+console.log(check.verdict); // "rejected"
+```
+
+Run the full quickstart: `npx tsx examples/quickstart.ts`
+
+---
 
-## Quick Start
+## Quickstart with real API
 
 ```typescript
 import { HttpClient } from 'wauldo';
 
 const client = new HttpClient({ baseUrl: 'https://api.wauldo.com', apiKey: 'YOUR_API_KEY' });
 
-const reply = await client.chatSimple('auto', 'What is TypeScript?');
-console.log(reply);
+// Upload a document
+await client.ragUpload('Our refund policy allows returns within 60 days...', 'policy.txt');
+
+// Ask a question — answer is verified against the source
+const result = await client.ragQuery('What is the refund policy?');
+console.log(result.answer);
+console.log(result.sources);
 ```
 
-## Installation
+```
+Output:
+Answer: Returns are accepted within 60 days of purchase.
+Sources: policy.txt — "Our refund policy allows returns within 60 days"
+Grounded: true | Confidence: 0.92
+```
+
+[Try the demo](https://wauldo.com/demo) | [Get a free API key](https://rapidapi.com/binnewzzin/api/smart-rag-api)
+
+---
+
+## Why Wauldo (and not standard RAG)
+
+**Typical RAG pipeline**
 
-```bash
-npm install wauldo
+```
+retrieve → generate → hope it's correct
 ```
 
-**Requirements:** Node.js 18+, TypeScript 5.0+
+**Wauldo pipeline**
 
-## Features
+```
+retrieve → extract facts → generate → verify → return or refuse
+```
 
-### Chat Completions
+If the answer can't be verified, it returns **"insufficient evidence"** instead of guessing.
 
-```typescript
-import { HttpClient } from 'wauldo';
+### See the difference
 
-const client = new HttpClient({ baseUrl: 'https://api.wauldo.com', apiKey: 'YOUR_API_KEY' });
+```
+Document: "Refunds are processed within 60 days"
 
-const response = await client.chat({
-  model: 'auto',
-  messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'Explain async/await in TypeScript' },
-  ],
-});
-console.log(response.choices[0]?.message?.content);
+Typical RAG:  "Refunds are processed within 30 days"     ← wrong
+Wauldo:       "Refunds are processed within 60 days"     ← verified
+              or "insufficient evidence" if unclear       ← safe
 ```
 
-### RAG — Upload & Query
+---
+
+## Examples
+
+### Upload a PDF and ask questions
 
 ```typescript
-// Upload a document
-const upload = await client.ragUpload('Contract text here...', 'contract.txt');
-console.log(`Indexed ${upload.chunks_count} chunks`);
+// Upload — text extraction + quality scoring happens server-side
+const upload = await client.uploadFile(filePath, { title: 'Q3 Contract' });
+console.log(`Extracted ${upload.chunks_count} chunks, quality: ${upload.quality_label}`);
 
-// Query with verified answer
+// Query
 const result = await client.ragQuery('What are the payment terms?');
 console.log(`Answer: ${result.answer}`);
 console.log(`Confidence: ${Math.round(result.audit.confidence * 100)}%`);
 console.log(`Grounded: ${result.audit.grounded}`);
-for (const source of result.sources) {
-  console.log(`  Source (${Math.round(source.score * 100)}%): ${source.content}`);
-}
 ```
 
-### Streaming (SSE)
+### Fact-check any LLM output
+
+```typescript
+const result = await client.factCheck({
+  text: 'Returns are accepted within 60 days.',
+  sourceContext: 'Our policy allows returns within 14 days.',
+  mode: 'lexical',
+});
+console.log(result.verdict);          // "rejected"
+console.log(result.action);           // "block"
+console.log(result.claims[0].reason); // "numerical_mismatch"
+```
+
+### Chat (OpenAI-compatible)
+
+```typescript
+const reply = await client.chatSimple('auto', 'Explain async/await in TypeScript');
+console.log(reply);
+```
+
+### Streaming
 
 ```typescript
 const stream = client.chatStream({
@@ -88,7 +158,7 @@ for await (const chunk of stream) {
 }
 ```
 
-### Conversation Helper
+### Conversation
 
 ```typescript
 const conv = client.conversation({ system: 'You are an expert on TypeScript.', model: 'auto' });
@@ -96,18 +166,21 @@ const reply = await conv.say('What are generics?');
 const followUp = await conv.say('Give me an example');
 ```
 
-### Fact-Check — Verify Claims
+---
 
-```typescript
-const result = await client.factCheck({
-  text: 'Returns are accepted within 60 days.',
-  source_context: 'Our policy allows returns within 14 days.',
-  mode: 'lexical',
-});
-console.log(result.verdict); // "rejected"
-console.log(result.action);  // "block"
-result.claims.forEach(c => console.log(`${c.text} → ${c.verdict} (${c.reason})`));
-```
+## Features
+
+- **Pre-generation fact extraction** — numbers, dates, limits injected as constraints
+- **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
+- **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
+- **OpenAI-compatible** — swap your `baseUrl`, keep your existing code
+- **Zero dependencies** — uses Node 18+ built-in APIs (fetch, ReadableStream)
+
+---
 
 ## Error Handling
 
@@ -115,19 +188,16 @@ result.claims.forEach(c => console.log(`${c.text} → ${c.verdict} (${c.reason})
 import { HttpClient, ServerError } from 'wauldo';
 
 try {
-  const response = await client.chat({
-    model: 'auto',
-    messages: [{ role: 'user', content: 'Hello' }],
-  });
+  const response = await client.chat({ model: 'auto', messages: [{ role: 'user', content: 'Hello' }] });
 } catch (error) {
   if (error instanceof ServerError) {
     console.error(`Server error [${error.code}]: ${error.message}`);
-  } else {
-    console.error('Unknown error:', error);
   }
 }
 ```
 
+---
+
 ## RapidAPI
 
 ```typescript
@@ -140,19 +210,17 @@ const client = new HttpClient({
 });
 ```
 
-Get your free API key (300 req/month): [RapidAPI](https://rapidapi.com/binnewzzin/api/smart-rag-api)
+Free tier (300 req/month): [RapidAPI](https://rapidapi.com/binnewzzin/api/smart-rag-api)
 
-## Links
+---
 
-- [Website](https://wauldo.com)
-- [Documentation](https://wauldo.com/docs)
-- [Live Demo](https://api.wauldo.com/demo)
-- [Cost Calculator](https://wauldo.com/calculator)
-- [Status](https://wauldo.com/status)
+[Website](https://wauldo.com) | [Docs](https://wauldo.com/docs) | [Demo](https://wauldo.com/demo) | [Benchmarks](https://dev.to/wauldo/how-we-achieved-0-hallucination-rate-in-our-rag-api-with-benchmarks-4g54)
 
 ## Contributing
 
-Found a bug? Have a feature request? [Open an issue](https://github.com/wauldo/wauldo-sdk-js/issues).
+PRs welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions and guidelines.
+
+Check the [good first issues](https://github.com/wauldo/wauldo-sdk-js/labels/good%20first%20issue) to get started.
 
 ## License
 

package/dist/index.d.mts

@@ -380,6 +380,58 @@ interface VerifyCitationResponse {
     phantom_count?: number;
     processing_time_ms: number;
 }
+interface GuardResult {
+    safe: boolean;
+    verdict: string;
+    action: string;
+    reason: string | null;
+    confidence: number;
+}
+interface InsightsResponse {
+    tig_key: string;
+    total_requests: number;
+    intelligence_requests: number;
+    fallback_requests: number;
+    tokens: {
+        baseline_total: number;
+        real_total: number;
+        saved_total: number;
+        saved_percent_avg: number;
+    };
+    cost: {
+        estimated_usd_saved: number;
+    };
+}
+interface AnalyticsResponse {
+    cache: {
+        total_requests: number;
+        cache_hit_rate: number;
+        avg_latency_ms: number;
+        p95_latency_ms: number;
+    };
+    tokens: {
+        total_baseline: number;
+        total_real: number;
+        total_saved: number;
+        avg_savings_percent: number;
+    };
+    uptime_secs: number;
+}
+interface TrafficSummary {
+    total_requests_today: number;
+    total_tokens_today: number;
+    top_tenants: Array<{
+        tenant_id: string;
+        requests_today: number;
+        tokens_used: number;
+        success_rate: number;
+        avg_latency_ms: number;
+    }>;
+    error_rate: number;
+    avg_latency_ms: number;
+    p95_latency_ms: number;
+    uptime_secs: number;
+}
 /** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
 interface ChatClientLike {
     chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
@@ -580,6 +632,23 @@ 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.
+     */
+    guard(text: string, source: string, mode?: 'lexical' | 'hybrid' | 'semantic'): Promise<GuardResult>;
+    /**
+     * GET /v1/insights — ROI metrics for your API key
+     */
+    getInsights(): Promise<InsightsResponse>;
+    /**
+     * GET /v1/analytics — Usage analytics and cache performance
+     */
+    getAnalytics(minutes?: number): Promise<AnalyticsResponse>;
+    /**
+     * GET /v1/analytics/traffic — Per-tenant traffic monitoring
+     */
+    getAnalyticsTraffic(): Promise<TrafficSummary>;
 }
 
 /**
@@ -650,6 +719,17 @@ declare class MockHttpClient {
         system?: string;
         model?: string;
     }): Conversation;
+    uploadFile(_file: Uint8Array | Buffer, filename: string, options?: {
+        title?: string;
+        tags?: string;
+        timeoutMs?: number;
+    }): Promise<UploadFileResponse>;
+    factCheck(request: FactCheckRequest): Promise<FactCheckResponse>;
+    guard(text: string, source: string, mode?: string): Promise<GuardResult>;
+    verifyCitation(request: VerifyCitationRequest): Promise<VerifyCitationResponse>;
+    getInsights(): Promise<InsightsResponse>;
+    getAnalytics(minutes?: number): Promise<AnalyticsResponse>;
+    getAnalyticsTraffic(): Promise<TrafficSummary>;
     ragAsk(question: string, text: string, source?: string): Promise<string>;
     private record;
 }
@@ -700,4 +780,4 @@ declare class ToolNotFoundError extends WauldoError {
     constructor(toolName: string);
 }
 
-export { AgentClient, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type CitationDetail, type ClaimResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type DocumentQuality, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type FactCheckRequest, type FactCheckResponse, type GraphNode, HttpClient, type HttpClientConfig, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceChunk, type SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UploadFileResponse, ValidationError, type VerifyCitationRequest, type VerifyCitationResponse, WauldoError, chatContent };
+export { AgentClient, type AnalyticsResponse, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type CitationDetail, type ClaimResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type DocumentQuality, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type FactCheckRequest, type FactCheckResponse, type GraphNode, type GuardResult, HttpClient, type HttpClientConfig, type InsightsResponse, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceChunk, type SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type TrafficSummary, type UploadFileResponse, ValidationError, type VerifyCitationRequest, type VerifyCitationResponse, WauldoError, chatContent };

package/dist/index.d.ts

@@ -380,6 +380,58 @@ interface VerifyCitationResponse {
     phantom_count?: number;
     processing_time_ms: number;
 }
+interface GuardResult {
+    safe: boolean;
+    verdict: string;
+    action: string;
+    reason: string | null;
+    confidence: number;
+}
+interface InsightsResponse {
+    tig_key: string;
+    total_requests: number;
+    intelligence_requests: number;
+    fallback_requests: number;
+    tokens: {
+        baseline_total: number;
+        real_total: number;
+        saved_total: number;
+        saved_percent_avg: number;
+    };
+    cost: {
+        estimated_usd_saved: number;
+    };
+}
+interface AnalyticsResponse {
+    cache: {
+        total_requests: number;
+        cache_hit_rate: number;
+        avg_latency_ms: number;
+        p95_latency_ms: number;
+    };
+    tokens: {
+        total_baseline: number;
+        total_real: number;
+        total_saved: number;
+        avg_savings_percent: number;
+    };
+    uptime_secs: number;
+}
+interface TrafficSummary {
+    total_requests_today: number;
+    total_tokens_today: number;
+    top_tenants: Array<{
+        tenant_id: string;
+        requests_today: number;
+        tokens_used: number;
+        success_rate: number;
+        avg_latency_ms: number;
+    }>;
+    error_rate: number;
+    avg_latency_ms: number;
+    p95_latency_ms: number;
+    uptime_secs: number;
+}
 /** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
 interface ChatClientLike {
     chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
@@ -580,6 +632,23 @@ 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.
+     */
+    guard(text: string, source: string, mode?: 'lexical' | 'hybrid' | 'semantic'): Promise<GuardResult>;
+    /**
+     * GET /v1/insights — ROI metrics for your API key
+     */
+    getInsights(): Promise<InsightsResponse>;
+    /**
+     * GET /v1/analytics — Usage analytics and cache performance
+     */
+    getAnalytics(minutes?: number): Promise<AnalyticsResponse>;
+    /**
+     * GET /v1/analytics/traffic — Per-tenant traffic monitoring
+     */
+    getAnalyticsTraffic(): Promise<TrafficSummary>;
 }
 
 /**
@@ -650,6 +719,17 @@ declare class MockHttpClient {
         system?: string;
         model?: string;
     }): Conversation;
+    uploadFile(_file: Uint8Array | Buffer, filename: string, options?: {
+        title?: string;
+        tags?: string;
+        timeoutMs?: number;
+    }): Promise<UploadFileResponse>;
+    factCheck(request: FactCheckRequest): Promise<FactCheckResponse>;
+    guard(text: string, source: string, mode?: string): Promise<GuardResult>;
+    verifyCitation(request: VerifyCitationRequest): Promise<VerifyCitationResponse>;
+    getInsights(): Promise<InsightsResponse>;
+    getAnalytics(minutes?: number): Promise<AnalyticsResponse>;
+    getAnalyticsTraffic(): Promise<TrafficSummary>;
     ragAsk(question: string, text: string, source?: string): Promise<string>;
     private record;
 }
@@ -700,4 +780,4 @@ declare class ToolNotFoundError extends WauldoError {
     constructor(toolName: string);
 }
 
-export { AgentClient, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type CitationDetail, type ClaimResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type DocumentQuality, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type FactCheckRequest, type FactCheckResponse, type GraphNode, HttpClient, type HttpClientConfig, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceChunk, type SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UploadFileResponse, ValidationError, type VerifyCitationRequest, type VerifyCitationResponse, WauldoError, chatContent };
+export { AgentClient, type AnalyticsResponse, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type CitationDetail, type ClaimResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type DocumentQuality, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type FactCheckRequest, type FactCheckResponse, type GraphNode, type GuardResult, HttpClient, type HttpClientConfig, type InsightsResponse, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceChunk, type SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type TrafficSummary, type UploadFileResponse, ValidationError, type VerifyCitationRequest, type VerifyCitationResponse, WauldoError, chatContent };

package/dist/index.js

@@ -1199,6 +1199,55 @@ ${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.
+   */
+  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
+    };
+  }
+  // ── Analytics & Insights endpoints ───────────────────────────────────
+  /**
+   * GET /v1/insights — ROI metrics for your API key
+   */
+  async getInsights() {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "GET",
+      "/v1/insights"
+    );
+    return validateResponse(data, "InsightsResponse");
+  }
+  /**
+   * GET /v1/analytics — Usage analytics and cache performance
+   */
+  async getAnalytics(minutes = 60) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "GET",
+      `/v1/analytics?minutes=${minutes}`
+    );
+    return validateResponse(data, "AnalyticsResponse");
+  }
+  /**
+   * GET /v1/analytics/traffic — Per-tenant traffic monitoring
+   */
+  async getAnalyticsTraffic() {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "GET",
+      "/v1/analytics/traffic"
+    );
+    return validateResponse(data, "TrafficSummary");
+  }
 };
 
 // src/mock_client.ts
@@ -1302,6 +1351,132 @@ var MockHttpClient = class {
     this.record("conversation", options);
     return new Conversation(this, options);
   }
+  async uploadFile(_file, filename, options) {
+    this.record("uploadFile", filename, options);
+    return {
+      document_id: "mock-doc-file-1",
+      chunks_count: 5,
+      indexed_at: (/* @__PURE__ */ new Date()).toISOString(),
+      content_type: "application/pdf",
+      trace_id: "mock-trace-1",
+      quality: {
+        score: 0.85,
+        label: "good",
+        word_count: 1200,
+        line_density: 8.5,
+        avg_line_length: 72,
+        paragraph_count: 15
+      }
+    };
+  }
+  async factCheck(request) {
+    this.record("factCheck", request);
+    const hasConflict = request.text !== request.source_context;
+    return {
+      verdict: hasConflict ? "rejected" : "verified",
+      action: hasConflict ? "block" : "allow",
+      hallucination_rate: hasConflict ? 1 : 0,
+      mode: request.mode ?? "lexical",
+      total_claims: 1,
+      supported_claims: hasConflict ? 0 : 1,
+      confidence: hasConflict ? 0.25 : 0.92,
+      claims: [{
+        text: request.text,
+        claim_type: "factual",
+        supported: !hasConflict,
+        confidence: hasConflict ? 0.25 : 0.92,
+        confidence_label: hasConflict ? "low" : "high",
+        verdict: hasConflict ? "rejected" : "verified",
+        action: hasConflict ? "block" : "allow",
+        reason: hasConflict ? "numerical_mismatch" : null,
+        evidence: request.source_context
+      }],
+      processing_time_ms: 1
+    };
+  }
+  async guard(text, source, mode = "lexical") {
+    this.record("guard", text, source, mode);
+    return {
+      safe: true,
+      verdict: "verified",
+      action: "allow",
+      reason: null,
+      confidence: 0.95
+    };
+  }
+  async verifyCitation(request) {
+    this.record("verifyCitation", request);
+    const citations = request.text.match(/\[(?:Source:\s*[^\]]+|\d+|Ref:\s*[^\]]+)\]/g) ?? [];
+    const sentences = request.text.split(/[.!?]+/).filter((s) => s.trim().length > 0);
+    const citedSentences = sentences.filter((s) => /\[(?:Source:\s*[^\]]+|\d+|Ref:\s*[^\]]+)\]/.test(s));
+    const ratio = sentences.length > 0 ? citedSentences.length / sentences.length : 0;
+    return {
+      citation_ratio: ratio,
+      has_sufficient_citations: ratio >= (request.threshold ?? 0.5),
+      sentence_count: sentences.length,
+      citation_count: citations.length,
+      uncited_sentences: sentences.filter((s) => !/\[(?:Source:\s*[^\]]+|\d+|Ref:\s*[^\]]+)\]/.test(s)).map((s) => s.trim()),
+      citations: citations.map((c) => ({
+        citation: c,
+        source_name: c.replace(/[\[\]]/g, "").replace("Source: ", ""),
+        is_valid: (request.sources ?? []).some((src) => c.includes(src.name))
+      })),
+      phantom_count: 0,
+      processing_time_ms: 1
+    };
+  }
+  async getInsights() {
+    this.record("getInsights");
+    return {
+      tig_key: "mock-tig-key",
+      total_requests: 1250,
+      intelligence_requests: 980,
+      fallback_requests: 270,
+      tokens: {
+        baseline_total: 5e5,
+        real_total: 325e3,
+        saved_total: 175e3,
+        saved_percent_avg: 35
+      },
+      cost: {
+        estimated_usd_saved: 12.5
+      }
+    };
+  }
+  async getAnalytics(minutes = 60) {
+    this.record("getAnalytics", minutes);
+    return {
+      cache: {
+        total_requests: 450,
+        cache_hit_rate: 0.42,
+        avg_latency_ms: 180,
+        p95_latency_ms: 850
+      },
+      tokens: {
+        total_baseline: 12e4,
+        total_real: 78e3,
+        total_saved: 42e3,
+        avg_savings_percent: 35
+      },
+      uptime_secs: 86400
+    };
+  }
+  async getAnalyticsTraffic() {
+    this.record("getAnalyticsTraffic");
+    return {
+      total_requests_today: 3200,
+      total_tokens_today: 15e5,
+      top_tenants: [
+        { tenant_id: "tenant-alpha", requests_today: 1200, tokens_used: 58e4, success_rate: 0.98, avg_latency_ms: 220 },
+        { tenant_id: "tenant-beta", requests_today: 850, tokens_used: 42e4, success_rate: 0.96, avg_latency_ms: 310 },
+        { tenant_id: "tenant-gamma", requests_today: 600, tokens_used: 28e4, success_rate: 0.99, avg_latency_ms: 150 }
+      ],
+      error_rate: 0.02,
+      avg_latency_ms: 240,
+      p95_latency_ms: 890,
+      uptime_secs: 86400
+    };
+  }
   async ragAsk(question, text, source = "document") {
     this.record("ragAsk", question, text, source);
     await this.ragUpload(text, source);

package/dist/index.mjs

@@ -1163,6 +1163,55 @@ ${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.
+   */
+  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
+    };
+  }
+  // ── Analytics & Insights endpoints ───────────────────────────────────
+  /**
+   * GET /v1/insights — ROI metrics for your API key
+   */
+  async getInsights() {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "GET",
+      "/v1/insights"
+    );
+    return validateResponse(data, "InsightsResponse");
+  }
+  /**
+   * GET /v1/analytics — Usage analytics and cache performance
+   */
+  async getAnalytics(minutes = 60) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "GET",
+      `/v1/analytics?minutes=${minutes}`
+    );
+    return validateResponse(data, "AnalyticsResponse");
+  }
+  /**
+   * GET /v1/analytics/traffic — Per-tenant traffic monitoring
+   */
+  async getAnalyticsTraffic() {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "GET",
+      "/v1/analytics/traffic"
+    );
+    return validateResponse(data, "TrafficSummary");
+  }
 };
 
 // src/mock_client.ts
@@ -1266,6 +1315,132 @@ var MockHttpClient = class {
     this.record("conversation", options);
     return new Conversation(this, options);
   }
+  async uploadFile(_file, filename, options) {
+    this.record("uploadFile", filename, options);
+    return {
+      document_id: "mock-doc-file-1",
+      chunks_count: 5,
+      indexed_at: (/* @__PURE__ */ new Date()).toISOString(),
+      content_type: "application/pdf",
+      trace_id: "mock-trace-1",
+      quality: {
+        score: 0.85,
+        label: "good",
+        word_count: 1200,
+        line_density: 8.5,
+        avg_line_length: 72,
+        paragraph_count: 15
+      }
+    };
+  }
+  async factCheck(request) {
+    this.record("factCheck", request);
+    const hasConflict = request.text !== request.source_context;
+    return {
+      verdict: hasConflict ? "rejected" : "verified",
+      action: hasConflict ? "block" : "allow",
+      hallucination_rate: hasConflict ? 1 : 0,
+      mode: request.mode ?? "lexical",
+      total_claims: 1,
+      supported_claims: hasConflict ? 0 : 1,
+      confidence: hasConflict ? 0.25 : 0.92,
+      claims: [{
+        text: request.text,
+        claim_type: "factual",
+        supported: !hasConflict,
+        confidence: hasConflict ? 0.25 : 0.92,
+        confidence_label: hasConflict ? "low" : "high",
+        verdict: hasConflict ? "rejected" : "verified",
+        action: hasConflict ? "block" : "allow",
+        reason: hasConflict ? "numerical_mismatch" : null,
+        evidence: request.source_context
+      }],
+      processing_time_ms: 1
+    };
+  }
+  async guard(text, source, mode = "lexical") {
+    this.record("guard", text, source, mode);
+    return {
+      safe: true,
+      verdict: "verified",
+      action: "allow",
+      reason: null,
+      confidence: 0.95
+    };
+  }
+  async verifyCitation(request) {
+    this.record("verifyCitation", request);
+    const citations = request.text.match(/\[(?:Source:\s*[^\]]+|\d+|Ref:\s*[^\]]+)\]/g) ?? [];
+    const sentences = request.text.split(/[.!?]+/).filter((s) => s.trim().length > 0);
+    const citedSentences = sentences.filter((s) => /\[(?:Source:\s*[^\]]+|\d+|Ref:\s*[^\]]+)\]/.test(s));
+    const ratio = sentences.length > 0 ? citedSentences.length / sentences.length : 0;
+    return {
+      citation_ratio: ratio,
+      has_sufficient_citations: ratio >= (request.threshold ?? 0.5),
+      sentence_count: sentences.length,
+      citation_count: citations.length,
+      uncited_sentences: sentences.filter((s) => !/\[(?:Source:\s*[^\]]+|\d+|Ref:\s*[^\]]+)\]/.test(s)).map((s) => s.trim()),
+      citations: citations.map((c) => ({
+        citation: c,
+        source_name: c.replace(/[\[\]]/g, "").replace("Source: ", ""),
+        is_valid: (request.sources ?? []).some((src) => c.includes(src.name))
+      })),
+      phantom_count: 0,
+      processing_time_ms: 1
+    };
+  }
+  async getInsights() {
+    this.record("getInsights");
+    return {
+      tig_key: "mock-tig-key",
+      total_requests: 1250,
+      intelligence_requests: 980,
+      fallback_requests: 270,
+      tokens: {
+        baseline_total: 5e5,
+        real_total: 325e3,
+        saved_total: 175e3,
+        saved_percent_avg: 35
+      },
+      cost: {
+        estimated_usd_saved: 12.5
+      }
+    };
+  }
+  async getAnalytics(minutes = 60) {
+    this.record("getAnalytics", minutes);
+    return {
+      cache: {
+        total_requests: 450,
+        cache_hit_rate: 0.42,
+        avg_latency_ms: 180,
+        p95_latency_ms: 850
+      },
+      tokens: {
+        total_baseline: 12e4,
+        total_real: 78e3,
+        total_saved: 42e3,
+        avg_savings_percent: 35
+      },
+      uptime_secs: 86400
+    };
+  }
+  async getAnalyticsTraffic() {
+    this.record("getAnalyticsTraffic");
+    return {
+      total_requests_today: 3200,
+      total_tokens_today: 15e5,
+      top_tenants: [
+        { tenant_id: "tenant-alpha", requests_today: 1200, tokens_used: 58e4, success_rate: 0.98, avg_latency_ms: 220 },
+        { tenant_id: "tenant-beta", requests_today: 850, tokens_used: 42e4, success_rate: 0.96, avg_latency_ms: 310 },
+        { tenant_id: "tenant-gamma", requests_today: 600, tokens_used: 28e4, success_rate: 0.99, avg_latency_ms: 150 }
+      ],
+      error_rate: 0.02,
+      avg_latency_ms: 240,
+      p95_latency_ms: 890,
+      uptime_secs: 86400
+    };
+  }
   async ragAsk(question, text, source = "document") {
     this.record("ragAsk", question, text, source);
     await this.ragUpload(text, source);

package/package.json

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