@doclo/core 0.1.12 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as ProviderVendor, A as AccessMethod } from './validation-wlK06puw.js';
-export { G as AggregatedMetrics, B as BBox, r as CategorizeNodeConfig, t as ChunkMetadata, v as ChunkNodeConfig, u as ChunkOutput, n as CitationConfig, k as CitationSourceType, w as CombineNodeConfig, U as CompatibilityRule, C as ConsensusConfig, e as ConsensusMetadata, d as ConsensusRunResult, D as DocumentIR, b as DocumentIRExtras, y as EnhancedExtractionSchema, s as ExtractInputMode, E as ExtractNodeConfig, a0 as ExtractedImage, m as FieldCitation, F as FieldVotingDetails, H as FlowContext, a8 as FlowExecutionError, h as FlowInput, i as FlowInputValidation, j as FlowResult, a4 as FlowStepLocation, a9 as FlowValidationError, I as IRLine, a as IRPage, X as JSONSchemaNode, c as LLMJsonProvider, L as LLMProvider, _ as LanguageOptions, l as LineCitation, g as MaybeWithConsensusMetadata, M as MultimodalInput, aa as NODE_COMPATIBILITY_MATRIX, J as NodeCtx, Q as NodeDef, K as NodeTypeInfo, T as NodeTypeName, N as NormalizedBBox, O as OCRProvider, a1 as OCRProviderOptions, x as OutputNodeConfig, o as OutputWithCitations, f as OutputWithConsensus, Z as PageRangeOptions, p as ParseNodeConfig, Y as ProcessingMode, a3 as ProviderCitation, am as ProviderIdentity, aj as RESERVED_VARIABLES, R as ReasoningConfig, $ as SegmentationResult, S as SplitDocument, q as SplitNodeConfig, z as StepMetric, V as VLMProvider, a2 as VLMProviderOptions, W as ValidationResult, a5 as aggregateMetrics, ah as canStartForEachItemFlow, aq as createIdentity, al as extractErrorMessage, ad as getCompatibleTargets, ac as getNodeTypeInfo, ab as getNodeTypeName, ae as getSuggestedConnections, ag as getValidForEachStarters, ap as isLocalEndpoint, a6 as node, ao as parseProviderString, ak as protectReservedVariables, a7 as runPipeline, an as toProviderString, ai as validateJson, af as validateNodeConnection } from './validation-wlK06puw.js';
+import { P as ProviderVendor, A as AccessMethod } from './validation-B8GRTtww.js';
+export { G as AggregatedMetrics, B as BBox, r as CategorizeNodeConfig, t as ChunkMetadata, v as ChunkNodeConfig, u as ChunkOutput, n as CitationConfig, k as CitationSourceType, w as CombineNodeConfig, U as CompatibilityRule, C as ConsensusConfig, e as ConsensusMetadata, d as ConsensusRunResult, D as DocumentIR, b as DocumentIRExtras, y as EnhancedExtractionSchema, s as ExtractInputMode, E as ExtractNodeConfig, a0 as ExtractedImage, m as FieldCitation, F as FieldVotingDetails, H as FlowContext, a8 as FlowExecutionError, h as FlowInput, i as FlowInputValidation, j as FlowResult, a4 as FlowStepLocation, a9 as FlowValidationError, I as IRLine, a as IRPage, X as JSONSchemaNode, c as LLMJsonProvider, L as LLMProvider, _ as LanguageOptions, l as LineCitation, g as MaybeWithConsensusMetadata, M as MultimodalInput, aa as NODE_COMPATIBILITY_MATRIX, J as NodeCtx, Q as NodeDef, K as NodeTypeInfo, T as NodeTypeName, N as NormalizedBBox, O as OCRProvider, a1 as OCRProviderOptions, x as OutputNodeConfig, o as OutputWithCitations, f as OutputWithConsensus, Z as PageRangeOptions, p as ParseNodeConfig, Y as ProcessingMode, a3 as ProviderCitation, am as ProviderIdentity, aj as RESERVED_VARIABLES, R as ReasoningConfig, $ as SegmentationResult, S as SplitDocument, q as SplitNodeConfig, z as StepMetric, V as VLMProvider, a2 as VLMProviderOptions, W as ValidationResult, a5 as aggregateMetrics, ah as canStartForEachItemFlow, aq as createIdentity, al as extractErrorMessage, ad as getCompatibleTargets, ac as getNodeTypeInfo, ab as getNodeTypeName, ae as getSuggestedConnections, ag as getValidForEachStarters, ap as isLocalEndpoint, a6 as node, ao as parseProviderString, ak as protectReservedVariables, a7 as runPipeline, an as toProviderString, ai as validateJson, af as validateNodeConnection } from './validation-B8GRTtww.js';
 export { getDocumentPageCount, getPDFPageCount, getPageCountMetadata, getTotalPageCount, splitPDFIntoChunks } from './pdf-utils.js';
 
 /**
@@ -511,6 +511,22 @@ type OutputFormatSupport = {
     html: boolean;
     json: boolean;
 };
+/**
+ * Feature status values for normalized features.
+ * - `true`: Natively supported by the API
+ * - `false`: Not supported
+ * - `'deprecated'`: API deprecated this feature, may not work
+ * - `'derived'`: SDK provides via transformation (e.g., maxPages from pageRange)
+ */
+type FeatureStatus = true | false | 'deprecated' | 'derived';
+/**
+ * Helper to check if a feature is enabled (true, deprecated, or derived)
+ */
+declare function isFeatureEnabled(status: FeatureStatus): boolean;
+/**
+ * Page indexing convention used by provider
+ */
+type PageIndexing = '0-indexed' | '1-indexed';
 /**
  * Normalized features across all providers.
  * Maps provider-specific option names to unified names.
@@ -520,47 +536,77 @@ type OutputFormatSupport = {
  */
 type NormalizedFeatures = {
     /** Limit to first N pages */
-    maxPages: boolean;
+    maxPages: FeatureStatus;
     /** Specific page range selection */
-    pageRange: boolean;
+    pageRange: FeatureStatus;
     /** OCR language hints (maps from 'langs') */
-    languageHints: boolean;
+    languageHints: FeatureStatus;
     /** Quality/speed modes (fast/balanced/high_accuracy) */
-    processingModes: boolean;
+    processingModes: FeatureStatus;
     /** Reducto agentic mode (higher accuracy, more cost) */
-    agenticMode: boolean;
+    agenticMode: FeatureStatus;
     /** Custom prompts (maps from blockCorrectionPrompt, additionalPrompt, systemPrompt) */
-    customPrompts: boolean;
+    customPrompts: FeatureStatus;
     /** Extract embedded images (maps from extractImages, returnImages) */
-    imageExtraction: boolean;
+    imageExtraction: FeatureStatus;
     /** Page delimiters (maps from paginate, addPageMarkers) */
-    pageMarkers: boolean;
-    /** Field-level citations with source references */
-    citations: boolean;
+    pageMarkers: FeatureStatus;
+    /** Field-level citations with source references (page/char/block indices) */
+    citations: FeatureStatus;
     /** Document chunking modes (RAG-optimized) */
-    chunking: boolean;
+    chunking: FeatureStatus;
     /** Auto-segmentation for multi-document PDFs */
-    segmentation: boolean;
+    segmentation: FeatureStatus;
     /** Re-run OCR on already-OCR'd documents */
-    stripExistingOCR: boolean;
+    stripExistingOCR: FeatureStatus;
     /** Format lines in output */
-    formatLines: boolean;
+    formatLines: FeatureStatus;
     /** Force OCR even if text layer exists */
-    forceOCR: boolean;
+    forceOCR: FeatureStatus;
     /** Table format options (html/json/md/csv) */
-    tableOutputFormats: boolean;
+    tableOutputFormats: FeatureStatus;
     /** Merge consecutive tables */
-    tableMerging: boolean;
+    tableMerging: FeatureStatus;
     /** Block-level confidence scores */
-    confidence: boolean;
-    /** Bounding box coordinates for text/elements */
-    boundingBoxes: boolean;
+    confidence: FeatureStatus;
+    /** Bounding box coordinates for TEXT elements (pixel/normalized coords) */
+    boundingBoxes: FeatureStatus;
+    /** Bounding box coordinates for IMAGES/FIGURES only (not text) */
+    imageBoundingBoxes: FeatureStatus;
     /** JSON schema validation for structured output */
-    schemaValidation: boolean;
+    schemaValidation: FeatureStatus;
     /** Handwritten text recognition support */
-    handwrittenText: boolean;
+    handwrittenText: FeatureStatus;
     /** Separate header/footer extraction from main content */
-    headerFooterExtraction: boolean;
+    headerFooterExtraction: FeatureStatus;
+    /** Optimize output for embeddings/RAG */
+    embedOptimized: FeatureStatus;
+    /** Handle encrypted/password-protected PDFs */
+    passwordProtected: FeatureStatus;
+    /** Filter block types (headers, footers, page numbers, etc.) */
+    contentFiltering: FeatureStatus;
+    /** OCR system/mode selection (standard/legacy, auto/full) */
+    ocrMode: FeatureStatus;
+    /** Async completion webhook callbacks */
+    webhookCallback: FeatureStatus;
+    /** Vision quality control (low/medium/high) - Gemini */
+    mediaResolution: FeatureStatus;
+    /** Track changes extraction from Word docs */
+    changeTracking: FeatureStatus;
+    /** Extract hyperlinks from documents */
+    hyperlinkExtraction: FeatureStatus;
+    /** Enhanced chart and graph interpretation (Datalab extras=chart_understanding) */
+    chartUnderstanding: FeatureStatus;
+    /** Control image caption generation (Datalab disable_image_captions) */
+    imageCaptions: FeatureStatus;
+    /** Extract signatures from documents (Reducto include: ["signatures"]) */
+    signatureExtraction: FeatureStatus;
+    /** Extract comments/annotations from documents (Reducto include: ["comments"]) */
+    commentExtraction: FeatureStatus;
+    /** Extract highlighted text from documents (Reducto include: ["highlight"]) */
+    highlightExtraction: FeatureStatus;
+    /** Summarize figures/charts with VLM (Reducto summarize_figures) */
+    figureSummaries: FeatureStatus;
     /** Supported output formats */
     outputFormats: OutputFormatSupport;
 };
