FIELD_NOTES.md

# TeXada Field Notes

Build Small Hackathon field notes for `build-small-hackathon/texada`.

## 1. The Nearby Problem

The user was deliberately small and specific: a physics undergraduate who writes lab reports and homework in LaTeX. The painful part was not solving the math. It was translating already-understood formulas from paper, screenshots, or rough language into valid LaTeX.

The repeated workflow looked like this:

1. Write or derive the formula on paper.
2. Search for the right LaTeX command or AMS environment.
3. Type the formula into Overleaf or Markdown.
4. Fix missing braces, unknown commands, and broken rendering.

TeXada tries to compress that loop into one place: describe or upload the formula, get renderable LaTeX, validate it, auto-fix common syntax mistakes, then copy it out.

## 2. Why This Fits Small Models

Formula conversion is narrow, structured, and easy to verify. The app does not need a large model's broad world knowledge. It needs:

- enough symbolic pattern knowledge to write common math syntax;
- enough visual understanding to read a formula image;
- deterministic checks for braces, environments, and suspicious commands;
- a preview that makes errors visible immediately.

The current Space uses:

- `openbmb/MiniCPM5-1B` for natural-language formula generation and LaTeX completion;
- `openbmb/MiniCPM-V-4.6` for formula image OCR;
- local validation and repair code for syntax checks after inference.

Each model is under the hackathon's 32B cap and also under the Tiny Titan 4B threshold.

## 3. What The Agent Does

The core workflow is intentionally more than one model call:

1. Classify the formula intent with rules: integral, derivative, sum, limit, matrix, probability, or generic.
2. Return a deterministic high-confidence pattern for common demo and study formulas when the match is exact.
3. Otherwise, add intent-specific few-shot examples.
4. Ask the small text model to return only a wrapped LaTeX formula.
5. Extract the LaTeX body from noisy model output if needed.
6. Reject degenerate outputs such as `...`, then fall back to a matched deterministic formula if one exists.
7. Validate braces, `begin`/`end` environments, and command names.
8. Auto-repair common missing braces or unmatched environments.
9. Render the chosen output format and store a short history entry.

For images, the OCR path uses the vision model first, then sends the recognized formula through the same extraction, validation, repair, render, and history path.

## 4. Product Choices

The interface is shaped around the actual work surface:

- left side: editor-style input and output code;
- right side: clean rendered formula preview;
- small status panel: validity, intent, confidence, and latency;
- history rail: recent formulas without forcing account setup or persistence.

The custom styling is meant to feel closer to a code editor than a chatbot. For a STEM writing workflow, copying reliable code matters more than conversational polish.

## 5. What Worked

The biggest win was pairing a small model with deterministic guardrails. A 1B-class model can produce a reasonable LaTeX candidate, while the validator catches issues the model does not need to reason about perfectly.

Intent-specific examples also helped keep simple formulas simple. Without them, even small models can over-upgrade a plain phrase like "x squared plus y squared" into a more abstract expression. The prompt now explicitly asks the model to translate literally.

## 6. Current Limitations

- Handwriting quality still matters. Cropped, low-contrast, or heavily slanted formulas can produce OCR mistakes.
- Validation is syntactic, not semantic. It can tell that braces balance, but not whether the formula matches the student's intended derivation.
- The command whitelist is conservative. Some valid niche LaTeX commands may be flagged as suspicious.
- CPU Space inference can be slow on a cold model load, especially for OCR.

## 7. Next Iterations

- Add a small gallery of real anonymized formula examples and expected outputs.
- Add a "strict copy mode" that strips display wrappers for direct Overleaf insertion.
- Add optional user corrections that build a small eval set over time.
- Expand validation for matrices, `cases`, alignment rows, and delimiter pairing.
- Publish a tiny formula-correction dataset if enough examples accumulate.

## 8. Submission Links

- Space: <https://huggingface.co/spaces/build-small-hackathon/texada>
- Demo video: TODO
- Social post: TODO