entext

README

entext

Enterprise document conversion toolkit with CLI and embeddable Go API.

Installation

go get github.com/axsh/entext

Requirements

• Go 1.26.4+ (required by github.com/axsh/arctic-tern)
• arctic-tern compatible server endpoint for image analysis
• excel-to-pdf --engine go-native:
  • Windows
  • Installed Microsoft Excel (COM automation)
• pdf-to-image --engine go-native:
  • CGO-enabled Go toolchain
  • go-fitz supported build environment
• Legacy engine (--engine legacy) still depends on external tools:
  • Excel -> PDF: excel-com (Windows Excel COM) or libreoffice
  • PDF -> image: pdftoppm or magick (ImageMagick + PDF delegate)

CLI Usage

entext provides CLI commands under cmd.

bin/entext/excel-to-pdf -i ./sample.xlsx -o ./tmp/pdf --backend auto
bin/entext/excel-to-csv -i ./sample.xlsx -o ./tmp/csv --backend auto
bin/entext/pdf-to-image -i ./tmp/pdf/sample.pdf -o ./tmp/images --format png --backend auto
bin/entext/image-to-markdown -i ./tmp/images/sample_001.png -o ./tmp/md/sample.md
bin/entext/excel-template-analyze -i ./template.xlsx -o ./tmp/structure/template.structure.md
bin/entext/excel-fill --template ./template.xlsx --structure ./tmp/structure/template.structure.md -o ./tmp/filled.xlsx --mode text --max-retries 5

All commands support:

• -i/--input
• --stdin (one path per line)
• -o/--output or --output-dir (command dependent)
• --output-mode path|json

Image-to-markdown tern runtime options:

• image-to-markdown --tern-mode auto|external|inproc
• image-to-markdown --tern-config ./settings/tern/tern-config.yaml
• auto tries --server first and falls back to in-process tern server boot.
• inproc boots github.com/axsh/arctic-tern/server in the same process.

image-to-markdown final output is table-faithful Markdown centered on the source table from the image. Gap judgment is limited to conversion fidelity (faithful transcription from the image) and uses a binary verdict: SUFFICIENT or INSUFFICIENT. Intermediate phase analysis tables and explanatory report sections (for example element inventories or interpretation tables) are not included in the delivered document.

CSV hint options for image-to-markdown:

• --csv-hint <path> (repeatable): inject Excel-derived cell-value CSV into Vision prompts.
• --no-csv-hint-auto: disable automatic CSV lookup (basename match, parent csv/, or sheet-map resolution).
• CSV hints supplement cell text only within the image-visible row scope; rows present in CSV but not visible in the image must not appear in output Markdown.
• Full CSV body is attached only on Phase 2 execute round 1 (scope-filtered excerpt). Classify and Phase 1 execute do not receive CSV content.
• With *.sheet-map.json beside the PDF (../pdf/ from images) and ../csv/{workbook}.sheet-N.csv, the matching sheet CSV is auto-selected from the image basename (e.g. 01_変更履歴.png → workbook.sheet-1.csv).
• When CSV hints are present, table structure (columns, blank rows, nesting layout) still comes from the image (Vision).

Excel template analyze (excel-template-analyze):

• Builds a structure markdown for later fill workflows: Vision semantic structure + excelize cell mapping.
• -i/--input template workbook, -o/--output or --output-dir (<basename>.structure.md).
• Hints (same names as fill): --ref (regexp), --ref-dir (recursive .md), --prompt, --prompt-file.
• --keep-work-dir keeps intermediate PDF/images.
• Tern options mirror image-to-markdown (--tern-mode, --tern-config, --server-url, --agent, --model).
• Go API: AnalyzeExcelTemplate(job, cfg).

Excel fill (excel-fill):

• Fills a template using structure markdown with interactive dialog (--mode text|json).
• Required: --template, --structure, -o/--output.
• Shared hints: --ref, --ref-dir, --prompt, --prompt-file.
• --max-retries (default 5) counts visual verification failures; --continue-retries auto-extends when exhausted.
• After each fill: Excel→PDF→image visual check for cutoff/overflow; issues feed the next rewrite round.
• Go API: FillExcel(job, cfg).

