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