Add HF Spaces Docker deployment: transliteration endpoint, static UI serving

server/transliterate.py wraps IndicXlit (ai4bharat-transliteration),
imported defensively in app.py since fairseq only installs cleanly on
Linux - local Windows dev keeps working without it, the Space container
has it. New GET / serves the UI directly instead of requiring a separate
static server. ui/rachana-desk.html's API_BASE now self-detects file://
vs served-origin, and the Roman-script notice gets a real Transliterate
action instead of a static message. Dockerfile/requirements-deploy.txt/
README.md frontmatter configure the Docker SDK Space.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,21 @@
+.git/
+.gitattributes
+.gitignore
+.env
+__pycache__/
+*.pyc
+.venv/
+.venv-unsloth/
+wandb/
+unsloth_compiled_cache/
+data/
+models/*
+!models/exp3_gemma3_4b_public_v0_1/
+models/exp3_gemma3_4b_public_v0_1/checkpoint-*/
+.obsidian/
+.agents/
+.claude/
+reports/
+scripts/
+IndicXlit_python_inference.ipynb
+AUDIT_REPORT.md

Dockerfile

@@ -0,0 +1,45 @@
+# Rachana News - HF Spaces deployment image.
+# Python 3.10 is required, not just conventional: fairseq's config
+# dataclasses crash on Python 3.11+'s stricter mutable-default rule
+# (see errors.md 2026-07-21/22).
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# build-essential: fairseq compiles a small C extension (fairseq.libbleu)
+# at install time - this is exactly what native Windows lacked (no MSVC),
+# and what WSL2/Linux ships by default via gcc/g++.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements-deploy.txt .
+
+# Standard PyPI torch build - the special cu128/Blackwell pin this project
+# needs for local dev (RTX 5050) does not apply to Spaces GPU hardware
+# (T4/A10G/etc, all standard architectures with kernels in the default
+# distribution already).
+RUN pip install --no-cache-dir torch && \
+    pip install --no-cache-dir -r requirements-deploy.txt
+
+# fairseq/ai4bharat-transliteration: pip<24.1 works around a real
+# omegaconf metadata-rejection bug (a malformed PyYAML version specifier
+# in omegaconf's own wheel, rejected by pip>=24.1's stricter parsing).
+# Cloning fairseq manually (rather than letting pip clone it internally)
+# avoids an intermittent git smart-protocol error seen during this
+# project's WSL2 validation. Both fixes are logged in errors.md
+# 2026-07-21/22, where this exact sequence was proven working.
+RUN pip install --no-cache-dir "pip<24.1" && \
+    git clone --depth 1 https://github.com/facebookresearch/fairseq.git /tmp/fairseq_src && \
+    pip install --no-cache-dir -e /tmp/fairseq_src && \
+    pip install --no-cache-dir ai4bharat-transliteration
+
+COPY server/ server/
+COPY ui/ ui/
+COPY models/exp3_gemma3_4b_public_v0_1/ models/exp3_gemma3_4b_public_v0_1/
+
+ENV PYTHONUNBUFFERED=1
+# HF Spaces' Docker SDK expects the app to listen on 7860 by default.
+EXPOSE 7860
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,63 +1,44 @@
+---
+title: Rachana News
+emoji: 📰
+colorFrom: blue
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
 # Rachana News
 
-A Telugu-language AI assistant for newsroom editors and reporters, built by fine-tuning Gemma 3 (4B) into a domain specialist for editorial tasks: drafting, paraphrasing, editing, translation, and transliteration.
+A Telugu-language AI writing assistant for newsroom editors and reporters, built by fine-tuning Gemma 3 (4B) into a domain specialist for editorial tasks: headline generation, paraphrasing, grammar correction, translation, transliteration, and research.
 
 **Full product spec:** See `Rachana_News_PRD.md`
+**Current project state:** See `progress.md` (rewritten each session — the authoritative status snapshot)
 
-## Repo Structure
+## What's here
 
