From fc9ce395f615bb83b4bb5bf2ac139859f814eb2f Mon Sep 17 00:00:00 2001 From: hieu-jan <150573299+hieu-jan@users.noreply.github.com> Date: Thu, 30 Nov 2023 10:27:04 +0900 Subject: [PATCH] docs: new version API reference --- docs/openapi/jan.yaml | 128 ++++++------------------------ docs/openapi/specs/assistant.yaml | 59 ++++++++++++++ docs/openapi/specs/chat.yaml | 18 +---- docs/openapi/specs/messages.yaml | 18 +---- docs/openapi/specs/models.yaml | 4 - docs/openapi/specs/threads.yaml | 19 ++--- docs/src/styles/base.scss | 13 +++ 7 files changed, 105 insertions(+), 154 deletions(-) create mode 100644 docs/openapi/specs/assistant.yaml diff --git a/docs/openapi/jan.yaml b/docs/openapi/jan.yaml index 445daf8a46..49c59c5c32 100644 --- a/docs/openapi/jan.yaml +++ b/docs/openapi/jan.yaml @@ -23,19 +23,7 @@ tags: - name: Messages description: | 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:1337/v1/messages`. - - - 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. - - name: Threads - description: | - Threads are conversations between an `assistant` and the user: - - 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:1337/v1/threads`. - name: Assistants description: Configures and utilizes different AI assistants for varied tasks x-tagGroups: @@ -54,12 +42,10 @@ paths: operationId: createChatCompletion tags: - Chat - summary: Create chat completion + summary: | + Create chat completion description: | - - and Jan - - Creates a model response for the given chat conversation. + Creates a model response for the given chat conversation. Equivalent to OpenAI's create chat completion. requestBody: content: application/json: @@ -93,12 +79,9 @@ paths: operationId: listModels tags: - Models - summary: List models description: | - - - Lists the currently available models, and provides basic information about each one such as the owner and availability. + Lists the currently available models, and provides basic information about each one such as the owner and availability. Equivalent to OpenAI's list model. responses: "200": description: OK @@ -116,8 +99,6 @@ paths: - Models summary: Download model description: | - Jan - Download a model. responses: "200": @@ -137,9 +118,7 @@ paths: - Models summary: Retrieve model description: | - - - Get a model instance, providing basic information about the model such as the owner and permissioning. + Get a model instance, providing basic information about the model such as the owner and permissioning. Equivalent to OpenAI's retrieve model. parameters: - in: path name: model_id @@ -150,8 +129,6 @@ paths: example: zephyr-7b description: | The ID of the model to use for this request - - OpenAI compatible responses: "200": description: OK @@ -169,9 +146,7 @@ paths: - Models summary: Delete model description: | - - - Delete a model. + Delete a model. Equivalent to OpenAI's delete model. parameters: - in: path name: model @@ -181,8 +156,6 @@ paths: example: zephyr-7b description: | The model to delete - - OpenAI compatible responses: "200": description: OK @@ -201,8 +174,6 @@ paths: - Models summary: Start model description: | - Jan - Starts an imported model. Loads the model into V/RAM. parameters: - in: path @@ -232,8 +203,6 @@ paths: - Models summary: Stop model description: | - Jan - Stop an imported model. parameters: - in: path @@ -264,9 +233,7 @@ paths: - Threads summary: Create thread description: | - - - Create a thread + Create a thread. Equivalent to OpenAI's create thread. requestBody: required: false content: @@ -307,8 +274,6 @@ paths: - Threads summary: List threads description: | - Jan - Retrieves a list of all threads available in the system. responses: "200": @@ -344,9 +309,7 @@ paths: - Threads summary: Retrieve thread description: | - - - Retrieves detailed information about a specific thread using its thread_id. + Retrieves detailed information about a specific thread using its thread_id. Equivalent to OpenAI's retrieve thread. parameters: - in: path name: thread_id @@ -357,7 +320,6 @@ paths: description: | The ID of the thread to retrieve. - OpenAI compatible responses: "200": description: Thread details retrieved successfully @@ -375,9 +337,7 @@ paths: - Threads summary: Modify thread description: | - - - Modifies a thread + Modifies a thread. Equivalent to OpenAI's modify thread. parameters: - in: path name: thread_id @@ -388,7 +348,6 @@ paths: description: | The ID of the thread to be modified. - OpenAI compatible requestBody: required: false content: @@ -430,9 +389,7 @@ paths: - Threads summary: Delete thread description: | - - - Delete a thread + Delete a thread. Equivalent to OpenAI's delete thread. parameters: - in: path name: thread_id @@ -443,7 +400,6 @@ paths: description: | The ID of the thread to be deleted. - OpenAI compatible responses: "200": description: Thread deleted successfully @@ -464,7 +420,7 @@ paths: - Threads summary: Get Thread.Assistants description: | - Jan + Can achieve this goal by calling Get thread API parameters: @@ -494,7 +450,7 @@ paths: - Threads summary: Modify Thread.Assistants description: | - Jan + Can achieve this goal by calling Modify Assistant API with thread.assistant[] @@ -505,7 +461,7 @@ paths: - Threads summary: List Thread.Messages description: | - Jan + Can achieve this goal by calling Get Thread API parameters: @@ -536,9 +492,7 @@ paths: - Messages summary: List messages description: | - - - Retrieves all messages from the given thread. + Retrieves all messages from the given thread. Equivalent to OpenAI's list messages. parameters: - in: path name: thread_id @@ -549,7 +503,6 @@ paths: description: | The ID of the thread from which to retrieve messages. - OpenAI compatible responses: "200": description: List of messages retrieved successfully @@ -568,9 +521,7 @@ paths: - Messages summary: Create message description: | - - - Create a message + Create a message. Equivalent to OpenAI's list messages. parameters: - in: path name: thread_id @@ -581,7 +532,6 @@ paths: description: | The ID of the thread to which the message will be posted. - OpenAI compatible requestBody: required: true content: @@ -594,7 +544,7 @@ paths: description: | "Role of the sender, either 'user' or 'assistant'." - OpenAI compatible + OpenAI compatible example: "user" enum: ["user", "assistant"] content: @@ -602,7 +552,7 @@ paths: description: | "Text content of the message." - OpenAI compatible + OpenAI compatible example: "How does AI work? Explain it in simple terms." required: - role @@ -631,9 +581,7 @@ paths: - Messages summary: Retrieve message description: | - - - Retrieve a specific message from a thread using its thread_id and message_id. + Retrieve a specific message from a thread using its thread_id and message_id. Equivalent to OpenAI's retrieve messages. parameters: - in: path name: thread_id @@ -644,7 +592,6 @@ paths: description: | The ID of the thread containing the message. - OpenAI compatible - in: path name: message_id required: true @@ -654,7 +601,6 @@ paths: description: | The ID of the message to retrieve. - OpenAI compatible responses: "200": description: OK @@ -673,11 +619,10 @@ paths: operationId: listMessageFiles tags: - Messages - summary: List message files + summary: | + List message files description: | - - - Returns a list of message files. + Returns a list of message files. Equivalent to OpenAI's list message files. parameters: - in: path name: thread_id @@ -688,7 +633,6 @@ paths: description: | The ID of the thread containing the message. - OpenAI compatible - in: path name: message_id required: true @@ -698,7 +642,6 @@ paths: description: | The ID of the message whose files are to be listed. - OpenAI compatible responses: "200": description: List of files retrieved successfully @@ -719,9 +662,7 @@ paths: - Messages summary: Retrieve message file description: | - - - Retrieves a file associated with a specific message in a thread. + Retrieves a file associated with a specific message in a thread. Equivalent to OpenAI's retrieve message file. parameters: - in: path name: thread_id @@ -732,7 +673,6 @@ paths: description: | The ID of the thread containing the message. - OpenAI compatible - in: path name: message_id required: true @@ -742,7 +682,6 @@ paths: description: | The ID of the message associated with the file. - OpenAI compatible - in: path name: file_id required: true @@ -752,7 +691,6 @@ paths: description: | The ID of the file to retrieve. - OpenAI compatible responses: "200": description: File retrieved successfully @@ -771,11 +709,7 @@ x-webhooks: post: summary: The model object description: | - - - Describe a model offering that can be used with the API. - - + Describe a model offering that can be used with the API. Equivalent to OpenAI's model object. operationId: ModelObject tags: - Models @@ -784,14 +718,11 @@ x-webhooks: application/json: schema: $ref: 'specs/models.yaml#/components/schemas/ModelObject' - MessageObject: post: summary: The message object description: | - - - Information about a message in the thread + Information about a message in the thread. Equivalent to OpenAI's message object. operationId: MessageObject tags: - Messages @@ -800,19 +731,10 @@ x-webhooks: application/json: schema: $ref: 'specs/messages.yaml#/components/schemas/MessageObject' - ThreadObject: post: summary: The thread object - description: | - and Jan - - 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. - + description: Represents a thread that contains messages. Equivalent to OpenAI's thread object. operationId: ThreadObject tags: - Threads diff --git a/docs/openapi/specs/assistant.yaml b/docs/openapi/specs/assistant.yaml new file mode 100644 index 0000000000..95b4cd22dd --- /dev/null +++ b/docs/openapi/specs/assistant.yaml @@ -0,0 +1,59 @@ +AssistantObject: + type: object + properties: + avatar: + type: string + description: "URL of the assistant's avatar. Jan-specific property." + example: "https://lala.png" + id: + type: string + description: "The identifier of the assistant." + example: "asst_abc123" + object: + type: string + description: "Type of the object, indicating it's an assistant." + default: "assistant" + version: + type: integer + description: "Version number of the assistant." + example: 1 + created_at: + type: integer + format: int64 + description: "Unix timestamp representing the creation time of the assistant." + name: + type: string + description: "Name of the assistant." + example: "Math Tutor" + description: + type: string + description: "Description of the assistant. Can be null." + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + # Additional properties for models can be added here + events: + type: object + description: "Event subscription settings for the assistant." + properties: + in: + type: array + items: + type: string + out: + type: array + items: + type: string + # If there are specific event types, they can be detailed here + metadata: + type: object + description: "Metadata associated with the assistant." + required: + - name + - models + - events \ No newline at end of file diff --git a/docs/openapi/specs/chat.yaml b/docs/openapi/specs/chat.yaml index db738aee50..05444c444b 100644 --- a/docs/openapi/specs/chat.yaml +++ b/docs/openapi/specs/chat.yaml @@ -59,8 +59,6 @@ components: type: arrays description: | Contains input data or prompts for the model to process - - OpenAI compatible example: [ { "content": "Hello there :wave:", "role": "assistant" }, @@ -71,43 +69,31 @@ components: example: model-zephyr-7B description: | Specifies the model being used for inference or processing tasks - - OpenAI compatible stream: type: boolean default: true description: | Enables continuous output generation, allowing for streaming of model responses - - OpenAI compatible max_tokens: type: number default: 2048 description: | The maximum number of tokens the model will generate in a single response - - OpenAI compatible stop: type: arrays example: ["hello"] description: | Defines specific tokens or phrases at which the model will stop generating further output - - OpenAI compatible frequency_penalty: type: number default: 0 description: | Adjusts the likelihood of the model repeating words or phrases in its output - - OpenAI compatible presence_penalty: type: number default: 0 description: | Influences the generation of new and varied concepts in the model's output - - OpenAI compatible temperature: type: number default: 0.7 @@ -115,8 +101,6 @@ components: max: 1 description: | Controls the randomness of the model's output - - OpenAI compatible top_p: type: number default: 0.95 @@ -125,7 +109,7 @@ components: description: | Set probability threshold for more relevant outputs - OpenAI compatible + ChatCompletionResponse: type: object diff --git a/docs/openapi/specs/messages.yaml b/docs/openapi/specs/messages.yaml index d4f61117e9..b99fc4221b 100644 --- a/docs/openapi/specs/messages.yaml +++ b/docs/openapi/specs/messages.yaml @@ -7,36 +7,26 @@ components: type: string description: | "Sequential or UUID identifier of the message." - - OpenAI compatible example: 0 object: type: string description: | "Type of the object, defaults to 'thread.message'." - - OpenAI compatible example: thread.message created_at: type: integer format: int64 description: | "Unix timestamp representing the creation time of the message." - - OpenAI compatible thread_id: type: string description: | "Identifier of the thread to which this message belongs. Defaults to parent thread." - - OpenAI compatible example: "thread_asdf" assistant_id: type: string description: | "Identifier of the assistant involved in the message. Defaults to parent thread." - - OpenAI compatible example: jan role: type: string @@ -44,7 +34,6 @@ components: description: | "Role of the sender, either 'user' or 'assistant'." - OpenAI compatible content: type: array items: @@ -55,7 +44,7 @@ components: description: | "Type of content, e.g., 'text'." - OpenAI compatible + text: type: object properties: @@ -63,8 +52,6 @@ components: type: string description: | "Text content of the message." - - OpenAI compatible example: "Hi!?" annotations: type: array @@ -72,15 +59,12 @@ components: type: string description: | "Annotations for the text content, if any." - - OpenAI compatible example: [] metadata: type: object description: | "Metadata associated with the message, defaults to an empty object." - OpenAI compatible example: {} GetMessageResponse: diff --git a/docs/openapi/specs/models.yaml b/docs/openapi/specs/models.yaml index fdb9e1f9a4..aa5cc4155c 100644 --- a/docs/openapi/specs/models.yaml +++ b/docs/openapi/specs/models.yaml @@ -120,14 +120,12 @@ components: description: | "The identifier of the model." - OpenAI compatible example: "zephyr-7b" object: type: string description: | "The type of the object, indicating it's a model." - OpenAI compatible default: "model" created: type: integer @@ -135,14 +133,12 @@ components: description: | "Unix timestamp representing the creation time of the model." - OpenAI compatible example: "1253935178" owned_by: type: string description: | "The entity that owns the model." - OpenAI compatible example: "_" GetModelResponse: diff --git a/docs/openapi/specs/threads.yaml b/docs/openapi/specs/threads.yaml index 578e1ecdce..c009381e34 100644 --- a/docs/openapi/specs/threads.yaml +++ b/docs/openapi/specs/threads.yaml @@ -8,26 +8,24 @@ components: description: | "The identifier of the thread, defaults to foldername." - OpenAI compatible example: thread_.... object: type: string description: | "Type of the object, defaults to thread." - OpenAI compatible example: thread title: type: string description: | "A brief summary or description of the thread, defaults to an empty string." - Jan + example: "funny physics joke" assistants: type: array description: | - Jan + items: properties: assistant_id: @@ -35,7 +33,7 @@ components: description: | The identifier of assistant, defaults to "jan" - Jan + example: jan model: type: object @@ -43,34 +41,32 @@ components: id: type: string description: | - Jan + example: ... settings: type: object description: | Defaults to and overrides assistant.json's "settings" (and if none, then model.json "settings") - Jan + parameters: type: object description: | Defaults to and overrides assistant.json's "parameters" (and if none, then model.json "parameters") - Jan + created: type: integer format: int64 description: | "Unix timestamp representing the creation time of the thread, defaults to file creation time." - OpenAI compatible example: 1231231 metadata: type: object description: | "Metadata associated with the thread, defaults to an empty object." - OpenAI compatible example: {} GetThreadResponse: @@ -135,14 +131,12 @@ components: description: | "Role of the sender, either 'user' or 'assistant'." - OpenAI compatible enum: ["user", "assistant"] content: type: string description: | "Text content of the message." - OpenAI compatible file_ids: type: array items: @@ -150,7 +144,6 @@ components: description: | "Array of file IDs associated with the message, if any." - OpenAI compatible ModifyThreadResponse: type: object diff --git a/docs/src/styles/base.scss b/docs/src/styles/base.scss index a59df6f73c..b94081d668 100644 --- a/docs/src/styles/base.scss +++ b/docs/src/styles/base.scss @@ -1,4 +1,5 @@ @layer base { + html[data-theme="light"] { --ifm-background-color: white; --ifm-color-primary: #2563eb; /* New Primary Blue */ @@ -39,4 +40,16 @@ text-decoration: none; } } + compatible-label { + display: inline-block; + padding: 2px 8px; + margin: 0; + background-color: #228B22; + color: #000; + font-size: 13px; + vertical-align: middle; + line-height: 1.6; + border-radius: 4px; + font-weight: var(--ifm-font-weight-bold); +} }