README.md

---
title: TeXada — Math Formula Agent
emoji: 🧮
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.16.0
python_version: "3.11"
app_file: app.py
pinned: false
license: mit
short_description: Tiny MiniCPM formula agent for NL/OCR to LaTeX.
startup_duration_timeout: 1h
tags:
  - gradio
  - build-small-hackathon
  - small-models
  - agent
  - latex
  - ocr
  - track:backyard
  - sponsor:openbmb
  - sponsor:openai
  - achievement:offgrid
  - achievement:offbrand
  - achievement:fieldnotes
  - tiny-titan
  - best-agent
models:
  - openbmb/MiniCPM5-1B
  - openbmb/MiniCPM-V-4.6
---

# TeXada — Math Formula Agent

> **一句话**：把自然语言、手写截图里的数学公式 instantly 变成可渲染、可复制的 LaTeX，让写论文和做作业的人少敲 80% 的公式代码。

**参赛赛道**：Backyard AI @ Build Small Hackathon  
**提交三件套**：Space 链接 · Demo 视频 · 社交媒体 Post（见底部链接区）  
**总参数规模**：≤ 32B；并且每个模型都 ≤4B（文本 `openbmb/MiniCPM5-1B` 约 1.08B + 视觉 `openbmb/MiniCPM-V-4.6` 约 1B）

---

## 🧑‍🎓 真实用户与真实痛点

**目标用户**：本科 STEM 同学（物理 / 数学 / 工程 / 计算机专业），在写实验报告、作业、论文、笔记时需要把公式转成 LaTeX。

**真实痛点一句话**：
> “我室友写物理实验报告时，草稿上已经写好了公式，却要花十几分钟去查 `amsmath` 宏包语法、调括号层级、修 KaTeX 报错——明明只是把纸上的公式敲进电脑。”

**对方真的用过**：
- 使用者：某 985 高校物理系大三同学（我的室友），经常需要把实验报告里的手写公式转成 LaTeX。
- 使用场景：把草稿里的公式描述复制进 TeXada，直接拿到可粘贴到 Overleaf / Markdown 的 LaTeX。
- 反馈：
  1. “以前一个公式要查半天符号，现在直接描述就能得到代码，省了很多时间。”
  2. “自动补全括号这个功能救了我，模型生成的公式基本不用再手动修。”
  3. “界面很简单，复制到 Overleaf 就能用，写作业的效率高了不少。”

---

## 🤏 为什么小模型就够？

LaTeX 生成是一个**结构化、语法严格**的任务，不需要大模型的世界知识：

| 约束优势 | 说明 |
|---|---|
| **速度** | 文本 + 视觉模型均约 1B 级参数，CPU Space 上适合“边写边查”。 |
| **隐私** | 作业/论文草稿与截图不上传给闭源大模型，全部在 Space 容器内推理。 |
| **低成本** | 1B 级模型可在免费 CPU Space 上运行，零 API 调用费用。 |
| **诚实匹配** | 任务边界清晰（NL/图片 → LaTeX + 校验 + 修复），小模型足够覆盖。 |

---

## 🏁 Hackathon Submission Evidence

TeXada primarily targets **Backyard AI**: it solves a concrete, recurring workflow for a real STEM student who writes lab reports and homework in LaTeX.

Targeted tags in the README YAML:

| Tag | Evidence |
|---|---|
| `track:backyard` | Built for a physics undergraduate who repeatedly converts handwritten/math-description formulas into LaTeX for reports. |
| `sponsor:openbmb` | Core text generation uses `openbmb/MiniCPM5-1B`; OCR uses `openbmb/MiniCPM-V-4.6`. |
| `sponsor:openai` | Codex was used to implement, debug, document, and prepare the Space submission; the Space history includes Codex-prepared commits. |
| `achievement:offgrid` | Runtime inference happens inside the Space process with open-weight Hugging Face models; no proprietary cloud inference API is called. |
| `achievement:offbrand` | The app uses a custom VSCode-inspired Gradio UI with editor, preview, status, and history panels rather than stock component styling. |
| `achievement:fieldnotes` | Build notes are included in [`FIELD_NOTES.md`](FIELD_NOTES.md). |
| `tiny-titan` | Both declared models are in the tiny-model range and each is under 4B parameters. |
| `best-agent` | The app runs a multi-step formula workflow: intent routing → generation/OCR → LaTeX extraction → validation → auto-fix → rendering/history. |

---

## 🚀 使用方法（2 步）

1. 打开 Space 链接（见底部）。
2. 选择模式：
   - **自然语言 → LaTeX**：输入公式描述，例如 `二重积分 f(x,y) 在区域 D 上`
   - **图片 OCR**：上传手写/截图公式，自动识别为 LaTeX
   - **LaTeX 补全**：输入不完整的 LaTeX 片段自动补全
3. 点击生成/识别，复制右侧代码到 Overleaf / Notion / Markdown。

**支持功能**：
- ✅ 自然语言 → LaTeX
- ✅ 图片 OCR → LaTeX（MiniCPM-V-4.6）
- ✅ LaTeX 片段补全
- ✅ 实时语法校验（括号、环境、命令）
- 🔧 自动修复常见错误（补全 `}`、`\end{}` 等）
- 🎨 Display / Inline / Equation 三种输出格式一键切换
- 🕘 历史记录侧边栏

---

## 🛰️ 部署到 Hugging Face Space

本仓库已部署至：`https://huggingface.co/spaces/build-small-hackathon/texada`

如需重新推送更新：

```bash
cd /Users/caciniep/Desktop/TeXada-BackyardAI-Space
hf auth login
git remote add space https://huggingface.co/spaces/build-small-hackathon/texada  # 若未添加
git push space main
```

首次 Build 会下载模型权重（约 2–3 GB），可能需要 5–15 分钟。

## 🏗️ 本地运行 / 二次开发

```bash
git clone <this-repo>
cd TeXada-BackyardAI-Space
pip install -r requirements.txt
python app.py
```

默认模型为 `openbmb/MiniCPM5-1B`，也可替换为任意 ≤32B 的 Hugging Face 模型：

```bash
MODEL_NAME="Qwen/Qwen2.5-1.5B-Instruct" python app.py
```

---

## ⚙️ 技术栈

- **UI**: Gradio 6.x，VSCode 深色科技风
- **推理**: Hugging Face `transformers`
- **文本模型**: `openbmb/MiniCPM5-1B`（约 1.08B 参数）
- **视觉模型**: `openbmb/MiniCPM-V-4.6`（约 1B 参数，用于图片 OCR）
- **校验**: 括号/环境平衡、命令白名单
- **修复**: 自动补全缺失的 `}` 和 `\end{...}`

---

## 👥 队员

- @Cacinie（需已加入 `build-small-hackathon` org）

---

## 🔗 链接区

- **Space 链接**: https://huggingface.co/spaces/build-small-hackathon/texada
- **Demo 视频**: TODO（30–90 秒，录制并上传后替换）
- **社交媒体 Post**: TODO（发布后将链接替换到这里）
- **Field Notes**: [FIELD_NOTES.md](FIELD_NOTES.md)

---

## 📜 License

本项目基于 [MIT License](LICENSE) 开源。