Merge pull request janhq#681 from janhq/threads

docs: threads and messages
akiroussama · Nov 22, 2023 · 5a9e39e · 5a9e39e
2 parents df163a8 + ac1075f
commit 5a9e39e
Show file tree

Hide file tree

Showing 4 changed files with 292 additions and 178 deletions.
diff --git a/docs/docs/specs/messages.md b/docs/docs/specs/messages.md
@@ -2,57 +2,114 @@
 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
+
+`Messages` capture a conversation's content. This can include the content from LLM responses and other metadata from [chat completions](/specs/chats).
+
+- Users and assistants can send multimedia messages.
+- An [OpenAI Message API](https://platform.openai.com/docs/api-reference/messages) compatible endpoint at `localhost:3000/v1/messages`.
+
+## Folder Structure
+
+Messages are saved in the `/threads/{thread_id}` folder in `messages.jsonl` files
+
+```sh
+jan/
+    threads/
+        assistant_name_unix_timestamp/
+            ...
+            messages.jsonl
+        jan_2341243134/
+            ...
+            messages.jsonl
+```
+
+## `message.jsonl`
+
+Individual messages are saved in `jsonl` format for indexing purposes.
 
-## Message Object
-> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/object
 ```json
-{
-  // Jan specific properties
-  "updatedAt": "...", // that's it I think
+{...message_2}
+{...message_1}
+{...message_0}
+```
 
-  // 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": []
-      }
+### Examples
+
+Here's a standard example `message` sent from a user.
+
+```json
+"id": "0",                            // Sequential or UUID
+"object": "thread.message",           // Defaults to "thread.message"
+"created_at": 1698983503,
+"thread_id": "thread_asdf",           // Defaults to parent thread
+"assistant_id": "jan",                // Defaults to parent thread
+"role": "user",                  // From either "user" or "assistant"
+"content": [
+  {
+    "type": "text",
+    "text": {
+      "value": "Hi!?",
+      "annotations": []
     }
-  ],
-  "file_ids": [],
-  "assistant_id": "asst_ToSF7Gb04YMj8AMMm50ZLLtY",
-  "run_id": "run_BjylUJgDqYK9bOhy4yjAiMrn",
-  "metadata": {}
-}
+  }
+],
+"metadata": {},                       // Defaults to {}
+// "run_id": "...",                   // Rather than `run` id abstraction
+// "file_ids": [],
+```
+
+Here's an example `message` response from an assistant.
+
+```json
+"id": "0",                            // Sequential or UUID
+"object": "thread.message",           // Defaults to "thread.message"
+"created_at": 1698983503,
+"thread_id": "thread_asdf",           // Defaults to parent thread
+"assistant_id": "jan",                // Defaults to parent thread
+"role": "assistant",                  // From either "user" or "assistant"
+"content": [                          // Usually from Chat Completion obj
+  {
+    "type": "text",
+    "text": {
+      "value": "Hi! How can I help you today?",
+      "annotations": []
+    }
+  }
+],
+"metadata": {},                       // Defaults to {}
+// "run_id": "...",                   // KIV
+// "file_ids": [],                    // KIV
+// "usage": {}                        // KIV: saving chat completion properties https://platform.openai.com/docs/api-reference/chat/object
 ```
 
-## Messages API
-> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages
+## API Reference
+
+Jan's `messages` 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)
+
+<!-- TODO clean this part up into API -->
+<!--
 ### 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 +132,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 +147,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"
-  }
-```
+{
+  "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
@@ -4,7 +4,7 @@ title: Models
 
 :::caution
 
-Draft Specification: functionality has not been implemented yet.
+This is currently under development.
 
 :::
 
@@ -46,19 +46,19 @@ jan/                               # Jan root folder
 - `model.json` contains metadata and default parameters used to run a model.
 - The only required field is `source_url`.
 
-### GGUF Example
+### Example
 
 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", ...]
@@ -95,7 +95,7 @@ See [Jan Models API](https://jan.ai/api-reference#tag/Models)
 
 :::caution
 
-This is current under development.
+This is currently under development.
 
 :::