@doclo/providers-llm 0.1.8 → 0.1.10

package/dist/index.d.ts

@@ -67,6 +67,8 @@ interface MultimodalInput {
     text?: string;
     images?: ImageInput[];
     pdfs?: PDFInput[];
+    /** Optional system message (text-only, prepended to conversation) */
+    systemPrompt?: string;
 }
 /** Response metrics */
 interface ResponseMetrics {
@@ -134,6 +136,27 @@ interface LLMDerivedOptions {
     maxChunkSize?: number;
     /** Language hints for the document */
     languageHints?: string[];
+    /**
+     * Normalize date fields to ISO 8601 format (YYYY-MM-DD)
+     * When enabled, date fields in the extraction output will be formatted consistently.
+     * Native support: Extend.ai (extend:type: "date")
+     * LLM support: Via prompting
+     */
+    dateNormalization?: boolean;
+    /**
+     * Normalize currency fields to { amount: number, currency: string } objects
+     * When enabled, monetary values are extracted as structured objects with ISO 4217 currency codes.
+     * Native support: Extend.ai (extend:type: "currency")
+     * LLM support: Via prompting
+     */
+    currencyNormalization?: boolean;
+    /**
+     * Detect and extract signature fields from documents
+     * When enabled, signature presence is detected and locations are reported.
+     * Native support: Extend.ai (extend:type: "signature"), Reducto
+     * LLM support: Via prompting (less reliable)
+     */
+    signatureDetection?: boolean;
 }
 /**
  * Extracted metadata from LLM response (populated when derived options are enabled)
@@ -160,6 +183,25 @@ interface LLMExtractedMetadata {
         text: string;
         pages: number[];
     }>;
+    /** Detected signatures with location and confidence */
+    signatures?: Array<{
+        field: string;
+        detected: boolean;
+        bbox?: [number, number, number, number];
+        page?: number;
+        confidence?: number;
+    }>;
+    /** Normalized currency values (original → normalized mapping) */
+    normalizedCurrencies?: Record<string, {
+        original: string;
+        amount: number;
+        currency: string;
+    }>;
+    /** Normalized date values (original → normalized mapping) */
+    normalizedDates?: Record<string, {
+        original: string;
+        normalized: string;
+    }>;
 }
 /** Provider interface */
 interface LLMProvider {
@@ -457,7 +499,8 @@ declare class OpenAIProvider implements LLMProvider {
     private limits;
     constructor(config: ProviderConfig);
     completeJson<T>(params: {
-        input: MultimodalInput;
+        input?: MultimodalInput;
+        prompt?: MultimodalInput | string;
         schema?: UnifiedSchema<T>;
         mode?: JsonMode;
         max_tokens?: number;
@@ -482,7 +525,8 @@ declare class AnthropicProvider implements LLMProvider {
     private limits;
     constructor(config: ProviderConfig);
     completeJson<T>(params: {
-        input: MultimodalInput;
+        input?: MultimodalInput;
+        prompt?: MultimodalInput | string;
         schema?: UnifiedSchema<T>;
         mode?: JsonMode;
         max_tokens?: number;
@@ -550,7 +594,8 @@ declare class XAIProvider implements LLMProvider {
     private limits;
     constructor(config: ProviderConfig);
     completeJson<T>(params: {
-        input: MultimodalInput;
+        input?: MultimodalInput;
+        prompt?: MultimodalInput | string;
         schema?: UnifiedSchema<T>;
         mode?: JsonMode;
         max_tokens?: number;

package/dist/index.js

@@ -343,25 +343,30 @@ var OpenAIProvider = class {
   }
   async completeJson(params) {
     const startTime = Date.now();
+    const rawInput = params.input ?? params.prompt;
+    if (!rawInput) {
+      throw new Error("Either input or prompt must be provided");
+    }
+    const normalizedInput = typeof rawInput === "string" ? { text: rawInput } : rawInput;
     const mode = params.mode || (params.schema ? "strict" : "relaxed");
     if (mode === "strict" && !params.schema) {
       throw new Error('schema is required when mode is "strict"');
     }
     const extractMetadata = shouldExtractMetadata(params.derivedOptions);
     const shouldEmbedSchema = params.embedSchemaInPrompt !== false && params.schema;
-    let enhancedInput = params.input;
+    let enhancedInput = normalizedInput;
     if (shouldEmbedSchema) {
       const jsonSchema = this.translator.convertZodIfNeeded(params.schema);
       const enhancedText = params.derivedOptions ? combineSchemaUserAndDerivedPrompts(
         jsonSchema,
-        params.input.text || "",
+        normalizedInput.text || "",
         params.derivedOptions
       ) : combineSchemaAndUserPrompt(
         jsonSchema,
-        params.input.text || ""
+        normalizedInput.text || ""
       );
       enhancedInput = {
-        ...params.input,
+        ...normalizedInput,
         text: enhancedText
       };
     } else if (params.derivedOptions) {
@@ -369,8 +374,8 @@ var OpenAIProvider = class {
       const derivedPrompt = buildLLMDerivedFeaturesPrompt2(params.derivedOptions);
       if (derivedPrompt) {
         enhancedInput = {
-          ...params.input,
-          text: (params.input.text || "") + "\n\n" + derivedPrompt
+          ...normalizedInput,
+          text: (normalizedInput.text || "") + "\n\n" + derivedPrompt
         };
       }
     }
@@ -496,6 +501,10 @@ var OpenAIProvider = class {
     return Object.keys(config).length > 0 ? config : void 0;
   }
   buildMessages(input) {
+    const messages = [];
+    if (input.systemPrompt) {
+      messages.push({ role: "system", content: input.systemPrompt });
+    }
     const content = [];
     if (input.text) {
       content.push({ type: "text", text: input.text });
@@ -536,7 +545,8 @@ var OpenAIProvider = class {
         });
       }
     }
-    return [{ role: "user", content }];
+    messages.push({ role: "user", content });
+    return messages;
   }
   /**
    * Extract base64 data from a data URL or return as-is if already raw base64
@@ -596,25 +606,30 @@ var AnthropicProvider = class {
   }
   async completeJson(params) {
     const startTime = Date.now();
+    const rawInput = params.input ?? params.prompt;
+    if (!rawInput) {
+      throw new Error("Either input or prompt must be provided");
+    }
+    const normalizedInput = typeof rawInput === "string" ? { text: rawInput } : rawInput;
     const mode = params.mode || (params.schema ? "strict" : "relaxed");
     if (mode === "strict" && !params.schema) {
       throw new Error('schema is required when mode is "strict"');
     }
     const extractMetadata = shouldExtractMetadata(params.derivedOptions);
     const shouldEmbedSchema = params.embedSchemaInPrompt !== false && params.schema;
-    let enhancedInput = params.input;
+    let enhancedInput = normalizedInput;
     if (shouldEmbedSchema) {
       const jsonSchema = this.translator.convertZodIfNeeded(params.schema);
       const enhancedText = params.derivedOptions ? combineSchemaUserAndDerivedPrompts(
         jsonSchema,
-        params.input.text || "",
+        normalizedInput.text || "",
         params.derivedOptions
       ) : combineSchemaAndUserPrompt(
         jsonSchema,
-        params.input.text || ""
+        normalizedInput.text || ""
       );
       enhancedInput = {
-        ...params.input,
+        ...normalizedInput,
         text: enhancedText
       };
     } else if (params.derivedOptions) {
@@ -622,8 +637,8 @@ var AnthropicProvider = class {
       const derivedPrompt = buildLLMDerivedFeaturesPrompt2(params.derivedOptions);
       if (derivedPrompt) {
         enhancedInput = {
-          ...params.input,
-          text: (params.input.text || "") + "\n\n" + derivedPrompt
+          ...normalizedInput,
+          text: (normalizedInput.text || "") + "\n\n" + derivedPrompt
         };
       }
     }
@@ -632,7 +647,9 @@ var AnthropicProvider = class {
     const requestBody = {
       model: this.config.model,
       max_tokens: params.max_tokens || 4096,
-      messages
+      messages,
+      // Native Anthropic API uses separate system parameter (text-only)
+      ...enhancedInput.systemPrompt && { system: enhancedInput.systemPrompt }
     };
     if (mode === "relaxed") {
       requestBody.messages.push({
@@ -677,7 +694,7 @@ var AnthropicProvider = class {
     let costUSD;
     if (this.config.via === "openrouter") {
       const useNewStructuredOutputs2 = this.supportsNewStructuredOutputs();
-      const openRouterRequest = this.translateToOpenRouterFormat(messages, params.schema, mode, params.max_tokens, params.reasoning);
+      const openRouterRequest = this.translateToOpenRouterFormat(messages, params.schema, mode, params.max_tokens, params.reasoning, enhancedInput.systemPrompt);
       if (process.env.DEBUG_PROVIDERS) {
         console.log("[AnthropicProvider] OpenRouter request body (messages):");
         console.log(JSON.stringify(openRouterRequest.messages, null, 2));
@@ -863,11 +880,15 @@ var AnthropicProvider = class {
       budget_tokens
     };
   }
-  translateToOpenRouterFormat(messages, schema, mode, max_tokens, reasoning) {
+  translateToOpenRouterFormat(messages, schema, mode, max_tokens, reasoning, systemPrompt) {
     const useNewStructuredOutputs = this.supportsNewStructuredOutputs();
+    const jsonInstructions = mode === "strict" ? "You must respond ONLY with valid JSON that matches the provided schema. Do not include any markdown formatting, explanations, or additional text." : "You must respond ONLY with valid JSON. Do not include any markdown formatting, explanations, or additional text.";
+    const systemContent = systemPrompt ? `${systemPrompt}
+
+${jsonInstructions}` : `You are a data extraction assistant. ${jsonInstructions}`;
     const systemMessage = {
       role: "system",
-      content: mode === "strict" ? "You are a data extraction assistant. You must respond ONLY with valid JSON that matches the provided schema. Do not include any markdown formatting, explanations, or additional text." : "You are a data extraction assistant. You must respond ONLY with valid JSON. Do not include any markdown formatting, explanations, or additional text."
+      content: systemContent
     };
     const messageArray = [systemMessage, ...messages];
     const requestBody = {
@@ -1281,6 +1302,10 @@ var GoogleProvider = class {
         // Use JSON mode without responseSchema - schema is already in the prompt via combineSchemaAndUserPrompt.
         // See: https://ubaidullahmomer.medium.com/why-google-geminis-response-schema-isn-t-ready-for-complex-json-46f35c3aaaea
         responseMimeType: "application/json"
+      },
+      // Native Gemini API uses systemInstruction with parts array (text-only)
+      ...enhancedInput.systemPrompt && {
+        systemInstruction: { parts: [{ text: enhancedInput.systemPrompt }] }
       }
     };
     if (process.env.DEBUG_PROVIDERS) {
@@ -1297,7 +1322,7 @@ var GoogleProvider = class {
       console.log("[GoogleProvider] Using via:", this.config.via, "Checking:", this.config.via === "openrouter");
     }
     if (this.config.via === "openrouter") {
-      const openRouterRequest = this.translateToOpenRouterFormat(contents, mode, params.max_tokens, params.reasoning);
+      const openRouterRequest = this.translateToOpenRouterFormat(contents, mode, params.max_tokens, params.reasoning, enhancedInput.systemPrompt);
       response = await fetchWithTimeout3("https://openrouter.ai/api/v1/chat/completions", {
         method: "POST",
         headers: {
@@ -1409,8 +1434,11 @@ var GoogleProvider = class {
       thinking_budget
     };
   }
-  translateToOpenRouterFormat(contents, mode, max_tokens, reasoning) {
+  translateToOpenRouterFormat(contents, mode, max_tokens, reasoning, systemPrompt) {
     const messages = [];
+    if (systemPrompt) {
+      messages.push({ role: "system", content: systemPrompt });
+    }
     for (const content of contents) {
       if (content.role === "user") {
         const messageContent = [];
@@ -1596,25 +1624,30 @@ var XAIProvider = class {
   }
   async completeJson(params) {
     const startTime = Date.now();
+    const rawInput = params.input ?? params.prompt;
+    if (!rawInput) {
+      throw new Error("Either input or prompt must be provided");
+    }
+    const normalizedInput = typeof rawInput === "string" ? { text: rawInput } : rawInput;
     const mode = params.mode || (params.schema ? "strict" : "relaxed");
     if (mode === "strict" && !params.schema) {
       throw new Error('schema is required when mode is "strict"');
     }
     const extractMetadata = shouldExtractMetadata(params.derivedOptions);
     const shouldEmbedSchema = params.embedSchemaInPrompt !== false && params.schema;
-    let enhancedInput = params.input;
+    let enhancedInput = normalizedInput;
     if (shouldEmbedSchema) {
       const jsonSchema = this.translator.convertZodIfNeeded(params.schema);
       const enhancedText = params.derivedOptions ? combineSchemaUserAndDerivedPrompts(
         jsonSchema,
-        params.input.text || "",
+        normalizedInput.text || "",
         params.derivedOptions
       ) : combineSchemaAndUserPrompt(
         jsonSchema,
-        params.input.text || ""
+        normalizedInput.text || ""
       );
       enhancedInput = {
-        ...params.input,
+        ...normalizedInput,
         text: enhancedText
       };
     } else if (params.derivedOptions) {
@@ -1622,8 +1655,8 @@ var XAIProvider = class {
       const derivedPrompt = buildLLMDerivedFeaturesPrompt2(params.derivedOptions);
       if (derivedPrompt) {
         enhancedInput = {
-          ...params.input,
-          text: (params.input.text || "") + "\n\n" + derivedPrompt
+          ...normalizedInput,
+          text: (normalizedInput.text || "") + "\n\n" + derivedPrompt
         };
       }
     }
@@ -1748,6 +1781,10 @@ var XAIProvider = class {
     return Object.keys(config).length > 0 ? config : void 0;
   }
   async buildMessages(input) {
+    const messages = [];
+    if (input.systemPrompt) {
+      messages.push({ role: "system", content: input.systemPrompt });
+    }
     const content = [];
     if (input.text) {
       content.push({ type: "text", text: input.text });
@@ -1788,7 +1825,8 @@ var XAIProvider = class {
         });
       }
     }
-    return [{ role: "user", content }];
+    messages.push({ role: "user", content });
+    return messages;
   }
   /**
    * Extract base64 data from a data URL or return as-is if already raw base64