Research notes · ParaClient
ParaClient is an on-prem AI tutor and maker's assistant for K-12. These notes cover the research decisions behind it: how it teaches, how it stays correct, and why a child's words never leave the box.
A language model is a brilliant proposer and an unreliable authority. So across ParaClient, the model proposes and a deterministic system decides — a grammar constrains what it can say, a checker verifies what it said, and only verified output reaches a student. Where facts change with time, we don't ask the model to remember; we send it to look.
That principle appears as pedagogy (a tutor trained to not just answer), as engineering (circuits and floor plans validated before they render), as sourcing (civics answered from .gov, with a citation), and as safety (a local classifier that fails closed). The rest of these notes is how each one works.
Each solved a specific failure mode of “just prompt a big model.”
A tutor that hands over the answer isn't teaching. Every subject adapter learns two behaviors and switches between them by system prompt at inference.
Instead of many full models, we train a small LoRA adapter per subject on a shared base — tens of megabytes each, hot-swappable, and cheap to serve together.
For circuits, CAD, and spreadsheets the model emits a structured artifact that a deterministic engine checks before anything renders. Invalid drafts are repaired or resampled — never shown.
Training dialogues are only as clean as their source and their generator. We built an LLM-propose / human-review pipeline and gated every dataset on license.
“Who represents my district now?” must never come from model memory — it goes stale. A constrained agent fetches the fact fresh and must cite an official source.
.gov / .mil · answer marked verified only when the citation is on an official domain.A cloud moderation API would mean shipping a child's text off-site. We can't. So safety is a local classifier screening both the student's input and the tutor's output.
Why a small model can be trusted to draw a working circuit: it never gets the last word.
The model emits a netlist — components plus the nets joining their pins. A grammar guarantees valid JSON with known parts; an electrical-rules check rejects shorts, unpowered nets, and un-current-limited LEDs; ngspice / avr8js actually simulate the survivor.
Floor plans pass a geometry gate (inside bounds, no overlaps) with auto-repair before they render or export to DXF. Spreadsheet routes gate the formula on both generation and tutoring, so a student never copies a formula that doesn't compute.
A quiet but important detail: the dataset synthesizer and the serving gateway import the same schema and system prompt. The model is always trained on exactly the instruction it is served with — no train/serve skew.
Free tutoring shouldn't need a GPU; paid, multimodal tutoring should feel instant. So the stack spans two base families across CPU and GPU.
| Tier | Base model | Runs on | Role |
|---|---|---|---|
| v2 | Qwen 2.5 · 7B | CPU · llama.cpp | Free default — responsive tutoring |
| v3 | Qwen 2.5 · 14B | CPU · llama.cpp | Free opt-in — stronger reasoning |
| v4 | Gemma-4 · 12B | GPU · vLLM | Paid — multimodal, image + handwriting |
| circuit | Qwen 2.5 · 3B | CPU · llama.cpp | Specialist — grammar-constrained netlists |
Both families carry the same per-subject LoRA adapters and honor the same two teaching modes, so the pedagogy is identical whether a student is on free CPU or paid GPU.
The Gemma-4 12B tier first ran in 4-bit via in-flight dequantization, which forced eager execution — no CUDA graphs, and slow. Moving to native FP8 on the L4's Ada cores restored graph capture and roughly tripled throughput at the same quality class, still on a single 24 GB card.
Measured on 1× NVIDIA L4 (24 GB), vLLM 0.26, greedy decode, 200-token generations. Quality spot-checked across base + subject adapters.
The obvious way to moderate a child-facing product is a cloud safety API. For ParaClient that's disqualifying — it means transmitting a student's words to a third party. So the safety layer is a local classifier, and it screens in both directions: the student's input and the tutor's output.
One finding shaped the design. ShieldGemma is a probability classifier trained one policy at a time; asking it about a merged policy badly under-detects (empirically P(yes)=0.02 for a racist joke), while a single-policy prompt separates cleanly (0.98 vs 0.00). So we run one pass per K-12 harm category — sexual, violence, hate, dangerous — concurrently, and flag the specific category that crosses threshold.
If the classifier is unreachable, the request is blocked, not allowed. Unavailable moderation is never “safe” for a child-facing product.
Moderation logs record that a screen happened and which category fired — never the content itself. Nothing sensitive sits at rest.
The classifier is a guardrail outside the model, by design. The adapter's training is not the safety net; a separate, auditable system is.
Every capability below shipped and is served on the same single-GPU machine. Hover a point for what landed.