Remove obsolete test files and training scripts for phoneme CTC model on Palestinian Arabic recordings

.env.example

@@ -1,86 +1,12 @@
-# Copy to .env and fill in. .env is git-ignored and is not copied into the Docker image.
-# On Hugging Face, set these as Space *secrets* instead (Settings -> Variables and secrets).
-
-# Sawtak Arabi TTS key for the model-answer playback (https://sawtakarabi.ai/dashboard).
-# Without it the page falls back to the device's Arabic voice.
-SAWTAK_API_KEY=
-# Optional: the Sawtak voice used for normal model-answer playback. Empty = Raef.
-# Pronunciation-score baselines keep their fixed reference voices and do not use this setting.
-SAWTAK_VOICE_ID=
-# its display name (default אמיר); playback only, the score baseline stays Raef + Fadwa
-SAWTAK_VOICE_NAME=
-
-# Optional: the edge-tts voice of the spoken Hebrew prompts. Empty = he-IL-HilaNeural.
-HEBREW_VOICE=
-
-# Optional: where the generated speech (Arabic answers, Hebrew prompts) is cached. Empty = ~/.cache/ihki-tts.
-TTS_CACHE_DIR=
-# The Hebrew read aloud gets niqqud first (Dicta's free Nakdan, cached in TTS_CACHE_DIR). 0 turns it off.
-HEBREW_NIQQUD=
-
-# Optional: the Hugging Face CTC phoneme model the scorer runs. Unset = facebook/wav2vec2-xlsr-53-espeak-cv-ft.
-# Leave the line commented out rather than empty: an empty value is used as is and fails to load.
-# scripts/bench.py and scripts/rescore.py read it too, so a benchmark runs on the same model as the server.
-# MODEL_ID=facebook/wav2vec2-xlsr-53-espeak-cv-ft
-
-# Optional: how a vowel's GOP pools its frames (docs/gop-pooling.md): max | mean | topk | lse | energy | gated.
-# Empty = gated. "max" is the scoring before pooling. The lab's results show it beside the version, to compare runs.
-GOP_RATIO_POOL=
-
-# Optional: which frames a vowel's competitors are read from. Empty = wide (from the sound before to the one after,
-# as consonants). "narrow" = its aligned frames +- 1, or a number for another margin. Narrow drops spikes in the
-# transitions, but also misses a substitution held just outside it; see scripts/gop_window_bench.py.
-GOP_VOWEL_WINDOW=
-
-# Google sign-in through Supabase (Project Settings -> API Keys). Both values are public: the page gets them too.
-# Empty = no sign-in, the service is open. On Hugging Face these can be plain Space *variables*.
+# Optional Supabase authentication. Leave both empty for a public local app.
 SUPABASE_URL=
 SUPABASE_PUBLISHABLE_KEY=
 
-# Optional: the teacher's account (or several, separated by commas or spaces). After sign-in a teacher chooses
-# between "תרגול" (the same as a student) and "ניהול" (the management panel: every student's progress, and the
-# classes). Who may sign in is set by the classes the teacher opens there (see the README), not here.
+# Required for class roster management.
+SUPABASE_SECRET_KEY=
 TEACHER_EMAILS=
-
-# Bootstrap accounts with full access, including the Lab. Admins do not get Lab access. Keep at least one address here
-# so database permission mistakes cannot lock every developer out.
 DEVELOPER_EMAILS=
 
-# Needed by the management panel and the classes: the project's secret key (Project Settings -> API Keys -> secret, or the
-# legacy service_role key). It reads every student's rows, so it is NOT public: on Hugging Face set it as a *secret*.
-# scripts/bench.py needs it (with the two values above) to read the lab's recordings.
-SUPABASE_SECRET_KEY=
-
-# Public URL of the restricted Grok Business MCP connector. On Hugging Face this is inferred from
-# SPACE_HOST; set it explicitly for a custom domain or local OAuth test. It must end in /mcp/ and
-# exactly match the URL entered in Grok. Authentication is handled by Supabase OAuth, not a shared secret.
-MCP_PUBLIC_URL=
-
-# Optional durable store for flag and Lab recordings. Set AUDIO_BUCKET to a private Hugging Face Storage Bucket
-# and HF_TOKEN as a Space secret with write access. New audio goes only to HF. To migrate old Supabase audio once
-# while preserving a fixed compatibility set, set AUDIO_MIGRATE_BEFORE to the oldest timestamp you want to keep.
-AUDIO_BUCKET=
-AUDIO_BUCKET_PREFIX=ihki-audio
-AUDIO_MIGRATE_BEFORE=2026-10-17T00:00:00+03:00
-
-# Optional: accounts (separated by commas or spaces) that, like the teachers, get a flag under each score, for a recording they said
-# right and the system scored wrong. A flag is kept in the Supabase table `flags` with its recording (see the README),
-# so it needs SUPABASE_SECRET_KEY. These accounts may sign in without being in a class.
-TUTORS_EMAIL=
-
-# Optional deployment metadata shown to teachers at the bottom of the management panel.
-# Without these, the app uses a content hash, the newest source-file time, and the local git commit when available.
-APP_VERSION=
-BUILD_DATE=
-GIT_COMMIT=
-GIT_COMMIT_MESSAGE=
-
-# Lets a developer replace SAWTAK_API_KEY / ANTHROPIC_API_KEY from the management panel (kept encrypted in Supabase,
-# table app_secrets; see the README). Make one with:
-#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-# Keep it only here / as a Space secret. Losing it loses the keys set in the panel (the ones above still work).
-SECRETS_MASTER_KEY=
-
-# the daily video's morning reminder (app/push.py): make one with  python -m app.push
-VAPID_PRIVATE_KEY=
-# PUSH_HOUR=8
+# Enables photographed-problem hints and solutions.
+ANTHROPIC_API_KEY=
+# MATH_MODEL=claude-opus-5-5

Dockerfile

@@ -2,27 +2,15 @@
 # CPU image; runs on Hugging Face Spaces (Docker SDK), Render, Fly, or any VM.
 FROM python:3.11-slim
 
-RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*
-
 # Spaces runs the container as uid 1000
 RUN useradd -m -u 1000 user
 ENV HOME=/home/user HF_HOME=/home/user/.cache/huggingface PYTHONUNBUFFERED=1
 WORKDIR /home/user/app
 
-RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
-ARG MODEL_ID=facebook/wav2vec2-xlsr-53-espeak-cv-ft
-ENV MODEL_ID=${MODEL_ID}
 USER user
-# bake the model into the image so cold starts don't download it (1.2-1.6 GB). MODEL_ID is a Space variable:
-# a wav2vec2 repo, or powsm-onnx:<repo> for the exported POWSM (app/powsm.py). A private repo needs a Space secret
-# HF_TOKEN; it is mounted for this step only and never stored in the image.
-COPY --chown=user app/__init__.py app/powsm.py app/prefetch.py ./app/
-RUN --mount=type=secret,id=HF_TOKEN,mode=0444,required=false \
-    if [ -s /run/secrets/HF_TOKEN ]; then export HF_TOKEN="$(cat /run/secrets/HF_TOKEN)"; fi; python -m app.prefetch
-
 COPY --chown=user app ./app
 COPY --chown=user static ./static
 

README.md

@@ -1,986 +1,25 @@
----
-title: mathly
-emoji: ➗
-colorFrom: blue
-colorTo: gray
-sdk: docker
-app_port: 7860
----
+# Mathly
 
-# احكي · ihki — pronunciation scoring service
+Mathly is a Hebrew ninth-grade algebra practice path. It contains 56 linked skills across six units, immediate feedback for known mistakes, and optional photographed-problem help.
 
-Hebrew prompt → the student says it in spoken Arabic → per-phoneme feedback.
-
-The service replaces the browser speech-recognition diff with phoneme-level scoring:
-
-1. **Phoneme posteriors.** `facebook/wav2vec2-xlsr-53-espeak-cv-ft`, a multilingual wav2vec2 CTC model that outputs IPA phonemes. It was fine-tuned on Common Voice data that includes Arabic, so its vocab should cover the pharyngeals; `/api/health` confirms this.
-2. **Forced alignment.** A CTC Viterbi pass (`app/align.py`, numpy) aligns the audio against each accepted variant's phoneme string and keeps the best-fitting variant. Example: "قديش" said with *k* aligns to the urban variant `ʔ a d d eː ʃ`.
-3. **GOP per phoneme.** Inside each phoneme's window (the frames between its neighbours), the scorer compares the target's peak posterior with the strongest competing phoneme.
-   - Example: for وين الحمام said with a Hebrew ח, the window of `ħ` is dominated by `χ`. The result is `ħ` score ≈ 0, `heard: χ`, and the Hebrew tip for ح→خ.
-4. **Scoring.**
-   - A phoneme's score is a softened target/competitor ratio (`GopConfig.leniency`); a vowel heard as its neighbour (i/e, u/o, short/long) scores at least 90; a dropped glottal stop is free.
-   - A word scores halfway between its weakest phoneme and the mean of its phonemes.
-   - The sentence score averages the phoneme mean and the word mean, so one wrong consonant moves "excellent" down to "almost".
-   - If the greedy phoneme decode is far from every variant, the response says "different sentence?" instead of listing tips.
-5. **Native baseline.** With a TTS key, the phrase's model answer is scored by the same model, and each of the learner's sounds is measured against the score the voice got on it (`app/reference.py`). A sound the model mishears from the native voice too is not marked down and gets no tip.
-
-**Why a letter is coloured.** The answer is shown letter by letter, each coloured by the weakest of its sounds (on a story's line and in every other exercise). A letter under 75 comes with its reason from the server: `why`, the sound and what was heard in its place ("ח (ح) נשמעה כמו ח' (خ)"), and `tip`, the advice for that substitution when `app/tips.py` has one. On the page the reason is the letter's tooltip. A screen with no mouse has no tooltip, so such a letter is also underlined with a dotted line, a tap on it opens the reason in a bubble over the letter, and a line under the result says so.
-
-```
-app/
-  align.py     CTC Viterbi alignment, GOP, greedy decode, edit distance (no torch)
-  scorer.py    model wrapper, IPA → vocab mapping with fallbacks, result assembly, ffmpeg decode
-  tips.py      Hebrew feedback keyed by (expected, heard) phoneme pairs
-  reference.py native baseline: the TTS voices scored by the same model
-  phrases.py   phrase bank: accepted variants (Arabic + IPA) per phrase
-  grammar.py   day-2 sentences as grammar: every pronoun × positive/negative, for the negation and conjugation buttons
-  workbook.py  the course workbook lesson by lesson: each lesson's topics (pronouns, verbs, conjugations, the Hebrew → Arabic and Arabic → Hebrew sentences), and the levels
-  verb_game.py "פועל יוצא" levels 1–5: exercise generation, adaptive choice, server-side grading
-  main.py      FastAPI: page, phrases/scoring, and "פועל יוצא" endpoints
-static/index.html   frontend (MediaRecorder → /api/score)
-train/finetune.py   CTC fine-tuning on your own recordings
-tests/              synthetic-emission tests, including an API test through ffmpeg
-```
-
-## Run locally (Ubuntu)
+## Run locally
 
 ```bash
-sudo apt install ffmpeg
-python3 -m venv .venv && source .venv/bin/activate
-pip install torch --index-url https://download.pytorch.org/whl/cpu
-pip install -r requirements.txt
-uvicorn app.main:app --host 0.0.0.0 --port 7860
+python3 -m venv venv
+venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
+venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 7860
 ```
 
-Open http://localhost:7860. The first start downloads the model (~1.2 GB). CPU inference on a 3 s clip takes about a second.
+Open <http://localhost:7860>. Authentication is disabled when the Supabase values are empty.
 
-Then check `http://localhost:7860/api/health`. Its `phoneme_fallbacks` field lists any phoneme from `phrases.py` that the model's vocab lacks, and what it was mapped to (e.g. `"sˤ": "s"`). A fallback on an emphatic means that contrast cannot be scored until you fine-tune. Look at this first.
+## Configuration
 
-Tests (no model needed):
-```bash
-pip install -r requirements-dev.txt && pytest -q
-```
+Copy `.env.example` to `.env`. `ANTHROPIC_API_KEY` enables photographed-problem help. Supabase settings enable Google sign-in and math-class rosters.
 
-### Browse OpenSpec requirements locally
+For an existing deployment, back up Supabase and then run [docs/mathly-supabase.sql](docs/mathly-supabase.sql) in its SQL editor. The migration deliberately deletes the removed product's tables and non-math classes.
 
-Run [OpenSpec WebUI](https://github.com/oioi555/openspec-webui) from the project root (needs Node 20.19+), then open http://127.0.0.1:3001:
+## Tests
 
 ```bash
-openspec-webui
-```
-
-## פועל יוצא (Switch & Speak)
-
-The Games tab contains an RTL, touch-first conjugation drill with two paths: learning new verbs and a daily retrieval workout. Levels 1–3 implement recognition, pronoun matching, and timed switching. Level 4 records a spoken conjugation; Level 5 starts with a controlled Palestinian-Arabic prompt and evaluates the target conjugation in the response.
-
-Conjugations come only from complete tables in `app/grammar.py` and the fully populated tables verified from the parsed Level 1/2 booklets. Every added booklet form must resolve to an Arabic entry in `workbook.LEX`; incomplete fill-in tables are excluded. Each verb carries the lesson where it is introduced, and signed-in learners receive only forms from their class's lessons.
-
-API endpoints:
-
-- `GET /api/verb-game` returns the available levels, tenses, and lesson-unlocked verbs.
-- `POST /api/verb-game/question` accepts `{"level": 1..3, "mastery": {...}, "recent": [...]}` and returns an opaque question. Correct answers are not sent to the browser.
-- `POST /api/verb-game/answer` accepts `{"question_id": "...", "answer": ..., "response_ms": 1234}`. A question can be graded only once. For Level 2, `answer` is a map from pronoun-card IDs to form-card IDs.
-- `POST /api/verb-game/speech` accepts multipart `question_id` and `audio` for Levels 4–5. `SpeechEvaluationService` wraps the existing phoneme scorer so another dialect ASR can replace it later. An unrelated or low-confidence recognition returns `outcome: "uncertain"` and `counts_as_attempt: false`; it never becomes a grammatical error automatically.
-
-Mastery is currently stored in browser local storage under `ihki.verbMastery` and `ihki.verbSummary`. `VERB_THRESH` in `static/index.html` configures the 85%/90% recognition gates, the Level 3 median response-time gate, and the 85% spoken-response gate; minimum attempt counts are defined next to it. `LEVELS` in `app/verb_game.py` configures choice counts and response windows. Persistent server mastery and spaced repetition remain separate work.
-
-## Deploy for the teacher: Hugging Face Spaces (free, https)
-
-1. Create a Space at huggingface.co → New Space → SDK **Docker** → hardware **CPU basic** (free).
-2. Push this folder to the Space's git repo. The YAML header of this README configures it.
-3. The build bakes the model into the image. The page is then live at `https://<user>-ihki.hf.space`.
-
-The teacher only needs that link. Free Spaces sleep after inactivity, so the first request after a pause takes ~30 s.
-
-`docker build -t ihki . && docker run -p 7860:7860 ihki` runs the same image anywhere.
-
-## Sign-in and progress (Supabase)
-
-Optional. With `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` set, the page asks for a sign-in (through Supabase Auth): with Google, or with a link sent to the student's email (no password), for one without a Google account. The practice endpoints refuse calls without a session. Who may sign in is set by the teacher's classes (see below). Without the two values the service is open.
-
-The email link needs, in Supabase: Authentication → Sign In / Providers → Email enabled; Authentication → URL Configuration → the app's address as the Site URL (or among the Redirect URLs); and Authentication → Emails → SMTP Settings → your own SMTP server, as Supabase's built-in one sends only to the project's team members, a few emails an hour.
-
-Each scored recording adds metadata to the table `attempts`, written with the student's own token so row-level security ties the row to them. The recording bytes are never written to this table or to Storage. Only a teacher/tutor's explicit `/api/flags` report stores its recording in the private `flags` bucket. Create `attempts` once in the Supabase SQL editor:
-
-```sql
-create table public.attempts (
-  id         bigint generated always as identity primary key,
-  user_id    uuid not null default auth.uid() references auth.users (id) on delete cascade,
-  cat        text not null,      -- the topic id, e.g. l1-verbs
-  phrase     text not null,      -- the Hebrew prompt
-  score      int  not null,      -- 0-100
-  unrelated  boolean not null default false,   -- "different sentence?"
-  issues     jsonb not null default '[]'::jsonb, -- compact [{word, expected, heard, score}], never audio
-  model      text not null default '',
-  version    text not null default '',
-  created_at timestamptz not null default now()
-);
-create index attempts_user_time on public.attempts (user_id, created_at desc);
-create index attempts_created_at_idx on public.attempts (created_at desc);
-
-alter table public.attempts enable row level security;
-grant select, insert on public.attempts to authenticated;
-create policy "students add their own attempts"  on public.attempts
-  for insert to authenticated with check (user_id = auth.uid());
-create policy "students read their own attempts" on public.attempts
-  for select to authenticated using (user_id = auth.uid());
-
--- Anonymous aggregate buckets for the teacher's Monitoring graph. Only the backend service role may call it.
-create or replace function public.activity_buckets(p_hours integer default 24, p_bucket_minutes integer default 15)
-returns table (bucket timestamptz, attempts bigint, active_students bigint)
-language sql stable security invoker set search_path = '' as $$
-  select date_bin(make_interval(mins => greatest(1, least(p_bucket_minutes, 60))), a.created_at,
-                  timestamptz '2000-01-01 00:00:00+00'),
-         count(*)::bigint, count(distinct a.user_id)::bigint
-  from public.attempts a
-  where a.created_at >= now() - make_interval(hours => greatest(1, least(p_hours, 168)))
-  group by 1 order by 1
-$$;
-revoke execute on function public.activity_buckets(integer, integer) from public, anon, authenticated;
-grant execute on function public.activity_buckets(integer, integer) to service_role;
-
--- Totals for the full selected window. This is separate from the buckets so a student who practised in several
--- buckets is counted only once.
-drop function if exists public.activity_summary(integer);
-create or replace function public.activity_summary(p_hours integer default 24)
-returns table (attempts bigint, active_students bigint, returning_students bigint, active_days bigint)
-language sql stable security invoker set search_path = '' as $$
-  with windowed as (
-    select a.user_id, (a.created_at at time zone 'Asia/Jerusalem')::date as practice_day
-    from public.attempts a
-    where a.created_at >= now() - make_interval(hours => greatest(1, least(p_hours, 168)))
-  ), per_user as (
-    select user_id, count(distinct practice_day) as days from windowed group by user_id
-  )
-  select (select count(*) from windowed)::bigint,
-         (select count(*) from per_user)::bigint,
-         (select count(*) from per_user where days >= 2)::bigint,
-         (select count(distinct practice_day) from windowed)::bigint
-$$;
-revoke execute on function public.activity_summary(integer) from public, anon, authenticated;
-grant execute on function public.activity_summary(integer) to service_role;
-
--- The same aggregates, limited to the students visible to a subject admin. Keeping this in PostgreSQL avoids
--- downloading and truncating a busy class's attempts in the monitoring page.
-create or replace function public.activity_buckets_scoped(
-  p_user_ids uuid[], p_since timestamptz, p_bucket_minutes integer default 15
-)
-returns table (bucket timestamptz, attempts bigint, active_students bigint)
-language sql stable security invoker set search_path = '' as $$
-  select date_bin(make_interval(mins => greatest(1, least(p_bucket_minutes, 60))), a.created_at,
-                  timestamptz '2000-01-01 00:00:00+00'),
-         count(*)::bigint, count(distinct a.user_id)::bigint
-  from public.attempts a
-  where a.created_at >= p_since and a.user_id = any(p_user_ids)
-  group by 1 order by 1
-$$;
-revoke execute on function public.activity_buckets_scoped(uuid[], timestamptz, integer) from public, anon, authenticated;
-grant execute on function public.activity_buckets_scoped(uuid[], timestamptz, integer) to service_role;
-
-create or replace function public.activity_summary_scoped(p_user_ids uuid[], p_since timestamptz)
-returns table (attempts bigint, active_students bigint, returning_students bigint, active_days bigint)
-language sql stable security invoker set search_path = '' as $$
-  with windowed as (
-    select a.user_id, (a.created_at at time zone 'Asia/Jerusalem')::date as practice_day
-    from public.attempts a
-    where a.created_at >= p_since and a.user_id = any(p_user_ids)
-  ), per_user as (
-    select user_id, count(distinct practice_day) as days from windowed group by user_id
-  )
-  select (select count(*) from windowed)::bigint,
-         (select count(*) from per_user)::bigint,
-         (select count(*) from per_user where days >= 2)::bigint,
-         (select count(distinct practice_day) from windowed)::bigint
-$$;
-revoke execute on function public.activity_summary_scoped(uuid[], timestamptz) from public, anon, authenticated;
-grant execute on function public.activity_summary_scoped(uuid[], timestamptz) to service_role;
-
--- Recent system activity shown only in the management panel. The backend writes with the service-role key;
--- no browser role gets direct table access.
-create table public.system_events (
-  id          bigint generated always as identity primary key,
-  kind        text not null check (kind in ('exercise','game','permission','content')),
-  actor_id    uuid references auth.users(id) on delete set null,
-  actor_email text not null default '',
-  label       text not null default '',
-  details     jsonb not null default '{}'::jsonb,
-  created_at  timestamptz not null default now()
-);
-create index system_events_created_at_idx on public.system_events (created_at desc);
-alter table public.system_events enable row level security;
-```
-
-API keys a developer replaces from the panel (`SAWTAK_API_KEY`, `ANTHROPIC_API_KEY`, see `app/keystore.py`), and the tutor's model (`TUTOR_MODEL`, chosen from a list or typed), so changing one needs no access to the Space. Each value is stored encrypted with `SECRETS_MASTER_KEY`, a Space secret, and the page never gets a key back (the model, which is no secret, it shows). No browser role can read the table:
-
-```sql
-create table public.app_secrets (
-  name        text primary key check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL')),
-  ciphertext  text not null,
-  last4       text not null default '',
-  updated_by  text not null default '',
-  updated_at  timestamptz not null default now()
-);
-alter table public.app_secrets enable row level security;
-revoke all on public.app_secrets from anon, authenticated;
-```
-
-A table made before the panel could set `TUTOR_MODEL` needs its name check widened once (saving the model answers 409 with this SQL until then):
-
-```sql
-alter table public.app_secrets drop constraint if exists app_secrets_name_check;
-alter table public.app_secrets add constraint app_secrets_name_check
-  check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL'));
-```
-
-For an existing `attempts` table, add the compact diagnostics once. Until this migration is run, attempts continue to be saved without diagnostics:
-
-```sql
-alter table public.attempts
-  add column if not exists issues jsonb not null default '[]'::jsonb,
-  add column if not exists model text not null default '',
-  add column if not exists version text not null default '';
-```
-
-The page reads these rows back through `GET /api/progress` (best score and tries per phrase, recordings, days practised, distinct practice days in the current week, and current/longest consecutive-day streaks); the best scores then follow the student between devices. Above the path, **הערבית שכבר שלכם** turns every practised phrase into a bead, except that a story or dialogue is represented by one bead for the whole topic. A phrase turns gold at 75 or more; a story's bead turns gold only when all of its lines do. Completing every listed spoken phrase in a lesson awards one **מסבחה**. The prominent collection card separately counts regular beads, gold beads, and מסבחות; its detail view marks each completed lesson's מסבחה. A compact collector at the top of the exercise card opens the same collection. When a new exercise bead is earned, its regular or gold bead flies from the microphone into that collector instead of showing a text popup. It also shows a four-day weekly practice ring and a 🔥 consecutive-day streak; yesterday keeps a streak alive until the student has had today to continue it. Gold upgrades, a newly completed lesson's מסבחה, meaningful personal bests, streaks and completed topics are celebrated on the practice card. Moving past a topic's last sentence once every sentence was practised opens the topic's end: a bead per sentence (gold 75+, red under 60). With no red bead it is a medal, stars, confetti and a chime, and the button goes on to the next topic (the lesson's next, or the next lesson's first). With red beads it offers a short round of just those sentences, after which the dialog comes back showing what improved; the student can also go on regardless. A bead opens its sentence. Hands-free driving mode skips the dialog. The teacher's **דיווחים** tab aggregates `issues` without returning student identities. It shows a candidate when the same judgement occurred in at least five attempts, for at least three students and 30% of the students who attempted that phrase. These are investigation candidates, not proof of a scoring error; a teacher must explicitly turn one into a calibration draft and apply it.
-
-### The teacher
-
-Access is managed from **ניהול → הרשאות**. Its matrix grants practice, management, Lab, games, the digital library,
-problem reporting, יאללה נדבר, and the learning path independently. יאללה נדבר has its own permission because each
-conversation uses the paid model API; unlike the other student features it is off until explicitly granted.
-Developers have full access including the Lab; admins do not receive Lab access. `DEVELOPER_EMAILS` bootstraps one or more developer
-accounts; keep at least one there to prevent a database mistake from locking every developer out. Existing
-`TEACHER_EMAILS` accounts retain the old management abilities during migration, but no longer receive Lab access.
-
-On first use, the permissions tab displays this migration to run in the Supabase SQL editor:
-
-```sql
-create table public.user_access (
-  user_id uuid primary key references auth.users(id) on delete cascade,
-  email text not null,
-  roles text[] not null default array['student']::text[],
-  entitlements text[] not null default '{}'::text[],
-  subject text not null default '',                 -- developer-set subject for admin-created classes
-  updated_at timestamptz not null default now(),
-  updated_by uuid references auth.users(id),
-  constraint valid_roles check (roles <@ array['student','teacher','flagger','admin','developer']::text[]),
-  constraint valid_entitlements check (entitlements <@ array['practice','games','tutor','path','library']::text[])
-);
-create unique index user_access_email_idx on public.user_access (lower(email));
-alter table public.user_access enable row level security;
-create table public.access_audit (
-  id bigint generated always as identity primary key,
-  target_user_id uuid not null,
-  changed_by uuid not null,
-  old_access jsonb not null,
-  new_access jsonb not null,
-  created_at timestamptz not null default now()
-);
-alter table public.access_audit enable row level security;
-```
-
-If `user_access` was created with the earlier three student features, run this once:
-
-```sql
-alter table public.user_access add column if not exists subject text not null default '';
-alter table public.user_access drop constraint if exists valid_entitlements;
-update public.user_access
-set entitlements = array_append(entitlements, 'practice')
-where 'path' = any(entitlements) and not ('practice' = any(entitlements));
-alter table public.user_access add constraint valid_entitlements check (
-  entitlements <@ array['practice','games','tutor','path','library']::text[]
-);
-```
-
-`TEACHER_EMAILS` names the teacher's Google account (several are separated by commas or spaces). After sign-in a teacher chooses between **תרגול**, the same practice a student gets, and **ניהול**, the management panel. The panel lists every student with their usage (recordings, those of the last 7 days, days practised, last practice), progress (sentences practised) and grade (the average of the best scores), and pressing a student opens their own screen in place of the class's: their figures, their homework, every lesson of the class with its topics, and their best and weakest sentences, all counted as the class counts. "חזרה לכיתה", or the browser's back button, returns to the class.
-
-### Flags: a score that is wrong
-
-Sometimes a sentence is said right and the system scores it wrong. The teachers (`TEACHER_EMAILS`) report such cases, and `TUTORS_EMAIL` names more accounts that do (several are separated by commas or spaces; they may sign in without being in a class, and get no management panel). The rank is kept by email in the table `tutors`:
-
-```sql
-create table public.tutors (
-  email      text primary key,
-  granted_by text not null default '',   -- the teacher who gave the rank
-  created_at timestamptz not null default now()
-);
-alter table public.tutors enable row level security;   -- no policy: only the secret key reads and writes it
-```
-
-Under each score a teacher or a tutor gets an optional note and the button "🚩 אמרתי נכון, המערכת טעתה". Pressing it sends the recording to `POST /api/flags` (teachers and tutors only), which keeps the structured diagnosis in the table `flags`, written with `SUPABASE_SECRET_KEY`. By default the recording is kept in the private Supabase `flags` Storage bucket. When `AUDIO_BUCKET` names a private Hugging Face Storage Bucket (and the `HF_TOKEN` Space secret can write it), new recordings go only below `AUDIO_BUCKET_PREFIX/flags`. Reads fall back to Supabase for existing recordings. Once, recordings older than the fixed `AUDIO_MIGRATE_BEFORE` boundary are copied to HF and only successfully copied objects are deleted from Supabase; a completion marker prevents later startup scans. Its default is `2026-10-17T00:00:00+03:00`, preserving the seven days that were current when this migration was introduced; that boundary does not move. The row holds:
-
-- who and what: `email`, `cat`, `phrase`, `he`, `note`;
-- the answer the scorer matched (`ar`, `ipa`), its free decode (`heard_ipa`), `score` and `unrelated`;
-- `result`: the whole score response, including the structured diagnostic trace (every word and phoneme, pipeline stage, threshold, score, replacement, tip and issue);
-- `model` and `version`, so a flag can be checked against the model and build that produced it;
-- `audio`: the private Storage object name when the upload succeeded, otherwise null.
-
-Create the table once (until then a flag is refused with this command in the message):
-
-```sql
-create table public.flags (
-  id         bigint generated always as identity primary key,
-  email      text not null,      -- the tutor
-  cat        text not null,      -- the topic id
-  phrase     text not null,
-  he         text not null,      -- the Hebrew prompt
-  ar         text not null,      -- the accepted answer the scorer matched
-  ipa        text not null,      -- its phonemes: what the tutor says was said
-  heard_ipa  text not null,      -- the model's free decode
-  score      int  not null,
-  unrelated  boolean not null default false,
-  note       text not null default '',
-  result     jsonb not null,     -- the whole score response
-  model      text not null,
-  version    text not null default '',
-  audio      text,               -- object name in the private flags Storage bucket
-  status     text not null default 'pending', -- pending, confirmed, rejected, or fixed
-  category   text,
-  reviewed_by text,
-  reviewed_at timestamptz,
-  review_note text not null default '',
-  false_issues jsonb not null default '[]'::jsonb, -- [{word, expected, heard}]
-  created_at timestamptz not null default now()
-);
-alter table public.flags enable row level security;   -- no policy: only the secret key reads and writes it
-
-insert into storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
-values (
-  'flags',
-  'flags',
-  false,
-  2000000,
-  array['audio/webm','audio/ogg','audio/mp4','audio/mpeg','audio/wav','audio/x-wav']
-)
-on conflict (id) do update set
-  public = excluded.public,
-  file_size_limit = excluded.file_size_limit,
-  allowed_mime_types = excluded.allowed_mime_types;
-```
-
-For a `flags` table created before reviews were added, run once:
-
-```sql
-alter table public.flags
-  add column if not exists status text not null default 'pending',
-  add column if not exists category text,
-  add column if not exists reviewed_by text,
-  add column if not exists reviewed_at timestamptz,
-  add column if not exists review_note text not null default '',
-  add column if not exists false_issues jsonb not null default '[]'::jsonb;
-```
-
-The management panel's **דיווחים** tab lets a teacher open the existing diagnostic dashboard beside the approval action, hear the stored recording, confirm or reject each report, classify it, and select the individual sound judgements that were false. The dashboard includes synchronized recording playback and a copyable, identity-free text payload for asking a chat assistant to distinguish acoustic-model, alignment, rule, threshold and feedback failures and suggest regression tests. The tab groups confirmed `expected → heard` pairs by reports, reporters, and phrases. Only confirmed reports should be used for calibration.
-
-### The lab (מעבדה)
-
-A teacher gets a third button on the opening screen, **מעבדה**, beside תרגול and ניהול. It is the recording bench for measuring the phoneme recognition. [app/lab.py](app/lab.py) holds a fixed diagnostic list: hard letters as syllables (حا, عا, صا …), minimal pairs (حال / هال / خال, صيف / سيف, طين / تين …) and each hard sound at the start, middle and end of a word. Before recording an item, the teacher marks how it will be said: right, or with a planted mistake on one sound. `POST /api/lab/score` scores the recording as practice does (with the native baseline and the stage-by-stage trace) and keeps it with that label. The page shows, sound by sound, whether the scorer agreed with the label: a sound said right but flagged, or a planted mistake not flagged.
-
-The lab opens on **מבחן**, a test that walks one speaker through the whole list. The speaker types their name; the list shows a row per item (what to say, its state, and record / play / accept / reject), grouped like the list, with the next row not yet submitted highlighted. Recording stops by itself on silence and the take plays back at once; after it was heard, **✓ אישור** keeps it as said right (`POST /api/lab/score`, the speaker's name with it) and moves the highlight to the next row, and **✗** discards it so the row can be recorded again. Every row is new, recorded (waiting for approval), submitted or rejected. Submitted comes from the server (`GET /api/lab?speaker=` returns the speaker's own counts as `mine`), so it holds across devices; rejected is remembered on the device; a take waiting for approval lives in the page only. Any row can be recorded out of turn. Keys, on the highlighted row: space records, Enter accepts, Backspace rejects. **הקלטה** is the single-item bench, where a planted mistake can be marked. Under it, **מבחן אוטומטי בקול TTS** runs the same test without a person: a TTS voice (ראאף or חנאן) says each item not yet submitted (`POST /api/lab/tts`), and it is kept as said right by the speaker "TTS <voice>", with a log line per item (its score, what was flagged, ▶ to hear what was sent). It is scored without the native baseline, which is made of the same voice and would measure every sound against itself. A TTS voice is one more near-native speaker for the benchmark, not a replacement for people: compare them in **תוצאות** by speaker.
-
-The lab has two more tabs. **דיווחים** runs the confirmed score reports through the current scorer, and shows for each sound a teacher marked in ניטור as wrongly flagged whether it is still flagged. **תוצאות** is the benchmark of the lab's recordings as they were scored, per sound: how often a sound said right was flagged (false rejections), how often a planted mistake was caught (detection), the mean score, what was heard instead, and how many confirmed reports name the sound. To rescore everything with the current model and rules and compare against the stored numbers, run `python scripts/bench.py` (`--flags` adds the confirmed reports, `--no-baseline` scores without the TTS baseline, `--speaker` keeps one speaker). Run it before shipping a scoring or model change: false rejections should go down without detection going down with them.
-
-Recordings go to the table `lab_samples` and, by default, the private Supabase storage bucket `lab`, written with `SUPABASE_SECRET_KEY`. With `AUDIO_BUCKET`, new recordings go only below `AUDIO_BUCKET_PREFIX/lab`; the optional fixed-cutoff migration first copies older recordings to Hugging Face and only then removes their Supabase copies. Until the table exists, the lab still scores but keeps nothing, and shows this SQL to run once:
-
-```sql
-create table public.lab_samples (
-  id bigint generated always as identity primary key, email text not null,
-  item text not null, ar text not null, ipa text not null, speaker text not null default '',
-  label text not null,             -- 'correct' or 'mistake'
-  mistake jsonb,                   -- {"index", "expected"}: the sound said wrong on purpose
-  device text not null default '', score int not null, heard_ipa text not null,
-  flagged jsonb not null default '[]'::jsonb,   -- the sounds the scorer marked down, "expected>heard"
-  result jsonb not null, model text not null, version text not null default '',
-  audio text,                      -- the recording's name in the storage bucket lab
-  created_at timestamptz not null default now());
-alter table public.lab_samples enable row level security;
-insert into storage.buckets (id, name) values ('lab', 'lab') on conflict (id) do nothing;
-```
-
-### The trace dashboard (לוח אבחון)
-
-[static/trace.html](static/trace.html) shows one recording through the scorer, for engineers, linguists and teachers. Open it with **לוח אבחון** from a lab recording or from a teacher's phoneme dialog; it reads that result's trace in a new tab. It has four panels that follow one selected sound (hover it anywhere, click to pin, ← → to step):
-
-1. the frames around the sound: target, competitor and neighbour posteriors, frame energy, and the window it was read from (the end of the sound before to the start of the one after)
-2. its score stage by stage: raw GOP → exemptions → cluster cap → native baseline → teacher floor → final
-3. the readings the audio was aligned to, with the winning CTC path, and the edit-distance gauge for a different sentence
-4. the sentence by word and sound, coloured by score, with how sounds add up to words and words to the sentence. When the recording was scored against native baselines, each TTS voice gets a row of its own scores under the sounds; the voice a sound was measured against (the lowest) is in bold. The waterfall marks every voice on the baseline step, and the table has a column per voice
-
-The data's schema is [docs/trace-schema.ts](docs/trace-schema.ts). `python scripts/mock_trace.py` regenerates the example (`static/assets/trace-mock.json`, the "דוגמה" button) by running the real scorer on synthetic posteriors, with a substitution, a teacher floor, a native baseline and a noise spike beside a short vowel planted in it (the spike shows how a sound's window takes in its neighbours' blank frames). `?src=mock` opens the example, `?i=6` pins a sound.
-
-### Calibration proposals
-
-Beside every confirmed `expected → heard` pattern, the teacher can create a calibration proposal. A proposal is only a draft until the teacher chooses its score floor and applies it, globally or to one of the supporting phrases. Applied rules are loaded into the scorer at startup and refreshed immediately after a proposal is applied, updated, or disabled; Supabase is not queried while scoring each recording. Phrase-specific rules take precedence over global ones. Create the private table once:
-
-```sql
-create table public.calibrations (
-  id          bigint generated always as identity primary key,
-  expected    text not null,
-  heard       text not null,
-  floor       numeric not null default 70,
-  scope       text not null default 'global', -- global or phrase
-  phrase      text not null default '',
-  evidence    jsonb not null default '{}',    -- report/reporter counts and supporting phrase keys
-  model       text not null default '',
-  status      text not null default 'draft',  -- draft, applied, or rejected
-  proposed_by text not null,
-  reviewed_by text,
-  reviewed_at timestamptz,
-  created_at  timestamptz not null default now()
-);
-alter table public.calibrations enable row level security;
-```
-
-An applied rule raises only the matching phoneme score to its configured floor; it never lowers a score. The score response includes `calibrated` when a rule changed it, so a flagged result records which rule effect was involved.
-
-### Pronunciation rules
-
-The scorer reads its dialect and Hebrew-speaker rules from the yaml blocks of `static/assets/pronunciation-rules.md` (see `app/rules.py` and `docs/scoring-dialects-plan.md`). The **ניטור** tab lists every rule taken from that document, under **כללי ההגייה מהמסמך**: which realisations of a letter count as correct, how a mistake is judged (exemptions, per-pair margins), and the feedback each rule gives. All are on by default. A teacher can switch one off, which brings back the behaviour from before the document for every student from the next recording on. The switches are loaded into the scorer at startup and refreshed right after a change. Create the private table once (without it the list still shows, all on, and cannot be changed):
-
-```sql
-create table public.scoring_rules (
-  id         text primary key,                 -- a rule of rules.TOGGLES, e.g. dialect_Q, margins, rule_pharyngeal_h
-  active     boolean not null default true,
-  updated_by text not null default '',
-  updated_at timestamptz not null default now()
-);
-alter table public.scoring_rules enable row level security;
-```
-
-### Levels
-
-The course has levels, each with a planned number of lessons (`LEVELS` in `app/workbook.py`: שלב א and שלב ב, 10 lessons each). Every lesson in `LESSONS` is keyed by its level and number, `(level, lesson)`; one outside the plan stops the app at startup. The path shows each level under its name, and the lessons not written yet as "בקרוב". Level 1's lessons keep their first ids ("1", topics "l1-…") so recorded attempts and saved classes still match; later levels' are "2.1", topics "l2.1-…".
-
-A lesson's homework in the workbook, sentences of the student's own, is a topic of the kind `"write"`, the lesson's last ("כתיבת משפטים": `l1-hw`, `l2-hw`). It has no sentences to say: its task and the number of sentences are in `WRITING` in `app/workbook.py`, and on the path it opens a box with the task and a line for each sentence; it is done once every line is filled. Nothing is scored, so the lesson's count of practised sentences leaves it out.
-
-What a signed-in student writes is sent to the server as they write (`PUT /api/writing/<topic>`) and kept in the table `writings`, a row per student and topic, so it follows them to any device (`GET /api/writing`). The device keeps a copy too: lines the server did not take stay there and are sent on the next visit, and without sign-in the copy is all there is. Create the table once in the Supabase SQL editor:
-
-```sql
-create table public.writings (
-  user_id    uuid not null default auth.uid() references auth.users (id) on delete cascade,
-  topic      text not null,      -- the topic id, e.g. l1-hw
-  lines      jsonb not null,     -- the sentences as written, "" for one not written yet
-  updated_at timestamptz not null default now(),
-  primary key (user_id, topic)
-);
-
-alter table public.writings enable row level security;
-grant select, insert, update on public.writings to authenticated;
-create policy "students read their own writings"   on public.writings
-  for select to authenticated using (user_id = auth.uid());
-create policy "students add their own writings"    on public.writings
-  for insert to authenticated with check (user_id = auth.uid());
-create policy "students change their own writings" on public.writings
-  for update to authenticated using (user_id = auth.uid()) with check (user_id = auth.uid());
-```
-
-Until the table exists the sentences stay on each student's device and the panel shows none.
-
-A writing topic can be the class's homework like any topic, and is the one offered: the new-class steps open with it chosen, and in a class's "עריכה" setting a day with no topic chosen picks the written homework of the class's last lesson that has one, so the teacher has only the day to set. The panel then counts its sentences ("נכתבו 3 מתוך 5") in the homework's summary and column, and a student's own screen lists the sentences they wrote under the topic.
-
-### Classes
-
-In the panel the teacher opens a class in five steps, a question each: its name (such as "מתחילים אוקטובר 2026"), its level (the class studies all the level's lessons; one not written yet opens to the class once it is), its students (ticked from the accounts the panel knows, or added by Google email, each with an optional nickname), its homework, and a summary to confirm, which says where all of it is changed later. That is the class's edit dialog ("עריכה", beside the class in the panel's list of classes): the name, the lessons one by one (by level: a level's box ticks all of it), the homework, and the students, a line each with the Google email and an optional nickname (`dana@gmail.com דנה`); the class is deleted there too. A student may be in several classes: after the opening screen the page asks which one they practise in now, and the learning path shows that class's lessons (a teacher, and anyone before the first class, sees every lesson and is not asked). The page shows the class under the app's name, and pressing it lists the class's students, with a button to move to another class; each student appears by their nickname in it or else their Google name (no addresses; `GET /api/classmates`). Once there is a class, only the classes' students and the teachers can sign in; before the first one, any Google account can.
-
-The panel's parts are chosen at its top (**תוכן** is described under "Content and videos"). **כיתות** lists the classes, each with its lessons, students and homework and its buttons: "עריכה", "מחיקה", and "התקדמות התלמידים", which moves to the other part; "כיתה חדשה" opens the steps above. An admin sees, edits and deletes only classes whose `subject` matches the subject assigned to that admin by a developer; developers see every subject. A new class receives its admin's subject on the server, regardless of anything sent by the browser. **תלמידים** starts with one unique list of the students in those visible classes, with an "all students" filter and a filter for each class; every row names the student's classes. An admin with no matching classes sees no students; the old unscoped setup shows every signed-in account before its first class is created. The all-students view uses the student's overall progress, and their page offers buttons for switching into each class's context. A class filter counts only what its students practised since the class was opened (its `created_at`), so a new class starts clean even when its students practised the same lessons before, in another class or in none; the students' own path keeps all they did. Every non-empty recording is a try and completes its exercise, including one that did not match the sentence on the screen (`unrelated`); only an empty recording remains incomplete. The panel still shows unmatched recordings diagnostically as "לא זוהו" beside the student and each topic. A class filter shows the class's figures, its lessons (each with the sentences the class finds hard: the class average of each student's best score under 70) and its students, with the same columns however many lessons the class has: the homework topic (when one is set), all the class's sentences, and the grade. This replaces the former `ALLOWED_EMAILS`, which is no longer read. The lessons limit what the path shows; the sentences themselves stay public, as before.
-
-### Content and videos
-
-The panel's third part, **תוכן**, shows the course as the students get it: every level, its lessons (those not written yet as "בקרוב"), and under each ready lesson its topics in the path's order. There the teacher adds a video to a lesson: a name and a Vimeo or YouTube link (any form of a YouTube video's link: `youtube.com/watch?v=…`, `youtu.be/…`, a short, a live), a Vimeo one as Vimeo's share button gives it (`https://vimeo.com/1233611297/d46ac373c8?share=copy&fl=sv&fe=ci`; the hash after the number is what opens an unlisted video, and the sharing parameters are dropped). The video becomes a topic of the lesson, with ▶ on its circle, and pressing it plays it in a box over the page, in Vimeo's player. A lesson may have several videos. A new one is added at the lesson's end, and the ↑ ↓ arrows on its row move it a step at a time to its place: before the first topic, between two topics, beside another video, or after them all. The path shows the lesson in that order. A video is not practised, so it counts in no figure; the path marks the ones a student opened ("✓ נצפה"), on their device only. In the panel each video also has "צפייה" and "מחיקה". Students get the videos of their classes' lessons (`GET /api/videos`); adding, moving and deleting (`POST /api/videos`, `PUT /api/content/order`, `DELETE /api/videos/{id}`) answer teachers only.
-
-The videos are kept in Supabase like the classes, read and written with `SUPABASE_SECRET_KEY` only. Create the table once (until it exists the lessons have no videos, and adding one is refused with this command in the message):
-
-```sql
-create table public.videos (
-  id         bigint generated always as identity primary key,
-  lesson     text not null,                        -- the lesson id, e.g. 2 or 2.1
-  title      text not null,                        -- the topic's name on the path
-  url        text not null,                        -- https://vimeo.com/<number>[/<hash>] or https://www.youtube.com/watch?v=<id>
-  pos        int,                                  -- how many of the lesson's own topics stand before it; null = after them all
-  ord        int  not null default 0,              -- its turn among the videos of one place
-  created_at timestamptz not null default now()
-);
-alter table public.videos enable row level security;
-```
-
-A table made before videos had places needs the two columns (until then its videos show after their lessons' topics, and adding or moving one is refused with this command in the message):
-
-```sql
-alter table public.videos add column if not exists pos int, add column if not exists ord int not null default 0;
-```
-
-### Daily videos
-
-Apart from a lesson's videos, each level has a library of daily videos. In **תוכן** each level opens and closes on its name (it stays as it was left, on that device); inside, the card "סרטונים יומיים" lists them; the teacher adds one (a name and a Vimeo or YouTube link) and deletes one there. A video in the library is shown to nobody until a class gives it a day: in the class's dialog ("עריכה"), and in the fourth step of opening a class, every daily video of the class's levels has a date field. The students find them in the "סרטון יומי" button above the path: it opens today's video, and is highlighted until that one is opened (on that device); with no video to watch today it opens the list of the earlier ones, the latest first, so a missed day can be caught up. A video whose day has not come, one without a date, one deleted from the library, or one of a level the class does not study, is not shown. It is the first of three buttons that stay in sight above the path: "סרטון יומי", "תרגול יומי" and "שיעורי בית" (the nearest one still to do). A teacher, who practises in no class, sees the daily videos of every class.
-
-The library is kept in Supabase, read and written with `SUPABASE_SECRET_KEY` only. Create the table once (until it exists adding a video is refused with this command in the message), and add the `dailies` column to `classes` (see "Classes" below):
-
-```sql
-create table public.dailies (
-  id         bigint generated always as identity primary key,
-  level      text not null,                        -- a level id, e.g. 1
-  title      text not null,
-  url        text not null,                        -- https://vimeo.com/<number>[/<hash>] or a YouTube link
-  created_at timestamptz not null default now()
-);
-alter table public.dailies enable row level security;
+venv/bin/python -m pytest
 ```
-
-### The daily video's morning reminder
-
-On the "סרטון יומי" screen a student taps "🔔 הזכירו לי כל בוקר" to get a push notification on that device each morning that one of their classes has a daily video (a teacher's account: any class's). It goes at `PUSH_HOUR` (default 8) Jerusalem time, once a day per device, and opens the daily videos' screen. On an iPhone it works only from the app added to the home screen (iOS 16.4+). See `app/push.py`.
-
-Set the Space secret `VAPID_PRIVATE_KEY` (make one with `python -m app.push`; changing it drops every device's subscription), and create the table once:
-
-```sql
-create table public.push_subs (
-  endpoint    text primary key,                   -- the browser's push address
-  email       text not null,
-  p256dh      text not null,
-  auth        text not null,
-  every_class boolean not null default false,     -- a teacher's: every class's daily videos
-  last_daily  date,                               -- the day it was last reminded
-  created_at  timestamptz not null default now()
-);
-alter table public.push_subs enable row level security;
-revoke all on public.push_subs from anon, authenticated;
-```
-
-The Space must be awake at that hour for the reminder to go.
-
-### Video library
-
-Apart from those there is one library of videos for the whole course: they are not part of the path, need no date, and are the same for every level and class. In **תוכן** the card "ספריה דיגיטלית" comes first, above the levels; the teacher adds a video (a name and a link), renames one, moves one up or down the list with its arrows, and deletes one there. A permitted student enters it from the "ספרייה דיגיטלית" button on the opening screen: a list appears, and a video plays in the same box as the path's videos. The ones opened are marked (on that device). Create the table once (its `level` column stays empty):
-
-```sql
-create table public.library (
-  id         bigint generated always as identity primary key,
-  level      text not null,                        -- a level id, e.g. 1
-  title      text not null,
-  url        text not null,
-  ord        int,                                  -- its turn in the list; none until the teacher moves a video
-  created_at timestamptz not null default now()
-);
-alter table public.library enable row level security;
-```
-
-A library made before its videos could be moved has no `ord` column; until it is added, moving a video is refused with this command in the message (renaming works without it):
-
-```sql
-alter table public.library add column if not exists ord int;
-notify pgrst, 'reload schema';
-```
-
-For the video to play inside the page, its Vimeo privacy setting has to allow embedding (on this site's domain, or anywhere); a YouTube video has to allow embedding too (it does unless its owner turned that off), and plays from `youtube-nocookie.com`.
-
-Keeping the link from being passed on is done in Vimeo, not here: the page has to give the browser the player's address, so a student who looks for it finds it (the server only keeps the link itself, `url`, for teachers). In the video's privacy settings on Vimeo, hide it from vimeo.com and allow embedding on specific domains only, naming the app's own domain (on Hugging Face, `<owner>-<space>.hf.space`). The video then plays inside the app and nowhere else: its link, opened or embedded anywhere else, shows nothing. Domain-level privacy needs a paid Vimeo plan.
-
-#### Managing the library and class rosters from Grok
-
-The app can expose a restricted [Model Context Protocol](https://modelcontextprotocol.io/) connector so a teacher can manage the digital library and basic class rosters, and read privacy-preserving monitoring data, from Grok Business without receiving a Supabase secret, Hugging Face token, or general administrator access. It exposes fifteen tools: four library tools, three class tools, and eight read-only monitoring/analytics tools: `get_activity_timeseries`, `get_current_activity`, `get_system_health`, `get_exercise_difficulty`, `get_pronunciation_difficulties`, `get_learning_progress`, `compare_class_difficulties`, and `get_learning_bottlenecks`. Class changes are limited to creating or renaming a class and adding or removing one student at a time.
-
-The connector uses the teacher's existing Supabase account through OAuth 2.1. Grok receives revocable user tokens; it never receives `SUPABASE_SECRET_KEY`. On every MCP request the app asks Supabase who the token belongs to and freshly checks that the account still has `management.access`, so removing the admin/developer role stops the connector even if Grok still has a token.
-
-Configure Supabase first:
-
-1. In **Authentication → Signing Keys**, migrate to an asymmetric signing key such as ES256 or RS256 if the project still uses HS256.
-2. In **Authentication → URL Configuration**, set **Site URL** to the public app origin, for example `https://<owner>-<space>.hf.space`.
-3. In **Authentication → OAuth Server**, enable the OAuth 2.1 server and **Dynamic Client Registration**. Set **Authorization Path** to `/oauth/consent`.
-4. Keep explicit user approval enabled. Dynamic registration lets compatible MCP clients register their exact callback URL, so periodically review OAuth applications and grants in Supabase.
-
-In Hugging Face **Settings → Variables and secrets**, keep `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, and `SUPABASE_SECRET_KEY` configured as described above. `SUPABASE_SECRET_KEY` remains a Space secret. `MCP_PUBLIC_URL` is normally inferred from `SPACE_HOST`; for a custom domain set it to the exact final URL:
-
-```text
-https://<your-domain>/mcp/
-```
-
-Restart the Space, then check these URLs in a browser:
-
-- `https://<host>/.well-known/oauth-protected-resource/mcp/` names the MCP resource and the Supabase authorization server.
-- `https://<project-ref>.supabase.co/.well-known/oauth-authorization-server/auth/v1` is Supabase's OAuth discovery document.
-- `https://<host>/oauth/consent` shows an error without an active `authorization_id`; that is expected because Supabase supplies it during sign-in.
-
-In Grok Business, add a Custom MCP connector whose final Streamable HTTP URL is:
-
-```text
-https://<owner>-<space>.hf.space/mcp/
-```
-
-Only the name and Server URL are needed. Grok should discover Supabase OAuth and display **Sign in**. Sign in with an account that currently has the app's admin or developer role, review the client name, callback and scopes on the Hebrew consent screen, then approve. A student or a user without `management.access` cannot approve or call MCP tools.
-
-Grok must first call `prepare_library_video`; the app returns the normalized title, URL and a single-use approval that expires after ten minutes. Only after the teacher explicitly confirms those details should Grok call `publish_library_video`. Pending approvals disappear safely when the Space restarts.
-
-Class mutations use the same two-step rule. Useful prompts include:
-
-```text
-הצג את הכיתות והתלמידים שאני רשאי/ת לנהל.
-הכן יצירת כיתה בשם "מתחילים נובמבר" עם התלמיד dana@example.com. אל תבצע עדיין.
-הכן הוספת התלמיד noam@example.com לכיתה 12 עם הכינוי נועם. אל תבצע עדיין.
-הכן הסרת התלמיד old@example.com מכיתה 12. אל תבצע עדיין.
-```
-
-Grok calls `prepare_class_change` with one of `create_class`, `rename_class`, `add_student`, or `remove_student`, then displays the normalized class and email details. After the teacher checks them and explicitly confirms, Grok calls `publish_class_change` with the returned approval id. The approval lasts ten minutes, is single-use, is bound to that signed-in manager, and is refused if the class or the manager's subject scope changed meanwhile.
-
-Class listing returns only class id, name, subject, student emails, and optional class-local nicknames. The connector cannot delete a class or account, create a login account, change roles or entitlements, assign teachers, edit lessons/homework/daily videos, or read individual progress, grades, raw attempts, or recordings. Those operations remain in the browser management screen where applicable. Adding an email to a class does not create a Supabase user; that student still signs in normally.
-
-The eight monitoring and analytics tools are read-only and do not use the prepare/publish flow. `get_activity_timeseries` accepts `from_date` and `to_date` as `YYYY-MM-DD`, an `interval` of `day` or `week`, and an optional `class_id`. The inclusive range is limited to 90 non-future days. With a class id it returns only that authorized class; without one it combines only classes currently visible to the signed-in manager. The response contains aggregate attempts, the peak simultaneously active learners reported by the source buckets, and a range summary. It never contains student names, emails, ids, individual scores, answers, recordings, or exact login events.
-
-`get_current_activity` accepts `window_minutes` equal to `5` or `15` (default `5`) and an optional `class_id`. `recent_practice` counts distinct learners and stored attempts in that window but explicitly sets `presence_claim: false`: a recent attempt does not prove that the learner is still connected. `live_presence` is available only during an explicit live-class session and defines active as a heartbeat within 20 seconds of `checked_at`; this process-local state disappears when the session ends or the service restarts. Combined class scopes deduplicate learners enrolled in more than one class.
-
-Attempt-derived counts and timestamps require at least three learners and five attempts. Live counts of one or two are suppressed. The result distinguishes `no_activity` (a successful window query with no events), `no_data` (no observation establishes a last time), `unavailable` (the source does not apply or cannot be read), and `suppressed` (data exists but privacy prevents display). Stored attempts are current as of the database read, not real-time telemetry. Timestamps use UTC ISO 8601 and include an `Asia/Jerusalem` rendering. The app stores no durable general application-activity event, so `last_application_activity` is `unavailable`; lack of practice does not mean the app was unused. No new tracking or retention policy is introduced.
-
-Example current-activity response (shortened):
-
-```json
-{
-  "ok": true,
-  "class_id": 12,
-  "checked_at": "2026-10-27T10:10:00Z",
-  "timezone": "Asia/Jerusalem",
-  "privacy_threshold": {"minimum_students": 3, "minimum_attempts": 5},
-  "recent_practice": {
-    "status": "complete",
-    "source": "persisted_attempts",
-    "window_minutes": 5,
-    "students_with_activity": 4,
-    "attempts": 7,
-    "presence_claim": false,
-    "update_semantics": "current_as_of_database_read"
-  },
-  "live_presence": {
-    "status": "complete",
-    "source": "live_session_heartbeat",
-    "active_users": 3,
-    "heartbeat_ttl_seconds": 20,
-    "ephemeral": true
-  },
-  "last_practice_activity": {
-    "status": "complete",
-    "event_type": "practice_attempt",
-    "timestamp": "2026-10-27T10:09:40Z",
-    "local_timestamp": "2026-10-27T12:09:40+02:00",
-    "timezone": "Asia/Jerusalem",
-    "elapsed_seconds": 20
-  },
-  "last_application_activity": {"status": "unavailable", "reason_code": "not_collected"}
-}
-```
-
-`get_system_health` returns only `healthy`, `degraded`, `unavailable`, or `not_configured` for the application, authentication, database, model, and text-to-speech components. `not_configured` for an optional component such as text-to-speech does not by itself make the service unhealthy. A developer may also see a non-sensitive build version and revision. No caller receives raw logs, stack traces, database queries, internal URLs, paths, environment variables, tokens, credentials, or secret-presence values.
-
-`get_exercise_difficulty` accepts `from_date`, `to_date`, optional `class_id` and `exercise_type`, `limit` from 1 through 20 (default 20), and `min_attempts` (default 10). Exercise types are `pronunciation`, `verb`, `game`, and `other`. It returns stable exercise metadata, attempts, students, successes, success rate, attempts per student, average score, retry metrics, and rank. Existing aliases such as `exercise`, `category`, `attempt_count`, and `student_count` remain available.
-
-`get_pronunciation_difficulties` uses only stored, actually flagged phoneme diagnostics. It returns a phoneme, safe example words, error attempts, affected students, average diagnostic score, and weekly trend. Stored `issues` do not contain every correctly pronounced exposure, so `pronunciation_error_rate` is currently `null` rather than a fabricated denominator. Missing optional diagnostic columns produce `status: "insufficient_data"`.
-
-`get_learning_progress` returns `day`, `week`, or `month` buckets with attempts, students, success and average score, first-observed-attempt success, retry success, and an aggregate score trend. Its optional stable `exercise_id` restricts the report. “First” means first persisted attempt inside the requested range, not lifetime first.
-
-`compare_class_difficulties` applies the same definitions to optional `class_ids` and normalizes by participating students and observed exercise exposure. Overlapping enrollment is disclosed because class populations may not be mutually exclusive.
-
-`get_learning_bottlenecks` returns qualifying exercise/topic aggregates for affected students, repeated-failure rate, attempts until success, improvement rate, and severity. Measured `observed_metrics` remain separate from `suggested_intervention`, which is labeled `recommendation` and lists its measured basis.
-
-Across analytics, success means `score >= 75` and `unrelated = false`. A group requires at least three students and `max(5, min_attempts)` attempts. Sparse groups are suppressed or marked `insufficient_data`; missing metrics are `null`. Dates use ISO 8601 and Asia/Jerusalem calendar boundaries.
-
-An exercise is omitted unless at least three students made at least five attempts in the selected scope and period. Suppressed exercise names and counts are not revealed. “Did not reach success” is not called abandonment because attempt data cannot show whether somebody quit. The report never returns student identities, individual scores or sequences, timestamps, answers, recordings, or pronunciation traces. If the bounded attempt safety cap is reached, the tool refuses partial analysis and asks for a narrower date range or one class.
-
-Example difficulty response (shortened):
-
-```json
-{
-  "ok": true,
-  "status": "complete",
-  "from_date": "2026-10-01",
-  "to_date": "2026-10-26",
-  "privacy_threshold": {"minimum_students": 3, "minimum_attempts": 10},
-  "exercises": [{
-    "exercise_id": "a1b2c3d4e5f6",
-    "exercise_name": "תרגיל לדוגמה",
-    "exercise_type": "pronunciation",
-    "topic": "הגופים",
-    "total_attempts": 18,
-    "unique_students": 6,
-    "successful_attempts": 7,
-    "success_rate": 38.9,
-    "average_attempts_per_student": 3.0,
-    "average_score": 61.4,
-    "difficulty_rank": 1
-  }]
-}
-```
-
-Persisted data has no reliable session boundaries, abandoned or incomplete exercise event, unanswered exposure, or item-level correctness for every non-spoken game. The tools therefore do not report sessions or abandonment and return `insufficient_data` for untracked answers. Trends describe association; they do not prove that practice caused learning.
-
-Useful read-only prompts include:
-
-```text
-הצג גרף פעילות יומי של כיתה 12 בין 2026-10-01 ל-2026-10-26. אל תציג מידע אישי.
-הצג פעילות שבועית בכל הכיתות שאני מורשה/ית לראות ב-30 הימים האחרונים.
-הצג פעילות עדכנית בכיתה 12 בחמש הדקות האחרונות, והפרד בין נוכחות חיה לבין תרגול שנשמר.
-מתי היה ניסיון התרגול האחרון בכל הכיתות שאני מורשה/ית לראות? ציין UTC וגם שעון ישראל ואל תציג מידע אישי.
-בדוק את מצב המערכת והסבר בעברית פשוטה אם רכיב כלשהו אינו זמין.
-הצג את 10 התרגילים הקשים ביותר בכל הכיתות שאני מורשה/ית לראות בין 2026-10-01 ל-2026-10-26. הסבר את המדדים ואל תציג מידע אישי.
-אילו פונמות ערביות גרמו לשגיאות הגייה מדודות בכיתה 12 בחודש האחרון? הצג רק קבוצות שעוברות את סף הפרטיות.
-הצג התקדמות שבועית בכיתה 12, כולל הצלחה בניסיון הראשון לעומת ניסיונות חוזרים.
-השווה בין כיתות 12 ו-15 לפי הצלחה, השתתפות וחשיפה לתרגילים. ציין אם יש תלמידים החופפים בין הכיתות.
-מצא צווארי בקבוק בלמידה בכל הכיתות המורשות. הפרד בבירור בין המדדים שנמדדו לבין המלצות הוראה.
-```
-
-The connector does not make calls to the xAI API, so an xAI developer API key and API credits are not required. Grok Business plan or connector charges, if any, are handled by xAI. To revoke one connector, revoke its grant or OAuth application in Supabase. To revoke the teacher immediately, remove their admin/developer role in the management screen; the next MCP request is refused. Existing videos and ordinary management-screen access are otherwise unaffected. Connector mutations appear in the existing management activity log when its optional `system_events` table is installed; application logs are the fallback and never contain OAuth tokens.
-
-If Grok does not show sign-in, confirm that both discovery URLs return JSON, dynamic registration is enabled, `MCP_PUBLIC_URL` matches Grok's URL including `/mcp/`, and the Space uses HTTPS. A registration 403/404 usually means dynamic registration is disabled. `invalid_grant` usually means the authorization code expired, its PKCE verifier differs, or the registered callback does not match exactly; remove and recreate the connector. A consent-page configuration error means the Site URL, Authorization Path, or Supabase public settings are missing. OAuth configuration failures never fall back to public or shared-secret access.
-
-### Texts
-
-In **תוכן** the teacher also adds texts to a lesson, as many as they like: a story or a dialogue, practised like the course's own conversation "שיחת היכרות". "+ הוספת טקסט" under the lesson asks for a name and the text twice, a line per sentence: in Hebrew, and the same lines, in the same order, in Arabic written in Hebrew letters as the course writes it (`כִּיף חַאלַכּ?`). Each is pasted into its box, or read into it from a plain-text file (`.txt`, UTF-8), and can be corrected there before it is added. Empty lines are not counted, and the two must have the same number of lines; otherwise the text is refused, with both numbers in the message. The kind is chosen there too:
-
-- **סיפור**: every line is played in the voice the student chose in the settings.
-- **שיחה**: the teacher picks a voice for the odd lines and one for the even lines, from the app's voices.
-
-The text becomes a topic of the lesson, laid out as a story: all its lines on the card, said one after the other, with "השמעת השיחה" and "בוחן". It counts like any topic (the lesson's progress, the class's figures, and it can be the homework). Like a video it is added at the lesson's end and moved with the ↑ ↓ arrows on its row, past topics, videos and other texts (`PUT /api/content/order` places both kinds); "תרגול" on the row opens it as the students get it, and "מחיקה" removes it (the recordings made in it stay in `attempts`, uncounted).
-
-The scorer needs each line's phonemes and the answer's voice needs it in Arabic letters, so the server reads the transliteration word by word (`app/texts.py`). A word of the course is found by its transliteration and gets the course's own Arabic spelling and accepted pronunciations (dagesh, shva and final letters are not compared; an unpointed word is found by its letters alone). Any other word is read by rule from its letters and points, which is close but not always right: vowel length and some spellings (ى, ء, ة) cannot be told from the transliteration, and an unpointed word outside the course has no vowels to read. The panel lists those words on the text's row ("מילים שאינן במילון הקורס נקראו לפי הכתיב"), so the teacher knows which lines are worth a listen. A word the course should know is added to `LEX` in `app/workbook.py`.
-
-A line's phrase id is past the bank's (1,000,000 + the text's id × 1000 + the line's number) and its topic is `t<text id>`; an attempt is recorded under that topic and the line's Hebrew (numbered from its second appearance in the text: `כן (2)`). The texts are kept in Supabase like the videos (`GET /api/texts` gives a student those of their classes' lessons; `POST /api/texts` and `DELETE /api/texts/{id}` answer teachers only). Create the table once:
-
-```sql
-create table public.texts (
-  id         bigint generated always as identity primary key,
-  lesson     text not null,                        -- the lesson id, e.g. 2 or 2.1
-  title      text not null,                        -- the topic's name on the path
-  voices     text[] not null default '{}',         -- a dialogue's two voices by name (odd lines, even lines); empty = a story
-  lines      jsonb not null,                       -- [[Hebrew, Arabic in Hebrew letters], ...]
-  pos        int,                                  -- as in videos
-  ord        int  not null default 0,
-  created_at timestamptz not null default now()
-);
-alter table public.texts enable row level security;
-```
-
-### Homework
-
-#### מדריך להגדרת שיעורי בית
-
-1. היכנסו לחשבון המורה ובחרו **ניהול** ואז **כיתות**.
-2. בכיתה קיימת לחצו **עריכה**. בעת יצירת כיתה חדשה מגיעים לאותה הגדרה בשלב **שיעורי הבית**.
-3. בשורת שיעורי הבית בחרו נושא מתוך השיעורים שסומנו לכיתה. אפשר לבחור גם **כתיבת משפטים** או טקסט שהוספתם לשיעור.
-4. בחרו תאריך הגשה, אם יש. אפשר להשאיר את התאריך ריק כדי להציג את המטלה ללא מועד אחרון.
-5. כדי לתת יותר ממטלה אחת לחצו **+ הוספת שיעורי בית**, ובחרו נושא ותאריך לכל שורה. אי אפשר לבחור את אותו נושא פעמיים.
-6. לחצו **שמירה**. התלמידים יראו מעל הנושא במסלול בועה של **שיעורי בית** ואת הזמן שנותר להגשה; השינוי יופיע אצלם בפתיחה הבאה של העמוד.
-
-כדי לשנות מטלה חוזרים ל־**ניהול** → **כיתות** → **עריכה** ומשנים את הנושא או התאריך. להסרת מטלה לוחצים **✕** בשורה שלה ושומרים. התקדמות והשלמה מופיעות בכרטיס הכיתה ובמסך התלמידים; מטלת תרגול מושלמת לאחר שכל משפטי הנושא תורגלו, ומטלת כתיבה לאחר שכל השורות מולאו.
-
-A class may have several homeworks at once, a topic each with its own day: for example the last topic of every lesson it studies (the written homework). In the class's dialog each is a row, the topic (named with its lesson) and its day, with "✕" to drop it; "+ הוספת שיעורי בית" adds the last topic of the first ticked lesson that has none yet. A topic can be homework once. On the path every homework topic has its own bubble; in the panel the class's card has a line per homework (who finished, who is still to), the tile counts the students who finished all of them, and the students' "שיעורי בית" column sums them. They are kept in the class's `homeworks` column, `[{"topic", "due"}]`; `homework` and `due` hold the first, as before. What follows describes one homework.
-
-In the class's dialog the teacher sets its homework: one topic of the class's lessons (for example the conversation "שיחת היכרות"), and optionally the day it is due. The students see it on the path itself: the bubble over the homework topic's circle says "שיעורי בית" and counts the days left ("נשארו 3 ימים", "מגישים מחר!", "מגישים היום!", and "באיחור של יומיים" once the day passed). On the last two days the bubble and the circle's ring turn amber, and red after them. The path's focus does not move: the page still opens on the next topic in the course's order, which keeps its own "התחילו" bubble, so the homework's bubble may be further up or down the path. The homework is done when every sentence of the topic was practised, whenever that was; the circle then gets its ✓ and "שיעורי הבית הושלמו". In the panel the class's card shows how many students finished and names those who did not, the furthest from it first. The students get the homework with `GET /api/me`, so a change reaches them the next time they open the page.
-
-### The daily session
-
-Above the path, "תרגול יומי" opens a session of 10 sentences, so a student with five minutes does not have to choose a topic. Half are sentences they already said with a best score under 75, drawn from their 15 weakest (so the same ones do not return every day); the other half are new, in the course's order, from the homework topic and then the rest of its lesson, or else from the first unfinished lesson. When one kind runs short the other fills in; stories are left out. At the end the page says how many were practised and how many scores went up, and the button shows "✓ תרגלתם היום" for the rest of the day (kept on the device, and only when at least half the sentences were said). The numbers are `DAILY` in `static/index.html`. Driving mode works in a session too.
-
-Under the microphone of a sentence translated from Hebrew to Arabic (the topics named "... עברית ← ערבית"), "תרגול שקט ללא ציון" swaps it for an exercise on the same sentence, for a student who cannot speak where they are: the sentence is built from its words, tapped in order out of a bank that also holds a few words of the topic's other sentences. The other topics (words, conjugations, Arabic → Hebrew, conversations) have no such exercise: their card keeps the microphone and has no button. Nothing is scored or sent to the server: a sentence answered this way is still not practised, on the path, in the homework and in the teacher's panel. It gets a mark of its own, kept on the device ("✓ בלי מיקרופון" in the list of sentences), and leaves the round. The mode lasts until the button is pressed again or the page is reloaded. `SILENT` in `static/index.html` is how many words too many the bank holds.
-
-A sentence translated from Arabic to Hebrew (the topics named "... ערבית ← עברית") can be answered in either language. Its card has two microphones side by side, each with its language's letter on it and a line under it: the filled one (ع, "קוראים בערבית") records the Arabic read aloud and scores its pronunciation, as before; the outlined one (א, "מתרגמים לעברית") listens to the translation instead, with the browser's own speech recognition (`he-IL`), and compares the words it heard with the translation. The card then shows the translation's grade, 0 to 100: the share of the translation's words that were heard, in order ("ציון התרגום: 70"), with what was heard and how many words matched, since a correct translation may be worded differently. 80 or more is "תרגום נכון" and shows the translation. The grade is shown only: it is not kept and does not reach the server, so such a sentence is still not practised and the teacher's panel counts the Arabic recordings alone. In Chrome the audio goes to Google's recognition service (the privacy page says so). A browser without speech recognition (Firefox) has the Arabic microphone alone, as before, and one that turns out not to recognise Hebrew drops the Hebrew one after the first try. The numbers are `HE` in `static/index.html`.
-
-### The story quiz
-
-A story topic (a conversation, all its lines on the card) has a "בוחן" button: the student says the whole conversation in one go. Each line is recorded by itself, once; its score appears beside the line, its Arabic under it, and the next line is recorded, with no answer played and no second try. A line that was not heard waits for the microphone button; one that was skipped comes back after the last line. At the end the card shows the grade (the average of the lines' scores, and how many were said) and the three mistakes made most often across the lines, each with its tip and the words it was heard in (`QUIZ` in `static/index.html`). "סיום הבוחן" ends it early on the lines said so far. The lines are recorded as attempts like any other, so a quiz counts in the student's progress and in the panel. Story driving mode is listening-only and asks how to play the conversation: **Arabic only** plays every Arabic line with a three-second pause between lines; **Hebrew then Arabic** reads each Hebrew sentence followed by its Arabic line. Throughout driving mode, the screen shows the Hebrew meaning and the spoken Arabic in Hebrew transliteration together.
-
-The classes are kept in Supabase and read and written with `SUPABASE_SECRET_KEY` only, so the table has row-level security and no policy. Create it once:
-
-```sql
-create table public.classes (
-  id         bigint generated always as identity primary key,
-  name       text not null unique,                 -- e.g. אוקטובר 2026
-  emails     text[] not null default '{}',         -- the students' Google emails, lower-case
-  nicknames  jsonb  not null default '{}',         -- {email: nickname}, for the students who have one
-  lessons    text[] not null default '{}',         -- the lesson ids the class studies; empty = every lesson
-  subject    text   not null default 'ערבית',      -- existing classes; new ones copy the creating admin
-  teachers   text[] not null default '{}',         -- class-scoped teachers; each address is also in emails
-  homework   text   not null default '',           -- the topic id the class practises now, e.g. l2-talk; '' = none
-  due        date,                                 -- the day the homework is due, if it has one
-  homeworks  jsonb  not null default '[]',         -- every homework of the class: [{"topic": ..., "due": ...}]
-  dailies    jsonb  not null default '[]',         -- the days of its daily videos: [{"video": id, "date": ...}]
-  created_at timestamptz not null default now()
-);
-alter table public.classes enable row level security;
-```
-
-A table made before the nicknames, the lessons, the homework or the daily videos needs the columns (a class saved before then studies every lesson and has no homework). Until they are there, saving a class in the panel is refused with this command in the message:
-
-```sql
-alter table public.classes add column if not exists nicknames jsonb not null default '{}',
-                           add column if not exists lessons text[] not null default '{}',
-                           add column if not exists homework text not null default '',
-                           add column if not exists due date,
-                           add column if not exists homeworks jsonb not null default '[]',
-                           add column if not exists teachers text[] not null default '{}',
-                           add column if not exists dailies jsonb not null default '[]',
-                           add column if not exists subject text not null default 'ערבית';
-update public.classes set subject = 'ערבית' where subject = '';
-```
-
-A subject is one of a fixed list, `SUBJECT_LABELS` in `app/main.py`: ערבית (served at `/`, and `/arabic`) and מתמטיקה (`/math`). It is kept in Hebrew, as the panel shows it, and the developer picks an admin's subject from that list in Monitoring; any other text is refused. `/api/me` names the subject of the account (an admin's own, or their class's), and the page moves an account that opened another subject's address to its own. A developer stays where they are. Each subject has its own title, colour and opening screen (`SUBJECTS`), and the installed app of a subject other than Arabic has its own manifest, `/math/manifest.webmanifest`, so its home-screen icon is named for it and opens `/math`.
-
-**The math path.** On `/math`, the start button opens the math path (`static/math.js`, `static/math.css`) in place of the Arabic one. Its skill graph is `app/math_algebra9.json`, served at `/api/math/skills`: 9th-grade algebra for the 5-unit track, by the Ministry's 2026/27 teaching schedule, in six units (foundations, algebraic technique, function properties, the quadratic function and equation, powers and roots, word problems). Each skill names the skills it needs, and has a sample question whose wrong choices are each a known mistake; a mistake sends the student back to the skill it comes from. `app/math_skills.py` refuses a graph with a cycle, an unknown skill, a redundant link, a question without exactly one right answer, or a mistake that sends a student forward. A skill is open once every skill it needs is done, and the path goes on from the first open one; a locked skill can still be opened, with the skills to do first named on it. For now a right answer to the sample question marks the skill done, and progress is kept on the device (`ihki.math.v1:<email>`). The questions were written for the app and still need a 5-unit teacher's review.
-
-**A photographed problem.** "צילום תרגיל" on the math path lets a student photograph a problem (camera or gallery). The page shrinks the photo to about 1600 px and sends it to `POST /api/math/photo`, where Claude (`app/math_photo.py`) reads it and solves it in a fixed JSON shape: the problem as read, the solution as steps (each a hint and the step itself), the answer, and the path's skill it practises. The sheet shows the reading and one hint; further hints, each step and the full solution with its answer come only when the student asks, and the skill links into the path. It runs on the tutor's Anthropic key (`ANTHROPIC_API_KEY`, or the panel's) and on `MATH_MODEL` (default `claude-opus-5-5`, with the API's default fallback model when it declines). A signed-in student has `DAILY_PHOTOS` (20) a day, counted in memory; a photo it could not read does not count, and developers are exempt. The photo is sent to Anthropic's API and not kept by the app; say so on the privacy page before students use it.
-
-The server keeps the list for a minute, so a change in the SQL editor (rather than the panel) applies within that time.
-
-### Current lesson and the focused home
-
-The first time a student enters an Arabic class, the page asks which lesson the class is on now, offering only that class's lessons. A class must study lessons of exactly one level for this: a class whose lessons span several levels, or that names no lessons (and so studies every one), shows a message asking to correct the class instead. Math classes keep their own path and are not asked. After the choice the student lands on a focused home of at most three actions, the first three that apply of: the nearest-due homework, today's daily video when not yet watched on that device, continuing the current lesson, and a short review of up to five sentences. The full path is one button away and opens at the current lesson. "שינוי" next to the lesson changes it; no progress is lost. Teachers, and the open service without sign-in, keep the path as their first screen.
-
-Each student's choice is kept for each class in the table `learner_class_state`, read and written with `SUPABASE_SECRET_KEY` only. Create it once:
-
-```sql
-create table public.learner_class_state (
-  email          text   not null,                  -- the student's sign-in email, lower-case
-  class_id       bigint not null references public.classes (id) on delete cascade,
-  current_lesson text   not null,                  -- a lesson id of the class, e.g. 5 or 2.3
-  created_at     timestamptz not null default now(),
-  updated_at     timestamptz not null default now(),
-  primary key (email, class_id)                    -- one current lesson per student and class
-);
-alter table public.learner_class_state enable row level security;
-revoke all on public.learner_class_state from anon, authenticated;
-```
-
-`/api/me` gives each of the student's classes its `id`, its `level` (`null` when it is not one level), the `current_lesson` the student chose (`null` before a choice, or when the class no longer has that lesson) and `teacher: true` for a class the account teaches. The page saves a choice with:
-
-```
-PUT /api/me/classes/{class_id}/current-lesson
-{"lesson": "5"}
-```
-
-The server takes the email from the session, never from the body. It answers 401 without sign-in, 403 for a class the caller does not study in (or teaches), 409 for a class that is not one level, 400 for a lesson that is not the class's, and 503 when Supabase cannot save it. Until the table exists, or while Supabase is unreachable, the page keeps the choice on the device under `ihki.lesson.v1:<subject>:<email>:<class id>`, so another account on the same device does not get it, and sends it again on a later sign-in. A choice the server has wins over the device's.
-
-### Live lessons
-
-An admin can choose several class teachers from the class's own student list. The assignment is scoped to that class:
-a person may teach one class and remain a student in another. Developers can edit every class; subject admins can edit
-only classes in their assigned subject.
-
-A class teacher opens **שיעור חי**, chooses their class and starts its single active session. Students see active sessions
-from their registered classes in the same tab. A six-digit code is also shown as a fallback; any signed-in account may
-join with it for that session only, without becoming a member of the class. The teacher chooses an existing sentence or
-searches the class's lesson bank by Hebrew text. No translation or LLM is used.
-
-The page polls every three seconds. The teacher sees the whole roster, who has joined, who is online, and each submitted
-score; a student sees only their own result. Every student gets one scored attempt per question. Empty or undecodable
-recordings may be retried because they never became a scored attempt. Session state, attendance and answers live only in
-the application process: ending a session, restarting the server, or two hours without a teacher heartbeat erases them.
-No live-session audio or result history is stored.
-
-The **ניטור** activity dashboard can switch between the last 5 minutes, 24 hours and 7 days. It also reports Sawtak cache usage: cached WAV count, disk size, cache hits, generated misses, and the hit rate since the current server process started. **הכנת כל ההקלטות** asks for a Sawtak voice id and starts a resumable, sequential background pass over every unique phrase for that voice; existing files are skipped and progress is returned by `GET /api/tts-cache`. Recordings are stored below `TTS_CACHE_DIR/<voice-id>/`. When `TTS_BUCKET` is set (a Hugging Face Storage Bucket id, e.g. `wzender/ihki-storage`, with an `HF_TOKEN` secret that can write to it), the sweep also uploads every WAV through the Bucket API to `TTS_BUCKET_PREFIX/<voice-id>/` (default prefix `ihki-tts`), and at the end uploads every other WAV already on disk; files already in the bucket with the same size are skipped. Writing to a mounted `/data` folder alone was not reaching the bucket, and was slow (the mount flushes a few files every ~30 s), so with `TTS_BUCKET` set new recordings are written to a local staging folder (`TTS_STAGING_DIR`, default `/tmp/ihki-tts-staging`) and uploaded through the API: the sweep in batches of 25 (at least every 30 s), playback misses one by one in the background. Lookups check the staging folder first, then `TTS_CACHE_DIR`. Clearing the cache resets the process counters and leaves the bucket untouched.
-
-The panel reads through `GET /api/class`, which answers teachers only. Row-level security hides other students' rows from the teacher's own token, so the server reads them with `SUPABASE_SECRET_KEY` (Supabase → Project Settings → API Keys → secret key). Unlike the publishable key it must stay private: set it as a Space **secret**. Without it the panel opens and says the data is not available.
-
-The same figures as a query, in the SQL editor (it runs as the owner, so it sees every student):
-
-```sql
-select u.email, a.cat, count(distinct a.phrase) as phrases, count(*) as tries,
-       round(avg(a.score)) as average, max(a.created_at) as last_practice
-from public.attempts a join auth.users u on u.id = a.user_id
-group by u.email, a.cat order by u.email, a.cat;
-```
-
-## Fine-tuning
-
-The base model was not trained on Palestinian Arabic, and it has heard few Hebrew-accented pharyngeals. Expect the zero-shot scores to be noisy until it is fine-tuned on matched data.
-
-**Data to collect** (CSV format in `data/example.csv`):
-- **Native recordings.** The teacher records each phrase 3–5 times, labelled with the main variant's IPA.
-- **Learner recordings, labelled with what was actually said.** Label الحمام said with ח as `… χ a m m aː m`, not `ħ`. These rows teach the model the exact contrasts the tips depend on (ħ/χ, ħ/h, ʕ/ʔ, ʔ/k, r/ʁ, emphatics).
-
-A few hundred utterances are enough to move the needle with the feature encoder frozen.
-
-```bash
-pip install -r requirements-train.txt
-python -m train.finetune --train data/train.csv --eval data/eval.csv --out checkpoints/ihki-ft
-MODEL_ID=checkpoints/ihki-ft uvicorn app.main:app --host 0.0.0.0 --port 7860
-```
-
-The script reports phoneme error rate (PER) before and after training. A GPU is advisable. A free Colab T4 handles a few hundred clips in minutes.
-
-### POWSM on the Space
-
-The most accurate model so far is POWSM-CTC fine-tuned on the Minerva lines with short padding (`train/finetune_powsm.py --pad random`). On the test lines it reaches 16.5% PER, against 38% for the base model, at 0.57 s a recording on 2 CPU threads. See [docs/zero-shot-phone-models.md](docs/zero-shot-phone-models.md). The Space runs it as an ONNX export, with `onnxruntime` and torch only. ESPnet, which training needs, stays on the training machine.
-
-1. **Export it.** Do this once per fine-tune, on the training machine, after running `scripts/setup_zero_shot_deps.sh`:
-   ```bash
-   python scripts/export_powsm_onnx.py checkpoints/powsm-ft-shortpad/powsm_ft.pt exports/powsm-ft-shortpad \
-       --check data/minerva/dev.csv   # each frame's best phone should match ESPnet's 100%
-   ```
-2. **Upload the folder to a Hub model repo.** Use `--private` if the model should not be public: it was trained on the copyrighted Minerva clips.
-   ```bash
-   hf repo create wzender/ihki-powsm-ft --repo-type model --private
-   hf upload wzender/ihki-powsm-ft exports/powsm-ft-shortpad .
-   ```
-3. **Point the Space at it.** In the Space settings, set the variable `MODEL_ID=powsm-onnx:wzender/ihki-powsm-ft`, and `POWSM_ONNX_THREADS=2` to match the free hardware. For a private repo, also add a secret `HF_TOKEN` with read access. The Docker build passes that secret only to the step that downloads the model, which is then baked into the image. Saving the settings rebuilds the Space. `/api/health` and the panel's פרטי המערכת show the model.
-
-Settings:
-- `POWSM_ONNX_PRECISION=int8` loads the int8 copy: 0.38 s a recording, but ط and ص drop by 5–6 points.
-- `POWSM_PAD_SECONDS` overrides the padding (default: what the export was trained for, none here).
-- `POWSM_ONNX_REPO` names the repo the panel's "מודלים" tab offers.
-
-To roll back, delete `MODEL_ID`. The Space rebuilds onto the base model.
-
-## Calibration knobs
-
-- `ScorerConfig.flag_below` (50): the phoneme score under which a consonant gets a tip.
-- `ScorerConfig.unrelated_ratio` (0.65): above this, the response says "different sentence".
-- `GopConfig.*`: the deletion thresholds, and the target posterior at which confidence stops lowering the score.
-
-Tune them on a handful of labelled learner recordings. A useful target is that natives score ≥ 85 and known ħ→χ errors get flagged.
-
-## Playback voice (Sawtak Arabi)
-
-"🔊 השמע" plays the model answer through `GET /api/tts/{phrase_id}`, which calls the [Sawtak Arabi](https://sawtakarabi.ai/docs) TTS API server-side and caches each phrase on disk. The key never reaches the browser.
-
-- Local: `cp .env.example .env` and set `SAWTAK_API_KEY` (`.env` is git-ignored and excluded from the Docker image).
-- Hugging Face: add `SAWTAK_API_KEY` as a Space **secret** (Settings → Variables and secrets). It is injected as an environment variable at runtime.
-- Model-answer playback uses `SAWTAK_VOICE_ID`, or the Palestinian voice רַאאִף when it is unset.
-- Without a key the endpoint answers 503 and the page falls back to the device's Arabic voice.
-- Score calibration keeps its fixed native baseline voices; it does not use `SAWTAK_VOICE_ID`. A baseline is prepared once for every phrase that gets scored, also when the learner never presses "השמע". The first score of a phrase waits up to 8 s for it. Without a key the scores are not calibrated; `/api/health` reports this as `references`.
-
-## Cost estimate (API keys)
-
-Estimated 2026-10-18 for **100 students, each doing 5 tutor chats a day (the daily limit, `DAILY_LIMIT`) of 10 turns each**: 500 chats a day, 15,000 a month (30 days). Anthropic prices are list prices per million tokens; the Sawtak price is the rate your own account was charged.
-
-### Anthropic (`ANTHROPIC_API_KEY`) — the tutor game יאללה נדבר
-
-How a chat is billed: 11 calls (the opening plus 10 turns). Each call sends the scenario's system prompt and the reply schema (the prefix), plus the conversation so far. The prefix grows with the lessons' vocabulary: 4,364 tokens in lesson 1, 16,466 mid-course and 22,728 in the last lesson (measured with `count_tokens`; the 5.5 models count the same). Each turn adds about 540 tokens of history, and each answer is about 490 output tokens. `cache_control` caches the prompt, so every call after the first reads the earlier part from the cache and writes only the new turn. That assumes the turns are less than 5 minutes apart, which a spoken conversation is.
-
-Tokens per chat (mid-course): ~22K cache writes (1.25× the input price), ~189K cache reads, ~5.7K output.
-
-| Model (`TUTOR_MODEL`) | $ in / out / cache read per 1M | Per chat (mid-course) | Per day | **Per month**: lesson 1 / mid / last | Per student per month (mid) |
-|---|---|---|---|---|---|
-| `claude-haiku-5-5` (the default) | 0.10 / 0.50 / 0.01 | $0.0075 | $3.73 | **$71 / $112 / $133** | $1.12 |
-| `claude-haiku-4-5` | 1 / 5 / 0.10 | $0.075 | $37 | $712 / $1,120 / $1,332 | $11.20 |
-| `claude-sonnet-5-5` | 2 / 10 / 0.20 | $0.149 | $75 | $1,424 / $2,241 / $2,663 | $22.40 |
-| `claude-opus-5-5` ¹ | 4 / 20 / 0.20 | $0.261 | $130 | $2,644 / $3,914 / $4,572 | $39.10 |
-| `claude-fable-5-1` ¹ | 10 / 50 / 0.25 | $0.605 | $303 | $6,354 / $9,077 / $10,486 | $90.80 |
-
-- **Without the prompt cache** the input would cost 3–3.5× more (for example Haiku 5.5 mid-course: $359 a month instead of $112). Keep `cache_control` in `Tutor._ask`.
-- These are upper bounds for the volume: every student uses all 5 chats, every day, all 10 turns. Real use is usually lower; `tutor_chats` records each chat's `input_tokens` and `output_tokens`, so the real bill can be checked against this table.
-- ¹ Opus 5.5 and Fable 5.1 cannot turn thinking off, so the tutor leaves it adaptive at `effort: "low"` (`thinking_for()` in `app/tutor.py`). The thinking tokens they spend are billed as output and are not in this table, so expect somewhat more for these two.
-- Set a monthly spending limit in the Console (Settings → Limits), so that a bug or unexpected use cannot cost more than planned.
-
-### Sawtak Arabi (`SAWTAK_API_KEY`) — the model-answer voice
-
-Sawtak charges per character of text spoken. This account was charged **$5.00 for 99,600 characters (about $0.05 per 1,000 characters, $50 per million)** in the 30 days before 2026-10-18 (`GET /v1/usage`).
-
-- **If the tutor's messages are spoken with Sawtak too** (the code does not do this yet), each one costs again: every message is new text, so none comes from the cache. A message is one or two short sentences, about 90 characters with vowel marks (the phrase bank averages 51 per phrase). A chat has 11 messages (the opening and 10 answers), so about 1,000 characters:
-
-  | | Characters | Cost |
-  |---|---|---|
-  | Per chat | ~990 | ~$0.05 |
-  | Per day (500 chats) | ~495,000 | ~$25 |
-  | **Per month (15,000 chats)** | ~14.9 million | **~$745** (between ~$500 and ~$1,000 for messages of 60–120 characters) |
-  | Per student per month | ~149,000 | ~$7.45 |
-
-  That is more than the tutor's model costs on Haiku 5.5 (~$112 a month), so voicing the tutor would be most of the bill.
-- The rest of the cost comes from "🔊 השמע" and from the native baseline the scores are calibrated against, both for the phrase bank:
-- Each phrase is generated once and kept in the voice cache (`TTS_CACHE_DIR`). All 3,546 phrases come to about 180,000 characters with their vowel marks, so **voicing the whole bank costs about $9, once**. A text's dialogue lines in the second voice add a little.
-- **The number of students does not change this cost**: 100 students cost the same as 1, because the second student to play a phrase gets it from the cache.
-- What does cost more: the cache is a folder on the server's disk. A Hugging Face Space without persistent storage loses it on every restart and rebuild, and "מחיקת מטמון ההקלטות" in the panel empties it. After either, the phrases are generated again as they are played, up to about $9 each time. To avoid that, give the Space persistent storage and set `TTS_CACHE_DIR=/data/ihki-tts`.

app/access.py

@@ -1,72 +1,36 @@
-"""Shared user-session and permission resolution for browser and MCP callers."""
+"""Mathly session roles and permissions."""
 from __future__ import annotations
 
-from .auth import AuthUnavailable, SupabaseAuth
+from .auth import SupabaseAuth
 
-
-ROLES = frozenset({"student", "teacher", "flagger", "admin", "developer"})
-DEFAULT_ROLES = ("student", "flagger")
-ENTITLEMENTS = frozenset({"practice", "games", "tutor", "path", "library"})
-DEFAULT_ENTITLEMENTS = ENTITLEMENTS - {"tutor"}
+ROLES = frozenset({"student", "teacher", "admin", "developer"})
+DEFAULT_ROLES = ("student",)
 ROLE_PERMISSIONS = {
-    "student": frozenset(),
-    "teacher": frozenset({"exercises.use_all", "students.view", "games.use", "path.use", "exercises.use", "library.view"}),
-    "flagger": frozenset({"flags.create"}),
-    "admin": frozenset({"exercises.use_all", "students.view", "management.access", "users.manage",
-                        "classes.manage", "content.manage", "flags.review", "games.use", "path.use",
-                        "exercises.use", "library.view"}),
+    "student": frozenset({"path.use"}),
+    "teacher": frozenset({"path.use", "students.view"}),
+    "admin": frozenset({"path.use", "students.view", "management.access", "classes.manage"}),
     "developer": frozenset({"*"}),
 }
-ENTITLEMENT_PERMISSIONS = {"practice": {"practice.use", "exercises.use"}, "games": {"games.use"},
-                           "tutor": {"tutor.use"}, "path": {"path.use"}, "library": {"library.view"}}
-
 
-def resolve_access(a: SupabaseAuth, token: str, *, fresh_permissions: bool = False) -> dict | None:
-    """Return the current application identity for a verified Supabase access token.
 
-    ``fresh_permissions`` bypasses the short user-access cache. MCP uses it on every
-    request so revoking management access takes effect immediately.
-    """
-    user = a.user(token)
+def resolve_access(store: SupabaseAuth, token: str, *, fresh_permissions: bool = False) -> dict | None:
+    user = store.user(token)
     if user is None:
         return None
     email = user["email"].lower()
-    classes = a.classes()
-    mine = [c for c in classes if email in c["emails"]]
-    teaches = [c for c in classes if email in (c.get("teachers") or [])]
-    member = bool(mine or teaches or not classes)
-    roles, entitlements, assigned = {"student"}, set(DEFAULT_ENTITLEMENTS) if member else set(), None
-    if hasattr(a, "access_for"):
-        try:
-            assigned = a.access_for(user["id"], fresh=fresh_permissions)
-        except TypeError:  # compatible with small test/deployment adapters predating ``fresh``
-            assigned = a.access_for(user["id"])
-        if assigned:
-            roles = set(assigned.get("roles") or ["student"]) & ROLES
-            entitlements = set(assigned.get("entitlements") or []) & ENTITLEMENTS
-    if email in getattr(a, "teachers", ()):
-        roles.update({"teacher", "admin", "flagger"})
-    if email in getattr(a, "tutors", ()):
-        roles.add("flagger")
-    if email in getattr(a, "developers", ()):
+    classes = store.classes()
+    mine = [row for row in classes if email in row.get("emails", ()) or email in row.get("teachers", ())]
+    assigned = store.access_for(user["id"], fresh=fresh_permissions)
+    roles = set((assigned or {}).get("roles") or DEFAULT_ROLES) & ROLES
+    if email in store.teachers:
+        roles.update({"teacher", "admin"})
+    if email in store.developers:
         roles.add("developer")
-    privileged = roles - {"student"}
-    if classes and not mine and not privileged and not entitlements:
+    if classes and not mine and roles == {"student"}:
         return {**user, "denied": True, "permissions": []}
-    if not assigned:
-        roles.update(DEFAULT_ROLES)
-    if "flagger" not in roles:
-        try:
-            if email in (a.ranked() or ()):
-                roles.add("flagger")
-        except AuthUnavailable:
-            pass
-    permissions = set().union(*(ROLE_PERMISSIONS[r] for r in roles))
-    permissions.update(*[ENTITLEMENT_PERMISSIONS[e] for e in entitlements])
-    return {**user, "token": token, "roles": sorted(roles), "entitlements": sorted(entitlements),
-            "subject": str((assigned or {}).get("subject") or ""), "permissions": sorted(permissions),
-            "teacher": bool(roles & {"teacher", "admin", "developer"}),
-            "tutor": "flags.create" in permissions or "*" in permissions, "classes": mine, "teaches": teaches}
+    permissions = set().union(*(ROLE_PERMISSIONS[role] for role in roles))
+    return {**user, "token": token, "roles": sorted(roles), "permissions": sorted(permissions),
+            "teacher": bool(roles & {"teacher", "admin", "developer"}), "classes": mine}
 
 
 def has_permission(user: dict | None, permission: str) -> bool:

app/align.py

@@ -1,316 +0,0 @@
-"""CTC forced alignment and goodness-of-pronunciation (GOP), in plain numpy.
-
-Inputs are frame-level log-posteriors `logp` of shape (T, V) from a CTC phoneme model.
-Nothing here depends on torch, so it is unit-testable with synthetic emissions.
-"""
-from __future__ import annotations
-
-import logging
-import os
-from dataclasses import dataclass, field
-
-import numpy as np
-
-log = logging.getLogger("ihki.align")
-
-NEG = -1e30
-POOLS = ("max", "mean", "topk", "lse", "energy", "gated")
-DEFAULT_POOL = "gated"
-
-
-def env_pool() -> str:
-    """The ratio pool GOP_RATIO_POOL names (read when a GopConfig is made, so after main.py loads .env).
-    Empty or unset: DEFAULT_POOL. An unknown name is logged and DEFAULT_POOL is used."""
-    pool = os.environ.get("GOP_RATIO_POOL", "").strip().lower() or DEFAULT_POOL
-    if pool not in POOLS:
-        log.warning("GOP_RATIO_POOL=%r is not one of %s: using %s", pool, ", ".join(POOLS), DEFAULT_POOL)
-        return DEFAULT_POOL
-    return pool
-
-
-NARROW_PAD = 1
-
-
-def env_vowel_window() -> int | None:
-    """GOP_VOWEL_WINDOW: empty, unset or "wide" (None: a vowel reads the consonants' wide window), "narrow" (its
-    aligned span +- NARROW_PAD frames), or that pad as a frame count. Anything else is logged and "wide" used.
-    Wide is the default: with a pooled ratio it absorbs a transition spike without the narrow window's blind spot
-    (docs/gop-pooling.md, scripts/gop_window_bench.py)."""
-    raw = os.environ.get("GOP_VOWEL_WINDOW", "").strip().lower()
-    if raw in ("", "wide"):
-        return None
-    if raw == "narrow":
-        return NARROW_PAD
-    if raw.isdigit():
-        return int(raw)
-    log.warning("GOP_VOWEL_WINDOW=%r is not wide, narrow or a frame count: using wide", raw)
-    return None
-
-
-@dataclass
-class Alignment:
-    total_logp: float           # log-prob of the best CTC path
-    spans: list[tuple[int, int]]  # [start, end) frames where each target token is emitted
-
-
-def ctc_viterbi(logp: np.ndarray, tokens: list[int], blank: int) -> Alignment | None:
-    """Best CTC path that emits exactly `tokens`. Returns None if the audio is too short."""
-    T, _ = logp.shape
-    N = len(tokens)
-    if N == 0 or T < N:
-        return None
-    S = 2 * N + 1
-    ext = np.array([blank if s % 2 == 0 else tokens[s // 2] for s in range(S)])
-    # skip transition s-2 -> s allowed for non-blank states whose label differs from s-2
-    can_skip = np.zeros(S, dtype=bool)
-    can_skip[2:] = (ext[2:] != blank) & (ext[2:] != ext[:-2])
-
-    dp = np.full((T, S), NEG)
-    bp = np.zeros((T, S), dtype=np.int8)  # 0 = stay, 1 = from s-1, 2 = from s-2
-    dp[0, 0] = logp[0, blank]
-    dp[0, 1] = logp[0, ext[1]]
-    for t in range(1, T):
-        prev = dp[t - 1]
-        stay = prev
-        one = np.concatenate(([NEG], prev[:-1]))
-        two = np.where(can_skip, np.concatenate(([NEG, NEG], prev[:-2])), NEG)
-        stacked = np.stack([stay, one, two])
-        choice = stacked.argmax(0)
-        dp[t] = stacked[choice, np.arange(S)] + logp[t, ext]
-        bp[t] = choice
-
-    # path must end in the last token or the trailing blank
-    end = S - 1 if dp[T - 1, S - 1] >= dp[T - 1, S - 2] else S - 2
-    total = float(dp[T - 1, end])
-    if total <= NEG / 2:
-        return None
-
-    states = np.empty(T, dtype=np.int64)
-    s = end
-    for t in range(T - 1, -1, -1):
-        states[t] = s
-        s -= int(bp[t, s])
-
-    spans: list[list[int]] = [[-1, -1] for _ in range(N)]
-    for t, st in enumerate(states):
-        if st % 2 == 1:
-            i = st // 2
-            if spans[i][0] < 0:
-                spans[i][0] = t
-            spans[i][1] = t + 1
-    return Alignment(total, [tuple(x) for x in spans])
-
-
-@dataclass
-class TokenScore:
-    score: float      # 0..100
-    gop: float        # log ratio target vs strongest competitor, <= 0
-    peak: float       # max log-posterior of the target inside its window
-    competitor: int | None  # strongest non-target, non-blank token in the window (None: nothing, or a sound we do not name)
-    deleted: bool     # target barely present and nothing else either
-    realised: int | None = None  # a class target (several correct realisations): the one said
-    other: bool = False          # the strongest competitor is a sound outside the named set
-    comp_peak: float = NEG       # max log-posterior of the strongest competitor (named or not) in the window
-    comp_frames: int = 0         # frames where that competitor clears deleted_comp (duration evidence)
-    window: tuple[int, int] = (0, 0)  # [start, end) frames the target and its competitors were read from
-
-
-@dataclass
-class GopConfig:
-    deleted_peak: float = float(np.log(0.05))    # target this weak ...
-    deleted_comp: float = float(np.log(0.20))    # ... and no strong competitor -> deletion
-    confident_peak: float = 0.30                 # target posterior at which the peak no longer lowers the score
-    # Softens the target/competitor ratio: at 0.5 a competitor twice as likely still scores 71, not 50.
-    # The zero-shot model is noisy on accented speech, so a linear ratio punishes its own uncertainty.
-    leniency: float = 0.5
-    # How the target/competitor ratio pools the window's frames (docs/gop-pooling.md). The peak behind
-    # `confidence` and `deleted` stays the max, so a peaky CTC emission is never diluted by its blanks.
-    ratio_pool: str = field(default_factory=env_pool)  # max | mean | topk | lse | energy | gated (GOP_RATIO_POOL)
-    pool_k: int = 2              # topk: frames averaged per column
-    pool_tau: float = 0.5        # lse: temperature (0 -> max, 1 -> mean)
-    energy_gamma: float = 1.0    # energy: frame weight = (RMS / loudest in the window) ** gamma
-    energy_gate: float = 0.3     # gated: frames quieter than this fraction of the window's loudest are dropped
-    energy_spread: int = 1       # frames the energy is max-filtered over (CTC peaks lead/lag the acoustics)
-    pool_vowels_only: bool = True  # consonants keep the max (bursts and voiceless sounds are short and quiet)
-    # Consonants need some surrounding blank for a CTC peak that leads/lags the forced span, but must not inherit an
-    # arbitrarily long pause up to the next token (e.g. a 760 ms window across a sentence break).
-    consonant_window: int | None = 4
-    # A vowel's competitors are read from its aligned span +- this many frames (None: the wide window consonants
-    # use). Its presence (`peak`, `deleted`) is still read from the wide window. GOP_VOWEL_WINDOW sets it.
-    vowel_window: int | None = field(default_factory=env_vowel_window)
-
-
-def pool_frames(seg: np.ndarray, how: str = "max", k: int = 2, tau: float = 0.5,
-                weight: np.ndarray | None = None) -> np.ndarray:
-    """Pool a window's (n, V) log-posteriors over time into one log-score per column.
-
-    max: the single best frame. topk: log of the mean of each column's k best frames. lse: the power mean
-    tau * log(mean(p ** (1/tau))), between the max (tau -> 0) and the mean (tau = 1). mean / energy / gated:
-    log of the weighted mean posterior, `weight` (uniform when None) normalised over the window.
-    """
-    n = len(seg)
-    if how == "max" or n == 1:
-        return seg.max(0)
-    if how == "topk":
-        k = max(1, min(k, n))
-        return np.logaddexp.reduce(np.partition(seg, n - k, axis=0)[n - k:], axis=0) - np.log(k)
-    if how == "lse":
-        return tau * (np.logaddexp.reduce(seg / tau, axis=0) - np.log(n))
-    w = np.ones(n) if weight is None else np.asarray(weight, dtype=np.float64)
-    w = w / w.sum() if w.sum() > 0 else np.full(n, 1.0 / n)
-    return np.logaddexp.reduce(seg + np.log(np.maximum(w, 1e-300))[:, None], axis=0)
-
-
-def energy_weights(energy: np.ndarray, how: str, gamma: float = 1.0, gate: float = 0.3) -> np.ndarray:
-    """Frame weights of one window from its (already smoothed) RMS: soft (`energy`) or a 0/1 voice gate (`gated`)."""
-    e = energy / max(float(energy.max()), 1e-12)
-    return (e >= gate).astype(np.float64) if how == "gated" else e ** gamma
-
-
-def spread_energy(energy: np.ndarray, spread: int) -> np.ndarray:
-    """Max-filter over +-spread frames: a CTC emission a frame off the loud nucleus still gets its weight."""
-    out = energy.astype(np.float64).copy()
-    for s in range(1, spread + 1):
-        out[s:] = np.maximum(out[s:], energy[:-s])
-        out[:-s] = np.maximum(out[:-s], energy[s:])
-    return out
-
-
-def token_window(spans: list[tuple[int, int]], i: int, T: int, pad: int | None = None) -> tuple[int, int]:
-    """[start, end) frames token i is read from. Wide (pad None): from the end of token i-1 to the start of token i+1,
-    the blanks around the emission where a substituted consonant peaks. Narrow: its own span +- `pad` frames, inside
-    the wide window (a vowel is its syllable's loud nucleus, not a sound hiding in the blanks)."""
-    a = spans[i - 1][1] if i > 0 else 0
-    b = spans[i + 1][0] if i + 1 < len(spans) else T
-    a, b = min(a, spans[i][0]), max(b, spans[i][1])
-    if pad is None:
-        return a, b
-    return max(a, spans[i][0] - pad), min(b, spans[i][1] + pad)
-
-
-def compute_token_gop(logp: np.ndarray, spans: list[tuple[int, int]], i: int, tokens: list[int], blank: int,
-                      cfg: GopConfig, vowel: bool = False, accept: list[set[int] | None] | None = None,
-                      n_real: int | None = None, named: set[int] | None = None, energy: np.ndarray | None = None,
-                      edge: tuple[set[int], set[int]] | None = None, pooled: bool | None = None) -> TokenScore:
-    """GOP of token i (see score_tokens), its window and pooling chosen by its class.
-
-    Presence is read from the wide window for every token: `peak` (behind the confidence) and `deleted` (target under
-    deleted_peak and no competitor over deleted_comp), so a vowel aligned to a single frame is still found deleted.
-    The competitor ratio of a vowel is read from its narrow window (cfg.vowel_window) and pooled with cfg.ratio_pool;
-    a consonant is capped at its span +- cfg.consonant_window and keeps the max unless cfg.pool_vowels_only is off.
-    `pooled` overrides the latter.
-    `edge`: ids that are no competitor on the frames between the token's span and its left / right neighbour (a vowel
-    gliding into j or w passes through i or u: coarticulation, not a substitution). `energy` is already spread.
-    """
-    T = logp.shape[0]
-    accept = accept or [None] * len(tokens)
-    a, b = token_window(spans, i, T, cfg.consonant_window) if not vowel else token_window(spans, i, T)
-    ra, rb = token_window(spans, i, T, cfg.vowel_window) if vowel and cfg.vowel_window is not None else (a, b)
-    tok, (s0, s1) = tokens[i], spans[i]
-    seg = logp[a:b]
-    peak = float(seg[:, tok].max())
-    members = accept[i] or set()
-    realised = max(members, key=lambda m: seg[:, m].max()) if members else None
-
-    cols = (seg[:, :n_real] if n_real else seg).copy()
-    if edge:
-        for ids, lo, hi in ((edge[0], a, s0), (edge[1], s1, b)):
-            ids = [x for x in ids if x < cols.shape[1]]
-            if ids and hi > lo:
-                cols[lo - a:hi - a, ids] = NEG
-    mask = np.zeros(cols.shape[1], dtype=bool)
-    mask[blank] = True
-    for j in (i - 1, i, i + 1):
-        if 0 <= j < len(tokens):
-            for x in {tokens[j], *(accept[j] or ())}:
-                if x < len(mask):
-                    mask[x] = True
-    deleted = bool(peak < cfg.deleted_peak and float(np.where(mask, NEG, cols.max(0)).max()) < cfg.deleted_comp)
-
-    how = cfg.ratio_pool if (pooled if pooled is not None else vowel or not cfg.pool_vowels_only) else "max"
-    weight = None
-    if how in ("energy", "gated"):
-        if energy is not None:
-            weight = energy_weights(energy[ra:rb], how, cfg.energy_gamma, cfg.energy_gate)
-            weight[max(0, s0 - ra):max(0, s1 - ra)] = 1.0   # the frames the token was emitted on count in full
-        how = "mean"
-    rcols = cols[ra - a:rb - a]
-    maxed = rcols.max(0)
-    ratio = maxed.copy() if how == "max" else pool_frames(rcols, how, cfg.pool_k, cfg.pool_tau, weight)
-    ratio[mask] = NEG
-    comp = int(ratio.argmax())
-    comp_peak = float(maxed[comp]) if ratio[comp] > NEG / 2 else NEG
-    # A lone CTC spike can be a breath or microphone onset rather than a produced consonant. Keep duration
-    # evidence separately from the peak so pronunciation policy can distinguish transients from substitutions.
-    comp_frames = int(np.count_nonzero(rcols[:, comp] >= cfg.deleted_comp)) if ratio[comp] > NEG / 2 else 0
-    tseg = logp[ra:rb, [tok]]
-    target = float(tseg.max()) if how == "max" else float(pool_frames(tseg, how, cfg.pool_k, cfg.pool_tau, weight)[0])
-
-    gop = target - max(target, float(ratio[comp]))
-    confidence = min(1.0, float(np.exp(peak)) / cfg.confident_peak)
-    score = 100.0 * float(np.exp(gop * cfg.leniency)) * float(np.sqrt(confidence))
-    present = comp_peak > NEG / 2
-    other = bool(present and named is not None and comp not in named)
-    return TokenScore(round(score, 1), round(gop, 3), round(peak, 3), comp if present and not other else None,
-                      deleted, realised, other, round(comp_peak, 3), comp_frames, (int(ra), int(rb)))
-
-
-def score_tokens(logp: np.ndarray, align: Alignment, tokens: list[int], blank: int,
-                 cfg: GopConfig | None = None, accept: list[set[int] | None] | None = None,
-                 n_real: int | None = None, named: set[int] | None = None,
-                 energy: np.ndarray | None = None, pooled: list[bool] | None = None,
-                 vowels: list[bool] | None = None,
-                 edges: list[tuple[set[int], set[int]] | None] | None = None) -> list[TokenScore]:
-    """Per-token GOP (compute_token_gop for each token).
-
-    The neighbours' own labels are excluded from the competitor set (coarticulation is not an error).
-    A class token (a virtual column pooling its correct realisations, `accept[i]` their ids) is scored on the
-    pooled column; its members are not competitors. Competitors come from the first `n_real` columns only, and
-    one outside `named` is reported as `other` rather than by name.
-
-    `vowels` marks the tokens that are vowels (narrow window, pooled ratio). Without it every token is read from the
-    wide window and pooled, unless `pooled` marks which are. `energy` is the per-frame RMS the energy pools need;
-    without it they fall back to the plain mean. `edges[i]`: see compute_token_gop.
-    """
-    cfg = cfg or GopConfig()
-    if energy is not None:
-        energy = spread_energy(np.asarray(energy)[:logp.shape[0]], cfg.energy_spread)
-    return [compute_token_gop(logp, align.spans, i, tokens, blank, cfg, bool(vowels and vowels[i]), accept, n_real,
-                              named, energy, edges[i] if edges else None,
-                              (pooled[i] if pooled is not None else None if vowels is not None else True))
-            for i in range(len(tokens))]
-
-
-def greedy_decode(logp: np.ndarray, blank: int) -> list[int]:
-    ids = logp.argmax(1)
-    out, prev = [], None
-    for x in ids:
-        x = int(x)
-        if x != prev and x != blank:
-            out.append(x)
-        prev = x
-    return out
-
-
-def edit_distance(a: list, b: list, same=None) -> int:
-    same = same or (lambda x, y: x == y)
-    d = list(range(len(b) + 1))
-    for i, x in enumerate(a, 1):
-        prev, d[0] = d[0], i
-        for j, y in enumerate(b, 1):
-            prev, d[j] = d[j], min(d[j] + 1, d[j - 1] + 1, prev + (not same(x, y)))
-    return d[len(b)]
-
-
-def weighted_edit_distance(a: list, b: list, sub, dele, ins) -> float:
-    """Edit distance of `a` (heard) from `b` (target) with a cost per edit: sub(x, j) for x heard in place of b[j],
-    dele(j) for b[j] not heard, ins(x, j) for x heard after b[:j] (j == 0 or len(b): at an edge)."""
-    n = len(b)
-    d = [0.0] * (n + 1)
-    for j in range(1, n + 1):
-        d[j] = d[j - 1] + dele(j - 1)
-    for x in a:
-        prev, d[0] = d[0], d[0] + ins(x, 0)
-        for j in range(1, n + 1):
-            prev, d[j] = d[j], min(d[j] + ins(x, j), d[j - 1] + dele(j - 1), prev + sub(x, j - 1))
-    return d[n]

app/arabic_diacritics.py

@@ -1,134 +0,0 @@
-"""Add Arabic vowel marks to an answer from the pronunciation stored beside it.
-
-The phrase bank deliberately keeps a plain Arabic spelling and an exact IPA reading.
-This module combines them for the learner-facing answer without changing the spelling
-used by the scorer or by text-to-speech.
-"""
-from __future__ import annotations
-
-import re
-from functools import lru_cache
-
-from .archi import _LETTERS, _align, _letters, _units
-from .phones import base
-
-FATHA, DAMMA, KASRA, SUKUN, SHADDA = "\u064e", "\u064f", "\u0650", "\u0652", "\u0651"
-_MARKS = re.compile(r"[\u0610-\u061a\u064b-\u065f\u0670\u06d6-\u06ed]")
-_VOWELS = {"a", "i", "u", "e", "o", "ə"}
-_VOWEL_MARK = {"a": FATHA, "i": KASRA, "e": KASRA, "ə": KASRA, "u": DAMMA, "o": DAMMA}
-
-
-def _vowel(ph: str) -> str | None:
-    sound = base(ph)
-    return sound if sound in _VOWELS else None
-
-
-def _point_word(word: str, ipa_word: str) -> str:
-    plain = _MARKS.sub("", word)
-    chars = list(plain)
-    letters = _letters(plain)
-    phs = ipa_word.split()
-    units = _units(phs)
-    if not letters or not units:
-        return plain
-
-    matched, _cost = _align(letters, [sound for sound, _positions in units])
-    unit_for_letter: dict[int, int] = {}
-    for letter_i, hits in matched.items():
-        real = [hit for hit in hits if hit >= 0]
-        if len(hits) == 1 and len(real) == 1:
-            unit_for_letter[letter_i] = real[0]
-
-    if not unit_for_letter:
-        return plain
-
-    marks: dict[int, list[str]] = {}
-    ordered = sorted(unit_for_letter.items(), key=lambda item: item[1])
-    for order_i, (letter_i, unit_i) in enumerate(ordered):
-        positions = units[unit_i][1]
-        if len(positions) > 1:
-            marks.setdefault(letter_i, []).append(SHADDA)
-
-        end = positions[-1] + 1
-        next_start = units[unit_i + 1][1][0] if unit_i + 1 < len(units) else len(phs)
-        following = next((_vowel(phs[i]) for i in range(end, next_start) if _vowel(phs[i])), None)
-        if following:
-            target = letter_i
-            next_letter_i = ordered[order_i + 1][0] if order_i + 1 < len(ordered) else len(letters)
-            between = range(letter_i + 1, next_letter_i)
-            # A final ta marbuta / h carries its spoken ending (qahwe, madrase).
-            ending = next((i for i in between if letters[i] in "ةه" and i == len(letters) - 1), None)
-            if ending is not None:
-                target = ending
-            marks.setdefault(target, []).append(_VOWEL_MARK[following])
-        else:
-            marks.setdefault(letter_i, []).append(SUKUN)
-
-    # A word-initial vowel belongs on its alif/hamza, before the first aligned consonant.
-    first_unit = ordered[0][1] if ordered else 0
-    first_phone = units[first_unit][1][0]
-    initial = next((_vowel(ph) for ph in phs[:first_phone] if _vowel(ph)), None)
-    if initial:
-        first_letter = ordered[0][0]
-        carrier = next((i for i in range(first_letter + 1) if letters[i] in "اٱأإآء"), first_letter)
-        marks.setdefault(carrier, []).append(_VOWEL_MARK[initial])
-
-    # In a sun-letter article the lam is silent but is still explicitly vowelless.
-    if plain.startswith("ال") and 1 not in unit_for_letter:
-        marks.setdefault(1, []).append(SUKUN)
-
-    output = []
-    letter_i = 0
-    for char in chars:
-        output.append(char)
-        if char in _LETTERS:
-            own = marks.get(letter_i, [])
-            output.extend(mark for mark in (SHADDA if SHADDA in own else "", next((m for m in own if m != SHADDA), "")) if mark)
-            letter_i += 1
-    return "".join(output)
-
-
-@lru_cache(maxsize=16384)
-def point_arabic(arabic: str, ipa: str) -> str:
-    """Return the original Arabic spelling with marks for its IPA pronunciation."""
-    ipa_words = [part.strip() for part in ipa.split("|")]
-    word_i = 0
-
-    def point(match: re.Match[str]) -> str:
-        nonlocal word_i
-        word = match.group(0)
-        if word_i >= len(ipa_words):
-            return word
-        result = _point_word(word, ipa_words[word_i])
-        word_i += 1
-        return result
-
-    return re.sub(r"[^\s]+", point, arabic) if len(arabic.split()) == len(ipa_words) else arabic
-
-
-# Spellings for the voice only, never shown: Sawtak reads the pointed هُوِّ / هِيِّ as "hu" / "hi". It reads these as
-# huwwe / hiyye: هوّة like the -e of قهوة, هِيِّي with the -e as a written yā'. Checked with the phoneme model
-# (the pronoun alone: 58 -> 95 and 65 -> 95).
-_TTS_RESPELL = {("هو", "h u w w e"): "هوّة", ("هي", "h i j j e"): "هِيِّي"}
-
-
-def tts_arabic(arabic: str, ipa: str) -> str:
-    """The text sent to the Arabic voice: point_arabic, with the words it misreads respelled."""
-    ipa_words = [part.strip() for part in ipa.split("|")]
-    if len(arabic.split()) != len(ipa_words):
-        return point_arabic(arabic, ipa)
-    words = iter(ipa_words)
-
-    def say(match: re.Match[str]) -> str:
-        word, ipa_word = match.group(0), next(words)
-        bare = _MARKS.sub("", word)
-        tail = re.search(r"[؟?!.,،]*$", bare).group(0)   # punctuation stuck to the word stays after it
-        core = bare[:len(bare) - len(tail)] if tail else bare
-        if core.startswith("و") and ipa_word.startswith("u "):   # وهيّ "and she": the و, then the pronoun
-            respelled = _TTS_RESPELL.get((core[1:], ipa_word[2:]))
-            if respelled:
-                return "وُ" + respelled + tail
-        respelled = _TTS_RESPELL.get((core, ipa_word))
-        return respelled + tail if respelled else _point_word(word, ipa_word)
-
-    return re.sub(r"[^\s]+", say, arabic)

app/archi.py

@@ -1,182 +0,0 @@
-"""Abstract symbols for letters with more than one correct pronunciation (section 5 of pronunciation-rules.md).
-
-phrases.py writes the realisation its author chose (ق as ʔ in قديش, q in القدس). The scorer must accept
-the others too (kaddeesh is rural Palestinian), so before tokenising, archify() rewrites each phoneme that
-comes from such a letter as "SYMBOL:written" (Q:ʔ), and tokenize() scores it against every correct
-realisation at once. The written phoneme is kept for display, tips and calibration keys.
-
-The letter behind a phoneme is found by aligning the Arabic letters of the word with its IPA consonants.
-A phrase can also write a symbol itself: "Q", "Q:k", or with its own set of realisations, "TH{t,s}".
-"""
-from __future__ import annotations
-
-import re
-from functools import lru_cache
-
-from .phones import base
-
-# letter -> the symbol its phoneme is rewritten to
-LETTER_SYMBOL = {"ق": "Q", "ك": "K", "ث": "TH", "ذ": "DH", "ظ": "ZH", "ج": "J"}
-
-# letter -> base() names of the phonemes it is said as in the phrase bank (dialects, MSA, careless spelling)
-_LETTERS = {
-    "ب": {"b"}, "ت": {"t"}, "ث": {"t", "s", "θ"}, "ج": {"dʒ", "g"}, "ح": {"ħ"}, "خ": {"x"}, "د": {"d"},
-    "ذ": {"d", "z", "ð"}, "ر": {"r"}, "ز": {"z"}, "س": {"s"}, "ش": {"ʃ"}, "ص": {"sˤ", "s"}, "ض": {"dˤ", "d"},
-    "ط": {"tˤ", "t"}, "ظ": {"ðˤ", "dˤ", "zˤ", "z", "ð"}, "ع": {"ʕ"}, "غ": {"ɣ"}, "ف": {"f"}, "ق": {"ʔ", "q", "k", "g"},
-    "ك": {"k", "tʃ"}, "ل": {"l"}, "م": {"m"}, "ن": {"n"}, "ه": {"h"}, "و": {"w"}, "ي": {"j"}, "ى": set(),
-    "ء": {"ʔ"}, "أ": {"ʔ"}, "إ": {"ʔ"}, "آ": {"ʔ"}, "ؤ": {"ʔ"}, "ئ": {"ʔ"}, "ا": {"ʔ"}, "ة": {"t"},
-}
-# letters that are often not said as a consonant at all (vowel letters, hamza seats, the article's ل): cheap to skip
-_WEAK = set("اوىيةهءأإآؤئل")
-_VOWELS = {"a", "i", "u", "e", "o", "ə"}
-
-_TOKEN = re.compile(r"^([A-Z]+)(?:\{([^}]*)\})?(?::(.+))?$")
-
-
-def split_token(tok: str) -> tuple[str | None, list[str] | None, str]:
-    """"Q:ʔ" -> ("Q", None, "ʔ"); "TH{t,s}" -> ("TH", ["t", "s"], "t"); "ʕ" -> (None, None, "ʕ").
-
-    The phoneme of a symbol written without one is its first listed realisation, or "" (the caller picks)."""
-    m = _TOKEN.match(tok)
-    if not m:
-        return None, None, tok
-    sym, members, written = m.group(1), m.group(2), m.group(3)
-    members = [p.strip() for p in members.split(",") if p.strip()] if members else None
-    return sym, members, written or (members[0] if members else "")
-
-
-def written(tok: str) -> str:
-    """The phoneme a token is written as in the phrase (Q:ʔ -> ʔ)."""
-    return split_token(tok)[2] or tok
-
-
-def _letters(ar_word: str) -> list[str]:
-    return [c for c in ar_word if c in _LETTERS]
-
-
-def _units(phs: list[str]) -> list[tuple[str, list[int]]]:
-    """The consonants of an IPA word, a geminate run as one unit: (base name, its positions)."""
-    out: list[tuple[str, list[int]]] = []
-    for i, ph in enumerate(phs):
-        b = base(ph)
-        if b in _VOWELS:
-            continue
-        if out and out[-1][0] == b and out[-1][1][-1] == i - 1:
-            out[-1][1].append(i)
-        else:
-            out.append((b, [i]))
-    return out
-
-
-_SKIP_LETTER, _SKIP_WEAK, _SKIP_UNIT, _MISMATCH = 1.0, 0.3, 1.0, 1.6
-
-
-def _align(letters: list[str], units: list[str]) -> tuple[dict[int, set[int]], float]:
-    """For each letter, the units it matches on some cheapest alignment of letters to consonants.
-
-    A letter matched to different units on two cheapest alignments (or matched on one and skipped on
-    another) is ambiguous; the caller leaves it alone."""
-    n, m = len(letters), len(units)
-    inf = float("inf")
-
-    def cost(i, j):
-        return 0.0 if units[j] in _LETTERS[letters[i]] else _MISMATCH
-
-    def skip(i):
-        return _SKIP_WEAK if letters[i] in _WEAK else _SKIP_LETTER
-
-    f = [[inf] * (m + 1) for _ in range(n + 1)]
-    f[0][0] = 0.0
-    for i in range(n + 1):
-        for j in range(m + 1):
-            if i < n:
-                f[i + 1][j] = min(f[i + 1][j], f[i][j] + skip(i))
-            if j < m:
-                f[i][j + 1] = min(f[i][j + 1], f[i][j] + _SKIP_UNIT)
-            if i < n and j < m:
-                f[i + 1][j + 1] = min(f[i + 1][j + 1], f[i][j] + cost(i, j))
-    b = [[inf] * (m + 1) for _ in range(n + 1)]
-    b[n][m] = 0.0
-    for i in range(n, -1, -1):
-        for j in range(m, -1, -1):
-            if i < n:
-                b[i][j] = min(b[i][j], b[i + 1][j] + skip(i))
-            if j < m:
-                b[i][j] = min(b[i][j], b[i][j + 1] + _SKIP_UNIT)
-            if i < n and j < m:
-                b[i][j] = min(b[i][j], b[i + 1][j + 1] + cost(i, j))
-    best, eps = f[n][m], 1e-9
-    matched: dict[int, set[int]] = {}
-    for i in range(n):
-        for j in range(m):
-            if cost(i, j) == 0.0 and abs(f[i][j] + b[i + 1][j + 1] - best) < eps:
-                matched.setdefault(i, set()).add(j)
-        # skipping letter i on a cheapest alignment
-        if any(abs(f[i][j] + skip(i) + b[i + 1][j] - best) < eps for j in range(m + 1)):
-            matched.setdefault(i, set()).add(-1)
-    return matched, best
-
-
-def archify_word(ipa_word: str, ar_word: str, off: frozenset[str] = frozenset()) -> tuple[str, list[str]]:
-    """One word: its IPA with symbol tokens, and the letters that could not be placed (ambiguous).
-    Symbols in `off` (switched off by the teacher) are left as the phoneme the phrase writes."""
-    phs = ipa_word.split()
-    if any(split_token(p)[0] for p in phs):
-        return ipa_word, []      # the phrase writes its symbols itself
-    letters, units = _letters(ar_word), _units(phs)
-    matched, _ = _align(letters, [u for u, _ in units])
-    out, unresolved = list(phs), []
-    for i, letter in enumerate(letters):
-        sym = LETTER_SYMBOL.get(letter)
-        if sym is None or sym in off:
-            continue
-        hits = matched.get(i, {-1})
-        if len(hits) != 1:
-            unresolved.append(letter)
-            continue
-        j = next(iter(hits))
-        if j < 0:
-            continue              # not said at all (a dropped ق): nothing to rewrite
-        for k in units[j][1]:
-            out[k] = f"{sym}:{phs[k]}"
-    # the vowel of a final ة (and ه written for it): a, e and i are all correct (section 6.3 #5)
-    if ("E" not in off and out and ar_word.endswith(("ة", "ه")) and "لله" not in ar_word
-            and base(out[-1]) in {"a", "e", "i"} and len(out) > 1):
-        out[-1] = f"E:{out[-1]}"
-    return " ".join(out), unresolved
-
-
-@lru_cache(maxsize=32768)  # the whole phrase bank (~12k variants) and the verb game's forms
-def archify(ar: str, ipa: str, off: frozenset[str] = frozenset()) -> str:
-    """The variant's IPA with each phoneme of a many-ways letter rewritten as its symbol (see the module doc).
-
-    A variant whose Arabic and IPA word counts differ is returned as it is."""
-    ipa_words, ar_words = ipa.split("|"), ar.split()
-    if len(ipa_words) != len(ar_words):
-        return ipa
-    return " | ".join(archify_word(w.strip(), a, off)[0] for w, a in zip(ipa_words, ar_words))
-
-
-def unresolved(ar: str, ipa: str) -> list[tuple[str, str]]:
-    """(Arabic word, letter) for every many-ways letter archify() could not place: the phrase must mark it."""
-    ipa_words, ar_words = ipa.split("|"), ar.split()
-    if len(ipa_words) != len(ar_words):
-        return []
-    return [(a, letter) for w, a in zip(ipa_words, ar_words) for letter in archify_word(w.strip(), a)[1]]
-
-
-def diphthong_variants(ar: str, ipa: str) -> list[str]:
-    """The same variant with eː said as a j and oː as a w where the Arabic writes ي / و (section 6.3 #8).
-
-    A diphthong is two tokens against one, so it is a variant of its own rather than a class."""
-    ipa_words, ar_words = ipa.split("|"), ar.split()
-    if len(ipa_words) != len(ar_words):
-        return []
-    out = []
-    for long, glide, letter in (("eː", "j", "ي"), ("oː", "w", "و")):
-        words = [" ".join(f"a {glide}" if ph == long and letter in a else ph for ph in w.split())
-                 for w, a in zip(ipa_words, ar_words)]
-        new = " | ".join(words)
-        if new != " | ".join(w.strip() for w in ipa_words):
-            out.append(new)
-    return out

app/auth.py

@@ -1,112 +1,20 @@
-"""Sign-in: the page logs in through Supabase, with Google or with a link sent to the email, and sends the session token with each call.
-
-The token is checked by asking Supabase who it belongs to (GET /auth/v1/user), so no signing key is
-kept here and a session revoked in Supabase stops working within CACHE_TTL.
-
-Progress: each scored recording is added to the Supabase table `attempts` with the student's own
-token, so row-level security ties the row to them (the table's SQL is in the README).
-
-Teachers: the accounts in TEACHER_EMAILS also get the management panel, which shows every student's
-progress. Those rows are read with the project's secret key, which passes row-level security and
-never leaves the server.
-
-Classes: the teacher opens classes in the panel (a name, e.g. "October 2026", the lessons it studies, its
-students' emails and an optional nickname of each, and the homework: a topic of its lessons, with the day it is due),
-kept in the Supabase table `classes`. A student may be in several. Once there is a class, only the classes'
-students and the teachers are let in; before the first one (or without the secret key, which reads the table) any account is.
-
-Videos: the teacher adds lesson videos in the panel's content part (a lesson, a title and a Vimeo or YouTube link) and moves
-each to its place among the lesson's topics, kept in the Supabase table `videos`. A student's path shows them as
-topics of their lessons.
-
-Texts: the teacher also adds texts there (a story or a dialogue: a lesson, a title, its lines in Hebrew and in
-Arabic written in Hebrew letters, and a dialogue's two voices), kept in the Supabase table `texts` and placed among
-the lesson's topics like the videos. Each is a topic practised line by line (see app/texts.py).
-
-Daily videos: a library the teacher keeps in the content part, a level's videos each with a title and a Vimeo or
-YouTube link, in the Supabase table `dailies`. A class gives a video its day (the class's `dailies`); on that day its
-students get a reminder above the path to watch it.
-
-Library: other videos (a title and a link each), in the Supabase table `library`, one for every level. Every student
-browses them from the tab at the screen's foot, whatever their level and class.
-
-Current lessons: a student tells, once for each class, which lesson the class is on now; the focused home of the page
-starts from it. It is the student's own, kept by email and class id in the Supabase table `learner_class_state`,
-read and written with the secret key only (the server takes the email from the session, never from the request).
-
-Tutors: the teacher gives a student the tutor's rank in the panel, in the list of all the students above the classes' tabs. It is the student's,
-whatever classes they are in, so it is kept by email in the Supabase table `tutors`.
-
-Flags: a teacher, a tutor, and an account in TUTORS_EMAIL, gets a flag under each score, for a recording that was said right and scored
-wrong. A flag keeps what describes the case in the Supabase table `flags`, and the recording itself in the storage
-bucket `flags`, both written with the secret key: the material for changing the scoring, and later for fine-tuning.
-
-Lab: a teacher's recordings of the lab's diagnostic list (see lab.py), each labelled said right or with one planted
-mistake, in the Supabase table `lab_samples` and the storage bucket `lab`, written with the secret key: the
-benchmark set of the phoneme recognition.
-
-Writing: a lesson's written homework (see workbook.py) is kept in the Supabase table `writings`, a row per student
-and topic, written with the student's own token like the attempts, so it follows them to any device. The panel
-reads every student's with the secret key.
-
-Tutor: each conversation of the game יאללה נדבר (see tutor.py), what the student said and how the tutor answered, in the
-Supabase table `tutor_chats`, written with the secret key, for the teacher to read.
-
-Env:  SUPABASE_URL             (https://<project-ref>.supabase.co)
-      SUPABASE_PUBLISHABLE_KEY  (the publishable/anon key; it is public and also goes to the page)
-      TEACHER_EMAILS            (optional: the accounts with the management panel, separated by commas or spaces)
-      TUTORS_EMAIL              (optional: more accounts that flag a wrong score, as the teachers do; separated by commas or spaces)
-      DEVELOPER_EMAILS           (optional bootstrap accounts with full access, including the Lab)
-      SUPABASE_SECRET_KEY       (the secret/service-role key, needed by the panel, the classes and the flags; never public)
-Without them the service is open, as before.
-"""
+"""Optional Supabase sign-in and math-class storage."""
 from __future__ import annotations
 
 import json
-import hashlib
 import logging
-import mimetypes
 import os
 import re
-import tempfile
 import threading
 import time
 import urllib.error
 import urllib.parse
 import urllib.request
-from datetime import datetime, timezone
-from pathlib import Path
-from zoneinfo import ZoneInfo
 
-log = logging.getLogger("ihki.auth")
+log = logging.getLogger("mathly.auth")
 TIMEOUT = 10
-CACHE_TTL = 300  # seconds a checked token is trusted without asking again
-CACHE_MAX = 2000
-PAGE = 1000  # rows per request: Supabase's default ceiling
-MAX_ATTEMPTS = 20_000  # of one student, read for their progress
-MAX_CLASS_ATTEMPTS = 200_000  # of all students, read for the teacher's panel
-MAX_MONITOR_ATTEMPTS = 5_000  # newest compact attempts sampled for pronunciation patterns; never audio
-MAX_DIFFICULTY_ATTEMPTS = 50_000  # bounded scoped metadata; refuse rather than rank a partial sample
-CLASSES_TTL = 60  # seconds the class list is trusted without reading it again (each sign-in check uses it)
-# One-time migration boundary requested on 24 Oct 2026: the then-current seven days remain in Supabase forever.
-DEFAULT_AUDIO_MIGRATION_CUTOFF = "2026-10-17T00:00:00+03:00"
-CREATE_LEARNER_CLASS_STATE = (
-    "create table public.learner_class_state (email text not null, "
-    "class_id bigint not null references public.classes (id) on delete cascade, current_lesson text not null, "
-    "created_at timestamptz not null default now(), updated_at timestamptz not null default now(), "
-    "primary key (email, class_id)); "
-    "alter table public.learner_class_state enable row level security; "
-    "revoke all on public.learner_class_state from anon, authenticated;")
-
-# Application-owned data. Supabase's auth users and managed schemas are deliberately not copied.
-BACKUP_TABLES = (
-    "dailies", "library", "videos", "texts", "classes", "writings", "tutors", "flags",
-    "lab_samples", "calibrations", "scoring_rules", "user_access", "access_audit", "app_secrets",
-    "system_events", "tutor_chats", "model_settings",
-)
-BACKUP_NATURAL_KEYS = {"writings": "user_id,topic", "tutors": "email", "scoring_rules": "id",
-                       "user_access": "user_id", "app_secrets": "name", "tutor_chats": "id",
-                       "model_settings": "model"}
+CACHE_TTL = 300
+CLASSES_TTL = 60
 
 
 class AuthUnavailable(RuntimeError):
@@ -114,1133 +22,127 @@ class AuthUnavailable(RuntimeError):
 
 
 class ClassConflict(ValueError):
-    """Supabase refused a class: its name is taken."""
-
-
-class HFAudioStore:
-    """Private durable audio storage in a Hugging Face Storage Bucket."""
-
-    def __init__(self, bucket_id: str, prefix: str = "ihki-audio", token: str | None = None):
-        self.bucket_id, self.prefix, self.token = bucket_id, prefix.strip("/"), token
-
-    def path(self, bucket: str, name: str) -> str:
-        rel = f"{bucket}/{name.lstrip('/')}"
-        return f"{self.prefix}/{rel}" if self.prefix else rel
-
-    def put(self, bucket: str, name: str, data: bytes) -> None:
-        from huggingface_hub import batch_bucket_files
-        batch_bucket_files(self.bucket_id, add=[(data, self.path(bucket, name))], token=self.token)
-
-    def get(self, bucket: str, name: str) -> bytes:
-        from huggingface_hub import download_bucket_files
-        with tempfile.TemporaryDirectory(prefix="ihki-audio-") as directory:
-            target = Path(directory) / Path(name).name
-            download_bucket_files(self.bucket_id, [(self.path(bucket, name), target)],
-                                  raise_on_missing_files=True, token=self.token)
-            return target.read_bytes()
-
-    def delete(self, bucket: str, names: list[str]) -> None:
-        if not names:
-            return
-        from huggingface_hub import batch_bucket_files
-        batch_bucket_files(self.bucket_id, delete=[self.path(bucket, name) for name in names], token=self.token)
+    pass
 
 
 class SupabaseAuth:
     def __init__(self, url: str, key: str, teachers: frozenset[str] = frozenset(), secret: str = "",
-                 tutors: frozenset[str] = frozenset(), developers: frozenset[str] = frozenset(),
-                 audio_store: HFAudioStore | None = None, audio_migrate_before: str = ""):
-        self.url, self.key = url.rstrip("/"), key
-        self.teachers = teachers  # lower-case emails of the accounts with the management panel
-        self.tutors = tutors  # lower-case emails of the accounts that flag a wrong score, besides the teachers
-        self.developers = developers  # bootstrap accounts; only developers may use the lab
-        self.secret = secret  # reads every student's rows and the classes; empty = the panel has no data
-        self.audio_store = audio_store
-        self.audio_migrate_before = audio_migrate_before
-        self._cache: dict[str, tuple[float, dict]] = {}
+                 developers: frozenset[str] = frozenset()):
+        self.url, self.key, self.secret = url.rstrip("/"), key, secret
+        self.teachers, self.developers = teachers, developers
+        self._users: dict[str, tuple[float, dict]] = {}
         self._classes: tuple[float, list[dict]] | None = None
-        self._videos: tuple[float, list[dict]] | None = None
-        self._texts: tuple[float, list[dict]] | None = None
-        self._ranked: tuple[float, frozenset[str] | None] | None = None
         self._access: dict[str, tuple[float, dict | None]] = {}
-        self._level_videos: dict[str, tuple[float, list[dict]]] = {}   # by table: the daily videos, the library
         self._lock = threading.Lock()
 
     def user(self, token: str) -> dict | None:
-        """The signed-in user of this access token ({"id", "email"}), or None when it is not valid."""
         now = time.monotonic()
         with self._lock:
-            hit = self._cache.get(token)
-        if hit and hit[0] > now:
-            return hit[1]
-        req = urllib.request.Request(
-            self.url + "/auth/v1/user",
-            headers={"Authorization": f"Bearer {token}", "apikey": self.key, "User-Agent": "ihki/1.0"},
-        )
+            cached = self._users.get(token)
+        if cached and cached[0] > now:
+            return cached[1]
+        request = urllib.request.Request(self.url + "/auth/v1/user",
+            headers={"Authorization": f"Bearer {token}", "apikey": self.key, "User-Agent": "mathly/1.0"})
         try:
-            with urllib.request.urlopen(req, timeout=TIMEOUT) as res:
-                data = json.load(res)
-        except urllib.error.HTTPError as e:
-            if e.code in (400, 401, 403):
+            with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
+                data = json.load(response)
+        except urllib.error.HTTPError as exc:
+            if exc.code in (400, 401, 403):
                 return None
-            raise AuthUnavailable(f"supabase answered {e.code}") from e
-        except (urllib.error.URLError, TimeoutError, ValueError) as e:
-            raise AuthUnavailable(str(e)) from e
+            raise AuthUnavailable(f"supabase answered {exc.code}") from exc
+        except (urllib.error.URLError, TimeoutError, ValueError) as exc:
+            raise AuthUnavailable(str(exc)) from exc
         if not data.get("id"):
             return None
         user = {"id": data["id"], "email": data.get("email", "")}
         with self._lock:
-            if len(self._cache) >= CACHE_MAX:
-                self._cache.clear()
-            self._cache[token] = (now + CACHE_TTL, user)
+            self._users[token] = (now + CACHE_TTL, user)
         return user
 
-    def record(self, token: str, row: dict) -> None:
-        """Adds one row to `attempts` as the student of this token. A failure is logged, never raised."""
-        def request(values: dict):
-            return urllib.request.Request(
-                self.url + "/rest/v1/attempts", data=json.dumps(values).encode(), method="POST",
-                headers={"Authorization": f"Bearer {token}", "apikey": self.key, "Content-Type": "application/json",
-                         "Prefer": "return=minimal", "User-Agent": "ihki/1.0"})
-        try:
-            urllib.request.urlopen(request(row), timeout=TIMEOUT).close()
-        except urllib.error.HTTPError as e:
-            if e.code == 400 and any(k in row for k in ("issues", "model", "version")):
-                legacy = {k: v for k, v in row.items() if k not in ("issues", "model", "version")}
-                try:
-                    urllib.request.urlopen(request(legacy), timeout=TIMEOUT).close()
-                    log.warning("attempt stored without issue diagnostics; migrate the attempts table (see README)")
-                    return
-                except (urllib.error.URLError, TimeoutError) as retry:
-                    e = retry
-            log.warning("attempt not recorded: %s", e)
-        except (urllib.error.URLError, TimeoutError) as e:  # HTTPError is a URLError
-            log.warning("attempt not recorded: %s", e)
-
-    def attempts(self, token: str) -> list[dict]:
-        """The student's non-empty scored recordings, newest first: cat, phrase, score, unrelated, created_at.
-        Row-level security limits them to the token's student. What cannot be read is logged."""
-        rows: list[dict] = []
-        while len(rows) < MAX_ATTEMPTS:
-            query = urllib.parse.urlencode({"select": "cat,phrase,score,unrelated,created_at",
-                                            "order": "created_at.desc", "limit": PAGE, "offset": len(rows)})
-            try:
-                batch = self._get(f"/rest/v1/attempts?{query}", token, self.key)
-            except (urllib.error.URLError, TimeoutError, ValueError) as e:
-                log.warning("attempts not read: %s", e)
-                break
-            rows += batch
-            if len(batch) < PAGE:
-                break
-        return rows
-
-    def writings(self, token: str) -> dict[str, list[str]]:
-        """The student's written homework, {topic id: its lines}. Row-level security limits it to the token's student.
-        Before the table is created there is none; any other failure is raised, so the page keeps its own copy."""
-        try:
-            rows = self._get("/rest/v1/writings?select=topic,lines", token, self.key)
-        except urllib.error.HTTPError as e:
-            if e.code == 404:
-                log.warning("the table `writings` is missing (see the README): written homework stays on the device")
-                raise AuthUnavailable("the table writings is missing") from e
-            raise AuthUnavailable(f"supabase answered {e.code}") from e
-        except (urllib.error.URLError, TimeoutError, ValueError) as e:
-            raise AuthUnavailable(str(e)) from e
-        return {r["topic"]: [str(x) for x in r["lines"]] for r in rows if isinstance(r.get("lines"), list)}
-
-    def save_writing(self, token: str, user_id: str, topic: str, lines: list[str]) -> None:
-        """Keeps a topic's lines as the student of this token, in place of what they wrote in it before."""
-        row = {"user_id": user_id, "topic": topic, "lines": lines, "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
-        req = urllib.request.Request(
-            self.url + "/rest/v1/writings?on_conflict=user_id,topic", data=json.dumps(row).encode(), method="POST",
-            headers={"Authorization": f"Bearer {token}", "apikey": self.key, "Content-Type": "application/json",
-                     "Prefer": "resolution=merge-duplicates,return=minimal", "User-Agent": "ihki/1.0"})
-        try:
-            urllib.request.urlopen(req, timeout=TIMEOUT).close()
-        except urllib.error.HTTPError as e:
-            raise AuthUnavailable(f"supabase answered {e.code}: {e.read().decode(errors='replace')[:300]}") from e
-        except (urllib.error.URLError, TimeoutError) as e:
-            raise AuthUnavailable(str(e)) from e
-
-    def all_writings(self) -> list[dict] | None:
-        """Every student's written homework, for the panel: user_id, topic, lines. Before the table is created it is
-        None: nothing a student writes is kept, which the panel says."""
-        try:
-            return self._admin(f"/rest/v1/writings?select=user_id,topic,lines&limit={PAGE * 10}")
-        except AuthUnavailable as e:
-            if "answered 404" not in str(e):
-                raise
-            log.warning("the table `writings` is missing (see the README): the panel shows no written homework")
-            return None
-
-    def _get(self, path: str, token: str, key: str):
-        req = urllib.request.Request(
-            self.url + path, headers={"Authorization": f"Bearer {token}", "apikey": key, "User-Agent": "ihki/1.0"})
-        with urllib.request.urlopen(req, timeout=TIMEOUT) as res:
-            return json.load(res)
-
-    def _admin(self, path: str, method: str = "GET", body: dict | None = None, prefer: str = "return=representation",
-               timeout: int = TIMEOUT):
-        """A call with the secret key, for the teacher's panel. Unlike a student's own progress, a failure is raised."""
+    def _admin(self, path: str, method: str = "GET", body=None, prefer: str = "return=representation"):
         if not self.secret:
             raise AuthUnavailable("SUPABASE_SECRET_KEY is not set")
-        req = urllib.request.Request(
-            self.url + path, method=method, data=json.dumps(body).encode() if body is not None else None,
-            headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret, "Content-Type": "application/json",
-                     "Prefer": prefer, "User-Agent": "ihki/1.0"})
-        try:
-            with urllib.request.urlopen(req, timeout=timeout) as res:
-                return json.loads(res.read() or b"null")
-        except urllib.error.HTTPError as e:
-            detail = e.read().decode(errors="replace")[:300]
-            if e.code == 409:
-                raise ClassConflict(detail) from e
-            raise AuthUnavailable(f"supabase answered {e.code}: {detail}") from e
-        except (urllib.error.URLError, TimeoutError, ValueError) as e:
-            raise AuthUnavailable(str(e)) from e
-
-    def backup_rows(self) -> dict[str, list[dict]]:
-        """All application-owned table rows. Tables not installed in an older deployment are omitted."""
-        result: dict[str, list[dict]] = {}
-        for table in BACKUP_TABLES:
-            rows = []
-            try:
-                for offset in range(0, 10_000_000, PAGE):
-                    path = f"/rest/v1/{table}?select=*&limit={PAGE}&offset={offset}"
-                    for attempt in range(3):
-                        try:
-                            batch = self._admin(path, timeout=60) or []
-                            break
-                        except AuthUnavailable as e:
-                            if attempt == 2 or not any(x in str(e).lower() for x in ("timed out", "timeout")):
-                                raise
-                    rows.extend(batch)
-                    if len(batch) < PAGE:
-                        break
-                result[table] = rows
-            except AuthUnavailable as e:
-                if "answered 404" not in str(e):
-                    raise
-        return result
-
-    def final_scores(self) -> list[dict]:
-        """One compact row per student and exercise: the highest score that drives the panel's final grades."""
-        best: dict[tuple[str, str, str], dict] = {}
-        for offset in range(0, MAX_CLASS_ATTEMPTS, PAGE):
-            query = urllib.parse.urlencode({"select": "user_id,cat,phrase,score,created_at",
-                                            "order": "id.asc", "limit": PAGE, "offset": offset})
-            path = f"/rest/v1/attempts?{query}"
-            for attempt in range(3):
-                try:
-                    batch = self._admin(path, timeout=60) or []
-                    break
-                except AuthUnavailable as e:
-                    if attempt == 2 or not any(x in str(e).lower() for x in ("timed out", "timeout")):
-                        raise
-            for row in batch:
-                key = (str(row["user_id"]), str(row["cat"]), str(row["phrase"]))
-                if key not in best or int(row["score"]) > int(best[key]["score"]):
-                    best[key] = row
-            if len(batch) < PAGE:
-                break
-        return list(best.values())
-
-    def restore_final_scores(self, rows: list[dict]) -> int:
-        """Restore only grades that improve the currently stored best score, without restoring attempt history."""
-        current = {(r["user_id"], r["cat"], r["phrase"]): int(r["score"]) for r in self.final_scores()}
-        add = [{**r, "unrelated": False} for r in rows
-               if int(r.get("score", -1)) > current.get((r.get("user_id"), r.get("cat"), r.get("phrase")), -1)]
-        for start in range(0, len(add), 200):
-            self._admin("/rest/v1/attempts", "POST", add[start:start + 200], prefer="return=minimal", timeout=60)
-        return len(add)
-
-    def restore_rows(self, tables: dict[str, list[dict]]) -> dict[str, int]:
-        """Merge a validated application backup. Existing rows are updated; unrelated current rows remain."""
-        restored: dict[str, int] = {}
-        text_ids: dict[int, int] = {}
-        daily_ids: dict[int, int] = {}
-        for table in BACKUP_TABLES:
-            rows = [dict(r) for r in tables.get(table, [])]
-            if not rows:
-                continue
-            if table == "classes":
-                for row in rows:
-                    row["dailies"] = [{**d, "video": daily_ids.get(d.get("video"), d.get("video"))}
-                                      for d in (row.get("dailies") or [])]
-                    for field in ("homework",):
-                        value = row.get(field, "")
-                        if isinstance(value, str) and value.startswith("t") and value[1:].isdigit():
-                            row[field] = "t" + str(text_ids.get(int(value[1:]), int(value[1:])))
-                    row["homeworks"] = [{**h, "topic": "t" + str(text_ids.get(int(h["topic"][1:]), int(h["topic"][1:])))
-                                          if isinstance(h.get("topic"), str) and h["topic"].startswith("t") and h["topic"][1:].isdigit()
-                                          else h.get("topic")} for h in (row.get("homeworks") or [])]
-            if table == "writings":
-                field = "topic"
-                for row in rows:
-                    value = row.get(field, "")
-                    if isinstance(value, str) and value.startswith("t") and value[1:].isdigit():
-                        row[field] = "t" + str(text_ids.get(int(value[1:]), int(value[1:])))
-            if table in BACKUP_NATURAL_KEYS:
-                key = BACKUP_NATURAL_KEYS[table]
-                for start in range(0, len(rows), 200):
-                    self._admin(f"/rest/v1/{table}?on_conflict={key}", "POST", rows[start:start + 200],
-                                prefer="resolution=merge-duplicates,return=minimal")
-                restored[table] = len(rows)
-                continue
-            for original in rows:
-                row = dict(original)
-                old_id = row.get("id")
-                if old_id is not None:
-                    patch = dict(row)
-                    patch.pop("id", None)
-                    existing = self._admin(f"/rest/v1/{table}?id=eq.{urllib.parse.quote(str(old_id))}", "PATCH", patch)
-                    if existing:
-                        new_id = old_id
-                    else:
-                        row.pop("id", None)  # identity columns reject explicitly supplied values
-                        made = self._admin(f"/rest/v1/{table}", "POST", row)
-                        new_id = made[0].get("id") if made else None
-                    if table == "texts" and new_id is not None:
-                        text_ids[int(old_id)] = int(new_id)
-                    if table == "dailies" and new_id is not None:
-                        daily_ids[int(old_id)] = int(new_id)
-                else:
-                    self._admin(f"/rest/v1/{table}", "POST", row, prefer="return=minimal")
-            restored[table] = len(rows)
-        self._classes = self._videos = self._texts = self._ranked = None
-        self._level_videos.clear()
-        self._access.clear()
-        return restored
+        request = urllib.request.Request(self.url + path, method=method,
+            data=json.dumps(body).encode() if body is not None else None,
+            headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret,
+                     "Content-Type": "application/json", "Prefer": prefer, "User-Agent": "mathly/1.0"})
+        try:
+            with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
+                return json.loads(response.read() or b"null")
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode(errors="replace")[:300]
+            if exc.code == 409:
+                raise ClassConflict(detail) from exc
+            raise AuthUnavailable(f"supabase answered {exc.code}: {detail}") from exc
+        except (urllib.error.URLError, TimeoutError, ValueError) as exc:
+            raise AuthUnavailable(str(exc)) from exc
 
     def classes(self, fresh: bool = False) -> list[dict]:
-        """Every class, newest first: id, name, emails (lower-case), nicknames ({email: nickname}), lessons (lesson ids;
-        empty in a class saved before classes had lessons), homeworks ([{"topic": a topic id, "due": its ISO date or
-        None}], one for each topic the class has as homework), homework and due (the first of them, as a class had
-        before it could have several; a class saved then has only these), dailies ([{"video": the id of a daily
-        video, "date": the ISO date the class watches it}]), created_at.
-        Kept for CLASSES_TTL, as each sign-in
-        check asks. Without the secret key, or before the table is created, there are none."""
         now = time.monotonic()
         with self._lock:
-            hit = self._classes
-        if hit and hit[0] > now and not fresh:
-            return hit[1]
+            cached = self._classes
+        if cached and cached[0] > now and not fresh:
+            return cached[1]
         rows: list[dict] = []
         if self.secret:
             try:
-                # every column: a table made before the nicknames still lets its students in
-                rows = self._admin("/rest/v1/classes?select=*&order=created_at.desc")
-                for r in rows:
-                    r["nicknames"], r["lessons"] = r.get("nicknames") or {}, r.get("lessons") or []
-                    r["homework"], r["due"] = r.get("homework") or "", r.get("due") or None
-                    r["homeworks"], r["dailies"] = r.get("homeworks") or [], r.get("dailies") or []
-                    r["teachers"] = [str(e).lower() for e in (r.get("teachers") or [])]
-            except AuthUnavailable as e:
-                if "answered 404" not in str(e):
+                rows = self._admin("/rest/v1/classes?select=*&order=created_at.desc") or []
+            except AuthUnavailable as exc:
+                if "answered 404" not in str(exc):
                     raise
-                log.warning("the table `classes` is missing (see the README): every account is let in")
+                log.warning("the classes table is missing; every account is allowed")
+        # During the database migration, ignore rows belonging to a removed product.
+        rows = [row for row in rows if not row.get("subject") or row.get("subject") == "מתמטיקה"]
+        for row in rows:
+            row["emails"] = [str(value).lower() for value in row.get("emails") or []]
+            row["teachers"] = [str(value).lower() for value in row.get("teachers") or []]
+            row["lessons"] = row.get("lessons") or []
+            row["nicknames"] = row.get("nicknames") or {}
         with self._lock:
             self._classes = (now + CLASSES_TTL, rows)
         return rows
 
-    def database_health(self) -> bool:
-        """Perform one bounded, read-only PostgREST probe without returning table data."""
-        if not self.secret:
-            return False
-        try:
-            self._admin("/rest/v1/classes?select=id&limit=1")
-        except AuthUnavailable as exc:
-            if "answered 404" not in str(exc):
-                raise
-        return True
-
-    def save_class(self, id: int | None, name: str, emails: list[str], nicknames: dict[str, str],
-                   lessons: list[str], homeworks: list[dict] = (), dailies: list[dict] | None = None,
-                   subject: str = "", teachers: list[str] | None = None) -> None:
-        """Adds a class (id None) or replaces one's name, emails, nicknames, lessons and homeworks ([{"topic", "due"}]),
-        and its daily videos' days ([{"video", "date"}]; None leaves them as they are, so a table made before them
-        still takes a class that has none). A name already taken raises ClassConflict."""
-        first = homeworks[0] if homeworks else {"topic": "", "due": None}   # the columns of a class with one homework
+    def save_class(self, class_id: int | None, name: str, emails: list[str], nicknames: dict[str, str],
+                   lessons: list[str], *, teachers: list[str] | None = None, **_ignored) -> None:
         body = {"name": name, "emails": emails, "nicknames": nicknames, "lessons": lessons,
-                "homework": first["topic"], "due": first["due"], "homeworks": list(homeworks)}
-        if dailies is not None:
-            body["dailies"] = list(dailies)
-        if teachers is not None:
-            body["teachers"] = list(teachers)
-        if id is None:
-            body["subject"] = subject
+                "teachers": list(teachers or [])}
+        if class_id is None:
             self._admin("/rest/v1/classes", "POST", body)
-        elif not self._admin(f"/rest/v1/classes?id=eq.{int(id)}", "PATCH", body):
-            raise KeyError(id)
+        elif not self._admin(f"/rest/v1/classes?id=eq.{int(class_id)}", "PATCH", body):
+            raise KeyError(class_id)
         self._classes = None
 
-    def delete_class(self, id: int) -> None:
-        self._admin(f"/rest/v1/classes?id=eq.{int(id)}", "DELETE")
+    def delete_class(self, class_id: int) -> None:
+        self._admin(f"/rest/v1/classes?id=eq.{int(class_id)}", "DELETE")
         self._classes = None
 
-    def videos(self, fresh: bool = False) -> list[dict]:
-        """Every lesson video, each lesson's in the order the teacher gave them: id, lesson (a lesson id), title, url
-        (the Vimeo or YouTube link), pos (how many of the lesson's own topics stand before it; None in a table made before videos
-        had places: after them all) and ord (its turn among the videos of one place).
-        Kept for CLASSES_TTL, as the path asks. Without the secret key, or before the table is created, there are none."""
-        now = time.monotonic()
-        with self._lock:
-            hit = self._videos
-        if hit and hit[0] > now and not fresh:
-            return hit[1]
-        rows: list[dict] = []
-        if self.secret:
-            try:
-                # every column: a table made before the places still shows its videos
-                rows = self._admin("/rest/v1/videos?select=*&order=id.asc")
-                for r in rows:
-                    r["pos"], r["ord"] = r.get("pos"), r.get("ord") or 0
-            except AuthUnavailable as e:
-                if "answered 404" not in str(e):
-                    raise
-                log.warning("the table `videos` is missing (see the README): the lessons have no videos")
-        with self._lock:
-            self._videos = (now + CLASSES_TTL, rows)
-        return rows
-
-    def add_video(self, lesson: str, title: str, url: str, pos: int, ord: int) -> None:
-        self._admin("/rest/v1/videos", "POST", {"lesson": lesson, "title": title, "url": url, "pos": pos, "ord": ord})
-        self._videos = None
-
-    def place(self, places: list[tuple[str, int, int, int]]) -> None:
-        """Moves videos and texts: (table, id, pos, ord) of each; the table is "videos" or "texts"."""
-        try:
-            for table, id, pos, ord in places:
-                assert table in ("videos", "texts")
-                self._admin(f"/rest/v1/{table}?id=eq.{int(id)}", "PATCH", {"pos": pos, "ord": ord})
-        finally:
-            self._videos = self._texts = None
-
-    def texts(self, fresh: bool = False) -> list[dict]:
-        """Every text the teacher added: id, lesson (a lesson id), title, voices (a dialogue's two voices by name,
-        the odd lines' and the even lines'; empty for a story), lines ([Hebrew, Arabic in Hebrew letters] each), and
-        pos and ord as a video has them (see `videos`).
-        Kept for CLASSES_TTL, as each score asks. Without the secret key, or before the table is created, there are none."""
-        now = time.monotonic()
-        with self._lock:
-            hit = self._texts
-        if hit and hit[0] > now and not fresh:
-            return hit[1]
-        rows: list[dict] = []
-        if self.secret:
-            try:
-                rows = self._admin("/rest/v1/texts?select=*&order=id.asc")
-                for r in rows:
-                    r["voices"], r["ord"] = r.get("voices") or [], r.get("ord") or 0
-            except AuthUnavailable as e:
-                if "answered 404" not in str(e):
-                    raise
-                log.warning("the table `texts` is missing (see the README): the lessons have no texts")
-        with self._lock:
-            self._texts = (now + CLASSES_TTL, rows)
-        return rows
-
-    def add_text(self, lesson: str, title: str, voices: list[str], lines: list[list[str]], pos: int, ord: int) -> None:
-        self._admin("/rest/v1/texts", "POST", {"lesson": lesson, "title": title, "voices": voices, "lines": lines,
-                                               "pos": pos, "ord": ord})
-        self._texts = None
-
-    def delete_text(self, id: int) -> None:
-        self._admin(f"/rest/v1/texts?id=eq.{int(id)}", "DELETE")
-        self._texts = None
-
-    def delete_video(self, id: int) -> None:
-        self._admin(f"/rest/v1/videos?id=eq.{int(id)}", "DELETE")
-        self._videos = None
-
-    def level_videos(self, table: str, fresh: bool = False) -> list[dict]:
-        """A level's videos that stand outside the path, in the order the teacher gave them (`ord`, see
-        `order_level_videos`) and then, those never moved, in the order they were added: id, level (a level id), title,
-        url (the Vimeo or YouTube link). `table` is "dailies" (the daily videos) or "library" (the video library,
-        which is one for every level: its `level` is empty). Kept for CLASSES_TTL. Without the secret key, or before the table is created, there are none."""
-        assert table in ("dailies", "library")
-        now = time.monotonic()
-        with self._lock:
-            hit = self._level_videos.get(table)
-        if hit and hit[0] > now and not fresh:
-            return hit[1]
-        rows: list[dict] = []
-        if self.secret:
-            try:
-                rows = self._admin(f"/rest/v1/{table}?select=*&order=id.asc")
-                rows.sort(key=lambda r: (r.get("ord") is None, r.get("ord") or 0, r["id"]))
-            except AuthUnavailable as e:
-                if "answered 404" not in str(e):
-                    raise
-                log.warning("the table `%s` is missing (see the README): it has no videos", table)
-        with self._lock:
-            self._level_videos[table] = (now + CLASSES_TTL, rows)
-        return rows
-
-    def add_level_video(self, table: str, level: str, title: str, url: str) -> None:
-        assert table in ("dailies", "library")
-        self._admin(f"/rest/v1/{table}", "POST", {"level": level, "title": title, "url": url})
-        self._level_videos.pop(table, None)
-
-    def delete_level_video(self, table: str, id: int) -> None:
-        assert table in ("dailies", "library")
-        self._admin(f"/rest/v1/{table}?id=eq.{int(id)}", "DELETE")
-        self._level_videos.pop(table, None)
-
-    def rename_level_video(self, table: str, id: int, title: str) -> None:
-        assert table in ("dailies", "library")
-        try:
-            self._admin(f"/rest/v1/{table}?id=eq.{int(id)}", "PATCH", {"title": title})
-        finally:
-            self._level_videos.pop(table, None)
-
-    def order_level_videos(self, table: str, ids: list[int]) -> None:
-        """Puts the table's videos in this order: each one's `ord` is its turn."""
-        assert table in ("dailies", "library")
-        try:
-            for k, id in enumerate(ids):
-                self._admin(f"/rest/v1/{table}?id=eq.{int(id)}", "PATCH", {"ord": k})
-        finally:
-            self._level_videos.pop(table, None)
-
-    def ranked(self, fresh: bool = False) -> frozenset[str] | None:
-        """The lower-case emails the teacher gave the tutor's rank (the table `tutors`). Kept for CLASSES_TTL, as each
-        sign-in check asks. None before the table is created; without the secret key there are none."""
-        now = time.monotonic()
-        with self._lock:
-            hit = self._ranked
-        if hit and hit[0] > now and not fresh:
-            return hit[1]
-        emails: frozenset[str] | None = frozenset()
-        if self.secret:
-            try:
-                emails = frozenset(r["email"].lower() for r in self._admin("/rest/v1/tutors?select=email"))
-            except AuthUnavailable as e:
-                if "answered 404" not in str(e):
-                    raise
-                log.warning("the table `tutors` is missing (see the README): no student has the tutor's rank")
-                emails = None
-        with self._lock:
-            self._ranked = (now + CLASSES_TTL, emails)
-        return emails
-
-    def set_tutor(self, email: str, on: bool, by: str) -> None:
-        """Gives the account of this email the tutor's rank, or takes it back. `by` is the teacher who gave it."""
-        email = email.lower()
-        try:
-            if on:
-                self._admin("/rest/v1/tutors", "POST", {"email": email, "granted_by": by})
-            else:
-                self._admin(f"/rest/v1/tutors?email=eq.{urllib.parse.quote(email)}", "DELETE")
-        except ClassConflict:   # has it already
-            pass
-        finally:
-            self._ranked = None
-
-    def current_lessons(self, email: str) -> dict[int, str]:
-        """The current lesson this account chose in each of its classes: {class id: lesson id}. Empty without the
-        secret key or before the table is created (the page then keeps the choice on the device); other failures raise."""
-        if not self.secret:
-            return {}
-        q = urllib.parse.urlencode({"select": "class_id,current_lesson", "email": f"eq.{email.strip().lower()}"})
-        try:
-            rows = self._admin(f"/rest/v1/learner_class_state?{q}") or []
-        except AuthUnavailable as e:
-            if "answered 404" not in str(e):
-                raise
-            log.warning("the table `learner_class_state` is missing (see the README): current lessons stay on the device")
-            return {}
-        return {int(r["class_id"]): str(r["current_lesson"]) for r in rows if r.get("current_lesson")}
-
-    def set_current_lesson(self, email: str, class_id: int, lesson: str) -> None:
-        """Keeps this account's current lesson in one class, replacing the one it had there. Only the account's own row:
-        the caller passes the session's email. A missing table raises with the command that creates it."""
-        row = {"email": email.strip().lower(), "class_id": int(class_id), "current_lesson": str(lesson).strip(),
-               "updated_at": datetime.now(timezone.utc).isoformat()}
-        try:
-            self._admin("/rest/v1/learner_class_state?on_conflict=email,class_id", "POST", row,
-                        prefer="resolution=merge-duplicates,return=minimal")
-        except AuthUnavailable as e:
-            if "answered 404" in str(e):
-                raise AuthUnavailable("the table learner_class_state is missing; run in Supabase's SQL editor: "
-                                      f"{CREATE_LEARNER_CLASS_STATE}") from e
-            raise
-
-    def _put_object(self, bucket: str, name: str, data: bytes, mime: str) -> bool:
-        """Stores a recording in a private storage bucket; False (logged) when it cannot be stored."""
-        if not self.secret:
-            return False
-        req = urllib.request.Request(
-            f"{self.url}/storage/v1/object/{bucket}/{urllib.parse.quote(name)}", data=data, method="POST",
-            headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret, "Content-Type": mime,
-                     "User-Agent": "ihki/1.0"})
-        try:
-            urllib.request.urlopen(req, timeout=TIMEOUT).close()
-            return True
-        except (urllib.error.URLError, TimeoutError) as e:  # HTTPError is a URLError
-            log.warning("a recording not stored (is there a storage bucket `%s`? see the README): %s", bucket, e)
-            return False
-
-    def _delete_objects(self, bucket: str, names: list[str]) -> bool:
-        """Removes recordings of a private storage bucket; False (logged) when some could not be removed."""
-        ok = True
-        for k in range(0, len(names), 1000):   # the storage API takes up to 1000 names a call
-            req = urllib.request.Request(
-                f"{self.url}/storage/v1/object/{bucket}", method="DELETE",
-                data=json.dumps({"prefixes": names[k:k + 1000]}).encode(),
-                headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret,
-                         "Content-Type": "application/json", "User-Agent": "ihki/1.0"})
-            try:
-                urllib.request.urlopen(req, timeout=TIMEOUT).close()
-            except (urllib.error.URLError, TimeoutError) as e:
-                log.warning("recordings of the storage bucket `%s` not removed: %s", bucket, e)
-                ok = False
-        return ok
-
-    def _get_object(self, bucket: str, name: str) -> tuple[bytes, str]:
-        """A recording of a private storage bucket and its media type."""
-        req = urllib.request.Request(
-            f"{self.url}/storage/v1/object/{bucket}/{urllib.parse.quote(name)}",
-            headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret, "User-Agent": "ihki/1.0"})
-        try:
-            with urllib.request.urlopen(req, timeout=TIMEOUT) as res:
-                data = res.read()
-                media_type = res.headers.get_content_type()
-        except (urllib.error.URLError, TimeoutError) as e:
-            raise AuthUnavailable(f"{bucket} audio unavailable: {e}") from e
-        if media_type == "application/octet-stream":
-            media_type = mimetypes.guess_type(name)[0] or media_type
-        return data, media_type
-
-    def _put_audio(self, bucket: str, name: str, data: bytes, mime: str) -> bool:
-        """Keep audio in HF when configured; Supabase is the legacy/default store only."""
-        if self.audio_store:
-            try:
-                self.audio_store.put(bucket, name, data)
-                return True
-            except Exception as e:
-                log.warning("%s audio not stored in Hugging Face bucket: %s", bucket, e)
-                return False
-        return self._put_object(bucket, name, data, mime)
-
-    def _get_audio(self, bucket: str, name: str, created_at: str = "") -> tuple[bytes, str]:
-        """Read new HF audio first, then fall back to legacy Supabase recordings."""
-        sources = ("hf", "supabase") if self.audio_store else ("supabase",)
-        errors = []
-        for source in sources:
-            if source == "hf":
-                if not self.audio_store:
-                    continue
-                try:
-                    return self.audio_store.get(bucket, name), mimetypes.guess_type(name)[0] or "application/octet-stream"
-                except Exception as e:
-                    errors.append(f"Hugging Face: {e}")
-            else:
-                try:
-                    return self._get_object(bucket, name)
-                except AuthUnavailable as e:
-                    errors.append(f"Supabase: {e}")
-        raise AuthUnavailable(f"{bucket} audio unavailable ({'; '.join(errors)})")
-
-    def migrate_legacy_audio(self) -> None:
-        """One-way migration before a fixed cutoff; newer legacy Supabase files remain indefinitely."""
-        if not self.audio_store or not self.secret or not self.audio_migrate_before:
-            return
-        threading.Thread(target=self._migrate_legacy_audio, name="ihki-audio-migration", daemon=True).start()
-
-    def _migrate_legacy_audio(self) -> None:
-        """Copy pre-cutoff audio to HF, then remove only the successfully copied Supabase objects."""
-        cutoff = self.audio_migrate_before
-        marker = hashlib.sha256(cutoff.encode()).hexdigest()[:16] + ".complete"
-        try:
-            self.audio_store.get("_migration", marker)
-            return
-        except Exception:
-            pass
-        complete = True
-        try:
-            for table, bucket in (("flags", "flags"), ("lab_samples", "lab")):
-                rows = []
-                for offset in range(0, 10_000_000, PAGE):
-                    query = urllib.parse.urlencode({"select": "audio,created_at", "audio": "not.is.null",
-                                                    "created_at": f"lt.{cutoff}", "order": "created_at.asc",
-                                                    "limit": PAGE, "offset": offset})
-                    batch = self._admin(f"/rest/v1/{table}?{query}") or []
-                    rows.extend(batch)
-                    if len(batch) < PAGE:
-                        break
-                copied = []
-                for row in rows:
-                    name = row.get("audio")
-                    if not name:
-                        continue
-                    try:
-                        data, _mime = self._get_object(bucket, name)
-                        self.audio_store.put(bucket, name, data)
-                        copied.append(name)
-                    except Exception as e:
-                        complete = False
-                        log.warning("old %s audio %s not migrated; Supabase copy retained: %s", bucket, name, e)
-                if copied and self._delete_objects(bucket, copied):
-                    log.info("migrated %d old %s recordings to Hugging Face and removed Supabase copies",
-                             len(copied), bucket)
-            if complete:
-                self.audio_store.put("_migration", marker, cutoff.encode())
-        except Exception as e:
-            log.warning("legacy audio migration failed: %s", e)
-
-    def ensure_backup_bucket(self) -> None:
-        """Create the private application-backup bucket on first use."""
-        try:
-            self._admin("/storage/v1/bucket/backups")
-        except AuthUnavailable as e:
-            detail = str(e).lower()
-            if not any(mark in detail for mark in ("answered 404", '"statuscode":"404"', "nosuchbucket", "bucket not found")):
-                raise
-            self._admin("/storage/v1/bucket", "POST", {"id": "backups", "name": "backups", "public": False},
-                        prefer="return=minimal")
-
-    def save_backup(self, name: str, data: bytes) -> None:
-        self.ensure_backup_bucket()
-        req = urllib.request.Request(
-            f"{self.url}/storage/v1/object/backups/{urllib.parse.quote(name)}", data=data, method="POST",
-            headers={"Authorization": f"Bearer {self.secret}", "apikey": self.secret,
-                     "Content-Type": "application/zip", "User-Agent": "ihki/1.0"})
-        try:
-            urllib.request.urlopen(req, timeout=max(TIMEOUT, 60)).close()
-        except urllib.error.HTTPError as e:
-            raise AuthUnavailable(f"supabase storage answered {e.code}: {e.read().decode(errors='replace')[:300]}") from e
-        except (urllib.error.URLError, TimeoutError) as e:
-            raise AuthUnavailable(str(e)) from e
-
-    def list_backups(self) -> list[dict]:
-        self.ensure_backup_bucket()
-        rows = self._admin("/storage/v1/object/list/backups", "POST",
-                           {"prefix": "", "limit": 100, "offset": 0, "sortBy": {"column": "name", "order": "desc"}})
-        return [r for r in (rows or []) if str(r.get("name", "")).endswith(".zip")]
-
-    def add_flag(self, row: dict, audio: bytes, mime: str, name: str) -> bool:
-        """Keeps a flagged score and its recording in HF, or Supabase when HF is not configured."""
-        kept = self._put_audio("flags", name, audio, mime)
-        self._admin("/rest/v1/flags", "POST", {**row, "audio": name if kept else None})
-        return kept
-
-    def list_flags(self, status: str = "pending") -> list[dict]:
-        """Flagged scores for the teacher's review, newest first."""
-        query = urllib.parse.urlencode({"select": "*", "status": f"eq.{status}", "order": "created_at.desc"})
-        return self._admin(f"/rest/v1/flags?{query}")
-
-    def review_flag(self, flag_id: int, values: dict) -> None:
-        """Records a teacher's decision about one flagged score."""
-        self._admin(f"/rest/v1/flags?id=eq.{int(flag_id)}", "PATCH", values)
-
-    def flag(self, flag_id: int) -> dict | None:
-        """One flag's row, or None."""
-        rows = self._admin(f"/rest/v1/flags?{urllib.parse.urlencode({'select': '*', 'id': f'eq.{int(flag_id)}', 'limit': 1})}")
-        return rows[0] if rows else None
-
-    def flag_audio(self, flag_id: int) -> tuple[bytes, str] | None:
-        """Returns one private flag recording and its media type, or None when it was not stored."""
-        query = urllib.parse.urlencode({"select": "audio,created_at", "id": f"eq.{int(flag_id)}", "limit": 1})
-        rows = self._admin(f"/rest/v1/flags?{query}")
-        name = rows[0].get("audio") if rows else None
-        return self._get_audio("flags", name, rows[0].get("created_at", "")) if name else None
-
-    def add_lab_sample(self, row: dict, audio: bytes, mime: str, name: str, attempts: int = 1) -> bool:
-        """Keeps a lab recording (see lab.py): the recording in the storage bucket `lab`, the row in the table
-        `lab_samples`. As with a flag, a recording that cannot be stored leaves the row without it (False).
-        `attempts` retries the upload (a bulk import outlives the storage's transient 5xx errors)."""
-        kept = False
-        for attempt in range(max(1, attempts)):
-            if attempt:
-                time.sleep(2 * attempt)
-            kept = self._put_audio("lab", name, audio, mime)
-            if kept:
-                break
-        self._admin("/rest/v1/lab_samples", "POST", {**row, "audio": name if kept else None}, prefer="return=minimal")
-        return kept
-
-    def lab_samples(self, full: bool = False) -> list[dict]:
-        """The lab's recordings, oldest first: what labels each one (and, with `full`, the scorer's whole result)."""
-        cols = "*" if full else "id,item,speaker,label,mistake,score,heard_ipa,flagged,model,audio,created_at"
-        # PostgREST caps a response (1000 rows by default), so the table is read in pages by id.
-        rows, last, page = [], 0, 500 if full else 1000
-        while True:
-            query = urllib.parse.urlencode({"select": cols, "order": "id.asc", "id": f"gt.{last}", "limit": page})
-            batch = self._admin(f"/rest/v1/lab_samples?{query}") or []
-            rows.extend(batch)
-            if len(batch) < page:
-                return rows
-            last = batch[-1]["id"]
-
-    def lab_sample(self, sample_id: int) -> dict | None:
-        """One lab recording's row, without the scorer's result, or None."""
-        query = urllib.parse.urlencode({"select": "id,item,ar,ipa,speaker,label,mistake,audio,result", "id": f"eq.{int(sample_id)}",
-                                        "limit": 1})
-        rows = self._admin(f"/rest/v1/lab_samples?{query}")
-        return rows[0] if rows else None
-
-    def lab_audio(self, sample_id: int) -> tuple[bytes, str] | None:
-        """One lab recording and its media type, or None when it was not stored."""
-        row = self.lab_sample(sample_id)
-        return self._get_audio("lab", row["audio"], row.get("created_at", "")) if row and row.get("audio") else None
-
-    def update_lab_result(self, sample_id: int, result: dict) -> None:
-        """Updates a lab result's review metadata (the original scoring fields remain in the same JSON document)."""
-        self._admin(f"/rest/v1/lab_samples?id=eq.{int(sample_id)}", "PATCH", {"result": result})
-
-    def delete_lab_samples(self, speaker: str | None = None) -> int:
-        """Deletes the lab's recordings of one speaker ("": the unnamed), or of every speaker when None: the rows,
-        then their files in the bucket `lab` (a file that cannot be removed is logged and left). Returns how many rows."""
-        where = {"speaker": f"eq.{speaker}"} if speaker is not None else {"id": "gt.0"}  # a DELETE needs a filter
-        rows = self._admin(f"/rest/v1/lab_samples?{urllib.parse.urlencode({**where, 'select': 'id,audio'})}",
-                           "DELETE") or []
-        names = [r["audio"] for r in rows if r.get("audio")]
-        if names:
-            self._delete_objects("lab", names)
-            if self.audio_store:
-                try:
-                    self.audio_store.delete("lab", names)
-                except Exception as e:
-                    log.warning("lab recordings not deleted from Hugging Face bucket: %s", e)
-        return len(rows)
-
-    def calibrations(self, status: str | None = None) -> list[dict]:
-        """Calibration proposals, optionally filtered by their workflow status."""
-        params = {"select": "*", "order": "created_at.desc"}
-        if status:
-            params["status"] = f"eq.{status}"
-        return self._admin(f"/rest/v1/calibrations?{urllib.parse.urlencode(params)}")
-
-    def add_calibration(self, row: dict) -> dict:
-        """Creates one draft calibration proposal and returns its stored row."""
-        made = self._admin("/rest/v1/calibrations", "POST", row)
-        return made[0] if made else row
-
-    def update_calibration(self, calibration_id: int, values: dict) -> None:
-        """Updates and optionally applies or rejects a calibration proposal."""
-        self._admin(f"/rest/v1/calibrations?id=eq.{int(calibration_id)}", "PATCH", values)
-
-    def delete_calibration(self, calibration_id: int) -> bool:
-        """Deletes a calibration proposal or rule; returns whether it existed."""
-        return bool(self._admin(f"/rest/v1/calibrations?id=eq.{int(calibration_id)}", "DELETE"))
-
-    def scoring_rules(self) -> list[dict]:
-        """The teacher's switches over the rules of pronunciation-rules.md: id, active, updated_by, updated_at.
-        A rule with no row is on."""
-        return self._admin("/rest/v1/scoring_rules?select=*") or []
-
-    def set_scoring_rule(self, rule_id: str, active: bool, by: str) -> None:
-        """Switches one rule on or off (an upsert on its id)."""
-        self._admin("/rest/v1/scoring_rules", "POST", {"id": rule_id, "active": bool(active), "updated_by": by,
-                                                       "updated_at": datetime.now(timezone.utc).isoformat()},
-                    prefer="resolution=merge-duplicates,return=minimal")
-
-    def model_settings(self) -> list[dict]:
-        """The scorer settings tuned per model in the panel's "מודלים" tab: model, settings, updated_by, updated_at."""
-        return self._admin("/rest/v1/model_settings?select=*") or []
-
-    def set_model_settings(self, model: str, settings: dict, by: str) -> None:
-        """Replaces one model's settings (an upsert on the model id)."""
-        self._admin("/rest/v1/model_settings", "POST", {"model": model, "settings": settings, "updated_by": by,
-                                                        "updated_at": datetime.now(timezone.utc).isoformat()},
-                    prefer="resolution=merge-duplicates,return=minimal")
-
-    def users(self) -> list[dict]:
-        """Every account that has signed in: id, email, name (as Google gave it; empty for one who signed in by email)."""
-        users: list[dict] = []
-        for page in range(1, 51):
-            batch = self._admin(f"/auth/v1/admin/users?page={page}&per_page={PAGE}").get("users", [])
-            users += [{"id": u["id"], "email": u.get("email") or "",
-                       "name": (u.get("user_metadata") or {}).get("full_name") or ""} for u in batch]
-            if len(batch) < PAGE:
-                break
-        return users
-
     def access_for(self, user_id: str, fresh: bool = False) -> dict | None:
-        """The roles and student entitlements assigned to an account. None also means the migration table is absent."""
+        if not self.secret:
+            return None
         now = time.monotonic()
         with self._lock:
-            hit = self._access.get(user_id)
-        if not fresh and hit and hit[0] > now:
-            return hit[1]
+            cached = self._access.get(user_id)
+        if cached and cached[0] > now and not fresh:
+            return cached[1]
         try:
-            rows = self._admin("/rest/v1/user_access?" + urllib.parse.urlencode({
-                "user_id": f"eq.{user_id}", "select": "user_id,email,roles,entitlements,subject,updated_at"}))
+            rows = self._admin("/rest/v1/user_access?" + urllib.parse.urlencode(
+                {"user_id": f"eq.{user_id}", "select": "user_id,email,roles,updated_at"}))
             value = rows[0] if rows else None
-        except AuthUnavailable as e:
-            if "subject" in str(e).lower():
-                rows = self._admin("/rest/v1/user_access?" + urllib.parse.urlencode({
-                    "user_id": f"eq.{user_id}", "select": "user_id,email,roles,entitlements,updated_at"}))
-                value = ({**rows[0], "subject": ""} if rows else None)
-            elif "answered 404" not in str(e):
+        except AuthUnavailable as exc:
+            if "answered 404" not in str(exc):
                 raise
-            else:
-                value = None
+            value = None
         with self._lock:
             self._access[user_id] = (now + CLASSES_TTL, value)
         return value
 
-    def access_rows(self) -> list[dict] | None:
-        """All explicit access assignments, or None until the user_access table is installed."""
-        try:
-            return self._admin("/rest/v1/user_access?select=user_id,email,roles,entitlements,subject,updated_at") or []
-        except AuthUnavailable as e:
-            if "subject" in str(e).lower():
-                return [{**r, "subject": ""} for r in
-                        (self._admin("/rest/v1/user_access?select=user_id,email,roles,entitlements,updated_at") or [])]
-            if "answered 404" in str(e):
-                return None
-            raise
-
-    def set_access(self, target: dict, roles: list[str], entitlements: list[str], actor: dict) -> None:
-        """Upsert an assignment and append a best-effort audit record."""
-        old = self.access_for(target["id"])
-        row = {"user_id": target["id"], "email": target["email"].lower(), "roles": roles,
-               "entitlements": entitlements, "updated_at": datetime.now(timezone.utc).isoformat(),
-               "updated_by": actor["id"]}
-        self._admin("/rest/v1/user_access?on_conflict=user_id", "POST", row,
-                    prefer="resolution=merge-duplicates,return=minimal")
-        with self._lock:
-            self._access.pop(target["id"], None)
-        try:
-            self._admin("/rest/v1/access_audit", "POST",
-                        {"target_user_id": target["id"], "changed_by": actor["id"],
-                         "old_access": old or {}, "new_access": row}, prefer="return=minimal")
-        except AuthUnavailable as e:
-            log.warning("access changed but audit row was not stored: %s", e)
-        self.log_event("permission", actor, target["email"], {"roles": roles, "entitlements": entitlements})
-
-    def set_admin_subject(self, target: dict, subject: str, actor: dict) -> None:
-        """Set an admin's subject without changing their access assignment."""
-        old = self.access_for(target["id"]) or {}
-        row = {"user_id": target["id"], "email": target["email"].lower(),
-               "roles": old.get("roles") or ["student", "flagger"], "entitlements": old.get("entitlements") or [],
-               "subject": subject, "updated_at": datetime.now(timezone.utc).isoformat(),
-               "updated_by": actor["id"]}
-        self._admin("/rest/v1/user_access?on_conflict=user_id", "POST", row,
-                    prefer="resolution=merge-duplicates,return=minimal")
-        with self._lock:
-            self._access.pop(target["id"], None)
-        self.log_event("permission", actor, target["email"], {"admin_subject": subject})
-
-    def secret_rows(self) -> list[dict] | None:
-        """The API keys set in the panel, encrypted (see keystore.py), or None until the table `app_secrets` exists."""
-        try:
-            return self._admin("/rest/v1/app_secrets?select=name,ciphertext,last4,updated_by,updated_at") or []
-        except AuthUnavailable as e:
-            if "answered 404" in str(e):
-                return None
-            raise
-
-    def save_secret(self, row: dict) -> None:
-        self._admin("/rest/v1/app_secrets?on_conflict=name", "POST",
-                    {**row, "updated_at": datetime.now(timezone.utc).isoformat()},
-                    prefer="resolution=merge-duplicates,return=minimal")
-
-    def delete_secret(self, name: str) -> None:
-        self._admin("/rest/v1/app_secrets?" + urllib.parse.urlencode({"name": f"eq.{name}"}), "DELETE",
-                    prefer="return=minimal")
-
-    def all_attempts(self, limit: int = MAX_CLASS_ATTEMPTS) -> list[dict]:
-        """Every student's attempts, as `attempts` gives one student's, each with its user_id. "Different sentence"
-        rows remain marked as unrelated for diagnostics, but count toward progress like every non-empty recording."""
-        limit = max(1, min(int(limit), MAX_CLASS_ATTEMPTS))
-        rows: list[dict] = []
-        while len(rows) < limit:
-            page = min(PAGE, limit - len(rows))
-            query = urllib.parse.urlencode({"select": "user_id,cat,phrase,score,unrelated,created_at",
-                                            "order": "id.desc", "limit": page, "offset": len(rows)})
-            batch = self._admin(f"/rest/v1/attempts?{query}")
-            rows += batch
-            if len(batch) < page:
-                break
-        return rows
-
-    def scoped_attempts(self, user_ids: set[str], since: datetime, until: datetime,
-                        limit: int = MAX_DIFFICULTY_ATTEMPTS, *,
-                        include_diagnostics: bool = False) -> tuple[list[dict], bool] | tuple[list[dict], bool, bool]:
-        """Bounded attempt metadata for authorized users and ``since <= created_at < until``.
-
-        The caller gets at most ``limit`` rows plus a truncation signal. Audio, diagnostics,
-        answers, and attempts from other users are never requested.
-        """
-        ids = sorted({str(user_id) for user_id in user_ids if str(user_id)})
-        if not ids:
-            return ([], False, True) if include_diagnostics else ([], False)
-        limit = max(1, min(int(limit), MAX_DIFFICULTY_ATTEMPTS))
-        wanted, rows = limit + 1, []
-        while len(rows) < wanted:
-            page = min(PAGE, wanted - len(rows))
-            fields = "id,user_id,cat,phrase,score,unrelated,created_at"
-            if include_diagnostics:
-                fields += ",issues,model,version"
-            query = urllib.parse.urlencode([
-                ("select", fields),
-                ("user_id", f"in.({','.join(ids)})"),
-                ("created_at", f"gte.{since.astimezone(timezone.utc).isoformat()}"),
-                ("created_at", f"lt.{until.astimezone(timezone.utc).isoformat()}"),
-                ("order", "created_at.asc,id.asc"), ("limit", page), ("offset", len(rows)),
-            ])
-            try:
-                batch = self._admin(f"/rest/v1/attempts?{query}") or []
-            except AuthUnavailable as exc:
-                if include_diagnostics and any(name in str(exc) for name in ("issues", "model", "version")):
-                    return [], False, False
-                raise
-            rows += batch
-            if len(batch) < page:
-                break
-        result = (rows[:limit], len(rows) > limit)
-        return (*result, True) if include_diagnostics else result
-
-    def activity(self, hours: int = 24, bucket_minutes: int = 15) -> dict:
-        """Aggregated attempt counts for monitoring, without returning student identities.
-
-        ``activity_summary`` supplies a distinct-student count for the whole window.  Keep the buckets usable with
-        older Supabase installations until that small migration is applied.
-        """
-        buckets = self._admin("/rest/v1/rpc/activity_buckets", "POST",
-                              {"p_hours": hours, "p_bucket_minutes": bucket_minutes})
-        summary = None
-        try:
-            rows = self._admin("/rest/v1/rpc/activity_summary", "POST", {"p_hours": hours}) or []
-            summary = rows[0] if rows else None
-        except AuthUnavailable as e:
-            if "answered 404" not in str(e):
-                raise
-        return {"buckets": buckets, "summary": summary}
-
-    def scoped_activity(self, user_ids: set[str], since: datetime, bucket_minutes: int = 15) -> dict:
-        """Aggregated monitoring data for one admin's students, calculated in Postgres without downloading attempts."""
-        if not user_ids:
-            return {"buckets": [], "summary": {"attempts": 0, "active_students": 0,
-                                                 "returning_students": 0, "active_days": 0}}
-        body = {"p_user_ids": sorted(user_ids), "p_since": since.isoformat()}
-        try:
-            buckets = self._admin("/rest/v1/rpc/activity_buckets_scoped", "POST",
-                                  {**body, "p_bucket_minutes": bucket_minutes})
-            rows = self._admin("/rest/v1/rpc/activity_summary_scoped", "POST", body) or []
-            return {"buckets": buckets or [], "summary": rows[0] if rows else None}
-        except AuthUnavailable as e:
-            if "answered 404" not in str(e):
-                raise
-            log.warning("scoped activity RPCs are missing; using the paged timestamp fallback")
-            return self._scoped_activity_fallback(user_ids, since, bucket_minutes)
-
-    def _scoped_activity_fallback(self, user_ids: set[str], since: datetime, bucket_minutes: int) -> dict:
-        """Accurate compatibility path until the scoped aggregate RPC migration is installed."""
-        rows: list[dict] = []
-        for offset in range(0, MAX_CLASS_ATTEMPTS, PAGE):
-            query = urllib.parse.urlencode({"select": "user_id,created_at", "user_id": f"in.({','.join(sorted(user_ids))})",
-                                            "created_at": f"gte.{since.isoformat()}", "order": "created_at.desc",
-                                            "limit": PAGE, "offset": offset})
-            batch = self._admin(f"/rest/v1/attempts?{query}") or []
-            rows += batch
-            if len(batch) < PAGE:
-                break
-        seconds, buckets, per_user = max(1, min(bucket_minutes, 60)) * 60, {}, {}
-        local = ZoneInfo("Asia/Jerusalem")
-        for row in rows:
-            stamp = datetime.strptime(row["created_at"][:19], "%Y-%m-%dT%H:%M:%S").replace(tzinfo=timezone.utc)
-            slot = int(stamp.timestamp()) // seconds * seconds
-            item = buckets.setdefault(slot, {"users": set(), "attempts": 0})
-            item["attempts"] += 1; item["users"].add(row["user_id"])
-            per_user.setdefault(row["user_id"], set()).add(stamp.astimezone(local).date())
-        return {"buckets": [{"bucket": datetime.fromtimestamp(slot, timezone.utc).isoformat(),
-                              "attempts": item["attempts"], "active_students": len(item["users"])}
-                             for slot, item in sorted(buckets.items())],
-                "summary": {"attempts": len(rows), "active_students": len(per_user),
-                            "returning_students": sum(len(days) >= 2 for days in per_user.values()),
-                            "active_days": len({day for days in per_user.values() for day in days})}}
-
-    def log_event(self, kind: str, user: dict | None, label: str = "", details: dict | None = None) -> None:
-        """Best-effort append to the management activity feed; a missing audit table never blocks the action."""
-        try:
-            self._admin("/rest/v1/system_events", "POST", {
-                "kind": kind, "actor_id": user.get("id") if user else None,
-                "actor_email": (user or {}).get("email", ""), "label": label[:200], "details": details or {},
-            }, prefer="return=minimal")
-        except AuthUnavailable as e:
-            log.warning("system activity event not stored: %s", e)
-
-    def recent_events(self, limit: int = 60) -> list[dict] | None:
-        """Newest audit events, or None when the optional table has not been installed yet."""
-        query = urllib.parse.urlencode({"select": "kind,actor_email,label,details,created_at",
-                                        "order": "created_at.desc", "limit": max(1, min(limit, 200))})
-        try:
-            return self._admin(f"/rest/v1/system_events?{query}") or []
-        except AuthUnavailable as e:
-            if "answered 404" in str(e):
-                return None
-            raise
-
-    def save_tutor_chat(self, row: dict) -> None:
-        """Keeps a conversation with the tutor (see tutor.py), in place of what was kept of it before. A failure is
-        logged, never raised: the conversation goes on without it."""
-        try:
-            self._admin("/rest/v1/tutor_chats?on_conflict=id", "POST", row,
-                        prefer="resolution=merge-duplicates,return=minimal")
-        except AuthUnavailable as e:
-            log.warning("a tutor conversation not kept%s: %s",
-                        " (the table `tutor_chats` is missing, see tutor.CREATE_TUTOR_CHATS)" if "answered 404" in str(e) else "", e)
-
-    def tutor_chats_since(self, user_id: str, since: str) -> int:
-        """How many conversations with the tutor the student started since this ISO time. 0 when they cannot be read."""
-        query = urllib.parse.urlencode({"select": "id", "user_id": f"eq.{user_id}", "created_at": f"gte.{since}"})
-        try:
-            return len(self._admin(f"/rest/v1/tutor_chats?{query}") or [])
-        except AuthUnavailable as e:
-            log.warning("tutor conversations not counted: %s", e)
-            return 0
-
-    def all_attempt_issues(self) -> list[dict] | None:
-        """Compact phoneme issues from recent attempts. None means the diagnostic columns have not been migrated.
-
-        Monitoring only needs a useful recent sample; bounding this query keeps opening the panel independent of the
-        full, ever-growing attempt history. Rows are requested newest first.
-        """
-        rows: list[dict] = []
-        while len(rows) < MAX_MONITOR_ATTEMPTS:
-            limit = min(PAGE, MAX_MONITOR_ATTEMPTS - len(rows))
-            query = urllib.parse.urlencode({"select": "user_id,phrase,score,issues,model,version",
-                                            "unrelated": "is.false", "order": "id.desc",
-                                            "limit": limit, "offset": len(rows)})
-            try:
-                batch = self._admin(f"/rest/v1/attempts?{query}")
-            except AuthUnavailable as e:
-                if any(name in str(e) for name in ("issues", "model", "version")):
-                    return None
-                raise
-            rows += batch
-            if len(batch) < limit:
-                break
-        return rows
-
 
 def load_auth() -> SupabaseAuth | None:
     url = os.environ.get("SUPABASE_URL", "").strip()
     key = os.environ.get("SUPABASE_PUBLISHABLE_KEY", "").strip()
     if not url or not key:
-        missing = [n for n, v in (("SUPABASE_URL", url), ("SUPABASE_PUBLISHABLE_KEY", key)) if not v]
-        seen = sorted(k for k in os.environ if "SUPA" in k.upper())   # names only: shows a misspelt variable
-        log.info("no sign-in, the service is open: %s missing or empty (similar names in the environment: %s)",
-                 " and ".join(missing), seen or "none")
+        log.info("sign-in is disabled; the math path is public")
         return None
     emails = lambda name: frozenset(re.split(r"[\s,;]+", os.environ.get(name, "").strip().lower())) - {""}
-    teachers, tutors, developers = emails("TEACHER_EMAILS"), emails("TUTORS_EMAIL"), emails("DEVELOPER_EMAILS")
-    secret = os.environ.get("SUPABASE_SECRET_KEY", "").strip()
-    log.info("sign-in on: %s", "the students of the classes" if secret else "any account (no SUPABASE_SECRET_KEY)")
-    if os.environ.get("ALLOWED_EMAILS", "").strip():
-        log.warning("ALLOWED_EMAILS is no longer read: the teacher lists the students in the panel's classes")
-    if teachers and not secret:
-        log.warning("TEACHER_EMAILS is set without SUPABASE_SECRET_KEY: the management panel has no data to show")
-    if tutors and not secret:
-        log.warning("TUTORS_EMAIL is set without SUPABASE_SECRET_KEY: a flag cannot be saved")
-    audio_store = None
-    if bucket := os.environ.get("AUDIO_BUCKET", "").strip():
-        audio_store = HFAudioStore(bucket, os.environ.get("AUDIO_BUCKET_PREFIX", "ihki-audio"),
-                                   os.environ.get("HF_TOKEN", "").strip() or None)
-        log.info("voice reports use Hugging Face bucket %s", bucket)
-    cutoff = os.environ.get("AUDIO_MIGRATE_BEFORE", DEFAULT_AUDIO_MIGRATION_CUTOFF).strip()
-    return SupabaseAuth(url, key, teachers, secret, tutors, developers, audio_store, cutoff)
+    return SupabaseAuth(url, key, emails("TEACHER_EMAILS"), os.environ.get("SUPABASE_SECRET_KEY", "").strip(),
+                        emails("DEVELOPER_EMAILS"))

app/class_management.py

@@ -1,208 +0,0 @@
-"""Shared, scope-aware class and roster operations for browser and MCP callers."""
-from __future__ import annotations
-
-import hashlib
-import json
-import re
-from typing import Any
-
-from .access import has_permission
-from .auth import AuthUnavailable, ClassConflict, SupabaseAuth
-
-
-MAX_CLASS_NAME = 80
-MAX_NICKNAME = 40
-EMAIL = re.compile(r"[^@\s,;<>]+@[^@\s,;<>]+\.[^@\s,;<>]+")
-OPERATIONS = frozenset({"create_class", "rename_class", "add_student", "remove_student"})
-PRESERVED = ("name", "emails", "nicknames", "lessons", "homeworks", "dailies", "subject", "teachers")
-
-
-class ClassManagementError(ValueError):
-    """Safe error suitable for management API and MCP results."""
-
-
-class ClassStorageUnavailable(ClassManagementError):
-    pass
-
-
-def normalize_class_name(value: object) -> str:
-    name = " ".join(str(value or "").split())
-    if not name or len(name) > MAX_CLASS_NAME:
-        raise ClassManagementError("לכיתה צריך שם (עד 80 תווים)")
-    return name
-
-
-def parse_roster(text: str) -> tuple[list[str], dict[str, str]]:
-    """Parse the management UI's line-oriented ``email [nickname]`` format."""
-    emails, nicknames = set(), {}
-    for line in re.split(r"[\r\n]+", text):
-        found = EMAIL.findall(line)
-        rest = re.sub(r"\s+", " ", EMAIL.sub(" ", line)).strip(" ,;:-–<>()\t")
-        if (not found and rest) or (len(found) > 1 and rest.strip(" ,;")):
-            raise ValueError(line.strip())
-        for email in found:
-            emails.add(email.lower())
-        if len(found) == 1 and rest:
-            nicknames[found[0].lower()] = rest[:MAX_NICKNAME]
-    return sorted(emails), nicknames
-
-
-def normalize_student(email: object, nickname: object = "") -> tuple[str, str]:
-    email = str(email or "").strip().lower()
-    if not EMAIL.fullmatch(email):
-        raise ClassManagementError("כתובת המייל של התלמיד/ה אינה תקינה")
-    nickname = " ".join(str(nickname or "").split())[:MAX_NICKNAME]
-    return email, nickname
-
-
-def visible_classes(auth: SupabaseAuth, actor: dict | None, *, fresh: bool = False) -> list[dict]:
-    try:
-        rows = auth.classes(fresh=fresh)
-    except AuthUnavailable as exc:
-        raise ClassStorageUnavailable(f"כיתות אינן זמינות: {exc}") from exc
-    if not actor or "developer" in actor.get("roles", ()) or not hasattr(auth, "access_for"):
-        return rows
-    subject = str(actor.get("subject") or "").strip()
-    return [row for row in rows if subject and str(row.get("subject") or "").strip() == subject]
-
-
-def public_classes(auth: SupabaseAuth, actor: dict) -> list[dict]:
-    return [{"id": row["id"], "name": row["name"], "subject": str(row.get("subject") or ""),
-             "students": [{"email": email, **({"nickname": row.get("nicknames", {}).get(email)}
-                                                    if row.get("nicknames", {}).get(email) else {})}
-                           for email in row.get("emails", [])]}
-            for row in visible_classes(auth, actor, fresh=True)]
-
-
-def fingerprint(row: dict) -> str:
-    content = {key: row.get(key, [] if key in {"emails", "lessons", "homeworks", "dailies", "teachers"} else
-                                  {} if key == "nicknames" else "") for key in PRESERVED}
-    return hashlib.sha256(json.dumps(content, ensure_ascii=False, sort_keys=True,
-                                     separators=(",", ":")).encode()).hexdigest()
-
-
-def _find(auth: SupabaseAuth, actor: dict, class_id: object) -> dict:
-    if not isinstance(class_id, int) or isinstance(class_id, bool) or class_id <= 0:
-        raise ClassManagementError("מזהה הכיתה אינו תקין")
-    row = next((item for item in visible_classes(auth, actor, fresh=True) if item.get("id") == class_id), None)
-    if row is None:
-        raise ClassManagementError("הכיתה לא נמצאה")
-    return row
-
-
-def _unique(rows: list[dict], name: str, except_id: int | None = None) -> None:
-    key = name.casefold()
-    if any(row.get("id") != except_id and " ".join(str(row.get("name") or "").split()).casefold() == key
-           for row in rows):
-        raise ClassManagementError("כבר יש כיתה בשם הזה")
-
-
-def prepare(auth: SupabaseAuth, actor: dict, operation: str, *, class_id: int | None = None,
-            name: str = "", subject: str = "", email: str = "", nickname: str = "",
-            students: list[dict[str, str]] | None = None,
-            initial_lessons: dict[str, str]) -> dict[str, Any]:
-    if operation not in OPERATIONS:
-        raise ClassManagementError("פעולת הכיתה אינה מותרת")
-    if not has_permission(actor, "management.access"):
-        raise ClassManagementError("אין הרשאת ניהול")
-    if operation == "create_class":
-        clean_name = normalize_class_name(name)
-        own_subject = str(actor.get("subject") or "").strip()
-        clean_subject = own_subject if "developer" not in actor.get("roles", ()) else " ".join(subject.split())
-        if clean_subject not in initial_lessons:
-            raise ClassManagementError("יש לבחור מקצוע נתמך לכיתה")
-        _unique(visible_classes(auth, actor, fresh=True), clean_name)
-        emails, nicknames = [], {}
-        for student in students or []:
-            if not isinstance(student, dict):
-                raise ClassManagementError("רשימת התלמידים אינה תקינה")
-            student_email, student_nickname = normalize_student(student.get("email"), student.get("nickname"))
-            if student_email in emails:
-                raise ClassManagementError("אותו תלמיד מופיע פעמיים")
-            emails.append(student_email)
-            if student_nickname:
-                nicknames[student_email] = student_nickname
-        return {"operation": operation, "name": clean_name, "subject": clean_subject,
-                "emails": sorted(emails), "nicknames": nicknames,
-                "lesson": initial_lessons[clean_subject]}
-
-    row = _find(auth, actor, class_id)
-    plan: dict[str, Any] = {"operation": operation, "class_id": row["id"], "class_name": row["name"],
-                            "state": fingerprint(row)}
-    if operation == "rename_class":
-        clean_name = normalize_class_name(name)
-        _unique(visible_classes(auth, actor, fresh=True), clean_name, int(row["id"]))
-        if clean_name == row["name"]:
-            raise ClassManagementError("זה כבר שם הכיתה")
-        plan["name"] = clean_name
-    else:
-        clean_email, clean_nickname = normalize_student(email, nickname)
-        enrolled = clean_email in row.get("emails", [])
-        if operation == "add_student" and enrolled:
-            raise ClassManagementError("התלמיד/ה כבר בכיתה")
-        if operation == "remove_student" and not enrolled:
-            raise ClassManagementError("התלמיד/ה אינו/ה בכיתה")
-        if operation == "remove_student" and clean_email in (row.get("teachers") or []):
-            raise ClassManagementError("אי אפשר להסיר מורה באמצעות פעולת תלמידים")
-        plan.update(email=clean_email, nickname=clean_nickname)
-    return plan
-
-
-def _save(auth: SupabaseAuth, row: dict) -> None:
-    args = (int(row["id"]), row["name"], list(row.get("emails") or []), dict(row.get("nicknames") or {}),
-            list(row.get("lessons") or []), list(row.get("homeworks") or []), list(row.get("dailies") or []),
-            str(row.get("subject") or ""))
-    try:
-        auth.save_class(*args, teachers=list(row.get("teachers") or []))
-    except TypeError:
-        auth.save_class(*args)
-
-
-def apply(auth: SupabaseAuth, actor: dict, plan: dict, *, initial_lessons: dict[str, str]) -> dict[str, Any]:
-    operation = str(plan.get("operation") or "")
-    if not has_permission(actor, "management.access") or operation not in OPERATIONS:
-        raise ClassManagementError("אין הרשאת ניהול")
-    try:
-        if operation == "create_class":
-            name, subject = normalize_class_name(plan.get("name")), str(plan.get("subject") or "")
-            own_subject = str(actor.get("subject") or "").strip()
-            if subject not in initial_lessons or ("developer" not in actor.get("roles", ()) and subject != own_subject):
-                raise ClassManagementError("אין הרשאה למקצוע של הכיתה")
-            _unique(visible_classes(auth, actor, fresh=True), name)
-            auth.save_class(None, name, list(plan.get("emails") or []), dict(plan.get("nicknames") or {}),
-                            [initial_lessons[subject]], [], None, subject)
-            created = next((row for row in visible_classes(auth, actor, fresh=True)
-                            if " ".join(row.get("name", "").split()).casefold() == name.casefold()), None)
-            return {"operation": operation, "class_id": created.get("id") if created else None,
-                    "class_name": name, "subject": subject}
-
-        row = _find(auth, actor, plan.get("class_id"))
-        if fingerprint(row) != plan.get("state"):
-            raise ClassManagementError("הכיתה השתנתה מאז ההכנה. הכינו את הפעולה מחדש")
-        if operation == "rename_class":
-            name = normalize_class_name(plan.get("name"))
-            _unique(visible_classes(auth, actor, fresh=True), name, int(row["id"]))
-            row = {**row, "name": name}
-        elif operation == "add_student":
-            email, nickname = normalize_student(plan.get("email"), plan.get("nickname"))
-            if email in row.get("emails", []):
-                raise ClassManagementError("התלמיד/ה כבר בכיתה")
-            emails, nicknames = sorted([*row.get("emails", []), email]), dict(row.get("nicknames") or {})
-            if nickname:
-                nicknames[email] = nickname
-            row = {**row, "emails": emails, "nicknames": nicknames}
-        else:
-            email, _ = normalize_student(plan.get("email"))
-            if email not in row.get("emails", []):
-                raise ClassManagementError("התלמיד/ה אינו/ה בכיתה")
-            if email in (row.get("teachers") or []):
-                raise ClassManagementError("אי אפשר להסיר מורה באמצעות פעולת תלמידים")
-            row = {**row, "emails": [item for item in row.get("emails", []) if item != email],
-                   "nicknames": {key: value for key, value in (row.get("nicknames") or {}).items() if key != email}}
-        _save(auth, row)
-        return {"operation": operation, "class_id": row["id"], "class_name": row["name"],
-                **({"email": plan["email"]} if operation in {"add_student", "remove_student"} else {})}
-    except (ClassManagementError, ClassConflict):
-        raise
-    except AuthUnavailable as exc:
-        raise ClassStorageUnavailable(f"לא ניתן לשמור את הכיתה: {exc}") from exc

app/conjugation.py

@@ -1,215 +0,0 @@
-"""Stage A's verbs (שלב א') in the past and the future, every pronoun, for the "איתן" levels of פועל יוצא.
-
-The future's prefixes are the Hebrew ones, אותיות איתן: ا/א for "I", ت/ת for "you" and "she", ي/י for "he" and
-"they", ن/נ for "we"; "you" (f.) adds ـي/ـי and the plurals ـو/ـו, as in Hebrew. Each form is split into
-prefix, body and ending so the page can colour the parts, beside the Hebrew form split the same way.
-
-Arabic forms come from LEX, the app's source of truth. A future form that LEX lacks comes from future_draft.py and
-marks its verb a draft: only teachers see draft verbs.
-"""
-from __future__ import annotations
-
-from .future_draft import FUTURE_DRAFT
-from .grammar import PRONOUNS
-from .workbook import LEX, VERBS_1, VERBS_3, VERBS_4, VERBS_5, VERBS_6, VERBS_8, VERBS_9, VERBS_10, _plain
-
-STAGE_A = [("1", VERBS_1), ("3", VERBS_3), ("4", VERBS_4), ("5", VERBS_5), ("6", VERBS_6), ("8", VERBS_8),
-           ("9", VERBS_9), ("10", VERBS_10)]
-
-# The Hebrew future, unpointed: the "I" form, the body after the prefix, and the body before ـי / ـו (קנה -> תקני).
-HE_FUTURE = {
-    "يفتح": ("אפתח", "פתח", "פתח"), "ياكل": ("אוכל", "אכל", "אכל"), "يسأل": ("אשאל", "שאל", "שאל"),
-    "يقعد": ("אשב", "שב", "שב"), "يدخل": ("איכנס", "יכנס", "יכנס"), "يسبح": ("אשחה", "שחה", "שח"),
-    "يطبخ": ("אבשל", "בשל", "בשל"), "ينقل": ("אעבור", "עבור", "עבר"), "يجي": ("אבוא", "בוא", "בוא"),
-    "يحكي": ("אדבר", "דבר", "דבר"), "يعطي": ("אתן", "יתן", "יתנ"), "يشتري": ("אקנה", "קנה", "קנ"),
-    "يروح": ("אלך", "לך", "לכ"), "يقول": ("אומר", "אמר", "אמר"), "يزور": ("אבקר", "בקר", "בקר"),
-    "يكون": ("אהיה", "היה", "הי"), "يبوس": ("אנשק", "נשק", "נשק"), "يسوق": ("אנהג", "נהג", "נהג"),
-    "يشوف": ("אראה", "ראה", "רא"), "يفوت": ("איכנס", "יכנס", "יכנס"), "ياخد": ("אקח", "יקח", "יקח"),
-    "يشرب": ("אשתה", "שתה", "שת"), "يطلع": ("אצא", "צא", "צא"), "يسمع": ("אשמע", "שמע", "שמע"),
-    "يفهم": ("אבין", "בין", "בינ"), "يرجع": ("אחזור", "חזור", "חזר"), "يشكر": ("אודה", "ודה", "וד"),
-    "يتغدّى": ("אוכל", "אכל", "אכל"), "ينزل": ("ארד", "רד", "רד"), "يوصل": ("אגיע", "גיע", "גיע"),
-    "يضحك": ("אצחק", "צחק", "צחק"), "يلبس": ("אלבש", "לבש", "לבש"), "يلعب": ("אשחק", "שחק", "שחק"),
-}
-
-FUTURE_PREFIX = "اتتيتنتي"                     # in PRONOUNS order
-FUTURE_SUFFIX = ["", "", "ي", "", "", "", "و", "و"]
-PAST_SUFFIX = ["ت", "ت", "تي", "", "ت", "نا", "تو", "و"]
-HE_PREFIX = "אתתיתנתי"
-HE_FUTURE_SUFFIX = ["", "", "י", "", "", "", "ו", "ו"]
-HE_PAST_SUFFIX = [("תי",), ("ת",), ("ת",), ("",), ("ה",), ("נו",), ("תם", "תן"), ("ו",)]
-# the tiles the student builds with: (Arabic, as the page shows it in Hebrew transliteration). A future prefix tile
-# shows the verb's own vowel (תֻ, תִ, תְ), filled in per question.
-PREFIX_TILES = [("ا", "א"), ("ت", "ת"), ("ي", "י"), ("ن", "נ")]
-FUTURE_SUFFIX_TILES = [("", ""), ("ي", "\u05B4י"), ("و", "וּ")]
-PAST_SUFFIX_TILES = [("", ""), ("ت", "ת"), ("تي", "תִי"), ("نا", "נַא"), ("تو", "תוּ"), ("و", "וּ")]
-# a past form's ending in transliteration, per pronoun (فتّي is written פֻתִّי)
-PAST_SUFFIX_TR = [("ת",), ("ת",), ("תִי", "תִّי"), ("",), ("ת",), ("נַא", "ّא"), ("תוּ", "תّוּ"), ("וּ",)]
-MARKS = set(chr(c) for c in range(0x0591, 0x05C8)) | {"'", "\u0651"}
-FINALS = dict(zip("כמנפצ", "ךםןףץ"))
-# Arabic forms the rule (prefix + the "he" form's body + ending) does not give
-IRREGULAR = {"يجي": ["اجي", "تيجي", "تيجي", "يجي", "تيجي", "نيجي", "تيجو", "يجو"]}
-ANA_IRREGULAR = {"ياكل": "آكل", "ياخد": "آخد"}
-SHADDA = "ّ"
-
-
-def plain(ar: str) -> str:
-    """The form as the tiles spell it: without shadda (كنّا, فتّي)."""
-    return ar.replace(SHADDA, "")
-
-
-def compose(prefix: str, body: str, suffix: str) -> str:
-    """Prefix + body + ending, as the page builds it: ا + اكل is آكل, and a body ending in ي/ى gives way to the
-    ending (تحكي + و -> تحكو, تتغدّى + ي -> تتغدّي)."""
-    word = prefix + body
-    if word.startswith("اا"):
-        word = "آ" + word[2:]
-    if suffix and body and body[-1] in "يى":
-        return word[:-1] + suffix
-    return word + suffix
-
-
-def _future_arabic(he: str) -> list[str]:
-    if he in IRREGULAR:
-        return IRREGULAR[he]
-    body = he[1:]
-    forms = [compose(pre, body, suf) for pre, suf in zip(FUTURE_PREFIX, FUTURE_SUFFIX)]
-    forms[0] = ANA_IRREGULAR.get(he, forms[0])
-    return forms
-
-
-def _lookup(ar: str, pronoun: int) -> tuple[str, list[str], bool] | None:
-    """LEX's entry for a future form (checked), else the draft's; "I" takes the entry read אַ (اسمع#i, not اسمع)."""
-    keys = [k for k in LEX if k.partition("#")[0] == ar and not k.endswith("#imp")]
-    if pronoun == 0:
-        keys.sort(key=lambda k: (not LEX[k][0].startswith(("אַ", "אֹ")), "#" in k))
-    else:
-        keys = [k for k in keys if not LEX[k][0].startswith("א")] or keys
-        keys.sort(key=lambda k: "#" in k)
-    if keys:
-        tr, ipas = LEX[keys[0]]
-        return tr, list(ipas), False
-    if ar in FUTURE_DRAFT:
-        tr, ipas = FUTURE_DRAFT[ar]
-        return tr, list(ipas), True
-    return None
-
-
-def _future_body(he: str, target: str, pronoun: int) -> str:
-    """The body the page shows between the slots: the "he" form's, unless that does not build this form (تيجي)."""
-    prefix, suffix = FUTURE_PREFIX[pronoun], FUTURE_SUFFIX[pronoun]
-    rest = ("ا" + target[1:]) if target.startswith("آ") else target[1:]
-    stripped = rest[:-1] if suffix and rest.endswith(suffix) else rest
-    for body in (he[1:], rest, stripped + "ي", stripped):
-        if plain(compose(prefix, body, suffix)) == plain(target):
-            return body
-    raise ValueError(f"no body builds {target}")
-
-
-def ar_parts(ar: str, tense: str, pronoun: int) -> dict[str, str]:
-    """A form split for colouring: {pre, body, suf}."""
-    if tense == "future":
-        suf = FUTURE_SUFFIX[pronoun] if FUTURE_SUFFIX[pronoun] and ar.endswith(FUTURE_SUFFIX[pronoun]) else ""
-        return {"pre": ar[0], "body": ar[1:len(ar) - len(suf)], "suf": suf}
-    suf = PAST_SUFFIX[pronoun]
-    if suf and ar.endswith(SHADDA + suf[-1]) and len(suf) == 2 and ar[:-2].endswith(suf[0]):   # كنّا, فتّي
-        return {"pre": "", "body": ar[:-3], "suf": ar[-3:]}
-    if suf and ar.endswith(suf):
-        return {"pre": "", "body": ar[:-len(suf)], "suf": suf}
-    return {"pre": "", "body": ar, "suf": ""}
-
-
-def lead(tr: str) -> tuple[str, str]:
-    """A transliteration's first letter with its marks (תֻ, גִ'), and the rest."""
-    i = 1
-    while i < len(tr) and tr[i] in MARKS:
-        i += 1
-    return tr[:i], tr[i:]
-
-
-def tr_parts(tr: str, tense: str, pronoun: int) -> dict[str, str]:
-    """A transliteration split for colouring, as ar_parts splits the Arabic: {pre, body, suf}."""
-    if tense == "past":
-        for suf in PAST_SUFFIX_TR[pronoun]:
-            if suf and tr.endswith(suf) and len(tr) > len(suf):
-                return {"pre": "", "body": tr[:-len(suf)], "suf": suf}
-        return {"pre": "", "body": tr, "suf": ""}
-    pre, rest = lead(tr)
-    if FUTURE_SUFFIX[pronoun] == "ي" and rest.endswith("י"):
-        body = rest[:-1]
-        cut = body.rfind("\u05B4")
-        if cut >= len(body) - 3:   # the ending's hiriq, on the last letter (before a geresh: חִ'י)
-            body = body[:cut] + body[cut + 1:]
-        return {"pre": pre, "body": body, "suf": "\u05B4י"}
-    if FUTURE_SUFFIX[pronoun] == "و" and rest.endswith("וּ"):
-        return {"pre": pre, "body": rest[:-2], "suf": "וּ"}
-    return {"pre": pre, "body": rest, "suf": ""}
-
-
-def compose_tr(pre: str, body: str, suf: str) -> str:
-    """The transliteration the tiles spell, as the page shows it while building: a final letter at the end only, and
-    an ending's hiriq before a geresh (חִ'י)."""
-    i = len(body)
-    while i and body[i - 1] in MARKS:
-        i -= 1
-    letter = body[i - 1] if i else ""
-    regular = {v: k for k, v in FINALS.items()}
-    if suf and letter in regular:
-        body = body[:i - 1] + regular[letter] + body[i:]
-    elif not suf and letter in FINALS and i == len(body):   # כּ at the end stays as the course writes it
-        body = body[:i - 1] + FINALS[letter] + body[i:]
-    if suf.startswith("\u05B4") and body.endswith("'"):
-        return pre + body[:-1] + "\u05B4'" + suf[1:]
-    return pre + body + suf
-
-
-def _he_past_parts(he: str, pronoun: int) -> dict[str, str]:
-    for suf in HE_PAST_SUFFIX[pronoun]:
-        if suf and he.endswith(suf):
-            return {"pre": "", "body": he[:-len(suf)], "suf": suf}
-    return {"pre": "", "body": he, "suf": ""}
-
-
-def _he_future_parts(spec: tuple[str, str, str], pronoun: int) -> dict[str, str]:
-    ana, body, before_suffix = spec
-    if pronoun == 0:
-        return {"pre": ana[0], "body": ana[1:], "suf": ""}
-    suf = HE_FUTURE_SUFFIX[pronoun]
-    return {"pre": HE_PREFIX[pronoun], "body": before_suffix if suf else body, "suf": suf}
-
-
-def _verb(lesson: str, item: tuple) -> dict:
-    he_past, keys, he = item[0].split(), item[1].split(), item[2]
-    name = _plain(he_past[3]) + (f" {item[3]}" if len(item) > 3 else "")
-    past = []
-    for p, key in enumerate(keys):
-        tr, ipas = LEX[key]
-        ar = key.partition("#")[0]
-        past.append({"ar": ar, "tr": tr, "ipas": list(ipas), "parts": ar_parts(ar, "past", p),
-                     "tr_parts": tr_parts(tr, "past", p),
-                     "he": _he_past_parts(_plain(he_past[p]), p), "draft": False,
-                     "body": ar_parts(plain(ar), "past", p)["body"]})
-    future = []
-    for p, ar in enumerate(_future_arabic(he)):
-        found = _lookup(ar, p)
-        if not found:
-            raise ValueError(f"{he}: no entry for {ar}")
-        tr, ipas, draft = found
-        future.append({"ar": ar, "tr": tr, "ipas": ipas, "parts": ar_parts(ar, "future", p),
-                       "tr_parts": tr_parts(tr, "future", p),
-                       "he": _he_future_parts(HE_FUTURE[he], p), "draft": draft, "body": _future_body(he, ar, p)})
-    return {"id": he, "lesson": lesson, "name": name, "arabic": f"{keys[3].partition('#')[0]} · {he}",
-            "transliteration": f"{past[3]['tr']} · {future[3]['tr']}",
-            "past": past, "future": future, "draft": any(f["draft"] for f in future)}
-
-
-def _stage_a() -> dict[str, dict]:
-    out = {}
-    for lesson, items in STAGE_A:
-        for item in items:
-            if item[2] not in out:
-                out[item[2]] = _verb(lesson, item)
-    return out
-
-
-STAGE_A_VERBS = _stage_a()
-assert all(len(v["past"]) == len(v["future"]) == len(PRONOUNS) for v in STAGE_A_VERBS.values())

app/future_draft.py

@@ -1,94 +0,0 @@
-"""Draft future forms of stage A's verbs (שלב א'): those that LEX does not have yet.
-
-Made by rule from the forms LEX has (another prefix letter on a known form, or ـي / ـو added), so they are NOT checked.
-The verb game shows a verb whose future is not all in LEX to teachers only, marked טיוטה. Once a teacher has checked
-a form, move it into LEX (workbook.py) and delete it here: the verb then reaches students when all eight are in LEX.
-The review list is docs/future-forms-draft.md.
-"""
-
-FUTURE_DRAFT: dict[str, tuple[str, list[str]]] = {
-    # يفتح
-    "تفتح": ("תִפְתַח", ["t i f t a ħ"]),
-    "تفتحي": ("תִפְתַחִי", ["t i f t a ħ i"]),
-    "نفتح": ("נִפְתַח", ["n i f t a ħ"]),
-    "تفتحو": ("תִפְתַחוּ", ["t i f t a ħ u"]),
-    "يفتحو": ("יִפְתַחוּ", ["j i f t a ħ u"]),
-    # ياكل
-    "ياكلو": ("יֹאכְּלוּ", ["j oː k u l u", "j oː k i l u", "j aː k u l u", "j oː k l u", "j aː k l u"]),
-    # يدخل
-    "تدخلي": ("תֻדְחֹ'לִי", ["t u d x u l i"]),
-    "تدخلو": ("תֻדְחֹ'לוּ", ["t u d x u l u"]),
-    "يدخلو": ("יֻדְחֹ'לוּ", ["j u d x u l u"]),
-    # يسبح
-    "اسبح": ("אַסְבַּח", ["ʔ a s b a ħ"]),
-    "تسبحي": ("תִסְבַּחִי", ["t i s b a ħ i"]),
-    "تسبحو": ("תִסְבַּחוּ", ["t i s b a ħ u"]),
-    "يسبحو": ("יִסְבַּחוּ", ["j i s b a ħ u"]),
-    # يطبخ
-    "تطبخو": ("תֻטְבֹּח'וּ", ["t u tˤ b u x u"]),
-    "يطبخو": ("יֻטְבֹּח'וּ", ["j u tˤ b u x u"]),
-    # ينقل
-    "انقل": ("אַנְקֹל", ["ʔ a n ʔ u l", "ʔ a n q u l"]),
-    "تنقلي": ("תֻנְקֹלִי", ["t u n ʔ u l i", "t u n q u l i"]),
-    "ننقل": ("נֻנְקֹל", ["n u n ʔ u l", "n u n q u l"]),
-    "تنقلو": ("תֻנְקֹלוּ", ["t u n ʔ u l u", "t u n q u l u"]),
-    # يعطي
-    "نعطي": ("נֵעַטִי", ["n a ʕ tˤ i", "n i ʕ tˤ i"]),
-    "تعطو": ("תֵעַטוּ", ["t a ʕ tˤ u", "t i ʕ tˤ u"]),
-    "يعطو": ("יֵעַטוּ", ["j a ʕ tˤ u", "j i ʕ tˤ u"]),
-    # يشتري
-    "تشترو": ("תִשְתְרוּ", ["t i ʃ t r u", "t i ʃ t i r u"]),
-    "يشترو": ("יִשְתְרוּ", ["j i ʃ t r u", "j i ʃ t i r u"]),
-    # يروح
-    "تروحو": ("תְרוּחוּ", ["t r uː ħ u", "t i r uː ħ u"]),
-    # يقول
-    "تقولي": ("תְקוּלִי", ["t ʔ uː l i", "t q uː l i"]),
-    "نقول": ("נְקוּל", ["n ʔ uː l", "n q uː l"]),
-    "تقولو": ("תְקוּלוּ", ["t ʔ uː l u", "t q uː l u"]),
-    "يقولو": ("יִקוּלוּ", ["j ʔ uː l u", "i ʔ uː l u", "j q uː l u", "j i ʔ uː l u"]),
-    # يكون
-    "تكونو": ("תְכּוּנוּ", ["t k uː n u"]),
-    "يكونو": ("יִכּוּנוּ", ["j k uː n u", "i k uː n u", "j i k uː n u"]),
-    # يبوس
-    "تبوسي": ("תְבּוּסִי", ["t b uː s i"]),
-    "نبوس": ("נְבּוּס", ["n b uː s"]),
-    "تبوسو": ("תְבּוּסוּ", ["t b uː s u"]),
-    "يبوسو": ("יִבּוּסוּ", ["j b uː s u", "i b uː s u", "j i b uː s u"]),
-    # يسوق
-    "نسوق": ("נְסוּק", ["n s uː ʔ", "n s uː q"]),
-    "تسوقو": ("תְסוּקוּ", ["t s uː ʔ u", "t s uː q u"]),
-    "يسوقو": ("יִסוּקוּ", ["j s uː ʔ u", "j s uː q u", "i s uː ʔ u", "j i s uː ʔ u"]),
-    # يفوت
-    "تفوتي": ("תְפוּתִי", ["t f uː t i"]),
-    "نفوت": ("נְפוּת", ["n f uː t"]),
-    "تفوتو": ("תְפוּתוּ", ["t f uː t u"]),
-    "يفوتو": ("יִפוּתוּ", ["j f uː t u", "i f uː t u", "j i f uː t u"]),
-    # ياخد
-    "ناخد": ("נֹאחֵ'ד", ["n oː x i d", "n aː x u d"]),
-    "تاخدو": ("תֹאחְ'דוּ", ["t oː x i d u", "t aː x u d u", "t oː x d u", "t aː x d u", "t oː x u d u"]),
-    # يفهم
-    "نفهم": ("נִפְהַם", ["n i f h a m"]),
-    "تفهمو": ("תִפְהַמוּ", ["t i f h a m u"]),
-    # يرجع
-    "نرجع": ("נִרְגַ'ע", ["n i r dʒ a ʕ"]),
-    # يشكر
-    "اشكر": ("אַשְכֹּר", ["ʔ a ʃ k u r"]),
-    "تشكر": ("תֻשְכֹּר", ["t u ʃ k u r"]),
-    "تشكري": ("תֻשְכֹּרִי", ["t u ʃ k u r i"]),
-    "تشكرو": ("תֻשְכֹּרוּ", ["t u ʃ k u r u"]),
-    "يشكرو": ("יֻשְכֹּרוּ", ["j u ʃ k u r u"]),
-    # ينزل
-    "انزل": ("אַנְזֵל", ["ʔ a n z i l", "ʔ a n z a l"]),
-    "تنزلي": ("תִנְזֵלִי", ["t i n z i l i", "t i n z a l i"]),
-    "ننزل": ("נִנְזֵל", ["n i n z i l", "n i n z a l"]),
-    "ينزلو": ("יִנְזְלוּ", ["j i n z i l u", "j i n z a l u", "j i n z l u"]),
-    # يوصل
-    "توصلو": ("תוֹצַלוּ", ["t oː sˤ a l u"]),
-    # يضحك
-    "يضحكو": ("יִדְֿחַכּוּ", ["j i dˤ ħ a k u"]),
-    # يلبس
-    "البس": ("אַלְבַּס", ["ʔ a l b a s"]),
-    "نلبس": ("נִלְבַּס", ["n i l b a s"]),
-    "تلبسو": ("תִלְבַּסוּ", ["t i l b a s u"]),
-    "يلبسو": ("יִלְבַּסוּ", ["j i l b a s u"]),
-}

app/grammar.py

@@ -1,184 +0,0 @@
-"""Day 2 sentences as grammar, so the page can ask for the same sentence negated or with another subject.
-
-A sentence is a subject pronoun, one or two past-tense verbs and fixed words. From each sentence
-pattern this module builds every pronoun x {positive, negative} phrase in the format of phrases.py.
-Only the forms taught in the course are "listed" (shown in the tab); the rest are reached through
-the page's "שלילה" and "הטיית פעלים" buttons.
-
-Negation is ما before the verb (ما اكلت); the -ش suffix is not accepted yet.
-Transliterations follow the course material: אֵל for the article, (ל) for its silent ל, ّ for doubling.
-"""
-from __future__ import annotations
-
-import itertools
-
-# subject pronouns, in the order used by every verb table below
-#            key       Hebrew    course tr   (arabic, ipa) readings, main one first
-PRONOUNS = [
-    # The initial glottal stop is routinely absent in natural Palestinian speech.  Keep both alignments so a weak
-    # breathy onset is not forced against ʔ and reported as h, while the written and displayed form stays identical.
-    ("ana",   "אני",    "אַנַא",    [("انا", "ʔ a n a"), ("انا", "a n a")]),
-    ("inte",  "אתה",    "אִנְתֵ",    [("انت", "ʔ i n t e"), ("انت", "ʔ i n t a")]),
-    ("inti",  "את",     "אִנְתִי",   [("انتي", "ʔ i n t i")]),
-    ("huwwe", "הוא",    "הוּّ",     [("هوّ", "h u w w e"), ("هو", "h uː")]),
-    ("hiyye", "היא",    "הִיֵّ",    [("هيّ", "h i j j e"), ("هي", "h iː")]),
-    ("ihna",  "אנחנו",  "אִחְנַא",   [("احنا", "ʔ i ħ n a")]),
-    ("intu",  "אתם",    "אִנְתוּ",   [("انتو", "ʔ i n t u")]),
-    ("humme", "הם",     "הֹםّ",     [("همّ", "h u m m e"), ("هم", "h o m")]),
-]
-P = [p[0] for p in PRONOUNS]
-
-# past tense, one row per pronoun (PRONOUNS order): Hebrew, course tr, Arabic, IPA readings
-VERBS = {
-    "akal": [
-        ("אכלתי",  "אַכַּלְת",    "اكلت",  ["ʔ a k a l t"]),
-        ("אכלת",   "אַכַּלְת",    "اكلت",  ["ʔ a k a l t"]),
-        ("אכלת",   "אַכַּלְתִי",   "اكلتي", ["ʔ a k a l t i"]),
-        ("אכל",    "אַכַּל",      "اكل",   ["ʔ a k a l"]),
-        ("אכלה",   "אַכְּלַת",    "اكلت",  ["ʔ a k l a t"]),
-        ("אכלנו",  "אַכַּלְנַא",   "اكلنا", ["ʔ a k a l n a"]),
-        ("אכלתם",  "אַכַּלְתוּ",   "اكلتو", ["ʔ a k a l t u"]),
-        ("אכלו",   "אַכְּלוּ",    "اكلو",  ["ʔ a k l u", "ʔ a k a l u"]),
-    ],
-    "qaad": [
-        ("ישבתי",  "קַעַדְת",    "قعدت",  ["ʔ a ʕ a d t", "q a ʕ a d t"]),
-        ("ישבת",   "קַעַדְת",    "قعدت",  ["ʔ a ʕ a d t", "q a ʕ a d t"]),
-        ("ישבת",   "קַעַדְתִי",   "قعدتي", ["ʔ a ʕ a d t i", "q a ʕ a d t i"]),
-        ("ישב",    "קַעַד",      "قعد",   ["ʔ a ʕ a d", "q a ʕ a d"]),
-        ("ישבה",   "קַעְדַת",    "قعدت",  ["ʔ a ʕ d a t", "q a ʕ d a t"]),
-        ("ישבנו",  "קַעַדְנַא",   "قعدنا", ["ʔ a ʕ a d n a", "q a ʕ a d n a"]),
-        ("ישבתם",  "קַעַדְתוּ",   "قعدتو", ["ʔ a ʕ a d t u", "q a ʕ a d t u"]),
-        ("ישבו",   "קַעַדוּ",    "قعدو",  ["ʔ a ʕ a d u", "q a ʕ a d u", "ʔ a ʕ d u", "q a ʕ d u"]),
-    ],
-    "fatah": [
-        ("פתחתי",  "פַתַחְת",    "فتحت",  ["f a t a ħ t"]),
-        ("פתחת",   "פַתַחְת",    "فتحت",  ["f a t a ħ t"]),
-        ("פתחת",   "פַתַחְתִי",   "فتحتي", ["f a t a ħ t i"]),
-        ("פתח",    "פַתַח",      "فتح",   ["f a t a ħ"]),
-        ("פתחה",   "פַתְחַת",    "فتحت",  ["f a t ħ a t"]),
-        ("פתחנו",  "פַתַחְנַא",   "فتحنا", ["f a t a ħ n a"]),
-        ("פתחתם",  "פַתַחְתוּ",   "فتحتو", ["f a t a ħ t u"]),
-        ("פתחו",   "פַתַחוּ",    "فتحو",  ["f a t a ħ u", "f a t ħ u"]),
-    ],
-    "saal": [
-        ("שאלתי",  "סַאַלֵת",    "سألت",  ["s a ʔ a l t", "s a ʔ a l i t"]),
-        ("שאלת",   "סַאַלְת",    "سألت",  ["s a ʔ a l t", "s a ʔ a l i t"]),
-        ("שאלת",   "סַאַלְתִי",   "سألتي", ["s a ʔ a l t i"]),
-        ("שאל",    "סַאַל",      "سأل",   ["s a ʔ a l"]),
-        ("שאלה",   "סַאְלַת",    "سألت",  ["s a ʔ l a t"]),
-        ("שאלנו",  "סַאַלְנַא",   "سألنا", ["s a ʔ a l n a"]),
-        ("שאלתם",  "סַאַלְתוּ",   "سألتو", ["s a ʔ a l t u"]),
-        ("שאלו",   "סַאַלוּ",    "سألو",  ["s a ʔ a l u", "s a ʔ l u"]),
-    ],
-}
-
-# every other word: arabic -> (course tr, IPA readings)
-WORDS = {
-    "بندورة": ("בַּנְדוֹרַה", ["b a n d oː r a"]), "على": ("עַלַא", ["ʕ a l a"]),
-    "الطّاولة": ("אֵ(ל)טַّאוְלֵה", ["i tˤ tˤ aː w l e"]), "في": ("פִי", ["f i"]),
-    "الحارة": ("אֵלְחַארַה", ["i l ħ aː r a"]), "الكرسي": ("אֵלְכֻּרְסִי", ["i l k u r s i"]),
-    "فلافل": ("פַלַאפֵל", ["f a l aː f i l"]), "الشّبّاك": ("אֵ(ל)שֻّבַּّאכּ", ["i ʃ ʃ u b b aː k"]),
-    "الدّكتور": ("אֵ(ל)דַّכְּתוֹר", ["i d d a k t oː r", "i d d u k t oː r"]), "الباب": ("אֵלְבַּאבּ", ["i l b aː b"]),
-    "المعلّم": ("אֵלְמְעַלֵّם", ["i l m ʕ a l l i m"]), "الأكل": ("אֵלְאַכֵּל", ["i l ʔ a k i l", "i l ʔ a k l"]),
-    "مع": ("מַע", ["m a ʕ"]), "اخوها": ("אַחַ'וּהַא", ["ʔ a x uː h a"]),
-    "الصّاحب": ("אֵ(ל)צַّאחֵבּ", ["i sˤ sˤ aː ħ i b"]), "السّيّارة": ("אֵ(ל)סַّיַّארַה", ["i s s a j j aː r a"]),
-    "البيت": ("אֵלְבֵּית", ["i l b eː t"]), "اليوم": ("אֵלְיוֹם", ["i l j oː m"]),
-    "الطّيّارة": ("אֵ(ל)טַّיַّארַה", ["i tˤ tˤ a j j aː r a"]), "الولد": ("אֵלְוַלַד", ["i l w a l a d"]),
-    "سؤال": ("סֻאַאל", ["s u ʔ aː l"]), "للكلب": ("לַלְכַּלְבּ", ["l a l k a l b"]),
-    "الكلب": ("אֵלְכַּלְבּ", ["i l k a l b"]), "احمد": ("אַחְמַד", ["ʔ a ħ m a d"]),
-    "الكبيرة": ("אֵלְכְּבִּירֵה", ["i l k b iː r e"]), "كبير": ("כְּבִּיר", ["k b iː r"]),
-    "ابوي": ("אַבּוּי", ["ʔ a b uː j"]), "من": ("מִן", ["m i n"]),
-}
-NOT = ("ما", "מַא", "m a")        # before a verb
-AND_NOT = ("وما", "וּמַא", "u m a")  # before a second verb
-
-# The course's sentences: subject taught, Hebrew pattern, Arabic pattern.
-# S = subject pronoun, V:verb = conjugated verb, W:verb = "and" + conjugated verb ({S} {V} {W} in the Hebrew).
-SENTENCES = [
-    ("inti",  "{S} {V} עגבנייה ליד השולחן",      "S V:akal بندورة على الطّاولة"),
-    ("inte",  "{S} {V} בשכונה",                   "S V:qaad في الحارة"),
-    ("huwwe", "{S} {V} על הכיסא ו{W} פלאפל",      "S V:qaad على الكرسي W:akal فلافل"),
-    ("hiyye", "{S} {V} את החלון",                 "S V:fatah الشّبّاك"),
-    ("ana",   "{S} {V} את הרופא",                 "S V:saal الدّكتور"),
-    ("ihna",  "{S} {V} את הדלת",                  "S V:fatah الباب"),
-    ("intu",  "{S} {V} ליד השולחן",               "S V:qaad على الطّاولة"),
-    ("humme", "{S} {V} את המורה",                 "S V:saal المعلّم"),
-    ("huwwe", "{S} {V} את האוכל על החלון",        "S V:akal الأكل على الشّبّاك"),
-    ("hiyye", "{S} {V} עם אחיה",                  "S V:qaad مع اخوها"),
-    ("inti",  "{S} {V} את החבר",                  "S V:saal الصّاحب"),
-    ("humme", "{S} {V} את החלון",                 "S V:fatah الشّبّاك"),
-    ("intu",  "{S} {V} במכונית",                  "S V:akal في السّيّارة"),
-    ("ana",   "{S} {V} בבית היום",                "S V:qaad في البيت اليوم"),
-    ("inte",  "{S} {V} את המטוס",                 "S V:fatah الطّيّارة"),
-    ("ihna",  "{S} {V} את הילד שאלה",             "S V:saal الولد سؤال"),
-    ("huwwe", "{S} {V} את הדלת לכלב",             "S V:fatah الباب للكلب"),
-    ("hiyye", "{S} {V} את הדלת ו{W} עם אחמד",     "S V:fatah الباب W:akal مع احمد"),
-    ("inti",  "{S} {V} את השולחן הגדול",          "S V:fatah الطّاولة الكبيرة"),
-    ("humme", "{S} {V} את החבר שאלה גדולה",       "S V:saal الصّاحب سؤال كبير"),
-    ("inte",  "{S} {V} פלאפל ליד השולחן",         "S V:akal فلافل على الطّاولة"),
-    ("intu",  "{S} {V} את הדלת היום",             "S V:fatah الباب اليوم"),
-    ("hiyye", "{S} {V} את הרופא",                 "S V:saal الدّكتور"),
-    ("ana",   "{S} {V} עגבנייה עם אבא שלי",       "S V:akal بندورة مع ابوي"),
-    ("ihna",  "{S} {V} בשכונה",                   "S V:qaad في الحارة"),
-    ("huwwe", "{S} {V} את המורה שאלה",            "S V:saal المعلّم سؤال"),
-    ("inte",  "{S} {V} עם הכלב",                  "S V:qaad مع الكلب"),
-    ("hiyye", "{S} {V} את האוכל על החלון",        "S V:akal الأكل على الشّبّاك"),
-    ("inti",  "{S} {V} את המטוס",                 "S V:fatah الطّيّارة"),
-    ("ihna",  "{S} {V} את החבר ו{W}",             "S V:saal الصّاحب W:qaad"),
-    ("humme", "{S} {V} עגבנייה מהשולחן",          "S V:akal بندورة من الطّاولة"),
-]
-MAX_VARIANTS = 16
-
-
-def _build(he_pattern: str, pattern: str, pron: int, neg: bool) -> dict:
-    """One phrase: lists of alternative (arabic, ipa) per word, then every combination of them."""
-    _, he_pron, tr_pron, pron_alts = PRONOUNS[pron]
-    slots: list[list[tuple[str, str]]] = []  # per word: its (arabic, ipa) readings
-    tr: list[str] = []
-    he = {"S": he_pron}
-    for tok in pattern.split():
-        kind, _, verb = tok.partition(":")
-        if tok == "S":
-            slots.append(pron_alts)
-            tr.append(tr_pron)
-        elif kind in ("V", "W") and verb:
-            he_verb, tr_verb, ar, ipas = VERBS[verb][pron]
-            he[kind] = ("לא " if neg else "") + he_verb
-            if kind == "W" and neg:        # ... وما اكل
-                slots.append([AND_NOT[::2]])
-                tr.append(AND_NOT[1])
-            elif kind == "W":              # ... واكل: the و is part of the word
-                ar, ipas, tr_verb = "و" + ar, ["u " + i for i in ipas], "וּ" + tr_verb
-            elif neg:                      # ما اكل ...
-                slots.append([NOT[::2]])
-                tr.append(NOT[1])
-            slots.append([(ar, i) for i in ipas])
-            tr.append(tr_verb)
-        else:
-            tr_word, ipas = WORDS[tok]
-            slots.append([(tok, i) for i in ipas])
-            tr.append(tr_word)
-    variants = [(" ".join(a for a, _ in combo), " | ".join(i for _, i in combo))
-                for combo in itertools.islice(itertools.product(*slots), MAX_VARIANTS)]
-    return dict(cat="day2", he=he_pattern.format(**he), tr=" ".join(tr), variants=variants)
-
-
-def day2_phrases() -> list[dict]:
-    """Every pattern x pronoun x polarity. `grp`/`pron`/`neg` let the page move between them;
-    `listed` marks the course's own sentences, which are the ones the tab starts from, and
-    `seq` is their 1-based place in SENTENCES: the tab shows them in that order."""
-    groups: dict[tuple[str, str], int] = {}
-    taught: dict[tuple[int, int], int] = {}
-    for seq, (pron, he_pattern, pattern) in enumerate(SENTENCES, 1):
-        g = groups.setdefault((he_pattern, pattern), len(groups))
-        taught.setdefault((g, P.index(pron)), seq)
-    out = []
-    for (he_pattern, pattern), g in groups.items():
-        for pron in range(len(PRONOUNS)):
-            for neg in (False, True):
-                phrase = _build(he_pattern, pattern, pron, neg)
-                phrase.update(grp=g, pron=pron, neg=neg, listed=(g, pron) in taught and not neg)
-                if phrase["listed"]:
-                    phrase["seq"] = taught[g, pron]
-                out.append(phrase)
-    return out

app/grok_mcp.py

@@ -1,490 +0,0 @@
-"""Restricted MCP connector through which Grok can manage library videos."""
-from __future__ import annotations
-
-import logging
-import os
-import secrets
-import threading
-import time
-from collections import deque
-from dataclasses import dataclass
-from typing import Any, Callable, Literal
-
-from mcp.server.auth.middleware.auth_context import get_access_token
-from mcp.server.auth.provider import AccessToken
-from mcp.server.auth.settings import AuthSettings
-from mcp.server.mcpserver import MCPServer
-from pydantic import AnyHttpUrl
-
-from . import library
-from . import class_management
-from . import monitoring
-from .access import has_permission, resolve_access
-from .auth import AuthUnavailable
-
-
-log = logging.getLogger("ihki.grok_mcp")
-APPROVAL_TTL = 10 * 60
-MAX_APPROVALS = 100
-MUTATION_LIMIT = 20
-MUTATION_WINDOW = 60
-
-
-@dataclass(frozen=True)
-class Approval:
-    title: str
-    url: str
-    expires_at: float
-
-
-class ApprovalStore:
-    def __init__(self, clock: Callable[[], float] = time.monotonic):
-        self.clock = clock
-        self._items: dict[str, Approval] = {}
-        self._lock = threading.Lock()
-
-    def _prune(self, now: float) -> None:
-        self._items = {key: item for key, item in self._items.items() if item.expires_at > now}
-        while len(self._items) >= MAX_APPROVALS:
-            self._items.pop(next(iter(self._items)))
-
-    def prepare(self, title: str, url: str) -> tuple[str, Approval]:
-        now = self.clock()
-        with self._lock:
-            self._prune(now)
-            approval_id = secrets.token_urlsafe(24)
-            item = Approval(title, url, now + APPROVAL_TTL)
-            self._items[approval_id] = item
-        return approval_id, item
-
-    def consume(self, approval_id: str) -> Approval | None:
-        now = self.clock()
-        with self._lock:
-            item = self._items.pop(str(approval_id), None)
-            self._prune(now)
-            return item if item and item.expires_at > now else None
-
-
-@dataclass(frozen=True)
-class ClassApproval:
-    actor_id: str
-    plan: dict[str, Any]
-    expires_at: float
-
-
-class ClassApprovalStore:
-    def __init__(self, clock: Callable[[], float] = time.monotonic):
-        self.clock = clock
-        self._items: dict[str, ClassApproval] = {}
-        self._lock = threading.Lock()
-
-    def _prune(self, now: float) -> None:
-        self._items = {key: item for key, item in self._items.items() if item.expires_at > now}
-        while len(self._items) >= MAX_APPROVALS:
-            self._items.pop(next(iter(self._items)))
-
-    def prepare(self, actor_id: str, plan: dict[str, Any]) -> tuple[str, ClassApproval]:
-        now = self.clock()
-        with self._lock:
-            self._prune(now)
-            approval_id = secrets.token_urlsafe(24)
-            item = ClassApproval(actor_id, plan, now + APPROVAL_TTL)
-            self._items[approval_id] = item
-        return approval_id, item
-
-    def consume(self, approval_id: str, actor_id: str) -> ClassApproval | None:
-        now = self.clock()
-        with self._lock:
-            self._prune(now)
-            item = self._items.get(str(approval_id))
-            if item is None or item.actor_id != actor_id:
-                return None
-            self._items.pop(str(approval_id), None)
-            return item if item.expires_at > now else None
-
-
-class MutationLimiter:
-    def __init__(self, clock: Callable[[], float] = time.monotonic):
-        self.clock = clock
-        self._uses: deque[float] = deque(maxlen=MUTATION_LIMIT)
-        self._lock = threading.Lock()
-
-    def allow(self) -> bool:
-        now = self.clock()
-        with self._lock:
-            while self._uses and self._uses[0] <= now - MUTATION_WINDOW:
-                self._uses.popleft()
-            if len(self._uses) >= MUTATION_LIMIT:
-                return False
-            self._uses.append(now)
-            return True
-
-
-def oauth_urls(app) -> tuple[str, str]:
-    """Return the public MCP resource and Supabase OAuth issuer URLs."""
-    auth = getattr(app.state, "auth", None)
-    supabase = (getattr(auth, "url", "") or os.environ.get("SUPABASE_URL", "")).rstrip("/")
-    public = os.environ.get("MCP_PUBLIC_URL", "").strip()
-    if not public and os.environ.get("SPACE_HOST", "").strip():
-        public = f"https://{os.environ['SPACE_HOST'].strip()}/mcp/"
-    public = public or "http://localhost:8000/mcp/"
-    return public.rstrip("/") + "/", (supabase + "/auth/v1" if supabase else "https://invalid.invalid/auth/v1")
-
-
-class SupabaseTokenVerifier:
-    """Validate a Supabase OAuth token and its current ihki management permission."""
-
-    def __init__(self, app):
-        self.app = app
-
-    async def verify_token(self, token: str) -> AccessToken | None:
-        auth = getattr(self.app.state, "auth", None)
-        if auth is None or not token:
-            return None
-        try:
-            # SupabaseAuth is deliberately synchronous throughout ihki. Keeping the same
-            # verifier path also avoids retaining a worker/thread beyond an MCP request.
-            user = resolve_access(auth, token, fresh_permissions=True)
-        except AuthUnavailable as exc:
-            log.warning("MCP OAuth verification unavailable: %s", exc)
-            return None
-        if not user or user.get("denied") or not has_permission(user, "management.access"):
-            return None
-        _, issuer = oauth_urls(self.app)
-        actor = {key: user.get(key) for key in ("id", "email", "roles", "subject", "permissions")}
-        return AccessToken(token=token, client_id="supabase-oauth", scopes=["openid", "email"],
-                           subject=str(user["id"]), claims={"iss": issuer, "ihki_actor": actor})
-
-
-def build(app, *, approvals: ApprovalStore | None = None, limiter: MutationLimiter | None = None,
-          class_approvals: ClassApprovalStore | None = None,
-          actor_provider: Callable[[], dict[str, Any] | None] | None = None):
-    """Return ``(server, authenticated ASGI app, raw Starlette app)``."""
-    resource_url, issuer_url = oauth_urls(app)
-    server = MCPServer(
-        "ihki-digital-library",
-        instructions=("Manage only the ihki digital video library and scoped class rosters, and provide read-only "
-                      "privacy-preserving monitoring. Always prepare a mutation, show its exact effect to the teacher, "
-                      "and publish only after explicit confirmation."),
-        token_verifier=SupabaseTokenVerifier(app),
-        auth=AuthSettings(issuer_url=AnyHttpUrl(issuer_url), resource_server_url=AnyHttpUrl(resource_url),
-                          validate_token_resource=False, required_scopes=[]),
-    )
-    approvals = approvals or ApprovalStore()
-    class_approvals = class_approvals or ClassApprovalStore()
-    limiter = limiter or MutationLimiter()
-
-    def auth():
-        return getattr(app.state, "auth", None)
-
-    def actor() -> dict[str, Any] | None:
-        if actor_provider:
-            return actor_provider()
-        access = get_access_token()
-        value = (access.claims or {}).get("ihki_actor") if access else None
-        return value if isinstance(value, dict) else None
-
-    def initial_lessons() -> dict[str, str]:
-        return dict(getattr(app.state, "initial_class_lessons", {}))
-
-    def class_audit(action: str, current: dict[str, Any] | None, outcome: str,
-                    result: dict[str, Any] | None = None, reason: str = "") -> None:
-        safe = result or {}
-        log.info("Grok class action=%s outcome=%s class_id=%s email=%s reason=%s", action, outcome,
-                 safe.get("class_id"), safe.get("email"), reason)
-        store = auth()
-        if store is not None and hasattr(store, "log_event"):
-            store.log_event("content", current or {"id": None, "email": ""},
-                            str(safe.get("class_name") or action),
-                            {"action": action, "outcome": outcome,
-                             **({"class_id": safe["class_id"]} if safe.get("class_id") is not None else {}),
-                             **({"email": safe["email"]} if safe.get("email") else {}),
-                             **({"reason": reason} if reason else {})})
-
-    def result(action: str, operation: Callable[[], dict[str, Any]]) -> dict[str, Any]:
-        if not limiter.allow():
-            library.audit(auth(), action, action, "refused", reason="rate_limit")
-            return {"ok": False, "error": "בוצעו יותר מדי פעולות. נסו שוב בעוד דקה."}
-        try:
-            answer = operation()
-            library.audit(auth(), action, str(answer.get("title") or action), "success",
-                          video_id=answer.get("video_id"))
-            return {"ok": True, **answer}
-        except library.LibraryError as exc:
-            library.audit(auth(), action, action, "refused", reason=type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description="List the digital-library videos in their current order. Returns no learner data.",
-                 structured_output=True)
-    async def list_library_videos() -> dict[str, Any]:
-        try:
-            videos = library.rows(auth(), fresh=True)
-            return {"ok": True, "videos": [
-                {"id": video["id"], "title": video["title"], "url": video["url"], "position": at + 1}
-                for at, video in enumerate(videos)
-            ]}
-        except library.LibraryError as exc:
-            return {"ok": False, "error": str(exc), "videos": []}
-
-    @server.tool(description="Validate a YouTube or Vimeo video and create a ten-minute approval. This does not publish it.",
-                 structured_output=True)
-    async def prepare_library_video(title: str, url: str) -> dict[str, Any]:
-        def prepare() -> dict[str, Any]:
-            clean_title = library.normalize_title(title)
-            clean_url = library.normalize_url(url, app.state.video_link)
-            library.ensure_unique(auth(), clean_url, fresh=True)
-            approval_id, item = approvals.prepare(clean_title, clean_url)
-            return {"approval_id": approval_id, "title": item.title, "url": item.url,
-                    "expires_in_seconds": APPROVAL_TTL, "published": False}
-        return result("prepare_library_video", prepare)
-
-    @server.tool(description="Publish a previously prepared video after the teacher explicitly confirms the shown title and URL.",
-                 structured_output=True)
-    async def publish_library_video(approval_id: str) -> dict[str, Any]:
-        def publish() -> dict[str, Any]:
-            item = approvals.consume(approval_id)
-            if item is None:
-                raise library.LibraryError("האישור אינו תקף, פג תוקף או כבר נוצל. הכינו את הסרטון מחדש.")
-            library.add(auth(), item.title, item.url)
-            created = next((video for video in library.rows(auth(), fresh=True) if video.get("url") == item.url), None)
-            return {"video_id": created.get("id") if created else None, "title": item.title,
-                    "url": item.url, "published": True}
-        return result("publish_library_video", publish)
-
-    @server.tool(description="Rename an existing digital-library video without changing its URL or position.",
-                 structured_output=True)
-    async def rename_library_video(video_id: int, title: str) -> dict[str, Any]:
-        def rename() -> dict[str, Any]:
-            clean_title = library.normalize_title(title)
-            library.rename(auth(), video_id, clean_title)
-            return {"video_id": video_id, "title": clean_title}
-        return result("rename_library_video", rename)
-
-    @server.tool(description="List only classes in the current manager's scope and their student emails/nicknames.",
-                 structured_output=True)
-    async def list_classes() -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "אין הרשאת ניהול", "classes": []}
-        try:
-            return {"ok": True, "classes": class_management.public_classes(store, current)}
-        except class_management.ClassManagementError as exc:
-            return {"ok": False, "error": str(exc), "classes": []}
-
-    @server.tool(description=("Prepare one class change for confirmation. Allowed operations: create_class, rename_class, "
-                              "add_student, remove_student. This does not mutate data."), structured_output=True)
-    async def prepare_class_change(
-        operation: Literal["create_class", "rename_class", "add_student", "remove_student"],
-        class_id: int | None = None, name: str = "", subject: str = "", email: str = "",
-        nickname: str = "", students: list[dict[str, str]] | None = None,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "אין הרשאת ניהול"}
-        if not limiter.allow():
-            class_audit("prepare_class_change", current, "refused", reason="rate_limit")
-            return {"ok": False, "error": "בוצעו יותר מדי פעולות. נסו שוב בעוד דקה."}
-        try:
-            plan = class_management.prepare(store, current, operation, class_id=class_id, name=name,
-                                            subject=subject, email=email, nickname=nickname, students=students,
-                                            initial_lessons=initial_lessons())
-            approval_id, _ = class_approvals.prepare(str(current["id"]), plan)
-            shown = {key: value for key, value in plan.items() if key not in {"state", "emails", "nicknames", "lesson"}}
-            if operation == "create_class":
-                shown["students"] = [{"email": item, **({"nickname": plan["nicknames"][item]}
-                                                          if item in plan["nicknames"] else {})}
-                                     for item in plan["emails"]]
-            class_audit("prepare_class_change", current, "success", shown)
-            return {"ok": True, "approval_id": approval_id, **shown,
-                    "expires_in_seconds": APPROVAL_TTL, "published": False}
-        except class_management.ClassManagementError as exc:
-            class_audit("prepare_class_change", current, "refused", reason=type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description="Publish a prepared class change only after the teacher explicitly confirms its exact effect.",
-                 structured_output=True)
-    async def publish_class_change(approval_id: str) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "אין הרשאת ניהול"}
-        if not limiter.allow():
-            class_audit("publish_class_change", current, "refused", reason="rate_limit")
-            return {"ok": False, "error": "בוצעו יותר מדי פעולות. נסו שוב בעוד דקה."}
-        item = class_approvals.consume(approval_id, str(current["id"]))
-        if item is None:
-            class_audit("publish_class_change", current, "refused", reason="invalid_approval")
-            return {"ok": False, "error": "האישור אינו תקף, פג תוקף, שייך למשתמש אחר או כבר נוצל."}
-        try:
-            answer = class_management.apply(store, current, item.plan, initial_lessons=initial_lessons())
-            class_audit("publish_class_change", current, "success", answer)
-            return {"ok": True, **answer, "published": True}
-        except class_management.ClassManagementError as exc:
-            class_audit("publish_class_change", current, "refused", reason=type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Return a read-only daily or weekly aggregate activity series for one authorized class "
-                              "or all classes in the current manager's scope. Returns no learner identities."),
-                 structured_output=True)
-    async def get_activity_timeseries(
-        from_date: str, to_date: str, interval: Literal["day", "week"] = "day",
-        class_id: int | None = None,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני הפעילות אינם זמינים"}
-        try:
-            return {"ok": True, **monitoring.activity_timeseries(
-                store, current, from_date=from_date, to_date=to_date, interval=interval, class_id=class_id)}
-        except monitoring.MonitoringError as exc:
-            log.info("MCP activity outcome=refused actor_id=%s class_id=%s range=%s..%s reason=%s",
-                     current.get("id"), class_id, from_date, to_date, type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Return privacy-thresholded current activity for one authorized class or all visible "
-                              "classes. Recent persisted practice never implies that learners are online; current "
-                              "presence is available only for an active live-class heartbeat session."),
-                 structured_output=True)
-    async def get_current_activity(
-        window_minutes: Literal[5, 15] = 5, class_id: int | None = None,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני הפעילות אינם זמינים"}
-        try:
-            answer = monitoring.current_activity(
-                store, current, window_minutes=window_minutes, class_id=class_id,
-                live_store=getattr(app.state, "live", None))
-            log.info("MCP current activity outcome=%s actor_id=%s class_id=%s window=%s",
-                     answer["status"], current.get("id"), class_id, window_minutes)
-            return {"ok": True, **answer}
-        except monitoring.MonitoringError as exc:
-            log.info("MCP current activity outcome=refused actor_id=%s class_id=%s window=%s reason=%s",
-                     current.get("id"), class_id, window_minutes, type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Return a read-only coarse application health summary. Never returns logs, errors, "
-                              "credentials, internal addresses, or configuration values."), structured_output=True)
-    async def get_system_health() -> dict[str, Any]:
-        current = actor()
-        if current is None:
-            return {"ok": False, "error": "אין הרשאת ניהול"}
-        try:
-            return {"ok": True, **monitoring.system_health(app, current)}
-        except monitoring.MonitoringError as exc:
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Return a read-only privacy-thresholded ranking of difficult exercises for one "
-                              "authorized class or all classes in the current manager's scope. Returns aggregates "
-                              "only and never identifies learners."), structured_output=True)
-    async def get_exercise_difficulty(
-        from_date: str, to_date: str, class_id: int | None = None,
-        exercise_type: Literal["pronunciation", "verb", "game", "other"] | None = None,
-        limit: int = 20, min_attempts: int = 10,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני הקושי אינם זמינים"}
-        try:
-            answer = monitoring.exercise_difficulty(
-                store, current, from_date=from_date, to_date=to_date, class_id=class_id,
-                exercise_type=exercise_type, limit=limit, min_attempts=min_attempts)
-            log.info("MCP difficulty outcome=success actor_id=%s class_id=%s range=%s..%s returned=%s",
-                     current.get("id"), class_id, from_date, to_date, answer["returned"])
-            return {"ok": True, **answer}
-        except monitoring.MonitoringError as exc:
-            log.info("MCP difficulty outcome=refused actor_id=%s class_id=%s range=%s..%s reason=%s",
-                     current.get("id"), class_id, from_date, to_date, type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Return measured pronunciation errors from stored phoneme diagnostics for one "
-                              "authorized class or all visible classes. Returns aggregates only and never infers "
-                              "linguistic difficulty when diagnostics are missing."), structured_output=True)
-    async def get_pronunciation_difficulties(
-        from_date: str, to_date: str, class_id: int | None = None,
-        limit: int = 20, min_attempts: int = 5,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני ההגייה אינם זמינים"}
-        try:
-            answer = monitoring.pronunciation_difficulties(
-                store, current, from_date=from_date, to_date=to_date, class_id=class_id,
-                limit=limit, min_attempts=min_attempts)
-            log.info("MCP pronunciation outcome=%s actor_id=%s class_id=%s range=%s..%s returned=%s",
-                     answer["status"], current.get("id"), class_id, from_date, to_date, answer["returned"])
-            return {"ok": True, **answer}
-        except monitoring.MonitoringError as exc:
-            log.info("MCP pronunciation outcome=refused actor_id=%s class_id=%s range=%s..%s reason=%s",
-                     current.get("id"), class_id, from_date, to_date, type(exc).__name__)
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Return a privacy-thresholded learning progress series for one authorized class or "
-                              "all visible classes, optionally restricted to a stable exercise identifier."),
-                 structured_output=True)
-    async def get_learning_progress(
-        from_date: str, to_date: str, interval: Literal["day", "week", "month"] = "week",
-        class_id: int | None = None, exercise_id: str | None = None, min_attempts: int = 5,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני הלמידה אינם זמינים"}
-        try:
-            answer = monitoring.learning_progress(
-                store, current, from_date=from_date, to_date=to_date, interval=interval,
-                class_id=class_id, exercise_id=exercise_id, min_attempts=min_attempts)
-            log.info("MCP progress outcome=%s actor_id=%s class_id=%s range=%s..%s",
-                     answer["status"], current.get("id"), class_id, from_date, to_date)
-            return {"ok": True, **answer}
-        except monitoring.MonitoringError as exc:
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Compare privacy-thresholded learning difficulty across authorized classes using "
-                              "normalized participation and exercise-exposure metrics. Returns no learner identities."),
-                 structured_output=True)
-    async def compare_class_difficulties(
-        from_date: str, to_date: str, class_ids: list[int] | None = None,
-        exercise_type: Literal["pronunciation", "verb", "game", "other"] | None = None,
-        min_attempts: int = 5,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני ההשוואה אינם זמינים"}
-        try:
-            answer = monitoring.compare_class_difficulties(
-                store, current, from_date=from_date, to_date=to_date, class_ids=class_ids,
-                exercise_type=exercise_type, min_attempts=min_attempts)
-            log.info("MCP class comparison outcome=%s actor_id=%s classes=%s range=%s..%s",
-                     answer["status"], current.get("id"), len(answer["classes"]), from_date, to_date)
-            return {"ok": True, **answer}
-        except monitoring.MonitoringError as exc:
-            return {"ok": False, "error": str(exc)}
-
-    @server.tool(description=("Identify privacy-thresholded exercise and topic bottlenecks from repeated failures "
-                              "and measured improvement. Recommendations are labeled separately from observations."),
-                 structured_output=True)
-    async def get_learning_bottlenecks(
-        from_date: str, to_date: str, class_id: int | None = None,
-        exercise_type: Literal["pronunciation", "verb", "game", "other"] | None = None,
-        limit: int = 20, min_attempts: int = 10,
-    ) -> dict[str, Any]:
-        current, store = actor(), auth()
-        if current is None or store is None:
-            return {"ok": False, "error": "נתוני הלמידה אינם זמינים"}
-        try:
-            answer = monitoring.learning_bottlenecks(
-                store, current, from_date=from_date, to_date=to_date, class_id=class_id,
-                exercise_type=exercise_type, limit=limit, min_attempts=min_attempts)
-            log.info("MCP bottlenecks outcome=%s actor_id=%s class_id=%s range=%s..%s returned=%s",
-                     answer["status"], current.get("id"), class_id, from_date, to_date, answer["returned"])
-            return {"ok": True, **answer}
-        except monitoring.MonitoringError as exc:
-            return {"ok": False, "error": str(exc)}
-
-    raw = server.streamable_http_app(
-        streamable_http_path="/",
-        stateless_http=True,
-        json_response=True,
-        max_request_body_size=64 * 1024,
-        host="0.0.0.0",
-    )
-    return server, raw, raw

app/keystore.py

@@ -1,204 +0,0 @@
-"""API keys a developer sets in the management panel (SAWTAK_API_KEY, ANTHROPIC_API_KEY), and the tutor's model
-(TUTOR_MODEL), so changing one needs no access to the host (the Hugging Face Space).
-
-Each key is kept in the Supabase table `app_secrets`, encrypted with Fernet under SECRETS_MASTER_KEY, which lives only in
-the host's environment: the table, a backup of it or a look at the Supabase dashboard shows no key. The table has
-row-level security on and no policy, so only the server's secret key reads it. A key never goes back to the page: the
-panel sees whether it is set, where from, and its last four characters. A new key is tried with its provider before it
-is kept, so a typo cannot switch the playback or the tutor off. TUTOR_MODEL is no secret: it is kept the same way, but
-the panel shows it, and a model is checked by asking Anthropic for it with the key in use.
-
-A key kept in the table takes the place of the environment's; without one (or without the table, the secret key or the
-master key) the environment's is used, as before.
-
-Env:  SECRETS_MASTER_KEY  (a Fernet key; make one with
-                           python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-                           and keep it as a Space secret. Losing it loses the stored keys, not the environment's.)
-"""
-from __future__ import annotations
-
-import logging
-import os
-import re
-import threading
-import urllib.error
-import urllib.request
-
-from .auth import AuthUnavailable
-
-log = logging.getLogger("ihki.keys")
-# the keys the panel may set, and how the panel names them; nothing else (the master key, the Supabase keys) is settable
-NAMES = {"SAWTAK_API_KEY": "Sawtak Arabi · השמעת התשובה", "ANTHROPIC_API_KEY": "Anthropic · המורה (יאללה נדבר)",
-         "TUTOR_MODEL": "המודל של המורה (TUTOR_MODEL)"}
-FALLBACK = {"ANTHROPIC_API_KEY": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"), "SAWTAK_API_KEY": ("SAWTAK_API_KEY",),
-            "TUTOR_MODEL": ("TUTOR_MODEL",)}
-PUBLIC = frozenset({"TUTOR_MODEL"})   # settings the panel may show in full
-# the panel's list of tutor models (any other id can be typed); empty = the code's default (tutor.DEFAULT_MODEL)
-MODEL_CHOICES = [("claude-haiku-5-5", "Haiku 5.5 · ברירת המחדל, הזול ביותר"), ("claude-sonnet-5-5", "Sonnet 5.5"),
-                 ("claude-opus-5-5", "Opus 5.5"), ("claude-fable-5-1", "Fable 5.1 · היקר ביותר"), ("claude-haiku-4-5", "Haiku 4.5")]
-MODEL_ID = re.compile(r"^claude-[a-z0-9][a-z0-9.-]{2,60}$")
-MAX_LEN = 300
-TIMEOUT = 15
-CREATE_APP_SECRETS = ("create table public.app_secrets (name text primary key check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL')), "
-                      "ciphertext text not null, last4 text not null default '', updated_by text not null default '', "
-                      "updated_at timestamptz not null default now()); "
-                      "alter table public.app_secrets enable row level security; "
-                      "revoke all on public.app_secrets from anon, authenticated;")
-# for a table made before TUTOR_MODEL could be kept in it
-MIGRATE_APP_SECRETS = ("alter table public.app_secrets drop constraint if exists app_secrets_name_check; "
-                       "alter table public.app_secrets add constraint app_secrets_name_check "
-                       "check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL'));")
-
-
-class KeyRefused(ValueError):
-    """The provider refused the key, or it could not be tried. The message is safe to show."""
-
-
-class KeyStore:
-    def __init__(self, auth, master: str = ""):
-        self.auth = auth
-        self._fernet, self.why = None, ""   # why: what keeps the panel from saving keys, in words for the page
-        if master:
-            try:
-                from cryptography.fernet import Fernet
-                self._fernet = Fernet(master.strip().encode())
-            except ImportError:
-                self.why = "החבילה cryptography לא מותקנת בשרת."
-            except ValueError:
-                log.error("SECRETS_MASTER_KEY is not a valid Fernet key: keys set in the panel are off")
-                self.why = "SECRETS_MASTER_KEY בשרת אינו מפתח Fernet תקין."
-        else:
-            self.why = "חסר SECRETS_MASTER_KEY בסודות השרת, ולכן אי אפשר לשמור מפתחות מהפאנל."
-        if not self.why and not getattr(auth, "secret", ""):
-            self.why = "חסר SUPABASE_SECRET_KEY בשרת, ולכן אי אפשר לשמור מפתחות מהפאנל."
-        self.missing = False   # the table is not there yet (CREATE_APP_SECRETS)
-        self._rows: dict[str, dict] = {}   # name -> {"value", "last4", "updated_by", "updated_at"}
-        self._lock = threading.Lock()
-
-    @property
-    def writable(self) -> bool:
-        return not self.why and not self.missing
-
-    def _seal(self, name: str, value: str) -> str:
-        # the name goes inside the ciphertext, so one key's row copied into another's does not decrypt as it
-        return self._fernet.encrypt(f"{name}\n{value}".encode()).decode()
-
-    def _open(self, name: str, token: str) -> str | None:
-        from cryptography.fernet import InvalidToken
-        try:
-            got, _, value = self._fernet.decrypt(token.encode()).decode().partition("\n")
-        except (InvalidToken, ValueError):
-            return None
-        return value if got == name else None
-
-    def load(self) -> None:
-        """Reads the stored keys. A failure is logged and leaves the environment's keys in use."""
-        if self.why or not hasattr(self.auth, "secret_rows"):
-            return
-        try:
-            rows = self.auth.secret_rows()
-        except AuthUnavailable as e:
-            log.warning("stored API keys not read, the environment's are used: %s", e)
-            return
-        if rows is None:
-            self.missing = True
-            return
-        found = {}
-        for r in rows:
-            value = self._open(r["name"], r.get("ciphertext") or "") if r.get("name") in NAMES else None
-            if value is None:
-                log.warning("stored key %s does not decrypt with this SECRETS_MASTER_KEY: the environment's is used", r.get("name"))
-                continue
-            found[r["name"]] = {"value": value, "last4": r.get("last4") or "", "updated_by": r.get("updated_by") or "",
-                                "updated_at": r.get("updated_at")}
-        with self._lock:
-            self._rows = found
-
-    @staticmethod
-    def _env(name: str) -> str:
-        return next((v for v in (os.environ.get(n, "").strip() for n in FALLBACK[name]) if v), "")
-
-    def get(self, name: str) -> str:
-        """The key in use: the panel's, else the environment's, else empty."""
-        with self._lock:
-            row = self._rows.get(name)
-        return row["value"] if row else self._env(name)
-
-    def status(self) -> list[dict]:
-        """What the panel shows of each key: never the key itself."""
-        out = []
-        for name, label in NAMES.items():
-            with self._lock:
-                row = self._rows.get(name)
-            env = self._env(name)
-            item = {"name": name, "label": label, "source": "db" if row else "env" if env else "none",
-                    "last4": "" if name in PUBLIC else row["last4"] if row else env[-4:] if len(env) >= 12 else "",
-                    "updated_by": row["updated_by"] if row else "", "updated_at": row["updated_at"] if row else None}
-            if name in PUBLIC:
-                item.update(value=row["value"] if row else env, choices=[{"id": i, "label": l} for i, l in MODEL_CHOICES])
-            out.append(item)
-        return out
-
-    def set(self, name: str, value: str, by: str) -> None:
-        """Encrypts and keeps a key that check() accepted."""
-        row = {"name": name, "ciphertext": self._seal(name, value), "last4": value[-4:], "updated_by": by}
-        self.auth.save_secret(row)
-        with self._lock:
-            self._rows[name] = {"value": value, "last4": row["last4"], "updated_by": by, "updated_at": None}
-
-    def clear(self, name: str) -> None:
-        """Forgets the panel's key; the environment's (if any) is used again."""
-        self.auth.delete_secret(name)
-        with self._lock:
-            self._rows.pop(name, None)
-
-
-def check(name: str, value: str, anthropic_key: str = "") -> None:
-    """Tries the key with its provider, with a call that costs nothing; a tutor model, by asking Anthropic for it with
-    `anthropic_key` (the key in use). Raises KeyRefused."""
-    if name == "TUTOR_MODEL":
-        if not MODEL_ID.match(value):
-            raise KeyRefused("מזהה מודל נראה כך: claude-haiku-5-5.")
-        if not anthropic_key:
-            raise KeyRefused("אין מפתח Anthropic, ולכן אי אפשר לבדוק את המודל. שמרו קודם מפתח.")
-        import anthropic
-        try:
-            anthropic.Anthropic(api_key=anthropic_key, timeout=TIMEOUT, max_retries=0).models.retrieve(value)
-        except anthropic.NotFoundError:
-            raise KeyRefused(f"Anthropic לא מכיר את המודל {value}.") from None
-        except (anthropic.AuthenticationError, anthropic.PermissionDeniedError):
-            raise KeyRefused("מפתח Anthropic שבשימוש נדחה, ולכן אי אפשר לבדוק את המודל.") from None
-        except anthropic.APIStatusError as e:
-            raise KeyRefused(f"לא ניתן לבדוק את המודל מול Anthropic כרגע ({e.status_code}). נסו שוב.") from None
-        except anthropic.APIConnectionError:
-            raise KeyRefused("אין חיבור ל-Anthropic כרגע. נסו שוב.") from None
-        return
-    if name == "SAWTAK_API_KEY":
-        req = urllib.request.Request("https://api.sawtakarabi.ai/v1/voices", headers={
-            "Authorization": f"Bearer {value}", "User-Agent": "ihki/1.0"})
-        try:
-            with urllib.request.urlopen(req, timeout=TIMEOUT):
-                return
-        except urllib.error.HTTPError as e:
-            if e.code == 403:   # a valid key restricted to `tts` may not list voices; speech is all it is used for
-                return
-            if e.code == 401:
-                raise KeyRefused("Sawtak דחה את המפתח.") from None
-            raise KeyRefused(f"לא ניתן לבדוק את המפתח מול Sawtak כרגע ({e.code}). נסו שוב.") from None
-        except OSError:
-            raise KeyRefused("אין חיבור ל-Sawtak כרגע. נסו שוב.") from None
-    import anthropic
-    try:
-        anthropic.Anthropic(api_key=value, timeout=TIMEOUT, max_retries=0).models.list(limit=1)
-    except (anthropic.AuthenticationError, anthropic.PermissionDeniedError):
-        raise KeyRefused("Anthropic דחה את המפתח.") from None
-    except anthropic.APIStatusError as e:
-        raise KeyRefused(f"לא ניתן לבדוק את המפתח מול Anthropic כרגע ({e.status_code}). נסו שוב.") from None
-    except anthropic.APIConnectionError:
-        raise KeyRefused("אין חיבור ל-Anthropic כרגע. נסו שוב.") from None
-
-
-def load_keys(auth) -> KeyStore:
-    keys = KeyStore(auth, os.environ.get("SECRETS_MASTER_KEY", ""))
-    keys.load()
-    return keys

app/lab.py

@@ -1,378 +0,0 @@
-"""The lab (מעבדה): a fixed diagnostic list for measuring the phoneme recognition, and its recordings.
-
-Every speaker reads the same short items once. Each item tests one sound (`focus`), so its answer is known and
-labelling a recording costs nothing: it was said right, or the speaker planted one mistake and marks which sound.
-Three groups:
-  - syllables: the hard letter alone before a long a (حا, عا, صا ...), and its easy neighbour beside it
-  - pairs:     minimal pairs (or a three) that differ in that sound only (حال / هال / خال, صيف / سيف ...): can the
-               model tell them apart
-  - positions: the sound at the start, the middle and the end of a word
-  - vowels:    a short vowel beside a glide (ولد, يلّا, شويّ: the glide's colour on the transition frames, GLIDE_KIN),
-               between consonants (كلب, بنت, كلّ: a spike from a neighbour's release), and short / long (من / مين).
-               Planting a↔i or u↔a on these measures whether the GOP pooling and windows (docs/gop-pooling.md)
-               still catch a real vowel substitution
-
-The recordings are kept in the Supabase table `lab_samples` and the storage bucket `lab` (see CREATE_LAB in main.py),
-the material for a per-sound benchmark: how often a sound said right is flagged, and how often a planted mistake is not.
-The IPA follows the bank's (phrases.py), and a word the bank has keeps the bank's reading.
-"""
-from __future__ import annotations
-
-import json
-from functools import lru_cache
-from pathlib import Path
-
-from .align import POOLS
-from .scorer import LETTER_GOOD
-from .tips import VOWELS
-from .translit import to_hebrew
-
-GROUPS = {"syllables": "הברות", "pairs": "זוגות מינימליים", "positions": "מיקום במילה", "vowels": "תנועות"}
-
-
-def _item(id: str, group: str, focus: str, he: str, *variants: tuple[str, str], pair: str = "") -> dict:
-    return {"id": id, "group": group, "focus": focus, "he": he, "variants": list(variants), "pair": pair}
-
-
-ITEMS = [
-    # syllables: the hard letter, then the sound a Hebrew speaker puts in its place
-    _item("syl-ħ", "syllables", "ħ", "ח גרונית", ("حا", "ħ aː")),
-    _item("syl-x", "syllables", "x", "ח' (כמו ח בעברית)", ("خا", "x aː")),
-    _item("syl-h", "syllables", "h", "ה", ("ها", "h aː")),
-    _item("syl-ʕ", "syllables", "ʕ", "ע גרונית", ("عا", "ʕ aː")),
-    _item("syl-ʔ", "syllables", "ʔ", "א", ("آ", "ʔ aː")),
-    _item("syl-ɣ", "syllables", "ɣ", "ע' (ר גרונית)", ("غا", "ɣ aː")),
-    _item("syl-r", "syllables", "r", "ר מתגלגלת", ("را", "r aː")),
-    _item("syl-sˤ", "syllables", "sˤ", "צ' (ס נחצית)", ("صا", "sˤ aː")),
-    _item("syl-s", "syllables", "s", "ס", ("سا", "s aː")),
-    _item("syl-tˤ", "syllables", "tˤ", "ט נחצית", ("طا", "tˤ aː")),
-    _item("syl-t", "syllables", "t", "ת", ("تا", "t aː")),
-    _item("syl-dˤ", "syllables", "dˤ", "צ' (ד נחצית)", ("ضا", "dˤ aː")),
-    _item("syl-d", "syllables", "d", "ד", ("دا", "d aː")),
-    # minimal pairs: the two words of a pair differ in the focus sound only
-    _item("pair-ħaal", "pairs", "ħ", "מצב", ("حال", "ħ aː l"), pair="ħ / h / x"),
-    _item("pair-haal", "pairs", "h", "הל (תבלין)", ("هال", "h aː l"), pair="ħ / h / x"),
-    _item("pair-xaal", "pairs", "x", "דוד (אח של אמא)", ("خال", "x aː l"), pair="ħ / h / x"),
-    _item("pair-ʕalam", "pairs", "ʕ", "דגל", ("علم", "ʕ a l a m"), pair="ʕ / ʔ"),
-    _item("pair-ʔalam", "pairs", "ʔ", "כאב", ("ألم", "ʔ a l a m"), pair="ʕ / ʔ"),
-    _item("pair-ɣaali", "pairs", "ɣ", "יקר", ("غالي", "ɣ aː l i"), pair="ɣ / x"),
-    _item("pair-xaali", "pairs", "x", "הדוד שלי", ("خالي", "x aː l i"), pair="ɣ / x"),
-    _item("pair-sˤeef", "pairs", "sˤ", "קיץ", ("صيف", "sˤ eː f"), pair="sˤ / s"),
-    _item("pair-seef", "pairs", "s", "חרב", ("سيف", "s eː f"), pair="sˤ / s"),
-    _item("pair-tˤiin", "pairs", "tˤ", "בוץ", ("طين", "tˤ iː n"), pair="tˤ / t"),
-    _item("pair-tiin", "pairs", "t", "תאנה", ("تين", "t iː n"), pair="tˤ / t"),
-    _item("pair-dˤaar", "pairs", "dˤ", "מזיק", ("ضار", "dˤ aː r"), pair="dˤ / d"),
-    _item("pair-daar", "pairs", "d", "בית", ("دار", "d aː r"), pair="dˤ / d"),
-    # no ق / ك pair: ق is said ʔ, k or q (archi.py), so قلب said kalb is right and the pair tells nothing
-    # positions: the focus sound at the start, the middle and the end of a word
-    _item("pos-ħ-1", "positions", "ħ", "חלב", ("حليب", "ħ a l iː b")),
-    _item("pos-ħ-2", "positions", "ħ", "בשר", ("لحم", "l a ħ m"), ("لحم", "l a ħ i m")),
-    _item("pos-ħ-3", "positions", "ħ", "בוקר", ("صباح", "sˤ a b aː ħ")),
-    _item("pos-ʕ-1", "positions", "ʕ", "עין", ("عين", "ʕ eː n")),
-    _item("pos-ʕ-2", "positions", "ʕ", "רחוק", ("بعيد", "b ʕ iː d"), ("بعيد", "b a ʕ iː d")),
-    _item("pos-ʕ-3", "positions", "ʕ", "שבע", ("سبع", "s a b ʕ"), ("سبع", "s a b i ʕ")),
-    _item("pos-x-1", "positions", "x", "הדוד שלי", ("خالي", "x aː l i")),
-    _item("pos-x-2", "positions", "x", "בסדר", ("بخير", "b i x eː r"), ("بخير", "b x eː r")),
-    _item("pos-x-3", "positions", "x", "מטבח", ("مطبخ", "m a tˤ b a x")),
-    _item("pos-ɣ-1", "positions", "ɣ", "חדר", ("غرفة", "ɣ u r f e")),
-    _item("pos-ɣ-2", "positions", "ɣ", "קטן", ("صغير", "sˤ ɣ iː r")),
-    _item("pos-sˤ-2", "positions", "sˤ", "נמוך", ("قصير", "ʔ a sˤ iː r"), ("قصير", "q a sˤ iː r")),
-    _item("pos-sˤ-3", "positions", "sˤ", "זול", ("رخيص", "r x iː sˤ")),
-    _item("pos-tˤ-1", "positions", "tˤ", "שולחן", ("طاولة", "tˤ aː w l e")),
-    _item("pos-tˤ-2", "positions", "tˤ", "תפוחי אדמה", ("بطاطا", "b a tˤ aː tˤ a")),
-    _item("pos-dˤ-2", "positions", "dˤ", "ירוק", ("اخضر", "ʔ a x dˤ a r")),
-    _item("pos-dˤ-3", "positions", "dˤ", "לבן", ("ابيض", "ʔ a b j a dˤ")),
-    _item("pos-ʔ-2", "positions", "ʔ", "שאלה", ("سؤال", "s u ʔ aː l")),
-    _item("pos-h-2", "positions", "h", "חודש", ("شهر", "ʃ a h r"), ("شهر", "ʃ a h i r")),
-    # vowels: the short vowel is the focus. Beside a glide: its i / u colour must not count against the vowel
-    _item("vow-walad", "vowels", "a", "ילד", ("ولد", "w a l a d")),
-    _item("vow-jalla", "vowels", "a", "יאללה", ("يلّا", "j a l l a")),
-    _item("vow-ʃwajj", "vowels", "a", "קצת", ("شويّ", "ʃ w a j j")),
-    _item("vow-majj", "vowels", "a", "מים", ("ميّ", "m a j j"), ("ميّ", "m a j j e")),
-    # between consonants: a release or a burst beside the vowel must not count against it
-    _item("vow-kalb", "vowels", "a", "כלב", ("كلب", "k a l b")),
-    _item("vow-bint", "vowels", "i", "בת", ("بنت", "b i n t")),
-    _item("vow-kull", "vowels", "u", "הכל", ("كلّ", "k u l l")),
-    _item("vow-sukkar", "vowels", "u", "סוכר", ("سكّر", "s u k k a r")),
-    _item("vow-bass", "vowels", "a", "רק / די", ("بسّ", "b a s s")),
-    # short / long: the same consonants, the vowel's length only
-    _item("vow-min", "vowels", "i", "מ־ (מן)", ("من", "m i n"), pair="i / iː"),
-    _item("vow-miin", "vowels", "iː", "מי", ("مين", "m iː n"), pair="i / iː"),
-]
-BY_ID = {item["id"]: item for item in ITEMS}
-
-# A deliberately small, single-take screen for comparing acoustic models with Hebrew speakers.  Unlike the full
-# diagnostic list above, this is not saved as labelled benchmark data: the same take is scored by every comparison
-# model and shown side by side.  It mixes the two pharyngeals, Hebrew ח' /x/, emphatics and short/long vowels.  زمن
-# is intentional: Hebrew speakers commonly insert an alif-like long /a:/ and say zama:n although both vowels are
-# short.  كتاب is the positive control, where the alif really should be long.
-QUICK_QUIZ = [
-    _item("quick-halib", "quick", "ħ", "חַלִיב — ח גרונית", ("حليب", "ħ a l iː b")),
-    _item("quick-baid", "quick", "ʕ", "בַּעִיד — ע גרונית", ("بعيد", "b a ʕ iː d")),
-    _item("quick-khali", "quick", "x", "חַ'אלִי — ח׳", ("خالي", "x aː l i")),
-    _item("quick-zaman", "quick", "a", "זַמַן — שתי תנועות קצרות (לא זַמַאן)", ("زمن", "z a m a n")),
-    _item("quick-kitab", "quick", "aː", "כִּתַאבּ — אליף ארוכה", ("كتاب", "k i t aː b")),
-    _item("quick-sabah", "quick", "ħ", "סַבַּאח — ח בסוף ואליף ארוכה", ("صباح", "sˤ a b aː ħ")),
-    _item("quick-sual", "quick", "ʔ", "סֻאַאל — המזה ואליף ארוכה", ("سؤال", "s u ʔ aː l")),
-    _item("quick-tawle", "quick", "tˤ", "טַאוְלֶה — ט נחצית", ("طاولة", "tˤ aː w l e")),
-    _item("quick-zghir", "quick", "ɣ", "זְעִ'יר — ע׳", ("صغير", "sˤ ɣ iː r")),
-    _item("quick-bint", "quick", "i", "בִּנְת — תנועה קצרה", ("بنت", "b i n t")),
-]
-QUICK_BY_ID = {item["id"]: item for item in QUICK_QUIZ}
-MINERVA_METADATA = Path(__file__).resolve().parent.parent / "data" / "minerva_metadata.json"
-
-
-@lru_cache(maxsize=1)
-def minerva_metadata() -> tuple[dict, ...]:
-    """The reviewed Minerva captions used by both the lab page and every rescore.
-
-    Supabase owns the recording and its historical result; this file owns the sentence, timing and expected phones.
-    Keeping that boundary explicit means an OCR correction takes effect on the next server start without reimporting
-    audio or editing database rows.
-    """
-    raw = json.loads(MINERVA_METADATA.read_text(encoding="utf-8"))
-    if not isinstance(raw, list):
-        raise ValueError("Minerva metadata must be a JSON array")
-    videos, seen = [], set()
-    for video in raw:
-        video_id = str(video.get("youtube_id") or "")
-        segments = video.get("segments")
-        if not video_id or video_id in seen or not isinstance(segments, list):
-            raise ValueError(f"invalid Minerva video metadata: {video_id or '<missing id>'}")
-        seen.add(video_id)
-        lines = []
-        for line, segment in enumerate(segments, 1):
-            timing = segment.get("voice_time_seconds") or {}
-            required = (segment.get("arabic"), segment.get("hebrew_transliteration"),
-                        segment.get("hebrew"), segment.get("expected_phonemes"))
-            if not all(isinstance(value, str) and value.strip() for value in required):
-                raise ValueError(f"incomplete Minerva metadata: {video_id}:{line:02d}")
-            try:
-                start, end = float(timing["start"]), float(timing["end"])
-            except (KeyError, TypeError, ValueError) as exc:
-                raise ValueError(f"invalid Minerva timing: {video_id}:{line:02d}") from exc
-            if end <= start:
-                raise ValueError(f"invalid Minerva timing: {video_id}:{line:02d}")
-            lines.append({"item": f"minerva:{video_id}:{line:02d}", "line": line, "start": start, "end": end,
-                          "ar": required[0], "tr": required[1], "he": required[2], "ipa": required[3]})
-        videos.append({"id": video_id, "title": str(video.get("title_hebrew") or video_id),
-                       "filename": str(video.get("file_name") or ""), "segments": tuple(lines)})
-    return tuple(videos)
-
-
-def minerva_segments() -> dict[str, dict]:
-    """Reviewed Minerva segments by their persisted lab item key."""
-    return {segment["item"]: segment for video in minerva_metadata() for segment in video["segments"]}
-
-
-def phrase(item: dict) -> dict:
-    """An item as the scorer takes a phrase."""
-    return {"cat": "lab", "key": f"lab:{item['id']}", "he": item["he"], "variants": item["variants"]}
-
-
-def sample_phrase(sample: dict) -> dict | None:
-    """The phrase of a saved recording, including imported lines outside the fixed diagnostic list.
-
-    Fixed items keep their current variants.  An importer stores the exact Arabic/IPA pair that was used for
-    scoring, so later rescores, sweeps and traces do not depend on the importer's manifest still being present.
-    """
-    item = BY_ID.get(sample.get("item"))
-    if item is not None:
-        return phrase(item)
-    segment = minerva_segments().get(sample.get("item"))
-    if segment is not None:
-        return {"cat": "lab", "key": segment["item"], "he": segment["he"],
-                "variants": [(segment["ar"], segment["ipa"])]}
-    ar, ipa = sample.get("ar"), sample.get("ipa")
-    if not ar or not ipa:
-        return None
-    key = str(sample.get("item") or f"sample:{sample.get('id', '')}")
-    return {"cat": "lab", "key": key, "he": sample.get("speaker") or key, "variants": [(ar, ipa)]}
-
-
-def public_items() -> list[dict]:
-    """The list for the lab's page (teachers only): each item with its first reading's sounds, which a planted
-    mistake is marked on, and that reading in Hebrew letters."""
-    out = []
-    for item in ITEMS:
-        ar, ipa = item["variants"][0]
-        out.append({"id": item["id"], "group": item["group"], "focus": item["focus"], "he": item["he"],
-                    "pair": item["pair"], "ar": ar, "tr": " ".join(to_hebrew(ipa, ar)),
-                    "sounds": [s for s in ipa.split() if s != "|"]})
-    return out
-
-
-def public_quick_quiz() -> list[dict]:
-    """The ten model-comparison prompts, without exposing any extra scorer internals."""
-    return [{"id": item["id"], "number": number, "focus": item["focus"], "he": item["he"],
-             "ar": item["variants"][0][0], "tr": " ".join(to_hebrew(item["variants"][0][1], item["variants"][0][0]))}
-            for number, item in enumerate(QUICK_QUIZ, 1)]
-
-
-# ---------- the benchmark ----------
-# A recording's sounds are judged against its label: a sound said right should not be flagged (one that is, is a false
-# rejection), and the planted mistake should be (one that is not, is a miss). The numbers are per sound as written.
-GOOD_SCORE = 75   # a recording said right should score at least this (the card's "מצוין")
-
-
-def flag_phrase(row: dict) -> dict:
-    """The bank phrase a flag was said for, or (a verb-game form, a teacher's text line) the variant it was scored on."""
-    from .phrases import PHRASES
-
-    key = row.get("phrase")
-    for p in PHRASES:
-        if p.get("key", p["he"]) == key:
-            return p
-    return {"variants": [(row["ar"], row["ipa"])], "key": key, "he": row.get("he", ""), "cat": row.get("cat", "")}
-
-
-def flagged_sounds(result: dict) -> list[str]:
-    """The sounds a result marked down, as "expected>heard"."""
-    return [f"{p.get('sound', p['ipa'])}>{p.get('heard') or '_'}" for w in result.get("words", [])
-            for p in w.get("phonemes", []) if p.get("flagged")]
-
-
-def judged(sample: dict, result: dict | None = None) -> list[dict]:
-    """The sounds of a lab recording, each {"sound", "planted", "flagged", "score", "heard"}: `planted` is the one the
-    speaker said wrong on purpose (the first sound written as the label's; the scorer may have chosen another reading
-    of the item, so it is found by sound and not by place). `result` replaces the stored one (a rescore)."""
-    result = result or sample.get("result") or {}
-    phones = [p for w in result.get("words", []) for p in w.get("phonemes", [])]
-    want = (sample.get("mistake") or {}).get("expected") if sample.get("label") == "mistake" else None
-    planted = next((k for k, p in enumerate(phones) if want in (p["ipa"], p.get("sound"))), None) if want else None
-    return [{"sound": p["ipa"], "planted": k == planted, "flagged": bool(p.get("flagged")), "score": p["score"],
-             "heard": p.get("heard") or "_"} for k, p in enumerate(phones)]
-
-
-def benchmark(samples: list[dict], results: dict | None = None, reports: list[dict] = ()) -> dict:
-    """Per-sound numbers of the lab's recordings. `results` ({sample id: result}) replaces their stored results, for a
-    rescore with the current scorer; `reports` are the confirmed flags, whose `false_issues` are false rejections a
-    teacher found in practice (counted per sound, without a denominator: what was said right is not known there).
-    {"sounds": [{"sound", "right", "false_flags", "frr", "planted", "caught", "detection", "mean", "confusions",
-    "reports"}], "totals": {...}}, the sounds that went wrong most first."""
-    results = results or {}
-    rows: dict[str, dict] = {}
-
-    def row(sound: str) -> dict:
-        return rows.setdefault(sound, {"sound": sound, "right": 0, "false_flags": 0, "planted": 0, "caught": 0,
-                                       "scores": [], "confusions": {}, "reports": 0})
-
-    totals = {"recordings": 0, "correct": 0, "mistake": 0, "unrelated": 0, "good": 0, "right": 0, "false_flags": 0,
-              "planted": 0, "caught": 0, "unplaced": 0, "said_right": 0}
-    for s in samples:
-        result = results.get(s.get("id")) or s.get("result") or {}
-        if not result.get("words"):
-            continue
-        totals["recordings"] += 1
-        totals[s["label"] if s.get("label") in ("correct", "mistake") else "correct"] += 1
-        if result.get("unrelated"):   # a different sentence: its sounds tell nothing
-            totals["unrelated"] += 1
-            continue
-        if s.get("label") != "mistake":
-            totals["said_right"] += 1
-            totals["good"] += result.get("score", 0) >= GOOD_SCORE
-        sounds = judged(s, result)
-        if s.get("label") == "mistake" and not any(x["planted"] for x in sounds):
-            totals["unplaced"] += 1
-        for x in sounds:
-            r = row(x["sound"])
-            if x["planted"]:
-                r["planted"] += 1; totals["planted"] += 1
-                if x["flagged"]:
-                    r["caught"] += 1; totals["caught"] += 1
-                continue
-            r["right"] += 1; totals["right"] += 1
-            r["scores"].append(x["score"])
-            if x["flagged"]:
-                r["false_flags"] += 1; totals["false_flags"] += 1
-                r["confusions"][x["heard"]] = r["confusions"].get(x["heard"], 0) + 1
-    for f in reports:
-        for issue in f.get("false_issues") or []:
-            if issue.get("expected"):
-                row(issue["expected"])["reports"] += 1
-
-    rate = lambda a, b: round(a / b, 3) if b else None
-    out = []
-    for r in rows.values():
-        scores = r.pop("scores")
-        r["mean"] = round(sum(scores) / len(scores), 1) if scores else None
-        r["frr"], r["detection"] = rate(r["false_flags"], r["right"]), rate(r["caught"], r["planted"])
-        r["confusions"] = dict(sorted(r["confusions"].items(), key=lambda kv: -kv[1]))
-        out.append(r)
-    out.sort(key=lambda r: (-(r["frr"] or 0), -(1 - r["detection"] if r["detection"] is not None else 0), -r["reports"],
-                            r["sound"]))
-    totals.update(frr=rate(totals["false_flags"], totals["right"]), detection=rate(totals["caught"], totals["planted"]),
-                  good_share=rate(totals["good"], totals["said_right"]))
-    return {"sounds": out, "totals": totals}
-
-
-def compact(result: dict) -> dict:
-    """What the benchmark reads of a result (the sounds, their scores and flags), for the page to send back."""
-    keep = ("ipa", "sound", "score", "flagged", "heard")
-    return {"score": result.get("score"), "heard_ipa": result.get("heard_ipa", ""),
-            "unrelated": bool(result.get("unrelated")),
-            "words": [{**{k: w[k] for k in ("ar", "tr", "heard_tr", "score") if k in w},
-                       "phonemes": [{k: p[k] for k in keep if k in p} for p in w.get("phonemes", [])]}
-                      for w in result.get("words", [])]}
-
-
-def still_flagged(result: dict, issue: dict) -> bool:
-    """Whether a sound a teacher marked as wrongly flagged (a confirmed flag's false issue: its word and written sound)
-    is flagged again in this result."""
-    words = result.get("words", [])
-    if not 0 <= issue.get("word", -1) < len(words):
-        return False
-    return any(p.get("flagged") and p["ipa"] == issue.get("expected") for p in words[issue["word"]].get("phonemes", []))
-
-
-# ---------- the sweep over the GOP settings ----------
-# Every GOP_RATIO_POOL with every GOP_VOWEL_WINDOW that differs in practice (a larger pad reaches the wide window).
-WINDOWS = (None, 0, 1, 2)
-SWEEP = [(pool, window) for pool in POOLS for window in WINDOWS]
-
-
-def sweep_key(pool: str, window: int | None) -> str:
-    """The name of a setting, as the env writes it: "gated|wide", "max|1"."""
-    return f"{pool}|{'wide' if window is None else window}"
-
-
-SWEEP_KEYS = {sweep_key(p, w): (p, w) for p, w in SWEEP}
-
-
-def quality(totals: dict) -> float | None:
-    """The pipeline's one number, 0..100: balanced accuracy over the judged sounds, the mean of
-    (1 - false rejection rate) and the detection rate. Each half is a rate, so the many sounds said right do not
-    drown the few planted mistakes, and a setting cannot win by flagging nothing (detection 0) or everything
-    (false rejections 1). Without planted mistakes it is 1 - frr alone (see `quality_partial`). None: no sound judged."""
-    frr, det = totals.get("frr"), totals.get("detection")
-    if frr is None:
-        return None
-    return round(100 * ((1 - frr) + det) / 2, 1) if det is not None else round(100 * (1 - frr), 1)
-
-
-def quality_partial(totals: dict) -> bool:
-    """True when `quality` could not weigh the detection (no planted mistake was judged)."""
-    return totals.get("detection") is None
-
-
-def vowel_stats(samples: list[dict], results: dict | None = None) -> dict:
-    """The vowels of the recordings, by score rather than flag: the scorer flags no vowel but the u of rule 3.11, so the
-    flag counts of `benchmark` cannot see a GOP change on vowels. Over recordings of the item's sentence (not
-    "unrelated"): {"right": vowels said right, "mean": their mean score, "weak": the share of them under LETTER_GOOD
-    (shown to the learner as weak), "planted": planted vowel mistakes, "auc": the chance that a vowel said right
-    scores above a planted wrong one (ties count half; None without planted vowels)}."""
-    results = results or {}
-    right, wrong = [], []
-    for s in samples:
-        result = results.get(s.get("id")) or s.get("result") or {}
-        if not result.get("words") or result.get("unrelated"):
-            continue
-        for x in judged(s, result):
-            if x["sound"] in VOWELS:
-                (wrong if x["planted"] else right).append(x["score"])
-    auc = None
-    if right and wrong:
-        auc = round(sum(1.0 if r > w else 0.5 if r == w else 0.0 for r in right for w in wrong) / (len(right) * len(wrong)), 3)
-    return {"right": len(right), "mean": round(sum(right) / len(right), 1) if right else None,
-            "weak": round(sum(x < LETTER_GOOD for x in right) / len(right), 3) if right else None,
-            "planted": len(wrong), "auc": auc}

app/library.py

@@ -1,78 +0,0 @@
-"""Shared digital-library validation and persistence operations."""
-from __future__ import annotations
-
-import logging
-from typing import Callable
-
-from .auth import AuthUnavailable, SupabaseAuth
-
-
-MAX_TITLE = 80
-log = logging.getLogger("ihki.library")
-
-
-class LibraryError(ValueError):
-    """A safe, user-facing library operation error."""
-
-
-class LibraryUnavailable(LibraryError):
-    """The optional persistent content store cannot be used."""
-
-
-def normalize_title(value: object) -> str:
-    title = " ".join(str(value or "").split())
-    if not title or len(title) > MAX_TITLE:
-        raise LibraryError(f"לסרטון צריך שם (עד {MAX_TITLE} תווים)")
-    return title
-
-
-def normalize_url(value: object, parse: Callable[[str], str | None]) -> str:
-    url = parse(str(value or ""))
-    if not url:
-        raise LibraryError("זה לא קישור לסרטון ב-Vimeo או ב-YouTube")
-    return url
-
-
-def rows(auth: SupabaseAuth | None, *, fresh: bool = False) -> list[dict]:
-    if auth is None:
-        raise LibraryUnavailable("ספריית הסרטונים אינה זמינה: Supabase אינו מוגדר")
-    try:
-        return auth.level_videos("library", fresh=fresh)
-    except AuthUnavailable as exc:
-        raise LibraryUnavailable(f"ספריית הסרטונים אינה זמינה: {exc}") from exc
-
-
-def ensure_unique(auth: SupabaseAuth | None, url: str, *, fresh: bool = True) -> None:
-    if any(video.get("url") == url for video in rows(auth, fresh=fresh)):
-        raise LibraryError("הסרטון כבר נמצא בספרייה הדיגיטלית")
-
-
-def add(auth: SupabaseAuth | None, title: str, url: str, *, reject_duplicate: bool = True) -> None:
-    if reject_duplicate:
-        ensure_unique(auth, url, fresh=True)
-    try:
-        assert auth is not None
-        auth.add_level_video("library", "", title, url)
-    except AuthUnavailable as exc:
-        raise LibraryUnavailable(f"לא ניתן להוסיף לספרייה: {exc}") from exc
-
-
-def rename(auth: SupabaseAuth | None, video_id: int, title: str) -> None:
-    if not isinstance(video_id, int) or isinstance(video_id, bool) or video_id <= 0:
-        raise LibraryError("מזהה הסרטון אינו תקין")
-    if all(video.get("id") != video_id for video in rows(auth, fresh=True)):
-        raise LibraryError("הסרטון אינו נמצא בספרייה")
-    try:
-        assert auth is not None
-        auth.rename_level_video("library", video_id, title)
-    except AuthUnavailable as exc:
-        raise LibraryUnavailable(f"לא ניתן לשנות את שם הסרטון: {exc}") from exc
-
-
-def audit(auth: SupabaseAuth | None, action: str, label: str, outcome: str, **details: object) -> None:
-    """Best-effort audit using the existing management activity feed."""
-    log.info("Grok library action=%s outcome=%s label=%s details=%s", action, outcome, label[:200], details)
-    if auth is None or not hasattr(auth, "log_event"):
-        return
-    auth.log_event("integration", {"id": None, "email": "grok-library"}, label,
-                   {"action": action, "outcome": outcome, **details})

app/live.py

@@ -1,181 +0,0 @@
-"""Temporary live-class state.
-
-Live sessions deliberately live in process memory: class/teacher assignments are durable in
-Supabase, while attendance, questions and answers disappear when a session ends or the service
-restarts.  The browser polls this store; no recording bytes are retained here.
-"""
-from __future__ import annotations
-
-import secrets
-import threading
-import time
-from datetime import datetime, timezone
-
-
-SESSION_TTL = 2 * 60 * 60
-PRESENCE_TTL = 20
-
-
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-class LiveConflict(ValueError):
-    pass
-
-
-class LiveStore:
-    def __init__(self):
-        self._lock = threading.Lock()
-        self._sessions: dict[str, dict] = {}
-
-    def _prune(self, now: float) -> None:
-        for code, session in list(self._sessions.items()):
-            if session["ended"] or now - session["teacher_seen"] > SESSION_TTL:
-                self._sessions.pop(code, None)
-
-    def _new_code(self) -> str:
-        for _ in range(100):
-            code = f"{secrets.randbelow(1_000_000):06d}"
-            if code not in self._sessions:
-                return code
-        raise RuntimeError("could not allocate a live-session code")
-
-    def start(self, course: dict, teacher: dict) -> dict:
-        now = time.monotonic()
-        with self._lock:
-            self._prune(now)
-            existing = next((s for s in self._sessions.values() if s["class_id"] == course["id"]), None)
-            if existing:
-                existing["teacher_seen"] = now
-                return self._public(existing)
-            code = self._new_code()
-            roster = {email: (course.get("nicknames") or {}).get(email) or email.split("@", 1)[0]
-                      for email in course.get("emails", [])}
-            session = {"code": code, "class_id": course["id"], "class_name": course["name"],
-                       "teacher_id": teacher["id"], "teacher_email": teacher["email"].lower(),
-                       "started_at": _now_iso(), "teacher_seen": now, "ended": False,
-                       "question": None, "participants": {}, "roster": roster, "answers": {}, "question_no": 0}
-            self._sessions[code] = session
-            return self._public(session)
-
-    def list_for(self, class_ids: set[int], user_id: str) -> list[dict]:
-        now = time.monotonic()
-        with self._lock:
-            self._prune(now)
-            return [self._public(s) for s in self._sessions.values()
-                    if s["class_id"] in class_ids or user_id in s["participants"]]
-
-    def get(self, code: str) -> dict | None:
-        now = time.monotonic()
-        with self._lock:
-            self._prune(now)
-            return self._sessions.get(code)
-
-    def presence_summary(self, class_ids: set[int], *, now: float | None = None) -> dict:
-        """Return identity-free presence for active sessions in the selected classes."""
-        instant = time.monotonic() if now is None else float(now)
-        selected = {int(class_id) for class_id in class_ids}
-        with self._lock:
-            self._prune(instant)
-            sessions = [session for session in self._sessions.values() if session["class_id"] in selected]
-            active = {user_id for session in sessions for user_id, person in session["participants"].items()
-                      if instant - person["last_seen"] <= PRESENCE_TTL}
-            return {"active_session": bool(sessions), "active_users": len(active),
-                    "heartbeat_ttl_seconds": PRESENCE_TTL, "ephemeral": True}
-
-    def join(self, code: str, user: dict, name: str = "") -> dict:
-        now = time.monotonic()
-        with self._lock:
-            self._prune(now)
-            session = self._sessions.get(code)
-            if not session:
-                raise KeyError(code)
-            session["participants"][user["id"]] = {"email": user["email"].lower(),
-                                                      "name": name or user["email"].split("@", 1)[0],
-                                                      "last_seen": now}
-            return self._public(session)
-
-    def heartbeat(self, code: str, user: dict, teacher: bool = False) -> dict:
-        now = time.monotonic()
-        with self._lock:
-            self._prune(now)
-            session = self._sessions.get(code)
-            if not session:
-                raise KeyError(code)
-            if teacher:
-                session["teacher_seen"] = now
-            elif user["id"] in session["participants"]:
-                session["participants"][user["id"]]["last_seen"] = now
-            else:
-                raise PermissionError(code)
-            return self._detail(session, user["id"], teacher, now)
-
-    def ask(self, code: str, phrase: dict) -> dict:
-        now = time.monotonic()
-        with self._lock:
-            session = self._sessions.get(code)
-            if not session:
-                raise KeyError(code)
-            variants = phrase.get("variants") or []
-            arabic = phrase.get("ar") or (variants[0][0] if variants else "")
-            session["question_no"] += 1
-            session["question"] = {"no": session["question_no"], "phrase_id": phrase["id"],
-                                   "he": phrase["he"], "ar": arabic, "tr": phrase["tr"],
-                                   "started_at": _now_iso()}
-            session["answers"] = {}
-            session["teacher_seen"] = now
-            return self._public(session)
-
-    def begin_answer(self, code: str, user_id: str) -> dict:
-        with self._lock:
-            session = self._sessions.get(code)
-            if not session or not session["question"]:
-                raise KeyError(code)
-            if user_id not in session["participants"]:
-                raise PermissionError(code)
-            if user_id in session["answers"]:
-                raise LiveConflict("one attempt only")
-            session["answers"][user_id] = {"pending": True}
-            return dict(session["question"])
-
-    def cancel_answer(self, code: str, user_id: str) -> None:
-        with self._lock:
-            session = self._sessions.get(code)
-            if session and session["answers"].get(user_id, {}).get("pending"):
-                session["answers"].pop(user_id, None)
-
-    def finish_answer(self, code: str, user_id: str, answer: dict) -> None:
-        with self._lock:
-            session = self._sessions.get(code)
-            if not session or user_id not in session["answers"]:
-                raise KeyError(code)
-            session["answers"][user_id] = answer
-
-    def end(self, code: str) -> None:
-        with self._lock:
-            if code not in self._sessions:
-                raise KeyError(code)
-            self._sessions.pop(code, None)
-
-    @staticmethod
-    def _public(session: dict) -> dict:
-        return {k: session[k] for k in ("code", "class_id", "class_name", "started_at", "question")}
-
-    def _detail(self, session: dict, user_id: str, teacher: bool, now: float) -> dict:
-        base = self._public(session)
-        if teacher:
-            participants = []
-            joined_emails = set()
-            for uid, person in session["participants"].items():
-                joined_emails.add(person["email"])
-                answer = session["answers"].get(uid)
-                participants.append({"id": uid, "name": person["name"], "email": person["email"],
-                                     "online": now - person["last_seen"] <= PRESENCE_TTL,
-                                     "answer": None if not answer or answer.get("pending") else answer})
-            participants += [{"id": "", "name": name, "email": email, "online": False, "answer": None}
-                             for email, name in session["roster"].items() if email not in joined_emails]
-            return {**base, "participants": participants}
-        answer = session["answers"].get(user_id)
-        return {**base, "answered": user_id in session["answers"],
-                "answer": None if not answer or answer.get("pending") else answer}

app/math_photo.py

@@ -5,8 +5,8 @@ the problem as it read it (so the student can check the reading), the solution a
 not give the step away and the step itself, the final answer, and the path's skill the problem practises. The page
 shows the hints one by one, and the steps and the answer only when the student asks for them.
 
-Runs on the server's Anthropic key (the tutor's, ANTHROPIC_API_KEY or the panel's), on MATH_MODEL (default
-DEFAULT_MODEL). The photo is sent to the API and not kept.
+Runs on the server's ``ANTHROPIC_API_KEY``, using ``MATH_MODEL`` (or ``DEFAULT_MODEL``).
+The photo is sent to the API and is not retained.
 """
 from __future__ import annotations
 

app/model_settings.py

@@ -1,159 +0,0 @@
-"""The scorer's settings a developer tunes per model from the panel's "מודלים" tab (stored in model_settings).
-
-A model starts from ScorerConfig's defaults and FLAG_BELOW_BY_MODEL (scorer.py). A stored row overrides some of them:
-  {"flag_below": 45, "gop.leniency": 0.4, "flag_below_sound": {"ħ": 30, "ʕ": null}}
-`null` for a sound means "the general threshold", which also clears a built-in one (the base model's ħ at 20).
-Settings belong to the model they were tuned on: a threshold means something else under another model's scores.
-"""
-from __future__ import annotations
-
-from dataclasses import replace
-
-from .align import POOLS
-from .scorer import ScorerConfig, scorer_config
-
-CREATE_MODEL_SETTINGS = ("create table public.model_settings (model text primary key, "
-                         "settings jsonb not null default '{}'::jsonb, updated_by text not null default '', "
-                         "updated_at timestamptz not null default now()); "
-                         "alter table public.model_settings enable row level security;")
-
-# key: a ScorerConfig field, or gop.<GopConfig field>. kind: number | int | choice | window (an int, or None: wide)
-FIELDS: list[dict] = [
-    {"key": "flag_below", "group": "flag", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "סף סימון כללי",
-     "help": "הגה שקיבל ציון מתחת לסף מסומן כטעות ומקבל טיפ. הגים עם סף משלהם (למטה) משתמשים בו במקום זה."},
-    {"key": "issue_below", "group": "flag", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "סף \"לא מדויק\"",
-     "help": "הגה מתחת לסף נרשם ברשימת ההגים כלא מדויק, גם בלי טיפ. גם תנועה ארוכה שנאמרה קצרה נמדדת מולו."},
-    {"key": "max_issues", "group": "flag", "kind": "int", "min": 1, "max": 20, "step": 1,
-     "label": "הכי הרבה הגים ברשימה", "help": "כמה הגים לא מדויקים מוצגים לתלמיד לכל היותר בכל הקלטה."},
-    {"key": "unrelated_ratio", "group": "unrelated", "kind": "number", "min": 0.1, "max": 1, "step": 0.05,
-     "label": "סף \"משפט אחר\"",
-     "help": "כמה רחוק מה שנשמע מהמשפט הצפוי עד שהמערכת אומרת שנאמר משפט אחר. גבוה יותר: סלחני יותר."},
-    {"key": "unrelated_veto_share", "group": "unrelated", "kind": "number", "min": 0, "max": 1, "step": 0.05,
-     "label": "וטו: חלק העיצורים שנמצאו",
-     "help": "אם לפחות החלק הזה של העיצורים נמצא בבירור ביישור, המשפט לא ייחשב אחר גם כשהמרחק גדול."},
-    {"key": "unrelated_veto_mean", "group": "unrelated", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "וטו: ציון ממוצע מינימלי", "help": "וטו \"משפט אחר\" חל רק כשהציון הממוצע של ההגים לפחות כזה."},
-    {"key": "near_vowel_floor", "group": "floors", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "תנועה שנשמעה כשכנתה",
-     "help": "ציון מינימום לתנועה שנשמעה כתנועה קרובה (i/e, u/o, קצרה/ארוכה): הבדל שלא כדאי להעניש עליו."},
-    {"key": "ayin_deleted_floor", "group": "floors", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "ע שלא נשמעה",
-     "help": "ציון מינימום ל־ע שהמודל לא שמע בכלל: המודל המקורי מפיל לעתים ע שנאמרה נכון."},
-    {"key": "onset_transient_floor", "group": "floors", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "עיצור ראשון מול רעש פתיחה", "help": "ציון מינימום לעיצור ראשון שהפסיד לקפיצה של פריים אחד בתחילת ההקלטה."},
-    {"key": "ref_noise_floor", "group": "floors", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "הגה שהמודל לא מודד במשפט",
-     "help": "אם הקול הילידי (TTS) קיבל על הגה ציון מתחת לזה, ההגה לא נמדד במשפט הזה והתלמיד מקבל עליו ציון מלא."},
-    {"key": "ref_min_mean", "group": "floors", "kind": "number", "min": 0, "max": 100, "step": 1,
-     "label": "אמינות הקול הילידי",
-     "help": "קול ילידי שהממוצע שלו מתחת לזה לא משמש בסיס להשוואה."},
-    {"key": "word_min_weight", "group": "floors", "kind": "number", "min": 0, "max": 1, "step": 0.05,
-     "label": "משקל ההגה החלש במילה", "help": "כמה הגה אחד חלש מוריד את ציון המילה כולה (0: לא משפיע, 1: קובע לבד)."},
-    {"key": "gop.leniency", "group": "gop", "kind": "number", "min": 0, "max": 1, "step": 0.05,
-     "label": "רכות הציון",
-     "help": "כמה הציון סלחני כשהמוד�� מתלבט בין ההגה הנכון לאחר. 0: ליניארי וקשוח; גבוה יותר: מתחרה כפול עדיין מקבל ציון סביר."},
-    {"key": "gop.confident_peak", "group": "gop", "kind": "number", "min": 0.05, "max": 0.95, "step": 0.05,
-     "label": "ביטחון מספיק", "help": "מאיזו הסתברות של ההגה הנכון השיא כבר לא מוריד את הציון."},
-    {"key": "gop.ratio_pool", "group": "gop", "kind": "choice", "choices": list(POOLS),
-     "label": "איחוד הפריימים", "help": "איך מצרפים את הפריימים של הגה לציון אחד (docs/gop-pooling.md). gated: רק הפריימים הרועשים."},
-    {"key": "gop.energy_gate", "group": "gop", "kind": "number", "min": 0, "max": 1, "step": 0.05,
-     "label": "סף עוצמה (gated)", "help": "פריימים שקטים מהחלק הזה של הפריים החזק ביותר לא נספרים."},
-    {"key": "gop.vowel_window", "group": "gop", "kind": "window", "min": 0, "max": 10,
-     "label": "חלון התנועה", "help": "מכמה פריימים סביב תנועה קוראים את המתחרים שלה. רחב: כמו עיצורים."},
-    {"key": "gop.consonant_window", "group": "gop", "kind": "window", "min": 1, "max": 12,
-     "label": "חלון העיצור", "help": "כמה פריימים של שקט סביב עיצור נכללים בקריאה שלו. רחב: עד ההגה הבא."},
-]
-GROUPS = {"flag": "סימון טעויות", "unrelated": "זיהוי \"משפט אחר\"", "floors": "רצפות והקלות",
-          "gop": "ניקוד ההגה (מתקדם)"}
-FIELD = {f["key"]: f for f in FIELDS}
-
-# Per-sound thresholds: the sounds tokens stand for (TargetToken.sound), grouped as a Hebrew speaker meets them.
-SOUND_GROUPS = [
-    ("גרוניים", [("ħ", "ח (ح)"), ("ʕ", "ע (ع)"), ("h", "ה (ه)"), ("ʔ", "א (ء)"), ("x", "ח׳ (خ)"), ("ɣ", "ע׳ (غ)")]),
-    ("מודגשים", [("tˤ", "ט (ط)"), ("sˤ", "צ (ص)"), ("dˤ", "ד׳ (ض)"), ("ZH", "ט׳ (ظ)")]),
-    ("אותיות עם כמה הגיות", [("Q", "ק (ق)"), ("K", "כ (ك)"), ("J", "ג׳ (ج)"), ("TH", "ת׳ (ث)"), ("DH", "ד״ (ذ)")]),
-    ("עיצורים נוספים", [("r", "ר (ر)"), ("l", "ל (ل)"), ("ʃ", "ש (ش)"), ("s", "ס (س)"), ("z", "ז (ز)"), ("t", "ת (ت)"),
-                        ("d", "ד (د)"), ("k", "כ (ك)"), ("b", "ב (ب)"), ("f", "פ (ف)"), ("m", "מ (م)"), ("n", "נ (ن)"),
-                        ("w", "ו (و)"), ("j", "י (ي)")]),
-]
-SOUNDS = {s for _, group in SOUND_GROUPS for s, _ in group}
-
-
-def _get(cfg: ScorerConfig, key: str):
-    return getattr(cfg.gop, key[4:]) if key.startswith("gop.") else getattr(cfg, key)
-
-
-def defaults(model_id: str) -> dict:
-    """What a model runs with before any stored setting: the fields, and the sounds with a built-in threshold."""
-    cfg = scorer_config(model_id)
-    return {"fields": {f["key"]: _get(cfg, f["key"]) for f in FIELDS}, "sounds": dict(cfg.flag_below_sound)}
-
-
-def clean(raw: dict) -> dict:
-    """A stored or submitted settings object, checked field by field. Raises ValueError (in Hebrew) on a bad one."""
-    if not isinstance(raw, dict):
-        raise ValueError("ההגדרות צריכות להיות אובייקט")
-    out: dict = {}
-    for key, value in raw.items():
-        if key == "flag_below_sound":
-            if not isinstance(value, dict):
-                raise ValueError("ספי ההגים צריכים להיות אובייקט")
-            sounds = {}
-            for sound, t in value.items():
-                if sound not in SOUNDS:
-                    raise ValueError(f"הגה לא מוכר: {sound}")
-                if t is not None and (isinstance(t, bool) or not isinstance(t, (int, float)) or not 0 <= t <= 100):
-                    raise ValueError(f"סף ל־{sound} צריך להיות בין 0 ל־100")
-                sounds[sound] = None if t is None else float(t)
-            out[key] = sounds
-            continue
-        f = FIELD.get(key)
-        if f is None:
-            raise ValueError(f"הגדרה לא מוכרת: {key}")
-        kind = f["kind"]
-        if kind == "choice":
-            if value not in f["choices"]:
-                raise ValueError(f"{f['label']}: ערך לא מוכר")
-        elif kind == "window":
-            if value is not None and (isinstance(value, bool) or not isinstance(value, int)
-                                      or not f["min"] <= value <= f["max"]):
-                raise ValueError(f"{f['label']}: רחב, או מספר פריימים בין {f['min']} ל־{f['max']}")
-        else:
-            if isinstance(value, bool) or not isinstance(value, (int, float)) or not f["min"] <= value <= f["max"]:
-                raise ValueError(f"{f['label']}: ערך בין {f['min']} ל־{f['max']}")
-            if kind == "int" and int(value) != value:
-                raise ValueError(f"{f['label']}: מספר שלם")
-            value = int(value) if kind == "int" else float(value)
-        out[key] = value
-    return out
-
-
-def build(model_id: str, settings: dict | None) -> ScorerConfig:
-    """The model's ScorerConfig with its stored settings applied."""
-    cfg = scorer_config(model_id)
-    settings = clean(settings or {})
-    gop = {k[4:]: v for k, v in settings.items() if k.startswith("gop.")}
-    top = {k: v for k, v in settings.items() if not k.startswith("gop.") and k != "flag_below_sound"}
-    sounds = dict(cfg.flag_below_sound)
-    for sound, t in settings.get("flag_below_sound", {}).items():
-        if t is None:
-            sounds.pop(sound, None)
-        else:
-            sounds[sound] = t
-    return replace(cfg, **top, flag_below_sound=sounds, gop=replace(cfg.gop, **gop))
-
-
-def describe(model_id: str, settings: dict | None, sound_counts: dict[str, int]) -> dict:
-    """Everything the tab draws: each field with its default and value, each sound with its threshold."""
-    base, cfg = defaults(model_id), build(model_id, settings)
-    stored = clean(settings or {})
-    fields = [{**f, "group_label": GROUPS[f["group"]], "default": base["fields"][f["key"]], "value": _get(cfg, f["key"]),
-               "changed": f["key"] in stored} for f in FIELDS]
-    stored_sounds = stored.get("flag_below_sound", {})
-    sounds = [{"group": name, "sounds": [{"sound": s, "label": label, "count": sound_counts.get(s, 0),
-                                          "default": base["sounds"].get(s), "value": cfg.flag_below_sound.get(s),
-                                          "changed": s in stored_sounds} for s, label in group]}
-              for name, group in SOUND_GROUPS]
-    return {"fields": fields, "sounds": sounds, "general": cfg.flag_below}

app/models.py

@@ -1,107 +0,0 @@
-"""The phoneme models the management panel's "מודלים" tab offers, with what each was measured to do.
-
-Numbers: Minerva test split (255 native lines), greedy CTC mapped onto the labels' phonemes, measured 2026-10-25
-with scripts/zero_shot_phone_models.py (docs/zero-shot-phone-models.md). Speeds: one 2.7 s recording, on this
-project's laptop GPU and on 2 CPU threads (about what the free Space has). POWSM runs padded to 8 s (app/powsm.py):
-its PER, consonant PER and long vowels below are measured that way; its other sounds at the 20 s they were first
-measured at (8 s changed PER by 0.4 points). The short-padding fine-tune runs unpadded, measured that way throughout.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-import os
-
-from .powsm import DEPS, ONNX_PREFIX, parse_model_id
-
-# the Hub repo the exported POWSM is uploaded to (scripts/export_powsm_onnx.py; README "POWSM on the Space")
-POWSM_ONNX_REPO = os.environ.get("POWSM_ONNX_REPO", "wzender/ihki-powsm-ft").strip()
-
-ROOT = Path(__file__).resolve().parent.parent
-
-# Per model: recall of each sound (None: the model has no symbol for it), PER and consonant PER.
-CATALOG: list[dict] = [
-    {"id": "facebook/wav2vec2-xlsr-53-espeak-cv-ft", "name": "Facebook (מקורי)", "family": "wav2vec2",
-     "summary": "המודל הרב־לשוני שהאתר נבנה עליו. לא אומן על ערבית פלסטינית: כמעט לא שומע ח ו־ע.",
-     "trained": False, "free_space": True,
-     "metrics": {"per": .38, "consonant_per": .29, "ħ": .09, "ʕ": .02, "tˤ": None, "sˤ": None, "dˤ": 0.0,
-                 "long_vowels": .45},
-     "speed": {"gpu": .05, "cpu": .8}, "fps": 50},
-    {"id": "checkpoints/ihki-ft-minerva", "name": "wav2vec2 מאומן", "family": "wav2vec2",
-     "summary": "אותו מודל, מאומן על הקלטות Minerva. מחליף ישיר: אותו גודל ואותה מהירות, גם על השרת החינמי.",
-     "trained": True, "free_space": True,
-     "metrics": {"per": .23, "consonant_per": .15, "ħ": .94, "ʕ": .69, "tˤ": None, "sˤ": None, "dˤ": .04,
-                 "long_vowels": .74},
-     "speed": {"gpu": .05, "cpu": .8}, "fps": 50},
-    {"id": "checkpoints/powsm-ft-minerva/powsm_ft.pt", "name": "POWSM מאומן", "family": "POWSM-CTC",
-     "summary": "מודל פונטי חדש (2026), מאומן על הקלטות Minerva. הכי מדויק, והיחיד ששומע את העיצורים המודגשים (ط ص ض).",
-     "trained": True, "free_space": False,
-     "metrics": {"per": .16, "consonant_per": .10, "ħ": .94, "ʕ": .89, "tˤ": .82, "sˤ": .77, "dˤ": .46,
-                 "long_vowels": .68},
-     "speed": {"gpu": .29, "cpu": 1.8}, "fps": 25},
-    {"id": "checkpoints/powsm-ft-shortpad/powsm_ft.pt", "name": "POWSM מאומן ומהיר", "family": "POWSM-CTC",
-     "summary": "אותו POWSM מאומן, שאומן שוב גם על הקלטות קצרות בלי ריפוד: מדויק כמו המקורי ומהיר פי 5 במעבד.",
-     "trained": True, "free_space": True,
-     "metrics": {"per": .16, "consonant_per": .105, "ħ": .92, "ʕ": .90, "tˤ": .81, "sˤ": .68, "dˤ": .64,
-                 "long_vowels": .69},
-     "speed": {"gpu": .06, "cpu": .8}, "fps": 25},
-    {"id": f"{ONNX_PREFIX}{POWSM_ONNX_REPO}", "name": "POWSM מאומן ומהיר (לשרת)", "family": "POWSM-CTC · ONNX",
-     "summary": "אותו מודל, מיוצא ל־ONNX: רץ בלי ESPnet, גם על השרת החינמי, ומהיר מהמודל הנוכחי. נטען מ־Hugging Face.",
-     "trained": True, "free_space": True,
-     "metrics": {"per": .165, "consonant_per": .105, "ħ": .92, "ʕ": .90, "tˤ": .81, "sˤ": .68, "dˤ": .64,
-                 "long_vowels": .69},
-     "speed": {"gpu": None, "cpu": .57}, "fps": 25},
-    {"id": "exports/powsm-ft-shortpad", "name": "POWSM מאומן ומהיר (ONNX מקומי)", "family": "POWSM-CTC · ONNX",
-     "summary": "הייצוא ל־ONNX מהתיקייה המקומית, לפני ההעלאה ל־Hugging Face.",
-     "trained": True, "free_space": True,
-     "metrics": {"per": .165, "consonant_per": .105, "ħ": .92, "ʕ": .90, "tˤ": .81, "sˤ": .68, "dˤ": .64,
-                 "long_vowels": .69},
-     "speed": {"gpu": None, "cpu": .57}, "fps": 25},
-    {"id": "powsm:<ara>", "name": "POWSM (מקורי)", "family": "POWSM-CTC",
-     "summary": "POWSM כפי שפורסם, עם הנחיית ערבית. שומע ח ו־ע היטב בלי אימון, אבל לא כותב תנועות ארוכות.",
-     "trained": False, "free_space": False,
-     "metrics": {"per": .37, "consonant_per": .22, "ħ": .87, "ʕ": .85, "tˤ": .66, "sˤ": .72, "dˤ": .54,
-                 "long_vowels": 0.0},
-     "speed": {"gpu": .29, "cpu": 1.8}, "fps": 25},
-]
-
-
-def availability(model_id: str) -> tuple[bool, str]:
-    """(can this server load it, why not). A Hub id counts as loadable: it downloads on first use."""
-    if model_id.startswith(ONNX_PREFIX) or (Path(model_id) / "powsm_onnx.json").is_file():
-        try:
-            import onnxruntime  # noqa: F401
-        except ImportError:
-            return False, "חסרה החבילה onnxruntime בשרת (requirements.txt)"
-        return True, ""
-    if model_id.startswith("exports/"):
-        return False, "הייצוא ל־ONNX לא נמצא בשרת (scripts/export_powsm_onnx.py)"
-    powsm = parse_model_id(model_id)
-    if powsm:
-        if not (DEPS / "pkgs").exists():
-            return False, "חסרות חבילות ההרצה של POWSM בשרת (scripts/setup_zero_shot_deps.sh)"
-        if powsm[1] and not Path(powsm[1]).is_file():
-            return False, "קובץ המודל לא נמצא בשרת"
-        return True, ""
-    local = Path(model_id)
-    if model_id.startswith(("checkpoints/", "./", "/")) or local.exists():
-        if not (local / "config.json").is_file():
-            return False, "תיקיית המודל לא נמצאה בשרת"
-        return True, ""
-    return True, ""
-
-
-def catalog(active: str) -> list[dict]:
-    """Every catalog model, plus the active one when it isn't in the catalog (a MODEL_ID of its own)."""
-    rows = [dict(m) for m in CATALOG]
-    if not any(m["id"] == active for m in rows):
-        rows.insert(0, {"id": active, "name": "מודל מותאם", "family": "", "summary": "הוגדר ב־MODEL_ID; לא נמדד כאן.",
-                        "trained": None, "free_space": None, "metrics": None, "speed": None, "fps": None})
-    for m in rows:
-        m["available"], m["why"] = availability(m["id"])
-        m["active"] = m["id"] == active
-    return rows
-
-
-def known(model_id: str) -> bool:
-    return any(m["id"] == model_id for m in CATALOG)

app/monitoring.py

@@ -1,718 +0,0 @@
-"""Read-only, privacy-preserving monitoring shared by MCP callers."""
-from __future__ import annotations
-
-import hashlib
-import math
-from collections import defaultdict
-from datetime import date, datetime, time, timedelta, timezone
-from typing import Any, Literal
-from zoneinfo import ZoneInfo
-
-from .access import has_permission
-from .auth import AuthUnavailable
-from .class_management import ClassManagementError, visible_classes
-
-
-LOCAL_TZ = ZoneInfo("Asia/Jerusalem")
-MAX_DAYS = 90
-INTERVALS = frozenset({"day", "week", "month"})
-STATUSES = frozenset({"healthy", "degraded", "unavailable", "not_configured"})
-SUCCESS_SCORE = 75
-MIN_DIFFICULTY_STUDENTS = 3
-MIN_DIFFICULTY_ATTEMPTS = 5
-MAX_DIFFICULTY_RESULTS = 20
-MAX_ANALYTICS_RESULTS = 50
-EXERCISE_TYPES = frozenset({"pronunciation", "verb", "game", "other"})
-CURRENT_ACTIVITY_WINDOWS = frozenset({5, 15})
-
-
-class MonitoringError(ValueError):
-    """A safe monitoring error suitable for returning through MCP."""
-
-
-class MonitoringUnavailable(MonitoringError):
-    pass
-
-
-def _date(value: object, label: str) -> date:
-    if not isinstance(value, str):
-        raise MonitoringError(f"{label} חייב להיות תאריך בפורמט YYYY-MM-DD")
-    try:
-        parsed = date.fromisoformat(value)
-    except ValueError as exc:
-        raise MonitoringError(f"{label} חייב להיות תאריך בפורמט YYYY-MM-DD") from exc
-    if parsed.isoformat() != value:
-        raise MonitoringError(f"{label} חייב להיות תאריך בפורמט YYYY-MM-DD")
-    return parsed
-
-
-def validate_range(from_date: object, to_date: object, interval: object,
-                   *, today: date | None = None) -> tuple[date, date, str]:
-    start, end = _date(from_date, "from_date"), _date(to_date, "to_date")
-    current = today or datetime.now(LOCAL_TZ).date()
-    if interval not in INTERVALS:
-        raise MonitoringError("interval חייב להיות day, week או month")
-    if start > end:
-        raise MonitoringError("from_date חייב להיות לפני או שווה ל-to_date")
-    if start > current or end > current:
-        raise MonitoringError("אי אפשר לבקש טווח עתידי")
-    if (end - start).days + 1 > MAX_DAYS:
-        raise MonitoringError("אפשר לבקש עד 90 ימים")
-    return start, end, str(interval)
-
-
-def _scope(auth: Any, actor: dict[str, Any], class_id: int | None) -> tuple[list[dict], dict[str, Any]]:
-    if not has_permission(actor, "management.access"):
-        raise MonitoringError("אין הרשאת ניהול")
-    try:
-        classes = visible_classes(auth, actor, fresh=True)
-    except ClassManagementError as exc:
-        raise MonitoringUnavailable("נתוני הפעילות אינם זמינים") from exc
-    if class_id is not None:
-        if not isinstance(class_id, int) or isinstance(class_id, bool) or class_id <= 0:
-            raise MonitoringError("מזהה הכיתה אינו תקין")
-        selected = [row for row in classes if row.get("id") == class_id]
-        if not selected:
-            raise MonitoringError("הכיתה אינה זמינה")
-        row = selected[0]
-        return selected, {"class_id": row["id"], "class_name": row.get("name", "")}
-    return classes, {"class_id": None, "class_name": "כל הכיתות המורשות"}
-
-
-def _scoped_user_ids(auth: Any, classes: list[dict]) -> set[str]:
-    emails = {str(email).strip().lower() for row in classes for email in row.get("emails", ()) if email}
-    if not emails:
-        return set()
-    users = auth.users()
-    return {str(user["id"]) for user in users
-            if str(user.get("email") or "").strip().lower() in emails and user.get("id")}
-
-
-def _stamp(value: object) -> datetime:
-    text = str(value or "").replace("Z", "+00:00")
-    parsed = datetime.fromisoformat(text)
-    return (parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)).astimezone(LOCAL_TZ)
-
-
-def _period_key(day: date, interval: str) -> date:
-    if interval == "day":
-        return day
-    if interval == "week":
-        return day - timedelta(days=day.weekday())
-    return day.replace(day=1)
-
-
-def activity_timeseries(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
-                        interval: object = "day", class_id: int | None = None,
-                        today: date | None = None) -> dict[str, Any]:
-    start, end, clean_interval = validate_range(from_date, to_date, interval, today=today)
-    classes, scope = _scope(auth, actor, class_id)
-    try:
-        user_ids = _scoped_user_ids(auth, classes)
-        since = datetime.combine(start, time.min, LOCAL_TZ).astimezone(timezone.utc)
-        raw = auth.scoped_activity(user_ids, since, 60)
-    except (AuthUnavailable, AttributeError, KeyError, TypeError) as exc:
-        raise MonitoringUnavailable("נתוני הפעילות אינם זמינים") from exc
-
-    keys: list[date] = []
-    cursor = start
-    while cursor <= end:
-        key = _period_key(cursor, clean_interval)
-        if not keys or keys[-1] != key:
-            keys.append(key)
-        cursor += timedelta(days=1)
-    grouped = {key: {"date": key.isoformat(), "attempts": 0, "peak_active_students": 0} for key in keys}
-    for item in raw.get("buckets", ()) if isinstance(raw, dict) else ():
-        try:
-            local_day = _stamp(item.get("bucket")).date()
-            if not start <= local_day <= end:
-                continue
-            bucket = grouped.get(_period_key(local_day, clean_interval))
-            if bucket is None:
-                continue
-            bucket["attempts"] += max(0, int(item.get("attempts") or 0))
-            bucket["peak_active_students"] = max(
-                bucket["peak_active_students"], max(0, int(item.get("active_students") or 0)))
-        except (TypeError, ValueError, OverflowError):
-            continue
-
-    summary = raw.get("summary") if isinstance(raw, dict) and isinstance(raw.get("summary"), dict) else {}
-    safe_summary = {key: max(0, int(summary.get(key) or 0))
-                    for key in ("attempts", "active_students", "returning_students", "active_days")}
-    return {**scope, "from_date": start.isoformat(), "to_date": end.isoformat(),
-            "interval": clean_interval, "series": list(grouped.values()), "summary": safe_summary}
-
-
-def _utc_iso(value: datetime) -> str:
-    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-
-
-def _activity_stamp(value: object) -> datetime | None:
-    try:
-        return _stamp(value).astimezone(timezone.utc)
-    except (TypeError, ValueError, OverflowError):
-        return None
-
-
-def current_activity(auth: Any, actor: dict[str, Any], *, window_minutes: object = 5,
-                     class_id: int | None = None, checked_at: datetime | None = None,
-                     live_store: Any = None) -> dict[str, Any]:
-    """Return scoped aggregate recency without treating recent attempts as presence."""
-    if (not isinstance(window_minutes, int) or isinstance(window_minutes, bool)
-            or window_minutes not in CURRENT_ACTIVITY_WINDOWS):
-        raise MonitoringError("window_minutes חייב להיות 5 או 15")
-    now = checked_at or datetime.now(timezone.utc)
-    if now.tzinfo is None:
-        now = now.replace(tzinfo=timezone.utc)
-    now = now.astimezone(timezone.utc)
-    classes, scope = _scope(auth, actor, class_id)
-    try:
-        user_ids = _scoped_user_ids(auth, classes)
-        since = now - timedelta(minutes=window_minutes)
-        rows, truncated = auth.scoped_attempts(user_ids, since, now + timedelta(microseconds=1))
-    except (AuthUnavailable, AttributeError, KeyError, TypeError) as exc:
-        raise MonitoringUnavailable("נתוני הפעילות אינם זמינים") from exc
-    if truncated:
-        raise MonitoringError("יש יותר מדי אירועים בחלון. נסו חלון קצר יותר.")
-
-    events: dict[str, tuple[str, datetime]] = {}
-    for index, row in enumerate(rows if isinstance(rows, list) else []):
-        user_id = str(row.get("user_id") or "") if isinstance(row, dict) else ""
-        stamp = _activity_stamp(row.get("created_at")) if isinstance(row, dict) else None
-        if not user_id or user_id not in user_ids or stamp is None or not since <= stamp <= now:
-            continue
-        event_id = str(row.get("id") or f"row-{index}")
-        events.setdefault(event_id, (user_id, stamp))
-
-    attempts = len(events)
-    learners = len({user_id for user_id, _ in events.values()})
-    checked_iso = _utc_iso(now)
-    threshold = {"minimum_students": MIN_DIFFICULTY_STUDENTS,
-                 "minimum_attempts": MIN_DIFFICULTY_ATTEMPTS}
-    recent: dict[str, Any] = {
-        "source": "persisted_attempts", "window_minutes": window_minutes,
-        "checked_at": checked_iso, "collection_delay_seconds": None,
-        "update_semantics": "current_as_of_database_read",
-        "presence_claim": False,
-    }
-    last_practice: dict[str, Any] = {"source": "persisted_attempts", "checked_at": checked_iso}
-    if not events:
-        recent["status"] = "no_activity"
-        last_practice.update(status="no_data", reason_code="no_observation_in_window")
-    elif learners < MIN_DIFFICULTY_STUDENTS or attempts < MIN_DIFFICULTY_ATTEMPTS:
-        recent["status"] = "suppressed"
-        last_practice.update(status="suppressed", reason_code="privacy_threshold")
-    else:
-        latest = max(stamp for _, stamp in events.values())
-        recent.update(status="complete", students_with_activity=learners, attempts=attempts)
-        last_practice.update(
-            status="complete", event_type="practice_attempt", timestamp=_utc_iso(latest),
-            local_timestamp=latest.astimezone(LOCAL_TZ).isoformat(), timezone="Asia/Jerusalem",
-            elapsed_seconds=max(0, int((now - latest).total_seconds())),
-        )
-    live_presence: dict[str, Any] = {
-        "status": "unavailable", "reason_code": "no_active_live_session",
-        "source": "live_session_heartbeat", "checked_at": checked_iso,
-    }
-    if live_store is not None:
-        try:
-            summary = live_store.presence_summary({int(row["id"]) for row in classes if row.get("id") is not None})
-            if summary.get("active_session"):
-                active = max(0, int(summary.get("active_users") or 0))
-                live_presence = {
-                    "status": "suppressed" if len(user_ids) < MIN_DIFFICULTY_STUDENTS or active in {1, 2}
-                    else "complete",
-                    "source": "live_session_heartbeat", "checked_at": checked_iso,
-                    "heartbeat_ttl_seconds": max(1, int(summary.get("heartbeat_ttl_seconds") or 20)),
-                    "ephemeral": True,
-                    "definition": "heartbeat_received_within_ttl",
-                }
-                if live_presence["status"] == "complete":
-                    live_presence["active_users"] = active
-                else:
-                    live_presence["reason_code"] = "privacy_threshold"
-        except (AttributeError, KeyError, TypeError, ValueError):
-            live_presence = {
-                "status": "unavailable", "reason_code": "live_source_unavailable",
-                "source": "live_session_heartbeat", "checked_at": checked_iso,
-            }
-    return {
-        **scope, "status": recent["status"], "checked_at": checked_iso,
-        "timezone": "Asia/Jerusalem", "privacy_threshold": threshold,
-        "recent_practice": recent,
-        "live_presence": live_presence,
-        "last_practice_activity": last_practice,
-        "last_application_activity": {
-            "status": "unavailable", "reason_code": "not_collected",
-            "checked_at": checked_iso,
-            "note": "General application activity is not stored; missing practice does not imply no app use.",
-        },
-    }
-
-
-def _exercise_id(category: str, phrase: str) -> str:
-    return hashlib.sha256(f"{category}\0{phrase}".encode()).hexdigest()[:12]
-
-
-def _catalog() -> dict[str, dict[str, Any]]:
-    try:
-        from .phrases import CATEGORIES, GAMES
-        categories = {str(row["id"]): row for row in [*CATEGORIES, *GAMES]}
-    except (ImportError, KeyError, TypeError):
-        categories = {}
-    return categories
-
-
-def _metadata(category: str, phrase: str) -> dict[str, Any]:
-    row = _catalog().get(category, {})
-    unit = str(row.get("unit") or "")
-    if category == "verb-game" or "פועל" in unit:
-        kind = "verb"
-    elif row.get("bubble") or category.startswith("game-"):
-        kind = "game"
-    elif row:
-        kind = "pronunciation"
-    else:
-        kind = "other"
-    return {"exercise_id": _exercise_id(category, phrase), "exercise_name": phrase,
-            "exercise_type": kind, "topic": row.get("name"), "lesson": row.get("lesson")}
-
-
-def normalize_attempts(rows: list[dict]) -> list[dict[str, Any]]:
-    normalized = []
-    for row in rows:
-        try:
-            user_id, category = str(row.get("user_id") or "").strip(), str(row.get("cat") or "").strip()
-            phrase = " ".join(str(row.get("phrase") or "").split())
-            score = float(row.get("score"))
-            stamp = _stamp(row.get("created_at"))
-            if not user_id or not category or not phrase or not math.isfinite(score):
-                continue
-            score = max(0.0, min(100.0, score))
-            issues = []
-            for issue in row.get("issues") or []:
-                if not isinstance(issue, dict):
-                    continue
-                expected = str(issue.get("expected") or "").strip()[:20]
-                heard = str(issue.get("heard") or "").strip()[:20]
-                if not expected:
-                    continue
-                word = issue.get("word")
-                issues.append({"expected": expected, "heard": heard,
-                               "word": word if isinstance(word, int) and not isinstance(word, bool) else None,
-                               "score": issue.get("score")})
-            normalized.append({"id": int(row.get("id") or 0), "user_id": user_id,
-                               "category": category, "phrase": phrase, "score": score,
-                               "unrelated": bool(row.get("unrelated")), "stamp": stamp,
-                               "local_date": stamp.date(), "issues": issues,
-                               "model": str(row.get("model") or ""),
-                               "version": str(row.get("version") or ""),
-                               **_metadata(category, phrase)})
-        except (TypeError, ValueError, OverflowError):
-            continue
-    return normalized
-
-
-def _threshold(value: object, *, default: int = MIN_DIFFICULTY_ATTEMPTS) -> int:
-    if value is None:
-        return max(MIN_DIFFICULTY_ATTEMPTS, default)
-    if not isinstance(value, int) or isinstance(value, bool) or value < 1 or value > 10_000:
-        raise MonitoringError("min_attempts חייב להיות מספר בין 1 ל-10000")
-    return max(MIN_DIFFICULTY_ATTEMPTS, value if value is not None else default)
-
-
-def _exercise_metrics(items: list[dict[str, Any]]) -> dict[str, Any]:
-    students: dict[str, list[dict[str, Any]]] = defaultdict(list)
-    for item in items:
-        students[item["user_id"]].append(item)
-    successes = sum(not item["unrelated"] and item["score"] >= SUCCESS_SCORE for item in items)
-    first_success, never, changes = [], 0, []
-    for learner_items in students.values():
-        ordered = sorted(learner_items, key=lambda item: (item["stamp"], item["id"]))
-        succeeded = [at for at, item in enumerate(ordered, 1)
-                     if not item["unrelated"] and item["score"] >= SUCCESS_SCORE]
-        if succeeded:
-            first_success.append(succeeded[0])
-        else:
-            never += 1
-        if len(ordered) >= 2:
-            changes.append(ordered[-1]["score"] - ordered[0]["score"])
-    count, learners = len(items), len(students)
-    return {"total_attempts": count, "unique_students": learners,
-            "successful_attempts": successes,
-            "success_rate": round(successes * 100 / count, 1) if count else None,
-            "average_attempts_per_student": round(count / learners, 2) if learners else None,
-            "average_score": round(sum(item["score"] for item in items) / count, 1) if count else None,
-            "average_attempts_to_first_success": round(sum(first_success) / len(first_success), 2)
-            if first_success else None, "never_succeeded_students": never,
-            "average_score_change": round(sum(changes) / len(changes), 1) if changes else None}
-
-
-def aggregate_exercise_difficulty(rows: list[dict], *, limit: int,
-                                  min_attempts: int = MIN_DIFFICULTY_ATTEMPTS,
-                                  exercise_type: str | None = None) -> list[dict[str, Any]]:
-    grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
-    for item in normalize_attempts(rows):
-        if exercise_type and item["exercise_type"] != exercise_type:
-            continue
-        grouped[item["exercise_id"]].append(item)
-    ranked = []
-    for exercise_id, items in grouped.items():
-        metrics = _exercise_metrics(items)
-        if metrics["unique_students"] < MIN_DIFFICULTY_STUDENTS or metrics["total_attempts"] < min_attempts:
-            continue
-        first = items[0]
-        ranked.append({"exercise_id": exercise_id, "exercise_name": first["exercise_name"],
-                       "exercise_type": first["exercise_type"], "topic": first["topic"],
-                       "category": first["category"], "exercise": first["phrase"], **metrics,
-                       "attempt_count": metrics["total_attempts"],
-                       "student_count": metrics["unique_students"]})
-    ranked.sort(key=lambda item: (item["success_rate"],
-                                  -(item["average_attempts_to_first_success"] or math.inf),
-                                  -item["total_attempts"], item["exercise_id"]))
-    for at, item in enumerate(ranked[:limit], 1):
-        item["difficulty_rank"] = at
-    return ranked[:limit]
-
-
-def exercise_difficulty(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
-                        class_id: int | None = None, limit: object = 20,
-                        exercise_type: str | None = None, min_attempts: object = None,
-                        today: date | None = None) -> dict[str, Any]:
-    start, end, _ = validate_range(from_date, to_date, "day", today=today)
-    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= MAX_DIFFICULTY_RESULTS:
-        raise MonitoringError("limit חייב להיות מספר בין 1 ל-20")
-    if exercise_type is not None and exercise_type not in EXERCISE_TYPES:
-        raise MonitoringError("exercise_type אינו מוכר")
-    effective = _threshold(min_attempts, default=MIN_DIFFICULTY_ATTEMPTS)
-    classes, scope = _scope(auth, actor, class_id)
-    try:
-        user_ids = _scoped_user_ids(auth, classes)
-        since = datetime.combine(start, time.min, LOCAL_TZ).astimezone(timezone.utc)
-        until = datetime.combine(end + timedelta(days=1), time.min, LOCAL_TZ).astimezone(timezone.utc)
-        rows, truncated = auth.scoped_attempts(user_ids, since, until)
-    except (AuthUnavailable, AttributeError, KeyError, TypeError) as exc:
-        raise MonitoringUnavailable("נתוני הקושי אינם זמינים") from exc
-    if truncated:
-        raise MonitoringError("יש יותר מדי ניסיונות לניתוח מלא. צמצמו את טווח התאריכים או בחרו כיתה אחת.")
-    exercises = aggregate_exercise_difficulty(rows, limit=limit, min_attempts=effective,
-                                              exercise_type=exercise_type)
-    return {**scope, "from_date": start.isoformat(), "to_date": end.isoformat(),
-            "status": "complete" if exercises else "insufficient_data", "success_score": SUCCESS_SCORE,
-            "exercise_type": exercise_type,
-            "privacy_threshold": {"minimum_students": MIN_DIFFICULTY_STUDENTS,
-                                  "minimum_attempts": effective},
-            "definitions": {"success": "score >= 75 and unrelated = false",
-                            "first_attempt": "first observed attempt in requested range"},
-            "exercises": exercises, "returned": len(exercises)}
-
-
-def pronunciation_difficulties(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
-                               class_id: int | None = None, limit: object = 20,
-                               min_attempts: object = 5, today: date | None = None) -> dict[str, Any]:
-    start, end, _ = validate_range(from_date, to_date, "day", today=today)
-    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= MAX_ANALYTICS_RESULTS:
-        raise MonitoringError("limit חייב להיות מספר בין 1 ל-50")
-    effective = _threshold(min_attempts)
-    classes, scope = _scope(auth, actor, class_id)
-    try:
-        user_ids = _scoped_user_ids(auth, classes)
-        since = datetime.combine(start, time.min, LOCAL_TZ).astimezone(timezone.utc)
-        until = datetime.combine(end + timedelta(days=1), time.min, LOCAL_TZ).astimezone(timezone.utc)
-        result = auth.scoped_attempts(user_ids, since, until, include_diagnostics=True)
-        rows, truncated, diagnostics = result
-    except (AuthUnavailable, AttributeError, KeyError, TypeError, ValueError) as exc:
-        raise MonitoringUnavailable("נתוני ההגייה אינם זמינים") from exc
-    if truncated:
-        raise MonitoringError("יש יותר מדי ניסיונות לניתוח מלא. צמצמו את הטווח או בחרו כיתה אחת.")
-    base = {**scope, "from_date": start.isoformat(), "to_date": end.isoformat(),
-            "privacy_threshold": {"minimum_students": MIN_DIFFICULTY_STUDENTS,
-                                  "minimum_attempts": effective}}
-    if not diagnostics:
-        return {**base, "status": "insufficient_data", "diagnostics_available": False,
-                "phonemes": [], "returned": 0}
-    attempts = normalize_attempts(rows)
-    evaluated = [item for item in attempts if not item["unrelated"] and item["model"]]
-    groups: dict[str, dict[str, Any]] = defaultdict(lambda: {
-        "attempts": set(), "students": set(), "scores": [], "examples": set(), "dates": defaultdict(int)})
-    for item in evaluated:
-        words = item["phrase"].split()
-        for issue in item["issues"]:
-            group = groups[issue["expected"]]
-            group["attempts"].add((item["user_id"], item["id"]))
-            group["students"].add(item["user_id"])
-            group["dates"][_period_key(item["local_date"], "week")] += 1
-            try:
-                score = float(issue["score"])
-                if math.isfinite(score):
-                    group["scores"].append(max(0.0, min(100.0, score)))
-            except (TypeError, ValueError):
-                pass
-            word = issue["word"]
-            if word is not None and 0 <= word < len(words):
-                group["examples"].add(words[word])
-    phonemes = []
-    for phoneme, group in groups.items():
-        count, learners = len(group["attempts"]), len(group["students"])
-        if count < effective or learners < MIN_DIFFICULTY_STUDENTS:
-            continue
-        dates = sorted(group["dates"])
-        trend = (group["dates"][dates[-1]] - group["dates"][dates[0]]) if len(dates) >= 2 else None
-        phonemes.append({"phoneme": phoneme, "example_words": sorted(group["examples"])[:5],
-                         "total_evaluated_attempts": len(evaluated), "error_attempts": count,
-                         "pronunciation_error_rate": None, "affected_students": learners,
-                         "average_pronunciation_score": round(sum(group["scores"]) / len(group["scores"]), 1)
-                         if group["scores"] else None,
-                         "trend": {"interval": "week", "error_attempt_change": trend}})
-    phonemes.sort(key=lambda item: (-item["affected_students"], -item["error_attempts"], item["phoneme"]))
-    phonemes = phonemes[:limit]
-    return {**base, "status": "complete" if phonemes else "insufficient_data",
-            "diagnostics_available": True,
-            "diagnostic_coverage": {"evaluated_attempts": len(evaluated), "scored_attempts": len(attempts)},
-            "rate_note": "null: stored diagnostics contain flagged errors but not correct phoneme exposure",
-            "phonemes": phonemes, "returned": len(phonemes)}
-
-
-def _read_attempts(auth: Any, classes: list[dict], start: date, end: date) -> list[dict[str, Any]]:
-    try:
-        user_ids = _scoped_user_ids(auth, classes)
-        since = datetime.combine(start, time.min, LOCAL_TZ).astimezone(timezone.utc)
-        until = datetime.combine(end + timedelta(days=1), time.min, LOCAL_TZ).astimezone(timezone.utc)
-        rows, truncated = auth.scoped_attempts(user_ids, since, until)
-    except (AuthUnavailable, AttributeError, KeyError, TypeError, ValueError) as exc:
-        raise MonitoringUnavailable("נתוני הלמידה אינם זמינים") from exc
-    if truncated:
-        raise MonitoringError("יש יותר מדי ניסיונות לניתוח מלא. צמצמו את הטווח או בחרו כיתה אחת.")
-    return normalize_attempts(rows)
-
-
-def _rate(numerator: int, denominator: int) -> float | None:
-    return round(numerator * 100 / denominator, 1) if denominator else None
-
-
-def learning_progress(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
-                      class_id: int | None = None, exercise_id: str | None = None,
-                      interval: object = "week", min_attempts: object = 5,
-                      today: date | None = None) -> dict[str, Any]:
-    start, end, clean_interval = validate_range(from_date, to_date, interval, today=today)
-    effective = _threshold(min_attempts)
-    classes, scope = _scope(auth, actor, class_id)
-    attempts = _read_attempts(auth, classes, start, end)
-    if exercise_id is not None:
-        if not isinstance(exercise_id, str) or len(exercise_id) != 12:
-            raise MonitoringError("התרגיל אינו זמין")
-        attempts = [item for item in attempts if item["exercise_id"] == exercise_id]
-        if not attempts:
-            raise MonitoringError("התרגיל אינו זמין")
-
-    ordered = sorted(attempts, key=lambda item: (item["stamp"], item["id"]))
-    seen: set[tuple[str, str]] = set()
-    for item in ordered:
-        key = item["user_id"], item["exercise_id"]
-        item["retry"] = key in seen
-        seen.add(key)
-    keys, cursor = [], start
-    while cursor <= end:
-        key = _period_key(cursor, clean_interval)
-        if not keys or keys[-1] != key:
-            keys.append(key)
-        cursor += timedelta(days=1)
-    grouped: dict[date, list[dict[str, Any]]] = {key: [] for key in keys}
-    for item in ordered:
-        key = _period_key(item["local_date"], clean_interval)
-        if key in grouped:
-            grouped[key].append(item)
-    series = []
-    for key, items in grouped.items():
-        learners = {item["user_id"] for item in items}
-        if len(items) < effective or len(learners) < MIN_DIFFICULTY_STUDENTS:
-            series.append({"date": key.isoformat(), "status": "insufficient_data", "attempts": 0,
-                           "unique_students": 0, "success_rate": None, "average_score": None,
-                           "first_attempt_success_rate": None, "repeated_attempt_success_rate": None})
-            continue
-        first = [item for item in items if not item["retry"]]
-        retries = [item for item in items if item["retry"]]
-        success = lambda item: not item["unrelated"] and item["score"] >= SUCCESS_SCORE
-        series.append({"date": key.isoformat(), "status": "complete", "attempts": len(items),
-                       "unique_students": len(learners),
-                       "success_rate": _rate(sum(success(item) for item in items), len(items)),
-                       "average_score": round(sum(item["score"] for item in items) / len(items), 1),
-                       "first_attempt_success_rate": _rate(sum(success(item) for item in first), len(first)),
-                       "repeated_attempt_success_rate": _rate(sum(success(item) for item in retries), len(retries))})
-    measured = [item for item in series if item["status"] == "complete"]
-    trend = (round(measured[-1]["average_score"] - measured[0]["average_score"], 1)
-             if len(measured) >= 2 else None)
-    return {**scope, "from_date": start.isoformat(), "to_date": end.isoformat(),
-            "interval": clean_interval, "exercise_id": exercise_id,
-            "status": "complete" if measured else "insufficient_data",
-            "privacy_threshold": {"minimum_students": MIN_DIFFICULTY_STUDENTS,
-                                  "minimum_attempts": effective},
-            "definitions": {"success": "score >= 75 and unrelated = false",
-                            "first_attempt": "first observed attempt in requested range"},
-            "series": series, "improvement_trend": trend}
-
-
-def compare_class_difficulties(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
-                               class_ids: list[int] | None = None, exercise_type: str | None = None,
-                               min_attempts: object = 5, today: date | None = None) -> dict[str, Any]:
-    start, end, _ = validate_range(from_date, to_date, "day", today=today)
-    effective = _threshold(min_attempts)
-    if exercise_type is not None and exercise_type not in EXERCISE_TYPES:
-        raise MonitoringError("exercise_type אינו מוכר")
-    visible, _ = _scope(auth, actor, None)
-    by_id = {row.get("id"): row for row in visible}
-    if class_ids is None:
-        selected = visible
-    else:
-        if (not isinstance(class_ids, list) or not class_ids or
-                any(not isinstance(item, int) or isinstance(item, bool) or item <= 0 for item in class_ids)):
-            raise MonitoringError("class_ids אינה רשימה תקינה")
-        if len(set(class_ids)) != len(class_ids) or any(item not in by_id for item in class_ids):
-            raise MonitoringError("אחת הכיתות אינה זמינה")
-        selected = [by_id[item] for item in class_ids]
-    user_sets = {int(row["id"]): _scoped_user_ids(auth, [row]) for row in selected}
-    overlap = any(user_sets[a] & user_sets[b] for at, a in enumerate(user_sets) for b in list(user_sets)[at + 1:])
-    results = []
-    for row in sorted(selected, key=lambda item: int(item["id"])):
-        attempts = _read_attempts(auth, [row], start, end)
-        if exercise_type:
-            attempts = [item for item in attempts if item["exercise_type"] == exercise_type]
-        learners, exercises = {item["user_id"] for item in attempts}, {item["exercise_id"] for item in attempts}
-        if len(attempts) < effective or len(learners) < MIN_DIFFICULTY_STUDENTS:
-            results.append({"class_id": row["id"], "class_name": row.get("name", ""),
-                            "status": "insufficient_data"})
-            continue
-        successes = sum(not item["unrelated"] and item["score"] >= SUCCESS_SCORE for item in attempts)
-        results.append({"class_id": row["id"], "class_name": row.get("name", ""), "status": "complete",
-                        "total_attempts": len(attempts), "participating_students": len(learners),
-                        "observed_exercises": len(exercises), "success_rate": _rate(successes, len(attempts)),
-                        "average_score": round(sum(item["score"] for item in attempts) / len(attempts), 1),
-                        "attempts_per_participant": round(len(attempts) / len(learners), 2),
-                        "attempts_per_student_exercise_exposure":
-                            round(len(attempts) / (len(learners) * len(exercises)), 2) if exercises else None})
-    return {"from_date": start.isoformat(), "to_date": end.isoformat(), "exercise_type": exercise_type,
-            "status": "complete" if any(row["status"] == "complete" for row in results) else "insufficient_data",
-            "privacy_threshold": {"minimum_students": MIN_DIFFICULTY_STUDENTS,
-                                  "minimum_attempts": effective},
-            "overlapping_enrollment": overlap,
-            "overlap_note": "class populations are not mutually exclusive" if overlap else None,
-            "classes": results, "returned": len(results)}
-
-
-def _bottleneck_item(items: list[dict[str, Any]], *, label: str, identifier: str,
-                     level: str) -> dict[str, Any]:
-    students: dict[str, list[dict[str, Any]]] = defaultdict(list)
-    for item in items:
-        students[item["user_id"]].append(item)
-    repeated_failures, first_success, changes, improved = 0, [], [], 0
-    for learner_items in students.values():
-        ordered = sorted(learner_items, key=lambda item: (item["stamp"], item["id"]))
-        failures = [item for item in ordered if item["unrelated"] or item["score"] < SUCCESS_SCORE]
-        if len(failures) >= 2:
-            repeated_failures += 1
-        successes = [at for at, item in enumerate(ordered, 1)
-                     if not item["unrelated"] and item["score"] >= SUCCESS_SCORE]
-        if successes:
-            first_success.append(successes[0])
-        if len(ordered) >= 2:
-            change = ordered[-1]["score"] - ordered[0]["score"]
-            changes.append(change)
-            improved += change > 0
-    affected, attempts = len(students), len(items)
-    repeated_rate = _rate(repeated_failures, affected)
-    improvement_rate = _rate(improved, len(changes))
-    average_until = round(sum(first_success) / len(first_success), 2) if first_success else None
-    basis = []
-    if repeated_rate is not None and repeated_rate >= 60:
-        basis.append("high_repeated_failure_rate")
-    if improvement_rate is not None and improvement_rate < 40:
-        basis.append("low_improvement_rate")
-    if average_until is None or average_until >= 3:
-        basis.append("slow_or_absent_success")
-    severity = "high" if len(basis) >= 2 else "medium" if basis else "low"
-    suggestion = ("לפרק את התרגיל לשלבים קצרים, להדגים שוב ולבצע תרגול מונחה"
-                  if severity == "high" else "לשלב חזרה ממוקדת ומשוב מיידי")
-    return {"level": level, "id": identifier, "name": label,
-            "observed_metrics": {"affected_students": affected, "total_attempts": attempts,
-                                 "repeated_failure_rate": repeated_rate,
-                                 "average_attempts_until_success": average_until,
-                                 "improvement_rate": improvement_rate,
-                                 "average_score_change": round(sum(changes) / len(changes), 1) if changes else None},
-            "severity": severity,
-            "suggested_intervention": {"type": "recommendation", "text": suggestion, "basis": basis}}
-
-
-def learning_bottlenecks(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
-                         class_id: int | None = None, exercise_type: str | None = None,
-                         limit: object = 20, min_attempts: object = 10,
-                         today: date | None = None) -> dict[str, Any]:
-    start, end, _ = validate_range(from_date, to_date, "day", today=today)
-    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= MAX_ANALYTICS_RESULTS:
-        raise MonitoringError("limit חייב להיות מספר בין 1 ל-50")
-    if exercise_type is not None and exercise_type not in EXERCISE_TYPES:
-        raise MonitoringError("exercise_type אינו מוכר")
-    effective = _threshold(min_attempts, default=10)
-    classes, scope = _scope(auth, actor, class_id)
-    attempts = _read_attempts(auth, classes, start, end)
-    if exercise_type:
-        attempts = [item for item in attempts if item["exercise_type"] == exercise_type]
-    exercise_groups: dict[str, list[dict[str, Any]]] = defaultdict(list)
-    topic_groups: dict[str, list[dict[str, Any]]] = defaultdict(list)
-    for item in attempts:
-        exercise_groups[item["exercise_id"]].append(item)
-        if item["topic"]:
-            topic_groups[str(item["topic"])].append(item)
-    results = []
-    for exercise_id, items in exercise_groups.items():
-        if len(items) >= effective and len({item["user_id"] for item in items}) >= MIN_DIFFICULTY_STUDENTS:
-            results.append(_bottleneck_item(items, label=items[0]["exercise_name"],
-                                            identifier=exercise_id, level="exercise"))
-    for topic, items in topic_groups.items():
-        if len(items) >= effective and len({item["user_id"] for item in items}) >= MIN_DIFFICULTY_STUDENTS:
-            results.append(_bottleneck_item(items, label=topic,
-                                            identifier=hashlib.sha256(topic.encode()).hexdigest()[:12],
-                                            level="topic"))
-    results = [item for item in results if item["severity"] != "low"]
-    severity_order = {"high": 0, "medium": 1}
-    results.sort(key=lambda item: (severity_order[item["severity"]],
-                                   -(item["observed_metrics"]["repeated_failure_rate"] or 0), item["id"]))
-    results = results[:limit]
-    return {**scope, "from_date": start.isoformat(), "to_date": end.isoformat(),
-            "exercise_type": exercise_type, "status": "complete" if results else "insufficient_data",
-            "privacy_threshold": {"minimum_students": MIN_DIFFICULTY_STUDENTS,
-                                  "minimum_attempts": effective},
-            "bottlenecks": results, "returned": len(results)}
-
-
-def system_health(app: Any, actor: dict[str, Any]) -> dict[str, Any]:
-    if not has_permission(actor, "management.access"):
-        raise MonitoringError("אין הרשאת ניהול")
-    state = app.state
-    auth = getattr(state, "auth", None)
-    database = "not_configured" if auth is None else "healthy"
-    if auth is not None:
-        try:
-            if hasattr(auth, "database_health"):
-                if not auth.database_health():
-                    database = "unavailable"
-            else:
-                auth.classes(fresh=True)
-        except Exception:  # The response deliberately never carries infrastructure exception text.
-            database = "unavailable"
-    components = {
-        "application": "healthy",
-        "authentication": "healthy" if auth is not None else "not_configured",
-        "database": database,
-        "model": "healthy" if getattr(state, "scorer", None) is not None else "unavailable",
-        "text_to_speech": "healthy" if getattr(state, "tts", None) is not None else "not_configured",
-    }
-    required = (components["application"], components["authentication"], components["database"], components["model"])
-    overall = "healthy" if all(value == "healthy" for value in required) else "degraded"
-    answer: dict[str, Any] = {"status": overall,
-                              "checked_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
-                              "components": components}
-    if "developer" in actor.get("roles", ()):
-        info = getattr(state, "mcp_build_info", {})
-        if isinstance(info, dict):
-            answer["build"] = {key: str(info[key])[:100] for key in ("version", "revision") if info.get(key)}
-    return answer

app/nakdan.py

@@ -1,113 +0,0 @@
-"""Adds niqqud to Hebrew before it is read aloud: the TTS voices misread many unpointed words.
-
-Uses Dicta's free Nakdan service (no key). A word that already has niqqud (hand pointed, as in `he_say`)
-is kept as written; every other word takes Nakdan's first choice. Results are cached on disk, so each
-sentence is sent once. When the service cannot be reached, the text is returned as it was.
-
-Env:  HEBREW_NIQQUD  "0" turns it off (the tests do)
-      NAKDAN_URL     optional; default Dicta's public endpoint
-      TTS_CACHE_DIR  optional; default ~/.cache/ihki-tts (the cache is niqqud.json inside it)
-"""
-from __future__ import annotations
-
-import json
-import logging
-import os
-import re
-import threading
-from pathlib import Path
-
-log = logging.getLogger("ihki.nakdan")
-NIQQUD = re.compile(r"[֑-ׇ]")
-HEBREW = re.compile(r"[א-ת]")
-DEFAULT_URL = "https://nakdan-5-3.loadbalancer.dicta.org.il/api"
-_lock = threading.Lock()
-_cache: dict[str, str] | None = None
-
-
-def _cache_path() -> Path:
-    return Path(os.environ.get("TTS_CACHE_DIR", "").strip() or Path.home() / ".cache" / "ihki-tts") / "niqqud.json"
-
-
-def _load() -> dict[str, str]:
-    global _cache
-    if _cache is None:
-        try:
-            _cache = json.loads(_cache_path().read_text("utf-8"))
-        except (OSError, ValueError):
-            _cache = {}
-    return _cache
-
-
-def _save() -> None:
-    path = _cache_path()
-    try:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(_cache, ensure_ascii=False), "utf-8")
-        tmp.replace(path)
-    except OSError as e:
-        log.warning("niqqud cache write failed: %s: %s", type(e).__name__, e)
-
-
-def _fetch(text: str) -> list[dict]:
-    import requests
-
-    r = requests.post(os.environ.get("NAKDAN_URL", "").strip() or DEFAULT_URL, timeout=8, json={
-        "task": "nakdan", "data": text, "genre": "modern", "addmorph": False, "keepqq": False,
-        "nodageshdefmem": False, "patachma": False, "keepmetagim": False})
-    r.raise_for_status()
-    return r.json()
-
-
-# second person endings, (said to a woman, said to a man): שְׁלוֹמֵךְ / שְׁלוֹמְךָ, שָׁבַרְתְּ / שָׁבַרְתָּ
-ENDINGS = (("\u05b5\u05da\u05b0", "\u05b0\u05da\u05b8"), ("\u05ea\u05bc\u05b0", "\u05ea\u05bc\u05b8"))
-
-
-def _choose(options: list[str], gender: str | None) -> str:
-    """Nakdan's first choice, unless the sentence is said to a man ("m") or a woman ("f") and it says otherwise."""
-    first = options[0]
-    if gender in ("m", "f"):
-        for fem, male in ENDINGS:
-            wrong, right = (fem, male) if gender == "m" else (male, fem)
-            if first.endswith(wrong):
-                return next((o for o in options if o.endswith(right)), first)
-    return first
-
-
-def _join(words: list[dict], gender: str | None = None) -> str:
-    out = []
-    for w in words:
-        word = w.get("word", "")
-        options = w.get("options") or []
-        if w.get("sep") or not options or NIQQUD.search(word) or not HEBREW.search(word):
-            out.append(word)                        # spaces, punctuation, numbers, and words already pointed
-        else:
-            best = _choose(options, gender).replace("|", "")       # "בְּ|בַיִת": the bar marks a prefix
-            out.append(best if NIQQUD.sub("", best) == word else word)   # never a different spelling
-    return "".join(out)
-
-
-def point(text: str, gender: str | None = None) -> tuple[str, bool]:
-    """(text with niqqud, final). Final is False only when Nakdan failed: the text is unchanged and worth retrying.
-
-    gender: "m" or "f" when the sentence is said to a man or a woman (its note, "(לגבר)" or "(לאישה)").
-    """
-    if os.environ.get("HEBREW_NIQQUD", "").strip() == "0" or not HEBREW.search(text):
-        return text, True
-    with _lock:
-        cache = _load()
-        key = f"{gender}|{text}" if gender else text
-        if key in cache:
-            return cache[key], True
-        try:
-            pointed = _join(_fetch(text), gender)
-        except Exception as e:  # network, rate limit, odd reply: read it unpointed this time
-            log.warning("nakdan failed: %s: %s", type(e).__name__, e)
-            return text, False
-        if NIQQUD.sub("", pointed) != NIQQUD.sub("", text):
-            log.warning("nakdan changed more than niqqud, ignored: %r -> %r", text, pointed)
-            return text, False
-        cache[key] = pointed
-        _save()
-        return pointed, True

app/phones.py

@@ -1,19 +0,0 @@
-"""The sound a model symbol stands for.
-
-The model's vocab is multilingual (392 symbols) and spells one sound several ways: t / t̪ / tʰ / tː,
-r / ɾ, a / æ / ɐ, x / χ. Left alone, a correctly said t loses to its own spelling variant t̪.
-base() names the sound a symbol stands for; Vocab.merge() (scorer.py) pools the posteriors of each sound,
-and rules.py writes its rules in the same names.
-"""
-_STRIP = set("ːʰʲ.^[:\"̪̩̝̞̊̃")  # length, aspiration, palatalisation, dental, syllabic, nasal ...
-_SAME = {"æ": "a", "ɐ": "a", "ɑ": "a", "ä": "a", "ʌ": "a", "ɪ": "i", "ʊ": "u", "ɛ": "e", "ɔ": "o",
-         "ɾ": "r", "ɫ": "l", "ɡ": "g", "χ": "x", "ʁ": "ɣ", "ʒ": "dʒ", "dZ": "dʒ", "tS": "tʃ", "S": "ʃ",
-         "d͡ʒ": "dʒ", "t͡ʃ": "tʃ", "t͡s": "ts"}
-
-
-def base(symbol: str) -> str:
-    """The sound a model symbol stands for, ignoring length and spelling variants. Emphatics stay distinct.
-    Mandarin tone numbers go too (i5, iː1, a2: 85 symbols in the espeak vocab): a correct ي heard as i5 otherwise
-    lost to its own tone variant (هيّ scored 36 on its vowel). A diphthong (ai5) stays a diphthong."""
-    s = "".join(c for c in symbol if c not in _STRIP).rstrip("0123456789")
-    return _SAME.get(s, s) or symbol

app/phrases.py

@@ -1,154 +0,0 @@
-"""Phrase bank.
-
-Each phrase: Hebrew prompt, Hebrew transliteration hint, category, and accepted variants.
-A variant is (arabic, ipa). IPA phonemes are space-separated and words are separated by " | ".
-The Arabic text and the IPA must have the same number of words (checked in tests).
-
-Conventions (Palestinian urban speech as the main form):
-  ق -> ʔ (urban); a variant with q or k is listed where the rural form is common.
-  ث -> t, ذ -> d (normal in the dialect).
-  ج -> dʒ.
-  Emphatics are written with ˤ (sˤ tˤ dˤ ðˤ), long vowels with ː.
-  Geminates are written doubled; the tokenizer collapses them for CTC.
-"""
-from .arabic_diacritics import point_arabic
-from .grammar import day2_phrases
-from .workbook import CATEGORIES as WORKBOOK_CATEGORIES, GAMES as WORKBOOK_GAMES, LESSON_TABS, LEVEL_TABS, workbook_phrases
-
-PHRASES = [
-    # ---- היכרות ----
-    dict(cat="meet", he="שלום", tr="מַרְחַבַּא", variants=[
-        ("مرحبا", "m a r ħ a b a"),
-        ("اهلا", "ʔ a h l a"),
-        ("اهلين", "ʔ a h l eː n"),
-    ]),
-    dict(cat="meet", he="מה שלומך? (לגבר)", tr="כִּיפַכּ", variants=[
-        ("كيفك", "k iː f a k"),
-        ("كيف حالك", "k iː f | ħ aː l a k"),
-    ]),
-    dict(cat="meet", he="אני בסדר, ברוך השם", tr="מְנִיח, אִלְחַמְדִלַّה", variants=[
-        ("منيح الحمد للّه", "m n iː ħ | i l ħ a m d | i l l a"),
-        ("منيح والحمد للّه", "m n iː ħ | w i l ħ a m d | i l l a"),
-        ("تمام الحمد للّه", "t a m aː m | i l ħ a m d | i l l a"),
-    ]),
-    dict(cat="meet", he="איך קוראים לך? (לגבר)", tr="שוּ אִסְמַכּ", variants=[
-        ("شو اسمك", "ʃ u | ʔ i s m a k"),
-        ("شو اسمك", "ʃ u | s m a k"),
-        ("ايش اسمك", "ʔ eː ʃ | ʔ i s m a k"),
-    ]),
-    dict(cat="meet", he="אני מירושלים", tr="אַנַא מִן אִלְקֻדְס", variants=[
-        ("انا من القدس", "ʔ a n a | m i n | i l ʔ u d s"),
-        ("انا من القدس", "ʔ a n a | m i n | i l q u d s"),
-    ]),
-    dict(cat="meet", he="בוקר טוב", tr="צַבַּאח אִלְח'ֵיר", variants=[
-        ("صباح الخير", "sˤ a b aː ħ | i l x eː r"),
-    ]),
-    dict(cat="meet", he="לילה טוב (לגבר)", tr="תִצְבַּח עַלַא ח'ֵיר", variants=[
-        ("تصبح على خير", "t i sˤ b a ħ | ʕ a l a | x eː r"),
-    ]),
-    dict(cat="meet", he="תודה רבה", tr="שֻכְּרַן כְּתִיר", variants=[
-        ("شكرا كتير", "ʃ u k r a n | k t iː r"),
-        ("مشكور كتير", "m a ʃ k uː r | k t iː r"),
-    ]),
-    dict(cat="meet", he="להתראות", tr="מַע אִ(ל)סַّלַאמֶה", variants=[
-        ("مع السّلامة", "m a ʕ | i s s a l aː m e"),
-        ("يلّا باي", "j a l l a | b aː j"),
-    ]),
-    dict(cat="meet", he="סליחה, תסלח לי", tr="סַאמְחְנִי", variants=[
-        ("سامحني", "s aː m ħ i n i"),
-        ("اسف", "ʔ aː s i f"),
-    ]),
-    # ---- שיחה ----
-    dict(cat="talk", he="מה אתה עושה? (עכשיו)", tr="שוּ בְּתִעְמַל", variants=[
-        ("شو بتعمل", "ʃ u | b t i ʕ m a l"),
-        ("شو بتسوّي", "ʃ u | b t s a w w i"),
-    ]),
-    dict(cat="talk", he="אני עובד בבית חולים", tr="בַּשְתְע'ִל בִּלְמֻסְתַשְפַא", variants=[
-        ("بشتغل بالمستشفى", "b a ʃ t ɣ i l | b i l m u s t a ʃ f a"),
-        ("بشتغل في المستشفى", "b a ʃ t ɣ i l | f i | l m u s t a ʃ f a"),
-    ]),
-    dict(cat="talk", he="אני לא מבין (גבר)", tr="מִש פַאהֵם", variants=[
-        ("مش فاهم", "m i ʃ | f aː h i m"),
-        ("ما فهمت", "m aː | f h i m t"),
-    ]),
-    dict(cat="talk", he="אתה יכול לדבר לאט?", tr="מֻמְכִּן תִחְכִּי שְוַיّ שְוַיّ", variants=[
-        ("ممكن تحكي شويّ شويّ", "m u m k i n | t i ħ k i | ʃ w a j j | ʃ w a j j"),
-        ("ممكن تحكي شويّ", "m u m k i n | t i ħ k i | ʃ w a j j"),
-    ]),
-    dict(cat="talk", he="אין בעיה", tr="מִש מֻשְכִּלֶה", variants=[
-        ("مش مشكلة", "m i ʃ | m u ʃ k i l e"),
-        ("ما في مشكلة", "m aː | f i | m u ʃ k i l e"),
-    ]),
-    dict(cat="talk", he="נתראה מחר", tr="בְּנְשוּף בַּעְד' בֻּכְּרַה", variants=[
-        ("بنشوف بعض بكرة", "b n ʃ uː f | b a ʕ dˤ | b u k r a"),
-        ("منشوف بعض بكرة", "m n ʃ uː f | b a ʕ dˤ | b u k r a"),
-        ("بنشوفك بكرة", "b n ʃ uː f a k | b u k r a"),
-    ]),
-    dict(cat="talk", he="היום חם מאוד", tr="אִלְיוֹם שוֹבּ כְּתִיר", variants=[
-        ("اليوم شوب كتير", "i l j oː m | ʃ oː b | k t iː r"),
-        ("اليوم حرّ كتير", "i l j oː m | ħ a r r | k t iː r"),
-        ("الجوّ حرّ كتير", "i l dʒ a w w | ħ a r r | k t iː r"),
-    ]),
-    # ---- בעיר ----
-    dict(cat="city", he="איפה התחנה?", tr="וֵין אִלְמַחַטַّה", variants=[
-        ("وين المحطّة", "w eː n | i l m a ħ a tˤ tˤ a"),
-    ]),
-    dict(cat="city", he="איפה השירותים?", tr="וֵין אִלְחַמַّאם", variants=[
-        ("وين الحمّام", "w eː n | i l ħ a m m aː m"),
-    ]),
-    dict(cat="city", he="מה השעה?", tr="קַדֵّיש אִ(ל)סַّאעַה", variants=[
-        ("قدّيش السّاعة", "ʔ a d d eː ʃ | i s s aː ʕ a"),
-        ("قدّيش السّاعة", "q a d d eː ʃ | i s s aː ʕ a"),
-        ("كم السّاعة", "k a m | i s s aː ʕ a"),
-    ]),
-    # ---- אוכל וקניות ----
-    dict(cat="food", he="אני רוצה כוס קפה", tr="בִּדִّי פִנְג'אן קַהְוֶה", variants=[
-        ("بدّي فنجان قهوة", "b i d d i | f i n dʒ aː n | ʔ a h w e"),
-        ("بدّي فنجان قهوة", "b i d d i | f i n dʒ aː n | q a h w e"),
-        ("بدّي كاسة قهوة", "b i d d i | k aː s e t | ʔ a h w e"),
-    ]),
-    dict(cat="food", he="תן לי מים, בבקשה", tr="אַעְטִינִי מַיّ לַוּ סַמַחְת", variants=[
-        ("اعطيني ميّ لو سمحت", "ʔ a ʕ tˤ iː n i | m a j j | l a w | s a m a ħ t"),
-        ("عطيني ميّ لو سمحت", "ʕ tˤ iː n i | m a j j | l a w | s a m a ħ t"),
-    ]),
-    dict(cat="food", he="אני אוהב אוכל ערבי", tr="בַּחִבּّ אִלְאַכְּל אִלְעַרַבִּי", variants=[
-        ("بحبّ الأكل العربي", "b a ħ i b b | i l ʔ a k l | i l ʕ a r a b i"),
-    ]),
-    dict(cat="food", he="כמה זה עולה?", tr="קַדֵّיש חַקّוֹ", variants=[
-        ("قدّيش حقّه", "ʔ a d d eː ʃ | ħ a ʔ ʔ o"),
-        ("قدّيش حقّه", "q a d d eː ʃ | ħ a q q o"),
-        ("بقدّيش", "b i ʔ a d d eː ʃ"),
-    ]),
-    dict(cat="food", he="החשבון, בבקשה", tr="אִלְחְסַאבּ לַוּ סַמַחְת", variants=[
-        ("الحساب لو سمحت", "i l ħ s aː b | l a w | s a m a ħ t"),
-        ("الحساب لو سمحت", "i l ħ i s aː b | l a w | s a m a ħ t"),
-    ]),
-]
-# ---- יום 2 ---- generated: every sentence pattern x pronoun x positive/negative (see grammar.py)
-PHRASES += day2_phrases()
-# ---- שיעורים ---- the workbook's translation exercises, lesson by lesson (see workbook.py)
-PHRASES += workbook_phrases()
-
-# The page asks for a lesson first, then one of its categories: the course's lessons (workbook.py).
-# The phrases that belong to no lesson (meet, talk, city, food, day2) have no tab. They stay in the
-# bank, so phrase ids and the attempts recorded on them hold; public_phrases leaves them out.
-LEVELS = [*LEVEL_TABS]
-LESSONS = [*LESSON_TABS]   # every planned lesson; one not written yet is `soon` and has no categories
-CATEGORIES = [*WORKBOOK_CATEGORIES]
-GAMES = [*WORKBOOK_GAMES]
-
-
-def public_phrases():
-    """What the frontend needs: no IPA, first variant's Arabic as the model answer.
-
-    Grammar-built phrases also carry grp / pron / neg / listed / seq (see grammar.py); the page lists a
-    category's `listed` phrases, in `seq` order, and reaches the others with its negation and
-    conjugation buttons. Workbook phrases carry seq and read (see workbook.py).
-    """
-    shown = {c["id"] for c in CATEGORIES + GAMES}
-    return [
-        {"id": i, "cat": p["cat"], "he": p["he"], "tr": p["tr"], "ar": p["variants"][0][0],
-         "ar_pointed": point_arabic(*p["variants"][0]),
-         **{k: p[k] for k in ("grp", "pron", "neg", "listed", "seq", "read", "unlock", "binyan", "gizra", "speaker", "he_say") if k in p}}
-        for i, p in enumerate(PHRASES) if p["cat"] in shown
-    ]

app/powsm.py

@@ -1,237 +0,0 @@
-"""POWSM-CTC (espnet/powsm_ctc) as the app's phoneme model: an Emitter like HFEmitter.
-
-Serve a fine-tune with MODEL_ID=checkpoints/powsm-ft-minerva/powsm_ft.pt (train/finetune_powsm.py), or the
-published model with MODEL_ID=powsm:<ara>. It needs the extra packages from scripts/setup_zero_shot_deps.sh
-(.zero-shot-deps/), which are not in requirements.txt: this is for trying the model locally, not yet for the Space.
-
-What the adapter changes so the scorer can read POWSM's output unchanged:
-- columns: only POWSM's phone tokens (6,405 of 40,002; the rest are text pieces and task tags) and the blank,
-  renormalised. Phone names lose their slashes and tie bars (/d͡ʒ/ -> dʒ), the spelling the scorer's rules use.
-- frames: the language/task prompt's two positions and the padding after the speech are dropped, and every frame
-  is repeated once. POWSM runs at 25 frames/s; the scorer's frame counts (vowel length, alignment padding) were
-  tuned at wav2vec2's 50.
-"""
-from __future__ import annotations
-
-import glob
-import os
-import sys
-from pathlib import Path
-
-import numpy as np
-
-ROOT = Path(__file__).resolve().parent.parent
-DEPS = ROOT / ".zero-shot-deps"
-SAMPLE_RATE = 16_000
-# POWSM was trained on 20 s inputs (its model card says pad to 20 s) and loses accuracy without padding (test PER
-# 16% -> 21%). 8 s keeps it (16.2%) at 1.8 s a recording on 2 CPU threads instead of 4.4 s. A fine-tune trained on
-# random padding (train/finetune_powsm.py --pad random) needs none: unpadded it scores 16.2% at ~0.8 s.
-# POWSM_PAD_SECONDS, when set, overrides both (0: no padding).
-SECONDS = 8.0
-
-
-def pad_seconds(checkpoint: str | None) -> float:
-    """The padding a model runs with: POWSM_PAD_SECONDS if set, none for a short-padding fine-tune, else SECONDS."""
-    env = os.environ.get("POWSM_PAD_SECONDS", "").strip()
-    if env:
-        return float(env)
-    if checkpoint:
-        import torch
-        args = torch.load(checkpoint, map_location="cpu").get("args") or {}
-        if args.get("pad") == "random":
-            return 0.0
-    return SECONDS
-PROMPT = 2       # the language and task tokens the encoder prepends to its output
-UPSAMPLE = 2     # 25 frames/s -> the 50 the scorer was tuned at
-
-
-def use_extra_deps() -> None:
-    """Make .zero-shot-deps importable, after the app's own packages so its torch/numpy always win."""
-    if not (DEPS / "pkgs").exists():
-        raise RuntimeError("POWSM needs extra packages: run scripts/setup_zero_shot_deps.sh first")
-    for sub in ("pkgs", "stubs"):
-        if str(DEPS / sub) not in sys.path:
-            sys.path.append(str(DEPS / sub))
-
-
-def patch_espnet_for_powsm_ctc() -> None:
-    """ESPnet 202511 (the newest release for Python 3.10) can't run POWSM-CTC as published: the encoder hands
-    Conv2dSubsampling the language/task prompt, which that release's layer doesn't accept. Same logic as ESPnet
-    master: linear -> prepend the prompt embeddings -> positional encoding."""
-    import torch
-    from espnet.nets.pytorch_backend.transformer import subsampling
-
-    def forward(self, x, x_mask, prefix_embeds=None):
-        x = self.conv(x.unsqueeze(1))
-        b, c, t, f = x.size()
-        linear, pos_enc = self.out[0], self.out[1]
-        x = linear(x.transpose(1, 2).contiguous().view(b, t, c * f))
-        if x_mask is not None:
-            x_mask = x_mask[:, :, :-2:2][:, :, :-2:2]
-        if prefix_embeds is not None:
-            x = torch.cat([prefix_embeds, x], dim=1)
-            if x_mask is not None:
-                ones = torch.ones(x_mask.shape[0], 1, prefix_embeds.size(1), dtype=x_mask.dtype, device=x_mask.device)
-                x_mask = torch.cat([ones, x_mask], dim=-1)
-        return pos_enc(x), x_mask
-
-    subsampling.Conv2dSubsampling.forward = forward
-
-
-def load_powsm(lang: str = "<ara>", checkpoint: str | None = None, device: str | None = None):
-    """espnet/powsm_ctc as ESPnet's greedy-CTC Speech2Text, with an optional fine-tune's weights on top."""
-    use_extra_deps()
-    import torch
-    from huggingface_hub import snapshot_download
-    patch_espnet_for_powsm_ctc()
-    from espnet2.bin.s2t_inference_ctc import Speech2TextGreedySearch
-    device = device or ("cuda" if torch.cuda.is_available() else "cpu")
-    s2t = Speech2TextGreedySearch.from_pretrained("espnet/powsm_ctc", device=device, lang_sym=lang, task_sym="<pr>")
-    model = s2t.s2t_model
-    # The checkpoint stores the subsampling linear layer as `embed.out.*` (master's layout); the release expects
-    # `embed.out.0.*` and silently leaves it random. Copy it in.
-    ckpt = glob.glob(f"{snapshot_download('espnet/powsm_ctc')}/exp/s2t_train*/*.pth")[0]
-    state = torch.load(ckpt, map_location="cpu")
-    lin = model.encoder.embed.out[0]
-    with torch.no_grad():
-        lin.weight.copy_(state["encoder.embed.out.weight"])
-        lin.bias.copy_(state["encoder.embed.out.bias"])
-    if checkpoint:  # train/finetune_powsm.py saves only the weights it trained
-        saved = torch.load(checkpoint, map_location="cpu")
-        missing = set(saved["state"]) - set(model.state_dict())
-        if missing:
-            raise KeyError(f"{checkpoint} has weights this model lacks: {sorted(missing)[:5]}")
-        model.load_state_dict(saved["state"], strict=False)
-    model.eval()
-    return s2t
-
-
-def parse_model_id(model_id: str) -> tuple[str, str | None] | None:
-    """(language token, checkpoint) when MODEL_ID names a POWSM model, else None.
-    'powsm' or 'powsm:<ara>' is the published model; a path to a .pt file is a fine-tune (always <ara>)."""
-    if model_id == "powsm" or model_id.startswith("powsm:"):
-        return (model_id.split(":", 1)[1] if ":" in model_id else "<ara>"), None
-    if model_id.endswith(".pt"):
-        return "<ara>", model_id
-    return None
-
-
-class PowsmEmitter:
-    """POWSM-CTC -> (T, V) log-posteriors over its phone tokens, at 50 frames/s (see the module docstring)."""
-
-    def __init__(self, lang: str = "<ara>", checkpoint: str | None = None, device: str | None = None):
-        import torch
-        self.torch = torch
-        self.s2t = load_powsm(lang, checkpoint, device)
-        self.pad = pad_seconds(checkpoint)
-        model = self.s2t.s2t_model
-        tokens = model.token_list
-        cols, names = [model.blank_id], {"<blank>": 0}
-        for i, t in enumerate(tokens):
-            if len(t) > 2 and t[0] == "/" and t[-1] == "/":
-                name = t[1:-1].replace("͡", "")
-                if name not in names:  # a tie-barred spelling that collides with a plain one keeps the plain one
-                    names[name] = len(cols)
-                    cols.append(i)
-        self.cols = torch.tensor(cols)
-        self.token_to_id: dict[str, int] = names
-        self.blank_token = "<blank>"
-        self.lang_id = self.s2t.converter.token2id[lang]
-        self.task_id = self.s2t.converter.token2id["<pr>"]
-
-    def __call__(self, wav: np.ndarray) -> np.ndarray:
-        torch = self.torch
-        model, device = self.s2t.s2t_model, self.s2t.device
-        n = int(self.pad * SAMPLE_RATE)
-        x = np.pad(wav, (0, max(0, n - len(wav)))).astype(np.float32)  # longer recordings run as they are
-        speech = torch.from_numpy(x)[None].to(device)
-        prefix = torch.tensor([[self.lang_id, self.task_id]], device=device)
-        prev = torch.tensor([[model.na]], device=device)
-        with torch.inference_mode():
-            enc, _ = model.encode(speech, torch.tensor([speech.shape[1]], device=device), prev,
-                                  torch.tensor([1], device=device), prefix, torch.tensor([2], device=device))
-            if isinstance(enc, tuple):
-                enc = enc[0]
-            enc = enc[0, PROMPT:]
-            keep = max(1, round(enc.shape[0] * len(wav) / len(x)))  # frames that cover the speech
-            logits = model.ctc.ctc_lo(enc[:keep].float())[:, self.cols.to(device)]
-            logp = torch.log_softmax(logits, -1).cpu().numpy()
-        return np.repeat(logp, UPSAMPLE, axis=0)
-
-
-# ---- the exported model (scripts/export_powsm_onnx.py): what the Space runs, with onnxruntime and torch only ----
-
-ONNX_PREFIX = "powsm-onnx:"
-
-
-def onnx_model_dir(model_id: str, download: bool = True) -> Path | None:
-    """The folder of an exported POWSM when MODEL_ID names one, else None: powsm-onnx:<Hub repo> (downloaded once,
-    then from the Hugging Face cache) or a local folder with powsm_onnx.json."""
-    if model_id.startswith(ONNX_PREFIX):
-        repo = model_id[len(ONNX_PREFIX):]
-        if not download:
-            return Path(repo)
-        from huggingface_hub import snapshot_download
-        return Path(snapshot_download(repo, allow_patterns=["powsm_onnx.json", "frontend.npz", onnx_precision_file()]))
-    local = Path(model_id)
-    return local if (local / "powsm_onnx.json").is_file() else None
-
-
-def onnx_precision_file(meta: dict | None = None) -> str:
-    """The weights file POWSM_ONNX_PRECISION picks: fp32 (the default) or int8. On the Minerva test lines, 2 CPU
-    threads: fp32 PER 16.5% at 0.57 s a recording; int8 16.6% at 0.38 s, but ط 81% -> 76% and ص 68% -> 62%."""
-    precision = os.environ.get("POWSM_ONNX_PRECISION", "fp32").strip().lower() or "fp32"
-    files = (meta or {}).get("files") or {"fp32": "model.onnx", "int8": "model.int8.onnx"}
-    return files.get(precision) or files["fp32"]
-
-
-class PowsmOnnxEmitter:
-    """An exported POWSM-CTC -> (T, V) log-posteriors over its phone tokens at 50 frames/s, like PowsmEmitter but
-    without ESPnet. The front end (STFT, mel, log, global mean/variance) runs in torch from frontend.npz; the encoder
-    and CTC head in onnxruntime. The prompt (<ara>, <pr>) is baked into the export."""
-
-    def __init__(self, folder: str, precision: str | None = None):
-        import json
-
-        import onnxruntime as ort
-        import torch
-        self.torch, self.folder = torch, Path(folder)
-        self.meta = json.loads((self.folder / "powsm_onnx.json").read_text(encoding="utf-8"))
-        weights = (self.meta["files"].get(precision) or self.meta["files"]["fp32"]) if precision \
-            else onnx_precision_file(self.meta)
-        opts = ort.SessionOptions()
-        opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
-        # a container can see more cores than it may use (the free Space has 2): POWSM_ONNX_THREADS caps them
-        threads = int(os.environ.get("POWSM_ONNX_THREADS", "0") or 0)
-        if threads > 0:
-            opts.intra_op_num_threads, opts.inter_op_num_threads = threads, 1
-        self.session = ort.InferenceSession(str(self.folder / weights), opts, providers=["CPUExecutionProvider"])
-        fe = np.load(self.folder / "frontend.npz")
-        self.window = torch.from_numpy(fe["window"].astype(np.float32))
-        self.melmat = torch.from_numpy(fe["melmat"].astype(np.float32))
-        self.mean = torch.from_numpy(fe["mean"].astype(np.float32))
-        self.std = torch.from_numpy(fe["std"].astype(np.float32))
-        self.n_fft, self.win, self.hop = int(fe["n_fft"]), int(fe["win_length"]), int(fe["hop_length"])
-        self.token_to_id: dict[str, int] = self.meta["vocab"]
-        self.blank_token = "<blank>"
-        env = os.environ.get("POWSM_PAD_SECONDS", "").strip()
-        self.pad = float(env) if env else float(self.meta.get("pad_seconds", SECONDS))
-        self.weights = weights
-
-    def features(self, x: np.ndarray):
-        """ESPnet's DefaultFrontend + GlobalMVN: centred STFT, power, 80 mel bands, natural log, (x - mean) / std."""
-        torch = self.torch
-        spec = torch.stft(torch.from_numpy(x), self.n_fft, hop_length=self.hop, win_length=self.win,
-                          window=self.window, center=True, pad_mode="reflect", normalized=False, onesided=True,
-                          return_complex=True)
-        power = spec.real ** 2 + spec.imag ** 2                       # (F, T)
-        mel = torch.clamp(power.transpose(0, 1) @ self.melmat, min=1e-10).log()
-        return ((mel - self.mean) / self.std)[None].numpy()
-
-    def __call__(self, wav: np.ndarray) -> np.ndarray:
-        n = int(self.pad * SAMPLE_RATE)
-        x = np.pad(wav, (0, max(0, n - len(wav)))).astype(np.float32)  # a longer recording runs as it is
-        feats = self.features(x)
-        logp = self.session.run(None, {"feats": feats, "feats_lens": np.array([feats.shape[1]], dtype=np.int64)})[0][0]
-        keep = max(1, round(logp.shape[0] * len(wav) / len(x)))      # frames that cover the speech
-        return np.repeat(logp[:keep], UPSAMPLE, axis=0)

app/prefetch.py

@@ -1,35 +0,0 @@
-"""Downloads MODEL_ID's files while the Docker image is built, so a cold start doesn't (see the Dockerfile).
-
-    MODEL_ID=powsm-onnx:<repo> python -m app.prefetch     # an exported POWSM (scripts/export_powsm_onnx.py)
-    MODEL_ID=facebook/wav2vec2-xlsr-53-espeak-cv-ft python -m app.prefetch
-
-A private repo needs HF_TOKEN (the Dockerfile passes the Space secret of that name to this step only).
-"""
-from __future__ import annotations
-
-import os
-import sys
-
-from .powsm import ONNX_PREFIX, onnx_model_dir, parse_model_id
-
-DEFAULT = "facebook/wav2vec2-xlsr-53-espeak-cv-ft"
-
-
-def main() -> None:
-    model_id = os.environ.get("MODEL_ID", "").strip() or DEFAULT
-    if model_id.startswith(ONNX_PREFIX):
-        print("exported POWSM:", onnx_model_dir(model_id))
-        return
-    if parse_model_id(model_id):
-        sys.exit(f"MODEL_ID={model_id} needs ESPnet, which the image doesn't have: export it with "
-                 f"scripts/export_powsm_onnx.py and use MODEL_ID={ONNX_PREFIX}<repo>")
-    from huggingface_hub import hf_hub_download
-    from transformers import AutoFeatureExtractor, Wav2Vec2ForCTC
-    AutoFeatureExtractor.from_pretrained(model_id)
-    Wav2Vec2ForCTC.from_pretrained(model_id)
-    hf_hub_download(model_id, "vocab.json")
-    print("wav2vec2:", model_id)
-
-
-if __name__ == "__main__":
-    main()

app/prompt_tts.py

@@ -1,102 +0,0 @@
-"""Reads the Hebrew prompt aloud with a free TTS engine: edge-tts (Microsoft Edge's online voices)
-or gTTS (Google Translate's voice). The page asks for edge-tts in Edge and gTTS elsewhere.
-
-Before it is read, the text gets niqqud (nakdan.py): unpointed Hebrew is often misread.
-
-No API key. Both engines call an unofficial public endpoint, so either can fail or be rate limited:
-the other one is tried before giving up. Each prompt is generated once per engine and cached on disk.
-
-Env:  HEBREW_VOICE   edge-tts voice (default he-IL-HilaNeural; he-IL-AvriNeural is the male one)
-      TTS_CACHE_DIR  optional; default ~/.cache/ihki-tts
-"""
-from __future__ import annotations
-
-import asyncio
-import hashlib
-import io
-import logging
-import os
-import re
-import threading
-from pathlib import Path
-
-from .nakdan import point
-
-log = logging.getLogger("ihki.prompt_tts")
-ENGINES = ("edge", "gtts")
-_lock = threading.Lock()
-
-
-class PromptTTSUnavailable(Exception):
-    pass
-
-
-def _edge(text: str) -> bytes:
-    import edge_tts
-
-    voice = os.environ.get("HEBREW_VOICE", "").strip() or "he-IL-HilaNeural"
-
-    async def run() -> bytes:
-        out = b""
-        async for chunk in edge_tts.Communicate(text, voice).stream():
-            if chunk["type"] == "audio":
-                out += chunk["data"]
-        return out
-
-    return asyncio.run(run())
-
-
-def _gtts(text: str) -> bytes:
-    from gtts import gTTS
-
-    buf = io.BytesIO()
-    gTTS(text, lang="iw").write_to_fp(buf)  # "iw" is Google's code for Hebrew
-    return buf.getvalue()
-
-
-_SYNTH = {"edge": _edge, "gtts": _gtts}
-
-
-def spoken(he: str) -> str:
-    """The prompt as it should be read: without bracketed notes such as "(לגבר)"."""
-    return re.sub(r"\s*\([^)]*\)", "", he).strip()
-
-
-def gender_of(he: str) -> str | None:
-    """"m" or "f" when the note says who the sentence is said to: "(לגבר)", "(לאישה)"."""
-    return "m" if "(לגבר)" in he else "f" if "(לאישה)" in he else None
-
-
-def hebrew_mp3(he: str, engine: str, cache_it: bool = True) -> tuple[bytes, str]:
-    """(MP3, engine that produced it) for a Hebrew text; `engine` is tried first, then the other.
-
-    Prompts are cached; one-off texts (the spoken assessment of driving mode) pass cache_it=False.
-    A text that could not get niqqud is read as it is and not cached, so it is pointed next time.
-    """
-    text, final = point(spoken(he), gender_of(he))
-    cache_it = cache_it and final
-    cache = Path(os.environ.get("TTS_CACHE_DIR", "").strip() or Path.home() / ".cache" / "ihki-tts") / "he"
-    order = [engine] + [e for e in ENGINES if e != engine]
-    with _lock:
-        for name in order:
-            path = cache / f"{name}-{hashlib.sha1(text.encode()).hexdigest()}.mp3"
-            if cache_it and path.exists():
-                return path.read_bytes(), name
-            try:
-                data = _SYNTH[name](text)
-            except Exception as e:  # network, rate limit, missing package: fall through to the other engine
-                log.warning("hebrew tts %s failed: %s: %s", name, type(e).__name__, e)
-                continue
-            if not data:
-                continue
-            if not cache_it:
-                return data, name
-            try:
-                cache.mkdir(parents=True, exist_ok=True)
-                tmp = path.with_suffix(".tmp")
-                tmp.write_bytes(data)
-                tmp.replace(path)
-            except OSError as e:  # read-only or full cache dir: the audio is still good, it just isn't kept
-                log.warning("hebrew tts cache write failed: %s: %s", type(e).__name__, e)
-            return data, name
-    raise PromptTTSUnavailable("hebrew tts unavailable")

app/push.py

@@ -1,210 +0,0 @@
-"""Push notifications: each morning, a reminder of the day's daily video (see "Daily videos" in auth.py).
-
-A student turns them on from the daily videos' screen. The browser gives a subscription (an address of its push service
-and two keys), kept in the Supabase table `push_subs` with the account's email; only the server's secret key reads it.
-Every few minutes the server looks whether it is PUSH_HOUR or later in Jerusalem; if so, each subscription whose account
-has a daily video today (a class's student or teacher, or, for a staff account, any class's) and was not reminded today
-gets one notification. A subscription the push service no longer knows (404/410) is deleted.
-
-On an iPhone the browser sends them only from the app added to the home screen (iOS 16.4 and later).
-
-Env:  VAPID_PRIVATE_KEY  (the server's push key; make one with  python -m app.push  and keep it as a Space secret.
-                          Changing it drops every subscription: each device has to turn the reminders on again.)
-      VAPID_SUBJECT      (a contact the push services may write to, "mailto:..."; default: the first developer's email)
-      PUSH_HOUR          (the hour of the reminder in Jerusalem, 0-23; default 8)
-"""
-from __future__ import annotations
-
-import asyncio
-import base64
-import json
-import logging
-import os
-import urllib.parse
-from datetime import date, datetime
-from typing import Callable
-
-from .auth import AuthUnavailable
-
-log = logging.getLogger("ihki.push")
-CHECK_EVERY = 300   # seconds between looks at the clock
-MAX_ENDPOINT = 1000
-CREATE_PUSH_SUBS = ("create table public.push_subs (endpoint text primary key, email text not null, p256dh text not null, "
-                    "auth text not null, every_class boolean not null default false, last_daily date, "
-                    "created_at timestamptz not null default now()); "
-                    "alter table public.push_subs enable row level security; "
-                    "revoke all on public.push_subs from anon, authenticated;")
-
-
-def _b64(raw: bytes) -> str:
-    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
-
-
-def new_private_key() -> str:
-    """A new VAPID private key, as VAPID_PRIVATE_KEY keeps it: the raw 32 bytes, base64url."""
-    from cryptography.hazmat.primitives.asymmetric import ec
-    return _b64(ec.generate_private_key(ec.SECP256R1()).private_numbers().private_value.to_bytes(32, "big"))
-
-
-def public_key(private: str) -> str:
-    """The browser's applicationServerKey for this private key: the uncompressed point, base64url."""
-    from cryptography.hazmat.primitives import serialization
-    from cryptography.hazmat.primitives.asymmetric import ec
-    raw = base64.urlsafe_b64decode(private + "=" * (-len(private) % 4))
-    key = ec.derive_private_key(int.from_bytes(raw, "big"), ec.SECP256R1())
-    return _b64(key.public_key().public_bytes(serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint))
-
-
-class Push:
-    def __init__(self, auth, private: str = "", subject: str = "", hour: int = 8):
-        self.auth, self.private, self.subject, self.hour = auth, private.strip(), subject, hour
-        self.public, self.why = "", ""   # why: what keeps the reminders off, in words for the page
-        if not self.private:
-            self.why = "VAPID_PRIVATE_KEY is not set"
-        elif not getattr(auth, "secret", ""):
-            self.why = "SUPABASE_SECRET_KEY is not set"
-        else:
-            try:
-                self.public = public_key(self.private)
-            except ValueError as e:
-                log.error("VAPID_PRIVATE_KEY is not a valid key: push reminders are off (%s)", e)
-                self.why = "VAPID_PRIVATE_KEY is not a valid key"
-
-    @property
-    def on(self) -> bool:
-        return not self.why
-
-    # the table
-    def _rows(self, query: str = "") -> list[dict]:
-        try:
-            return self.auth._admin("/rest/v1/push_subs?select=*" + query) or []
-        except AuthUnavailable as e:
-            if "answered 404" in str(e):
-                raise AuthUnavailable(f"the table push_subs is missing; run in Supabase's SQL editor: {CREATE_PUSH_SUBS}") from e
-            raise
-
-    def save(self, email: str, sub: dict, every_class: bool) -> None:
-        """Keeps a browser's subscription, raising ValueError when it is not one."""
-        endpoint, keys = str(sub.get("endpoint") or ""), sub.get("keys") or {}
-        if not endpoint.startswith("https://") or len(endpoint) > MAX_ENDPOINT or not isinstance(keys, dict):
-            raise ValueError("not a push subscription")
-        p256dh, auth = str(keys.get("p256dh") or ""), str(keys.get("auth") or "")
-        if not (0 < len(p256dh) <= 200 and 0 < len(auth) <= 100):
-            raise ValueError("not a push subscription")
-        self._rows("&limit=0")   # a missing table is told in words that say how to make it
-        self.auth._admin("/rest/v1/push_subs?on_conflict=endpoint", "POST",
-                         {"endpoint": endpoint, "email": email.lower(), "p256dh": p256dh, "auth": auth,
-                          "every_class": every_class}, prefer="resolution=merge-duplicates,return=minimal")
-
-    def delete(self, endpoint: str, email: str | None = None) -> None:
-        q = {"endpoint": f"eq.{endpoint}", **({"email": f"eq.{email.lower()}"} if email else {})}
-        self.auth._admin("/rest/v1/push_subs?" + urllib.parse.urlencode(q), "DELETE", prefer="return=minimal")
-
-    def _sent(self, endpoint: str, day: str) -> None:
-        self.auth._admin("/rest/v1/push_subs?" + urllib.parse.urlencode({"endpoint": f"eq.{endpoint}"}), "PATCH",
-                         {"last_daily": day}, prefer="return=minimal")
-
-    # sending
-    def send(self, row: dict, payload: dict) -> bool:
-        """One notification; False when it did not go (a subscription that is gone is deleted)."""
-        from pywebpush import WebPushException, webpush
-        try:
-            webpush({"endpoint": row["endpoint"], "keys": {"p256dh": row["p256dh"], "auth": row["auth"]}},
-                    json.dumps(payload, ensure_ascii=False), vapid_private_key=self.private,
-                    vapid_claims={"sub": self.subject}, ttl=12 * 3600, timeout=15)
-            return True
-        except WebPushException as e:
-            status = getattr(e.response, "status_code", None)
-            if status in (404, 410):
-                log.info("push subscription of %s is gone: deleted", row.get("email"))
-                try:
-                    self.delete(row["endpoint"])
-                except AuthUnavailable as e2:
-                    log.warning("push subscription not deleted: %s", e2)
-            else:
-                log.warning("push to %s failed: %s", row.get("email"), e)
-        except Exception as e:   # a network failure: tried again on the next look
-            log.warning("push to %s failed: %s", row.get("email"), e)
-        return False
-
-    def every(self) -> list[dict]:
-        """Every subscription (an admin's message goes to some of them)."""
-        return self._rows()
-
-    def send_many(self, rows: list[dict], message: dict) -> int:
-        """One notification to each, a few at a time; how many went."""
-        from concurrent.futures import ThreadPoolExecutor
-        if not rows:
-            return 0
-        with ThreadPoolExecutor(max_workers=min(8, len(rows))) as pool:
-            return sum(pool.map(lambda r: self.send(r, message), rows))
-
-    def mine(self, email: str) -> list[dict]:
-        return self._rows("&" + urllib.parse.urlencode({"email": f"eq.{email.lower()}"}))
-
-    def remind(self, today_of: Callable[[str, bool], list[dict]], day: str) -> int:
-        """Sends the day's reminder to each subscription not reminded on `day`; how many went.
-        `today_of(email, every_class)` gives the daily videos that account has on that day."""
-        sent = 0
-        for row in self._rows("&" + urllib.parse.urlencode({"or": f"(last_daily.is.null,last_daily.lt.{day})"})):
-            videos = today_of(row["email"], bool(row.get("every_class")))
-            if not videos:
-                continue
-            if self.send(row, payload(videos)):
-                sent += 1
-                self._sent(row["endpoint"], day)
-        return sent
-
-
-MAX_TITLE, MAX_BODY = 60, 240
-
-
-def message(title: str, body: str) -> dict:
-    """An admin's notification; ValueError when it is empty or too long. Each has its own tag, so one does not replace another."""
-    title, body = " ".join(title.split()), body.strip()
-    if not title or len(title) > MAX_TITLE or len(body) > MAX_BODY:
-        raise ValueError(f"a title of 1-{MAX_TITLE} characters, and a message of up to {MAX_BODY}")
-    return {"title": title, "body": body, "url": "/", "tag": f"msg-{datetime.now().timestamp():.0f}"}
-
-
-def payload(videos: list[dict]) -> dict:
-    """What the service worker shows: the day's video (or how many there are)."""
-    body = videos[0]["title"] if len(videos) == 1 else f"{len(videos)} סרטונים חדשים: " + " · ".join(v["title"] for v in videos)
-    return {"title": "🎬 הסרטון היומי מחכה לכם", "body": body, "url": "/?view=daily", "tag": "daily-video"}
-
-
-async def loop(push: Push, today_of: Callable[[str, bool], list[dict]], now: Callable[[], datetime]) -> None:
-    """Looks at the clock every CHECK_EVERY seconds and sends the day's reminders from PUSH_HOUR on."""
-    while True:
-        try:
-            t = now()
-            if t.hour >= push.hour:
-                n = await asyncio.to_thread(push.remind, today_of, t.date().isoformat())
-                if n:
-                    log.info("daily video reminders sent: %d", n)
-        except AuthUnavailable as e:
-            log.warning("daily video reminders not sent: %s", e)
-        except Exception:
-            log.exception("daily video reminders failed")
-        await asyncio.sleep(CHECK_EVERY)
-
-
-def load_push(auth) -> Push | None:
-    if auth is None:
-        return None
-    subject = os.environ.get("VAPID_SUBJECT", "").strip()
-    if not subject:
-        dev = sorted(getattr(auth, "developers", ()) or getattr(auth, "teachers", ()))
-        subject = f"mailto:{dev[0]}" if dev else "mailto:admin@example.com"
-    try:
-        hour = max(0, min(23, int(os.environ.get("PUSH_HOUR", "8"))))
-    except ValueError:
-        hour = 8
-    push = Push(auth, os.environ.get("VAPID_PRIVATE_KEY", ""), subject, hour)
-    log.info("daily video reminders: %s", f"on, at {hour}:00" if push.on else f"off ({push.why})")
-    return push
-
-
-if __name__ == "__main__":
-    key = new_private_key()
-    print(f"VAPID_PRIVATE_KEY={key}\n# its public key (the page reads it from the server): {public_key(key)}")

app/reference.py

@@ -1,89 +0,0 @@
-"""Native baseline for the scores: the playback voices saying the phrase, scored by the same model.
-
-The phoneme model mishears some sounds even from a native (ʕ in على as dropped, l as r), and a
-learner should not be marked down or get a tip for those. So each practised phrase is also scored
-on its TTS model answer, and Scorer measures the learner against that (see Scorer.score_logp).
-
-One voice is generated per phrase (the first of the list); the other voices are used only when
-the page has already played them, so calibration costs at most one TTS call per phrase.
-References are built in the background and kept in memory; a score waits a few seconds for them
-and is given without calibration if they are not ready by then.
-"""
-from __future__ import annotations
-
-import logging
-import threading
-import time
-from dataclasses import replace
-from concurrent.futures import Future, ThreadPoolExecutor, wait
-
-from .arabic_diacritics import tts_arabic
-from .scorer import Reference, Scorer, decode_audio
-from .tts import voice_name
-
-log = logging.getLogger("ihki.reference")
-
-
-class References:
-    def __init__(self, scorer: Scorer, tts, voices: list[str], wait_s: float = 8.0, retry_s: float = 300.0):
-        self.scorer, self.tts, self.voices = scorer, tts, voices
-        self.wait_s, self.retry_s = wait_s, retry_s
-        self._pool = ThreadPoolExecutor(max_workers=1, thread_name_prefix="ihki-ref")
-        self._jobs: dict[tuple[int, str], Future] = {}
-        self._retry_at: dict[tuple[int, str], float] = {}  # failed builds are not retried before this time
-        self._lock = threading.Lock()
-
-    def _build(self, phrase: dict, text: str, voice: str) -> Reference | None:
-        # wav() would turn a voice it does not offer for playback (فدوى) into Raef's
-        data, _ = self.tts.wav_for_voice(text, voice, source="baseline", upload=True)
-        ref = self.scorer.reference(decode_audio(data), phrase)
-        if ref is None:
-            log.info("reference not usable: %r by voice %s", text, voice)
-            return None
-        return replace(ref, voice=voice_name(voice))
-
-    def get(self, phrase_id: int, phrase: dict) -> list[Reference]:
-        """The references of a phrase that are ready within the wait."""
-        text = tts_arabic(*phrase["variants"][0])
-        jobs: list[tuple[tuple[int, str], Future]] = []
-        with self._lock:
-            for n, voice in enumerate(self.voices):
-                key = (phrase_id, voice)
-                job = self._jobs.get(key)
-                if (job is None and time.monotonic() >= self._retry_at.get(key, 0)
-                        and (n == 0 or self.tts.cached(text, voice))):
-                    job = self._jobs[key] = self._pool.submit(self._build, phrase, text, voice)
-                if job is not None:
-                    jobs.append((key, job))
-        done, _ = wait([job for _, job in jobs], timeout=self.wait_s)
-        refs = []
-        for key, job in jobs:
-            if job not in done:
-                continue
-            try:
-                ref = job.result()
-            except Exception as e:  # provider down, undecodable audio: score without this voice
-                log.warning("reference for phrase %s failed: %s", key[0], e)
-                with self._lock:
-                    if self._jobs.get(key) is job:
-                        del self._jobs[key]
-                        self._retry_at[key] = time.monotonic() + self.retry_s
-                continue
-            if ref is not None:
-                refs.append(ref)
-        return refs
-
-    def invalidate(self, phrase_id: int | None = None, voice: str | None = None) -> int:
-        """Forget matching in-memory baselines so the next score rebuilds them from the current WAV."""
-        with self._lock:
-            keys = [key for key in self._jobs
-                    if (phrase_id is None or key[0] == phrase_id) and (voice is None or key[1] == voice)]
-            for key in keys:
-                job = self._jobs.pop(key)
-                job.cancel()  # harmless when generation or analysis has already started
-                self._retry_at.pop(key, None)
-            retry_keys = [key for key in self._retry_at
-                          if (phrase_id is None or key[0] == phrase_id) and (voice is None or key[1] == voice)]
-            for key in retry_keys:
-                self._retry_at.pop(key, None)
-            return len(keys)

app/rules.py

@@ -1,433 +0,0 @@
-"""Pronunciation rules for Hebrew-speaking learners, read from the yaml blocks of pronunciation-rules.md.
-
-The document is written for two audiences: its student sections are served as a guide, and its scorer
-sections (the ```yaml blocks) say what the scorer accepts and how it judges errors:
-
-  archiphonemes   letters said differently in the urban and the rural dialect, and their correct realisations
-  checks          per rule: (target, heard) -> severity and the Hebrew feedback
-  scoring         margins per (target, heard) pair, max_tips, ...
-  heard_labels    the Hebrew name of every heard symbol
-
-Every symbol is stored by its base() name (phones.py), the names the scorer compares in, so a rule written
-with ʁ matches a model that heard ɣ. check_detectable() tells which rules a model can catch at all.
-"""
-from __future__ import annotations
-
-import re
-import math
-from dataclasses import dataclass, field
-from functools import lru_cache
-from pathlib import Path
-from typing import Callable
-
-import yaml
-
-from .phones import base
-
-RULES_PATH = Path(__file__).resolve().parent.parent / "static" / "assets" / "pronunciation-rules.md"
-
-# Realisations correct only in learned words (ثقافة as saqaafe): accepted where the phrase writes them, not elsewhere.
-LEARNED_ONLY = {"TH": {"s"}, "DH": {"z"}}
-# Classes set by position, not by letter (section 6.3 #5 and #6): the vowel of a final ة, the vowel of a pronoun ending.
-POSITIONAL = {"E": ["a", "e", "i"], "O": ["o", "u"]}
-
-
-def norm(symbol: str) -> str:
-    """A rule symbol in the scorer's names. "_" (nothing heard) and the abstract symbols stay as they are."""
-    return symbol if symbol == "_" or symbol.isupper() else base(symbol)
-
-
-@dataclass(frozen=True)
-class Check:
-    rule: str
-    target: str
-    heard: str
-    severity: int
-    feedback: str
-
-
-@dataclass
-class Rules:
-    archiphonemes: dict[str, dict[str, list[str]]]
-    dialects: list[str]
-    optional: bool
-    scoring: dict
-    checks: dict[tuple[str, str], Check]
-    titles: dict[str, str]                       # rule id -> title
-    heard_labels: dict[str, str]
-    margins: dict[tuple[str, str], float] = field(default_factory=dict)
-    # a vowel heard between two consonants of a word (3.10): rule, severity, min_peak, min_frames, score_cap, feedback
-    insertion: dict | None = None
-    # short vowels a rule flags although short vowels are not flagged (6.3 #7): vowel -> rule id (3.11: u)
-    flag_vowels: dict[str, str] = field(default_factory=dict)
-    # a long vowel said short, judged by its duration (3.8): rule, severity, min_ratio, prior_frames, ..., feedback
-    length: dict | None = None
-    # (target, heard) pairs a native reference never forgives (scoring.baseline_protected, 6.4)
-    baseline_protected: set[tuple[str, str]] = field(default_factory=set)
-
-    def members(self, symbol: str, written: str | None = None) -> list[str]:
-        """The correct realisations of an abstract symbol, in base() names, first the dialects' own.
-
-        A learned-only realisation (TH as s) counts only when the phrase writes it (`written`)."""
-        if symbol in POSITIONAL:
-            return list(POSITIONAL[symbol])
-        spec = self.archiphonemes.get(symbol)
-        if spec is None:
-            return []
-        out: list[str] = []
-        keys = [*self.dialects, "also_ok", *(["optional"] if self.optional else [])]
-        for key in keys:
-            for ph in spec.get(key, []):
-                ph = base(ph)
-                if ph not in out and (ph not in LEARNED_ONLY.get(symbol, ()) or ph == written):
-                    out.append(ph)
-        return out
-
-    def dialects_of(self, symbol: str, phone: str) -> set[str]:
-        """The dialects in which `phone` is a correct realisation of `symbol` (empty: in none, or not dialectal)."""
-        spec = self.archiphonemes.get(symbol, {})
-        return {d for d in ("urban", "rural") if phone in {base(p) for p in spec.get(d, [])}}
-
-    def check(self, targets: str | list[str], heard: str | None) -> Check | None:
-        """The rule for hearing `heard` instead of the target: the first of `targets` that has one."""
-        if not heard:
-            return None
-        for t in [targets] if isinstance(targets, str) else targets:
-            c = self.checks.get((norm(t), norm(heard)))
-            if c is not None:
-                return c
-        return None
-
-    def margin(self, targets: str | list[str], heard: str | None) -> float:
-        """How much likelier than the target `heard` must be before it is a mistake (natural log). The first
-        of `targets` (the abstract symbol, then the written phoneme) with a margin of its own decides."""
-        default = float(self.scoring.get("margin_default", 0.0))
-        for t in [targets] if isinstance(targets, str) else targets:
-            m = self.margins.get((norm(t), norm(heard or "_")))
-            if m is not None:
-                return m
-        return default
-
-    def protected(self, targets: str | list[str], heard: str | None) -> bool:
-        """Is (target, heard) a pair a native reference never forgives? The target as an abstract symbol or written."""
-        return heard is not None and any((norm(t), norm(heard)) in self.baseline_protected
-                                         for t in ([targets] if isinstance(targets, str) else targets))
-
-    def label(self, heard: str | None) -> str | None:
-        """The Hebrew name of a heard symbol, as section 8 gives it."""
-        if heard is None:
-            return None
-        return self.heard_labels.get(heard) or self.heard_labels.get(norm(heard))
-
-    def interference(self) -> set[str]:
-        """Every symbol some rule expects to hear instead of the target: the Hebrew sounds worth naming."""
-        return {h for (_, h) in self.checks if h != "_"}
-
-
-def _blocks(text: str) -> list[dict]:
-    out = []
-    for block in re.findall(r"```yaml\n(.*?)```", text, re.S):
-        for doc in re.split(r"^---$", block, flags=re.M):
-            if doc.strip():
-                out.append(yaml.safe_load(doc))
-    return out
-
-
-def parse(text: str) -> Rules:
-    archi, dialects, optional, scoring, labels = {}, ["urban", "rural"], False, {}, {}
-    checks: dict[tuple[str, str], Check] = {}
-    titles: dict[str, str] = {}
-    insertion, flag_vowels, length = None, {}, None
-    for doc in _blocks(text):
-        if "duration" in doc:
-            length = {"rule": doc["id"], **doc["duration"]}
-        if "insertion" in doc:
-            titles[doc["id"]] = doc.get("title", doc["id"])
-            insertion = {"rule": doc["id"], **doc["insertion"]}
-        for v in doc.get("flag_vowels", []):
-            flag_vowels[str(v)] = doc["id"]
-        if "archiphonemes" in doc:
-            archi = {k: {d: list(v.get(d, [])) for d in ("urban", "rural", "also_ok", "optional")}
-                     for k, v in doc["archiphonemes"].items()}
-            dialects = list(doc.get("dialects_enabled", dialects))
-            optional = bool(doc.get("optional_realisations_enabled", False))
-        if "scoring" in doc:
-            scoring = dict(doc["scoring"])
-        if "heard_labels" in doc:
-            labels = {str(k): str(v) for k, v in doc["heard_labels"].items()}
-        if "checks" in doc:
-            titles[doc["id"]] = doc.get("title", doc["id"])
-            for c in doc["checks"]:
-                for heard in c["heard"]:
-                    key = (norm(str(c["target"])), norm(str(heard)))
-                    # two spellings of one sound (ʁ and ɣ) meet here: the first rule written wins
-                    checks.setdefault(key, Check(doc["id"], key[0], key[1], int(c["severity"]), str(c["feedback"])))
-    rules = Rules(archi, dialects, optional, scoring, checks, titles, labels, insertion=insertion, flag_vowels=flag_vowels,
-                  length=length)
-    for m in scoring.get("margins", []):
-        # base() drops vowel length, so a margin for long vowels would land on quality pairs (a / i) it was not meant for
-        for t in (t for t in m["target"] if "ː" not in str(t)):
-            for h in m["heard"]:
-                rules.margins[(norm(str(t)), norm(str(h)))] = float(m["margin"])
-    rules.baseline_protected = {(norm(str(p["target"])), norm(str(p["heard"]))) for p in scoring.get("baseline_protected", [])}
-    return rules
-
-
-@lru_cache(maxsize=1)
-def load(path: str = str(RULES_PATH)) -> Rules:
-    return parse(Path(path).read_text(encoding="utf-8"))
-
-
-def undetectable(check: Check, rules: Rules, in_model: Callable[[str], bool],
-                 heard_as: Callable[[str], object] | None = None) -> str | None:
-    """Why the model cannot catch this mistake, or None if it can.
-
-    `heard_as` names the model symbol a sound is heard as (stand-ins included: ðˤ as z); two sounds heard
-    as the same symbol cannot be told apart."""
-    same = (lambda a, b: a == b or (heard_as(a) is not None and heard_as(a) == heard_as(b))) if heard_as \
-        else (lambda a, b: a == b)
-    if rules.length and check.rule == rules.length["rule"]:
-        return None                         # a long vowel said short is measured by its duration, not its symbol
-    if same(check.target, check.heard):
-        return "same_sound"                 # the two collapse to one sound (aː / a: length is not modelled)
-    accepted = rules.members(check.target) if check.target.isupper() else [check.target]
-    if any(same(check.heard, p) for p in accepted):
-        return "accepted"                   # the 'mistake' is a correct realisation of the target
-    if not any(in_model(p) for p in accepted):
-        return "target_not_in_model"
-    if check.heard != "_" and not in_model(check.heard):
-        return "heard_not_in_model"
-    return None
-
-
-def check_detectable(rules: Rules, in_model: Callable[[str], bool],
-                     heard_as: Callable[[str], object] | None = None) -> dict[str, dict]:
-    """Per rule: whether at least one of its checks can fire, and why each of the others cannot."""
-    out: dict[str, dict] = {}
-    for c in rules.checks.values():
-        r = out.setdefault(c.rule, {"title": rules.titles.get(c.rule, c.rule), "detectable": False, "missing": []})
-        why = undetectable(c, rules, in_model, heard_as)
-        if why is None:
-            r["detectable"] = True
-        else:
-            r["missing"].append({"target": c.target, "heard": c.heard, "why": why})
-    return out
-
-
-# ---------- exemptions (section 6.3): what the model hears as a mistake but is ordinary speech ----------
-
-VOWELS = {"a", "i", "u", "e", "o", "aː", "iː", "uː", "eː", "oː"}
-_VOWEL_GROUPS = [set("iɪeɛ"), set("uʊoɔ"), set("aæɐɑəɛe")]  # a raised towards e is ordinary Palestinian speech
-
-
-def near_vowels(expected: str, heard: str | None) -> bool:
-    """Same vowel with another length, or the neighbouring quality (i/e, u/o, a/ə, a/e)."""
-    if expected not in VOWELS or not heard:
-        return False
-    e, h = expected.rstrip("ː"), heard.rstrip("ː")
-    return any(e in g and h in g for g in _VOWEL_GROUPS)
-
-
-def elided_article(toks, i: int, ar_words: list[str]) -> bool:
-    """Is token i the vowel of the article ال right after a word that ends in a vowel?
-
-    There it is not said (على الطّاولة is ʕ a l a | tˤ tˤ aː w l e), so its absence is not an error.
-    """
-    t = toks[i]
-    return (i > 0 and t.phoneme in VOWELS and toks[i - 1].word == t.word - 1 and toks[i - 1].phoneme in VOWELS
-            and t.word < len(ar_words) and ar_words[t.word].startswith("ال"))
-
-
-# A glottal stop that is simply not there is how natives say it too (انا, اهلا; ق between vowels): #1, #2.
-# A glottal stop replaced by another consonant still counts, unless the class accepts it (ق said as k).
-# At utterance onset, though, one weak competitor frame is commonly a breath or microphone transient. Treat that
-# as an omission regardless of the phone the multilingual model names; two frames (~40 ms) remain a substitution.
-def _glottal_dropped(toks, i, sc, heard, ar_words):
-    if toks[i].sound not in ("ʔ", "Q"):
-        return False
-    transient_onset = i == 0 and sc.peak < math.log(0.05) and sc.comp_frames < 2
-    return sc.deleted or transient_onset
-
-
-# Rule 31: the same onset transient in front of any other first consonant. The multilingual model hears a
-# word-initial stop (طاولتنا: closure silence, then a short burst) weakly, and a single breath or microphone frame
-# above deleted_comp then outscores it under an arbitrary name (tˤ heard as j). The target must still be there
-# (not deleted, peak at least deleted_peak); an omission, or a competitor held two frames (~40 ms), still counts.
-def _onset_transient(toks, i, sc, heard, ar_words):
-    t = toks[i]
-    return (i == 0 and t.phoneme not in VOWELS and t.sound not in ("ʔ", "Q") and not sc.deleted
-            and sc.comp_frames == 1 and sc.peak >= math.log(0.05))
-
-
-def _article_vowel_elided(toks, i, sc, heard, ar_words):     # #3
-    return sc.deleted and elided_article(toks, i, ar_words)
-
-
-# Neighbouring vowel qualities and vowel length vary between speakers and towns (il / el),
-# and the model confuses them on its own: not worth marking a word down for (#7).
-def _near_vowel(toks, i, sc, heard, ar_words):
-    return near_vowels(toks[i].phoneme, heard)
-
-
-# Short vowels are deliberately not judged by the learner policy, except u after a consonant inside the same word
-# (rule 3.11).  Their acoustic score must follow that decision: an unflagged 1/100 must not collapse the word score.
-def _unmarked_short_vowel(toks, i, sc, heard, ar_words):
-    t = toks[i]
-    checked_u = (t.phoneme == "u" and i > 0 and toks[i - 1].word == t.word
-                 and toks[i - 1].phoneme not in VOWELS)
-    return t.phoneme in {"a", "i", "u", "e", "o"} and not checked_u
-
-
-# Rule 28: a native final /b/ can lose its acoustic voicing before a voiceless consonant across a word boundary.
-# The multilingual CTC then strongly labels that closure /p/ (ħaliib tˤaare), although Arabic has no phonemic /p/.
-# Keep this narrow: a learner's /p/ inside a word, or before a voiced sound, must not be hidden.
-_VOICELESS_ONSETS = {"t", "tˤ", "k", "q", "ʔ", "s", "sˤ", "ʃ", "f", "x", "ħ", "h", "θ"}
-
-
-def _final_b_devoicing(toks, i, sc, heard, ar_words):
-    if base(toks[i].phoneme) != "b" or base(heard or "") != "p" or i + 1 >= len(toks):
-        return False
-    following = toks[i + 1]
-    return following.word == toks[i].word + 1 and base(following.phoneme) in _VOICELESS_ONSETS
-
-
-# Rule 32: plain t heard as d, or d heard as t. Hebrew has the same contrast (ת / ד), so a learner hardly ever swaps
-# them, while the multilingual model often does: a t after n (انتي) or between vowels (فتح) gets some voicing in
-# natural speech and is labelled d. Emphatics (tˤ, dˤ) are not covered: their plain counterparts are rule 3.3.
-_VOICING_PAIR = {("t", "d"), ("d", "t")}
-
-
-def _t_d_voicing(toks, i, sc, heard, ar_words):
-    return not sc.deleted and (base(toks[i].phoneme), base(heard or "")) in _VOICING_PAIR
-
-
-# Rule 29: in connected speech, a word-final short vowel flows into a vowel-initial next word.  The next word is
-# commonly represented with an initial ʔ token, so accept either V or ʔ+V as the hiatus context.  CTC may assign the
-# transition to only one side and call the final vowel deleted even in native speech (على إيدك).
-def _word_final_vowel_linking(toks, i, sc, heard, ar_words):
-    t = toks[i]
-    if not sc.deleted or t.phoneme not in {"a", "i", "u", "e", "o"} or i + 1 >= len(toks):
-        return False
-    following = toks[i + 1]
-    if following.word != t.word + 1:
-        return False
-    if following.phoneme in VOWELS:
-        return True
-    return (following.sound in {"ʔ", "Q"} and i + 2 < len(toks)
-            and toks[i + 2].word == following.word and toks[i + 2].phoneme in VOWELS)
-
-
-# (name, applies(tokens, index, TokenScore, heard symbol, Arabic words), score it gets: None = full marks,
-# else the name of the ScorerConfig floor). The first that applies wins.
-EXEMPTIONS = [
-    ("glottal_dropped", _glottal_dropped, None),
-    ("onset_transient", _onset_transient, "onset_transient_floor"),
-    ("article_vowel_elided", _article_vowel_elided, None),
-    ("near_vowel", _near_vowel, "near_vowel_floor"),
-    ("final_b_devoicing", _final_b_devoicing, None),
-    ("t_d_voicing", _t_d_voicing, None),
-    ("word_final_vowel_linking", _word_final_vowel_linking, "near_vowel_floor"),
-    ("unmarked_short_vowel", _unmarked_short_vowel, "near_vowel_floor"),
-]
-
-
-# ---------- the rules a teacher can switch off (ניטור): every behaviour taken from pronunciation-rules.md ----------
-
-@dataclass(frozen=True)
-class Toggle:
-    id: str
-    group: str        # "accept": what counts as correct · "judge": how a mistake is judged · "feedback": what is said
-    section: str      # where pronunciation-rules.md has it
-    title: str
-    description: str  # what the scorer does while the rule is on; off is the behaviour before the document
-
-
-def _toggles() -> list[Toggle]:
-    letters = [
-        ("Q", "ق", "ʔ (עירוני), k (כפרי) או q", "אַהְוֶה, כַּהְוֶה וקַהְוֶה נכונות שלושתן."),
-        ("K", "ك", "k או tʃ (כפרי)", "כַּלְבּ וצ'ַלְבּ נכונות שתיהן."),
-        ("TH", "ث", "t או θ (כפרי), ו־s במילים ספרותיות כשהמשפט כותב s", "תְלַאתֶה ות'לַאת'ֶה נכונות שתיהן."),
-        ("DH", "ذ", "d או ð (כפרי), ו־z במילים ספרותיות כשהמשפט כותב z", "דַהַבּ וד״ַהַבּ נכונות שתיהן."),
-        ("ZH", "ظ", "dˤ, zˤ או ðˤ", "ד'ֻהְר וט'ֻהְר נכונות שתיהן."),
-        ("J", "ج", "dʒ או ʒ", "ג' כמו בג'ינס או ז' כמו בז'קט."),
-    ]
-    out = [Toggle(f"dialect_{s}", "accept", "5", f"{ar}: {said}",
-                  f"כל המימושים נכונים, וההגה נמדד מול סכום ההסתברויות שלהם (6.1). {ex} "
-                  f"כבוי: נבדק רק המימוש שכתוב במשפט.") for s, ar, said, ex in letters]
-    out += [
-        Toggle("final_vowel", "accept", "6.3 #5", "תנועה סופית של ة: a, e או i",
-               "אַהְוֶה, אַהְוַה ואַהְוִי נכונות. כבוי: נבדקת התנועה שכתובה במשפט."),
-        Toggle("diphthong", "accept", "6.3 #8", "eː גם כ־aj, ו־oː גם כ־aw",
-               "בֵּית ובַּיְת נכונות שתיהן (נבדק כווריאנט נוסף). כבוי: רק התנועה הארוכה."),
-        Toggle("glottal_dropped", "judge", "6.3 #1–2", "עצירה סותמית שהושמטה אינה טעות",
-               "ʔ (ء, ו־ق עירונית) שלא נשמעה מקבלת ציון מלא, כמו אצל דוברים ילידיים (אַנַא ← אנה)."),
-        Toggle("onset_transient", "judge", "6.3 #31", "קפיצה של פריים אחד לפני העיצור הראשון",
-               "עיצור שפותח את המשפט, שנשמע אך חלש, ומתחרה שהופיע בפריים אחד בלבד (נשימה או רעש מיקרופון) מקבל "
-               "לפחות 90 ולא מסומן. השמטה, או מתחרה בשני פריימים ומעלה, עדיין נבדקים."),
-        Toggle("article_vowel_elided", "judge", "6.3 #3", "תנועת ה־ال אחרי תנועה",
-               "ה־i של ال שלא נאמרה אחרי מילה שמסתיימת בתנועה (עַלַא לְ...) אינה טעות."),
-        Toggle("near_vowel", "judge", "6.3 #7", "תנועות קרובות",
-               "תנועה שנשמעה כשכנתה (i/e, u/o, a/e) או באורך אחר מקבלת לפחות 90."),
-        Toggle("unmarked_short_vowel", "judge", "6.3 #30", "תנועה קצרה שאינה נבדקת",
-               "תנועה קצרה שהמדיניות אינה מסמנת מקבלת לפחות 90, כדי שלא תפיל את ציון המילה. "
-               "u אחר�� עיצור בתוך אותה מילה עדיין נבדקת לפי כלל הקובוץ."),
-        Toggle("final_b_devoicing", "judge", "6.3 #28", "b סופית לפני עיצור אטום",
-               "b בסוף מילה שהמודל שמע כ־p לפני עיצור אטום במילה הבאה מקבלת ציון מלא; "
-               "באמצע מילה או לפני עיצור קולי אין פטור."),
-        Toggle("t_d_voicing", "judge", "6.3 #32", "t ו־d לא מתחלפות",
-               "t שהמודל שמע כ־d, או d שנשמעה כ־t, מקבלת ציון מלא: דוברי עברית מבחינים בין ת ל־ד, "
-               "והמודל טועה בזוג הזה (אחרי n, בין תנועות). עיצורים מודגשים (ط, ض) נבדקים כרגיל."),
-        Toggle("word_final_vowel_linking", "judge", "6.3 #29", "תנועה סופית שמתחברת לתנועה הבאה",
-               "תנועה קצרה בסוף מילה שהמודל רואה כמחוקה לפני מילה שמתחילה בתנועה מקבלת לפחות 90; "
-               "באמצע מילה או לפני עיצור אין פטור."),
-        Toggle("margins", "judge", "6.2", "מרווח ביטחון לזוגות שהמודל מבלבל",
-               "עיצור מודגש נחשב שגוי רק אם הרגיל סביר ממנו פי 2 בערך, ħ מול h פי 1.5, "
-               "ו־h נחשבת שנבלעה רק אם היא חלשה פי 2 מסף ההשמטה. "
-               "כבוי: כל מתחרה שמנצח מסמן טעות."),
-        Toggle("unnamed_sounds", "judge", "7", "צליל שאינו בערבית או בעברית לא נקרא בשמו",
-               "כשהמודל הרב־לשוני שומע צליל זר (נקישה, צליל רטרופלקסי) הוא מדווח כ'לא ברור'. כבוי: נאמר שם הסמל."),
-        Toggle("tips_by_severity", "feedback", "6.2", "סדר הטיפים לפי חומרה, עד 3",
-               "טעות שמשנה משמעות (ח, ע) מוצגת לפני מבטא, ואחריה הציון הנמוך. כבוי: לפי הציון בלבד, עד 4."),
-    ]
-    own = {
-        "vowel_length": "המודל לא מבחין בין a ל־aː, ולכן האורך נמדד בזמן: תנועה ארוכה בין שני עיצורים שקצרה בבירור "
-                        "ביחס לתנועות הקצרות של אותו דובר יורדת לכל היותר ל־60, עם טיפ בחומרה 1. "
-                        "כבוי: אורך התנועה לא נבדק.",
-        "cluster": "תנועה שהמודל שומע בבירור בין שני עיצורים של אותה מילה (katiir במקום ktiir) מורידה את העיצור השני "
-                   "לכל היותר ל־60, עם טיפ בחומרה 1. לא בצרור שפותח את המשפט, ולא ליד w או j. כבוי: תנועה שנוספה לא נבדקת.",
-        "kubutz": "u אחרי עיצור היא התנועה הקצרה היחידה שמסומנת: כשנשמטה, או נשמעה כ־e, i או שווא. "
-                  "כ־o היא עדיין תנועה קרובה. כבוי: כמו שאר התנועות הקצרות, לא מסומנת.",
-    }
-    for rule_id, title, section in (("pharyngeal_h", "ח לועית", "3.1"), ("ayin", "ע לועית", "3.2"),
-                                    ("emphatics", "עיצורים מודגשים", "3.3"), ("r_tap", "ר מתגלגלת", "3.4"),
-                                    ("ghain", "ע' היא ה־ר העברית", "3.5"), ("h", "ה נהגית תמיד", "3.6"),
-                                    ("w", "ו היא w", "3.7"), ("b", "ב היא תמיד b", "3.7"), ("f", "פ היא תמיד f", "3.7"),
-                                    ("vowel_length", "תנועה ארוכה", "3.8"), ("jim", "ג' ולא g", "3.9"),
-                                    ("cluster", "שני עיצורים צמודים", "3.10"), ("kubutz", "קובוץ ברור", "3.11")):
-        out.append(Toggle(f"rule_{rule_id}", "judge" if rule_id in own else "feedback", section, title,
-                          own.get(rule_id) or
-                          f"הטיפ והחומרה (בסוגריים) מהמסמך כשנשמע: {_confusions(rule_id)}. "
-                          "כבוי: טיפ כללי בחומרה בינונית; ההחלטה אם לסמן לא משתנה."))
-    return out
-
-
-def _confusions(rule_id: str) -> str:
-    """'ח ← ח עברית (3), ה (2), נבלעת (2)': the substitutions a section-3 rule speaks for, in Hebrew labels."""
-    rules = load()
-    by_target: dict[str, list[str]] = {}
-    for c in rules.checks.values():
-        if c.rule == rule_id:
-            heard = rules.label(c.heard) or c.heard
-            item = f"{'נבלעת' if c.heard == '_' else heard} ({c.severity})"
-            if item not in by_target.setdefault(c.target, []):
-                by_target[c.target].append(item)
-    return "; ".join(f"{_LETTER.get(t, t)} ← {', '.join(items)}" for t, items in by_target.items())
-
-
-# a target sound by the letter of the transliteration (section 1), for the teacher's list
-_LETTER = {"ħ": "ח", "ʕ": "ע", "sˤ": "צ", "tˤ": "ט", "dˤ": "ד'", "ZH": "ט'", "r": "ר", "ɣ": "ע'", "h": "ה", "w": "ו",
-           "b": "ב", "f": "פ", "J": "ג'", "a": "אַא", "i": "ִי", "u": "וּ", "e": "ֵי", "o": "וֹ"}
-
-
-TOGGLES = _toggles()
-TOGGLE_IDS = frozenset(t.id for t in TOGGLES)

app/scorer.py

@@ -1,1150 +0,0 @@
-"""Pronunciation scorer: phoneme CTC model + forced alignment against the expected phonemes."""
-from __future__ import annotations
-
-import copy
-import json
-import logging
-import os
-import subprocess
-from dataclasses import dataclass, field, replace
-from difflib import SequenceMatcher
-from typing import Callable, Protocol
-
-import numpy as np
-
-from .align import (Alignment, GopConfig, TokenScore, ctc_viterbi, edit_distance, greedy_decode, score_tokens,
-                    weighted_edit_distance)
-from .archi import archify, diphthong_variants, split_token, written
-from .phones import base
-from .rules import EXEMPTIONS, TOGGLE_IDS, Check, Rules, elided_article, near_vowels, norm, load as load_rules  # noqa: F401 (re-exported)
-from .tips import VOWELS, letter_reason, sound_name, tip_for
-from .translit import CONSONANTS as _HEB_C, HEARD_ONLY as _HEB_HEARD, VOWELS as _HEB_V, to_hebrew, word_letters, word_to_hebrew
-
-HEBREW_SOUNDS = set(_HEB_C) | set(_HEB_V) | set(_HEB_HEARD)
-# a vowel gliding into (or out of) j or w passes through these: on the frames between the two, coarticulation
-GLIDE_KIN = {"j": ("i", "iː", "e", "eː"), "w": ("u", "uː", "o", "oː")}
-
-log = logging.getLogger("ihki.scorer")
-
-SAMPLE_RATE = 16_000
-MAX_SECONDS = 32  # the recording includes the time to read the sentence and think (the page stops at 30 s)
-
-# Fallbacks when the model vocab lacks a phoneme. The first symbol found in the vocab wins.
-FALLBACKS = {
-    "sˤ": ["sˤ", "sˠ", "s"], "tˤ": ["tˤ", "tˠ", "t"], "dˤ": ["dˤ", "dˠ", "d"], "zˤ": ["zˤ", "zˠ", "z"],
-    "ðˤ": ["ðˤ", "ðˠ", "zˤ", "z"], "dʒ": ["dʒ", "d͡ʒ", "ʒ"],
-    "aː": ["aː", "a"], "iː": ["iː", "i"], "uː": ["uː", "u"], "eː": ["eː", "e"], "oː": ["oː", "o"],
-    "x": ["x", "χ"], "ɣ": ["ɣ", "ʁ"], "q": ["q", "k"], "r": ["r", "ɾ"], "g": ["ɡ", "g"],
-}
-
-
-class Emitter(Protocol):
-    """Anything that turns 16 kHz mono float32 audio into (T, V) log-posteriors."""
-    def __call__(self, wav: np.ndarray) -> np.ndarray: ...
-
-
-class Vocab:
-    def __init__(self, token_to_id: dict[str, int], blank_token: str = "<pad>", rules: Rules | None = None):
-        self.t2i = token_to_id
-        self.i2t = {i: t for t, i in token_to_id.items()}
-        self.blank = token_to_id[blank_token]
-        self.rules = rules or load_rules()
-        self.downgraded: dict[str, str] = {}
-        # sound classes: every id points at one representative id (the plain symbol when the vocab has it)
-        groups: dict[str, list[int]] = {}
-        for t, i in token_to_id.items():
-            if i != self.blank and not t.startswith("<"):
-                groups.setdefault(base(t), []).append(i)
-        self.canon = {i: i for i in self.i2t}
-        self._groups: list[tuple[int, list[int]]] = []
-        self.rep_of: dict[str, int] = {}  # base() name -> representative id
-        for name, ids in groups.items():
-            rep = token_to_id.get(name, ids[0]) if token_to_id.get(name) in ids else ids[0]
-            self.rep_of[name] = rep
-            for i in ids:
-                self.canon[i] = rep
-            if len(ids) > 1:
-                self._groups.append((rep, ids))
-        # Letters with several correct realisations (archi.py): one virtual id per (symbol, realisations),
-        # numbered after the real vocab, whose column extend() fills with the pooled posterior of its members.
-        self.n_real = max(self.i2t) + 1
-        self.members: dict[int, set[int]] = {}
-        self._classes: dict[tuple[str, frozenset[int]], int] = {}
-        self.class_missing: dict[str, set[str]] = {}  # symbol -> realisations the model has no symbol for
-
-    def merge(self, logp: np.ndarray) -> np.ndarray:
-        """Pool each sound's spelling variants into its representative column; the other columns go silent."""
-        out = logp.copy()
-        for rep, ids in self._groups:
-            out[:, ids] = -1e9
-            out[:, rep] = np.logaddexp.reduce(logp[:, ids], axis=1)
-        return out
-
-    def sound_id(self, phone: str) -> int | None:
-        """The representative id of a sound (any spelling of it), or None if the model has no symbol for it."""
-        return self.rep_of.get(base(phone))
-
-    def model_id(self, phone: str) -> int | None:
-        """The id the model hears `phone` as: its own, else its first FALLBACKS stand-in (ðˤ -> z), else None."""
-        for cand in [phone, *FALLBACKS.get(phone, [])]:
-            i = self.sound_id(cand)
-            if i is not None:
-                return i
-        return None
-
-    def add_class(self, symbol: str, phones: list[str]) -> int:
-        """The id that stands for 'any of `phones`': a virtual id, or the real one when only one is in the model.
-        A realisation the model lacks is heard as its stand-in, as a plain phoneme would be (zˤ as z)."""
-        ids: list[int] = []
-        for ph in phones:
-            i = self.model_id(ph)
-            if i is None:
-                self.class_missing.setdefault(symbol, set()).add(ph)
-                continue
-            if i != self.sound_id(ph):
-                self.downgraded[ph] = self.i2t[i]
-            if i not in ids:
-                ids.append(i)
-        if not ids:
-            raise KeyError(f"no realisation of {symbol} ({phones}) is in the model vocab")
-        if len(ids) == 1:
-            return ids[0]
-        key = (symbol, frozenset(ids))
-        if key not in self._classes:
-            vid = self.n_real + len(self._classes)
-            self._classes[key], self.members[vid] = vid, set(ids)
-            self.i2t[vid], self.canon[vid] = symbol, vid
-        return self._classes[key]
-
-    def extend(self, logp: np.ndarray) -> np.ndarray:
-        """Merged posteriors with one more column per class: the pooled posterior of its realisations."""
-        logp = logp[:, :self.n_real]
-        if not self.members:
-            return logp
-        out = np.full((logp.shape[0], self.n_real + len(self.members)), -1e9, dtype=logp.dtype)
-        out[:, :logp.shape[1]] = logp
-        for vid, ids in self.members.items():
-            out[:, vid] = np.logaddexp.reduce(logp[:, sorted(ids)], axis=1)
-        return out
-
-    def resolve(self, phoneme: str) -> list[int]:
-        for cand in FALLBACKS.get(phoneme, [phoneme]):
-            if cand in self.t2i:
-                if cand != phoneme:
-                    self.downgraded[phoneme] = cand
-                return [self.t2i[cand]]
-        # last resort: greedy longest-match split into vocab symbols
-        ids, rest = [], phoneme
-        while rest:
-            for k in range(len(rest), 0, -1):
-                if rest[:k] in self.t2i:
-                    ids.append(self.t2i[rest[:k]])
-                    rest = rest[k:]
-                    break
-            else:
-                raise KeyError(f"phoneme {phoneme!r} cannot be expressed in the model vocab")
-        self.downgraded[phoneme] = " ".join(self.i2t[i] for i in ids)
-        return ids
-
-    def token(self, tok: str) -> tuple[list[int], str, str]:
-        """A token of an IPA string (a phoneme, or an archi.py symbol "Q:ʔ") -> (model ids, phoneme as written, sound).
-
-        The sound is the symbol for a many-ways letter, the phoneme otherwise."""
-        sym, members, ph = split_token(tok)
-        if sym is None:
-            return self.resolve(tok), tok, tok
-        phones = members or self.rules.members(sym, written=base(ph) if ph else None)
-        ph = ph or (phones[0] if phones else sym)
-        try:
-            return [self.add_class(sym, phones)], ph, sym
-        except KeyError:
-            return self.resolve(ph), ph, sym
-
-
-LETTER_GOOD = 75  # a letter scoring under this is coloured on the page (`band` in static/index.html)
-
-
-@dataclass
-class TargetToken:
-    phoneme: str    # phoneme as written in phrases.py
-    id: int         # model token id (a virtual id for a letter with several correct realisations)
-    word: int       # word index in the variant
-    sound: str = ""  # what the token stands for: the archi.py symbol (Q) or the phoneme itself
-
-    def __post_init__(self):
-        self.sound = self.sound or self.phoneme
-
-
-def tokenize(ipa: str, vocab: Vocab) -> list[TargetToken]:
-    """IPA string -> model tokens. Geminates (and any repeated id) collapse to one CTC token."""
-    out: list[TargetToken] = []
-    for w, word in enumerate(ipa.split("|")):
-        for tok in word.split():
-            ids, ph, sound = vocab.token(tok)
-            for tid in ids:
-                if out and out[-1].id == tid:
-                    continue
-                out.append(TargetToken(ph, tid, w, sound))
-    return out
-
-
-@dataclass
-class Reference:
-    """How the model scored a native voice saying a phrase: the baseline a learner is measured against."""
-    sounds: list[tuple[int, str]]  # (word, sound) of each sound of the variant the voice said (Q, not ʔ / k)
-    scores: list[float]            # their scores, same order
-    voice: str = ""                # who said it (the TTS voice's name), for the trace dashboard
-    # per sound, what took its place in the voice (Scorer._heard): "_" nothing, a symbol, None kept.
-    # Empty for a reference built before this was recorded: its failures are then unknown.
-    heard: list[str | None] = field(default_factory=list)
-
-
-@dataclass
-class ScorerConfig:
-    flag_below: float = 50.0        # phoneme score under which a consonant gets a tip
-    flag_below_sound: dict[str, float] = field(default_factory=dict)   # per sound, in place of flag_below (see
-                                                                       # FLAG_BELOW_BY_MODEL: it depends on the model)
-    # weighted edit distance (Scorer._distance) over the weight of the sounds that can be wrong, above which we say
-    # "different sentence". 0.65 with plain edit distance over all sounds; the weighted ratio runs lower
-    unrelated_ratio: float = 0.5
-    # ... unless the forced alignment clearly found the sentence: this share of its consonants (at least 2) peak
-    # at unrelated_veto_peak or more, and the mean GOP score (before the exemptions) is at least unrelated_veto_mean
-    unrelated_veto_share: float = 0.6
-    unrelated_veto_peak: float = 0.5
-    unrelated_veto_mean: float = 60.0
-    issue_below: float = 90.0       # phoneme score under which it is listed as imprecise
-    max_issues: int = 8
-    max_tips: int | None = None     # None: as many as the rules document says (scoring.max_tips)
-    near_vowel_floor: float = 90.0  # a vowel heard as its neighbour (i/e, u/o, a/ə, short/long) scores at least this
-    word_min_weight: float = 0.35   # one weak phoneme matters, without dominating half of the whole word
-    ref_min_mean: float = 60.0      # a native reference whose mean phoneme score is under this is not trusted
-    # a sound the native reference scored under this, the model cannot measure in this phrase (ħ in رحنا: 0.2): the
-    # learner's score on it is noise too, so it is given back in full and the unrelated gate does not count it
-    ref_noise_floor: float = 10.0
-    ayin_deleted_floor: float = 60.0 # the base model often drops a correctly pronounced pharyngeal ʕ
-    onset_transient_floor: float = 90.0  # a first consonant outscored by a one-frame onset spike (rule 31)
-    # The learner-facing pipeline is more encouraging than the generic GOP primitive: a competitor twice as likely
-    # scores about 78, while a clearly dominant competitor can still pull the phoneme below the feedback threshold.
-    gop: GopConfig = field(default_factory=lambda: GopConfig(leniency=0.35))
-
-
-def frame_energy(wav: np.ndarray | None, frames: int) -> np.ndarray | None:
-    """RMS energy of the audio under each of the model's `frames` (they split the recording evenly, ~20 ms each)."""
-    if wav is None or frames <= 0 or len(wav) == 0:
-        return None
-    edges = np.linspace(0, len(wav), frames + 1).astype(int)
-    sq = np.concatenate([[0.0], np.cumsum(np.asarray(wav, dtype=np.float64) ** 2)])
-    n = np.maximum(edges[1:] - edges[:-1], 1)
-    return np.sqrt((sq[edges[1:]] - sq[edges[:-1]]) / n)
-
-
-@dataclass
-class Fit:
-    """The accepted variant the audio fits best, and how each of its sounds scored."""
-    ar: str
-    ipa: str                 # as written in the phrase bank (display, transliteration)
-    aipa: str                # the same with archi.py symbols, one token per phoneme of `ipa`
-    toks: list[TargetToken]
-    al: Alignment
-    scores: list[TokenScore]
-    heard_ids: list[int]     # greedy decode, real symbols only
-    unrelated: bool
-    logp: np.ndarray         # merged posteriors with the class columns (Vocab.extend)
-    # for the teacher's stage-by-stage view (Scorer._trace)
-    candidates: list[tuple[str, str, float | None]] = field(default_factory=list)  # (ar, ipa, path log-prob)
-    gop_scores: list[TokenScore] = field(default_factory=list)   # before the exemptions
-    exempted: list[str | None] = field(default_factory=list)     # per token, the exemption that applied
-    exempt_scores: list[TokenScore] = field(default_factory=list)  # after the exemptions, before the inserted vowels
-    inserted: dict[int, str] = field(default_factory=dict)        # token -> the vowel heard before it (rules 3.10)
-    insert_scores: list[TokenScore] = field(default_factory=list)  # after the inserted vowels, before vowel length
-    shortened: dict[int, dict] = field(default_factory=dict)      # token -> how short its long vowel was (rules 3.8)
-    distance: float = 0.0    # weighted edit distance of the greedy decode from the chosen variant (_distance)
-    raw_distance: int = 0    # the same, every edit costing 1
-    distance_weight: float = 1.0  # what `distance` is divided by: the weight of the sounds that can be wrong
-    veto: bool = False       # the alignment found the sentence, so it is not called unrelated (_veto)
-    energy: np.ndarray | None = None   # per frame RMS (frame_energy), when the audio was given
-    paths: list[list[str]] = field(default_factory=list)   # each candidate's tokens (archi symbols), as `candidates`
-
-
-class Scorer:
-    def __init__(self, emit: Emitter, vocab: Vocab, cfg: ScorerConfig | None = None):
-        self.emit, self.vocab, self.cfg = emit, vocab, cfg or ScorerConfig()
-        self.rules = vocab.rules
-        self.calibrations: dict[tuple[str, str, str], float] = {}
-        # the sounds a competitor is named by: Arabic, the Hebrew sounds the rules expect instead, and their labels;
-        # anything else the multilingual model offers (clicks, retroflexes) is reported as "not clear"
-        names = (set(HEBREW_SOUNDS) | self.rules.interference() | set(self.rules.heard_labels)
-                 | {p for s in self.rules.archiphonemes for p in self.rules.members(s)})
-        self.named = {i for i in (vocab.sound_id(n) for n in names) if i is not None}
-        self.disabled: frozenset[str] = frozenset()  # rules.TOGGLES the teacher switched off (ניטור)
-
-    def with_gop(self, **changes) -> "Scorer":
-        """This scorer with some GopConfig fields changed (ratio_pool, vowel_window ...), sharing its model, vocab and
-        rules: for the lab's sweep over the settings. Nothing of this scorer changes."""
-        other = copy.copy(self)
-        other.cfg = replace(self.cfg, gop=replace(self.cfg.gop, **changes))
-        return other
-
-    def set_disabled(self, ids) -> None:
-        """Atomically replaces the switched-off rules; unknown ids are ignored."""
-        self.disabled = frozenset(ids) & TOGGLE_IDS
-
-    def _on(self, toggle: str) -> bool:
-        return toggle not in self.disabled
-
-    def _off_symbols(self) -> frozenset[str]:
-        """The archi.py symbols not to use: letters whose dialect rule is off, and E for the final-vowel rule."""
-        off = {t.removeprefix("dialect_") for t in self.disabled if t.startswith("dialect_")}
-        return frozenset(off | ({"E"} if "final_vowel" in self.disabled else set()))
-
-    def _check(self, tok: TargetToken, heard: str | None):
-        """The rule of pronunciation-rules.md for this substitution, unless the teacher switched it off.
-        A rule for a short vowel (3.11: u) speaks for that vowel only, not for its long form (base() drops length)."""
-        check = self.rules.check([tok.sound, tok.phoneme], heard)
-        if check and check.target in self.rules.flag_vowels and tok.phoneme != check.target:
-            return None
-        return check if check and self._on(f"rule_{check.rule}") else None
-
-    def _flag_vowel(self, toks: list[TargetToken], i: int) -> bool:
-        """Is token i a short vowel a rule flags (3.11: u after a consonant of the same word, not the و of 'and')?"""
-        t = toks[i]
-        rule = self.rules.flag_vowels.get(t.phoneme)
-        return bool(rule and self._on(f"rule_{rule}") and i > 0 and toks[i - 1].word == t.word
-                    and toks[i - 1].phoneme not in VOWELS)
-
-    _GLIDES = {"w", "j"}  # the way into or out of a glide sounds like a vowel in anyone's speech
-
-    def _glide_edges(self, toks: list[TargetToken]) -> list[tuple[set[int], set[int]] | None]:
-        """For a vowel beside j or w: the vowels that glide is made of (GLIDE_KIN), no competitor on the frames
-        between the vowel and that glide."""
-        kin = lambda k: {x for p in GLIDE_KIN.get(toks[k].phoneme, ()) if (x := self.vocab.sound_id(p)) is not None}
-        return [(kin(i - 1) if i else set(), kin(i + 1) if i + 1 < len(toks) else set())
-                if t.phoneme in VOWELS else None for i, t in enumerate(toks)]
-
-    def _insertions(self, logp: np.ndarray, toks: list[TargetToken], al: Alignment) -> dict[int, str]:
-        """Rules 3.10: token -> the vowel the model clearly heard between it and the consonant before it, in one word
-        (katiir for ktiir). The cluster that opens the sentence is spared (6.3 #16), and so are pairs with w or j."""
-        spec = self.rules.insertion
-        if not spec or not self._on(f"rule_{spec['rule']}"):
-            return {}
-        vowels = {i: base(self.vocab.i2t[i]) for i in (self.vocab.sound_id(v) for v in ("a", "e", "i", "o", "u", "ə"))
-                  if i is not None}
-        real = logp[:, :self.vocab.n_real]
-        greedy = real.argmax(1)
-        min_peak, min_frames = float(np.log(spec.get("min_peak", 0.5))), int(spec.get("min_frames", 2))
-        out: dict[int, str] = {}
-        for j in range(2, len(toks)):     # j == 1 is the cluster that opens the sentence
-            a, b = toks[j - 1], toks[j]
-            if (a.word != b.word or a.phoneme in VOWELS or b.phoneme in VOWELS
-                    or {base(a.phoneme), base(b.phoneme)} & self._GLIDES):
-                continue
-            frames = [t for t in range(al.spans[j - 1][0], al.spans[j][1])
-                      if int(greedy[t]) in vowels and real[t, greedy[t]] >= min_peak]
-            if len(frames) >= min_frames:
-                out[j] = vowels[int(greedy[frames[0]])]
-        return out
-
-    _SHORT = {"a", "i", "u", "e", "o"}
-
-    def _shortened(self, toks: list[TargetToken], al: Alignment, scores: list[TokenScore],
-                   energy: np.ndarray | None = None) -> dict[int, dict]:
-        """Rules 3.8: token -> how short its long vowel was, for each long vowel said short.
-
-        The model pools a and aː (base() drops length), so length is read from time: the frames between the
-        sounds on either side of the vowel, against the same span around this speaker's short vowels (with a
-        prior for sentences that have few). With the audio, only the frames at least half as loud as the loudest
-        of the span count, so a held nasal or a pause after the vowel does not make it long. Only between two
-        consonants: at the edges of the recording, or beside another vowel, the span says nothing about this one."""
-        spec = self.rules.length
-        if not spec or not self._on(f"rule_{spec['rule']}"):
-            return {}
-
-        def span(k: int) -> int | None:
-            if not 0 < k < len(toks) - 1 or toks[k - 1].phoneme in VOWELS or toks[k + 1].phoneme in VOWELS \
-                    or scores[k].deleted:
-                return None
-            a, b = al.spans[k - 1][1], al.spans[k + 1][0]
-            if energy is None:
-                return b - a
-            seg = energy[a:b]
-            return int((seg >= 0.5 * seg.max()).sum()) if seg.size and seg.max() > 0 else 0
-
-        shorts = [g for k, t in enumerate(toks) if t.phoneme in self._SHORT and (g := span(k)) is not None]
-        prior = float(spec["prior_frames"] if energy is not None else spec["prior_frames_plain"])
-        weight = float(spec["prior_weight"])
-        ref = (sum(shorts) + prior * weight) / (len(shorts) + weight)
-        targets = {str(t): float(r) for t, r in spec["min_ratio"].items()}
-        out: dict[int, dict] = {}
-        for k, t in enumerate(toks):
-            g = span(k) if t.phoneme in targets else None
-            if g is not None and g / ref < targets[t.phoneme]:
-                out[k] = {"frames": g, "short_frames": round(ref, 2), "ratio": round(g / ref, 2),
-                          "min_ratio": targets[t.phoneme]}
-        return out
-
-    def set_calibrations(self, rows: list[dict]) -> None:
-        """Atomically replaces applied score floors. A blank phrase is a global rule."""
-        rules = {}
-        for row in rows:
-            expected, heard = str(row.get("expected", "")), str(row.get("heard", ""))
-            phrase = str(row.get("phrase", "")) if row.get("scope") == "phrase" else ""
-            if expected and heard:
-                rules[(expected, heard, phrase)] = max(0.0, min(100.0, float(row.get("floor", 0))))
-        self.calibrations = rules
-
-    def score(self, wav: np.ndarray, phrase: dict, refs: list[Reference] = (), diagnostics: bool = False) -> dict:
-        logp = self.emit(wav)
-        duration_s = len(wav) / SAMPLE_RATE if wav is not None else None
-        return self.score_logp(logp, phrase, refs, diagnostics, duration_s, frame_energy(wav, len(logp)))
-
-    def reference(self, wav: np.ndarray, phrase: dict) -> Reference | None:
-        """The baseline from a native recording of the phrase, or None when the model does not
-        recognise the phrase in it (then it says nothing about single sounds)."""
-        logp = self.emit(wav)
-        return self.reference_logp(logp, phrase, frame_energy(wav, len(logp)))
-
-    def reference_logp(self, logp: np.ndarray, phrase: dict, energy: np.ndarray | None = None) -> Reference | None:
-        """Scorer.reference from the model's posteriors of the native recording (`emit`), and its frame energy."""
-        fit = self._fit(self.vocab.merge(logp), phrase, energy)
-        if fit is None:
-            return None
-        if fit.unrelated or float(np.mean([sc.score for sc in fit.scores])) < self.cfg.ref_min_mean:
-            return None
-        return Reference([(t.word, t.sound) for t in fit.toks], [sc.score for sc in fit.scores],
-                         heard=[self._heard(t, sc) for t, sc in zip(fit.toks, fit.scores)])
-
-    def _baseline(self, toks: list[TargetToken], scores: list[TokenScore],
-                  refs: list[Reference]) -> tuple[list[float | None], list[str | None]]:
-        """Per target token, the lowest score a native reference got on the same sound, counting only a reference
-        that is evidence about the learner's realisation (None: none counts), and why compensation was refused.
-
-        A reference counts when the learner kept the sound (a weak but correct sound), or when the reference lost it
-        too, however (the model's limitation in this phrase, as ʕ heard as ʔ). It does not count when it kept the
-        sound ("kept"), nor for a pair the rules protect, which a TTS voice can say the learner's way ("protected":
-        ħ heard as x).
-        References may have said another accepted variant: only the sounds the two variants share are matched.
-        Sounds are compared by symbol, so a voice that said ق as q is a baseline for a learner who says ʔ.
-        """
-        out: list[float | None] = [None] * len(toks)
-        why: list[str | None] = [None] * len(toks)
-        learner = [self._heard(t, sc) for t, sc in zip(toks, scores)]
-        rows = self._ref_rows(toks, refs)
-        for i, tok in enumerate(toks):
-            lh = learner[i]
-            have = [cell for row in rows if (cell := row[i]) is not None]
-            if not have:
-                continue
-            if lh is not None and self.rules.protected([tok.sound, tok.phoneme], lh):
-                why[i] = "protected"
-                continue
-            counting = [score for score, heard, known in have if lh is None or not known or heard is not None]
-            if counting:
-                out[i] = min(counting)
-            else:
-                why[i] = "kept"
-        return out, why
-
-    @staticmethod
-    def _ref_rows(toks: list[TargetToken], refs: list[Reference]) -> list[list[tuple[float, str | None, bool] | None]]:
-        """Per reference, per target token: (its score, what took the sound's place, whether that is known), or None
-        when the reference does not have the sound."""
-        sounds = [(t.word, t.sound) for t in toks]
-        out = []
-        for ref in refs:
-            known = len(ref.heard) == len(ref.sounds)
-            row: list[tuple[float, str | None, bool] | None] = [None] * len(toks)
-            for a, b, n in SequenceMatcher(None, ref.sounds, sounds, autojunk=False).get_matching_blocks():
-                for k in range(n):
-                    row[b + k] = (ref.scores[a + k], ref.heard[a + k] if known else None, known)
-            out.append(row)
-        return out
-
-    @staticmethod
-    def _ref_scores(toks: list[TargetToken], refs: list[Reference]) -> list[list[float | None]]:
-        """Per reference, per target token, the score that reference got on the same sound (None: it does not have it)."""
-        return [[None if cell is None else cell[0] for cell in row] for row in Scorer._ref_rows(toks, refs)]
-
-    def _carriers(self, ipa: str) -> list[list[list[int]]]:
-        """For each word, for each of its phonemes, the indexes in _targets(ipa) of the tokens that carry it.
-        A phoneme that collapsed into its neighbour (a geminate, a merged sound) shares the neighbour's token."""
-        out, n, last = [], -1, None
-        for word in ipa.split("|"):
-            row = []
-            for ph in word.split():
-                idx = []
-                for tid in self.vocab.token(ph)[0]:
-                    tid = self.vocab.canon[tid]
-                    if tid != last:
-                        n, last = n + 1, tid
-                    idx.append(n)
-                row.append(sorted(set(idx)))
-            out.append(row)
-        return out
-
-    def _targets(self, ipa: str) -> list[TargetToken]:
-        """Target tokens on the merged sound classes (two neighbours that became one sound collapse, as in CTC)."""
-        out: list[TargetToken] = []
-        for t in tokenize(ipa, self.vocab):
-            tid = self.vocab.canon[t.id]
-            if not out or out[-1].id != tid:
-                out.append(replace(t, id=tid))
-        return out
-
-    @staticmethod
-    def _spellings(ipa: str, toks: list[TargetToken]) -> list[str]:
-        """How each target token is written in the phrase bank, geminates included ("m m")."""
-        runs: list[tuple[int, str, int]] = []  # (word, phoneme, repeat)
-        for w, word in enumerate(ipa.split("|")):
-            for ph in map(written, word.split()):
-                if runs and runs[-1][:2] == (w, ph):
-                    runs[-1] = (w, ph, runs[-1][2] + 1)
-                else:
-                    runs.append((w, ph, 1))
-        if [(w, ph) for w, ph, _ in runs] != [(t.word, t.phoneme) for t in toks]:
-            return [t.phoneme for t in toks]  # tokens merged across a boundary: no geminate info
-        return [" ".join([ph] * n) for _, ph, n in runs]
-
-    def _heard_hebrew(self, logp: np.ndarray, toks: list[TargetToken], al, ipa: str, ar_words: list[str]) -> list[str]:
-        """What the model heard, in Hebrew letters, cut at the times where the expected words begin.
-
-        A sound heard as expected is written the way the answer writes it (length, gemination, emphasis:
-        things the scorer does not tell apart), so the two lines differ only where the scorer heard a difference.
-        A letter with several correct realisations is written as the one said (כּ for a rural ق), not coloured.
-        """
-        n_words = len(ipa.split("|"))
-        starts = [None] * n_words  # first frame of each expected word
-        expected: dict[int, tuple[int, str]] = {}  # frame -> (token id, its spelling)
-        for tok, (a, b), spell in zip(toks, al.spans, self._spellings(ipa, toks)):
-            if starts[tok.word] is None:
-                starts[tok.word] = a
-            for t in range(a, b):
-                expected[t] = (tok.id, spell)
-        heard: list[list[str]] = [[] for _ in range(n_words)]
-        prev, w = None, 0
-        for t, i in enumerate(logp[:, :self.vocab.n_real].argmax(1)):
-            i = int(i)
-            if i != prev and i != self.vocab.blank:
-                while w + 1 < n_words and starts[w + 1] is not None and t >= starts[w + 1]:
-                    w += 1
-                ph = base(self.vocab.i2t[i])
-                tid, spell = expected.get(t, (None, ""))
-                if tid == i:
-                    heard[w].append(spell)
-                elif i in self.vocab.members.get(tid, ()):
-                    heard[w].append(spell if base(spell.split()[0]) == ph else ph)
-                elif ph in HEBREW_SOUNDS:
-                    heard[w].append(ph)
-            prev = i
-        # the Arabic spelling is passed so the heard line follows the answer's conventions (ק for ق, silent ל)
-        return [word_to_hebrew(" ".join(phs), ar_words[w] if w < len(ar_words) else "") for w, phs in enumerate(heard)]
-
-    def _variants(self, phrase: dict) -> list[tuple[str, str, str, list[TargetToken]]]:
-        """(arabic, ipa, ipa with symbols, tokens) for each accepted variant and its diphthong forms. Variants
-        that differ only in how a many-ways letter is said (ʔ / q / k for ق) become one: the first written.
-        A diphthong form the model has no symbols for is left out."""
-        out, seen, off = [], set(), self._off_symbols()
-        for ar, ipa in phrase["variants"]:
-            forms = (ipa, *diphthong_variants(ar, ipa)) if self._on("diphthong") else (ipa,)
-            for n, form in enumerate(forms):
-                aipa = archify(ar, form, off)
-                if aipa in seen:
-                    continue
-                seen.add(aipa)
-                try:
-                    out.append((ar, form, aipa, self._targets(aipa)))
-                except KeyError:
-                    if n == 0:
-                        raise
-        return out
-
-    def _fit(self, logp: np.ndarray, phrase: dict, energy: np.ndarray | None = None) -> Fit | None:
-        """The accepted variant the audio fits best and the score of each of its sounds, from merged
-        posteriors, or None if the recording is too short for every variant."""
-        blank, vocab = self.vocab.blank, self.vocab
-        heard_ids = greedy_decode(logp[:, :vocab.n_real], blank)
-        cands = self._variants(phrase)
-        ext = vocab.extend(logp)  # after tokenising: a variant may have brought a new class
-        best, tried, paths = None, [], []
-        for ar, ipa, aipa, toks in cands:
-            al = ctc_viterbi(ext, [t.id for t in toks], blank)
-            tried.append((ar, ipa, round(al.total_logp, 2) if al else None))
-            paths.append([t.sound for t in toks])
-            if al and (best is None or al.total_logp > best[4].total_logp):
-                best = (ar, ipa, aipa, toks, al)
-        if best is None:
-            return None
-
-        ar, ipa, aipa, toks, al = best
-        ids = [t.id for t in toks]
-        ar_words = ar.split()
-        scores = score_tokens(ext, al, ids, blank, self.cfg.gop, [vocab.members.get(i) for i in ids],
-                              vocab.n_real, self.named if self._on("unnamed_sounds") else None, energy,
-                              vowels=[t.phoneme in VOWELS for t in toks], edges=self._glide_edges(toks))
-        gop_scores, exempted = list(scores), [None] * len(scores)
-        for i, (t, sc) in enumerate(zip(toks, scores)):
-            heard = vocab.i2t.get(sc.competitor) if sc.competitor is not None else None
-            for name, applies, floor in EXEMPTIONS:
-                if self._on(name) and applies(toks, i, sc, heard, ar_words):
-                    scores[i] = replace(sc, score=max(sc.score, 100.0 if floor is None else getattr(self.cfg, floor)))
-                    exempted[i] = name
-                    break
-        exempt_scores = list(scores)
-        inserted = self._insertions(logp, toks, al)
-        cap = float((self.rules.insertion or {}).get("score_cap", 60))
-        for j in inserted:
-            scores[j] = replace(scores[j], score=min(scores[j].score, cap))
-        insert_scores = list(scores)
-        shortened = self._shortened(toks, al, scores, energy)
-        cap = float((self.rules.length or {}).get("score_cap", 60))
-        for j in shortened:
-            scores[j] = replace(scores[j], score=min(scores[j].score, cap))
-        same = lambda h, t: h == t or h in vocab.members.get(t, ())
-        raw = edit_distance(heard_ids, ids, same)
-        distance, weight = self._distance(heard_ids, toks, gop_scores, exempted, same)
-        veto = self._veto(toks, gop_scores, exempted)
-        unrelated = bool(distance / weight > self.cfg.unrelated_ratio) and not veto
-        return Fit(ar, ipa, aipa, toks, al, scores, heard_ids, unrelated, ext, candidates=tried, gop_scores=gop_scores,
-                   exempted=exempted, exempt_scores=exempt_scores, inserted=inserted, insert_scores=insert_scores,
-                   shortened=shortened, distance=distance, energy=energy,
-                   paths=paths, raw_distance=raw, distance_weight=weight, veto=veto)
-
-    # heard at the very start or end of the recording, these are usually breath or noise, not a sound of another word
-    _EDGE_NOISE = {"h", "θ", "f", "s", "x", "χ"}
-    _ANY_VOWEL = {"a", "e", "i", "o", "u", "ə", "ɪ", "ʊ", "ɛ", "ɔ", "æ", "ɐ", "ɑ"}
-    _FREE_DROPS = {"glottal_dropped", "article_vowel_elided"}
-    _SHORT_VOWELS = {"a", "e", "i", "o", "u"}
-
-    def _distance(self, heard_ids: list[int], toks: list[TargetToken], gop_scores: list[TokenScore],
-                  exempted: list[str | None], same, lost: frozenset[int] = frozenset()) -> float:
-        """How far the free decode is from the chosen variant, forgiving only what the exemptions mean:
-        - a vowel heard as another vowel: 0 when it is the competitor an exemption forgave, else 0.25 (a consonant
-          for a vowel: 1);
-        - a consonant heard as the competitor its exemption forgave (b/p, t/d): 0. The exemptions that forgive a
-          dropped sound (_FREE_DROPS) do not forgive a replaced one;
-        - a deletion: 0 for _FREE_DROPS, 0.25 for another exempted short vowel, else 1;
-        - edge noise (_EDGE_NOISE before the first or after the last sound): 0.25;
-        - a sound in `lost` (the native reference lost it too, under ref_noise_floor) replaced or dropped: 0.25.
-        Returns (distance, weight): weight is the sum of the deletion costs, the sounds that can be wrong at all, and
-        at least half the sounds, so a short word does not turn unrelated on one stray sound."""
-        i2t, n = self.vocab.i2t, len(toks)
-        name = lambda h: base(i2t.get(h, ""))
-        comp = [name(sc.competitor) if sc.competitor is not None else None for sc in gop_scores]
-
-        def sub(h, j):
-            if same(h, toks[j].id):
-                return 0.0
-            if j in lost:
-                return 0.25
-            heard = name(h)
-            if toks[j].phoneme in VOWELS:
-                return (0.0 if exempted[j] and comp[j] == heard else 0.25) if heard in self._ANY_VOWEL else 1.0
-            if (exempted[j] and exempted[j] not in self._FREE_DROPS and comp[j] == heard
-                    and heard not in self._ANY_VOWEL):
-                return 0.0
-            return 1.0
-
-        def dele(j):
-            if exempted[j] in self._FREE_DROPS:
-                return 0.0
-            return 0.25 if exempted[j] and toks[j].phoneme in self._SHORT_VOWELS else 1.0
-
-        def dele_cost(j):
-            return min(dele(j), 0.25) if j in lost else dele(j)
-
-        def ins(h, j):
-            return 0.25 if j in (0, n) and name(h) in self._EDGE_NOISE else 1.0
-
-        weight = max(1.0, n / 2, sum(dele(j) for j in range(n)))   # the same with or without `lost`
-        return weighted_edit_distance(heard_ids, [t.id for t in toks], sub, dele_cost, ins), weight
-
-    def _veto(self, toks: list[TargetToken], gop_scores: list[TokenScore], exempted: list[str | None],
-              lost: frozenset[int] = frozenset()) -> bool:
-        """The forced alignment clearly found the sentence's consonants (ScorerConfig.unrelated_veto_*).
-        A consonant that says nothing either way is left out: one an exemption lets drop (ʔ), and one the native
-        reference lost too (`lost`)."""
-        cfg = self.cfg
-        mute = lambda i: i in lost or exempted[i] in self._FREE_DROPS
-        cons = [sc for i, (t, sc) in enumerate(zip(toks, gop_scores)) if t.phoneme not in VOWELS and not mute(i)]
-        rest = [sc.score for i, sc in enumerate(gop_scores) if not mute(i)]
-        if not cons or not rest:
-            return False
-        sure = sum(float(np.exp(sc.peak)) >= cfg.unrelated_veto_peak for sc in cons)
-        return (sure >= 2 and sure / len(cons) >= cfg.unrelated_veto_share
-                and float(np.mean(rest)) >= cfg.unrelated_veto_mean)
-
-    def _heatmap(self, logp: np.ndarray, toks: list[TargetToken], alignment, scores,
-                 duration_s: float | None) -> dict:
-        """A compact posterior heatmap for teacher diagnostics: expected sounds, strongest competitors and blank.
-
-        Max-pooling preserves short phoneme peaks while capping the response at 180 time columns.
-        A letter with several correct realisations is one row, the pooled posterior, labelled "ʔ/k/q".
-        """
-        expected_ids = list(dict.fromkeys(t.id for t in toks))
-        competitor_ids = list(dict.fromkeys(sc.competitor for sc in scores
-                                            if sc.competitor is not None and sc.competitor not in expected_ids))[:6]
-        ids = expected_ids + competitor_ids + ([self.vocab.blank] if self.vocab.blank not in expected_ids else [])
-        frames, bins = len(logp), min(len(logp), 180)
-        edges = np.linspace(0, frames, bins + 1, dtype=int)
-        labels = {t.id: ("/".join(self.vocab.i2t[m] for m in sorted(self.vocab.members[t.id]))
-                         if t.id in self.vocab.members else t.phoneme) for t in toks}
-        rows = []
-        for token_id in ids:
-            probability = np.exp(logp[:, token_id])
-            values = [round(100 * float(probability[edges[i]:edges[i + 1]].max())) for i in range(bins)]
-            rows.append({"phoneme": labels.get(token_id, "blank" if token_id == self.vocab.blank
-                                                else self.vocab.i2t.get(token_id, "?")),
-                         "expected": token_id in expected_ids, "values": values})
-        greedy = logp[:, :self.vocab.n_real].argmax(1)
-        heard = []
-        start = 0
-        for end in range(1, frames + 1):
-            if end < frames and greedy[end] == greedy[start]:
-                continue
-            token_id = int(greedy[start])
-            if token_id != self.vocab.blank:
-                heard.append({"phoneme": self.vocab.i2t.get(token_id, "?"), "start": start, "end": end})
-            start = end
-        expected = [{"phoneme": tok.phoneme, "start": span[0], "end": span[1]}
-                    for tok, span in zip(toks, alignment.spans)]
-        return {"duration_ms": round(1000 * duration_s) if duration_s is not None else None,
-                "frames": frames, "frame_bins": bins, "rows": rows,
-                "tracks": {"expected": expected, "heard": heard}}
-
-    def _max_tips(self) -> int:
-        """As many tips as the rules document says (3), or the 4 of before when its severity order is off."""
-        if self.cfg.max_tips:
-            return self.cfg.max_tips
-        return int(self.rules.scoring.get("max_tips", 4)) if self._on("tips_by_severity") else 4
-
-    def _beyond_margin(self, tok: TargetToken, sc: TokenScore, heard: str | None) -> bool:
-        """Is the competitor likelier than the target by more than the pair's margin? Pairs the model confuses
-        on natives too (emphatics, a dropped h) need a clearer win before they count as a mistake."""
-        targets = [tok.sound, tok.phoneme]
-        if sc.deleted:
-            return sc.peak <= self.cfg.gop.deleted_peak - self._margin(targets, "_")
-        if heard is None:
-            return True
-        return -sc.gop >= self._margin(targets, heard)
-
-    def _evidenced(self, sc: TokenScore) -> bool:
-        """Did the competitor show up in the audio: win at least one frame, or reach the confident posterior?
-        A competitor barely likelier than a weak target, and winning no frame, is no finding (a tip needs this)."""
-        return sc.comp_frames >= 1 or sc.comp_peak >= float(np.log(self.cfg.gop.confident_peak))
-
-    def _heard(self, tok: TargetToken, sc: TokenScore) -> str | None:
-        """What took the sound's place, the same way for a learner and a native reference: "_" when the sound is
-        missing, the competitor's symbol when it won beyond the pair's margin with evidence, None when it was kept."""
-        if sc.deleted:
-            return "_"
-        sym = self.vocab.i2t.get(sc.competitor) if sc.competitor is not None else None
-        if sym is None or sc.gop >= 0 or not self._evidenced(sc) or not self._beyond_margin(tok, sc, sym):
-            return None   # no competitor, the target won, no evidence, or not by the pair's margin
-        return sym
-
-    def _margin(self, targets: list[str], heard: str | None) -> float:
-        """The pair's margin (rules 6.2), or the default for every pair when the teacher switched margins off."""
-        return self.rules.margin(targets if self._on("margins") else [], heard)
-
-    def _dialect(self, toks: list[TargetToken], scores: list[TokenScore]) -> dict:
-        """Which dialect the accepted realisations point to: {"dialect": urban | rural} when they agree,
-        {"mixed_dialect": True} when one is urban-only and another rural-only. Never part of the score."""
-        seen: set[str] = set()
-        for t, sc in zip(toks, scores):
-            if sc.realised is None or sc.score < self.cfg.issue_below:
-                continue
-            ds = self.rules.dialects_of(t.sound, base(self.vocab.i2t[sc.realised]))
-            if len(ds) == 1:
-                seen |= ds
-        if len(seen) > 1:
-            return {"mixed_dialect": True}
-        return {"dialect": next(iter(seen))} if seen else {}
-
-    def score_logp(self, logp: np.ndarray, phrase: dict, refs: list[Reference] = (), diagnostics: bool = False,
-                   duration_s: float | None = None, energy: np.ndarray | None = None) -> dict:
-        logp = self.vocab.merge(logp)
-        fit = self._fit(logp, phrase, energy)
-        if fit is None:
-            return {"error": "too_short", "message": "ההקלטה קצרה מדי. החזיקו את הכפתור ואמרו את כל המשפט."}
-        ar, ipa, toks, al, scores, unrelated = fit.ar, fit.ipa, fit.toks, fit.al, fit.scores, fit.unrelated
-        i2t = self.vocab.i2t
-        heard = " ".join(i2t[i] for i in fit.heard_ids)
-        # Measure against what the model gives a native on the same sound: a sound it misses in the
-        # reference voice too (ʕ in على heard as dropped) is the model's weakness, not the learner's.
-        heatmap = self._heatmap(fit.logp, toks, al, scores, duration_s) if diagnostics else None
-        raw, (bases, refused) = scores, self._baseline(toks, scores, refs)
-        floor_ = self.cfg.ref_noise_floor
-        # under the noise floor the ratio of two near-zero scores is noise (0.3 / 0.2 was capped to 30): give it back
-        scores = [sc if b is None or b >= 100
-                  else replace(sc, score=100.0) if b < floor_
-                  else replace(sc, score=round(min(100.0, 100.0 * sc.score / b), 1))
-                  for sc, b in zip(raw, bases)]
-        after_baseline = scores
-        # the unrelated gate ran before the references were known: a sound they lost too is the model's limitation
-        # in this phrase, not a sign of another sentence, so the gate is decided again without counting it
-        lost = frozenset(i for i, b in enumerate(bases) if b is not None and b < floor_)
-        if lost and unrelated:
-            same = lambda h, t: h == t or h in self.vocab.members.get(t, ())
-            distance, weight = self._distance(fit.heard_ids, toks, fit.gop_scores, fit.exempted, same, lost)
-            veto = self._veto(toks, fit.gop_scores, fit.exempted, lost)
-            unrelated = bool(distance / weight > self.cfg.unrelated_ratio) and not veto
-            fit = replace(fit, distance=distance, distance_weight=weight, veto=veto, unrelated=unrelated)
-        # Teacher floors take priority. The base model has a recurring false negative for pharyngeal ʕ;
-        # when it reports only silence there, keep a modest penalty instead of claiming it was certainly absent.
-        phrase_key, calibrated = str(phrase.get("key", phrase.get("he", ""))), []
-        adjusted, floors = [], []
-        for tok, sc in zip(toks, scores):
-            heard_ph = "_" if sc.deleted else (i2t.get(sc.competitor) if sc.competitor is not None else "")
-            floor = next((self.calibrations[k] for k in ((tok.sound, heard_ph, phrase_key), (tok.sound, heard_ph, ""),
-                                                         (tok.phoneme, heard_ph, phrase_key), (tok.phoneme, heard_ph, ""))
-                          if k in self.calibrations), None)
-            if floor is None and tok.sound == "ʕ" and heard_ph == "_":
-                floor = self.cfg.ayin_deleted_floor
-            floors.append(floor)
-            if floor is not None and sc.score < floor:
-                calibrated.append({"expected": tok.phoneme, "heard": heard_ph, "from": round(sc.score), "to": round(floor)})
-                sc = replace(sc, score=floor)
-            adjusted.append(sc)
-        scores = adjusted
-        forgiven = {t.word for t, sc, r in zip(toks, scores, raw) if sc.score > r.score}
-
-        phonemes, tips, seen = [], [], set()
-        heard_as = []   # per phoneme, what took its place ("_": nothing), flagged or not: the reason a letter gives
-        checks = []     # per phoneme, the rule for what took its place (None: no rule)
-        beyond = []     # per phoneme, whether what took its place won by the pair's margin
-        ar_words = ar.split()
-        tr_words = to_hebrew(ipa, ar)
-        for idx, (tok, sc) in enumerate(zip(toks, scores)):
-            heard_ph = "_" if sc.deleted else (i2t.get(sc.competitor) if sc.competitor is not None else None)
-            # a competitor with no acoustic evidence (won no frame, never confident) is not named: no substitution
-            # tip and no "heard as" for its letter, whose score stays as it is
-            unevidenced = heard_ph is not None and not sc.deleted and not self._evidenced(sc)
-            if unevidenced:
-                heard_ph = None
-            check = self._check(tok, heard_ph)
-            beyond.append(self._beyond_margin(tok, sc, heard_ph))
-            flagged = (bool(sc.score < self.cfg.flag_below_sound.get(tok.sound, self.cfg.flag_below)) and beyond[-1]
-                       and not unevidenced and (tok.phoneme not in VOWELS or self._flag_vowel(toks, idx)))
-            # a long vowel said short (3.8): heard as its short vowel, with the rule's tip, unless the native
-            # reference was as short (the baseline gave the score back)
-            short = idx in fit.shortened and sc.score < self.cfg.issue_below
-            if short:
-                spec, heard_ph, flagged, beyond[-1] = self.rules.length, tok.phoneme.rstrip("ː"), True, True
-                check = Check(spec["rule"], tok.phoneme, heard_ph, int(spec["severity"]), str(spec["feedback"]))
-            if idx in fit.inserted:   # a vowel before this consonant (3.10): the reason its letter gives
-                spec = self.rules.insertion
-                heard_as.append("+" + fit.inserted[idx])
-                checks.append(Check(spec["rule"], tok.phoneme, "+", int(spec["severity"]), str(spec["feedback"])))
-            else:
-                heard_as.append(heard_ph)
-                checks.append(check)
-            p = {"ipa": tok.phoneme, "word": tok.word, "score": sc.score,
-                 "flagged": flagged, "heard": heard_ph if flagged else None}
-            if idx in fit.inserted:
-                p["inserted"] = fit.inserted[idx]
-            if short:
-                p["shortened"] = fit.shortened[idx]["ratio"]
-            if tok.sound != tok.phoneme:
-                p["sound"] = tok.sound
-            if sc.realised is not None:
-                p["realised"] = base(i2t[sc.realised])
-            phonemes.append(p)
-            if short and not unrelated:
-                if check.rule not in seen:
-                    seen.add(check.rule)
-                    tips.append({"title": self.rules.titles.get(check.rule, check.rule), "text": check.feedback,
-                                 "key": check.rule, "severity": check.severity,
-                                 "word": ar_words[tok.word] if tok.word < len(ar_words) else "",
-                                 "word_tr": tr_words[tok.word], "idx": idx, "score": round(sc.score)})
-            elif flagged and not unrelated:
-                tip = tip_for(tok.sound, heard_ph, check)
-                if tip and tip["key"] not in seen:
-                    seen.add(tip["key"])
-                    tip["word"] = ar_words[tok.word] if tok.word < len(ar_words) else ""
-                    tip["word_tr"] = tr_words[tok.word]
-                    tip["idx"] = idx
-                    tip["score"] = round(sc.score)
-                    tips.append(tip)
-            if idx in fit.inserted and not unrelated and "cluster" not in seen:
-                seen.add("cluster")
-                spec = self.rules.insertion
-                tips.append({"title": self.rules.titles.get(spec["rule"], spec["rule"]), "text": str(spec["feedback"]),
-                             "key": spec["rule"], "severity": int(spec["severity"]),
-                             "word": ar_words[tok.word] if tok.word < len(ar_words) else "",
-                             "word_tr": tr_words[tok.word], "idx": idx, "score": round(sc.score)})
-
-        n_words = len(ipa.split("|"))
-        heard_words = self._heard_hebrew(logp, toks, al, fit.aipa, ar_words)
-        words, k = [], self.cfg.word_min_weight
-        carriers, ipa_words = self._carriers(fit.aipa), ipa.split("|")
-        for w in range(n_words):
-            ws = [p["score"] for p in phonemes if p["word"] == w]
-            # the transliteration letter by letter, each with the weakest score among its sounds; a letter the
-            # page colours (under LETTER_GOOD) also says why: what that sound was heard as, and how to say it
-            letters = []
-            for text, at in word_letters(ipa_words[w], ar_words[w] if w < len(ar_words) else ""):
-                got = [i for j in at for i in carriers[w][j] if 0 <= i < len(phonemes)]
-                worst = min(got, key=lambda i: phonemes[i]["score"]) if got else None
-                letter = {"t": text, "score": phonemes[worst]["score"] if got else None}
-                if got and letter["score"] < LETTER_GOOD and not unrelated:
-                    letter.update(letter_reason(toks[worst].sound, heard_as[worst], checks[worst]))
-                letters.append(letter)
-            if w in forgiven and min(ws) >= self.cfg.issue_below:
-                heard_words[w] = tr_words[w]  # what differs from the answer here is what a native voice gets too
-            words.append({"ar": ar_words[w] if w < len(ar_words) else "", "tr": tr_words[w], "heard_tr": heard_words[w],
-                          "score": round(k * min(ws) + (1 - k) * float(np.mean(ws)), 1) if ws else 0.0,
-                          "letters": letters, "phonemes": [p for p in phonemes if p["word"] == w]})
-
-        weights = np.array([0.5 if p["ipa"] in VOWELS else 1.0 for p in phonemes])
-        phone_mean = float(np.dot(weights, [p["score"] for p in phonemes]) / weights.sum())
-        word_mean = float(np.mean([w["score"] for w in words]))
-        overall = 0.5 * phone_mean + 0.5 * word_mean  # one wrong consonant must pull the sentence down
-        if unrelated:
-            overall = min(overall, 30.0)
-        # most crucial first: the mistakes that change meaning (severity 3), then the worst-scoring sounds
-        max_tips = self._max_tips()
-        tips = (sorted(tips, key=lambda t: (-t["severity"], t["score"])) if self._on("tips_by_severity")
-                else sorted(tips, key=lambda t: t["score"]))[:max_tips]
-        tip_idx, issue_idx = {t["idx"] for t in tips}, []
-
-        # Anything short of 100 must say why: every imprecise sound that did not get a full tip,
-        # weakest first. If nothing is clearly off, name the weakest few.
-        issues = []
-        if round(overall) < 100 and not unrelated:
-            tipped = {t.pop("idx") for t in tips}
-            rest = sorted((i for i in range(len(toks)) if i not in tipped and scores[i].score < 100),
-                          key=lambda i: scores[i].score)
-            picked = [i for i in rest if scores[i].score < self.cfg.issue_below and beyond[i]]
-            if not picked and not tips:
-                picked = rest[:3]
-            issue_idx = picked[:self.cfg.max_issues]
-            for i in issue_idx:
-                tok, sc = toks[i], scores[i]
-                # a one-frame onset spike (rule 31) is no sound the learner said: listed, but not named
-                comp = (i2t.get(sc.competitor) if sc.competitor is not None and fit.exempted[i] != "onset_transient"
-                        else None)
-                if i in fit.inserted:
-                    issues.append({"sound": "תנועה מיותרת לפני " + (sound_name(tok.phoneme) or tok.phoneme),
-                                   "word_tr": tr_words[tok.word], "score": round(sc.score), "missing": False,
-                                   "heard": sound_name(fit.inserted[i])})
-                    continue
-                if phonemes[i].get("shortened") is not None:
-                    issues.append({"sound": sound_name(tok.phoneme) or tok.phoneme, "word_tr": tr_words[tok.word],
-                                   "score": round(sc.score), "missing": False,
-                                   "heard": sound_name(tok.phoneme.rstrip("ː"))})
-                    continue
-                issues.append({"sound": sound_name(tok.sound) or sound_name(tok.phoneme) or tok.phoneme,
-                               "word_tr": tr_words[tok.word], "score": round(sc.score), "missing": bool(sc.deleted),
-                               "heard": None if sc.deleted else sound_name(comp)})
-        for t in tips:
-            t.pop("idx", None)
-        result = {"score": round(overall), "variant": {"ar": ar, "tr": " ".join(tr_words), "ipa": ipa}, "heard_ipa": heard, "heard_tr": " ".join(h for h in heard_words if h),
-                  "unrelated": unrelated, "words": words, "tips": tips, "issues": issues, "references": len(refs),
-                  **self._dialect(toks, scores)}
-        if calibrated:
-            result["calibrated"] = calibrated
-        if heatmap is not None:
-            result["phoneme_heatmap"] = heatmap
-        if diagnostics:
-            result["trace"] = self._trace(fit, refs, bases, after_baseline, floors, scores, phonemes, checks, beyond,
-                                          words, tips, tip_idx, set(issue_idx), phone_mean, word_mean, overall, heard,
-                                          duration_s, refused)
-        return result
-
-    def _trace(self, fit: Fit, refs, bases, after_baseline, floors, scores, phonemes, checks, beyond,
-               words, tips, tip_idx, issue_idx, phone_mean, word_mean, overall, heard,
-               duration_s: float | None = None, refused: list[str | None] | None = None) -> dict:
-        """Every stage of the classification with its numbers, weights and thresholds, for the teacher's view
-        (the 'stages' part of the phoneme analysis). Nothing here changes the result."""
-        cfg, g, i2t = self.cfg, self.cfg.gop, self.vocab.i2t
-        rows = self._ref_rows(fit.toks, refs)
-        per_ref = [[None if c is None else c[0] for c in row] for row in rows]
-        per_heard = [[None if c is None else c[1] for c in row] for row in rows]   # what took the sound's place in each voice
-        refused = refused or [None] * len(fit.toks)
-        p = lambda lp: round(float(np.exp(lp)), 4) if lp > -1e20 else 0.0
-        max_tips = self._max_tips()
-        n, T = len(fit.toks), len(fit.logp)
-        pr = lambda col, a, b: [round(float(x), 3) for x in np.exp(fit.logp[a:b, col])] if col is not None else None
-        tokens = []
-        for i, (tok, gsc, sc) in enumerate(zip(fit.toks, fit.gop_scores, scores)):
-            # the frames the curves show: the sound's window (score_tokens) and a few around it
-            ca, cb = max(0, gsc.window[0] - 4), min(T, gsc.window[1] + 4)
-            curves = {"start": ca, "target": pr(tok.id, ca, cb), "competitor": pr(gsc.competitor, ca, cb),
-                      "prev": pr(fit.toks[i - 1].id, ca, cb) if i else None,
-                      "next": pr(fit.toks[i + 1].id, ca, cb) if i + 1 < n else None,
-                      "blank": pr(self.vocab.blank, ca, cb)}
-            heard_ph = "_" if gsc.deleted else (i2t.get(gsc.competitor) if gsc.competitor is not None else None)
-            members = self.vocab.members.get(tok.id)
-            targets = [tok.sound, tok.phoneme]
-            confidence = min(1.0, p(gsc.peak) / g.confident_peak)
-            check = checks[i]
-            b = bases[i]
-            stages = [
-                {"stage": "gop", "score": gsc.score},
-                {"stage": "exemption", "score": fit.exempt_scores[i].score, "applied": fit.exempted[i]},
-                {"stage": "insertion", "score": fit.insert_scores[i].score, "applied": fit.inserted.get(i)},
-                {"stage": "length", "score": fit.scores[i].score, "applied": fit.shortened.get(i)},
-                {"stage": "baseline", "score": after_baseline[i].score, "ref": b,
-                 "refs": [row[i] for row in per_ref], "heard": [None if h is None else norm(h) for h in (row[i] for row in per_heard)],
-                 "refused": refused[i], "applied": b is not None and b < 100},
-                {"stage": "calibration", "score": sc.score, "floor": floors[i],
-                 "applied": floors[i] is not None and after_baseline[i].score < floors[i]},
-            ]
-            tokens.append({
-                "i": i, "word": tok.word, "ipa": tok.phoneme, "sound": tok.sound,
-                "class": sorted(base(i2t[m]) for m in members) if members else None,
-                "realised": base(i2t[gsc.realised]) if gsc.realised is not None else None,
-                "span": list(fit.al.spans[i]), "window": list(gsc.window), "curves": curves,
-                "p_target": p(gsc.peak), "competitor": heard_ph if not gsc.deleted else None,
-                "competitor_other": gsc.other, "p_competitor": p(gsc.comp_peak),
-                "competitor_frames": gsc.comp_frames,
-                "gop": gsc.gop, "confidence": round(confidence, 3),
-                "gop_factor": round(float(np.exp(gsc.gop * g.leniency)), 3),
-                "confidence_factor": round(float(np.sqrt(confidence)), 3),
-                "deleted": gsc.deleted, "stages": stages, "final": sc.score,
-                "margin": {"needed": self._margin(targets, "_" if gsc.deleted else heard_ph),
-                           "got": (round(g.deleted_peak - gsc.peak, 3) if gsc.deleted else round(-gsc.gop, 3)),
-                           "beyond": beyond[i]},
-                "vowel": tok.phoneme in VOWELS, "weight": 0.5 if tok.phoneme in VOWELS else 1.0,
-                "flagged": phonemes[i]["flagged"],
-                "rule": {"id": check.rule, "title": self.rules.titles.get(check.rule, check.rule),
-                         "severity": check.severity} if check else None,
-                "tip": i in tip_idx, "issue": i in issue_idx,
-            })
-        return {
-            "config": {
-                "leniency": g.leniency, "confident_peak": g.confident_peak,
-                "consonant_window": g.consonant_window,
-                "deleted_peak": round(float(np.exp(g.deleted_peak)), 3),
-                "deleted_comp": round(float(np.exp(g.deleted_comp)), 3),
-                "flag_below": cfg.flag_below, "flag_below_sound": dict(cfg.flag_below_sound), "issue_below": cfg.issue_below, "near_vowel_floor": cfg.near_vowel_floor,
-                "word_min_weight": cfg.word_min_weight, "vowel_weight": 0.5, "unrelated_ratio": cfg.unrelated_ratio,
-                "unrelated_veto": {"share": cfg.unrelated_veto_share, "peak": cfg.unrelated_veto_peak,
-                                   "mean": cfg.unrelated_veto_mean},
-                "unrelated_cap": 30.0, "letter_good": LETTER_GOOD, "max_tips": max_tips, "max_issues": cfg.max_issues,
-                "ref_min_mean": cfg.ref_min_mean, "ref_noise_floor": cfg.ref_noise_floor, "margin_default": float(self.rules.scoring.get("margin_default", 0.0)),
-                "ayin_deleted_floor": cfg.ayin_deleted_floor, "onset_transient_floor": cfg.onset_transient_floor,
-                "margins": [{"target": t, "heard": h, "margin": m} for (t, h), m in sorted(self.rules.margins.items())]
-                if self._on("margins") else [],
-                "exemptions": [name for name, _, _ in EXEMPTIONS if self._on(name)],
-                "insertion": ({k: self.rules.insertion[k] for k in ("score_cap", "min_peak", "min_frames")}
-                              if self.rules.insertion and self._on(f"rule_{self.rules.insertion['rule']}") else None),
-                "vowel_length": ({k: v for k, v in self.rules.length.items() if k not in ("rule", "feedback")}
-                                 if self.rules.length and self._on(f"rule_{self.rules.length['rule']}") else None),
-                "disabled": sorted(self.disabled),
-            },
-            "variants": [{"ar": ar, "ipa": ipa, "logp": lp, "chosen": ar == fit.ar and ipa == fit.ipa,
-                          "tokens": fit.paths[k] if k < len(fit.paths) else []}
-                         for k, (ar, ipa, lp) in enumerate(fit.candidates)],
-            "frames": {"count": T, "ms": round(1000 * duration_s / T, 2) if duration_s and T else 20.0,
-                       "energy": ([round(float(e), 3) for e in fit.energy / max(float(fit.energy.max()), 1e-9)]
-                                  if fit.energy is not None else None)},
-            "aipa": fit.aipa,
-            "unrelated": {"heard": heard, "distance": round(fit.distance, 2), "raw_distance": fit.raw_distance,
-                          "tokens": n, "weight": round(fit.distance_weight, 2),
-                          "ratio": round(fit.distance / fit.distance_weight, 3), "threshold": cfg.unrelated_ratio,
-                          "veto": fit.veto, "unrelated": fit.unrelated},
-            "references": [{"voice": r.voice or f"קול {k + 1}", "mean": round(float(np.mean(r.scores)), 1),
-                            "sounds": len(r.sounds)} for k, r in enumerate(refs)],
-            "tokens": tokens,
-            "words": [{"tr": w["tr"], "scores": [ph["score"] for ph in w["phonemes"]],
-                       "min": min((ph["score"] for ph in w["phonemes"]), default=0.0),
-                       "mean": round(float(np.mean([ph["score"] for ph in w["phonemes"]])), 1) if w["phonemes"] else 0.0,
-                       "score": w["score"]} for w in words],
-            "sentence": {"phone_mean": round(phone_mean, 1), "word_mean": round(word_mean, 1),
-                         "phone_weight": 0.5, "word_weight": 0.5,
-                         "before_cap": round(0.5 * phone_mean + 0.5 * word_mean, 1), "final": round(overall),
-                         "capped": fit.unrelated},
-            "tips": [{"key": t["key"], "severity": t["severity"], "score": t["score"]} for t in tips],
-        }
-
-
-# ---------- real model ----------
-
-class HFEmitter:
-    """wav2vec2 phoneme CTC model from the Hugging Face hub (or a local fine-tuned checkpoint)."""
-
-    def __init__(self, model_id: str, device: str | None = None):
-        import torch
-        from huggingface_hub import hf_hub_download
-        from transformers import AutoFeatureExtractor, Wav2Vec2ForCTC
-
-        self.torch = torch
-        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
-        self.fe = AutoFeatureExtractor.from_pretrained(model_id)
-        self.model = Wav2Vec2ForCTC.from_pretrained(model_id).to(self.device).eval()
-        vocab_path = (os.path.join(model_id, "vocab.json") if os.path.isdir(model_id)
-                      else hf_hub_download(model_id, "vocab.json"))
-        with open(vocab_path, encoding="utf-8") as f:
-            self.token_to_id: dict[str, int] = json.load(f)
-
-    def __call__(self, wav: np.ndarray) -> np.ndarray:
-        inputs = self.fe(wav, sampling_rate=SAMPLE_RATE, return_tensors="pt")
-        with self.torch.inference_mode():
-            logits = self.model(inputs.input_values.to(self.device)).logits[0]
-            return self.torch.log_softmax(logits.float(), -1).cpu().numpy()
-
-
-def decode_audio_with_timing(data: bytes) -> tuple[np.ndarray, int]:
-    """Decodes audio and returns (trimmed 16 kHz samples, samples removed from its start)."""
-    proc = subprocess.run(
-        ["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", "pipe:0",
-         "-t", str(MAX_SECONDS), "-ac", "1", "-ar", str(SAMPLE_RATE), "-f", "f32le", "pipe:1"],
-        input=data, capture_output=True, check=False)
-    if proc.returncode != 0:
-        raise ValueError(proc.stderr.decode(errors="replace")[:300])
-    wav = np.frombuffer(proc.stdout, dtype=np.float32)
-    trim_start = 0
-    # trim leading/trailing silence so CTC isn't fed seconds of blank
-    if wav.size:
-        frame = 320
-        energy = np.sqrt(np.convolve(wav ** 2, np.ones(frame) / frame, mode="same"))
-        voiced = np.where(energy > max(0.01, energy.max() * 0.05))[0]
-        if voiced.size:
-            pad = SAMPLE_RATE // 5
-            trim_start = max(0, int(voiced[0]) - pad)
-            wav = wav[trim_start:voiced[-1] + pad]
-    return wav, trim_start
-
-
-def decode_audio(data: bytes) -> np.ndarray:
-    """Any browser recording (webm/opus, ogg, mp4/aac, wav) -> trimmed 16 kHz mono float32."""
-    return decode_audio_with_timing(data)[0]
-
-
-# Per-sound flag thresholds, chosen per model on the Minerva dev split and checked on its test split
-# (scripts/minerva_benchmark.py --sweep / --compare, with the TTS baselines). A threshold belongs to the model it was
-# measured on: another model (a fine-tuned checkpoint) starts from the global flag_below until it is measured too.
-FLAG_BELOW_BY_MODEL: dict[str, dict[str, float]] = {
-    # The base model hears a correct ح as ه/خ with scores in the 20s-40s: at 50 it flagged 12.7% of natives' ح;
-    # at 20, 5.6%, still catching 69% of خ and 71% of ه said for ح (was 76% / 75%).
-    "facebook/wav2vec2-xlsr-53-espeak-cv-ft": {"ħ": 20.0},
-}
-
-
-def scorer_config(model_id: str) -> ScorerConfig:
-    return ScorerConfig(flag_below_sound=dict(FLAG_BELOW_BY_MODEL.get(model_id, {})))
-
-
-def load_scorer(model_id: str) -> Scorer:
-    from .powsm import PowsmEmitter, PowsmOnnxEmitter, onnx_model_dir, parse_model_id
-    powsm, exported = parse_model_id(model_id), onnx_model_dir(model_id)
-    if exported:  # an exported POWSM-CTC (scripts/export_powsm_onnx.py): onnxruntime only, what the Space runs
-        emitter = PowsmOnnxEmitter(str(exported))
-        vocab = Vocab(emitter.token_to_id, blank_token=emitter.blank_token)
-    elif powsm:  # POWSM-CTC through ESPnet (app/powsm.py): a local trial, needs .zero-shot-deps
-        emitter = PowsmEmitter(*powsm)
-        vocab = Vocab(emitter.token_to_id, blank_token=emitter.blank_token)
-    else:
-        emitter = HFEmitter(model_id)
-        vocab = Vocab(emitter.token_to_id)
-    scorer = Scorer(emitter, vocab, scorer_config(model_id))
-    # resolve every phoneme once at startup so missing symbols show up in the logs and /api/health
-    from .phrases import PHRASES
-    for p in PHRASES:
-        for ar, ipa in p["variants"]:
-            tokenize(archify(ar, ipa), vocab)
-    if vocab.downgraded:
-        log.warning("phonemes mapped to fallbacks: %s", vocab.downgraded)
-    if vocab.class_missing:
-        log.warning("realisations the model cannot hear, left out of their letter's class: %s", vocab.class_missing)
-    return scorer

app/speech_evaluation.py

@@ -1,28 +0,0 @@
-"""Replaceable speech policy for spoken conjugation exercises.
-
-The acoustic scorer is Palestinian-Arabic aware at the phoneme level, but it is not
-treated as a general dialect ASR.  In particular, an unrelated/low-confidence result
-asks for a retry instead of becoming a grammatical error.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-
-class SpeechEvaluationService:
-    def __init__(self, scorer: Any, pass_score: int = 75):
-        self.scorer = scorer
-        self.pass_score = pass_score
-
-    def evaluate(self, wav, phrase: dict, diagnostics: bool = False) -> dict:
-        result = self.scorer.score(wav, phrase, diagnostics=diagnostics)
-        if result.get("error"):
-            return {**result, "outcome": "uncertain", "counts_as_attempt": False}
-        if result.get("unrelated"):
-            return {**result, "outcome": "uncertain", "counts_as_attempt": False,
-                    "message": "לא הצלחתי לזהות בביטחון את ההטיה. האזינו להקלטה ונסו שוב."}
-        correct = int(result.get("score", 0)) >= self.pass_score
-        return {**result, "outcome": "correct" if correct else "needs_work",
-                "error_kind": None if correct else "undetermined",
-                "correct": correct, "counts_as_attempt": True,
-                "message": "נכון" if correct else "לא הצלחתי לאשר את התשובה. הקשיבו להקלטה ולתשובה ונסו שוב."}

app/texts.py

@@ -1,189 +0,0 @@
-"""Texts the teacher adds in the panel: a story or a dialogue, practised line by line like the course's conversation.
-
-The teacher gives each line twice: in Hebrew, and in Arabic written in Hebrew letters, as the course writes it
-(pointed, geresh for the sounds Hebrew lacks, ّ for doubling: כִּיף חַאלַכּ). The scorer needs the line's phonemes
-and the answer's voice needs it in Arabic letters, so each word is read here:
-  a word of the course (LEX in workbook.py), found by its transliteration, gets the course's own Arabic spelling and
-  accepted pronunciations. Dagesh, shva and the final letters' forms are not compared, and a word written without
-  points is found by its letters alone;
-  any other word is read by rule, letter by letter (`_guess`). Short vowels come from the points, so an unpointed
-  word that the course does not have is read badly. Such words are reported back to the teacher (`guessed`).
-"""
-from __future__ import annotations
-
-import re
-
-from .workbook import LEX, _variants
-
-SHVA, DAGESH, SHADDA = "\u05b0", "\u05bc", "\u0651"
-MARKS = re.compile("[\u05b0-\u05bc\u05c1\u05c2\u05c7\u0651]")
-GERESH = "'\u05f3\u2019\u2018`\u00b4"
-FINALS = {"ך": "כ", "ם": "מ", "ן": "נ", "ף": "פ", "ץ": "צ"}
-VOWEL_OF = {"\u05b7": "a", "\u05b8": "a", "\u05b2": "a", "\u05b4": "i", "\u05bb": "u", "\u05b6": "e", "\u05b1": "e",
-            "\u05b5": "E", "\u05b9": "o", "\u05ba": "o", "\u05b3": "o", "\u05c7": "o"}   # E: tsere, i alone and eː before י
-# letter -> (phoneme, Arabic letter); ק is the urban ʔ, with q as a second reading
-CONS = {"א": ("ʔ", "ا"), "ב": ("b", "ب"), "ג": ("g", "ج"), "ד": ("d", "د"), "ה": ("h", "ه"), "ו": ("w", "و"),
-        "ז": ("z", "ز"), "ח": ("ħ", "ح"), "ט": ("tˤ", "ط"), "י": ("j", "ي"), "כ": ("k", "ك"), "ל": ("l", "ل"),
-        "מ": ("m", "م"), "נ": ("n", "ن"), "ס": ("s", "س"), "ע": ("ʕ", "ع"), "פ": ("f", "ف"), "צ": ("sˤ", "ص"),
-        "ק": ("ʔ", "ق"), "ר": ("r", "ر"), "ש": ("ʃ", "ش"), "ת": ("t", "ت")}
-GERESHED = {"ג": ("dʒ", "ج"), "ח": ("x", "خ"), "ע": ("ɣ", "غ"), "ד": ("dˤ", "ض"), "ט": ("ðˤ", "ظ"), "ת": ("t", "ث"),
-            "ז": ("dʒ", "ج"), "צ": ("sˤ", "ص")}
-PUNCT_AR = {"?": "؟", ",": "،", ";": "؛"}
-Cluster = tuple[str, bool, str]   # a letter, whether it has a geresh, its points
-
-
-def _clusters(word: str) -> list[Cluster]:
-    """The word's letters, each with its geresh and points. A letter in brackets, the article's silent (ל), is left out."""
-    out: list[list] = []
-    for ch in re.sub(r"\([^)]*\)", "", word):
-        if "א" <= ch <= "ת":
-            out.append([FINALS.get(ch, ch), False, ""])
-        elif out and ch in GERESH:
-            out[-1][1] = True
-        elif out and MARKS.fullmatch(ch):
-            out[-1][2] += ch
-    return [(l, g, m) for l, g, m in out]
-
-
-def _key(cl: list[Cluster], points: bool = True) -> str:
-    """What two spellings of one word share: the letters and their vowels, without dagesh (but the vav's) and shva.
-    The article's vowel is one, hiriq or tsere."""
-    def marks(k: int, letter: str, m: str) -> str:
-        keep = {"\u05b7" if c == "\u05b8" else c for c in m if c != SHVA and (c != DAGESH or letter == "ו")}
-        if k == 0 and letter == "א" and "\u05b4" in keep:
-            keep = keep - {"\u05b4"} | {"\u05b5"}
-        return "".join(sorted(keep))
-    return "".join(l + "'" * g + (marks(k, l, m) if points else "") for k, (l, g, m) in enumerate(cl))
-
-
-def _lexicon() -> tuple[dict, dict]:
-    pointed, plain = {}, {}
-    for ar, (tr, ipas) in LEX.items():
-        cl = _clusters(tr)
-        entry = (ar.partition("#")[0], ipas)
-        pointed.setdefault(_key(cl), entry)
-        plain.setdefault(_key(cl, False), entry)
-    return pointed, plain
-
-
-POINTED, PLAIN = _lexicon()
-
-
-def _guess(cl: list[Cluster], silent_l: bool = False) -> tuple[str, list[str]]:
-    """(Arabic spelling, readings) of a word the course does not have, from its letters and points. `silent_l`: the
-    word was written with the article's (ל), so its first vowel is the article."""
-    phs: list[str] = []
-    ar = ""
-    n, i = len(cl), 0
-    bare = lambda c: not c[1] and not any(m in VOWEL_OF or m == SHADDA for m in c[2])   # no vowel of its own
-    pointed = any(m in VOWEL_OF for _, _, marks in cl for m in marks)
-    if n > 1 and cl[0][0] == "ו" and bare(cl[0]) and (DAGESH in cl[0][2] or SHVA in cl[0][2]):   # "and" on the word
-        phs, ar, i = ["u"], "و", 1
-    start, prev = i, None   # prev: the vowel the letter before ended in
-    while i < n:
-        letter, geresh, marks = cl[i]
-        last, vowel = i == n - 1, next((VOWEL_OF[m] for m in marks if m in VOWEL_OF), None)
-        double = SHADDA in marks
-        i += 1
-        if bare((letter, geresh, marks)) and i - 1 > start:   # a letter that only lengthens the vowel before it
-            long = None
-            if letter == "א":
-                long, ar = ("a" if last else "aː"), ar + "ا"
-                if prev:
-                    phs.pop()
-            elif letter == "י" and (prev in ("i", "E") or not prev and last or not pointed and not last):
-                long, ar = ("eː" if prev == "E" else "i" if last else "iː"), ar + "ي"
-                if prev:
-                    phs.pop()
-            elif letter == "ו" and not prev and (DAGESH in marks or not pointed and not last):
-                long, ar = ("u" if last else "uː"), ar + "و"
-            elif letter == "ה" and last and (prev in ("a", "e", "E") or not pointed):   # the feminine ending
-                ar += "ة"
-                if not prev:
-                    phs.append("a")
-                elif prev == "E":
-                    phs[-1] = "e"
-                break
-            if long:
-                phs.append(long)
-                prev = None
-                continue
-        if letter == "ו" and DAGESH in marks and double and not vowel and not prev:   # וּّ
-            phs += ["u", "w", "w"]
-            ar, prev = ar + "وّ", None
-            continue
-        if letter == "ו" and vowel == "o" and not double and not prev and i - 1 > start:   # וֹ
-            phs.append("o" if last else "oː")
-            ar, prev = ar + "و", None
-            continue
-        ph, ar_letter = (GERESHED if geresh and letter in GERESHED else CONS)[letter]
-        if letter == "א" and i - 1 == start and vowel in ("i", "a", "E") and i < n and (
-                cl[i][0] == "ל" and bare(cl[i]) and i + 1 < n or silent_l):   # the article: אִלְ, or אִ(ל) before a doubled letter
-            phs.append("i")
-            ar += "ال"
-            if cl[i][0] == "ל" and bare(cl[i]):
-                phs.append("l")
-                i += 1
-            prev = None
-            continue
-        phs += [ph, ph] if double else [ph]
-        ar += ("ا" if i - 1 == start else "أ") if letter == "א" else ar_letter + (SHADDA if double else "")
-        prev = vowel
-        if vowel:
-            phs.append(("e" if last else "i") if vowel == "E" else vowel)   # a tsere is i inside the word, e at its end
-    main = " ".join(phs)
-    return ar, [main] + ([main.replace("ʔ", "q") if not cl[start][0] == "א" else "ʔ" + main[1:].replace("ʔ", "q")]
-                         if any(l == "ק" for l, _, _ in cl) else [])
-
-
-def _word(token: str) -> tuple[str, list[str], bool] | None:
-    """(Arabic, readings, whether the course has the word) of one written word; None when it has no letters."""
-    cl = _clusters(token)
-    if not cl:
-        return None
-    tail = "".join(PUNCT_AR.get(c, c) for c in re.search(r"[?!.,;:]*$", token)[0])
-    pointed = any(m in VOWEL_OF for _, _, marks in cl for m in marks)
-    for cut, pre_ar, pre_ipa in ((0, "", ""), (1, "و", "u ")):   # the word itself, then "and" written on it
-        if cut and not (len(cl) > 1 and cl[0][0] == "ו" and not cl[0][1] and not any(m in VOWEL_OF for m in cl[0][2])):
-            break
-        hit = POINTED.get(_key(cl[cut:])) if pointed else PLAIN.get(_key(cl[cut:], False))
-        if hit:
-            return pre_ar + hit[0] + tail, [pre_ipa + ipa for ipa in hit[1]], True
-    rest = cl[2:] if len(cl) > 2 and cl[0][0] == "א" and cl[1][0] == "ל" and not any(m in VOWEL_OF for m in cl[1][2]) else \
-        cl[1:] if len(cl) > 1 and cl[0][0] == "א" and "(ל)" in token else None
-    hit = rest and (POINTED.get(_key(rest)) if pointed else PLAIN.get(_key(rest, False)))
-    if hit and not hit[0].startswith("ال"):   # the article on a word of the course: אִלְבֵּית, אִ(ל)סַّיַּארַה
-        said = "i l " if rest is cl[2:] or len(rest) == len(cl) - 2 else "i "
-        double = lambda ipa: ipa if said == "i l " else f"{ipa.split()[0]} {ipa}"
-        return "ال" + hit[0] + tail, [said + double(ipa) for ipa in hit[1]], True
-    ar, ipas = _guess(cl, "(ל)" in token)
-    return (ar + tail, ipas, False) if ipas[0] else None
-
-
-def read_line(tr: str) -> tuple[list[tuple[str, str, list[str]]], list[str]]:
-    """A line of Arabic in Hebrew letters as the words of a phrase, (Arabic, transliteration, readings) each, and
-    the words that were read by rule, as written."""
-    words, guessed = [], []
-    for token in tr.split():
-        word = _word(token)
-        if word is None:   # a dash, a number
-            continue
-        ar, ipas, known = word
-        words.append((ar, token, ipas))
-        if not known:
-            guessed.append(token.strip("?!.,;:\"()"))
-    return words, guessed
-
-
-def text_phrases(cat: str, lines: list[list[str]]) -> tuple[list[dict], list[str]]:
-    """A text's lines ([Hebrew, transliteration] each) as phrases in the format of phrases.py, in the text's order,
-    and its words that were read by rule. `key` is what a recording of the line is kept under: the Hebrew, numbered
-    from its second appearance in the text ("כן (2)"), so that two lines with the same Hebrew stay apart."""
-    out, guessed, seen = [], [], {}
-    for seq, (he, tr) in enumerate(lines, 1):
-        words, new = read_line(tr)
-        guessed += [w for w in new if w not in guessed]
-        seen[he] = seen.get(he, 0) + 1
-        out.append(dict(cat=cat, he=he, tr=tr, variants=_variants(words), seq=seq,
-                        key=he if seen[he] == 1 else f"{he} ({seen[he]})"))
-    return out, guessed

app/tips.py

@@ -1,125 +0,0 @@
-"""Hebrew feedback for the substitutions Hebrew speakers typically make.
-
-Keys are (expected phoneme, heard phoneme); "_" means the expected phoneme was missing.
-Phonemes are in the IPA used by phrases.py; HEARD_ALIASES maps model outputs onto those symbols.
-"""
-import re
-
-from .rules import load as load_rules
-
-NAMES = {
-    "ħ": "ח (ح)", "ʕ": "ע (ع)", "x": "ח' (خ)", "ɣ": "ע' (غ)", "r": "ר (ر)",
-    "q": "ק (ق)", "ʔ": "עצירה סותמית (ء / ق)", "h": "ה (ه)",
-    "sˤ": "צ (ص)", "tˤ": "ט (ط)", "dˤ": "ד' (ض)", "ðˤ": "ט' (ظ)",
-    "k": "כ (ك)", "s": "ס (س)", "t": "ת (ت)", "d": "ד (د)", "z": "ז (ز)",
-    "ʃ": "ש (ش)", "dʒ": "ג' (ج)", "b": "ב (ب)", "f": "פ (ف)", "m": "מ (م)",
-    "n": "נ (ن)", "l": "ל (ل)", "w": "ו (و)", "j": "י (ي)",
-    "tʃ": "צ' (tʃ)", "θ": "ת' (th)", "ð": "ד״ (th)",
-    # letters with several correct realisations (archi.py): named by the letter, not by one way of saying it
-    "Q": "ק (ق)", "K": "כ (ك)", "TH": "ת' (ث)", "DH": "ד״ (ذ)", "ZH": "ט' (ظ)", "J": "ג' (ج)",
-}
-
-# model output symbol -> symbol used in TIPS keys
-HEARD_ALIASES = {"χ": "x", "ɦ": "h", "ɡ": "g", "ʁ": "ʁ"}
-
-_EMPH = "גב הלשון נסוג לאחור והלסת יורדת מעט; התנועות סביב העיצור נשמעות כהות יותר."
-
-TIPS = {
-    ("ħ", "x"): "נהגתה כמו ח' (خ), החי\"ת של העברית המודרנית. ح נוצרת בלוע ולא בחך: מכווצים את הגרון ונושפים, בלי רעש גירוד.",
-    ("ħ", "h"): "נהגתה כמו ה. צריך יותר כיווץ בלוע: הצליל יבש ומתוח, כמו לחישה חזקה מגרון צר.",
-    ("ħ", "_"): "לא נשמעה. ح היא עיצור לועי: מכווצים את שרירי הגרון ונושפים.",
-    ("ʕ", "ʔ"): "נהגתה כמו עצירה (א). ع היא עיצור לועי קולי: מכווצים את הגרון תוך כדי השמעת קול, בלי לסגור אותו.",
-    ("ʕ", "a"): "נבלעה לתוך התנועה. ع דורשת כיווץ ברור של הלוע לפני התנועה.",
-    ("ʕ", "_"): "נבלעה. ע (ع) נהגית תמיד, גם באמצע מילה.",
-    ("x", "ħ"): "נהגתה רכה מדי, כמו ح. خ היא חיכוך בחך הרך, כמו ח' בעברית.",
-    ("x", "h"): "נהגתה כמו ה. خ דורשת חיכוך בחך הרך, כמו ח' בעברית.",
-    ("x", "k"): "נהגתה כעצירה (כ). خ היא חיכוך רציף, בלי סגירה.",
-    ("ɣ", "x"): "נהגתה בלי קול, כמו خ. غ קולית, קרובה מאוד לר' הגרונית של העברית.",
-    ("ɣ", "r"): "נהגתה כמו ר מתגלגלת. غ קרובה לר' העברית הגרונית.",
-    ("ɣ", "g"): "נהגתה כעצירה (ג). غ היא חיכוך רציף ולא סגירה.",
-    ("r", "ʁ"): "ר (ر) נהגתה גרונית, כמו ר' עברית. ر מתגלגלת בקצה הלשון מאחורי השיניים העליונות.",
-    ("r", "ɣ"): "ר (ر) נהגתה גרונית, כמו ר' עברית, וזוהתה כ־غ. ر מתגלגלת בקצה הלשון.",
-    ("r", "x"): "ר (ر) נהגתה גרונית ובלי קול. ر מתגלגלת בקצה הלשון מאחורי השיניים.",
-    ("q", "k"): "ق נהגתה כמו כ/ק עברית. במבטא הכפרי זה מקובל, אבל ق נוצרת עמוק יותר, בענבל.",
-    ("ʔ", "k"): "ق נהגתה כמו כ/ק עברית. בדיבור העירוני ق נהגית כעצירה קצרה בגרון (\"אַהְוֶה\", לא \"קַהְוֶה\").",
-    ("h", "ħ"): "נהגתה חזקה מדי, כמו ح. ه היא נשיפה רכה בלבד.",
-    ("h", "x"): "נהגתה כמו ח' עברית. ه היא נשיפה רכה בלבד, בלי חיכוך.",
-    ("h", "_"): "נבלעה. בערבית ה נהגית תמיד, גם לפני עיצור (קַהְוֶה, פַאהֵם).",
-    ("sˤ", "s"): "נהגתה כ־ס רגילה. ص היא ס מודגשת: " + _EMPH,
-    ("tˤ", "t"): "נהגתה כ־ת רגילה. ط היא ת מודגשת: " + _EMPH,
-    ("dˤ", "d"): "נהגתה כ־ד רגילה. ض היא ד מודגשת: " + _EMPH,
-    ("ðˤ", "z"): "נהגתה כ־ז רגילה. ظ היא ז מודגשת: " + _EMPH,
-    ("ðˤ", "ð"): "נהגתה בלי הדגשה. ظ היא עיצור מודגש: " + _EMPH,
-}
-
-# bare Arabic letter in a tip text -> "Hebrew (Arabic)", so Arabic never appears without a Hebrew reading
-_PAIRED = {name[name.index("(") + 1]: name for name in NAMES.values() if "/" not in name}
-DEFAULT_SEVERITY = 2  # a tip no rule in pronunciation-rules.md grades
-_BARE_AR = re.compile(r"(?<!\()[\u0621-\u064a](?![\u0621-\u064a])")
-
-
-def with_hebrew(text: str) -> str:
-    return _BARE_AR.sub(lambda m: _PAIRED.get(m.group(), m.group()), text)
-
-
-VOWEL_NAMES = {
-    "a": "תנועת אַ", "i": "תנועת אִ", "u": "תנועת אֻ", "e": "תנועת אֶ", "o": "תנועת אוֹ",
-    "aː": "תנועה ארוכה אַא", "iː": "תנועה ארוכה אִי", "uː": "תנועה ארוכה אוּ",
-    "eː": "תנועה ארוכה אֵי", "oː": "תנועה ארוכה אוֹ",
-}
-
-
-def sound_name(phoneme: str | None) -> str | None:
-    """Hebrew name of a phoneme (expected or heard), or None if we have no name for it.
-    Sounds Arabic does not have (p, v, ts) are named by the labels of pronunciation-rules.md."""
-    if phoneme is None:
-        return None
-    phoneme = HEARD_ALIASES.get(phoneme, phoneme)
-    return NAMES.get(phoneme) or VOWEL_NAMES.get(phoneme) or load_rules().label(phoneme)
-
-
-def letter_reason(expected: str, heard: str | None, check=None) -> dict:
-    """Why a letter of the answer is coloured: {"why": the sound and what was heard in its place ("_": nothing was),
-    "tip": how to say it, from the rule for that substitution (`check`, rules.Check) or TIPS}."""
-    name = sound_name(expected) or expected
-    heard = HEARD_ALIASES.get(heard, heard)
-    other = sound_name(heard)
-    if heard and heard.startswith("+"):   # a vowel added before this consonant (rules 3.10)
-        why = f"נוספה {sound_name(heard[1:]) or 'תנועה'} לפני {name}"
-    elif heard == "_":
-        why = f"{name} לא נשמעה"
-    elif other and other != name:
-        why = f"{name} נשמעה כמו {other}"
-    else:
-        why = f"{name} לא נשמעה בבירור"
-    text = check.feedback if check else TIPS.get((expected, heard))
-    return {"why": why, **({"tip": with_hebrew(text)} if text else {})}
-
-
-VOWELS = {"a", "i", "u", "e", "o", "aː", "iː", "uː", "eː", "oː"}
-# the glottal stop (ء, and ق said the urban way) is often dropped by natives too; don't nag about it
-NO_DELETION_TIP = {"ʔ", "Q"}
-
-
-def tip_for(expected: str, heard: str | None, check=None) -> dict | None:
-    """Feedback for one flagged phoneme, or None if there is nothing useful to say.
-
-    `check` (rules.Check) is the rule of pronunciation-rules.md for this substitution: its feedback and
-    severity win over TIPS. The key stays "expected>heard" either way."""
-    if expected in VOWELS and not check:   # a short vowel gets a tip only from a rule that flags it (3.11)
-        return None
-    heard = HEARD_ALIASES.get(heard, heard) if heard else "_"
-    if heard == "_" and expected in NO_DELETION_TIP:
-        return None
-    name = NAMES.get(expected, expected)
-    key = f"{expected}>{heard}"
-    if check:
-        return {"title": name, "text": with_hebrew(check.feedback), "key": key, "severity": check.severity}
-    text = TIPS.get((expected, heard))
-    if text:
-        return {"title": name, "text": with_hebrew(text), "key": key, "severity": DEFAULT_SEVERITY}
-    if heard == "_":
-        return {"title": name, "text": "לא נשמעה בבירור.", "key": key, "severity": DEFAULT_SEVERITY}
-    other = sound_name(heard)
-    text = f"נשמעה כמו {other}." if other else "נשמעה אחרת מהצפוי."
-    return {"title": name, "text": text, "key": key, "severity": DEFAULT_SEVERITY}

app/translit.py

@@ -1,89 +0,0 @@
-"""Hebrew transliteration generated from the IPA in phrases.py.
-
-Used wherever Arabic is shown for a specific variant or word, so every variant gets a reading
-without hand-writing one. Follows the conventions of the hand-written `tr` hints: pointed Hebrew,
-geresh for sounds Hebrew lacks (ח' ע' ג' ד' ט'), and the Arabic shadda (ّ, the small w above
-the letter) for geminates, as the course material writes it. A dagesh only marks the stops בּ כּ.
-"""
-
-CONSONANTS = {
-    "ʔ": "א", "b": "בּ", "t": "ת", "dʒ": "ג'", "ħ": "ח", "x": "ח'", "d": "ד", "r": "ר", "z": "ז",
-    "s": "ס", "ʃ": "ש", "sˤ": "צ", "dˤ": "ד'", "tˤ": "ט", "ðˤ": "ט'", "ʕ": "ע", "ɣ": "ע'", "f": "פ",
-    "q": "ק", "k": "כּ", "g": "ג", "l": "ל", "m": "מ", "n": "נ", "h": "ה", "w": "ו", "j": "י",
-    # rural realisations (pronunciation-rules.md, section 1)
-    "tʃ": "צ'", "θ": "ת'", "ð": "ד״",
-}
-# Sounds Arabic does not have, written only in the line of what was heard, never in an answer: a Hebrew
-# speaker's p for ف, v for و / ب, and Hebrew צ (ts) for ص. Without them the heard line would drop the letter.
-HEARD_ONLY = {"p": "פּ", "v": "ב", "β": "ב", "ʋ": "ב", "ts": "טס"}
-# vowel -> ((mark on the consonant, letter after it) mid-word, (same) word-finally)
-VOWELS = {
-    "a": (("ַ", ""), ("ַ", "א")), "i": (("ִ", ""), ("ִ", "י")), "u": (("ֻ", ""), ("", "וּ")),
-    "e": (("ֶ", ""), ("ֶ", "ה")), "o": (("", "וֹ"),) * 2,
-    "aː": (("ַ", "א"),) * 2, "iː": (("ִ", "י"),) * 2, "uː": (("", "וּ"),) * 2,
-    "eː": (("ֵ", "י"),) * 2, "oː": (("", "וֹ"),) * 2,
-}
-FINALS = {"מ": "ם", "נ": "ן", "צ": "ץ", "פ": "ף"}
-SHADDA, SHVA = "\u0651", "\u05b0"
-
-
-def _letter(base: str, marks: str) -> str:
-    """Points go on the letter itself, before a geresh (or gershayim), and on the first letter of טס."""
-    return base[0] + marks + base[1:] if len(base) > 1 and base[1] != "\u05bc" else base + marks
-
-
-def word_letters(ipa_word: str, ar_word: str = "") -> list[tuple[str, list[int]]]:
-    """The word letter by letter: each Hebrew letter (with its points) and the positions, in the IPA word,
-    of the phonemes it stands for, so that a score per phoneme can colour the letters. The bracketed
-    silent ל stands for none.
-
-    The Arabic spelling, when given, settles what the IPA cannot: an urban ʔ that is written ق
-    stays ק (as in the hand-written hints), a final a written ة/ه ends in ה, and the ل of the
-    article ال that is swallowed by the next consonant is shown in brackets: אִ(ל)דַّכְּתוֹר."""
-    phs = ipa_word.split()
-    if "ق" in ar_word:
-        phs = ["q" if ph == "ʔ" else ph for ph in phs]
-    final_a = "ה" if ar_word.endswith(("ة", "ه")) else "א"
-    # written ال, said as a vowel + doubled consonant: the ل is silent
-    silent_l = (ar_word.startswith("ال") and len(phs) > 2 and phs[0] in VOWELS
-                and phs[1] == phs[2] and phs[1] != "l")
-    out: list[tuple[str, list[int]]] = []
-    i = 0
-    if len(phs) > 1 and phs[0] == "u":  # the conjunction و before a word: וּ, not an alef
-        out, i = [("וּ", [0])], 1
-    while i < len(phs):
-        ph, start = phs[i], i
-        if ph in VOWELS:  # vowel with no consonant before it (word-initial): carry it on an alef
-            base, shadda = "א", ""
-        else:
-            base, shadda = CONSONANTS.get(ph) or HEARD_ONLY.get(ph, ph), ""
-            i += 1
-            if i < len(phs) and phs[i] == ph:  # geminate
-                shadda = SHADDA
-                i += 1
-        if i < len(phs) and phs[i] in VOWELS:
-            vowel = phs[i]
-            i += 1
-            mark, after = VOWELS[vowel][i == len(phs)]
-            if vowel == "a" and after:
-                after = final_a
-            out.append((_letter(base, mark + shadda) + after, list(range(start, i))))
-            if silent_l and i == 1:
-                out.append(("(ל)", []))
-        elif i < len(phs):
-            out.append((_letter(base, SHVA + shadda), list(range(start, i))))
-        else:
-            out.append((_letter(FINALS.get(base, base), shadda), list(range(start, i))))
-    return out
-
-
-def word_to_hebrew(ipa_word: str, ar_word: str = "") -> str:
-    return "".join(text for text, _ in word_letters(ipa_word, ar_word))
-
-
-def to_hebrew(ipa: str, ar: str = "") -> list[str]:
-    """One Hebrew word per IPA word (words are separated by "|")."""
-    ipa_words, ar_words = ipa.split("|"), ar.split()
-    if len(ar_words) != len(ipa_words):
-        ar_words = [""] * len(ipa_words)
-    return [word_to_hebrew(w, a) for w, a in zip(ipa_words, ar_words)]

app/tts.py

@@ -1,492 +0,0 @@
-"""Model-answer playback through the Sawtak Arabi TTS API (https://sawtakarabi.ai/docs).
-
-The API key stays on the server: the browser asks for a phrase by id and gets a WAV back.
-Only phrases from the phrase bank can be synthesised, and each one is generated once and cached on disk.
-
-Env:  SAWTAK_API_KEY   required; without it /api/tts answers 503 and the page falls back to the device voice
-      SAWTAK_VOICE_ID  optional voice used to read sentences; default is Raef
-      TTS_CACHE_DIR    optional; default ~/.cache/ihki-tts
-      TTS_BUCKET       optional Hugging Face Storage Bucket id (e.g. "user/ihki-storage"); the cache-warm sweep
-                       uploads every cached WAV to it through the Bucket API (needs HF_TOKEN with write access)
-      TTS_BUCKET_PREFIX  folder inside the bucket; default "ihki-tts"
-      TTS_STAGING_DIR  with TTS_BUCKET: a fast local folder new recordings are written to before their upload;
-                       default <tmp>/ihki-tts-staging. A bucket mounted at /data takes ~10 s per written file.
-"""
-from __future__ import annotations
-
-import hashlib
-import itertools
-from collections import deque
-import http.client
-import io
-import json
-import logging
-import os
-import tempfile
-import threading
-import time
-import urllib.error
-import urllib.request
-import wave
-from pathlib import Path
-
-log = logging.getLogger("ihki.tts")
-BASE_URL = "https://api.sawtakarabi.ai/v1"
-MODEL = "arabic-tts-1"
-CACHE_VERSION = "raef-pointed-enhanced-provider-default-v1"
-TIMEOUT = 60  # per socket operation: a response that keeps trickling never hits it, hence the two caps below
-MAX_SECONDS = 90  # one whole generation, download included
-MAX_AUDIO_SECONDS = 60  # the longest phrase is ~240 characters; Sawtak's broken answer is minutes of silence
-# The account allows 60 requests a minute and 5 at once (GET /v1/me). Request starts are spaced to at most 45 a minute
-# for this server, and at most 3 are in flight, so student playback and other clients keep some room. 429s are retried.
-MIN_REQUEST_INTERVAL = 60 / 45
-MAX_CONCURRENT = 3
-# The default Sawtak voice used throughout the application.
-RAEF_VOICE_ID = "273d81b2-991b-5b76-8525-eeacc6a3d759"
-VOICES = {"רַאאִף": RAEF_VOICE_ID}
-# A female voice, only for the lines a dialogue gives her (workbook.LINE_VOICES); never offered on the page.
-LINE_VOICES = {"חנאן": "e41781f5-127c-5eb0-b83c-50bf52a64caf"}
-FADWA_VOICE_ID = "39a7e0e0-087e-52b3-afff-5203e430fc39"   # فدوى: Palestinian, female, conversational
-# The native voices the scores are measured against (reference.py), first one first: only it is generated for
-# the baseline; the others count when their recording is already cached (the cache-warm sweep made them).
-BASELINE_VOICES = {"ראאף": RAEF_VOICE_ID, "פדוא": FADWA_VOICE_ID}
-
-
-def playback_voices() -> dict[str, str]:
-    """The playback voices by name: VOICES, plus the one SAWTAK_VOICE_ID sets, named by SAWTAK_VOICE_NAME (אמיר).
-    Read when called, after main.py has loaded .env. Playback only: the baseline stays BASELINE_VOICES."""
-    out = dict(VOICES)
-    voice = os.environ.get("SAWTAK_VOICE_ID", "").strip()
-    if voice and voice not in out.values():
-        out[os.environ.get("SAWTAK_VOICE_NAME", "").strip() or "אַמִיר"] = voice
-    return out
-
-
-def voice_name(voice_id: str) -> str:
-    """A voice id's display name, without vowel points (ראאף, חנאן); the id itself when it is not one of ours."""
-    names = {v: k for k, v in {**playback_voices(), **LINE_VOICES, **BASELINE_VOICES}.items()}
-    return names.get(voice_id, voice_id).translate({c: None for c in range(0x591, 0x5c8)})
-
-class TTSUnavailable(Exception):
-    """No key configured, or the provider refused / failed. The message is safe to show."""
-
-    def __init__(self, message: str, status: int | None = None, retry_after: float | None = None,
-                 transient: bool = False):
-        super().__init__(message)
-        self.status, self.retry_after = status, retry_after
-        # worth retrying: rate limited, a provider-side 5xx, or the connection dropped mid-request
-        self.transient = transient or status == 429 or (status is not None and status >= 500)
-
-
-class ActivityLog:
-    """What the voice cache is doing, for the monitoring panel: requests in flight and the latest results.
-
-    Holds phrase-bank text only (no user data), kept in memory for the life of the process."""
-
-    def __init__(self, size: int = 80):
-        self._lock = threading.Lock()
-        self._events: deque[dict] = deque(maxlen=size)
-        self._active: dict[int, dict] = {}
-        self._ids = itertools.count(1)
-
-    def begin(self, **info) -> int:
-        with self._lock:
-            n = next(self._ids)
-            self._active[n] = {**info, "id": n, "started": time.time()}
-            return n
-
-    def end(self, n: int, **result) -> None:
-        with self._lock:
-            event = self._active.pop(n, None) or {"started": time.time()}
-            now = time.time()
-            event.update(result, at=now, ms=round((now - event["started"]) * 1000))
-            self._events.appendleft(event)
-
-    def snapshot(self) -> dict:
-        with self._lock:
-            now = time.time()
-            active = [{**a, "elapsed_ms": round((now - a["started"]) * 1000)} for a in self._active.values()]
-            return {"now": now, "active": sorted(active, key=lambda a: a["started"]), "events": list(self._events)}
-
-
-class BucketMirror:
-    """Copies cached WAVs into a Hugging Face Storage Bucket through its API.
-
-    Writing to a mounted /data folder is not enough on its own: files written there have been seen to never reach
-    the bucket. The sweep therefore uploads explicitly, comparing sizes so files already there are not sent again."""
-
-    def __init__(self, bucket_id: str, prefix: str = "ihki-tts", token: str | None = None):
-        self.bucket_id, self.prefix, self.token = bucket_id, prefix.strip("/"), token
-        self.activity: ActivityLog | None = None  # set when attached to a SawtakTTS
-        self._stats_lock = threading.Lock()
-        self._stats: tuple[float, int, int] | None = None
-
-    def remote_path(self, rel: str) -> str:
-        return f"{self.prefix}/{rel}" if self.prefix else rel
-
-    def remote_sizes(self) -> dict[str, int]:
-        """{bucket path: size} of every file under the prefix."""
-        from huggingface_hub import list_bucket_tree
-        out = {}
-        for item in list_bucket_tree(self.bucket_id, prefix=f"{self.prefix}/" if self.prefix else None,
-                                     recursive=True, token=self.token):
-            size = getattr(item, "size", None)
-            if size is not None:
-                out[item.path] = size
-        return out
-
-    def cache_stats(self, max_age: float = 60) -> tuple[int, int] | None:
-        """Cached WAV count/size in the shared bucket; refresh without holding up the monitoring request."""
-        stats = self._stats
-        if (stats is None or time.monotonic() - stats[0] > max_age) and self._stats_lock.acquire(blocking=False):
-            def scan() -> None:
-                try:
-                    sizes = self.remote_sizes()
-                    wavs = [size for path, size in sizes.items() if path.endswith(".wav")]
-                    self._stats = (time.monotonic(), len(wavs), sum(wavs))
-                except Exception as e:
-                    log.warning("could not inspect TTS bucket: %s", e)
-                finally:
-                    self._stats_lock.release()
-            threading.Thread(target=scan, name="ihki-tts-bucket-count", daemon=True).start()
-        return (stats[1], stats[2]) if stats else None
-
-    def upload(self, files: list[tuple[Path | bytes, str]], source: str = "") -> None:
-        """Upload (local path or bytes, bucket path) pairs in one batch."""
-        from huggingface_hub import batch_bucket_files
-        size = sum(len(src) if isinstance(src, bytes) else src.stat().st_size for src, _dest in files)
-        n = self.activity.begin(kind="upload", source=source, files=len(files), bytes=size,
-                                text=files[0][1].rsplit("/", 1)[-1] if len(files) == 1 else "") if self.activity else 0
-        try:
-            batch_bucket_files(self.bucket_id, add=[(str(src) if isinstance(src, Path) else src, dest)
-                                                    for src, dest in files], token=self.token)
-        except Exception as e:
-            if self.activity:
-                self.activity.end(n, status="error", message=str(e)[:200])
-            raise
-        if self.activity:
-            self.activity.end(n, status="ok")
-
-
-class SawtakTTS:
-    def __init__(self, api_key: str, voice_id: str = RAEF_VOICE_ID, cache_dir: Path | None = None):
-        self.api_key, self.voice_id = api_key, voice_id.strip() or RAEF_VOICE_ID
-        self.voice_name = voice_name(self.voice_id)
-        self.cache_dir = cache_dir or Path.home() / ".cache" / "ihki-tts"
-        # Separate locks, so nothing slow holds up a generation: walking a bucket-mounted cache folder for the
-        # panel's file count takes tens of seconds, and it once stalled every sweep worker behind it.
-        self._lock = threading.Lock()  # clearing the cache
-        self._counts = threading.Lock()  # the hit and miss counters
-        self._keys_guard = threading.Lock()  # the per-recording locks
-        self._stats_lock = threading.Lock()  # one disk walk at a time for cache_stats
-        self._disk: tuple[float, int, int] | None = None  # (when, files, bytes) of the last walk
-        self._pace = threading.Lock()  # hands out request start times, MIN_REQUEST_INTERVAL apart
-        self._next_start = 0.0
-        self._in_flight = threading.Semaphore(MAX_CONCURRENT)
-        self._key_locks: dict[str, threading.Lock] = {}  # one generation per recording at a time
-        self._cache_hits = self._cache_misses = 0
-        self.activity = ActivityLog()  # Sawtak requests and bucket uploads, for the monitoring panel
-        self._mirror: BucketMirror | None = None  # set by load_tts when TTS_BUCKET is configured
-        # With a mirror, new recordings are written here (local disk) and uploaded through the Bucket API, instead
-        # of into cache_dir: a bucket mounted there only flushes a few files every ~30 s, so each write crawled.
-        self.staging_dir: Path | None = None
-
-    @property
-    def mirror(self) -> BucketMirror | None:
-        return self._mirror
-
-    @mirror.setter
-    def mirror(self, mirror: BucketMirror | None) -> None:
-        self._mirror = mirror
-        if mirror is not None:
-            mirror.activity = self.activity
-
-    def _request(self, path: str, body: dict | None = None):
-        req = urllib.request.Request(
-            BASE_URL + path,
-            data=json.dumps(body).encode() if body is not None else None,
-            # explicit User-Agent: the provider's CDN answers Python's default one with 403 (error 1010)
-            headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json",
-                     "User-Agent": "ihki/1.0"},
-        )
-        try:
-            return urllib.request.urlopen(req, timeout=TIMEOUT)
-        except urllib.error.HTTPError as e:
-            try:
-                err = json.load(e).get("error", {})
-            except ValueError:
-                err = {}
-            log.warning("sawtak %s -> %s %s (request %s)", path, e.code, err.get("code"), err.get("request_id"))
-            try:
-                retry_after = float(e.headers.get("Retry-After", ""))
-            except (TypeError, ValueError):
-                retry_after = None
-            raise TTSUnavailable(f"tts provider error {e.code}: {err.get('message', 'request failed')}",
-                                 e.code, retry_after) from None
-        except OSError as e:
-            log.warning("sawtak %s unreachable: %s", path, e)
-            raise TTSUnavailable("tts provider unreachable", transient=True) from None
-
-    def _path(self, text: str, voice: str) -> Path:
-        name = hashlib.sha1(f"{CACHE_VERSION}|{MODEL}|{voice}|{text}".encode()).hexdigest() + ".wav"
-        return self.cache_dir / voice / name
-
-    def _legacy_path(self, path: Path) -> Path:
-        """The flat cache layout used before recordings were grouped by voice id."""
-        return self.cache_dir / path.name
-
-    def cache_key(self, text: str, voice: str) -> str:
-        """The recording's path relative to the cache folder ("<voice>/<sha1>.wav"), also its path in the bucket."""
-        return self._path(text, voice).relative_to(self.cache_dir).as_posix()
-
-    def _candidates(self, text: str, voice: str) -> list[Path]:
-        """Where a recording may be: the local staging folder first (fast), then the cache folder, then its
-        legacy flat layout."""
-        path = self._path(text, voice)
-        staged = [self.staging_dir / self.cache_key(text, voice)] if self.staging_dir else []
-        return staged + [path, self._legacy_path(path)]
-
-    def cache_file(self, text: str, voice: str) -> Path | None:
-        """The cached WAV on disk, wherever it is; None when not cached."""
-        return next((c for c in self._candidates(text, voice) if c.is_file()), None)
-
-    def cached_files(self) -> list[tuple[Path, str]]:
-        """Every cached WAV on disk with its path relative to its folder; a staged copy wins over the cache's."""
-        found: dict[str, Path] = {}
-        for root in (self.cache_dir, self.staging_dir):  # staging last, so it overrides
-            if root is not None and root.is_dir():
-                for p in root.rglob("*.wav"):
-                    if p.is_file():
-                        found[p.relative_to(root).as_posix()] = p
-        return [(found[rel], rel) for rel in sorted(found)]
-
-    def store(self, rel: str, data: bytes) -> Path:
-        """Keep a recording from an offline copy at `rel` ("<voice>/<sha1>.wav" or a legacy "<sha1>.wav"): in the
-        staging folder with a mirror (the slow mount is not written), else in the cache folder."""
-        path = (self.staging_dir or self.cache_dir) / rel
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = path.with_suffix(".tmp")
-        tmp.write_bytes(data)
-        tmp.replace(path)
-        return path
-
-    def has(self, rel: str) -> Path | None:
-        """The cached file at `rel`, staged or in the cache folder; None when neither has it."""
-        for root in (self.staging_dir, self.cache_dir):
-            if root is not None and (root / rel).is_file():
-                return root / rel
-        return None
-
-    def cached(self, text: str, voice: str) -> bool:
-        """Has this voice said `text` before? Then wav() answers from disk, without the provider."""
-        return any(c.exists() for c in self._candidates(text, voice))
-
-    def hold(self, seconds: float) -> None:
-        """No new request starts for `seconds` (after a 429, so the other requests in flight back off too)."""
-        with self._pace:
-            self._next_start = max(self._next_start, time.monotonic() + seconds)
-
-    def _key_lock(self, key: str) -> threading.Lock:
-        with self._keys_guard:
-            return self._key_locks.setdefault(key, threading.Lock())
-
-    def _generate(self, text: str, voice: str, source: str = "") -> bytes:
-        """Generate one uncached WAV recording: paced, and at most MAX_CONCURRENT at once."""
-        queued = time.monotonic()
-        with self._pace:
-            start = max(time.monotonic(), self._next_start)
-            self._next_start = start + MIN_REQUEST_INTERVAL
-        if start > time.monotonic():
-            time.sleep(start - time.monotonic())
-        with self._in_flight:
-            n = self.activity.begin(kind="sawtak", source=source, text=text[:80], voice=voice,
-                                    waited_ms=round((time.monotonic() - queued) * 1000))
-            try:
-                data = self._generate_now(text, voice)
-            except TTSUnavailable as e:
-                self.activity.end(n, status=e.status or "error", message=str(e)[:200])
-                raise
-            except Exception as e:
-                self.activity.end(n, status="error", message=f"{type(e).__name__}: {e}"[:200])
-                raise
-            try:
-                with wave.open(io.BytesIO(data)) as w:
-                    audio = round(w.getnframes() / w.getframerate(), 2)
-            except (wave.Error, EOFError):
-                audio = None
-            self.activity.end(n, status=200, bytes=len(data), audio_s=audio)
-            return data
-
-    def _generate_now(self, text: str, voice: str) -> bytes:
-        # Sawtak currently returns 320 seconds of silence whenever `temperature` is present,
-        # including for 0 and 0.1. Omitting it uses the provider's deterministic supported path.
-        with self._request("/audio/speech", {"model": MODEL, "voice": voice, "input": text,
-                                             "response_format": "pcm", "enhance_pronunciation": True,
-                                             }) as res:
-            rate = int(res.headers.get("X-Sample-Rate", 24000))
-            started, parts, size = time.monotonic(), [], 0
-            try:
-                while chunk := res.read(65536):
-                    parts.append(chunk)
-                    size += len(chunk)
-                    if size > rate * 2 * MAX_AUDIO_SECONDS or time.monotonic() - started > MAX_SECONDS:
-                        log.warning("sawtak audio for %r abandoned: %d bytes after %.0fs", text[:40], size,
-                                    time.monotonic() - started)
-                        raise TTSUnavailable("tts provider sent overlong or stalled audio", transient=True)
-            except (http.client.HTTPException, OSError) as e:  # e.g. IncompleteRead: the audio arrived cut off
-                log.warning("sawtak audio download broke: %s: %s", type(e).__name__, e)
-                raise TTSUnavailable("tts audio download broke off", transient=True) from None
-            pcm = b"".join(parts)
-        if len(pcm) < rate // 5:
-            raise TTSUnavailable("tts provider returned no audio")
-        buf = io.BytesIO()
-        with wave.open(buf, "wb") as w:
-            w.setnchannels(1)
-            w.setsampwidth(2)
-            w.setframerate(rate)
-            w.writeframes(pcm[: len(pcm) // 2 * 2])
-        return buf.getvalue()
-
-    def clear_cache(self) -> int:
-        """Delete only generated audio files from this instance's dedicated cache directory."""
-        with self._lock:
-            removed = 0
-            roots = [r for r in (self.cache_dir, self.staging_dir) if r is not None and r.is_dir()]
-            for path in (p for root in roots for p in root.rglob("*")):
-                if path.is_file() and (path.suffix == ".wav" or path.name.endswith(".tmp")):
-                    try:
-                        path.unlink()
-                        removed += 1
-                    except FileNotFoundError:
-                        pass
-                    except OSError as e:
-                        raise TTSUnavailable(f"could not clear voice cache: {e}") from None
-            with self._counts:
-                self._cache_hits = self._cache_misses = 0
-            self._disk = None
-            return removed
-
-    def cache_stats(self, max_age: float = 30, wait: bool = False) -> dict:
-        """Anonymous disk and process-lifetime cache usage for the monitoring panel. Counting the files on a bucket
-        mount takes minutes, so a stale count is refreshed in a background thread and the call returns at once with
-        the previous count (files and bytes are None before the first count ends). `wait`: count now instead."""
-        disk = self._disk
-        if disk is None or time.monotonic() - disk[0] > max_age:
-            if wait:
-                with self._stats_lock:
-                    self._count_files()
-            elif self._stats_lock.acquire(blocking=False):
-                def walk() -> None:
-                    try:
-                        self._count_files()
-                    except TTSUnavailable as e:
-                        log.warning("%s", e)
-                    finally:
-                        self._stats_lock.release()
-                threading.Thread(target=walk, name="ihki-tts-count", daemon=True).start()
-        disk = self._disk
-        with self._counts:
-            hits, misses = self._cache_hits, self._cache_misses
-        requests = hits + misses
-        shared = self.mirror.cache_stats() if self.mirror is not None and hasattr(self.mirror, "cache_stats") else None
-        if self.mirror is not None and hasattr(self.mirror, "cache_stats"):
-            files, size = shared if shared is not None else (None, None)
-        else:
-            files, size = (disk[1], disk[2]) if disk else (None, None)
-        return {"files": files, "bytes": size, "hits": hits,
-                "misses": misses, "hit_rate": round(hits / requests, 4) if requests else None}
-
-    def _count_files(self) -> None:
-        """Walk the cache folder; the caller holds _stats_lock."""
-        files = size = 0
-        try:
-            for path, _rel in self.cached_files():
-                files += 1
-                size += path.stat().st_size
-        except OSError as e:
-            raise TTSUnavailable(f"could not inspect voice cache: {e}") from None
-        self._disk = (time.monotonic(), files, size)
-
-    def _wav(self, text: str, voice: str, upload: bool = False, source: str = "") -> tuple[bytes, str]:
-        """Generate or read `text` for an already validated voice id. `upload`: send a new recording to the bucket
-        in the background (playback); the cache-warm sweep uploads its own in batches. Different recordings can be
-        generated at the same time (see _generate); the same one waits for the first request and then reads it."""
-        with self._key_lock(self.cache_key(text, voice)):
-            found = self.cache_file(text, voice) if self.staging_dir else None
-            if found is not None:  # with a mirror the cache folder may be a slow mount: no migration there
-                if source == "playback": self._count(hit=True)
-                return found.read_bytes(), voice
-            path = self._path(text, voice)
-            legacy = self._legacy_path(path)
-            if self.staging_dir is None and not path.exists() and legacy.exists():
-                try:
-                    path.parent.mkdir(parents=True, exist_ok=True)
-                    legacy.replace(path)
-                except OSError as e:
-                    log.warning("tts cache migration failed: %s: %s", type(e).__name__, e)
-                    path = legacy
-            if path.exists():
-                if source == "playback": self._count(hit=True)
-                return path.read_bytes(), voice
-            if source == "playback": self._count(hit=False)
-            # The caller supplies the phrase's Palestinian vowel marks. Sawtak preserves existing
-            # marks; enhancement fills remaining pronunciation cues using the selected voice's dialect.
-            data = self._generate(text, voice, source)
-            if self.staging_dir is not None:
-                path = self.staging_dir / self.cache_key(text, voice)
-            try:
-                path.parent.mkdir(parents=True, exist_ok=True)
-                tmp = path.with_suffix(".tmp")
-                tmp.write_bytes(data)
-                tmp.replace(path)
-            except OSError as e:  # read-only or full cache dir: the audio is still good, it just isn't kept
-                log.warning("tts cache write failed: %s: %s", type(e).__name__, e)
-            if upload and self.mirror is not None:
-                self._upload_soon(data, self.cache_key(text, voice))
-            return data, voice
-
-    def _count(self, hit: bool) -> None:
-        with self._counts:
-            if hit:
-                self._cache_hits += 1
-            else:
-                self._cache_misses += 1
-
-    def _upload_soon(self, data: bytes, rel: str) -> None:
-        """One playback recording to the bucket, off the request: the student does not wait for it."""
-        mirror = self.mirror
-
-        def go() -> None:
-            try:
-                mirror.upload([(data, mirror.remote_path(rel))], source="playback")
-            except Exception as e:  # the next cache-warm sweep uploads what is still missing
-                log.warning("tts bucket upload of %s failed: %s", rel, e)
-        threading.Thread(target=go, name="ihki-tts-upload", daemon=True).start()
-
-    def wav(self, text: str, voice: str = "") -> tuple[bytes, str]:
-        """(WAV, voice id) in the configured voice, or a dialogue line's own voice."""
-        voice = voice if voice in LINE_VOICES.values() else self.voice_id
-        return self._wav(text, voice, upload=True, source="playback")
-
-    def wav_for_voice(self, text: str, voice: str, source: str = "sweep", upload: bool = False) -> tuple[bytes, str]:
-        """(WAV, voice id) for a teacher-selected, validated Sawtak voice. Unlike wav(), any voice id is kept.
-        `upload`: a new recording also goes to the bucket in the background."""
-        return self._wav(text, voice, upload=upload, source=source)
-
-
-def load_tts(key: str | None = None) -> SawtakTTS | None:
-    """`key`: the one the panel set (see keystore.py); None reads the environment's."""
-    key = (os.environ.get("SAWTAK_API_KEY", "") if key is None else key).strip()
-    if not key:
-        log.info("SAWTAK_API_KEY not set: playback uses the device voice")
-        return None
-    cache = os.environ.get("TTS_CACHE_DIR", "").strip()
-    voice = os.environ.get("SAWTAK_VOICE_ID", RAEF_VOICE_ID).strip() or RAEF_VOICE_ID
-    tts = SawtakTTS(key, voice, Path(cache) if cache else None)
-    bucket = os.environ.get("TTS_BUCKET", "").strip()
-    if bucket:
-        tts.mirror = BucketMirror(bucket, os.environ.get("TTS_BUCKET_PREFIX", "ihki-tts"),
-                                  os.environ.get("HF_TOKEN", "").strip() or None)
-        staging = os.environ.get("TTS_STAGING_DIR", "").strip()
-        tts.staging_dir = Path(staging) if staging else Path(tempfile.gettempdir()) / "ihki-tts-staging"
-    return tts

app/tutor.py

@@ -1,534 +0,0 @@
-"""יאללה נדבר: short spoken conversations with an AI tutor, on scenario cards, one for each lesson of the course.
-
-The tutor writes; the student talks. The page turns the student's speech into text (the browser's own recognition)
-and sends the text; the tutor's answer comes back as text too, so the student sees what the tutor understood.
-The students do not read Arabic script, so what the page shows is Arabic in Hebrew letters as the course writes it:
-the tutor's message, and the student's own sentence as the tutor read it. The Arabic script is kept for the teacher.
-
-Each scenario belongs to a lesson (SCENARIOS) and plays out that lesson's theme: its story, its words and its grammar.
-The tutor speaks with the words of that lesson and of the lessons before it (`vocabulary`); the page shows each word
-of the tutor's message with its Hebrew translation, and marks a word the student has not learnt yet (`is_known`).
-A sentence of the student's that is wrong in grammar or wording gets a correction, explained in Hebrew.
-A conversation lasts MAX_TURNS sentences of the student's and ends with a short summary in Hebrew.
-
-The model is Claude Haiku (DEFAULT_MODEL, or TUTOR_MODEL), called with the server's key; the browser never sees it. A conversation lives in
-this process's memory while it runs (a restart ends it) and is kept, turn by turn, in the Supabase table
-`tutor_chats` (CREATE_TUTOR_CHATS), so the teacher can read what was said and how the tutor answered.
-
-Env:  ANTHROPIC_API_KEY (or CLAUDE_API_KEY)  required; without it the game is not offered
-      Access is granted per account in the management panel; an open service remains open.
-      TUTOR_MODEL  optional: the Claude model the tutor runs on (default DEFAULT_MODEL), e.g. claude-sonnet-5-5
-                   (request_options() fits the request to it: Haiku 5.5/4.5, Sonnet 5.5, Opus 5.5 and Fable 5.1 all run)
-"""
-from __future__ import annotations
-
-import functools
-import json
-import logging
-import os
-import re
-import threading
-import time
-import uuid
-from dataclasses import dataclass, field
-
-from .phrases import CATEGORIES, LESSONS, PHRASES
-from .workbook import LEX
-
-log = logging.getLogger("ihki.tutor")
-DEFAULT_MODEL = "claude-haiku-5-5"
-NO_FIX = re.compile(r"אין (?:כאן )?(?:צורך|תיקון|טעות)|(?:המשפט|הדוגמה|התשובה) (?:שלך |שלכם )?נכונ")   # a correction whose note says there is none
-MAX_TURNS = 10   # the student's sentences in one conversation
-DAILY_LIMIT = 5   # conversations per signed-in account per day; developers are exempt in main.py
-MAX_TEXT = 300   # characters of one sentence of the student's
-TTL = 2 * 3600   # seconds a conversation nobody continues is kept in memory
-MAX_LIVE = 2000   # conversations in memory at once
-CREATE_TUTOR_CHATS = ("create table public.tutor_chats (id uuid primary key, user_id uuid, email text not null default '', "
-                      "scenario text not null, gender text not null default '', messages jsonb not null default '[]'::jsonb, "
-                      "turns int not null default 0, finished boolean not null default false, model text not null default '', "
-                      "input_tokens int not null default 0, output_tokens int not null default 0, "
-                      "created_at timestamptz not null default now(), updated_at timestamptz not null default now()); "
-                      "alter table public.tutor_chats enable row level security;")
-
-# A scenario for each lesson the path shows: who the tutor plays (`who`, `ar`: the name on the chat's avatar, `she`:
-# the character is a woman), the card (`title`, `desc`), and for the model the conversation's aim (`goal`) and the
-# lesson's grammar to bring in (`focus`). `story`: the lesson's story or dialogue, the model's example of its words.
-SCENARIOS = [
-    {"id": "l1", "lesson": "1", "who": "ראמי", "ar": "رامي", "she": False, "story": "l1-say",
-     "title": "מי, איפה ולמה?", "desc": "ראמי שואל אתכם מה עשיתם אתמול: מי, איפה, מתי ולמה",
-     "goal": "a friend asks the student simple questions about yesterday: who sat in the car, what they ate, who "
-             "opened the door, where their friend lives, and asks why and when",
-     "focus": "the question words مين، وين، ليش، ايمتى and the past tense of سأل، فتح، اكل، قعد"},
-    {"id": "l2", "lesson": "2", "who": "ח'ליל", "ar": "خليل", "she": False, "story": "l2-talk",
-     "title": "היכרות", "desc": "ח'ליל פוגש אתכם בפעם הראשונה: שם, גיל, מאיפה אתם, משפחה ועבודה",
-     "goal": "Khalil, from Tur'an in the north, now living in Jerusalem, meets the student for the first time and "
-             "gets to know them: their name, how they are, their age, where they are from and live, whether they are "
-             "married and have children, and their work",
-     "focus": "greetings and the possessive endings (اسمي، اسمك، بيتي)"},
-    {"id": "l3", "lesson": "3", "who": "רובה", "ar": "روبا", "she": True, "story": "l3-story",
-     "title": "השכנה רובה", "desc": "רובה עברה לשכונה שלכם: מספר הבית, הטלפון, הגיל והמשפחה",
-     "goal": "Ruba, eighteen, has just moved to the student's neighbourhood. She asks for their house number and "
-             "phone number, their age, and how many brothers and sisters they have, and tells about her own family",
-     "focus": "numbers (house numbers, phone numbers, ages) and the past tense"},
-    {"id": "l4", "lesson": "4", "who": "סמיר", "ar": "سمير", "she": False, "story": "l4-story",
-     "title": "השכן החדש", "desc": "באתם עם עוגה לשכן החדש סמיר. הוא מציע קפה או תה",
-     "goal": "the student visits Samir Atallah, the new neighbour, bringing him a cake. Samir welcomes them, offers "
-             "coffee or tea (with sugar or without), asks whether they are tired or hungry, and they talk about "
-             "their families",
-     "focus": "بدّي (I want), بلا، كل، and the past tense"},
-    {"id": "l5", "lesson": "5", "who": "אבו מחמד", "ar": "ابو محمد", "she": False, "story": "l5-story",
-     "title": "בשוק", "desc": "קונים ירקות ופירות אצל אבו מחמד: מחיר, קילו וחצי",
-     "goal": "Abu Mohammad sells vegetables and fruit in the market. The student buys: he asks what they want, "
-             "tells prices in shekels per kilo, and they bargain a little",
-     "focus": "prices and quantities (كيلو، نصّ، شيكل) and the negation ما"},
-    {"id": "l6", "lesson": "6", "who": "קפטן איוב", "ar": "ايّوب", "she": False, "story": "l6-story",
-     "title": "במונית של קפטן איוב", "desc": "נוסעים במונית של קפטן איוב, והוא שואל מה תעשו מחר",
-     "goal": "Captain Ayyub, a talkative taxi driver, drives the student. He asks where they are going, what they "
-             "will do tomorrow, whether they are going to a party, and talks about himself",
-     "focus": "the future tense (بروح، باكل) next to the past"},
-    {"id": "l7", "lesson": "7", "who": "הדודה אם סמיר", "ar": "امّ سمير", "she": True, "story": "l7-say",
-     "title": "ביקור אצל הדודה", "desc": "הדודה אם סמיר מארחת אתכם ושואלת על הילדים, האחים והמכוניות",
-     "goal": "the student visits their aunt Umm Samir. She serves maqluba and asks how many children, brothers, "
-             "sisters and cars they have, and how old everyone is",
-     "focus": "masculine and feminine, the dual (ولدين، بنتين) and numbers with nouns"},
-    {"id": "l8", "lesson": "8", "who": "סוהא", "ar": "سهى", "she": True, "story": "l8-story",
-     "title": "בחנות הבגדים", "desc": "סוהא המוכרת עוזרת לכם לבחור מכנסיים ושמלה: איזה צבע וכמה זה עולה",
-     "goal": "Suha works in a clothes shop. She asks what the student is looking for, which colour they like, "
-             "and tells how much each item costs; they ask how many there are",
-     "focus": "colours, قدّيش (how much) and كم (how many)"},
-    {"id": "l9", "lesson": "9", "who": "אבו נדאל", "ar": "ابو نضال", "she": False, "story": "l9-story",
-     "title": "קפה אצל אבו נדאל", "desc": "אבו נדאל הבדואי מארח אתכם לקפה ושואל מה תרצו לעשות בשבוע הבא",
-     "goal": "Abu Nidal, a Bedouin near Arad, welcomes the student, serves coffee (bitter, without sugar or milk), "
-             "asks about their family and work, and what they want to do next week",
-     "focus": "the future with بدّ (بدّي، بدّك) and hospitality phrases"},
-    {"id": "l10", "lesson": "10", "who": "הדוד סעיד", "ar": "سعيد", "she": False, "story": "l10-story",
-     "title": "הדוד סעיד בא לבקר", "desc": "הדוד סעיד הגיע לבקר. משווים: מה יותר גדול, יותר יפה, הכי טוב",
-     "goal": "uncle Said has come to visit. He asks the student about their life, football, the beach and the "
-             "train, and they compare things: which is bigger, nicer, the best",
-     "focus": "the comparative and superlative (أكبر، أحلى، أحسن) and هاد، هاي، هدول"},
-    {"id": "l2.1", "lesson": "2.1", "who": "אבו חסן", "ar": "ابو حسن", "she": False, "story": "l2.1-story",
-     "title": "במכולת של אבו חסן", "desc": "אורחים באים היום: קונים במכולת של אבו חסן לפי הרשימה",
-     "goal": "Abu Hassan runs the village grocery. Guests are coming to the student today; they buy what is on "
-             "their list. He asks what they need, who is coming and what they will cook",
-     "focus": "the future with رح and must with لازم"},
-    {"id": "l2.2", "lesson": "2.2", "who": "עלי", "ar": "علي", "she": False, "story": "l2.2-story",
-     "title": "בדוכן הפלאפל", "desc": "מזמינים מנת פלאפל אצל עלי, ומספרים מה אתם עושים בדרך כלל",
-     "goal": "Ali owns a falafel restaurant. He takes the student's order (which salads and sauces in the pita) and "
-             "chats about what they usually do on each day of the week",
-     "focus": "the present tense with بـ (باكل، بتروح) and the days of the week"},
-    {"id": "l2.3", "lesson": "2.3", "who": "אבו ג'מיל", "ar": "ابو جميل", "she": False, "story": "l2.3-talk",
-     "title": "סליחה, מה השעה?", "desc": "אבו ג'מיל ברחוב שואל מה השעה, ומספר על יום ההולדת של הערב",
-     "goal": "Abu Jamil stops the student in the street to ask the time, because his phone is broken. They talk "
-             "about the time of tonight's birthday party and how to get there",
-     "focus": "telling the time (ربع، ثلث، نصّ) and form II verbs (فعّل)"},
-    {"id": "l2.4", "lesson": "2.4", "who": "שאדי", "ar": "شادي", "she": False, "story": "l2.4-talk2",
-     "title": "שיחת טלפון", "desc": "שאדי מתקשר: קובעים להיפגש מחר, באיזו שעה ואיפה",
-     "goal": "Shadi phones the student. He asks how they are and arranges to meet tomorrow: at what time, where, "
-             "and asks for a phone number",
-     "focus": "phone phrases (ألو، مين معي) and the relative words اللي، انّو"},
-    {"id": "l2.5", "lesson": "2.5", "who": "אבו ויסאם", "ar": "ابو وسام", "she": False, "story": "l2.5-story",
-     "title": "במוסך", "desc": "האוטו עושה רעש: אבו ויסאם במוסך שואל מה קרה",
-     "goal": "Abu Wisam owns a garage. The student's car is making a noise and the engine light is red. He asks "
-             "what happened and when, checks the oil, and tells them how long it will take",
-     "focus": "صار (happened, became) and verbs like جاب (brought)"},
-    {"id": "l2.6", "lesson": "2.6", "who": "פואד", "ar": "فؤاد", "she": False, "story": "l2.6-story",
-     "title": "הכד העתיק", "desc": "מצאתם כד עתיק. מר פואד רוצה לקנות אותו: יקר או זול?",
-     "goal": "the student found an old jar and brings it to Mr Fuad Arafat, who buys antiques. He asks where they "
-             "found it, and they bargain over the price in dinars: expensive or cheap",
-     "focus": "form III verbs (ساعد، لاقى) and the object suffix after a vowel"},
-    {"id": "l2.7", "lesson": "2.7", "who": "יוסף", "ar": "يوسف", "she": False, "story": "l2.7-story",
-     "title": "בתחנת האוטובוס", "desc": "התחנה מלאה. יוסף מחכה לקו לטבריה ונותן לכם עצות",
-     "goal": "Yusuf is waiting at a crowded bus stop at the Furaydis junction. He talks with the student about "
-             "which line goes to Tiberias and when it comes, and tells them what to do",
-     "focus": "the imperative (استنّى، تعال، قول) next to the past, present and future"},
-    {"id": "l2.8", "lesson": "2.8", "who": "ד\"ר לילא", "ar": "ليلى", "she": True, "story": "l2.8-story",
-     "title": "אצל הרופאה", "desc": "הרופאה לילא שואלת מה כואב ומה אתם עושים עכשיו",
-     "goal": "Dr Layla, a doctor, asks the student what hurts, since when, and what they are doing for it right now, "
-             "and gives advice (rest, aspirin, health)",
-     "focus": "عم for an action happening now and doubled verbs (حبّ، ضلّ)"},
-    {"id": "l2.9", "lesson": "2.9", "who": "המוכתר", "ar": "المختار", "she": False, "story": "l2.9-story",
-     "title": "המוכתר של הכפר", "desc": "המוכתר פוגש אתכם בכפר: לאן הולכים, מאיפה באים ומה אתם חושבים",
-     "goal": "the village mukhtar meets the student on the road and asks where they are going and coming from, "
-             "whether they live here, and tells the story of the father, the son and the donkey",
-     "focus": "the active participle (رايح، جاي، ساكن، عارف)"},
-]
-BY_ID = {s["id"]: s for s in SCENARIOS}
-READY = [l["id"] for l in LESSONS if not l.get("soon")]
-LESSON_OF = {c["id"]: c["lesson"] for c in CATEGORIES}
-LEARN = {c["id"] for c in CATEGORIES if c.get("learn")}
-TASHKEEL = re.compile(r"[ً-ْٰـ]")
-PUNCT = "،؟!.,:;\"'()«»…-"
-ARABIC = re.compile(r"[ء-ي]")
-PREFIXES = ("وال", "بال", "فال", "لل", "ال", "و", "ب", "ف", "ل", "ع", "م")
-SUFFIXES = ("كم", "هم", "ها", "نا", "ني", "تي", "ين", "ات", "ي", "ك", "ه", "و", "ت", "ة")
-
-
-def norm(word: str) -> str:
-    """An Arabic word as it is compared: no tag, vowel signs or punctuation; one alef; ى as ي and ة as ه."""
-    w = TASHKEEL.sub("", word.split("#")[0]).strip(PUNCT)
-    return w.translate(str.maketrans("أإآٱى", "ااااي")).replace("ة", "ه")
-
-
-TR_OF = {norm(k): v[0] for k, v in LEX.items()}   # a word's reading in Hebrew letters, as the course writes it
-
-
-@functools.lru_cache(maxsize=None)
-def vocabulary(lesson: str) -> tuple[list[tuple[str, str, str]], frozenset[str]]:
-    """What a student knows by the end of this lesson: the new words of it and of the lessons before it, as
-    (Arabic, Hebrew letters, Hebrew), and every word form their sentences used (normalised, see `norm`)."""
-    upto = set(READY[:READY.index(lesson) + 1])
-    learnt, forms = [], set()
-    for p in PHRASES:
-        if LESSON_OF.get(p["cat"]) not in upto:
-            continue
-        if p["cat"] in LEARN:
-            learnt.append((p["variants"][0][0], p["tr"], p["he"]))
-        for ar, _ in p["variants"]:
-            forms.update(n for n in map(norm, ar.split()) if n)
-    return learnt, frozenset(forms)
-
-
-def is_known(word: str, forms: frozenset[str]) -> bool:
-    """Whether the student has met this word: as it is, or without a prefix (و، ال، بـ...) or an ending (ي، ك، ها...)
-    that they learnt as such. Lenient on purpose: a word marked new must be one the lessons never had."""
-    w = norm(word)
-    if not w or w.isdigit() or not re.search(r"[ء-ي]", w):
-        return True
-    stems = {w} | {w[len(p):] for p in PREFIXES if w.startswith(p) and len(w) - len(p) >= 2}
-    stems |= {s[:-len(x)] for s in list(stems) for x in SUFFIXES if s.endswith(x) and len(s) - len(x) >= 2}
-    return any(s in forms or s + "ه" in forms for s in stems)
-
-
-def _lines(cat: str) -> list[str]:
-    """A topic of the course, line by line (Arabic | Hebrew letters | Hebrew): the model's example of the lesson."""
-    return [f"{p['variants'][0][0]} | {p['tr']} | {p['he']}" for p in PHRASES if p["cat"] == cat]
-
-
-# The tutor's every answer, as JSON (structured output). heard_tr: the student's sentence as the tutor read it, in
-# Hebrew letters; words: the tutor's message word by word; fix_*: the student's last sentence said right, empty when
-# it was right; summary: only in the last answer.
-WORD_SCHEMA = {
-    "type": "object",
-    "properties": {"ar": {"type": "string"}, "tr": {"type": "string"}, "he": {"type": "string"},
-                   "name": {"type": "boolean"}},
-    "required": ["ar", "tr", "he", "name"],
-    "additionalProperties": False,
-}
-REPLY_SCHEMA = {
-    "type": "object",
-    "properties": {
-        "heard_tr": {"type": "string"},
-        "words": {"type": "array", "items": WORD_SCHEMA},
-        "he": {"type": "string"},
-        "fix_ar": {"type": "string"}, "fix_tr": {"type": "string"}, "fix_note": {"type": "string"},
-        "summary": {"type": "string"},
-    },
-    "required": ["heard_tr", "words", "he", "fix_ar", "fix_tr", "fix_note", "summary"],
-    "additionalProperties": False,
-}
-OPEN = "(The student has opened the chat. Start the conversation: greet them and begin the scenario.)"
-
-
-def system_prompt(sc: dict, gender: str) -> str:
-    """The tutor's instructions: the character, the scenario, the words it may use, the answer's fields."""
-    student = "a woman: speak to her in the feminine (حالِك، اسمِك، انتِ، بتشتغلي)" if gender == "f" else \
-        "a man: speak to him in the masculine (حالَك، اسمَك، انتَ، بتشتغل)"
-    who = f"{sc['ar']}, a Palestinian {'woman' if sc['she'] else 'man'} (speak of yourself in the " \
-          f"{'feminine' if sc['she'] else 'masculine'})"
-    learnt, forms = vocabulary(sc["lesson"])
-    words = "\n".join(f"{a} | {t} | {h}" for a, t, h in learnt)
-    lesson = next(l["name"] for l in LESSONS if l["id"] == sc["lesson"])
-    return f"""You play {who} in a short conversation with a Hebrew-speaking beginner who is learning spoken Palestinian
-Arabic. The student is {student}.
-
-The scenario: {sc["goal"]}. Ask one thing at a time, answer the student's questions in your character, and keep
-the conversation going. Read each message to its end before you answer: never ask for something the student has
-already told you. If the student goes off the topic, answer in one short sentence and bring the talk back.
-
-The student has studied up to {lesson} of the course. This lesson's grammar, to bring in naturally: {sc["focus"]}.
-Speak ONLY with the words the student knows: the word list and the word forms below (with their usual prefixes and
-endings: و، ال، بـ، the possessive and verb endings). Prefer the words of this lesson's story. Use a word outside the
-lists only when there is no natural way to say it with known words, and then keep it simple.
-
-The student cannot read Arabic script: they read Arabic only in Hebrew letters. They mostly speak, and the browser's
-speech recognition writes down what it heard in Arabic script, so a message may be misspelled, missing words or partly
-wrong; a student who types writes the Arabic in Hebrew letters. Answer what you understood. If you understood nothing,
-say so kindly and ask again in simpler words. Never use Modern Standard Arabic: speak the spoken Palestinian dialect
-of the course (شو، وين، كيف، قدّيش، بدّي، كتير، هلّق). Keep each message to one or two short sentences.
-
-Arabic in Hebrew letters ("Hebrew letters" below) is written exactly as the course writes it, as in the lesson lines
-below: pointed Hebrew; ח' for خ, ע' for غ, ג' for ج, ד' for ض, ט' for ظ, ת' for ث; ح is ח, ع is ע, ص is צ, ط is ט,
-ق is ק; the shadda ّ after a doubled letter; a hyphen before a pronoun suffix (אִסְמַ-כּ, חַאלֵ-כּ, עִנְד-י).
-
-Every answer has these fields:
-- heard_tr: the student's last message exactly as you understood it, in Hebrew letters. Write what they said, mistakes
-  and all: do not correct it here (corrections go in fix_*). Empty when there is no student message yet.
-- words: your message, word by word in order. For each word: ar (the word in Arabic script, as the course writes it,
-  no vowel signs except shadda ّ), tr (the word in Hebrew letters, with the punctuation that follows it, e.g. "חַאלַ-כּ?"),
-  he (its meaning here in Hebrew, one to three words), name (true only for a person's or a place's name).
-- he: a natural Hebrew translation of your whole message.
-- fix_ar, fix_tr, fix_note: only for a clear mistake in the student's last sentence: a wrong verb form, gender or
-  person, a wrong word, or Modern Standard Arabic or Hebrew where the dialect has its own word (ثلاثون for تلاتين).
-  Then give the sentence as they should have said it (in Arabic script and in Hebrew letters), and in fix_note one
-  short, simple line in Hebrew naming exactly what changed (e.g. "בניב אומרים תַלַאתִין ולא ת'לַאת'וּן"). Most
-  sentences of a student are fine: then leave all three empty. Leave them empty too when you are not sure, when the
-  difference is only spelling or vowels (that came from the speech recognition, not from the student), or when the
-  sentence is a correct way to say it even if you would say it differently. Never correct a correct sentence.
-- summary: empty, except in your very last message (you will be told when it is). Then write in Hebrew, addressed to
-  the student, two or three sentences on what went well and the two or three things most worth practising.
-fix_note and summary are in Hebrew, and any Arabic word in them is written in Hebrew letters, never in Arabic script.
-
-Lines of this lesson (Arabic | Hebrew letters | Hebrew):
-{chr(10).join(_lines(sc["story"]))}
-
-The words the student has learnt (Arabic | Hebrew letters | Hebrew):
-{words}
-
-Every word form the lessons so far have used:
-{" ".join(sorted(forms))}
-
-YOUR ROLE NOW: you are {sc["ar"]}. {sc["goal"]}. From your very first message, be this character in this situation
-and lead the conversation toward it; every answer of yours moves the scenario on. Speak to the student as
-{student.split(":")[0]}."""
-
-
-class TutorUnavailable(Exception):
-    """No key, or the model failed. The message is safe to show the student (Hebrew)."""
-
-
-class TutorLimit(Exception):
-    """The student has started their conversations for today."""
-
-
-@dataclass
-class Chat:
-    id: str
-    scenario: str
-    gender: str
-    user_id: str | None
-    email: str
-    system: str
-    messages: list[dict] = field(default_factory=list)   # as the model reads them: user text, assistant JSON
-    log: list[dict] = field(default_factory=list)   # as the page and the teacher read them
-    turns: int = 0
-    done: bool = False
-    seen: float = field(default_factory=time.monotonic)
-    input_tokens: int = 0
-    output_tokens: int = 0
-    model: str = DEFAULT_MODEL
-
-    def row(self) -> dict:
-        """The conversation as the table `tutor_chats` keeps it."""
-        return {"id": self.id, "user_id": self.user_id, "email": self.email, "scenario": self.scenario,
-                "gender": self.gender, "messages": self.log, "turns": self.turns, "finished": self.done,
-                "model": self.model, "input_tokens": self.input_tokens, "output_tokens": self.output_tokens,
-                "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
-
-
-# models that take a `role: "system"` message in the middle of `messages` (the others answer 400)
-SYSTEM_MESSAGES = ("claude-opus-5", "claude-opus-4-8", "claude-fable-5", "claude-mythos-5", "claude-sonnet-5-5", "claude-haiku-5-5")
-
-
-def thinking_for(model: str) -> dict | None:
-    """As little thinking as each model allows for a chat answer. Sonnet 5.5 refuses "disabled" and turns thinking off
-    with "between_tools"; Opus 5.5 and Fable 5.x cannot turn it off at all (None: the parameter is left out, so it is
-    adaptive, and effort "low" keeps it short); the others take "disabled". Only the answer's text goes back into the
-    history, never a thinking block, so the history stays append-only and nothing is checked against it."""
-    if model.startswith("claude-sonnet-5-5"):
-        return {"type": "between_tools"}
-    if model.startswith(("claude-opus-5-5", "claude-fable-5", "claude-mythos-5")):
-        return None
-    return {"type": "disabled"}
-
-
-def request_options(model: str) -> dict:
-    """The arguments of a chat answer that differ by model: thinking (see thinking_for), effort (Haiku 4.5 has none),
-    and room for a thinking model to think before it answers."""
-    thinking = thinking_for(model)
-    config = {"format": {"type": "json_schema", "schema": REPLY_SCHEMA}}
-    if not model.startswith("claude-haiku-4-5"):
-        config["effort"] = "low"
-    return {"max_tokens": 4000 if thinking else 8000, "output_config": config, **({"thinking": thinking} if thinking else {})}
-
-
-def last_turn(model: str, messages: list[dict], note: str) -> list[dict]:
-    """Tells the model this is the last sentence: as a system message where the model takes one, else after the
-    student's sentence in the same user turn."""
-    if model.startswith(SYSTEM_MESSAGES):
-        return messages + [{"role": "system", "content": note}]
-    *before, student = messages
-    return before + [{"role": "user", "content": [{"type": "text", "text": student["content"]},
-                                                  {"type": "text", "text": f"(Instruction: {note})"}]}]
-
-
-class Tutor:
-    def __init__(self, client, model: str = DEFAULT_MODEL):
-        self.client = client   # an anthropic.Anthropic
-        self.model = model
-        self._chats: dict[str, Chat] = {}
-        self._started: dict[tuple[str, str], int] = {}   # (student, day): conversations started
-        self._lock = threading.Lock()
-
-    def started(self, student: str, day: str, seed=None) -> int:
-        """How many conversations the student started on this day. `seed` reads the number kept in Supabase the first
-        time it is asked (a restart forgets the count in memory)."""
-        key = (student, day)
-        with self._lock:
-            if key in self._started:
-                return self._started[key]
-        n = seed() if seed else 0
-        with self._lock:
-            return self._started.setdefault(key, n)
-
-    def start(self, scenario: str, gender: str, user_id: str | None, email: str, student: str, day: str,
-              limit: int | None, seed=None) -> tuple[Chat, dict]:
-        """A new conversation and the tutor's opening message (see `message`). Raises TutorLimit past the day's
-        `limit` (None: none), and TutorUnavailable when the model fails (the conversation is then not counted)."""
-        sc = BY_ID[scenario]
-        if limit is not None and self.started(student, day, seed) >= limit:
-            raise TutorLimit()
-        chat = Chat(id=str(uuid.uuid4()), scenario=scenario, gender=gender, user_id=user_id, email=email,
-                    system=system_prompt(sc, gender), model=self.model)
-        messages = [{"role": "user", "content": OPEN}]
-        data = self._answer(chat, messages)
-        opening = self.message(data, sc)
-        chat.log.append({"from": "tutor", **opening})
-        with self._lock:
-            self._started[(student, day)] = self._started.get((student, day), 0) + 1
-            self._sweep()
-            self._chats[chat.id] = chat
-        return chat, opening
-
-    def get(self, chat_id: str, user_id: str | None) -> Chat | None:
-        with self._lock:
-            chat = self._chats.get(chat_id)
-        return chat if chat and chat.user_id == user_id else None
-
-    @staticmethod
-    def message(data: dict, sc: dict) -> dict:
-        """The tutor's message as the page shows it: {"ar", "tr", "he", "words": [{tr, he, new}]}. A word is new when
-        the lessons up to the scenario's never had it (a name never is)."""
-        _, forms = vocabulary(sc["lesson"])
-        words: list[dict] = []
-        for w in data["words"]:
-            tr, ar = w["tr"].strip(), w["ar"].strip()
-            if not tr:
-                continue
-            if not re.search(r"[א-ת]", tr):   # punctuation the model gave as a word of its own
-                if words:
-                    words[-1]["tr"] += tr.strip()
-                    words[-1]["ar"] += ar.strip()
-                continue
-            if ARABIC.search(tr):   # Arabic letters in the Hebrew ones: the course's own reading of the word, if it has it
-                tr = TR_OF.get(norm(ar), re.sub(r"[؀-ۿ]+", "", tr).strip() or "…") + tr[len(tr.rstrip(PUNCT + "?")):]
-            words.append({"ar": ar, "tr": tr, "he": w["he"].strip(), "new": not w["name"] and not is_known(ar, forms)})
-        return {"ar": " ".join(w["ar"] for w in words), "tr": " ".join(w["tr"] for w in words),
-                "he": data["he"].strip(), "words": [{k: w[k] for k in ("tr", "he", "new")} for w in words]}
-
-    def turn(self, chat: Chat, text: str) -> dict:
-        """The student's sentence, and the tutor's answer to it: {"heard": the sentence as the tutor read it, in Hebrew
-        letters, "reply": the tutor's message (see `message`), "fix": {ar, tr, note} or None, "summary": text or None,
-        "turn", "turns", "done"}. Raises TutorUnavailable when the model fails; the student's sentence is then not
-        counted, and can be said again."""
-        if chat.done:
-            raise ValueError("the conversation has ended")
-        last = chat.turns + 1 >= MAX_TURNS
-        messages = chat.messages + [{"role": "user", "content": text}]
-        if last:
-            messages = last_turn(self.model, messages, "This is the student's last sentence. Answer it and say "
-                                 "goodbye warmly, and write the summary.")
-        data = self._answer(chat, messages)
-        chat.turns += 1
-        chat.done = last
-        fix = {"ar": data["fix_ar"].strip(), "tr": data["fix_tr"].strip(), "note": data["fix_note"].strip()}
-        if not fix["ar"] or not fix["note"] or NO_FIX.search(fix["note"]) or \
-                [norm(w) for w in fix["ar"].split()] == [norm(w) for w in text.split()]:
-            fix = None   # no correction, or one that changes nothing: the model is not to correct a correct sentence
-        reply = self.message(data, BY_ID[chat.scenario])
-        summary = data["summary"].strip() if last else ""
-        heard = data["heard_tr"].strip() or text
-        chat.log.append({"from": "student", "text": text, "tr": heard, **({"fix": fix} if fix else {})})
-        chat.log.append({"from": "tutor", **reply, **({"summary": summary} if summary else {})})
-        return {"heard": heard, "reply": reply, "fix": fix, "summary": summary or None, "turn": chat.turns,
-                "turns": MAX_TURNS, "done": chat.done}
-
-    def _answer(self, chat: Chat, messages: list[dict]) -> dict:
-        """Asks the model and keeps the exchange in the conversation's history (only once it has answered)."""
-        data, usage = self._ask(chat.system, messages)
-        chat.model = self.model   # the panel may have changed it since the conversation began
-        chat.messages = messages + [{"role": "assistant", "content": json.dumps(data, ensure_ascii=False)}]
-        chat.seen = time.monotonic()
-        chat.input_tokens += usage[0]
-        chat.output_tokens += usage[1]
-        return data
-
-    def _ask(self, system: str, messages: list[dict]) -> tuple[dict, tuple[int, int]]:
-        import anthropic
-        try:
-            res = self.client.messages.create(
-                model=self.model, system=system, messages=messages, cache_control={"type": "ephemeral"},
-                **request_options(self.model),
-            )
-        except anthropic.RateLimitError as e:
-            log.warning("tutor rate limited: %s", e)
-            raise TutorUnavailable("המורה עמוס כרגע. נסו שוב בעוד דקה.") from e
-        except anthropic.AuthenticationError as e:
-            log.error("tutor: the API key was refused: %s", e)
-            raise TutorUnavailable("המורה לא זמין כרגע (מפתח ה-API לא תקין).") from e
-        except anthropic.APIStatusError as e:
-            log.warning("tutor: the API answered %s: %s", e.status_code, e.message)
-            raise TutorUnavailable("המורה לא זמין כרגע. נסו שוב.") from e
-        except anthropic.APIConnectionError as e:
-            log.warning("tutor: no connection: %s", e)
-            raise TutorUnavailable("אין חיבור למורה כרגע. נסו שוב.") from e
-        if res.stop_reason == "refusal":
-            log.warning("tutor: the model declined (%s)", res.stop_details)
-            raise TutorUnavailable("המורה לא יכול לענות על זה. נסו לומר משהו אחר.")
-        if res.stop_reason == "max_tokens":
-            raise TutorUnavailable("התשובה נקטעה. נסו שוב.")
-        text = next((b.text for b in res.content if b.type == "text"), "")
-        try:
-            data = json.loads(text)
-        except ValueError as e:
-            log.warning("tutor: an answer that is not JSON: %r", text[:300])
-            raise TutorUnavailable("המורה לא הצליח לענות. נסו שוב.") from e
-        return data, (res.usage.input_tokens + (res.usage.cache_read_input_tokens or 0)
-                      + (res.usage.cache_creation_input_tokens or 0), res.usage.output_tokens)
-
-    def _sweep(self) -> None:
-        """Drops conversations nobody continued for TTL, and the oldest past MAX_LIVE. Called with the lock held."""
-        now = time.monotonic()
-        for k in [k for k, c in self._chats.items() if now - c.seen > TTL]:
-            del self._chats[k]
-        while len(self._chats) >= MAX_LIVE:
-            del self._chats[min(self._chats, key=lambda k: self._chats[k].seen)]
-        if len(self._started) > 10 * MAX_LIVE:
-            self._started.clear()
-
-
-def tutor_client(key: str):
-    import anthropic
-    return anthropic.Anthropic(api_key=key, timeout=30.0, max_retries=2)
-
-
-def load_tutor(key: str | None = None, model: str | None = None) -> Tutor | None:
-    """`key`, `model`: the ones the panel set (see keystore.py); None reads the environment's."""
-    if key is None:
-        key = os.environ.get("ANTHROPIC_API_KEY", "") or os.environ.get("CLAUDE_API_KEY", "")
-    key = key.strip()
-    if not key:
-        log.info("no ANTHROPIC_API_KEY: the tutor game (יאללה נדבר) is off")
-        return None
-    try:
-        import anthropic
-    except ImportError:
-        log.warning("ANTHROPIC_API_KEY is set but the anthropic package is not installed: the tutor game is off")
-        return None
-    model = (os.environ.get("TUTOR_MODEL", "") if model is None else model).strip() or DEFAULT_MODEL
-    log.info("the tutor game (יאללה נדבר) runs on %s", model)
-    return Tutor(tutor_client(key), model)
-
-
-def tutor_open() -> bool:
-    """Whether every student gets the game, and not only the teachers."""
-    return os.environ.get("TUTOR_OPEN", "").strip().lower() in ("1", "true", "yes", "on")

app/verb_game.py

@@ -1,411 +0,0 @@
-"""Exercise generation and server-side checking for "פועל יוצא" levels 1--5.
-
-The grammar tables are deliberately the only linguistic source used here.  A verb
-without a complete table is not eligible for the game: guessing a missing form is
-worse than offering a smaller, accurate exercise pool.
-"""
-from __future__ import annotations
-
-import random
-import secrets
-import time
-from dataclasses import dataclass, field
-from typing import Any
-
-from .conjugation import (FUTURE_PREFIX, FUTURE_SUFFIX, FUTURE_SUFFIX_TILES, PAST_SUFFIX, PAST_SUFFIX_TILES,
-                          PAST_SUFFIX_TR, PREFIX_TILES, STAGE_A_VERBS, compose, lead, plain)
-from .grammar import PRONOUNS, VERBS
-from .workbook import LEX
-
-
-VERB_META = {
-    "akal": {"name": "אכל", "unlock": "1"},
-    "qaad": {"name": "ישב", "unlock": "1"},
-    "fatah": {"name": "פתח", "unlock": "1"},
-    "saal": {"name": "שאל", "unlock": "1"},
-    "tabakh": {"name": "בישל", "unlock": "3"},
-    "aja": {"name": "בא", "unlock": "4"},
-    "raah": {"name": "הלך", "unlock": "5"},
-    "faat": {"name": "נכנס / עבר", "unlock": "6"},
-    "fihem": {"name": "הבין", "unlock": "8"},
-    "laeb": {"name": "שיחק", "unlock": "10"},
-    "libes": {"name": "לבש", "unlock": "2.3"},
-    "labbas": {"name": "הלביש", "unlock": "2.3"},
-    "jaab": {"name": "הביא", "unlock": "2.5"},
-    "saaad": {"name": "עזר", "unlock": "2.6"},
-    "rakad": {"name": "רץ", "unlock": "2.7"},
-    "dall": {"name": "נשאר / המשיך", "unlock": "2.8"},
-}
-LEVELS = {
-    1: {"name": "בחירת ההטיה", "choices": 4, "window_ms": 12000},
-    2: {"name": "התאמת הגופים", "pairs": 6},
-    3: {"name": "החלפה מהירה", "choices": 3, "window_ms": 6000},
-    4: {"name": "אומרים בקול"},
-    5: {"name": "תגובה בשיחה"},
-}
-
-# "בונים עם איתן": stage A's verbs, past and future together, built from tiles (אותיות איתן and the endings).
-# 6 shows the Hebrew beside the slots, 7 only after the answer; 8 shows a form and asks every pronoun it can be.
-EITAN_LEVELS = {
-    6: {"name": "בונים עם עברית"},
-    7: {"name": "בונים לבד"},
-    8: {"name": "מי אמר?"},
-}
-TENSE_NAMES = {"past": "עבר", "future": "עתיד"}
-
-# Complete, filled past-tense tables in the parsed book.  Order is PRONOUNS order.
-# Arabic is not copied or inferred from transliteration: each form must resolve back
-# to the application's existing LEX source of truth, otherwise the paradigm is dropped.
-BOOK_PAST_TRANSLITERATIONS = {
-    "tabakh": ["טַבַּחֵ'ת", "טַבַּחֵ'ת", "טַבַּחְ'תִי", "טַבַּח'", "טַבְּחַ'ת", "טַבַּחְ'נַא", "טַבַּחְ'תוּ", "טַבַּח'וּ"],
-    "aja": ["אַגֵ'ית", "אַגֵ'ית", "אַגֵ'יתִי", "אַגַ'א", "אַגַ'ת", "אַגֵ'ינַא", "אַגֵ'יתוּ", "אַג'וּ"],
-    "raah": ["רֻחֵת", "רֻחֵת", "רֻחְתִי", "רַאח", "רַאחַת", "רֻחְנַא", "רֻחְתוּ", "רַאחוּ"],
-    "faat": ["פֻתֵת", "פֻתֵת", "פֻתִّי", "פַאת", "פַאתַת", "פֻתְנַא", "פֻתّוּ", "פַאתוּ"],
-    "fihem": ["פְהִמֵת", "פְהִמֵת", "פְהִמְתִי", "פִהֵם", "פִהְמַת", "פְהִמְנַא", "פְהִמְתוּ", "פִהְמוּ"],
-    "laeb": ["לְעִבֵּת", "לְעִבֵּת", "לְעִבְּתִי", "לִעֵבּ", "לִעְבַּת", "לְעִבְּנַא", "לְעִבְּתוּ", "לִעְבּוּ"],
-    "libes": ["לְבִּסֵת", "לְבִּסֵת", "לְבִּסְתִי", "לִבֵּס", "לִבְּסַת", "לְבִּסְנַא", "לְבִּסְתוּ", "לִבְּסוּ"],
-    "labbas": ["לַבַּّסֵת", "לַבַּّסֵת", "לַבַּّסְתִי", "לַבַּّס", "לַבַּّסַת", "לַבַּّסְנַא", "לַבַּّסְתוּ", "לַבַּّסוּ"],
-    "jaab": ["גִ'בֵּת", "גִ'בֵּת", "גִ'בְּתִי", "גַ'אבּ", "גַ'אבַּת", "גִ'בְּנַא", "גִ'בְּתוּ", "גַ'אבּוּ"],
-    "saaad": ["סַאעַדֵת", "סַאעַדֵת", "סַאעַדְתִי", "סַאעַד", "סַאעַדַת", "סַאעַדְנַא", "סַאעַדְתוּ", "סַאעַדוּ"],
-    "rakad": ["רַכַּדֵֿת", "רַכַּדֵֿת", "רַכַּדְֿתִי", "רַכַּדֿ", "רַכְּדַֿת", "רַכַּדְֿנַא", "רַכַּדְֿתוּ", "רַכַּדֿוּ"],
-    "dall": ["דַֿלֵّית", "דַֿלֵّית", "דַֿלֵّיתִי", "דַֿלّ", "דַֿלַّת", "דַֿלֵّינַא", "דַֿלֵّיתוּ", "דַֿלّוּ"],
-}
-
-
-def _book_paradigms() -> dict[str, list[tuple[str, str]]]:
-    by_tr: dict[str, tuple[str, str]] = {}
-    for key, (tr, _ipas) in LEX.items():
-        by_tr.setdefault(tr, (key.partition("#")[0], tr, list(_ipas)))
-    return {verb: [by_tr[tr] for tr in forms] for verb, forms in BOOK_PAST_TRANSLITERATIONS.items()
-            if all(tr in by_tr for tr in forms)}
-
-
-BOOK_VERBS = _book_paradigms()
-
-
-def _form(verb: str, pronoun: int) -> dict[str, Any]:
-    if verb in VERBS:
-        he, tr, arabic, ipas = VERBS[verb][pronoun]
-        return {"hebrew": he, "transliteration": tr, "arabic": arabic, "ipas": list(ipas)}
-    arabic, tr, ipas = BOOK_VERBS[verb][pronoun]
-    return {"hebrew": "", "transliteration": tr, "arabic": arabic, "ipas": ipas}
-
-
-def _paradigm(verb: str) -> list:
-    return VERBS[verb] if verb in VERBS else BOOK_VERBS[verb]
-
-
-def _distance(a: str, b: str) -> int:
-    """Small edit distance, used only to rank real database forms as distractors."""
-    row = list(range(len(b) + 1))
-    for i, x in enumerate(a, 1):
-        old = row[0]
-        row[0] = i
-        for j, y in enumerate(b, 1):
-            above = row[j]
-            row[j] = min(row[j] + 1, row[j - 1] + 1, old + (x != y))
-            old = above
-    return row[-1]
-
-
-@dataclass
-class StoredQuestion:
-    mode: int
-    verb: str
-    correct: dict[str, str]
-    made_at: float
-    forms: dict[str, tuple[str, str]] = field(default_factory=dict)
-    phrase: dict[str, Any] | None = None
-
-
-class PracticeSessionManager:
-    """Short-lived opaque questions prevent clients from grading themselves."""
-
-    def __init__(self, ttl_seconds: int = 1800, rng: random.Random | None = None):
-        self.ttl_seconds = ttl_seconds
-        self.rng = rng or random.Random()
-        self.questions: dict[str, StoredQuestion] = {}
-
-    def put(self, question: StoredQuestion) -> str:
-        now = time.monotonic()
-        self.questions = {k: v for k, v in self.questions.items() if now - v.made_at < self.ttl_seconds}
-        key = secrets.token_urlsafe(18)
-        self.questions[key] = question
-        return key
-
-    def take(self, key: str) -> StoredQuestion | None:
-        question = self.questions.pop(key, None)
-        if question and time.monotonic() - question.made_at < self.ttl_seconds:
-            return question
-        return None
-
-    def get(self, key: str) -> StoredQuestion | None:
-        question = self.questions.get(key)
-        if question and time.monotonic() - question.made_at < self.ttl_seconds:
-            return question
-        self.questions.pop(key, None)
-        return None
-
-    def finish(self, key: str) -> None:
-        self.questions.pop(key, None)
-
-
-class VerbExerciseGenerator:
-    def __init__(self, sessions: PracticeSessionManager | None = None):
-        self.sessions = sessions or PracticeSessionManager()
-        self.rng = self.sessions.rng
-
-    @staticmethod
-    def available(lessons: list[str]) -> list[str]:
-        allowed = set(lessons)
-        return [v for v in VERB_META
-                if (v in VERBS or v in BOOK_VERBS)
-                and len(_paradigm(v)) == len(PRONOUNS)
-                and VERB_META[v]["unlock"] in allowed]
-
-    def metadata(self, lessons: list[str]) -> dict[str, Any]:
-        return {
-            "levels": [{"id": n, **cfg} for n, cfg in LEVELS.items()],
-            "verbs": [{"id": v, "name": VERB_META[v]["name"], "unlock": VERB_META[v]["unlock"]}
-                      for v in self.available(lessons)],
-            "tenses": [{"id": "past", "name": "עבר"}],
-            "eitan_levels": [{"id": n, **cfg} for n, cfg in EITAN_LEVELS.items()],
-            "eitan_verbs": [{"id": v, "name": STAGE_A_VERBS[v]["name"], "draft": STAGE_A_VERBS[v]["draft"]}
-                            for v in self.eitan_available(lessons, drafts=True)],
-        }
-
-    def _target(self, verbs: list[str], mastery: dict, recent: list[str]) -> tuple[str, int]:
-        candidates = [(v, p) for v in verbs for p in range(len(PRONOUNS))]
-        def priority(item: tuple[str, int]) -> float:
-            v, p = item
-            key = f"{v}:past:{PRONOUNS[p][0]}"
-            m = mastery.get(key, {}) if isinstance(mastery, dict) else {}
-            attempts = max(0, int(m.get("attempts", 0) or 0))
-            accuracy = float(m.get("correct", 0) or 0) / attempts if attempts else 0.0
-            slow = min(float(m.get("median_ms", 0) or 0) / 4000, 1.5)
-            recency_penalty = 5 if key in recent[-3:] else 0
-            # Incorrect, slow, and unseen forms rise; a little noise avoids a fixed drill order.
-            return (3 if attempts and accuracy < .7 else 0) + slow + (2 if not attempts else 0) - recency_penalty + self.rng.random()
-        return max(candidates, key=priority)
-
-    @staticmethod
-    def eitan_available(lessons: list[str], drafts: bool = False) -> list[str]:
-        """Stage A's verbs of the lessons given; a verb with draft future forms only when drafts are wanted (teachers)."""
-        allowed = set(lessons)
-        return [v for v, verb in STAGE_A_VERBS.items() if verb["lesson"] in allowed and (drafts or not verb["draft"])]
-
-    def question(self, level: int, lessons: list[str], mastery: dict | None = None,
-                 recent: list[str] | None = None, drafts: bool = False) -> dict[str, Any]:
-        if level in EITAN_LEVELS:
-            return self._eitan(level, lessons, mastery or {}, recent or [], drafts)
-        if level not in LEVELS:
-            raise ValueError("unsupported level")
-        verbs = self.available(lessons)
-        if not verbs:
-            raise LookupError("no complete verb paradigms are unlocked")
-        if level == 2:
-            return self._matching(verbs, mastery or {}, recent or [])
-        if level in (4, 5):
-            return self._spoken(level, verbs, mastery or {}, recent or [])
-        verb, pron = self._target(verbs, mastery or {}, recent or [])
-        right = _form(verb, pron)
-        count = LEVELS[level]["choices"]
-        pool = []
-        for other_pron in range(len(PRONOUNS)):
-            if other_pron != pron:
-                pool.append((verb, other_pron, _form(verb, other_pron)))
-        if level == 3 and len(verbs) > 1:
-            for other in verbs:
-                if other != verb:
-                    pool.append((other, pron, _form(other, pron)))
-        pool.sort(key=lambda x: (_distance(right["transliteration"], x[2]["transliteration"]), self.rng.random()))
-        unique, seen = [], {(right["transliteration"], right["arabic"])}
-        for _, _, form in pool:
-            signature = (form["transliteration"], form["arabic"])
-            if signature not in seen:
-                seen.add(signature)
-                unique.append(form)
-            if len(unique) == count - 1:
-                break
-        choices = [{"id": secrets.token_urlsafe(7), "transliteration": f["transliteration"], "arabic": f["arabic"]}
-                   for f in [right, *unique]]
-        self.rng.shuffle(choices)
-        correct_id = next(c["id"] for c in choices if (c["transliteration"], c["arabic"]) ==
-                          (right["transliteration"], right["arabic"]))
-        qid = self.sessions.put(StoredQuestion(level, verb, {"choice": correct_id}, time.monotonic()))
-        pronoun = PRONOUNS[pron]
-        return {
-            "question_id": qid, "level": level, "tense": {"id": "past", "name": "עבר"},
-            "verb": {"id": verb, "name": VERB_META[verb]["name"], "arabic": _form(verb, 3)["arabic"]},
-            "pronoun": {"id": pronoun[0], "hebrew": pronoun[1], "transliteration": pronoun[2]},
-            "choices": choices, "time_limit_ms": LEVELS[level]["window_ms"],
-            "mastery_key": f"{verb}:past:{pronoun[0]}",
-        }
-
-    def _matching(self, verbs: list[str], mastery: dict, recent: list[str]) -> dict[str, Any]:
-        verb, _ = self._target(verbs, mastery, recent)
-        count = min(LEVELS[2]["pairs"], len(PRONOUNS))
-        indices = self.rng.sample(range(len(PRONOUNS)), count)
-        left, right, correct, forms = [], [], {}, {}
-        for p in indices:
-            pron = PRONOUNS[p]
-            form = _form(verb, p)
-            pid, fid = secrets.token_urlsafe(6), secrets.token_urlsafe(6)
-            left.append({"id": pid, "hebrew": pron[1], "transliteration": pron[2]})
-            right.append({"id": fid, "transliteration": form["transliteration"], "arabic": form["arabic"]})
-            correct[pid] = fid
-            forms[fid] = (form["transliteration"], form["arabic"])
-        self.rng.shuffle(left)
-        self.rng.shuffle(right)
-        qid = self.sessions.put(StoredQuestion(2, verb, correct, time.monotonic(), forms))
-        return {"question_id": qid, "level": 2, "tense": {"id": "past", "name": "עבר"},
-                "verb": {"id": verb, "name": VERB_META[verb]["name"], "arabic": _form(verb, 3)["arabic"]},
-                "pronouns": left, "forms": right, "pair_count": count,
-                "mastery_key": f"{verb}:past:matching"}
-
-    def _spoken(self, level: int, verbs: list[str], mastery: dict, recent: list[str]) -> dict[str, Any]:
-        if level == 5:
-            # A controlled first conversation: the learner answers about themself.  Keeping
-            # the target to ana makes the prompt natural and the grammar target unambiguous.
-            scored = [(v, 0) for v in verbs]
-            verb, pron = max(scored, key=lambda x: self.rng.random() +
-                             (2 if not mastery.get(f"{x[0]}:past:ana") else 0))
-        else:
-            verb, pron = self._target(verbs, mastery, recent)
-        form = _form(verb, pron)
-        p = PRONOUNS[pron]
-        variants = [(form["arabic"], ipa) for ipa in form["ipas"]]
-        if level == 5:
-            pron_ar, pron_ipa = PRONOUNS[0][3][0]
-            variants += [(f"{pron_ar} {form['arabic']}", f"{pron_ipa} | {ipa}") for ipa in form["ipas"]]
-        phrase = {"variants": variants, "cat": "verb-game", "key": f"{verb}:past:{p[0]}:spoken",
-                  "he": f"{p[1]} · {VERB_META[verb]['name']} (עבר)"}
-        qid = self.sessions.put(StoredQuestion(level, verb, {}, time.monotonic(), phrase=phrase))
-        result = {
-            "question_id": qid, "level": level, "tense": {"id": "past", "name": "עבר"},
-            "verb": {"id": verb, "name": VERB_META[verb]["name"], "arabic": _form(verb, 3)["arabic"]},
-            "pronoun": {"id": p[0], "hebrew": p[1], "transliteration": p[2]},
-            "mastery_key": f"{verb}:past:{p[0]}:spoken",
-        }
-        if level == 5:
-            result["conversation"] = {"arabic": "شو عملت مبارح؟", "transliteration": "שוּ עְמֵלְת אִמְבַּארֵח?",
-                                      "hebrew": "מה עשית אתמול?"}
-        return result
-
-    def _pick(self, keys: list[tuple[str, Any]], mastery: dict, recent: list[str]) -> tuple[str, Any]:
-        """(mastery key, item): the weakest, slowest or unseen first, never one of the last three."""
-        def priority(entry: tuple[str, Any]) -> float:
-            m = mastery.get(entry[0], {}) if isinstance(mastery, dict) else {}
-            m = m if isinstance(m, dict) else {}
-            attempts = max(0, int(m.get("attempts", 0) or 0))
-            accuracy = float(m.get("correct", 0) or 0) / attempts if attempts else 0.0
-            slow = min(float(m.get("median_ms", 0) or 0) / 6000, 1.5)
-            return ((3 if attempts and accuracy < .7 else 0) + slow + (2 if not attempts else 0)
-                    - (5 if entry[0] in recent[-3:] else 0) + self.rng.random())
-        return max(keys, key=priority)
-
-    def _eitan(self, level: int, lessons: list[str], mastery: dict, recent: list[str], drafts: bool) -> dict[str, Any]:
-        verbs = self.eitan_available(lessons, drafts)
-        if not verbs:
-            raise LookupError("no stage A verbs with a checked future are unlocked")
-        if level == 8:
-            entries = [(f"{v}:{t}:who:{p}", (v, t, p)) for v in verbs for t in ("past", "future") for p in range(len(PRONOUNS))]
-            key, (verb_id, tense, pron) = self._pick(entries, mastery, recent)
-            verb, form = STAGE_A_VERBS[verb_id], STAGE_A_VERBS[verb_id][tense][pron]
-            same = lambda f: plain(f["ar"]) == plain(form["ar"]) and f["tr"] == form["tr"]
-            who = [PRONOUNS[p][0] for p, f in enumerate(verb[tense]) if same(f)]
-            qid = self.sessions.put(StoredQuestion(level, verb_id, {"who": who, "tense": tense, "pronoun": pron},
-                                                   time.monotonic()))
-            return {"question_id": qid, "level": level, "tense": {"id": tense, "name": TENSE_NAMES[tense]},
-                    "verb": {"id": verb_id, "name": verb["name"], "transliteration": verb["transliteration"],
-                             "draft": verb["draft"]},
-                    "form": {"arabic": form["ar"], "transliteration": form["tr"], "parts": form["tr_parts"]},
-                    "pronouns": [{"id": p[0], "hebrew": p[1], "transliteration": p[2]} for p in PRONOUNS],
-                    "mastery_key": key}
-        entries = [(f"{v}:pf:{PRONOUNS[p][0]}", (v, p)) for v in verbs for p in range(len(PRONOUNS))]
-        key, (verb_id, pron) = self._pick(entries, mastery, recent)
-        verb, p = STAGE_A_VERBS[verb_id], PRONOUNS[pron]
-        past, future = verb["past"][pron], verb["future"][pron]
-        # a tile: its Arabic (what is sent back and graded) and its transliteration (what the page shows)
-        tiles = lambda pairs: [{"arabic": a, "label": h} for a, h in pairs]
-        leads = {FUTURE_PREFIX[i]: lead(verb["future"][i]["tr"])[0] for i in (0, 1, 3, 5)}   # this verb's vowels
-        question = {
-            "question_id": self.sessions.put(StoredQuestion(level, verb_id, {"pronoun": pron}, time.monotonic())),
-            "level": level, "tense": {"id": "both", "name": "עבר ועתיד"},
-            "verb": {"id": verb_id, "name": verb["name"], "transliteration": verb["transliteration"],
-                     "draft": verb["draft"]},
-            "pronoun": {"id": p[0], "hebrew": p[1], "transliteration": p[2]},
-            "past": {"body": past["tr_parts"]["body"], "tiles": tiles(PAST_SUFFIX_TILES)},
-            "future": {"body": future["tr_parts"]["body"],
-                       "prefix_tiles": tiles([(a, leads[a]) for a, _ in PREFIX_TILES]),
-                       "suffix_tiles": tiles(FUTURE_SUFFIX_TILES)},
-            "mastery_key": key,
-        }
-        if level == 6:
-            question["past"]["hebrew"], question["future"]["hebrew"] = past["he"], future["he"]
-        return question
-
-    @staticmethod
-    def _shown(form: dict) -> dict[str, Any]:
-        return {"arabic": form["ar"], "transliteration": form["tr"], "parts": form["tr_parts"], "hebrew": form["he"],
-                "draft": form["draft"]}
-
-    def _eitan_answer(self, q: StoredQuestion, answer: Any, response_ms: int) -> dict[str, Any]:
-        verb = STAGE_A_VERBS[q.verb]
-        supplied = answer if isinstance(answer, dict) else {}
-        if q.mode == 8:
-            chosen = supplied.get("who") if isinstance(supplied.get("who"), list) else []
-            chosen = sorted({str(c) for c in chosen})
-            ok = chosen == sorted(q.correct["who"])
-            tense = q.correct["tense"]
-            explain = ("בעתיד התחילית אומרת מי: א=אני, ת=אתה/את/היא/אתם, י=הוא/הם, נ=אנחנו, כמו בעברית. "
-                       "ת לבדה היא גם אתה וגם היא." if tense == "future" else
-                       "בעבר הסיומת אומרת מי. ת בסוף היא אני, אתה וגם היא, ורק התנועות מבדילות ביניהם.")
-            return {"correct": ok, "who": q.correct["who"], "response_ms": response_ms,
-                    "forms": [{"pronoun": PRONOUNS[i][0], **self._shown(f)} for i, f in enumerate(verb[tense])],
-                    **({} if ok else {"explanation": explain})}
-        pron = q.correct["pronoun"]
-        past, future = verb["past"][pron], verb["future"][pron]
-        text = lambda k: str(supplied.get(k) or "")
-        past_ok = plain(past["body"] + text("past")) == plain(past["ar"])
-        future_ok = plain(compose(text("prefix"), future["body"], text("suffix"))) == plain(future["ar"])
-        result = {"correct": past_ok and future_ok, "past_correct": past_ok, "future_correct": future_ok,
-                  "past": self._shown(past), "future": self._shown(future), "response_ms": response_ms}
-        if not future_ok:
-            he, parts = "".join(future["he"].values()), future["tr_parts"]
-            ending = f"…{parts['suf'].lstrip(chr(0x05B4))}" if parts["suf"] else ""   # …י, not a hiriq on the dots
-            result["explanation"] = f"בעתיד: {parts['pre']}{ending}, כמו {he} בעברית."
-        elif not past_ok:
-            ending = PAST_SUFFIX_TR[pron][0]
-            result["explanation"] = f"בעבר הסיומת של {PRONOUNS[pron][1]} היא {'…' + ending if ending else 'בלי סיומת'}."
-        return result
-
-    def speech_phrase(self, question_id: str) -> tuple[StoredQuestion, dict[str, Any]]:
-        question = self.sessions.get(question_id)
-        if not question or question.mode not in (4, 5) or not question.phrase:
-            raise LookupError("spoken question expired")
-        return question, question.phrase
-
-    def answer(self, question_id: str, answer: Any, response_ms: int) -> dict[str, Any]:
-        q = self.sessions.take(question_id)
-        if not q:
-            raise LookupError("question expired or already answered")
-        response_ms = max(0, min(int(response_ms), 300_000))
-        if q.mode in EITAN_LEVELS:
-            return self._eitan_answer(q, answer, response_ms)
-        if q.mode == 2:
-            supplied = answer if isinstance(answer, dict) else {}
-            # A duplicated written/spoken form is interchangeable with its identical twin.
-            pair_results = {pid: supplied.get(pid) in q.forms and q.forms[supplied[pid]] == q.forms[expected]
-                            for pid, expected in q.correct.items()}
-            correct = sum(pair_results.values())
-            total = len(q.correct)
-            return {"correct": correct == total, "correct_pairs": correct, "total_pairs": total,
-                    "pair_results": pair_results, "response_ms": response_ms}
-        chosen = str(answer)
-        ok = chosen == q.correct["choice"]
-        result = {"correct": ok, "response_ms": response_ms}
-        if not ok:
-            result["explanation"] = "הסיומת משתנה לפי הגוף. התאימו את ההטיה לכינוי שמופיע בשאלה."
-            result["correct_choice_id"] = q.correct["choice"]
-        return result

arabic_splash/README.md

@@ -1,12 +0,0 @@
-# Animated splash for FastAPI / HTML
-
-Run locally:
-
-```bash
-pip install -r requirements.txt
-uvicorn app:app --host 0.0.0.0 --port 7860
-```
-
-For Hugging Face Spaces Docker, run uvicorn on port 7860 and expose port 7860 in your Dockerfile.
-
-To integrate into an existing project: copy static/logo.png, splash.css, splash.js; add the stylesheet to your HTML head, the `#app-splash` div from index.html at the beginning of body, and the JS script at the end of body. Ensure your FastAPI app serves /static. The demo uses three clipped copies of the original image, preserving the logo exactly. It is a reveal animation, not true vector stroke tracing.

arabic_splash/app.py

@@ -1,12 +0,0 @@
-from pathlib import Path
-from fastapi import FastAPI
-from fastapi.responses import FileResponse
-from fastapi.staticfiles import StaticFiles
-
-BASE = Path(__file__).resolve().parent
-app = FastAPI()
-app.mount('/static', StaticFiles(directory=BASE / 'static'), name='static')
-
-@app.get('/')
-def home():
-    return FileResponse(BASE / 'index.html')

arabic_splash/index.html

@@ -1,20 +0,0 @@
-<!doctype html>
-<html lang="he" dir="rtl">
-<head>
-  <meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Arabic School — Splash Demo</title>
-  <link rel="stylesheet" href="/static/splash.css">
-  <style>body{margin:0;font-family:system-ui,sans-serif;background:#faf9f6;color:#252525}main{max-width:720px;margin:12vh auto;padding:24px;text-align:center}button{padding:12px 20px;border:1px solid #333;background:white;border-radius:8px;cursor:pointer}</style>
-</head>
-<body>
-  <div id="app-splash" role="status" aria-label="האפליקציה נטענת">
-    <div class="splash-art" aria-hidden="true">
-      <img class="splash-layer splash-symbol" src="/static/logo.png" alt="">
-      <img class="splash-layer splash-arabic" src="/static/logo.png" alt="">
-      <img class="splash-layer splash-hebrew" src="/static/logo.png" alt="">
-    </div>
-  </div>
-  <main><h1>ברוכים הבאים</h1><p>זהו מסך הדגמה. החליפו את התוכן הזה בממשק האפליקציה שלכם.</p><button onclick="location.reload()">הפעל את האנימציה שוב</button></main>
-  <script src="/static/splash.js" defer></script>
-</body>
-</html>

arabic_splash/requirements.txt

@@ -1,2 +0,0 @@
-fastapi
-uvicorn

arabic_splash/static/splash.css

@@ -1,12 +0,0 @@
-:root { --splash-bg: #fff; --splash-duration: 3100ms; }
-#app-splash { position:fixed; inset:0; z-index:99999; display:grid; place-items:center; background:var(--splash-bg); transition:opacity .45s ease, visibility .45s ease; }
-#app-splash.splash-done { opacity:0; visibility:hidden; pointer-events:none; }
-.splash-art { position:relative; width:min(88vw, 560px); aspect-ratio:489/225; }
-.splash-layer { position:absolute; inset:0; width:100%; height:100%; object-fit:contain; }
-.splash-symbol { clip-path:polygon(64% 0,100% 0,100% 100%,64% 100%); animation:symbol-in .95s ease-out both; transform-origin:82% 48%; }
-.splash-arabic { clip-path:polygon(0 0,65% 0,65% 72%,0 72%); animation:arabic-in 1.05s .65s ease-out both; }
-.splash-hebrew { clip-path:polygon(0 69%,65% 69%,65% 100%,0 100%); animation:hebrew-in .65s 1.6s ease-out both; }
-@keyframes symbol-in { from {opacity:0; transform:scale(.78) rotate(-18deg)} to {opacity:1; transform:scale(1) rotate(0)} }
-@keyframes arabic-in { from {opacity:0; clip-path:polygon(65% 0,65% 0,65% 72%,65% 72%)} to {opacity:1; clip-path:polygon(0 0,65% 0,65% 72%,0 72%)} }
-@keyframes hebrew-in { from {opacity:0; transform:translateY(10px)} to {opacity:1; transform:translateY(0)} }
-@media (prefers-reduced-motion:reduce) { .splash-layer {animation:none!important} #app-splash {transition:none} }

arabic_splash/static/splash.js

@@ -1,9 +0,0 @@
-(() => {
-  const splash = document.getElementById('app-splash');
-  if (!splash) return;
-  const hide = () => { splash.classList.add('splash-done'); window.setTimeout(() => splash.remove(), 500); };
-  const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-  const start = () => window.setTimeout(hide, reduced ? 300 : 3100);
-  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, { once:true });
-  else start();
-})();

data/example.csv

@@ -1,4 +0,0 @@
-audio,ipa
-native/toilet_01.webm,w eː n | i l ħ a m m aː m
-learners/toilet_dana_03.webm,w eː n | i l χ a m m aː m
-native/coffee_01.webm,b i d d i | f i n dʒ aː n | ʔ a h w e

docs/future-forms-draft.md

@@ -1,293 +0,0 @@
-# טיוטת העתיד של פעלי שלב א' — לבדיקה
-
-הטבלה מציגה את צורות העתיד של כל פועל משלב א' שחסרה לו לפחות צורה אחת במאגר (LEX). ✓ = כבר במאגר ונבדקה. ✎ = טיוטה שנבנתה לפי הכלל, וצריך לבדוק אותה. אחרי הבדיקה, הצורות הנכונות עוברות ל־LEX (`app/workbook.py`) ונמחקות מ־`app/future_draft.py`. פועל שכל שמונה הצורות שלו נמצאות ב־LEX מגיע לתלמידים במשחק "בונים פועל עם איתן". עד אז רק מורים רואים אותו, עם התווית טיוטה.
-
-**כבר מוכנים לתלמידים (11):** שאל (يسأل), ישב (يقعد), בא (يجي), דיבר (يحكي), ביקר (يزور), ראה (يشوف), שתה (يشرب), יצא ועלה (يطلع), שמע (يسمع), אכל צהריים (يتغدّى), שיחק (يلعب)
-
-מה לבדוק בכל ✎: הכתיב בערבית, התעתיק (בעיקר התנועה של התחילית: יִ / יֻ / יְ) וההגייה. השמטת התנועה ב־ـي/ـו (למשל תֹאכְּלִי) נבנתה רק במקומות שבהם היא כבר מופיעה במאגר.
-
-## פתח · فتح · يفتح (שיעור 1) — 6 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | افتح | אַפְתַח | `ʔ a f t a ħ` |
-| ✎ | אתה | تفتح | תִפְתַח | `t i f t a ħ` |
-| ✎ | את | تفتحي | תִפְתַחִי | `t i f t a ħ i` |
-| ✓ | הוא | يفتح | יִפְתַח | `j i f t a ħ` |
-| ✎ | היא | تفتح | תִפְתַח | `t i f t a ħ` |
-| ✎ | אנחנו | نفتح | נִפְתַח | `n i f t a ħ` |
-| ✎ | אתם | تفتحو | תִפְתַחוּ | `t i f t a ħ u` |
-| ✎ | הם | يفتحو | יִפְתַחוּ | `j i f t a ħ u` |
-
-## אכל · اكل · ياكل (שיעור 1) — 1 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | آكل | אַאכֹּל | `ʔ aː k u l / ʔ aː k i l` |
-| ✓ | אתה | تاكل | תֹאכֹּל | `t oː k u l / t oː k i l / t aː k u l` |
-| ✓ | את | تاكلي | תֹאכְּלִי | `t oː k l i / t aː k l i / t oː k i l i` |
-| ✓ | הוא | ياكل | יֹאכֹּל | `j oː k u l / j oː k i l / j aː k u l` |
-| ✓ | היא | تاكل | תֹאכֹּל | `t oː k u l / t oː k i l / t aː k u l` |
-| ✓ | אנחנו | ناكل | נֹאכֹּל | `n oː k u l / n oː k i l / n aː k u l` |
-| ✓ | אתם | تاكلو | תֹאכְּלוּ | `t oː k l u / t aː k l u / t oː k u l u` |
-| ✎ | הם | ياكلو | יֹאכְּלוּ | `j oː k u l u / j oː k i l u / j aː k u l u / j oː k l u / j aː k l u` |
-
-## נכנס · دخل · يدخل (שיעור 3) — 3 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | ادخل | אַדְחֹ'ל | `ʔ a d x u l` |
-| ✓ | אתה | تدخل | תֻדְחֹ'ל | `t u d x u l` |
-| ✎ | את | تدخلي | תֻדְחֹ'לִי | `t u d x u l i` |
-| ✓ | הוא | يدخل | יֻדְחֹ'ל | `j u d x u l` |
-| ✓ | היא | تدخل | תֻדְחֹ'ל | `t u d x u l` |
-| ✓ | אנחנו | ندخل | נֻדְחֹ'ל | `n u d x u l` |
-| ✎ | אתם | تدخلو | תֻדְחֹ'לוּ | `t u d x u l u` |
-| ✎ | הם | يدخلو | יֻדְחֹ'לוּ | `j u d x u l u` |
-
-## שחה · سبح · يسبح (שיעור 3) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✎ | אני | اسبح | אַסְבַּח | `ʔ a s b a ħ` |
-| ✓ | אתה | تسبح | תִסְבַּח | `t i s b a ħ` |
-| ✎ | את | تسبحي | תִסְבַּחִי | `t i s b a ħ i` |
-| ✓ | הוא | يسبح | יִסְבַּח | `j i s b a ħ` |
-| ✓ | היא | تسبح | תִסְבַּח | `t i s b a ħ` |
-| ✓ | אנחנו | نسبح | נִסְבַּח | `n i s b a ħ` |
-| ✎ | אתם | تسبحو | תִסְבַּחוּ | `t i s b a ħ u` |
-| ✎ | הם | يسبحو | יִסְבַּחוּ | `j i s b a ħ u` |
-
-## בישל · طبخ · يطبخ (שיעור 3) — 2 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اطبخ | אַטְבֹּח' | `ʔ a tˤ b u x` |
-| ✓ | אתה | تطبخ | תֻטְבֹּח' | `t u tˤ b u x` |
-| ✓ | את | تطبخي | תֻטְבֹּחִ'י | `t u tˤ b u x i` |
-| ✓ | הוא | يطبخ | יֻטְבֹּח' | `j u tˤ b u x` |
-| ✓ | היא | تطبخ | תֻטְבֹּח' | `t u tˤ b u x` |
-| ✓ | אנחנו | نطبخ | נֻטְבֹּח' | `n u tˤ b u x` |
-| ✎ | אתם | تطبخو | תֻטְבֹּח'וּ | `t u tˤ b u x u` |
-| ✎ | הם | يطبخو | יֻטְבֹּח'וּ | `j u tˤ b u x u` |
-
-## עבר דירה · نقل · ينقل (שיעור 3) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✎ | אני | انقل | אַנְקֹל | `ʔ a n ʔ u l / ʔ a n q u l` |
-| ✓ | אתה | تنقل | תֻנְקֹל | `t u n ʔ u l / t u n q u l` |
-| ✎ | את | تنقلي | תֻנְקֹלִי | `t u n ʔ u l i / t u n q u l i` |
-| ✓ | הוא | ينقل | יֻנְקֹל | `j u n ʔ u l / j u n q u l` |
-| ✓ | היא | تنقل | תֻנְקֹל | `t u n ʔ u l / t u n q u l` |
-| ✎ | אנחנו | ننقل | נֻנְקֹל | `n u n ʔ u l / n u n q u l` |
-| ✎ | אתם | تنقلو | תֻנְקֹלוּ | `t u n ʔ u l u / t u n q u l u` |
-| ✓ | הם | ينقلو | יֻנְקֹלוּ | `j u n ʔ u l u / j u n q u l u` |
-
-## נתן · اعطى · يعطي (שיעור 4) — 3 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اعطي | אַעַטִי | `ʔ a ʕ tˤ i / ʔ a ʕ a tˤ i` |
-| ✓ | אתה | تعطي | תֵעַטִי | `t a ʕ tˤ i / t i ʕ tˤ i` |
-| ✓ | את | تعطي | תֵעַטִי | `t a ʕ tˤ i / t i ʕ tˤ i` |
-| ✓ | הוא | يعطي | יֵעַטִי | `j a ʕ tˤ i / j i ʕ tˤ i` |
-| ✓ | היא | تعطي | תֵעַטִי | `t a ʕ tˤ i / t i ʕ tˤ i` |
-| ✎ | אנחנו | نعطي | נֵעַטִי | `n a ʕ tˤ i / n i ʕ tˤ i` |
-| ✎ | אתם | تعطو | תֵעַטוּ | `t a ʕ tˤ u / t i ʕ tˤ u` |
-| ✎ | הם | يعطو | יֵעַטוּ | `j a ʕ tˤ u / j i ʕ tˤ u` |
-
-## קנה · اشترى · يشتري (שיעור 4) — 2 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اشتري | אַשְתְרִי | `ʔ a ʃ t r i / ʔ a ʃ t i r i` |
-| ✓ | אתה | تشتري | תִשְתְרִי | `t i ʃ t r i / t i ʃ t i r i` |
-| ✓ | את | تشتري | תִשְתְרִי | `t i ʃ t r i / t i ʃ t i r i` |
-| ✓ | הוא | يشتري | יִשְתְרִי | `j i ʃ t r i / j i ʃ t i r i` |
-| ✓ | היא | تشتري | תִשְתְרִי | `t i ʃ t r i / t i ʃ t i r i` |
-| ✓ | אנחנו | نشتري | נִשְתְרִי | `n i ʃ t r i / n i ʃ t i r i` |
-| ✎ | אתם | تشترو | תִשְתְרוּ | `t i ʃ t r u / t i ʃ t i r u` |
-| ✎ | הם | يشترو | יִשְתְרוּ | `j i ʃ t r u / j i ʃ t i r u` |
-
-## הלך · راح · يروح (שיעור 5) — 1 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اروح | אַרוּח | `ʔ a r uː ħ` |
-| ✓ | אתה | تروح | תְרוּח | `t r uː ħ` |
-| ✓ | את | تروحي | תְרוּחִי | `t r uː ħ i` |
-| ✓ | הוא | يروح | יִרוּח | `j r uː ħ / i r uː ħ / j i r uː ħ` |
-| ✓ | היא | تروح | תְרוּח | `t r uː ħ` |
-| ✓ | אנחנו | نروح | נְרוּח | `n r uː ħ` |
-| ✎ | אתם | تروحو | תְרוּחוּ | `t r uː ħ u / t i r uː ħ u` |
-| ✓ | הם | يروحو | יִרוּחוּ | `j r uː ħ u / i r uː ħ u / j i r uː ħ u` |
-
-## אמר · قال · يقول (שיעור 5) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اقول | אַקוּל | `ʔ a ʔ uː l / ʔ a q uː l` |
-| ✓ | אתה | تقول | תְקוּל | `t ʔ uː l / t q uː l` |
-| ✎ | את | تقولي | תְקוּלִי | `t ʔ uː l i / t q uː l i` |
-| ✓ | הוא | يقول | יִקוּל | `j ʔ uː l / i ʔ uː l / j q uː l / j i ʔ uː l` |
-| ✓ | היא | تقول | תְקוּל | `t ʔ uː l / t q uː l` |
-| ✎ | אנחנו | نقول | נְקוּל | `n ʔ uː l / n q uː l` |
-| ✎ | אתם | تقولو | תְקוּלוּ | `t ʔ uː l u / t q uː l u` |
-| ✎ | הם | يقولو | יִקוּלוּ | `j ʔ uː l u / i ʔ uː l u / j q uː l u / j i ʔ uː l u` |
-
-## היה · كان · يكون (שיעור 5) — 2 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اكون | אַכּוּן | `ʔ a k uː n` |
-| ✓ | אתה | تكون | תְכּוּן | `t k uː n` |
-| ✓ | את | تكوني | תְכּוּנִי | `t k uː n i` |
-| ✓ | הוא | يكون | יִכּוּן | `j k uː n / i k uː n / j i k uː n` |
-| ✓ | היא | تكون | תְכּוּן | `t k uː n` |
-| ✓ | אנחנו | نكون | נְכּוּן | `n k uː n` |
-| ✎ | אתם | تكونو | תְכּוּנוּ | `t k uː n u` |
-| ✎ | הם | يكونو | יִכּוּנוּ | `j k uː n u / i k uː n u / j i k uː n u` |
-
-## נישק · باس · يبوس (שיעור 6) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | ابوس | אַבּוּס | `ʔ a b uː s` |
-| ✓ | אתה | تبوس | תְבּוּס | `t b uː s` |
-| ✎ | את | تبوسي | תְבּוּסִי | `t b uː s i` |
-| ✓ | הוא | يبوس | יִבּוּס | `j b uː s / i b uː s / j i b uː s` |
-| ✓ | היא | تبوس | תְבּוּס | `t b uː s` |
-| ✎ | אנחנו | نبوس | נְבּוּס | `n b uː s` |
-| ✎ | אתם | تبوسو | תְבּוּסוּ | `t b uː s u` |
-| ✎ | הם | يبوسو | יִבּוּסוּ | `j b uː s u / i b uː s u / j i b uː s u` |
-
-## נהג · ساق · يسوق (שיעור 6) — 3 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اسوق | אַסוּק | `ʔ a s uː ʔ / ʔ a s uː q` |
-| ✓ | אתה | تسوق | תְסוּק | `t s uː ʔ / t s uː q` |
-| ✓ | את | تسوقي | תְסוּקִי | `t s uː ʔ i / t s uː q i` |
-| ✓ | הוא | يسوق | יִסוּק | `j s uː ʔ / j s uː q / i s uː ʔ / j i s uː ʔ` |
-| ✓ | היא | تسوق | תְסוּק | `t s uː ʔ / t s uː q` |
-| ✎ | אנחנו | نسوق | נְסוּק | `n s uː ʔ / n s uː q` |
-| ✎ | אתם | تسوقو | תְסוּקוּ | `t s uː ʔ u / t s uː q u` |
-| ✎ | הם | يسوقو | יִסוּקוּ | `j s uː ʔ u / j s uː q u / i s uː ʔ u / j i s uː ʔ u` |
-
-## נכנס ועבר · فات · يفوت (שיעור 6) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | افوت | אַפוּת | `ʔ a f uː t` |
-| ✓ | אתה | تفوت | תְפוּת | `t f uː t` |
-| ✎ | את | تفوتي | תְפוּתִי | `t f uː t i` |
-| ✓ | הוא | يفوت | יִפוּת | `j f uː t / i f uː t / j i f uː t` |
-| ✓ | היא | تفوت | תְפוּת | `t f uː t` |
-| ✎ | אנחנו | نفوت | נְפוּת | `n f uː t` |
-| ✎ | אתם | تفوتو | תְפוּתוּ | `t f uː t u` |
-| ✎ | הם | يفوتو | יִפוּתוּ | `j f uː t u / i f uː t u / j i f uː t u` |
-
-## לקח · اخد · ياخد (שיעור 6) — 2 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | آخد | אַאחֹ'ד | `ʔ aː x u d / ʔ aː x i d` |
-| ✓ | אתה | تاخد | תֹאחֵ'ד | `t oː x i d / t aː x u d` |
-| ✓ | את | تاخدي | תֹאחְ'דִי | `t oː x d i / t aː x d i / t oː x u d i` |
-| ✓ | הוא | ياخد | יֹאחֵ'ד | `j oː x i d / j aː x u d / j oː x u d` |
-| ✓ | היא | تاخد | תֹאחֵ'ד | `t oː x i d / t aː x u d` |
-| ✎ | אנחנו | ناخد | נֹאחֵ'ד | `n oː x i d / n aː x u d` |
-| ✎ | אתם | تاخدو | תֹאחְ'דוּ | `t oː x i d u / t aː x u d u / t oː x d u / t aː x d u / t oː x u d u` |
-| ✓ | הם | ياخدو | יֹאחְ'דוּ | `j oː x d u / j aː x d u / j oː x u d u` |
-
-## הבין · فهم · يفهم (שיעור 8) — 2 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | افهم | אַפְהַם | `ʔ a f h a m` |
-| ✓ | אתה | تفهم | תִפְהַם | `t i f h a m` |
-| ✓ | את | تفهمي | תִפְהַמִי | `t i f h a m i` |
-| ✓ | הוא | يفهم | יִפְהַם | `j i f h a m` |
-| ✓ | היא | تفهم | תִפְהַם | `t i f h a m` |
-| ✎ | אנחנו | نفهم | נִפְהַם | `n i f h a m` |
-| ✎ | אתם | تفهمو | תִפְהַמוּ | `t i f h a m u` |
-| ✓ | הם | يفهمو | יִפְהַמוּ | `j i f h a m u` |
-
-## חזר · رجع · يرجع (שיעור 8) — 1 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | ارجع | אַרְגַ'ע | `ʔ a r dʒ a ʕ` |
-| ✓ | אתה | ترجع | תִרְגַ'ע | `t i r dʒ a ʕ` |
-| ✓ | את | ترجعي | תִרְגַ'עִי | `t i r dʒ a ʕ i` |
-| ✓ | הוא | يرجع | יִרְגַ'ע | `j i r dʒ a ʕ` |
-| ✓ | היא | ترجع | תִרְגַ'ע | `t i r dʒ a ʕ` |
-| ✎ | אנחנו | نرجع | נִרְגַ'ע | `n i r dʒ a ʕ` |
-| ✓ | אתם | ترجعو | תִרְגַ'עוּ | `t i r dʒ a ʕ u` |
-| ✓ | הם | يرجعو | יִרְגַ'עוּ | `j i r dʒ a ʕ u` |
-
-## הודה · شكر · يشكر (שיעור 9) — 6 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✎ | אני | اشكر | אַשְכֹּר | `ʔ a ʃ k u r` |
-| ✎ | אתה | تشكر | תֻשְכֹּר | `t u ʃ k u r` |
-| ✎ | את | تشكري | תֻשְכֹּרִי | `t u ʃ k u r i` |
-| ✓ | הוא | يشكر | יֻשְכֹּר | `j u ʃ k u r` |
-| ✎ | היא | تشكر | תֻשְכֹּר | `t u ʃ k u r` |
-| ✓ | אנחנו | نشكر | נֻשְכֹּר | `n u ʃ k u r` |
-| ✎ | אתם | تشكرو | תֻשְכֹּרוּ | `t u ʃ k u r u` |
-| ✎ | הם | يشكرو | יֻשְכֹּרוּ | `j u ʃ k u r u` |
-
-## ירד · نزل · ينزل (שיעור 10) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✎ | אני | انزل | אַנְזֵל | `ʔ a n z i l / ʔ a n z a l` |
-| ✓ | אתה | تنزل | תִנְזֵל | `t i n z i l / t i n z a l` |
-| ✎ | את | تنزلي | תִנְזֵלִי | `t i n z i l i / t i n z a l i` |
-| ✓ | הוא | ينزل | יִנְזֵל | `j i n z i l / j i n z a l` |
-| ✓ | היא | تنزل | תִנְזֵל | `t i n z i l / t i n z a l` |
-| ✎ | אנחנו | ننزل | נִנְזֵל | `n i n z i l / n i n z a l` |
-| ✓ | אתם | تنزلو | תִנְזְלוּ | `t i n z l u / t i n z i l u / t i n z a l u` |
-| ✎ | הם | ينزلو | יִנְזְלוּ | `j i n z i l u / j i n z a l u / j i n z l u` |
-
-## הגיע · وصل · يوصل (שיעור 10) — 1 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اوصل | אַוְצַל | `ʔ a w sˤ a l / ʔ oː sˤ a l` |
-| ✓ | אתה | توصل | תוֹצַל | `t oː sˤ a l` |
-| ✓ | את | توصلي | תוֹצַלִי | `t oː sˤ a l i` |
-| ✓ | הוא | يوصل | יוֹצַל | `j oː sˤ a l` |
-| ✓ | היא | توصل | תוֹצַל | `t oː sˤ a l` |
-| ✓ | אנחנו | نوصل | נוֹצַל | `n oː sˤ a l` |
-| ✎ | אתם | توصلو | תוֹצַלוּ | `t oː sˤ a l u` |
-| ✓ | הם | يوصلو | יוֹצַלוּ | `j oː sˤ a l u` |
-
-## צחק וחייך · ضحك · يضحك (שיעור 10) — 1 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✓ | אני | اضحك | אַדְֿחַכּ | `ʔ a dˤ ħ a k` |
-| ✓ | אתה | تضحك | תִדְֿחַכּ | `t i dˤ ħ a k` |
-| ✓ | את | تضحكي | תִדְֿחַכִּי | `t i dˤ ħ a k i` |
-| ✓ | הוא | يضحك | יִדְֿחַכּ | `j i dˤ ħ a k` |
-| ✓ | היא | تضحك | תִדְֿחַכּ | `t i dˤ ħ a k` |
-| ✓ | אנחנו | نضحك | נִדְֿחַכּ | `n i dˤ ħ a k` |
-| ✓ | אתם | تضحكو | תִדְֿחַכּוּ | `t i dˤ ħ a k u` |
-| ✎ | הם | يضحكو | יִדְֿחַכּוּ | `j i dˤ ħ a k u` |
-
-## לבש · لبس · يلبس (שיעור 10) — 4 לבדיקה
-
-| | גוף | ערבית | תעתיק | הגייה |
-|---|---|---|---|---|
-| ✎ | אני | البس | אַלְבַּס | `ʔ a l b a s` |
-| ✓ | אתה | تلبس | תִלְבַּס | `t i l b a s` |
-| ✓ | את | تلبسي | תִלְבַּסִי | `t i l b a s i` |
-| ✓ | הוא | يلبس | יִלְבַּס | `j i l b a s` |
-| ✓ | היא | تلبس | תִלְבַּס | `t i l b a s` |
-| ✎ | אנחנו | نلبس | נִלְבַּס | `n i l b a s` |
-| ✎ | אתם | تلبسو | תִלְבַּסוּ | `t i l b a s u` |
-| ✎ | הם | يلبسو | יִלְבַּסוּ | `j i l b a s u` |