feat: make transformers optional (#31)

[hallerite]

Closes #31.

Why

transformers is a heavy dependency, and text-only consumers that already own
a tokenizer should not have to install it just to render and parse token IDs.

This branch has been rebuilt on current main. It keeps the current
offset-capable tokenizer policy and does not restore the removed fastokens
integration.

What changed

• Added structural Tokenizer and ChatTemplateTokenizer protocols and moved
  all 19 concrete renderer modules off type-only Transformers imports.
• Moved transformers from the base install to the
  renderers[transformers] extra.
• Added renderers[multimodal] for Transformers plus Pillow.
• Kept load_tokenizer, processor auto-loading, unknown-model AutoConfig
  probing, and vLLM multimodal feature encoding behind lazy, actionable
  dependency checks.
• Preserved processor injection, so text rendering and callers that provide
  their own processor remain lightweight.
• Regenerated uv.lock and documented the installation/BYO contracts.

The vLLM/OpenAI client remains part of the base package in this revision. That
split is separate from making Transformers optional and avoids breaking the
existing root exports for client exceptions.

Behavior without Transformers

• Every concrete renderer module imports successfully.
• Registered text models work through create_renderer() with an
  offset-capable BYO tokenizer.
• Text-only Inkling renders without importing Transformers or constructing an
  image/audio processor.
• DefaultRenderer works when selected explicitly with a tokenizer that
  provides apply_chat_template.
• Unknown-name auto-resolution asks for renderers[transformers] or an
  explicit renderer config, rather than silently treating a possible VLM as a
  text model.
• Tokenizer loading, processor auto-loading, and vLLM multimodal serialization
  report the appropriate optional-extra hint.

Verification

• Full suite: 3660 passed, 179 skipped, 1 xfailed
• Focused config/client/multimodal/Kimi tests: 174 passed, 24 skipped
• Ruff and format checks pass.
• Ty completes successfully (diagnostic count is lower than current main).
• A clean base sync installs no Transformers and imports every renderer.
• Built wheel metadata lists Transformers only under the transformers and
  multimodal extras.

Note

Make transformers an optional dependency and remove RendererPool

• Moves transformers out of core dependencies into optional extras (transformers and multimodal) in pyproject.toml, allowing the library to be installed without transformers.
• Introduces runtime-checkable Tokenizer and ChatTemplateTokenizer Protocols in renderers/base.py so callers can pass any compatible tokenizer object instead of requiring PreTrainedTokenizer.
• Removes the entire RendererPool class, create_renderer_pool factory, and pool-based offloading in renderers/client.py. generate now accepts only Renderer, not RendererPool.
• Adds _require_transformers helper that raises an actionable ImportError when transformers is missing, used by load_tokenizer, _model_has_vision_config, and multimodal feature builders in each renderer.
• Behavioral Change: RendererPool and create_renderer_pool are removed from renderers/__init__.py exports; generate in renderers/client.py no longer accepts RendererPool; DefaultRenderer.__init__ now requires a tokenizer with apply_chat_template.

^{Macroscope summarized de6b9d2.}

---

Note

High Risk
Removes RendererPool/create_renderer_pool and changes default dependencies, which can break integrators; auto-resolution behavior for unknown models without Transformers is stricter and may require explicit configs.

Overview
Makes Hugging Face Transformers optional so text-only users can install the base package and supply an offset-capable BYO tokenizer. transformers moves to renderers[transformers]; renderers[multimodal] adds Pillow plus Transformers for image/audio paths. Docs and examples now describe BYO tokenizer requirements and the new extras.

Introduces Tokenizer and ChatTemplateTokenizer protocols and retargets all concrete renderers from PreTrainedTokenizer to those structural types. load_tokenizer, processor auto-load, unknown-model AutoConfig probing, and vLLM multimodal encoding call _require_transformers lazily with install hints. Without Transformers, registered text models still auto-resolve; unregistered names must use an explicit config (e.g. DefaultRendererConfig()) instead of silently falling back.

Removes RendererPool and create_renderer_pool from the public API, base, docs, and tests. client.generate only accepts a single Renderer and runs render/parse synchronously on the event loop (no pool thread offload).

Breaking for downstream: default pip install renderers no longer pulls Transformers; pool-based concurrency must be reimplemented outside the library.

^{Reviewed by Cursor Bugbot for commit de6b9d2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — The PR moves Transformers and multimodal dependencies into extras and adds BYO-tokenizer support, but it also removes the public RendererPool/create_renderer_pool API and its concurrent execution path while changing dependency-sensitive auto-resolution. These production contract changes exceed a self-contained dependency tweak and merit human review.

Notes:

• Macroscope's correctness review did not run, so approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[hallerite]

not really satisfied with the way attribute_text_segments for character-offset attribution is handled, so further iterating.

[felipemello1]

hey @hallerite , thanks for writing this PR! I see that its "approved" (by a bot, so idk if that counts). I am just wondering if you think it will still get merged. Thank you!

[hallerite]

@felipemello1 I will try to get this in asap, probably tomorrow or the day after!

[felipemello1]

awesome, thanks @hallerite . Just to be clear: its not blocking us in TorchTitan. It is just a great feature. It is fine if you want to take your time to get it merged later. Ty!

[felipemello1]

hey @hallerite , just checking if you still plan on merging it. We wanted to use it in SFT and not have to require transformers as a dependency. Is merging this PR still in your roadmap?

[hallerite]

@felipemello1 we are about to merge this PR. will be in the next renderers release after we test it for a bit!