feat: Added voice journal recording with Cohere ASR integration

COHERE_ASR_SETUP.md

@@ -0,0 +1,127 @@
+# Cohere Transcribe ASR — Setup Guide
+
+## Overview
+
+The voice journal pipeline uses **CohereLabs/cohere-transcribe-03-2026**, a
+2 B-parameter conformer encoder + lightweight transformer decoder trained
+from scratch for ASR. It is gated on the Hugging Face Hub (you must
+accept the model terms once with your account) and supports 14
+languages:
+
+- **European:** English, French, German, Italian, Spanish, Portuguese,
+  Greek, Dutch, Polish
+- **APAC:** Chinese (Mandarin), Japanese, Korean, Vietnamese
+- **MENA:** Arabic
+
+The model is Apache 2.0 licensed and is integrated into the journal
+pipeline so players can speak during a game instead of typing.
+
+## Why this configuration
+
+1. **Sponsor visibility** — Cohere Labs is a hackathon sponsor.
+2. **State-of-the-art accuracy** — 5.42 mean WER on the Open ASR
+   Leaderboard (5.x–10.x WER across real-world domains) and 1.25 WER on
+   LibriSpeech clean.
+3. **Production runtime** — supports 🤗 Transformers (offline),
+   vLLM, mlx-audio, Rust, and a WebGPU browser demo.
+4. **Lazy loading** — the model is downloaded on first use, never at
+   app startup, so demo boot is unaffected.
+
+## Installation
+
+### 1. Accept the model terms
+
+Visit <https://huggingface.co/CohereLabs/cohere-transcribe-03-2026>,
+click **Agree and access repository** with the account you plan to
+authenticate as.
+
+### 2. Install dependencies
+
+```bash
+pip install 'transformers>=5.4.0' torch huggingface_hub \
+            soundfile librosa sentencepiece protobuf
+```
+
+(These are added to `requirements.txt` for the demo; `transformers` is
+already present.)
+
+### 3. Provide an HF token
+
+Set a token in the environment so the gated model can be downloaded:
+
+```bash
+export HF_TOKEN=hf_xxx...    # Linux/macOS
+$env:HF_TOKEN="hf_xxx..."     # PowerShell
+```
+
+On Hugging Face Spaces, create a `HF_TOKEN` secret (same name as
+`huggingface` in `modal_serve.py`/`modal_train.py`).
+
+## How the pipeline uses it
+
+```text
+Gradio microphone / upload
+   ↓
+app.py: record_journal(audio_path, language)
+   ↓
+app/services/asr.py: transcribe(audio_path, language)
+   ↓
+CohereAsrForConditionalGeneration  ←  CohereLabs/cohere-transcribe-03-2026
+   ↓
+transcript
+   ↓
+app/services/journal.py: create_journal_entry(...)
+   ↓
+app/logs/journals.jsonl
+```
+
+Each journal entry now carries:
+
+- `transcript_source` — `"typed" | "asr" | "hybrid"`
+- `audio_ref` — path of the recorded audio clip
+- `asr` — `{ model, language, status, error }`
+
+The `journal_recorded` event log also includes `transcript_source`,
+`asr_status`, and `asr_model` for full traceability.
+
+## Skipping the model in tests
+
+To run the demo without downloading the model, set either of:
+
+```bash
+CITYQUEST_SKIP_MODEL=1
+CITYQUEST_FAST_TEST=1
+```
+
+When set, `app.services.asr.transcribe()` returns
+`status="skipped"` with an empty transcript. The journal pipeline
+silently falls back to typed input.
+
+## Verification
+
+```bash
+$env:CITYQUEST_FAST_TEST="1"
+.\.venv\Scripts\python.exe test_asr.py
+.\.venv\Scripts\python.exe test_end_to_end.py
+```
+
+Expected: 30/30 ASR tests + 86/86 end-to-end tests pass in skip-mode.
+
+## Limitations (per the model card)
+
+1. **Single language per call** — pick the right language code; the
+   model does not auto-detect or handle code-switching well.
+2. **No diarization or timestamps** — only plain text is returned.
+3. **Eager on silence** — prepend a VAD/silence gate if the recording
+   has noisy backgrounds; otherwise the model may hallucinate.
+
+## File map
+
+| File | Purpose |
+| --- | --- |
+| `app/services/asr.py` | Lazy-loaded Cohere Transcribe wrapper. |
+| `app/services/journal.py` | `transcribe_journal()` and `create_journal_entry()` now accept ASR metadata. |
+| `app/schemas/journal_schema.json` | Optional `transcript_source`, `audio_ref`, `asr` fields. |
+| `app.py` | Gradio audio component + `record_journal()` voice path. |
+| `test_asr.py` | Skip-mode tests for the ASR pipeline. |
+| `requirements.txt` | Optional ASR runtime deps. |

README.md

@@ -28,7 +28,20 @@ An AI-powered platform that generates complete, playable real-world games — ru
 1. Select a game type, city, and preferences
 2. AI generates rules, tasks, and hints
 3. Play in the real world, track progress in the app
