mtph 0.1.0

An AI-native file format for math & physics problems: real symbolic notation + diagrams-as-code, rendered crisply.

mtph

An AI-native file format for math & physics problems.

One plain-text file an AI can write and a human can read: real symbolic notation (true fraction bars, ∫, Greek, vectors, tensors — not ASCII like /) and diagrams-as-code (free-body diagrams, fields, circuits, 3-D, thermodynamics, function plots — or any freeform shape), rendered crisply. No PDF, no OCR, no images — the .mtph file is the semantic source, equally readable by an AI, a human, and git.

.mtph  ──parse──▶  validated DOM  ──render──▶  crisp HTML · PNG · SVG · a native reader
 │ LaTeX for math (→ real glyphs via KaTeX)
 │ a small diagram DSL for figures (→ SVG)
 └ a function-plot mini-language (→ SVG)

▶ Try it in your browser — no install: the playground is a live editor that renders .mtph client-side (figures, plots, LaTeX) and turns any problem into a share link that carries its own source. (Powered by the JavaScript port in js/, which reproduces the Python renderer byte-for-byte; served from playground/ on GitHub Pages — zero server.)

▶ Embed a problem anywhere: the <mtph-doc> web component renders a live .mtph — figures, LaTeX, self-check quizzes, even params: sliders — from one <script> tag, with nothing to install on the host page:

<script src="mtph-doc.js"></script>
<mtph-doc><script type="text/plain">
---
mtph: "0.2"
title: My problem
---
A block of mass $m$ on an incline of angle $\theta$ …
</script></mtph-doc>

---

Install

Everything (including the math fonts) is bundled — it works offline, with zero setup.

# straight from GitHub, no clone needed:
pip install git+https://github.com/Saurav0989/mtph

# …or clone and install:
git clone https://github.com/Saurav0989/mtph && cd mtph
pip install .

Optional extras:

pip install "mtph[raster]"   # figure/plot PNG, browserless (cairosvg)
pip install "mtph[export]"   # full-page PNG/SVG export   (also: playwright install chromium)
pip install "mtph[app]"      # native desktop reader window (pywebview)

