tov
Rewrite text in a given tone of voice using Google Gemini, from the command line, and tune that tone across models in a local web UI.
Install
uv tool install tov
or pipx install tov, or pip install tov. You'll need a Gemini API key in GEMINI_API_KEY.
To try it without installing:
uvx tov "Plain, friendly British English" "Please be advised that the office is closed."
As a single-file script
tov.py is self-contained: its dependencies are declared inline
(PEP 723), so uv
installs them automatically when you run it directly.
curl -fsSL https://raw.githubusercontent.com/tomdyson/tov/main/tov.py -o ~/.local/bin/tov
chmod +x ~/.local/bin/tov
Usage
tov TONE INPUT [MODEL]
tov INPUT [MODEL] # with TOV_TONE set
echo "text" | tov TONE [MODEL] # INPUT omitted or "-" reads stdin
tov --ui [--port N] [--no-open]
tov --version
TONEandINPUTcan each be literal text or a path to a file.MODELdefaults togemini-3.8-flash(orTOV_MODELif set), with thinking set tolow(orTOV_THINKING).- The rewrite streams to stdout with nothing else added; errors go to stderr.
Examples
tov "Warm, plain British English. No jargon." "Per our previous correspondence, your application has been actioned."
pbpaste | tov ~/tone-guide.md | pbcopy
export TOV_TONE="Formal incident update for enterprise customers"
tov "server's down again lol" gemini-3.5-flash
A model name is recognised by its shape: a single lowercase hyphenated token such as
gemini-3.5-flash. That lets tov work out what you meant:
- When input is piped in,
tov TONE MODELreads the input from stdin. - When
TOV_TONEis set,tov INPUT MODELuses the tone from the environment, whiletov TONE INPUT(second argument not model-shaped) overrides it.
If your input text happens to look like a model name, pass it explicitly with
tov TONE - MODEL and pipe it in.
Tuning a tone in the web UI
TOV_TONE=~/tone-guide.md tov --ui
This starts a small web server on your machine (port 8686, or a free one if that's taken) and opens it in your browser. Use it to iterate on a tone and check how different models handle it:
- Compare models side by side. Pick any number of Gemini models; each rewrite streams into its own card at the same time.
- Control thinking. Each model has its own thinking level, and you can add the
same model twice to compare, say,
gemini-4-neonat low against high. Thinking is usually most of the time and cost of a rewrite, so this is where the trade-offs are. - Timing and cost for every run. Time to first token, total time, input, output and thinking tokens, and the cost of the run, plus a running total for the session. Prices come from a built-in table (USD per 1M tokens); click a price to set your own, for models without a published price or when prices change.
- See what changed. Switch a card between the plain output, a word diff against the input, and a diff against that model's previous run, so you can see exactly what a tone edit did. Each card also shows the share of words reworded.
- Keep your tone. If
TOV_TONEpoints to a file, Save writes your edits back to it. Copy export copies anexport TOV_TONE='…'command, and History lists every tone you've run in this browser.
The server listens only on 127.0.0.1 and rejects requests from other websites.
Stop it with Ctrl-C.
Environment
| Variable | Purpose |
|---|---|
GEMINI_API_KEY |
Required. Your Gemini API key. |
TOV_TONE |
Default tone guidance (text or path). |
TOV_MODEL |
Default model. Defaults to gemini-3.8-flash. |
TOV_TIMEOUT |
Seconds to wait without hearing from Gemini before giving up. Defaults to 60. |
TOV_THINKING |
Thinking level: default, minimal, low, medium, high or xhigh. Defaults to low. |
The timeout is for a stalled connection: a long rewrite that keeps streaming is never cut off.
Models support different thinking levels (for example, gemini-4-neon has no
minimal). If a model rejects the level you asked for, tov uses the nearest one it
accepts and says so: on stderr from the command line, and on the card in the web UI.
default leaves the choice to the model.
The defaults, gemini-3.8-flash at low, are a good balance of quality, speed and
cost for rewriting. (gemini-3.8-flash doesn't accept minimal.)
Development
uv build # builds dist/tov-*.whl and .tar.gz
uv publish # uploads to PyPI (needs a PyPI token)
Bump __version__ in tov.py before each release.
evals/markdown_eval.py checks that rewrites keep the input's format: no Markdown
added to plain text, and none lost from Markdown input. Rerun it after changing the
system prompt:
uv run evals/markdown_eval.py # 5 runs per input with the default model
uv run evals/markdown_eval.py 20 gemini-3.8-flash low todo,md_link
Licence
MIT — see LICENSE.
Metadata
Release files for tov 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tov-0.2.0.tar.gz | 21.6 kB | Without provenance | Details for tov-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tov-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for tov-0.2.0-py3-none-any.whl |
Total release size: 43.9 kB
Release files / tov-0.2.0.tar.gz
| Download URL | tov-0.2.0.tar.gz |
|---|---|
| Size | 21.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
630db0416dd769e3ec5570a549f1e28be339842d087e603d891339af456cd615
|
|
BLAKE2b-256 checksum How to use checksums |
c8323a59f58e7da76bb9110e5d7a162528a1be2e705ab8c267a2072cc2e6aba5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tov-0.2.0-py3-none-any.whl
| Download URL | tov-0.2.0-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
acac9f5e1f375f506b314254f201324a3d1f506172a96fd1365c2d2d0db4f287
|
|
BLAKE2b-256 checksum How to use checksums |
697a0a0cad0f9fbe09a533b626d5ca00697c13e3868cd2898d2ad581df4ba13a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for tov 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.