wauldo 0.1.1 → 0.3.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

@@ -312,6 +312,58 @@ 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;
+}
 /** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
 interface ChatClientLike {
     chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
@@ -469,6 +521,36 @@ 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>;
 }
 
 /**
@@ -589,4 +671,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 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 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, ValidationError, type VerifyCitationRequest, type VerifyCitationResponse, WauldoError, chatContent };

package/dist/index.d.ts

@@ -312,6 +312,58 @@ 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;
+}
 /** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
 interface ChatClientLike {
     chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
@@ -469,6 +521,36 @@ 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>;
 }
 
 /**
@@ -589,4 +671,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 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 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, ValidationError, type VerifyCitationRequest, type VerifyCitationResponse, WauldoError, chatContent };

package/dist/index.js

@@ -1097,6 +1097,53 @@ 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");
+  }
 };
 
 // src/mock_client.ts

package/dist/index.mjs

@@ -1061,6 +1061,53 @@ 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");
+  }
 };
 
 // src/mock_client.ts

package/package.json

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