docconv

type Format int

type ImageDescriber interface {
	// DescribeImage returns a text description of an image.
	//
	// img is raw encoded image bytes (PNG, JPEG, ...). mimeType is the image
	// MIME type, useful for APIs that require explicit typing. prompt is the
	// caller-chosen (or library-default) instruction sent to the vision
	// model.
	DescribeImage(ctx context.Context, img []byte, mimeType string, prompt string) (string, error)
}

type Metadata struct {
	Title    string
	Author   string
	Subject  string
	Keywords string
	Created  string
	Modified string
	Pages    int
	Format   string
	Extra    map[string]string
}

type Options struct {
	// LLMClient, when non-nil, is called to describe embedded images
	// (see IncludeImages) and to transcribe pages when OCRFallback is set.
	LLMClient ImageDescriber

	// IncludeImages controls whether embedded images are represented in
	// the markdown output:
	//
	//   - true + LLMClient != nil: images are described inline via
	//     DescribePrompt.
	//   - true + LLMClient == nil: images are referenced with placeholder
	//     alt-text.
	//   - false: images are stripped entirely.
	IncludeImages bool

	// ImageDir is an optional directory where extracted images are
	// written. When empty, images live only in memory.
	ImageDir string

	// IncludeMetadata prepends a YAML front-matter block with document
	// metadata (title, author, page count, created-at) where the source
	// document exposes it.
	IncludeMetadata bool

	// OCRFallback enables LLM-based transcription of documents that have
	// no extractable text. Requires LLMClient != nil. Default false; the
	// library returns ErrNoText in that case.
	//
	// When enabled, the library renders each page via go-fitz and feeds
	// the image to LLMClient.DescribeImage with OCRPrompt. This is slow
	// and costs API credits, so it is strictly opt-in.
	OCRFallback bool

	// OCRDPI is the render resolution used for OCR fallback pages. Zero
	// means use the default (200).
	OCRDPI float64

	// DescribePrompt overrides the default prompt used for embedded-image
	// description.
	//
	// When empty (the default), the library applies DefaultDescribePromptTemplate
	// with the surrounding document text and any author-supplied alt-text
	// spliced in; it also honours the DecorativeMarker sentinel by
	// suppressing images the describer flags as DECORATIVE.
	//
	// When set to a non-empty string, the caller's prompt is used verbatim
	// for every image — surrounding document text and author alt-text are
	// NOT injected, and DecorativeMarker handling is disabled. Callers who
	// want to own prompt semantics take the whole prompt.
	DescribePrompt string

	// OCRPrompt overrides the default prompt used for OCR fallback pages.
	// Empty means use the library default.
	OCRPrompt string

	// IncludeComments, when true, surfaces reviewer comments (currently
	// DOCX word/comments.xml) inline as HTML comments at each anchor
	// position: "<!-- comment by AUTHOR (DATE): TEXT -->". HTML comments
	// survive markdown conversion untouched — invisible in rendered
	// markdown, present in the byte stream that LLMs tokenise.
	//
	// Off by default because reviewer chatter degrades the "what does this
	// document say" signal LLM-agent consumers expect (unresolved
	// disputes can be treated as document claims). Turn on for audit,
	// legal review, or version-archaeology workflows where reviewer
	// context is itself the content of interest.
	IncludeComments bool
}