Agentic chat

POST /api/chat persists a user turn, plans retrieval work, executes tools, and streams the result as Server-Sent Events.

Expand diagram

Chat request sequence

The API sends resolved source passages to generation, then streams response events and citations to the web client.

Use the zoom controls, drag to pan, or pinch on a touch screen. Press Escape to close.

Request lifecycleCopy Anchor Link

1. Prepare. Validate the request and persist the user message with its conversation.
2. Plan. Keyword routing handles common intents. The optional LLM planner can decompose a question into tool calls. Plans are capped at six deduplicated steps; invalid or unavailable model output falls back to hybrid search.
3. Execute. Tool steps run sequentially. Each trace entry records the tool, arguments, result, citations, error state, and elapsed time. A tool failure is recorded instead of discarding other step results.
4. Collect evidence. Successful citable passages are combined and deduplicated by chunk ID. Graph facts without source passages are not presented to the generator as citable text.
5. Generate and gate. The generator decides whether evidence supports an answer before answer prose is streamed. An unsupported question can be declined without emitting token events.
6. Persist. The assistant turn, citations, confidence, and tool attribution are saved before the final event.

SSE event sequenceCopy Anchor Link

A successful stream commonly contains stage, plan, one or more step, citations, one or more token, and done. A decline can contain no token events and report supported: false. That is a refusal due to evidence, not an execution error.

Each frame has an event name and JSON data. Network reads can split a frame across multiple chunks, so clients must buffer until a complete SSE frame is available. The frontend parser in src/lib/chat.ts handles arbitrary byte boundaries.

Planner modesCopy Anchor Link

PLANNER=keyword uses local routing without an LLM planning request. PLANNER=llm enables model-based decomposition with keyword rules as fallback. Both paths return a bounded sequence of tool specifications.

Follow-up detection uses conversation history for short fragments such as “what else?” or “why?”. Questions with their own substantive topic can be planned as standalone requests.

Tools and memoryCopy Anchor Link

The available tool surface includes hybrid search and structured college lookups for faculty, courses, facilities, timetables, and departments, as well as memory operations. Web search is a disabled stub until a provider is implemented.

The tool trace is intentionally sequential. It keeps order and evidence attribution explicit and avoids parallel load on shared local model and graph services.