Bilingual (中文+EN) ML / LLM / diffusion / agent interview cheat sheets for AI 秋招 — generated by ARIS /interview-cheatsheet, rendered by /render-html into single-file HTML, reads anywhere — plus a CV→DB
Altair 8800 emulator in your browser: a working front panel, an Intel 8080, an ASR-33 Teletype and Microsoft's original 4K BASIC
8h +2★ 147Education
Do you operate this project?
Owners of public repositories under a personal GitHub account can sign in to verify ownership and manage the introduction themselves. No administrator approval is needed.
Organization repository · verify with a repository file
Sign in, generate a verification file, and commit it to this repository’s default branch within 30 minutes. Files on other branches or forks do not count. Then check the file below to manage the project without administrator approval. Keep the file to retain your access.
If needed, you will go to sign-in. After signing in, return here and press your chosen verification button again.
Run /nomorevibe verify in your project folder to verify ownership and manage the introduction yourself.
A web app that teaches English chunks — the ready-made phrases native speakers use, like “that makes sense” or “get used to” — to learners from A1 to C2, with one daily session: hear it, say it twice, write it, read it aloud, and get pronunciation scores and friendly tips from open-source AI running on infrastructure we control.
Most apps teach single words, but fluent speakers think in chunks: “by the way”, “make a decision”, “I tend to…”. Learners need to say those chunks out loud and know exactly which sounds to fix — and pronunciation feedback usually means sending your voice to a closed cloud API.
This project does the speech scoring with self-hosted open models (Silero VAD, NVIDIA Parakeet, wav2vec2 phonemes) and writes tips with an open-weight LLM (Gemma 4). Learner recordings are scored in memory and deleted immediately — they never touch a disk or a third party. Pronunciation hints come from a fixed, curated table of ~40 English sounds; the AI only adds warmth around them, so the teaching is always correct and consistent.
A session is Learn → Speak (try 1, try 2) → Write → Read aloud → Daily score, with streaks, points, a level-band ranking, a searchable chunk library, learner chunk suggestions with admin review, and an admin console.
Diagrams of the physical deployment, logical components and user workflow are in docs/architecture.md.
Installation
Prerequisites
Tool
Version
Node.js
≥ 22
pnpm
10
Python
3.12 (installed by uv)
uv
≥ 0.12
espeak-ng
≥ 1.51
Docker
any recent (local Postgres)
git clone https://github.com/gusanchefullstack/englishchunks.guru.git
cd englishchunks.guru
pnpm install
# Local Postgres (localhost URLs use the standard `pg` driver)
docker run -d --name ec-pg-dev -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=englishchunks \
-p 54329:5432 postgres:17-alpine
cp web/.env.example web/.env.local # fill in values (never commit them)
export DATABASE_URL=postgres://postgres:dev@localhost:54329/englishchunks
pnpm --filter web db:migrate
pnpm --filter web db:seed # voices, sound hints, 30 starter chunks
# Scoring service + models (~950 MB of ONNX int8 models)
cd scoring
cp .env.example .env
uv sync
uv run python -m scoring.models.download # Silero VAD + Parakeet
uv run --extra export python -m scoring.models.download --wav2vec2 # export + quantize wav2vec2
Quick Start
# Terminal 1 — scoring service on :8001 (models preload in the background)
cd scoring && uv run uvicorn scoring.app:app --port 8001
curl localhost:8001/healthz # {"status":"ok","models":{"vad":true,"asr":true,"phonemes":true}}
# Terminal 2 — web app on :3001
pnpm --filter web dev
Open http://localhost:3001, create an account (confirm you're 16+), click the link in the verification email, choose your level, and start today's chunk.
DigitalOcean Spaces (TTS cache, avatars). Also needed at build time for the CSP
Yes
—
RESEND_API_KEY / EMAIL_FROM
Transactional email
Yes
—
SCORING_URL / SCORING_SHARED_SECRET
Scoring service URL and HMAC secret (≥ 32 chars)
Yes
—
CRON_SECRET
Bearer secret for /api/cron/*
Yes
—
UNSUBSCRIBE_SECRET
Signs one-click unsubscribe links
Yes
—
STRIPE_SECRET_KEY
Stripe restricted key (rk_…)
When billing is on
—
scoring/.env: SCORING_SHARED_SECRET (same as the web app), MODELS_DIR (default ./models), MAX_AUDIO_SECONDS (15), MAX_AUDIO_BYTES (1 MiB), SOUND_HINTS_PATH (set in Docker).
{
"kind": "scored",
"score": 82,
"components": { "sounds": 83, "words": 100, "flow": 95 },
"weakestSounds": [{ "ipa": "ð", "hint": "Put your tongue tip lightly between your teeth, then use your voice. Not \"d\" or \"z\".", "exampleWords": ["that", "the", "other"] }],
"tip": "Lovely rhythm! Let your tongue touch your teeth on “that”.",
"improvement": 12
}
422 {"kind":"unusable","reason":"no_speech"} asks the learner to try again (not counted).
Other routes: GET /api/tts?ref=chunk:<id>|example:<id>|sentence:<id> (302 to audio), POST /api/profile/avatar, POST /api/billing/checkout, POST /api/billing/portal, POST /api/webhooks/stripe, POST /api/cron/hourly, GET|POST /api/cron/daily, POST /api/unsubscribe (RFC 8058).
Web unit + integration (real SQL in PGlite, external services mocked with MSW — unmocked network fails the test)
Vitest
pnpm test
End-to-end (fake mic, real app + Postgres, deterministic AI fakes, axe WCAG 2.2 AA scans, keyboard-only run)
Playwright
pnpm --filter web test:e2e
Scoring unit + OpenAPI contract + "no audio persisted"
pytest
cd scoring && uv run pytest
Scoring calibration on speechocean762 (SC-005, ≥ 85 %)
pytest
uv run pytest -m calibration
Scoring latency (SC-003, p95 ≤ 5 s)
—
uv run python -m scoring.bench
Lint · types · secrets
ESLint · tsc · ruff · mypy · gitleaks
pnpm lint && pnpm typecheck && pnpm secret-scan
Current results: 197 web tests, 21 e2e tests, 30 scoring tests; calibration 89.1 % over 66,189 pairs; scoring server p95 1.68 s on the production Droplet (see scoring/BENCHMARKS.md).
Deployment
Every change goes through a pull request to main; CI (lint, types, unit/integration, Playwright e2e with axe, scoring tests, secret scan) must pass, and merging deploys production automatically. The scoring service is updated separately per its runbook.
Web → Vercel (Hobby while testing; Pro before charging money). Set every variable above in the project, including Spaces ones (used by the CSP at build). vercel.json schedules the daily cron.
Scoring → DigitalOcean Droplet (start 4 GB / 2 vCPU): docker build -f scoring/deploy/Dockerfile -t ec-scoring ., mount models read-only, run with scoring/deploy/scoring.service (read-only root, tmpfs /tmp with exec for espeak), Caddy for TLS, and cron-hourly.timer to call /api/cron/hourly (reminders, invite expiry). See scoring/deploy/RUNBOOK.md.
Billing stays off until an admin types ACTIVATE in Admin → Settings, after the go-live checklist (Stripe test-mode demo, Vercel Pro, restricted live keys, Stripe Tax decision).
What I learned
Spec-driven development with Spec Kit: constitution → spec → clarify → plan → tasks → analyze → implement kept a 150-task build coherent, and /speckit-analyze caught real gaps (Google account-linking takeover, overdue-payment limits) before any code existed.
Next.js 16 Cache Components: request data (cookies(), headers(), searchParams, DB reads) must live inside <Suspense>; read headers before touching anything that needs env during prerender; await connection() marks DB reads as request-time; a streamed page can't change its status code later, so real 404s for the admin area come from proxy.ts.
Pronunciation scoring from first principles: CTC forced alignment and goodness-of-pronunciation (GOP) per phone. Averaging GOP in log space let one leaked boundary frame wreck a clean sound — averaging probabilities fixed it. Word accuracy as in-order recall (LCS) stops “that makes… that makes sense” from being marked wrong. (GOP paper)
Privacy by construction: Starlette spools multipart uploads > 1 MB to disk, so the service rejects oversized bodies before parsing; Docker's --tmpfs is noexec by default, which breaks phonemizer's espeak-ng copy.
Better Auth: email sign-up hides creation failures behind a synthetic success (anti-enumeration), so the account-cap gate must run in a request before hook; implicit Google account linking had to be disabled.
Testing seams that unit tests miss: MSW 3 renamed onUnhandledRequest to onUnhandledFrame (the old option silently let tests hit the real network); a real Chrome MediaRecorder recording and the Docker image each exposed bugs that every fake had hidden.
Accessibility: disabling a button while it's busy drops keyboard focus to <body> — use aria-disabled/aria-busy instead; brand colors needed an AA-safe palette and validated chart colors.
Stripe Billing: one Product per plan, hosted Checkout + Customer Portal, signature-verified idempotent webhooks resolved by Customer ID, and since the 2025 “basil” API the billing period lives on subscription items.
Roadmap
Daily session with self-hosted pronunciation scoring and open-weight LLM feedback
Write tests first; keep pnpm lint && pnpm typecheck && pnpm test, the e2e suite and uv run pytest green.
Use Conventional Commits (feat:, fix:, docs:…) and open a PR describing the user-visible change.
License
Distributed under the MIT License. See LICENSE for details. The AI models keep their own licenses: Silero VAD (MIT), Parakeet TDT 0.6B v2 (CC-BY-4.0), wav2vec2-lv-60-espeak-cv-ft (Apache-2.0), speechocean762 (CC-BY-4.0, calibration only).
Landing video (Spaces CDN) + WebVTT captions and poster (served from web/public/video)
No
walkthrough fallback
Structured output across providers: through the AI Gateway, Gemma runs on a provider without JSON-schema response formats, so the SDK silently dropped the schema and the model invented its own keys. Stating the schema in the system prompt fixed it — and mocked tests could never have caught it.
Perceived latency vs. compute: running ASR and the phoneme model in parallel only saved ~10 % on 2 vCPUs, but streaming the score before the LLM tip (NDJSON from a route handler) removed the 2–3 s the learner actually felt — with zero extra infrastructure cost.
Tailwind v4 defaults: buttons no longer get cursor: pointer, so a single global hover layer (pointer, deeper primary, muted fill) beat editing 30+ class strings.
