M3.5 — KB Builder en mode "agent appelé" (`ask_kb_builder` handler)

[zestones]

Note

Milestone: M3 — KB Builder Agent
Planning doc: docs/planning/M3-kb-builder/issues.md
Status: IMPLEMENTED on branch 19-m33-onboarding-session-multi-turn (will move to its own branch / PR before merge).

Scope. backend/agents/kb_builder/qa.py — answer_kb_question(cell_id, question).

This handler is called by the M4.6 orchestrator when Investigator calls the
ask_kb_builder tool. It is a pure async function: no WebSocket broadcasts,
no session state, no DB writes.

Note

Depends on M3.1 (#17). anthropic_client.py exists with
model_for, parse_json_response, and the anthropic singleton — verified.

---

1. Implementation

Lives in backend/agents/kb_builder/qa.py (split-by-concern, matching pdf_extraction.py and onboarding/). Re-exported from agents.kb_builder for from agents.kb_builder import answer_kb_question.

Body matches the issue's reference snippet, with two minor adjustments:

• import logging lives at module top (not inside the function) — single logger per module is the project pattern.
• # noqa: BLE001 kept on the bare except Exception — the safe-fallback contract is explicit.

---

2. Model choice

Uses model_for("chat") — always Sonnet, regardless of ARIA_MODEL. Verified by test_returns_parsed_json_on_happy_path asserting the captured model kwarg is claude-sonnet-4-5.

---

3. Pure handler contract

Static guard test test_module_does_not_import_ws_manager_or_db parses the module AST, strips docstrings, and asserts ws_manager, broadcast, from core import database, and import asyncpg are absent from the executable code. Fails fast if anyone reintroduces a duplicate broadcast path.

---

4. Error contract

Three failure paths return the documented fallback dict:

Failure	Returned dict
MCP is_error=True	{answer: "KB not available for cell {n}", source: null, confidence: 0.0}
anthropic.messages.create raises	{answer: "KB query failed — information unavailable", source: null, confidence: 0.0}
parse_json_response raises ValueError	same as above (caught by the same except)

All three are covered by dedicated tests.

---

5. Dependency chain

flowchart LR
    M31["M3.1 anthropic_client<br/>(anthropic, model_for,<br/>parse_json_response)"]
    M25["M2.5 update_equipment_kb<br/>get_equipment_kb (DONE)"]
    M35["M3.5 answer_kb_question<br/>(this issue)"]
    M46["M4.6 ask_kb_builder tool<br/>in Investigator orchestrator"]

    M31 --> M35
    M25 --> M35
    M35 --> M46

Loading

---

6. Acceptance

• await answer_kb_question(2, "What is the max bolt torque on the turbine?") returns {answer, source, confidence}
• Latency < 5 s (Sonnet) — single messages.create with max_tokens=1024
• If info absent in KB: answer contains "unknown", not a hallucinated value (system prompt enforces it; test_unknown_answer_is_passed_through_not_hallucinated verifies pass-through)
• If cell has no KB row: returns {answer: "KB not available...", confidence: 0.0} — does NOT raise
• Function performs no DB writes and emits no WS broadcasts (static guard test)

[zestones]

Note

Implemented answer_kb_question per spec on branch 19-m33-onboarding-session-multi-turn (will be split out before merge — also carries M3.3). Backend suite: 103 passed, 0 failed, lint + typecheck clean.

Files added

• backend/agents/kb_builder/qa.py — answer_kb_question(cell_id, question), ~75 LOC, no DB touch, no WS touch.
• backend/tests/unit/agents/kb_builder/test_qa.py — 6 unit tests with mocked mcp_client + anthropic.

Files modified

• backend/agents/kb_builder/init.py — re-export answer_kb_question and document the third sub-module in the package docstring.

Test coverage map

Acceptance	Test
Returns {answer, source, confidence}	test_returns_parsed_json_on_happy_path
answer == "unknown" passed through verbatim	test_unknown_answer_is_passed_through_not_hallucinated
KB missing returns {answer: "KB not available..."} and does NOT raise	test_returns_kb_unavailable_when_mcp_reports_error (also asserts Anthropic is NOT called)
Sonnet transport error returns fallback dict and does NOT raise	test_returns_safe_fallback_when_anthropic_raises
Malformed (non-JSON) Sonnet response returns fallback dict	test_returns_safe_fallback_when_response_is_not_json
No DB writes, no WS broadcasts, always Sonnet	test_module_does_not_import_ws_manager_or_db (AST-based, strips docstrings) + happy-path test asserts model == "claude-sonnet-4-5"

Decisions weighed

Choice	Picked	Why
Module location	agents/kb_builder/qa.py	Matches existing split-by-concern pattern (pdf_extraction.py, onboarding/).
import logging placement	Module top	Single _log per module is the project's convention; the issue's inline import was a stylistic suggestion only.
Bare except Exception	Kept (with # noqa: BLE001)	The safe-fallback contract is explicit in the issue — the Investigator tool loop must keep going.
Integration / e2e test	Skipped	M2.5 already covers get_equipment_kb; this function adds no DB writes. The static guard + 5 behavioural unit tests cover everything testable without a live Anthropic key. The real end-to-end path will be exercised by the M4.6 Investigator tests.

sequenceDiagram
    participant Inv as Investigator (M4.6)
    participant QA as answer_kb_question
    participant MCP as mcp_client
    participant LLM as Sonnet

    Inv->>QA: ask_kb_builder(cell_id, question)
    QA->>MCP: get_equipment_kb(cell_id)
    alt KB missing
        MCP-->>QA: ToolCallResult(is_error=True)
        QA-->>Inv: {answer: "KB not available...", confidence: 0.0}
    else KB present
        MCP-->>QA: ToolCallResult(content=kb_json)
        QA->>LLM: messages.create(model=Sonnet, kb + question)
        alt LLM ok
            LLM-->>QA: JSON answer
            QA-->>Inv: {answer, source, confidence}
        else LLM error or bad JSON
            QA-->>Inv: {answer: "KB query failed...", confidence: 0.0}
        end
    end

Loading

Important

No commits made — branch is staged for the issue owner to commit and push.

[zestones]

Note

Implemented answer_kb_question per spec on branch 19-m33-onboarding-session-multi-turn (will be split out before merge — also carries M3.3). Backend suite: 103 passed, 0 failed, lint + typecheck clean.

Files added

• backend/agents/kb_builder/qa.py — answer_kb_question(cell_id, question), ~75 LOC, no DB touch, no WS touch.
• backend/tests/unit/agents/kb_builder/test_qa.py — 6 unit tests with mocked mcp_client + anthropic.

Files modified

• backend/agents/kb_builder/init.py — re-export answer_kb_question and document the third sub-module in the package docstring.

Test coverage map

Acceptance	Test
Returns {answer, source, confidence}	test_returns_parsed_json_on_happy_path
answer == "unknown" passed through verbatim	test_unknown_answer_is_passed_through_not_hallucinated
KB missing returns {answer: "KB not available..."} and does NOT raise	test_returns_kb_unavailable_when_mcp_reports_error (also asserts Anthropic is NOT called)
Sonnet transport error returns fallback dict and does NOT raise	test_returns_safe_fallback_when_anthropic_raises
Malformed (non-JSON) Sonnet response returns fallback dict	test_returns_safe_fallback_when_response_is_not_json
No DB writes, no WS broadcasts, always Sonnet	test_module_does_not_import_ws_manager_or_db (AST-based, strips docstrings) + happy-path test asserts model == "claude-sonnet-4-5"

Decisions weighed

Choice	Picked	Why
Module location	agents/kb_builder/qa.py	Matches existing split-by-concern pattern (pdf_extraction.py, onboarding/).
import logging placement	Module top	Single _log per module is the project's convention; the issue's inline import was a stylistic suggestion only.
Bare except Exception	Kept (with # noqa: BLE001)	The safe-fallback contract is explicit in the issue — the Investigator tool loop must keep going.
Integration / e2e test	Skipped	M2.5 already covers get_equipment_kb; this function adds no DB writes. The static guard + 5 behavioural unit tests cover everything testable without a live Anthropic key. The real end-to-end path will be exercised by the M4.6 Investigator tests.

sequenceDiagram
    participant Inv as Investigator (M4.6)
    participant QA as answer_kb_question
    participant MCP as mcp_client
    participant LLM as Sonnet

    Inv->>QA: ask_kb_builder(cell_id, question)
    QA->>MCP: get_equipment_kb(cell_id)
    alt KB missing
        MCP-->>QA: ToolCallResult(is_error=True)
        QA-->>Inv: {answer: "KB not available...", confidence: 0.0}
    else KB present
        MCP-->>QA: ToolCallResult(content=kb_json)
        QA->>LLM: messages.create(model=Sonnet, kb + question)
        alt LLM ok
            LLM-->>QA: JSON answer
            QA-->>Inv: {answer, source, confidence}
        else LLM error or bad JSON
            QA-->>Inv: {answer: "KB query failed...", confidence: 0.0}
        end
    end

Loading

Important

No commits made — branch is staged for the issue owner to commit and push.