wauldo 0.5.0 → 0.6.0

package/README.md

@@ -28,12 +28,35 @@
 
 ---
 
-## Quickstart (30 seconds)
+## 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`
+
+---
+
+## Quickstart with real API
+
 ```typescript
 import { HttpClient } from 'wauldo';
 
@@ -150,6 +173,7 @@ const followUp = await conv.say('Give me an example');
 - **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
@@ -194,7 +218,9 @@ Free tier (300 req/month): [RapidAPI](https://rapidapi.com/binnewzzin/api/smart-
 
 ## Contributing
 
-PRs welcome. Check the [good first issues](https://github.com/wauldo/wauldo-sdk-js/labels/good%20first%20issue).
+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

@@ -277,6 +277,22 @@ interface RagUploadResponse {
     document_id: string;
     chunks_count: number;
 }
+interface DocumentQuality {
+    score: number;
+    label: string;
+    word_count: number;
+    line_density: number;
+    avg_line_length: number;
+    paragraph_count: number;
+}
+interface UploadFileResponse {
+    document_id: string;
+    chunks_count: number;
+    indexed_at: string;
+    content_type: string;
+    trace_id: string;
+    quality?: DocumentQuality;
+}
 interface RagSource {
     document_id: string;
     content: string;
@@ -312,6 +328,110 @@ interface RagQueryResponse {
 interface OrchestratorResponse {
     final_output: string;
 }
+interface FactCheckRequest {
+    text: string;
+    source_context: string;
+    mode?: 'lexical' | 'hybrid' | 'semantic';
+}
+interface ClaimResult {
+    text: string;
+    claim_type: string;
+    supported: boolean;
+    confidence: number;
+    confidence_label: string;
+    verdict: string;
+    action: string;
+    reason?: string | null;
+    evidence?: string | null;
+}
+interface FactCheckResponse {
+    verdict: string;
+    action: string;
+    hallucination_rate: number;
+    mode: string;
+    total_claims: number;
+    supported_claims: number;
+    confidence: number;
+    claims: ClaimResult[];
+    mode_warning?: string | null;
+    processing_time_ms: number;
+}
+interface SourceChunk {
+    name: string;
+    content: string;
+}
+interface CitationDetail {
+    citation: string;
+    source_name: string;
+    is_valid: boolean;
+}
+interface VerifyCitationRequest {
+    text: string;
+    sources?: SourceChunk[];
+    threshold?: number;
+}
+interface VerifyCitationResponse {
+    citation_ratio: number;
+    has_sufficient_citations: boolean;
+    sentence_count: number;
+    citation_count: number;
+    uncited_sentences: string[];
+    citations?: CitationDetail[];
+    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>;
@@ -435,6 +555,19 @@ declare class HttpClient {
      * @returns Upload confirmation with document_id and chunks_count
      */
     ragUpload(content: string, filename?: string, options?: RequestOptions): Promise<RagUploadResponse>;
+    /**
+     * POST /v1/upload-file — Upload a file (PDF, DOCX, text, image) for RAG indexing.
+     *
+     * @param file - File content as Buffer/Uint8Array
+     * @param filename - The filename (determines content type detection)
+     * @param options - Optional title, tags, timeoutMs
+     * @returns Upload confirmation with quality scoring
+     */
+    uploadFile(file: Uint8Array | Buffer, filename: string, options?: {
+        title?: string;
+        tags?: string;
+        timeoutMs?: number;
+    }): Promise<UploadFileResponse>;
     /** POST /v1/query — Query RAG knowledge base */
     ragQuery(query: string, topK?: number, options?: {
         debug?: boolean;
@@ -469,6 +602,53 @@ declare class HttpClient {
     orchestrate(prompt: string): Promise<OrchestratorResponse>;
     /** POST /v1/orchestrator/parallel — Run all 4 specialists in parallel */
     orchestrateParallel(prompt: string): Promise<OrchestratorResponse>;
+    /**
+     * POST /v1/fact-check — Verify claims against source context.
+     *
+     * @param request - Text and source context to verify
+     * @returns FactCheckResponse with verdict, action, and per-claim results
+     *
+     * @example
+     * ```typescript
+     * const result = await client.factCheck({
+     *   text: 'Returns accepted within 60 days.',
+     *   source_context: 'Our policy allows returns within 14 days.',
+     *   mode: 'lexical',
+     * });
+     * console.log(result.verdict); // "rejected"
+     * ```
+     */
+    factCheck(request: FactCheckRequest): Promise<FactCheckResponse>;
+    /**
+     * POST /v1/verify — Verify citations in AI-generated text.
+     *
+     * @example
+     * ```ts
+     * const result = await client.verifyCitation({
+     *   text: 'Rust was released in 2010 [Source: rust_book].',
+     *   sources: [{ name: 'rust_book', content: 'Rust was first released in 2010.' }],
+     * });
+     * console.log(result.phantom_count); // 0
+     * ```
+     */
+    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>;
 }
 
 /**
@@ -539,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;
 }
@@ -589,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 ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, 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 SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, 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

@@ -277,6 +277,22 @@ interface RagUploadResponse {
     document_id: string;
     chunks_count: number;
 }
+interface DocumentQuality {
+    score: number;
+    label: string;
+    word_count: number;
+    line_density: number;
+    avg_line_length: number;
+    paragraph_count: number;
+}
+interface UploadFileResponse {
+    document_id: string;
+    chunks_count: number;
+    indexed_at: string;
+    content_type: string;
+    trace_id: string;
+    quality?: DocumentQuality;
+}
 interface RagSource {
     document_id: string;
     content: string;
@@ -312,6 +328,110 @@ interface RagQueryResponse {
 interface OrchestratorResponse {
     final_output: string;
 }
+interface FactCheckRequest {
+    text: string;
+    source_context: string;
+    mode?: 'lexical' | 'hybrid' | 'semantic';
+}
+interface ClaimResult {
+    text: string;
+    claim_type: string;
+    supported: boolean;
+    confidence: number;
+    confidence_label: string;
+    verdict: string;
+    action: string;
+    reason?: string | null;
+    evidence?: string | null;
+}
+interface FactCheckResponse {
+    verdict: string;
+    action: string;
+    hallucination_rate: number;
+    mode: string;
+    total_claims: number;
+    supported_claims: number;
+    confidence: number;
+    claims: ClaimResult[];
+    mode_warning?: string | null;
+    processing_time_ms: number;
+}
+interface SourceChunk {
+    name: string;
+    content: string;
+}
+interface CitationDetail {
+    citation: string;
+    source_name: string;
+    is_valid: boolean;
+}
+interface VerifyCitationRequest {
+    text: string;
+    sources?: SourceChunk[];
+    threshold?: number;
+}
+interface VerifyCitationResponse {
+    citation_ratio: number;
+    has_sufficient_citations: boolean;
+    sentence_count: number;
+    citation_count: number;
+    uncited_sentences: string[];
+    citations?: CitationDetail[];
+    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>;
@@ -435,6 +555,19 @@ declare class HttpClient {
      * @returns Upload confirmation with document_id and chunks_count
      */
     ragUpload(content: string, filename?: string, options?: RequestOptions): Promise<RagUploadResponse>;
+    /**
+     * POST /v1/upload-file — Upload a file (PDF, DOCX, text, image) for RAG indexing.
+     *
+     * @param file - File content as Buffer/Uint8Array
+     * @param filename - The filename (determines content type detection)
+     * @param options - Optional title, tags, timeoutMs
+     * @returns Upload confirmation with quality scoring
+     */
+    uploadFile(file: Uint8Array | Buffer, filename: string, options?: {
+        title?: string;
+        tags?: string;
+        timeoutMs?: number;
+    }): Promise<UploadFileResponse>;
     /** POST /v1/query — Query RAG knowledge base */
     ragQuery(query: string, topK?: number, options?: {
         debug?: boolean;
@@ -469,6 +602,53 @@ declare class HttpClient {
     orchestrate(prompt: string): Promise<OrchestratorResponse>;
     /** POST /v1/orchestrator/parallel — Run all 4 specialists in parallel */
     orchestrateParallel(prompt: string): Promise<OrchestratorResponse>;
+    /**
+     * POST /v1/fact-check — Verify claims against source context.
+     *
+     * @param request - Text and source context to verify
+     * @returns FactCheckResponse with verdict, action, and per-claim results
+     *
+     * @example
+     * ```typescript
+     * const result = await client.factCheck({
+     *   text: 'Returns accepted within 60 days.',
+     *   source_context: 'Our policy allows returns within 14 days.',
+     *   mode: 'lexical',
+     * });
+     * console.log(result.verdict); // "rejected"
+     * ```
+     */
+    factCheck(request: FactCheckRequest): Promise<FactCheckResponse>;
+    /**
+     * POST /v1/verify — Verify citations in AI-generated text.
+     *
+     * @example
+     * ```ts
+     * const result = await client.verifyCitation({
+     *   text: 'Rust was released in 2010 [Source: rust_book].',
+     *   sources: [{ name: 'rust_book', content: 'Rust was first released in 2010.' }],
+     * });
+     * console.log(result.phantom_count); // 0
+     * ```
+     */
+    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>;
 }
 
 /**
@@ -539,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;
 }
@@ -589,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 ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, 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 SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, 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

@@ -900,6 +900,16 @@ async function* parseSSEStream(body) {
 }
 
 // src/http_client.ts
+function concatUint8Arrays(arrays) {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) {
+    result.set(a, offset);
+    offset += a.length;
+  }
+  return result;
+}
 function validateResponse(data, typeName) {
   if (data === null || data === void 0) {
     throw new ServerError(`Invalid ${typeName}: response is null`, 0);
@@ -1034,6 +1044,51 @@ var HttpClient = class {
     );
     return validateResponse(data, "RagUploadResponse");
   }
+  /**
+   * POST /v1/upload-file — Upload a file (PDF, DOCX, text, image) for RAG indexing.
+   *
+   * @param file - File content as Buffer/Uint8Array
+   * @param filename - The filename (determines content type detection)
+   * @param options - Optional title, tags, timeoutMs
+   * @returns Upload confirmation with quality scoring
+   */
+  async uploadFile(file, filename, options) {
+    const boundary = "----WauldoSDKBoundary";
+    const parts = [];
+    const enc = new TextEncoder();
+    parts.push(enc.encode(`--${boundary}\r
+Content-Disposition: form-data; name="file"; filename="${filename}"\r
+Content-Type: application/octet-stream\r
+\r
+`));
+    parts.push(file instanceof Uint8Array ? file : new Uint8Array(file));
+    parts.push(enc.encode("\r\n"));
+    if (options?.title) {
+      parts.push(enc.encode(`--${boundary}\r
+Content-Disposition: form-data; name="title"\r
+\r
+${options.title}\r
+`));
+    }
+    if (options?.tags) {
+      parts.push(enc.encode(`--${boundary}\r
+Content-Disposition: form-data; name="tags"\r
+\r
+${options.tags}\r
+`));
+    }
+    parts.push(enc.encode(`--${boundary}--\r
+`));
+    const body = concatUint8Arrays(parts);
+    const data = await fetchWithRetry(
+      { ...this.retryConfig, headers: { ...this.retryConfig.headers, "Content-Type": `multipart/form-data; boundary=${boundary}` } },
+      "POST",
+      "/v1/upload-file",
+      body,
+      options?.timeoutMs
+    );
+    return validateResponse(data, "UploadFileResponse");
+  }
   /** POST /v1/query — Query RAG knowledge base */
   async ragQuery(query, topK = 5, options) {
     const body = { query, top_k: topK };
@@ -1097,6 +1152,102 @@ var HttpClient = class {
     );
     return validateResponse(data, "OrchestratorResponse");
   }
+  // ── Fact-Check endpoints ──────────────────────────────────────────────
+  /**
+   * POST /v1/fact-check — Verify claims against source context.
+   *
+   * @param request - Text and source context to verify
+   * @returns FactCheckResponse with verdict, action, and per-claim results
+   *
+   * @example
+   * ```typescript
+   * const result = await client.factCheck({
+   *   text: 'Returns accepted within 60 days.',
+   *   source_context: 'Our policy allows returns within 14 days.',
+   *   mode: 'lexical',
+   * });
+   * console.log(result.verdict); // "rejected"
+   * ```
+   */
+  async factCheck(request) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/fact-check",
+      request
+    );
+    return validateResponse(data, "FactCheckResponse");
+  }
+  /**
+   * POST /v1/verify — Verify citations in AI-generated text.
+   *
+   * @example
+   * ```ts
+   * const result = await client.verifyCitation({
+   *   text: 'Rust was released in 2010 [Source: rust_book].',
+   *   sources: [{ name: 'rust_book', content: 'Rust was first released in 2010.' }],
+   * });
+   * console.log(result.phantom_count); // 0
+   * ```
+   */
+  async verifyCitation(request) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/verify",
+      request
+    );
+    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
@@ -1200,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

@@ -864,6 +864,16 @@ async function* parseSSEStream(body) {
 }
 
 // src/http_client.ts
+function concatUint8Arrays(arrays) {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) {
+    result.set(a, offset);
+    offset += a.length;
+  }
+  return result;
+}
 function validateResponse(data, typeName) {
   if (data === null || data === void 0) {
     throw new ServerError(`Invalid ${typeName}: response is null`, 0);
@@ -998,6 +1008,51 @@ var HttpClient = class {
     );
     return validateResponse(data, "RagUploadResponse");
   }
+  /**
+   * POST /v1/upload-file — Upload a file (PDF, DOCX, text, image) for RAG indexing.
+   *
+   * @param file - File content as Buffer/Uint8Array
+   * @param filename - The filename (determines content type detection)
+   * @param options - Optional title, tags, timeoutMs
+   * @returns Upload confirmation with quality scoring
+   */
+  async uploadFile(file, filename, options) {
+    const boundary = "----WauldoSDKBoundary";
+    const parts = [];
+    const enc = new TextEncoder();
+    parts.push(enc.encode(`--${boundary}\r
+Content-Disposition: form-data; name="file"; filename="${filename}"\r
+Content-Type: application/octet-stream\r
+\r
+`));
+    parts.push(file instanceof Uint8Array ? file : new Uint8Array(file));
+    parts.push(enc.encode("\r\n"));
+    if (options?.title) {
+      parts.push(enc.encode(`--${boundary}\r
+Content-Disposition: form-data; name="title"\r
+\r
+${options.title}\r
+`));
+    }
+    if (options?.tags) {
+      parts.push(enc.encode(`--${boundary}\r
+Content-Disposition: form-data; name="tags"\r
+\r
+${options.tags}\r
+`));
+    }
+    parts.push(enc.encode(`--${boundary}--\r
+`));
+    const body = concatUint8Arrays(parts);
+    const data = await fetchWithRetry(
+      { ...this.retryConfig, headers: { ...this.retryConfig.headers, "Content-Type": `multipart/form-data; boundary=${boundary}` } },
+      "POST",
+      "/v1/upload-file",
+      body,
+      options?.timeoutMs
+    );
+    return validateResponse(data, "UploadFileResponse");
+  }
   /** POST /v1/query — Query RAG knowledge base */
   async ragQuery(query, topK = 5, options) {
     const body = { query, top_k: topK };
@@ -1061,6 +1116,102 @@ var HttpClient = class {
     );
     return validateResponse(data, "OrchestratorResponse");
   }
+  // ── Fact-Check endpoints ──────────────────────────────────────────────
+  /**
+   * POST /v1/fact-check — Verify claims against source context.
+   *
+   * @param request - Text and source context to verify
+   * @returns FactCheckResponse with verdict, action, and per-claim results
+   *
+   * @example
+   * ```typescript
+   * const result = await client.factCheck({
+   *   text: 'Returns accepted within 60 days.',
+   *   source_context: 'Our policy allows returns within 14 days.',
+   *   mode: 'lexical',
+   * });
+   * console.log(result.verdict); // "rejected"
+   * ```
+   */
+  async factCheck(request) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/fact-check",
+      request
+    );
+    return validateResponse(data, "FactCheckResponse");
+  }
+  /**
+   * POST /v1/verify — Verify citations in AI-generated text.
+   *
+   * @example
+   * ```ts
+   * const result = await client.verifyCitation({
+   *   text: 'Rust was released in 2010 [Source: rust_book].',
+   *   sources: [{ name: 'rust_book', content: 'Rust was first released in 2010.' }],
+   * });
+   * console.log(result.phantom_count); // 0
+   * ```
+   */
+  async verifyCitation(request) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/verify",
+      request
+    );
+    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
@@ -1164,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.5.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",