Update README with current algorithm, tech stack, and architecture

README.md

@@ -6,118 +6,110 @@ colorTo: purple
 sdk: docker
 pinned: false
 ---
-# 🎤 Speech Analysis MVP - 'Sh' Sound Trainer
+# SpeechKid API - Hebrew 'Sh' Sound Pronunciation Trainer
 
-מערכת לניתוח וזיהוי הגייה של צליל ה-"ש" בעברית, עם יכולת אבחון שגיאות ספציפיות.
+AI-powered pronunciation trainer for children learning the Hebrew 'Sh' (ש) sound. Uses Wav2Vec2 forced alignment + acoustic physics to grade pronunciation as CORRECT or INCORRECT in real-time. No reference audio needed — pure AI inference.
 
-## ✨ תכונות
+## Technology Stack
 
-- **ניתוח DTW**: השוואה מבוססת Dynamic Time Warping על תכונות MFCC
-- **זיהוי פונמות**: בידוד אוטומטי של צליל ה-"ש" מתוך המילה
-- **אבחון שגיאות**: זיהוי סוג השגיאה (החלפה ב-ס', השמטה, עיוות)
-- **ממשק אינטראקטיבי**: הקלטה בזמן אמת עם משוב מיידי
+| Layer | Technology |
+|-------|-----------|
+| **AI Model** | Wav2Vec2 (`imvladikon/wav2vec2-large-xlsr-53-hebrew`) — CTC forced alignment |
+| **Audio Processing** | librosa, torchaudio, scipy — spectral analysis, bandpass filtering |
+| **Backend** | FastAPI + Uvicorn |
+| **Deployment** | Hugging Face Spaces (Docker SDK), PyTorch CPU-only |
+| **Clinical Engine** | OpenAI GPT-4o Structured Outputs — diagnostic report generation |
+| **Frontend** | Expo React Native app (separate repo) |
 
-## 📁 מבנה הפרויקט
+## How the Algorithm Works
+
+### Processing Pipeline
 
 ```
-speechai/
-├── audio_data/           # קבצי אודיו לאימון (ref_* = תקין, err_* = שגוי)
-├── calibrate.py          # כיול ובדיקת המודל
-├── score_engine.py       # מנוע הניקוד והאבחון
-├── simulate.py           # ממשק אינטראקטיבי להקלטה
-├── requirements.txt      # תלויות Python
-└── README.md
+Recording → Silence Trimming → Wav2Vec2 Forced Alignment → ש Segment Extraction
+         → Bandpass Filter (3-8kHz) → Spectral Centroid → Binary Diagnosis
 ```
 
-## 🚀 התקנה
+1. **Silence Trimming** — Removes leading silence (`librosa.effects.trim`, top_db=25) so the AI model sees speech immediately. Mobile recordings often have 1-2s of dead air.
 
-### 1. שכפול הפרויקט
+2. **Wav2Vec2 Forced Alignment** — CTC forced alignment (`torchaudio.functional.forced_align`) maps each Hebrew character to a time span + confidence score. The model identifies exactly where the ש sound starts.
 
-```bash
-git clone https://github.com/YOUR_USERNAME/speechai.git
-cd speechai
-```
+3. **Segment Extraction** — Extracts 120ms **forward** from the Wav2Vec2 onset of ש. Forward-only extraction avoids capturing pre-speech silence. Falls back to energy-peak scanning if alignment fails.
 
-### 2. יצירת סביבה וירטואלית
+4. **Bandpass Filter** — 4th-order Butterworth bandpass (3-8kHz) isolates the fricative frequency range.
 
-```bash
-# Windows
-python -m venv venv
-venv\Scripts\activate
+5. **Spectral Centroid** — Computes the frequency center of gravity on the bandpassed audio. This is device-invariant — doesn't change with recording volume or distance.
 
-# Linux/Mac
-python3 -m venv venv
-source venv/bin/activate
-```
+6. **Binary Diagnosis** — Two gates, both must pass:
 
-### 3. התקנת תלויות
+### Diagnosis Gates
 
-```bash
-pip install -r requirements.txt
-```
+| Gate | Threshold | What it catches |
+|------|-----------|-----------------|
+| **AI Score** | Wav2Vec2 confidence ≥ 0.70 | Lisps, substitutions, wet CH, omission |
+| **Centroid** | 2700–5500 Hz | Too low = wet/lateral distortion; too high = S substitution |
 
-## 📖 שימוש
+Result: **CORRECT** (score 100) or **INCORRECT** (score 0).
 
-### כיול המערכת
+### Key Techniques
 
-בדיקת הפרדה בין הקלטות תקינות לשגויות:
+- **CTC Forced Alignment**: Aligns Hebrew characters to audio frames using Connectionist Temporal Classification, providing per-character timestamps and confidence scores
+- **Spectral Centroid Analysis**: Frequency center of gravity — robust across devices, volumes, and recording distances (unlike energy-based measures)
+- **Forward-Only Extraction**: Always extract audio forward from the detected onset, never backward into silence
+- **Leading Silence Trimming**: Prevents alignment failure caused by long pre-speech silence on mobile recordings
+- **Model Warmup**: Pre-loads Wav2Vec2 at startup via FastAPI lifespan to eliminate cold-start latency (~10s warmup vs ~2min on first request)
 
-```bash
-python calibrate.py
-```
+## API Endpoints
 
-### ניקוד הקלטה בודדת
+### `POST /evaluate`
+Score a pronunciation recording.
+- **file**: Audio file (WAV, M4A, AAC, WebM, etc.)
+- **word**: Target word key (shalom, shemesh, shir, shuk, geshem, shshshsh, shaon, shulchan)
+- **Returns**: `{ score, status, diagnosis, feedback, details, evidence }`
 
-```bash
-python score_engine.py "path/to/recording.wav" shalom --pretty
-```
+### `POST /diagnose_profile`
+Generate a clinical diagnostic report via GPT-4o.
+- **Body**: Intake questionnaire (child age, error patterns, history)
+- **Returns**: Clinical hypothesis, intervention recommendation, exercises, app roadmap
 
-פלט לדוגמה:
-```json
-{
-  "score": 85,
-  "status": "PASS",
-  "error_type": "none",
-  "feedback": "Great job! Your 'Sh' sound is clear and accurate!"
-}
-```
+## Supported Words
 
-### סימולציה אינטראקטיבית
+שלום (shalom), שמש (shemesh), שיר (shir), שוק (shuk), גשם (geshem), שששש (shshshsh), שעון (shaon), שולחן (shulchan)
 
-הקלטה בזמן אמת עם משוב:
+## Project Structure
 
-```bash
-python simulate.py
+```
+speechkid-api/
+├── score_engine.py       # Main scoring pipeline — trimming, extraction, diagnosis
+├── phoneme_extractor.py  # Wav2Vec2 forced alignment & ש isolation
+├── main.py               # FastAPI backend (HF Spaces deployment)
+├── simulate_remote.py    # Terminal simulator — records mic, calls HF API
+├── simulate.py           # Local terminal simulator — scores without API
+├── calibrate.py          # Batch calibration tool
+├── Dockerfile            # HF Spaces Docker deployment
+├── requirements.txt      # Python dependencies
+└── CLAUDE.md             # AI assistant context file
 ```
 
-## 🔧 סוגי שגיאות מזוהות
-
-| סוג שגיאה | תיאור | משוב |
-|-----------|--------|------|
-| `s_substitution` | החלפת "ש" ב-"ס" | "הזז את הלשון אחורה" |
-| `lateral_sh` | "ש" רטובה/צדדית | "שמור את הלשון במרכז" |
-| `omission` | השמטת הצליל | "הארך את הצליל" |
-| `distortion` | עיוות כללי | "עגל את השפתיים" |
-
-## 📊 פורמט קבצי האודיו
+## Quick Start
 
-שם הקובץ: `type_word_variation.wav`
+```bash
+# Install
+pip install -r requirements.txt
 
-- `type`: `ref` (תקין) או `err` (שגוי)
-- `word`: המילה (למשל: shalom, shemesh)
-- `variation`: וריאציה (normal, fast, slow, sub_s, wet_ch)
+# Test via terminal (calls HF Spaces API)
+python simulate_remote.py
 
-דוגמאות:
-- `ref_shalom_normal.wav` - הגייה תקינה של "שלום"
-- `err_shalom_sub_s.wav` - החלפת ש' ב-ס' במילה "שלום"
+# Score a single file locally
+python score_engine.py "recording.wav" shalom --pretty
+```
 
-## 🛠️ דרישות מערכת
+## Deployment
 
-- Python 3.9+
-- מיקרופון (לסימולציה אינטראקטיבית)
-- Windows / Linux / macOS
+Deployed on **Hugging Face Spaces** (Docker SDK) at:
+`https://yoavzamir-speechkid-api.hf.space`
 
-## 📝 רישיון
+## License
 
 MIT License