/**
 * The pluggable extraction-provider contract. Tier 1/2 (after raw text/words are
 * obtained) delegate field extraction to a provider, so the engine is a config
 * choice — self-hosted by default, optional LLM when enabled. Tier 0 (e-invoice
 * XML) bypasses providers (it is already perfect structured data).
 */

import type { ExtractionResult } from '../fieldExtractors'
import type { TextItem } from '../pdfTextLayer'

export interface ExtractionInput {
  /** Full plain text (from the PDF text layer or OCR). */
  text: string
  /** Positioned text items (text-layer items or OCR words), for box-based learning. */
  items?: TextItem[]
  /** Rendered page images — only used by a vision-capable LLM provider. */
  pageImages?: Buffer[]
  /** The matched vendor profile (defaults + learned field hints), if any. */
  vendorProfile?: any
}

export interface ExtractionProvider {
  name: string
  extract(input: ExtractionInput): Promise<ExtractionResult>
}