Skip to content

feat(composition): TokenizerSpec: JSON config as source of truth - #2562

Open
SBrandeis wants to merge 15 commits into
mainfrom
feat/composition-2-tokenizer-spec
Open

SBrandeis wants to merge 15 commits into
mainfrom
feat/composition-2-tokenizer-spec

Conversation

@SBrandeis

@SBrandeis SBrandeis commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR

Introduce TokenizerSpec backing the Tokenizer pyclass in the Python bindings.

TokenizerSpec mirrors the tokenizer.json config in memory, and compiles a PipelineTokenizer from it.

Benefits:

  • Recompile on change. When the pipeline config changes (say, a new normalizer at runtime), we detect it and recompile the PipelineTokenizer on the next encode. Changing padding or truncation never recompiles.
  • Cheap copies. Every value sits behind an Arc, and a copy gets a reference to the compiled pipeline. copy.deepcopy no longer goes through __reduce__ and a full re-compilation.
  • serialize/deserialize identity writing the tokenizer to disk outputs the same json it was loaded from
  • Unified handling of padding and truncation They live in the spec instead of two extra mutexes on the pyclass
  • Pickle and repr now use the JSON config

Visuals

image
Diagram What it shows
1 1-source-of-truth The JSON is the source of truth. The compiled tokenizer is a cache built from it.
2 2-lazy-compile Edits don't compile. The next encode does, once.
3 3-shared-cells Components are shared, like in 0.23.1. Editing one updates every tokenizer using it.
4 4-encode-concurrency Encodes run without the lock or the GIL. Only a recompile makes other encodes wait.
5 5-pointers Slot → cell → JSON. The first edit after a compile copies the JSON.
6 6-copies What each operation copies.

@HuggingFaceDocBuilderDev

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@SBrandeis
SBrandeis marked this pull request as ready for review October 21, 2026 14:28
@SBrandeis
SBrandeis added this pull request to stack #2564 October 21, 2026 14:28
@SBrandeis
SBrandeis force-pushed the feat/composition-2-tokenizer-spec branch from 76ed13e to 11f25d5 Compare October 22, 2026 10:46
@SBrandeis
SBrandeis removed this pull request from stack #2564 October 22, 2026 14:17
@SBrandeis
SBrandeis added this pull request to stack #2576 October 22, 2026 14:17
@SBrandeis
SBrandeis marked this pull request as draft October 22, 2026 14:19
@SBrandeis
SBrandeis removed this pull request from stack #2576 October 22, 2026 14:51
@SBrandeis
SBrandeis added this pull request to stack #2578 October 22, 2026 14:51
@SBrandeis
SBrandeis removed this pull request from stack #2578 October 22, 2026 15:00
@SBrandeis
SBrandeis added this pull request to stack #2580 October 22, 2026 15:01
@SBrandeis
SBrandeis force-pushed the feat/composition-2-tokenizer-spec branch from a91d1d1 to 2090802 Compare October 23, 2026 10:45
Older tokenizer.json files leave the model's "type" out, and tk-convert infers it.
The Python bindings pick a component's class from that "type", so they need the
same inference. fill_model_type becomes pub and is re-exported from tk-convert
and from the tokenizers umbrella crate. No behaviour change.
Spec: groundwork for §1.2 (component getters return the concrete class).
Each component's JSON lives in a ComponentSpec cell (Mutex<Arc<JsonObject>>). The
component handles of the next PRs share these cells, so an edit through a handle
reaches the tokenizer, as in 0.23. PipelineSpec is generic over what it holds: cells
in the tokenizer, a JSON snapshot in the compile cache. Copying a tokenizer gives it
new cells over the same JSON.

The repr's object printing moves into write_object, which component reprs reuse.
@SBrandeis
SBrandeis force-pushed the feat/composition-2-tokenizer-spec branch from 2090802 to 4de5962 Compare October 23, 2026 11:07
@SBrandeis
SBrandeis marked this pull request as ready for review October 23, 2026 11:08
CI builds all targets before fetching fixtures, so the compile-time
include broke Build & Clippy on every OS.
Its only caller outside convert.rs is TokenizerJson, now in the same
crate, so the public export from #2560 is no longer needed.
@SBrandeis
SBrandeis removed this pull request from stack #2580 October 23, 2026 11:21
@SBrandeis
SBrandeis changed the base branch from feat/composition-1-fill-model-type to main October 23, 2026 11:21
@SBrandeis
SBrandeis added this pull request to stack #2583 October 23, 2026 11:22

This branch has not been deployed

No deployments
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.

2 participants