README.md

metadata

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

pip install -r requirements.txt
# spaCy en_core_web_sm is included via the wheel URL in requirements.txt

2. Environment

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

cd frontend
npm install
npm run build
cd ..

4. Start the application

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:

docker compose up languagetool -d

Set in .env: LANGUAGE_TOOL_URL=http://127.0.0.1:8010
See docs/GRAMMAR_SETUP.md.

API

• GET /health
• GET /v1/auth/config
• GET /v1/me
• POST /v1/rewrite
• POST /v1/grammar

Rewrite request:

{"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

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