Pantogloss

Pantogloss is a TensorFlow/Keras many-to-English machine-translation library. Its first model, pantogloss-500-en, was converted and numerically validated from the model described in Many-to-English Machine Translation Tools, Data, and Pretrained Models (ACL-IJCNLP 2021).

The Python package is distributed through PyPI, while the initial model is kept in a separate public Hugging Face repository. Pantogloss 0.3.0 and later download it anonymously by default; cached or explicit Hugging Face credentials remain supported for private and gated model repositories.

The codebase and converted model are licensed under Apache-2.0. This repository is private during initial development.

Intended API

from pantogloss import Translator

translator = Translator.from_pretrained("pantogloss-500-en")
print(translator.translate("Comment allez-vous ?"))

RTG-compatible beam search is available without changing the return type:

print(
    translator.translate(
        "Comment allez-vous ?",
        beam_size=4,
        length_penalty=0.6,
    )
)

Pantogloss selects the first TensorFlow GPU automatically and enables memory growth. Device choice can also be made explicit:

translator = Translator.from_pretrained("pantogloss-500-en", device="gpu")
print(translator.device_info)

Using device="gpu" fails clearly if TensorFlow cannot see a GPU; use device="cpu" to force CPU inference.

Greedy translation uses an encode-once, graph-compiled TensorFlow decoding loop with decoder self-attention and cross-attention key/value caches by default. If a TensorFlow backend cannot compile that loop, Pantogloss falls back to the equivalent eager decoder. The fallback can also be selected explicitly for diagnostics or parity testing:

translator = Translator.from_pretrained(
    "pantogloss-500-en", compiled_decode=False
)

Structured results are additive to the original string API:

result = translator.translate_detailed("Bonjour le monde.")
print(result.text, result.source_tokens, result.target_tokens)
print(result.execution_device, result.elapsed_seconds)

For extracted documents, one shared model can segment, batch, and reconstruct text while retaining blank lines and paragraph boundaries:

from pantogloss import DocumentTranslator

documents = DocumentTranslator(translator)
result = documents.translate(
    extracted_text,
    source_language="fr",
    max_source_tokens=512,
    long_input="split",
)
print(result.text)

Long segments can use split, truncate, or error policy. Failures are isolated to individual segments and recorded in result.segments; successful neighbors remain ordered. Layout-only segments such as page numbers, dot leaders, and separator rules are preserved verbatim instead of being sent to the translation model.

Install pantogloss[tika] to use the pantogloss-tika extraction-to-English command without a translation server or Docker container. It supports bounded trials and page ranges, displays progress, writes output incrementally, and resumes from a fingerprint-protected JSONL checkpoint. See examples/tika_to_english.py for its compatibility wrapper.

The same workflow is available as a stable Python API:

from pantogloss.tika import translate_document

result = translate_document(
    "report.pdf",
    output="report.en.txt",
    device="auto",
)
print(result.diagnostics)
print(result.runtime)

Apple Silicon GPU document runs automatically use short-lived TensorFlow workers, committing five chunks before each worker exits. This bounds Metal's retained unified-memory allocations without changing translations or checkpoint compatibility. Tune the interval with metal_worker_chunks=N in Python or --metal-worker-chunks N on the command line; use None in Python or 0 on the command line to disable recycling. CPU and CUDA runs remain in-process.

New checkpoints record per-chunk diagnostics, translation timing, throughput, peak process memory, and effective device metadata. Inspect or validate them offline without importing TensorFlow or Tika:

pantogloss-tika inspect report.en.txt.jsonl
pantogloss-tika validate report.en.txt.jsonl --output report.en.txt
pantogloss-tika review report.en.txt.jsonl --output review.jsonl
pantogloss-tika review report.en.txt.jsonl --format csv --output review.csv
pantogloss-tika review report.en.txt.jsonl \
  --include-preserved formula --format csv --output formulas.csv

Diagnostics are conservative review signals—not translation-quality scores. They flag empty output, retained multi-character source-script runs, fourfold word repetition, and extreme character-length ratios; scientific symbols such as α, β, and π are intentionally not treated as untranslated prose. The model-free review command joins every finding back to its aligned source and translation with chunk, segment, character-offset, token, truncation, and error metadata. JSONL is the default for automated processing; CSV is convenient for spreadsheet review. Use --include-preserved formula, layout_only, or all to add informational rows for deliberately untranslated spans without turning them into diagnostic warnings. During classifier development, tools/audit_formula_detection.py replays the explainable formula policy over an existing checkpoint and can emit candidate-level JSONL with signal counts, natural-word count, and math density.

