Skip to content

Steer the auto-backend selector

Every parsecraft convert decides per page which backend converts it. The defaults need no flags: page signals select an intent, the rule table narrows the catalog to that intent's family, and the first candidate that converts wins. This page is for the runs where the defaults are not what you want.

The mechanics live in Routing and auto mode and Auto routing; every flag and spec is listed in the CLI reference. In short: --judge and --backend are mutually exclusive — both choose the lead candidate — while --classifier works with either, and with --no-auto.

Preview the decision

inspect runs the cheapest analysis and prints the route it would take, without converting content:

parsecraft inspect report.pdf
parsecraft inspect report.pdf --json

It previews the default plan (rule table plus the deterministic judge) and forbids OCR with --no-ocr; it takes no --judge, --classifier or --preference. When nothing is eligible it prints routing: unavailable — <reason> and still exits 0, because the analysis itself succeeded.

Rank differently inside the intent

--preference reorders candidates within the family the rules already picked — it never moves a page to a different family:

parsecraft convert report.pdf --preference quality
parsecraft convert report.pdf --preference speed
Axis Effect inside the family
speed / balanced smallest declared VRAM first
quality largest declared VRAM first (a documented proxy, not a quality score)

--preference reaches the deterministic judge in auto mode and the resolved --judge provider alike. --backend already names the lead, so the axis is ignored there.

Lead with one backend

Name the backend you want first, keeping the other eligible candidates as fallbacks (a backend that cannot serve the source is a usage error, exit 2):

parsecraft convert report.pdf --backend docling
parsecraft convert report.pdf --no-auto --backend pymupdf

Let a judge order the candidates

A judge receives the page's intent and the eligible candidates — never the document text — and returns an order. It is opt-in by naming a provider, and it may use the network:

parsecraft judges                                  # providers, model tokens, credentials
parsecraft convert report.pdf --judge ollama/nimble          # local daemon, no credential
parsecraft convert report.pdf --judge zen/jev-1.13-free     # cloud, OPENCODE_API_KEY
parsecraft convert report.pdf --judge typesafe-ai/jev-latest # cloud, TYPESAFE_API_KEY

No extra covers the judge providers: typesafe-sdk and the pdf-inspector classifier ship in the base install, so every provider above works on a plain pip install parsecraft. What remains separate are the extraction engines — add the PDF/OCR backends you want as their own extras.

The spec is provider/model (or provider:model): the provider token names who serves the model, and the model token is everything after the first separator, verbatim — registry paths and :tag suffixes pass through untouched, exactly as the model is named upstream (ollama/hf.co/darkgoatie/TinyJev-4B-GGUF:Q8_0). parsecraft judges is the live list — it reports each provider's model tokens, its credential, and whether this host currently has that credential exported:

$ parsecraft judges
no --judge: the deterministic rule table decides; no provider is resolved and no network is used
typesafe-ai/jev-latest   TYPESAFE_API_KEY (unset)         SDK default base URL
zen/jev-1.13-free        OPENCODE_API_KEY (unset)         https://opencode.ai/zen
ollama/<model>           no credential                    http://localhost:11434
                         verified local models: nimble, tev

Export the credential before the run; a missing key is a typed failure (exit 1, judge unavailable: …) before any backend converts anything. The three shipped providers are the TypeSafe cloud, OpenCode Zen, and a local Ollama daemon — Auto routing covers what each one serves and how the request is built.

ollama/<model> needs a scoring-capable local GGUF (nimble, tev) and ollama ≥ 0.35.

Add OCR-need facts before routing

The classifier runs during analysis, before any routing decision, and can only add OCR-need to a page — a rule-table OCR verdict is never cleared, so it behaves the same in auto mode and under --no-auto:

parsecraft convert scan.pdf --classifier pdfinspector/detect_pdf

pdfinspector/detect_pdf is the shipped provider: a local, model-free text-layer scan (pdf-inspector ships in the base install).

Constrain the run

Flag Effect
--no-ocr forbid OCR backends, wherever a spec or judge would send a page
--max-passes N how many candidates per page are tried before the page fails
--cache / --no-cache reuse the content-addressed conversion cache (the key includes the judge identity)
--verbose keep third-party library output (progress bars, tokenizer and generation advisories); by default it is suppressed, never our own messages

When it fails

Exit Meaning
0 success (including inspect with no eligible backend)
1 analysis or routing failed: a missing extra, an unset credential, an unavailable --judge/--classifier provider, no eligible backend, or a page whose intent has no eligible family (an OCR page with no OCR backend that can run here)
2 usage error: malformed spec, --backend combined with --judge, --no-auto without --backend, ineligible --backend, a judge that crosses the native/OCR boundary, unsupported suffix

One exit 1 case is a host fact rather than a flag mistake: a GPU present but unusable by the installed runtime excludes every GPU-only backend, so an OCR page can fail with no eligible backend for intent 'ocr'. See Auto routing for the rule.

What the selector will not do

The invariants a caller can rely on — a judge re-ranks but never widens the candidate set, families are never crossed, and a classifier cannot remove OCR-need — are defined once in Routing and auto mode and Auto routing.

  • Routing and auto mode — the funnel, eligibility, and dispatch mechanics.
  • Auto routing — hardware inputs, the rule table's thresholds, the classifier's cost profile, the provider contracts.
  • CLI reference — every flag default and the spec tables.
  • Backends — what each candidate can serve, and its cost class.