pediatric-ai-scribe-v3/docs/ops-docs-ped-ai-and-milvus.md

# Ped AI And Milvus

Last updated: 2026-09-11

What Ped-AI is, which Milvus is which, and where each kind of data lives. Written
for the operator handbook, so it says where things are rather than how they are
coded.

## What Ped-AI is

A clinical documentation assistant. Two halves:

- **Workspace** — encounter notes, dictation, SOAP, well and sick visits, ED,
  hospital course, calculators, Learning Hub. Each generates text with an LLM
  through the LiteLLM gateway.
- **Clinical Assistant** — a chat that answers only from an indexed medical
  library, with numbered citations back to the source documents.

It runs as one container, `pediatric-ai-scribe`, on `127.0.0.1:3552` behind
Caddy. Postgres and Redis are its own; everything else it talks to belongs to
another stack.

## The two Milvus servers

They are easy to confuse, and both listen on 19530. Connecting to the wrong one
succeeds at the network level and then fails authentication, because each has
its own users — so a mistake here looks like a password problem.

| Which | Container | Database | Collection | Holds |
|---|---|---|---|---|
| **Clinical** | `nextcloud-mcp-server-milvus-1` | `default` | `mcp_bge_m3_1024` | The medical library Ped-AI answers from. ~1.8M chunks. |
| **Personal assistant** | `personal-assistant-storage-milvus-basic-milvus-1` | `basic` | `personal_assistant_bge_m3_1024` | Your Nextcloud mail, notes, tables and files. |

Both embed with **bge-m3** at 1024 dimensions, which is what the collection names
now say. Neither is reachable from the internet: the personal one publishes no
ports at all, the clinical one is bound to `127.0.0.1`.

Repositories, renamed 2026-09-11 to match what they hold:

- `personal-assistant-storage-milvus` — was `ped-ai-storage`
- `clinical-storage-milvus` — was `nextcloud-mcp-server`, and runs no MCP server,
  only etcd, MinIO and Milvus

Container and volume prefixes still read `ped-ai-storage_*` on anything not yet
migrated; the project name is pinned deliberately, because changing it makes
Compose create empty volumes instead of finding the existing ones.

## How Milvus stores its data

Milvus keeps **segment files in MinIO**, not on a local disk, and its metadata in
etcd. That matters: `COMMON_STORAGETYPE=local` writes segments relative to the
working directory, so recreating the container destroys them while etcd still
references them, and the collection then hangs at `Loading` forever. Each Milvus
has its own MinIO and its own etcd container.

Access is per-database and per-collection. Renaming a collection revokes its
grants, because a grant names the collection — after any rename, re-run the
bootstrap that provisions the roles.

## Where each kind of data lives

| Data | Where |
|---|---|
| Accounts, notes, encounters, Learning Hub content and quizzes | Postgres (`pedscribe`) |
| Learning Hub semantic search | `learning_content.embedding`, pgvector |
| Generated images | MinIO bucket `generated-images` |
| Voice recordings, kept 24 hours | MinIO bucket `audio-backups` |
| Medical library chunks | Clinical Milvus |
| Nextcloud mail, notes, tables, files | Personal assistant Milvus |

Quizzes are ordinary relational tables and use no vectors at all.

## How a question is answered

1. The browser posts to `/api/clinical-assistant/chat/stream`.
2. Ped-AI calls the MCP tool `clinical_semantic_search` on `mcp-server-mcp-1`.
3. That searches the clinical Milvus and returns passages with scores.
4. Ped-AI sends those passages to the chat model as the only permitted source.
5. The answer streams back with numbered citations; the Sources panel shows the
   passages behind them.

If retrieval returns nothing, the assistant says so rather than answering from
the model's own knowledge.

## Recordings

Every recording is kept for 24 hours, whether or not its transcription
succeeded, gzipped and encrypted before storage. A recording holds a screen wake
lock while it runs, survives moving around the app, and is saved with the module
it came from if the session ends. Recordings can be downloaded from
Settings → Audio backups.

Transcription is a gateway model — currently `mistral-voxtral-mini-transcribe`.
The browser's own speech recognition is a separate, off-by-default setting; it
sends audio to the browser vendor and is not HIPAA-compliant.

## Indexing

| Index | Written by | Source |
|---|---|---|
| Clinical | `mcp-server-mcp-indexer-1` | The medical library. Text extraction via `unstructured`, PyMuPDF4LLM and Tesseract. |
| Personal assistant | `personal-assistant-storage-milvus-basic-indexer-1` | Nextcloud. Mail first, then notes, deck, tables, calendar, todos, collectives, cookbook, talk, contacts, and files. PDF text via PyMuPDF4LLM. |

The folder the personal indexer walks is `BASIC_INDEXING_DOCUMENTS_FOLDER`. It
takes one folder or several separated by commas, each walked recursively:

```
BASIC_INDEXING_DOCUMENTS_FOLDER=Personal assistant,Clinical Notes
```

A complete listing is the authority for deletion, so moving that setting to a
different folder removes the chunks of everything no longer under an indexed
root.

## Quick checks

```bash
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3552/api/health
docker ps --format '{{.Names}} {{.Status}}' | grep -E 'pediatric-ai-scribe|milvus|indexer'
docker logs --since 10m personal-assistant-storage-milvus-basic-indexer-1 | grep -c Indexed
```