GlyphGuide

An agentic handwriting tutor for children that helps them practice and improve basic word writing through intelligent, step-by-step guidance.

Quick Start

Prerequisites: Node 20+, npm

1. Start the Server

cd server
cp .env.example .env   # Add your OPENAI_API_KEY
npm install
npm run dev            # http://localhost:3000

2. Start the Client

cd client
npm install
npx expo start --web   # http://localhost:8081

Environment Variables

Create server/.env with:

OPENAI_API_KEY=your-key
PORT=3000
CORS_ORIGIN=http://localhost:8081

See server/README.md for full API documentation and all environment options.

---

Testing with ngrok

When testing the Expo app on a physical device or emulator, localhost won't work. Use ngrok to expose your server:

# Terminal 1: Start the server
cd server && npm run dev

# Terminal 2: Expose via ngrok
ngrok http 3000

Then update BASE_URL in client/App.js:

// For ngrok use https://<id>.ngrok-free.app (no port)
// For LAN use http://<ip>:3000
const BASE_URL = "https://abc123.ngrok-free.app";

This is the preferred approach for mobile testing with Expo.

---

How It Works

Handwriting flows through a 3-agent pipeline:

Evaluator → Diagnosis Summarizer → Coach Planner

1. Evaluator – Grades the handwriting (1-10), identifies weak letters
2. Diagnosis Summarizer – Creates one child-friendly goal and fix steps
3. Coach Planner – Picks the next word and generates spoken instructions

Results stream to the client via Server-Sent Events. TTS speaks feedback aloud for non-readers.

See server/README.md for detailed agent architecture, data flow, and model configuration.

---

Demo

Watch the demo video

1. Start both server and client
2. Tap "Start practice" to connect to the server
3. Draw on the canvas, press "Submit" to send the strokes to the server
4. Watch: evaluation overlays appear, spoken feedback plays, coach card updates
5. Repeat to see mastery progression

---

API Reference

See server/README.md for endpoint documentation:

• POST /v1/sessions – create session
• GET /v1/sessions/:id/events – SSE stream
• POST /v1/sessions/:id/ink – submit strokes

---

Project Summary

Learn to Write combines stroke rasterization with a 3-agent coaching loop tuned for early writers. Kids see a clean canvas, draw a word, and instantly hear encouragement plus one doable fix. Session-local mastery means no accounts needed—ideal for classroom centers or quick practice at home.

---

Future Scope

• Dictation mode – Children listen to a word and write it from memory, building spelling skills
• Advanced vocabulary – Expand word banks with sentences, sight words, and phonics patterns
• Drawing evaluation – Evaluate freeform drawings (shapes, objects, scenes) with age-appropriate feedback