-- `scripts/` — Python pipeline for evaluation
-  - `prepare_eval_data.py` — samples ~10 prompts per capability from public datasets
-  - `run_eval.py` — runs prompts through local Gemma 3 4B via Ollama
-  - `score_eval.py` — scores capabilities with automated metrics or outputs manual-rating CSVs
-- `data/processed/` — evaluation data
-  - `eval_prompts.jsonl` — input prompts across 8 capabilities
-  - `eval_results.jsonl` — model outputs
-  - `manual_ratings_*.csv` — three CSVs awaiting human ratings:
-    - `manual_ratings_paraphrase.csv`
-    - `manual_ratings_fluency.csv`
-    - `manual_ratings_notes_to_article.csv`
-- `reports/` — findings
-  - `baseline_v0.md` — baseline eval of unmodified Gemma 3 4B-IT; answers PRD §11 open question #1
-- `.obsidian/` — Obsidian vault config (project is indexed as a vault)
+- `server/` — FastAPI backend serving the exp3 QLoRA adapter (headline/grammar/paraphrase/translate/summarize/transliterate) plus a controlled-RAG Research Assistant over curated Telugu news feeds
+- `ui/rachana-desk.html` — the writer workspace UI, served by the backend at `/`
+- `models/exp3_gemma3_4b_public_v0_1/` — the trained LoRA adapter (base model `google/gemma-3-4b-it` downloads at container startup, gated - requires `HF_TOKEN`)
+- `scripts/` — the training/eval pipeline (dataset prep, QLoRA training, adapter evaluation) - not part of the deployed image, local-dev only
+- `Rachana_News_PRD.md`, `progress.md`, `decisions.md`, `errors.md`, `data-sources.md` — project memory; read `progress.md` first for current status
 
-## Setup
+## Running locally
 
