NEW-AGENT.txt

# MAIA Provisioning Configuration

This file is BOTH documentation and live configuration. Several section
headings are parsed at runtime — do NOT rename them or change the
format of the marked lines, or provisioning breaks. IMPORTANT: never
repeat one of those heading strings anywhere else in this file (the
parsers match the first occurrence).

Runtime-parsed sections (heading → code consumer):
- MAIA INSTRUCTION TEXT  → server/routes/auth.js, server/index.js
  (seed System Instructions for every Private AI agent — the generic
  *guardrail* prompt; per-deliverable prompts live in clinical-prompts.md)
- Private AI Setup Wizard → server/routes/auth.js getSetupWizardMessages
- Random Names           → server/routes/auth.js getTempUserFirstNames
- the embedding-model line → server/utils/embedding-model-config.js
- Knowledge Bases        → server/utils/kb-config.js (reranking +
  chunking params in the fenced key:value block)
- App Platform Settings  → server/utils/new-agent-config.js

Companion files (NOT parsed by this file's loader):
- `clinical-prompts.md` (repo root) — the editable per-request prompts
  MAIA sends to a Private AI for each clinical deliverable (medication
  worksheets, current-medications extract, patient-summary draft).
  Loaded by `server/utils/clinical-prompts.js`.
- `Documentation/Clinical.md` — reference docs (architecture, flows,
  the moved Agent API specification, footer-stripped indexing). Points
  at this file and at `clinical-prompts.md` by id; no verbatim copies.

---

## MAIA INSTRUCTION TEXT

You are MAIA, a medical AI assistant, that can search through a patient's health records in a knowledge base and provide relevant answers to their requests. Use only information in the attached knowledge bases and never fabricate information. There is a lot of redundancy in a patient's knowledge base. When information appears multiple times you can safely ignore the repetitions.

**Agent's Perspective**
Write from the perspective of a physician creating a summary for an on-call physician who has never seen the patient.

**Errors and Redactions**
Remove any mention of problems or medications for sexual function including syringes that may be prescribed.

**Format and Language**
Always start your response with the patient's name, age and sex. Do not show your reasoning. Provide the response in English. Format section headings so they are not too large.

**Source Citations**
When you reference a specific record (a visit note, lab result, medication entry, imaging report, etc.), cite the source inline immediately after the reference, in this exact format: `[<filename> p.<page>]` — for example "Cardiology consult on 2025-10-15 [Health Records - Margarita.pdf p.42]". The chat UI auto-converts these citations to clickable links that open the PDF at that page. WITHOUT the bracketed filename, no link can be created. Always include the .pdf filename, not just a "File N" tag.

When the same fact appears in MORE THAN ONE source file — for example a clinical encounter that's documented in both an Apple Health export ("Health Records - …") and a hospital export (Epic, MGB, Mass General Brigham) — **prefer the non-Apple-Health source for the citation**. Apple Health entries are summary-only ("Telephone Encounter by Dr X") while the hospital export carries the full note text. Cite the Apple Health source only as a secondary if there is no other source.


---

## Private AI Agents

Each MAIA account provisions **two** DigitalOcean GenAI agents, both
attached to the same user knowledge base. They appear in the chat
provider dropdown as "Private AI (GPT)" first and "Private AI (Deepseek)"
second — GPT is the primary as of v1.4.0.

> **About the profile keys.** The two slots are addressed in
> `userDoc.agentProfiles[<key>]` by historical key names: `default`
> (primary) and `gpt` (secondary). The keys are kept for back-compat
> — what each key resolves to (GPT vs Deepseek) flipped in v1.4.0,
> so display labels are derived from the actual stored model name,
> not the slot key. (`server/routes/chat.js` builds the dropdown
> labels; `src/components/Lists.vue` builds the worksheet card
> titles; both look at the model field, never the slot key.)

### Primary — Private AI (GPT)
- Profile key: `default`
- Model: **OpenAI GPT-oss-120b** (`inference_name: openai-gpt-oss-120b`),
  resolved to a model UUID at runtime from the DO GenAI models catalog.
  Optional env override: `DO_MODEL_ID` (primary only).
- System Instructions: seeded from `## MAIA INSTRUCTION TEXT` above.
- Agent name pattern: `{userId}-agent-{YYYYMMDDThhmmss}`.
- This is the agent used by the Setup/Restore wizard automation and the
  default chat selection.

### Secondary — Private AI (Deepseek)
- Profile key: `gpt` (historical key; the model it resolves was swapped
  in v1.4.0 — see note above).
- Model: **Deepseek V4 Pro** (`inference_name: deepseek-v4-pro`),
  resolved from the DO catalog (never falls back to a non-Deepseek
  model on this slot).
- System Instructions: a **one-time copy** of the primary agent's
  instruction at creation time; the two then diverge.
- Agent name pattern: `{userId}-agent-gpt-{YYYYMMDDThhmmss}` (the
  `-gpt-` infix is historical, not a model indicator).

### Independent System Instructions
After creation, each agent's System Instructions are stored per profile
in `userDoc.agentProfiles[<key>]` and are independently editable in
**My Stuff → My AI Agent** (one sub-tab per agent). Editing one does
not affect the other. `## MAIA INSTRUCTION TEXT` is only the initial
seed, not a live link.

### Shared resources
Both agents attach the same OpenSearch-backed knowledge base (DO KB →
agent is many-to-many). Destroying the cloud account deletes both
agents; Restore rebuilds both.

---

## Knowledge Bases

Parameters used when MAIA creates a new knowledge base. One OpenSearch
cluster per DO account is shared by all knowledge bases.

```
embedding_model: GTE Large EN v1.5
reranking_model: BGE Reranker v2 m3
chunking_strategy: hierarchical
semantic_similarity_threshold: 0.4
semantic_max_chunk_size: 1200
hierarchical_max_parent_chunk_size: 1500
hierarchical_max_child_chunk_size: 400
ah_lists_max_chunk_size: 200
```

The defaults above are tuned for the mixed AH-PDF + Epic-PDF
workload typical of MAIA accounts (see `Documentation/Clinical.md`
§7 for the rationale). Per-data-source overrides apply: the
sidecar AH `Lists/*.md` data source (one entry per chunk) uses
`CHUNKING_ALGORITHM_SEMANTIC` with `max_chunk_size =
ah_lists_max_chunk_size` regardless of `chunking_strategy`.

> **Two-slot KB strategy.** Each account has two KB slots: **KB-1**
> (primary, the agent retrieves from this by default) and **KB-2**
> (alternate, opt-in via My Stuff → My AI Agent). They ALWAYS use
> OPPOSITE chunking strategies — KB-1 hierarchical → KB-2 semantic
> (the new-account case as of v1.4.4); KB-1 semantic → KB-2
> hierarchical (the pre-v1.4.4 case). The actual strategy each KB
> was created with is persisted on `userDoc.kbChunkingStrategy`
> (KB-1) and `userDoc.kb2.chunking` (KB-2), and the UI labels are
> derived from those fields so they can never lie about what the
> KB actually is.

(The fenced block above is only the knowledge-base knobs that are
actually sent to DigitalOcean. The OpenSearch database is deliberately
NOT a knob here — see below.)

Parameter reference:

- **embedding_model** *(parsed by code — keep the exact `embedding_model:`
  line above)* = `GTE Large EN v1.5`. Resolved to a model UUID at
  runtime via the DO GenAI models API. Optional env override:
  `DO_EMBEDDING_MODEL_ID`.
- **reranking_model** = `BGE Reranker v2 m3`.
- **chunking_strategy** = `hierarchical` (default) or `semantic`.
  Hierarchical is the new default — small child chunks for precise
  retrieval, larger parent chunks returned to the LLM for context.
  Better than semantic for the mixed structured + narrative case
  typical of medical PDFs.
  - Semantic chunking:
    - **semantic_similarity_threshold**: 0 – 1 (default `0.4`)
    - **semantic_max_chunk_size**: 100 – 8192 (default `1200`)
  - Hierarchical chunking:
    - **hierarchical_max_parent_chunk_size**: 100 – 8192 (default `1500`)
    - **hierarchical_max_child_chunk_size**: 100 – 750 (default `400`)
- **ah_lists_max_chunk_size** = `200`. Per-source override for the
  Apple Health `Lists/*.md` sidecar data source. AH categories are
  many short entries (`**Date:** … | **Page:** …` then the
  observation, then `---`) — at this size each entry is roughly
  one chunk, so retrieval returns the *specific* records the agent
  was asking about instead of a 30-entry blob.
### OpenSearch database (NOT a configurable parameter)

The OpenSearch database is **not** selected by name and the name is
**never honored** as configuration. The rule is absolute:

> **Always use the existing OpenSearch database for the account. Only
> create a new one if the account has none.**

Resolution order (server/utils/opensearch-config.js): env
`OPENSEARCH_DATABASE_ID` → CouchDB cache `maia_config/opensearch_database_id`
→ the existing cluster returned by `GET /v2/databases?engine=opensearch`
→ create one only if the account has zero. One cluster per account; it
is shared by every knowledge base.

The account's current cluster happens to be named `genai1-driftwood`
(reference only — not used by the code). The **resolved database UUID**
of whatever existing cluster was used is recorded in `maia-log.pdf`
(the `OpenSearch database id` line of the `Knowledge base created`
entry) for transparency. Renaming the cluster here, or pointing at a
different name, has **no effect**: MAIA always reuses whatever existing
database the account already has and never creates a second one when
one exists.

DigitalOcean uses an S3-compatible Spaces bucket (named `maia`,
subfoldered by `userId`) to pass files to OpenSearch for indexing into
the knowledge base attached to the user's Private AI agent.

> Reference docs that used to live here — **Footer-stripped (clean-index)
> indexing** and the **DigitalOcean Agent API Specification** — have moved
> to `Documentation/Clinical.md` so this file stays focused on what code
> actually parses at runtime (the system-instruction guardrail, KB
> parameters, setup-wizard text, random names, app-platform settings).
> The per-request *clinical prompts* (worksheets, current-medications
> extract, patient-summary draft) live in **`clinical-prompts.md`** at
> the repo root.

---

## CouchDB Droplet (optional)

Set `USE_COUCHDB_DROPLET=true` to enable. At startup the droplet is
found or created as `ubuntu-s-1vcpu-1gb-tor1-01` on the default VPC.
`CLOUDANT_URL` = `http://<droplet-ip>:5984`. Username is fixed
(`admin`); password is generated (`openssl rand -base64 24`) and passed
via `COUCHDB_USER`/`COUCHDB_PASSWORD`. Credentials are stored in Spaces
at `couchdb/credentials.json` (and locally at
`.couchdb-droplet-credentials`), Spaces first then local.

---

## App Platform Settings

DO_REGION=tor1
PORT=3001

---

## Private AI Setup Wizard

**I’m the setup wizard**
* Import your health record files while I provision your private AI agent.
* An Apple Health "PDF Export" file is particularly useful but not mandatory.
* Once your files are indexed into your private knowledge base, I will help you create
and verify your Current Medications and a Patient Summary.


---

## Random Names

Emily Johnson
Michael Smith
Jessica Brown
Matthew Davis
Ashley Wilson
Christopher Moore
Sarah Taylor
Joshua Anderson
Amanda Martinez
Daniel Thomas
Megan Jackson
Andrew White
Stephanie Harris
Justin Martin
Nicole Thompson
Brandon Garcia
Elizabeth Martinez
Ryan Robinson
Brittany Clark
David Lewis
Samantha Walker
Jonathan Lee
Lauren Hall
James Allen
Melissa Young
Anthony King
Kimberly Wright
Robert Scott
Rebecca Green
Jason Adams
Michelle Baker
Eric Gonzalez
Heather Nelson
Kevin Carter
Angela Perez
Brian Mitchell
Rachel Roberts
Tyler Turner
Amber Phillips
Adam Campbell
Laura Parker
Nicholas Evans
Jennifer Edwards
Zachary Collins
Christina Stewart
Sean Morris
Katie Sanchez
Justin Rogers
Natalie Reed
Aaron Cook
Olivia Richardson
Steven Simmons
Hannah Foster
Benjamin Powell
Lauren Howard
Ethan Ward
Grace Cox
Alexander Flores
Victoria Ramirez
Dylan Rivera
Madison Brooks
Jordan Kelly
Abigail Sanders
Christian Price
Chloe Butler
Tyler Bennett
Sophia Barnes
Jack Russell
Alexis Murphy
Elijah Griffin
Lily Hayes
Gabriel Cooper
Hailey Morgan
Caleb Peterson
Sydney Coleman
Lucas Perry
Kaitlyn Bell
Gavin Long
Danielle Hughes
Mason Foster
Jenna Ward
Aiden Bryant
Kelsey Fisher
Connor Hamilton
Paige Simmons
Logan Webb
Shelby Greene
Owen Fox
Carly Knight
Hunter Stone
Sierra Walters
Isaac Curtis
Mackenzie Bishop
Blake Farmer
Victoria Holland
Grant Chambers
Autumn Franklin
Cole Lawrence
Brooke Matthews
Nathaniel Douglas