# TorchFont llms.txt

Machine-readable guide for AI agents that need TorchFont’s most important references and entry points.

## Overview

- Project: TorchFont (`vector-font datasets, transforms, IO built on PyTorch`)
- Repository: https://github.com/fjktkm/torchfont
- Documentation source: https://github.com/fjktkm/torchfont/tree/main/docs/source
- Current version: `0.5.2` (see `pyproject.toml`)
- License: MIT (https://github.com/fjktkm/torchfont/blob/main/LICENSE)
- Audience: ML researchers building models over glyph sequences, font engineers, contributors

## Priority documents (read in order)

1. **Project README** – goals, installation basics, citation  
   https://github.com/fjktkm/torchfont/blob/main/README.md
2. **Getting Started** – environment requirements, dataset bootstrap, first dataloader example  
   https://github.com/fjktkm/torchfont/blob/main/docs/source/getting_started/index.rst
3. **User Guide** – dataset wrappers, transform recipes, IO utilities, best practices  
   https://github.com/fjktkm/torchfont/blob/main/docs/source/user_guide/index.rst
4. **API Reference index** – Sphinx autosummary root for all public modules (`torchfont.*`)  
   https://github.com/fjktkm/torchfont/blob/main/docs/source/api/index.rst
5. **Contributor Guide / CONTRIBUTING** – development setup, workflow, lint/test requirements  
   https://github.com/fjktkm/torchfont/blob/main/CONTRIBUTING.rst
6. **Tests** – canonical behavioral examples for datasets/transforms  
   https://github.com/fjktkm/torchfont/tree/main/tests

## Key modules and files

- `python/torchfont/datasets/` – `FontFolder`, `GoogleFonts`, `FontRepo`
  https://github.com/fjktkm/torchfont/tree/main/python/torchfont/datasets
- `python/torchfont/io/` – Internal Git repository synchronization helpers with progress display
  https://github.com/fjktkm/torchfont/tree/main/python/torchfont/io
- `python/torchfont/transforms/` – sequence transforms such as `LimitSequenceLength`, `Patchify`
  https://github.com/fjktkm/torchfont/tree/main/python/torchfont/transforms
- `src/pen.rs` – Rust pen that records glyph outlines into normalized tensors
  https://github.com/fjktkm/torchfont/blob/main/src/pen.rs
- `examples/` – runnable notebooks/scripts (e.g., combined dataloaders)
  https://github.com/fjktkm/torchfont/tree/main/examples
- `data/` – user-provided font caches (empty placeholder in repo; the code expects writable paths)

## Dataset & transform guidance

- `getting_started/index.rst` documents `GoogleFonts` shallow-clone usage and the minimal `FontFolder` pipeline.
- `user_guide/index.rst` describes how to compose transforms and gives caching cautions (datasets cache parsed fonts for the process lifetime).
- For large repos, prefer `torchfont.datasets.FontRepo` with selective `patterns` to reduce how many fonts are indexed from the shallow clone.
- Always pair datasets with a custom `collate_fn` that pads/clips sequences before batching (`See Getting Started > First Glyph Dataset`).

## Build, test, and docs workflow

- Dependency manager: [`uv`](https://docs.astral.sh/uv/) (`uv add torchfont`), alternatively `pip install torchfont`.
- Python version: >=3.10; PyTorch >=2.3 (`pyproject.toml`).
- Run lint/tests via `uv run ruff check`, `uv run mypy`, `uv run pytest` (see `CONTRIBUTING.rst` for exact commands).
- Docs built with Sphinx + Furo; entry point `docs/source/index.rst`. To build locally: `uv run sphinx-build -b html docs/source docs/build/html`.

## Release & metadata

- Latest release tag: see `pyproject.toml` + `python/torchfont/__init__.py` for authoritative version constants.
- Citation BibTeX is embedded in both `README.md` and `docs/source/index.rst`.
- Package published on PyPI as `torchfont`; verify badges/versions via `uv pip show torchfont`.

## Contact & policies

- Maintainer: Takumu Fujioka (`fjktkm@gmail.com`)
- Issues & feature requests: https://github.com/fjktkm/torchfont/issues
- License: MIT; contributions are accepted under the same license.
- When mirroring or summarizing documentation, retain the project name and cite the GitHub repo per the provided BibTeX entry.
