GatPack is a CLI and Python API for automating LaTeX and PDF document generation using Jinja templating. This was originally developed for creating professional looking packets for AI safety coursework at MIT AI Alignment.
Screenshots
| CLI | Generated Cover Page | Pre-Rendered Cover Page |
|---|---|---|
 |
 |
 |
Built With
- Typer (For the CLI)
- LaTeX (For creating documents from text)
- Jinja (For templating and placeholders)
- Pydantic (For specifying the config file schema)
See who is using
- MIT AI Alignment (MAIA)
- AI Safety Student Team (AISST) at Harvard
- Columbia AI Alignment Club (CAIAC)
Let us know if your team is using it an how!
Table of Contents
- Python 3.10+
- LaTeX (
pdflatexspecifically, see more instructions on installing below)
Run the following command to install globally:
python3 -m pip install gatpackFurther Install Instructions
Run the following command to install globally (or install into a virtual environment and activate, whichever you prefer.):
python3 -m pip install gatpackTo use gatpack build which will convert a LaTeX document to a PDF, you will need pdflatex to be available on your path. You can check for this with
pdflatex --verisonIf this command isn't found, then you need to install a LaTeX compiler to your machine.
For mac you can install MacTeX. Using Homebrew:
brew install --cask mactexNote: Eventually this LaTeX requirement will be removed
You can then run the following to confirm GatPack has been successfully installed (will not check for a valid pdflatex):
gatpack --helpcd into the directory you would like to create your project and run
gatpack initFollow the set up steps to name your project.
Source code for the project template can be found here
Run the build.sh script. Check that output/packet.pdf was successfully built.
The LaTeX template files are denoted with *.jinja.tex. See the instructions on writing LaTeX-Jinja templates in the 02 LaTeX-Modified Jinja (gatpack render) section down below
Opening YOUR_PROJECT/compose.gatpack.json will reveal a number of variable assignments. Everything in the context object can be used to fill in Jinja placeholders when passed as an argument to gatpack.
Intellisense Tip
The JSON schema for a gatpack.json project is specified at the top of the compose.gatpack.json file. If you you use an editor like VSCode, it will automatically display recommendations, raise errors, and provide other intellisense features to make sure you're developing your config correctly. At the moment, there isn't much of a schema, but this will be developed as time goes on.
`compose.gatpack.json` Contents
{
"$schema": "https://raw.githubusercontent.com/GatlenCulp/gatpack/refs/heads/dev/gatpack/schema/json/GatPackCompose.schema.json",
"name": "test",
"context": {
"program_long_name": "Intro Fellowship",
"time_period": "Spring 2025",
"chron_info": "WEEK 0",
"title": "Introduction to machine learning",
"subtitle": "READINGS",
"primary_color": "0B0D63",
"primary_color_faded": "789BD6",
"core_readings": [
{
"title": "Neural Networks",
"read_on_device": true,
"subsection": "Chapters 1-6",
"author": "3Blue1Brown",
"year": 2024,
"url": "https://youtube.com/playlist?list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi&feature=shared",
"thumbnail_path": ""
}
],
"further_readings": [
{
"title": "A short introduction to machine learning",
"subsection": "",
"author": "Ngo",
"year": 2021,
"url": "https://www.alignmentforum.org/posts/qE73pqxAZmeACsAdF/a-short-introduction-to-machine-learning",
"thumbnail_path": ""
},
{
"title": "Machine Learning for Humans, Part 2.1: Supervised Learning",
"subsection": "",
"author": "Maini and Sabri",
"year": 2017,
"url": "https://medium.com/@v_maini/supervised-learning-740383a2feab",
"thumbnail_path": ""
},
{
"title": "What is self-supervised learning?",
"subsection": "",
"author": "CodeBasics",
"year": 2021,
"url": "https://youtu.be/sJzuNAisXHA",
"thumbnail_path": ""
},
{
"title": "Introduction to reinforcement learning",
"subsection": "",
"author": "von Hasselt",
"year": 2021,
"url": "https://www.youtube.com/watch?v=TCCjZe0y4Qc&t=2m0s",
"thumbnail_path": ""
},
{
"title": "The spelled-out intro to neural networks and backpropagation: building micrograd",
"subsection": "",
"author": "Karpathy",
"year": 2022,
"url": "https://youtu.be/VMj-3S1tku0",
"thumbnail_path": ""
},
{
"title": "Transformers from scratch",
"subsection": "",
"author": "Rohrer",
"year": 2021,
"url": "https://e2eml.school/transformers.html",
"thumbnail_path": ""
},
{
"title": "Machine learning for humans",
"subsection": "",
"author": "Maini and Sabri",
"year": 2017,
"url": "https://medium.com/machine-learning-for-humans/why-machine-learning-matters-6164faf1df12",
"thumbnail_path": ""
},
{
"title": "Machine learning glossary",
"subsection": "",
"author": "Google",
"year": 2017,
"url": "https://developers.google.com/machine-learning/glossary",
"thumbnail_path": ""
},
{
"title": "Spinning up deep RL: part 1 and part 2",
"subsection": "",
"author": "OpenAI",
"year": 2018,
"url": "https://spinningup.openai.com/en/latest/spinningup/rl_intro.html",
"thumbnail_path": ""
},
{
"title": "A (long) peek into reinforcement learning",
"subsection": "",
"author": "Weng",
"year": 2018,
"url": "https://lilianweng.github.io/posts/2018-02-19-rl-overview/",
"thumbnail_path": ""
}
]
}
}Open the example build pipeline located in YOUR_PROJECT/build.sh. You will see a number of commands outlining the pipeline. These are fairly self explanatory, but if you need additional assistance, you can learn more about these commands with gatpack COMMAND --help
`build.sh` Contents
#!/bin/bash
# Exit on any error
set -e
# Exit on any undefined variable
set -u
# Exit if any command in a pipe fails
set -o pipefail
COMPOSE=compose.gatpack.json
COVER_LATEX_TEMPLATE=cover/cover.jinja.tex
COVER_LATEX=cover/cover.tex
COVER_PDF=cover/cover.pdf
DEVICE_READINGS_LATEX_TEMPLATE=device_readings/device_readings.jinja.tex
DEVICE_READINGS_LATEX=device_readings/device_readings.tex
DEVICE_READINGS_PDF=device_readings/device_readings.pdf
READINGS_PDFS=readings/*.pdf
FURTHER_READINGS_LATEX_TEMPLATE=further_readings/further_readings.jinja.tex
FURTHER_READINGS_LATEX=further_readings/further_readings.tex
FURTHER_READINGS_PDF=further_readings/further_readings.pdf
OUTPUT_PDF=output/packet.pdf
# Build Cover Page
rm -f $COVER_LATEX
rm -f $COVER_PDF
gatpack render \
$COVER_LATEX_TEMPLATE \
$COVER_LATEX \
$COMPOSE
gatpack build \
$COVER_LATEX \
$COVER_PDF
# Build Device Readings Page
rm -f $DEVICE_READINGS_LATEX
rm -f $DEVICE_READINGS_PDF
gatpack render \
$DEVICE_READINGS_LATEX_TEMPLATE \
$DEVICE_READINGS_LATEX \
$COMPOSE
gatpack build \
$DEVICE_READINGS_LATEX \
$DEVICE_READINGS_PDF
# Build Further Readings Page
rm -f $FURTHER_READINGS_LATEX
rm -f $FURTHER_READINGS_PDF
gatpack render \
$FURTHER_READINGS_LATEX_TEMPLATE \
$FURTHER_READINGS_LATEX \
$COMPOSE
gatpack build \
$FURTHER_READINGS_LATEX \
$FURTHER_READINGS_PDF
# Combine all readings into "packet.pdf"
rm -f $OUTPUT_PDF
gatpack combine \
$COVER_PDF \
$DEVICE_READINGS_PDF\
$FURTHER_READINGS_PDF \
$OUTPUT_PDF
# $READINGS_PDFS \
open $OUTPUT_PDFgatpack --help will provide various information about how to use the tool. You can get further help with subcommands using gatpack COMMAND --help
Usage: gatpack [OPTIONS] COMMAND [ARGS]...
╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or │
│ customize the installation. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────────────────────────╮
│ init Initialize a new GatPack project in your specified directory. │
│ render Render a specified LaTeX document with Jinja placeholders with provided │
│ context. │
│ combine Combine any number of PDFs into a single PDF. │
│ build Build a LaTeX document into a PDF. │
╰───────────────────────────────────────────────────────────────────────────────────────────╯The Jinja placeholders for LaTeX were modified to ensure compatability and a good user experience:
| Function | LaTeX-Modified | Standard | Usage |
|---|---|---|---|
| Expresssions & Variables | \VAR{variable_name} |
{{ variable_name }} |
Insert a variable value |
| Statements & Control Structures | \BLOCK{for item in items} |
{% for item in items %} |
Control structures (loops, conditionals) |
| Comments | \#{comment text} |
{# comment text #} |
Add template comments |
| Line Statements | %- |
# |
Single line statements |
| Line Comment | %# |
## |
Single line comments |
See the Jinja API for more information. Apart from the delimeter syntax, everything should work the same.
Why this Modification is Needed
Standard Jinja placeholders: {{ variable_name }}, {% for item in items %} {% endfor %}, etc. don't play well with LaTeX. It becomes very difficult to view your LaTeX template since you run into syntax errors and some LaTeX syntax conflicts with Jinja tags, leading to errors from both systems.
Standard Jinja:
LaTeX-Adapted Jinja:
The Jinja placeholders above are meant to fix this issue.
Get placeholder highlighting in your LaTeX document
% Define Jinja placeholder commands for better editor visualization
\usepackage{xcolor}
\definecolor{jinjaColor}{HTML}{7B68EE} % Medium slate blue color for Jinja
\definecolor{jinjaVarBg}{HTML}{E6E6FA} % Light lavender for variables
\definecolor{jinjaBlockBg}{HTML}{FFE4E1} % Misty rose for blocks
\definecolor{jinjaCommentBg}{HTML}{E0FFFF} % Light cyan for comments
\newcommand{\VAR}[1]{\colorbox{jinjaVarBg}{\detokenize{#1}}}
\newcommand{\BLOCK}[1]{\colorbox{jinjaBlockBg}{\detokenize{#1}}}
\newcommand{\COMMENT}[1]{\colorbox{jinjaCommentBg}{\detokenize{#1}}}-
You want to combine multiple files into a packet:
pdfs/document1.pdf,pdfs/document2.pdf, andpdfs/document3.pdf. This makes printing and stapling multiple copies easier:gatpack combine pdfs/*.pdf packet.pdf -
You want to build and reuse a LaTeX template for an invoice:
invoice.jinja.tex. To do this, render your template using Jinja placeholders intoinvoice.texusing the assignments fromcompose.gatpack.jsonthen build your invoice to a pdfinvoice.pdf:gatpack render invoice.jinja.tex invoice.tex compose.gatpack.json gatpack build invoice.tex invoice.pdf
Planned features:
-
Change Jinja template delimiters to be LaTeX friendly (Highest priority)
-
Fix the actual Jinja LaTeX templates for packet making to look nice
-
Add a padding command that will make sure all PDFs have an even number of pages before merging (that way unrelated documents don't get printed on the front and back side of the same page)
-
Better syntax for the CLI
-
Make it easier to chain together multiple gatpack calls
-
Footers
See the open issues for a list of proposed features (and known issues).
-
Top Feature Requests (Add your votes using the 👍 reaction)
-
Top Bugs (Add your votes using the 👍 reaction)
Reach out to the maintainer at one of the following places:
- GitHub issues
- Contact options listed on this GitHub profile
If you want to say thank you or/and support active development of GatPack:
- Add a GitHub Star to the project.
- Tweet about the GatPack.
- Write interesting articles about the project on Dev.to, Medium or your personal blog.
Together, we can make GatPack better!
First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.
Please read our contribution guidelines, and thank you for being involved!
Project Organization
📁 .
├── ⚙️ .cursorrules <- LLM instructions for Cursor IDE
├── 💻 .devcontainer <- Devcontainer config
├── ⚙️ .gitattributes <- GIT-LFS Setup Configuration
├── 🧑💻 .github
│ ├── ⚡️ actions
│ │ └── 📁 setup-python-env <- Automated python setup w/ uv
│ ├── 💡 ISSUE_TEMPLATE <- Templates for Raising Issues on GH
│ ├── 💡 pull_request_template.md <- Template for making GitHub PR
│ └── ⚡️ workflows
│ ├── 🚀 main.yml <- Automated cross-platform testing w/ uv, precommit, deptry,
│ └── 🚀 on-release-main.yml <- Automated mkdocs updates
├── 💻 .vscode <- Preconfigured extensions, debug profiles, workspaces, and tasks for VSCode/Cursor powerusers
│ ├── 🚀 launch.json
│ ├── ⚙️ settings.json
│ ├── 📋 tasks.json
│ └── ⚙️ 'gatpack.code-workspace'
├── 🐳 docker <- Docker configuration for reproducability
├── 📚 docs <- Project documentation (using mkdocs)
├── 👩⚖️ LICENSE <- Open-source license if one is chosen
├── 📋 logs <- Preconfigured logging directory for
├── 👷♂️ Makefile <- Makefile with convenience commands (PyPi publishing, formatting, testing, and more)
├── ⚙️ pyproject.toml <- Project configuration file w/ carefully selected dependency stacks
├── 📰 README.md <- The top-level README
├── 🔒 secrets <- Ignored project-level secrets directory to keep API keys and SSH keys safe and separate from your system (no setting up a new SSH-key in ~/.ssh for every project)
│ └── ⚙️ schema <- Clearly outline expected variables
│ ├── ⚙️ example.env
│ └── 🔑 ssh
│ ├── ⚙️ example.config.ssh
│ ├── 🔑 example.something.key
│ └── 🔑 example.something.pub
└── 🚰 'gatpack' <- Easily publishable source code
├── ⚙️ config.py <- Store useful variables and configuration (Preset)
├── 🐍 dataset.py <- Scripts to download or generate data
├── 🐍 features.py <- Code to create features for modeling
├── 📁 modeling
│ ├── 🐍 __init__.py
│ ├── 🐍 predict.py <- Code to run model inference with trained models
│ └── 🐍 train.py <- Code to train models
└── 🐍 plots.py <- Code to create visualizations
The original setup of this repository is by Gatlen Culp.
For a full list of all authors and contributors, see the contributors page.
GatPack follows good practices of security, but 100% security cannot be assured. GatPack is provided "as is" without any warranty. Use at your own risk.
For more information and to report security issues, please refer to our security documentation.
This project is licensed under the MIT.
See LICENSE for more information.
- Cambridge-Boston Alignment Initiative + MIT AI Alignment for employing me to work on program logistics which lead me to develop and share this project as a consequence
- Further upstream, Open Philanthrophy provides a lot of the funding for CBAI/MAIA
- Other AI Safety Student groups who are doing their best to keep the world safe.
- Thanks to Samuel Roeca for developing latexbuild, from which some of the LaTeX templating code was borrowed.
- https://github.com/mbr/latex