Presets

Presets

A preset is a pre-tuned Orchestrator recipe plus a schema for a specific document type. It picks the right splitter, Worker, prompt, and reconstruct/export steps for a kind of document so you don’t have to.

import scriva

invoice = scriva.presets.invoice("acme.pdf")
receipt = scriva.presets.receipt("rest.jpg")

Every preset is callable for the one-shot case and exposes a .recipe() builder for the case where you want to inspect, tweak, or re-use:

recipe = scriva.presets.invoice.recipe(model="claude-opus-4-7")
result = recipe("acme.pdf")
invoice = result.fields                                  # -> Invoice

The shorthand scriva.presets.invoice("acme.pdf") and the explicit recipe = scriva.presets.invoice.recipe(); result = recipe("acme.pdf") are equivalent.

Catalogue

Preset	Schema	Splitter	Default Worker
presets.invoice	schemas.Invoice	whole page + table-aware	Worker.openai("gpt-4o")
presets.receipt	schemas.Receipt	whole page	Worker.openai("gpt-4o")
presets.id_card	schemas.IdCard	whole page	Worker.openai("gpt-4o")
presets.passport	schemas.Passport	whole page + MRZ band	Worker.openai("gpt-4o")
presets.business_card	schemas.BusinessCard	whole page	Worker.openai("gpt-4o")
presets.contract	schemas.Contract	block segmentation	Worker.anthropic("claude-opus-4-7")
presets.bank_statement	schemas.BankStatement	grid + cross-page stitch	Worker.openai("gpt-4o")
presets.resume	schemas.Resume	block segmentation	Worker.openai("gpt-4o")
presets.medical_form	schemas.MedicalForm	grid	Worker.openai("gpt-4o")
presets.prescription	schemas.Prescription	whole page	Worker.openai("gpt-4o")
presets.purchase_order	schemas.PurchaseOrder	whole page + table	Worker.openai("gpt-4o")
presets.shipping_label	schemas.ShippingLabel	whole page	Worker.openai("gpt-4o")
presets.cheque	schemas.Cheque	whole page + MICR band	Worker.openai("gpt-4o")
presets.tabular_form	schemas.TabularForm	.split.grid()	Worker.openai("gpt-4o")
presets.handwritten_notes	schemas.Notes	block segmentation	Worker.anthropic("claude-opus-4-7")

Worker defaults are picked per document kind for empirical accuracy on a public benchmark suite — they are not endorsements. You can swap any of them with a single argument.

Customising a preset

Every preset accepts the same kwargs as scriva.extract:

invoice = scriva.presets.invoice(
    "acme.pdf",
    model="claude-opus-4-7",                 # swap the Worker engine model
    locale="en",
    cache=".scriva_cache",
    timeout_s=60.0,
    max_cost_usd=0.20,
)

If you need deeper changes, grab the underlying recipe and replace or insert steps:

from scriva import Worker

recipe = scriva.presets.invoice.recipe()
recipe = recipe.replace("recognize", Worker.bedrock("qwen.qwen3-vl-235b-a22b"))
recipe = recipe.insert_after(
    "reconstruct",
    scriva.reconstruct.dictionary.from_yaml("vendors.yaml"),
)
result = recipe("acme.pdf")

.replace, .insert_after, and .remove are described in Orchestrator › Replacing and re-using steps.

Preset structure

A preset is a thin dataclass:

class Preset:
    name: str
    schema: type[BaseModel]
    kind: DocumentKind
    description: str

    def __call__(self, source, **kwargs) -> BaseModel: ...
    def recipe(self, **overrides) -> Orchestrator: ...
    def with_overrides(self, **kwargs) -> "Preset": ...

with_overrides is the right shape when you want a new preset with permanent changes, not a one-shot call:

acme_invoice = scriva.presets.invoice.with_overrides(
    model="claude-opus-4-7",
    schema=AcmeInvoice,
    extra_reconstruct=[scriva.reconstruct.dictionary.from_yaml("acme-vendors.yaml")],
)

invoice = acme_invoice("acme.pdf")

AcmeInvoice can subclass schemas.Invoice to add fields — see Schemas › Extending a built-in.

Registering your own

from scriva.presets import register, Preset
from scriva import Orchestrator, Worker
from scriva.prompts import Prompt
from scriva.schemas import TabularForm

class LabPanel(TabularForm):
    patient_name: str
    glucose_mg_dl: float
    cholesterol_mg_dl: float

@register("lab_panel")
class LabPanelPreset(Preset):
    schema = LabPanel
    kind = scriva.DocumentKind.MEDICAL_FORM
    description = "Routine blood panel (en/ja)"

    def recipe(self, **kw):
        worker = Worker.openai(
            model=kw.get("model", "gpt-4o"),
            prompt=Prompt.structured(schema=LabPanel),
        ).cache(kw.get("cache", ".scriva_cache"))

        return (
            Orchestrator()
            .split.whole_page()
            .recognize(worker)
        )

# Now available as scriva.presets.lab_panel
result = scriva.presets.lab_panel("scan.pdf")

Registered presets also appear in:

• scriva.classify_document candidate set (so auto-routing finds them).
• scriva extract --preset lab_panel on the CLI.
• scriva.presets.list() for discovery.

Auto-routing

scriva.extract("unknown.pdf")                # classifies then routes to the preset
scriva.classify_document("unknown.pdf")      # just classifies

The classifier uses a small vision-language pass against the first page; its candidates are restricted to registered presets. See scriva.classify_document.

What to read next

• scriva.extract — the schema-first one-liner that resolves to a preset.
• Schemas — the pydantic models presets return.
• Domains — pre-built Orchestrator + Worker pairs per document family.
• Cookbook — worked recipes for each preset.