documents

type Block struct {
	// Type selects which other fields apply: "heading", "paragraph",
	// "list", "table", "code", or "image".
	Type string

	// Level is the heading level (1-6). heading only.
	Level int

	// Text is the block's plain text content. heading, paragraph, and
	// code. For heading/paragraph, Spans takes precedence when non-empty
	// — Text is the fallback plain-text path.
	Text string

	// Spans, when non-empty, renders inline-formatted text (bold/italic
	// runs) instead of Text. heading and paragraph only. Structured
	// spans rather than an inline-markdown string: each span's Text
	// still passes through escapeMarkdown, so a model can never smuggle
	// real Markdown/HTML syntax through a "formatting" field the way it
	// could through a raw markup string — see escapeMarkdown's own doc
	// comment for why that distinction matters.
	Spans []Span

	// Ordered selects a numbered (true) vs bulleted (false) list. list only.
	Ordered bool

	// Items is the list's plain-text entries, one per line. list only.
	// When ItemSpans is non-empty, it takes precedence per item.
	Items []string

	// ItemSpans, when non-empty, gives each list item inline formatting
	// the same way Spans does for heading/paragraph text. list only.
	// Must have the same length as Items when both are set; a shorter
	// ItemSpans falls back to the corresponding Items entry for the
	// missing tail.
	ItemSpans [][]Span

	// Header is the table's column headers. table only.
	Header []string

	// Rows is the table's body, one slice of cells per row. table only.
	Rows [][]string

	// Language is the code block's fenced-block language tag (e.g. "go",
	// "python"); empty renders a plain fence. code only.
	Language string

	// Path is the image's already-resolved, already-trust-validated
	// absolute file path. image only. Like ExtractRequest.Path, this
	// package never validates it — that trust boundary lives at the
	// agent-tool layer (see CreateDocumentTool.DenyReadPaths), the same
	// pattern read_document's Path field already documents.
	Path string

	// Alt is the image's alt text. image only.
	Alt string
}

type CSVExtractor struct {
	// Delimiter is the field separator assumed from the extension: ','
	// for CSV, '\t' for TSV. For .csv it is only a starting point —
	// see sniff.
	Delimiter rune
	// contains filtered or unexported fields
}

type Cell struct {
	Value        any
	Formula      string
	Bold         bool
	Italic       bool
	NumberFormat string
}

type CommandRunner func(ctx context.Context, command string) (stdout, stderr []byte, err error)

type DocAST struct {
	Blocks []Block
}

type DocumentMetadata struct {
	// Kind is the extractor's short format name: "csv", "tsv", "json",
	// "jsonl", "xml", "html", "pdf", "xlsx", "docx", or "pptx".
	Kind string

	// SizeBytes is the source file's size on disk (not the bounded
	// amount actually read).
	SizeBytes int64

	// Columns is the CSV/TSV header row, when the file has one. Empty
	// for other formats.
	Columns []string

	// RowCount is the number of logical rows/records the extractor
	// actually walked (which may be less than the file's true row
	// count when a cap stopped it early — see Warnings for that case).
	RowCount int

	// Shape is a free-form one-line structure summary: JSON top-level
	// keys/types, the XML root element name, or the HTML <title>.
	Shape string

	// Title, Author, and CreationDate are the document's own embedded
	// metadata, when the extractor found any — currently PDF only,
	// read from pdfinfo's output (already fetched for the page count).
	// CreationDate is poppler's own human-readable rendering of the
	// PDF's internal date, not reparsed here. Empty when absent or not
	// supported by the format.
	Title        string
	Author       string
	CreationDate string
}

type DocumentSection struct {
	Label string
	Text  string
}

type DocxExtractor struct {
	// Run is nil-safe: a nil Run skips straight to the native tier,
	// mirroring PDFExtractor's own optional-CommandRunner shape.
	Run CommandRunner
}

