Skip to content

feat(api): expose strategy auto-selection on the public API#19

Open
jerefrer wants to merge 1 commit into
OpenPecha:mainfrom
jerefrer:feat/strategy-api
Open

feat(api): expose strategy auto-selection on the public API#19
jerefrer wants to merge 1 commit into
OpenPecha:mainfrom
jerefrer:feat/strategy-api

Conversation

@jerefrer

Copy link
Copy Markdown
Collaborator

Closes #18.

Strategy auto-selection currently lives only in cli_main, so the patch_pdf / extract_pdf_text / build_tounicode_dict API can't auto-select — programmatic callers have to re-implement the scoring. (We do exactly that in the in-browser Easy Tibetan Copy worker.)

API

A new strategy= argument, backed by a resolve_strategy helper in tounicode_core:

patch_pdf(path)                                  # unchanged: default gid tier
patch_pdf(path, strategy="gid-pua-free")         # pin one bundled tree, no scoring
patch_pdf(path, strategy="auto")                 # score every bundled tree, keep best
patch_pdf(path, strategy=["gid", "gid-pua-free"])# score over an explicit subset

The subset form is the one that matters for us: a browser consumer can't afford to auto-try the 139 MB gshape tree, so "auto over these strategies" is what we need.

Design choices (open to your preference)

  • Default unchanged. strategy=None keeps the historical behaviour (default gid tier) and adds no new key to stats, so existing callers are unaffected. I did not flip the API default to "auto" the way the CLI does — that felt like the maintainer's call given the docstring's "the public API is tier 1 (gid)" stance. Easy to change if you'd prefer auto-by-default.
  • When a strategy is given, the winning name is reported as stats["strategy"].
  • font_lookup_dir and strategy are mutually exclusive (raises ValueError).
  • resolve_strategy reuses the existing _select_auto_strategy / _default_strategy_specs; single-name strategies skip scoring; unknown names and uninstalled trees raise clear errors.

Tests

tests/test_api_strategy.py covers: default-unchanged (no strategy key), pinned named tree, subset auto-select picking gid-pua-free on the #16 page, "auto", build_tounicode_dict(strategy=...), and the two error cases. Full suite: 81 passed, 10 skipped locally.

Stacks cleanly on top of #17 (independent file).

Strategy auto-selection previously lived only in `cli_main`; the
`patch_pdf` / `extract_pdf_text` / `build_tounicode_dict` API could not
auto-select, so programmatic callers had to re-implement the scoring.

Add a `strategy=` argument backed by a new `resolve_strategy` helper:

- `strategy=None` (default): unchanged — the default gid tier. No new key
  is added to stats, so existing callers are unaffected.
- `strategy="<name>"`: pin one bundled tree (e.g. "gid-pua-free"), no scoring.
- `strategy="auto"`: score every bundled tree and keep the best.
- `strategy=["gid", "gid-pua-free"]`: score over an explicit ordered subset —
  important for consumers that can't afford to auto-try the 139M gshape tree.

When a strategy is given, the winning name is reported as stats["strategy"].
`font_lookup_dir` and `strategy` are mutually exclusive.

Closes OpenPecha#18.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: expose strategy auto-selection on the patch_pdf/extract_pdf_text API?

1 participant