wauldo 0.1.0 → 0.2.0

package/README.md

@@ -7,10 +7,11 @@
 
 > **Verified AI answers from your documents.** Every response includes source citations, confidence scores, and an audit trail — or we don't answer at all.
 
-Official TypeScript SDK for the [Wauldo API](https://wauldo.com) — the AI inference layer with smart model routing and zero hallucinations.
+Official TypeScript SDK for the [Wauldo API](https://wauldo.com) — the AI inference layer with smart model routing, zero hallucinations, and standalone fact-checking.
 
 ## Why Wauldo?
 
+- **Fact-Check API** — verify any claim against source context, get verdict (verified/weak/rejected), action (allow/review/block), 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
@@ -93,6 +94,19 @@ 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})`));
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -248,6 +248,8 @@ interface ChatResponse {
     choices: ChatChoice[];
     usage: ChatUsage;
 }
+/** Get the text content of the first choice, or empty string */
+declare function chatContent(response: ChatResponse): string;
 interface ModelInfo {
     id: string;
     object: string;
@@ -310,6 +312,34 @@ 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;
+}
 /** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
 interface ChatClientLike {
     chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
@@ -467,6 +497,23 @@ 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>;
 }
 
 /**
@@ -587,4 +634,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 };
+export { AgentClient, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClaimResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, 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 SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, WauldoError, chatContent };

package/dist/index.d.ts

@@ -248,6 +248,8 @@ interface ChatResponse {
     choices: ChatChoice[];
     usage: ChatUsage;
 }
+/** Get the text content of the first choice, or empty string */
+declare function chatContent(response: ChatResponse): string;
 interface ModelInfo {
     id: string;
     object: string;
@@ -310,6 +312,34 @@ 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;
+}
 /** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
 interface ChatClientLike {
     chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
@@ -467,6 +497,23 @@ 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>;
 }
 
 /**
@@ -587,4 +634,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 };
+export { AgentClient, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClaimResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, 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 SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, WauldoError, chatContent };

package/dist/index.js

@@ -29,7 +29,8 @@ __export(index_exports, {
   TimeoutError: () => TimeoutError,
   ToolNotFoundError: () => ToolNotFoundError,
   ValidationError: () => ValidationError,
-  WauldoError: () => WauldoError
+  WauldoError: () => WauldoError,
+  chatContent: () => chatContent
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -819,8 +820,14 @@ async function fetchWithRetry(config, method, path, body, overrideTimeoutMs) {
         continue;
       }
       const text = await resp.text();
-      config.onLog?.("error", `${method} ${path} -> ${resp.status}: ${text}`);
-      const err = new Error(`HTTP ${resp.status}: ${text}`);
+      let message = text;
+      try {
+        const j = JSON.parse(text);
+        if (j?.error?.message) message = j.error.message;
+      } catch {
+      }
+      config.onLog?.("error", `${method} ${path} -> ${resp.status}: ${message}`);
+      const err = new Error(`HTTP ${resp.status}: ${message}`);
       config.onError?.(err);
       throw err;
     } catch (err) {
@@ -982,7 +989,13 @@ var HttpClient = class {
     }
     if (!resp.ok) {
       const body = await resp.text();
-      const err = new ServerError(`HTTP ${resp.status}: ${body}`, resp.status);
+      let message = body;
+      try {
+        const j = JSON.parse(body);
+        if (j?.error?.message) message = j.error.message;
+      } catch {
+      }
+      const err = new ServerError(`HTTP ${resp.status}: ${message}`, resp.status);
       cfg.onError?.(err);
       throw err;
     }
@@ -1084,6 +1097,32 @@ 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");
+  }
 };
 
 // src/mock_client.ts
@@ -1197,6 +1236,11 @@ var MockHttpClient = class {
     this.calls.push({ method, args });
   }
 };
+
+// src/http_types.ts
+function chatContent(response) {
+  return response.choices[0]?.message?.content ?? "";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentClient,
@@ -1208,5 +1252,6 @@ var MockHttpClient = class {
   TimeoutError,
   ToolNotFoundError,
   ValidationError,
-  WauldoError
+  WauldoError,
+  chatContent
 });

package/dist/index.mjs

@@ -784,8 +784,14 @@ async function fetchWithRetry(config, method, path, body, overrideTimeoutMs) {
         continue;
       }
       const text = await resp.text();
-      config.onLog?.("error", `${method} ${path} -> ${resp.status}: ${text}`);
-      const err = new Error(`HTTP ${resp.status}: ${text}`);
+      let message = text;
+      try {
+        const j = JSON.parse(text);
+        if (j?.error?.message) message = j.error.message;
+      } catch {
+      }
+      config.onLog?.("error", `${method} ${path} -> ${resp.status}: ${message}`);
+      const err = new Error(`HTTP ${resp.status}: ${message}`);
       config.onError?.(err);
       throw err;
     } catch (err) {
@@ -947,7 +953,13 @@ var HttpClient = class {
     }
     if (!resp.ok) {
       const body = await resp.text();
-      const err = new ServerError(`HTTP ${resp.status}: ${body}`, resp.status);
+      let message = body;
+      try {
+        const j = JSON.parse(body);
+        if (j?.error?.message) message = j.error.message;
+      } catch {
+      }
+      const err = new ServerError(`HTTP ${resp.status}: ${message}`, resp.status);
       cfg.onError?.(err);
       throw err;
     }
@@ -1049,6 +1061,32 @@ 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");
+  }
 };
 
 // src/mock_client.ts
@@ -1162,6 +1200,11 @@ var MockHttpClient = class {
     this.calls.push({ method, args });
   }
 };
+
+// src/http_types.ts
+function chatContent(response) {
+  return response.choices[0]?.message?.content ?? "";
+}
 export {
   AgentClient,
   ConnectionError,
@@ -1172,5 +1215,6 @@ export {
   TimeoutError,
   ToolNotFoundError,
   ValidationError,
-  WauldoError
+  WauldoError,
+  chatContent
 };

package/package.json

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