Formula-heavy spans are preserved verbatim by default because general-purpose translation models can turn extracted equations into plausible but invented prose. Checkpoints record these spans with preservation_reason="formula", and inspect reports preservation counts. Normal prose containing occasional mathematical notation remains translatable. Whole-span preservation requires zero natural-language words; mixed prose and notation stays in the translation and diagnostic path rather than silently retaining source-language prose. Use preserve_formulas=False with DocumentTranslator.translate() or translate_document(), or pass --translate-formulas to pantogloss-tika, to restore the prior behavior. The Tika choice is protected by the checkpoint fingerprint.

Schema-1 checkpoints created by Pantogloss 0.5 remain inspectable and can be resumed when their source checksum, model revision, and decoding options match.

The August 2026 full-document validation translated a 285,527-character Russian dissertation on an Apple M3 Max in 58 durable chunks. Twelve recycled Metal workers bounded peak process RSS at 6.10 GiB. All 6,517 aligned segments completed without failures or truncation, 793 layout-only segments were preserved verbatim, and the 286,361-character English result contained no Cyrillic runs. The result was byte-identical across exact padding and bounded power-of-two padding, including an interrupted/resumed run. A matching three-page CUDA trial completed 139 segments with zero failures or truncation.

Install the accelerator backend for the machine:

# Linux with an NVIDIA GPU
pip install 'pantogloss[cuda]'

# Apple Silicon
pip install 'pantogloss[metal]'

Both use the same device="auto" or device="gpu" Python API. The CUDA extra does not install or replace the host NVIDIA driver. The Metal extra uses Apple's TensorFlow PluggableDevice and the TensorFlow 2.18 runtime combination validated by the Bytewise project.

Source batches use bounded power-of-two padded widths by default (for example, 16, 32, and 64 through the active source-token limit). Padding remains masked and does not change source token counts. This bounds accelerator allocation shapes for long document runs; use source_padding="exact" with Translator.from_pretrained() or --source-padding exact as a reference mode. The policy and actual padded width are included in runtime and segment metadata and the policy is protected by Tika checkpoint fingerprints.

Greedy decoding runs on the selected device. On Apple Silicon, beam decoding uses a correctness-first CPU execution fallback because Panto-500 validation found shape-sensitive corruption in Metal beam-expanded inference. CUDA beam decoding remains on GPU. Pantogloss records the effective beam execution device in evaluation manifests instead of silently claiming Metal placement.

The model is stored separately in the public Hugging Face repository chrismattmann/pantogloss-500-en; it is never included in the Python wheel.

The default token=None uses a locally cached Hugging Face credential when one exists but does not require one for public repositories. Use token=False to force anonymous access or pass a token explicitly without storing it:

import os

translator = Translator.from_pretrained(token=os.environ["HF_TOKEN"])

Command line

The pantogloss command loads the model once and supports arguments, files, and line-oriented Unix pipelines:

pantogloss info
pantogloss translate "Comment allez-vous ?"
printf 'Hola señor\nWie geht es Ihnen?\n' | pantogloss translate --device gpu
pantogloss translate --input source.txt --output english.txt --batch-size 16
pantogloss translate --beam-size 4 --length-penalty 0.6 "Hola señor"
pantogloss translate --max-source-tokens 512 --source-length-policy truncate "..."

Use --json for JSON Lines output and --offline to require an already cached model snapshot. Translation data goes to stdout (or --output); model and device diagnostics are suppressed by default so pipelines remain clean. Use --verbose for Pantogloss loading progress or --tensorflow-logs for TensorFlow, CUDA, and Metal startup diagnostics.

Development status

The complete 307-variable Keras model has been converted locally from all 308 learned PyTorch tensors (the target embedding and output projection are tied). Greedy parity against the archived RTG implementation passes across a ten-language batch: token IDs and translations match exactly, while final logits have a maximum absolute error of 1.24e-5. With the original beam size 4 and length penalty 0.6, all decoded four-best candidate sets match. One near-tied example changes top rank because of framework floating-point ordering. Model version 0.1.0 is released in the public Hugging Face repository at an immutable commit.

