Write a note from my jottings

# Assemble "Notes from your own jottings" on this machine

You are setting up a documentation aid for a psychotherapy practice. After a session the therapist gives it their own
jottings (typed bullets, a photo of handwritten notes, or a dictation of up to 60 seconds made after the session) and gets
a draft DAP, SOAP or BIRP progress note where every sentence cites the jotting it came from, plus a list of what an
auditor would find missing. It never takes a session recording. Work step by step, show me each command before you run
anything with `sudo`, and stop to ask if a check fails.

## 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/jottings-note.zip (3 KB, 12 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 jottings-note` (the api image carries the same bundle under /app/rehearsal/jottings-note/;
   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 jottings-note --bundle jottings-note.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: "every audited element is in the CBT jottings, so nothing is missing", "the risk line carries the jotting as written", "the start and stop times are the ones written, with the minutes between them"). 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.

## 0. Ground rules and licences
- Models: Qwen3.8-27B (Apache-2.0) drafts, checks every sentence and reads photos; PaddleOCR-VL-1.6 (Apache-2.0) is the
  second reader for handwriting (optional); Qwen3-ASR-1.7B (Apache-2.0) transcribes dictations (optional). The pipeline,
  the checks and the signed record are decosa-api (AGPL-3.0-or-later).
- Therapy notes are PHI. They stay on this machine. Bind every port to 127.0.0.1. The service keeps no note text: nothing
  is written to disk and logs carry counts only. Do not add request logging.
- It is a draft for the licensed clinician to review, edit and sign. Do not add features that record sessions, send
  anything to clients, sign notes, or suggest diagnoses or treatment. The tests fail if a recording input appears.

## 1. Check the machine
1. `nvidia-smi`: one GPU with at least 32 GB (Qwen3.8-27B NVFP4 needs about 20 GB of weights plus KV cache; we measured
   on an RTX PRO 6000 96 GB; an RTX 5090 32 GB should fit but we have not run this tool on one). Blackwell runs NVFP4;
   on older cards use `Qwen/Qwen3.8-27B-FP8`. Typed jottings need only this model.
2. `docker --version`, `docker compose version`. If Docker or the NVIDIA container toolkit is missing, install them from
   the official Docker and NVIDIA repositories after asking me, then run
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
3. Disk: about 40 GB free (the model, plus about 2 GB for the optional handwriting reader).

## 2. Images and weights
- `${DECOSA_REGISTRY}/decosa-api:<tag>` (**publishing soon**). If the pull fails, build from source:
  `git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>` (access required), check out the newest release tag that
  contains `decosa_api/verticals/jottings/` (`main` until one does), and build `docker/api/Dockerfile`.
- `vllm/vllm-openai:v0.29.0`; weights `nvidia/Qwen3.8-27B-NVFP4` (revision `482ca0f3832238542f8f5295dde86b5f22711d80`).
- Optional, for photos: a second vLLM serving `PaddlePaddle/PaddleOCR-VL-1.6` (revision `c5630ab`) with
  `--gpu-memory-utilization 0.04`. Without it, photos are read by Qwen3.8 alone and nothing is flagged as "readers differ".
- Optional, for dictation: the language pack's speech service (Qwen3-ASR-1.7B), see decosa-api `services/lang/`.

## 3. docker-compose.yml
Write this in `~/decosa/jottings/`:

```yaml
services:
  llm:
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "nvidia/Qwen3.8-27B-NVFP4", "--served-model-name", "qwen3.8-27b", "--max-model-len", "32768",
              "--enable-prefix-caching"]
    ports: ["127.0.0.1:8114:8000"]
    volumes: ["~/.cache/huggingface:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
    healthcheck: { test: ["CMD", "curl", "-fs", "http://localhost:8000/v1/models"], interval: 30s, retries: 20 }
  reader:   # optional: the second reader for handwriting photos
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "PaddlePaddle/PaddleOCR-VL-1.6", "--revision", "c5630ab", "--served-model-name", "PaddlePaddle/PaddleOCR-VL-1.6",
              "--trust-remote-code", "--gpu-memory-utilization", "0.04", "--max-model-len", "8192", "--max-num-seqs", "16"]
    ports: ["127.0.0.1:8498:8000"]
    volumes: ["~/.cache/huggingface:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:<tag>
    ports: ["127.0.0.1:8445:8445"]
    environment:
      DECOSA_HOST: 0.0.0.0
      DECOSA_PORT: "8445"
      DECOSA_DATA_DIR: /data
      DECOSA_LLM_ROUTE: direct
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_JOTTINGS_SYNTHETIC_ONLY: "0"
      DECOSA_DOCREADER_PARSER_URL: http://reader:8000/v1
      DECOSA_BUDGET_LLM_TOKENS: "400000"
    volumes: ["decosa-data:/data"]
    depends_on: { llm: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8445/jottings/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
```

