[KM-687] Add Dedicated /tools/help Endpoint + Regroup Tools List

pr/5 Phase 2 (Sofhia's part of the skills regroup under /tools):

- New POST /api/v1/tools/help (src/api/v1/help.py): dedicated, deterministic
help dispatch — the slash command IS the intent, so no router round-trip and
no misclassification (contract open-Q #2, dedicated endpoint). SSE shape
mirrors chat: sources ([]) -> chunk -> done {message_id}. Generative-only:
does NOT persist the turn (Go owns analyses_messages). message_id is minted
Python-side when Go omits it (open-Q #1), echoed on done.
- ChatHandler.stream_help(): additive method reusing the warm HelpAgent +
state store + is_report_ready. The router help path (handle() intent=="help")
is left intact — BOTH paths stay live by design.
- Rename GET /api/v1/tools -> GET /api/v1/tools/list (tools.py).
- Mount help_router in main.py; mark the two rows done in DEV_PLAN §0.

Verified: app imports clean, /api/v1/tools/help + /api/v1/tools/list mounted,
old /api/v1/tools gone.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

DEV_PLAN.md

@@ -26,8 +26,8 @@ the endpoint contract *before* coding the tools. Status legend: ⬜ not started
 | **2 — v2 + regroup** | Create `src/api/v2/` and move the chat pilot there | Rifqi/Sofhia | ⬜ | Only chat moves to v2; mirror v1 structure. |
 | **2 — v2 + regroup** | Chat: `room_id` → **`analysis_id`** (request field + handler + history) | Rifqi | ⬜ | `ChatRequest` [chat.py:51](src/api/v1/chat.py:51); `done` event returns `message_id`. Ties to #25 (`analyses_messages`). |
 | **2 — v2 + regroup** | Move report under tools → `/api/v1/tools/report` (+ version routes) | Rifqi | ⬜ | Today standalone `/api/v1/report` (still mounted). Same functionality, new path. |
-| **2 — v2 + regroup** | Move help under tools → `POST /api/v1/tools/help` (dedicated endpoint) | Sofhia | ⬜ | Today help is a chat **intent** only. Dedicated endpoint = deterministic dispatch (open Q for Harry). |
-| **2 — v2 + regroup** | Tools list → `/api/v1/tools/list` | Sofhia | ⬜ | Today `GET /api/v1/tools` ([tools.py:133](src/api/v1/tools.py:133)). |
+| **2 — v2 + regroup** | Move help under tools → `POST /api/v1/tools/help` (dedicated endpoint) | Sofhia | ✅ | New `src/api/v1/help.py` (SSE: `sources:[]`→`chunk`→`done{message_id}`) + additive `ChatHandler.stream_help()` (reuses HelpAgent+state+readiness, no router). Generative-only (no persist). **Router `help` intent KEPT** — both paths live by design. message_id minted Python-side if Go omits (open-Q #1). Import-verified. |
+| **2 — v2 + regroup** | Tools list → `/api/v1/tools/list` | Sofhia | ✅ | Renamed route `GET /api/v1/tools` → `GET /api/v1/tools/list` ([tools.py:133](src/api/v1/tools.py:133)). |
 | **2 — v2 + regroup** | FE: slash menu = `/help` only; report = right-side button | Mentor (FE) | ⬜ | Coordination note, not Python work. |
 | **3 — tools + obs** | Finish `help` so it actually **calls** (not just lists) + test | Sofhia | ⬜ | Mentor: help currently only lists tools. Core #2 after chat. |
 | **3 — tools + obs** | Observability **scratchpad** (decorator) accumulating in the chat agent | Rifqi + Sofhia | ⬜ | Capture planning / tool I/O / sources during the run; flush one record on `done`. |

main.py

@@ -19,6 +19,7 @@ from slowapi.errors import RateLimitExceeded
 from src.api.v1.chat import router as chat_router
 from src.api.v1.report import router as report_router
 from src.api.v1.tools import router as tools_router
+from src.api.v1.help import router as help_router  # pr/5 Phase 2: dedicated /tools/help
 from src.db.postgres.init_db import init_db
 import os
 import uvicorn
@@ -63,6 +64,7 @@ app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
 app.include_router(chat_router)
 app.include_router(report_router)
 app.include_router(tools_router)
+app.include_router(help_router)
 
 
 @app.get("/")

src/agents/chat_handler.py

@@ -227,6 +227,55 @@ class ChatHandler:
     # Public entry
     # ------------------------------------------------------------------
 
+    async def stream_help(
+        self,
+        user_id: str,
+        analysis_id: str | None,
+        history: list[BaseMessage] | None = None,
+        message: str | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Deterministic `help` dispatch for the dedicated `/api/v1/tools/help` endpoint.
+
+        Bypasses the intent router — the slash command IS the intent, so there is no
+        classify round-trip and no misclassification risk. Streams the same guidance as
+        the `help` branch of `handle()`, reusing the warm HelpAgent + state store.
+
+        Emits SSE-style events: `sources` (always `[]` — help never references
+        documents), `chunk`*, then `done` (data left empty; the endpoint stamps the
+        `message_id`). On failure, yields a terminal `error` event.
+        """
+        # Load (or lazily create) the analysis state; fail closed to a not-validated
+        # stub so help degrades gracefully on a missing row / read error / legacy id.
+        state: AnalysisState | None = None
+        if analysis_id:
+            try:
+                state = await self._get_state_store().ensure(analysis_id, user_id)
+            except Exception as e:  # noqa: BLE001 — never block help on a state read
+                logger.warning("help state ensure failed", analysis_id=analysis_id, error=str(e))
+        if state is None:
+            state = await self._load_analysis_state(analysis_id)
+
+        # report_ready (seam #5): deterministic, never-throws (fails closed to
+        # not-ready) — the HelpAgent guard only offers generate_report when ready.
+        from .report.readiness import is_report_ready
+
+        report_ready = await is_report_ready(analysis_id, state)
+
+        yield {"event": "sources", "data": json.dumps([])}
+        try:
+            async for token in self._get_help_agent().astream(
+                state,
+                history=history,
+                message=message,
+                report_ready=report_ready,
+            ):
+                yield {"event": "chunk", "data": token}
+        except Exception as e:  # noqa: BLE001
+            logger.error("help streaming failed", user_id=user_id, error=str(e))
+            yield {"event": "error", "data": f"Help generation failed: {e}"}
+            return
+        yield {"event": "done", "data": ""}
+
     async def handle(
         self,
         message: str,

src/api/v1/help.py

@@ -0,0 +1,82 @@
+"""`help` skill endpoint — dedicated, deterministic dispatch (pr/5 Phase 2).
+
+`POST /api/v1/tools/help` streams state-aware next-step guidance over SSE. Unlike v1
+— where `/help` was reachable only by letting the intent router classify a chat
+message — this endpoint dispatches Help directly: the slash command IS the intent, so
+there is no router round-trip and no misclassification risk (contract open-Q #2,
+resolved in favour of a dedicated endpoint).
+
+Contract: `API_ENDPOINTS_RESTRUCTURE.md` §3. The SSE shape mirrors `/chat/stream`, but
+help never references documents, so `sources` is always `[]` and there are no `status`
+pings. The `done` event carries the assistant `message_id` for observability
+correlation (§7).
+
+Python is generative-only (06-25 direction): this endpoint does NOT persist the turn —
+Go owns writes to `analyses_messages`. It only generates + streams.
+"""
+
+import json
+import uuid
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sse_starlette.sse import EventSourceResponse
+
+# Reuse the warm, process-shared ChatHandler (keeps HelpAgent + Azure clients warm)
+# and the same history loader the chat endpoint uses. `load_history` reads by
+# `analysis_id` (== room_id today); it moves to `analyses_messages` with DEV_PLAN #25.
+from src.api.v1.chat import _chat_handler, load_history
+from src.db.postgres.connection import get_db
+from src.middlewares.logging import get_logger, log_execution
+
+logger = get_logger("help_api")
+
+router = APIRouter(prefix="/api/v1/tools", tags=["Tools"])
+
+
+class HelpRequest(BaseModel):
+    user_id: str
+    analysis_id: str
+    # ⚠️ open-Q #1: Go may mint the assistant turn id and pass it; if absent, Python
+    # mints one and returns it on `done` so the FE can call /observability in parallel.
+    message_id: Optional[str] = None
+
+
+@router.post("/help")
+@log_execution(logger)
+async def help_stream(request: HelpRequest, db: AsyncSession = Depends(get_db)):
+    """Stream state-aware next-step guidance (deterministic `/help` dispatch).
+
+    SSE event sequence:
+      1. sources  — always `[]` (help never references documents)
+      2. chunk    — text fragments of the guidance
+      3. done     — `{"message_id": "..."}` for the observability lookup
+    """
+    message_id = request.message_id or f"msg_{uuid.uuid4().hex[:12]}"
+    try:
+        history = await load_history(db, request.analysis_id, limit=10)
+
+        async def stream_response():
+            async for event in _chat_handler.stream_help(
+                request.user_id,
+                request.analysis_id,
+                history=history,
+                message=None,
+            ):
+                if event["event"] == "done":
+                    # Stamp the turn id so the FE can fetch /observability for it.
+                    yield {"event": "done", "data": json.dumps({"message_id": message_id})}
+                elif event["event"] == "error":
+                    yield event
+                    return
+                else:
+                    # `sources` ([]) and `chunk` pass through unchanged.
+                    yield event
+
+        return EventSourceResponse(stream_response())
+
+    except Exception as e:
+        logger.error("Help failed", error=str(e))
+        raise HTTPException(status_code=500, detail=f"Help failed: {str(e)}")

src/api/v1/tools.py

@@ -130,11 +130,14 @@ _COMMAND_CATALOG: list[CommandResponse] = [
 ]
 
 
-@router.get("/tools", response_model=ListToolsResponse)
+@router.get("/tools/list", response_model=ListToolsResponse)
 @log_execution(logger)
 async def list_tools() -> ListToolsResponse:
     """List the user-invocable slash-command catalog (skills + tools).
 
     Static per deployment — safe for the Golang backend to cache.
+
+    pr/5 Phase 2: moved from `GET /api/v1/tools` to `GET /api/v1/tools/list` so the
+    skills group is `/tools/list` · `/tools/help` · `/tools/report`.
     """
     return ListToolsResponse(count=len(_COMMAND_CATALOG), tools=_COMMAND_CATALOG)