Chat endpoints

refs #114

This is an overall description of how to interact with the chat feature of the assistant via the OCS API.
The messages are grouped in conversations (sessions).

• Session
  • id
  • timestamp: the creation date
  • title
  • agency_conversation_token: only set when using agency
  • agency_pending_actions: only set when using agency
• Message
  • id
  • session_id
  • role: system (system prompt added by the assistant), human (messages written by the user) or assistant (LLM messages)
  • ocp_task_id: The related task processing task ID, the one that produced the content of the message (only for assistant role tasks)
  • sources: only set when using agency
  • attachments: only set when using audio chat

Sequence of actions

This is the classic course of actions (API calls):

• Create a session (if needed)
• Create a human message in the session
• Ask the assistant to generate a response to the last human message of a session. This returns a taskprocessing task ID.
• Poll the message generation status until it finishes and returns the new message

Endpoints

All endpoints are OCS

• List sessions: GET /ocs/v2.php/apps/assistant/chat/sessions
• Delete a session: DELETE /ocs/v2.php/apps/assistant/chat/delete_session
  • sessionId
• Create a session: PUT /ocs/v2.php/apps/assistant/chat/new_session with params
  • title: session title, is optional
  • timestamp
• Create a message: PUT /ocs/v2.php/apps/assistant/chat/new_message
  • sessionId
  • role
  • content
  • timestamp
  • attachments: optional, only useful when using agency
  • firstHumanMessage: boolean, set it to true if it is the first human message of the session
• Delete a message: DELETE /ocs/v2.php/apps/assistant/chat/delete_message
  • messageId
  • sessionId
• Ask to generate new assistant message/response in the session: GET /ocs/v2.php/apps/assistant/chat/generate , no parameters
• Get messages of a session: GET /ocs/v2.php/apps/assistant/chat/messages
  • sessionId

Other endpoints are documented in the OpenAPI specs that can be browsed with the ocs_api_viewer app while the assistant app is installed

Review the endpoint list and request sequence in this issue, then inspect the OpenAPI specs through the ocs_api_viewer app while the assistant is installed. Done means the chat sessions, messages, and generation workflow are documented consistently with those specifications.