clincalc 0.2.0

Open, auditable clinical calculators: a pure scoring engine plus the `calc` CLI in one crate. The engine is a serde-only leaf (build with default-features = false); the default `cli` feature adds the `calc` binary.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# CLI reference

Every mode and flag the `calc` binary supports, in one place. There are no per-calculator flags - the same surface drives all 42 calculators.

```text
calc [OPTIONS] [NAME]
```

## Modes

The shape of the invocation selects the mode:

| Invocation | What it does |
|---|---|
| `calc` (or `calc list`) | Print the calculator catalogue. |
| `calc <name>` | Print a fillable **input template** (JSON to stdout, hint to stderr). |
| `calc <name> --schema` | Print the calculator's full **JSON Schema** input contract. |
| `calc <name> --license` | Print the algorithm's distribution licence and evidence URL. |
| `calc <name> --input <src>` | **Compute** a result. `<src>` is `-` (stdin), a file path, or an inline JSON string. |
| `calc completions install` | Install shell completions for the current user. |

Computing always requires an explicit `--input`, so a bare `calc <name>` is pure discovery and will never block waiting on stdin.

## Options

### `--input <JSON|FILE|->`

Source of the input JSON. The argument is resolved in this order:

1. `-` reads the whole of standard input.
2. An existing file path is read from disk.
3. Anything else is treated as an inline JSON string.

```bash
calc news2 --input -                    # stdin
calc news2 --input examples/news2.json  # file
calc news2 --input '{"respiratory_rate":21, ...}'  # inline
```

Invalid JSON is rejected with a clear message and a non-zero exit; the reminder points you at `calc <name>` to see the expected shape.

### `--schema`

Print the calculator's JSON Schema to stdout. This is the formal input contract - field names, types, ranges, enumerations - and is the same schema served to LLMs by the MCP surface when `calc` is embedded in a host.

```bash
calc gad7 --schema
```

### `--license`

Print the algorithm's distribution licence (an SPDX identifier where one applies, otherwise a short description) plus a reverifiable URL, as a small JSON object:

```bash
calc qrisk3 --license
```

This is separate from the **code** licence (AGPL-3.0-or-later for the whole project) - it records the basis on which the **clinical algorithm itself** is being shipped.

### `--format <text|json>`

Output format for computed results and for `calc list`.

- `text` (default) - a clinician-facing block: result, interpretation, working, reference. Designed for the clipboard.
- `json` - the `CalculationResponse` structure as machine-readable JSON. The same shape every surface (CLI, MCP, GUI) produces.

```bash
calc list --format json
calc feverpain --input examples/feverpain.json --format json
```

### `--help`, `--version`

Standard. `--help` describes flags; `--version` prints the workspace version.

## Shell completions

Install completions for your current shell:

```bash
calc completions install
```

For package managers or custom locations, generate or write a specific shell's completion script:

```bash
calc completions bash
calc completions --dir ~/.local/share/bash-completion/completions bash
calc completions --dir ~/.zfunc zsh
calc completions --dir ~/.config/fish/completions fish
calc completions --dir ~/.config/powershell/completions powershell
```

The installer detects `$SHELL`, creates the completion directory, writes the correctly named file, and prints any one-time shell configuration still needed.

## The `CalculationResponse` shape

Every computed result, regardless of calculator, has the same JSON shape:

```json
{
  "calculator": "feverpain",
  "result": 3,
  "interpretation": "A score of 3 is associated with 34–40% isolation of streptococcus. ...",
  "working": {
    "score": 3,
    "level": "delayed",
    "...": "..."
  },
  "reference": "Little P, Stuart B, Hobbs FDR, et al. Lancet Infect Dis. 2014. ..."
}
```

- `calculator` - the machine name (matches the CLI subcommand and the MCP tool name).
- `result` - the primary computed value. A number for most scores, a short string for categorical results.
- `interpretation` - the clinician-facing summary line(s).
- `working` - every intermediate value the score depends on, so the result is auditable without re-running.
- `reference` - the primary citation.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success. (Includes proprietary-stub responses, which are valid `CalculationResponse` objects - they are *unavailable*, not errors.) |
| `1` | Anything else: unknown calculator, invalid JSON, schema mismatch, range violation. |

## Conventions

- Template / schema / compute output is on **stdout** as pure JSON or pure text - safe to redirect or pipe.
- Reminders and usage hints go to **stderr** so they never corrupt a stream.
- The CLI never reads stdin unless you ask for it (`--input -`).
- All output is deterministic - no timestamps, no random ids - so it diffs cleanly in tests and audits.

## Embedding in a host CLI

The same library that drives the `calc` binary is reusable as `clincalc::cli::run`, so a host CLI repeats nothing:

```rust
#[derive(clap::Subcommand)]
enum Commands {
    // ...
    /// Clinical calculators
    Calc(clincalc::cli::CalcCommand),
}

// dispatch:
Commands::Calc(cmd) => clincalc::cli::run(cmd)?,
```

GitEHR's `gitehr calc` subcommand is implemented exactly this way. See [How it works](how-it-works.md) for the wider architecture.