The source model and generated artifacts stay under the ignored artifacts/ directory. To reproduce conversion after acquiring the source archive:

python tools/convert_rtg_checkpoint.py \
  artifacts/source/rtg500eng-tfm9L6L768d-bsz720k-stp200k-ens05 \
  artifacts/converted/pantogloss-500-en-candidate

Run the reference parity harness with:

CUDA_VISIBLE_DEVICES=-1 python tools/check_parity.py \
  artifacts/source/rtg500eng-tfm9L6L768d-bsz720k-stp200k-ens05 \
  artifacts/converted/pantogloss-500-en-candidate

To require and verify real GPU placement:

python tools/check_gpu.py artifacts/converted/pantogloss-500-en-candidate

Apple Silicon validation

Pantogloss uses the same hardware-neutral GPU API for CUDA and Metal. On an M-series Mac with Python 3.12 and Xcode command-line tools installed:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[metal,test]'
hf auth login
python tools/check_platform.py --device cpu
python tools/check_platform.py --device gpu
python tools/benchmark_inference.py --device gpu --runs 5

The portable platform report identifies the selected backend as cpu, cuda, or metal, verifies the first model variable's actual TensorFlow placement, and runs a real translation. Metal placement and inference are validated on an Apple M3 Max with TensorFlow 2.18.1. Before compiled decoding, a short batch-one sentence had warmed medians of 0.545 seconds on CPU and 0.633 seconds on Metal.

Decoding benchmark

Use the same input repeated into batches of 1, 8, 16, and 32:

for batch in 1 8 16 32; do
  python tools/benchmark_inference.py --device gpu --runs 5 \
    --batch-size "$batch"
done

The August 2026 TensorFlow 2.18.1 validation produced the following warmed throughput. CPU and CUDA were measured on Linux; Metal was measured on an Apple M3 Max with 128 GB unified memory.

The M3 Max batch-one median was 0.253 seconds with compiled cached decoding, down from the pre-compilation measurement of 0.633 seconds. Cold model load and first-call graph compilation are reported separately from the warmed runs.

The benchmark JSON also reports total process peak RSS and, where supported by the TensorFlow backend, allocator current memory, peak memory, and the peak increment above its post-warmup baseline. At batch 32, CUDA's allocator rose by 22.5 MiB above the 2,114.5 MiB model baseline. Peak process RSS was approximately 8.4 GiB on CPU, 5.9 GiB with CUDA, and 4.0 GiB with Metal. TensorFlow Metal 1.2 reports zero for its allocator counters, so process RSS is the meaningful Metal memory measurement.

Replay real checkpoint segments to test padding parity and long-run allocation behavior without rerunning Tika:

python tools/check_padding_parity.py report.en.txt.jsonl \
  --device gpu --segments 256 --offline

python tools/stress_document_memory.py report.en.txt.jsonl \
  --device gpu --padding power_of_two --chunks 40 --offline \
  --output memory-stress.jsonl --max-growth-gib 3

The stress artifact is appended and flushed after every chunk, so partial runs remain inspectable after interruption.

Translation evaluation

Pantogloss includes a versioned evaluation runner and a checksum-pinned, project-authored CC0 smoke corpus covering 12 languages and seven scripts. It supports durable resumable translation artifacts, model-free rescoring, adaptive batch recovery, deterministic paired-bootstrap confidence intervals, and aligned regression comparisons. Reports include BLEU, chrF, per-language diagnostics, failures, empty and unknown-token outputs, latency, and throughput.

Install the development extras and run the complete automated suite:

# Linux CUDA
python -m pip install -e '.[cuda,evaluation,test]'

# Apple Silicon Metal
python -m pip install -e '.[metal,evaluation,test]'

python -m pytest

The August 2026 smoke validation used Panto-500 revision 250fc3b4122d79ac0734b28b368d2c1d68f72f7e and TensorFlow 2.18.1:

The M3 beam fallback matched CPU exactly across all 12 translations: zero metric delta, zero disagreements, and zero new failures. The automated suite passed on both Kubuntu and Apple Silicon; hardware validation supplements the routine tests because hosted CI does not provide these accelerators.

See evaluation/README.md for commands, checked-in reports, reproducibility details, and the important limits on interpreting this deliberately small regression fixture.