type ExtractRequest struct {
	// Path is an already-resolved, already-trust-validated absolute
	// path. Extractors do not re-validate it.
	Path string

	MaxBytes int64
	MaxChars int
	MaxRows  int

	// Offset is where the preview window starts, counted in whatever
	// unit that format's preview is made of: data rows for CSV/TSV/xlsx,
	// records for JSONL, characters for the JSON/XML/HTML/docx text
	// preview, pages for PDF, slides for pptx. One name rather than
	// row_offset/char_offset because every result labels the window it
	// actually returned ("rows 201-400 of 5000"), so the unit is
	// unambiguous exactly where it's read.
	//
	// Skipping still requires streaming through what came before —
	// rows are variable-length and a quoted field may contain newlines,
	// so there is no seek. Skipped content is parsed and discarded
	// rather than retained, so paging costs time, not memory. It does
	// consume the MaxBytes budget, and a window that lies past the cap
	// says so rather than looking like the end of the file.
	Offset int

	// HasHeader overrides CSV/TSV header handling. Nil auto-detects
	// (see firstRowLooksLikeData); non-nil forces the answer, which is
	// the escape hatch for the cases the heuristic cannot get right —
	// a header of bare years, or a headerless file whose first row
	// happens to be all text. Ignored by non-tabular extractors.
	HasHeader *bool

	// MaxPages bounds how many PDF pages are read. PDF-only; every other
	// extractor ignores it.
	MaxPages int

	// OCRLang is the Tesseract language code (or "+"-joined codes, e.g.
	// "eng+fra") passed to the optional PDF OCR fallback tier. PDF-only;
	// every other extractor ignores it. Empty means "let pytesseract use
	// its own default" (English), not "OCR disabled" — the tier's
	// availability is controlled by whether the dependency is reachable
	// at all, not by this field.
	OCRLang string
}

type ExtractResult struct {
	Metadata DocumentMetadata
	Sections []DocumentSection

	// Warnings surfaces truncation and degraded-parse notices — e.g.
	// "stopped at the 5 MiB read cap after 40 rows" or "malformed row
	// 12 skipped". Never silent: a capped or partial read always shows
	// up here.
	Warnings []string
}

type Extractor interface {
	// Match reports whether this extractor handles path, based on its
	// extension. The Phase A format set is self-describing by suffix,
	// so content sniffing isn't needed.
	Match(path string) bool

	Extract(ctx context.Context, req ExtractRequest) (ExtractResult, error)
}

type HTMLExtractor struct{}

type ImageBounds struct {
	X, Y, CX, CY int64
}

type JSONExtractor struct{}

type PDFExtractor struct {
	Run CommandRunner

	// ResolveScript enables the optional pdfplumber-backed table-
	// extraction tier (see extractTablesAndImages) and the optional
	// pytesseract-backed OCR tier (see extractOCR) — both are named by
	// PyHelperScript, so one resolver serves either. Nil-safe: a nil
	// resolver just skips both tiers, same as a nil Run skips
	// extraction entirely — the primary pdftotext-based text extraction
	// never depends on this field.
	ResolveScript ScriptResolver
}

type PptxExtractor struct{}

type PyHelperScript string

type Registry struct {
	// contains filtered or unexported fields
}

type ScriptResolver func(script PyHelperScript) (string, error)

type Sheet struct {
	Name string
	Rows [][]Cell
}

type SheetModel struct {
	Sheets []Sheet
}

type SlideModel struct {
	Title    string
	Bullets  []string
	Notes    string
	Image    string
	ImageAlt string
	Layout   string

	// ImageBounds is the image's placement on the slide, in EMU. Nil
	// reproduces the original fixed right-half placement exactly, so a
	// slide built before this field existed generates byte-identical
	// output. Ignored when Image is empty. Presets and validation
	// against slide dimensions live in the create_document tool layer
	// (internal/agent), which owns the user-facing schema and error
	// messages; this package only draws the rectangle it's given.
	ImageBounds *ImageBounds
}

type Span struct {
	Text         string
	Bold, Italic bool
}

type XLSXExtractor struct{}

type XMLExtractor struct{}