bounded-calcs 0.1.0__tar.gz

bounded_calcs-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+# Publishes to PyPI when a version tag such as v0.1.0 is pushed. Publishing a GitHub release
+# creates the tag, so that is the usual way to start it. Procedure: docs/RELEASING.md.
+#
+# No token is stored anywhere: PyPI trusts this workflow through Trusted Publishing, which is
+# configured once on pypi.org (project bounded-calcs, workflow publish.yml, environment pypi).
+#
+# Layout and action pins follow the official uv guide
+# (https://docs.astral.sh/uv/guides/integration/github/). Actions are pinned to commits
+# because the publish job can upload to PyPI; update a pin only to a tagged release.
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Test and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: The tag must match the version in pyproject.toml
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $version in pyproject.toml"
+            exit 1
+          fi
+      - name: Run the tests
+        run: |
+          uv sync --locked
+          uv run pytest -q
+      - name: Build the sdist and the wheel
+        run: uv build
+      - name: Smoke-test both distributions as installed packages
+        run: |
+          uv run --isolated --no-project --with dist/*.whl --with "mcp>=2,<3" scripts/smoke_test.py
+          uv run --isolated --no-project --with dist/*.tar.gz --with "mcp>=2,<3" scripts/smoke_test.py
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/bounded-calcs/
+    permissions:
+      id-token: write # lets PyPI verify that the upload comes from this workflow
+    steps:
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: Publish with Trusted Publishing
+        run: uv publish

bounded_calcs-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/

bounded_calcs-0.1.0/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md — bounded-calcs
+
+Clinical calculators that treat **unknown as unknown**: one YAML spec per calculator, an exact
+bounding engine, a Python library and an MCP server. Companion to the paper repo
+`nicoveraz/calc-bounds` (arXiv:2609.34112). Research and reference tool, not a medical device.
+
+These instructions are written so that a small model can extend the repo safely. Follow them
+literally. When they do not cover a situation, stop and ask; do not improvise.
+
+## Start here
+
+| Task | Read first |
+|---|---|
+| Add a calculator | `docs/ADDING_A_CALCULATOR.md`, then follow it step by step |
+| Choose what to build | `docs/ROADMAP.md`: take the first item marked **ready**, one at a time, and read the GitHub issue it links to |
+| Understand the engine | README "How it works"; docstrings of `spec.py`, `engine.py`, `testing.py` |
+| Prepare a release | `docs/RELEASING.md`, and only when the user asks for a release |
+
+## Hard rules
+
+1. **Unknown is never absent or normal.** No defaults for missing items, in code, specs,
+   tests or examples.
+2. **No clinical criteria from memory.** Every item, threshold, inequality (`>` or `>=`),
+   point value and category cut-off comes from a source you opened in this session. If you
+   cannot open a source, stop and ask the user for it (they can attach the PDF).
+3. **Say how each source was verified.** End every citation with `[P]` (primary full text
+   read), `[A]` (abstract only) or `[S]` (secondary source, such as NICE or a later paper).
+4. **Mark what is uncertain.** For an ambiguous or unverifiable criterion, implement the best
+   reading and add an item note that starts with `TODO(physician-review):` and gives the
+   reading chosen and the alternative. Only the user changes a `TODO(physician-review)` into
+   `REVIEWED(physician)`. Never write `REVIEWED(physician)` yourself, unless a roadmap entry
+   tells you to carry over a reading that calc-bounds already records as reviewed.
+5. **Two independent implementations.** Every calculator has a `reference(v)` function in
+   `tests/calculators/test_<id>.py`, written from the source and not from the YAML, and checked
+   with `assert_matches_reference`. When the two disagree, re-read the source. Never copy one
+   side into the other to make the test pass.
+6. **Expected values come from the source, by hand.** Never run the engine and paste its
+   output into a test as the expected value.
+7. **Never weaken a check to get green.** Do not edit or delete existing tests, loosen the
+   validation in `spec.py`, or change `testing.py` to make something pass. If a check looks
+   wrong, stop and ask.
+8. **Engine and format are frozen unless the user approves.** Adding a calculator touches only
+   the files listed in "What a calculator consists of". Do not change `engine.py`, `spec.py`,
+   `testing.py`, `mcp_server.py`, the YAML format or the names of output fields (they are a
+   public API). If a calculator does not fit the format, stop and ask.
+9. **Deterministic core.** No LLM calls, network access or randomness in `src/`.
+10. **No real patient data** anywhere: specs, tests, examples, commit messages.
+11. **No claims of clinical validity.** Never write that this is validated, safe for clinical
+    use or a medical device.
+12. **Dependencies:** `pyyaml` (runtime), `mcp>=2,<3` (optional extra), `pytest` (dev). Ask
+    before adding anything else.
+
+## When to stop and ask
+
+- You cannot open the primary source, and the scoring table is not in an abstract or a
+  secondary source you can open.
+- The score exists in versions (two-tier or three-tier, original or modified) and the roadmap
+  does not say which one.
+- The calculator needs something the format lacks: an item used by two components,
+  categories that depend on anything other than the total score, a continuous formula, or
+  points that are not whole or half numbers.
+- A test you did not write fails, or a fix seems to need a change in `src/` outside `specs/`.
+- Sources disagree in a way that changes a category for some patient and you cannot tell
+  which reading the roadmap intends.
+- You are about to push, publish, tag a release or change repository settings.
+
+## What a calculator consists of
+
+Adding calculator `<id>` creates or edits exactly these files:
+
+| File | Change |
+|---|---|
+| `src/bounded_calcs/specs/<id>.yaml` | new: the spec |
+| `tests/calculators/test_<id>.py` | new: reference function, threshold tests, clinical examples |
+| `README.md` | one row in the calculator table |
+| `docs/ROADMAP.md` | move the item to the "Built" table |
+
+Nothing else. The MCP server and the generic tests pick up new specs automatically.
+
+## Layout
+
+```
+src/bounded_calcs/
+  spec.py         YAML format, strict validation (rejects typos, bad band order, bad YAML text)
+  engine.py       evaluate(): bounds, possible categories, decisive unknowns; schema()
+  testing.py      assert_matches_reference(): spec and engine against an independent reference
+  mcp_server.py   MCP tools: list_calculators, get_schema, evaluate
+  specs/*.yaml    one calculator each (file name = id)
+tests/
+  calculators/    one test file per calculator (copy test_curb65.py for a new one)
+  test_builtin_specs.py   rules every built-in calculator must satisfy
+  test_spec.py, test_engine.py, test_testing.py, test_mcp.py
+docs/
+  ADDING_A_CALCULATOR.md  the procedure
+  ROADMAP.md              what is built, what is next, open decisions
+  RELEASING.md            how a version reaches PyPI
+scripts/smoke_test.py     checks a built wheel or sdist as an installed package
+.github/workflows/publish.yml   tests, builds and publishes when a version tag is pushed
+```
+
+## Commands
+
+```sh
+uv sync                                          # install (pytest and the MCP SDK included)
+uv run pytest                                    # everything; must be green before a commit
+uv run pytest tests/calculators/test_<id>.py -x  # one calculator while working
+uv run python -c "from bounded_calcs import load_builtin; print(list(load_builtin()))"
+uv run bounded-calcs-mcp                         # MCP server on stdio
+grep -rn "TODO(physician-review)" src/bounded_calcs/specs/   # open review items
+```
+
+The MCP SDK is version 2: `from mcp.server import MCPServer`, tool errors via
+`mcp.server.mcpserver.exceptions.ToolError`. Version 1 `FastMCP` examples do not apply. Check
+an API by importing it before you use it.
+
+## Working style
+
+- One calculator per commit. Subject: `Add <name> (<id>)`. Body: sources with their `[P]`,
+  `[A]`, `[S]` tags, each `TODO(physician-review)` note you added, and a last line
+  `Closes #N` with the number of the item's issue.
+- Give your report in your reply. Comment on an issue, or change its labels, only when the
+  user asks.
+- Do not refactor, rename or "improve" anything outside the task.
+- Everything in the repository is written in English: code, specs, docs, commit messages.
+- Run `uv run pytest` before every commit and read the output. A commit with a failing or
+  skipped test is not done.
+- Push only when the user asks. The default branch is `main`.
+- End every task with this report:
+  1. What you added (files).
+  2. Sources and how each was verified (`[P]`, `[A]`, `[S]`), and what you could not open.
+  3. The scoring table you built in step 2 of the procedure.
+  4. The last line of `uv run pytest`.
+  5. Every `TODO(physician-review)` note you added, quoted in full.
+  6. Anything you were unsure about.
+- After a roadmap item, stop. Start the next one only when the user says so.

bounded_calcs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolás Vera Zúñiga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bounded_calcs-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: bounded-calcs
+Version: 0.1.0
+Summary: Clinical risk calculators that treat unknown as unknown: exact score bounds, settled or unsettled decisions, and the questions worth asking. Python library and MCP server. Research use, not a medical device.
+Project-URL: Homepage, https://github.com/nicoveraz/bounded-calcs
+Project-URL: Repository, https://github.com/nicoveraz/bounded-calcs
+Project-URL: Issues, https://github.com/nicoveraz/bounded-calcs/issues
+Project-URL: Paper, https://arxiv.org/abs/2609.34112
+Author: Nicolás Vera Zúñiga
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clinical decision support,emergency medicine,llm,mcp,medical calculators,missing data,model context protocol,risk scores
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# bounded-calcs
+
+Clinical calculators that treat **unknown as unknown**.
+
+Most calculator tools, and the LLM benchmarks built on them, take a complete input. When a
+note doesn't mention a finding, someone fills it in as absent or normal, and the calculator
+returns a confident number. `bounded-calcs` instead accepts **present / absent / unknown** for
+every item and returns:
+
+- whether the decision category is **settled** by what is known,
+- every category still **possible**, and the **worst case**,
+- the exact **score range**,
+- the **decisive unknowns**: the only items worth asking the clinician about, with what the
+  category would be for each possible answer.
+
+It packages the approach from *Unknown is not normal: separating language-model extraction
+from rule-based decision logic for clinical risk scores*
+([arXiv:2609.34112](https://arxiv.org/abs/2609.34112); experiment code:
+[calc-bounds](https://github.com/nicoveraz/calc-bounds)): the LLM only reads the note;
+deterministic code decides whether the missing items matter.
+
+> **Research and reference use only.** Not a medical device. The built-in definitions were
+> reviewed by one emergency physician (the author); several sources were read only as
+> abstracts or through secondary sources, as each spec states.
+
+## Install
+
+```bash
+pip install bounded-calcs            # the library
+pip install "bounded-calcs[mcp]"     # the library and the MCP server
+```
+
+Python 3.11 or later. The MCP server can also run without installing anything first: see
+[MCP server](#mcp-server).
+
+## Calculators
+
+| id | Calculator | Source | Verified |
+|---|---|---|---|
+| `heart` | HEART score (low / moderate / high) | Six et al., Neth Heart J 2008. PMID 18665203 | [P] |
+| `wells_pe` | Wells criteria for PE, two-tier (unlikely / likely) | Wells et al., Thromb Haemost 2000. PMID 10744147 | [A], [S] |
+| `perc` | PERC rule (negative / positive) | Kline et al., J Thromb Haemost 2004. PMID 15304025 | [A] |
+| `curb65` | CURB-65 (low / moderate / high) | Lim et al., Thorax 2003. PMID 12728155 | [P] |
+
+Verified: **[P]** primary full text read, **[A]** abstract only, **[S]** secondary source
+(guideline or later paper). All four are ported from calc-bounds, whose readings the author
+reviewed and accepted (`docs/CALCULATOR_NOTES.md` there). Item notes in each spec record the
+reading implemented and the alternatives: `REVIEWED(physician)` marks a reading a physician
+accepted, `TODO(physician-review)` one that is still open.
+
+Every calculator is checked against an independent reference function on all complete
+inputs, including each numeric threshold, and on partial inputs by brute force.
+
+## Example
+
+A note documents heart rate 110, no haemoptysis, no malignancy, and says nothing else:
+
+```python
+from bounded_calcs import load_builtin, evaluate
+
+wells = load_builtin()["wells_pe"]
+r = evaluate(wells, {"heart_rate": 110, "hemoptysis": "absent", "malignancy": "absent"})
+```
+
+```json
+{
+  "settled": false,
+  "possible_categories": ["pe_unlikely", "pe_likely"],
+  "worst_case_category": "pe_likely",
+  "score_range": [1.5, 10.5],
+  "decisive_unknowns": [
+    {"item": "dvt_signs", "kind": "finding", "settles_decision_in": "1 of 2 answers", "...": "..."},
+    {"item": "pe_most_likely", "kind": "judgment", "settles_decision_in": "1 of 2 answers", "...": "..."}
+  ],
+  "jointly_relevant_unknowns": ["immobilization_or_surgery", "prior_vte"],
+  "judgment_items_pending": ["pe_most_likely"]
+}
+```
+
+Filling the silence with "absent" would have returned *PE unlikely*. The honest answer is
+that it depends on two things the note doesn't say, one of which only the clinician can judge.
+
+## Inputs
+
+- **boolean** items: `"present"`, `"absent"` (or `true` / `false`)
+- **ordinal** items: one of the listed levels
+- **numeric** items: a number in the item's unit
+- anything omitted, `null`, or `"unknown"` is unknown, **never** normal
+- a numeric item the source only calls "normal", with no number, is also unknown
+
+Each item also has a **kind**: `finding` (readable from a note), `measurement` (vitals, labs,
+age) or `judgment` (clinician only, e.g. HEART history, Wells "alternative diagnosis less
+likely"). Clients should never infer judgment items from text.
+
+### Unknown categories in the output
+
+| field | meaning |
+|---|---|
+| `decisive_unknowns` | knowing this item alone could narrow the possible categories; ask these, in order |
+| `jointly_relevant_unknowns` | can move the score but cannot change the category on its own; may matter together |
+| `irrelevant_unknowns` | cannot change the category (always the case for every unknown once settled) |
+
+## MCP server
+
+Runs over stdio by default, so notes stay on the machine. With
+[uv](https://docs.astral.sh/uv/) installed, one command fetches and starts it:
+
+```bash
+uvx --from "bounded-calcs[mcp]" bounded-calcs-mcp
+```
+
+Claude Desktop / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "bounded-calcs": {
+      "command": "uvx",
+      "args": ["--from", "bounded-calcs[mcp]", "bounded-calcs-mcp"]
+    }
+  }
+}
+```
+
+From a clone of this repository, use `"command": "uv"` with
+`"args": ["--directory", "/path/to/bounded-calcs", "run", "bounded-calcs-mcp"]`.
+
+Tools: `list_calculators`, `get_schema(calculator_id)`, `evaluate(calculator_id, findings)`.
+The server's instructions tell the model to send only documented findings, ask about
+decisive unknowns, and never fill judgment items itself.
+
+## Adding a calculator
+
+Each calculator is one YAML file in `src/bounded_calcs/specs/`: items (type, kind, levels or
+unit, a question to ask), components (how items become points), and categories. Component
+rules: `present`, `absent`, `levels`, `bands` (numeric thresholds), `count` (number of present
+items, with an optional override item), and `any_of` (points if any of several conditions is
+met, such as CURB-65's "SBP < 90 or DBP <= 60"). Points may be negative. Every item belongs to
+exactly one component; that is what makes the bounds exact rather than approximate. The
+loader is strict: misspelled keys, bands that can never match and text that YAML misread are
+errors.
+
+The procedure is in [`docs/ADDING_A_CALCULATOR.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/docs/ADDING_A_CALCULATOR.md), the
+queue in [`docs/ROADMAP.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/docs/ROADMAP.md), and the rules for AI coding agents in
+[`CLAUDE.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/CLAUDE.md). In short: take every criterion from the primary source, write the
+spec and an independent reference function, and let `assert_matches_reference` compare them:
+
+```python
+from bounded_calcs import load_file
+from bounded_calcs.testing import assert_matches_reference
+
+def reference(v):   # written from the paper, not from the YAML
+    score = v["confusion"] + (v["urea"] > 7) + (v["resp_rate"] >= 30) \
+        + (v["sbp"] < 90 or v["dbp"] <= 60) + (v["age"] >= 65)
+    return score, "low" if score <= 1 else "moderate" if score == 2 else "high"
+
+assert_matches_reference(load_file("curb65.yaml"), reference)
+```
+
+## How it works
+
+Components are independent, so the reachable scores are exactly the sumset of each
+component's reachable points; there is no sampling and no LLM in the loop. An unknown item is
+decisive if some value of it removes at least one category from the possible set. Decisive
+items are ordered by how often an answer settles the decision, then by how much it narrows on
+average, with data items before judgments when otherwise equal.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+Releases are published to PyPI by a GitHub Actions workflow when a version tag is pushed:
+[`docs/RELEASING.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/docs/RELEASING.md).
+
+Each calculator has its own test file with an independent reference function, threshold
+cases taken from the source, and sparse-note examples. Other tests cover the spec loader's
+validation, input handling, every rule type, an end-to-end MCP session, and that the
+reference check itself fails on a wrong spec.
+
+## License
+
+MIT

bounded_calcs-0.1.0/README.md

@@ -0,0 +1,185 @@
+# bounded-calcs
+
+Clinical calculators that treat **unknown as unknown**.
+
+Most calculator tools, and the LLM benchmarks built on them, take a complete input. When a
+note doesn't mention a finding, someone fills it in as absent or normal, and the calculator
+returns a confident number. `bounded-calcs` instead accepts **present / absent / unknown** for
+every item and returns:
+
+- whether the decision category is **settled** by what is known,
+- every category still **possible**, and the **worst case**,
+- the exact **score range**,
+- the **decisive unknowns**: the only items worth asking the clinician about, with what the
+  category would be for each possible answer.
+
+It packages the approach from *Unknown is not normal: separating language-model extraction
+from rule-based decision logic for clinical risk scores*
+([arXiv:2609.34112](https://arxiv.org/abs/2609.34112); experiment code:
+[calc-bounds](https://github.com/nicoveraz/calc-bounds)): the LLM only reads the note;
+deterministic code decides whether the missing items matter.
+
+> **Research and reference use only.** Not a medical device. The built-in definitions were
+> reviewed by one emergency physician (the author); several sources were read only as
+> abstracts or through secondary sources, as each spec states.
+
+## Install
+
+```bash
+pip install bounded-calcs            # the library
+pip install "bounded-calcs[mcp]"     # the library and the MCP server
+```
+
+Python 3.11 or later. The MCP server can also run without installing anything first: see
+[MCP server](#mcp-server).
+
+## Calculators
+
+| id | Calculator | Source | Verified |
+|---|---|---|---|
+| `heart` | HEART score (low / moderate / high) | Six et al., Neth Heart J 2008. PMID 18665203 | [P] |
+| `wells_pe` | Wells criteria for PE, two-tier (unlikely / likely) | Wells et al., Thromb Haemost 2000. PMID 10744147 | [A], [S] |
+| `perc` | PERC rule (negative / positive) | Kline et al., J Thromb Haemost 2004. PMID 15304025 | [A] |
+| `curb65` | CURB-65 (low / moderate / high) | Lim et al., Thorax 2003. PMID 12728155 | [P] |
+
+Verified: **[P]** primary full text read, **[A]** abstract only, **[S]** secondary source
+(guideline or later paper). All four are ported from calc-bounds, whose readings the author
+reviewed and accepted (`docs/CALCULATOR_NOTES.md` there). Item notes in each spec record the
+reading implemented and the alternatives: `REVIEWED(physician)` marks a reading a physician
+accepted, `TODO(physician-review)` one that is still open.
+
+Every calculator is checked against an independent reference function on all complete
+inputs, including each numeric threshold, and on partial inputs by brute force.
+
+## Example
+
+A note documents heart rate 110, no haemoptysis, no malignancy, and says nothing else:
+
+```python
+from bounded_calcs import load_builtin, evaluate
+
+wells = load_builtin()["wells_pe"]
+r = evaluate(wells, {"heart_rate": 110, "hemoptysis": "absent", "malignancy": "absent"})
+```
+
+```json
+{
+  "settled": false,
+  "possible_categories": ["pe_unlikely", "pe_likely"],
+  "worst_case_category": "pe_likely",
+  "score_range": [1.5, 10.5],
+  "decisive_unknowns": [
+    {"item": "dvt_signs", "kind": "finding", "settles_decision_in": "1 of 2 answers", "...": "..."},
+    {"item": "pe_most_likely", "kind": "judgment", "settles_decision_in": "1 of 2 answers", "...": "..."}
+  ],
+  "jointly_relevant_unknowns": ["immobilization_or_surgery", "prior_vte"],
+  "judgment_items_pending": ["pe_most_likely"]
+}
+```
+
+Filling the silence with "absent" would have returned *PE unlikely*. The honest answer is
+that it depends on two things the note doesn't say, one of which only the clinician can judge.
+
+## Inputs
+
+- **boolean** items: `"present"`, `"absent"` (or `true` / `false`)
+- **ordinal** items: one of the listed levels
+- **numeric** items: a number in the item's unit
+- anything omitted, `null`, or `"unknown"` is unknown, **never** normal
+- a numeric item the source only calls "normal", with no number, is also unknown
+
+Each item also has a **kind**: `finding` (readable from a note), `measurement` (vitals, labs,
+age) or `judgment` (clinician only, e.g. HEART history, Wells "alternative diagnosis less
+likely"). Clients should never infer judgment items from text.
+
+### Unknown categories in the output
+
+| field | meaning |
+|---|---|
+| `decisive_unknowns` | knowing this item alone could narrow the possible categories; ask these, in order |
+| `jointly_relevant_unknowns` | can move the score but cannot change the category on its own; may matter together |
+| `irrelevant_unknowns` | cannot change the category (always the case for every unknown once settled) |
+
+## MCP server
+
+Runs over stdio by default, so notes stay on the machine. With
+[uv](https://docs.astral.sh/uv/) installed, one command fetches and starts it:
+
+```bash
+uvx --from "bounded-calcs[mcp]" bounded-calcs-mcp
+```
+
+Claude Desktop / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "bounded-calcs": {
+      "command": "uvx",
+      "args": ["--from", "bounded-calcs[mcp]", "bounded-calcs-mcp"]
+    }
+  }
+}
+```
+
+From a clone of this repository, use `"command": "uv"` with
+`"args": ["--directory", "/path/to/bounded-calcs", "run", "bounded-calcs-mcp"]`.
+
+Tools: `list_calculators`, `get_schema(calculator_id)`, `evaluate(calculator_id, findings)`.
+The server's instructions tell the model to send only documented findings, ask about
+decisive unknowns, and never fill judgment items itself.
+
+## Adding a calculator
+
+Each calculator is one YAML file in `src/bounded_calcs/specs/`: items (type, kind, levels or
+unit, a question to ask), components (how items become points), and categories. Component
+rules: `present`, `absent`, `levels`, `bands` (numeric thresholds), `count` (number of present
+items, with an optional override item), and `any_of` (points if any of several conditions is
+met, such as CURB-65's "SBP < 90 or DBP <= 60"). Points may be negative. Every item belongs to
+exactly one component; that is what makes the bounds exact rather than approximate. The
+loader is strict: misspelled keys, bands that can never match and text that YAML misread are
+errors.
+
+The procedure is in [`docs/ADDING_A_CALCULATOR.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/docs/ADDING_A_CALCULATOR.md), the
+queue in [`docs/ROADMAP.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/docs/ROADMAP.md), and the rules for AI coding agents in
+[`CLAUDE.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/CLAUDE.md). In short: take every criterion from the primary source, write the
+spec and an independent reference function, and let `assert_matches_reference` compare them:
+
+```python
+from bounded_calcs import load_file
+from bounded_calcs.testing import assert_matches_reference
+
+def reference(v):   # written from the paper, not from the YAML
+    score = v["confusion"] + (v["urea"] > 7) + (v["resp_rate"] >= 30) \
+        + (v["sbp"] < 90 or v["dbp"] <= 60) + (v["age"] >= 65)
+    return score, "low" if score <= 1 else "moderate" if score == 2 else "high"
+
+assert_matches_reference(load_file("curb65.yaml"), reference)
+```
+
+## How it works
+
+Components are independent, so the reachable scores are exactly the sumset of each
+component's reachable points; there is no sampling and no LLM in the loop. An unknown item is
+decisive if some value of it removes at least one category from the possible set. Decisive
+items are ordered by how often an answer settles the decision, then by how much it narrows on
+average, with data items before judgments when otherwise equal.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+Releases are published to PyPI by a GitHub Actions workflow when a version tag is pushed:
+[`docs/RELEASING.md`](https://github.com/nicoveraz/bounded-calcs/blob/main/docs/RELEASING.md).
+
+Each calculator has its own test file with an independent reference function, threshold
+cases taken from the source, and sparse-note examples. Other tests cover the spec loader's
+validation, input handling, every rule type, an end-to-end MCP session, and that the
+reference check itself fails on a wrong spec.
+
+## License
+
+MIT