Check HCC codes for MEAT evidence · Decosa Clinics

Use it from your codeThe hosted API with your key, and prompts to paste into a coding agent

Self-host · your GPUs · recommended

Run it yourself, on request

The same open models and app, on 1× RTX PRO 6000 (96 GB) or 1× RTX 5090 (32 GB) for Qwen3.8-27B; the V28 map, the record checks and the signed record run on CPU.
Data never leaves your machines, and there are no Decosa charges.
One prompt for Claude Code or Codex assembles the whole stack.
Early access: the container images are not public yet and the source needs access; the prompt says how to ask.

Get the assembly prompt

Hosted · by Decosa

Get an API key

Call the hcc evidence file and radv defence API from your own code in minutes.
Every model answer carries a signed receipt.
Synthetic, public or test data only: real patient data belongs on your own hardware.

Build with it

Paste one of these into Claude Code, Codex or another coding agent. The first wires your project to the hosted API with your DECOSA_API_KEY. The second pulls our containers and runs the same stack on your own GPU, with no Decosa charges.

Base URL: https://api.decosa.ai
Auth: Authorization: Bearer $DECOSA_API_KEY (or a demo session token)
Tool id: hcc-evidence-file

Use the hosted API

# Decosa HCC evidence file: use the hosted API (synthetic members only)

You are wiring Decosa's HCC evidence file into this project. For one member and service year it takes the diagnosis
codes the plan submitted and the member's notes, and for each code that maps to a CMS-HCC V28 payment HCC it says
supported (keep), insufficient (hold for a certified coder) or not supported (delete: do not submit), with the MEAT
sentences (monitor, evaluate, assess, treat) quoted from the notes or their absence stated. It checks each note and
addendum as a RADV reviewer would, reports the net effect, and returns a Markdown evidence file and a record signed by
the server, with a signed receipt for every model call. Use only what is listed below. If you need something else, stop
and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- **The hosted API takes synthetic members only.** Clinical notes are protected health information. Every request must
  carry `"synthetic": true`; anything else gets HTTP 400. Real members belong on a self-hosted box (see the self-host
  prompt). Never send real names, member ids or notes here.
