ducoterra
15c1272828
Grounded chat turns now run the agent loop (app/rag/agent.py) instead
of a bare chat_stream: while the per-turn budgets last
(BOR_AGENT_LIST_CALLS / BOR_AGENT_READ_CALLS, default 1 each) the model
gets list_documents (the indexed catalog, /api/docs order) and
read_document (full text, never truncated — A7-revised contract); once
both budgets are spent the tools key is dropped from the request and
the model must answer. Rejected calls (unknown tool, unknown/missing
path, document already in context, spent budget) consume no budget.
Budgets 0/0 make exactly one tools=None request — byte-identical to
the pre-phase path (budgets-as-kill-switch). Deflected turns keep the
direct chat_stream (A8 unchanged; the LOW prompt never carries the
<tools> section).
SSE contract gains {"type":"tool","name":...,"argument":
"source/path"|null} frames ahead of the answer deltas (PLAN §4
extension, owner permission 2026-08-26); done.sources, query_log.sources
and the per-turn log line (gains tool_calls=N) report the retrieval
docs + read docs, deduped. The UI shows a "calling tool"
button/label state and one visible .tool-call line per call above the
answer; the lines persist with the chat record and re-render on
reload. chat_stream passes tools through and accumulates streaming
tool_calls deltas into ToolCallPiece (tools=None stays byte-identical).
E2E: deterministic mock tool flow ("use your tools" + <tools> marker:
list -> read first catalog line -> quoted answer) plus the story suite
(marker flow, reload re-render, plain/deflected no-tool regressions).
Docs: .env.example + README (the two tools, the budgets, the SSE tool
frame, the "calling tool" UI state).
probe: turbo tool_calls=supported 2026-08-26 (uv run python -m
scripts.llm_probe --tools — non-streaming + streaming
finish_reason=tool_calls, indexed delta.tool_calls partials)
103 lines
4.4 KiB
Python
103 lines
4.4 KiB
Python
"""Unit: SSE frame serialization for POST /api/chat (PLAN §4 contract)."""
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
|
|
from app.api.chat import sse_event
|
|
from app.schemas import ChatErrorEvent, ChatThinkingEvent, ChatToolEvent
|
|
|
|
|
|
def _payload(frame: str) -> dict:
|
|
assert frame.startswith("data: ")
|
|
assert frame.endswith("\n\n")
|
|
return json.loads(frame.removeprefix("data: ").strip())
|
|
|
|
|
|
def test_delta_frame_serializes_exactly() -> None:
|
|
frame = sse_event({"type": "delta", "text": "hi"})
|
|
assert frame == 'data: {"type": "delta", "text": "hi"}\n\n'
|
|
assert _payload(frame) == {"type": "delta", "text": "hi"}
|
|
|
|
|
|
def test_done_frame_carries_full_contract_shape() -> None:
|
|
payload = {
|
|
"type": "done",
|
|
"deflected": False,
|
|
"sources": [{"source": "Homelab", "path": "kubernetes.md", "title": "K8s"}],
|
|
"suggestions": [],
|
|
}
|
|
assert _payload(sse_event(payload)) == payload
|
|
|
|
|
|
def test_error_frame_serializes() -> None:
|
|
frame = sse_event({"type": "error", "detail": "boom"})
|
|
assert _payload(frame) == {"type": "error", "detail": "boom"}
|
|
|
|
|
|
def test_unicode_survives_roundtrip() -> None:
|
|
frame = sse_event({"type": "delta", "text": "🧠 café — \"quoted\""})
|
|
# ensure_ascii=False keeps the frame readable (no \uXXXX escapes).
|
|
assert "🧠 café" in frame
|
|
assert _payload(frame)["text"] == "🧠 café — \"quoted\""
|
|
|
|
|
|
def test_multi_line_text_stays_one_frame() -> None:
|
|
"""Newlines inside the JSON payload must be escaped so the frame
|
|
delimiter ``\\n\\n`` remains unambiguous."""
|
|
frame = sse_event({"type": "delta", "text": "line1\nline2\n\n"})
|
|
assert frame.count("\n\n") == 1 # only the frame terminator
|
|
assert _payload(frame)["text"] == "line1\nline2\n\n"
|
|
|
|
|
|
def test_error_event_model_serializes_exact_frame() -> None:
|
|
"""The ``ChatErrorEvent`` model is the wire shape of every server-side
|
|
failure the UI's state machine (phase 06) must recover from."""
|
|
frame = sse_event(ChatErrorEvent(detail="boom").model_dump())
|
|
assert frame == 'data: {"type": "error", "detail": "boom"}\n\n'
|
|
assert _payload(frame) == {"type": "error", "detail": "boom"}
|
|
|
|
|
|
def test_error_event_shape_is_type_and_detail_only() -> None:
|
|
dumped = ChatErrorEvent(detail="The chat model dropped the connection").model_dump()
|
|
assert set(dumped.keys()) == {"type", "detail"}
|
|
assert dumped["type"] == "error" # default — call sites never spell it out
|
|
|
|
|
|
def test_thinking_frame_serializes_exactly() -> None:
|
|
"""Phase 17 (PLAN §4 extension): the ``thinking`` frame is exactly
|
|
``{type: "thinking", text: str}`` — the sibling shape of ``delta``
|
|
the client's readSSE handler will branch on."""
|
|
frame = sse_event(ChatThinkingEvent(text="Step 1: check the docs…").model_dump())
|
|
assert frame == 'data: {"type": "thinking", "text": "Step 1: check the docs…"}\n\n'
|
|
assert _payload(frame) == {"type": "thinking", "text": "Step 1: check the docs…"}
|
|
|
|
|
|
def test_thinking_event_shape_is_type_and_text_only() -> None:
|
|
dumped = ChatThinkingEvent(text="hmm").model_dump()
|
|
assert set(dumped.keys()) == {"type", "text"}
|
|
assert dumped["type"] == "thinking" # default — call sites never spell it out
|
|
|
|
|
|
def test_tool_frame_serializes_exactly() -> None:
|
|
"""Phase 37 (PLAN §4 extension): the ``tool`` frame is exactly
|
|
``{type: "tool", name: str, argument: str | null}`` — one per
|
|
model-requested document tool call, streamed ahead of the ``delta``
|
|
frames of the answer."""
|
|
frame = sse_event(ChatToolEvent(name="read_document", argument="S/p.md").model_dump())
|
|
assert frame == 'data: {"type": "tool", "name": "read_document", "argument": "S/p.md"}\n\n'
|
|
assert _payload(frame) == {"type": "tool", "name": "read_document", "argument": "S/p.md"}
|
|
|
|
|
|
def test_tool_frame_argument_is_null_for_parameterless_tools() -> None:
|
|
"""``list_documents`` takes no parameters, so its frame's ``argument``
|
|
serializes as JSON null (the client renders the name alone)."""
|
|
dumped = ChatToolEvent(name="list_documents").model_dump()
|
|
assert dumped == {"type": "tool", "name": "list_documents", "argument": None}
|
|
assert _payload(sse_event(dumped))["argument"] is None
|
|
|
|
|
|
def test_tool_event_shape_is_type_name_argument_only() -> None:
|
|
dumped = ChatToolEvent(name="read_document", argument="S/p.md").model_dump()
|
|
assert set(dumped.keys()) == {"type", "name", "argument"}
|
|
assert dumped["type"] == "tool" # default — call sites never spell it out
|