Developers

Installing and running cadence from the shell, from Python and as an MCP server. What the two numbers measure is on the Method page, and the grammar they rest on is defined under Concepts.

Install

pip install "cadence-writer[llm]"
cadence download-model # English
cadence download-model --lang all # English, Spanish and Portuguese

The spaCy models are a separate step because PyPI rejects packages that declare a dependency by URL, and the models are only distributed that way. download-model wraps python -m spacy download en_core_web_sm, which you can run instead; --lang es and --lang pt fetch the other two.

Extras: llm adds the Anthropic client, web adds the site, dev adds the test and lint tooling. The core install needs only spaCy, and everything that does not call a model works without a key.

Set ANTHROPIC_API_KEY, or pass api_key= to any call that reaches a model.

Languages

cadence measures English, Spanish and Portuguese. A tone has a language, chosen when it is saved, and everything follows from it: the writing is parsed in that language, the specification says which language it describes, and the model is told to write in it. On the demo page the language is read off the writing unless you pick one. The measurements are the same in all three; what changes underneath is the parser, and the words the content check counts as negations, relative dates and spelled-out numbers.

cadence profile cartas/*.txt --lang es
cadence restyle borrador.txt --corpus cartas/*.txt --lang es

profile = cadence.build_profile(cartas, name="yo", lang="es")
cadence.guess_language(texto) # "en", "es" or "pt"

Over MCP, measure_voice, restyle, check_fidelity, score and analyze_text take a language argument, and the hosted server's list_tones reports each tone's.

Command line

cadence analyze notes.txt # trees and findings, no rewrite
cadence report notes.txt # everything, including fidelity
cadence rewrite notes.txt --backend rules # deterministic, no API call
cadence profile samples/*.txt # the specification for a corpus
cadence restyle draft.txt --corpus samples/*.txt
cadence compose topic.txt --corpus samples/*.txt
cadence score out.txt --corpus samples/*.txt --source-text draft.txt

restyle and compose take --mode, which selects what the model is given:

Exit codes: 0 success, 2 bad input, 3 spaCy model missing, 4 no credentials.

Python

import cadence

profile = cadence.build_profile(my_documents, name="me")
result = cadence.generate(draft, mode="profile", profile=profile,
 task="restyle", api_key=key)

print(result.similarity) # voice match, 0 to 100
print(result.fidelity.score) # content kept, 0 to 100
print(result.fidelity.introduced) # anything invented, which should be empty

cadence.score(text, profile, source=draft) returns both numbers in one object along with the caveats that belong beside them. cadence.analyze(text) returns findings without touching a model. cadence.rewrite(analysis, backend="rules") applies the deterministic repairs and nothing else.

Everything raises cadence.ModelNotInstalled or cadence.MissingAPIKey rather than exiting, so it embeds in a server.

As an MCP server

pip install "cadence-writer[mcp]"
cadence mcp

That serves the library over stdio for Claude Desktop, Claude Code, or any other MCP client, so a model can measure a voice, restyle a draft and check fidelity as tools. Nothing leaves your machine except the model call the restyle tool makes. In Claude Code, claude mcp add cadence -- cadence mcp registers it.

Tools: measure_voice, analyze_text, restyle, check_fidelity, score, repair_structure. Each one is a library function with its arguments flattened. Where a tool takes a corpus it takes the documents themselves, so the server holds no state a client has to manage.

The hosted MCP server

Signed in, the Connect page mints a token and shows the install command for Claude Code, the JSON for Claude Desktop, and the URL and header for any other client. The server runs here at /mcp; there is nothing to install.

What it adds over the local server is state. It already knows the account's saved tones, so restyle takes a draft and a tone name and nothing else. It charges the account's credits at the same rate as the panel, records each restyle where the panel lists them, and refunds a call that fails. list_tones, tone_spec, quote, balance, check_fidelity and analyze_text are free.

Tokens are stored as hashes, shown once, and revocable one at a time.

The two numbers

Every command that reaches a model returns two scores. Voice match, 0 to 100, is how close the output's sentence shapes sit to the corpus profile. Content kept, 0 to 100, is how much of the source's names, numbers, dates and coverage survived, and it comes with a pass or fail verdict that is stricter than the score. Both are defined on the Method page. A rewrite may fix structure and may not invent content: anything the analysis finds missing is reported as a gap and left missing.