| ---
|
| title: ZuZu Writer
|
| emoji: ✍️
|
| colorFrom: gray
|
| colorTo: blue
|
| sdk: docker
|
| app_port: 7860
|
| pinned: false
|
| ---
|
|
|
| # ZuZu Writer
|
|
|
| The existing React interface backed by a CPU-friendly rewriting engine:
|
| structural spaCy reordering, local T5 paraphrase fallback, MiniLM safety,
|
| and low-impact synonym refinement.
|
|
|
| ## Local run
|
|
|
| ### 1. Backend deps
|
|
|
| ```bash
|
| pip install -r requirements.txt
|
| # spaCy en_core_web_sm is included via the wheel URL in requirements.txt
|
| ```
|
|
|
| ### 2. Environment
|
|
|
| ```bash
|
| copy .env.example .env
|
| ```
|
|
|
| Structural rewriting is the first pass. Unchanged rewriteable sentences are
|
| then paraphrased with a local CPU T5 model and ranked by MiniLM similarity.
|
| With `ENGINE_PARAPHRASE_PRIMARY=true`, a more divergent paraphrase can also
|
| replace a light structural rewrite so a second pass (out1→out2) moves further.
|
| Low-impact synonyms can still apply afterward. Keep
|
| `ENGINE_FORCE_REWRITE=false` to avoid the old fixed `It is … that …` cleft.
|
|
|
| ### 3. Build the existing UI
|
|
|
| ```bash
|
| cd frontend
|
| npm install
|
| npm run build
|
| cd ..
|
| ```
|
|
|
| ### 4. Start the application
|
|
|
| ```bash
|
| python app.py
|
| ```
|
|
|
| Open the UI at http://127.0.0.1:7860 and API documentation at `/docs`.
|
|
|
| ### LanguageTool (self-hosted)
|
|
|
| The Docker image embeds LanguageTool. It may take 1–2 minutes to become ready.
|
|
|
| **Local:**
|
|
|
| ```bash
|
| docker compose up languagetool -d
|
| ```
|
|
|
| Set in `.env`: `LANGUAGE_TOOL_URL=http://127.0.0.1:8010`
|
| See [docs/GRAMMAR_SETUP.md](docs/GRAMMAR_SETUP.md).
|
|
|
| ## API
|
|
|
| - `GET /health`
|
| - `GET /v1/auth/config`
|
| - `GET /v1/me`
|
| - `POST /v1/rewrite`
|
| - `POST /v1/grammar`
|
|
|
| Rewrite request:
|
|
|
| ```json
|
| {"text": "Ram went to school yesterday happily."}
|
| ```
|
|
|
| The response includes rewritten text, per-sentence status and confidence,
|
| template IDs, optional lexical-change metadata, skipped sentences,
|
| original-to-rewritten mappings, and batch stats.
|
|
|
| ## Docker
|
|
|
| ```bash
|
| docker compose up --build
|
| ```
|
|
|
| ## Deploy (Hugging Face)
|
|
|
| Use a **Docker** Space (`app_port: 7860`), not Gradio SDK. Prefer **CPU basic**.
|
|
|
| ## Design
|
|
|
| - spaCy tokenization, dependency parsing, and NER
|
| - confidence-ranked deterministic templates
|
| - sentence-level grammar repair with LanguageTool/local fallback
|
| - entity, number, negation, tense, and semantic safety checks
|
| - optional Open English WordNet sense-matched vocabulary refinement
|
| - paragraph batches for 10,000+ word documents
|
| - untouched tables, code, formulas, citations, lists, and bibliography blocks |
