SpellCoach AI

Helping children become confident spellers, one word at a time.

SpellCoach AI is a demo / prototype spelling coach for Australian primary school students. Parents upload weekly spelling lists; children practise with guided learning and educational feedback; parents see simple progress insights.

AI advises. Deterministic code decides.

---

Project status

This repository contains the DEMO / PROTOTYPE version (v1.0-demo).

What this is	What this is not
A working Streamlit prototype for demos and portfolio review	A production SaaS product
Validation of product ideas and architecture	Live OpenAI-backed tutoring
Reproducible local demo with seeded data	Multi-tenant, cloud-hosted deployment

Future directions (not claimed as done): adaptive learning, live AI-generated hints, spaced repetition, richer analytics, and a production web stack (Next.js + FastAPI + Supabase).

---

Problem

Parents receive weekly spelling lists from school/Tuitions. Children often practise from paper. It is hard for parents to see:

• which words are mastered
• where mistakes occur
• which spelling patterns are difficult
• whether improvement is happening week to week

SpellCoach AI makes practice more engaging for children while giving parents clearer, local progress insights.

---

Features

Implemented

Feature	Notes
Welcome screen with parent / child paths	Role chooser; child enters without login
Parent demo login	Email + password via Streamlit secrets
PDF weekly-list upload	Filename pattern Term X - Week Y.pdf; pypdf extraction
WeeklyList domain model	Core business object for lists and words
Learning Mode	Meanings, example sentences, memory tips, browser TTS
Practice Mode	Attempt spelling, progressive hints, session scoring
Deterministic error classification	Vowel, omission, transposition, silent letter, and related types
Educational incorrect feedback	Child-friendly tips tied to error type
Local progress persistence	JSON under prototype/data/
Parent dashboard	Scores, word chips, session/week charts, insight summary
Demo mode + seed / reset	Auto-seed on empty data; sidebar reset
Browser text-to-speech	Prototype uses the browser’s native Web Speech API via speech_service (Chrome recommended)
Automated tests	pytest under prototype/tests/

Speech note: The current prototype uses the browser’s native Web Speech API for pronunciation. A production version could integrate a cloud-based neural Text-to-Speech service (such as Azure AI Speech or OpenAI TTS) to provide higher-quality voices, consistent pronunciation, and improved cross-browser reliability.

Demo / Prototype

Feature	Notes
Static educational “AI” content	Meanings, tips, hints, encouragement from ai_service.py dictionaries
OpenAI Python package in requirements	Available for future use; not used on the current demo path
Single demo parent account	Intentionally public credentials for reviewers
Local JSON storage	No database; suitable for demos only
Demo PDF fixtures	Weeks 1–4 under demo/fixtures/
Parent narrative text	Deterministic template strings, not a live LLM

Planned

Feature	Notes
Optional child PIN / access code	Children currently enter with no login
Live schema-validated OpenAI responses	Replace static dictionaries where appropriate
Adaptive learning & spaced repetition	Beyond the current week-centric flow
Production auth & multi-user accounts	Supabase (or equivalent)
Next.js + FastAPI production UI/API	Migrate off Streamlit
Richer cross-term analytics	Beyond current dashboard summaries
Cloud storage & proper child privacy controls	Not present in this prototype
Cloud neural TTS (e.g. Azure AI Speech / OpenAI TTS)	Replace browser Web Speech API for higher-quality, consistent voices

---

Technology stack

Technology	Role	Why
Python	Language	Fast iteration and a strong ecosystem for education / AI tooling
Streamlit	UI prototype	Rapid UI for demos without a full frontend build
Pydantic models (domain classes)	Models	Clear WeeklyList / progress structures
pypdf	PDF text extraction	Read spelling words from uploaded weekly PDFs
Altair	Charts	Simple parent progress visualisations
pytest	Tests	Regression coverage for classifiers, PDFs, analytics
openai (dependency only)	Future client	Package present for later live generation; demo uses static content
Local JSON files	Storage	Zero-ops demo persistence
GitHub Actions	CI	Run pytest on Python 3.11 and 3.12

Production direction (planned): Next.js (polished multi-page UI), FastAPI (portable services layer), Supabase (auth, Postgres, storage). Better for real accounts, security, scaling, and maintainable frontends than a Streamlit single-process demo.

---

Architecture

