# 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.

## 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.