Installation

The core package is all you need for service mode. The [local] extra adds OCR engines and parsers for running extraction on your own machine.

Authentication

Service Mode

Pass your ClicheFactory API key directly:

Local Mode (BYOK)

Provide your own LLM key — extraction runs on your machine, ClicheFactory handles parsing and orchestration:

Config File

Run the interactive setup to save credentials to ~/.clichefactory/config.toml:

Precedence: explicit factory() args > environment variables > config file > defaults. See Execution Modes for details on local vs. service.

Extraction

Define a schema, create a cliche (extraction pipeline), and extract. Schemas can be Pydantic models or plain dicts.

With Pydantic

With Dict Schema

No Pydantic required — pass a JSON Schema dict:

See Schemas in Core Concepts for detailed schema patterns including nested objects and arrays.

Extraction Modes

Control the accuracy/cost tradeoff per call. See Core Concepts for what each mode does.

When artifact_id is provided, the pipeline mode is defined by the artifact — you don't need to set mode explicitly. For maximum accuracy, trained artifacts can be combined with verification automatically.

Trained Models

Use a trained extraction pipeline by passing the artifact_id from a completed training run:

The trained pipeline knows its data model — the schema you pass is used for local validation only. See Training → Using Trained Models for the full workflow.

Saved Configs (config_id)

Tune a pipeline in the web app — schema, mode, trained model, BYOK model/key — then publish it for REST API access in Pipeline Configs to get a config_id (cfg-...). Pass that ID to extract and the server resolves the whole configuration for you — no need to repeat the schema, mode, or keys in code. Service mode only.

Schemaless — let the config supply the schema

Create a cliche with no schema and pass config_id. The saved config's schema drives extraction and you get a plain dict back:

Typed — keep your Pydantic model

Pass a model in code and the config supplies everything else (mode, trained model, BYOK). You get a validated model instance back:

Document Conversion

Convert any supported document to markdown text:

conversion_mode="fast" skips OCR and sends the file directly to a vision model — useful for speed when the document is image-heavy and the LLM can read it natively. Supported values: "default", "fast".

Supports PDF, images, DOC, DOCX, ODT, XLSX, CSV, EML, and more — see Supported File Types.

Long Documents (chunk + merge)

The single-call extract pipeline is bounded by the LLM context window — roughly ~100 pages per file. For longer documents, use extract_long: it converts the file to markdown once, chunks it, extracts each chunk in parallel, and merges the per-chunk results into a single Pydantic model.

List-valued fields are concatenated across chunks; scalar fields pick the first non-null value by default. Override the merge rule per-field with the resolvers= argument on cliche() or extract_long() — e.g. {"total": "sum_numeric", "line_items": "concat_dedupe_by=sku"}.

Pass include_chunk_results=True to get a LongExtractionResult with per-chunk outputs, resolution traces, warnings and aggregated cost. v1 limitation: extract_long runs the BYOK one-shot path only; mode="trained" | "robust" is rejected.

Full reference (chunkers, resolver aliases, default policy): SDK README — Long documents.

Batch Operations

Process multiple files concurrently:

max_concurrency controls how many files are processed in parallel. Defaults to 5. All keyword arguments are forwarded to the underlying extract() or to_markdown() call.

Async API

Every synchronous method has an _async variant for use in async frameworks like FastAPI, asyncio scripts, or Jupyter notebooks:

All async variants accept the same arguments as their sync counterparts.

Advanced

Partial Results

Return partial data on validation failure instead of raising an error:

When validation passes, a normal result is returned. When it fails, PartialExtraction is returned with .raw (the coerced dict) and .validation_errors (list of Pydantic error dicts) so you can inspect and recover what the model extracted.

Include Document & Costs

Get the parsed document or cost breakdown alongside the extraction result:

When include_doc=True, the return value is a (result, doc) tuple. doc.get_markdown() returns the parsed document text that was sent to the LLM — useful for debugging extraction quality.

Postprocess Hooks

Transform extraction results before they're returned:

Pipeline order: raw LLM dict → system coerce (EU decimals, currency, accounting negatives) → postprocess → Pydantic validation. The function receives and must return a dict.

Parser & OCR Configuration (Local Mode)

Fine-tune parsing at the client or cliche level via ParsingOptions. ParsingOptions has no effect on service-mode extraction. See Processing & OCR for background.

PDF image parser — controls how image-based PDF pages are processed:

docling_vlm requires ocr_model to be configured (it uses a VLM per page). vision_layout is service-only and will raise an error in local mode.

PDF OCR engine — the engine used when OCR is applied to PDF pages:

Image parser — controls OCR for standalone image files (PNG, JPG, etc.):

Full ParsingOptions reference:

Model & OCR Model Override Per Call

Use a different LLM for a specific extraction, or route OCR to a separate (cheaper) model:

ocr_model is used for document parsing / VLM refinement passes (e.g. with pdf_image_parser="docling_vlm" or when OCR falls back to a VLM). If not set, the extraction model is also used for OCR.

Endpoint Configuration

The Endpoint object configures any LLM call — on factory(), cliche(), or per extract():

Text Input

Extract structured data from raw text (no file needed):