diff --git a/docs/docs/specs/messages.md b/docs/docs/specs/messages.md index 66e4eeaa22..7133d23d3c 100644 --- a/docs/docs/specs/messages.md +++ b/docs/docs/specs/messages.md @@ -2,57 +2,70 @@ title: Messages --- -:::warning +:::caution -Draft Specification: functionality has not been implemented yet. - -Feedback: [HackMD: Threads Spec](https://hackmd.io/BM_8o_OCQ-iLCYhunn2Aug) +This is currently under development. ::: -Messages are within `threads` and capture additional metadata. -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages +## Overview -## Message Object -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/object -```json -{ - // Jan specific properties - "updatedAt": "...", // that's it I think +`Messages` are in `threads` and capture additional metadata: - // OpenAI compatible properties: https://platform.openai.com/docs/api-reference/messages) - "id": "msg_dKYDWyQvtjDBi3tudL1yWKDa", - "object": "thread.message", - "created_at": 1698983503, - "thread_id": "thread_RGUhOuO9b2nrktrmsQ2uSR6I", - "role": "assistant", - "content": [ - { - "type": "text", - "text": { - "value": "Hi! How can I help you today?", - "annotations": [] - } +- Users can ... + +## Folder Structure + +- `Message` objects are in `thread.json` files under `messages` property. See [threads](./threads.md) + +## `message` object + +### Example + +Here's a standard example `message` json. + +```json +"id": "0", // Sequential or UUID? +"object": "thread.message", // Defaults to "thread.message" +"created_at": 1698983503, +"thread_id": "thread_asdf", // Defaults to parent thread +"role": "assistant", // Defaults to "user" or "assistant" +"content": [ + { + "type": "text", + "text": { + "value": "Hi! How can I help you today?", + "annotations": [] } - ], - "file_ids": [], - "assistant_id": "asst_ToSF7Gb04YMj8AMMm50ZLLtY", - "run_id": "run_BjylUJgDqYK9bOhy4yjAiMrn", - "metadata": {} -} + } +], +"assistant_id": "...", +"run_id": "...", // The `run` resulting in this message +"metadata": {}, // Defaults to {} +// "file_ids": [], ``` -## Messages API -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages +## API Reference + +Jan's Threads API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally. + +See [Jan Messages API](https://jan.ai/api-reference#tag/Messages) + + ### Get list message + > OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/getMessage + - Example request + ```shell curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \ -H "Content-Type: application/json" ``` + - Example response + ```json { "id": "msg_abc123", @@ -75,9 +88,13 @@ Messages are within `threads` and capture additional metadata. "metadata": {} } ``` + ### Create message + > OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/createMessage + - Example request + ```shell curl -X POST {JAN_URL}/v1/threads/{thread_id}/messages \ -H "Content-Type: application/json" \ @@ -86,93 +103,112 @@ Messages are within `threads` and capture additional metadata. "content": "How does AI work? Explain it in simple terms." }' ``` + - Example response + ```json - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "thread_id": "thread_abc123", - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "thread_id": "thread_abc123", + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] } - ], - "file_ids": [], - "assistant_id": null, - "run_id": null, - "metadata": {} - } + } + ], + "file_ids": [], + "assistant_id": null, + "run_id": null, + "metadata": {} +} ``` + ### Get message + > OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/listAssistants + - Example request + ```shell curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \ -H "Content-Type: application/json" ``` + - Example response + ```json - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "thread_id": "thread_abc123", - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "thread_id": "thread_abc123", + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] } - ], - "file_ids": [], - "assistant_id": null, - "run_id": null, - "metadata": {} - } + } + ], + "file_ids": [], + "assistant_id": null, + "run_id": null, + "metadata": {} +} ``` ### Modify message + > Jan: TODO: Do we need to modify message? Or let user create new message? # Get message file + > OpenAI Equivalent: https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id} + - Example request + ```shell curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id}/files/{file_id} \ -H "Content-Type: application/json" ``` + - Example response + ```json - { - "id": "file-abc123", - "object": "thread.message.file", - "created_at": 1699061776, - "message_id": "msg_abc123" - } +{ + "id": "file-abc123", + "object": "thread.message.file", + "created_at": 1699061776, + "message_id": "msg_abc123" +} ``` + # List message files + > OpenAI Equivalent: https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files -``` + +```` - Example request ```shell curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id}/files/{file_id} \ -H "Content-Type: application/json" -``` +```` + - Example response + ```json - { - "id": "file-abc123", - "object": "thread.message.file", - "created_at": 1699061776, - "message_id": "msg_abc123" - } -``` \ No newline at end of file +{ + "id": "file-abc123", + "object": "thread.message.file", + "created_at": 1699061776, + "message_id": "msg_abc123" +} +``` diff --git a/docs/docs/specs/models.md b/docs/docs/specs/models.md index fa33a3755a..471904bc58 100644 --- a/docs/docs/specs/models.md +++ b/docs/docs/specs/models.md @@ -53,12 +53,12 @@ Here's a standard example `model.json` for a GGUF model. - `source_url`: https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/. ```json -"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf", -"type": "model", // Defaults to "model" -"version": "1", // Defaults to 1 "id": "zephyr-7b" // Defaults to foldername +"object": "model", // Defaults to "model" +"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf", "name": "Zephyr 7B" // Defaults to foldername "owned_by": "you" // Defaults to you +"version": "1", // Defaults to 1 "created": 1231231 // Defaults to file creation time "description": "" "state": enum[null, "downloading", "ready", "starting", "stopping", ...] diff --git a/docs/docs/specs/threads.md b/docs/docs/specs/threads.md index c424e0a63b..98e3af5b10 100644 --- a/docs/docs/specs/threads.md +++ b/docs/docs/specs/threads.md @@ -41,23 +41,16 @@ jan/ Here's a standard example `thread.json` for a conversation between the user and the default Jan assistant. ```json -"type": "thread", // Defaults to "thread" +"id": "thread_....", // Defaults to foldername +"object": "thread", // Defaults to "thread" "summary": "funny physics joke", // Defaults to "" "assistants": ["jan"], // Defaults to "jan" "created": 1231231 // Defaults to file creation time "metadata": {}, // Defaults to {} -"messages": [ - {...message_0}, {...message_1} -], -"model_id": "...", // Do we need this property? -// Overrides assistant.settings && model.settings -"settings": { - ... -}, -// Overrides assistant.settings && model.settings -"parameters": { - ... -}, +"messages": [], +"model_id": "...", // Defaults to assistant.model ??? +"settings": {}, // Defaults to and overrides assistant.settings +"parameters": {}, // Defaults to and overrides assistant.settings ``` ## API Reference @@ -66,7 +59,7 @@ Jan's Threads API is compatible with [OpenAI's Threads API](https://platform.ope See [Jan Threads API](https://jan.ai/api-reference#tag/Threads) - + ### Get thread