- It checks only the codes you submit. It has no mode that searches notes for codes to add, suggests codes or drafts
  provider queries, and a request with fields such as `mode`, `suggest`, `find`, `opportunities` or `gaps` gets HTTP 400.
  Do not build that feature around it. Show deletions at least as prominently as confirmations, and say that a certified
  coder decides.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "hcc-evidence-file"}` returns `{"token", "expires_at", "budget"}`.
   Sessions per IP are limited; over a limit you get HTTP 429 with `Retry-After`.
3. A member needs about 800 generated tokens of budget per code that maps to an HCC (402 otherwise). One review at a
   time per demo token (409 while one is going).

## Endpoints
- `POST /hcc/review` (token). Body:
  ```json
  {"member": {"id": "SYN-1", "service_year": 2025},
   "codes": ["E11.22", "I50.22"],
   "notes": [{"id": "N1", "date": "2025-03-14", "kind": "physician", "provider": "...", "credential": "MD",
              "specialty": "Internal Medicine", "signed": {"by": "...", "credential": "MD", "date": "2025-03-14"},
              "addenda": [{"date": "2025-04-01", "by": "...", "credential": "MD", "text": "..."}], "text": "..."}],
   "synthetic": true, "stream": false}
  ```
  `kind`: physician, hospital_outpatient, hospital_inpatient, telehealth_video, telehealth_audio, diagnostic_report, lab,
  home_health, hospice, superbill, other. Up to 20 codes and 12 notes (12,000 characters each, 60,000 in total).
  `{"sample": "mixed-file", "synthetic": true}` runs a built-in sample.
- JSON answer: `{status: deletions | holds | all_supported, net_effect: {codes: {submitted, delete, hold, keep,
  not_reviewed}, hccs: {rows: [{hcc, label, outcome, codes}]}, text}, codes: [{code, dotted, description, hccs, verdict:
  not_supported | insufficient | supported, action: delete | hold | keep, reasons, summary, records: [{note, valid,
  issues, quotes: [{id, meat, text, start, end}], typed, grounding}]}] (deletions first), not_reviewed, notes (with the
  RADV record checks), guard, receipts, evidence_file_md, record}`.
- SSE: send `Accept: text/event-stream` (or `"stream": true`): `ready`, `receipt`, `code` (one per code), `report`,
  `budget`, `done`.
- `POST /hcc/codes` (no token, no model): `{codes: [...]}` → V28 payment HCCs and the ones that pay after the hierarchies.
- `POST /hcc/records` (no token, no model): the review body → the RADV record check for every note and addendum.
- `POST /record/verify` (no token): the `record` → `{ok, checks, summary}`.
- `GET /hcc/info`, `GET /hcc/samples` (no token): the rules, the V28 table's source, limits, sources and three samples.

## Errors
400 bad input (the message names the field or limit, says the member is not marked synthetic, or that no code maps to a
V28 HCC, or refuses an add mode), 401/403 token, 402 budget, 409 a review already going on this demo token, 413 body
over 256 KB, 429 busy (`Retry-After`).

Run it yourself (containers)

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa HCC evidence file: run it yourself (containers)

You are setting up the Decosa HCC evidence file on this machine, so clinical notes never leave it. For each diagnosis
code a plan submitted for a member it says keep, hold or delete, with the MEAT sentences quoted from the notes or their
absence stated, checks each record as a RADV reviewer would, and returns the net effect, a Markdown evidence file and a
signed record. It checks only the submitted codes and never suggests codes to add. Nothing is sent to Decosa's hosted
API. It is a review aid: certified coders decide.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
"test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
https://decosa.ai/samples/hcc-evidence-file.zip (3 KB, 15 checks, synthetic or openly licensed: see `licence` in expected.json),
show me what is in it, and run the rehearsal against the local API:
`docker compose exec api python scripts/rehearse.py hcc-evidence-file` (the api image carries the same bundle under /app/rehearsal/hcc-evidence-file/;
with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
`python scripts/rehearse.py hcc-evidence-file --bundle hcc-evidence-file.zip --base-url http://127.0.0.1:<PORT>`.
It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the 2021 heart attack coded as acute is not supported (delete)", "breast cancer treated in 2016 is not supported (delete)", "morbid obesity is held: its only evidence is an audio-only call"). Show me
the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
instructions for this distribution (docs.docker.com/engine/install). Install the NVIDIA container toolkit and check
`docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
`mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
Read it. Keep the `llm` service (Qwen3.8-27B on vLLM, with prefix caching on) and the `api` service. For the `api`
service set `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b`,
`DECOSA_HCC_SYNTHETIC_ONLY=0` (so this box accepts real members) and bind every port to 127.0.0.1. Never set the
gateway route on this box: it would send PHI to the Decosa API.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
downloads about 20 GB of weights).
4. Check: `curl -fsS http://127.0.0.1:<PORT>/hcc/info` shows `synthetic_only: false`, `judgment_method: "logprobs"` and
the V28 table's source; `GET /attest/signing-key` shows this box's public key. Show me the key: it is what an auditor
pins to verify my records.
5. Smoke test: get a token with `POST /demo/session {"vertical":"hcc-evidence-file"}` and send
`{"sample": "mixed-file", "synthetic": true}` to `POST /hcc/review`. Expect I21.4 and C50.911 deleted (history),
E66.01 and J44.9 held with reason `invalid_record` (an audio-only call, a diagnostic radiologist's report), E11.22 and
I50.22 kept with quotes, and I10 under `not_reviewed`. Send the record to `POST /record/verify`: `ok` must be true.
Send the same request with `"mode": "opportunities"`: it must be refused with 400.
6. Report back: the public key, the net effect, the held and deleted codes with their reasons, and how long it took.

Off by default. Joining as a provider serves other people's requests on this GPU; never do it on a box that holds PHI.
If I ask for it later, follow the Provide page instead of improvising.

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/hcc-evidence-file-mac.md instead.

Run it on your own hardwareWhat it needs, and the prompt that sets it up

Run it on your own GPU

Same app, same pinned models, your hardware. Nothing goes to our servers and there are no Decosa charges.

Hardware check

Check your own hardware

CPU only, 64 GB RAMlite tierRuns with a smaller tier
The standard tier does not fit: Qwen3.8-27B (NVFP4) needs a GPU. The lite tier fits.
GeForce RTX 4090standard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVFP4) with A community 4-bit build of Qwen3.8-27B (AWQ or GGUF). This build is NVIDIA NVFP4, which needs a Blackwell GPU. (Memory is an estimate.)
GeForce RTX 5090standard tierRuns
The standard tier fits with changes: Qwen3.8-27B (NVFP4): run it at its smallest setting (about 28 GB instead of 57.6 GB), with a shorter context and fewer parallel sessions.
2x GeForce RTX 5090standard tierRuns
The standard tier fits with changes: Split the language model across the GPUs with tensor parallelism (vLLM --tensor-parallel-size).
L40Sstandard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVFP4) with Qwen3.8-27B official FP8. This build is NVIDIA NVFP4, which needs a Blackwell GPU.
H100 80 GB (SXM)standard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVFP4) with Qwen3.8-27B official FP8. This build is NVIDIA NVFP4, which needs a Blackwell GPU.
RTX PRO 6000 Blackwell 96 GBstandard tierRuns
The standard tier fits (57.6 of 96 GB).
2x RTX PRO 6000 Blackwell 96 GBstandard tierRuns
The standard tier fits (57.6 of 192 GB).
Apple M3 Ultra (Mac Studio), 96 GBstandard tierRuns
The standard tier fits (32 of 96 GB).
Apple M5 Max, 64 GBstandard tierRuns
The standard tier fits (32 of 64 GB).

