Judge

The optional judge (Optional judge (TypeSafe / Jev)) lives in doc2mark.judge; the TypeSafe client is imported only when a TypeSafeJudge is created. The loader resolves its judge= argument with resolve_judge() and takes the hooks from it with judge_hooks().

A hook is a plain callable that returns the probability of “yes” (0 to 1) or None when it cannot judge. None, an exception or a value outside 0 to 1 (or NaN) leaves the rule’s decision in place:

• legibility_judge(page_text) -> float | None: probability that a PDF page’s text layer is legible (UnifiedDocumentLoader(legibility_judge=...));

• boilerplate_judge(line_text, context) -> float | None: probability that a repeated top/bottom line is page chrome (UnifiedDocumentLoader(boilerplate_judge=...));

• non_content_judge(ocr_text) -> float | None: probability that an OCR answer is only a refusal, an error or a “no readable text” statement (OCRConfig(non_content_judge=...)).

class doc2mark.judge.TypeSafeJudge(*, api_key=None, model='jev-1.13.0', hooks=None, cache_dir=None, cache=None, timeout=2.0, max_workers=4, thresholds=None, suspect_thresholds=None, client=None)

doc2mark’s judge hooks answered by TypeSafe’s Jev (see the module docstring).

Parameters:

• api_key (str | None) – TypeSafe API key; default $TYPESAFE_API_KEY (never logged).

• model (str) – Model version to ask (default: the pinned questions.MODEL). The thresholds are calibrated for the pinned version.

• hooks (None | str | Iterable[str]) – Hooks to answer ("legibility", "boilerplate", "non_content"); default $DOC2MARK_JUDGE_HOOKS or DEFAULT_HOOKS. A hook left out is None.

• cache_dir (None | str | PathLike | bool) – Verdict cache directory (default $DOC2MARK_JUDGE_CACHE or ~/.cache/doc2mark/judge); False keeps verdicts in memory only.

• cache (VerdictCache | None) – A VerdictCache to use instead (overrides cache_dir).

• timeout (float) – Seconds per HTTP attempt; a question gets one retry within RETRY_BUDGET seconds, so one that cannot be answered costs at most about that long.

• max_workers (int) – Questions in flight at once.

• thresholds (Mapping[str, float] | None) – Override the calibrated per-hook thresholds (questions.RAW_THRESHOLDS).

• suspect_thresholds (Mapping[str, float] | None) – Override the flag-only thresholds (questions.RAW_SUSPECT_THRESHOLDS).

• client (Any) – A ready typesafe_sdk.TypeSafeClient (or a stand-in with its system_one); the SDK is not imported then.

Attributes legibility_judge, boilerplate_judge and non_content_judge are the hook callables (None for a hook not answered); pass the judge itself to UnifiedDocumentLoader(judge=...) to wire them all.

Its attributes legibility_judge, boilerplate_judge and non_content_judge are the hook callables (None for a hook it does not answer); unavailable says why it cannot answer at all (no extra, no key, key rejected), or is None.

close()

Release the HTTP client (a new one is created on the next question).

Return type:

None

probability(hook, *args)

Jev’s raw probability for one hook’s question (args as the hook takes them), without the hook’s rescaling; None when it cannot answer.

Parameters:

hook (str)

Return type:

float | None

usage()

Totals since the judge was created: requests, cache hits, failures, tokens, cost and the latency (p50/p95, ms) of the fresh requests.

Return type:

Dict[str, Any]

verdict(hook, *args)

The cached or fresh Verdict for one hook’s question (for evaluation).

Parameters:

hook (str)

Return type:

Verdict | None

doc2mark.judge.resolve_judge(judge=None)

The judge object for a judge setting, or None.

None reads $DOC2MARK_JUDGE (an unknown value there is ignored with a warning); "none" is no judge; "typesafe" creates a TypeSafeJudge; any other object is returned as it is. An unknown name raises ValueError.

Parameters:

judge (Any)

Return type:

Any

doc2mark.judge.judge_hooks(judge)

The hook callables of a judge object, by attribute name (None where it has none).

Parameters:

judge (Any)

Return type:

Dict[str, Callable[[…], float | None] | None]