-4. Receive an AI-generated story summary of the outcome
+4. Record voice journals during play (auto-transcribed with [Cohere Transcribe](https://huggingface.co/CohereLabs/cohere-transcribe-03-2026))
+5. Receive an AI-generated story summary of the outcome
+
+## AI Models
+
+| Stage | Model | Notes |
+| --- | --- | --- |
+| Game generation | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` via llama.cpp | Retrieval-grounded, validation + repair enforced |
+| Voice journal ASR | `CohereLabs/cohere-transcribe-03-2026` via 🤗 Transformers | 14 languages, lazy-loaded; typed-input fallback |
+| Recap (optional) | `openbmb/MiniCPM5-1B-GGUF` | Currently using deterministic template recap for reliability |
+| Poster (optional) | `black-forest-labs/FLUX.1-schnell` | Skipped under `CITYQUEST_SKIP_MODEL` |
+
+Set `CITYQUEST_FAST_TEST=1` to run the entire pipeline without
+downloading any model weights.
 
 ## Team
 

app.py

@@ -215,22 +215,77 @@ def use_hint(session_id: str, task_id: str, team_id: str = "team-a"):
 
 def record_journal(
     session_id: str,
-    transcript: str,
+    transcript: str = "",
     task_id: str = "",
     location_note: str = "",
     team_id: str = "team-a",
+    audio_path: str = "",
+    language: str = "en",
 ):
-    """Record a text journal entry, summarize it, and return the result."""
+    """Record a journal entry, summarize it, and return the result.
+
+    Two input paths are supported:
+
+    * **Voice path** — pass ``audio_path`` (e.g. a path returned by
+      ``gr.Audio(type="filepath")``). The audio is transcribed with the
+      Cohere ASR service (``CohereLabs/cohere-transcribe-03-2026``) and
+      the transcript is stored with ASR metadata.
+    * **Typed path** — pass ``transcript`` directly. The user can also
+      edit an ASR transcript in the UI before submitting; if both
+      ``audio_path`` and ``transcript`` are present, the typed
+      transcript wins and is treated as a manual correction
+      (``transcript_source == "hybrid"``).
+    """
     if session_id not in SESSION_STORE:
         return "[!] Unknown session"
 
-    # Build full journal entry
+    asr_metadata: dict | None = None
+    audio_ref: str | None = None
+    transcript_source = "typed"
+
+    # ── 1. Voice path — transcribe audio if provided ───────────────────
+    if audio_path:
+        audio_ref = audio_path
+        try:
+            from app.services.asr import transcribe as _asr_transcribe
+
+            asr_result = _asr_transcribe(audio_path, language=language)
+            asr_metadata = {
+                "model": asr_result.get("model"),
+                "language": asr_result.get("language"),
+                "status": asr_result.get("status"),
+                "error": asr_result.get("error"),
+            }
+            asr_text = (asr_result.get("transcript") or "").strip()
+            if asr_text and not transcript.strip():
+                transcript = asr_text
+                transcript_source = "asr"
+            elif asr_text and transcript.strip() and asr_text != transcript.strip():
+                transcript_source = "hybrid"
+        except Exception as exc:
+            print(f"[app] ASR transcription failed: {type(exc).__name__}: {exc}")
+            asr_metadata = {
+                "model": None,
+                "language": language,
+                "status": "error",
+                "error": f"{type(exc).__name__}: {exc}",
+            }
+
+    if not transcript or not transcript.strip():
+        return (
+            "⚠️ No transcript available — record audio or type a note first."
+        )
+
+    # ── 2. Build journal entry ────────────────────────────────────────
     entry = create_journal_entry(
         transcript=transcript,
         session_id=session_id,
         team_id=team_id,
         task_id=task_id or None,
         location_note=location_note,
+        audio_ref=audio_ref,
+        asr_metadata=asr_metadata,
+        transcript_source=transcript_source,
     )
 
     # Summarize
@@ -248,16 +303,28 @@ def record_journal(
         "mood": entry["mood"],
         "story_value": summary["story_value"],
         "summary": summary["moment_summary"],
+        "transcript_source": transcript_source,
+        "asr_status": asr_metadata.get("status") if asr_metadata else None,
+        "asr_model": asr_metadata.get("model") if asr_metadata else None,
     }, team_id=team_id)
     SESSION_STORE[session_id]["events"].append(ev)
     SESSION_STORE[session_id]["journals"].append(entry)
 
     # Build display text
+    source_label = {
+        "asr": "🎙️ (transcribed)",
+        "hybrid": "🎙️✏️ (transcribed, edited)",
+        "typed": "⌨️ (typed)",
+    }.get(transcript_source, transcript_source)
+    asr_line = ""
+    if asr_metadata and asr_metadata.get("status") != "ok":
+        asr_line = f"- ASR status: **{asr_metadata.get('status')}** — {asr_metadata.get('error') or ''}\n"
     display = (
-        f"🎙️ **Journal recorded!**\n"
+        f"🎙️ **Journal recorded!** {source_label}\n"
         f"- Mood: *{entry['mood']}*\n"
         f"- Story value: **{summary['story_value']}**\n"
         f"- Tags: {', '.join(summary['tags'])}\n"
+        f"{asr_line}"
         f"- Summary: {summary['moment_summary']}"
     )
     return display
@@ -1008,13 +1075,24 @@ with gr.Blocks(title="CityQuest-AI") as demo:
                 task_feedback = gr.Markdown(value="")
 
                 gr.HTML('<div class="section-label" style="margin-top:20px;">Voice Journal</div>')
+                journal_audio = gr.Audio(
+                    label="🎙️ Record voice (auto-transcribed via Cohere ASR)",
+                    sources=["microphone", "upload"],
+                    type="filepath",
+                )
                 journal_transcript = gr.Textbox(
-                    label="What happened? How do you feel?", lines=3,
+                    label="Transcript (edit the ASR result or type your own)",
+                    lines=3,
                     placeholder="We just found the mural near the canal — it was incredible!",
                 )
                 with gr.Row():
                     journal_task_id  = gr.Textbox(label="Task ID (opt.)", placeholder="t1")
                     journal_location = gr.Textbox(label="Location note", placeholder="Rue de Rivoli")
+                    journal_language = gr.Dropdown(
+                        label="Language", value="en",
+                        choices=["en", "fr", "de", "it", "es", "pt", "el", "nl", "pl",
+                                 "zh", "ja", "ko", "vi", "ar"],
+                    )
                 journal_btn    = gr.Button("🎙️ Record Journal", variant="secondary")
                 journal_output = gr.Markdown(value="")
 
@@ -1226,7 +1304,8 @@ with gr.Blocks(title="CityQuest-AI") as demo:
 
     journal_btn.click(
         fn=record_journal,
-        inputs=[current_session, journal_transcript, journal_task_id, journal_location, current_team],
+        inputs=[current_session, journal_transcript, journal_task_id, journal_location,
+                current_team, journal_audio, journal_language],
         outputs=[journal_output],
     )
     photo_btn.click(

app/data/sessions_store.json

@@ -1 +1 @@
-{"codes": {"75ZKFE": "9fcb0953-4e36-4485-9bbe-fad577de31fa", "JWR5RV": "6b1af473-b00b-44ae-bffc-7b8e93616767"}, "sessions": {"9fcb0953-4e36-4485-9bbe-fad577de31fa": {"config": {"game_type": "scavenger_hunt", "city": "Paris", "area": "Le Marais", "location_type": "mixed", "duration_minutes": 60, "num_players": 2, "difficulty": "easy", "age_group": "adults", "energy_level": "low", "photo_enabled": true}, "game": {"game_id": "mock-8506e14a", "title": "Scavenger_Hunt in Le Marais", "theme": "easy adventure", "setup": {"city": "Paris", "area": "Le Marais", "meeting_point": "Main entrance of Le Marais", "duration_minutes": 60, "num_players": 2}, "rules": ["Complete as many tasks as possible within 60 minutes", "Take photos or notes as proof of completion", "Stay within the designated area at all times", "No entering private buildings or restricted areas", "This game is suitable for adults"], "tasks": [{"task_id": "t1", "title": "Task 1: Explore the main square", "description": "Find and document something interesting in the main square", "location_hint": "Navigate to the main square and look for distinctive features", "points": 15, "time_limit_minutes": 8, "proof_type": "photo", "hint": "Look for signs or landmarks in the main square", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t2", "title": "Task 2: Explore the city center", "description": "Find and document something interesting in the city center", "location_hint": "Navigate to the city center and look for distinctive features", "points": 20, "time_limit_minutes": 10, "proof_type": "observation", "hint": "Look for signs or landmarks in the city center", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t3", "title": "Task 3: Explore the park area", "description": "Find and document something interesting in the park area", "location_hint": "Navigate to the park area and look for distinctive features", "points": 25, "time_limit_minutes": 12, "proof_type": "text", "hint": "Look for signs or landmarks in the park area", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t4", "title": "Task 4: Explore the landmark district", "description": "Find and document something interesting in the landmark district", "location_hint": "Navigate to the landmark district and look for distinctive features", "points": 30, "time_limit_minutes": 14, "proof_type": "photo", "hint": "Look for signs or landmarks in the landmark district", "safety_note": "Stay on public paths and avoid restricted areas"}], "global_hints": ["Explore systematically from the meeting point outward", "Ask locals for directions if needed", "Time management is key - don't spend too long on any single task"], "score_rules": ["Each task completed: full points", "Early completion: +1 bonus point per minute under limit", "Hints used: -5 points per hint", "Late arrival at meeting point: -10 points per minute"], "tie_breaker": "Winner is the player with the most points when time expires. Ties broken by earliest completion time.", "safety": {"allowed_zone": "Le Marais", "forbidden_behaviors": ["Entering buildings without permission", "Crossing busy streets recklessly", "Approaching strangers", "Leaving the designated area"], "adult_supervision": false, "stop_conditions": ["If a player feels unsafe, the game stops immediately", "If weather becomes severe, relocate to shelter", "If anyone is injured, call emergency services"]}, "story_seed": {"tone": "playful", "motifs": ["exploration", "discovery", "teamwork"], "recap_style": "episode_recap"}}, "adventure_code": "75ZKFE", "teams": ["team-a", "team-b"], "players": [{"name": "Player 1", "team_id": "team-a"}, {"name": "play 2", "team_id": "team-b"}, {"name": "hola", "team_id": "team-b"}], "photos": [{"photo_id": "photo-71c44ee8", "photo_name": "", "caption": "", "task_id": "t1"}]}, "6b1af473-b00b-44ae-bffc-7b8e93616767": {"config": {"game_type": "scavenger_hunt", "city": "Paris", "area": "Le Marais", "location_type": "mixed", "duration_minutes": 60, "num_players": 2, "difficulty": "easy", "age_group": "adults", "energy_level": "low", "photo_enabled": true}, "game": {"game_id": "mock-6d6ab9cf", "title": "Scavenger_Hunt in Le Marais", "theme": "easy adventure", "setup": {"city": "Paris", "area": "Le Marais", "meeting_point": "Main entrance of Le Marais", "duration_minutes": 60, "num_players": 2}, "rules": ["Complete as many tasks as possible within 60 minutes", "Take photos or notes as proof of completion", "Stay within the designated area at all times", "No entering private buildings or restricted areas", "This game is suitable for adults"], "tasks": [{"task_id": "t1", "title": "Task 1: Explore the main square", "description": "Find and document something interesting in the main square", "location_hint": "Navigate to the main square and look for distinctive features", "points": 15, "time_limit_minutes": 8, "proof_type": "photo", "hint": "Look for signs or landmarks in the main square", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t2", "title": "Task 2: Explore the city center", "description": "Find and document something interesting in the city center", "location_hint": "Navigate to the city center and look for distinctive features", "points": 20, "time_limit_minutes": 10, "proof_type": "observation", "hint": "Look for signs or landmarks in the city center", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t3", "title": "Task 3: Explore the park area", "description": "Find and document something interesting in the park area", "location_hint": "Navigate to the park area and look for distinctive features", "points": 25, "time_limit_minutes": 12, "proof_type": "text", "hint": "Look for signs or landmarks in the park area", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t4", "title": "Task 4: Explore the landmark district", "description": "Find and document something interesting in the landmark district", "location_hint": "Navigate to the landmark district and look for distinctive features", "points": 30, "time_limit_minutes": 14, "proof_type": "photo", "hint": "Look for signs or landmarks in the landmark district", "safety_note": "Stay on public paths and avoid restricted areas"}], "global_hints": ["Explore systematically from the meeting point outward", "Ask locals for directions if needed", "Time management is key - don't spend too long on any single task"], "score_rules": ["Each task completed: full points", "Early completion: +1 bonus point per minute under limit", "Hints used: -5 points per hint", "Late arrival at meeting point: -10 points per minute"], "tie_breaker": "Winner is the player with the most points when time expires. Ties broken by earliest completion time.", "safety": {"allowed_zone": "Le Marais", "forbidden_behaviors": ["Entering buildings without permission", "Crossing busy streets recklessly", "Approaching strangers", "Leaving the designated area"], "adult_supervision": false, "stop_conditions": ["If a player feels unsafe, the game stops immediately", "If weather becomes severe, relocate to shelter", "If anyone is injured, call emergency services"]}, "story_seed": {"tone": "playful", "motifs": ["exploration", "discovery", "teamwork"], "recap_style": "episode_recap"}}, "adventure_code": "JWR5RV", "teams": ["team-a", "team-b"], "players": [{"name": "Player 1", "team_id": "team-a"}], "photos": []}}}
+{"codes": {"75ZKFE": "9fcb0953-4e36-4485-9bbe-fad577de31fa", "JWR5RV": "6b1af473-b00b-44ae-bffc-7b8e93616767", "NKPZKT": "32e1bbe3-50a1-4e43-a7c2-8ecf3f781550", "NXWHQK": "4b03fbfc-4326-4325-8975-e4216c44e03e"}, "sessions": {"9fcb0953-4e36-4485-9bbe-fad577de31fa": {"config": {"game_type": "scavenger_hunt", "city": "Paris", "area": "Le Marais", "location_type": "mixed", "duration_minutes": 60, "num_players": 2, "difficulty": "easy", "age_group": "adults", "energy_level": "low", "photo_enabled": true}, "game": {"game_id": "mock-8506e14a", "title": "Scavenger_Hunt in Le Marais", "theme": "easy adventure", "setup": {"city": "Paris", "area": "Le Marais", "meeting_point": "Main entrance of Le Marais", "duration_minutes": 60, "num_players": 2}, "rules": ["Complete as many tasks as possible within 60 minutes", "Take photos or notes as proof of completion", "Stay within the designated area at all times", "No entering private buildings or restricted areas", "This game is suitable for adults"], "tasks": [{"task_id": "t1", "title": "Task 1: Explore the main square", "description": "Find and document something interesting in the main square", "location_hint": "Navigate to the main square and look for distinctive features", "points": 15, "time_limit_minutes": 8, "proof_type": "photo", "hint": "Look for signs or landmarks in the main square", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t2", "title": "Task 2: Explore the city center", "description": "Find and document something interesting in the city center", "location_hint": "Navigate to the city center and look for distinctive features", "points": 20, "time_limit_minutes": 10, "proof_type": "observation", "hint": "Look for signs or landmarks in the city center", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t3", "title": "Task 3: Explore the park area", "description": "Find and document something interesting in the park area", "location_hint": "Navigate to the park area and look for distinctive features", "points": 25, "time_limit_minutes": 12, "proof_type": "text", "hint": "Look for signs or landmarks in the park area", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t4", "title": "Task 4: Explore the landmark district", "description": "Find and document something interesting in the landmark district", "location_hint": "Navigate to the landmark district and look for distinctive features", "points": 30, "time_limit_minutes": 14, "proof_type": "photo", "hint": "Look for signs or landmarks in the landmark district", "safety_note": "Stay on public paths and avoid restricted areas"}], "global_hints": ["Explore systematically from the meeting point outward", "Ask locals for directions if needed", "Time management is key - don't spend too long on any single task"], "score_rules": ["Each task completed: full points", "Early completion: +1 bonus point per minute under limit", "Hints used: -5 points per hint", "Late arrival at meeting point: -10 points per minute"], "tie_breaker": "Winner is the player with the most points when time expires. Ties broken by earliest completion time.", "safety": {"allowed_zone": "Le Marais", "forbidden_behaviors": ["Entering buildings without permission", "Crossing busy streets recklessly", "Approaching strangers", "Leaving the designated area"], "adult_supervision": false, "stop_conditions": ["If a player feels unsafe, the game stops immediately", "If weather becomes severe, relocate to shelter", "If anyone is injured, call emergency services"]}, "story_seed": {"tone": "playful", "motifs": ["exploration", "discovery", "teamwork"], "recap_style": "episode_recap"}}, "adventure_code": "75ZKFE", "teams": ["team-a", "team-b"], "players": [{"name": "Player 1", "team_id": "team-a"}, {"name": "play 2", "team_id": "team-b"}, {"name": "hola", "team_id": "team-b"}], "photos": [{"photo_id": "photo-71c44ee8", "photo_name": "", "caption": "", "task_id": "t1"}]}, "6b1af473-b00b-44ae-bffc-7b8e93616767": {"config": {"game_type": "scavenger_hunt", "city": "Paris", "area": "Le Marais", "location_type": "mixed", "duration_minutes": 60, "num_players": 2, "difficulty": "easy", "age_group": "adults", "energy_level": "low", "photo_enabled": true}, "game": {"game_id": "mock-6d6ab9cf", "title": "Scavenger_Hunt in Le Marais", "theme": "easy adventure", "setup": {"city": "Paris", "area": "Le Marais", "meeting_point": "Main entrance of Le Marais", "duration_minutes": 60, "num_players": 2}, "rules": ["Complete as many tasks as possible within 60 minutes", "Take photos or notes as proof of completion", "Stay within the designated area at all times", "No entering private buildings or restricted areas", "This game is suitable for adults"], "tasks": [{"task_id": "t1", "title": "Task 1: Explore the main square", "description": "Find and document something interesting in the main square", "location_hint": "Navigate to the main square and look for distinctive features", "points": 15, "time_limit_minutes": 8, "proof_type": "photo", "hint": "Look for signs or landmarks in the main square", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t2", "title": "Task 2: Explore the city center", "description": "Find and document something interesting in the city center", "location_hint": "Navigate to the city center and look for distinctive features", "points": 20, "time_limit_minutes": 10, "proof_type": "observation", "hint": "Look for signs or landmarks in the city center", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t3", "title": "Task 3: Explore the park area", "description": "Find and document something interesting in the park area", "location_hint": "Navigate to the park area and look for distinctive features", "points": 25, "time_limit_minutes": 12, "proof_type": "text", "hint": "Look for signs or landmarks in the park area", "safety_note": "Stay on public paths and avoid restricted areas"}, {"task_id": "t4", "title": "Task 4: Explore the landmark district", "description": "Find and document something interesting in the landmark district", "location_hint": "Navigate to the landmark district and look for distinctive features", "points": 30, "time_limit_minutes": 14, "proof_type": "photo", "hint": "Look for signs or landmarks in the landmark district", "safety_note": "Stay on public paths and avoid restricted areas"}], "global_hints": ["Explore systematically from the meeting point outward", "Ask locals for directions if needed", "Time management is key - don't spend too long on any single task"], "score_rules": ["Each task completed: full points", "Early completion: +1 bonus point per minute under limit", "Hints used: -5 points per hint", "Late arrival at meeting point: -10 points per minute"], "tie_breaker": "Winner is the player with the most points when time expires. Ties broken by earliest completion time.", "safety": {"allowed_zone": "Le Marais", "forbidden_behaviors": ["Entering buildings without permission", "Crossing busy streets recklessly", "Approaching strangers", "Leaving the designated area"], "adult_supervision": false, "stop_conditions": ["If a player feels unsafe, the game stops immediately", "If weather becomes severe, relocate to shelter", "If anyone is injured, call emergency services"]}, "story_seed": {"tone": "playful", "motifs": ["exploration", "discovery", "teamwork"], "recap_style": "episode_recap"}}, "adventure_code": "JWR5RV", "teams": ["team-a", "team-b"], "players": [{"name": "Player 1", "team_id": "team-a"}], "photos": []}, "32e1bbe3-50a1-4e43-a7c2-8ecf3f781550": {"config": {"game_type": "scavenger_hunt", "city": "Paris", "area": "Le Marais", "location_type": "mixed", "duration_minutes": 60, "num_players": 4, "difficulty": "medium", "age_group": "adults", "energy_level": "medium", "photo_enabled": true}, "game": {"game_id": "game_042", "title": "Le Marais Mystery Hunt", "theme": "Scavenger Hunt", "setup": {"city": "Paris", "area": "Le Marais", "meeting_point": "Place des Vosges", "duration_minutes": 60, "num_players": 4}, "rules": ["Stay within Le Marais boundaries", "No entering buildings or private property", "No proximity to water, traffic, or rail lines", "No interacting with strangers", "All tasks must be observed, no purchases"], "tasks": [{"task_id": "t1", "title": "Historic Fountain", "description": "Observe the historic fountain at Place des Vosges.", "location_hint": "Place des Vosges", "points": 20, "time_limit_minutes": null, "proof_type": "observation", "hint": "Look for the historic fountain", "safety_note": "Only observe, no touching or entering"}, {"task_id": "t2", "title": "Colorful Door", "description": "Observe the colorful door on Rue des Rosiers.", "location_hint": "Rue des Rosiers", "points": 15, "time_limit_minutes": null, "proof_type": "observation", "hint": "Look for the colorful door", "safety_note": "Only observe, no touching or entering"}, {"task_id": "t3", "title": "Task 3", "description": "Explore and discover something interesting in the area", "location_hint": "Look around the central area", "points": 25, "time_limit_minutes": null, "proof_type": "text", "hint": "Check visible landmarks and signs for clues", "safety_note": "Stay on public paths and respect local rules"}], "global_hints": ["Le Marais is a historic district", "All tasks are observation-based"], "score_rules": ["Higher points win", "Tie broken by total points"], "tie_breaker": "Highest total points wins", "safety": {"allowed_zone": "Le Marais public streets and parks", "forbidden_behaviors": ["Entering buildings or private property", "Proximity to water, traffic, or rail lines", "Interacting with strangers", "Purchasing items"], "adult_supervision": false, "stop_conditions": ["All tasks completed", "Time limit 60 minutes reached", "Any rule violation"]}, "story_seed": {"tone": "playful", "motifs": ["historic architecture", "urban exploration"], "recap_style": "Summarize each player's observations and points"}}, "adventure_code": "NKPZKT", "teams": ["team-a", "team-b"], "players": [{"name": "Nithin", "team_id": "team-a"}], "photos": []}, "4b03fbfc-4326-4325-8975-e4216c44e03e": {"config": {"game_type": "scavenger_hunt", "city": "Paris", "area": "Le Marais", "location_type": "mixed", "duration_minutes": 60, "num_players": 4, "difficulty": "medium", "age_group": "adults", "energy_level": "medium", "photo_enabled": true}, "game": {"game_id": "game_042", "title": "Le Marais Mystery Hunt", "theme": "Observational scavenger hunt", "setup": {"city": "Paris", "area": "Le Marais", "meeting_point": "Place des Vosges", "duration_minutes": 60, "num_players": 4}, "rules": ["Stay within Le Marais boundaries", "No entering buildings or private property", "No crossing traffic or water", "No interacting with strangers", "No purchases", "All tasks are observation only"], "tasks": [{"task_id": "t1", "title": "Vosges View", "description": "Find the historic square Place des Vosges and note its symmetrical layout.", "location_hint": "Place des Vosges", "points": 20, "time_limit_minutes": null, "proof_type": "observation", "hint": "Look for the central fountain", "safety_note": "Stay on pavement, no building entry"}, {"task_id": "t2", "title": "Rue des Rosiers", "description": "Observe the vibrant street market stalls and colorful awnings.", "location_hint": "Rue des Rosiers", "points": 15, "time_limit_minutes": null, "proof_type": "observation", "hint": "Notice the flower displays", "safety_note": "No entering stalls"}, {"task_id": "t3", "title": "H\u00f4tel de Ville View", "description": "Observe the fa\u00e7ade of the H\u00f4tel de Ville from the street.", "location_hint": "Place des Vosges near H\u00f4tel de Ville", "points": 20, "time_limit_minutes": null, "proof_type": "observation", "hint": "Look for the clock tower", "safety_note": "No entering building"}], "global_hints": ["Stay within Le Marais", "Use observation only", "No purchases"], "score_rules": ["Highest points wins", "All tasks completed for bonus"], "tie_breaker": "First player to reach 50 points wins", "safety": {"allowed_zone": "Le Marais streets and public squares", "forbidden_behaviors": ["Entering buildings", "Crossing traffic", "Approaching water", "Interacting with strangers", "Purchasing items"], "adult_supervision": true, "stop_conditions": ["Time limit 60 minutes", "Safety breach", "All tasks completed"]}, "story_seed": {"tone": "playful", "motifs": ["hidden clues", "Parisian charm", "observation"], "recap_style": "Gather at the meeting point for a recap of findings."}}, "adventure_code": "NXWHQK", "teams": ["team-a", "team-b"], "players": [{"name": "Nithin", "team_id": "team-a"}], "photos": []}}}

app/schemas/journal_schema.json

@@ -52,6 +52,38 @@
         "type": "string"
       },
       "description": "References to associated photos"
+    },
+    "transcript_source": {
+      "type": "string",
+      "enum": ["typed", "asr", "hybrid"],
+      "description": "Where the transcript text came from: typed by the user, produced by the ASR service, or hybrid (ASR + manual edits)."
+    },
+    "audio_ref": {
+      "type": "string",
+      "description": "Path or URL of the recorded audio clip associated with this entry."
+    },
+    "asr": {
+      "type": "object",
+      "description": "Metadata describing the ASR pass that produced the transcript (when transcript_source is 'asr' or 'hybrid').",
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "ASR model identifier (e.g. CohereLabs/cohere-transcribe-03-2026)."
+        },
+        "language": {
+          "type": "string",
+          "description": "Language code used for transcription."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ok", "skipped", "error"],
+          "description": "Outcome of the ASR pass."
+        },
+        "error": {
+          "type": ["string", "null"],
+          "description": "Error message if status is 'error' or 'skipped'."
+        }
+      }
     }
   }
 }

app/services/asr.py

@@ -0,0 +1,269 @@
+"""Automatic Speech Recognition (ASR) module.
+
+Default model: ``CohereLabs/cohere-transcribe-03-2026`` (Apache 2.0, 2B
+parameters, 14 languages).
+
+Uses the official 🤗 Transformers integration:
+
+  - transformers >= 5.4.0
+  - torch
+  - huggingface_hub
+  - soundfile, librosa
+  - sentencepiece, protobuf
+
+Audio is auto-resampled to 16 kHz and downmixed to mono by the
+processor. The model supports 14 languages (English, French, German,
+Italian, Spanish, Portuguese, Greek, Dutch, Polish, Mandarin, Japanese,
+Korean, Vietnamese, Arabic) but does not auto-detect language, so
+callers should pass an explicit language code.
+
+Like the other model services, the model is **lazy-loaded** so it does
+not block app startup. Setting the environment variable
+``CITYQUEST_SKIP_MODEL=1`` (or ``CITYQUEST_FAST_TEST=1``) will make all
+ASR calls return an empty string with a warning so the rest of the
+pipeline (typed journal fallback, scoring, recap) keeps working.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+# ── Configuration ───────────────────────────────────────────────────────────
+MODEL_ID = "CohereLabs/cohere-transcribe-03-2026"
+SUPPORTED_LANGUAGES = [
+    "en", "fr", "de", "it", "es", "pt", "el", "nl", "pl",
+    "zh", "ja", "ko", "vi", "ar",
+]
+DEFAULT_LANGUAGE = "en"
+MAX_NEW_TOKENS = 256
+SAMPLING_RATE = 16_000
+
+# Skipped under CITYQUEST_SKIP_MODEL (model download) and CITYQUEST_FAST_TEST
+# (used by `test_end_to_end.py`).
+_skip_env_var = "CITYQUEST_SKIP_MODEL"
+_fast_test_env_var = "CITYQUEST_FAST_TEST"
+
+
+# ── Lazy model state ────────────────────────────────────────────────────────
+_processor = None
+_model = None
+_model_loaded = False
+_load_attempted = False
+
+
+def _is_skipped() -> bool:
+    """True if ASR model loading/inference should be short-circuited."""
+    return bool(os.environ.get(_skip_env_var) or os.environ.get(_fast_test_env_var))
+
+
+def _load_model() -> bool:
+    """Lazy-load the Cohere Transcribe model + processor on first call.
+
+    Returns:
+        ``True`` if the model is ready, ``False`` if it was skipped or
+        failed to load.
+    """
+    global _processor, _model, _model_loaded, _load_attempted
+    if _model_loaded:
+        return _processor is not None and _model is not None
+    _load_attempted = True
+
+    if _is_skipped():
+        print("[asr] skip env var set — ASR model not loaded")
+        return False
+
+    try:
+        import torch
+        from transformers import AutoProcessor, CohereAsrForConditionalGeneration
+        from huggingface_hub import login
+
+        # Try logging in if a token is provided in env (gated model).
+        token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+        if token:
+            try:
+                login(token=token, add_to_git_credential=False)
+            except Exception as exc:
+                print(f"[asr] HF login skipped: {exc}")
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        dtype = torch.bfloat16 if device == "cuda" else torch.float32
+
+        print(f"[asr] Loading {MODEL_ID} on {device} ({dtype}) …")
+        _processor = AutoProcessor.from_pretrained(MODEL_ID)
+        _model = CohereAsrForConditionalGeneration.from_pretrained(
+            MODEL_ID, torch_dtype=dtype, device_map="auto",
+        )
+        _model.eval()
+        _model_loaded = True
+        print("[asr] Model ready")
+        return True
+
+    except ImportError as exc:
+        print(
+            f"[asr] Required packages not installed: {exc}. "
+            "Install with: pip install 'transformers>=5.4.0' torch "
+            "huggingface_hub soundfile librosa sentencepiece protobuf"
+        )
+    except Exception as exc:
+        print(f"[asr] Model load failed: {type(exc).__name__}: {exc}")
+    return False
+
+
+def _load_audio(audio_path: str) -> Optional[list[float]]:
+    """Load an audio file as a mono float32 waveform at 16 kHz.
+
+    Tries multiple loading strategies in order:
+      1. ``transformers.audio_utils.load_audio`` (preferred, handles
+         resampling + mono conversion).
+      2. ``soundfile`` fallback.
+    """
+    if not Path(audio_path).exists():
+        print(f"[asr] Audio file not found: {audio_path}")
+        return None
+
+    try:
+        from transformers.audio_utils import load_audio
+
+        waveform = load_audio(audio_path, sampling_rate=SAMPLING_RATE)
+        return list(waveform)
+    except ImportError:
+        pass
+    except Exception as exc:
+        print(f"[asr] transformers audio load failed: {exc}")
+
+    # Fallback: soundfile + numpy
+    try:
+        import numpy as np
+        import soundfile as sf
+
+        data, sr = sf.read(audio_path, dtype="float32", always_2d=False)
+        if data.ndim > 1:
+            data = data.mean(axis=1)
+        if sr != SAMPLING_RATE:
+            # simple linear resample — good enough for short voice notes
+            ratio = SAMPLING_RATE / sr
+            new_len = int(len(data) * ratio)
+            data = np.interp(
+                np.linspace(0, len(data), new_len, endpoint=False),
+                np.arange(len(data)),
+                data,
+            ).astype("float32")
+        return list(data)
+    except ImportError:
+        print(
+            "[asr] soundfile not installed — install with: "
+            "pip install soundfile librosa"
+        )
+    except Exception as exc:
+        print(f"[asr] soundfile load failed: {exc}")
+    return None
+
+
+# ── Public API ──────────────────────────────────────────────────────────────
+
+def transcribe(
+    audio_path: str,
+    language: str = DEFAULT_LANGUAGE,
+    max_new_tokens: int = MAX_NEW_TOKENS,
+) -> dict:
+    """Transcribe a voice journal audio clip to text.
+
+    Args:
+        audio_path: Path to an audio file (wav/mp3/m4a/ogg/webm).
+        language: One of ``SUPPORTED_LANGUAGES``. Defaults to ``"en"``.
+        max_new_tokens: Maximum number of tokens to generate.
+
+    Returns:
+        Dict with keys ``transcript`` (str), ``language`` (str),
+        ``model`` (str), ``status`` (str — ``"ok"`` | ``"skipped"`` |
+        ``"error"``), and ``error`` (str | None). On non-ok statuses
+        ``transcript`` is ``""``.
+    """
+    if language not in SUPPORTED_LANGUAGES:
+        print(
+            f"[asr] Language '{language}' not in supported set — "
+            f"falling back to '{DEFAULT_LANGUAGE}'."
+        )
+        language = DEFAULT_LANGUAGE
+
+    if _is_skipped():
+        return {
+            "transcript": "",
+            "language": language,
+            "model": MODEL_ID,
+            "status": "skipped",
+            "error": "ASR model skipped (CITYQUEST_SKIP_MODEL/CITYQUEST_FAST_TEST).",
+        }
+
+    if not _load_model():
+        return {
+            "transcript": "",
+            "language": language,
+            "model": MODEL_ID,
+            "status": "error",
+            "error": "ASR model unavailable.",
+        }
+
+    waveform = _load_audio(audio_path)
+    if waveform is None:
+        return {
+            "transcript": "",
+            "language": language,
+            "model": MODEL_ID,
+            "status": "error",
+            "error": f"Could not load audio at {audio_path}.",
+        }
+
+    try:
+        import torch
+
+        inputs = _processor(
+            waveform,
+            sampling_rate=SAMPLING_RATE,
+            return_tensors="pt",
+            language=language,
+        )
+        inputs = {
+            k: v.to(_model.device, dtype=_model.dtype) if hasattr(v, "to") else v
+            for k, v in inputs.items()
+        }
+
+        with torch.inference_mode():
+            outputs = _model.generate(
+                **inputs,
+                max_new_tokens=max_new_tokens,
+            )
+        text = _processor.decode(outputs[0], skip_special_tokens=True).strip()
+
+        return {
+            "transcript": text,
+            "language": language,
+            "model": MODEL_ID,
+            "status": "ok",
+            "error": None,
+        }
+
+    except Exception as exc:
+        print(f"[asr] Inference failed: {type(exc).__name__}: {exc}")
+        return {
+            "transcript": "",
+            "language": language,
+            "model": MODEL_ID,
+            "status": "error",
+            "error": f"{type(exc).__name__}: {exc}",
+        }
+
+
+def transcribe_text(
+    audio_path: str,
+    language: str = DEFAULT_LANGUAGE,
+) -> str:
+    """Convenience wrapper that returns just the transcript string.
+
+    Returns ``""`` on any failure so callers can fall back to typed
+    journal input without exception handling.
+    """
+    return transcribe(audio_path, language=language).get("transcript", "")

app/services/journal.py

@@ -62,16 +62,25 @@ LOCATION_KEYWORDS = [
 
 # ── Transcription ───────────────────────────────────────────────────────────
 
-def transcribe_journal(audio_path: str) -> str:
+def transcribe_journal(
+    audio_path: str,
+    language: str = "en",
+    prefer: str = "cohere",
+) -> str:
     """Transcribe voice journal audio to text.
 
-    Tries (in order):
-      1. ``whisper`` Python package (OpenAI Whisper, runs locally).
-      2. Returns an empty string with a warning so downstream code
-         still works and the user can fall back to typed input.
+    Tries (in order, controlled by ``prefer``):
+      1. ``"cohere"`` (default) — ``CohereLabs/cohere-transcribe-03-2026``
+         via ``app.services.asr``. Lazy-loaded; honors the
+         ``CITYQUEST_SKIP_MODEL`` / ``CITYQUEST_FAST_TEST`` env vars.
+      2. ``"whisper"`` — OpenAI Whisper, runs locally.
+      3. Returns an empty string with a warning so the caller can fall
+         back to typed input.
 
     Args:
         audio_path: Path to a recorded audio file (wav/mp3/m4a/ogg/webm).
+        language: Language code passed to the ASR model (e.g. ``"en"``).
+        prefer: ``"cohere"`` | ``"whisper"`` | ``"any"``.
 
     Returns:
         Transcribed text, or ``""`` if transcription is unavailable.
@@ -80,7 +89,24 @@ def transcribe_journal(audio_path: str) -> str:
     if not path.exists():
         raise FileNotFoundError(f"Audio file not found: {audio_path}")
 
-    # Try local Whisper
+    # ── 1. Cohere Transcribe (preferred) ──────────────────────────────────
+    if prefer in ("cohere", "any"):
+        try:
+            from app.services.asr import transcribe_text as _cohere_transcribe
+
+            text = _cohere_transcribe(str(path), language=language)
+            if text:
+                return text
+        except ImportError as exc:
+            print(f"[journal] Cohere ASR import failed: {exc}")
+        except Exception as exc:
+            print(f"[journal] Cohere ASR failed: {type(exc).__name__}: {exc}")
+
+    if prefer == "cohere":
+        # Don't fall back to Whisper unless the caller asks for it.
+        return ""
+
+    # ── 2. Whisper fallback (opt-in) ──────────────────────────────────────
     try:
         import whisper  # type: ignore
 
@@ -224,6 +250,9 @@ def create_journal_entry(
     task_id: Optional[str] = None,
     location_note: str = "",
     photo_refs: Optional[list[str]] = None,
+    audio_ref: Optional[str] = None,
+    asr_metadata: Optional[dict] = None,
+    transcript_source: str = "typed",
 ) -> dict:
     """Build a complete journal entry dict matching the journal schema.
 
@@ -234,6 +263,12 @@ def create_journal_entry(
         task_id: Optional associated task ID.
         location_note: Where the entry was recorded.
         photo_refs: List of photo identifiers to attach.
+        audio_ref: Optional path/URL of the recorded audio clip.
+        asr_metadata: Optional dict describing the ASR pass that
+            produced ``transcript`` (model, language, status, error).
+        transcript_source: One of ``"typed"`` | ``"asr"`` | ``"hybrid"`` —
+            whether the transcript came from typing, the ASR service,
+            or a combination (ASR with manual edits).
 
     Returns:
         Full journal entry dict.
@@ -249,11 +284,18 @@ def create_journal_entry(
         "mood": mood,
         "location_note": location_note or "Unknown location",
         "photo_refs": photo_refs or [],
+        "transcript_source": transcript_source,
     }
 
     if task_id:
         entry["task_id"] = task_id
 
+    if audio_ref:
+        entry["audio_ref"] = audio_ref
+
+    if asr_metadata:
+        entry["asr"] = asr_metadata
+
     return entry
 
 

requirements.txt

@@ -11,4 +11,9 @@ jsonschema
 diffusers[torch]   # uncomment for offline FLUX poster generation
 transformers
 accelerate
+# Cohere Transcribe ASR (voice journal) — gated model, requires HF_TOKEN
+soundfile
+librosa
+sentencepiece
+protobuf
 # modal            # uncomment to deploy to Modal cloud GPU

test_asr.py

@@ -0,0 +1,249 @@
+"""Tests for the ASR-backed journal pipeline.
+
+These tests cover the fast/skip-model path and the metadata path so the
+rest of the journal pipeline (scoring, recap, persistence) keeps
+working even when no audio model is available.
+
+Run with:
+
+    CITYQUEST_FAST_TEST=1 python test_asr.py
+
+To exercise the real model, run without the skip env var on a GPU box.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import uuid
+from pathlib import Path
+
+
+# ── Fast-test guard ───────────────────────────────────────────────────────
+if os.environ.get("CITYQUEST_FAST_TEST") or not os.environ.get("CITYQUEST_RUN_ASR"):
+    os.environ.setdefault("CITYQUEST_SKIP_MODEL", "1")
+
+passed = 0
+failed = 0
+errors: list[str] = []
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    global passed, failed
+    if condition:
+        passed += 1
+        print(f"  ✓ PASS: {label}")
+    else:
+        failed += 1
+        msg = f"✗ FAIL: {label} — {detail}" if detail else f"✗ FAIL: {label}"
+        errors.append(msg)
+        print(f"  {msg}")
+
+
+def main() -> int:
+    global passed, failed
+    print("=" * 80)
+    print("ASR JOURNAL PIPELINE — TESTS")
+    print("=" * 80)
+
+    # ── T1: ASR module imports & constants ──────────────────────────────
+    print("\n" + "-" * 80)
+    print("T1: ASR MODULE IMPORTS")
+    print("-" * 80)
+    try:
+        from app.services.asr import (
+            MODEL_ID,
+            SUPPORTED_LANGUAGES,
+            DEFAULT_LANGUAGE,
+            transcribe,
+            transcribe_text,
+        )
+        check("ASR module imports", True)
+        check("Model id is Cohere Transcribe", "cohere-transcribe" in MODEL_ID,
+              f"Got {MODEL_ID}")
+        check("Supports 14 languages", len(SUPPORTED_LANGUAGES) == 14,
+              f"Got {len(SUPPORTED_LANGUAGES)}")
+        check("Default language is English", DEFAULT_LANGUAGE == "en")
+    except Exception as e:
+        check("ASR module imports", False, str(e))
+        _summary()
+        return 1
+
+    # ── T2: transcribe() returns structured result ──────────────────────
+    print("\n" + "-" * 80)
+    print("T2: transcribe() CONTRACT")
+    print("-" * 80)
+    try:
+        # Use a fake file path — skipped mode should never reach the disk
+        result = transcribe("/nonexistent/audio.wav", language="en")
+        check("transcribe() returns dict", isinstance(result, dict))
+        for key in ("transcript", "language", "model", "status", "error"):
+            check(f"transcribe() has '{key}'", key in result)
+        check("status is 'ok' | 'skipped' | 'error'",
+              result["status"] in ("ok", "skipped", "error"),
+              f"Got {result['status']}")
+        check("transcript is a string", isinstance(result["transcript"], str))
+        check("model is reported", bool(result["model"]))
+    except Exception as e:
+        check("transcribe() contract", False, str(e))
+
+    # ── T3: Skipped mode is silent and empty ────────────────────────────
+    print("\n" + "-" * 80)
+    print("T3: SKIP-MODE BEHAVIOR")
+    print("-" * 80)
+    try:
+        os.environ["CITYQUEST_SKIP_MODEL"] = "1"
+        result = transcribe("/tmp/fake.wav", language="en")
+        check("Skip mode returns empty transcript", result["transcript"] == "")
+        check("Skip mode reports status=skipped", result["status"] == "skipped")
+        # Restore to be safe
+        del os.environ["CITYQUEST_SKIP_MODEL"]
+    except Exception as e:
+        check("Skip-mode behavior", False, str(e))
+
+    # ── T4: transcribe_journal() returns empty on skip ──────────────────
+    print("\n" + "-" * 80)
+    print("T4: JOURNAL.transcribe_journal() FALLBACK")
+    print("-" * 80)
+    try:
+        os.environ["CITYQUEST_SKIP_MODEL"] = "1"
+        from app.services.journal import transcribe_journal
+
+        # Create a tiny valid wav so path checks pass
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as fh:
+            wav_path = fh.name
+            # Minimal RIFF header — not a real wav, but enough for the
+            # existence check in transcribe_journal()
+            fh.write(b"RIFF\x24\x00\x00\x00WAVEfmt ")
+
+        try:
+            text = transcribe_journal(wav_path, language="en")
+            check("transcribe_journal returns str", isinstance(text, str))
+            check("transcribe_journal empty when ASR skipped", text == "",
+                  f"Got {text!r}")
+        finally:
+            try:
+                os.unlink(wav_path)
+            except OSError:
+                pass
+    except Exception as e:
+        check("Journal.transcribe_journal fallback", False, str(e))
+
+    # ── T5: create_journal_entry() supports ASR metadata ───────────────
+    print("\n" + "-" * 80)
+    print("T5: JOURNAL ENTRY METADATA")
+    print("-" * 80)
+    try:
+        from app.services.journal import create_journal_entry, save_journal_entry, load_journal_entries
+
+        asr_meta = {
+            "model": "CohereLabs/cohere-transcribe-03-2026",
+            "language": "en",
+            "status": "ok",
+            "error": None,
+        }
+        entry = create_journal_entry(
+            transcript="We just found the mural near the canal, amazing!",
+            session_id="test-asr",
+            team_id="team-a",
+            task_id="t1",
+            location_note="Canal area",
+            audio_ref="/tmp/clip.wav",
+            asr_metadata=asr_meta,
+            transcript_source="asr",
+        )
+        check("Entry has transcript_source", entry.get("transcript_source") == "asr")
+        check("Entry has audio_ref", entry.get("audio_ref") == "/tmp/clip.wav")
+        check("Entry has asr metadata", isinstance(entry.get("asr"), dict))
+        check("ASR metadata has model", entry["asr"]["model"] == asr_meta["model"])
+        check("ASR metadata has language", entry["asr"]["language"] == "en")
+        check("ASR metadata has status", entry["asr"]["status"] == "ok")
+
+        # Schema validation (optional — only if jsonschema is installed)
+        try:
+            import jsonschema  # type: ignore
+            schema_path = Path("app/schemas/journal_schema.json")
+            schema = json.loads(schema_path.read_text())
+            jsonschema.validate(instance=entry, schema=schema)
+            check("Entry validates against journal_schema.json", True)
+        except ImportError:
+            check("Entry validates against journal_schema.json (skipped, no jsonschema)", True)
+
+        # Persistence round-trip
+        save_journal_entry(entry)
+        loaded = load_journal_entries(session_id="test-asr")
+        check("Entry persisted with ASR metadata", len(loaded) >= 1)
+        if loaded:
+            check("Loaded entry has transcript_source",
+                  loaded[-1].get("transcript_source") == "asr")
+            check("Loaded entry has asr block",
+                  isinstance(loaded[-1].get("asr"), dict))
+    except Exception as e:
+        check("Journal entry metadata", False, str(e))
+
+    # ── T6: app.record_journal() handles voice path ─────────────────────
+    print("\n" + "-" * 80)
+    print("T6: app.record_journal() VOICE PATH (skip-mode)")
+    print("-" * 80)
+    try:
+        os.environ["CITYQUEST_SKIP_MODEL"] = "1"
+        # We can't import the whole app (it boots Gradio), so test the
+        # logic by directly exercising the journal functions.
+        from app.services.journal import transcribe_journal, create_journal_entry
+        from app.services.asr import transcribe as _asr_transcribe
+
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as fh:
+            wav_path = fh.name
+            fh.write(b"RIFF\x24\x00\x00\x00WAVEfmt ")
+
+        try:
+            asr_result = _asr_transcribe(wav_path, language="en")
+            check("ASR returns skipped status", asr_result["status"] == "skipped")
+            check("ASR transcript is empty", asr_result["transcript"] == "")
+
+            # When ASR produces no text, journal creation should still
+            # be possible via the typed/manual correction path.
+            entry = create_journal_entry(
+                transcript="Typed correction (ASR was unavailable).",
+                session_id="test-asr-voice",
+                audio_ref=wav_path,
+                asr_metadata={
+                    "model": asr_result["model"],
+                    "language": asr_result["language"],
+                    "status": asr_result["status"],
+                    "error": asr_result["error"],
+                },
+                transcript_source="typed",
+            )
+            check("Hybrid entry created with asr metadata",
+                  entry.get("asr", {}).get("status") == "skipped")
+        finally:
+            try:
+                os.unlink(wav_path)
+            except OSError:
+                pass
+    except Exception as e:
+        check("Voice path in skip-mode", False, str(e))
+
+    _summary()
+    return 0 if failed == 0 else 1
+
+
+def _summary() -> None:
+    total = passed + failed
+    print("\n" + "=" * 80)
+    if failed == 0:
+        print(f"RESULTS: {passed}/{total} tests passed — ALL CLEAR 🎉")
+    else:
+        print(f"RESULTS: {passed}/{total} tests passed — {failed} FAILED")
+    print("=" * 80)
+    if errors:
+        print("\nFailed tests:")
+        for e in errors:
+            print(f"  {e}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())