108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
# Clinical Assistant
|
|
|
|
The Clinical Assistant is a retrieval-grounded assistant for pediatric clinical reference questions. It is not the same as the app's note-generation/HPI workflow.
|
|
|
|
## Responsibilities
|
|
|
|
| Component | Responsibility |
|
|
|---|---|
|
|
| Browser UI | question input, source display, markdown/citation rendering, export |
|
|
| Ped-AI backend | settings, MCP search call, answer prompt construction, model call |
|
|
| MCP server | Nextcloud access, indexing, vector search, rerank, source metadata |
|
|
| LiteLLM | model routing and provider abstraction |
|
|
|
|
## Request Flow
|
|
|
|
```txt
|
|
User asks a question
|
|
-> browser posts to Ped-AI
|
|
-> Ped-AI calls MCP `nc_semantic_search`
|
|
-> MCP returns source excerpts and metadata
|
|
-> Ped-AI builds an answer prompt with source constraints
|
|
-> LiteLLM model returns answer text
|
|
-> browser renders answer and source cards
|
|
```
|
|
|
|
## Source Rules
|
|
|
|
- Prefer MCP `file_path` basename for displayed source titles when present.
|
|
- Do not relabel one source as another requested source.
|
|
- If the user names a source and retrieval does not return it, say that before using other sources.
|
|
- Use citations only for returned source numbers.
|
|
- Unknown citation numbers should remain plain text instead of being guessed.
|
|
|
|
## Table And Markdown Rendering
|
|
|
|
LLM output is not guaranteed to be valid markdown. The browser renderer defensively handles common problems:
|
|
|
|
- adjacent citation clusters,
|
|
- missing closing bracket in narrow citation cases,
|
|
- smashed bullet lists,
|
|
- inline headings,
|
|
- malformed pipe tables,
|
|
- bare source numbers in source/citation table columns,
|
|
- orphan markdown emphasis markers,
|
|
- code blocks that must not be modified.
|
|
|
|
Renderer fixes must be narrow. Do not add broad repairs that turn arbitrary clinical numbers into citations.
|
|
|
|
## Image Routing
|
|
|
|
Table lookup requests should stay in retrieval flow.
|
|
|
|
Examples that should use retrieval:
|
|
|
|
```txt
|
|
show me the table
|
|
show me Table 13.1
|
|
summarize the developmental table
|
|
```
|
|
|
|
Explicit visual creation/display requests can use image flow.
|
|
|
|
Examples:
|
|
|
|
```txt
|
|
create an infographic
|
|
generate a diagram
|
|
show me the image/figure
|
|
```
|
|
|
|
## Caching Policy
|
|
|
|
Clinical answer response caching is intentionally disabled. Redis can support prompt suggestions and operational metadata, but final answers should be generated from current retrieval context.
|
|
|
|
## Image Attachments
|
|
|
|
Users can attach up to 4 images (PNG, JPEG, WebP) to an outgoing clinical question. Attachments are **input-only**:
|
|
|
|
- They are validated client-side and authoritatively on the server (MIME allowlist, canonical base64, ≤ 5 MiB per image, ≤ 4 images, ≤ 10 MiB decoded total). Invalid input is rejected with 400 before any retrieval or provider call.
|
|
- They are sent **only** with the outgoing clinical question, never with handoff summaries, image generation, saved chats, downloads or transcripts.
|
|
- The conversation budget counts text only: images are excluded from the UTF-16 code-unit count. The server still validates every request.
|
|
- Only OpenAI-compatible providers (LiteLLM, OpenRouter, Azure) receive them as multimodal content parts (`text` + `image_url` data URIs) on the latest user message; the system/retrieval/history structure is unchanged. Legacy direct adapters (Bedrock/Vertex) refuse with a clear 400 before contacting the provider.
|
|
- Attachments clear on a successful send and on New chat; a rejected send keeps them for correction.
|
|
|
|
## Settings
|
|
|
|
Important settings include:
|
|
|
|
| Setting | Purpose |
|
|
|---|---|
|
|
| `clinical_assistant.chat_model` | Chat model used for answers |
|
|
| `clinical_assistant.image_model` | Image model used for explicit image generation |
|
|
| `clinical_assistant.search_limit` | Number of MCP results requested |
|
|
| `clinical_assistant.context_chars` | Context characters requested from MCP |
|
|
| `clinical_assistant.system_behavior` | Admin-editable assistant behavior guidance |
|
|
|
|
## Testing Priorities
|
|
|
|
Add or update tests when changing:
|
|
|
|
- citation rendering,
|
|
- source title cleanup,
|
|
- named-source provenance behavior,
|
|
- table rendering,
|
|
- image intent routing,
|
|
- image attachment validation and multimodal payload shape,
|
|
- MCP result normalization,
|
|
- model discovery or settings behavior.
|