flowchart TB
    subgraph ui [UI Layer — prototype/UI]
        APP[app.py orchestrator]
        AUTH[auth_view]
        PARENT[parent_dashboard / pdf_upload]
        CHILD[learning_mode / practice_mode]
    end

    subgraph services [Services Layer — prototype/services]
        PDF[pdf_service]
        STORE[storage_service]
        PROG[progress_service]
        ANALYTICS[progress_analytics]
        ERR[error_classifier]
        FEEDBACK[feedback_service]
        HINT[hint_service]
        INSIGHT[parent_insight_service]
        AI[ai_service — static demo content]
        SPEECH[speech_service]
    end

    subgraph models [Models — prototype/models]
        WL[WeeklyList]
        WP[WeeklyProgress / WordProgress]
    end

    subgraph data [Local data]
        JSON[prototype/data/*.json]
        FIX[demo/fixtures/*.pdf]
    end

    APP --> AUTH
    APP --> PARENT
    APP --> CHILD
    PARENT --> PDF
    PARENT --> ANALYTICS
    PARENT --> INSIGHT
    CHILD --> FEEDBACK
    CHILD --> HINT
    CHILD --> PROG
    CHILD --> AI
    CHILD --> SPEECH
    FEEDBACK --> ERR
    HINT --> AI
    PROG --> WP
    STORE --> WL
    STORE --> JSON
    PDF --> FIX

Loading

Principle: AI (or static educational text) may suggest meanings, hints, and encouragement. Deterministic Python owns spelling validation, scoring, progress rules, authentication checks, and persistence.

Full write-up: docs/architecture.md · docs/ai-system-design.md · docs/design-decisions.md

---

Repository structure

.
├── README.md                 # This file
├── LICENSE                   # MIT
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── requirements.txt          # Points at prototype/requirements.txt
├── .env.example
├── docs/                     # Architecture, AI design, demo guides
├── demo/                     # Credentials notes + PDF fixtures
├── prototype/                # Streamlit app (run from here)
│   ├── app.py
│   ├── UI/
│   ├── services/
│   ├── models/
│   ├── tests/
│   └── scripts/
├── sample-data/              # Sample WeeklyList + progress JSON
├── screenshots/              # Screenshot placeholders
├── scripts/                  # Convenience runners
└── .github/workflows/        # CI

---

Quick start

git clone https://github.com/laxmipreethi/spellcoach-ai.git
cd spellcoach-ai

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt    # installs prototype/requirements.txt

cp prototype/.streamlit/secrets.toml.example prototype/.streamlit/secrets.toml
# Demo credentials are already filled in the example — for reviewers only.

./scripts/seed_demo.sh             # or: cd prototype && python scripts/seed_demo_data.py
./scripts/run_prototype.sh         # or: cd prototype && streamlit run app.py

Open the local URL Streamlit prints (usually http://localhost:8501).

Environment

Variable / secret	Purpose
SPELLCOACH_DEMO_MODE	Default true. Set false to disable auto-seed / reset UI
DEMO_PARENT_EMAIL / DEMO_PARENT_PASSWORD	In prototype/.streamlit/secrets.toml
OPENAI_API_KEY	Optional future use only — not required for the demo

See .env.example.

Tests

cd prototype
pytest tests/

---

Demo credentials

These exist only for demonstration. They are intentionally public. Never reuse them in production.

Role	Credential	Value
Parent	Email	parent@spellcoach.demo
Parent	Password	spellcoach123
Child	Access code	N/A — children enter without login in this prototype

Details: demo/credentials.md

---

Demo flow

1. Welcome → I'm a Parent → sign in with demo credentials.
2. Upload a PDF from demo/fixtures/ (or use pre-seeded lists).
3. Confirm extracted words and open the parent dashboard (try Term 1 · Week 3).
4. Welcome → I'm a Child → choose a list → Practice Mode.
5. Intentionally misspell a word (e.g. beatiful for beautiful) → read educational feedback.
6. Spell it correctly → finish the session → return to the parent dashboard.

Full script: docs/demo-script.md · checklist: docs/demo-checklist.md

---

Screenshots

Place PNG/WebP captures in screenshots/:

Placeholder	File
Welcome	screenshots/01-welcome.png
Parent login	screenshots/02-login.png
Parent dashboard	screenshots/03-dashboard.png
Learning Mode	screenshots/04-learning.png
Practice Mode	screenshots/05-practice.png
Progress	screenshots/06-progress.png
PDF upload	screenshots/07-pdf-upload.png
Error classification	screenshots/08-error-classification.png
Session completion	screenshots/09-completion.png

(Images not yet committed — see screenshots README for capture guidance.)

---

Known limitations

Honest summary: single demo parent, no child auth, local JSON only, static educational content (not live LLM), PDF extraction is best-effort for simple text PDFs, Streamlit UX constraints. Full list: docs/limitations.md.

---

Roadmap

See docs/roadmap.md for v0.1 → v0.2 → Demo → Production → Future AI.

---

Contributing

Contributions that preserve architecture (orchestrator / services / UI / models) are welcome. Start with CONTRIBUTING.md and CODE_OF_CONDUCT.md.

---

Security

Prototype-only security posture, demo credentials, and disclosure: SECURITY.md.

---

License

MIT © 2026 Laxmipreethi