diff --git a/docs/docs/specs/messages.md b/docs/docs/specs/messages.md index 66e4eeaa22..dbee33fe49 100644 --- 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) + + + diff --git a/docs/docs/specs/models.md b/docs/docs/specs/models.md index 8516264316..471904bc58 100644 --- 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. ::: diff --git a/docs/docs/specs/threads.md b/docs/docs/specs/threads.md index d5bc15c8f2..c9d9c9d4ce 100644 --- a/docs/docs/specs/threads.md +++ b/docs/docs/specs/threads.md @@ -2,89 +2,101 @@ title: Threads --- -:::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. ::: -## User Stories - -_Users can chat with an assistant in a thread_ +## Overview -- See [Messages Spec](./messages.md) +`Threads` are conversations between an `assistant` and the user: -_Users can change assistant and model parameters in a thread_ +- Users can tweak `model` params and `assistant` behavior within each thread. +- Users can import and export threads. +- An [OpenAI Thread API](https://platform.openai.com/docs/api-reference/threads) compatible endpoint at `localhost:3000/v1/threads`. -- Wireframes of +## Folder Structure -_Users can delete all thread history_ +- Threads are saved in the `/threads` folder. +- Threads are organized by folders, one for each thread, and can be easily zipped, exported, and cleared. +- Thread folders follow the naming: `assistant_id` + `thread_created_at`. +- Thread folders also contain `messages.jsonl` files. See [messages](/specs/messages). -- Wireframes of settings page. +```sh +jan/ + threads/ + assistant_name_unix_timestamp/ + thread.json + messages.jsonl + jan_2341243134/ + thread.json +``` -## Jan Thread Object +## `thread.json` -- A `Jan Thread Object` is a "representation of a conversation thread" between an `assistant` and the user -- Objects are defined by `thread-uuid.json` files in `json` format -- Objects are designed to be compatible with `OpenAI Thread Objects` with additional properties needed to run on our infrastructure. -- Objects contain a `models` field, to track when the user overrides the assistant's default model parameters. +- Each `thread` folder contains a `thread.json` file, which is a representation of a thread. +- `thread.json` contains metadata and model parameter overrides. +- There are no required fields. -| Property | Type | Description | Validation | -| ---------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -| `object` | enum: `model`, `assistant`, `thread`, `message` | The Jan Object type | Defaults to `thread` | -| `assistants` | array | An array of Jan Assistant Objects. Threads can "override" an assistant's parameters. Thread-level model parameters are directly saved in the `thread.models` property! (see Models spec) | Defaults to `assistant.name` | -| `messages` | array | An array of Jan Message Objects. (see Messages spec) | Defaults to `[]` | -| `metadata` | map | Useful for storing additional information about the object in a structured format. | Defaults to `{}` | +### Example -### Generic Example +Here's a standard example `thread.json` for a conversation between the user and the default Jan assistant. ```json -// janroot/threads/jan_1700123404.json -"assistants": ["assistant-123"], -"messages": [ - {...message0}, {...message1} +"id": "thread_....", // Defaults to foldername +"object": "thread", // Defaults to "thread" +"title": "funny physics joke", // Defaults to "" +"assistants": [ + { + "assistant_id": "jan", // Defaults to "jan" + "model": { // Defaults to 1 currently active model (can be changed before thread is begun) + "settings": {}, // Defaults to and overrides assistant.json's "settings" (and if none, then model.json "settings") + "parameters": {}, // Defaults to and overrides assistant.json's "parameters" (and if none, then model.json "parameters") + } + }, ], -"metadata": { - "summary": "funny physics joke", -}, +"created": 1231231 // Defaults to file creation time +"metadata": {}, // Defaults to {} ``` -## Filesystem +## API Reference -- `Jan Thread Objects`'s `json` files always has the naming schema: `assistant_uuid` + `unix_time_thread_created_at. See below. -- Threads are all saved in the `janroot/threads` folder in a flat folder structure. -- The folder is standalone and can be easily zipped, exported, and cleared. +Jan's Threads API is compatible with [OpenAI's Threads API](https://platform.openai.com/docs/api-reference/threads), with additional methods for managing threads locally. -```sh -janroot/ - threads/ - jan_1700123404.json - homework_helper_700120003.json -``` +See [Jan Threads API](https://jan.ai/api-reference#tag/Threads) -## Jan API + + Can achieve this goal by calling `Get Thread` API + +-> Can achieve this goal by calling `Get Thread` API --> diff --git a/docs/sidebars.js b/docs/sidebars.js index 477b82a548..745a16a7fe 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -61,8 +61,8 @@ const sidebars = { items: [ "specs/chats", "specs/models", - // "specs/threads", - // "specs/messages", + "specs/threads", + "specs/messages", // "specs/assistants", // "specs/files", // "specs/jan",