VoiceRedline — hands-free contract redlining on SuperDocs

[vanamkarthiknetha]

Karthik Vanam

VoiceRedline is a voice-driven front end for SuperDocs' human-in-the-loop editing loop: you speak an edit instruction, every proposed change is read back to you and rendered as a real before/after diff, and nothing is applied until you approve it by voice — then you say "export" and get a .docx.

The pairing is the point. A voice interface makes an editing API dangerous, because you cannot proofread what you just dictated into a 40-page contract. approval_mode: ask_every_time is exactly the missing half: the voice makes it fast, the gate makes it safe.

SuperDocs features used

Async chat editing (/v1/chat/async), human-in-the-loop approval (ask_every_time + per-change decisions on /v1/chat/{session}/approve), job polling, sticky multi-round sessions, and format-preserving export (docx/pdf/html/txt — also used for the free live preview).

Run it

cd use-cases/vanamkarthiknetha/voice-redline
pip install -r requirements.txt
export SUPERDOCS_API_KEY=your-key-here
uvicorn server:app --port 8765

Open http://127.0.0.1:8765 in Chrome or Edge, click Load sample MSA, click the mic, and talk. Offline tests: pytest tests/ -q (6 tests, no network or key needed).

Two bugs found while building this

Reported separately to hello@superdocs.app; both are worked around in the code and documented in the README.

1. Positional edit instructions can return a no-op change with a success gloss. "In Section 2, change the automatic renewal period from twenty-four (24) months to twelve (12) months" came back as one pending change whose old_html and new_html were byte-identical — the section heading replaced by itself — with ai_explanation reading "✅ I have updated the automatic renewal period…". Approving it completed the job; the document was unchanged. 2/2 runs. Rephrasing as find-and-replace targeted the correct paragraph first try. This is why the app now diffs every pending change client-side and announces no-ops out loud: a review gate whose explanations can claim a null edit succeeded is a trust problem.

2. The approve endpoint accepts decisions for change_ids that don't exist, and the job completes anyway — so an integrator's id-mapping bug can silently resolve a human review gate. The server here validates every decision batch against the real pending set before forwarding.

Honest limits

Web Speech recognition is Chrome/Edge only (elsewhere it degrades to type-and-click, and note Chrome's STT is cloud-backed, which matters for real contracts). Single-user desk tool by design. The command grammar is a regex table, not an NLU model. Sample contract is fully fictional synthetic data.

Built with AI assistance (Claude Code), the way I actually build.