CMChristopher Musial

All projects

Live

2026 – present

Homeschool Tools

A parent photographs a handwritten math problem, a vision model returns a validated template, and a preview-or-retake step feeds practice tests on the web and in the Maxon Practice iOS app.

Live site

Private repo, walkthrough on request

Grade 2 spec
15 questions, 30 points
Photo size cap
1600 px JPEG

AI details

What the system actually does

Models

  • Vision model through an AI Gateway.

Techniques

  • Downscale the photo to at most 1600 px JPEG before the vision call.
  • Ask for a reusable JSON template, not a copy of the numbers in the photo.
  • Validate the JSON on the server and in the iOS client before anything is saved.
  • Show a preview with fresh sample numbers, then Save or Retake.

Data

  • One handwritten first- or second-grade math question, or a worksheet of one problem type.
  • Maxon Test A photos plus Practice Tests 1 to 6, used as the source for a written Grade 2 spec.

Evaluation

  • A bad reply is rejected with an error a parent can read, and it isn't stored.
  • Unit tests cover photo-import layouts and the boxed 3-digit add and subtract types.
  • Playwright scripts check the web app, including production checks against the live site.
  • Maxon Practice has had an iPad QA pass.

Challenges

  • The template has to keep the same difficulty with new numbers, using placeholders and ranges.
  • A failed or unconfirmed parse must never become a live question type.
  • Vertical column work and written boxed 3-digit problems are different layouts.
  • Maxon Practice is an iOS app.

Innovations

  • The same photo-to-template flow runs on homeschooltools.co and in the Maxon Practice iOS app.
  • A parent preview is the gate between the model and a saved question type.
  • New Test regenerates all 15 spec questions with fresh numbers, and weak types can build a trouble-spots test.

Stack and tags

  • Vercel
  • AI Gateway
  • JSON schema
  • Playwright
  • iOS
  • PDF
  • vision
  • human-in-the-loop
  • education
  • structured-output

Problem

When a parent has a math problem in front of them, they need more practice of that same kind, not a photocopy with the same numbers. Homeschool Tools is my web test generator (package name home-school-test-generator, page title "Home School Test Generator") on Vercel at homeschooltools.co. The Maxon Practice iOS app uses the same photo-to-template flow.

Why I built it

With it, a parent (or a demo) can photograph one handwritten first- or second-grade math question and get back a reusable question type. The same path turns photos of Maxon's example tests into a written Grade 2 spec and a set of practice tests.

How it works

The photo gets downscaled to at most 1600 px JPEG and sent to a vision model through an AI Gateway. The model is told to return a reusable JSON template: a type name, a layout, placeholders for the operands, an answer formula, and ranges that keep the difficulty the same. A worksheet of several problems of the same kind should come back as one template.

Supported layouts include a single answer box, two-part word problems, fill-in equations, multiple choice, vertical column addition or subtraction (ones, then tens, then hundreds), missing-digit column problems, and sentence frames. A bar-graph visual is allowed only when the photo has a graph the child has to read.

The web route POST /api/template and the iOS VisionClient both validate the JSON before anything is saved. A bad reply is rejected with an error a parent can read, and the parent can retake the photo. The preview shows sample questions with fresh numbers. Save stores the type, and Retake starts over. Nothing from a failed or unconfirmed parse is stored as a live question type.

Saved types then show up in generated practice tests on the website and in Maxon Practice. The iOS app can also share or save a PDF of a test.

Written boxed addition and subtraction are their own built-in types, Q22 and Q23. Each uses two 3-digit numbers from 100 to 999 (addition sums stay at 999 or less), a 4-column by 3-row written work grid, and an answer typed right-aligned on the bottom row. That layout is separate from the photo vertical column layout.

Maxon Practice Tests start from the Test A photos and the Practice Tests 1 to 6 generators. Those are the source for a Grade 2, Chapter 2 Addition and Subtraction Part 1 spec: 15 questions, 30 points, Section A multiple choice (questions 1 to 5), Section B written (questions 6 to 15), number rules, distractors, and bar and number-bond visuals. New Test regenerates all 15 with fresh numbers. Each question can be checked, and Print makes a PDF of the full test plus an optional answer key. The app tracks progress locally and can build a "practice my trouble spots" test from weak types. A person reviewed the printed PDFs and the spec before the generators and the app used them.

Outcome

The result is a reusable question type, or a full 15-question Maxon practice test, on the web and in the iOS app, with fresh numbers every time a test is generated.

Templates are schema-validated before they're saved. Unit tests cover the photo-import layouts (including vertical addition and subtraction, missing digits, and sentence layouts) plus the boxed 3-digit types. Playwright scripts cover the web app, including production checks and local previews of vertical and boxed problems. Maxon Practice has had an iPad QA pass.