# Developers

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

## Install

```bash
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.

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

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

```bash
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:

| Mode | What the model sees | Calls |
|---|---|---|
| `tone` | Your raw samples, plus "write like this" | 1 |
| `profile` | The measured specification only, never the samples | 1 |
| `profile_verify` | The spec, then its own output's measured deviations | 1 + iterations |
| `compare` | All three, so they can be read blind | 5 |

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

## Python

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

```bash
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](/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.