// This file is auto-generated by alef — DO NOT EDIT.
// alef:hash:7e723dc88906267241296254002a983ed79eebe3ca5959fc6203f72917e562ce
// To regenerate: alef generate
// To verify freshness: alef verify
/* eslint-disable */

export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };

/**
 * Classify a document's chunks and return the updated document.
 *
 * This owned form preserves the mutations when the document crosses a language-binding boundary.
 * Rust callers that already own a mutable document can use `classify_chunks` to avoid moving it.
 * @throws Returns the same validation and LLM errors as `classify_chunks`.
 */
export declare function classifyChunksOwned(
  config: ChunkClassificationConfig,
  result?: ExtractedDocument | undefined | null,
): Promise<ExtractedDocument>;

/**
 * Clear all document extractors from the global registry.
 *
 * Calls `shutdown()` on every registered extractor, then empties the registry.
 * @throws - Any error returned by an extractor's `shutdown()` method. The first error
 *   encountered stops processing of remaining extractors.
 */
export declare function clearDocumentExtractors(): void;

/**
 * Clear all embedding backends from the global registry.
 *
 * Calls `shutdown()` on every registered backend, then empties the registry.
 * @throws - Any error returned by a backend's `shutdown()` method. The first error
 *   encountered stops processing of remaining backends.
 */
export declare function clearEmbeddingBackends(): void;

/**
 * Clear all OCR backends from the global registry.
 *
 * Removes all OCR backends and calls their `shutdown()` methods.
 * @returns - `Ok(())` if all backends were cleared successfully
 * - `Err(...)` if any shutdown method failed
 */
export declare function clearOcrBackends(): void;

/**
 * Remove all registered post-processors.
 *
 * The next post-processed extraction restores enabled built-in processors before it snapshots
 * the processor cache. Custom processors remain removed. Use `unregister_post_processor` when
 * one named processor should remain absent while the rest of the registry stays intact.
 * Returns a retryable in-use error when an extraction is executing a processor snapshot.
 */
export declare function clearPostProcessors(): void;

/**
 * Clear all renderers from the global registry.
 *
 * Removes every renderer, including the built-in defaults (markdown, html,
 * djot, plain). After calling this no renderers are registered; re-register
 * as needed.
 * @throws Returns an error if the registry lock is poisoned.
 */
export declare function clearRenderers(): void;

/**
 * Clear all reranker backends from the global registry.
 *
 * Calls `shutdown()` on every registered backend, then empties the registry.
 * @throws - Any error returned by a backend's `shutdown()` method. The first error
 *   encountered stops processing of remaining backends.
 */
export declare function clearRerankerBackends(): void;

/**
 * Clear all tokenizer backends from the global registry.
 *
 * Calls `shutdown()` on every registered backend, then empties the registry.
 * @throws - Any error returned by a backend's `shutdown()` method. The first error
 *   encountered stops processing of remaining backends.
 */
export declare function clearTokenizerBackends(): void;

/** Remove all registered validators. */
export declare function clearValidators(): void;

/**
 * Probe the backends and settings in `config` and report what will actually
 * execute on this host.
 *
 * Runs no downloads and no billable API calls. Backends that are not compiled
 * in or whose models are not cached report `Skip` rather than failing.
 */
export declare function doctor(config?: ExtractionConfig | undefined | null): DoctorReport;

/** Extract content from a single bytes or URI input. */
export declare function extract(
  input?: ExtractInput | undefined | null,
  config?: ExtractionConfig | undefined | null,
): Promise<ExtractionResult>;

/** Extract content from multiple bytes or URI inputs. */
export declare function extractBatch(
  inputs: Array<ExtractInput>,
  config?: ExtractionConfig | undefined | null,
): Promise<ExtractionResult>;

/**
 * Find unmarked claims in markdown text.
 *
 * Returns lines that assert a claim but carry neither a footnote citation anchor (`[^...]`)
 * nor an inference marker (`[*inference*]`).
 *
 * The heuristic is simple: a line that contains alphabetic words, ends with sentence punctuation,
 * and is not a heading, blank line, or markup-only line is considered a claim.
 * Exclude lines that appear in the citation block (after `---` + `<!-- citations ... -->`).
 * @param markdown - The markdown text to search
 *
 * @returns A vector of trimmed line text strings for unmarked claims.
 */
export declare function findUnmarkedClaims(markdown: string): Array<string>;

/**
 * Hardware acceleration configuration for ONNX Runtime models.
 *
 * Controls which execution provider (CPU, CoreML, CUDA, TensorRT) is used
 * for inference in layout detection and embedding generation.
 */
export interface AccelerationConfig {
  /** Execution provider to use for ONNX inference. */
  readonly provider?: ExecutionProviderType;
  /** GPU device ID (for CUDA/TensorRT). Ignored for CPU/CoreML/Auto. */
  readonly deviceId?: number;
}

/** Types of inline text annotations. */
export type AnnotationKind =
  | { annotation_type: "bold" }
  | { annotation_type: "italic" }
  | { annotation_type: "underline" }
  | { annotation_type: "strikethrough" }
  | { annotation_type: "code" }
  | { annotation_type: "subscript" }
  | { annotation_type: "superscript" }
  | { annotation_type: "link"; url: string; title: string }
  | { annotation_type: "highlight" }
  | { annotation_type: "color"; value: string }
  | { annotation_type: "font_size"; value: string }
  | { annotation_type: "custom"; name: string; value: string };

/**
 * A single file extracted from an archive.
 *
 * When archives (ZIP, TAR, 7Z, GZIP) are extracted with recursive extraction
 * enabled, each processable file produces its own full `ExtractedDocument`.
 */
export interface ArchiveEntry {
  /** Archive-relative file path (e.g. "folder/document.pdf"). */
  readonly path: string;
  /** Detected MIME type of the file. */
  readonly mimeType: string;
  /** Full extraction result for this file. */
  readonly result: ExtractedDocument;
}

/**
 * Archive (ZIP/TAR/7Z) metadata.
 *
 * Extracted from compressed archive files containing file lists and size information.
 */
export interface ArchiveMetadata {
  /** Archive format ("ZIP", "TAR", "7Z", etc.) */
  readonly format?: string;
  /** Total number of files in the archive */
  readonly fileCount?: number;
  /** List of file paths within the archive */
  readonly fileList?: Array<string>;
  /** Total uncompressed size in bytes */
  readonly totalSize?: number;
  /** Compressed size in bytes (if available) */
  readonly compressedSize?: number;
}

/** The category of a downloaded asset. */
export declare enum AssetCategory {
  /** A document file (PDF, DOC, etc.). */
  Document = "document",
  /** An image file. */
  Image = "image",
  /** An audio file. */
  Audio = "audio",
  /** A video file. */
  Video = "video",
  /** A font file. */
  Font = "font",
  /** A CSS stylesheet. */
  Stylesheet = "stylesheet",
  /** A JavaScript file. */
  Script = "script",
  /** An archive file (ZIP, TAR, etc.). */
  Archive = "archive",
  /** A data file (JSON, XML, CSV, etc.). */
  Data = "data",
  /** An unrecognized asset type. */
  Other = "other",
}

/**
 * Element attributes in Djot.
 *
 * Represents the attributes attached to elements using {.class #id key="value"} syntax.
 */
export interface Attributes {
  /** Element ID (#identifier) */
  readonly id?: string;
  /** CSS classes (.class1 .class2) */
  readonly classes?: Array<string>;
  /** Key-value pairs (key="value") */
  readonly keyValues?: Array<KeyValueAttribute>;
}

/**
 * Audio/video file metadata.
 *
 * Populated from container tags (ID3v2, MP4 atoms, Vorbis comments, etc.) and
 * PCM decode properties. Available when the `transcription-types` feature is enabled.
 */
export interface AudioMetadata {
  /** Duration in milliseconds derived from the decoded audio stream. */
  readonly durationMs?: number;
  /** Audio codec (e.g. "mp3", "aac", "opus", "flac"). */
  readonly codec?: string;
  /** Container format (e.g. "mpeg", "mp4", "ogg", "wav"). */
  readonly container?: string;
  /** Sample rate in Hz after decode (always 16000 when resampled for Whisper). */
  readonly sampleRateHz?: number;
  /** Number of audio channels (1 = mono, 2 = stereo). */
  readonly channels?: number;
  /** Audio bitrate in kbps from the source file tags/properties. */
  readonly bitrate?: number;
}

/** Authentication configuration. */
export type AuthConfig =
  | { type: "basic"; username: string; password: string }
  | { type: "bearer"; token: string }
  | { type: "header"; name: string; value: string };

/** Bounding box in original image coordinates (x1, y1) top-left, (x2, y2) bottom-right. */
export interface BBox {
  /** Left edge (x-coordinate of the top-left corner). */
  readonly x1: number;
  /** Top edge (y-coordinate of the top-left corner). */
  readonly y1: number;
  /** Right edge (x-coordinate of the bottom-right corner). */
  readonly x2: number;
  /** Bottom edge (y-coordinate of the bottom-right corner). */
  readonly y2: number;
}

/**
 * AWS Bedrock configuration for `bedrock/`-prefixed models.
 *
 * Mirrors liter-llm's `BedrockConfig`. Every field is optional: anything left
 * unset falls back to the standard AWS environment variables
 * (`AWS_DEFAULT_REGION` / `AWS_REGION`, `AWS_ACCESS_KEY_ID`,
 * `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `BEDROCK_CROSS_REGION`) and the
 * default AWS credential chain. Leave the credential fields unset unless you
 * have an explicit reason to pin them.
 * @example
 * ```typescript
 * [ocr.vlm_config]
 * model = "bedrock/anthropic.claude-3-sonnet-20240229-v1:0"
 *
 * [ocr.vlm_config.bedrock]
 * region = "eu-central-1"
 * cross_region_prefix = "eu"
 * ```
 *
 * `Debug` is implemented by hand so the three credential fields are never printed.
 */
export interface BedrockConfig {
  /** AWS region (e.g. `"us-east-1"`). */
  readonly region?: string;
  /** Cross-region inference profile prefix (e.g. `"us"`). */
  readonly crossRegionPrefix?: string;
  /** Explicit AWS access key ID. Secret — never logged. */
  readonly accessKeyId?: string;
  /** Explicit AWS secret access key. Secret — never logged. */
  readonly secretAccessKey?: string;
  /** Explicit AWS session token for temporary credentials. Secret — never logged. */
  readonly sessionToken?: string;
}

/** BibTeX bibliography metadata. */
export interface BibtexMetadata {
  /** Number of entries in the bibliography. */
  readonly entryCount?: number;
  /** BibTeX citation keys (e.g. `"knuth1984"`) for all entries. */
  readonly citationKeys?: Array<string>;
  /** Author names collected across all bibliography entries. */
  readonly authors?: Array<string>;
  /** Earliest and latest publication years found in the bibliography. */
  readonly yearRange?: YearRange;
  /** Count of entries grouped by BibTeX entry type (e.g. `"article"` → 5). */
  readonly entryTypes?: Record<string, number>;
}

/** Types of block-level elements in Djot. */
export declare enum BlockType {
  /** Standard prose paragraph. */
  Paragraph = "paragraph",
  /** Section heading (level stored in `FormattedBlock.level`). */
  Heading = "heading",
  /** Block quotation container. */
  Blockquote = "blockquote",
  /** Fenced or indented code block. */
  CodeBlock = "code_block",
  /** Individual item within a list. */
  ListItem = "list_item",
  /** Numbered (ordered) list container. */
  OrderedList = "ordered_list",
  /** Unnumbered (bullet) list container. */
  BulletList = "bullet_list",
  /** Task / checkbox list container. */
  TaskList = "task_list",
  /** Definition list container. */
  DefinitionList = "definition_list",
  /** Term part of a definition list entry. */
  DefinitionTerm = "definition_term",
  /** Description / definition part of a definition list entry. */
  DefinitionDescription = "definition_description",
  /** Generic `div` container with optional attributes. */
  Div = "div",
  /** Logical section container, often associated with a heading. */
  Section = "section",
  /** Horizontal rule / thematic break. */
  ThematicBreak = "thematic_break",
  /** Raw content block in a specified format (e.g. HTML, LaTeX). */
  RawBlock = "raw_block",
  /** Display-mode mathematical expression. */
  MathDisplay = "math_display",
}

/** Reason for boundary detection. */
export declare enum BoundaryReason {
  /** Start of PDF. */
  Start = "start",
  /** Page-one marker ("Page 1", "1 of N") detected. */
  PageOneMarker = "page_one_marker",
  /** Letterhead reset after signature block. */
  LetterheadReset = "letterhead_reset",
  /** Text density shift with low bigram overlap. */
  DensityShift = "density_shift",
  /** End of PDF. */
  End = "end",
}

/** Bounding box coordinates for element positioning. */
export interface BoundingBox {
  /** Left x-coordinate */
  readonly x0?: number;
  /** Bottom y-coordinate */
  readonly y0?: number;
  /** Right x-coordinate */
  readonly x1?: number;
  /** Top y-coordinate */
  readonly y1?: number;
}

/** Browser backend used for JavaScript rendering. */
export declare enum BrowserBackend {
  /** Existing Chromium/CDP backend powered by chromiumoxide. */
  Chromiumoxide = "chromiumoxide",
  /** Crawlberg-owned native browser backend derived from Obscura. */
  Native = "native",
}

/** Browser fallback configuration. */
export interface BrowserConfig {
  /** When to use the headless browser fallback. */
  readonly mode?: BrowserMode;
  /** Browser backend used to render JavaScript-heavy pages. */
  readonly backend?: BrowserBackend;
  /** CDP WebSocket endpoint for connecting to an external browser instance. */
  readonly endpoint?: string;
  /** Timeout for browser page load and rendering (in milliseconds when serialized). */
  readonly timeout?: number;
  /** Wait strategy after browser navigation. */
  readonly wait?: BrowserWait;
  /** CSS selector to wait for when `wait` is `Selector`. */
  readonly waitSelector?: string;
  /** Extra time to wait after the wait condition is met. */
  readonly extraWait?: number;
  /**
   * Proxy for browser fetches. Overrides `CrawlConfig.proxy` when set.
   * Native backend supports http/https only (no SOCKS5).
   */
  readonly proxy?: ProxyConfig;
  /**
   * URL patterns to block before the network request fires. Supports `*`
   * wildcards. Useful for skipping ads/analytics/large images. Honored by
   * `BrowserBackend.Native`; chromiumoxide ignores this field today.
   */
  readonly blockUrlPatterns?: Array<string>;
  /**
   * JavaScript snippet evaluated after navigation completes.
   *
   * Scraping captures the native backend result in `ScrapeResult.browser.eval_result`.
   * Interactions run this script before page actions on both browser backends but do
   * not include the script result in `InteractionResult`.
   */
  readonly evalScript?: string;
  /**
   * User-agent used when fetching robots.txt. Defaults to `BrowserConfig.user_agent`
   * (or crawlberg's default) if unset. Native only.
   */
  readonly robotsUserAgent?: string;
  /**
   * Capture the full network event stream into the result. Default false
   * (only the document event is captured). Native only.
   */
  readonly captureNetworkEvents?: boolean;
  /**
   * Enable session affinity: reuse chromiumoxide Pages for same-domain
   * requests so cookies + fingerprint + solved challenges persist.
   * Default: true. When false, each request gets a fresh Page.
   */
  readonly sessionAffinity?: boolean;
}

/** When to use the headless browser fallback. */
export declare enum BrowserMode {
  /** Automatically detect when JS rendering is needed and fall back to browser. */
  Auto = "auto",
  /** Always use the browser for every request. */
  Always = "always",
  /** Never use the browser fallback. */
  Never = "never",
  /**
   * Always use the browser with all stealth surfaces enabled.
   *
   * Behaves like `Always` for escalation purposes
   * (every request is routed through the browser tier), but additionally
   * enables:
   *
   * - browser JavaScript stealth patches
   * - native-backend TLS fingerprint spoofing
   * - stealth-aware default user-agent when no explicit UA is set
   * - 1920×1080 viewport override
   *
   * Use this instead of setting the now-removed `BrowserConfig.stealth`
   * boolean field.
   */
  Stealth = "stealth",
}

/** Wait strategy for browser page rendering. */
export declare enum BrowserWait {
  /** Wait until network activity is idle. */
  NetworkIdle = "network_idle",
  /** Wait for a specific CSS selector to appear in the DOM. */
  Selector = "selector",
  /** Wait for a fixed duration after navigation. */
  Fixed = "fixed",
}

/** Aggregate statistics for a xberg cache directory. */
export interface CacheStats {
  /** Total number of files currently in the cache directory. */
  readonly totalFiles: number;
  /** Combined size of all cache files in megabytes. */
  readonly totalSizeMb: number;
  /** Free disk space available on the cache volume, in megabytes. */
  readonly availableSpaceMb: number;
  /** Age of the oldest cache file in days (0.0 if the cache is empty). */
  readonly oldestFileAgeDays: number;
  /** Age of the most recently written cache file in days (0.0 if the cache is empty). */
  readonly newestFileAgeDays: number;
}

/**
 * How a structured-extraction preset is dispatched to the model.
 *
 * This is the preset-facing call mode (the `preferred_call_mode` field of a
 * `Preset`). The structured pipeline has a richer
 * runtime-only decision enum with skip and fallback states; this 3-variant
 * type is the stable, serializable surface presets and bindings depend on.
 */
export declare enum CallMode {
  /** Use the extracted text only. */
  TextOnly = "text_only",
  /** Use rasterized page images only. */
  VisionOnly = "vision_only",
  /** Provide both extracted text and page images to the model. */
  TextPlusVision = "text_plus_vision",
}

/** Device selection shared by the typed candle backend option objects. */
export declare enum CandleDevicePreference {
  Auto = "auto",
  Cpu = "cpu",
  Cuda = "cuda",
  Metal = "metal",
}

/** TrOCR model variant accepted by `candle-trocr` backend options. */
export declare enum CandleTrocrVariant {
  BasePrinted = "base-printed",
  LargePrinted = "large-printed",
  BaseHandwritten = "base-handwritten",
  LargeHandwritten = "large-handwritten",
}

/** Configuration for the VLM captioning post-processor. */
export interface CaptioningConfig {
  /** LLM configuration used for the VLM call. */
  readonly llm: LlmConfig;
  /**
   * Optional custom caption prompt. `None` uses the default `RegionKind.Caption`
   * prompt that ships with `crate.llm.region_extractor`.
   */
  readonly prompt?: string;
  /**
   * Skip images whose `width * height` is below this threshold (in pixels).
   * Default `1_000` filters out icons and decorations.
   */
  readonly minImageArea: number;
}

/**
 * A single changed cell within a table.
 *
 * Defined here (rather than only in `crate.diff`) so `RevisionDelta` can
 * reference it unconditionally, without requiring the `diff` Cargo feature.
 * `crate.diff` re-exports this type verbatim.
 */
export interface CellChange {
  /** Zero-based row index. */
  readonly row: number;
  /** Zero-based column index. */
  readonly col: number;
  /** Value before the change. */
  readonly from: string;
  /** Value after the change. */
  readonly to: string;
}

/**
 * A text chunk with optional embedding and metadata.
 *
 * Chunks are created when chunking is enabled in `ExtractionConfig`. Each chunk
 * contains the text content, optional embedding vector (if embedding generation
 * is configured), and metadata about its position in the document.
 */
export interface Chunk {
  /** The text content of this chunk. */
  readonly content: string;
  /**
   * Semantic structural classification of this chunk.
   *
   * Assigned by the heuristic classifier based on content patterns and
   * heading context. Defaults to `ChunkType.Unknown` when no rule matches.
   */
  readonly chunkType: ChunkType;
  /**
   * Optional embedding vector for this chunk.
   *
   * Only populated when `EmbeddingConfig` is provided in chunking configuration.
   * The dimensionality depends on the chosen embedding model.
   */
  readonly embedding?: Array<number>;
  /**
   * Optional sparse (SPLADE) learned embedding for this chunk.
   *
   * Only populated when sparse-embedding generation is configured for chunking.
   * `None` otherwise, including on builds without the `sparse-embeddings` feature.
   *
   * Uses the crate-root `SparseEmbedding` alias rather than
   * `crate.sparse_embeddings.SparseEmbedding` directly: the `sparse_embeddings`
   * module itself only compiles under `sparse-embeddings`/`sparse-embedding-presets`,
   * while the crate-root alias is always defined (a field-compatible stub on builds
   * without either feature), so this field — and `Chunk` itself — compiles on every
   * feature combination, including the crate's default features.
   */
  readonly sparseEmbedding?: SparseEmbedding;
  /**
   * Optional ColBERT-style multi-vector (late-interaction) embedding for this chunk.
   *
   * Only populated when late-interaction embedding generation is configured for
   * chunking. `None` otherwise, including on builds without the `late-interaction`
   * feature.
   *
   * Uses the crate-root `MultiVectorEmbedding` alias for the same reason
   * `sparse_embedding` uses `SparseEmbedding` — see that field's docs.
   */
  readonly lateInteraction?: MultiVectorEmbedding;
  /** Metadata about this chunk's position and properties. */
  readonly metadata: ChunkMetadata;
}

/**
 * Configuration for the chunk-classification post-processor.
 *
 * Chunk classification is always multi-label: a chunk may match zero, one, or
 * many of the configured definitions. This is the chunk-level equivalent of
 * `PageClassificationConfig`, but scoped to individual chunks
 * (`ExtractedDocument.chunks`) rather than whole pages, and built for large
 * taxonomies where each label needs its own description rather than a bare name.
 */
export interface ChunkClassificationConfig {
  /**
   * Minijinja prompt template. Receives `{{ definitions }}` (rendered label +
   * description list) and `{{ chunks }}` (a numbered list of chunk texts in
   * the current batch) variables. `None` lets the backend pick a sensible
   * default.
   */
  readonly promptTemplate?: string;
  /**
   * The set of label definitions the classifier may emit. Must contain at
   * least one entry.
   */
  readonly definitions: Array<ChunkClassificationDefinition>;
  /** LLM configuration used for classification. */
  readonly llm: LlmConfig;
  /**
   * Number of chunks batched into a single LLM request.
   *
   * Larger batches amortize the fixed prompt cost (definitions block) across
   * more chunks, at the risk of exceeding the model's context window for
   * very large taxonomies or chunk texts. Defaults to `DEFAULT_BATCH_SIZE`.
   */
  readonly batchSize: number;
  /**
   * Maximum number of in-flight batch requests.
   *
   * Bounds concurrency against the configured LLM provider. Defaults to
   * `DEFAULT_MAX_CONCURRENCY`.
   */
  readonly maxConcurrency: number;
}

/**
 * A single labeled definition the chunk classifier may emit.
 *
 * Unlike `PageClassificationConfig.labels` (bare label names), chunk
 * classification targets potentially large domain taxonomies where every
 * label carries its own semantic description, letting the LLM disambiguate
 * similarly named labels without relying on the label string alone.
 */
export interface ChunkClassificationDefinition {
  /** Label name returned in `ChunkMetadata.classifications`. */
  readonly label: string;
  /**
   * Semantic description of when this label applies. Injected verbatim into
   * the classification prompt next to the label name.
   */
  readonly description: string;
}

/**
 * Chunk-classification enrichment knob: how to multi-label individual chunks.
 *
 * Operates on `ExtractedDocument.chunks` in place — the caller must have
 * already produced chunks (e.g. via `ExtractionConfig.chunking`) for this
 * stage to have any effect; a document with no chunks is a no-op.
 */
export interface ChunkClassificationEnrichmentConfig {
  /** Label-definition set and LLM/batching settings for the chunk-classification stage. */
  readonly config: ChunkClassificationConfig;
}

/**
 * Type of text chunker to use.
 *
 * # Variants
 *
 * * `Text` - Generic text splitter, splits on whitespace and punctuation
 * * `Markdown` - Markdown-aware splitter, preserves formatting and structure
 * * `Yaml` - YAML-aware splitter, creates one chunk per top-level key
 * * `Semantic` - Topic-aware chunker. With an `EmbeddingConfig`, splits at
 *   embedding-based topic shifts tuned by `topic_threshold` (default 0.75,
 *   lower = more splits). Without an embedding, falls back to a
 *   structural-boundary heuristic (ALL-CAPS headers, numbered sections,
 *   blank-line paragraphs) and merges groups into chunks capped at
 *   `max_characters` (default 1000). `topic_threshold` has no effect in the
 *   fallback path. For best results, pair with an embedding model.
 */
export declare enum ChunkerType {
  /** Generic whitespace- and punctuation-aware text splitter (default). */
  Text = "text",
  /** Markdown-aware splitter that preserves heading and code-block boundaries. */
  Markdown = "markdown",
  /** YAML-aware splitter that creates one chunk per top-level key. */
  Yaml = "yaml",
  /** Topic-aware chunker that splits at embedding-based topic shifts. */
  Semantic = "semantic",
}

/** Information about a single chunk. */
export interface ChunkInfo {
  /** Zero-based chunk index. */
  readonly index: number;
  /** Page range for this chunk. */
  readonly pages: PageRange;
  /** Estimated processing time for this chunk in milliseconds. */
  readonly estimatedTimeMs: number;
}

/**
 * Chunking configuration.
 *
 * Configures text chunking for document content, including chunk size,
 * overlap, trimming behavior, and optional embeddings.
 *
 * Use `..Default.default()` when constructing to allow for future field additions:
 */
export interface ChunkingConfig {
  /**
   * Maximum size per chunk (in units determined by `sizing`).
   *
   * When `sizing` is `Characters` (default), this is the max character count.
   * When using token-based sizing, this is the max token count.
   *
   * Default: 1000
   */
  readonly maxCharacters?: number;
  /**
   * Overlap between chunks (in units determined by `sizing`).
   *
   * Default: 200
   */
  readonly overlap?: number;
  /**
   * Whether to trim whitespace from chunk boundaries.
   *
   * Default: true
   */
  readonly trim?: boolean;
  /**
   * Type of chunker to use (Text or Markdown).
   *
   * Default: Text
   */
  readonly chunkerType?: ChunkerType;
  /** Optional embedding configuration for chunk embeddings. */
  readonly embedding?: EmbeddingConfig;
  /**
   * Optional sparse (SPLADE) embedding configuration for chunk embeddings.
   *
   * When set, sparse vectors are generated for each chunk's content and attached
   * via `sparse_embedding`. Requires the `sparse-embeddings`
   * feature; without it, a warning is emitted and no sparse vectors are attached.
   *
   * Config-file only: like `RerankerConfig` and the local-ONNX branch of
   * `embedding`, this has no CLI flag and no environment variable. Only the secret/identity
   * fields of LLM-routed configs (model, API key, base URL) get that reach.
   */
  readonly sparseEmbedding?: SparseEmbeddingConfig;
  /**
   * Optional late-interaction (ColBERT) embedding configuration for chunk embeddings.
   *
   * When set, multi-vector embeddings are generated for each chunk's content and
   * attached via `late_interaction`. Requires the
   * `late-interaction` feature; without it, a warning is emitted and no
   * late-interaction vectors are attached.
   *
   * Config-file only, for the same reason as `sparse_embedding` above.
   */
  readonly lateInteraction?: LateInteractionConfig;
  /** Use a preset configuration (overrides individual settings if provided). */
  readonly preset?: string;
  /**
   * How to measure chunk size.
   *
   * Default: `Characters` (Unicode character count).
   * Enable `chunking-tiktoken` or `chunking-tokenizers` features for token-based sizing.
   */
  readonly sizing?: ChunkSizing;
  /**
   * Optional cosine similarity threshold for semantic topic boundary detection.
   *
   * Only used when `chunker_type` is `Semantic` and an `EmbeddingConfig` is
   * provided. You almost never need to set this. When omitted, defaults to
   * `0.75` which works well for most documents. Lower values detect more
   * topic boundaries (more, smaller chunks); higher values detect fewer.
   * Range: `0.0..=1.0`.
   */
  readonly topicThreshold?: number;
  /**
   * How to handle markdown tables that exceed the chunk size limit.
   *
   * Only applies when `chunker_type` is `Markdown`.
   *
   * * `Split` (default) — tables are split at row boundaries; continuation
   *   chunks do not repeat the header.
   * * `RepeatHeader` — the table header row and separator are prepended to
   *   every continuation chunk so each chunk is self-contained.
   *
   * Default: `Split`
   */
  readonly tableChunking?: TableChunkingMode;
}

/** Reason for chunking a document. */
export type ChunkingReason =
  | { type: "LargeFile"; sizeBytes: number; thresholdBytes: number }
  | { type: "ManyPages"; pageCount: number; threshold: number }
  | { type: "OcrRequired"; pageCount: number; forceOcr: boolean }
  | { type: "LargeAndManyPages"; sizeBytes: number; pageCount: number };

/** Metadata about a chunk's position in the original document. */
export interface ChunkMetadata {
  /** Byte offset where this chunk starts in the original text (UTF-8 valid boundary). */
  readonly byteStart: number;
  /** Byte offset where this chunk ends in the original text (UTF-8 valid boundary). */
  readonly byteEnd: number;
  /**
   * Number of tokens in this chunk (if available).
   *
   * This is calculated by the embedding model's tokenizer if embeddings are enabled.
   */
  readonly tokenCount?: number;
  /** Zero-based index of this chunk in the document. */
  readonly chunkIndex: number;
  /** Total number of chunks in the document. */
  readonly totalChunks: number;
  /**
   * First page number this chunk spans (1-indexed).
   *
   * Only populated when page tracking is enabled in extraction configuration.
   */
  readonly firstPage?: number;
  /**
   * Last page number this chunk spans (1-indexed, equal to first_page for single-page chunks).
   *
   * Only populated when page tracking is enabled in extraction configuration.
   */
  readonly lastPage?: number;
  /**
   * Heading context when using Markdown chunker.
   *
   * Contains the heading hierarchy this chunk falls under.
   * Only populated when `ChunkerType.Markdown` is used.
   */
  readonly headingContext?: HeadingContext;
  /**
   * Flattened heading trail from document root to this chunk's section.
   *
   * Each element is a heading's text, outermost first. Derived from
   * `heading_context` when present; empty otherwise.
   * Provides a binding-friendly, RAG-shaped breadcrumb without requiring
   * callers to walk the nested `HeadingContext` structure.
   */
  readonly headingPath: Array<string>;
  /**
   * Indices into `ExtractedDocument.images` for images on pages covered by this chunk.
   *
   * Contains zero-based indices into the top-level `images` collection for every
   * image whose `page_number` falls within `[first_page, last_page]`.
   * Empty when image extraction is disabled or the chunk spans no pages with images.
   */
  readonly imageIndices: Array<number>;
  /**
   * Ids of the `DocumentNode`s
   * this chunk was derived from.
   *
   * Joins a chunk back to the structured document tree via
   * `DocumentNode.id`.
   * Populated from exact node provenance when available, with a textual
   * containment fallback for rendered chunks that do not retain byte offsets.
   */
  readonly nodeIds: Array<string>;
  /**
   * Per-page bounding-box spans this chunk covers, for viewer highlighting (#1295).
   *
   * One entry per page the chunk overlaps, in page order — the first and last entries'
   * `page` fields equal `first_page`/`last_page`.
   * Populated whenever page-boundary provenance is available (the same condition under
   * which `first_page`/`last_page` are populated); each entry's `bbox` is additionally
   * populated when the document's structured node tree (`ExtractedDocument.document`) is
   * available, as the union of that page's body-layer node bounding boxes found within this
   * chunk. Empty when page-boundary provenance is unavailable (mirrors `first_page`/
   * `last_page` being `None`).
   */
  readonly pageSpans: Array<PageSpan>;
  /**
   * Multi-label classification result for this chunk.
   *
   * Populated by the chunk-classification post-processor when
   * `ExtractionConfig.chunk_classification`
   * is set. A chunk may match zero, one, or many of the configured label
   * definitions. Empty when chunk classification was not configured.
   */
  readonly classifications: Array<ClassificationLabel>;
}

/**
 * How chunk size is measured.
 *
 * Defaults to `Characters` (Unicode character count). When using token-based sizing,
 * chunks are sized by token count according to the specified tokenizer.
 *
 * Token-based sizing uses HuggingFace tokenizers loaded at runtime, or a tokenizer
 * backend you register yourself. Any tokenizer available on HuggingFace Hub can be
 * used, including OpenAI-compatible tokenizers (e.g., `Xenova/gpt-4o`,
 * `Xenova/cl100k_base`). To size chunks with your own tokenizer instead (llama.cpp/GGUF
 * vocabularies, SentencePiece models, custom vocabs), register a `TokenizerBackend`
 * with `register_tokenizer_backend` and set `model` to the registered name.
 */
export type ChunkSizing = { type: "characters" } | { type: "tokenizer"; model: string; cacheDir: string };

/**
 * Semantic structural classification of a text chunk.
 *
 * Assigned by the heuristic classifier in `chunking.classifier`.
 * Defaults to `Unknown` when no rule matches.
 * Designed to be extended in future versions without breaking changes.
 */
export declare enum ChunkType {
  /** Section heading or document title. */
  Heading = "heading",
  /** Party list: names, addresses, and signatories. */
  PartyList = "party_list",
  /** Definition clause ("X means…", "X shall mean…"). */
  Definitions = "definitions",
  /** Operative clause containing legal/contractual action verbs. */
  OperativeClause = "operative_clause",
  /** Signature block with signatures, names, and dates. */
  SignatureBlock = "signature_block",
  /** Schedule, annex, appendix, or exhibit section. */
  Schedule = "schedule",
  /** Table-like content with aligned columns or repeated patterns. */
  TableLike = "table_like",
  /** Mathematical formula or equation. */
  Formula = "formula",
  /** Code block or preformatted content. */
  CodeBlock = "code_block",
  /** Function or method definition (tree-sitter structured code chunking). */
  Function = "function",
  /** Class, struct, interface, or trait definition (tree-sitter structured code chunking). */
  Class = "class",
  /** Module, namespace, or top-level file scope (tree-sitter structured code chunking). */
  Module = "module",
  /** Embedded or referenced image content. */
  Image = "image",
  /** Organizational chart or hierarchy diagram. */
  OrgChart = "org_chart",
  /** Diagram, figure, or visual illustration. */
  Diagram = "diagram",
  /** Unclassified or mixed content. */
  Unknown = "unknown",
}

/**
 * A structured citation from a citation block.
 *
 * Parsed from entries like:
 * `[^srcN]: source, locator, excerpt: "text"`
 */
export interface Citation {
  /** The label of the citation (e.g., "src1" in `[^src1]: ...`). */
  readonly label: string;
  /** The source reference (path, URL, or identifier). */
  readonly source: string;
  /** Optional locator within the source (e.g., "page 3" or "section 2.1"). */
  readonly locator?: string;
  /** Optional excerpt — quoted text from the source. */
  readonly excerpt?: string;
}

/** Citation file metadata (RIS, PubMed, EndNote). */
export interface CitationMetadata {
  /** Total number of citation records in the file. */
  readonly citationCount?: number;
  /** Detected citation file format (e.g. `"ris"`, `"pubmed"`, `"endnote"`). */
  readonly format?: string;
  /** Author names collected across all citation records. */
  readonly authors?: Array<string>;
  /** Earliest and latest publication years found in the file. */
  readonly yearRange?: YearRange;
  /** DOI identifiers found in the citation records. */
  readonly dois?: Array<string>;
  /** Keywords collected from all citation records. */
  readonly keywords?: Array<string>;
}

/** A single label + confidence pair. */
export interface ClassificationLabel {
  /** Label name as configured in `PageClassificationConfig.labels`. */
  readonly label: string;
  /**
   * Backend-reported confidence in `[0.0, 1.0]`. `None` when the backend (e.g. an LLM
   * prompt without explicit confidence schema) did not report one.
   */
  readonly confidence?: number;
}

/**
 * Code block fence style in Markdown output.
 *
 * Determines how code blocks (`<pre><code>`) are rendered in Markdown.
 */
export declare enum CodeBlockStyle {
  /** Indented code blocks (4 spaces). `CommonMark` standard. */
  Indented = "Indented",
  /** Fenced code blocks with triple backticks. Default (GFM). Supports language hints. */
  Backticks = "Backticks",
  /** Fenced code blocks with tildes (~~~). Supports language hints. */
  Tildes = "Tildes",
}

/**
 * A single structurally-meaningful code chunk produced by tree-sitter parsing.
 *
 * Purpose-built payload owned by xberg — deliberately does not expose the upstream
 * `tree_sitter_language_pack` types, so binding generators never need to resolve an
 * external crate's types across FFI/language boundaries.
 */
export interface CodeChunkInfo {
  /** The raw source text of this chunk. */
  readonly text: string;
  /** Hierarchical path of enclosing structural items (e.g. `["MyClass", "my_method"]`). */
  readonly contextPath: Array<string>;
  /**
   * Tree-sitter node kinds that appear at the top level of this chunk (e.g.
   * `"function_definition"`, `"class_definition"`).
   */
  readonly nodeTypes: Array<string>;
  /** Inclusive start byte offset of this chunk in the original source. */
  readonly byteStart: number;
  /** Exclusive end byte offset of this chunk in the original source. */
  readonly byteEnd: number;
}

/**
 * Content rendering mode for code extraction.
 *
 * Controls how extracted code content is represented in the `content` field
 * of `ExtractedDocument`.
 */
export declare enum CodeContentMode {
  /** Use TSLP semantic chunks as content (default). */
  Chunks = "chunks",
  /** Use raw source code as content. */
  Raw = "raw",
  /** Emit function/class headings + docstrings (no code bodies). */
  Structure = "structure",
}

/**
 * An XML-style attribute attached to an `Element` node.
 *
 * Populated only for `CodeDataNodeKind.Element`; always empty for `KeyValue` and
 * `Sequence` nodes.
 */
export interface CodeDataAttribute {
  /** Attribute name (e.g. `"class"`, `"href"`). */
  readonly name: string;
  /** Attribute value as a raw string (quotes stripped). */
  readonly value: string;
  /** Inclusive start byte offset of the `name="value"` attribute token. */
  readonly byteStart: number;
  /** Exclusive end byte offset of the `name="value"` attribute token. */
  readonly byteEnd: number;
}

/**
 * A node in the hierarchical data tree produced by data-format extraction.
 *
 * Purpose-built payload owned by xberg — mirrors
 * `tree_sitter_language_pack.DataNode` but flattens its `Span` down to plain byte
 * offsets, so binding generators never need to resolve an external crate's types
 * across FFI/language boundaries.
 */
export interface CodeDataNode {
  /** Whether this node is a key/value pair, XML element, or sequence item. */
  readonly kind: CodeDataNodeKind;
  /**
   * Key, attribute name, tag name, or positional index (`"0"`, `"1"`, …).
   * `None` at the document root.
   */
  readonly key?: string;
  /**
   * Leaf scalar value, if any. `None` for containers (objects, arrays, XML
   * elements with child elements).
   */
  readonly value?: string;
  /**
   * Attributes on element-shape nodes (XML `STag` attributes). Empty for all
   * other kinds.
   */
  readonly attributes: Array<CodeDataAttribute>;
  /** Children for nested containers and XML element bodies. */
  readonly children: Array<CodeDataNode>;
  /** Inclusive start byte offset of this node in the original source. */
  readonly byteStart: number;
  /** Exclusive end byte offset of this node in the original source. */
  readonly byteEnd: number;
}

/**
 * Discriminates the shape of a `CodeDataNode`.
 *
 * Purpose-built mirror of `tree_sitter_language_pack.DataNodeKind` — kept as an
 * xberg-owned type so binding generators never need to resolve the upstream crate's
 * types across FFI/language boundaries.
 */
export declare enum CodeDataNodeKind {
  /**
   * A key/value pair or mapping (JSON/TOML/properties/YAML/HCL/CUE/KDL pair, or a
   * wrapper "object"/"mapping" container).
   */
  KeyValue = "key_value",
  /** An XML element with a tag name in `key` and attributes in `attributes`. */
  Element = "element",
  /**
   * A positional sequence item (JSON array element, YAML block sequence item,
   * CSV/PSV row or cell).
   */
  Sequence = "sequence",
}

/**
 * Code-format metadata: the structural chunks produced by tree-sitter parsing.
 *
 * Wrapped by `FormatMetadata.Code`. Kept as a named struct (rather than an inline
 * enum-variant body) so serde can tag it under internal tagging and utoipa can emit a
 * referenceable `CodeMetadata` component in the OpenAPI schema.
 */
export interface CodeMetadata {
  /** Structural code chunks (function/class/module boundaries). */
  readonly chunks?: Array<CodeChunkInfo>;
  /**
   * Hierarchical key/value data tree extracted from data-format source
   * (JSON, YAML, TOML, XML, CSV, etc.), when data extraction was enabled.
   */
  readonly data?: CodeDataNode;
}

/**
 * Controls thread usage for constrained environments.
 *
 * Set `max_threads` to cap all internal thread pools (Rayon, ONNX Runtime
 * intra-op) and batch concurrency to a single limit.
 *
 * # Default budget when `max_threads` is unset
 *
 * Without an explicit `max_threads`, the effective budget is
 * `min(detected_cpu_cores, 8)` — a deliberate ceiling chosen for
 * serverless/shared-tenant defaults, not a full-host auto-scale. On a host
 * with more than 8 cores this means the extra cores go **unused** unless one
 * of the following applies:
 *
 * - `max_threads` is set explicitly above 8 (the only way to exceed the
 *   ceiling on a bare-metal or VM host with no CPU quota).
 * - The process runs under a Linux cgroup CPU quota (containers, Kubernetes
 *   `resources.limits.cpu`); in that case the quota itself is used as the
 *   ceiling instead of the hardcoded 8, since the quota already reflects a
 *   deliberately-configured resource limit.
 *
 * When neither applies and the host has more than 8 cores, a single
 * `WARN`-level log is emitted the first time the budget is resolved,
 * naming the detected core count and the applied cap, so the ceiling is
 * discoverable without reading source.
 */
export interface ConcurrencyConfig {
  /**
   * Maximum number of threads for all internal thread pools.
   *
   * Caps Rayon global pool size, ONNX Runtime intra-op threads, and the
   * combined document/inner-task budget for batch extraction. When `None`,
   * the effective budget is `min(detected_cpu_cores, 8)` unless a Linux
   * cgroup CPU quota is present, in which case the quota is used as the
   * ceiling instead. On hosts with more than 8 cores and no cgroup quota,
   * set `max_threads` explicitly to use the additional cores — the
   * default will not scale past 8 on its own.
   */
  readonly maxThreads?: number;
}

/**
 * How a backend's reported page-level confidence must be interpreted.
 *
 * Backend confidence scores are not interchangeable. Tesseract's mean word confidence is a
 * classifier score validated to track legibility on a 0-100 scale. Sceptre (EasyOCR-based)
 * reports a length-penalised `custom_mean` that is rescaled into the same 0-100 range but is
 * *not* comparable — its ordering can be inverted relative to legibility (a dense prose page
 * can score lower than a nearly-blank one). A page-rejection gate calibrated on Tesseract's
 * scale was once applied unconditionally to sceptre's output and rejected every page of a
 * 16-page document, emptying it. This descriptor exists so gating code can ask a backend what
 * its number means instead of assuming.
 */
export type ConfidenceSemantics =
  | { type: "Legibility"; scaleMax: number }
  | { type: "Uncalibrated" }
  | { type: "None" };

/**
 * Content extraction and conversion configuration.
 *
 * Controls how HTML is converted to the output format. Uses
 * html-to-markdown-rs as the conversion engine for all formats
 * (markdown, plain text, djot).
 */
export interface ContentConfig {
  /** Output format: `"markdown"` (default), `"plain"`, `"djot"`. */
  readonly outputFormat?: string;
  /**
   * Preprocessing aggressiveness: `"minimal"`, `"standard"` (default), `"aggressive"`.
   *
   * - Minimal: only scripts/styles removed.
   * - Standard: also removes nav, nav-hinted headers/footers/asides, forms.
   * - Aggressive: removes all footers/asides unconditionally.
   */
  readonly preprocessingPreset?: string;
  /** Remove navigation elements (nav, breadcrumbs, menus). Default: `true`. */
  readonly removeNavigation?: boolean;
  /** Remove form elements. Default: `true`. */
  readonly removeForms?: boolean;
  /**
   * HTML tag names to strip (render children only, remove the tag wrapper).
   * Default: `[]`.
   */
  readonly stripTags?: Array<string>;
  /** HTML tag names to preserve as raw HTML in output. */
  readonly preserveTags?: Array<string>;
  /**
   * CSS selectors for elements to exclude entirely (element + all content).
   *
   * Unlike `strip_tags` (which removes the wrapper but keeps children),
   * excluded elements and all descendants are dropped. Supports CSS selectors:
   * `.class`, `#id`, `[attribute]`, compound selectors.
   *
   * Default: `["noscript"]`. `<noscript>` fallback content (no-JS notices,
   * tracking pixels, GTM iframes) is meant for browsers with JavaScript
   * disabled, not for a markdown reader, and `strip_tags` cannot drop it —
   * on `preprocessing_preset: "standard"` (crawlberg's only path) it only
   * removes the wrapper and still renders the children.
   *
   * Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]`
   */
  readonly excludeSelectors?: Array<string>;
  /** Skip image elements in output. Default: `false`. */
  readonly skipImages?: boolean;
  /** Max DOM traversal depth. Prevents stack overflow on deeply nested HTML. */
  readonly maxDepth?: number;
  /** Enable line wrapping. Default: `false`. */
  readonly wrap?: boolean;
  /** Wrap width when `wrap` is enabled. Default: `80`. */
  readonly wrapWidth?: number;
  /** Include document structure tree in output. Default: `true`. */
  readonly includeDocumentStructure?: boolean;
}

/**
 * Cross-extractor content filtering configuration.
 *
 * Controls whether "furniture" content (headers, footers, page numbers,
 * watermarks, repeating text) is included in or stripped from extraction
 * results. Applies across all extractors (PDF, DOCX, RTF, ODT, HTML, etc.)
 * with format-specific implementation.
 *
 * When `None` on `ExtractionConfig`, each extractor uses its current
 * default behavior unchanged.
 */
export interface ContentFilterConfig {
  /**
   * Include running headers in extraction output.
   *
   * - PDF: Disables top-margin furniture stripping and prevents the layout
   *   model from treating `PageHeader`-classified regions as furniture.
   * - DOCX: Includes document headers in text output.
   * - RTF/ODT: Headers already included; this is a no-op when true.
   * - HTML/EPUB: Keeps `<header>` element content.
   *
   * Default: `false` (headers are stripped or excluded).
   */
  readonly includeHeaders?: boolean;
  /**
   * Include running footers in extraction output.
   *
   * - PDF: Disables bottom-margin furniture stripping and prevents the layout
   *   model from treating `PageFooter`-classified regions as furniture.
   * - DOCX: Includes document footers in text output.
   * - RTF/ODT: Footers already included; this is a no-op when true.
   * - HTML/EPUB: Keeps `<footer>` element content.
   *
   * Default: `false` (footers are stripped or excluded).
   */
  readonly includeFooters?: boolean;
  /**
   * Include footnote bodies in extraction output.
   *
   * - PDF: Prevents the layout model from treating `Footnote`-classified
   *   regions as furniture, so footnote bodies survive alongside the main
   *   text instead of being silently dropped.
   * - Other formats: No effect currently.
   *
   * Default: `false` (footnotes are stripped), matching the existing
   * `include_headers` / `include_footers` defaults.
   */
  readonly includeFootnotes?: boolean;
  /**
   * Enable the heuristic cross-page repeating text detector.
   *
   * When `true` (default), text that repeats verbatim across a supermajority
   * of pages is classified as furniture and stripped.  Disable this if brand
   * names or repeated headings are being incorrectly removed by the heuristic.
   *
   * This flag also gates a same-page rule: a body paragraph is removed when
   * its text is also carried by a table detected on the same page (catches
   * table content that PDF extraction renders both as a table and as body
   * text). The comparison preserves case and never touches headings, list
   * items, code blocks, formulas, or captions, so it cannot delete a body
   * sentence merely for repeating an earlier heading's words (GH#1623).
   *
   * Note: when a layout-detection model is active, the model may independently
   * classify page-header / page-footer / footnote regions as furniture on a
   * per-page basis. To preserve those regions, set `include_headers = true`,
   * `include_footers = true`, `include_footnotes = true`, or any combination,
   * in addition to disabling this flag.
   *
   * Primarily affects PDF extraction.
   *
   * Default: `true`.
   */
  readonly stripRepeatingText?: boolean;
  /**
   * Include watermark text in extraction output.
   *
   * - PDF: Keeps watermark artifacts and arXiv identifiers.
   * - Other formats: No effect currently.
   *
   * Default: `false` (watermarks are stripped).
   */
  readonly includeWatermarks?: boolean;
}

/** Content filter applied to each crawled page before it reaches the result. */
export declare enum ContentFilterKind {
  /** Keep only pages scoring at or above `bm25_threshold` for `bm25_query`. */
  Bm25 = "bm_25",
}

/**
 * Content layer classification for document nodes.
 *
 * Replaces separate body/furniture arrays with per-node granularity.
 */
export declare enum ContentLayer {
  /** Main document body content. */
  Body = "body",
  /** Page/section header (running header). */
  Header = "header",
  /** Page/section footer (running footer). */
  Footer = "footer",
  /** Footnote content. */
  Footnote = "footnote",
}

/** JATS contributor with role. */
export interface ContributorRole {
  /** Contributor display name. */
  readonly name: string;
  /** Contributor role (e.g. `"author"`, `"editor"`). */
  readonly role?: string;
}

/**
 * Main conversion options for HTML to Markdown conversion.
 *
 * Use `ConversionOptions.builder()` to construct, or `Default.default()` for defaults.
 */
export interface ConversionOptions {
  /** Heading style to use in Markdown output (ATX `#` or Setext underline). */
  readonly headingStyle?: HeadingStyle;
  /** How to indent nested list items (spaces or tab). */
  readonly listIndentType?: ListIndentType;
  /** Number of spaces (or tabs) to use for each level of list indentation. */
  readonly listIndentWidth?: number;
  /** Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). */
  readonly bullets?: string;
  /** Character used for bold/italic emphasis markers (`*` or `_`). */
  readonly strongEmSymbol?: string;
  /** Escape `*` characters in plain text to avoid unintended bold/italic. */
  readonly escapeAsterisks?: boolean;
  /** Escape `_` characters in plain text to avoid unintended bold/italic. */
  readonly escapeUnderscores?: boolean;
  /** Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. */
  readonly escapeMisc?: boolean;
  /** Escape ASCII characters that have special meaning in certain Markdown dialects. */
  readonly escapeAscii?: boolean;
  /** Default language annotation for fenced code blocks that have no language hint. */
  readonly codeLanguage?: string;
  /** Automatically convert bare URLs into Markdown autolinks. */
  readonly autolinks?: boolean;
  /** Emit a default title when no `<title>` tag is present. */
  readonly defaultTitle?: boolean;
  /** Render `<br>` elements inside table cells as literal line breaks. */
  readonly brInTables?: boolean;
  /**
   * Emit tables without column padding (compact GFM format).
   *
   * When `true`, column widths are not computed and cells are emitted with
   * no trailing spaces. Separator rows use exactly `---` per column.
   * Produces token-efficient output suitable for RAG / LLM contexts.
   *
   * Default `false` (aligned padding preserved).
   */
  readonly compactTables?: boolean;
  /** Style used for `<mark>` / highlighted text (e.g. `==text==`). */
  readonly highlightStyle?: HighlightStyle;
  /**
   * Populate `result.metadata` with `<head>` / `<meta>` extraction
   * (title, description, Open Graph, Twitter Card, JSON-LD, …).
   *
   * Default `true`. Disabling skips the metadata pass only — table
   * extraction into `result.tables` runs unconditionally.
   */
  readonly extractMetadata?: boolean;
  /**
   * Controls how whitespace sequences are normalised in the converted output.
   *
   * - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters
   *   (spaces, tabs, newlines) to a single space, matching browser rendering behaviour.
   * - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the
   *   source HTML, including runs of spaces and embedded newlines.
   *
   * Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted
   * content outside `<pre>` tags). For most documents `Normalized` produces cleaner output.
   */
  readonly whitespaceMode?: WhitespaceMode;
  /** Strip all newlines from the output, producing a single-line result. */
  readonly stripNewlines?: boolean;
  /** Wrap long lines at `wrap_width` characters. */
  readonly wrap?: boolean;
  /**
   * Maximum output line width in characters when `wrap` is `true` (default `80`).
   *
   * Lines are broken at word boundaries so that no line exceeds this length. A value of `0`
   * is treated as "no limit" — equivalent to leaving `wrap` disabled. Has no
   * effect when `wrap` is `false`.
   */
  readonly wrapWidth?: number;
  /** Treat the entire document as inline content (no block-level wrappers). */
  readonly convertAsInline?: boolean;
  /** Markdown notation for subscript text (e.g. `"~"`). */
  readonly subSymbol?: string;
  /** Markdown notation for superscript text (e.g. `"^"`). */
  readonly supSymbol?: string;
  /** How to encode hard line breaks (`<br>`) in Markdown. */
  readonly newlineStyle?: NewlineStyle;
  /** Style used for fenced code blocks (backticks or tilde). */
  readonly codeBlockStyle?: CodeBlockStyle;
  /** HTML tag names whose `<img>` children are kept inline instead of block. */
  readonly keepInlineImagesIn?: Array<string>;
  /**
   * Options for the HTML pre-processing pass applied before conversion begins.
   *
   * Pre-processing runs before the HTML is handed to the converter and can perform operations
   * such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising
   * vendor-specific markup. See `PreprocessingOptions` for the full set of knobs.
   *
   * Defaults to `PreprocessingOptions.default()`, which enables the standard cleaning
   * passes. Set individual fields on `PreprocessingOptions` (or construct via
   * `ConversionOptions.builder`) to opt in or out of specific passes.
   */
  readonly preprocessing?: PreprocessingOptions;
  /** Expected character encoding of the input HTML (default `"utf-8"`). */
  readonly encoding?: string;
  /** Emit debug information during conversion. */
  readonly debug?: boolean;
  /** HTML tag names whose content is stripped from the output entirely. */
  readonly stripTags?: Array<string>;
  /** HTML tag names that are preserved verbatim in the output. */
  readonly preserveTags?: Array<string>;
  /** Skip conversion of `<img>` elements (omit images from output). */
  readonly skipImages?: boolean;
  /**
   * URL encoding strategy for link and image destinations.
   *
   * Controls how special characters in URL destinations are escaped:
   * - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it
   *   contains spaces or newlines. parsers misinterpret `>` inside such a destination.
   * - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986
   *   unreserved character or `/`, producing a destination that all Markdown parsers handle
   *   correctly even when the URL contains `<`, `>`, spaces, or parentheses.
   */
  readonly urlEscapeStyle?: UrlEscapeStyle;
  /** Link rendering style (inline or reference). */
  readonly linkStyle?: LinkStyle;
  /** Target output format (Markdown, plain text, etc.). */
  readonly outputFormat?: HtmlToMarkdownRsOutputFormat;
  /** Include structured document tree in result. */
  readonly includeDocumentStructure?: boolean;
  /** Extract inline images from data URIs and SVGs. */
  readonly extractImages?: boolean;
  /** Maximum decoded image size in bytes (default 5MB). */
  readonly maxImageSize?: number;
  /** Capture SVG elements as images. */
  readonly captureSvg?: boolean;
  /** Infer image dimensions from data. */
  readonly inferDimensions?: boolean;
  /**
   * Maximum DOM traversal depth.
   *
   * `None` uses the library's internal native-stack safety limit. Explicit
   * values above that safety limit are clamped to prevent process-aborting
   * stack overflows on pathologically deep DOM trees.
   */
  readonly maxDepth?: number;
  /**
   * CSS selectors for elements to exclude entirely (element + all content).
   *
   * Unlike `strip_tags` (which removes the tag wrapper but keeps children),
   * excluded elements and all their descendants are dropped from the output.
   * Supports any CSS selector that `tl` supports: tag names, `.class`,
   * `#id`, `[attribute]`, etc.
   *
   * Invalid selectors are silently skipped at conversion time.
   *
   * Example: `vec![".cookie-banner".into(), "#ad-container".into(), "[role='complementary']".into()]`
   */
  readonly excludeSelectors?: Array<string>;
  /**
   * Which conversion tier to use.
   *
   * - `TierStrategy.Auto` (default) — automatically choose the best path.
   * - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path.
   */
  readonly tierStrategy?: TierStrategy;
}

/**
 * Dublin Core metadata from docProps/core.xml
 *
 * Contains standard metadata fields defined by the Dublin Core standard
 * and Office-specific extensions.
 */
export interface CoreProperties {
  /** Document title */
  readonly title?: string;
  /** Document subject/topic */
  readonly subject?: string;
  /** Document creator/author */
  readonly creator?: string;
  /** Keywords or tags */
  readonly keywords?: string;
  /** Document description/abstract */
  readonly description?: string;
  /** User who last modified the document */
  readonly lastModifiedBy?: string;
  /** Revision number */
  readonly revision?: string;
  /** Creation timestamp (ISO 8601) */
  readonly created?: string;
  /** Last modification timestamp (ISO 8601) */
  readonly modified?: string;
  /** Document category */
  readonly category?: string;
  /** Content status (Draft, Final, etc.) */
  readonly contentStatus?: string;
  /** Document language */
  readonly language?: string;
  /** Unique identifier */
  readonly identifier?: string;
  /** Document version */
  readonly version?: string;
  /** Last print timestamp (ISO 8601) */
  readonly lastPrinted?: string;
}

/** Configuration for crawl, scrape, and map operations. */
export interface CrawlConfig {
  /** Maximum crawl depth (number of link hops from the start URL). */
  readonly maxDepth?: number;
  /** Maximum number of pages to crawl. */
  readonly maxPages?: number;
  /**
   * Maximum links enqueued from a single page. Defaults to 10000.
   *
   * Bounds the work one hostile or pathological page can create; links past the
   * cap are dropped and a warning is logged.
   */
  readonly maxLinksPerPage?: number;
  /** Maximum number of concurrent requests. */
  readonly maxConcurrent?: number;
  /**
   * Traversal order. Defaults to breadth-first.
   *
   * A frontier or strategy set explicitly on `CrawlEngineBuilder` takes precedence over
   * this field.
   */
  readonly crawlStrategy?: CrawlStrategyKind;
  /**
   * Content filter applied to each page. `None` keeps every page.
   *
   * A content filter set explicitly on `CrawlEngineBuilder` takes precedence.
   */
  readonly contentFilter?: ContentFilterKind;
  /** Query the BM25 content filter scores pages against. Required by `ContentFilterKind.Bm25`. */
  readonly bm25Query?: string;
  /** Minimum BM25 score a page must reach to be kept. Defaults to `0.0`. */
  readonly bm25Threshold?: number;
  /** Whether to respect robots.txt directives. */
  readonly respectRobotsTxt?: boolean;
  /**
   * When true, HTTP-level error responses (404 NotFound, 403 Forbidden, WAF blocks)
   * are surfaced as `ScrapeResult` records with the matching `status_code` rather
   * than raised as `CrawlError`. Default `false` preserves the historical
   * throw-on-error contract for direct fetches. Independently of this flag,
   * 404s reached at the end of a redirect chain are *always* surfaced softly —
   * the user opted into redirect-following, so receiving a 404 there is part of
   * the normal flow rather than an unexpected error.
   */
  readonly softHttpErrors?: boolean;
  /** Custom user-agent string. */
  readonly userAgent?: string;
  /** Whether to restrict crawling to the same domain. */
  readonly stayOnDomain?: boolean;
  /** Whether to allow subdomains when `stay_on_domain` is true. */
  readonly allowSubdomains?: boolean;
  /** Regex patterns for paths to include during crawling. */
  readonly includePaths?: Array<string>;
  /** Regex patterns for paths to exclude during crawling. */
  readonly excludePaths?: Array<string>;
  /** Custom HTTP headers to send with each request. */
  readonly customHeaders?: Record<string, string>;
  /** Timeout for individual HTTP requests (in milliseconds when serialized). */
  readonly requestTimeout?: number;
  /**
   * Per-domain rate limit in milliseconds. When set, enforces a minimum delay
   * between requests to the same domain. Defaults to 200ms when `None`.
   */
  readonly rateLimitMs?: number;
  /** Maximum number of redirects to follow. */
  readonly maxRedirects?: number;
  /** Number of retry attempts for failed requests. */
  readonly retryCount?: number;
  /** HTTP status codes that should trigger a retry. */
  readonly retryCodes?: Array<number>;
  /** Whether to enable cookie handling. */
  readonly cookiesEnabled?: boolean;
  /** Authentication configuration. */
  readonly auth?: AuthConfig;
  /**
   * Maximum response body size in bytes.
   *
   * `None` does not mean unbounded: an unset cap falls back to a 100 MiB safety
   * ceiling, because HTTP responses are decompressed while being read and a few
   * hundred compressed bytes can otherwise expand to gigabytes in memory. To read
   * bodies larger than that, set this explicitly.
   */
  readonly maxBodySize?: number;
  /** CSS selectors for tags to remove from HTML before processing. */
  readonly removeTags?: Array<string>;
  /** Content extraction and conversion configuration. */
  readonly content?: ContentConfig;
  /** Maximum number of URLs to return from a map operation. */
  readonly mapLimit?: number;
  /** Search filter for map results (case-insensitive substring match on URLs). */
  readonly mapSearch?: string;
  /** Whether to download assets (CSS, JS, images, etc.) from the page. */
  readonly downloadAssets?: boolean;
  /** Filter for asset categories to download. */
  readonly assetTypes?: Array<AssetCategory>;
  /** Maximum size in bytes for individual asset downloads. */
  readonly maxAssetSize?: number;
  /** Browser configuration. */
  readonly browser?: BrowserConfig;
  /** Proxy configuration for HTTP requests. */
  readonly proxy?: ProxyConfig;
  /** List of user-agent strings for rotation. If non-empty, overrides `user_agent`. */
  readonly userAgents?: Array<string>;
  /**
   * Whether to capture a screenshot when using the browser.
   *
   * Only supported by `scrape()` with `BrowserBackend.Chromiumoxide` and
   * `BrowserMode.Always` or `Stealth`. A screenshot is 100–500 KB of PNG per page,
   * so `crawl()` does not carry screenshots in `CrawlPageResult`/`CrawlResult` at
   * all — a multi-thousand-page crawl holding one per page in memory is not a safe
   * default. Setting this with any other configuration (a different backend,
   * `BrowserMode.Auto`/`Never`, or during `crawl()`) has no effect and logs a
   * warning rather than silently doing nothing.
   */
  readonly captureScreenshot?: boolean;
  /**
   * Re-enqueue discovered `LinkType.Document` URLs into the crawl frontier so
   * the crawl follows links *from* document pages (PDFs, etc.) as it would
   * from HTML pages. Default: `false` (documents terminate at materialisation).
   */
  readonly followDocumentUrls?: boolean;
  /**
   * Maximum document-depth (from the seed URL through document links only)
   * when `follow_document_urls` is true. `None` means inherit `max_depth`.
   * Independent of `max_depth`: a document URL is enqueued only if BOTH the
   * outer `max_depth` and (if set) `document_url_depth` permit it.
   */
  readonly documentUrlDepth?: number;
  /**
   * Whether to download non-HTML documents (PDF, DOCX, images, code, etc.) instead of skipping them.
   * Defaults to `true` — unlike `download_assets` and `capture_screenshot`, which default to `false`.
   */
  readonly downloadDocuments?: boolean;
  /** Maximum size in bytes for document downloads. Defaults to 50 MB. */
  readonly documentMaxSize?: number;
  /** Allowlist of MIME types to download. If empty, uses built-in defaults. */
  readonly documentMimeTypes?: Array<string>;
  /**
   * Directory to stream downloaded document bytes into instead of holding them in
   * memory on `DownloadedDocument.content`. When set, `content` is left empty and
   * `DownloadedDocument.content_path` is populated with `<dir>/<content_hash>.<ext>`.
   * `None` (default) preserves today's in-memory-only behavior. Has no effect on
   * wasm32, which has no filesystem — use `document_content_encoding` there instead.
   */
  readonly documentOutputDir?: string;
  /**
   * Opt-in encoding that duplicates `DownloadedDocument.content` into a serializable
   * field for language bindings that need the bytes in-memory (`content` itself is
   * `alef(skip)`ed). `None` (default) means no encoding is produced. Independent of
   * `document_output_dir` — set both to get a file on disk and an in-memory copy.
   */
  readonly documentContentEncoding?: DocumentContentEncoding;
  /** Path to write WARC output. If `None`, WARC output is disabled. */
  readonly warcOutput?: string;
  /**
   * Named browser profile for persistent sessions (cookies, localStorage).
   *
   * Chromiumoxide backend only. The native backend runs an in-process JavaScript
   * engine with no Chrome process and therefore no profile directory, so this is
   * ignored there and logs a warning. It is also ignored — with a warning — when a
   * shared browser pool is in use (the pool launches before any per-crawl config
   * exists) or when connecting to an external CDP endpoint whose process crawlberg
   * does not own.
   */
  readonly browserProfile?: string;
  /** Whether to save changes back to the browser profile on exit. */
  readonly saveBrowserProfile?: boolean;
  /**
   * SSRF policy for outbound network requests. Default: deny private networks,
   * allow http/https only, max 5 redirects.
   *
   * All policy fields are exposed to language bindings.
   *
   * **wasm32 (including Node.js): `deny_private` does not stop hostname-based
   * requests.** There is no DNS resolution on this target, so only a literal IP host is
   * checked against the policy — a domain name is always permitted, regardless of
   * `deny_private`. Under Node, where `fetch` enforces no CORS, this means a service
   * embedding the wasm binding can be driven to internal hosts by domain name even with
   * `deny_private = true`. Enforce egress restrictions at the network layer for that
   * deployment target; do not rely on this field. See `crawlberg.net.validate_url`.
   */
  readonly ssrf?: SsrfPolicy;
  /**
   * Pins `SsrfPolicy.deny_private` to a caller-chosen value, bypassing the
   * `CRAWLBERG_ALLOW_PRIVATE_NETWORK` operator override entirely for this config.
   *
   * `ssrf.deny_private` is a plain, always-serialized `bool`: several alef-generated
   * bindings construct `SsrfPolicy.default()` (hardcoding `deny_private: true`)
   * whenever their caller never touches SSRF settings at all, so `true` on that field
   * alone cannot distinguish "the caller wants private networks denied" from "the
   * binding's own structural default landed on `true`". The environment variable
   * exists precisely to resolve that ambiguity in the common case by treating any
   * `true` as inconclusive and deferring to the operator.
   *
   * Set this field when that default-deferral is wrong for your call — e.g. a test
   * that must prove `deny_private: true` still denies even while the operator has set
   * `CRAWLBERG_ALLOW_PRIVATE_NETWORK` suite-wide for every other call. `None` (default)
   * preserves today's behavior: the environment variable may still flip
   * `ssrf.deny_private` to `false`. `Some(value)` pins `ssrf.deny_private` to `value`
   * and the environment variable is not consulted for this config.
   */
  readonly ssrfDenyPrivateExplicit?: boolean;
}

/**
 * Traversal order for a crawl.
 *
 * Selects both the queue discipline and the selection strategy, because global order is a
 * property of the frontier: the engine hands its bounded selection window to the strategy, so
 * a strategy alone can only reorder URLs that have already been dequeued.
 */
export declare enum CrawlStrategyKind {
  /** Breadth-first: a FIFO frontier visits every URL at one depth before the next. */
  Bfs = "bfs",
  /** Depth-first: a LIFO frontier descends into a page's children before its siblings. */
  Dfs = "dfs",
  /** Highest-priority-first within the selection window, scored by `CrawlStrategy.score_url`. */
  BestFirst = "best_first",
  /** Like `BestFirst`, but stops once newly crawled pages stop contributing new terms. */
  Adaptive = "adaptive",
}

/**
 * Managed credential-provider configuration for OAuth2/STS-based authentication modes liter-llm
 * cannot express via a static `api_key`. See `LlmConfig.credential_provider`.
 *
 * `Debug` is implemented by hand: `CredentialProviderConfig.AzureAd`'s `client_secret` is a
 * credential and must never be printed, matching `LlmConfig`'s own redaction policy. The
 * other variants carry no secret material — `CredentialProviderConfig.VertexOauth2` and
 * `CredentialProviderConfig.BedrockWebIdentity` reference a *file path*, never the key or
 * token itself.
 */
export type CredentialProviderConfig =
  | { type: "azure_ad"; tenantId: string; clientId: string; clientSecret: string; scope: string }
  | { type: "vertex_oauth2"; serviceAccountKeyFile: string; scope: string }
  | { type: "vertex_adc"; scope: string }
  | { type: "bedrock_web_identity"; roleArn: string; tokenFile: string; sessionName: string; region: string };

/**
 * Configuration for CSV/TSV extraction.
 *
 * When unset (`ExtractionConfig.csv == None`), the extractor keeps its
 * existing default behavior: the delimiter is auto-detected by sampling the
 * file (comma, tab, pipe, or semicolon), and no line is treated as a comment.
 */
export interface CsvConfig {
  /**
   * Field delimiter, as a single-character string (e.g. `","`, `";"`,
   * `"\t"`, `"|"`). When `None` (default), the delimiter is auto-detected
   * from a sample of the file.
   *
   * Must be exactly one ASCII byte when set — `ExtractionConfig.validate`
   * rejects an empty string or a multi-byte value with a helpful error.
   * The TSV MIME type (`text/tab-separated-values`) always forces `\t`
   * regardless of this setting.
   */
  readonly delimiter?: string;
  /**
   * Line prefixes that mark a comment line to skip entirely during row
   * parsing (e.g. `["#"]`). A line is treated as a comment when its
   * trimmed start matches any of these prefixes exactly.
   *
   * Default: empty, meaning no line is treated as a comment (matches the
   * pre-existing extractor behavior).
   */
  readonly commentPrefixes?: Array<string>;
}

/** CSV/TSV file metadata. */
export interface CsvMetadata {
  /** Total number of data rows (excluding the header row if present). */
  readonly rowCount?: number;
  /** Number of columns detected. */
  readonly columnCount?: number;
  /** Field delimiter character (e.g. `","` or `"\t"`). */
  readonly delimiter?: string;
  /** Whether the first row was treated as a header. */
  readonly hasHeader?: boolean;
  /** Inferred data type for each column (e.g. `"string"`, `"integer"`, `"float"`). */
  readonly columnTypes?: Array<string>;
}

/** dBASE field information. */
export interface DbfFieldInfo {
  /** Field (column) name. */
  readonly name: string;
  /** dBASE field type character (e.g. `"C"` for character, `"N"` for numeric). */
  readonly fieldType: string;
}

/** dBASE (DBF) file metadata. */
export interface DbfMetadata {
  /** Total number of data records in the DBF file. */
  readonly recordCount?: number;
  /** Number of field (column) definitions. */
  readonly fieldCount?: number;
  /** Descriptor for each field in the table schema. */
  readonly fields?: Array<DbfFieldInfo>;
}

/** Runtime options accepted by the `candle-deepseek-ocr` backend. */
export interface DeepseekOcrBackendOptions {
  /** Local DeepSeek-OCR model directory. The backend requires this option. */
  readonly modelPath?: string;
  /** Optional per-call device override. */
  readonly device?: CandleDevicePreference;
  /** DeepSeek-OCR model generation, either 1 or 2. Defaults to 2. */
  readonly version?: number;
}

/** Page-level detection result containing all detections and page metadata. */
export interface DetectionResult {
  /** Page width in pixels (as seen by the model). */
  readonly pageWidth: number;
  /** Page height in pixels (as seen by the model). */
  readonly pageHeight: number;
  /** All layout detections on this page after postprocessing. */
  readonly detections: Array<LayoutDetection>;
}

/** MIME type detection response. */
export interface DetectResponse {
  /** Detected MIME type */
  readonly mimeType: string;
  /** Original filename (if provided) */
  readonly filename?: string;
}

/** A single contiguous hunk in a unified diff. */
export interface DiffHunk {
  /** Starting line number in the old content (0-indexed). */
  readonly fromLine: number;
  /** Number of lines from the old content in this hunk. */
  readonly fromCount: number;
  /** Starting line number in the new content (0-indexed). */
  readonly toLine: number;
  /** Number of lines from the new content in this hunk. */
  readonly toCount: number;
  /** Lines that make up this hunk. */
  readonly lines: Array<DiffLine>;
}

/**
 * A single line in a unified-diff hunk.
 *
 * Defined here (rather than only in `crate.diff`) so `RevisionDelta` can
 * reference it unconditionally, without requiring the `diff` Cargo feature.
 * `crate.diff` re-exports this type verbatim.
 */
export type DiffLine =
  | { kind: "context"; text: string }
  | { kind: "added"; text: string }
  | { kind: "removed"; text: string };
export declare const DiffLine: {
  Context(text: string): DiffLine;
  Added(text: string): DiffLine;
  Removed(text: string): DiffLine;
};

/** Options controlling how two `ExtractedDocument` values are compared. */
export interface DiffOptions {
  /** Include metadata changes in the diff. Default: `true`. */
  readonly includeMetadata?: boolean;
  /** Include embedded-children changes in the diff. Default: `true`. */
  readonly includeEmbedded?: boolean;
  /**
   * Truncate content to this many characters before diffing.
   *
   * Useful for very large documents where only the first N characters matter.
   * `None` means no truncation.
   */
  readonly maxContentChars?: number;
}

/** Attributes associated with a named Djot element. */
export interface DjotAttributeGroup {
  /** Element identifier used by the Djot attribute map. */
  readonly identifier?: string;
  /** Attributes associated with the element. */
  readonly attributes?: Attributes;
}

/**
 * Comprehensive Djot document structure with semantic preservation.
 *
 * This type captures the full richness of Djot markup, including:
 * - Block-level structures (headings, lists, blockquotes, code blocks, etc.)
 * - Inline formatting (emphasis, strong, highlight, subscript, superscript, etc.)
 * - Attributes (classes, IDs, key-value pairs)
 * - Links, images, footnotes
 * - Math expressions (inline and display)
 * - Tables with full structure
 *
 * Available when the `djot` feature is enabled.
 */
export interface DjotContent {
  /** Plain text representation for backwards compatibility */
  readonly plainText: string;
  /** Structured block-level content */
  readonly blocks: Array<FormattedBlock>;
  /** Metadata from YAML frontmatter */
  readonly metadata: Metadata;
  /** Extracted tables as structured data */
  readonly tables: Array<Table>;
  /** Extracted images with metadata */
  readonly images: Array<DjotImage>;
  /** Extracted links with URLs */
  readonly links: Array<DjotLink>;
  /** Footnote definitions */
  readonly footnotes: Array<Footnote>;
  /** Attributes mapped by element identifier (if present) */
  readonly attributes: Array<DjotAttributeGroup>;
}

/** Image element in Djot. */
export interface DjotImage {
  /** Image source URL or path */
  readonly src: string;
  /** Alternative text */
  readonly alt: string;
  /** Optional title */
  readonly title?: string;
  /** Element attributes */
  readonly attributes?: Attributes;
}

/** Link element in Djot. */
export interface DjotLink {
  /** Link URL */
  readonly url: string;
  /** Link text content */
  readonly text: string;
  /** Optional title */
  readonly title?: string;
  /** Element attributes */
  readonly attributes?: Attributes;
}

/** A single doctor verdict: what was checked, the outcome, and why. */
export interface DoctorCheck {
  /** Check identifier, e.g. `ocr.tesseract` or `layout.rtdetr`. */
  readonly name: string;
  /** Pass / warn / fail / skip verdict. */
  readonly status: ProbeStatus;
  /** One-line reason or detail (e.g. missing language, resolved path, error). */
  readonly message: string;
}

/** Aggregate doctor report over all configured backends and settings. */
export interface DoctorReport {
  /** Individual check verdicts, in execution order. */
  readonly checks?: Array<DoctorCheck>;
}

/** Detected document boundary within a PDF. */
export interface DocumentBoundary {
  /** 1-indexed start page (inclusive). */
  readonly startPage: number;
  /** 1-indexed end page (inclusive). */
  readonly endPage: number;
  /** Confidence in this boundary, `[0.0, 1.0]`. */
  readonly confidence: number;
  /** Reason for the boundary detection. */
  readonly reason: BoundaryReason;
}

/**
 * Opt-in encoding applied to a downloaded document's bytes for callers who need the
 * content available in a serializable field rather than reading it from disk.
 *
 * `None` (the `CrawlConfig.document_content_encoding` default) produces neither — unlike
 * screenshots, base64-encoding a document by default would duplicate an already
 * up-to-`document_max_size` buffer (50 MB default) in memory per document.
 */
export declare enum DocumentContentEncoding {
  /** Populate `DownloadedDocument.content_base64` with a base64-encoded copy. */
  Base64 = "base_64",
}

/**
 * Cheap structural counts for an extracted document.
 *
 * Populated on every `ExtractedDocument` returned by `extract` /
 * `extract_batch`, regardless of whether the heavy `pages` / `images`
 * collections are materialized. A caller that only needs "how many pages /
 * tables / images did this document have?" (reporting, cost estimation,
 * progress, quotas) can read these without enabling per-page or per-image
 * extraction.
 *
 * The page count comes from the parse (the extractor already walks the page
 * tree); it does not require opting into per-page content. `pages` is `0` for
 * inputs that are not page-addressable (e.g. plain text).
 */
export interface DocumentCounts {
  /** Total pages in the source document (`0` when not page-addressable). */
  readonly pages?: number;
  /** Tables detected in the document. */
  readonly tables?: number;
  /** Images detected in the document. */
  readonly images?: number;
}

/**
 * Trait for document extractor plugins.
 *
 * Implement this trait to add support for new document formats or override
 * built-in extraction behavior. Foreign-language bindings expose the
 * `DocumentExtractor.extract` method, which accepts `ExtractInput` and
 * returns an `ExtractedDocument`.
 *
 * # Priority System
 *
 * When multiple extractors support the same MIME type, the registry selects
 * the extractor with the highest priority value. Use this to:
 * - Override built-in extractors (priority > 50)
 * - Provide fallback extractors (priority < 50)
 * - Implement specialized extractors for specific use cases
 *
 * Default priority is 50.
 *
 * # Thread Safety
 *
 * Extractors must be thread-safe (`Send + Sync`) to support concurrent extraction.
 */
export interface DocumentExtractor {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Binding-safe extraction entry point for foreign-language plugin bridges.
   *
   * Accepts the same unified input shape as the public extraction API and
   * returns one extracted document result.
   */
  extract(
    input?: ExtractInput | undefined | null,
    config?: ExtractionConfig | undefined | null,
  ): Promise<ExtractedDocument>;
  /**
   * Get the list of MIME types supported by this extractor.
   *
   * Can include exact MIME types and prefix patterns:
   * - Exact: `"application/pdf"`, `"text/plain"`
   * - Prefix: `"image/*"` (matches any image type)
   * @returns A slice of MIME type strings.
   */
  supportedMimeTypes(): Array<string>;
  /**
   * Get the priority of this extractor.
   *
   * Higher priority extractors are preferred when multiple extractors
   * support the same MIME type.
   *
   * # Priority Guidelines
   *
   * - **0-25**: Fallback/low-quality extractors
   * - **26-49**: Alternative extractors
   * - **50**: Default priority (built-in extractors)
   * - **51-75**: Premium/enhanced extractors
   * - **76-100**: Specialized/high-priority extractors
   * @returns Priority value (default: 50)
   */
  priority?(): number;
  /**
   * Optional: Check if this extractor can handle a specific file.
   *
   * Allows for more sophisticated detection beyond MIME types.
   * Defaults to `true` (rely on MIME type matching).
   * @param path - Path to the file to check
   *
   * @param mime_type - Detected MIME type
   *
   * @returns `true` if the extractor can handle this file, `false` otherwise.
   */
  canHandle?(path: string, mimeType: string): boolean;
}

/** Metadata about a document for analysis. */
export interface DocumentMetadata {
  /** MIME type of the document. */
  readonly mimeType: string;
  /** File size in bytes. */
  readonly sizeBytes: number;
  /** Page count (if known, e.g., from previous analysis). */
  readonly pageCount?: number;
  /** Whether OCR is forced regardless of text layer. */
  readonly forceOcr: boolean;
  /** User-provided chunk configuration overrides. */
  readonly userChunkConfig?: UserChunkConfig;
  /** Whether chunking is enabled for this job. */
  readonly chunkingEnabled: boolean;
}

/**
 * A single node in the document tree.
 *
 * Each node has deterministic `id`, typed `content`, optional `parent`/`children`
 * for tree structure, and metadata like page number, bounding box, and content layer.
 */
export interface DocumentNode {
  /**
   * Deterministic identifier (hash of node type + text + page + position).
   *
   * Stable and unique within a single extraction response: every internal
   * construction path threads the node's position (its index in
   * `DocumentStructure.nodes`) into the hash, so identical
   * `(node_type, text, page)` tuples at different positions never collide.
   * Always serialised — `ChunkMetadata.node_ids` references it to join
   * chunks back to the nodes they were derived from.
   * `#[serde(default)]` covers the missing-field case on inbound JSON
   * (e.g. documents serialised before this field existed).
   */
  readonly id: string;
  /** Node content — tagged enum, type-specific data only. */
  readonly content: NodeContent;
  /** Parent node index (`None` = root-level node). */
  readonly parent?: number;
  /** Child node indices in reading order. */
  readonly children: Array<number>;
  /**
   * Content layer classification.
   *
   * Always serialised — Kotlin-Android (and any other typed binding) treats
   * the field as non-nullable, so omitting it from the JSON wire would
   * break consumer deserialisation.  `#[serde(default)]` covers the
   * missing-field case on inbound JSON.
   */
  readonly contentLayer: ContentLayer;
  /** Page number where this node starts (1-indexed). */
  readonly page?: number;
  /** Page number where this node ends (for multi-page tables/sections). */
  readonly pageEnd?: number;
  /** Bounding box in document coordinates. */
  readonly bbox?: BoundingBox;
  /**
   * Inline annotations (formatting, links) on this node's text content.
   *
   * Only meaningful for text-carrying nodes; empty for containers.
   */
  readonly annotations: Array<TextAnnotation>;
  /**
   * Format-specific key-value attributes.
   *
   * Extensible bag for miscellaneous data without a dedicated typed field: CSS classes,
   * LaTeX environment names, Excel cell formulas, slide layout names, etc.
   */
  readonly attributes?: Record<string, string>;
}

/** A resolved relationship between two nodes in the document tree. */
export interface DocumentRelationship {
  /** Source node index (the referencing node). */
  readonly source: number;
  /** Target node index (the referenced node). */
  readonly target: number;
  /** Semantic kind of the relationship. */
  readonly kind: RelationshipKind;
}

/**
 * A single tracked change embedded in a document.
 *
 * Populated by per-format extractors that understand change-tracking metadata
 * (DOCX `w:ins`/`w:del`/`w:rPrChange`, ODT `text:change-*`, …). Every
 * extractor defaults to `ExtractedDocument.revisions = None` until a
 * format-specific implementation is added.
 */
export interface DocumentRevision {
  /**
   * Format-specific revision identifier.
   *
   * For DOCX this is the `w:id` attribute value on the change element
   * (e.g. `"42"`). When the attribute is absent a synthetic fallback is
   * generated (`"docx-ins-0"`, `"docx-del-3"`, …).
   */
  readonly revisionId: string;
  /** Display name of the author who made this change, when available. */
  readonly author?: string;
  /**
   * ISO-8601 timestamp of the change, when available.
   *
   * Stored as a plain string so this type remains FFI-friendly and
   * unconditionally available without the `chrono` optional dep.
   * DOCX populates this from the `w:date` attribute (e.g.
   * `"2024-03-15T10:30:00Z"`).
   */
  readonly timestamp?: string;
  /** Semantic kind of this revision. */
  readonly kind: RevisionKind;
  /**
   * Best-effort document location for this revision.
   *
   * Resolution is format-dependent and may be `None` when the location
   * cannot be determined (e.g. changes inside table cells before
   * table-cell anchor support is added).
   */
  readonly anchor?: RevisionAnchor;
  /** The content changes that make up this revision. */
  readonly delta: RevisionDelta;
}

/**
 * Top-level structured document representation.
 *
 * A flat array of nodes with index-based parent/child references forming a tree.
 * Root-level nodes have `parent: None`. Use `body_roots()` and `furniture_roots()`
 * to iterate over top-level content by layer.
 *
 * # Validation
 *
 * Call `validate()` after construction to verify all node indices are in bounds
 * and parent-child relationships are bidirectionally consistent.
 */
export interface DocumentStructure {
  /** All nodes in document/reading order. */
  readonly nodes?: Array<DocumentNode>;
  /**
   * Origin format identifier (e.g. "docx", "pptx", "html", "pdf").
   *
   * Allows renderers to apply format-aware heuristics when converting
   * the document tree to output formats.
   */
  readonly sourceFormat?: string;
  /**
   * Resolved relationships between nodes (footnote refs, citations, anchor links, etc.).
   *
   * Populated during derivation from the internal document representation.
   * Empty when no relationships are detected.
   */
  readonly relationships?: Array<DocumentRelationship>;
  /**
   * Sorted, deduplicated list of node type names present in this document.
   *
   * Each value is the snake_case `node_type` tag of the corresponding
   * `NodeContent` variant (e.g. `"paragraph"`, `"heading"`, `"table"`, …).
   *
   * Computed from `nodes` via `DocumentStructure.finalize_node_types`.
   * Empty until that method is called (internal construction paths call it
   * at the end of derivation).
   */
  readonly nodeTypes?: Array<string>;
}

/** Summary of an extracted document. */
export interface DocumentSummary {
  /** Summary text (plain prose). */
  readonly text: string;
  /** Strategy that produced this summary. */
  readonly strategy: SummaryStrategy;
  /** Approximate token count of the summary, when known. */
  readonly tokenCount?: number;
}

/**
 * Application properties from docProps/app.xml for DOCX
 *
 * Contains Word-specific document statistics and metadata.
 */
export interface DocxAppProperties {
  /** Application name (e.g., "Microsoft Office Word") */
  readonly application?: string;
  /** Application version */
  readonly appVersion?: string;
  /** Template filename */
  readonly template?: string;
  /** Total editing time in minutes */
  readonly totalTime?: number;
  /** Number of pages */
  readonly pages?: number;
  /** Number of words */
  readonly words?: number;
  /** Number of characters (excluding spaces) */
  readonly characters?: number;
  /** Number of characters (including spaces) */
  readonly charactersWithSpaces?: number;
  /** Number of lines */
  readonly lines?: number;
  /** Number of paragraphs */
  readonly paragraphs?: number;
  /** Company name */
  readonly company?: string;
  /** Document security level */
  readonly docSecurity?: number;
  /** Scale crop flag */
  readonly scaleCrop?: boolean;
  /** Links up to date flag */
  readonly linksUpToDate?: boolean;
  /** Shared document flag */
  readonly sharedDoc?: boolean;
  /** Hyperlinks changed flag */
  readonly hyperlinksChanged?: boolean;
}

/**
 * Word document metadata.
 *
 * Extracted from DOCX files using shared Office Open XML metadata extraction.
 * Integrates with `office_metadata` module for core/app/custom properties.
 */
export interface DocxMetadata {
  /**
   * Core properties from docProps/core.xml (Dublin Core metadata)
   *
   * Contains title, creator, subject, keywords, dates, etc.
   * Shared format across DOCX/PPTX/XLSX documents.
   */
  readonly coreProperties?: CoreProperties;
  /**
   * Application properties from docProps/app.xml (Word-specific statistics)
   *
   * Contains word count, page count, paragraph count, editing time, etc.
   * DOCX-specific variant of Office application properties.
   */
  readonly appProperties?: DocxAppProperties;
  /**
   * Custom properties from docProps/custom.xml (user-defined properties)
   *
   * Contains key-value pairs defined by users or applications.
   * Values can be strings, numbers, booleans, or dates.
   */
  readonly customProperties?: Record<string, JsonValue>;
}

/**
 * Semantic element extracted from document.
 *
 * Represents a logical unit of content with semantic classification,
 * unique identifier, and metadata for tracking origin and position.
 */
export interface Element {
  /**
   * Deterministic element identifier. Empty only when deserializing legacy payloads
   * that predate this field's wire representation.
   */
  readonly elementId: string;
  /** Semantic type of this element */
  readonly elementType: ElementType;
  /** Text content of the element */
  readonly text: string;
  /** Metadata about the element */
  readonly metadata: ElementMetadata;
}

/** Metadata for a semantic element. */
export interface ElementMetadata {
  /** Page number (1-indexed) */
  readonly pageNumber?: number;
  /** Source filename or document name */
  readonly filename?: string;
  /** Bounding box coordinates if available */
  readonly coordinates?: BoundingBox;
  /** Position index in the element sequence */
  readonly elementIndex?: number;
  /** Additional custom metadata */
  readonly additional: Record<string, string>;
}

/**
 * Semantic element type classification.
 *
 * Categorizes text content into semantic units for downstream processing.
 * Supports the element types commonly found in Unstructured documents.
 */
export declare enum ElementType {
  /** Document title */
  Title = "title",
  /** Main narrative text body */
  NarrativeText = "narrative_text",
  /** Section heading */
  Heading = "heading",
  /** List item (bullet, numbered, etc.) */
  ListItem = "list_item",
  /** Table element */
  Table = "table",
  /** Image element */
  Image = "image",
  /** Page break marker */
  PageBreak = "page_break",
  /** Code block */
  CodeBlock = "code_block",
  /** Mathematical formula (LaTeX source in `text`) */
  Formula = "formula",
  /** Block quote */
  BlockQuote = "block_quote",
  /** Footer text */
  Footer = "footer",
  /** Header text */
  Header = "header",
}

/**
 * Email attachment representation.
 *
 * Contains metadata and optionally the content of an email attachment.
 */
export interface EmailAttachment {
  /** Attachment name (from Content-Disposition header) */
  readonly name?: string;
  /** Filename of the attachment */
  readonly filename?: string;
  /** MIME type of the attachment */
  readonly mimeType?: string;
  /** Size in bytes */
  readonly size?: number;
  /** Whether this attachment is an image */
  readonly isImage: boolean;
  /**
   * Attachment data (if extracted).
   * Uses `bytes.Bytes` for cheap cloning of large buffers.
   */
  readonly data?: Uint8Array;
}

/** Configuration for email extraction. */
export interface EmailConfig {
  /**
   * Windows codepage number to use when an MSG file contains no codepage property.
   * Defaults to `None`, which falls back to windows-1252.
   *
   * If an unrecognized or invalid codepage number is supplied (including 0),
   * the behavior silently falls back to windows-1252 — the same as when the
   * MSG file itself contains an unrecognized codepage. No error or warning is
   * emitted. Users should verify output when supplying unusual values.
   *
   * Common values:
   * - 1250: Central European (Polish, Czech, Hungarian, etc.)
   * - 1251: Cyrillic (Russian, Ukrainian, Bulgarian, etc.)
   * - 1252: Western European (default)
   * - 1253: Greek
   * - 1254: Turkish
   * - 1255: Hebrew
   * - 1256: Arabic
   * - 932:  Japanese (Shift-JIS)
   * - 936:  Simplified Chinese (GBK)
   */
  readonly msgFallbackCodepage?: number;
}

/**
 * Email extraction result.
 *
 * Complete representation of an extracted email message (.eml or .msg)
 * including headers, body content, and attachments.
 */
export interface EmailExtractionResult {
  /** Email subject line */
  readonly subject?: string;
  /** Sender email address */
  readonly fromEmail?: string;
  /** Primary recipient email addresses */
  readonly toEmails: Array<string>;
  /** CC recipient email addresses */
  readonly ccEmails: Array<string>;
  /** BCC recipient email addresses */
  readonly bccEmails: Array<string>;
  /** Email date/timestamp */
  readonly date?: string;
  /** Message-ID header value */
  readonly messageId?: string;
  /** Plain text version of the email body */
  readonly plainText?: string;
  /** HTML version of the email body */
  readonly htmlContent?: string;
  /** Cleaned/processed text content. Aliased as `cleaned_text` for back-compat. */
  readonly content: string;
  /** List of email attachments */
  readonly attachments: Array<EmailAttachment>;
  /** Additional email headers and metadata */
  readonly metadata: Record<string, string>;
}

/**
 * Email metadata extracted from .eml and .msg files.
 *
 * Includes sender/recipient information, message ID, and attachment list.
 */
export interface EmailMetadata {
  /** Sender's email address */
  readonly fromEmail?: string;
  /** Sender's display name */
  readonly fromName?: string;
  /** Primary recipients */
  readonly toEmails?: Array<string>;
  /** CC recipients */
  readonly ccEmails?: Array<string>;
  /** BCC recipients */
  readonly bccEmails?: Array<string>;
  /** Message-ID header value */
  readonly messageId?: string;
  /** List of attachment filenames */
  readonly attachments?: Array<string>;
}

/** Changes to embedded archive children between two results. */
export interface EmbeddedChanges {
  /** Children present in `b` but not in `a` (matched by `path`). */
  readonly added?: Array<ArchiveEntry>;
  /** Children present in `a` but not in `b` (matched by `path`). */
  readonly removed?: Array<ArchiveEntry>;
  /**
   * Children present in both but with differing content (matched by `path`).
   *
   * Each entry holds the diff of the nested `ExtractedDocument`.
   */
  readonly changed?: Array<EmbeddedDiff>;
}

/** Diff for a single embedded archive entry that appears in both results. */
export interface EmbeddedDiff {
  /** Archive-relative path identifying this entry. */
  readonly path: string;
  /** The recursive diff of the entry's extraction result. */
  readonly diff: ExtractionDiff;
}

/** Embedded file descriptor extracted from the PDF name tree. */
export interface EmbeddedFile {
  /** The filename as stored in the PDF name tree. */
  readonly name: string;
  /** Raw file bytes from the embedded stream (already decompressed by lopdf). */
  readonly data: Uint8Array;
  /**
   * Compressed byte count of the original stream (before decompression).
   *
   * Used by callers to compute the decompression ratio and detect zip-bomb-style
   * attacks that embed a tiny compressed stream expanding to gigabytes of data.
   */
  readonly compressedSize: number;
  /** MIME type if specified in the filespec, otherwise `None`. */
  readonly mimeType?: string;
}

/**
 * Trait for in-process embedding backend plugins.
 *
 * Async to match the convention used by other plugin hooks such as
 * `OcrBackend` and `PostProcessor`.
 * Host-language bridges (PyO3, napi-rs, Rustler, extendr, magnus, ext-php-rs,
 * C FFI, etc.) wrap their synchronous host callables in `spawn_blocking` or the
 * equivalent to satisfy the async signature.
 *
 * # Thread safety
 *
 * Backends must be `Send + Sync + 'static`. They are stored in
 * `Arc<dyn EmbeddingBackend>` and called concurrently from xberg's chunking
 * pipeline. If the backend's underlying model isn't thread-safe, the backend
 * itself must serialize access internally (e.g. via `Mutex<Inner>`).
 *
 * # Contract
 *
 * - `embed(texts)` MUST return exactly `texts.len()` vectors, each of length
 *   `self.dimensions()`. The dispatcher in `crate.embeddings.embed_texts`
 *   validates this before returning to downstream consumers; a non-conforming
 *   backend surfaces as a `XbergError.Validation`, not a panic.
 * - `embed` may be called from any thread. Its future must be `Send`
 *   (enforced by `async_trait` when `#[async_trait]` is used on non-WASM targets).
 * - `dimensions()` is called exactly once at registration, immediately after
 *   `initialize()` succeeds. The returned value is cached by the registry and
 *   used for all subsequent shape validation. Lazy-loading implementations can
 *   defer model loading into `initialize()` and report the real dimension
 *   afterwards. Later mutations of the backend's reported dimension are not
 *   observed by xberg — implementations that need to change dimension
 *   must unregister and re-register.
 * - `shutdown()` (inherited from `Plugin`) may be invoked
 *   concurrently with an in-flight `embed()` call. Implementations must
 *   tolerate this — e.g. by letting in-flight calls finish using resources
 *   held via the `Arc<dyn EmbeddingBackend>` reference, and only releasing
 *   shared state that isn't needed by `embed`.
 *
 * # Runtime
 *
 * The synchronous `embed_texts` entry uses
 * `tokio.task.block_in_place` to await the trait's async `embed`, which
 * requires a multi-thread tokio runtime. Callers running inside a
 * `current_thread` runtime (e.g. `#[tokio.test]` without `flavor = "multi_thread"`,
 * or `tokio.runtime.Builder.new_current_thread()`) must use
 * `embed_texts_async` instead, which awaits directly without `block_in_place`.
 */
export interface EmbeddingBackend {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Embedding vector dimension. Must be `> 0` and must match the length of
   * every vector returned by `embed`.
   */
  dimensions(): number;
  /**
   * Embed a batch of texts, returning one vector per input in order.
   * @throws Implementations should return `Plugin` for
   * backend-specific failures. The dispatcher layers its own validation
   * (length, per-vector dimension) on top.
   */
  embed(texts: Array<string>): Promise<Array<Array<number>>>;
}

/**
 * Embedding configuration for text chunks.
 *
 * Configures embedding generation using ONNX models via the vendored embedding engine.
 * Requires the `embeddings` feature to be enabled.
 */
export interface EmbeddingConfig {
  /** The embedding model to use (defaults to "gte-modernbert-base" preset if not specified) */
  readonly model?: EmbeddingModelType;
  /** Whether to normalize embedding vectors (recommended for cosine similarity) */
  readonly normalize?: boolean;
  /** Batch size for embedding generation */
  readonly batchSize?: number;
  /**
   * Show model download progress.
   *
   * When enabled, transfer progress for the model, tokenizer and config files is reported at
   * `info` level on the `xberg.model_download` target while they download (#279). Covers both
   * local backends (ONNX and static/model2vec). A warm Hugging Face cache transfers nothing and
   * so reports nothing. Ignored by `EmbeddingModelType.Llm` and
   * `EmbeddingModelType.Plugin`, which download no model.
   */
  readonly showDownloadProgress?: boolean;
  /**
   * Optional alternate Hugging Face cache root for model files.
   *
   * When unset, hf-hub follows `HF_HUB_CACHE`, `HUGGINGFACE_HUB_CACHE`,
   * `HF_HOME`, XDG, and platform defaults. Prefer those environment variables
   * when configuring the cache process-wide.
   */
  readonly cacheDir?: string;
  /**
   * Hardware acceleration for the embedding ONNX model.
   *
   * When set, controls which execution provider (CPU, CUDA, CoreML, TensorRT)
   * is used for inference. Defaults to `None` (auto-select per platform).
   */
  readonly acceleration?: AccelerationConfig;
  /**
   * Maximum wall-clock duration (in seconds) for a single `embed()` call when
   * using `EmbeddingModelType.Plugin`.
   *
   * Applies only to the in-process plugin path — protects against hung
   * host-language backends (e.g. a Python callback deadlocked on the GIL,
   * a model stuck on CUDA OOM retries, etc.). On timeout, the dispatcher
   * returns `Plugin` instead of blocking forever.
   *
   * `None` disables the timeout. The default (60 seconds) is conservative
   * for common in-process inference; increase for large batches on slow
   * hardware.
   */
  readonly maxEmbedDurationSecs?: number;
  /**
   * Maximum number of tokens fed to the tokenizer before truncation when
   * embedding a chunk with a local ONNX model (Preset/Custom).
   *
   * A chunk longer than this many tokens has its tail dropped before
   * inference, so only the prefix contributes to the stored vector. `None`
   * falls back to 512 (the historical default). The effective value is
   * always capped at the model's own `model_max_length`, so raising it past
   * what the model supports has no effect — set it to match a long-context
   * model (e.g. 8192 for Jina/Nomic) so long chunks embed in full.
   *
   * Ignored by the `Llm` and `Plugin` model types, which own their own
   * tokenization.
   */
  readonly maxSequenceLength?: number;
}

/** Embedding model types supported by Xberg. */
export type EmbeddingModelType =
  | { type: "preset"; name: string }
  | { type: "custom"; modelId: string; dimensions: number }
  | { type: "llm"; llm: LlmConfig }
  | { type: "plugin"; name: string };

/**
 * Inference backend that an `EmbeddingPreset` runs on.
 *
 * `Onnx` presets require the `embeddings` feature (ONNX Runtime, not available on
 * WASM/Android x86_64 emulator). `Static` presets require `static-embeddings`
 * (pure-Rust model2vec inference, no ORT — the only dense-embedding backend
 * available on `no-ort-target`).
 *
 * Defaults to `Onnx` via `#[serde(default)]` so every existing preset payload
 * (which predates this field) keeps deserializing without change.
 */
export declare enum EmbeddingsEmbeddingBackend {
  /** ONNX Runtime transformer inference (the historical, default backend). */
  Onnx = "onnx",
  /** Pure-Rust static (model2vec) inference — no ONNX Runtime. */
  Static = "static",
}

/** A single named entity detected in the extracted text. */
export interface Entity {
  /** Canonical category the entity belongs to (PERSON, ORG, LOCATION, etc.). */
  readonly category: EntityCategory;
  /** Raw mention text exactly as it appeared in the source. */
  readonly text: string;
  /** Byte-offset span in `ExtractedDocument.content` where the mention starts. */
  readonly start: number;
  /** Byte-offset span in `ExtractedDocument.content` where the mention ends (exclusive). */
  readonly end: number;
  /**
   * Backend-reported confidence in `[0.0, 1.0]`. `None` when the backend does not
   * expose confidence scores.
   */
  readonly confidence?: number;
}

/**
 * Standard entity categories produced by built-in NER backends.
 *
 * The `Custom(String)` variant lets caller-supplied categories (e.g. LLM
 * schemas) flow through without losing fidelity to the consumer.
 */
export type EntityCategory =
  | { type: "person" }
  | { type: "organization" }
  | { type: "location" }
  | { type: "date" }
  | { type: "time" }
  | { type: "money" }
  | { type: "percent" }
  | { type: "email" }
  | { type: "phone" }
  | { type: "url" }
  | { type: "custom"; custom: string };

/** EPUB metadata (Dublin Core extensions). */
export interface EpubMetadata {
  /** Dublin Core `coverage` field (geographic or temporal scope). */
  readonly coverage?: string;
  /** Dublin Core `format` field (media type of the resource). */
  readonly dcFormat?: string;
  /** Dublin Core `relation` field (related resource identifier). */
  readonly relation?: string;
  /** Dublin Core `source` field (origin resource identifier). */
  readonly source?: string;
  /** Dublin Core `type` field (nature or genre of the resource). */
  readonly dcType?: string;
  /** Path or identifier of the cover image within the EPUB container. */
  readonly coverImage?: string;
}

/** Error metadata (for batch operations). */
export interface ErrorMetadata {
  /** Machine-readable error type identifier (e.g. "UnsupportedFormat"). */
  readonly errorType: string;
  /** Human-readable error description. */
  readonly message: string;
}

/**
 * Excel/spreadsheet format metadata.
 *
 * Identifies the document as a spreadsheet source via the `FormatMetadata.Excel`
 * discriminant. Sheet count and sheet names are stored inside this struct.
 */
export interface ExcelMetadata {
  /** Number of sheets in the workbook. */
  readonly sheetCount?: number;
  /** Names of all sheets in the workbook. */
  readonly sheetNames?: Array<string>;
}

/**
 * Single Excel worksheet.
 *
 * Represents one sheet from an Excel workbook with its content
 * converted to Markdown format and dimensional statistics.
 */
export interface ExcelSheet {
  /** Sheet name as it appears in Excel */
  readonly name: string;
  /** Sheet content converted to Markdown tables */
  readonly markdown: string;
  /** Number of rows */
  readonly rowCount: number;
  /** Number of columns */
  readonly colCount: number;
  /** Total number of non-empty cells */
  readonly cellCount: number;
  /**
   * Pre-extracted table cells (2D vector of cell values)
   * Populated during markdown generation to avoid re-parsing markdown.
   * undefined for empty sheets.
   */
  readonly tableCells?: Array<Array<string>>;
}

/**
 * Excel workbook representation.
 *
 * Contains all sheets from an Excel file (.xlsx, .xls, etc.) with
 * extracted content and metadata.
 */
export interface ExcelWorkbook {
  /** All sheets in the workbook */
  readonly sheets: Array<ExcelSheet>;
  /** Workbook-level metadata (author, creation date, etc.) */
  readonly metadata: Record<string, string>;
  /**
   * Collaborative-edit revision headers from `xl/revisions/revisionHeaders.xml`.
   *
   * Populated for legacy shared-workbook `.xlsx` files that contain the
   * `xl/revisions/` directory. Each `<header>` element maps to one
   * `DocumentRevision { kind: FormatChange }` carrying the header's `guid`
   * (→ `revision_id`), `userName` (→ `author`), and `dateTime` (→ `timestamp`).
   * `anchor` and `delta` are `None`/empty for v1 (per-cell log parsing is a
   * follow-up). `None` when `xl/revisions/revisionHeaders.xml` is absent.
   */
  readonly revisions?: Array<DocumentRevision>;
}

/**
 * ONNX Runtime execution provider type.
 *
 * Determines which hardware backend is used for model inference.
 * `Auto` (default) selects the best available provider per platform.
 */
export declare enum ExecutionProviderType {
  /** Auto-select: CoreML on macOS, CUDA on Linux, CPU elsewhere. */
  Auto = "auto",
  /** CPU execution provider (always available). */
  Cpu = "cpu",
  /** Apple CoreML (macOS/iOS Neural Engine + GPU). */
  CoreMl = "coreml",
  /** NVIDIA CUDA GPU acceleration. */
  Cuda = "cuda",
  /** NVIDIA TensorRT (optimized CUDA inference). */
  TensorRt = "tensorrt",
}

/**
 * Document extracted by the core extraction pipeline.
 *
 * `extract` and `extract_batch` return an `ExtractionResult` envelope whose
 * `results` field contains these per-document payloads.
 */
export interface ExtractedDocument {
  /** Plain-text representation of the extracted document content. */
  readonly content?: string;
  /** MIME type of the source document (e.g. `"application/pdf"`). */
  readonly mimeType?: string;
  /** Document-level metadata (author, title, dates, format-specific fields). */
  readonly metadata?: Metadata;
  /**
   * Extraction strategy used to produce the returned text.
   *
   * Populated when the extractor can reliably distinguish native text extraction,
   * OCR-only extraction, or mixed native/OCR output.
   */
  readonly extractionMethod?: ExtractionMethod;
  /** Tables extracted from the document, each with structured cell data. */
  readonly tables?: Array<Table>;
  /**
   * Cheap structural counts (pages, tables, images).
   *
   * Always populated by the extraction pipeline, even when the `pages` /
   * `images` collections are `None`. See `DocumentCounts`.
   */
  readonly counts?: DocumentCounts;
  /** ISO 639-1 language codes detected in the document content. */
  readonly detectedLanguages?: Array<string>;
  /**
   * Structured per-language detection results: confidence, document share, script,
   * and reliability, alongside the ISO-code-only `detected_languages` (#261).
   *
   * One entry per language in `detected_languages`, in the same order. `None` under
   * the same conditions as `detected_languages`: detection disabled, empty input
   * text, or no language met the configured `min_confidence`.
   */
  readonly detectedLanguageConfidences?: Array<LanguageConfidence>;
  /**
   * Text chunks when chunking is enabled.
   *
   * When chunking configuration is provided, the content is split into
   * overlapping chunks for efficient processing. Each chunk contains the text,
   * optional embeddings (if enabled), and metadata about its position.
   */
  readonly chunks?: Array<Chunk>;
  /**
   * Extracted images from the document.
   *
   * When image extraction is enabled via `ImageExtractionConfig`, this field
   * contains all images found in the document with their raw data and metadata.
   * Each image may optionally contain a nested `ocr_result` if OCR was performed.
   */
  readonly images?: Array<ExtractedImage>;
  /**
   * Per-page content when page extraction is enabled.
   *
   * When page extraction is configured, the document is split into per-page content
   * with tables and images mapped to their respective pages.
   */
  readonly pages?: Array<PageContent>;
  /**
   * Semantic elements when element-based result format is enabled.
   *
   * When result_format is set to ElementBased, this field contains semantic
   * elements with type classification, unique identifiers, and metadata for
   * Unstructured-compatible element-based processing.
   */
  readonly elements?: Array<Element>;
  /**
   * Rich Djot content structure (when extracting Djot documents).
   *
   * When extracting Djot documents with structured extraction enabled,
   * this field contains the full semantic structure including:
   * - Block-level elements with nesting
   * - Inline formatting with attributes
   * - Links, images, footnotes
   * - Math expressions
   * - Complete attribute information
   *
   * The `content` field still contains plain text for backward compatibility.
   *
   * Always `None` for non-Djot documents.
   */
  readonly djotContent?: DjotContent;
  /**
   * OCR elements with full spatial and confidence metadata.
   *
   * When OCR is performed with element extraction enabled, this field contains
   * the structured representation of detected text including:
   * - Bounding geometry (rectangles or quadrilaterals)
   * - Confidence scores (detection and recognition)
   * - Rotation information
   * - Hierarchical relationships (Tesseract only)
   *
   * This field preserves all metadata that would otherwise be lost when
   * converting to plain text or markdown output formats.
   *
   * Only populated when `OcrElementConfig.include_elements` is true.
   */
  readonly ocrElements?: Array<OcrElement>;
  /**
   * Structured document tree (when document structure extraction is enabled).
   *
   * When `include_document_structure` is true in `ExtractionConfig`, this field
   * contains the full hierarchical representation of the document including:
   * - Heading-driven section nesting
   * - Table grids with cell-level metadata
   * - Content layer classification (body, header, footer, footnote)
   * - Inline text annotations (formatting, links)
   * - Bounding boxes and page numbers
   *
   * Independent of `result_format` — can be combined with Unified or ElementBased.
   */
  readonly document?: DocumentStructure;
  /**
   * Extracted keywords when keyword extraction is enabled.
   *
   * When keyword extraction (RAKE or YAKE) is configured, this field contains
   * the extracted keywords with scores, algorithm info, and position data.
   * Previously stored in `metadata.additional["keywords"]`.
   */
  readonly extractedKeywords?: Array<Keyword>;
  /**
   * Text cleanliness/readability score from quality analysis.
   *
   * A value between 0.0 and 1.0 describing the quality of the text that was
   * retained. This is not a completeness or recall score: clean text can score
   * highly even when an extractor omitted or rejected other content. Inspect
   * `processing_warnings` separately for known degraded or partial extraction.
   * Previously stored in `metadata.additional["quality_score"]`.
   */
  readonly qualityScore?: number;
  /**
   * Non-fatal warnings collected during processing pipeline stages.
   *
   * Captures errors from optional pipeline features (embedding, chunking,
   * language detection, output formatting) that don't prevent extraction
   * but may indicate degraded or incomplete results. These warnings are
   * independent of `quality_score`, which assesses only retained text.
   * Previously stored as individual keys in `metadata.additional`.
   */
  readonly processingWarnings?: Array<ProcessingWarning>;
  /**
   * PDF annotations extracted from the document.
   *
   * When annotation extraction is enabled via `PdfConfig.extract_annotations`,
   * this field contains text notes, highlights, links, stamps, and other
   * annotations found in PDF documents.
   */
  readonly annotations?: Array<PdfAnnotation>;
  /**
   * Nested extraction results from archive contents.
   *
   * When extracting archives, each processable file inside produces its own
   * full extraction result. Set to `None` for non-archive formats.
   * Use `max_archive_depth` in config to control recursion depth.
   */
  readonly children?: Array<ArchiveEntry>;
  /**
   * URIs/links discovered during document extraction.
   *
   * Contains hyperlinks, image references, citations, email addresses, and
   * other URI-like references found in the document. Always extracted when
   * present in the source document.
   */
  readonly uris?: Array<ExtractedUri>;
  /**
   * Tracked changes embedded in the source document.
   *
   * Populated by per-format extractors that understand change-tracking
   * metadata (DOCX `w:ins`/`w:del`/`w:rPrChange`, ODT `text:change-*`,
   * …). Every extractor defaults to `None` until its format-specific
   * implementation is added. Extractors that do populate this field follow
   * the "accepted-changes" convention: inserted text is present in
   * `content`, deleted text is absent — the revision list is the separate
   * audit trail.
   */
  readonly revisions?: Array<DocumentRevision>;
  /**
   * Structured extraction output from LLM-based JSON schema extraction.
   *
   * When `structured_extraction` is configured in `ExtractionConfig`, the
   * extracted document content is sent to a VLM with the provided JSON schema.
   * The response is parsed and stored here as a JSON value matching the schema.
   */
  readonly structuredOutput?: JsonValue;
  /**
   * Code intelligence results from tree-sitter analysis.
   *
   * Populated when extracting source code files with the `tree-sitter` feature.
   * Contains metrics, structural analysis, imports/exports, comments,
   * docstrings, symbols, diagnostics, and optionally chunked code segments.
   *
   * Stored as an opaque JSON value so that all language bindings (Go, Java,
   * C#, …) can deserialize it as a raw JSON object rather than a typed struct.
   * The underlying type is `tree_sitter_language_pack.ProcessResult`.
   */
  readonly codeIntelligence?: JsonValue;
  /**
   * LLM token usage and cost data for all LLM calls made during this extraction.
   *
   * Contains one entry per LLM call. Multiple entries are produced when
   * VLM OCR, structured extraction, or LLM embeddings run during
   * the same extraction.
   *
   * `None` when no LLM was used.
   */
  readonly llmUsage?: Array<LlmUsage>;
  /**
   * Named entities detected in `content` by the NER post-processor.
   *
   * `None` when no NER backend is configured. Populated by the `xberg-gliner`
   * ONNX backend or the LLM-driven backend (see `crates/xberg/src/text/ner/`).
   */
  readonly entities?: Array<Entity>;
  /**
   * Summary of `content` produced by the summarisation post-processor.
   *
   * `None` when summarisation is not configured. Populated by the TextRank
   * extractive backend (deterministic, no external service) or by the
   * liter-llm-driven abstractive backend.
   */
  readonly summary?: DocumentSummary;
  /**
   * Confidence score computed by the heuristics pipeline.
   *
   * Populated when the `heuristics` feature is enabled and confidence
   * scoring has been performed.  Combines text-coverage, OCR aggregate
   * confidence, and schema-compliance into a single `[0, 1]` value.
   *
   * `None` when confidence scoring is not configured or the feature is
   * absent.
   */
  readonly extractionConfidence?: ExtractionConfidence;
  /**
   * Translation of `content` produced by the translation post-processor.
   *
   * `None` when translation is not configured.
   */
  readonly translation?: Translation;
  /**
   * Per-page classifications produced by the page-classification post-processor.
   *
   * `None` when classification is not configured.
   */
  readonly pageClassifications?: Array<PageClassification>;
  /**
   * Audit report of redactions applied by the redaction post-processor.
   *
   * The redaction processor rewrites `content`, `formatted_content`, every
   * chunk's text, and the textual fields of `entities` / `summary` / `translation` /
   * `page_classifications` in place. This report describes what was found and how it
   * was replaced. `None` when redaction is not configured.
   */
  readonly redactionReport?: RedactionReport;
  /**
   * Mathematical formulas recognized in the document.
   *
   * Populated from every source that produces formulas: layout-guided OCR
   * (with geometry), VLM OCR (text only), and markup extraction (DOCX,
   * PPTX, ODT, EPUB, HTML, JATS, LaTeX, Markdown, and related formats,
   * without geometry). Empty when the document contains no formulas.
   */
  readonly formulas?: Array<Formula>;
  /**
   * Form fields extracted from a PDF's AcroForm or XFA structure.
   *
   * Populated by the PDF extractor when `PdfConfig.extract_form_fields` is
   * enabled (default) and the document is a fillable form. Empty otherwise.
   */
  readonly formFields?: Array<PdfFormField>;
}

/**
 * Extracted image from a document.
 *
 * Contains raw image data, metadata, and optional nested OCR results.
 * Raw bytes allow cross-language compatibility - users can convert to
 * PIL.Image (Python), Sharp (Node.js), or other formats as needed.
 */
export interface ExtractedImage {
  /**
   * Raw image data (PNG, JPEG, WebP, etc. bytes).
   * Uses `bytes.Bytes` for cheap cloning of large buffers.
   */
  readonly data?: Uint8Array;
  /**
   * Image format (e.g., "jpeg", "png", "webp")
   * Uses Cow<, str> to avoid allocation for static literals.
   */
  readonly format?: string;
  /** Zero-indexed position of this image in the document/page */
  readonly imageIndex?: number;
  /** Page/slide number where image was found (1-indexed) */
  readonly pageNumber?: number;
  /** Image width in pixels */
  readonly width?: number;
  /** Image height in pixels */
  readonly height?: number;
  /** Colorspace information (e.g., "RGB", "CMYK", "Gray") */
  readonly colorspace?: string;
  /** Bits per color component (e.g., 8, 16) */
  readonly bitsPerComponent?: number;
  /** Whether this image is a mask image */
  readonly isMask?: boolean;
  /** Optional description of the image */
  readonly description?: string;
  /**
   * Nested OCR extraction result (if image was OCRed)
   *
   * When OCR is performed on this image, the result is embedded here
   * rather than in a separate collection, making the relationship explicit.
   */
  readonly ocrResult?: ExtractedDocument;
  /**
   * Bounding box of the image on the page (PDF coordinates: x0=left, y0=bottom, x1=right, y1=top).
   * Only populated for PDF-extracted images when position data is available from the PDF extractor.
   */
  readonly boundingBox?: BoundingBox;
  /**
   * Original source path of the image within the document archive (e.g., "media/image1.png" in DOCX).
   * Used for rendering image references when the binary data is not extracted.
   */
  readonly sourcePath?: string;
  /**
   * Heuristic classification of what this image likely depicts.
   * `None` if classification was disabled or inconclusive.
   */
  readonly imageKind?: ImageKind;
  /** Confidence score for `image_kind`, in the range 0.0 to 1.0. */
  readonly kindConfidence?: number;
  /**
   * Identifier shared across images that form a single logical figure
   * (e.g. all raster tiles of one technical drawing). `None` for singletons.
   */
  readonly clusterId?: number;
  /**
   * VLM-generated caption describing the image, when captioning is configured.
   *
   * Populated by the captioning post-processor
   * (`crates/xberg/src/plugins/processor/builtin/captioning.rs`), which routes
   * each image through `crate.llm.region_extractor.extract_region_with_vlm` in
   * caption mode. `None` when captioning is disabled or the VLM declined to caption.
   */
  readonly caption?: string;
  /**
   * QR codes decoded from this image, when QR detection is enabled.
   *
   * Populated by the QR post-processor (`crates/xberg/src/extractors/qr.rs`) via
   * the pure-Rust `rqrr` decoder. `None` when QR detection is disabled; an empty
   * `Some(vec![])` when detection ran but found nothing.
   */
  readonly qrCodes?: Array<QrCode>;
  /**
   * Base64-encoded copy of `data`; populated when `ImageExtractionConfig.include_data_base64`
   * is `true`. Omitted from JSON by default; use instead of `data` in JSON-only clients.
   */
  readonly dataBase64?: string;
}

/**
 * A URI extracted from a document.
 *
 * Represents any link, reference, or resource pointer found during extraction.
 * The `kind` field classifies the URI semantically, while `label` carries
 * optional human-readable display text.
 */
export interface ExtractedUri {
  /** The URL or path string. */
  readonly url: string;
  /** Optional display text / label for the link. */
  readonly label?: string;
  /** Optional page number where the URI was found (1-indexed). */
  readonly page?: number;
  /** Semantic classification of the URI. */
  readonly kind: UriKind;
}

/** Unified extraction input for all public extraction entry points. */
export interface ExtractInput {
  /** Source kind. `bytes` requires `bytes`; `uri` requires `uri`. */
  readonly kind?: ExtractInputKind;
  /** Raw bytes for `kind = "bytes"`. */
  readonly bytes?: Uint8Array;
  /** Local path, `file://` URI, or HTTP(S) URL for `kind = "uri"`. */
  readonly uri?: string;
  /** MIME type hint. */
  readonly mimeType?: string;
  /** Filename hint used for MIME detection and metadata. */
  readonly filename?: string;
  /** Per-input extraction overrides. */
  readonly config?: FileExtractionConfig;
}

/** Source kind for `ExtractInput`. */
export declare enum ExtractInputKind {
  /** Raw in-memory bytes. */
  Bytes = "bytes",
  /** A filesystem path, `file://` URI, or HTTP(S) URL. */
  Uri = "uri",
}

/**
 * Combined confidence on `[0, 1]`.
 *
 * When OCR did not run, the `ocr_aggregate` weight folds into `text_coverage`
 * so the weighted sum still totals 1.0.
 */
export interface ExtractionConfidence {
  /** Fraction of pages with a usable text layer. */
  readonly textCoverage: number;
  /** Mean OCR per-element recognition confidence when OCR ran; `None` when it did not. */
  readonly ocrAggregate?: number;
  /** Whether the merged output validates against the preset schema. */
  readonly schemaCompliance: SchemaCompliance;
  /** Weighted blend in `[0, 1]`.  The value compared against the fallback threshold. */
  readonly combined: number;
}

/**
 * Main extraction configuration.
 *
 * This struct contains all configuration options for the extraction process.
 * It can be loaded from TOML, YAML, or JSON files, or created programmatically.
 */
export interface ExtractionConfig {
  /** Controls whether MIME inference prefers content, a supported extension, or content alone. */
  readonly mimeDetectionPolicy?: MimeDetectionPolicy;
  /** Enable caching of extraction results */
  readonly useCache?: boolean;
  /** Enable quality post-processing */
  readonly enableQualityProcessing?: boolean;
  /**
   * OCR configuration.
   *
   * `None` does not run OCR for documents that already have usable text. Under
   * `OcrStrategy.Auto`, a PDF with no text layer at all (a scan) is still routed
   * to OCR with default settings so it is not returned empty (#1338). Set
   * `Self.disable_ocr` to hard-disable OCR regardless of the detected content.
   */
  readonly ocr?: OcrConfig;
  /** Force OCR even for searchable PDFs */
  readonly forceOcr?: boolean;
  /**
   * Which pages get OCR'd when neither `force_ocr` nor `force_ocr_pages` applies.
   *
   * Defaults to `OcrStrategy.Auto`, which OCRs only pages whose native text
   * fails a quality check. Only applies to PDF documents. Cannot be
   * `OcrStrategy.ScannedPages` while `disable_ocr` is `true`.
   */
  readonly ocrStrategy?: OcrStrategy;
  /**
   * Force OCR on specific pages only (1-indexed page numbers, must be >= 1).
   *
   * When set, only the listed pages are OCR'd regardless of text layer quality.
   * Unlisted pages use native text extraction. Ignored when `force_ocr` is `true`.
   * Only applies to PDF documents. Duplicates are automatically deduplicated.
   * An `ocr` config is recommended for backend/language selection; defaults are used if absent.
   */
  readonly forceOcrPages?: Array<number>;
  /**
   * Disable OCR entirely, even for images.
   *
   * When `true`, OCR is skipped for all document types. Images return metadata
   * only (dimensions, format, EXIF) without text extraction. PDFs use only
   * native text extraction without OCR fallback.
   *
   * Cannot be `true` simultaneously with `force_ocr`.
   */
  readonly disableOcr?: boolean;
  /** Text chunking configuration (undefined = chunking disabled) */
  readonly chunking?: ChunkingConfig;
  /**
   * Content filtering configuration (undefined = use extractor defaults).
   *
   * Controls whether document "furniture" (headers, footers, watermarks,
   * repeating text) is included in or stripped from extraction results.
   * See `ContentFilterConfig` for per-field documentation.
   */
  readonly contentFilter?: ContentFilterConfig;
  /** Image extraction configuration (undefined = no image extraction) */
  readonly images?: ImageExtractionConfig;
  /** PDF-specific options (undefined = use defaults) */
  readonly pdfOptions?: PdfConfig;
  /** Token reduction configuration (undefined = no token reduction) */
  readonly tokenReduction?: TokenReductionOptions;
  /** Language detection configuration (undefined = no language detection) */
  readonly languageDetection?: LanguageDetectionConfig;
  /** Page extraction configuration (undefined = no page tracking) */
  readonly pages?: PageConfig;
  /** Keyword extraction configuration (undefined = no keyword extraction) */
  readonly keywords?: KeywordConfig;
  /** Post-processor configuration (undefined = use defaults) */
  readonly postprocessor?: PostProcessorConfig;
  /**
   * HTML to Markdown conversion options (undefined = use defaults)
   *
   * Configure how HTML documents are converted to Markdown, including heading styles,
   * list formatting, code block styles, and preprocessing options.
   */
  readonly htmlOptions?: ConversionOptions;
  /**
   * Styled HTML output configuration.
   *
   * When set alongside `output_format = OutputFormat.Html`, the extraction
   * pipeline uses `StyledHtmlRenderer`
   * which emits stable `kb-*` CSS class hooks on every structural element
   * and optionally embeds theme CSS or user-supplied CSS in a `<style>` block.
   *
   * When `None`, the existing plain comrak-based HTML renderer is used.
   */
  readonly htmlOutput?: HtmlOutputConfig;
  /**
   * Default per-file timeout in seconds for batch extraction.
   *
   * When set, each file in a batch will be canceled after this duration
   * unless overridden by `FileExtractionConfig.timeout_secs`.
   *
   * Defaults to `Some(600)` (10 minutes) to prevent pathological files
   * (e.g. deeply nested archives, documents with millions of cells) from
   * running indefinitely and exhausting caller resources, while still
   * giving slow paths (VLM-based OCR, large scanned documents) enough
   * headroom to finish. Set to `None` to disable the timeout for trusted
   * input or long-running workloads.
   */
  readonly extractionTimeoutSecs?: number;
  /**
   * Maximum concurrent document extractions in batch operations.
   *
   * This is a ceiling within the configured total thread budget, not an
   * independent pool size. When unset, the scheduler derives document and
   * per-document concurrency from `ConcurrencyConfig.max_threads`.
   */
  readonly maxConcurrentExtractions?: number;
  /**
   * Result structure format
   *
   * Controls whether results are returned in unified format (default) with all
   * content in the `content` field, or element-based format with semantic
   * elements (for Unstructured-compatible output).
   */
  readonly resultFormat?: ResultFormat;
  /**
   * Security limits for archive extraction.
   *
   * Controls maximum archive size, compression ratio, file count, and other
   * security thresholds to prevent decompression bomb attacks. Also caps
   * nesting depth, iteration count, entity / token length, total content size,
   * decoded image allocation, and table cell count for every extraction path
   * that ingests user-controlled bytes.
   * When `None`, default limits are used.
   */
  readonly securityLimits?: SecurityLimits;
  /**
   * Maximum uncompressed size in bytes for a single embedded file before
   * recursive extraction is attempted (default: 50 MiB).
   *
   * Applies to embedded objects inside OOXML containers (DOCX, PPTX) and
   * to email attachments processed via recursive extraction. Files that
   * exceed this limit are skipped with a `ProcessingWarning` rather than
   * passed to the extraction pipeline, preventing a single oversized
   * embedded object from consuming unbounded memory or time.
   *
   * Set to `None` to disable the per-embedded-file cap (falls back to
   * `security_limits.max_archive_size` as the only guard).
   */
  readonly maxEmbeddedFileBytes?: number;
  /**
   * Content text format (default: Plain).
   *
   * Controls the format of the extracted content:
   * - `Plain`: Raw extracted text (default)
   * - `Markdown`: Markdown formatted output
   * - `Djot`: Djot markup format (requires djot feature)
   * - `Html`: HTML formatted output
   *
   * When set to a structured format, extraction results will include
   * formatted output. The `formatted_content` field may be populated
   * when format conversion is applied.
   */
  readonly outputFormat?: OutputFormat;
  /**
   * Escape Markdown special characters in rendered prose (default: `true`).
   *
   * When `output_format` is `Markdown` or `Djot`, the renderer backslash-escapes
   * CommonMark-significant leading characters (e.g. `-`, `#`) so that literal
   * text such as `#06-18` or `- clause` round-trips safely through a CommonMark
   * parser instead of being reinterpreted as a heading or list marker.
   *
   * Table cell text is never escaped, so escaped prose can look inconsistent
   * with table cells containing the same characters. Set this to `false` to
   * disable prose escaping and make `content`, `pages[].content`, and
   * `chunks[].content` read identically to table cell text — useful for LLM
   * prompts or search indexing where CommonMark round-tripping does not matter.
   *
   * Defaults to `true` to preserve existing behavior.
   */
  readonly escapeMarkdown?: boolean;
  /**
   * Emit an opt-in anchor marker before each table's rendered Markdown
   * block (default: `false`).
   *
   * When `output_format` is `Markdown` (or `Djot`) and this is `true`, the
   * renderer inserts a `[TABLE:{table_id}]` marker immediately before each
   * table's Markdown in `content`, `pages[].content`, and
   * `chunks[].content`, where `table_id` matches the corresponding
   * entry's `table_id`. This lets a consumer
   * reconcile a rendered Markdown table block with its structured
   * `tables[]` entry.
   *
   * Defaults to `false` so existing output is byte-identical unless
   * explicitly enabled.
   */
  readonly tableAnchors?: boolean;
  /**
   * Controls how Jupyter notebook (`.ipynb`) code cells are rendered.
   *
   * - `Both` (default): code source plus the notebook's saved outputs
   * - `Source`: only the code source (fenced code blocks)
   * - `Outputs`: only the saved outputs
   *
   * Cells are never executed; `Outputs`/`Both` surface only outputs already
   * stored in the notebook.
   */
  readonly jupyterCellRendering?: JupyterCellRendering;
  /**
   * Apply Jupyter Book/MyST cell visibility tags while rendering notebooks.
   *
   * When enabled, `remove-cell`/`hide-cell`, `remove-input`/`hide-input`,
   * and `remove-output`/`hide-output` suppress the corresponding saved
   * source or output. Cells are never executed, and their metadata remains
   * available even when their rendered content is suppressed.
   *
   * Defaults to `true`. Set this to `false` to preserve all saved notebook
   * content regardless of cell tags.
   */
  readonly applyNotebookCellTags?: boolean;
  /**
   * Layout detection configuration (undefined = layout detection disabled).
   *
   * When set, PDF pages and images are analyzed for document structure
   * (headings, code, formulas, tables, figures, etc.) using RT-DETR models
   * via ONNX Runtime. For PDFs, layout hints override paragraph classification
   * in the markdown pipeline. For images, per-region OCR is performed with
   * markdown formatting based on detected layout classes.
   * Requires the `layout-detection` feature to run inference; the field is
   * present whenever the `layout-types` feature is active (which includes
   * `layout-detection` as well as the no-ORT target groups).
   */
  readonly layout?: LayoutDetectionConfig;
  /**
   * Transcription (speech-to-text) configuration for audio/video files.
   *
   * When set and `enabled`, files with audio/video MIME types (mp3, mp4,
   * m4a, wav, webm, etc.) are routed to the Whisper-based transcription
   * pipeline. The actual heavy dependencies are only active under the
   * `transcription` feature; the field is visible under `transcription-types`
   * (including on WASM and Android targets that use the no-ORT preset).
   *
   * Default: `None` (transcription disabled). This is an additive,
   * non-breaking change.
   */
  readonly transcription?: TranscriptionConfig;
  /**
   * Run layout detection on the non-OCR PDF markdown path.
   *
   * When `true` and `layout` is `Some(_)`, layout regions inform reading
   * order, region grouping, and table detection while native font/tag
   * semantics remain authoritative for headings, lists, code, and formulas.
   * OCR layout classification is unchanged. This improves structural output
   * at the cost of inference latency (~150-300ms/page CPU, ~20-50ms/page
   * GPU). Default: `false`. Requires the `layout-detection` feature.
   */
  readonly useLayoutForMarkdown?: boolean;
  /**
   * Enable structured document tree output.
   *
   * When true, populates the `document` field on `ExtractedDocument` with a
   * hierarchical `DocumentStructure` containing heading-driven section nesting,
   * table grids, content layer classification, and inline annotations.
   *
   * Independent of `result_format` — can be combined with Unified or ElementBased.
   */
  readonly includeDocumentStructure?: boolean;
  /**
   * Hardware acceleration configuration for ONNX Runtime models.
   *
   * Controls execution provider selection for layout detection and embedding
   * models. When `None`, uses platform defaults (CoreML on macOS, CUDA on
   * Linux, CPU on Windows).
   */
  readonly acceleration?: AccelerationConfig;
  /**
   * Cache namespace for tenant isolation.
   *
   * When set, cache entries are stored under `{cache_dir}/{namespace}/`.
   * Must be alphanumeric, hyphens, or underscores only (max 64 chars).
   * Different namespaces have isolated cache spaces on the same filesystem.
   */
  readonly cacheNamespace?: string;
  /**
   * Per-request cache TTL in seconds.
   *
   * Overrides the global `max_age_days` for this specific extraction.
   * When `0`, caching is completely skipped (no read or write).
   * When `None`, the global TTL applies.
   */
  readonly cacheTtlSecs?: number;
  /**
   * Email extraction configuration (undefined = use defaults).
   *
   * Currently supports configuring the fallback codepage for MSG files
   * that do not specify one. See `EmailConfig` for details.
   */
  readonly email?: EmailConfig;
  /**
   * CSV/TSV extraction configuration (undefined = use defaults).
   *
   * Lets callers set an explicit delimiter and declare comment-line
   * prefixes to skip, instead of relying solely on delimiter
   * auto-detection. See `CsvConfig` for details.
   */
  readonly csv?: CsvConfig;
  /**
   * GeoJSON extraction configuration (undefined = bounded summary).
   *
   * By default, GeoJSON coordinates are replaced by aggregate counts and bounds
   * so large geometry arrays do not become unbounded rendered output. Set
   * `include_full_coordinates`
   * explicitly to retain the legacy full-coordinate output.
   */
  readonly geojson?: GeoJsonExtractionConfig;
  /**
   * Concurrency limits for constrained environments (undefined = use defaults).
   *
   * Controls Rayon thread pool size, ONNX Runtime intra-op threads, and the
   * combined document/inner-task budget for batch extraction. See
   * `ConcurrencyConfig` for details.
   */
  readonly concurrency?: ConcurrencyConfig;
  /** URL ingestion and crawl configuration. */
  readonly url?: UrlExtractionConfig;
  /**
   * Maximum recursion depth for archive extraction (default: 3).
   * Set to 0 to disable recursive extraction (legacy behavior).
   */
  readonly maxArchiveDepth?: number;
  /**
   * Tree-sitter language pack configuration (undefined = tree-sitter disabled).
   *
   * When set, enables code file extraction using tree-sitter parsers.
   * Controls grammar download behavior and code analysis options.
   */
  readonly treeSitter?: TreeSitterConfig;
  /**
   * Structured extraction via LLM (undefined = disabled).
   *
   * When set, the extracted document content is sent to an LLM with the
   * provided JSON schema. The structured response is stored in
   * `ExtractedDocument.structured_output`.
   */
  readonly structuredExtraction?: StructuredExtractionConfig;
  /**
   * Named-entity recognition configuration. When set, the NER post-processor runs at
   * the Middle stage and populates `ExtractedDocument.entities`.
   */
  readonly ner?: NerConfig;
  /**
   * Redaction / anonymisation configuration. When set, the redaction post-processor
   * runs at the Late stage and rewrites every textual field in `ExtractedDocument`,
   * emitting an audit trail in `ExtractedDocument.redaction_report`.
   */
  readonly redaction?: RedactionConfig;
  /**
   * Summarisation configuration. When set, the summarisation post-processor runs at
   * the Middle stage and populates `ExtractedDocument.summary`.
   */
  readonly summarization?: SummarizationConfig;
  /**
   * Translation configuration. When set, the translation post-processor runs at the
   * Middle stage and populates `ExtractedDocument.translation`.
   */
  readonly translation?: TranslationConfig;
  /**
   * Per-page classification configuration. When set, the classification post-processor
   * runs at the Middle stage and populates `ExtractedDocument.page_classifications`.
   */
  readonly pageClassification?: PageClassificationConfig;
  /**
   * Per-chunk multi-label classification configuration. When set, the
   * chunk-classification post-processor runs at the Middle stage (after
   * chunking) and populates `ChunkMetadata.classifications` on every chunk.
   */
  readonly chunkClassification?: ChunkClassificationConfig;
  /**
   * VLM captioning configuration for extracted images. When set, the captioning
   * post-processor runs at the Middle stage and writes a caption into each
   * `ExtractedImage.caption`.
   */
  readonly captioning?: CaptioningConfig;
  /**
   * Enable QR-code detection in extracted images. When `true`, the QR post-processor
   * runs at the Middle stage and populates `ExtractedImage.qr_codes`.
   */
  readonly qrCodes?: boolean;
}

/** The complete diff between two `ExtractedDocument` values. */
export interface ExtractionDiff {
  /**
   * Unified-diff hunks for the `content` field.
   *
   * Empty when the content is identical.
   */
  readonly contentDiff?: Array<DiffHunk>;
  /** Tables present in `b` but not in `a` (by index position, excess right-side tables). */
  readonly tablesAdded?: Array<Table>;
  /** Tables present in `a` but not in `b` (by index position, excess left-side tables). */
  readonly tablesRemoved?: Array<Table>;
  /** Cell-level changes for table pairs that share the same index and dimensions. */
  readonly tablesChanged?: Array<TableDiff>;
  /**
   * Metadata difference, encoded as a JSON object with three top-level keys:
   * `added` (keys present in `b` but not `a`), `removed` (keys present in `a`
   * but not `b`), and `changed` (keys whose values differ — each entry is
   * `{ "from": <value-in-a>, "to": <value-in-b> }`).
   *
   * This is NOT RFC 6902 JSON Patch — we deliberately chose a flatter shape
   * to avoid pulling in a json-patch crate. If you need RFC 6902 semantics
   * (with JSON Pointer paths) feed `a.metadata` and `b.metadata` to your
   * preferred json-patch impl directly.
   */
  readonly metadataChanged?: JsonValue;
  /** Changes to embedded archive children. */
  readonly embeddedChanges?: EmbeddedChanges;
}

/** Non-fatal per-input extraction error captured by `ExtractionResult`. */
export interface ExtractionErrorItem {
  /** Input index in the original request. */
  readonly index: number;
  /** Stable numeric error code. */
  readonly code: number;
  /** Stable snake_case error kind. */
  readonly errorType: string;
  /** Best-effort source identifier. */
  readonly source: string;
  /** Error message. */
  readonly message: string;
}

/** How the extracted text was produced. */
export declare enum ExtractionMethod {
  /** Text extracted directly from the document's native format (no OCR). */
  Native = "native",
  /** All text was obtained via OCR (e.g. scanned image-only PDF). */
  Ocr = "ocr",
  /** Text came from a combination of native extraction and OCR. */
  Mixed = "mixed",
}

/** Unified extraction result envelope. */
export interface ExtractionResult {
  /** Extracted documents in discovery order. */
  readonly results?: Array<ExtractedDocument>;
  /** Non-fatal per-input errors. */
  readonly errors?: Array<ExtractionErrorItem>;
  /** Aggregate counts for the operation. */
  readonly summary?: ExtractionSummary;
  /** Final URLs reached after redirects during URL ingestion. */
  readonly crawlFinalUrls?: Array<string>;
  /** Total redirects followed while fetching or crawling URLs. */
  readonly crawlRedirectCount?: number;
  /** Unique normalized URLs discovered by crawls. */
  readonly crawlUniqueNormalizedUrls?: Array<string>;
}

/** Summary for a unified extraction call. */
export interface ExtractionSummary {
  /** Number of inputs submitted by the caller. */
  readonly inputs?: number;
  /** Number of extraction results produced. */
  readonly results?: number;
  /** Number of per-input errors. */
  readonly errors?: number;
  /** Number of URI inputs that resolved to remote HTTP(S) URLs. */
  readonly remoteUrls?: number;
  /** Number of HTML pages crawled or scraped. */
  readonly pagesCrawled?: number;
  /** Number of downloaded non-HTML documents extracted from URLs. */
  readonly documentsDownloaded?: number;
}

/** FictionBook (FB2) metadata. */
export interface FictionBookMetadata {
  /** Genre tags as declared in the FB2 `<genre>` elements. */
  readonly genres?: Array<string>;
  /** Book series (sequence) names, if any. */
  readonly sequences?: Array<string>;
  /** Short annotation / summary from the FB2 `<annotation>` element. */
  readonly annotation?: string;
}

/**
 * Per-file extraction configuration overrides for batch processing.
 *
 * All fields are `Option<T>` — `None` means "use the batch-level default."
 * This type is used by `config` and `extract_batch`
 * to allow heterogeneous extraction settings within a single batch.
 *
 * # Excluded Fields
 *
 * The following `ExtractionConfig` fields are batch-level only and
 * cannot be overridden per file:
 * - `max_concurrent_extractions` — controls batch parallelism
 * - `use_cache` — global caching policy
 * - `acceleration` — shared ONNX execution provider
 * - `security_limits` — global archive security policy
 */
export interface FileExtractionConfig {
  /** Override MIME inference policy for this file. */
  readonly mimeDetectionPolicy?: MimeDetectionPolicy;
  /** Override quality post-processing for this file. */
  readonly enableQualityProcessing?: boolean;
  /** Override OCR configuration for this file (undefined in the Option = use batch default). */
  readonly ocr?: OcrConfig;
  /** Override force OCR for this file. */
  readonly forceOcr?: boolean;
  /** Override the OCR page-selection strategy for this file. */
  readonly ocrStrategy?: OcrStrategy;
  /** Override force OCR pages for this file (1-indexed page numbers). */
  readonly forceOcrPages?: Array<number>;
  /** Override disable OCR for this file. */
  readonly disableOcr?: boolean;
  /** Override chunking configuration for this file. */
  readonly chunking?: ChunkingConfig;
  /** Override content filtering configuration for this file. */
  readonly contentFilter?: ContentFilterConfig;
  /** Override image extraction configuration for this file. */
  readonly images?: ImageExtractionConfig;
  /** Override PDF options for this file. */
  readonly pdfOptions?: PdfConfig;
  /** Override token reduction for this file. */
  readonly tokenReduction?: TokenReductionOptions;
  /** Override language detection for this file. */
  readonly languageDetection?: LanguageDetectionConfig;
  /** Override page extraction for this file. */
  readonly pages?: PageConfig;
  /** Override keyword extraction for this file. */
  readonly keywords?: KeywordConfig;
  /** Override post-processor for this file. */
  readonly postprocessor?: PostProcessorConfig;
  /** Override HTML conversion options for this file. */
  readonly htmlOptions?: ConversionOptions;
  /** Override styled HTML output configuration for this file. */
  readonly htmlOutput?: HtmlOutputConfig;
  /** Override result format for this file. */
  readonly resultFormat?: ResultFormat;
  /** Override output content format for this file. */
  readonly outputFormat?: OutputFormat;
  /** Override document structure output for this file. */
  readonly includeDocumentStructure?: boolean;
  /** Override layout detection for this file. */
  readonly layout?: LayoutDetectionConfig;
  /** Transcription configuration (see ExtractionConfig for docs). */
  readonly transcription?: TranscriptionConfig;
  /**
   * Override per-file extraction timeout in seconds.
   *
   * When set, the extraction for this file will be canceled after the
   * specified duration. A timed-out file produces an error result without
   * affecting other files in the batch.
   */
  readonly timeoutSecs?: number;
  /** Override tree-sitter configuration for this file. */
  readonly treeSitter?: TreeSitterConfig;
  /**
   * Override structured extraction configuration for this file.
   *
   * When set, enables LLM-based structured extraction with a JSON schema
   * for this specific file. The extracted content is sent to a VLM/LLM
   * and the response is parsed according to the provided schema.
   */
  readonly structuredExtraction?: StructuredExtractionConfig;
  /** Override URL ingestion and crawl configuration for this file. */
  readonly url?: UrlExtractionConfig;
  /** Override named-entity recognition configuration for this file. */
  readonly ner?: NerConfig;
  /** Override redaction configuration for this file. */
  readonly redaction?: RedactionConfig;
  /** Override summarization configuration for this file. */
  readonly summarization?: SummarizationConfig;
  /** Override translation configuration for this file. */
  readonly translation?: TranslationConfig;
  /** Override per-page classification configuration for this file. */
  readonly pageClassification?: PageClassificationConfig;
  /** Override per-chunk classification configuration for this file. */
  readonly chunkClassification?: ChunkClassificationConfig;
  /** Override VLM captioning configuration for this file. */
  readonly captioning?: CaptioningConfig;
  /** Override QR-code detection for this file. */
  readonly qrCodes?: boolean;
}

/** Footnote in Djot. */
export interface Footnote {
  /** Footnote label */
  readonly label: string;
  /** Footnote content blocks */
  readonly content: Array<FormattedBlock>;
}

/**
 * A footnote anchor reference in markdown text.
 *
 * Represents a `[^label]` use-site (not a definition).
 */
export interface FootnoteAnchor {
  /** The label of the footnote reference (e.g., "1" in `[^1]`). */
  readonly label: string;
  /** Byte offset of the anchor in the markdown text. */
  readonly offset: number;
}

/** Configuration for markdown footnote and citation parsing. */
export interface FootnoteConfig {
  /**
   * Whether to parse the structured citation block (default: true).
   *
   * When enabled, the parser will look for and extract citations from
   * the block after `---` + `<!-- citations ... -->`.
   */
  readonly parseCitations?: boolean;
}

/**
 * A footnote definition from markdown text.
 *
 * Represents `[^label]: content` declarations (including multi-line continuations).
 */
export interface FootnoteDefinition {
  /** The label of the footnote (e.g., "1" in `[^1]: ...`). */
  readonly label: string;
  /** The full content of the footnote definition. */
  readonly content: string;
  /** Byte offset of the definition line in the markdown text. */
  readonly offset: number;
}

/**
 * Format-specific metadata (discriminated union).
 *
 * Only one format type can exist per extraction result. This provides
 * type-safe, clean metadata without nested optionals.
 */
export type FormatMetadata =
  | ({ formatType: "pdf" } & PdfMetadata)
  | ({ formatType: "docx" } & DocxMetadata)
  | ({ formatType: "excel" } & ExcelMetadata)
  | ({ formatType: "email" } & EmailMetadata)
  | ({ formatType: "pptx" } & PptxMetadata)
  | ({ formatType: "archive" } & ArchiveMetadata)
  | ({ formatType: "image" } & ImageMetadata)
  | ({ formatType: "xml" } & XmlMetadata)
  | ({ formatType: "text" } & TextMetadata)
  | ({ formatType: "html" } & HtmlMetadata)
  | ({ formatType: "ocr" } & OcrMetadata)
  | ({ formatType: "csv" } & CsvMetadata)
  | ({ formatType: "bibtex" } & BibtexMetadata)
  | ({ formatType: "citation" } & CitationMetadata)
  | ({ formatType: "fiction_book" } & FictionBookMetadata)
  | ({ formatType: "dbf" } & DbfMetadata)
  | ({ formatType: "jats" } & JatsMetadata)
  | ({ formatType: "epub" } & EpubMetadata)
  | ({ formatType: "pst" } & PstMetadata)
  | ({ formatType: "audio" } & AudioMetadata)
  | ({ formatType: "code" } & CodeMetadata);

/**
 * Block-level element in a Djot document.
 *
 * Represents structural elements like headings, paragraphs, lists, code blocks, etc.
 */
export interface FormattedBlock {
  /** Type of block element */
  readonly blockType: BlockType;
  /** Heading level (1-6) for headings, or nesting level for lists */
  readonly level?: number;
  /** Inline content within the block */
  readonly inlineContent: Array<InlineElement>;
  /** Element attributes (classes, IDs, key-value pairs) */
  readonly attributes?: Attributes;
  /** Language identifier for code blocks */
  readonly language?: string;
  /** Raw code content for code blocks */
  readonly code?: string;
  /** Nested blocks for containers (blockquotes, list items, divs) */
  readonly children: Array<FormattedBlock>;
}

/**
 * Kind of a PDF form field.
 *
 * Mirrors `xberg_native_pdf`'s widget field taxonomy without leaking the upstream
 * type across the binding surface.
 */
export declare enum FormFieldType {
  /** Single- or multi-line text input. */
  Text = "text",
  /** Checkbox (on/off toggle). */
  Checkbox = "checkbox",
  /** Radio-button group member. */
  Radio = "radio",
  /** Choice field (dropdown or list box). */
  Choice = "choice",
  /** Digital-signature field. */
  Signature = "signature",
  /** Push button. */
  Button = "button",
  /** Field type that could not be classified. */
  Unknown = "unknown",
}

/**
 * A mathematical formula extracted from a document.
 *
 * Three kinds of sources populate this type. Layout-guided OCR detects
 * formula regions and recognizes them; those formulas carry a `bbox` and a
 * `page`. VLM OCR recognizes formulas in transcribed text without layout, so
 * its formulas carry no geometry. Markup extraction (DOCX, PPTX, ODT, EPUB,
 * HTML, JATS, LaTeX, Markdown, and related formats) converts embedded math
 * to LaTeX, also without geometry.
 */
export interface Formula {
  /**
   * LaTeX source of the formula, without surrounding `$$` delimiters.
   *
   * Markup converters and formula OCR produce real LaTeX. The native PDF
   * layout path stores the plain text of a detected formula region, which
   * keeps the original Unicode math characters instead of LaTeX commands.
   * To render the formula in Markdown or other formats, wrap it in `$$..$$`.
   */
  readonly latex: string;
  /**
   * Bounding box of the formula region on its page. `None` for markup sources.
   *
   * PDF OCR sources report PDF point coordinates with the origin at the
   * bottom-left of the page, comparable to native PDF geometry. Image
   * sources, and PDF pages whose geometry is unavailable, report pixels of
   * the image the OCR backend saw. The C FFI reports an absent bbox as a
   * null pointer.
   */
  readonly bbox?: BoundingBox;
  /**
   * 1-indexed page number the formula appears on. `None` when the source
   * format has no page concept. The C FFI reports an absent page as `0`.
   */
  readonly page?: number;
}

/** Formula recognition model selection. */
export declare enum FormulaModel {
  /**
   * RapidLaTeXOCR (MIT, pix2tex-derived): resizer + encoder + decoder ONNX,
   * ~180 MB total, downloaded on demand.
   */
  LatexOcr = "latex_ocr",
}

/**
 * Configuration for GeoJSON extraction.
 *
 * GeoJSON coordinates can dominate extraction output and duplicate large geometry
 * payloads in rendered content and metadata. The default therefore emits a bounded
 * aggregate summary. Set `Self.include_full_coordinates` only when callers need
 * every coordinate in the extracted text and accept output proportional to the input.
 */
export interface GeoJsonExtractionConfig {
  /**
   * Include every coordinate in rendered content and `flattened_fields` metadata.
   *
   * Defaults to `false`. When false, extraction reports feature, property, geometry,
   * position-count, bounds, truncation, and discarded-category metadata and emits a
   * `ProcessingWarning` for every GeoJSON input.
   */
  readonly includeFullCoordinates?: boolean;
}

/** Runtime options accepted by the `candle-glm-ocr` backend. */
export interface GlmOcrBackendOptions {
  /** Optional recognition task; the backend constructor's task is used when absent. */
  readonly task?: GlmOcrTaskKind;
  /** Optional per-call device override. */
  readonly device?: CandleDevicePreference;
  /** Optional whole-page or layout-paired dispatch mode. */
  readonly layoutMode?: GlmOcrLayoutMode;
  /** Whether chart regions use chart understanding instead of captioning. */
  readonly enableChartUnderstanding?: boolean;
  /** Optional Hugging Face cache root. */
  readonly cacheDir?: string;
}

/** Page layout mode accepted by `candle-glm-ocr` backend options. */
export declare enum GlmOcrLayoutMode {
  WholePage = "whole_page",
  Paired = "paired",
}

/** Task accepted by `candle-glm-ocr` backend options. */
export declare enum GlmOcrTaskKind {
  Ocr = "ocr",
  Table = "table",
  Formula = "formula",
  Chart = "chart",
  Caption = "caption",
}

/** Individual grid cell with position and span metadata. */
export interface GridCell {
  /** Cell text content. */
  readonly content: string;
  /** Zero-indexed row position. */
  readonly row: number;
  /** Zero-indexed column position. */
  readonly col: number;
  /** Number of rows this cell spans. */
  readonly rowSpan: number;
  /** Number of columns this cell spans. */
  readonly colSpan: number;
  /** Whether this is a header cell. */
  readonly isHeader: boolean;
  /** Bounding box for this cell (if available). */
  readonly bbox?: BoundingBox;
  /**
   * Outline level (1-6) of the heading style this cell's text carries, when it has one.
   *
   * A DOCX banner row -- row 0, one cell spanning the grid, styled `Heading1`..`Heading6` --
   * is what Word's navigation pane and a `TOC` field treat as the document's outline, but as
   * a table cell it reached consumers as anonymous text (GH#1587). `content` is deliberately
   * left as the bare cell text: prefixing it with `#` would put a markdown heading inside a
   * table cell, which is invalid where it lands and changes text every existing consumer
   * already reads. This field is the signal instead, so a caller can decide for itself
   * whether a `heading 2` in a banner row is a section title or a column label.
   */
  readonly headingLevel?: number;
  /**
   * Human-readable name of the paragraph style applied to this cell's text (`heading 2`).
   *
   * Carries the style even when it resolves to no outline level, so a caller can key on a
   * named style this crate does not map to a heading. See `GridCell.heading_level`.
   */
  readonly styleName?: string;
}

/** Header/heading element metadata. */
export interface HeaderMetadata {
  /** Header level: 1 (h1) through 6 (h6) */
  readonly level: number;
  /** Normalized text content of the header */
  readonly text: string;
  /** HTML id attribute if present */
  readonly id?: string;
  /** Document tree depth at the header element */
  readonly depth: number;
  /** Byte offset in original HTML document */
  readonly htmlOffset: number;
}

/**
 * Heading context for a chunk within a Markdown document.
 *
 * Contains the heading hierarchy from document root to this chunk's section.
 */
export interface HeadingContext {
  /**
   * The heading hierarchy from document root to this chunk's section.
   * Index 0 is the outermost (h1), last element is the most specific.
   */
  readonly headings: Array<HeadingLevel>;
}

/** A single heading in the hierarchy. */
export interface HeadingLevel {
  /** Heading depth (1 = h1, 2 = h2, etc.) */
  readonly level: number;
  /** The text content of the heading. */
  readonly text: string;
}

/**
 * Heading style options for Markdown output.
 *
 * Controls how headings (h1-h6) are rendered in the output Markdown.
 */
export declare enum HeadingStyle {
  /** Underlined style (=== for h1, --- for h2). */
  Underlined = "Underlined",
  /** ATX style (# for h1, ## for h2, etc.). Default. */
  Atx = "Atx",
  /** ATX closed style (# title #, with closing hashes). */
  AtxClosed = "AtxClosed",
}

/**
 * Configuration for document chunking and analysis heuristics.
 *
 * Every threshold is a public field so callers can override any subset via
 * struct-update syntax: `HeuristicsConfig { text_layer_threshold: 0.5, ..Default.default() }`.
 */
export interface HeuristicsConfig {
  /**
   * Enable PDF text-layer detection heuristics.
   *
   * When `true`, PDFs with a substantial text layer will skip chunking.
   * Default: `true`.
   */
  readonly enablePdfTextHeuristics?: boolean;
  /**
   * Minimum fraction of pages that must have text to skip chunking.
   *
   * Range `0.0..=1.0`. Default: `0.7` (70 % of pages).
   */
  readonly textLayerThreshold?: number;
  /**
   * File size threshold in bytes for considering chunking.
   *
   * Files smaller than this are processed without chunking.
   * Default: 10 MiB (10 × 1 024 × 1 024).
   */
  readonly fileSizeThresholdBytes?: number;
  /**
   * Page count threshold for considering chunking.
   *
   * Documents with fewer pages are processed without chunking.
   * Default: 50.
   */
  readonly pageCountThreshold?: number;
  /**
   * Target number of pages per chunk for optimal parallel processing.
   *
   * Default: 10.
   */
  readonly targetPagesPerChunk?: number;
  /**
   * Hard cap on pages per chunk.
   *
   * No chunk will exceed this limit. Must be ≥ `target_pages_per_chunk`.
   * Default: 25.
   */
  readonly maxPagesPerChunk?: number;
  /**
   * File size threshold for disk-based processing.
   *
   * Files larger than this are buffered to disk to prevent OOM.
   * Default: 50 MiB (50 × 1 024 × 1 024).
   */
  readonly diskProcessingThresholdBytes?: number;
  /**
   * Minimum characters per page to consider a page as having text.
   *
   * Default: 50.
   */
  readonly minCharsPerPage?: number;
  /**
   * Maximum sheet count allowed in an XLSX workbook.
   *
   * Workbooks beyond this are rejected pre-extraction to avoid OOM /
   * abusive billing inflation. Default: 200.
   */
  readonly maxXlsxSheetCount?: number;
  /**
   * Maximum cell count (sheets × rows × columns approximation) in an XLSX workbook.
   *
   * Default: 5 000 000 (≈ 200 sheets × 25 k cells).
   */
  readonly maxXlsxWorkbookCells?: number;
  /**
   * Maximum number of OLE-embedded objects extractable from a single PPTX or DOCX.
   *
   * Protects against zip-bomb-style nested-document abuse. Default: 50.
   */
  readonly maxPptxEmbeddedCount?: number;
}

export interface HierarchicalBlock {
  /** The text content of this block */
  readonly text: string;
  /** The font size of the text in this block */
  readonly fontSize: number;
  /**
   * The hierarchy level of this block (H1-H6 or Body)
   *
   * Levels correspond to HTML heading tags:
   * - "h1": Top-level heading
   * - "h2": Secondary heading
   * - "h3": Tertiary heading
   * - "h4": Quaternary heading
   * - "h5": Quinary heading
   * - "h6": Senary heading
   * - "body": Body text (no heading level)
   */
  readonly level: string;
  /**
   * Bounding box information for the block
   *
   * Contains left, top, right, and bottom coordinates in PDF units.
   */
  readonly bbox?: HierarchicalBoundingBox;
}

/**
 * A text block with hierarchy level assignment.
 *
 * Represents a block of text with semantic heading information extracted from
 * font size clustering and hierarchical analysis.
 */
export interface HierarchicalBoundingBox {
  /** Left coordinate. */
  readonly left?: number;
  /** Top coordinate. */
  readonly top?: number;
  /** Right coordinate. */
  readonly right?: number;
  /** Bottom coordinate. */
  readonly bottom?: number;
}

/**
 * Hierarchy extraction configuration for PDF text structure analysis.
 *
 * Enables extraction of document hierarchy levels (H1-H6) based on font size
 * clustering and semantic analysis. When enabled, hierarchical blocks are
 * included in page content.
 */
export interface HierarchyConfig {
  /** Enable hierarchy extraction */
  readonly enabled?: boolean;
  /**
   * Number of font size clusters to use for hierarchy levels (1-7)
   *
   * Default: 3, which provides two heading levels plus body text.
   * Larger values create more fine-grained hierarchy levels.
   */
  readonly kClusters?: number;
  /** Include bounding box information in hierarchy blocks */
  readonly includeBbox?: boolean;
}

/**
 * Highlight rendering style for `<mark>` elements.
 *
 * Controls how highlighted text is rendered in Markdown output.
 */
export declare enum HighlightStyle {
  /** Double equals syntax (==text==). Default. Pandoc-compatible. */
  DoubleEqual = "DoubleEqual",
  /** Preserve as HTML (==text==). Original HTML tag. */
  Html = "Html",
  /** Render as bold (**text**). Uses strong emphasis. */
  Bold = "Bold",
  /** Strip formatting, render as plain text. No markup. */
  None = "None",
}

/**
 * Hostname/IP allowlist matcher for SSRF policy.
 *
 * Serializes as an internally-tagged object so each variant is distinguishable on the
 * wire and round-trips losslessly:
 *
 * ```json
 * {"type": "exact",  "value": "api.example.com"}
 * {"type": "suffix", "value": ".example.com"}
 * {"type": "cidr",   "value": "10.0.0.0/8"}
 * ```
 *
 * A bare JSON string is still accepted on deserialization and resolves to `Exact`,
 * preserving configs written against the previous untagged representation.
 *
 * `Exact`: HostMatcher.Exact
 */
export type HostMatcher =
  | { type: "exact"; value: string }
  | { type: "suffix"; value: string }
  | { type: "cidr"; value: string };

/**
 * HTML metadata extracted from HTML documents.
 *
 * Includes document-level metadata, Open Graph data, Twitter Card metadata,
 * and extracted structural elements (headers, links, images, structured data).
 */
export interface HtmlMetadata {
  /** Document title from `<title>` tag */
  readonly title?: string;
  /** Document description from `<meta name="description">` tag */
  readonly description?: string;
  /** Document keywords from `<meta name="keywords">` tag, split on commas */
  readonly keywords?: Array<string>;
  /** Document author from `<meta name="author">` tag */
  readonly author?: string;
  /** Canonical URL from `<link rel="canonical">` tag */
  readonly canonicalUrl?: string;
  /** Base URL from `<base href="">` tag for resolving relative URLs */
  readonly baseHref?: string;
  /** Document language from `lang` attribute */
  readonly language?: string;
  /** Document text direction from `dir` attribute */
  readonly textDirection?: TextDirection;
  /**
   * Open Graph metadata (og:* properties) for social media
   * Keys like "title", "description", "image", "url", etc.
   */
  readonly openGraph?: Record<string, string>;
  /**
   * Twitter Card metadata (twitter:* properties)
   * Keys like "card", "site", "creator", "title", "description", "image", etc.
   */
  readonly twitterCard?: Record<string, string>;
  /**
   * Additional meta tags not covered by specific fields
   * Keys are meta name/property attributes, values are content
   */
  readonly metaTags?: Record<string, string>;
  /** Extracted header elements with hierarchy */
  readonly headers?: Array<HeaderMetadata>;
  /** Extracted hyperlinks with type classification */
  readonly links?: Array<LinkMetadata>;
  /** Extracted images with source and dimensions */
  readonly images?: Array<ImageMetadataType>;
  /** Extracted structured data blocks */
  readonly structuredData?: Array<StructuredData>;
}

/**
 * Configuration for styled HTML output.
 *
 * When set on `html_output` alongside
 * `output_format = OutputFormat.Html`, the pipeline builds a
 * `StyledHtmlRenderer` instead of
 * the plain comrak-based renderer.
 */
export interface HtmlOutputConfig {
  /**
   * Inline CSS string injected into the output after the theme stylesheet.
   * Concatenated after `css_file` content when both are set.
   */
  readonly css?: string;
  /**
   * Path to a CSS file loaded once at renderer construction time.
   * Concatenated before `css` when both are set.
   */
  readonly cssFile?: string;
  /** Built-in colour/typography theme. Default: `HtmlTheme.Unstyled`. */
  readonly theme?: HtmlTheme;
  /**
   * CSS class prefix applied to every emitted class name.
   *
   * Default: `"kb-"`. Change this if your host application already uses
   * classes that start with `kb-`.
   */
  readonly classPrefix?: string;
  /**
   * When `true` (default), write the resolved CSS into a `<style>` block
   * immediately after the opening `<div class="{prefix}doc">`.
   *
   * Set to `false` to emit only the structural markup and wire up your
   * own stylesheet targeting the `kb-*` class names.
   */
  readonly embedCss?: boolean;
}

/** Built-in HTML theme selection. */
export declare enum HtmlTheme {
  /**
   * Sensible defaults: system font stack, neutral colours, readable line
   * measure. CSS custom properties (`--kb-*`) are all defined so user CSS
   * can override individual values.
   */
  Default = "default",
  /** GitHub Markdown-inspired palette and spacing. */
  GitHub = "github",
  /** Dark background, light text. */
  Dark = "dark",
  /** Minimal light theme with generous whitespace. */
  Light = "light",
  /**
   * No built-in stylesheet emitted. CSS custom properties are still defined
   * on `:root` so user stylesheets can reference `var(--kb-*)` tokens.
   */
  Unstyled = "unstyled",
}

/**
 * Output format for conversion.
 *
 * Specifies the target markup language format for the conversion output.
 */
export declare enum HtmlToMarkdownRsOutputFormat {
  /** Standard Markdown (`CommonMark` compatible). Default. */
  Markdown = "Markdown",
  /** Djot lightweight markup language. */
  Djot = "Djot",
  /** Plain text output (no markup, visible text only). */
  Plain = "Plain",
}

/** Image dimensions in pixels. */
export interface ImageDimensions {
  /** Width in pixels. */
  readonly width?: number;
  /** Height in pixels. */
  readonly height?: number;
}

/** Horizontal and vertical image resolution in dots per inch. */
export interface ImageDpi {
  /** Horizontal resolution. */
  readonly horizontal?: number;
  /** Vertical resolution. */
  readonly vertical?: number;
}

/** Image extraction configuration. */
export interface ImageExtractionConfig {
  /** Extract images from documents */
  readonly extractImages?: boolean;
  /** Target DPI for image normalization */
  readonly targetDpi?: number;
  /** Maximum dimension for images (width or height) */
  readonly maxImageDimension?: number;
  /**
   * Whether to inject image reference placeholders into markdown output.
   * When `true` (default), image references like `![Image 1](embedded:p1_i0)`
   * are appended to the markdown. Set to `false` to extract images as data
   * without polluting the markdown output.
   */
  readonly injectPlaceholders?: boolean;
  /** Automatically adjust DPI based on image content */
  readonly autoAdjustDpi?: boolean;
  /** Minimum DPI threshold */
  readonly minDpi?: number;
  /** Maximum DPI threshold */
  readonly maxDpi?: number;
  /**
   * Maximum number of image objects to extract per PDF page.
   *
   * Some PDFs (e.g. technical diagrams stored as thousands of raster fragments)
   * can trigger extremely long or indefinite extraction times when every image
   * object on a dense page is decoded individually via the PDF extractor. Setting this
   * limit causes xberg to stop collecting individual images once the count
   * per page reaches the cap and emit a warning instead.
   *
   * `None` (default) means no limit — all images are extracted.
   */
  readonly maxImagesPerPage?: number;
  /**
   * When `true`, extracted images are classified by kind and grouped
   * into clusters where they appear to belong to one figure.
   * Defaults to `false` — opt in explicitly to avoid unexpected ML overhead.
   */
  readonly classify?: boolean;
  /**
   * When `true`, full-page renders produced during OCR preprocessing are captured
   * and returned as `ImageKind.PageRaster` entries in `ExtractedDocument.images`.
   *
   * **PDF + OCR only.** No rasters are captured for non-PDF inputs or when the
   * document-level OCR bypass is active (whole-document backend). When OCR is
   * enabled and this flag is set but the active backend skips per-page rendering,
   * a `ProcessingWarning` is emitted in `ExtractedDocument.processing_warnings`.
   *
   * Defaults to `false`. Enable when downstream consumers need page thumbnails
   * (e.g. citation previews, visual grounding).
   */
  readonly includePageRasters?: boolean;
  /**
   * Run OCR on extracted images and include the recognized text in the document content.
   *
   * When `true` (default) and `ExtractionConfig.ocr` is configured, extracted images
   * are processed with the configured OCR backend. Set to `false` to extract images
   * without OCR processing, even when OCR is enabled.
   */
  readonly runOcrOnImages?: boolean;
  /**
   * When `true`, image OCR results are rendered as plain text without the
   * `![...](...)` markdown placeholder. Only takes effect when `run_ocr_on_images`
   * is also `true`.
   */
  readonly ocrTextOnly?: boolean;
  /**
   * When `true` and `ocr_text_only` is `false`, append the OCR text after
   * the image placeholder in the rendered output.
   */
  readonly appendOcrText?: boolean;
  /**
   * Target format for re-encoding extracted images.
   *
   * When set to anything other than `Native`, each extracted image is
   * re-encoded to the requested format before being returned. This lets
   * callers receive uniform output without duplicating encode logic
   * downstream.
   *
   * Defaults to `Native` — no re-encode pass is performed and
   * `ExtractedImage.format` reflects the source extractor's output.
   */
  readonly outputFormat?: ImageOutputFormat;
  /**
   * SVG-specific knobs for the image-encode pipeline.
   *
   * Controls sanitization and rasterization DPI when the source or output
   * format is SVG.  Only available when the `svg` feature is active.
   */
  readonly svg?: SvgOptions;
  /**
   * When `true`, populate `ExtractedImage.data_base64` with a Base64-encoded
   * copy of the raw image bytes.
   *
   * Useful for JSON-only clients that cannot efficiently parse the default
   * integer-array serialization of `data`. Defaults to `false`; enabling it
   * doubles the in-memory image representation for the duration of the response.
   */
  readonly includeDataBase64?: boolean;
}

/** Heuristic classification of what an image likely depicts. */
export declare enum ImageKind {
  /** Photographic image (natural scene, photograph) */
  Photograph = "photograph",
  /** Technical or schematic diagram */
  Diagram = "diagram",
  /** Chart, graph, or plot */
  Chart = "chart",
  /** Freehand or technical drawing */
  Drawing = "drawing",
  /** Text-heavy image (scanned text, document) */
  TextBlock = "text_block",
  /** Decorative element or border */
  Decoration = "decoration",
  /** Logo or brand mark */
  Logo = "logo",
  /** Small icon */
  Icon = "icon",
  /** Fragment of a larger tiled image (tile of a technical drawing) */
  TileFragment = "tile_fragment",
  /** Mask or transparency map */
  Mask = "mask",
  /** Full-page render produced during OCR preprocessing; used as a citation thumbnail. */
  PageRaster = "page_raster",
  /** Could not classify with reasonable confidence */
  Unknown = "unknown",
}

/**
 * Image metadata extracted from image files.
 *
 * Includes dimensions, format, and EXIF data.
 */
export interface ImageMetadata {
  /** Image width in pixels */
  readonly width?: number;
  /** Image height in pixels */
  readonly height?: number;
  /** Image format (e.g., "PNG", "JPEG", "TIFF") */
  readonly format?: string;
  /** EXIF metadata tags */
  readonly exif?: Record<string, string>;
}

/** Image element metadata. */
export interface ImageMetadataType {
  /** Image source (URL, data URI, or SVG content) */
  readonly src: string;
  /** Alternative text from alt attribute */
  readonly alt?: string;
  /** Title attribute */
  readonly title?: string;
  /** Image dimensions if available. */
  readonly dimensions?: ImageDimensions;
  /** Image type classification */
  readonly imageType: ImageType;
  /** Additional attributes as key-value pairs. */
  readonly attributes: Array<KeyValueAttribute>;
}

/**
 * Target format for re-encoding extracted images.
 *
 * Controls whether and how extracted images are normalised to a uniform
 * container format before being returned in `ExtractedDocument.images`.
 * The default (`Native`) preserves the format produced by each extractor
 * without any additional encode pass.
 *
 * Callers that need uniform output — e.g. cloud pipelines that always store
 * WebP thumbnails — set this once on `ImageExtractionConfig.output_format`
 * rather than re-encoding downstream.
 *
 * # Serde shape
 *
 * Uses a tagged enum: `{"type": "native"}`, `{"type": "png"}`,
 * `{"type": "jpeg", "quality": 90}`, etc.
 */
export type ImageOutputFormat =
  | { type: "native" }
  | { type: "png" }
  | { type: "jpeg"; quality: number }
  | { type: "webp"; quality: number }
  | { type: "heif"; quality: number }
  | { type: "svg" };

/**
 * Image preprocessing configuration for OCR.
 *
 * These settings control how images are preprocessed before OCR to improve
 * text recognition quality. Different preprocessing strategies work better
 * for different document types.
 */
export interface ImagePreprocessingConfig {
  /** Target DPI for the image (300 is standard, 600 for small text). */
  readonly targetDpi?: number;
  /** Auto-detect and correct image rotation. */
  readonly autoRotate?: boolean;
  /** Correct skew (tilted images). Must be `false` with `none` or `off` binarization. */
  readonly deskew?: boolean;
  /** Remove noise from the image. */
  readonly denoise?: boolean;
  /**
   * Enhance contrast for better text visibility. With `none` or `off` binarization, this
   * applies background normalization and sharpening while preserving grayscale pixels.
   */
  readonly contrastEnhance?: boolean;
  /**
   * Binarization method: "none" (alias "off"), "otsu", "sauvola", or "adaptive".
   * `deskew` must be `false` when this is `none` or `off`.
   */
  readonly binarizationMethod?: string;
  /** Invert colors (white text on black → black on white). */
  readonly invertColors?: boolean;
}

export interface ImagePreprocessingMetadata {
  /** Original image dimensions in pixels. */
  readonly originalDimensions: PixelDimensions;
  /** Original image resolution. */
  readonly originalDpi: ImageDpi;
  /** Target DPI from configuration */
  readonly targetDpi: number;
  /** Scaling factor applied to the image */
  readonly scaleFactor: number;
  /** Whether DPI was auto-adjusted based on content */
  readonly autoAdjusted: boolean;
  /** Final DPI after processing */
  readonly finalDpi: number;
  /** New dimensions after resizing (if resized). */
  readonly newDimensions?: PixelDimensions;
  /** Resampling algorithm used ("LANCZOS3", "CATMULLROM", etc.) */
  readonly resampleMethod: string;
  /** Whether dimensions were clamped to max_image_dimension */
  readonly dimensionClamped: boolean;
  /** Calculated optimal DPI (if auto_adjust_dpi enabled) */
  readonly calculatedDpi?: number;
  /** Whether resize was skipped (dimensions already optimal) */
  readonly skippedResize: boolean;
  /** Error message if resize failed */
  readonly resizeError?: string;
}

/** Image type classification. */
export declare enum ImageType {
  /** Data URI image */
  DataUri = "data-uri",
  /** Inline SVG */
  InlineSvg = "inline-svg",
  /** External image URL */
  External = "external",
  /** Relative path image */
  Relative = "relative",
}

/**
 * Inline element within a block.
 *
 * Represents text with formatting, links, images, etc.
 */
export interface InlineElement {
  /** Type of inline element */
  readonly elementType: InlineType;
  /** Text content */
  readonly content: string;
  /** Element attributes */
  readonly attributes?: Attributes;
  /** Additional metadata (e.g., href for links, src/alt for images) */
  readonly metadata?: Record<string, string>;
}

/** Types of inline elements in Djot. */
export declare enum InlineType {
  /** Plain text run. */
  Text = "text",
  /** Bold / strong emphasis. */
  Strong = "strong",
  /** Italic / regular emphasis. */
  Emphasis = "emphasis",
  /** Highlighted text (marker pen). */
  Highlight = "highlight",
  /** Subscript text. */
  Subscript = "subscript",
  /** Superscript text. */
  Superscript = "superscript",
  /** Inserted text (tracked change). */
  Insert = "insert",
  /** Deleted text (tracked change). */
  Delete = "delete",
  /** Inline code span. */
  Code = "code",
  /** Hyperlink with URL. */
  Link = "link",
  /** Inline image reference. */
  Image = "image",
  /** Generic inline span with optional attributes. */
  Span = "span",
  /** Inline mathematical expression. */
  Math = "math",
  /** Raw inline content in a specified format. */
  RawInline = "raw_inline",
  /** Footnote reference marker. */
  FootnoteRef = "footnote_ref",
  /** Named symbol or emoji shortcode. */
  Symbol = "symbol",
}

/** JATS (Journal Article Tag Suite) metadata. */
export interface JatsMetadata {
  /** Copyright statement from the article's `<permissions>` element. */
  readonly copyright?: string;
  /** Open-access license URI from the article's `<license>` element. */
  readonly license?: string;
  /** Publication history dates keyed by event type (e.g. `"received"`, `"accepted"`). */
  readonly historyDates?: Record<string, string>;
  /** Authors and contributors with their stated roles. */
  readonly contributorRoles?: Array<ContributorRole>;
}

/**
 * Controls how Jupyter notebook code cells are rendered during extraction.
 *
 * A code cell carries both its **source** and any **outputs** that were saved in
 * the notebook. Callers ingesting notebooks for AI agents want different slices of
 * this depending on the task. Xberg never executes cells — `Outputs` and `Both`
 * only surface outputs already stored in the `.ipynb`.
 *
 * This toggle governs a code cell's **source body** and its **saved outputs**.
 * Markdown (prose) cells and structural markers (kernel language, cell id, tags,
 * execution count) are unaffected — prose always renders and markers orient the
 * reader regardless of mode.
 */
export declare enum JupyterCellRendering {
  /** Render the code source as a fenced code block; omit saved outputs. */
  Source = "source",
  /** Omit the code source; render only the saved cell outputs. */
  Outputs = "outputs",
  /**
   * Render both the code source and the saved outputs (default; preserves the
   * historical behavior).
   */
  Both = "both",
}

/** A string key-value attribute. */
export interface KeyValueAttribute {
  /** Attribute name. */
  readonly key?: string;
  /** Attribute value. */
  readonly value?: string;
}

/** Extracted keyword with metadata. */
export interface Keyword {
  /** The keyword text. */
  readonly text: string;
  /** Relevance score (higher is better, algorithm-specific range). */
  readonly score: number;
  /** Algorithm that extracted this keyword. */
  readonly algorithm: KeywordAlgorithm;
  /** Optional positions where keyword appears in text (character offsets). */
  readonly positions?: Array<number>;
}

/** Keyword algorithm selection. */
export declare enum KeywordAlgorithm {
  /** YAKE (Yet Another Keyword Extractor) - statistical approach */
  Yake = "yake",
  /** RAKE (Rapid Automatic Keyword Extraction) - co-occurrence based */
  Rake = "rake",
}

/** Keyword extraction configuration. */
export interface KeywordConfig {
  /** Algorithm to use for extraction. */
  readonly algorithm?: KeywordAlgorithm;
  /** Maximum number of keywords to extract (default: 10). */
  readonly maxKeywords?: number;
  /**
   * Minimum score threshold (0.0-1.0, default: 0.0).
   *
   * Keywords with scores below this threshold are filtered out.
   * Note: Score ranges differ between algorithms.
   */
  readonly minScore?: number;
  /**
   * N-gram range for keyword extraction (min, max).
   *
   * (1, 1) = unigrams only
   * (1, 2) = unigrams and bigrams
   * (1, 3) = unigrams, bigrams, and trigrams (default)
   */
  readonly ngramRange?: NgramRange;
  /**
   * Language code for stopword filtering (e.g., "en", "de", "fr").
   *
   * If undefined, no stopword filtering is applied.
   */
  readonly language?: string;
  /** YAKE-specific tuning parameters. */
  readonly yakeParams?: YakeParams;
  /** RAKE-specific tuning parameters. */
  readonly rakeParams?: RakeParams;
}

/**
 * Structured per-language detection result: confidence, document share, and script —
 * the information the ISO-code-only `detected_languages` list cannot convey (#261).
 *
 * Populated by the language-detection processor alongside `detected_languages`, with one
 * entry per language, in the same order as `detected_languages`.
 */
export interface LanguageConfidence {
  /** ISO 639-3 language code, matching the corresponding entry in `detected_languages`. */
  readonly language: string;
  /**
   * Confidence for this language, in `[0.0, 1.0]`.
   *
   * In single-language mode this is whatlang's `Info.confidence()` for the whole
   * document. In multi-language mode this is the average whatlang confidence across
   * the document's 200-character chunks that were classified as this language.
   */
  readonly confidence: number;
  /**
   * Share of the document's analyzed content classified as this language, in `[0.0, 1.0]`.
   *
   * In single-language mode this is always `1.0`. In multi-language mode this is the
   * fraction of 200-character chunks classified as this language (chunks that did not
   * meet `min_confidence` for any language are excluded from the count but still count
   * toward the denominator).
   */
  readonly proportion: number;
  /** Writing system whatlang detected for this language (e.g. `"Latin"`, `"Cyrillic"`). */
  readonly script: string;
  /**
   * Whether this detection is considered reliable.
   *
   * In single-language mode this is whatlang's own `Info.is_reliable()` (confidence
   * above whatlang's internal 0.9 threshold). In multi-language mode this is the
   * chunk-averaged `confidence` above that same 0.9 threshold, since whatlang's
   * `is_reliable()` only applies to a single detection.
   */
  readonly reliable: boolean;
}

/** Language detection configuration. */
export interface LanguageDetectionConfig {
  /** Enable language detection */
  readonly enabled?: boolean;
  /** Minimum confidence threshold (0.0-1.0) */
  readonly minConfidence?: number;
  /** Detect multiple languages in the document */
  readonly detectMultiple?: boolean;
}

/**
 * Configuration for the late-interaction (ColBERT) pipeline.
 *
 * Controls which model to use, batching, and download/cache behavior for the
 * local ONNX ColBERT model.
 */
export interface LateInteractionConfig {
  /** The late-interaction model to use (defaults to the "gte-moderncolbert" preset). */
  readonly model?: LateInteractionModelType;
  /**
   * Batch size for local ONNX inference.
   *
   * ColBERT emits a `[seq, dim]` multi-vector embedding per document, so
   * memory scales with batch size — keep this modest.
   */
  readonly batchSize?: number;
  /** Maximum token sequence length for the tokenizer (documents). */
  readonly maxLength?: number;
  /**
   * Fixed padded length for query augmentation.
   *
   * ColBERT queries are padded (with the mask token, kept attention-live)
   * to exactly this many tokens rather than truncated/left as-is — this is
   * the "query augmentation" trick from the ColBERT paper.
   */
  readonly queryMaxLength?: number;
  /**
   * Show model download progress (local ONNX path only).
   *
   * When enabled, transfer progress for the model, tokenizer and config files is reported at
   * `info` level on the `xberg.model_download` target while they download (#279). A warm
   * Hugging Face cache transfers nothing and so reports nothing. Ignored by
   * `LateInteractionModelType.Plugin`, which downloads no model.
   */
  readonly showDownloadProgress?: boolean;
  /**
   * Optional alternate Hugging Face cache root for model files.
   *
   * When unset, hf-hub follows the standard Hugging Face environment and
   * platform cache conventions.
   */
  readonly cacheDir?: string;
  /** Hardware acceleration for the late-interaction ONNX model. */
  readonly acceleration?: AccelerationConfig;
  /**
   * Maximum wall-clock duration (in seconds) for a single embed call when
   * using `LateInteractionModelType.Plugin`. `None` disables the timeout.
   */
  readonly maxEmbedDurationSecs?: number;
}

/**
 * A single document match returned by `max_sim_rank`, with its position in
 * the input and MaxSim score.
 */
export interface LateInteractionMatch {
  /** Position of this document in the original input slice. */
  readonly index: number;
  /** MaxSim relevance score. Higher means more relevant to the query. */
  readonly score: number;
}

/** Late-interaction model types supported by Xberg. */
export type LateInteractionModelType =
  | { type: "preset"; name: string }
  | { type: "custom"; modelId: string; modelFile: string; additionalFiles: Array<string>; maxLength: number }
  | { type: "plugin"; name: string };

/** Static metadata for a bundled ColBERT preset (WASM/Android-safe, no ORT). */
export interface LateInteractionPreset {
  /** Stable preset name referenced from config. */
  readonly name: string;
  /** HuggingFace repository hosting the ONNX model. */
  readonly modelRepo: string;
  /** Path to the ONNX file within the repo. */
  readonly modelFile: string;
  /** Sibling files that must be downloaded alongside `model_file`. */
  readonly additionalFiles: Array<string>;
  /** Maximum document token sequence length. */
  readonly maxLength: number;
  /** Fixed padded query length (ColBERT query augmentation). */
  readonly queryMaxLength: number;
  /** Per-token embedding dimensionality. */
  readonly dim: number;
  /** Human-readable description. */
  readonly description: string;
}

/**
 * The 18 canonical document layout classes.
 *
 * All model backends (RT-DETR, YOLO, etc.) map their native class IDs
 * to this shared set. Models with fewer classes (DocLayNet: 11, PubLayNet: 5)
 * map to the closest equivalent.
 *
 * Wire format is snake_case in all serializers (JSON, TOML, YAML).
 */
export declare enum LayoutClass {
  /** Figure or table caption text. */
  Caption = "caption",
  /** Chart or graph visualization. */
  Chart = "chart",
  /** Footnote or endnote text. */
  Footnote = "footnote",
  /** Mathematical formula or equation. */
  Formula = "formula",
  /** A single item in a bulleted or numbered list. */
  ListItem = "list_item",
  /** Running footer at the bottom of a page. */
  PageFooter = "page_footer",
  /** Running header at the top of a page. */
  PageHeader = "page_header",
  /** Image, chart, or other graphical element. */
  Picture = "picture",
  /** Section heading. */
  SectionHeader = "section_header",
  /** Data table. */
  Table = "table",
  /** Body text paragraph. */
  Text = "text",
  /** Document or chapter title. */
  Title = "title",
  /** Table of contents or index. */
  DocumentIndex = "document_index",
  /** Source code block. */
  Code = "code",
  /** Checkbox in selected state. */
  CheckboxSelected = "checkbox_selected",
  /** Checkbox in unselected state. */
  CheckboxUnselected = "checkbox_unselected",
  /** Form field or form element. */
  Form = "form",
  /** Key-value pair region (e.g. label + value in a form). */
  KeyValueRegion = "key_value_region",
}

/** A single layout detection result. */
export interface LayoutDetection {
  /** Detected layout class (e.g. `Table`, `Text`, `Title`). */
  readonly className: LayoutClass;
  /** Detection confidence score in `[0.0, 1.0]`. */
  readonly confidence: number;
  /** Bounding box in image pixel coordinates. */
  readonly bbox: BBox;
}

/**
 * Layout detection configuration.
 *
 * Controls layout detection behavior in the extraction pipeline.
 * When set on `ExtractionConfig`, layout detection
 * is enabled for PDF extraction.
 */
export interface LayoutDetectionConfig {
  /**
   * Which pages the layout model runs on.
   *
   * Defaults to `LayoutStrategy.Always`, the historical behavior:
   * every page is rendered and inferred. `LayoutStrategy.Auto`
   * pre-screens pages with cheap signals and skips the model where it
   * cannot help.
   */
  readonly strategy?: LayoutStrategy;
  /** Confidence threshold override (undefined = use model default). */
  readonly confidenceThreshold?: number;
  /** Whether to apply postprocessing heuristics (default: true). */
  readonly applyHeuristics?: boolean;
  /**
   * Table structure recognition model.
   *
   * Controls which model is used for table cell detection within layout-detected
   * table regions. Defaults to `TableModel.Tatr`.
   */
  readonly tableModel?: TableModel;
  /**
   * Formula recognition model for layout-detected formula regions.
   *
   * `None` (the default) keeps the plain OCR text of the region. Setting a
   * model converts each formula region crop to LaTeX. Requires the
   * `formula-recognition` feature; without it the setting is ignored.
   */
  readonly formulaModel?: FormulaModel;
  /**
   * How to resolve overlapping native vs layout tables.
   *
   * When a native table and a layout (TATR/SLANeXT) table overlap on the
   * same region, this controls which one is kept. Defaults to
   * `TableOverlapPreference.Content` (historical behavior: keep the table with
   * more content). Set to `TableOverlapPreference.Native` to favor source
   * reading order (higher text F1) over the model's cell reflow.
   */
  readonly tableOverlapPreference?: TableOverlapPreference;
  /**
   * Hardware acceleration for ONNX models (layout detection + table structure).
   *
   * When set, controls which execution provider (CPU, CUDA, CoreML, TensorRT)
   * is used for inference. Defaults to `None` (auto-select per platform).
   */
  readonly acceleration?: AccelerationConfig;
  /**
   * Route regions classified as charts to the chart-understanding OCR task.
   *
   * When `true`, layout regions detected as charts are sent to the VLM
   * chart task (data-series/axis recovery) instead of being treated as
   * generic image regions. Defaults to `false` — chart understanding is
   * opt-in and has no effect on standard text/table extraction scores.
   */
  readonly enableChartUnderstanding?: boolean;
}

/**
 * A detected layout region on a page.
 *
 * When layout detection is enabled, each page may have layout regions
 * identifying different content types (text, pictures, tables, etc.)
 * with confidence scores and spatial positions.
 */
export interface LayoutRegion {
  /** Layout class name (e.g. "picture", "table", "text", "section_header"). */
  readonly className?: string;
  /** Confidence score from the layout detection model (0.0 to 1.0). */
  readonly confidence?: number;
  /** Bounding box in document coordinate space. */
  readonly boundingBox?: BoundingBox;
  /** Fraction of the page area covered by this region (0.0 to 1.0). */
  readonly areaFraction?: number;
}

/**
 * Which PDF pages the layout model runs on.
 *
 * Layout detection renders each selected page to a raster and runs ONNX
 * inference on it, which dominates extraction cost. This controls page
 * selection; `LayoutStrategy.Always` preserves the historical behavior of
 * running on every page. Wire format is snake_case in all serializers
 * (JSON, TOML, YAML).
 */
export declare enum LayoutStrategy {
  /** Run layout detection unconditionally on every page. */
  Always = "always",
  /**
   * Pre-screen each page with cheap geometry signals and run the model
   * only on pages likely to benefit (multi-column, table-bearing,
   * figure-heavy, form-like, or rotated pages).
   *
   * Pages the pre-screen skips are processed exactly like pages where the
   * model ran and found no regions. On the OCR path only inference is
   * skipped; page rasters are still produced because OCR consumes them.
   * For non-PDF inputs `Auto` behaves as `LayoutStrategy.Always`.
   */
  Auto = "auto",
}

/** Link element metadata. */
export interface LinkMetadata {
  /** The href URL value */
  readonly href: string;
  /** Link text content (normalized) */
  readonly text: string;
  /** Optional title attribute */
  readonly title?: string;
  /** Link type classification */
  readonly linkType: LinkType;
  /** Rel attribute values */
  readonly rel: Array<string>;
  /** Additional attributes as key-value pairs. */
  readonly attributes: Array<KeyValueAttribute>;
}

/**
 * Link rendering style in Markdown output.
 *
 * Controls whether links and images use inline `[text](url)` syntax or
 * reference-style `[text][1]` syntax with definitions collected at the end.
 */
export declare enum LinkStyle {
  /** Inline links: `[text](url)`. Default. */
  Inline = "Inline",
  /** Reference-style links: `[text][1]` with `[1]: url` at end of document. */
  Reference = "Reference",
}

/** Link type classification. */
export declare enum LinkType {
  /** Anchor link (#section) */
  Anchor = "anchor",
  /** Internal link (same domain) */
  Internal = "internal",
  /** External link (different domain) */
  External = "external",
  /** Email link (mailto:) */
  Email = "email",
  /** Phone link (tel:) */
  Phone = "phone",
  /** Other link type */
  Other = "other",
}

/**
 * List indentation character type.
 *
 * Controls whether list items are indented with spaces or tabs.
 */
export declare enum ListIndentType {
  /** Use spaces for indentation. Default. Width controlled by `list_indent_width`. */
  Spaces = "Spaces",
  /** Use tabs for indentation. */
  Tabs = "Tabs",
}

/** Type of list detection. */
export declare enum ListType {
  /** Bullet points (-, *, •, etc.) */
  Bullet = "Bullet",
  /** Numbered lists (1., 2., etc.) */
  Numbered = "Numbered",
  /** Lettered lists (a., b., A., B., etc.) */
  Lettered = "Lettered",
  /** Indented items */
  Indented = "Indented",
}

/**
 * Budget enforcement configuration.
 *
 * Mirrors liter-llm's `LlmBudgetConfig`. Only takes effect when liter-llm's `tower`
 * feature is compiled in; otherwise the value round-trips through configuration
 * but is not enforced at request time.
 */
export interface LlmBudgetConfig {
  /** Global spend limit in USD. */
  readonly globalLimit?: number;
  /** Per-model spend limits in USD, keyed by model name. */
  readonly modelLimits?: Record<string, number>;
  /** Enforcement mode: `"hard"` (reject over-budget requests) or `"soft"` (log only). */
  readonly enforcement?: string;
}

/**
 * Response cache configuration.
 *
 * Mirrors liter-llm's `LlmCacheConfig`. Only takes effect when liter-llm's `tower`
 * feature is compiled in; otherwise the value round-trips through configuration
 * but is not consulted at request time.
 */
export interface LlmCacheConfig {
  /** Maximum number of cached entries. */
  readonly maxEntries?: number;
  /** Cache entry time-to-live, in seconds. */
  readonly ttlSeconds?: number;
  /** Cache backend name (e.g. `"memory"`, or an `opendal` scheme). */
  readonly backend?: string;
  /** Backend-specific configuration key/value pairs. */
  readonly backendConfig?: Record<string, string>;
}

/**
 * Configuration for an LLM provider/model via liter-llm.
 *
 * Each feature (VLM OCR, VLM embeddings, structured extraction) carries
 * its own `LlmConfig`, allowing different providers per feature.
 * @example
 * ```typescript
 * [structured_extraction.llm]
 * model = "openai/gpt-4o"
 * api_key = "sk-..."  # or use XBERG_LLM_API_KEY env var
 * ```
 *
 * `Debug` is implemented by hand so `api_key`, header values, and the AWS
 * credentials in `BedrockConfig` are never printed.
 */
export interface LlmConfig {
  /**
   * Provider/model string using liter-llm routing format.
   *
   * Examples: `"openai/gpt-4o"`, `"anthropic/claude-sonnet-4-20250514"`,
   * `"groq/llama-3.1-70b-versatile"`.
   */
  readonly model?: string;
  /**
   * API key for the provider. When `None`, liter-llm falls back to
   * the provider's standard environment variable (e.g., `OPENAI_API_KEY`).
   */
  readonly apiKey?: string;
  /** Custom base URL override for the provider endpoint. */
  readonly baseUrl?: string;
  /**
   * Request timeout in seconds. When `None`, liter-llm's built-in 60s default
   * applies, except the VLM OCR path which uses a 300s default (a single page
   * image transcription routinely exceeds 60s). Set explicitly to override.
   */
  readonly timeoutSecs?: number;
  /** Maximum retry attempts (default: 3). */
  readonly maxRetries?: number;
  /** Sampling temperature for generation tasks. */
  readonly temperature?: number;
  /** Maximum tokens to generate. */
  readonly maxTokens?: number;
  /**
   * Nucleus sampling parameter for generation tasks, applied to individual
   * requests built from this config. Restricts sampling to the smallest set of
   * tokens whose cumulative probability mass is at least this value; lower is
   * more focused. Validated to `[0.0, 1.0]` by `LlmConfig.validate`.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.top_p`. A request-time
   * parameter like `temperature`/`max_tokens` above, not a client-level
   * setting.
   */
  readonly topP?: number;
  /**
   * Stop sequence(s) that halt token generation, applied to individual requests
   * built from this config.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.stop`
   * (`types.common.StopSequence`), which liter-llm represents as either a
   * single string or a list of strings via an untagged enum. Always expressed
   * here as a list — even one stop sequence is `["..."]` — so the field has a
   * single, FFI-friendly shape across every language binding instead of a
   * single-or-list union type. Converted to liter-llm's
   * `StopSequence.Multiple` at each request-building call site; see
   * `llm.client.to_stop_sequence`.
   */
  readonly stop?: Array<string>;
  /**
   * Random seed for reproducible outputs, applied to individual requests built
   * from this config. Provider support varies — some silently ignore it.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.seed`.
   */
  readonly seed?: number;
  /**
   * Presence penalty for generation tasks, applied to individual requests
   * built from this config. Positive values discourage the model from
   * repeating topics already present in the conversation. Validated to
   * `[-2.0, 2.0]` by `LlmConfig.validate`.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.presence_penalty`.
   */
  readonly presencePenalty?: number;
  /**
   * Frequency penalty for generation tasks, applied to individual requests
   * built from this config. Positive values discourage the model from
   * repeating the same tokens verbatim. Validated to `[-2.0, 2.0]` by
   * `LlmConfig.validate`.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.frequency_penalty`.
   */
  readonly frequencyPenalty?: number;
  /**
   * Reasoning effort level for extended-thinking models, applied to individual
   * requests built from this config.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.reasoning_effort`
   * (`types.chat.ReasoningEffort`). A request-time parameter like `temperature`/
   * `max_tokens` above, not a client-level setting — `into_client_builder` does not
   * map it. Accepted as a plain string — one of `"low"`, `"medium"`, `"high"`,
   * `"minimal"`, `"max"` (case-insensitive; liter-llm's own
   * `#[serde(rename_all = "lowercase")]` spelling) — rather than importing
   * liter-llm's enum, because this module compiles even when the `liter-llm`
   * feature is disabled. See `llm.client.parse_reasoning_effort` for the
   * conversion into `liter_llm.ReasoningEffort`.
   */
  readonly reasoningEffort?: string;
  /**
   * Provider-specific extra parameters merged into the request body (guardrails,
   * safety settings, grounding config, etc.), applied to individual requests built
   * from this config.
   *
   * Mirrors liter-llm's `ChatCompletionRequest.extra_body`. A request-time
   * parameter like `temperature`/`max_tokens` above, not a client-level setting.
   */
  readonly extraBody?: JsonValue;
  /**
   * Whether liter-llm should load provider credentials from environment variables.
   *
   * Mirrors liter-llm's `ClientConfigBuilder.load_env`. When `None`, liter-llm's
   * own default behavior applies.
   */
  readonly loadEnv?: boolean;
  /**
   * Extra HTTP headers sent with every request to the provider.
   *
   * Mirrors liter-llm's `ClientConfigBuilder.header`, for gateways or providers
   * that require custom auth/routing headers.
   */
  readonly headers?: Record<string, string>;
  /**
   * Custom provider configurations, in addition to liter-llm's built-in providers.
   *
   * Mirrors liter-llm's `LlmConfig.providers`, for OpenAI-compatible gateways
   * and self-hosted model servers that are not in the built-in provider catalog.
   */
  readonly providers?: Array<LlmProviderConfig>;
  /**
   * Response cache configuration.
   *
   * Mirrors liter-llm's `LlmConfig.cache`. Only takes effect when liter-llm's
   * `tower` feature is compiled in; otherwise the value is accepted but unused.
   *
   * Boxed for the same reason as `bedrock` (a4579589ac): `LlmConfig` is the payload
   * of `EmbeddingModelType.Llm` and `RerankerModelType.Llm`, whose other variants
   * are tens of bytes. Inlining this and the two sub-configs below pushed that
   * variant to 480 bytes and tripped `clippy.large_enum_variant` on the
   * `--features full` leg.
   */
  readonly cache?: LlmCacheConfig;
  /**
   * Budget enforcement configuration.
   *
   * Mirrors liter-llm's `LlmConfig.budget`. Only takes effect when liter-llm's
   * `tower` feature is compiled in; otherwise the value is accepted but unused.
   */
  readonly budget?: LlmBudgetConfig;
  /**
   * Per-model rate limiting configuration.
   *
   * Mirrors liter-llm's `LlmConfig.rate_limit`. Only takes effect when liter-llm's
   * `tower` feature is compiled in; otherwise the value is accepted but unused.
   */
  readonly rateLimit?: LlmRateLimitConfig;
  /**
   * Enable per-request cost tracking.
   *
   * Mirrors liter-llm's `LlmConfig.cost_tracking`. Only takes effect when
   * liter-llm's `tower` feature is compiled in; otherwise the value is accepted
   * but unused.
   */
  readonly costTracking?: boolean;
  /**
   * Enable OpenTelemetry-compatible tracing spans.
   *
   * Mirrors liter-llm's `LlmConfig.tracing`. Only takes effect when liter-llm's
   * `tower` feature is compiled in; otherwise the value is accepted but unused.
   */
  readonly tracing?: boolean;
  /**
   * Cooldown duration after transient errors, in seconds.
   *
   * Mirrors liter-llm's `LlmConfig.cooldown_secs`. Only takes effect when
   * liter-llm's `tower` feature is compiled in; otherwise the value is accepted
   * but unused.
   */
  readonly cooldownSecs?: number;
  /**
   * Background health check interval, in seconds.
   *
   * Mirrors liter-llm's `LlmConfig.health_check_secs`. Only takes effect when
   * liter-llm's `tower` feature is compiled in; otherwise the value is accepted
   * but unused.
   */
  readonly healthCheckSecs?: number;
  /**
   * AWS Bedrock settings (region, cross-region routing, explicit credentials).
   *
   * Only consulted for `bedrock/`-prefixed models. When `None` — or when an
   * individual field inside it is `None` — liter-llm falls back to the standard
   * AWS environment variables and the default credential chain.
   */
  readonly bedrock?: BedrockConfig;
  /**
   * Managed OAuth2/STS credential provider for auth modes liter-llm cannot express via a
   * static `api_key` — Azure AD, Vertex AI OAuth2, Vertex AI Application Default
   * Credentials, and AWS STS Web Identity (EKS IRSA) for Bedrock.
   *
   * Mirrors liter-llm's `client.ClientConfigBuilder.credential_provider`, which takes an
   * `Arc<dyn liter_llm.auth.CredentialProvider>` trait object — that cannot appear in a
   * serde DTO. Every `CredentialProviderConfig` variant is plain data instead, so it
   * round-trips through TOML/JSON/YAML and every language binding like the rest of
   * `LlmConfig`.
   *
   * Managed credential providers are unavailable on `wasm32`, where liter-llm uses
   * browser HTTP rather than its native authentication modules. `LlmConfig.validate`
   * rejects a configured provider on that target instead of silently ignoring it.
   *
   * GitHub Copilot's device-flow provider has no variant here: it takes no configuration at
   * all (`liter_llm.auth.github_copilot.GithubCopilotCredentialProvider.new` accepts only
   * an HTTP client) and drives an interactive terminal prompt, so it cannot be expressed as
   * data. A Rust embedder who needs it — or any other fully custom `CredentialProvider` — can
   * call `xberg.llm.client.create_client_with_credential_provider` directly with a
   * `liter-llm` dependency of their own.
   */
  readonly credentialProvider?: CredentialProviderConfig;
  /**
   * Maximum number of simultaneously in-flight requests to the LLM provider this
   * config resolves to.
   *
   * This is a real, global bound on *provider* concurrency, not a per-extraction
   * allowance: `xberg.llm.client.create_client` shares one process-wide client
   * instance per distinct resolved config, so every concurrent extraction that
   * resolves to the same config shares the one in-flight-request limit this value
   * configures, instead of each minting its own (GH#1465). `None` means unlimited.
   *
   * PDF and image OCR batch sizing are **not** derived from this field, even when the
   * configured OCR backend or `vlm_fallback` policy can reach a VLM — those call sites
   * mix CPU-bound raster/OCR work with, at most, occasional remote requests, so they
   * size their batches from the general thread budget
   * (`max_threads`) unconditionally (GH#1465). Captioning is
   * the one feature that *additionally* uses this value to bound its own
   * per-extraction async request fan-out (issuing only VLM requests, with no CPU
   * batching to protect), on top of the global provider-side limit described above;
   * that per-extraction bound clamps a value below 1 up to 1. The global provider-side
   * limit does not clamp: `Some(0)` reaches liter-llm as-is, and liter-llm rejects it
   * when building the client (zero permitted in-flight requests is never useful), so it
   * surfaces as a `create_client` error rather than a silent clamp to 1.
   *
   * This field is intentionally last to preserve positional constructor
   * compatibility in generated language bindings.
   */
  readonly maxConcurrency?: number;
  /**
   * Maximum size, in bytes, of a single HTTP response body read from the LLM
   * provider.
   *
   * Bounds response bodies on every non-streaming call (chat completions,
   * embeddings, model listings, …) and the error body read on a failed
   * request; a successful streaming response keeps its own existing frame
   * bounds and is unaffected. `None` (the default) means unbounded, matching
   * liter-llm's own default.
   *
   * Mirrors liter-llm's `client.ClientConfigBuilder.max_response_bytes`, which
   * is native-only (`native-http`, non-`wasm32`) — see
   * `llm.client.build_client_config`. `Some(0)` is rejected by
   * `LlmConfig.validate` rather than reaching liter-llm, which would refuse it
   * at client-build time with the same complaint.
   */
  readonly maxResponseBytes?: number;
}

/**
 * A custom provider configuration entry, in addition to liter-llm's built-in providers.
 *
 * Mirrors liter-llm's `LlmProviderConfig`.
 */
export interface LlmProviderConfig {
  /** Provider name, used to key model prefix matching. */
  readonly name?: string;
  /** Base URL for the provider's OpenAI-compatible API. */
  readonly baseUrl?: string;
  /** Header name used to carry the API key (defaults to `Authorization` when unset). */
  readonly authHeader?: string;
  /** Model name prefixes routed to this provider (e.g. `["my-provider/"]`). */
  readonly modelPrefixes?: Array<string>;
}

/**
 * Per-model rate limiting configuration.
 *
 * Mirrors liter-llm's `LlmRateLimitConfig`. Only takes effect when liter-llm's
 * `tower` feature is compiled in; otherwise the value round-trips through
 * configuration but is not enforced at request time.
 */
export interface LlmRateLimitConfig {
  /** Requests per minute limit. */
  readonly rpm?: number;
  /** Tokens per minute limit. */
  readonly tpm?: number;
  /** Rate limit window, in seconds. */
  readonly windowSeconds?: number;
}

/**
 * Token usage and cost data for a single LLM call made during extraction.
 *
 * Populated when VLM OCR, structured extraction, or LLM-based embeddings
 * are used. Multiple entries may be present when multiple LLM calls occur
 * within one extraction (e.g. VLM OCR + structured extraction).
 */
export interface LlmUsage {
  /** The LLM model identifier (e.g. "openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"). */
  readonly model?: string;
  /**
   * The pipeline stage that triggered this LLM call
   * (e.g. "vlm_ocr", "structured_extraction", "embeddings").
   */
  readonly source?: string;
  /** Number of input/prompt tokens consumed. */
  readonly inputTokens?: number;
  /** Number of output/completion tokens generated. */
  readonly outputTokens?: number;
  /** Total tokens (input + output). */
  readonly totalTokens?: number;
  /** Estimated cost in USD based on the provider's published pricing. */
  readonly estimatedCost?: number;
  /** Why the model stopped generating (e.g. "stop", "length", "content_filter"). */
  readonly finishReason?: string;
}

/** The result of a map operation, containing discovered URLs. */
export interface MapResult {
  /** The list of discovered URLs. */
  readonly urls?: Array<SitemapUrl>;
}

/** A fenced code block extracted from Markdown. */
export interface MarkdownCodeBlock {
  /** Declared language identifier, or an empty string when absent. */
  readonly language?: string;
  /** Code block content. */
  readonly code?: string;
}

/** A link extracted from Markdown. */
export interface MarkdownLink {
  /** Visible link text. */
  readonly text?: string;
  /** Link destination. */
  readonly url?: string;
}

/**
 * How partial results from multiple model calls (e.g. per page batch) are combined.
 *
 * Canonical home for the merge strategy referenced by presets and by the
 * structured pipeline's post-processing. There is intentionally only one merge
 * type across the crate — do not introduce a second.
 */
export declare enum MergeMode {
  /** Deep-merge JSON objects field by field (later calls fill missing fields). */
  ObjectMerge = "object_merge",
  /** Concatenate top-level arrays across calls. */
  ArrayConcat = "array_concat",
  /** Keep the first non-empty result; ignore subsequent calls. */
  ObjectFirst = "object_first",
}

/**
 * Extraction result metadata.
 *
 * Contains common fields applicable to all formats, format-specific metadata
 * via a discriminated union, and additional custom fields from postprocessors.
 */
export interface Metadata {
  /** Document title */
  readonly title?: string;
  /** Document subject or description */
  readonly subject?: string;
  /** Primary author(s) - always Vec for consistency */
  readonly authors?: Array<string>;
  /** Keywords/tags - always Vec for consistency */
  readonly keywords?: Array<string>;
  /** Primary language (ISO 639 code) */
  readonly language?: string;
  /** Creation timestamp (ISO 8601 format) */
  readonly createdAt?: string;
  /** Last modification timestamp (ISO 8601 format) */
  readonly modifiedAt?: string;
  /** User who created the document */
  readonly createdBy?: string;
  /** User who last modified the document */
  readonly modifiedBy?: string;
  /** Page/slide/sheet structure with boundaries */
  readonly pages?: PageStructure;
  /**
   * Format-specific metadata (discriminated union)
   *
   * Contains detailed metadata specific to the document format.
   * Serialized as a nested `"format"` object with a `format_type` discriminator field.
   */
  readonly format?: FormatMetadata;
  /** Image preprocessing metadata (when OCR preprocessing was applied) */
  readonly imagePreprocessing?: ImagePreprocessingMetadata;
  /** JSON schema (for structured data extraction) */
  readonly jsonSchema?: JsonValue;
  /** Error metadata (for batch operations) */
  readonly error?: ErrorMetadata;
  /**
   * Extraction duration in milliseconds (for benchmarking).
   *
   * This field is populated by batch extraction to provide per-file timing
   * information. It's `None` for single-file extraction (which uses external timing).
   */
  readonly extractionDurationMs?: number;
  /** Document category (from frontmatter or classification). */
  readonly category?: string;
  /** Document tags (from frontmatter). */
  readonly tags?: Array<string>;
  /** Document version string (from frontmatter). */
  readonly documentVersion?: string;
  /** Abstract or summary text (from frontmatter). */
  readonly abstractText?: string;
  /**
   * Output format identifier (e.g., "markdown", "html", "text").
   *
   * Set by the output format pipeline stage when format conversion is applied.
   * Previously stored in `metadata.additional["output_format"]`.
   */
  readonly outputFormat?: string;
  /**
   * Whether OCR was used during extraction.
   *
   * Set to `true` whenever the extraction pipeline ran an OCR backend
   * (Tesseract, PaddleOCR, VLM, etc.) and used that output as the primary
   * or fallback text. `false` means native text extraction was used exclusively.
   */
  readonly ocrUsed?: boolean;
  /**
   * Additional custom fields from postprocessors.
   *
   * Serialized as a nested `"additional"` object (not flattened at root level).
   * Uses `Cow<'static, str>` keys so static string keys avoid allocation.
   */
  readonly additional?: Record<string, JsonValue>;
}

/** Compiled meta-schema validator over `preset.schema.json`. */
export declare class MetaSchema {
  /** Compile the given JSON text as a Draft 2020-12 meta-schema. */
  static compile(metaSchemaJson: string): MetaSchema;
  /**
   * Validate `raw` against the meta-schema and deserialize into a `Preset`,
   * stamping the fingerprint over the canonical file bytes.
   */
  parsePreset(path: string, raw: Uint8Array): Preset;
}

/** Selects which evidence is authoritative when Xberg infers a MIME type. */
export declare enum MimeDetectionPolicy {
  /** Prefer a supported content signature, falling back to the filename extension. */
  PreferContent = "prefer_content",
  /**
   * Trust a supported filename extension without reading content for detection.
   *
   * # Security
   *
   * Filenames are attacker-controlled input in uploads and downloads. Use this only for trusted sources;
   * otherwise a misleading extension can route arbitrary content to the wrong extractor.
   */
  TrustExtension = "trust_extension",
  /** Ignore the filename extension and require content-based detection. */
  ContentOnly = "content_only",
}

/** Combined paths to all models needed for OCR (backward compatibility). */
export interface ModelPaths {
  /** Exact path to the detection ONNX model in the Hugging Face snapshot. */
  readonly detModel: string;
  /** Exact path to the classification ONNX model in the Hugging Face snapshot. */
  readonly clsModel: string;
  /** Exact path to the recognition ONNX model in the Hugging Face snapshot. */
  readonly recModel: string;
  /** Path to the character dictionary file. */
  readonly dictFile: string;
}

/** Input signals for multi-document boundary detection. */
export interface MultidocInput {
  /** Total number of pages in the PDF. */
  readonly pageCount: number;
  /** Per-page signals extracted from the PDF. */
  readonly pages: Array<PageSignals>;
}

/**
 * Thresholds for multi-document boundary detection.
 *
 * All fields are public; callers override any subset via struct-update syntax.
 */
export interface MultidocThresholds {
  /**
   * Text density difference threshold for `DensityShift` detection.
   * Default: 0.3.
   */
  readonly densityShiftThreshold?: number;
  /**
   * Minimum bigram-overlap ratio below which a density shift is promoted to
   * a `DensityShift` boundary.  Default: 0.1 (10 % overlap).
   */
  readonly bigramOverlapMin?: number;
}

/**
 * A ColBERT multi-vector embedding: one row per attention-live token.
 *
 * `data` is a flat, row-major buffer of length `num_tokens * dim` — row `i`
 * (the embedding for token `i`) occupies `data[i*dim .. (i+1)*dim]`. Flat
 * storage keeps the type FFI-friendly across binding boundaries; use
 * `MultiVectorEmbedding.rows` internally to iterate per-token slices.
 */
export interface MultiVectorEmbedding {
  /**
   * Number of attention-live token rows (padding rows are dropped, not
   * zeroed — see `engine.normalize_tokens`).
   */
  readonly numTokens: number;
  /** Dimensionality of each per-token vector. */
  readonly dim: number;
  /** Flat row-major buffer, length `num_tokens * dim`. */
  readonly data: Array<number>;
}

/** NER backend selector. */
export declare enum NerBackendKind {
  /**
   * `xberg-gliner` ONNX inference. Requires `ner-onnx` feature. Models
   * download lazily from `xberg-io/gliner-models`.
   */
  Onnx = "onnx",
  /**
   * liter-llm zero-shot NER via structured-output prompts. Requires `ner-llm`
   * feature. Useful when domain-specific categories outstrip the ONNX taxonomy.
   */
  Llm = "llm",
}

/** Configuration for the NER post-processor. */
export interface NerConfig {
  /** Backend that runs the entity detection. */
  readonly backend?: NerBackendKind;
  /**
   * Entity categories to detect. Defaults to a sensible PERSON/ORG/LOCATION/EMAIL set
   * when empty.
   */
  readonly categories?: Array<EntityCategory>;
  /**
   * Override the default model — only used by `NerBackendKind.Onnx`.
   * `None` lets the backend pick its pinned default xberg GLiNER model alias.
   */
  readonly model?: string;
  /**
   * Optional LLM configuration — only used by `NerBackendKind.Llm`. Token usage
   * for LLM backends is recorded in `ExtractedDocument.llm_usage`.
   */
  readonly llm?: LlmConfig;
  /**
   * Arbitrary user-supplied entity labels for zero-shot detection.
   *
   * `xberg-gliner` natively supports zero-shot inference over caller-supplied
   * labels. The LLM backend also honours these
   * labels by including them in the structured-output schema. Custom labels
   * surface as `EntityCategory.Custom` in the resulting `Entity` stream.
   *
   * Use this when you need domain-specific entity types (e.g. `"Treatment"`,
   * `"Product"`, `"Vessel"`) without forking GLiNER's taxonomy.
   */
  readonly customLabels?: Array<string>;
}

/**
 * Line break syntax in Markdown output.
 *
 * Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
 */
export declare enum NewlineStyle {
  /** Two trailing spaces at end of line. Default. Standard Markdown syntax. */
  Spaces = "Spaces",
  /** Backslash at end of line. Alternative Markdown syntax. */
  Backslash = "Backslash",
}

/** Inclusive word-count range used to form keyword candidates. */
export interface NgramRange {
  /** Minimum number of words in a candidate. */
  readonly min?: number;
  /** Maximum number of words in a candidate. */
  readonly max?: number;
}

/** Reason for not chunking a document. */
export type NoChunkingReason =
  | { type: "SmallFile"; sizeBytes: number; thresholdBytes: number }
  | { type: "FewPages"; pageCount: number; threshold: number }
  | { type: "TextLayerDetected"; textCoverage: number; avgCharsPerPage: number }
  | { type: "FormatNotChunkable"; mimeType: string }
  | { type: "ChunkingDisabled" }
  | { type: "FastTextExtraction" };

/**
 * Tagged enum for node content. Each variant carries only type-specific data.
 *
 * Uses `#[serde(tag = "node_type")]` to avoid "type" keyword collision in
 * Go/Java/TypeScript bindings.
 */
export type NodeContent =
  | { node_type: "title"; text: string }
  | { node_type: "heading"; level: number; text: string }
  | { node_type: "paragraph"; text: string }
  | { node_type: "list"; ordered: boolean }
  | { node_type: "list_item"; text: string }
  | { node_type: "table"; grid: TableGrid }
  | { node_type: "image"; description: string; imageIndex: number; src: string }
  | { node_type: "code"; text: string; language: string }
  | { node_type: "quote" }
  | { node_type: "formula"; text: string }
  | { node_type: "footnote"; text: string }
  | { node_type: "comment"; text: string }
  | { node_type: "group"; label: string; headingLevel: number; headingText: string }
  | { node_type: "page_break" }
  | { node_type: "slide"; number: number; title: string }
  | { node_type: "definition_list" }
  | { node_type: "definition_item"; term: string; definition: string }
  | { node_type: "citation"; key: string; text: string }
  | { node_type: "admonition"; kind: string; title: string }
  | { node_type: "raw_block"; format: string; content: string }
  | { node_type: "metadata_block"; entries: Array<KeyValueAttribute> };

/**
 * Trait for OCR backend plugins.
 *
 * Implement this trait to add custom OCR capabilities. OCR backends can be:
 * - Native Rust implementations (like Tesseract)
 * - FFI bridges to external libraries (like PaddleOCR)
 * - Cloud-based OCR services (Google Vision, AWS Textract, etc.)
 *
 * # Thread Safety
 *
 * OCR backends must be thread-safe (`Send + Sync`) to support concurrent processing.
 */
export interface OcrBackend {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Process an image and extract text via OCR.
   * @param image_bytes - Raw image data (JPEG, PNG, TIFF, etc.)
   *
   * @param config - OCR configuration (language, PSM mode, etc.)
   *
   * @returns An `ExtractedDocument` containing the extracted text and metadata.
   *
   * @throws - `XbergError.Ocr` - OCR processing failed
   * - `XbergError.Validation` - Invalid image format or configuration
   * - `XbergError.Io` - I/O errors (these always bubble up)
   *
   * # Reading `backend_options`
   *
   * Backends that support runtime tuning can read `config.backend_options` and
   * deserialize only the keys they care about. Unknown keys are silently ignored,
   * so multiple backends can coexist in a pipeline without key conflicts.
   */
  processImage(imageBytes: Uint8Array, config?: OcrConfig | undefined | null): Promise<ExtractedDocument>;
  /**
   * Process a file and extract text via OCR.
   *
   * Default implementation reads the file and calls `process_image`.
   * Override for custom file handling or optimizations.
   * @param path - Path to the image file
   *
   * @param config - OCR configuration
   *
   * @throws Same as `process_image`, plus file I/O errors.
   */
  processImageFile?(path: string, config?: OcrConfig | undefined | null): Promise<ExtractedDocument>;
  /**
   * Check if this backend supports a given language code.
   * @param lang - ISO 639-2/3 language code (e.g., "eng", "deu", "fra")
   *
   * @returns `true` if the language is supported, `false` otherwise.
   */
  supportsLanguage(lang: string): boolean;
  /**
   * Get the backend type identifier.
   * @returns The backend type enum value.
   */
  backendType(): OcrBackendType;
  /**
   * Optional: Get a list of all supported languages.
   *
   * Defaults to empty list. Override to provide comprehensive language support info.
   */
  supportedLanguages?(): Array<string>;
  /**
   * Optional: Check if the backend supports table detection.
   *
   * Defaults to `false`. Override if your backend can detect and extract tables.
   */
  supportsTableDetection?(): boolean;
  /**
   * Check if the backend supports direct document-level processing (e.g. for PDFs).
   *
   * Defaults to `false`. Override if the backend has optimized document processing.
   * PDF extraction uses this optimized path only when both effective page margins
   * are zero; nonzero margins require per-page image processing so geometry can be
   * filtered correctly.
   */
  supportsDocumentProcessing?(): boolean;
  /**
   * Declare that this backend emits structured markdown directly (tables, headings, lists)
   * and downstream layout reconstruction should be skipped.
   *
   * Defaults to `false` — classical OCR backends (Tesseract, PaddleOCR classical) return
   * plain text per detected region. End-to-end VLM backends (PaddleOCR-VL, GOT-OCR 2.0)
   * emit markdown in one forward pass and should override this to `true`.
   */
  emitsStructuredMarkdown?(): boolean;
  /**
   * Declare how this backend's reported page-level confidence must be interpreted.
   *
   * Defaults to `ConfidenceSemantics.Uncalibrated`. This default is deliberately the
   * least trusting option, not `ConfidenceSemantics.Legibility`: a new backend that
   * reports *some* confidence number is not thereby safe to gate on, and defaulting to
   * `Legibility` would let the next backend silently inherit a threshold calibrated for a
   * different backend's scale — exactly the failure this type exists to prevent (see the
   * type's doc comment). Override this only after validating that the reported number
   * tracks legibility on a known scale.
   */
  confidenceSemantics?(): ConfidenceSemantics;
  /**
   * Declare how this backend copes with a page raster whose text is not upright.
   *
   * Defaults to `PageOrientationHandling.RequiresUpright`. This default is deliberately
   * the least capable option, not `PageOrientationHandling.SelfCorrecting`: a new backend
   * must not silently inherit Tesseract's ability to reconstruct reading order on a rotated
   * raster and then quietly emit garbage the first time it faces one (see the type's doc
   * comment for the measured A/B behind this). Override this only after validating the
   * backend's actual behaviour on a rotated page.
   */
  pageOrientationHandling?(): PageOrientationHandling;
  /**
   * Process a document file directly via OCR.
   *
   * Only called if `supports_document_processing` returns `true`.
   * @param path - Path to the document file (e.g. .pdf)
   *
   * @param config - OCR configuration
   */
  processDocument?(path: string, config?: OcrConfig | undefined | null): Promise<ExtractedDocument>;
}

/**
 * A registered OCR backend's declared name and language capabilities.
 *
 * Returned by `list_ocr_backend_capabilities`. See that function's documentation for the
 * determinism guarantees and the important caveat about what an empty `supported_languages`
 * means.
 */
export interface OcrBackendCapabilities {
  /** The backend's registered name, as returned by `list_ocr_backends`. */
  readonly name: string;
  /**
   * The languages this backend declares support for, via
   * `OcrBackend.supported_languages`.
   *
   * An empty list means the backend does not enumerate its languages — it is *not* a
   * statement that the backend supports no languages. `OcrBackend.supported_languages`
   * is a defaulted trait method that returns `vec![]`, and not every backend overrides it:
   * the VLM backend (`llm.vlm_ocr.VlmOcrBackend`) accepts every language via
   * `supports_language` while inheriting the empty default here. Use
   * `ocr_backend_supports_language` to decide whether one specific language is usable —
   * never infer "unsupported" from an empty list.
   *
   * The order of this list is preserved exactly as the backend reported it and is *not*
   * re-sorted. Tesseract's order comes from enumerating installed tessdata files; PaddleOCR's
   * comes from its own `SUPPORTED_LANGUAGES` constant. Re-sorting would disagree with the
   * precedence each backend's own `supports_language` implementation uses internally.
   */
  readonly supportedLanguages: Array<string>;
}

/** OCR backend types. */
export declare enum OcrBackendType {
  /** Tesseract OCR (native Rust binding) */
  Tesseract = "Tesseract",
  /** PaddleOCR (Python-based, via FFI) */
  PaddleOCR = "PaddleOCR",
  /** Candle-based VLM OCR (TrOCR, PaddleOCR-VL). */
  Candle = "Candle",
  /** Name-selected built-in or third-party OCR backend. */
  Custom = "Custom",
}

/**
 * Bounding geometry for an OCR element.
 *
 * Supports both axis-aligned rectangles (from Tesseract) and 4-point quadrilaterals
 * (from PaddleOCR and rotated text detection).
 */
export type OcrBoundingGeometry =
  | { type: "rectangle"; left: number; top: number; width: number; height: number }
  | { type: "quadrilateral"; points: Array<OcrPoint> };

/**
 * Confidence scores for an OCR element.
 *
 * Separates detection confidence (how confident that text exists at this location)
 * from recognition confidence (how confident about the actual text content).
 */
export interface OcrConfidence {
  /**
   * Detection confidence: how confident the OCR engine is that text exists here.
   *
   * PaddleOCR provides this as `box_score`, Tesseract doesn't have a direct equivalent.
   * Range: 0.0 to 1.0 (or undefined if not available).
   */
  readonly detection?: number;
  /**
   * Recognition confidence: how confident about the text content.
   *
   * Range: 0.0 to 1.0.
   */
  readonly recognition?: number;
}

/** OCR configuration. */
export interface OcrConfig {
  /**
   * Whether OCR is enabled.
   *
   * Setting `enabled: false` is a shorthand for `disable_ocr: true` on the parent
   * `ExtractionConfig`. Images return
   * metadata only; PDFs use native text extraction without OCR fallback.
   *
   * Defaults to `true`. When `false`, all other OCR settings are ignored.
   */
  readonly enabled?: boolean;
  /**
   * OCR backend: tesseract, paddleocr, paddle-ocr, sceptre, or vlm.
   * Sceptre uses ONNX Runtime on desktop/server and tract on supported mobile builds.
   * Browser WebAssembly uses the separate byte-fed Sceptre worker API.
   */
  readonly backend?: string;
  /**
   * Language code(s) for OCR recognition. Defaults to `["eng"]`. For Tesseract,
   * languages are joined with "+".
   *
   * A list is the canonical form and the only form accepted by the binding
   * object APIs (Python, Node, PHP, WASM, etc.): `["eng", "deu"]`. When
   * deserializing from a config file, JSON body, or the REST/MCP API, a
   * single string is also accepted, either as one code ("eng") or
   * "+"-joined ("eng+deu").
   */
  readonly language?: Array<string>;
  /** Tesseract-specific configuration (optional) */
  readonly tesseractConfig?: TesseractConfig;
  /** Output format for OCR results (optional, for format conversion) */
  readonly outputFormat?: OutputFormat;
  /**
   * PaddleOCR-specific configuration (optional, JSON passthrough).
   *
   * Deserialized into a `PaddleOcrConfig`, so any of its fields can be
   * overridden here — most notably `model_version` (`"pp-ocrv6"` default / `"pp-ocrv5"`) and
   * `model_tier`. In TOML:
   *
   * ```toml
   * [ocr.paddle_ocr_config]
   * model_version = "pp-ocrv5"
   * model_tier = "server"
   * ```
   *
   * The `XBERG_OCR_MODEL_VERSION` / `XBERG_OCR_MODEL_TIER` environment variables set the same two
   * keys for env-configured servers (issue #1279).
   */
  readonly paddleOcrConfig?: JsonValue;
  /**
   * Arbitrary per-call options passed through to the backend unchanged.
   *
   * Custom OCR backends and built-in backends that support runtime tuning
   * can read this value and deserialize the keys they care about. Keys
   * unknown to the backend are silently ignored.
   *
   * This is the recommended extension point for per-call parameters that
   * are not covered by the typed fields above (e.g. mode switching,
   * preprocessing flags, inference batch size).
   *
   * **Scope:** when `pipeline` is `None`, this value is propagated to the
   * primary stage of the auto-constructed pipeline. When `pipeline` is
   * explicitly set, this field has **no effect** — the caller must set
   * `OcrPipelineStage.backend_options` directly on the relevant stage(s)
   * instead.
   *
   * Example:
   * ```json
   * { "mode": "fast", "enable_layout": true, "timeout_ms": 5000 }
   * ```
   */
  readonly backendOptions?: JsonValue;
  /** OCR element extraction configuration */
  readonly elementConfig?: OcrElementConfig;
  /**
   * Quality thresholds for the native-text-to-OCR fallback decision.
   * When undefined, uses compiled defaults (matching previous hardcoded behavior).
   */
  readonly qualityThresholds?: OcrQualityThresholds;
  /**
   * Multi-backend OCR pipeline configuration. When set, enables weighted
   * fallback across multiple OCR backends based on output quality.
   * When undefined, uses the single `backend` field (same as today).
   */
  readonly pipeline?: OcrPipelineConfig;
  /**
   * Enable automatic page rotation based on orientation detection.
   *
   * When enabled, page orientation (0/90/180/270 degrees) is detected with an
   * ONNX PP-LCNet document-orientation classifier — NOT Tesseract's own
   * `DetectOrientationScript()`/OSD, which this crate does not call. If the
   * page is rotated with high confidence, the image is corrected before
   * recognition. Applies to every OCR backend; the tesseract-only
   * `TesseractConfig.preprocessing` field of the same name is OR'd in on
   * top of this one and affects tesseract alone.
   *
   * Independent of a page's PDF `/Rotate` entry, which is handled separately
   * on every OCR route regardless of this setting.
   */
  readonly autoRotate?: boolean;
  /**
   * Ergonomic VLM fallback policy.
   *
   * When set to anything other than `VlmFallbackPolicy.Disabled` and
   * `OcrConfig.pipeline` is `None`, a multi-stage pipeline is synthesised
   * automatically:
   *
   * - `VlmFallbackPolicy.OnLowQuality` → `[classical_stage, vlm_stage]` with the
   *   `quality_threshold` mapped onto `OcrQualityThresholds.pipeline_min_quality`.
   * - `VlmFallbackPolicy.Always` → `[vlm_stage]` only.
   *
   * Requires `OcrConfig.vlm_config` to be `Some` when not `Disabled`.
   * When `OcrConfig.pipeline` is explicitly set, this field is ignored.
   */
  readonly vlmFallback?: VlmFallbackPolicy;
  /**
   * VLM (Vision Language Model) OCR configuration.
   *
   * Required when `backend` is `"vlm"` or when `vlm_fallback` is not
   * `VlmFallbackPolicy.Disabled`. Uses liter-llm to send page images to a
   * vision model for text extraction.
   */
  readonly vlmConfig?: LlmConfig;
  /**
   * Custom Jinja2 prompt template for VLM OCR.
   *
   * When `None`, uses the default template. Available variables:
   * - `{{ language }}` — The document language code (e.g., "eng", "deu").
   */
  readonly vlmPrompt?: string;
  /**
   * Hardware acceleration for ONNX Runtime models (e.g. PaddleOCR, layout detection).
   *
   * Not user-configurable via config files — injected at runtime from
   * `ExtractionConfig.acceleration` before each `process_image` call.
   */
  readonly acceleration?: AccelerationConfig;
  /**
   * Security limits applied when decoding raw image bytes for OCR (GH#1554).
   *
   * Not user-configurable via config files — injected at runtime from
   * `ExtractionConfig.security_limits` before each `process_image` call, the same
   * pattern `Self.acceleration` uses. `ExtractionConfig.security_limits` remains the
   * source of truth and overwrites this field whenever it carries a value; a value set
   * here directly is honoured only when `ExtractionConfig` carries none, so the two
   * cannot drift while a directly-set limit is no longer silently discarded (GH#1651).
   * A backend consulting a
   * `backend_options` override for this call may still let that override win, but in
   * the absence of one this field is what backends should fall back to instead of
   * `SecurityLimits.default()`. `None` means "use `SecurityLimits.default()`", never
   * "disable the check".
   */
  readonly securityLimits?: SecurityLimits;
  /**
   * Caller-supplied Tesseract `traineddata` bytes per language code.
   *
   * Primary use case is the WASM build, which has no filesystem and cannot
   * download tessdata at runtime. Native builds typically rely on
   * `TessdataManager` and ignore this field. When present, the WASM
   * Tesseract backend prefers these bytes over its compile-time-bundled
   * English data.
   *
   * Skipped by serde to keep config files small — supply via the typed API
   * at runtime.
   */
  readonly tessdataBytes?: Record<string, Uint8Array>;
  /**
   * Runtime override for tessdata directory path.
   *
   * When set, uses this path as the highest-priority tessdata location,
   * bypassing environment variables and cache directories. Useful for
   * embedding pre-installed tessdata in applications. When `None`, uses
   * the standard resolution chain: TESSDATA_PREFIX env, cache dir, system paths.
   */
  readonly tessdataPath?: string;
}

/**
 * A unified OCR element representing detected text with full metadata.
 *
 * This is the primary type for structured OCR output, preserving all information
 * from both Tesseract and PaddleOCR backends.
 */
export interface OcrElement {
  /** The recognized text content. */
  readonly text?: string;
  /** Bounding geometry (rectangle or quadrilateral). */
  readonly geometry?: OcrBoundingGeometry;
  /** Confidence scores for detection and recognition. */
  readonly confidence?: OcrConfidence;
  /** Hierarchical level (word, line, block, page). */
  readonly level?: OcrElementLevel;
  /** Rotation information (if detected). */
  readonly rotation?: OcrRotation;
  /** Page number (1-indexed). */
  readonly pageNumber?: number;
  /**
   * Parent element ID for hierarchical relationships.
   *
   * When hierarchy output is enabled, this resolves to another emitted element's
   * `backend_metadata["element_id"]` value.
   */
  readonly parentId?: string;
  /** Backend-specific metadata that doesn't fit the unified schema. */
  readonly backendMetadata?: Record<string, JsonValue>;
}

/**
 * Configuration for OCR element extraction.
 *
 * Controls how OCR elements are extracted and filtered.
 */
export interface OcrElementConfig {
  /**
   * Whether to include OCR elements in the extraction result.
   *
   * When true, the `ocr_elements` field in `ExtractedDocument` will be populated.
   */
  readonly includeElements?: boolean;
  /**
   * Minimum hierarchical level to include.
   *
   * Elements below this level (e.g., words when min_level is Line) will be excluded.
   */
  readonly minLevel?: OcrElementLevel;
  /**
   * Minimum recognition confidence threshold (0.0-1.0).
   *
   * Elements with confidence below this threshold will be filtered out.
   */
  readonly minConfidence?: number;
  /**
   * Whether to build hierarchical relationships between elements.
   *
   * When true, emitted elements receive an `element_id` metadata value and `parent_id`
   * references are populated only when a spatially containing parent is also emitted.
   */
  readonly buildHierarchy?: boolean;
}

/**
 * Hierarchical level of an OCR element.
 *
 * Maps to Tesseract's page segmentation hierarchy and provides
 * equivalent semantics for PaddleOCR.
 */
export declare enum OcrElementLevel {
  /** Individual word */
  Word = "word",
  /** Line of text (default for PaddleOCR) */
  Line = "line",
  /** Paragraph or text block */
  Block = "block",
  /** Page-level element */
  Page = "page",
}

/**
 * OCR extraction result.
 *
 * Result of performing OCR on an image or scanned document,
 * including recognized text and detected tables.
 */
export interface OcrExtractionResult {
  /** Recognized text content */
  readonly content?: string;
  /** Original MIME type of the processed image */
  readonly mimeType?: string;
  /** OCR processing metadata (confidence scores, language, etc.) */
  readonly metadata?: Record<string, JsonValue>;
  /** Tables detected and extracted via OCR */
  readonly tables?: Array<OcrTable>;
  /**
   * Structured OCR elements with bounding boxes and confidence scores.
   * Available when TSV output is requested or table detection is enabled.
   */
  readonly ocrElements?: Array<OcrElement>;
}

/**
 * OCR processing metadata.
 *
 * Captures information about OCR processing configuration and results.
 */
export interface OcrMetadata {
  /** OCR language code(s) used */
  readonly language?: string;
  /** Tesseract Page Segmentation Mode (PSM) */
  readonly psm?: number;
  /** Output format (e.g., "text", "hocr") */
  readonly outputFormat?: string;
  /** Number of tables detected */
  readonly tableCount?: number;
  /** Number of rows in the detected table (if a single table was found). */
  readonly tableRows?: number;
  /** Number of columns in the detected table (if a single table was found). */
  readonly tableCols?: number;
}

/**
 * Multi-backend OCR pipeline with quality-based fallback.
 *
 * Backends are tried in priority order (highest first). After each backend
 * produces output, quality is evaluated. If it meets `quality_thresholds.pipeline_min_quality`,
 * the result is accepted. Otherwise the next backend is tried; if none clears the
 * threshold, an internal selection policy derived from the `OcrConfig` decides which
 * stage's result is returned as the best effort (`vlm_fallback` pipelines prefer their
 * last non-empty stage; explicit and classical pipelines stay score-based).
 */
export interface OcrPipelineConfig {
  /** Ordered list of backends to try. Sorted by priority (descending) at runtime. */
  readonly stages: Array<OcrPipelineStage>;
  /** Quality thresholds for deciding whether to accept a result or try the next backend. */
  readonly qualityThresholds: OcrQualityThresholds;
}

/** A single backend stage in the OCR pipeline. */
export interface OcrPipelineStage {
  /**
   * Backend name: "tesseract", "paddleocr", "paddle-ocr", "sceptre", "vlm", or a custom registered name.
   * Sceptre uses ONNX Runtime on desktop/server and tract on Android/iOS; browser WebAssembly has a separate
   * byte-fed engine because the normal async OCR registry assumes native model storage.
   */
  readonly backend: string;
  /** Priority weight (higher = tried first). Stages are sorted by priority descending. */
  readonly priority: number;
  /**
   * Language override for this stage (undefined = use parent OcrConfig.language).
   *
   * A list is the canonical form and the only form accepted by the binding
   * object APIs: `["eng", "deu"]`. When deserializing from a config file,
   * JSON body, or the REST/MCP API, a single string is also accepted,
   * either as one code ("eng") or "+"-joined ("eng+deu").
   */
  readonly language?: Array<string>;
  /** Tesseract-specific config override for this stage. */
  readonly tesseractConfig?: TesseractConfig;
  /** PaddleOCR-specific config for this stage. */
  readonly paddleOcrConfig?: JsonValue;
  /** VLM config override for this pipeline stage. */
  readonly vlmConfig?: LlmConfig;
  /**
   * Arbitrary per-call options passed through to the backend unchanged.
   *
   * Backends that support runtime tuning (mode switching, preprocessing
   * flags, inference parameters, etc.) read this value and deserialize
   * the keys they care about. Keys unknown to the backend are silently
   * ignored, so options from different backends can coexist in the same
   * config without conflict.
   *
   * Example (custom backend):
   * ```json
   * { "mode": "fast", "enable_layout": true }
   * ```
   */
  readonly backendOptions?: JsonValue;
}

/** A point in OCR raster pixel coordinates. */
export interface OcrPoint {
  /** Horizontal coordinate. */
  readonly x?: number;
  /** Vertical coordinate. */
  readonly y?: number;
}

/**
 * Quality thresholds for OCR fallback decisions and pipeline quality gating.
 *
 * Fields default to conservative extraction behavior. Suspected OCR recognition noise is
 * reported but retained unless destructive filtering is explicitly enabled.
 */
export interface OcrQualityThresholds {
  /** Minimum total non-whitespace characters to consider text substantive. */
  readonly minTotalNonWhitespace?: number;
  /** Minimum non-whitespace characters per page on average. */
  readonly minNonWhitespacePerPage?: number;
  /** Minimum character count for a word to be "meaningful". */
  readonly minMeaningfulWordLen?: number;
  /** Minimum count of meaningful words before text is accepted. */
  readonly minMeaningfulWords?: number;
  /** Minimum alphanumeric ratio (non-whitespace chars that are alphanumeric). */
  readonly minAlnumRatio?: number;
  /** Minimum Unicode replacement characters (U+FFFD) to trigger OCR fallback. */
  readonly minGarbageChars?: number;
  /** Maximum fraction of short (1-2 char) words before text is considered fragmented. */
  readonly maxFragmentedWordRatio?: number;
  /**
   * Critical fragmentation threshold — triggers OCR regardless of meaningful words.
   * Normal English text has ~20-30% short words. 80%+ is definitive garbage.
   */
  readonly criticalFragmentedWordRatio?: number;
  /**
   * Maximum fraction of short (1-2 char) words an *OCR result* may carry before the page
   * is reported as suspected recognition noise.
   *
   * This is a different decision, and a different operating point, from
   * `Self.max_fragmented_word_ratio` / `Self.critical_fragmented_word_ratio`: those
   * ask "is the native text bad enough that we should OCR this page?", and are tuned to
   * only fire on text that is already definitively broken (0.6 / 0.8). Here we are judging
   * what OCR *produced*, where the failure mode is an engine run over line art — a scanned
   * plat, an engineering drawing, a signature flourish — returning confident-looking
   * strings that are not words.
   *
   * Measured over the 16 pages of a recorded municipal ordinance (13 prose pages, 3 scanned
   * survey drawings): prose ran 0.04-0.28, the drawings 0.42-0.47. The default sits in that
   * gap with margin on both sides. By default, crossing the threshold emits a processing
   * warning but retains the recognized text. Set `Self.discard_suspected_ocr_noise` to
   * `true` to restore destructive filtering.
   */
  readonly maxOcrOutputFragmentedWordRatio?: number;
  /**
   * Minimum mean OCR confidence (0-100) below which a page is reported as suspected noise.
   *
   * This is the engine's own uncertainty about what it read, and it is a far sharper
   * instrument than any statistic derived from the output text. Measured per page over a
   * recorded municipal ordinance (10 prose pages, 6 scanned survey/architectural drawings)
   * with Tesseract 5.5.3:
   *
   * ```text
   * prose      86.3 - 95.3
   * drawings   18.5 - 64.3
   * ```
   *
   * The default sits in that gap with ~11 points of margin on each side. Compare the
   * short-word ratio, which separated the same two groups by 0.09 on a 0-1 scale.
   *
   * A backend that reports no confidence (no `mean_text_conf` in its result metadata)
   * skips this check entirely and falls back to
   * `Self.max_ocr_output_fragmented_word_ratio`. By default, the signal emits a warning
   * without discarding content. Set to 0.0 to disable the signal.
   */
  readonly minOcrMeanConfidence?: number;
  /**
   * Minimum word count before `Self.max_ocr_output_fragmented_word_ratio` may report a
   * page. Short pages (a signature block, an exhibit title) are legitimately dominated by
   * short words, so the ratio is not meaningful on them and the signal stays disabled.
   */
  readonly minWordsForOcrOutputCheck?: number;
  /**
   * Maximum fraction of a Tesseract page's dictionary-checkable words that
   * `TesseractAPI.is_valid_word` may reject before the page is treated as recognition
   * noise, supplementing (never replacing) `Self.max_ocr_output_fragmented_word_ratio`.
   *
   * Tesseract-only: other backends never report this ratio (see
   * `dictionary_invalid_word_ratio` in `ocr.processor.execution`), so this threshold is
   * simply never consulted for them.
   *
   * Calibration owed, same as `ocr.types.TesseractConfig.min_confidence`:
   * unlike `Self.max_ocr_output_fragmented_word_ratio` (measured across a recorded
   * ordinance's prose vs. drawing pages), this ratio has not yet had a page-level
   * measurement run over a labeled corpus. The default therefore disables the check
   * entirely (`1.01`, above the `[0.0, 1.0]` range a ratio can reach) rather than guess an
   * operating point. Do not lower this without running that measurement first.
   */
  readonly maxOcrOutputDictInvalidWordRatio?: number;
  /**
   * Discard non-empty OCR text when any configured recognition-noise signal fires.
   *
   * Defaults to `false`: suspected noise is retained and surfaced through
   * `processing_warnings`. Set to `true` to preserve the legacy destructive behavior.
   */
  readonly discardSuspectedOcrNoise?: boolean;
  /** Minimum average word length. Below this with enough words indicates garbled extraction. */
  readonly minAvgWordLength?: number;
  /** Minimum word count before average word length check applies. */
  readonly minWordsForAvgLengthCheck?: number;
  /** Minimum consecutive word repetition ratio to detect column scrambling. */
  readonly minConsecutiveRepeatRatio?: number;
  /** Minimum word count before consecutive repetition check is applied. */
  readonly minWordsForRepeatCheck?: number;
  /** Minimum character count for "substantive markdown" OCR skip gate. */
  readonly substantiveMinChars?: number;
  /** Minimum character count for "non-text content" OCR skip gate. */
  readonly nonTextMinChars?: number;
  /** Alphanumeric+whitespace ratio threshold for skip decisions. */
  readonly alnumWsRatioThreshold?: number;
  /**
   * Minimum quality score (0.0-1.0) for a pipeline stage result to be accepted.
   * If the result from a backend scores below this, try the next backend.
   */
  readonly pipelineMinQuality?: number;
  /**
   * Minimum fraction of non-whitespace characters that are undecodable
   * (Unicode Private Use Area, replacement characters, or non-whitespace
   * control characters) before a page's text layer is treated as
   * unreadable and routed to OCR (issue #1254). Gated by
   * `min_total_non_whitespace` so short snippets with a stray symbol or
   * two do not trip this check.
   */
  readonly minUndecodableRatio?: number;
  /**
   * Whether to route a page to OCR when xberg_native_pdf reports that a high
   * fraction of its text was fabricated rather than read from the file
   * (`MappingProvenance.Fallback`, xberg_native_pdf 0.3.75+, issue #1254). This is
   * a direct fact from the extractor's ISO 32000-1 §9.10.2 mapping cascade,
   * distinct from the character-heuristic proxy behind `min_undecodable_ratio`.
   * Defaults to `true`.
   */
  readonly enableProvenanceOcrRouting?: boolean;
  /**
   * Minimum fraction of a page's non-whitespace characters with
   * `MappingProvenance.Fallback` provenance before the page is treated as
   * having a fabricated text layer and routed to OCR (issue #1254). Gated by
   * `min_total_non_whitespace` so a short page with a stray fallback
   * character cannot trip it. Only used when `enable_provenance_ocr_routing`
   * is `true`.
   */
  readonly minProvenanceFallbackRatio?: number;
}

/** Rotation information for an OCR element. */
export interface OcrRotation {
  /** Rotation angle in degrees (0, 90, 180, 270 for PaddleOCR). */
  readonly angleDegrees: number;
  /** Confidence score for the rotation detection. */
  readonly confidence?: number;
}

/** Which pages of a PDF get OCR'd when neither `force_ocr` nor `force_ocr_pages` applies. */
export type OcrStrategy = { mode: "auto" } | { mode: "scanned_pages"; minConfidence: number };

/**
 * Table detected via OCR.
 *
 * Represents a table structure recognized during OCR processing.
 */
export interface OcrTable {
  /** Table cells as a 2D vector (rows × columns) */
  readonly cells: Array<Array<string>>;
  /** Markdown representation of the table */
  readonly markdown: string;
  /** Page number where the table was found (1-indexed) */
  readonly pageNumber: number;
  /** Bounding box of the table in pixel coordinates (from OCR word positions). */
  readonly boundingBox?: OcrTableBoundingBox;
}

/** Bounding box for an OCR-detected table in pixel coordinates. */
export interface OcrTableBoundingBox {
  /** Left x-coordinate (pixels) */
  readonly left: number;
  /** Top y-coordinate (pixels) */
  readonly top: number;
  /** Right x-coordinate (pixels) */
  readonly right: number;
  /** Bottom y-coordinate (pixels) */
  readonly bottom: number;
}

/** Document orientation detection result. */
export interface OrientationResult {
  /** Detected orientation in degrees (0, 90, 180, or 270). */
  readonly degrees: number;
  /** Confidence score (0.0-1.0). */
  readonly confidence: number;
}

/**
 * Output format for extraction results.
 *
 * Controls the format of the `content` field in `ExtractedDocument`.
 * When set to `Markdown`, `Djot`, or `Html`, the output uses that format.
 * `Plain` returns the raw extracted text.
 */
export type OutputFormat = "plain" | "markdown" | "djot" | "html" | "json" | "doctags" | (string & {});

/**
 * Which concrete ONNX inference engine PaddleOCR model loading uses.
 *
 * Mirrors `sceptre.Backend` for the PaddleOCR backend: `Ort` is the native,
 * full-featured path (acceleration/execution-provider hook, ONNX-embedded
 * dictionary metadata); `Tract` is the pure-Rust, CPU-only path used on targets
 * where `ort` cannot link (Android x86_64 emulator, WASM once wired).
 */
export declare enum PaddleInferenceBackend {
  /** Native ONNX Runtime (requires the `paddle-ocr-ort` feature). */
  Ort = "ort",
  /** Pure-Rust ONNX via `tract` (requires the `paddle-ocr-tract` feature). */
  Tract = "tract",
}

/**
 * Supported languages in PaddleOCR.
 *
 * Maps user-friendly language codes to paddle-ocr-rs language identifiers.
 */
export declare enum PaddleLanguage {
  /** English */
  English = "English",
  /** Simplified Chinese */
  Chinese = "Chinese",
  /** Japanese */
  Japanese = "Japanese",
  /** Korean */
  Korean = "Korean",
  /** German */
  German = "German",
  /** French */
  French = "French",
  /** Latin script (covers most European languages) */
  Latin = "Latin",
  /** Cyrillic (Russian and related) */
  Cyrillic = "Cyrillic",
  /** Traditional Chinese */
  TraditionalChinese = "TraditionalChinese",
  /** Thai */
  Thai = "Thai",
  /** Greek */
  Greek = "Greek",
  /** East Slavic (Russian, Ukrainian, Belarusian) */
  EastSlavic = "EastSlavic",
  /** Arabic (Arabic, Persian, Urdu) */
  Arabic = "Arabic",
  /** Devanagari (Hindi, Marathi, Sanskrit, Nepali) */
  Devanagari = "Devanagari",
  /** Tamil */
  Tamil = "Tamil",
  /** Telugu */
  Telugu = "Telugu",
}

/**
 * Configuration for PaddleOCR backend.
 *
 * Configures PaddleOCR text detection and recognition with multi-language support.
 * Uses a builder pattern for convenient configuration.
 */
export interface PaddleOcrConfig {
  /** Language code (e.g., "en", "ch", "jpn", "kor", "deu", "fra") */
  readonly language?: string;
  /**
   * Optional Hugging Face Hub cache root for model files.
   *
   * When unset, the standard `HF_HUB_CACHE`, legacy
   * `HUGGINGFACE_HUB_CACHE`, and `HF_HOME` conventions are used.
   */
  readonly cacheDir?: string;
  /**
   * Enable angle classification for rotated text (default: false).
   * Can misfire on short text regions, rotating crops incorrectly before recognition.
   */
  readonly useAngleCls?: boolean;
  /**
   * Enable table structure detection (default: **false**, unlike `TesseractConfig`
   * which defaults to `true` — see `crate.ocr.types.TesseractConfig`).
   *
   * PaddleOCR has no per-word table-candidate confidence carve-out the way Tesseract's
   * TSV does (every recognised word is a clustering candidate), so unfiltered clustering
   * over-fabricates tables on ordinary prose. This stays off until it clears a
   * cell-scored accuracy measurement (see the pinning test at the bottom of this file).
   * Consequence for callers: switching an existing config from the Tesseract backend to
   * PaddleOCR with stock defaults silently produces **no** OCR tables — enable this
   * explicitly if you need them.
   *
   * When enabled, this only clusters and reconstructs a grid from word boxes PaddleOCR
   * has already produced (see `crate.paddle_ocr.backend.PaddleOcrBackend.process_image`)
   * — it does not run any additional model inference, so the added per-page cost is the
   * CPU-only clustering/reconstruction pass, not another ONNX call.
   */
  readonly enableTableDetection?: boolean;
  /**
   * Database threshold for text detection (default: 0.3)
   * Range: 0.0-1.0, higher values require more confident detections
   */
  readonly detDbThresh?: number;
  /**
   * Box threshold for text bounding box refinement (default: 0.5)
   * Range: 0.0-1.0
   */
  readonly detDbBoxThresh?: number;
  /**
   * Unclip ratio for expanding text bounding boxes (default: 1.6)
   * Controls the expansion of detected text regions
   */
  readonly detDbUnclipRatio?: number;
  /**
   * Maximum side length for detection image (default: 1024)
   * Larger images may be resized to this limit for faster inference
   */
  readonly detLimitSideLen?: number;
  /**
   * Batch size for recognition inference (default: 6)
   * Number of text regions to process simultaneously
   */
  readonly recBatchNum?: number;
  /**
   * Padding in pixels added around the image before detection (default: 10).
   * Large values can include surrounding content like table gridlines.
   */
  readonly padding?: number;
  /**
   * Minimum recognition confidence score for text lines (default: 0.5).
   * Text regions with recognition confidence below this threshold are discarded.
   * Matches PaddleOCR Python's `drop_score` parameter.
   * Range: 0.0-1.0
   */
  readonly dropScore?: number;
  /**
   * Model tier controlling detection/recognition model size and accuracy trade-off.
   *
   * For PP-OCRv5 (`model_version = "pp-ocrv5"`):
   * - `"mobile"` (default): Lightweight models (~4.5MB detection, ~16.5MB recognition), fast download and inference
   * - `"server"`: Large, high-accuracy models (~88MB detection, ~84MB recognition), best for GPU or complex documents
   *
   * For PP-OCRv6 (`model_version = "pp-ocrv6"`, the default):
   * - `"small"`: ~9.9MB detection, full 18,708-char CJK+Latin+JA/KO recognition dictionary.
   *   The default `"mobile"` resolves here, so this is what an unconfigured extraction uses.
   * - `"medium"`: ~62MB detection, same dictionary. Higher accuracy, substantially slower on
   *   CPU. A legacy `"server"` tier, or any unrecognised value, resolves here.
   * - `"tiny"`: ~1.8MB detection, but a reduced 6,904-char (~zh/en) dictionary — it cannot
   *   read the scripts the other two cover.
   *
   * Note PaddleOCR pages do not run concurrently: the ONNX session is held behind a mutex, so
   * the thread budget goes to intra-op parallelism and wall time scales with page count times
   * per-page inference. Tier choice therefore dominates throughput on multi-page documents.
   */
  readonly modelTier?: string;
  /**
   * Model generation: `"pp-ocrv6"` (default) or `"pp-ocrv5"`.
   *
   * PP-OCRv6 adds a unified CJK+Latin+JA/KO recognition model with `medium`/`small`/`tiny`
   * tiers (see `model_tier`). Scripts outside the v6 unified coverage (Arabic, Cyrillic,
   * Devanagari, Greek, Tamil, Telugu, Thai) transparently fall back to the PP-OCRv5
   * per-script recognition models. Defaults to `"pp-ocrv6"`; the default `model_tier`
   * (`"mobile"`) resolves to the v6 `"small"` tier. Select `"pp-ocrv5"` to pin the
   * legacy per-script/unified fleet.
   */
  readonly modelVersion?: string;
  /**
   * Explicit inference engine choice.
   *
   * `None` (the default) resolves to the compiled default: `ort` when the
   * `paddle-ocr-ort` feature is compiled in, otherwise `tract`. An explicit choice
   * is validated against the compiled features when the OCR engine is constructed
   * (see `crate.paddle_ocr.backend.effective_backend`); requesting an engine
   * whose feature is not compiled in is a clear configuration error rather than a
   * silent fallback.
   */
  readonly inferenceBackend?: PaddleInferenceBackend;
}

/** Runtime options accepted by the `candle-paddleocr-vl` backend. */
export interface PaddleOcrVlBackendOptions {
  /** Optional per-call recognition task; the backend constructor's task is used when absent. */
  readonly task?: PaddleOcrVlTaskKind;
  /** Optional local model directory, which takes precedence over `model_id`. */
  readonly modelPath?: string;
  /** Optional Hugging Face repository identifier. */
  readonly modelId?: string;
  /** Optional immutable Hugging Face model revision. */
  readonly hfRevision?: string;
  /** Optional Hugging Face cache root. */
  readonly cacheDir?: string;
  /** Optional per-call device override. */
  readonly device?: CandleDevicePreference;
}

/** Task accepted by `candle-paddleocr-vl` backend options. */
export declare enum PaddleOcrVlTaskKind {
  Ocr = "ocr",
  Table = "table",
  Formula = "formula",
  Chart = "chart",
}

/**
 * Byte offset boundary for a page.
 *
 * Tracks where a specific page's content starts and ends in the main content string,
 * enabling mapping from byte positions to page numbers. Offsets are guaranteed to be
 * at valid UTF-8 character boundaries when using standard String methods (push_str, push, etc.).
 */
export interface PageBoundary {
  /** Byte offset where this page starts in the content string (UTF-8 valid boundary, inclusive) */
  readonly byteStart: number;
  /** Byte offset where this page ends in the content string (UTF-8 valid boundary, exclusive) */
  readonly byteEnd: number;
  /** Page number (1-indexed) */
  readonly pageNumber: number;
}

/** Classification result for a single page. */
export interface PageClassification {
  /** 1-indexed page number this classification belongs to. */
  readonly pageNumber: number;
  /**
   * Labels assigned to the page. Single-label classification yields exactly one
   * entry; multi-label classification yields any subset of the configured label set.
   */
  readonly labels: Array<ClassificationLabel>;
}

/** Configuration for the page-classification post-processor. */
export interface PageClassificationConfig {
  /**
   * Minijinja prompt template. Receives `{{ labels }}` (joined list), `{{ page_text }}`
   * and `{{ multi_label }}` variables. `None` lets the backend pick a sensible default.
   */
  readonly promptTemplate?: string;
  /** The set of labels the classifier may emit. Must contain at least one entry. */
  readonly labels: Array<string>;
  /** Allow multiple labels per page. Single-label mode returns at most one label. */
  readonly multiLabel: boolean;
  /** LLM configuration used for classification. */
  readonly llm: LlmConfig;
}

/**
 * Page extraction and tracking configuration.
 *
 * Controls how pages are extracted, tracked, and represented in the extraction results.
 * When `None`, page tracking is disabled.
 *
 * Page range tracking in chunk metadata (first_page/last_page) is automatically enabled
 * when page boundaries are available and chunking is configured.
 */
export interface PageConfig {
  /** Extract pages as separate array (ExtractedDocument.pages) */
  readonly extractPages?: boolean;
  /** Insert page markers in main content string */
  readonly insertPageMarkers?: boolean;
  /**
   * Page marker format (use {page_num} placeholder)
   * Default: "\n\n<!-- PAGE {page_num} -->\n\n"
   */
  readonly markerFormat?: string;
}

/**
 * Content for a single page/slide.
 *
 * When page extraction is enabled, documents are split into per-page content
 * with associated tables and images mapped to each page.
 *
 * # Performance
 *
 * Uses Arc-wrapped tables and images for memory efficiency:
 * - `Vec<Arc<Table>>` enables zero-copy sharing of table data
 * - `Vec<Arc<ExtractedImage>>` enables zero-copy sharing of image data
 * - Maintains exact JSON compatibility via custom Serialize/Deserialize
 *
 * This reduces memory overhead for documents with shared tables/images
 * by avoiding redundant copies during serialization.
 */
export interface PageContent {
  /** Page number (1-indexed) */
  readonly pageNumber: number;
  /** Text content for this page */
  readonly content: string;
  /**
   * Tables found on this page (uses Arc for memory efficiency)
   *
   * Serializes as `Vec<Table>` for JSON compatibility while maintaining
   * Arc semantics in-memory for zero-copy sharing.
   */
  readonly tables: Array<Table>;
  /**
   * Indices into `ExtractedDocument.images` for images found on this page.
   *
   * Each value is a zero-based index into the top-level `images` collection.
   * Only populated when `extract_images = true` in the extraction config.
   */
  readonly imageIndices: Array<number>;
  /** OCR image preprocessing applied to this page's raster. */
  readonly imagePreprocessing?: ImagePreprocessingMetadata;
  /**
   * Hierarchy information for the page (when hierarchy extraction is enabled)
   *
   * Contains text hierarchy levels (H1-H6) extracted from the page content.
   */
  readonly hierarchy?: PageHierarchy;
  /**
   * Whether this page is blank (no meaningful text content)
   *
   * Determined during extraction based on text content analysis.
   * A page is blank if it has fewer than 3 non-whitespace characters
   * and contains no tables or images.
   */
  readonly isBlank?: boolean;
  /**
   * Layout detection regions for this page (when layout detection is enabled).
   *
   * Contains detected layout regions with class, confidence, bounding box,
   * and area fraction. Only populated when layout detection is configured.
   */
  readonly layoutRegions?: Array<LayoutRegion>;
  /**
   * Speaker notes for this slide (PPTX only).
   *
   * Contains the text from the slide's notes pane (`ppt/notesSlides/notesSlide{N}.xml`).
   * Only populated when the source is a PPTX file and notes are present.
   */
  readonly speakerNotes?: string;
  /**
   * Section name this slide belongs to (PPTX only).
   *
   * PowerPoint sections group slides into logical chapters (`<p:sectionLst>` in
   * `ppt/presentation.xml`). Only populated when the source is a PPTX file and
   * the slide belongs to a named section.
   */
  readonly sectionName?: string;
  /**
   * Sheet name for this page (XLSX/ODS only).
   *
   * Each spreadsheet sheet maps to one `PageContent` entry. This field carries the
   * sheet's display name as it appears in the workbook. `None` for all non-spreadsheet
   * formats and for sheets with an empty name.
   */
  readonly sheetName?: string;
  /** Aggregate OCR confidence for this page. `None` when the page was not OCR'd. */
  readonly ocrConfidence?: PageOcrConfidence;
}

/**
 * Metadata for individual page/slide/sheet.
 *
 * Captures per-page information including dimensions, content counts,
 * and visibility state (for presentations).
 */
export interface PageDimensions {
  /** Page width in points or pixels. */
  readonly width?: number;
  /** Page height in points or pixels. */
  readonly height?: number;
}

/**
 * Page hierarchy structure containing heading levels and block information.
 *
 * Used when PDF text hierarchy extraction is enabled. Contains hierarchical
 * blocks with heading levels (H1-H6) for semantic document structure.
 */
export interface PageHierarchy {
  /** Number of hierarchy blocks on this page */
  readonly blockCount: number;
  /** Hierarchical blocks with heading levels */
  readonly blocks: Array<HierarchicalBlock>;
}

export interface PageInfo {
  /** Page number (1-indexed) */
  readonly number: number;
  /** Page title (usually for presentations) */
  readonly title?: string;
  /** Dimensions in points (PDF) or pixels (images). */
  readonly dimensions?: PageDimensions;
  /** Number of images on this page */
  readonly imageCount?: number;
  /** Number of tables on this page */
  readonly tableCount?: number;
  /** Whether this page is hidden (e.g., in presentations) */
  readonly hidden?: boolean;
  /**
   * Whether this page is blank (no meaningful text, no images, no tables)
   *
   * A page is considered blank if it has fewer than 3 non-whitespace characters
   * and contains no tables or images. This is useful for filtering out empty pages
   * in scanned documents or PDFs with blank separator pages.
   */
  readonly isBlank?: boolean;
  /**
   * Whether this page contains non-trivial vector graphics (paths, shapes, curves)
   *
   * Indicates the presence of vector-drawn content such as charts, diagrams,
   * or geometric shapes (e.g., from Adobe InDesign, LaTeX TikZ). These are
   * invisible to `ExtractedDocument.images` since they are not embedded as raster
   * XObjects. Set to `true` when path count exceeds a heuristic threshold,
   * signaling that downstream consumers may want to rasterize the page to
   * capture this content.
   *
   * Only populated for PDFs; `None` for other document types.
   */
  readonly hasVectorGraphics: boolean;
}

/**
 * Aggregate OCR legibility score for a page, reported by the backend that produced its text.
 *
 * This is distinct from `OcrConfidence`, which scores a single detected element (a word or
 * line) using detection/recognition confidence from the OCR engine itself. `PageOcrConfidence`
 * is a page-level summary computed after noise filtering, intended for triage of which pages
 * are worth a closer look, not for comparing OCR engines against each other.
 */
export interface PageOcrConfidence {
  /**
   * Aggregate legibility score in `0.0..=1.0`, or `None` when the backend that
   * produced this page does not report a calibrated legibility scale.
   *
   * Backends differ in what their confidence numbers mean (see `OcrConfidence`'s
   * per-backend normalization), and not every backend maps onto a 0.0-1.0 legibility
   * scale at all. When a backend has no such calibrated scale, this is `None` rather
   * than a misleading number, and scores must never be compared across backends.
   */
  readonly score?: number;
  /**
   * Number of words the score was averaged over, AFTER noise filtering.
   *
   * A small `word_count` means the average is based on little evidence, so a high
   * `score` next to a small `word_count` is not representative of the whole page.
   */
  readonly wordCount?: number;
  /** Name of the OCR backend that produced the page text. */
  readonly backend?: string;
}

/**
 * How a backend copes with a page raster whose text is not upright.
 *
 * Rotated-page handling is a backend capability, not a universal guarantee. An A/B run this
 * session against `/Rotate 270` scanned pages showed the three handled cases genuinely differ:
 * Tesseract reconstructs correct reading order on a sideways raster outright; PaddleOCR
 * recognises the rotated text correctly (it warps each detected quad upright before running
 * recognition) but leaves its block list in raw raster `(y, x)` order, so the caller must
 * reorder; sceptre produces character garbage on the same sideways raster and only reads
 * correctly once the page is rendered upright first. A caller that skips an upright-render step
 * for a backend that actually needs one gets silent garbage, not an error.
 *
 * # Only one variant is discriminated (#657)
 *
 * Read this before "simplifying" the type. There is exactly one decision point in the
 * codebase that inspects this value: `upright_raster_for_backend`
 * (`crate.extractors.pdf.ocr`), which tests `orientation_handling != RequiresUpright` and
 * otherwise does nothing. Every other mention forwards the value to that test. So, *to that
 * codepath*, `SelfCorrecting` and `RecognisesRotatedText` are behaviourally identical — the
 * enum is a boolean at the point of use, and the three variants describe measured backend
 * behaviour rather than three dispatch paths.
 *
 * `RecognisesRotatedText`'s actual remedy is not this enum. The block-order fix is the
 * `backend_options["page_rotation_degrees"]` hint injected by
 * `ocr_config_with_page_rotation_hint` (`crate.extractors.pdf.ocr`) **unconditionally, for
 * every backend**, which `PaddleOcrBackend.process_image` reads back
 * (`page_rotation_degrees_from_backend_options` -> `residual_rotation_for_reorder` ->
 * `reorder_blocks_for_page_rotation`, `crate.paddle_ocr.backend`) and applies internally.
 * Declaring `RecognisesRotatedText` therefore changes nothing on its own; a backend in that
 * class must also read the hint. Conversely, gating that hint on this enum would remove a
 * field from Tesseract's `OcrConfig` and hence from the OCR cache key
 * (`hash(image + language + config)`), invalidating every cached page — do not do it without
 * its own A/B.
 *
 * # PDF-route-only
 *
 * Only the PDF OCR routes call `OcrBackend.page_orientation_handling` (the `--force-ocr`
 * route via `extract_with_ocr` and the scanned-pages route via `extract_mixed_ocr_native`).
 * The raw-image route (`crate.extractors.image`) never calls it: there is no `/Rotate` to
 * consult, and orientation there is handled by the PP-LCNet document-orientation classifier
 * (`crate.doc_orientation`) gated on `OcrConfig.auto_rotate`.
 *
 * # Cost of the default
 *
 * The trait default is `RequiresUpright` (deliberately the least capable option, see
 * `OcrBackend.page_orientation_handling`). A backend that does not declare therefore pays,
 * on every page with `/Rotate != 0`, a re-encode plus rotation of the raster in
 * `upright_raster_for_backend` and a bounding-box round-trip back through
 * `undo_upright_raster_correction`. That is the safe direction to be wrong in, but it is not
 * free, and for a backend that never got measured it is not known to be necessary either.
 */
export declare enum PageOrientationHandling {
  /**
   * Reconstructs reading order regardless of page rotation — safe to hand a
   * raster in any orientation.
   */
  SelfCorrecting = "SelfCorrecting",
  /**
   * Recognises rotated text correctly but emits blocks in raw raster order,
   * so the caller must reorder.
   */
  RecognisesRotatedText = "RecognisesRotatedText",
  /** Requires an upright raster; rotated text produces garbage. */
  RequiresUpright = "RequiresUpright",
}

/** Page range for a chunk (0-indexed, inclusive). */
export interface PageRange {
  /** Start page (0-indexed, inclusive). */
  readonly start: number;
  /** End page (0-indexed, inclusive). */
  readonly end: number;
}

/** Per-page signals extracted from PDF content. */
export interface PageSignals {
  /** 1-indexed page number. */
  readonly pageNumber: number;
  /** First ~500 characters of extracted text. */
  readonly textExcerpt: string;
  /**
   * `true` if page starts with letterhead-like content (ALL CAPS line in first 5 lines
   * or a logo-image bbox at top).
   */
  readonly startsWithLetterheadLike: boolean;
  /** `true` if text contains "Page 1" or "1 of N" pattern. */
  readonly hasPageNumberOneMarker: boolean;
  /**
   * `true` if text contains signature indicators ("Sincerely", "Signed") or
   * a signature image bbox.
   */
  readonly hasSignatureBlock: boolean;
  /** Text density: characters per page area, normalised to `[0.0, 1.0]`. */
  readonly layoutTextDensity: number;
}

/**
 * A single page covered by a chunk, with an optional bounding box on that page.
 *
 * See `ChunkMetadata.page_spans` (#1295) for population semantics.
 */
export interface PageSpan {
  /** Page number (1-indexed). */
  readonly page: number;
  /** Bounding box on this page, if known. */
  readonly bbox?: BoundingBox;
}

/**
 * Unified page structure for documents.
 *
 * Supports different page types (PDF pages, PPTX slides, Excel sheets)
 * with character offset boundaries for chunk-to-page mapping.
 */
export interface PageStructure {
  /** Total number of pages/slides/sheets */
  readonly totalCount: number;
  /** Type of paginated unit */
  readonly unitType: PageUnitType;
  /**
   * Character offset boundaries for each page
   *
   * Maps character ranges in the extracted content to page numbers.
   * Used for chunk page range calculation.
   */
  readonly boundaries?: Array<PageBoundary>;
  /** Detailed per-page metadata (optional, only when needed) */
  readonly pages?: Array<PageInfo>;
}

/**
 * Type of paginated unit in a document.
 *
 * Distinguishes between different types of "pages" (PDF pages, presentation slides, spreadsheet sheets).
 */
export declare enum PageUnitType {
  /** Standard document pages (PDF, DOCX, images) */
  Page = "page",
  /** Presentation slides (PPTX, ODP) */
  Slide = "slide",
  /** Spreadsheet sheets (XLSX, ODS) */
  Sheet = "sheet",
}

/** One detected PII span in the input text. */
export interface PatternMatch {
  /** Inclusive byte-offset start of the match in the source text. */
  readonly start: number;
  /** Exclusive byte-offset end of the match. */
  readonly end: number;
  /** Category the match belongs to. */
  readonly category: PiiCategory;
  /**
   * Matched substring (owned copy — pattern engine returns owned data so the
   * caller can free the original text if needed before replacement).
   */
  readonly text: string;
}

/** A PDF annotation extracted from a document page. */
export interface PdfAnnotation {
  /** The type of annotation. */
  readonly annotationType: PdfAnnotationType;
  /** Text content of the annotation (e.g., comment text, link URL). */
  readonly content?: string;
  /** Page number where the annotation appears (1-indexed). */
  readonly pageNumber: number;
  /** Bounding box of the annotation on the page. */
  readonly boundingBox?: BoundingBox;
  /** Author/creator of the annotation (PDF `/T` entry). */
  readonly author?: string;
  /**
   * Last modification date of the annotation (PDF `/M` entry), as a raw
   * PDF date string (e.g. `"D:20240115120000Z"`).
   */
  readonly modified?: string;
  /**
   * Annotation colour (PDF `/C` entry), normalised to a CSS-compatible
   * `#rrggbb` hex string. Gray and CMYK colour spaces are converted to RGB.
   */
  readonly color?: string;
  /** Subject of the annotation (PDF `/Subj` entry). */
  readonly subject?: string;
  /**
   * Per-line bounding boxes derived from the annotation's `/QuadPoints`
   * entry. Present for text markup annotations (Highlight, Underline,
   * StrikeOut, Squiggly), one box per marked line/run of text.
   */
  readonly quadPoints?: Array<BoundingBox>;
  /**
   * The document text covered by `Self.quad_points`, recovered from the
   * page content underneath the marked-up region. Populated for
   * Highlight, Underline, StrikeOut, and Squiggly annotations when the
   * underlying text could be recovered.
   */
  readonly markedText?: string;
}

/** Type of PDF annotation. */
export declare enum PdfAnnotationType {
  /** Sticky note / text annotation */
  Text = "text",
  /** Highlighted text region */
  Highlight = "highlight",
  /** Hyperlink annotation */
  Link = "link",
  /** Rubber stamp annotation */
  Stamp = "stamp",
  /** Underline text markup */
  Underline = "underline",
  /** Strikeout text markup */
  StrikeOut = "strike_out",
  /** Squiggly (wavy) underline text markup */
  Squiggly = "squiggly",
  /** Freehand drawing (ink) annotation */
  Ink = "ink",
  /** Rectangle/box shape annotation */
  Square = "square",
  /** Ellipse/oval shape annotation */
  Circle = "circle",
  /** Closed polygon shape annotation */
  Polygon = "polygon",
  /** Open polyline shape annotation */
  PolyLine = "poly_line",
  /** Line annotation */
  Line = "line",
  /** Caret (text-insertion marker) annotation */
  Caret = "caret",
  /** Embedded file attachment annotation */
  FileAttachment = "file_attachment",
  /** Embedded sound annotation */
  Sound = "sound",
  /** Embedded movie annotation */
  Movie = "movie",
  /** Any other annotation type */
  Other = "other",
}

/**
 * PDF extraction backend selection.
 *
 * Controls which engine parses and renders PDF documents. Wire format is
 * snake_case in all serializers (JSON, TOML, YAML). Defaults to
 * `PdfBackend.Native` -- selecting anything else never changes behavior
 * for a caller who does not opt in.
 */
export declare enum PdfBackend {
  /** xberg's own pure-Rust PDF engine (default), `crates/xberg-native-pdf`. */
  Native = "native",
  /**
   * pdfium -- Google's PDFium engine, gated behind the `pdf-pdfium` Cargo
   * feature (#700 added the selection level; #702 added the extraction
   * engine, `extractors.pdf.pdfium_engine`, deliberately smaller in scope
   * than `Native` -- see that module's doc comment for exactly what it
   * extracts). A build without the `pdf-pdfium` feature rejects this at the
   * CLI validation layer rather than silently falling back to `Native`.
   * A build *with* the feature still enforces the selection at extraction
   * time (`extractors.pdf.PdfExtractor.extract_core`), because that is
   * the one dispatch point every caller -- CLI, library use, API/MCP
   * servers, language bindings -- passes through; see that function's doc
   * comment for why the enforcement lives there and not only in CLI
   * validation.
   */
  Pdfium = "pdfium",
}

/** PDF-specific configuration. */
export interface PdfConfig {
  /** Extract images from PDF */
  readonly extractImages?: boolean;
  /**
   * Extract tables from PDF.
   *
   * When `true` (default), runs the native engine's grid detector and, if it
   * finds nothing, falls back to the heuristic text-layer reconstruction in
   * `pdf.native.table.extract_tables_heuristic`. Set to `false` to skip
   * both passes — `tables` will then be empty in the result.
   */
  readonly extractTables?: boolean;
  /** List of passwords to try when opening encrypted PDFs */
  readonly passwords?: Array<string>;
  /** Extract PDF metadata */
  readonly extractMetadata?: boolean;
  /** Hierarchy extraction configuration (undefined = hierarchy extraction disabled) */
  readonly hierarchy?: HierarchyConfig;
  /**
   * Extract PDF annotations (text notes, highlights, links, stamps).
   * Default: false
   */
  readonly extractAnnotations?: boolean;
  /**
   * Top margin fraction (0.0–1.0) of page height to exclude headers/running heads.
   * Ignored when `ContentFilterConfig.include_headers` is `true`.
   * Effective nonzero margins require per-page OCR so geometry can be filtered;
   * document-capable OCR backends use their image-processing path in that case.
   * Default: 0.0 (disabled; set explicitly to filter header content)
   */
  readonly topMarginFraction?: number;
  /**
   * Bottom margin fraction (0.0–1.0) of page height to exclude footers/page numbers.
   * Ignored when `ContentFilterConfig.include_footers` is `true`.
   * Effective nonzero margins require per-page OCR so geometry can be filtered;
   * document-capable OCR backends use their image-processing path in that case.
   * Default: 0.0 (disabled; set explicitly to filter footer content)
   */
  readonly bottomMarginFraction?: number;
  /**
   * Allow single-column pseudo tables in extraction results.
   *
   * By default, tables with fewer than 2 columns (layout-guided) or 3 columns
   * (heuristic) are rejected. When `true`, the minimum column count is relaxed
   * to 1, allowing single-column structured data (glossaries, itemized lists)
   * to be emitted as tables. Other quality filters (density, sparsity, prose
   * detection) still apply.
   */
  readonly allowSingleColumnTables?: boolean;
  /**
   * Perform OCR on inline images extracted from PDF pages and attach the
   * recognized text to each `ExtractedImage.ocr_result`. Uses the backend
   * selected by `ExtractionConfig.ocr`, or the default OCR backend when no
   * OCR configuration is supplied. Requires the `ocr` or `ocr-pipeline`
   * feature. Per-image failures degrade gracefully (the image is returned
   * without OCR text rather than failing the whole extraction). Default:
   * `false`.
   */
  readonly ocrInlineImages?: boolean;
  /**
   * Extract AcroForm and XFA form fields into `ExtractedDocument.form_fields`.
   *
   * When `true` (default), reads the document's interactive form structure
   * (field names, types, values, widget geometry). Cheap and strictly
   * additive — non-form PDFs simply yield an empty list. Set to `false` to
   * skip the form pass entirely.
   */
  readonly extractFormFields?: boolean;
  /**
   * Reorder extracted text by layout-detected reading order.
   *
   * When `true`, projects text spans onto layout-detected regions, performs
   * column detection, and emits spans in natural reading order (important
   * for multi-column academic PDFs). It also repairs 90/180/270-degree
   * rotated text runs — sideways tables and captions — that otherwise read
   * word-reversed and glued (GH#1358); see
   * `crate.extractors.pdf.reading_order` for the rotation-handling
   * details and its limits. Requires the `layout-detection` feature and a
   * page for which layout detection actually produces hints: a page with
   * no detected regions falls back to the original, unrepaired extraction
   * order even with this enabled. Independent of
   * `LayoutStrategy`, which only
   * controls whether layout detection runs at all — enabling `Always` or
   * `Auto` alone does not turn reordering on. Defaults to `false`.
   */
  readonly readingOrder?: boolean;
  /**
   * Which engine parses and renders this PDF.
   *
   * Defaults to `PdfBackend.Native`. Selecting `PdfBackend.Pdfium`
   * requires the `pdf-pdfium` feature and is rejected otherwise; the
   * pdfium engine is also deliberately narrower in scope than `Native` --
   * see `PdfBackend` and `extractors.pdf.pdfium_engine` for details.
   */
  readonly backend?: PdfBackend;
}

/**
 * A form field extracted from a PDF's AcroForm or XFA structure.
 *
 * Populated by the PDF extractor when `PdfConfig.extract_form_fields` is
 * enabled and the document is a fillable form. Supports both AcroForm (standard)
 * and XFA (XML Forms Architecture) layers. When both are present, AcroForm fields
 * take priority (canonical fallback per PDF spec), and XFA-only fields are appended.
 * The collection is empty for non-form PDFs and for non-PDF formats.
 */
export interface PdfFormField {
  /** Partial field name (the leaf name within the field hierarchy). */
  readonly name: string;
  /** Fully-qualified field name (dotted path from the form root). */
  readonly fullName: string;
  /** Classified field type. */
  readonly fieldType: FormFieldType;
  /** Current field value, if any. */
  readonly value?: string;
  /** Default field value, if any. */
  readonly defaultValue?: string;
  /** Raw field-flags bitmask (read-only, required, multiline, …). */
  readonly flags: number;
  /**
   * 1-indexed page the field's widget appears on. Currently always `None` for
   * AcroForm fields; page assignment is a deferred enhancement requiring spatial
   * analysis of widget annotations per page.
   */
  readonly page?: number;
  /** Widget bounding box on its page, if known. */
  readonly bbox?: BoundingBox;
  /** Maximum input length for text fields, if specified. */
  readonly maxLength?: number;
  /** Tooltip / alternate field description, if present. */
  readonly tooltip?: string;
}

/**
 * PDF-specific metadata.
 *
 * Contains metadata fields specific to PDF documents that are not in the common
 * `Metadata` structure. Common fields like title, authors, keywords, and dates
 * are at the `Metadata` level.
 */
export interface PdfMetadata {
  /** PDF version (e.g., "1.7", "2.0") */
  readonly pdfVersion?: string;
  /** PDF producer (application that created the PDF) */
  readonly producer?: string;
  /** Whether the PDF is encrypted/password-protected */
  readonly isEncrypted?: boolean;
  /** First page width in points (1/72 inch) */
  readonly width?: number;
  /** First page height in points (1/72 inch) */
  readonly height?: number;
  /** Total number of pages in the PDF document */
  readonly pageCount?: number;
  /**
   * How strongly the document's most scan-like page resembles a scan, in `[0.0, 1.0]`.
   *
   * `None` when the document could not be inspected. A full-page raster with no
   * visible text scores at least `0.85`; a born-digital slide with a full-bleed
   * background image scores `0.50`.
   */
  readonly scannedConfidence?: number;
  /**
   * Pages that look like scans (1-indexed), using the default confidence threshold.
   *
   * `None` when the document could not be inspected; empty when no page qualifies.
   */
  readonly scannedPages?: Array<number>;
  /**
   * Pages the `auto` layout strategy skipped (1-indexed).
   *
   * `None` unless layout detection ran with `LayoutStrategy.Auto`; empty
   * when the gate selected every page.
   */
  readonly layoutGatedPages?: Array<number>;
  /**
   * Why the `auto` layout gate selected or skipped each page.
   *
   * Index `i` is page `i + 1`. Snake_case values such as `multi_column`,
   * `table_grid`, or `plain_text` (the skip reason). `None` unless layout
   * detection ran with `LayoutStrategy.Auto`.
   */
  readonly layoutGateReasons?: Array<string>;
}

/** PII categories the pattern engine recognises. */
export type PiiCategory =
  | { type: "email" }
  | { type: "phone" }
  | { type: "ssn" }
  | { type: "credit_card" }
  | { type: "postal_code" }
  | { type: "ip_address" }
  | { type: "iban" }
  | { type: "swift_bic" }
  | { type: "date_of_birth" }
  | { type: "person" }
  | { type: "organization" }
  | { type: "location" }
  | { type: "custom"; custom: string };

/**
 * Image preprocessing metadata.
 *
 * Tracks the transformations applied to an image during OCR preprocessing,
 * including DPI normalization, resizing, and resampling.
 */
export interface PixelDimensions {
  /** Width in pixels. */
  readonly width?: number;
  /** Height in pixels. */
  readonly height?: number;
}

/**
 * Base trait that all plugins must implement.
 *
 * This trait provides common functionality for plugin lifecycle management,
 * identification, and metadata.
 *
 * # Thread Safety
 *
 * All plugins must be `Send + Sync` to support concurrent usage across threads.
 */
export interface Plugin {
  /**
   * Returns the unique name/identifier for this plugin.
   *
   * The name should be:
   * - Unique across all plugins
   * - Lowercase with hyphens (e.g., "my-custom-plugin")
   * - URL-safe characters only
   */
  name(): string;
  /**
   * Returns the semantic version of this plugin.
   *
   * Should follow semver format: `MAJOR.MINOR.PATCH`
   */
  version?(): string;
  /**
   * Initialize the plugin.
   *
   * Called once when the plugin is registered. Use this to:
   * - Load configuration
   * - Initialize resources (connections, caches, etc.)
   * - Validate dependencies
   *
   * # Thread Safety
   *
   * This method takes `&self` instead of `&mut self` to work with `Arc<dyn Plugin>`.
   * Plugins needing mutable state during initialization should use interior mutability
   * patterns (Mutex, RwLock, OnceCell, etc.).
   * @throws Should return an error if initialization fails. The plugin will not be
   * registered if this method returns an error.
   */
  initialize?(): void;
  /**
   * Shutdown the plugin.
   *
   * Called when the plugin is being unregistered or the application is shutting down.
   * Use this to:
   * - Close connections
   * - Flush caches
   * - Release resources
   *
   * # Thread Safety
   *
   * This method takes `&self` instead of `&mut self` to work with `Arc<dyn Plugin>`.
   * Plugins needing mutable state during shutdown should use interior mutability
   * patterns (Mutex, RwLock, etc.).
   * @throws Errors during shutdown are logged but don't prevent the shutdown process.
   */
  shutdown?(): void;
  /**
   * Optional plugin description for debugging and logging.
   *
   * Defaults to empty string if not overridden.
   */
  description?(): string;
  /**
   * Optional plugin author information.
   *
   * Defaults to empty string if not overridden.
   */
  author?(): string;
}

/**
 * Trait for post-processor plugins.
 *
 * Post-processors transform or enrich extraction results after the initial
 * extraction is complete. They can:
 * - Clean and normalize text
 * - Add metadata (language, keywords, entities)
 * - Split content into chunks
 * - Score quality
 * - Apply custom transformations
 *
 * # Processing Order
 *
 * Post-processors are executed in stage order:
 * 1. **Early** - Language detection, entity extraction
 * 2. **Middle** - Keyword extraction, token reduction
 * 3. **Late** - Custom hooks, final validation
 *
 * Within each stage, processors are executed in registration order.
 *
 * # Error Handling
 *
 * Post-processor errors are non-fatal by default - they're captured in metadata
 * and execution continues. To make errors fatal, return an error from `process()`.
 *
 * # Thread Safety
 *
 * Post-processors must be thread-safe (`Send + Sync`).
 */
export interface PostProcessor {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Process an extraction result.
   *
   * Transform or enrich the extraction result. Can modify:
   * - `content` - The extracted text
   * - `metadata` - Add or update metadata fields
   * - `tables` - Modify or enhance table data
   * @param result - Mutable reference to the extraction result to process
   *
   * @param config - Extraction configuration
   *
   * @returns `Ok(())` if processing succeeded, `Err(...)` for fatal failures.
   *
   * @throws Return errors for fatal processing failures. Non-fatal errors should be
   * captured in metadata directly on the result.
   *
   * # Performance
   *
   * This signature avoids unnecessary cloning of large extraction results by
   * taking a mutable reference instead of ownership. Processors modify the
   * result in place.
   *
   * # Example - Language Detection
   *
   *
   * # Example - Text Cleaning
   */
  process(result?: ExtractedDocument | undefined | null, config?: ExtractionConfig | undefined | null): Promise<void>;
  /**
   * Get the processing stage for this post-processor.
   *
   * Determines when this processor runs in the pipeline.
   * @returns The `ProcessingStage` (Early, Middle, or Late).
   */
  processingStage(): ProcessingStage;
  /**
   * Optional: Check if this processor should run for a given result.
   *
   * Allows conditional processing based on MIME type, metadata, or content.
   * Defaults to `true` (always run).
   * @param result - The extraction result to check
   *
   * @param config - Extraction configuration
   *
   * @returns `true` if the processor should run, `false` to skip.
   */
  shouldProcess?(result?: ExtractedDocument | undefined | null, config?: ExtractionConfig | undefined | null): boolean;
  /**
   * Optional: Estimate processing time in milliseconds.
   *
   * Used for logging and debugging. Defaults to 0 (unknown).
   * @param result - The extraction result to estimate for
   *
   * @returns Estimated processing time in milliseconds.
   */
  estimatedDurationMs?(result?: ExtractedDocument | undefined | null): number;
  /**
   * Execution priority within the processing stage.
   *
   * Higher values run first within the same `ProcessingStage`. Defaults to 50.
   * Use 0-49 for fallback processors, 50 for normal processors, and 51-255
   * for high-priority processors that should run early in their stage.
   */
  priority?(): number;
}

/** Post-processor configuration. */
export interface PostProcessorConfig {
  /** Enable post-processors */
  readonly enabled?: boolean;
  /** Whitelist of processor names to run (undefined = all enabled) */
  readonly enabledProcessors?: Array<string>;
  /** Blacklist of processor names to skip (undefined = none disabled) */
  readonly disabledProcessors?: Array<string>;
  /** Pre-computed AHashSet for O(1) enabled processor lookup */
  readonly enabledSet?: Array<string>;
  /** Pre-computed AHashSet for O(1) disabled processor lookup */
  readonly disabledSet?: Array<string>;
}

/**
 * Application properties from docProps/app.xml for PPTX
 *
 * Contains PowerPoint-specific document metadata.
 */
export interface PptxAppProperties {
  /** Application name (e.g., "Microsoft Office PowerPoint") */
  readonly application?: string;
  /** Application version */
  readonly appVersion?: string;
  /** Total editing time in minutes */
  readonly totalTime?: number;
  /** Company name */
  readonly company?: string;
  /** Document security level */
  readonly docSecurity?: number;
  /** Scale crop flag */
  readonly scaleCrop?: boolean;
  /** Links up to date flag */
  readonly linksUpToDate?: boolean;
  /** Shared document flag */
  readonly sharedDoc?: boolean;
  /** Hyperlinks changed flag */
  readonly hyperlinksChanged?: boolean;
  /** Number of slides */
  readonly slides?: number;
  /** Number of notes */
  readonly notes?: number;
  /** Number of hidden slides */
  readonly hiddenSlides?: number;
  /** Number of multimedia clips */
  readonly multimediaClips?: number;
  /** Presentation format (e.g., "Widescreen", "Standard") */
  readonly presentationFormat?: string;
  /** Slide titles */
  readonly slideTitles?: Array<string>;
}

/**
 * PowerPoint (PPTX) extraction result.
 *
 * Contains extracted slide content, metadata, and embedded images/tables.
 */
export interface PptxExtractionResult {
  /** Extracted text content from all slides */
  readonly content: string;
  /** Presentation metadata */
  readonly metadata: PptxMetadata;
  /** Total number of slides */
  readonly slideCount: number;
  /** Total number of embedded images */
  readonly imageCount: number;
  /** Total number of tables */
  readonly tableCount: number;
  /** Extracted images from the presentation */
  readonly images: Array<ExtractedImage>;
  /** Slide structure with boundaries (when page tracking is enabled) */
  readonly pageStructure?: PageStructure;
  /** Per-slide content (when page tracking is enabled) */
  readonly pageContents?: Array<PageContent>;
  /** Structured document representation */
  readonly document?: DocumentStructure;
  /** Hyperlinks discovered in slides. */
  readonly hyperlinks: Array<PresentationHyperlink>;
  /**
   * Office metadata extracted from docProps/core.xml and docProps/app.xml.
   *
   * Contains keys like "title", "author", "created_by", "subject", "keywords",
   * "modified_by", "created_at", "modified_at", etc.
   */
  readonly officeMetadata: Record<string, string>;
  /**
   * Slide comments as revisions.
   *
   * Each `<p:cm>` element in `ppt/comments/comment{N}.xml` becomes a
   * `DocumentRevision { kind: Comment }` with author (resolved from
   * `ppt/commentAuthors.xml`), ISO-8601 timestamp, and
   * `RevisionAnchor.Slide { index }`. `None` when no comment XML parts exist.
   */
  readonly revisions?: Array<DocumentRevision>;
}

/**
 * PowerPoint presentation metadata.
 *
 * Extracted from PPTX files containing slide counts and presentation details.
 */
export interface PptxMetadata {
  /** Total number of slides in the presentation */
  readonly slideCount?: number;
  /** Names of slides (if available) */
  readonly slideNames?: Array<string>;
  /** Number of embedded images */
  readonly imageCount?: number;
  /** Number of tables */
  readonly tableCount?: number;
}

/** HTML preprocessing options for document cleanup before conversion. */
export interface PreprocessingOptions {
  /** Enable HTML preprocessing globally */
  readonly enabled?: boolean;
  /** Preprocessing preset level (Minimal, Standard, Aggressive) */
  readonly preset?: PreprocessingPreset;
  /** Remove navigation elements (nav, breadcrumbs, menus, sidebars) */
  readonly removeNavigation?: boolean;
  /** Remove form elements (forms, inputs, buttons, etc.) */
  readonly removeForms?: boolean;
}

/**
 * HTML preprocessing aggressiveness level.
 *
 * Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
 */
export declare enum PreprocessingPreset {
  /** Minimal cleanup. Remove only essential noise (scripts, styles). */
  Minimal = "Minimal",
  /** Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. */
  Standard = "Standard",
  /** Aggressive cleanup. Remove extensive non-content elements and structure. */
  Aggressive = "Aggressive",
}

/** A hyperlink discovered in a presentation slide. */
export interface PresentationHyperlink {
  /** Link destination. */
  readonly url?: string;
  /** Optional visible label. */
  readonly label?: string;
}

/**
 * A curated structured-extraction preset loaded from the embedded library.
 *
 * Each preset is a JSON file under `src/presets/library/<id>/v1.json` that
 * validates against the meta-schema in `src/presets/preset.schema.json`.
 *
 * Downstream catalog consumers can inject presets via
 * `extend_from_dir`. The embedded OSS library
 * ships only the `generic_document` toy preset.
 */
export interface Preset {
  /** Stable, URL-safe preset identifier (lowercase snake_case). */
  readonly id: string;
  /** Monotonic version string (e.g. `v1`). */
  readonly version: string;
  /** Human-readable schema name forwarded to the LLM as the response/tool name. */
  readonly schemaName: string;
  /** One-line preset description shown in the registry UI. */
  readonly description: string;
  /** Top-level category for grouping in the playground. */
  readonly category: PresetCategory;
  /** Free-form tags used for search/filtering. May be empty. */
  readonly tags: Array<string>;
  /** JSON Schema (Draft 2020-12) describing the structured output shape. */
  readonly schema: JsonValue;
  /** Instruction primer sent to the model. */
  readonly systemPrompt: string;
  /** Optional mustache-style template merged with caller-supplied context. */
  readonly contextTemplate?: string;
  /** Strategy for merging per-batch outputs across paginated calls. */
  readonly mergeMode: MergeMode;
  /** Default call mode suggested for this preset; heuristics may override. */
  readonly preferredCallMode: CallMode;
  /**
   * When true, the prompt asks the model to wrap each field as
   * `{value, page, bbox, confidence}` for downstream citation overlays.
   */
  readonly emitCitations: boolean;
  /** Optional bundled sample (input file + reference output) for preview. */
  readonly sample?: PresetSample;
  /**
   * Stable sha256 fingerprint of the canonical preset file contents.
   *
   * Populated at registry load — not present in the on-disk JSON files.
   * Used as a cache-invalidation token by the worker pipeline.
   */
  readonly fingerprint: string;
}

/** High-level category used to group presets in the registry UI. */
export declare enum PresetCategory {
  /** Invoices, receipts, statements, purchase orders, W-9. */
  Finance = "finance",
  /** Passports, drivers licenses, insurance cards. */
  Identity = "identity",
  /** Contracts, NDAs, agreements. */
  Legal = "legal",
  /** Bills of lading, customs declarations, packing lists. */
  Logistics = "logistics",
  /** Clinical records, lab reports. */
  Medical = "medical",
  /** Pay stubs, resumes, employment offers. */
  Hr = "hr",
  /** Catch-all for documents that don't fit the other categories. */
  Other = "other",
}

/** Pointer to a sample input + its reference output bundled with the preset. */
export interface PresetSample {
  /** Path to the sample input file, relative to the preset directory. */
  readonly inputPath: string;
  /** Path to the reference structured output, relative to the preset directory. */
  readonly outputPath: string;
}

/**
 * Lightweight projection of `Preset` used by the registry list endpoint
 * (omits the full schema and prompt to keep the payload small).
 */
export interface PresetSummary {
  /** Preset identifier matching `Preset.id`. */
  readonly id: string;
  /** Preset version matching `Preset.version`. */
  readonly version: string;
  /** Schema name matching `Preset.schema_name`. */
  readonly schemaName: string;
  /** One-line preset description. */
  readonly description: string;
  /** Top-level category. */
  readonly category: PresetCategory;
  /** Free-form tags. */
  readonly tags: Array<string>;
  /** Default call mode. */
  readonly preferredCallMode: CallMode;
  /** Whether the preset prompts the model for citations. */
  readonly emitCitations: boolean;
  /** Stable fingerprint matching `Preset.fingerprint`. */
  readonly fingerprint: string;
}

/** Outcome of a single doctor check. */
export declare enum ProbeStatus {
  /** The backend or setting will work as configured. */
  Pass = "pass",
  /**
   * The check ran and found something actionable, but nothing is broken
   * (e.g. stray cache files, stale model revisions). Never fails the report.
   */
  Warn = "warn",
  /** The configured setup will not work (or will silently degrade) on this host. */
  Fail = "fail",
  /**
   * The check cannot run locally (e.g. model not cached, feature not compiled in);
   * first real use decides, possibly after a download.
   */
  Skip = "skip",
}

/**
 * Processing stages for post-processors.
 *
 * Post-processors are executed in stage order (Early → Middle → Late).
 * Use stages to control the order of post-processing operations.
 */
export declare enum ProcessingStage {
  /**
   * Early stage - foundational processing.
   *
   * Use for:
   * - Language detection
   * - Character encoding normalization
   * - Entity extraction (NER)
   * - Text quality scoring
   */
  Early = "Early",
  /**
   * Middle stage - content transformation.
   *
   * Use for:
   * - Keyword extraction
   * - Token reduction
   * - Text summarization
   * - Semantic analysis
   */
  Middle = "Middle",
  /**
   * Late stage - final enrichment.
   *
   * Use for:
   * - Custom user hooks
   * - Analytics/logging
   * - Final validation
   * - Output formatting
   */
  Late = "Late",
}

/**
 * A non-fatal warning from a processing pipeline stage.
 *
 * Captures errors from optional features that don't prevent extraction
 * but may indicate degraded or incomplete results. Inspect these independently
 * from `ExtractedDocument.quality_score`, which assesses retained text only.
 */
export interface ProcessingWarning {
  /**
   * The pipeline stage or feature that produced this warning
   * (e.g., "embedding", "chunking", "language_detection", "output_format").
   */
  readonly source: string;
  /** Human-readable description of what went wrong. */
  readonly message: string;
}

/**
 * A single run-level or style-level property change.
 *
 * Used for revisions that change formatting rather than text content. `from`
 * and `to` store normalized property values when the source format exposes
 * them; either side may be absent when the format only records one side of the
 * change.
 */
export interface PropertyChange {
  /** Property name, such as `"bold"`, `"italic"`, `"font_size"`, or `"font_color"`. */
  readonly name: string;
  /** Value before the change, when available. */
  readonly from?: string;
  /** Value after the change, when available. */
  readonly to?: string;
}

/** Proxy configuration for HTTP requests. */
export interface ProxyConfig {
  /** Proxy URL (e.g. "http://proxy:8080", "socks5://proxy:1080"). */
  readonly url?: string;
  /** Optional username for proxy authentication. */
  readonly username?: string;
  /** Optional password for proxy authentication. */
  readonly password?: string;
}

/** Page Segmentation Mode for Tesseract OCR. */
export declare enum PSMMode {
  /** Orientation and script detection only. */
  OsdOnly = "OsdOnly",
  /** Automatic page segmentation with OSD. */
  AutoOsd = "AutoOsd",
  /** Automatic page segmentation without OSD or OCR. */
  AutoOnly = "AutoOnly",
  /** Fully automatic page segmentation with no OSD (default). */
  Auto = "Auto",
  /** Assume a single column of text of variable sizes. */
  SingleColumn = "SingleColumn",
  /** Assume a single uniform block of vertically aligned text. */
  SingleBlockVertical = "SingleBlockVertical",
  /** Assume a single uniform block of text. */
  SingleBlock = "SingleBlock",
  /** Treat the image as a single text line. */
  SingleLine = "SingleLine",
  /** Treat the image as a single word. */
  SingleWord = "SingleWord",
  /** Treat the image as a single word in a circle. */
  CircleWord = "CircleWord",
  /** Treat the image as a single character. */
  SingleChar = "SingleChar",
}

/** Outlook PST archive metadata. */
export interface PstMetadata {
  /** Total number of email messages found in the PST archive. */
  readonly messageCount?: number;
}

/** Pixel-space bounding box of a QR code inside its source image. */
export interface QrBoundingBox {
  /** Horizontal pixel offset of the bounding box top-left corner. */
  readonly x: number;
  /** Vertical pixel offset of the bounding box top-left corner. */
  readonly y: number;
  /** Width of the bounding box in pixels. */
  readonly width: number;
  /** Height of the bounding box in pixels. */
  readonly height: number;
}

/** One QR code decoded from an extracted image. */
export interface QrCode {
  /** Decoded payload (text, URL, vCard string, …). */
  readonly payload: string;
  /**
   * Detector-reported confidence in `[0.0, 1.0]`. `None` when the decoder
   * does not expose confidence (the default `rqrr` backend always reports
   * `Some` because successful decode implies high confidence).
   */
  readonly confidence?: number;
  /**
   * Bounding box of the QR code inside the source image, in pixel coordinates
   * (`x`, `y` of the top-left corner; `width`, `height` of the rectangle).
   * `None` if the decoder did not report a bounding box.
   */
  readonly bbox?: QrBoundingBox;
}

/** RAKE-specific parameters. */
export interface RakeParams {
  /** Minimum word length to consider (default: 1). */
  readonly minWordLength?: number;
  /** Maximum words in a keyword phrase (default: 3). */
  readonly maxWordsPerPhrase?: number;
}

/**
 * Pre-computed table markdown for a table detection region.
 *
 * Produced by the TATR-based table structure recognizer and surfaced as part of
 * layout-aware OCR results.  The struct lives here (under `layout-types`, pure-Rust)
 * so that consumers who do not enable `layout-detection` (ORT) can still reference
 * the type in their own code.
 */
export interface RecognizedTable {
  /** Detection bbox that this table corresponds to (for matching). */
  readonly detectionBbox: BBox;
  /** Table cells as a 2D vector (rows × columns). */
  readonly cells: Array<Array<string>>;
  /** Rendered markdown table. */
  readonly markdown: string;
}

/** Configuration for the redaction post-processor. */
export interface RedactionConfig {
  /** Categories to redact. Empty means "every category supported by the engine." */
  readonly categories?: Array<PiiCategory>;
  /** Strategy applied to every match. */
  readonly strategy?: RedactionStrategy;
  /**
   * Optional NER backend — required to redact PERSON / ORGANIZATION / LOCATION
   * categories (the pure-Rust pattern engine only covers regex-detectable PII).
   */
  readonly ner?: NerConfig;
  /**
   * When `true`, chunk byte ranges are kept consistent with the rewritten content by
   * adjusting `byte_start` / `byte_end` after replacement. When `false`, chunk byte
   * ranges still refer to the *original* content offsets — useful when downstream
   * consumers want to map findings back to the original document.
   */
  readonly preserveOffsets?: boolean;
  /**
   * Arbitrary user-supplied literal terms to redact.
   *
   * Each term is treated as a regex hit against the document, surfacing as
   * `PiiCategory.Custom(label)` in `RedactionFinding`
   * where `label` is the per-term label (defaulting to the literal value itself).
   * Case-insensitive by default; set `RedactionTerm.case_sensitive` for exact match.
   *
   * Use this when you need to redact tenant-specific tokens (employee IDs,
   * project codes, internal product names) without writing a custom plugin.
   */
  readonly customTerms?: Array<RedactionTerm>;
  /**
   * Arbitrary user-supplied regex patterns to redact.
   *
   * Same surfacing semantics as `custom_terms`: each
   * hit becomes a `PiiCategory.Custom(label)` finding. Patterns are validated
   * at config-construction time via `RedactionConfig.validate`.
   */
  readonly customPatterns?: Array<RedactionPattern>;
}

/** One redaction event: which span was rewritten, why, and with what. */
export interface RedactionFinding {
  /** Byte-offset start in the original (pre-redaction) `ExtractedDocument.content`. */
  readonly start: number;
  /** Byte-offset end (exclusive) in the original `ExtractedDocument.content`. */
  readonly end: number;
  /** PII category that fired this redaction. */
  readonly category: PiiCategory;
  /** Strategy applied to this finding (mask, hash, token-replace, drop). */
  readonly strategy: RedactionStrategy;
  /**
   * String that replaced the original mention. Always present; for `Drop` the
   * replacement is the empty string.
   */
  readonly replacementToken: string;
}

/**
 * One user-supplied regex pattern to redact.
 *
 * The pattern is compiled with the Rust `regex` crate (no look-around). Case
 * sensitivity is encoded in the pattern via the `(?i)` inline flag when
 * `Self.case_sensitive` is `false`.
 */
export interface RedactionPattern {
  /** Custom category label surfaced in `RedactionFinding.category`. */
  readonly label: string;
  /** Regex pattern (Rust `regex` crate dialect — no look-around). */
  readonly pattern: string;
  /** When `true`, match case-sensitively; otherwise prepend `(?i)` to the regex. */
  readonly caseSensitive: boolean;
}

/**
 * Audit report describing what the redaction processor found and how it replaced it.
 *
 * The redactor returns this alongside the rewritten content so compliance, replay, and
 * audit-log consumers can see exactly what fired. Offsets are relative to the *original*
 * pre-redaction `content` and are intended for audit reconstruction only — the original
 * bytes are dropped at the end of the pipeline.
 */
export interface RedactionReport {
  /** Individual redaction findings in original-source byte order. */
  readonly findings: Array<RedactionFinding>;
  /** Total number of redactions applied across the document. */
  readonly totalRedacted: number;
}

/** Strategy applied when a PII match is rewritten. */
export declare enum RedactionStrategy {
  /** Replace the matched span with a fixed mask token (default `"[REDACTED]"`). */
  Mask = "mask",
  /**
   * Replace with a SHA-256 hash of the original value (truncated to 16 hex chars).
   * Lets downstream consumers do equality joins without recovering the source.
   */
  Hash = "hash",
  /**
   * Replace with a per-category running token (`"[PERSON_1]"`, `"[PERSON_2]"`, …)
   * so the same person referenced twice gets the same token within the document.
   */
  TokenReplace = "token_replace",
  /** Delete the matched span entirely. */
  Drop = "drop",
}

/**
 * One user-supplied literal term to redact.
 *
 * Matched as a regex-escaped substring (so callers do not need to escape
 * metacharacters themselves). Case-insensitive by default — set
 * `Self.case_sensitive` to `true` for exact byte-match semantics.
 */
export interface RedactionTerm {
  /** Custom category label surfaced in `RedactionFinding.category`. */
  readonly label: string;
  /** Literal value to match. Regex metacharacters are escaped automatically. */
  readonly value: string;
  /** When `true`, match the value as-is; otherwise match ASCII-case-insensitively. */
  readonly caseSensitive: boolean;
}

/** Intensity level for the token-reduction pipeline. */
export declare enum ReductionLevel {
  /** No reduction applied; text is returned as-is. */
  Off = "Off",
  /** Remove only the most common stopwords. */
  Light = "Light",
  /** Balanced stopword removal and redundancy filtering. */
  Moderate = "Moderate",
  /** Aggressive filtering; may remove less common content words. */
  Aggressive = "Aggressive",
  /** Maximum compression; prioritizes brevity over completeness. */
  Maximum = "Maximum",
}

/** Classification of a detected layout region that warrants VLM extraction. */
export declare enum RegionKind {
  /** A figure, diagram, chart, or image region. */
  Figure = "Figure",
  /** A densely formatted or complex table. */
  DenseTable = "DenseTable",
  /** A region with complex or mixed layout. */
  ComplexLayout = "ComplexLayout",
  /** A standalone image to caption. */
  Caption = "Caption",
}

/** Sorted map of preset id → `Preset`. */
export declare class Registry {
  /**
   * Build the registry from preset files embedded at compile time under
   * `src/presets/library/`. Validates every file against the meta-schema.
   */
  static loadEmbedded(): Registry;
  /** Return the global registry, loading it on first access. */
  static global(): Registry;
  /** Look up a preset by its identifier. */
  get(id: string): Preset | null;
  /** Materialize a `PresetSummary` list for the public registry endpoint. */
  summaries(): Array<PresetSummary>;
  /** Number of presets currently loaded. */
  len(): number;
  /** Whether the registry contains zero presets. */
  isEmpty(): boolean;
  /**
   * Read raw sample bytes for `<preset_id>` from
   * `library/<id>/samples/<name>`. Returns `None` when the file is absent.
   */
  sampleBytes(presetId: string, name: string): Uint8Array | null;
  /**
   * Load additional preset files from a runtime directory and insert them
   * into this registry.
   *
   * Reads every `*.json` file directly under `dir` (non-recursive),
   * validates each against the meta-schema, and inserts it. Files that fail
   * validation are rejected — the error is returned immediately and the
   * registry is left in a partially-updated state. Existing entries with the
   * same id are overwritten.
   *
   * Returns the number of presets successfully loaded from `dir`.
   *
   * # Use case
   *
   * This is the injection point for downstream catalogs that add curated
   * presets on top of the single embedded OSS preset.
   */
  extendFromDir(dir: string): number;
}

/** Semantic kind of a relationship between document elements. */
export declare enum RelationshipKind {
  /** Footnote marker -> footnote definition. */
  FootnoteReference = "footnote_reference",
  /** Citation marker -> bibliography entry. */
  CitationReference = "citation_reference",
  /** Internal anchor link (`#id`) -> target heading/element. */
  InternalLink = "internal_link",
  /** Caption paragraph -> figure/table it describes. */
  Caption = "caption",
  /** Label -> labeled element (HTML `<label for>`, LaTeX `\label{}`). */
  Label = "label",
  /** TOC entry -> target section. */
  TocEntry = "toc_entry",
  /** Cross-reference (LaTeX `\ref{}`, DOCX cross-reference field). */
  CrossReference = "cross_reference",
}

/**
 * Trait for document renderers that convert extraction results to output strings.
 *
 * Renderers are typically stateless converters that transform extracted
 * content into a specific output format (Markdown, HTML, Djot, plain text,
 * etc.). They participate in the standard `Plugin`
 * lifecycle so custom renderers can be registered from any supported binding
 * language.
 *
 * The format name is exposed via `Plugin.name`. For stateless renderers
 * the `Plugin` lifecycle methods (`version`, `initialize`, `shutdown`) all
 * take no-op defaults and need not be overridden.
 *
 * # Thread Safety
 *
 * Renderers must be `Send + Sync` (inherited from `Plugin`).
 */
export interface Renderer {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Binding-safe rendering entry point for foreign-language plugin bridges.
   *
   * Accepts one public extraction result and returns the rendered output.
   */
  renderResult?(result?: ExtractedDocument | undefined | null): string;
}

/**
 * A single document returned by the reranker, with its position in the input and score.
 *
 * `index` maps back to the caller's original document list, so metadata arrays
 * (e.g. IDs, paths) can be reordered without passing them through the reranker.
 */
export interface RerankedDocument {
  /** Position of this document in the original input `documents` slice. */
  readonly index: number;
  /** Relevance score in `[0, 1]`. Higher means more relevant to the query. */
  readonly score: number;
  /** The document text. */
  readonly document: string;
}

/**
 * Trait for in-process reranker backend plugins.
 *
 * Cross-encoders score `(query, document)` pairs jointly and return a
 * raw logit per document. The crate-level `rerank` dispatcher applies
 * sigmoid to convert logits to `[0, 1]` scores, sorts descending by score,
 * and truncates to `top_k`.
 *
 * Async to match the convention used by `EmbeddingBackend`
 * and other plugin traits. Host-language bridges wrap their synchronous
 * host callables in `spawn_blocking` or the equivalent.
 *
 * # Thread safety
 *
 * Backends must be `Send + Sync + 'static`. They are stored in
 * `Arc<dyn RerankerBackend>` and may be called concurrently from xberg's
 * dispatcher. If the backend's underlying model is not thread-safe, the
 * backend itself must serialize access internally (e.g. via `Mutex<Inner>`).
 *
 * # Contract
 *
 * - `rerank(query, documents)` MUST return exactly `documents.len()` scores.
 *   The dispatcher validates this before sorting and returning to callers;
 *   a non-conforming backend surfaces as a `XbergError.Validation`, not
 *   a panic.
 * - Scores are raw logits in any range — callers must NOT assume `[0, 1]`.
 *   The dispatcher applies sigmoid before sorting.
 * - `rerank` may be called from any thread. Its future must be `Send`
 *   (enforced by `async_trait` when `#[async_trait]` is used on non-WASM
 *   targets).
 * - `shutdown()` (inherited from `Plugin`) may be invoked
 *   concurrently with an in-flight `rerank()` call. Implementations must
 *   tolerate this — letting in-flight calls finish via the `Arc` reference
 *   and only releasing shared state that isn't needed by `rerank`.
 *
 * # Runtime
 *
 * The synchronous `rerank` entry uses
 * `tokio.task.block_in_place` to await the trait's async `rerank`, which
 * requires a multi-thread tokio runtime. Callers running inside a
 * `current_thread` runtime must use `rerank_async` instead.
 */
export interface RerankerBackend {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Score a list of documents against a query.
   *
   * Returns one raw logit per document in the same order as the input.
   * The dispatcher applies sigmoid to convert to `[0, 1]` scores.
   * @throws Implementations should return `Plugin` for
   * backend-specific failures. The dispatcher validates the returned length
   * against `documents.len()` before sorting.
   */
  rerank(query: string, documents: Array<string>): Promise<Array<number>>;
}

/**
 * Configuration for the reranking pipeline.
 *
 * Controls which model to use, how many results to return, and download/cache
 * behavior for local ONNX models.
 */
export interface RerankerConfig {
  /** The reranker model to use (defaults to "balanced" preset if not specified). */
  readonly model?: RerankerModelType;
  /**
   * Return at most this many documents. `None` returns all.
   *
   * Applied after sorting by score, so the highest-scoring documents are kept.
   */
  readonly topK?: number;
  /** Batch size for local ONNX cross-encoder inference. */
  readonly batchSize?: number;
  /**
   * Show model download progress (local ONNX path only).
   *
   * When enabled, transfer progress for the model, tokenizer and config files is reported at
   * `info` level on the `xberg.model_download` target while they download (#279). A warm
   * Hugging Face cache transfers nothing and so reports nothing. Ignored by
   * `RerankerModelType.Llm` and `RerankerModelType.Plugin`, which download no model.
   */
  readonly showDownloadProgress?: boolean;
  /**
   * Optional alternate Hugging Face cache root for model files.
   *
   * When unset, hf-hub follows the standard Hugging Face environment and
   * platform cache conventions.
   */
  readonly cacheDir?: string;
  /**
   * Hardware acceleration for the reranker ONNX model.
   *
   * Controls which execution provider (CPU, CUDA, CoreML, TensorRT) is used for
   * local inference. Defaults to `None` (auto-select per platform).
   */
  readonly acceleration?: AccelerationConfig;
  /**
   * Maximum wall-clock duration (in seconds) for a single `rerank()` call when
   * using `RerankerModelType.Plugin`.
   *
   * Applies only to the in-process plugin path — protects against hung
   * host-language backends. On timeout, the dispatcher returns
   * `Plugin` instead of blocking forever.
   *
   * `None` disables the timeout. The default (60 seconds) is conservative
   * for common in-process inference; increase for large document sets on slow
   * hardware.
   */
  readonly maxRerankDurationSecs?: number;
}

/**
 * Selects how a local ONNX reranker's raw output tensor is turned into a score.
 *
 * - `RerankerHead.CrossEncoder` — classic single-logit cross-encoder head:
 *   the model emits `[batch, 1]` (or `[batch]`) logits; the caller applies
 *   sigmoid to get a `[0, 1]` score. This is the original, unchanged path.
 * - `RerankerHead.Qwen3Generative` — Qwen3 generative-reranker head: the
 *   model emits `[batch, seq, vocab]` logits; the score is `P("yes")` read
 *   from the last token's logits over the "yes"/"no" vocabulary entries,
 *   via a softmax over those two logits. Already a `[0, 1]` probability —
 *   no sigmoid is applied.
 */
export declare enum RerankerHead {
  /** Single-logit cross-encoder head (sigmoid applied by the caller). */
  CrossEncoder = "cross_encoder",
  /** Qwen3 generative-reranker head (softmax over yes/no token logits). */
  Qwen3Generative = "qwen_3_generative",
}

/** Reranker model types supported by Xberg. */
export type RerankerModelType =
  | { type: "preset"; name: string }
  | {
      type: "custom";
      modelId: string;
      modelFile: string;
      additionalFiles: Array<string>;
      maxLength: number;
      head: RerankerHead;
    }
  | { type: "llm"; llm: LlmConfig }
  | { type: "plugin"; name: string };

/**
 * A preset merged with caller-supplied overrides (custom schema, prompt suffix,
 * context map). Output is what the pipeline orchestrator consumes.
 */
export interface ResolvedPreset {
  /** Source preset identifier. */
  readonly id: string;
  /** Source preset version. */
  readonly version: string;
  /** Fingerprint of the source preset file, used as a cache token. */
  readonly fingerprint: string;
  /** Schema name forwarded to the LLM. */
  readonly schemaName: string;
  /** Effective JSON Schema (caller override or the preset's own). */
  readonly schema: JsonValue;
  /** System prompt with rendered context appended. */
  readonly systemPrompt: string;
  /** Merge strategy for paginated outputs. */
  readonly mergeMode: MergeMode;
  /** Preferred call mode. */
  readonly preferredCallMode: CallMode;
  /** Whether the prompt asks for per-field citations. */
  readonly emitCitations: boolean;
}

/**
 * Result-shape selection for extraction results.
 *
 * Distinct from `OutputFormat` (which controls rendering — Plain, Markdown,
 * HTML, etc.). `ResultFormat` controls the *shape* of the result: a unified content
 * blob vs. an element-based decomposition.
 */
export declare enum ResultFormat {
  /** Unified format with all content in `content` field */
  Unified = "unified",
  /** Element-based format with semantic element extraction */
  ElementBased = "element_based",
}

/** Best-effort document location for a revision. */
export type RevisionAnchor =
  | { type: "paragraph"; index: number }
  | { type: "table_cell"; row: number; col: number; tableIndex: number }
  | { type: "page"; index: number }
  | { type: "slide"; index: number }
  | { type: "sheet"; index: number; name: string };

/**
 * The content changes that make up a single revision.
 *
 * For insertions and deletions the `content` field carries the added/removed
 * lines as `DiffLine.Added` / `DiffLine.Removed` entries. For format
 * changes, `property_changes` carries normalized before/after formatting
 * values when the source document exposes them.
 */
export interface RevisionDelta {
  /** Line-level content changes for this revision. */
  readonly content?: Array<DiffLine>;
  /** Cell-level table changes for this revision. */
  readonly tableChanges?: Array<CellChange>;
  /** Formatting or metadata property changes for this revision. */
  readonly propertyChanges?: Array<PropertyChange>;
}

/** Semantic classification of a tracked change. */
export declare enum RevisionKind {
  /** Text or content was inserted. */
  Insertion = "insertion",
  /** Text or content was deleted. */
  Deletion = "deletion",
  /** Run-level formatting (font, size, colour, …) was changed. */
  FormatChange = "format_change",
  /** A reviewer comment or annotation. */
  Comment = "comment",
}

/**
 * Schema-validation outcome surfaced as one of three buckets.
 *
 * Fold into the combined confidence score without leaking internal validation
 * error types.
 */
export declare enum SchemaCompliance {
  /** Every batch validated against the schema. */
  AllValid = "all_valid",
  /** At least one batch validated; at least one did not. */
  PartialValid = "partial_valid",
  /** No batch validated. */
  AllInvalid = "all_invalid",
}

/**
 * Configuration for security limits across extractors.
 *
 * All limits are intentionally conservative to prevent DoS attacks
 * while still supporting legitimate documents.
 */
export interface SecurityLimits {
  /** Maximum uncompressed size for archives (500 MB) */
  readonly maxArchiveSize?: number;
  /** Maximum compression ratio before flagging as potential bomb (100:1) */
  readonly maxCompressionRatio?: number;
  /** Maximum number of files in archive (10,000) */
  readonly maxFilesInArchive?: number;
  /** Maximum nesting depth for structures (1024) */
  readonly maxNestingDepth?: number;
  /**
   * Maximum length of any single XML entity / attribute / token (1 MiB).
   * This is a per-token cap, NOT a total cap — billion-laughs class
   * attacks where a single entity expands to hundreds of MB are caught
   * here, while normal long text content (a paragraph, a CDATA block) is
   * caught by `max_content_size` instead.
   */
  readonly maxEntityLength?: number;
  /** Maximum string growth and decoded image allocation per document (100 MB) */
  readonly maxContentSize?: number;
  /** Maximum iterations per operation */
  readonly maxIterations?: number;
  /** Maximum XML depth (1024 levels) */
  readonly maxXmlDepth?: number;
  /**
   * Maximum aggregate table cells per document (100,000).
   *
   * Raise this for trusted large tabular inputs. Higher values permit
   * proportionally more parsing work and output allocation.
   */
  readonly maxTableCells?: number;
  /**
   * Maximum number of pages (or slides, or frames) in a single document.
   * `None` means unlimited.
   *
   * Checked once the count is known and before any per-page work (OCR, layout
   * detection, rendering) starts. Byte-size limits do not bound page count: a
   * scanned page can compress to a few kilobytes, so a document well under
   * `max_content_size` or `max_archive_size` can still hold thousands of pages
   * of per-page work. Defaults to `None` (unlimited) because a real ceiling
   * here is workload-specific and a low default would silently reject
   * legitimate large documents; callers that want a ceiling set this
   * explicitly.
   *
   * Enforced for: PDF (`extractors.pdf`, page count via `xberg_native_pdf`/`lopdf`),
   * PPTX (`extraction.pptx`, slide count from the archive's slide parts),
   * Keynote (`extractors.iwork.keynote`, slide count from `Index/Slide-*.iwa`
   * entry names), ODP (`extractors.odp`, `draw:page` count in `content.xml`),
   * and multi-frame TIFF images built with the `ocr` feature
   * (`extractors.image`, frame count via the `tiff` crate). Not enforced for
   * any other format, including DOCX, ODT, XLSX, legacy PPT/DOC, Pages/Numbers,
   * and TIFF images when the `ocr` feature is disabled: those formats either
   * have no fixed "page" the crate can count without doing the expensive work
   * itself (DOCX/ODT page count is a layout outcome, not a stored value), or
   * have no per-page pipeline to gate at all. Setting `max_pages` on a
   * document of an unenforced format is silently a no-op, not a guarantee.
   */
  readonly maxPages?: number;
}

/**
 * API server configuration.
 *
 * This struct holds all configuration options for the Xberg API server,
 * including host/port settings, CORS configuration, and upload limits.
 *
 * # Defaults
 *
 * - `host`: "127.0.0.1" (localhost only)
 * - `port`: 8000
 * - `cors_origins`: empty vector (allows all origins)
 * - `max_request_body_bytes`: 104_857_600 (100 MB)
 * - `max_multipart_field_bytes`: 104_857_600 (100 MB)
 * - `job_timeout_secs`: 600 (10 minutes)
 */
export interface ServerConfig {
  /** Server host address (e.g., "127.0.0.1", "0.0.0.0") */
  readonly host?: string;
  /** Server port number */
  readonly port?: number;
  /**
   * CORS allowed origins. Empty vector means allow all origins.
   *
   * If this is an empty vector, the server will accept requests from any origin.
   * If populated with specific origins (e.g., `"https://example.com"`), only
   * those origins will be allowed.
   */
  readonly corsOrigins?: Array<string>;
  /** Maximum size of request body in bytes (default: 100 MB) */
  readonly maxRequestBodyBytes?: number;
  /** Maximum size of multipart fields in bytes (default: 100 MB) */
  readonly maxMultipartFieldBytes?: number;
  /**
   * Fallback timeout, in seconds, for `POST /extract-async` jobs whose request does not
   * pin down `extraction_timeout_secs` (default: 600, 10 minutes).
   *
   * A per-request `extraction_timeout_secs: Some(n)` always overrides this value. An
   * explicit `extraction_timeout_secs: null` deliberately does NOT mean "run unbounded" —
   * it still falls back to this server-configured cap, because an unbounded job on a
   * shared server is a denial-of-service risk.
   */
  readonly jobTimeoutSecs?: number;
}

/** A URL entry from a sitemap. */
export interface SitemapUrl {
  /** The URL. */
  readonly url?: string;
  /** The last modification date, if present. */
  readonly lastmod?: string;
  /** The change frequency, if present. */
  readonly changefreq?: string;
  /** The priority, if present. */
  readonly priority?: string;
}

/**
 * A sparse learned embedding: vocabulary term indices and their weights.
 *
 * `indices` are ascending vocabulary token ids; `values[i]` is the weight for
 * `indices[i]`. The two arrays always have equal length. Only strictly-positive
 * terms are retained, so the representation is genuinely sparse.
 */
export interface SparseEmbedding {
  /** Vocabulary token ids with non-zero weight, ascending. */
  readonly indices: Array<number>;
  /** Weights parallel to `SparseEmbedding.indices`. */
  readonly values: Array<number>;
}

/**
 * Configuration for the sparse-embedding pipeline.
 *
 * Controls which model to use, batching, and download/cache behavior for the
 * local ONNX SPLADE model.
 */
export interface SparseEmbeddingConfig {
  /** The sparse-embedding model to use (defaults to the "opensearch-v3-distill" preset). */
  readonly model?: SparseEmbeddingModelType;
  /**
   * Batch size for local ONNX inference.
   *
   * SPLADE emits a `[seq, vocab]` logit tensor per document, so memory scales
   * with batch size — keep this modest.
   */
  readonly batchSize?: number;
  /** Maximum token sequence length for the tokenizer. */
  readonly maxLength?: number;
  /**
   * Show model download progress (local ONNX path only).
   *
   * When enabled, transfer progress for the model, tokenizer and config files is reported at
   * `info` level on the `xberg.model_download` target while they download (#279). A warm
   * Hugging Face cache transfers nothing and so reports nothing. Ignored by
   * `SparseEmbeddingModelType.Plugin`, which downloads no model.
   */
  readonly showDownloadProgress?: boolean;
  /**
   * Optional alternate Hugging Face cache root for model files.
   *
   * When unset, hf-hub follows the standard Hugging Face environment and
   * platform cache conventions.
   */
  readonly cacheDir?: string;
  /** Hardware acceleration for the sparse-embedding ONNX model. */
  readonly acceleration?: AccelerationConfig;
  /**
   * Maximum wall-clock duration (in seconds) for a single embed call when
   * using `SparseEmbeddingModelType.Plugin`. `None` disables the timeout.
   */
  readonly maxEmbedDurationSecs?: number;
}

/** Sparse-embedding model types supported by Xberg. */
export type SparseEmbeddingModelType =
  | { type: "preset"; name: string }
  | { type: "custom"; modelId: string; modelFile: string; additionalFiles: Array<string>; maxLength: number }
  | { type: "plugin"; name: string };

/** Static metadata for a bundled SPLADE preset (WASM/Android-safe, no ORT). */
export interface SparseEmbeddingPreset {
  /** Stable preset name referenced from config. */
  readonly name: string;
  /** HuggingFace repository hosting the ONNX model. */
  readonly modelRepo: string;
  /** Path to the ONNX file within the repo. */
  readonly modelFile: string;
  /** Sibling files that must be downloaded alongside `model_file`. */
  readonly additionalFiles: Array<string>;
  /** Maximum token sequence length. */
  readonly maxLength: number;
  /** Human-readable description. */
  readonly description: string;
}

/** SSRF policy configuration. */
export interface SsrfPolicy {
  /** If true, reject URLs that resolve to private/metadata IP ranges. */
  readonly denyPrivate?: boolean;
  /**
   * Hostnames and IP ranges permitted regardless of `deny_private`.
   *
   * The allowlist is an *override* of `deny_private`, not an intersection with it.
   * Precedence, in order:
   *
   * 1. `deny_private == false` permits everything; the allowlist is not consulted.
   * 2. A hostname matching an `Exact` or `Suffix` entry is permitted immediately,
   *    *before* DNS resolution — so the deny-list is never applied to it. This trusts
   *    the host string: a name that resolves into private space is still permitted.
   * 3. A literal or resolved IP inside a `Cidr` entry is permitted even though it is
   *    in the default deny-list.
   * 4. Otherwise the default deny-list decides.
   *
   * An empty allowlist therefore denies nothing by itself — it simply leaves
   * `deny_private` and the deny-list in sole control.
   */
  readonly allowlist?: Array<HostMatcher>;
  /** Maximum number of HTTP redirects to follow during validation. */
  readonly maxRedirects?: number;
  /**
   * Allowed URI schemes. Default: `["http", "https"]`.
   *
   * Only `http` and `https` are supported. An empty list denies every URL.
   */
  readonly schemeAllowlist?: Array<string>;
}

/** Structured data (Schema.org, microdata, RDFa) block. */
export interface StructuredData {
  /** Type of structured data */
  readonly dataType: StructuredDataType;
  /** Raw JSON string representation */
  readonly rawJson: string;
  /** Schema type if detectable (e.g., "Article", "Event", "Product") */
  readonly schemaType?: string;
}

/** Result of parsing a structured data file (JSON, JSONL, YAML, or TOML). */
export interface StructuredDataResult {
  /** The extracted text content, formatted for readability. */
  readonly content: string;
  /** The source format identifier (e.g. `"json"`, `"yaml"`, `"toml"`). */
  readonly format: string;
  /** Key-value metadata extracted from recognized text fields. */
  readonly metadata: Record<string, string>;
  /** JSON paths of fields that were classified as text-bearing. */
  readonly textFields: Array<string>;
  /**
   * The parsed document as a canonical `serde_json.Value` tree, when the
   * source format could be represented as one. `None` only for TOML inputs
   * whose `toml.Value` fails to round-trip through `serde_json.Value`
   * (xberg-io/xberg#155): the extractor falls back to a raw code block in
   * that case.
   */
  readonly value?: JsonValue;
  /**
   * Flattened `path: value` renderings for every leaf field, in traversal
   * order. Previously computed and discarded (xberg-io/xberg#166); now
   * surfaced so callers get a full-text view even when the structured
   * renderer only emits headings/lists for a subset of fields.
   */
  readonly flattened: Array<string>;
}

/** Structured data type classification. */
export declare enum StructuredDataType {
  /** JSON-LD structured data */
  JsonLd = "json-ld",
  /** Microdata */
  Microdata = "microdata",
  /** RDFa */
  RDFa = "rdfa",
}

/**
 * Configuration for LLM-based structured data extraction.
 *
 * Sends extracted document content to a VLM with a JSON schema,
 * returning structured data that conforms to the schema.
 * @example
 * ```typescript
 * [structured_extraction]
 * schema_name = "invoice_data"
 * strict = true
 *
 * [structured_extraction.schema]
 * type = "object"
 * properties.vendor = { type = "string" }
 * properties.total = { type = "number" }
 * required = ["vendor", "total"]
 *
 * [structured_extraction.llm]
 * model = "openai/gpt-4o"
 * ```
 */
export interface StructuredExtractionConfig {
  /** JSON Schema defining the desired output structure. */
  readonly schema: JsonValue;
  /** Schema name passed to the LLM's structured output mode. */
  readonly schemaName: string;
  /** Optional schema description for the LLM. */
  readonly schemaDescription?: string;
  /** Enable strict mode — output must exactly match the schema. */
  readonly strict: boolean;
  /**
   * Custom Jinja2 extraction prompt template. When `None`, a default template is used.
   *
   * Available template variables:
   * - `{{ content }}` — The extracted document text.
   * - `{{ schema }}` — The JSON schema as a formatted string.
   * - `{{ schema_name }}` — The schema name.
   * - `{{ schema_description }}` — The schema description (may be empty).
   */
  readonly prompt?: string;
  /** LLM configuration for the extraction. */
  readonly llm: LlmConfig;
}

/** Configuration for the summarisation post-processor. */
export interface SummarizationConfig {
  /** Summarisation strategy. */
  readonly strategy?: SummaryStrategy;
  /** Maximum summary length in tokens. `None` lets the backend pick a default. */
  readonly maxTokens?: number;
  /**
   * LLM configuration for the abstractive backend. Ignored when
   * `strategy = Extractive`. Required when `strategy = Abstractive`.
   */
  readonly llm?: LlmConfig;
}

/** Summarisation strategy. */
export declare enum SummaryStrategy {
  /**
   * Pure-Rust extractive summary (TextRank over the chunk graph). Deterministic,
   * fast, no external service required.
   */
  Extractive = "extractive",
  /**
   * Abstractive summary produced by liter-llm. Requires `liter-llm` feature and
   * a configured `LlmConfig`. Token usage is captured in
   * `ExtractedDocument.llm_usage`.
   */
  Abstractive = "abstractive",
}

/**
 * A supported document format entry.
 *
 * Represents a file extension and its corresponding MIME type that Xberg can process.
 */
export interface SupportedFormat {
  /** File extension (without leading dot), e.g., "pdf", "docx" */
  readonly extension: string;
  /** MIME type string, e.g., "application/pdf" */
  readonly mimeType: string;
}

/**
 * SVG-specific configuration for the image-encode pipeline.
 *
 * Applies when the source image is SVG or when the output format is set to
 * `ImageOutputFormat.Svg`.  Available when the `svg` feature is active.
 *
 * Used via `ImageExtractionConfig.svg`.
 */
export interface SvgOptions {
  /**
   * Run SVG bytes through `usvg` sanitization (strips external `href` attributes,
   * JavaScript event handlers, and `foreignObject` elements) even when the
   * output format is `Native`.  Defaults to `true`.
   */
  readonly sanitize?: boolean;
  /**
   * Target DPI when rasterizing SVG to a pixel-based format (PNG, JPEG, WebP,
   * HEIF).  The tree's viewBox is scaled by `render_dpi / 96.0` before the
   * pixel buffer is allocated.  Defaults to `96.0` (1× CSS pixel density).
   */
  readonly renderDpi?: number;
}

/**
 * Extracted table structure.
 *
 * Represents a table detected and extracted from a document (PDF, image, etc.).
 * Tables are converted to both structured cell data and Markdown format.
 */
export interface Table {
  /** Table cells as a 2D vector (rows × columns) */
  readonly cells?: Array<Array<string>>;
  /** Markdown representation of the table */
  readonly markdown?: string;
  /** Page number where the table was found (1-indexed) */
  readonly pageNumber?: number;
  /**
   * Bounding box of the table's position. Only populated when position data is
   * available from the producing extractor.
   *
   * The coordinate space depends on how the table was produced, and callers must
   * know which route produced a given `Table` before interpreting this field:
   *
   * - Tables extracted from a PDF's native content, and tables recognized on a
   *   scanned PDF page that went through xberg's OCR pipeline (`--force-ocr` /
   *   `--ocr-scanned-pages`), are in **PDF points with a bottom-left origin**
   *   (x0=left, y0=bottom, x1=right, y1=top; y increases upward). For the OCR
   *   case, the pipeline rescales the backend's raw pixel output into this space
   *   before it reaches `Table.bounding_box` — see
   *   `rescale_ocr_bboxes_to_page_points` in `extractors.pdf.ocr`.
   * - Tables detected by OCR on a standalone image with no backing PDF page (for
   *   example extracting a bare PNG/JPEG/TIFF) are in **raster pixel coordinates
   *   with a top-left origin** (x0=left, y0=top, x1=right, y1=bottom; y increases
   *   downward) — the same convention the OCR backend (Tesseract, PaddleOCR,
   *   candle-based backends) or the layout detector reported them in. There is no
   *   PDF page geometry to rescale into for this case, so the raw pixel box is
   *   passed through unchanged.
   */
  readonly boundingBox?: BoundingBox;
  /**
   * Stable identifier shared by every `tables[]` entry that represents a
   * fragment of the same physical table.
   *
   * Assigned deterministically by the extraction pipeline (e.g. a
   * sequential `"table-N"` in document order); never derived from
   * randomness or wall-clock time, so the same input document always
   * produces the same ids. Consumers can use it to reconcile the markdown
   * blocks in `content` / `pages[].content` / `chunks[].content` with the
   * structured entries in `tables[]`. `None` when the extractor did not
   * assign one.
   *
   * Today, same-page fragments of one physical table are already merged
   * into a single `tables[]` entry before ids are assigned (see PDF table
   * stitching), so in practice `table_id` is unique per entry rather than
   * shared across several. A table split across a page boundary is
   * intentionally *not* linked — its per-page pieces get separate ids.
   * Sharing one id across page-boundary fragments is a known possible
   * future extension, not implemented yet.
   */
  readonly tableId?: string;
  /**
   * Paragraph styles carried by individual cells, for the cells that have one.
   *
   * Sparse and flat on purpose. A DOCX banner row -- row 0, one cell spanning the grid,
   * styled `Heading1`..`Heading6` -- is what Word's navigation pane and a `TOC` field treat
   * as the document outline, but as a table cell it reached consumers as anonymous text
   * (GH#1587). `cells` keeps the bare text: prefixing it with `#` would put a markdown
   * heading inside a table cell, which is invalid where it lands and would change text every
   * existing consumer already reads. This list is the signal instead.
   *
   * Entries are only emitted for cells that actually carry a style, so an ordinary table
   * serialises exactly as it did before. Indices are into `cells`.
   */
  readonly cellStyles?: Array<TableCellStyle>;
  /**
   * Header cells for this fragment, i.e. the first row of `cells`.
   *
   * Populated even when this fragment's own header row was merged away or
   * physically lives in a sibling fragment (see `table_id`), so a single
   * fragment is interpretable in isolation. `None` when no header row
   * could be determined.
   */
  readonly columns?: Array<string>;
}

/**
 * Individual table cell with content and optional styling.
 *
 * Future extension point for rich table support with cell-level metadata.
 */
export interface TableCell {
  /** Cell content as text */
  readonly content?: string;
  /** Row span (number of rows this cell spans) */
  readonly rowSpan?: number;
  /** Column span (number of columns this cell spans) */
  readonly colSpan?: number;
  /** Whether this is a header cell */
  readonly isHeader?: boolean;
}

/**
 * The paragraph style a single table cell's text carries, located by grid position.
 *
 * Flat rather than a nested `Vec<Vec<Option<..>>>`: the nested shape marshals badly across the
 * FFI bindings, and the data is sparse anyway. See `Table.cell_styles`.
 */
export interface TableCellStyle {
  /** Zero-indexed row of the cell this style belongs to. */
  readonly row?: number;
  /** Zero-indexed column of the cell this style belongs to. */
  readonly col?: number;
  /** Outline level 1-6 when the style resolves to a heading, otherwise `None`. */
  readonly headingLevel?: number;
  /** Human-readable style name, e.g. `heading 2`. */
  readonly styleName?: string;
}

/**
 * Controls how markdown tables are handled when they exceed the chunk size limit.
 *
 * Only applies when `chunker_type` is `Markdown`.
 *
 * # Variants
 *
 * * `Split` - Default behavior: tables are split at row boundaries like any
 *   other block element. Continuation chunks contain only data rows without
 *   the header, which can break downstream consumers that need column context.
 * * `RepeatHeader` - Prepend the table header (header row + separator row) to
 *   every continuation chunk that contains data rows from the same table.
 *   Adds a small amount of duplicate text but ensures each chunk is
 *   self-contained for extraction, search, and LLM consumption.
 */
export declare enum TableChunkingMode {
  /** Split tables at row boundaries (default). Continuation chunks have no header. */
  Split = "split",
  /** Prepend the table header to every chunk that continues a split table. */
  RepeatHeader = "repeat_header",
}

/** Cell-level changes for a pair of tables that share the same index. */
export interface TableDiff {
  /** Zero-based index of the table in both `a.tables` and `b.tables`. */
  readonly fromIndex: number;
  /** Zero-based index in `b.tables` (equal to `from_index` for same-dimension tables). */
  readonly toIndex: number;
  /** Cell-level changes within the table. */
  readonly cellChanges: Array<CellChange>;
}

/**
 * Structured table grid with cell-level metadata.
 *
 * Stores row/column dimensions and a flat list of cells with position info.
 */
export interface TableGrid {
  /** Number of rows in the table. */
  readonly rows?: number;
  /** Number of columns in the table. */
  readonly cols?: number;
  /** All cells in row-major order. */
  readonly cells?: Array<GridCell>;
}

/**
 * Which table structure recognition model to use.
 *
 * Controls the model used for table cell detection within layout-detected
 * table regions. Wire format is snake_case in all serializers (JSON, TOML,
 * YAML).
 */
export declare enum TableModel {
  /** TATR (Table Transformer) -- default, 30MB, DETR-based row/column detection. */
  Tatr = "tatr",
  /** SLANeXT wired variant -- 365MB, optimized for bordered tables. */
  SlanetWired = "slanet_wired",
  /** SLANeXT wireless variant -- 365MB, optimized for borderless tables. */
  SlanetWireless = "slanet_wireless",
  /** SLANet-plus -- 7.78MB, lightweight general-purpose. */
  SlanetPlus = "slanet_plus",
  /**
   * Classifier-routed SLANeXT: auto-select wired/wireless per table.
   * Uses PP-LCNet classifier (6.78MB) + both SLANeXT variants (730MB total).
   */
  SlanetAuto = "slanet_auto",
  /** Disable table structure model inference entirely; use heuristic path only. */
  Disabled = "disabled",
}

/**
 * How to resolve overlapping native vs layout (TATR/SLANeXT) tables.
 *
 * When both native detection and the layout table model produce a table for
 * the same page region, one must be dropped. This controls which one wins. Wire
 * format is snake_case in all serializers (JSON, TOML, YAML).
 */
export declare enum TableOverlapPreference {
  /**
   * Keep whichever table carries more content (cell count + markdown length).
   * This is the historical default. TATR/SLANeXT tables usually recognize more
   * cells and therefore win, which maximizes table-structure F1 but can lower
   * text F1 when the recognized cell reflow diverges from the source reading order.
   */
  Content = "content",
  /**
   * Prefer the native table when it overlaps a layout table. Native tables
   * preserve the source reading order, which scores higher on text F1 for
   * documents where the layout model's cell reflow diverges from the ground truth.
   */
  Native = "native",
  /** Prefer the layout (TATR/SLANeXT) table when it overlaps a native table. */
  Layout = "layout",
}

/**
 * Tesseract OCR configuration.
 *
 * Provides fine-grained control over Tesseract OCR engine parameters.
 * Most users can use the defaults, but these settings allow optimization
 * for specific document types (invoices, handwriting, etc.).
 *
 * **This is the public-facing counterpart of `ocr.types.TesseractConfig`
 * (the internal, engine-facing representation with `u8`/`String` fields instead of
 * `i32`/`Vec<String>`).** They are two independent struct definitions bridged only by
 * an explicit `From<&TesseractConfig> for crate.ocr.types.TesseractConfig` impl in
 * `ocr/types.rs` — that conversion carries field *values* across, but each struct keeps
 * its own `Default` impl, and the conversion does nothing to keep those two defaults in
 * sync. Several production call sites (`extractors.image.apply_default_tesseract_psm`,
 * `configured_region_ocr`, `sparse_image_ocr_fallback_config`) construct *this* struct's
 * default and convert it, bypassing the internal struct's `Default` entirely — so if the
 * two defaults disagree, standalone image OCR silently uses this struct's value while
 * PDF-embedded OCR (which can reach the internal `Default` directly when no
 * `tesseract_config` is set) uses the other. When changing a default here, also update
 * `ocr.types.TesseractConfig.default`, and vice versa.
 */
export interface TesseractConfig {
  /**
   * Language code(s) for OCR recognition. For Tesseract, languages are joined with "+".
   *
   * A list is the canonical form and the only form accepted by the binding
   * object APIs (Python, Node, PHP, WASM, etc.): `["eng", "deu"]`. When
   * deserializing from a config file, JSON body, or the REST/MCP API, a
   * single string is also accepted, either as one code ("eng") or
   * "+"-joined ("eng+deu").
   */
  readonly language?: Array<string>;
  /**
   * Page Segmentation Mode (1-13).
   *
   * PSM 0 is rejected: Tesseract's `PSM_OSD_ONLY` performs orientation and script
   * detection with no character recognition, so it cannot satisfy a text-extraction
   * request and previously yielded an empty document (GH#1586).
   *
   * `None` (the default) means the caller made no explicit choice: the extraction
   * pipeline applies its own context-appropriate PSM (whole-image PSM 11, vertical-
   * language PSM 5, layout-region PSM 6, or the sparse-text retry's PSM 3) exactly as
   * it would with no `TesseractConfig` at all — see issue #1573. Setting any other
   * field on this struct no longer changes that behaviour.
   *
   * Common explicit values:
   * - 3: Fully automatic page segmentation (native engine default)
   * - 6: Assume a single uniform block of text (WASM engine default — avoids
   *   layout-analysis hang)
   * - 11: Sparse text with no particular order
   */
  readonly psm?: number;
  /** Output format ("text" or "markdown") */
  readonly outputFormat?: string;
  /**
   * OCR Engine Mode (0-3).
   *
   * - 0: Legacy engine only
   * - 1: Neural nets (LSTM) only (usually best)
   * - 2: Legacy + LSTM
   * - 3: Default (based on what's available)
   */
  readonly oem?: number;
  /**
   * Minimum confidence threshold (0.0-100.0).
   *
   * Words with confidence below this threshold may be rejected or flagged.
   */
  readonly minConfidence?: number;
  /**
   * Image preprocessing configuration.
   *
   * Controls how images are preprocessed before OCR. Can significantly
   * improve quality for scanned documents or low-quality images.
   */
  readonly preprocessing?: ImagePreprocessingConfig;
  /** Enable automatic table detection and reconstruction */
  readonly enableTableDetection?: boolean;
  /** Minimum confidence threshold for table detection (0.0-1.0) */
  readonly tableMinConfidence?: number;
  /** Column threshold for table detection (pixels) */
  readonly tableColumnThreshold?: number;
  /** Row threshold ratio for table detection (0.0-1.0) */
  readonly tableRowThresholdRatio?: number;
  /** Enable OCR result caching */
  readonly useCache?: boolean;
  /** Use pre-adapted templates for character classification */
  readonly classifyUsePreAdaptedTemplates?: boolean;
  /**
   * Enable N-gram language model.
   *
   * Kept on by default (see `Self.default` and
   * `ocr.types.TesseractConfig.language_model_ngram_on` for the rationale);
   * keep this field's default in sync with the internal struct's.
   */
  readonly languageModelNgramOn?: boolean;
  /** Don't reject good words during block-level processing */
  readonly tesseditDontBlkrejGoodWds?: boolean;
  /** Don't reject good words during row-level processing */
  readonly tesseditDontRowrejGoodWds?: boolean;
  /** Enable dictionary correction */
  readonly tesseditEnableDictCorrection?: boolean;
  /** Whitelist of allowed characters (empty = all allowed) */
  readonly tesseditCharWhitelist?: string;
  /** Blacklist of forbidden characters (empty = none forbidden) */
  readonly tesseditCharBlacklist?: string;
  /** Use primary language params model */
  readonly tesseditUsePrimaryParamsModel?: boolean;
  /** Variable-width space detection */
  readonly textordSpaceSizeIsVariable?: boolean;
  /** Use adaptive thresholding method */
  readonly thresholdingMethod?: boolean;
}

/**
 * Inline text annotation — byte-range based formatting and links.
 *
 * Annotations reference byte offsets into the node's text content,
 * enabling precise identification of formatted regions.
 */
export interface TextAnnotation {
  /** Start byte offset in the node's text content (inclusive). */
  readonly start: number;
  /** End byte offset in the node's text content (exclusive). */
  readonly end: number;
  /** Annotation type. */
  readonly kind: AnnotationKind;
}

/** Text direction enumeration for HTML documents. */
export declare enum TextDirection {
  /** Left-to-right text direction */
  LeftToRight = "ltr",
  /** Right-to-left text direction */
  RightToLeft = "rtl",
  /** Automatic text direction detection */
  Auto = "auto",
}

/**
 * Plain text and Markdown extraction result.
 *
 * Contains the extracted text along with statistics and,
 * for Markdown files, structural elements like headers and links.
 */
export interface TextExtractionResult {
  /** Extracted text content */
  readonly content: string;
  /** Number of lines */
  readonly lineCount: number;
  /** Number of words */
  readonly wordCount: number;
  /** Number of characters */
  readonly characterCount: number;
  /** Markdown headers (text only, Markdown files only) */
  readonly headers?: Array<string>;
  /** Markdown links (Markdown files only). */
  readonly links?: Array<MarkdownLink>;
  /** Code blocks (Markdown files only). */
  readonly codeBlocks?: Array<MarkdownCodeBlock>;
}

/**
 * Text/Markdown metadata.
 *
 * Extracted from plain text and Markdown files. Includes word counts and,
 * for Markdown, structural elements like headers and links.
 */
export interface TextMetadata {
  /** Number of lines in the document */
  readonly lineCount?: number;
  /** Number of words */
  readonly wordCount?: number;
  /** Number of characters */
  readonly characterCount?: number;
  /** Markdown headers (headings text only, for Markdown files) */
  readonly headers?: Array<string>;
  /** Markdown links (for Markdown files). */
  readonly links?: Array<MarkdownLink>;
  /** Code blocks (for Markdown files). */
  readonly codeBlocks?: Array<MarkdownCodeBlock>;
}

/** Controls which conversion tier is used. */
export declare enum TierStrategy {
  /**
   * Automatically pick the best tier for the input (default).
   *
   * Runs the classifier against the prescan report and uses Tier-1 when
   * eligible; falls back to Tier-2 on bail or when the classifier routes
   * to Tier-2.
   */
  Auto = "auto",
  /** Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. */
  Tier2 = "tier_2",
}

/** Per-category running counter for `RedactionStrategy.TokenReplace`. */
export declare class TokenCounter {
  /** Create a fresh counter with no previous state. */
  static new(): TokenCounter;
}

/**
 * Trait for in-process tokenizer backend plugins.
 *
 * Unlike `EmbeddingBackend`, this trait is **synchronous**:
 * the chunk splitter calls `Self.count_tokens` inside its boundary search,
 * many times per chunk, so counting must be a direct call with no async
 * dispatch. Host-language bridges (PyO3, napi-rs, etc.) invoke their host
 * callable synchronously on the calling thread; implementations should keep
 * `count_tokens` cheap — it dominates chunking time when the backend is slow.
 *
 * # Lifecycle
 *
 * `initialize()` is called once during registration, before any
 * `count_tokens` call; lazy-loading implementations should load their
 * vocabulary there. After registration succeeds, `count_tokens` may be called
 * from any thread, concurrently. `shutdown()` runs on unregistration and may
 * overlap an in-flight `count_tokens` call from a chunking run that resolved
 * the backend earlier — implementations must tolerate this, e.g. by keeping
 * the resources `count_tokens` needs alive via `Arc`.
 *
 * # Thread safety
 *
 * Backends must be `Send + Sync + 'static` (inherited from `Plugin`). They
 * are stored in `Arc<dyn TokenizerBackend>` and called concurrently from
 * xberg's chunking pipeline. If the underlying tokenizer isn't thread-safe,
 * the backend must serialize access internally.
 *
 * # Contract
 *
 * - `count_tokens` must return a non-zero count for non-empty text. The
 *   registry probes this once at registration and rejects backends that
 *   report zero — a zero count would make every span appear to fit any
 *   budget. At runtime, a zero count for non-empty text is not trusted:
 *   the chunker substitutes the character count and logs the substitution.
 *   (An implementation may still return 0 for the empty string.)
 * - `count_tokens` must not panic; return a best-effort count for text the
 *   tokenizer can't fully process.
 * - Counting should be deterministic for a given input — the splitter may
 *   evaluate overlapping spans of the same text repeatedly.
 */
export interface TokenizerBackend {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /** Count the tokens in `text` according to this backend's tokenizer. */
  countTokens(text: string): number;
}

/** Configuration for the token-reduction pipeline. */
export interface TokenReductionConfig {
  /** Reduction intensity level. */
  readonly level?: ReductionLevel;
  /** ISO 639-1 language code hint for stopword selection (e.g. `"en"`, `"de"`). */
  readonly languageHint?: string;
  /** Preserve Markdown formatting tokens during reduction. */
  readonly preserveMarkdown?: boolean;
  /** Preserve code block contents unchanged. */
  readonly preserveCode?: boolean;
  /** Cosine similarity threshold below which sentences are considered dissimilar. */
  readonly semanticThreshold?: number;
  /** Use Rayon parallel iterators for multi-core processing. */
  readonly enableParallel?: boolean;
  /** Use SIMD-optimized text scanning where available. */
  readonly useSimd?: boolean;
  /** Per-language custom stopword lists (`language_code → stopword_list`). */
  readonly customStopwords?: Record<string, Array<string>>;
  /** Regex patterns whose matched text is always preserved unchanged. */
  readonly preservePatterns?: Array<string>;
  /** Target fraction of text to retain (0.0–1.0); `None` = no fixed target. */
  readonly targetReduction?: number;
  /** Group semantically similar sentences and emit only one per cluster. */
  readonly enableSemanticClustering?: boolean;
  /**
   * Skip removal of words with "important" characteristics (all-caps
   * acronyms, words containing digits, mixed-case identifiers, very long
   * words) during the `Aggressive`/`Maximum` common-word removal pass.
   *
   * `true` (the default) protects those words even when they would
   * otherwise be dropped as low-value filler; `false` lets the frequency/
   * length heuristics apply uniformly to every word, including ones that
   * look like acronyms or technical terms (#269).
   */
  readonly preserveImportantWords?: boolean;
}

/** Token reduction configuration. */
export interface TokenReductionOptions {
  /** Reduction mode: "off", "light", "moderate", "aggressive", "maximum" */
  readonly mode?: string;
  /** Preserve important words (capitalized, technical terms) */
  readonly preserveImportantWords?: boolean;
}

/**
 * Configuration for audio/video transcription (speech-to-text).
 *
 * When present and `enabled`, Xberg will route audio and video files
 * (mp3, mp4, m4a, wav, webm, etc.) through the transcription pipeline.
 *
 * The heavy dependencies (ORT, hf-hub, symphonia) are only pulled when the
 * `transcription` feature is enabled. The config struct itself is available
 * under `transcription-types` so that `ExtractionConfig` round-trips on all
 * targets.
 *
 * All fields have sensible defaults. The recommended starting point is:
 *
 * ```toml
 * [extraction.transcription]
 * enabled = true
 * model = "tiny"
 * ```
 */
export interface TranscriptionConfig {
  /**
   * Master switch. When `false`, the transcription pipeline is not run.
   *
   * The extractor is registered for audio/video MIME types whenever the `transcription`
   * feature is compiled in, independently of this flag, so an audio/video input with
   * `enabled = false` fails with an `XbergError.Transcription` explaining how to turn
   * transcription on — it does not fall through to another extractor.
   */
  readonly enabled?: boolean;
  /**
   * Whisper model size to use.
   *
   * Smaller = faster + lower memory. `tiny` is the pragmatic default for
   * first-time users and CI.
   */
  readonly model?: WhisperModel;
  /**
   * Optional language hint (ISO-639-1 code, e.g. "en", "de").
   *
   * When `None` (default), the current engine falls back to English.
   * For deterministic production output, always set this explicitly.
   */
  readonly language?: string;
  /**
   * Whether to request segment-level timestamps.
   *
   * When `true`, the decoder prompt omits `<|notimestamps|>` so the model emits
   * `<|x.xx|>` tokens, and each transcript segment becomes its own paragraph element
   * carrying `start_ms` / `end_ms` attributes. When `false` (default), all segment
   * text is joined into a single flat paragraph with no timing attributes.
   */
  readonly timestamps?: boolean;
  /**
   * Hard safety limit on input duration (milliseconds).
   *
   * Files longer than this are rejected after decode, before model work.
   * Default: 30 minutes. Set to `None` to disable (not recommended for
   * untrusted input).
   */
  readonly maxDurationMs?: number;
  /**
   * Hard safety limit on input size (bytes).
   *
   * Default: 512 MiB. Protects against pathological or malicious uploads.
   */
  readonly maxBytes?: number;
  /**
   * Wall-clock timeout for the entire transcription operation (ms).
   *
   * Bounds audio decode, model resolution/download, and inference together. On expiry
   * the extraction fails with an `XbergError.Transcription`. `None` disables the bound
   * and lets the operation run unbounded (not recommended for untrusted input).
   *
   * Enforced on the async extraction path only; the size and duration caps
   * (`max_bytes`, `max_duration_ms`) are checked on every path.
   *
   * Default: 10 minutes.
   */
  readonly timeoutMs?: number;
  /**
   * Optional alternate Hugging Face cache root for Whisper models.
   *
   * When unset, hf-hub follows `HF_HUB_CACHE`, `HUGGINGFACE_HUB_CACHE`,
   * `HF_HOME`, XDG, and platform defaults. Files remain in the standard
   * content-addressed snapshot layout and are not copied into an Xberg cache.
   */
  readonly modelCacheDir?: string;
  /**
   * Allow network access to download models from Hugging Face Hub.
   *
   * When `false`, only previously cached models may be used. Useful for
   * air-gapped or fully offline deployments.
   */
  readonly allowNetwork?: boolean;
  /**
   * Request SHA256 verification of downloaded model files.
   *
   * Defaults to `false` because the resolver downloads from mutable Hugging
   * Face refs unless callers pin and verify models out-of-band. Explicit
   * `true` requests are rejected by the model resolver until pinned checksum
   * metadata is available.
   */
  readonly verifyHash?: boolean;
}

/**
 * Translation of the extracted content.
 *
 * Holds the translated rendition of `ExtractedDocument.content` and (when
 * `preserve_markup` was requested) the translated `formatted_content`. Chunks
 * are translated in place inside `ExtractedDocument.chunks[*].content` rather
 * than duplicated here.
 */
export interface Translation {
  /** BCP-47 language tag the translation was produced into (e.g. `"de"`, `"fr-CA"`). */
  readonly targetLang: string;
  /** BCP-47 source language. `None` when the translation backend was asked to detect. */
  readonly sourceLang?: string;
  /** Translated plain-text body. Matches the shape of `ExtractedDocument.content`. */
  readonly content: string;
  /**
   * Translated markup body (Markdown / HTML / etc.) when `preserve_markup` was
   * enabled on the config. `None` otherwise.
   */
  readonly formattedContent?: string;
}

/** Configuration for the translation post-processor. */
export interface TranslationConfig {
  /** BCP-47 language tag for the target language (e.g. `"de"`, `"fr-CA"`). */
  readonly targetLang: string;
  /** Optional explicit source language. `None` asks the backend to auto-detect. */
  readonly sourceLang?: string;
  /**
   * Translate the formatted (Markdown/HTML) rendition alongside plain text when
   * `formatted_content` is present.
   */
  readonly preserveMarkup: boolean;
  /** LLM configuration used for translation. */
  readonly llm: LlmConfig;
}

/**
 * Configuration for tree-sitter language pack integration.
 *
 * Controls grammar download behavior and code analysis options.
 *
 * # Example (TOML)
 *
 * ```toml
 * [tree_sitter]
 * languages = ["python", "rust"]
 * groups = ["web"]
 *
 * [tree_sitter.process]
 * structure = true
 * comments = true
 * docstrings = true
 * ```
 */
export interface TreeSitterConfig {
  /**
   * Enable code intelligence processing (default: true).
   *
   * When `false`, tree-sitter analysis is completely skipped even if
   * the config section is present.
   */
  readonly enabled?: boolean;
  /**
   * Custom cache directory for downloaded grammars.
   *
   * When `None`, uses the default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`.
   *
   * Consumed both by the CLI (`tree-sitter download --from-config`,
   * `cache warm`) and by `CodeExtractor` at
   * extraction time, so that a configured cache directory is honoured
   * wherever grammars are looked up or downloaded, not only during an
   * explicit CLI download.
   */
  readonly cacheDir?: string;
  /**
   * Languages to pre-download on init (e.g., `["python", "rust"]`).
   *
   * Consumed only by the CLI's `tree-sitter download --from-config` and
   * `cache warm` commands as a pre-download hint. Extraction itself does
   * not read this field: a given source file always processes with a
   * single, already auto-detected language, so there is nothing for a
   * language allowlist to gate at extraction time.
   */
  readonly languages?: Array<string>;
  /**
   * Language groups to pre-download (e.g., `["web", "systems", "scripting"]`).
   *
   * Consumed only by the CLI's `tree-sitter download --from-config` and
   * `cache warm` commands, for the same reason as `languages` above.
   */
  readonly groups?: Array<string>;
  /** Processing options for code analysis. */
  readonly process?: TreeSitterProcessConfig;
}

/**
 * Processing options for tree-sitter code analysis.
 *
 * Controls which analysis features are enabled when extracting code files.
 */
export interface TreeSitterProcessConfig {
  /** Extract structural items (functions, classes, structs, etc.). Default: true. */
  readonly structure?: boolean;
  /** Extract import statements. Default: true. */
  readonly imports?: boolean;
  /** Extract export statements. Default: true. */
  readonly exports?: boolean;
  /** Extract comments. Default: false. */
  readonly comments?: boolean;
  /** Extract docstrings. Default: false. */
  readonly docstrings?: boolean;
  /** Extract symbol definitions. Default: false. */
  readonly symbols?: boolean;
  /** Include parse diagnostics. Default: false. */
  readonly diagnostics?: boolean;
  /**
   * Extract a hierarchical key/value data tree from data-format files
   * (JSON, YAML, TOML, XML, CSV, etc.). Default: false.
   */
  readonly dataExtraction?: boolean;
  /** Maximum chunk size in bytes. `None` disables chunking. */
  readonly chunkMaxSize?: number;
  /** Content rendering mode for code extraction. */
  readonly contentMode?: CodeContentMode;
}

/** Runtime options accepted by the `candle-trocr` backend. */
export interface TrocrBackendOptions {
  /** Optional model variant; the backend constructor's variant is used when absent. */
  readonly variant?: CandleTrocrVariant;
  /** Optional per-call device override. */
  readonly device?: CandleDevicePreference;
  /** Optional Hugging Face cache root. */
  readonly cacheDir?: string;
  /** Optional immutable Hugging Face model revision. */
  readonly hfRevision?: string;
}

/** Semantic classification of an extracted URI. */
export declare enum UriKind {
  /** A clickable hyperlink (web URL, file link). */
  Hyperlink = "hyperlink",
  /** An image or media resource reference. */
  Image = "image",
  /** An internal anchor or cross-reference target. */
  Anchor = "anchor",
  /** A citation or bibliographic reference (DOI, academic ref). */
  Citation = "citation",
  /** A general reference (e.g. `\ref{}` in LaTeX, `:ref:` in RST). */
  Reference = "reference",
  /** An email address (`mailto:` link or bare email). */
  Email = "email",
}

/**
 * URL encoding strategy for link and image destinations.
 *
 * Controls how special characters in URL destinations are handled when they
 * require escaping to produce valid Markdown.
 *
 * The `Angle` variant (default) wraps the destination in angle brackets:
 * `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch
 * but breaks when the URL itself contains `>`.
 *
 * The `Percent` variant percent-encodes every character that is not an RFC 3986
 * unreserved character or `/`, producing a destination safe for all Markdown
 * parsers: `[text](url%20with%20spaces)`.
 */
export declare enum UrlEscapeStyle {
  /** Wrap destinations that contain spaces or newlines in angle brackets. Default. */
  Angle = "Angle",
  /** Percent-encode all characters that are not RFC 3986 unreserved or `/`. */
  Percent = "Percent",
}

/** URL ingestion and crawl configuration. */
export interface UrlExtractionConfig {
  /** URL extraction mode. */
  readonly mode?: UrlExtractionMode;
  /** Crawlberg crawl configuration used for HTTP(S) URL extraction. */
  readonly crawl?: CrawlConfig;
  /** Optional regex filter for document-discovered URLs. */
  readonly documentUrlPattern?: string;
  /** Maximum URLs to follow per extraction result. */
  readonly maxDocumentUrlsPerResult?: number;
  /** Maximum URLs followed across the whole extraction call. */
  readonly maxTotalUrls?: number;
  /** Allow bare local filesystem path inputs. */
  readonly allowLocalFileInputs?: boolean;
  /** Allow local `file://` URI inputs. */
  readonly allowFileUris?: boolean;
}

/** URL extraction mode. */
export declare enum UrlExtractionMode {
  /** Classify HTTP(S) resources after fetch. */
  Auto = "auto",
  /** Treat the URI as a single remote document/page. */
  Document = "document",
  /** Crawl from the seed URI and extract discovered pages/documents. */
  Crawl = "crawl",
}

/** User-provided chunk configuration. */
export interface UserChunkConfig {
  /** User-specified page ranges (overrides automatic chunking). */
  readonly pageRanges?: Array<PageRange>;
  /** User-specified pages per chunk (overrides automatic calculation). */
  readonly pagesPerChunk?: number;
  /** Force chunking even for small documents. */
  readonly forceChunking?: boolean;
  /** Disable chunking even for large documents. */
  readonly disableChunking?: boolean;
}

/**
 * Trait for validator plugins.
 *
 * Validators check extraction results for quality, completeness, or correctness.
 * Unlike post-processors, validator errors **fail fast** - if a validator returns
 * an error, the extraction fails immediately.
 *
 * # Use Cases
 *
 * - **Quality Gates**: Ensure extracted content meets minimum quality standards
 * - **Compliance**: Verify content meets regulatory requirements
 * - **Content Filtering**: Reject documents containing unwanted content
 * - **Format Validation**: Verify extracted content structure
 * - **Security Checks**: Scan for malicious content
 *
 * # Error Handling
 *
 * Validator errors are **fatal** - they cause the extraction to fail and bubble up
 * to the caller. Use validators for hard requirements that must be met.
 *
 * For non-fatal checks, use post-processors instead.
 *
 * # Thread Safety
 *
 * Validators must be thread-safe (`Send + Sync`).
 */
export interface Validator {
  name(): string;
  version?(): string;
  initialize?(): void;
  shutdown?(): void;
  /**
   * Validate an extraction result.
   *
   * Check the extraction result and return `Ok(())` if valid, or an error
   * if validation fails.
   * @param result - The extraction result to validate
   *
   * @param config - Extraction configuration
   *
   * @returns - `Ok(())` if validation passes
   * - `Err(...)` if validation fails (extraction will fail)
   *
   * @throws - `XbergError.Validation` - Validation failed
   * - Any other error type appropriate for the failure
   *
   * # Example - Content Length Validation
   *
   *
   * # Example - Quality Score Validation
   *
   *
   * # Example - Security Validation
   */
  validate(result?: ExtractedDocument | undefined | null, config?: ExtractionConfig | undefined | null): Promise<void>;
  /**
   * Optional: Check if this validator should run for a given result.
   *
   * Allows conditional validation based on MIME type, metadata, or content.
   * Defaults to `true` (always run).
   * @param result - The extraction result to check
   *
   * @param config - Extraction configuration
   *
   * @returns `true` if the validator should run, `false` to skip.
   */
  shouldValidate?(result?: ExtractedDocument | undefined | null, config?: ExtractionConfig | undefined | null): boolean;
  /**
   * Optional: Get the validation priority.
   *
   * Higher priority validators run first. Useful for ordering validation checks
   * (e.g., run cheap validations before expensive ones).
   *
   * Default priority is 50.
   * @returns Priority value (higher = runs earlier).
   */
  priority?(): number;
}

/**
 * Policy controlling when VLM (Vision Language Model) OCR is used as a fallback.
 *
 * This knob is syntactic sugar over the explicit `OcrPipelineConfig` stage
 * ordering. When `vlm_fallback` is set and `pipeline` is `None`, an equivalent
 * pipeline is synthesised at extraction time:
 *
 * - `VlmFallbackPolicy.Disabled` — no synthesis; single-backend mode (default).
 * - `VlmFallbackPolicy.OnLowQuality` — tries the classical backend first; if the
 *   result scores below `quality_threshold`, tries VLM.
 * - `VlmFallbackPolicy.Always` — skips the classical backend and sends every page
 *   to the VLM.
 *
 * When `OcrConfig.pipeline` is explicitly set, `vlm_fallback` is ignored — the
 * explicit pipeline takes precedence.
 * @throws Both `OnLowQuality` and `Always` require `OcrConfig.vlm_config` to be `Some`.
 * Constructing an `OcrConfig` with one of these policies but no `vlm_config` is
 * detected by `OcrConfig.validate` and will surface as a
 * `Validation` error at extraction time, not a panic.
 */
export type VlmFallbackPolicy =
  | { mode: "disabled" }
  | { mode: "on_low_quality"; qualityThreshold: number }
  | { mode: "always" };

/**
 * Supported Whisper model sizes.
 *
 * These map to published ONNX exports on Hugging Face (onnx-community or
 * similar orgs). The actual filenames and repos are resolved inside the
 * transcription engine.
 */
export declare enum WhisperModel {
  /** Smallest, fastest, lowest quality. Good default for development and CI. */
  Tiny = "tiny",
  /** Reasonable quality/speed tradeoff. */
  Base = "base",
  /** Better accuracy with higher memory and cache use. */
  Small = "small",
  /** High quality; slower and more memory-intensive. */
  Medium = "medium",
  /** Best quality (large-v3). Use only when latency and memory use are acceptable. */
  LargeV3 = "large_v_3",
}

/**
 * Whitespace handling strategy during conversion.
 *
 * Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
 */
export declare enum WhitespaceMode {
  /** Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. */
  Normalized = "Normalized",
  /** Preserve all whitespace exactly as it appears in the HTML. */
  Strict = "Strict",
}

/**
 * Application properties from docProps/app.xml for XLSX
 *
 * Contains Excel-specific document metadata.
 */
export interface XlsxAppProperties {
  /** Application name (e.g., "Microsoft Excel") */
  readonly application?: string;
  /** Application version */
  readonly appVersion?: string;
  /** Document security level */
  readonly docSecurity?: number;
  /** Scale crop flag */
  readonly scaleCrop?: boolean;
  /** Links up to date flag */
  readonly linksUpToDate?: boolean;
  /** Shared document flag */
  readonly sharedDoc?: boolean;
  /** Hyperlinks changed flag */
  readonly hyperlinksChanged?: boolean;
  /** Company name */
  readonly company?: string;
  /** Worksheet names */
  readonly worksheetNames?: Array<string>;
}

/**
 * XML extraction result.
 *
 * Contains extracted text content from XML files along with
 * structural statistics about the XML document.
 */
export interface XmlExtractionResult {
  /** Extracted text content (XML structure filtered out) */
  readonly content: string;
  /** Total number of XML elements processed */
  readonly elementCount: number;
  /** List of unique element names found (sorted) */
  readonly uniqueElements: Array<string>;
}

/**
 * XML metadata extracted during XML parsing.
 *
 * Provides statistics about XML document structure.
 */
export interface XmlMetadata {
  /** Total number of XML elements processed */
  readonly elementCount?: number;
  /** List of unique element tag names (sorted) */
  readonly uniqueElements?: Array<string>;
}

/** YAKE-specific parameters. */
export interface YakeParams {
  /**
   * Window size for co-occurrence analysis (default: 2).
   *
   * Controls the context window for computing co-occurrence statistics.
   */
  readonly windowSize?: number;
}

/** Year range for bibliographic metadata. */
export interface YearRange {
  /** Earliest (minimum) year in the range. */
  readonly min?: number;
  /** Latest (maximum) year in the range. */
  readonly max?: number;
  /** All individual years present in the collection. */
  readonly years: Array<number>;
}

/** List names of all registered document extractors. */
export declare function listDocumentExtractors(): Array<string>;

/**
 * List the names of all registered embedding backends.
 *
 * Used by `xberg-cli`, the api/mcp endpoints, and generated language
 * bindings.
 */
export declare function listEmbeddingBackends(): Array<string>;

/**
 * List every registered OCR backend's name alongside its declared supported languages.
 *
 * This is the capability-enumeration counterpart to `list_ocr_backends`: where that function
 * exposes only backend names, this exposes each backend's `supported_languages()` too, so a
 * consumer (for example, a job-acceptance gate) does not need to hardcode a second list of
 * backend languages.
 *
 * # Determinism
 *
 * The returned vector is sorted by `name`, regardless of registration order or the order
 * reported by the underlying registry. `supported_languages` within each entry is **not**
 * sorted — see `OcrBackendCapabilities.supported_languages` for why.
 *
 * # Cost
 *
 * Calling this is not free for every backend. In particular, `TesseractBackend`'s
 * `supported_languages()` allocates a Tesseract API and initializes it (`init("", "eng")`) the
 * first time it is called, to enumerate installed tessdata languages; subsequent calls are
 * served from a cache.
 * @throws Returns an error only if the registry lock cannot be acquired in the current environment.
 */
export declare function listOcrBackendCapabilities(): Array<OcrBackendCapabilities>;

/**
 * List all registered OCR backends.
 *
 * Returns the names of all OCR backends currently registered in the global registry.
 * @returns A vector of OCR backend names.
 */
export declare function listOcrBackends(): Array<string>;

/**
 * List all registered post-processor names.
 *
 * Returns a vector of all post-processor names currently registered in the
 * global registry.
 * @returns - `Ok(Vec<String>)` - Vector of post-processor names
 * - `Err(...)` if the registry lock is poisoned
 */
export declare function listPostProcessors(): Array<string>;

/**
 * List names of all registered renderers.
 * @throws Returns an error if the registry lock is poisoned.
 */
export declare function listRenderers(): Array<string>;

/**
 * List the names of all registered reranker backends.
 *
 * Used by `xberg-cli`, the api/mcp endpoints, and generated language
 * bindings.
 */
export declare function listRerankerBackends(): Array<string>;

/**
 * List all supported document formats.
 *
 * Returns every file extension Xberg recognizes together with its
 * corresponding MIME type, derived from the central format registry.
 * Formats that have no registered file extension (such as source code,
 * which is detected dynamically) are not included.
 *
 * The static `EXT_TO_MIME` table lists every format the *codebase* knows how
 * to describe, regardless of which Cargo features were compiled in. Advertising
 * that table directly would claim support for extractors that may not exist in
 * this build (see GH#1387). To keep the advertised catalogue honest, the table
 * is intersected with the document extractor registry: an extension is only
 * included if some registered extractor actually claims its MIME type in this
 * build. This can never drift from reality and automatically covers
 * third-party extractors registered at runtime.
 *
 * The list is sorted alphabetically by file extension.
 * @returns A vector of `SupportedFormat` entries sorted by extension, limited to
 * formats with a registered extractor in this build.
 */
export declare function listSupportedFormats(): Array<SupportedFormat>;

/**
 * List the names of all registered tokenizer backends.
 *
 * Used by `xberg-cli`, the api/mcp endpoints, and generated language
 * bindings.
 */
export declare function listTokenizerBackends(): Array<string>;

/** List names of all registered validators. */
export declare function listValidators(): Array<string>;

/**
 * Discover all pages and sitemaps reachable from `uri` without extracting document content.
 *
 * Builds a `crawlberg.CrawlEngine` from `config.crawl`, calls
 * `CrawlEngine.map`, and returns the set of discovered URLs as a
 * `crawlberg.MapResult` (re-exported as `MapResult`).
 *
 * Use this when you need the URL inventory of a site before committing to
 * full document extraction — e.g. to build a crawl queue or validate scope.
 * @throws Returns `Validation` if the crawl configuration fails
 * validation or if the map operation itself fails.
 */
export declare function mapUrl(uri: string, config?: UrlExtractionConfig | undefined | null): Promise<MapResult>;

/**
 * Rank a set of documents against a query by MaxSim score, descending.
 *
 * Mirrors the sort/truncate shape of `crate.reranking`'s `build_results`,
 * minus top-k truncation (callers slice the returned `Vec` themselves).
 *
 * Pure CPU primitive — available without ONNX Runtime.
 */
export declare function maxSimRank(
  query: MultiVectorEmbedding,
  docs: Array<MultiVectorEmbedding>,
): Array<LateInteractionMatch>;

/**
 * Score a query against a document using ColBERT's MaxSim operator: for each
 * query token vector, take the maximum dot product against any document
 * token vector, then sum across query tokens.
 *
 * Returns `0.0` if `query` and `doc` have mismatched dimensionality, if either
 * has zero tokens, or if either is not well-formed per
 * `MultiVectorEmbedding.is_well_formed` (its `data` length does not match
 * `num_tokens * dim`).
 *
 * Pure CPU primitive — available without ONNX Runtime.
 */
export declare function maxSimScore(query: MultiVectorEmbedding, doc: MultiVectorEmbedding): number;

/**
 * Check whether a specific registered OCR backend supports a language.
 *
 * Delegates to the named backend's own `OcrBackend.supports_language`, which is the correct
 * per-language decision — do not infer support (or its absence) from whether
 * `list_ocr_backend_capabilities` reports an empty `supported_languages` list for that
 * backend, since an empty list can mean "does not enumerate" rather than "supports nothing"
 * (see `OcrBackendCapabilities.supported_languages`).
 * @param backend - Name of a registered OCR backend, as returned by `list_ocr_backends`. Lookup is case-insensitive and resolves the same `paddleocr` alias as backend dispatch.
 *
 * @param language - Language code to check (e.g. `"eng"`, `"deu"`).
 *
 * @throws Returns an error if no backend with that name (or alias) is registered.
 */
export declare function ocrBackendSupportsLanguage(backend: string, language: string): boolean;

/**
 * Register a document extractor with the global registry.
 *
 * The extractor is keyed by `name` and indexed for
 * every MIME type returned by
 * `supported_mime_types`.
 * @throws - `Validation` if the plugin name is empty or
 *   contains whitespace.
 * - Any error returned by the extractor's `initialize()` method.
 */
export declare function registerDocumentExtractor(extractor: DocumentExtractor): void;

export declare function registerEmbeddingBackend(impl: EmbeddingBackend): void;

export declare function registerOcrBackend(impl: OcrBackend): void;

export declare function registerPostProcessor(impl: PostProcessor): void;

/**
 * Register a renderer plugin with the global registry.
 *
 * The renderer's format name is taken from `Plugin.name`. Registering a
 * renderer with a name that already exists replaces the previous renderer
 * for that format.
 *
 * # Note on `Result` return type
 *
 * Returns `Result<()>` for cross-language API symmetry required by the alef
 * trait-bridge codegen. The underlying `parking_lot.RwLock` cannot be
 * poisoned (parking_lot provides no poisoning semantics), so this function
 * never returns `Err` in practice.
 */
export declare function registerRenderer(renderer: Renderer): void;

export declare function registerRerankerBackend(impl: RerankerBackend): void;

export declare function registerTokenizerBackend(impl: TokenizerBackend): void;

export declare function registerValidator(impl: Validator): void;

/**
 * Unregister a document extractor by name.
 *
 * Removes the extractor from the global registry and calls its `shutdown()`
 * method. No-op if no extractor with that name is registered.
 * @throws - Any error returned by the extractor's `shutdown()` method.
 */
export declare function unregisterDocumentExtractor(name: string): void;

export declare function unregisterEmbeddingBackend(name: string): void;

export declare function unregisterOcrBackend(name: string): void;

export declare function unregisterPostProcessor(name: string): void;

/**
 * Unregister a renderer by format name.
 * @throws Returns an error if the registry lock is poisoned.
 */
export declare function unregisterRenderer(name: string): void;

export declare function unregisterRerankerBackend(name: string): void;

export declare function unregisterTokenizerBackend(name: string): void;

export declare function unregisterValidator(name: string): void;

/**
 * Verify that an excerpt appears verbatim in source text.
 *
 * Performs exact matching by default. Also tries whitespace-normalized matching
 * (collapsing runs of whitespace on both sides) since PDF-extracted text often
 * has irregular spacing.
 * @param excerpt - The text snippet to find
 *
 * @param source_text - The full source text to search
 *
 * @returns `true` if the excerpt appears (exactly or with normalized whitespace), `false` otherwise.
 */
export declare function verifyExcerpt(excerpt: string, sourceText: string): boolean;