-Requires Python 3.10, `pip`, and Ollama (installed separately).
+Requires Python 3.10.
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate  # or .venv\Scripts\activate on Windows
-pip install -r requirements.txt
-ollama pull gemma3:4b
+pip install -r requirements-deploy.txt
+pip install torch --index-url https://download.pytorch.org/whl/cu128  # or the CUDA build matching your GPU
+uvicorn server.app:app --reload --port 8000
 ```
 
-## Running the Pipeline
-
-```bash
-# Step 1: Prepare evaluation data (samples from public datasets)
-python scripts/prepare_eval_data.py
-
-# Step 2: Run Gemma 3 4B on each prompt via local Ollama
-python scripts/run_eval.py
-
-# Step 3: Score outputs with automated metrics, emit manual-rating CSVs for tasks without ground truth
-python scripts/score_eval.py
-```
-
-**Awaiting human review:** The three `manual_ratings_*.csv` files need 1–5 ratings (fluency/register/fact-preservation/task-success columns) filled in by hand; no automated scoring exists for paraphrase, fluency, or notes→article capability.
-
-## Key Findings
-
-**Baseline evaluation (Gemma 3 4B-IT, unmodified)** is complete — see `reports/baseline_v0.md` for full results.
+Set `HF_TOKEN` (accepted `google/gemma-3-4b-it` license required) in a local `.env` file — never commit it.
 
-**Open question #1 (§11 of PRD):** Is continued pretraining needed?  
-**Answer:** Tentatively no. Base Telugu fluency and grounded generation are solid already; targeted fine-tuning on weak capabilities (headline generation coherence, summarization register, transliteration task data) is more cost-effective than a pretraining stage.
+Transliteration (`/api/transliterate`) needs `fairseq`/`ai4bharat-transliteration`, which only install cleanly on Linux (see `errors.md` 2026-07-21/22) - the endpoint degrades gracefully (`available: false`) when those packages aren't present, so local Windows dev works without them.
 
-Real weak points identified:
-- **Headline generation**: incoherent word insertions, hallucination at word level
-- **Summarization**: accurate but wrong register (too formal, not terse)
-- **Transliteration**: exact-match score understates real quality due to romanization-convention variance; needs dedicated task data but metric caveat is important
-- **Translation (En→Te)**: solid starting point, lower sample size (n=5), worth rechecking
+## Deploying
 
-**Next steps:** See PRD §11 items 2–5 (human-written seed set size, external teacher model decision, Phase 3 scoping, Rachana Data Studio extension for preference collection).
+See `Dockerfile` — builds a self-contained image (server + UI + transliteration) for HF Spaces' Docker SDK. Requires a GPU-tier Space (bitsandbytes 4-bit quantization needs CUDA) and `HF_TOKEN` set as a Space repository secret.

requirements-deploy.txt

@@ -0,0 +1,19 @@
+# Serving-only dependencies for the deployed Space - trimmed from the
+# training-oriented requirements.txt. Excludes datasets/sacrebleu/
+# rouge-score/jiwer/wandb/trl/pandas, which server/app.py, server/
+# guardrails.py, and server/research.py never import.
+#
+# torch and fairseq/ai4bharat-transliteration are installed separately in
+# the Dockerfile (see decisions.md 2026-07-22 for why: torch needs a CUDA
+# index URL pip can't express in a plain requirements file, and fairseq
+# needs the pip<24.1 + build-tooling sequence validated in WSL2 this
+# session).
+fastapi==0.139.2
+uvicorn==0.51.0
+feedparser==6.0.12
+python-dotenv==1.2.2
+requests==2.34.2
+transformers==5.14.1
+accelerate==1.14.0
+peft==0.19.1
+bitsandbytes==0.49.2

server/app.py

@@ -23,6 +23,7 @@ import torch
 from dotenv import load_dotenv
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
 from peft import PeftModel
 from pydantic import BaseModel
 from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
@@ -30,6 +31,18 @@ from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
 from server.guardrails import check_fact_preservation, check_headline_needs_review, detect_script
 from server.research import fetch_all_entries, search_entries, summarize_article
 
+try:
+    # fairseq/ai4bharat-transliteration only install cleanly in a Linux
+    # environment (see errors.md 2026-07-21/22 - native Windows needs both
+    # Developer Mode and an MSVC compiler, neither pursued for local dev).
+    # Import defensively so the rest of the server still runs locally on
+    # Windows without this dependency; the deploy container has it.
+    from server.transliterate import transliterate_text
+    from server.transliterate import load_engine as load_transliteration_engine
+    TRANSLITERATION_AVAILABLE = True
+except ImportError:
+    TRANSLITERATION_AVAILABLE = False
+
 ROOT = Path(__file__).resolve().parent.parent
 load_dotenv(ROOT / ".env")
 
@@ -92,6 +105,8 @@ app.add_middleware(
 @app.on_event("startup")
 def _startup():
     load_model()
+    if TRANSLITERATION_AVAILABLE:
+        load_transliteration_engine()
 
 
 class TextRequest(BaseModel):
@@ -193,6 +208,18 @@ def api_research(req: ResearchRequest):
     return {"results": results}
 
 
+@app.post("/api/transliterate")
+def api_transliterate(req: TextRequest):
+    if not TRANSLITERATION_AVAILABLE:
+        return {"available": False, "words": []}
+    return {"available": True, "words": transliterate_text(req.text)}
+
+
+@app.get("/")
+def ui_index():
+    return FileResponse(ROOT / "ui" / "rachana-desk.html")
+
+
 @app.post("/api/feedback")
 def api_feedback(req: FeedbackRequest):
     FEEDBACK_LOG.parent.mkdir(parents=True, exist_ok=True)

server/transliterate.py

@@ -0,0 +1,34 @@
+"""
+Roman-to-Telugu transliteration via IndicXlit (ai4bharat-transliteration).
+
+Not usable on native Windows (fairseq needs a symlink at build time that
+requires Developer Mode, plus an MSVC compiler for its C extensions) - see
+errors.md 2026-07-21/22. Works cleanly in a Linux container, where this
+module is actually loaded, matching the WSL2 validation done this session.
+"""
+from ai4bharat.transliteration import XlitEngine
+
+_engine = None
+
+
+def load_engine():
+    global _engine
+    if _engine is None:
+        print("[transliterate] loading XlitEngine('te') ...")
+        _engine = XlitEngine("te", beam_width=10, rescore=False)
+        print("[transliterate] engine ready")
+    return _engine
+
+
+def transliterate_text(text: str, topk: int = 3) -> list[dict]:
+    """Transliterate each whitespace-delimited word; punctuation passes through unchanged."""
+    engine = load_engine()
+    results = []
+    for word in text.split():
+        core = word.strip(".,!?;:\"'()[]")
+        if not core:
+            results.append({"input": word, "candidates": [word]})
+            continue
+        candidates = engine.translit_word(core, topk=topk)["te"]
+        results.append({"input": word, "candidates": candidates})
+    return results

ui/rachana-desk.html

@@ -789,7 +789,11 @@
 (function () {
   "use strict";
 
-  var API_BASE = "http://127.0.0.1:8000";
+  // Local double-click-the-file workflow needs an absolute origin (no
+  // origin to resolve a relative fetch against under file://); served from
+  // the FastAPI app itself (local dev via uvicorn, or the deployed
+  // container) same-origin relative paths just work.
+  var API_BASE = (location.protocol === "file:") ? "http://127.0.0.1:8000" : "";
 
   // ============ Task definitions (Quick Tools) ============
   // Live-wired day-1 tasks. notes->article and transliteration are
@@ -1053,7 +1057,9 @@
     html += '<textarea class="input-area" id="input-area">' + escapeHtml(ts_.input) + '</textarea>';
     if (SCRIPT_SENSITIVE_TASKS[task.id]) {
       html += '<div class="review-banner" id="script-notice" style="display:none">' +
-        '⚠ ఈ ఇన్‌పుట్ రోమన్/మిక్స్డ్ లిపిలో ఉంది. ఉత్తమ ఫలితాల కోసం తెలుగు లిపిలో టైప్ చేయండి లేదా అతికించండి.</div>';
+        '⚠ ఈ ఇన్‌పుట్ రోమన్/మిక్స్డ్ లిపిలో ఉంది. ఉత్తమ ఫలితాల కోసం తెలుగు లిపిలో టైప్ చేయండి లేదా అతికించండి. ' +
+        '<button class="action-btn" id="transliterate-btn" type="button">తెలుగులోకి మార్చండి · Transliterate</button>' +
+        '</div>';
     }
     var genLabel = task.render === "research" ? "శోధించండి · Search" : "రూపొందించండి · Generate";
     var genLoadingLabel = task.render === "research" ? "శోధిస్తోంది…" : "రూపొందిస్తోంది…";
@@ -1156,6 +1162,31 @@
         updateScriptNotice(inputArea.value);
       });
     }
+    var translitBtn = document.getElementById("transliterate-btn");
+    if (translitBtn) {
+      translitBtn.addEventListener("click", function () {
+        translitBtn.disabled = true;
+        translitBtn.textContent = "మారుస్తోంది…";
+        fetch(API_BASE + "/api/transliterate", {
+          method: "POST", headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ text: inputArea.value })
+        }).then(function (r) { return r.json(); }).then(function (data) {
+          if (!data.available) {
+            flash("Transliteration is not available in this environment.");
+            return;
+          }
+          var converted = data.words.map(function (w) { return w.candidates[0]; }).join(" ");
+          inputArea.value = converted;
+          ts_.input = converted;
+          updateScriptNotice(converted);
+        }).catch(function (e) {
+          flash("Transliteration failed: " + e.message);
+        }).finally(function () {
+          translitBtn.disabled = false;
+          translitBtn.textContent = "తెలుగులోకి మార్చండి · Transliterate";
+        });
+      });
+    }
     Array.prototype.forEach.call(document.querySelectorAll("[data-dir]"), function (btn) {
       btn.addEventListener("click", function () {
         ts_.direction = btn.getAttribute("data-dir");