docs/frontend_api_spec.md

Vectorless-RAG Backend API Specification

This document provides the API endpoints, request payloads, response schemas, and Server-Sent Events (SSE) stream structures exposed by the FastAPI backend to build the frontend.

---

Base Configuration

• Local URL: http://127.0.0.1:8000
• CORS: Configured to allow all origins (*) and standard headers (Authorization, Content-Type).

---

Endpoints

1. Health Status

Verify that the backend service and index structures are loaded.

• Method: GET
• Path: /
• Response:

  {
    "status": "online",
    "message": "Vectorless-RAG Legal Assistant API is fully operational locally."
  }
  

---

2. Stream Chat Message (Server-Sent Events)

Sends a user message to the ReAct agent and streams the agent's internal thoughts, tool calls, tool outputs, and the final cited response.

• Method: POST
• Path: /api/chats/{thread_id}/message
• URL Parameters:
  • thread_id (string, required): A unique conversation identifier (e.g., UUID or custom slug). Memory checkpoints are keyed by this ID.
• Request Body:
  • Content-Type: application/json
  • Body:

    {
      "message": "What is the punishment for robbery?"
    }
    

• Response:
  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive

SSE Stream Events Structure

Each event is emitted in the standard format data: <JSON_STRING>\n\n. The data object always contains a type key telling the frontend how to render it.

Event A: Agent Thought

Fires when the agent is reasoning about its next step.

data: {"type": "thought", "content": "Under the Bharatiya Nyaya Sanhita (BNS), I need to find the specific section for robbery. I will call search_statutes."}

Event B: Tool Call

Fires when the agent decides to execute one of the legal search tools.

data: {"type": "tool_call", "name": "search_statutes", "args": {"query": "robbery punishment", "statute_code": "BNS"}}

Event C: Observation (Tool Output)

Fires when the tool completes, returning the raw observation context (truncated to keep payload lightweight).

data: {"type": "observation", "content": "BNS_S309: Robbery. Whoever commits robbery shall be punished with rigorous imprisonment for a term which may extend to ten years..."}

Event D: Final Answer

Fires once the agent finishes reasoning and outputs the final structured markdown answer. This is the last event of the stream.

data: {
  "type": "final_answer",
  "answer_text": "Under the Bharatiya Nyaya Sanhita (BNS), robbery is punishable with rigorous imprisonment up to ten years...",
  "key_provisions": [
    "- General robbery: Rigorous imprisonment up to 10 years [Source: BNS_S309].",
    "- Highway robbery (sunset to sunrise): Imprisonment up to 14 years [Source: BNS_S309]."
  ],
  "citations": [
    {
      "node_id": "BNS_S309",
      "title": "309. Robbery",
      "page_range": [82, 83]
    }
  ],
  "is_insufficient_context": false,
  "confidence": 1.0,
  "latency_ms": 8450
}

Event E: Error

Fires if any exception occurs during agent graph execution.

data: {"type": "error", "content": "API streaming error: Rate limit exceeded."}

---

3. Retrieve Chat History

Loads the saved message history for a specific thread from the backend checkpointer.

• Method: GET
• Path: /api/chats/{thread_id}/history
• URL Parameters:
  • thread_id (string, required): The target conversation identifier.
• Response:
  • Content-Type: application/json
  • Body:

    {
      "thread_id": "test-thread-123",
      "messages": [
        {
          "role": "user",
          "content": "What is the punishment for robbery?"
        },
        {
          "role": "assistant",
          "content": "Under the Bharatiya Nyaya Sanhita (BNS), robbery is punishable with rigorous imprisonment up to ten years..."
        }
      ]
    }