LaTeXTransPlus is a Python package that translates LaTeX paper sources and PDFs into translated PDF output. It is derived from the upstream LaTeXTrans project and ships two workflows: the source-based Heavy workflow orchestrated by src/agents/, and the PDF-to-Markdown Lite workflow in src/engines/. Heavy is available through the latextrans CLI and both workflows through the Textual terminal UI in src/tui/.
main.pyis thelatextransCLI entry point for Heavy;latextrans-tuiresolves tosrc/tui/app.py:run.src/agents/holds Heavy agent orchestration (coordinator_agent.py,tool_agents/).src/engines/holds the engine interface (base.py,EngineName),heavy.py, and the Lite stages (lite.py,lite_inputs.py,lite_mineru.py,lite_markdown.py,lite_math.py,lite_fonts.py,lite_pdf.py).src/tui/holds the UI.app.pyonly coordinates project identity and task lifecycle; state, configuration page/schema, project detail, history, error reports, runner/process runner, widgets and Zotero helpers live in their own modules.src/formats/latex/holds LaTeX parsing, prompt, reconstruction and compilation helpers.- Shared services live in
src/runtime.py(workflow orchestration and runtime config loading),src/config.py(LLM profile and payload helpers),src/project_sources.pyandsrc/project_metadata.py(input acquisition and titles),src/terminology.py,src/validation_policy.py,src/events.py(JSON Lines events) andsrc/utils/progress.py. config/default.tomlis the working configuration andconfig/template.tomlthe tracked template next to it;config/ui.tomlis created locally on first TUI run and git-ignored, andconfig/provider/*.tomlholds LLM profiles (onlyconfig/provider/default.tomlis tracked).terms/stores terminology CSVs andexamples/sample inputs and PDFs/images.scripts/windows,scripts/linuxandscripts/macoscontain launcher wrappers that activate thelatextransconda environment.docs/holds usage and design documentation (configuration-and-usage.md,superpowers/plans/,superpowers/specs/),evaluation/scripts/holds evaluation scripts, andtests/holds theunittestsuite.
- Activate and use the local
latextransconda environment for all project runs and tests; do not run this project from any other environment. pip install -e .: install the package in editable mode with thelatextransandlatextrans-tuiconsole scripts.latextrans --arxiv 2508.18791: run the Heavy workflow for an arXiv ID.latextrans --project D:\path\to\paper_source.tar.gz: process a local LaTeX project or archive.latextrans-tui,latextrans-tui --engine heavy,latextrans-tui -e lite: open the terminal UI and select a workflow. Addscripts/windows,scripts/linuxorscripts/macostoPATHfirst; the wrappers activate the conda environment, and the Linux and macOS scripts needchmod +x.python -m unittest discover tests: run the current test suite.- If a change is unrelated to TUI behavior, do not run TUI tests. For TUI-related changes, run only the newly added tests by default unless the user explicitly requests the full TUI test suite.
Install MiKTeX or TeXLive before testing PDF compilation paths. Lite additionally requires pandoc, XeLaTeX and a MinerU API token. Installation, configuration keys, language codes, model profiles and output layout are documented in docs/configuration-and-usage.md; keep that guide in sync with CLI and configuration changes.
Use Python 3.10+ style with 4-space indentation, explicit imports, and pathlib.Path for filesystem paths where practical. Keep functions small and name helpers with clear snake_case verbs, such as _safe_extract_tar or load_runtime_config. Preserve existing public CLI option names and configuration keys. When editing configuration examples, keep TOML keys aligned with config/default.toml.
Tests currently use the standard unittest framework. Add tests under tests/ with filenames like test_runtime_config.py and test classes ending in Tests. Prefer temporary directories and environment variable isolation for filesystem or configuration behavior. Run python -m unittest discover tests before submitting changes.
- This project has two configuration paths: runtime configuration (
config/default.tomlplusconfig/provider/*.toml, loaded throughsrc/runtime.pyandsrc/config.py) and TUI configuration (config/ui.toml, loaded throughsrc/tui/config.py). Do not letmain.pygrow its own parsing; route changes through the shared runtime helpers, and keep thesrc/tui/config_schema.pyform fields aligned with the TOML keys, otherwise the CLI, the runtime and the UI can easily drift into inconsistent behavior. - When removing legacy compatibility, clean it up thoroughly. Do not only update configuration examples or entry-point parameters; also inspect and remove leftover compatibility logic in low-level helpers, alias mappings, fallback branches, and old tests to keep documentation and runtime behavior from drifting again.
- Future development should not assume English-to-Chinese translation by default. Any work involving translation direction, prompts, glossaries, language configuration, or tests should be reviewed for multilingual support. If the user mentions only one case, such as "English-to-Chinese", pause first to note that it may affect multilingual capability and confirm whether the change should target only that language pair.
- New tool agents should log their
execute()flow throughBaseToolAgent.log, including start, key processing milestones, failure branches, and successful output paths, so workflow logs remain consistent across agents. - The remote download helper must not only clean up on network exceptions;
OSErrorduring file open or write phases must also clean up partial archives, preventing subsequent--all-existingor extraction flows from mishandling corrupted packages. - The skip semantics for batch input need regression tests covering "partial failure while continuing to process remaining items," not just a single failure causing a full abort.
- When adding new explicit input parameters, the
--all-existingpriority description, help text, README anddocs/configuration-and-usage.mdmust be updated in sync, so the documentation does not still reference only the old parameters. - Textual
DataTablecolumns with manually assigned fixed widths do not automatically redistribute when the terminal is resized. Any TUI table that computes fixed column widths from available space needs an explicit resize hook and a regression test that exercises terminal resizing. - Never let tests mutate the real UI config. Any test that runs the TUI, Textual, the configuration page, settings controls,
save_ui_config(Path.cwd(), ...), or code that may trigger asynchronous configuration-widgetChangedevents must protect the realconfig/ui.toml. This is not cosmetic test pollution: repeated unexpected edits can overwrite the user's active paper list, target language, terminology settings, model settings, and other working preferences, creating serious disruption. Mock the configuration save function for the entirerun_test()interaction lifecycle, including widget assignments, clicks,pilot.pause(), and queued Textual event draining, or run the test from a temporary cwd / project root. When verifying these tests, prefer comparing the realconfig/ui.tomlhash or diff. - Do not let a single module grow into a multi-purpose script. The TUI started as one large
src/tui/app.pyand had to be decomposed afterwards into focused components, so when a module starts mixing unrelated responsibilities, extract a new module next to it with one clear purpose instead of appending more code to the existing file.
Recent commits use short messages such as chore: ignore generated files and Update README. Prefer concise, imperative messages; use a scoped conventional prefix when helpful, for example fix(config): resolve API key from env. Pull requests should describe the workflow affected, list verification commands, and note configuration changes.
Do not commit API keys. Store secrets in environment variables. Treat outputs/, output-lite/, tex source/, downloaded archives, and compiled PDFs as generated artifacts unless a fixture is intentionally added for tests or documentation.