@@ -929,6 +975,64 @@ declare function getAllModels(): ResolvedModelMetadata[];
  * Clear model registry (useful for testing)
  */
 declare function clearModelRegistry(): void;
+/**
+ * Get the page indexing convention for a provider.
+ *
+ * @param provider - Provider metadata or source string
+ * @returns Page indexing convention ('0-indexed' or '1-indexed')
+ */
+declare function getPageIndexing(provider: NormalizedProviderMetadata | string): PageIndexing;
+/**
+ * Options that can be transformed for derived features.
+ */
+type DerivedFeatureOptions = {
+    maxPages?: number;
+    pageRange?: string;
+};
+/**
+ * Result of derived feature transformation.
+ */
+type TransformedOptions = {
+    /** The transformed page_range parameter (provider-specific format) */
+    page_range?: string;
+    /** Array format for providers that support it (e.g., Mistral) */
+    pages?: number[];
+    /** Original options minus the derived ones */
+    remainingOptions: Record<string, unknown>;
+};
+/**
+ * Transform maxPages to provider-specific pageRange format.
+ *
+ * This utility handles the conversion when a provider has `maxPages: 'derived'`,
+ * meaning the SDK provides maxPages functionality via the underlying pageRange API.
+ *
+ * @param options - User-provided options including maxPages
+ * @param provider - Provider metadata to determine format
+ * @returns Transformed options with provider-specific pageRange
+ *
+ * @example
+ * ```typescript
+ * // User wants first 5 pages from Reducto (1-indexed)
+ * const result = transformDerivedFeatures({ maxPages: 5 }, reductoProvider);
+ * // => { page_range: '1-5', remainingOptions: {} }
+ *
+ * // User wants first 5 pages from Datalab (0-indexed)
+ * const result = transformDerivedFeatures({ maxPages: 5 }, datalabProvider);
+ * // => { page_range: '0-4', remainingOptions: {} }
+ *
+ * // User wants first 5 pages from Mistral (0-indexed, array format)
+ * const result = transformDerivedFeatures({ maxPages: 5 }, mistralProvider);
+ * // => { page_range: '0-4', pages: [0,1,2,3,4], remainingOptions: {} }
+ * ```
+ */
+declare function transformDerivedFeatures(options: DerivedFeatureOptions & Record<string, unknown>, provider: NormalizedProviderMetadata): TransformedOptions;
+/**
+ * Check if a provider requires derived feature transformation for maxPages.
+ *
+ * @param provider - Provider metadata
+ * @returns true if maxPages needs to be transformed to pageRange
+ */
+declare function requiresMaxPagesTransformation(provider: NormalizedProviderMetadata): boolean;
 
 /**
  * @doclo/core - Retry Utilities
@@ -1090,4 +1194,4 @@ declare function getCircuitBreaker(key: string): CircuitBreaker | undefined;
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: WithRetryOptions<T>): Promise<T>;
 
-export { type AcceptedMimeType, AccessMethod, type AllAutoVariables, type AutoVariablesForNode, type BaseProviderConfig, type CategorizeAutoVariables, type CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerState, DEFAULT_CIRCUIT_BREAKER_CONFIG, DEFAULT_RETRY_CONFIG, type DocumentMimeType, type ExtractAutoVariables, type FeatureName, FlowInputValidationError, type InputRequirements, type ModelMetadata, type ModelQueryFilter, type NormalizedCapabilities, type NormalizedFeatures, type NormalizedProviderMetadata, type OCRProviderConfig, type OutputFormatSupport, type ParseAutoVariables, type PromptVariables, type ProviderConfig, type ProviderInputType, type ProviderInstance, type ProviderMetadataWithModels, type ProviderQueryFilter, type ProviderRegistry, type ProviderSecrets, ProviderVendor, type ResolvedModelMetadata, type RetryConfig, type VLMProviderConfig, type WithRetryOptions, bufferToBase64, bufferToDataUri, buildProviderFromConfig, buildProvidersFromConfigs, calculateRetryDelay, clearCircuitBreakers, clearModelRegistry, clearProviderRegistry, createCircuitBreaker, defineMarkerProvider, defineSuryaProvider, defineVLMProvider, detectDocumentType, detectMimeTypeFromBase64, detectMimeTypeFromBase64Async, detectMimeTypeFromBytes, extractBase64, extractStatusCode, getAllModels, getAllProviders, getCheapestProviderFor, getCircuitBreaker, getModelsForNode, getProviderById, getProvidersBySource, getProvidersForLargeFiles, getProvidersForMimeType, isPDFDocument, isRetryableError, parseRetryAfter, queryModels, queryProviders, registerProviderMetadata, registerProviderWithModels, resolveDocument, resolveModelMetadata, validateFlowInputFormat, validateMimeType, validateMimeTypeAsync, withRetry };
+export { type AcceptedMimeType, AccessMethod, type AllAutoVariables, type AutoVariablesForNode, type BaseProviderConfig, type CategorizeAutoVariables, type CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerState, DEFAULT_CIRCUIT_BREAKER_CONFIG, DEFAULT_RETRY_CONFIG, type DerivedFeatureOptions, type DocumentMimeType, type ExtractAutoVariables, type FeatureName, type FeatureStatus, FlowInputValidationError, type InputRequirements, type ModelMetadata, type ModelQueryFilter, type NormalizedCapabilities, type NormalizedFeatures, type NormalizedProviderMetadata, type OCRProviderConfig, type OutputFormatSupport, type PageIndexing, type ParseAutoVariables, type PromptVariables, type ProviderConfig, type ProviderInputType, type ProviderInstance, type ProviderMetadataWithModels, type ProviderQueryFilter, type ProviderRegistry, type ProviderSecrets, ProviderVendor, type ResolvedModelMetadata, type RetryConfig, type TransformedOptions, type VLMProviderConfig, type WithRetryOptions, bufferToBase64, bufferToDataUri, buildProviderFromConfig, buildProvidersFromConfigs, calculateRetryDelay, clearCircuitBreakers, clearModelRegistry, clearProviderRegistry, createCircuitBreaker, defineMarkerProvider, defineSuryaProvider, defineVLMProvider, detectDocumentType, detectMimeTypeFromBase64, detectMimeTypeFromBase64Async, detectMimeTypeFromBytes, extractBase64, extractStatusCode, getAllModels, getAllProviders, getCheapestProviderFor, getCircuitBreaker, getModelsForNode, getPageIndexing, getProviderById, getProvidersBySource, getProvidersForLargeFiles, getProvidersForMimeType, isFeatureEnabled, isPDFDocument, isRetryableError, parseRetryAfter, queryModels, queryProviders, registerProviderMetadata, registerProviderWithModels, requiresMaxPagesTransformation, resolveDocument, resolveModelMetadata, transformDerivedFeatures, validateFlowInputFormat, validateMimeType, validateMimeTypeAsync, withRetry };