wauldo 0.2.0 → 0.4.0

package/README.md

@@ -11,7 +11,9 @@ Official TypeScript SDK for the [Wauldo API](https://wauldo.com) — the AI infe
 
 ## Why Wauldo?
 
-- **Fact-Check API** — verify any claim against source context, get verdict (verified/weak/rejected), action (allow/review/block), and structured reason
+- **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

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;
@@ -340,6 +356,30 @@ interface FactCheckResponse {
     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>;
@@ -463,6 +503,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;
@@ -514,6 +567,19 @@ declare class HttpClient {
      * ```
      */
     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>;
 }
 
 /**
@@ -634,4 +700,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 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 };
+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 };

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;
@@ -340,6 +356,30 @@ interface FactCheckResponse {
     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>;
@@ -463,6 +503,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;
@@ -514,6 +567,19 @@ declare class HttpClient {
      * ```
      */
     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>;
 }
 
 /**
@@ -634,4 +700,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 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 };
+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 };

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 };
@@ -1123,6 +1178,27 @@ var HttpClient = class {
     );
     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

@@ -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 };
@@ -1087,6 +1142,27 @@ var HttpClient = class {
     );
     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.2.0",
+  "version": "0.4.0",
   "description": "Official TypeScript SDK for Wauldo — Verified AI answers from your documents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",