PNG, honestly. A figure or plot is pure SVG, so turning it into PNG needs only a vector rasterizer — mtph figure problem.mtph -o fig.png works with the light [raster] extra, no 300 MB browser. A full page (math + prose laid out by KaTeX's HTML/CSS) can only be rasterized faithfully by a browser engine, so mtph render … -o page.png still uses [export].

Requires Python 3.9+. Once published to PyPI it'll be a plain pip install mtph.

---

Try it in 30 seconds

mtph init                        # one-shot setup + self-test (after pip install)
mtph new problem.mtph            # scaffold a starter problem (--template for a known shape)
mtph view problem.mtph           # open a live reader (auto-refreshes as you edit)
mtph render problem.mtph -o problem.html    # self-contained HTML (dark-mode aware)
mtph render problem.mtph --cdn -o page.html # tiny HTML, KaTeX from a CDN
mtph figure problem.mtph -o fig.png         # just the figure → PNG (needs mtph[raster])
mtph verify problem.mtph         # graduated checks (silent errors + fixes, as JSON)
mtph audit problem.mtph          # verify + structural nudges + the hard-problem checklist
mtph inspect problem.mtph        # a figure's resolved scene as data (coords, overlaps)
mtph validate problem.mtph       # fast schema-only gate
mtph render spec/examples/(problem path) -o (problem).html #create the html file reg .mtph file.

On macOS, make .mtph open in a native window by double-clicking (like a PDF):

mtph install-viewer

---

Use it with your AI ✨

mtph is built so an AI can author hard problems end-to-end. Point your assistant at two files and let it work:

1. AGENTS.md — the operating manual: how to write .mtph, the full diagram DSL, notation conventions, and a quality checklist.
2. thesis/card.md — the doctrine of what makes a physics problem genuinely hard, condensed to ~100 lines (7 pillars, 8 techniques, the design checklist). The full thesis/phythesis.md is there for depth.

Or just run mtph prompt --full — it prints both to stdout, so an AI can load its instructions locally with no filesystem spelunking.

A typical prompt:

Read AGENTS.md and thesis/phythesis.md, then create a hard rotational-dynamics problem as a .mtph file with a free-body diagram. Validate and render it.

The AI writes plain text; mtph render turns it into crisp math + figures. You read it.

Render it as a Claude Artifact. mtph's HTML is fully self-contained, so it drops straight into a claude.ai HTML artifact and renders in the side panel — math, figures, plots, and all:

mtph render spec/examples/earnshaw-trap.mtph --artifact -o problem.html
# then paste problem.html's contents into a claude.ai HTML artifact

--artifact loads KaTeX from cdnjs (the host the artifact sandbox allows) for a ~57 KB file; plain mtph render inlines everything (~560 KB, zero network).

Keep a problem bank honest in CI. The bundled verify-mtph GitHub Action runs mtph verify on every changed .mtph in a PR, comments the findings, and fails on any error — so a doubled backslash, a dangling \ref, or an undefined figure anchor never lands silently.

---

What a .mtph file looks like

---
mtph: "0.2"
title: Block on a frictionless incline
subject: physics
---

A block of mass $m$ rests on a **frictionless** incline of angle $\theta$.

$$\sum F_\parallel = mg\sin\theta = ma$$

```figure
incline angle=30 length=6
mass m at=incline.mid size=0.9 label="m"
force from=m dir=down     label="mg"
force from=m dir=perp-out label="N"
angle at=incline.base from=0 to=30 value="\theta"
```

```answer
a = g\sin\theta
```

What you can express

• Math — full LaTeX (rendered to real glyphs by KaTeX, bundled offline). Any symbol: \frac \int \oint \nabla \hbar \langle\psi| \vec B \otimes \zeta(3) …
• Diagrams — a compact DSL compiled to SVG: mechanics (incline, mass, force, pendulum, pulley, spring…), fields & charges (charge, dipole, bfield, fieldline, gaussian), 3-D & frames (axes3d, sphere, omega), thermo/fluids/waves (container, piston, gas, heat, wavefront), circuits, optics — and path, a freeform Bézier primitive to draw anything.
• Plots — f(x) = … function plots with axes, grids, marks.

Full reference: spec/SPEC.md. Validation schema: spec/schema.json.

The reader

mtph view is a dedicated reader (not a PDF, not a raw browser tab): a Reveal-answer toggle so you can solve first, a Source panel showing the raw .mtph, live-reload on save, and a searchable gallery when you point it at a folder (mtph view ./problems/).

---

Project layout

spec/        the format — SPEC.md, schema.json, examples/*.mtph
thesis/      the doctrine of hard-problem design (phythesis.md)
AGENTS.md    the AI authoring manual
python/      the reference implementation (the `mtph` package + tests)

Docs

File	What
AGENTS.md	How an AI should author .mtph problems
spec/SPEC.md	The .mtph format + full diagram DSL
thesis/phythesis.md	What makes a physics problem hard
spec/examples/	Worked example problems
CONTRIBUTING.md	Dev setup & how to contribute
CHANGELOG.md	Release notes

Status & roadmap

Format v0.2 (current), Python reference implementation: the format + renderer (validate/verify/audit/inspect/render/figure/dev/view/open), the full diagram DSL, five plot modes (function, parametric, polar, vector field, implicit), multi-panel figures, numbered equations (\label/\ref), body answer/solution blocks, grading rubrics, notation packs, dark mode, a CI verify Action, and the AI authoring layer (thesis/card.md, mtph prompt). 0.1 files still validate and render. The macOS native viewer opens .mtph on double-click.

Next: the npm/browser implementation (sharing the same schema.json) — the gateway to a live web viewer, a hosted validator, and shareable links. See js/ for the port in progress.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. The golden rule: spec/schema.json is the source of truth, and any new DSL/format feature ships with a spec entry, a renderer, and a test.

License

MIT — see LICENSE. Bundles KaTeX (MIT) for offline math rendering.