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

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:

show me the table
show me Table 13.1
summarize the developmental table

Explicit visual creation/display requests can use image flow.

Examples:

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.

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,
MCP result normalization,
model discovery or settings behavior.

3 KiB Raw Blame History