Multimodal vision delivery:

• Classify, simple_text, and phase execute (answer) calls use arctic-tern multimodal SendMessage (text + image ContentPart). Assess, question generation, and final synthesis remain text-only SendText.
• Prompt bodies still include [Attached image: <abs-path>] for debug readability alongside the binary image attachment.
• Image files larger than 20MB are rejected with ErrImageTooLarge before send.

Unattended batch mode (agent guard):

• image-to-markdown is designed for unattended batch execution. With arctic-tern v0.1.2+, user_input_required events are answered automatically (fixed text for free-form prompts; first choice when choices are present).
• Auto-response limit: 3 per SendText / SendImagePrompt; a 4th interactive prompt returns a typed error instead of hanging indefinitely.
• simple_text path may fall back to complex_table when output looks like a question or plan-only text; stream stall errors do not trigger fallback.
• Nightly manual check (06_List regression):

  go run ./cmd/image-to-markdown --tern-mode inproc \
    --tern-config ./settings/tern/tern-config.yaml \
    -i tmp/output/pc/images/06_List_出力選択.png \
    --output-dir tmp/output/pc/md --verbose
  

  Success: finishes within ~10 minutes; Markdown contains プレナビ/44, プレ管理/47, 本ナビ/50 rows.

Backend selection:

• excel-to-pdf --backend auto|libreoffice|excel-com
• excel-to-csv --backend auto|libreoffice|excel-com
  • auto: Windows=excel-com -> libreoffice, non-Windows=libreoffice
• pdf-to-image --backend auto|pdftoppm|magick
  • auto: pdftoppm -> magick
• Specific backend mode does not fallback to other backends.
• auto mode returns aggregated errors with tried backend names and reasons.

Go-native related options:

• excel-to-pdf --engine legacy|go-native
• excel-to-pdf --sheets "1,3,5"
• pdf-to-image --engine legacy|go-native
• pdf-to-image --dpi 200
• pdf-to-image --sheet-map ./tmp/pdf/sample.sheet-map.json

excel-to-pdf writes sidecar metadata (*.sheet-map.json) next to generated PDF. pdf-to-image --engine go-native reads sidecar in the following order:

1. Explicit --sheet-map path
2. Auto-detected <input_pdf_basename>.sheet-map.json in the same directory

Go-native sidecar behavior:

• sheet_entries contains real sheet name, page count, and failure reason when available.
• page_sheet_names is expanded per page and is used for image naming.
• Output naming format is NN_<sanitized_sheet_name>.<ext>.
• If sidecar is missing or page mapping is insufficient, naming falls back to NN_page.<ext>.

Go API Usage

Import the root package:

import "github.com/axsh/entext"

Example:

ctx := context.Background()

pdf, err := entext.ConvertExcelToPDF(ctx, entext.FileJob{
    InputPath: "sample.xlsx",
    OutputDir: "tmp/pdf",
})
if err != nil {
    return err
}

imgs, err := entext.ConvertPDFToImage(ctx, entext.FileJob{
    InputPath: pdf.Paths[0],
    OutputDir: "tmp/images",
}, "png")
if err != nil {
    return err
}

cfg := entext.DefaultImageToMarkdownConfig()
md, err := entext.ConvertImageToMarkdown(ctx, entext.ImageToMarkdownJob{
    InputPath: imgs.Paths[0],
    OutputDir: "tmp/md",
}, cfg)
if err != nil {
    return err
}
_ = md

Backend-explicit API:

pdf, err := entext.ConvertExcelToPDFWithBackend(ctx, entext.FileJob{
    InputPath: "sample.xlsx",
    OutputDir: "tmp/pdf",
}, "excel-com")

imgs, err := entext.ConvertPDFToImageWithBackend(ctx, entext.FileJob{
    InputPath: "tmp/pdf/sample.pdf",
    OutputDir: "tmp/images",
}, "png", "magick")

Go-native options API:

pdf, err := entext.ConvertExcelToPDFWithOptions(ctx, entext.FileJob{
    InputPath: "sample.xlsx",
    OutputDir: "tmp/pdf",
}, entext.ExcelPDFOptions{
    Backend: "auto",
    Engine:  "go-native",
    Sheets:  "1,3,5",
})

