openspec/project.md

# Project Context

## Purpose

**Lingo Bridge** is a *Progressive Translation Card Stack* built for the Hugging
Face "Build Small Hackathon". It turns a single sentence into a visible **and
audible** 7-layer progressive translation: the source language gradually becomes
the target language, one phrase-type at a time. The result is shown as an
interactive 3D card stack plus a 2D parallel-sets visualization, with per-layer
text-to-speech.

The product goal is for it to feel like an **interactive language toy**, not a
normal translator. Build priority order: clarity first, then visual impact.

Status: mid-build. Where source-file comments disagree with this document, this
document and the capability specs under `openspec/specs/` are the source of
truth (the code still carries some stale comments, e.g. older model names).

## Tech Stack

- **Language / runtime:** Python 3.11, served by **FastAPI** + uvicorn (port
  7860 locally). Deliberately *not* Gradio (targets the "Off-Brand" bonus).
- **Text model:** `Qwen3-4B-Instruct-2507` (Q4_K_M GGUF, repo
  `unsloth/Qwen3-4B-Instruct-2507-GGUF`) run via **llama.cpp**
  (`llama-cpp-python`). A deterministic mock backend is the fallback when no
  GGUF is present.
- **TTS model:** target is `Qwen3-TTS-12Hz-1.7B` (the **CustomVoice** variant,
  which ships preset speaker voices). Interim/current engine is **Kokoro-82M**
  via `kokoro-onnx` (Apache-2.0, torch-free), pluggable via env `TTS_ENGINE`.
- **Frontend:** fully custom **WebGL** (Three.js, vendored locally) 3D card
  stack + a 2D parallel-sets (SVG) view. Lives under `static/`.
- **Deployment:** **Modal.com** (serverless GPU), app name `lingo-bridge`,
  file `modal_app.py`. Models live in a Modal Volume `lingua-models`.

## Project Conventions

### Code Style

- Small, single-responsibility modules at repo root: `config.py`, `llm.py`,
  `translate.py`, `tts.py`, `examples.py`, `app.py`, `modal_app.py`.
- All configuration is env-driven through `config.py`
  (`LINGO_MODELS_DIR`, `LINGO_AUDIO_DIR`, `LINGO_STATIC_DIR`,
  `LINGO_LLM_REPO`/`LINGO_LLM_FILE`, `LINGO_LLM_THREADS`,
  `LINGO_GPU_LAYERS`, `TTS_ENGINE`).
- Keep LLM JSON simple and **validate model output before rendering**.
- Every backend that can fail has a graceful fallback (mock LLM, beep/silence
  TTS) so the app and frontend always work.

### Architecture

- **One** structured LLM call decomposes + aligns the sentence into phrase
  "units"; **plain Python** then builds the 7 layers and all the cross-layer
  links deterministically. This keeps JSON small and makes every visual link
  valid by construction.
- Backend API (FastAPI, `app.py`):
  - `GET /api/status`
  - `POST /api/translate {text, source, target}`
  - `POST /api/tts {text, lang}`
  - `GET /api/examples[?random=true]`
  - `GET /audio/{name}`
  - `GET /` (serves the custom frontend)

### Ownership boundary

- The **frontend (`static/*`) is owned by a separate coding agent and must not
  be edited** by anyone else. Application source files (`*.py`, `*.sh`,
  `requirements.txt`, etc.) are likewise out of scope for spec/doc work — only
  files under `openspec/` are edited here.

### Testing

- No formal test suite yet. Validation is empirical: the decompose+align prompt
  was tested across 7 cases and passed 7/7 both at full precision (HF Inference
  Providers) and at Q4 locally. Ad-hoc test scripts (`_modeltest.py`,
  `_q4test.py`) exist at repo root.

## Important Constraints

- **Hackathon model-size rule:** each model must be **≤32B parameters
  per model** (not summed); multiple models are allowed.
- **Languages: exactly 10** (the Qwen3-TTS supported set): English, Spanish,
  French, Italian, Portuguese, German, Russian, Japanese, Korean, Chinese.
  Hindi was dropped because Qwen3-TTS does not support it.
- **Cost guards on Modal:** `min_containers=0` (scale-to-zero),
  `max_containers=1`, `scaledown_window=120`; dev budget cap **$50**.
- Currently on **T4** GPU; moving to **L4** (needed for Qwen3-TTS /
  FlashAttention-2, also speeds up the LLM).
- `llama-cpp-python` is installed from a **prebuilt CUDA wheel** (cu125 index)
  on a CUDA runtime base image — compiling from source on a GPU-less builder
  fails.

## Targeted Bonus Quests

- **Off-Brand** — fully custom UI (no Gradio).
- **Llama Champion** — llama.cpp.
- **Field Notes** — blog write-up (`BLOG.md`).
- **Sharing is Caring** — agent trace.
- **Tiny Titan** — ≤4B per model (both models qualify).

## External Dependencies

- Hugging Face Hub (model download), `llama-cpp-python` cu125 prebuilt wheel
  index, `kokoro-onnx` + onnxruntime, `qwen-tts` (pins `transformers==4.57.3`,
  `accelerate==1.12.0`; optional flash-attn), Three.js (vendored locally under
  `static/vendor/three`), Modal.com.
- Live URL: https://uiharu-kazari--lingo-bridge-web.modal.run