From b390fa4d73932182b79151d173fe575e32652efa Mon Sep 17 00:00:00 2001 From: NamH Date: Fri, 13 Dec 2024 08:43:57 +0700 Subject: [PATCH] chore: add thread api docs (#1794) --- docs/static/openapi/cortex.json | 566 +++++++++++++++----------------- engine/controllers/threads.cc | 7 +- 2 files changed, 268 insertions(+), 305 deletions(-) diff --git a/docs/static/openapi/cortex.json b/docs/static/openapi/cortex.json index 9b96ba0a7..ba7944b71 100644 --- a/docs/static/openapi/cortex.json +++ b/docs/static/openapi/cortex.json @@ -908,319 +908,174 @@ }, "/v1/threads": { "post": { - "operationId": "ThreadsController_create", - "summary": "Create thread", - "tags": ["Threads"], - "description": "Creates a new thread.", - "parameters": [], + "summary": "Create Thread", + "description": "Creates a new thread with optional metadata.", "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateThreadDto" - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - } - }, - "get": { - "operationId": "ThreadsController_findAll", - "summary": "List threads", - "tags": ["Threads"], - "description": "Lists all the available threads along with its configurations.", - "parameters": [], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object" + "type": "object", + "properties": { + "metadata": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Title of the thread" + } + }, + "description": "Optional metadata for the thread" } } + }, + "example": { + "metadata": { + "title": "New Thread" + } } } - } - } - } - }, - "/v1/threads/{thread_id}/messages/{message_id}": { - "get": { - "operationId": "ThreadsController_retrieveMessage", - "summary": "Retrieve message", - "tags": ["Messages"], - "description": "Retrieves a message.", - "parameters": [ - { - "name": "thread_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } }, - { - "name": "message_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], + "required": false + }, "responses": { "200": { - "description": "The message object matching the specified ID.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GetMessageResponseDto" - } - } - } - } - } - }, - "post": { - "operationId": "ThreadsController_updateMessage", - "summary": "Modify message", - "tags": ["Messages"], - "description": "Modifies a message.", - "responses": { - "201": { - "description": "", + "description": "Thread created successfully", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "Unix timestamp of when the thread was created" + }, + "id": { + "type": "string", + "description": "Unique identifier for the thread" + }, + "metadata": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Title of the thread" + } + }, + "description": "Metadata associated with the thread" + }, + "object": { + "type": "string", + "description": "Type of object, always 'thread'" + } + }, + "required": ["created_at", "id", "object"] + }, + "example": { + "created_at": 1734020845, + "id": "0001KNP3QDX314435VAEGW1Z2X", + "metadata": { + "title": "New Thread" + }, + "object": "thread" } } } } }, - "parameters": [ - { - "name": "thread_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "message_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateMessageDto" - } - } - } - } + "tags": ["Threads"] }, - "delete": { - "operationId": "ThreadsController_deleteMessage", - "summary": "Delete message", - "description": "Deletes a message.", - "tags": ["Messages"], - "parameters": [ - { - "name": "thread_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "message_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Deletion status.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeleteMessageDto" - } - } - } - } - } - } - }, - "/v1/threads/{thread_id}/messages": { "get": { - "operationId": "ThreadsController_getMessagesOfThread", - "summary": "List messages", - "tags": ["Messages"], - "description": "Returns a list of messages for a given thread.", - "parameters": [ - { - "name": "thread_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "required": true, - "in": "query", - "schema": { - "type": "number" - } - }, - { - "name": "order", - "required": true, - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "after", - "required": true, - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "before", - "required": true, - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "run_id", - "required": true, - "in": "query", - "schema": { - "type": "string" - } - } - ], + "summary": "List Threads", + "description": "Returns a list of threads with their metadata.", "responses": { "200": { - "description": "A list of message objects.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListMessagesResponseDto" - } - } - } - } - } - }, - "post": { - "operationId": "ThreadsController_createMessageInThread", - "summary": "Create message", - "tags": ["Messages"], - "description": "Create a message.", - "responses": { - "201": { - "description": "", + "description": "List of threads retrieved successfully", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of the list response, always 'list'" + }, + "data": { + "type": "array", + "description": "Array of thread objects", + "items": { + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "Unix timestamp of when the thread was created" + }, + "id": { + "type": "string", + "description": "Unique identifier for the thread" + }, + "metadata": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Title of the thread" + }, + "lastMessage": { + "type": "string", + "description": "Content of the last message in the thread" + } + }, + "description": "Metadata associated with the thread" + }, + "object": { + "type": "string", + "description": "Type of object, always 'thread'" + } + }, + "required": ["created_at", "id", "object"] + } + } + }, + "required": ["object", "data"] + }, + "example": { + "data": [ + { + "created_at": 1734020845, + "id": "0001KNP3QDX314435VAEGW1Z2X", + "metadata": { + "title": "New Thread" + }, + "object": "thread" + }, + { + "created_at": 1734020803, + "id": "0001KNP3P3DAQSDVEQGRBTCTNJ", + "metadata": { + "title": "" + }, + "object": "thread" + } + ], + "object": "list" } } } } }, - "parameters": [ - { - "name": "thread_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateMessageDto" - } - } - } - } - } - }, - "/v1/threads/{thread_id}/clean": { - "post": { - "operationId": "ThreadsController_cleanThread", - "summary": "Clean thread", - "description": "Deletes all messages in a thread.", - "tags": ["Threads"], - "parameters": [ - { - "name": "thread_id", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "responses": { - "201": { - "description": "" - } - } + "tags": ["Threads"] } }, - "/v1/threads/{thread_id}": { + "/v1/threads/{id}": { "get": { - "operationId": "ThreadsController_retrieveThread", - "summary": "Retrieve thread", - "tags": ["Threads"], - "description": "Retrieves a thread.", + "summary": "Retrieve Thread", + "description": "Retrieves a specific thread by its ID.", "parameters": [ { - "name": "thread_id", - "required": true, + "name": "id", "in": "path", + "required": true, + "description": "The ID of the thread to retrieve", "schema": { "type": "string" } @@ -1228,27 +1083,65 @@ ], "responses": { "200": { - "description": "Retrieves a thread.", + "description": "Thread retrieved successfully", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetThreadResponseDto" + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "Unix timestamp of when the thread was created" + }, + "id": { + "type": "string", + "description": "Unique identifier for the thread" + }, + "metadata": { + "type": "object", + "properties": { + "lastMessage": { + "type": "string", + "description": "Content of the last message in the thread" + }, + "title": { + "type": "string", + "description": "Title of the thread" + } + }, + "description": "Metadata associated with the thread" + }, + "object": { + "type": "string", + "description": "Type of object, always 'thread'" + } + }, + "required": ["created_at", "id", "object"] + }, + "example": { + "created_at": 1732370026, + "id": "jan_1732370027", + "metadata": { + "lastMessage": "Based on the context, I'm not sure how to build a unique experience quickly and easily. The text mentions that there are some concerns about Android apps providing consistent experiences for different users, which makes me skeptical about building one.\n\nSpecifically, it says:\n\n* \"Might not pass CTS\" (Computer Science Technology standards)\n* \"Might not comply with CDD\" (Consumer Development Division standards)\n\nThis suggests that building a unique experience for all users could be challenging or impossible. Therefore, I don't know how to build a unique experience quickly and easily.\n\nWould you like me to try again?", + "title": "hello" + }, + "object": "thread" } } } } - } + }, + "tags": ["Threads"] }, - "post": { - "operationId": "ThreadsController_modifyThread", - "summary": "Modify thread", - "tags": ["Threads"], - "description": "Modifies a thread.", + "patch": { + "summary": "Modify Thread", + "description": "Updates a specific thread's metadata.", "parameters": [ { - "name": "thread_id", - "required": true, + "name": "id", "in": "path", + "required": true, + "description": "The ID of the thread to modify", "schema": { "type": "string" } @@ -1259,37 +1152,84 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateThreadDto" + "type": "object", + "properties": { + "metadata": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "New title for the thread" + } + }, + "description": "Metadata to update" + } + } + }, + "example": { + "metadata": { + "title": "my title" + } } } } }, "responses": { "200": { - "description": "The thread has been successfully updated.", + "description": "Thread modified successfully", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateThreadDto" + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "Unix timestamp of when the thread was created" + }, + "id": { + "type": "string", + "description": "Unique identifier for the thread" + }, + "metadata": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Updated title of the thread" + } + }, + "description": "Updated metadata for the thread" + }, + "object": { + "type": "string", + "description": "Type of object, always 'thread'" + } + }, + "required": ["created_at", "id", "object"] + }, + "example": { + "created_at": 1733301054, + "id": "0001KN04SY7D75K0MPTXMXCH39", + "metadata": { + "title": "my title" + }, + "object": "thread" } } } - }, - "201": { - "description": "" } - } + }, + "tags": ["Threads"] }, "delete": { - "operationId": "ThreadsController_remove", - "summary": "Delete thread", - "tags": ["Threads"], - "description": "Deletes a specific thread defined by a thread `id` .", + "summary": "Delete Thread", + "description": "Deletes a specific thread by its ID.", "parameters": [ { - "name": "thread_id", - "required": true, + "name": "id", "in": "path", + "required": true, + "description": "The ID of the thread to delete", "schema": { "type": "string" } @@ -1297,16 +1237,37 @@ ], "responses": { "200": { - "description": "The thread has been successfully deleted.", + "description": "Thread deleted successfully", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteThreadResponseDto" + "type": "object", + "properties": { + "deleted": { + "type": "boolean", + "description": "Indicates if the thread was successfully deleted" + }, + "id": { + "type": "string", + "description": "ID of the deleted thread" + }, + "object": { + "type": "string", + "description": "Type of object, always 'thread.deleted'" + } + }, + "required": ["deleted", "id", "object"] + }, + "example": { + "deleted": true, + "id": "jan_1732370027", + "object": "thread.deleted" } } } } - } + }, + "tags": ["Threads"] } }, "/v1/system": { @@ -2692,6 +2653,7 @@ "Files", "Hardware", "Events", + "Threads", "Pulling Models", "Running Models", "Processes", diff --git a/engine/controllers/threads.cc b/engine/controllers/threads.cc index 81e14ce5a..4a87bc9eb 100644 --- a/engine/controllers/threads.cc +++ b/engine/controllers/threads.cc @@ -193,10 +193,11 @@ void Threads::ModifyThread( resp->setStatusCode(k400BadRequest); callback(resp); } else { - res->ToJson()->removeMember("title"); - res->ToJson()->removeMember("assistants"); + auto json_res = res->ToJson(); + json_res->removeMember("title"); + json_res->removeMember("assistants"); auto resp = - cortex_utils::CreateCortexHttpJsonResponse(res->ToJson().value()); + cortex_utils::CreateCortexHttpJsonResponse(json_res.value()); resp->setStatusCode(k200OK); callback(resp); }