Memory per component comes from measured footprints, the tool's stack.json, or an estimate from its parameter count, and each is labelled that way below. Only an RTX PRO 6000 and an M3 Ultra Mac Studio have actually been run.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

1
Check the GPU, Docker and the NVIDIA Container Toolkit
The driver must see the GPU, and Docker must be able to pass it into a container.
```
nvidia-smi
docker compose version
docker run --rm --gpus all ubuntu nvidia-smi
```
2
Fetch the compose file
One file describes the API and the language model as services.
```
mkdir -p ~/decosa && cd ~/decosa
curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml
```
3
Pull and start
The first start downloads pinned model weights, tens of gigabytes.
```
docker compose pull
docker compose up -d
```

4

Check health

Wait until the API reports ok with the language model loaded. Then point your app at the local base URL.

curl -fsS http://localhost:<PORT>/healthz
# {"ok": true, "llm": true, ...}
curl -fsS -X POST http://localhost:<PORT>/demo/session \
  -H 'Content-Type: application/json' -d '{"vertical":"hcc-evidence-file"}'

Set up with a coding agent, rehearse on mock data, then go private

Set up with a coding agent. Paste the self-host prompt into a coding agent on the machine that will run the service. We recommend Claude Code with Claude Opus 5.5; any capable coding agent works.
Rehearse on mock data. The agent runs the tool on a bundle of synthetic inputs and checks each answer against the bundle's expected.json. Every check must print PASS.
Go private. Only then do you run your own data against the local API, yourself, on that machine. Never give the agent real data during setup: a coding agent that runs in the cloud sees everything in its context, so keep real data out of the chat and out of the files it reads.

Rehearsal command

docker compose exec api python scripts/rehearse.py hcc-evidence-file

Download the mock-data bundle (3 KB, 15 checks)expected.json

A synthetic Medicare Advantage member (service year 2025) with nine submitted diagnosis codes (eight map to CMS-HCC V28 payment HCCs) and four notes plus an addendum: an internist's visit, a cardiology visit, an audio-only phone call, a diagnostic radiologist's CT report, and an addendum a coder wrote five months after the visit. The review must delete the 2021 heart attack coded as acute and the breast cancer treated in 2016, hold the codes whose only evidence is in the phone call and the radiology report, keep diabetes with CKD, CKD 3b and heart failure with MEAT quotes, report the net effect, refuse an 'opportunities' mode, and sign a record that verifies and fails when changed.

What the rehearsal checks

the 2021 heart attack coded as acute is not supported (delete)
breast cancer treated in 2016 is not supported (delete)
morbid obesity is held: its only evidence is an audio-only call
COPD is held: its only evidence is a diagnostic radiologist's report
diabetes with CKD is kept
chronic systolic heart failure is kept
at least two codes are to be deleted
the net effect covers all eight HCC codes
the code outside the model (I10) is listed as not reviewed
the coder's late addendum is not an acceptable record
the evidence file lists deletions first
an opportunities mode is refused
the signed record verifies
a record with its status changed no longer verifies
every model call has a signed receipt

Licence: Synthetic: the member, providers and notes are invented (decosa_api/verticals/hcc/synth.py). ICD-10-CM and the CMS-HCC V28 mapping are CMS/CDC public-domain works. Part of decosa-api, AGPL-3.0-or-later.

Prompt for your coding agent