`DECOSA_JOTTINGS_SYNTHETIC_ONLY: "0"` lets this box take real notes; the hosted service takes made-up sessions only and
refuses text that looks like real identifiers. Leave out the `reader` service (and `DECOSA_DOCREADER_PARSER_URL`, or set
`DECOSA_JOTTINGS_SECOND_READER: "0"`) if you only type jottings. The api keeps its state in the named volume
`decosa-data` (a host folder created by Docker is owned by root and stops the unprivileged api). Then
`docker compose up -d`.

On first start the api creates this box's Ed25519 key in `decosa-data` (`/data/attest/`, mode 0600). Back it up with
`docker compose cp api:/data/attest ./attest-backup`, keep it private, never print it. Every model call on the direct
route gets a receipt signed with that key (an attestation by the operator, not a proof). Never set
`DECOSA_LLM_ROUTE=gateway` on this box: that sends PHI off the machine.

## 4. Smoke test
1. `curl -s localhost:8445/jottings/info | jq '{synthetic_only, route: .model.route, elements: [.elements[].id]}'` shows
   `synthetic_only: false`, `direct`, and the ten elements (date ... signature, risk).
2. Token: `T=$(curl -s -XPOST localhost:8445/demo/session -H 'content-type: application/json' -d '{"vertical":"jottings-note"}' | jq -r .token)`.
3. `curl -s -XPOST localhost:8445/jottings/note -H "authorization: Bearer $T" -H 'content-type: application/json' -d '{"sample":"cbt-panic"}' > res.json`,
   then `jq -r .note.plain res.json`. Expect nothing in `.report.missing`, `Total time: 53 minutes`, the risk line
   `"denies SI/HI"` as written, and the mother's opinion kept as her opinion (never "diagnosed with bipolar disorder").
4. `jq '{removed: .report.sentences.removed, missing: .report.missing}' <(curl -s -XPOST localhost:8445/jottings/note -H "authorization: Bearer $T" -H 'content-type: application/json' -d '{"sample":"couples-gaps"}')`:
   `missing` includes `start_time`, `stop_time` and `plan`, and the note says `[not in your notes]` for them.
5. `jq .report.record res.json | curl -s -XPOST localhost:8445/record/verify -H 'content-type: application/json' -d @- | jq .ok`
   must print `true`.
6. A request with a `"recording"` field must return 400 ("never takes a session recording").
7. If decosa-api's source is at hand, `python scripts/rehearse.py jottings-note --base-url http://127.0.0.1:8445` runs the
   checks and prints PASS or FAIL per property (11 checks). On our server it took 49 s.
8. Photos (if the reader runs): `{"sample":"dbt-photo"}` reads nine lines; `.ready.jottings[].read` says `agree` for lines
   both readers read the same.

## 5. Use it
- Open `http://127.0.0.1:8445/jottings/app` in a browser on this machine: type or photograph jottings, pick DAP, SOAP or
  BIRP, add goals and your name and credential, Draft, then Copy the note (or one section at a time) into your EHR. The
  "Catch up on a backlog" tab drafts up to 30 sessions at once.
- Or call `POST /jottings/note` and `POST /jottings/batch` from your own scripts; contract: `API_CONTRACT.md`, section
  "Changes (jottings-note: write a note from my jottings, 2026-09-28)".

Off by default. Never on a box that holds PHI. If I ask for it, follow the provider guide at `/provide` on the site, and
do not enable it without my explicit yes.