imgs, err := entext.ConvertPDFToImageWithOptions(ctx, entext.FileJob{
    InputPath: pdf.Paths[0],
    OutputDir: "tmp/images",
}, "png", entext.PDFImageOptions{
    Backend:      "auto",
    Engine:       "go-native",
    DPI:          300,
    SheetMapPath: pdf.SheetMapPath,
})

Image-to-markdown in-process runtime API:

cfg := entext.DefaultImageToMarkdownConfig()
cfg.TernMode = "inproc"
cfg.TernConfigPath = "settings/tern/tern-config.yaml"
cfg.ServerURL = "http://localhost:3100" // used when tern mode is external/auto

Vault Keyring Utility

features/vault-cli provides keyring setup for tern vault references:

go run ./cmd/vault-cli --help
go run ./cmd/vault-cli set --provider openai --name default --secret "YOUR_KEY"
go run ./cmd/vault-cli set --provider anthropic --name default --secret "YOUR_KEY"
go run ./cmd/vault-cli get --provider openai --name default

These map to:

• vault://providers/openai/default
• vault://providers/anthropic/default

Documentation

Index

• Variables
• func IsValidation(err error) bool
• type ExcelCSVOptions
• type ExcelFillArtifact
  • func FillExcel(ctx context.Context, job ExcelFillJob, cfg ExcelFillConfig) (ExcelFillArtifact, error)
• type ExcelFillConfig
• type ExcelFillJob
• type ExcelPDFOptions
• type ExcelTemplateAnalyzeConfig
• type ExcelTemplateAnalyzeJob
• type FileArtifact
  • func ConvertExcelToCSV(ctx context.Context, job FileJob) (FileArtifact, error)
  • func ConvertExcelToCSVWithOptions(ctx context.Context, job FileJob, opts ExcelCSVOptions) (FileArtifact, error)
  • func ConvertExcelToPDF(ctx context.Context, job FileJob) (FileArtifact, error)
  • func ConvertExcelToPDFWithBackend(ctx context.Context, job FileJob, backend string) (FileArtifact, error)
  • func ConvertExcelToPDFWithOptions(ctx context.Context, job FileJob, opts ExcelPDFOptions) (FileArtifact, error)
  • func ConvertPDFToImage(ctx context.Context, job FileJob, format string) (FileArtifact, error)
  • func ConvertPDFToImageWithBackend(ctx context.Context, job FileJob, format string, backend string) (FileArtifact, error)
  • func ConvertPDFToImageWithOptions(ctx context.Context, job FileJob, format string, opts PDFImageOptions) (FileArtifact, error)
• type FileJob
• type ImageToMarkdownConfig
  • func DefaultImageToMarkdownConfig() ImageToMarkdownConfig
• type ImageToMarkdownJob
• type MarkdownArtifact
  • func ConvertImageToMarkdown(ctx context.Context, job ImageToMarkdownJob, cfg ImageToMarkdownConfig) (MarkdownArtifact, error)
• type PDFImageOptions
• type StructureArtifact
  • func AnalyzeExcelTemplate(ctx context.Context, job ExcelTemplateAnalyzeJob, ...) (StructureArtifact, error)
• type ValidationError
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) Unwrap() error

Variables

var (
	ErrInvalidArgs   = errors.New("invalid arguments")
	ErrInputRequired = errors.New("input is required")
)

Functions

func IsValidation

func IsValidation(err error) bool

Types

type ExcelCSVOptions

type ExcelCSVOptions struct {
	Backend string
	Sheets  string
}

type ExcelFillArtifact

type ExcelFillArtifact struct {
	OutputPath  string
	RetriesUsed int
}

func FillExcel

func FillExcel(ctx context.Context, job ExcelFillJob, cfg ExcelFillConfig) (ExcelFillArtifact, error)

type ExcelFillConfig

type ExcelFillConfig struct {
	ServerURL      string
	Agent          string
	Model          string
	TernMode       string
	TernConfigPath string
	PDFBackend     string
	PDFEngine      string
	ImageBackend   string
	ImageEngine    string
	DPI            int
	Verbose        bool
	Quiet          bool
	Stdin          io.Reader
	Stdout         io.Writer
	Stderr         io.Writer
}

type ExcelFillJob

type ExcelFillJob struct {
	TemplatePath    string
	StructurePath   string
	OutputPath      string
	RefPatterns     []string
	RefDirs         []string
	Prompts         []string
	PromptFiles     []string
	Mode            string
	MaxRetries      int
	ContinueRetries int
}

type ExcelPDFOptions

type ExcelPDFOptions struct {
	Backend string
	Engine  string
	Sheets  string
}

type ExcelTemplateAnalyzeConfig

type ExcelTemplateAnalyzeConfig struct {
	ServerURL      string
	Agent          string
	Model          string
	TernMode       string
	TernConfigPath string
	PDFBackend     string
	PDFEngine      string
	ImageBackend   string
	ImageEngine    string
	DPI            int
	Verbose        bool
	Quiet          bool
}

type ExcelTemplateAnalyzeJob

type ExcelTemplateAnalyzeJob struct {
	InputPath   string
	OutputPath  string
	OutputDir   string
	KeepWorkDir string
	RefPatterns []string
	RefDirs     []string
	Prompts     []string
	PromptFiles []string
}

type FileArtifact

type FileArtifact struct {
	Paths        []string
	SheetMapPath string
}

func ConvertExcelToCSV

func ConvertExcelToCSV(ctx context.Context, job FileJob) (FileArtifact, error)

func ConvertExcelToCSVWithOptions

func ConvertExcelToCSVWithOptions(ctx context.Context, job FileJob, opts ExcelCSVOptions) (FileArtifact, error)

func ConvertExcelToPDF

func ConvertExcelToPDF(ctx context.Context, job FileJob) (FileArtifact, error)

func ConvertExcelToPDFWithBackend

func ConvertExcelToPDFWithBackend(ctx context.Context, job FileJob, backend string) (FileArtifact, error)

func ConvertExcelToPDFWithOptions

func ConvertExcelToPDFWithOptions(ctx context.Context, job FileJob, opts ExcelPDFOptions) (FileArtifact, error)

func ConvertPDFToImage

func ConvertPDFToImage(ctx context.Context, job FileJob, format string) (FileArtifact, error)

func ConvertPDFToImageWithBackend

func ConvertPDFToImageWithBackend(ctx context.Context, job FileJob, format string, backend string) (FileArtifact, error)

func ConvertPDFToImageWithOptions

func ConvertPDFToImageWithOptions(ctx context.Context, job FileJob, format string, opts PDFImageOptions) (FileArtifact, error)

type FileJob

type FileJob struct {
	InputPath string
	OutputDir string
}

type ImageToMarkdownConfig

type ImageToMarkdownConfig struct {
	ServerURL       string
	Agent           string
	Model           string
	TernMode        string
	TernConfigPath  string
	Verbose         bool
	Quiet           bool
	StrictGapJudge  bool
	SaveQuestionLog bool
	RoundSleepMS    int
	PhaseSleepMS    int
	MaxRounds       int
}

func DefaultImageToMarkdownConfig

func DefaultImageToMarkdownConfig() ImageToMarkdownConfig

type ImageToMarkdownJob

type ImageToMarkdownJob struct {
	InputPath     string
	OutputPath    string
	OutputDir     string
	RefPatterns   []string
	CsvHintPaths  []string
	NoCsvHintAuto bool
}

type MarkdownArtifact

type MarkdownArtifact struct {
	MarkdownPath string
	SessionPath  string
}

func ConvertImageToMarkdown

func ConvertImageToMarkdown(ctx context.Context, job ImageToMarkdownJob, cfg ImageToMarkdownConfig) (MarkdownArtifact, error)

type PDFImageOptions

type PDFImageOptions struct {
	Backend      string
	Engine       string
	DPI          int
	SheetMapPath string
}

type StructureArtifact

type StructureArtifact struct {
	StructurePath string
}

func AnalyzeExcelTemplate

func AnalyzeExcelTemplate(ctx context.Context, job ExcelTemplateAnalyzeJob, cfg ExcelTemplateAnalyzeConfig) (StructureArtifact, error)

type ValidationError

type ValidationError struct {
	Err error
}

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error