diff --git a/docs/docs/specs/engineering/assistants.md b/docs/docs/specs/engineering/assistants.md index 90661af84..50646f9cb 100644 --- a/docs/docs/specs/engineering/assistants.md +++ b/docs/docs/specs/engineering/assistants.md @@ -40,6 +40,10 @@ In Jan, assistants are `primary` entities with the following capabilities: ## `assistant.json` +- Each `assistant` folder contains an `assistant.json` file, which is a representation of an assistant. +- `assistant.json` contains metadata and model parameter overrides +- There are no required fields. + ```js { "id": "asst_abc123", // Defaults to foldername diff --git a/docs/openapi/jan.yaml b/docs/openapi/jan.yaml index 43c07cb3c..ed558d14d 100644 --- a/docs/openapi/jan.yaml +++ b/docs/openapi/jan.yaml @@ -16,7 +16,7 @@ servers: tags: - name: Models description: List and describe the various models available in the API. - - name: Chat + - name: Chat description: | Given a list of messages comprising a conversation, the model will return a response. @@ -42,7 +42,7 @@ paths: operationId: createChatCompletion tags: - Chat - summary: | + summary: | Create chat completion description: | Creates a model response for the given chat conversation. Equivalent to OpenAI's create chat completion. @@ -72,7 +72,7 @@ paths: }, ] }' - + ### MODELS /models: get: @@ -111,7 +111,7 @@ paths: - lang: "curl" source: | curl -X POST https://localhost:1337/v1/models - /models/{model_id}: + /models/{model_id}: get: operationId: retrieveModel tags: @@ -139,7 +139,7 @@ paths: x-codeSamples: - lang: "curl" source: | - curl https://localhost:1337/v1/models/zephyr-7b + curl https://localhost:1337/v1/models/{model_id} delete: operationId: deleteModel tags: @@ -166,7 +166,7 @@ paths: x-codeSamples: - lang: "curl" source: | - curl -X DELETE https://localhost:1337/v1/models/zephyr-7b + curl -X DELETE https://localhost:1337/v1/models/{model_id} /models/{model_id}/start: put: operationId: startModel @@ -195,7 +195,7 @@ paths: x-codeSamples: - lang: "curl" source: | - curl -X PUT https://localhost:1337/v1/models/zephyr-7b/start + curl -X PUT https://localhost:1337/v1/models/{model_id}/start /models/{model_id}/stop: put: operationId: stopModel @@ -223,7 +223,7 @@ paths: x-codeSamples: - lang: "curl" source: | - curl -X PUT https://localhost:1337/v1/models/zephyr-7b/stop + curl -X PUT https://localhost:1337/v1/models/{model_id}/stop ### THREADS /threads: @@ -245,14 +245,14 @@ paths: type: array description: "Initial set of messages for the thread." items: - $ref: 'specs/threads.yaml#/components/schemas/ThreadMessageObject' + $ref: "specs/threads.yaml#/components/schemas/ThreadMessageObject" responses: "200": description: Thread created successfully content: application/json: schema: - $ref: 'specs/threads.yaml#/components/schemas/CreateThreadResponse' + $ref: "specs/threads.yaml#/components/schemas/CreateThreadResponse" x-codeSamples: - lang: "cURL" source: | @@ -267,7 +267,7 @@ paths: "role": "user", "content": "How does AI work? Explain it in simple terms." }] - }' + }' get: operationId: listThreads tags: @@ -283,7 +283,7 @@ paths: schema: type: array items: - $ref: 'specs/threads.yaml#/components/schemas/ThreadObject' + $ref: "specs/threads.yaml#/components/schemas/ThreadObject" example: - id: "thread_abc123" object: "thread" @@ -299,9 +299,9 @@ paths: x-codeSamples: - lang: "curl" source: | - curl http://localhost:1337/v1/threads \ - -H "Content-Type: application/json" \ - + curl http://localhost:1337/v1/threads \ + -H "Content-Type: application/json" \ + /threads/{thread_id}: get: operationId: getThread @@ -359,29 +359,29 @@ paths: type: array description: "Set of messages to update in the thread." items: - $ref: 'specs/threads.yaml#/components/schemas/ThreadMessageObject' + $ref: "specs/threads.yaml#/components/schemas/ThreadMessageObject" responses: "200": description: Thread modified successfully content: application/json: schema: - $ref: 'specs/threads.yaml#/components/schemas/ModifyThreadResponse' + $ref: "specs/threads.yaml#/components/schemas/ModifyThreadResponse" x-codeSamples: - lang: "curl" source: | - curl -X POST http://localhost:1337/v1/threads/{thread_id} \ - -H "Content-Type: application/json" \ - -d '{ - "messages": [{ - "role": "user", - "content": "Hello, what is AI?", - "file_ids": ["file-abc123"] - }, { - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }] - }' + curl -X POST http://localhost:1337/v1/threads/{thread_id} \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [{ + "role": "user", + "content": "Hello, what is AI?", + "file_ids": ["file-abc123"] + }, { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }] + }' delete: operationId: deleteThread tags: @@ -404,7 +404,7 @@ paths: content: application/json: schema: - $ref: 'specs/threads.yaml#/components/schemas/DeleteThreadResponse' + $ref: "specs/threads.yaml#/components/schemas/DeleteThreadResponse" x-codeSamples: - lang: "curl" source: | @@ -445,17 +445,17 @@ paths: - Threads summary: Modify Thread.Assistants description: | - + Can achieve this goal by calling Modify Assistant API with thread.assistant[] - + /threads/{thread_id}/: get: operationId: listThreadMessage tags: - Threads summary: List Thread.Messages - description: | + description: | Can achieve this goal by calling Get Thread API parameters: - in: path @@ -476,6 +476,218 @@ paths: - lang: "curl" source: | curl http://localhost:1337/v1/threads/{thread_id} + ### ASSISTANTS + /assistants/: + get: + operationId: listAssistants + tags: + - Assistants + summary: List assistants + description: | + Return a list of assistants. Equivalent to OpenAI's list assistants. + responses: + responses: + "200": + description: List of threads retrieved successfully + content: + application/json: + schema: + type: array + example: + - id: "asst_abc123" + object: "assistant" + version: 1 + created_at: 1698984975 + name: "Math Tutor" + description: null + avatar: "https://pic.png" + models: + - model_id: "model_0" + instructions: "Be concise" + events: + in: [] + out: [] + metadata: {} + + - id: "asst_abc456" + object: "assistant" + version: 1 + created_at: 1698984975 + name: "Physics Tutor" + description: null + avatar: "https://pic.png" + models: + - model_id: "model_1" + instructions: "Be concise!" + events: + in: [] + out: [] + metadata: {} + x-codeSamples: + - lang: "curl" + source: | + curl http://localhost:1337/v1/assistants \ + -H "Content-Type: application/json" \ + post: + operationId: createAssistant + tags: + - Assistants + summary: Create assistant + description: | + Create an assistant with a model and instructions. Equivalent to OpenAI's create assistants. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + responses: + "200": + description: + content: + application/json: + schema: + $ref: "specs/assistants.yaml#/components/schemas/CreateAssistantResponse" + x-codeSamples: + - lang: "curl" + source: | + curl http://localhost:1337/v1/assistants \ + -H "Content-Type: application/json" \ + -d '{ + "models": [ + { + "model_id": "model_0" + } + ] + }' + /assistants/{assistant_id}: + get: + operationId: getAssistant + tags: + - Assistants + summary: Retrieve assistant + description: | + Retrieves an assistant. Equivalent to OpenAI's retrieve assistants. + parameters: + - in: path + name: assistant_id + required: true + schema: + type: string + example: asst_abc123 + description: | + The ID of the assistant to retrieve. + responses: + "200": + description: + content: + application/json: + schema: + $ref: "specs/assistants.yaml#/components/schemas/RetrieveAssistantResponse" + x-codeSamples: + - lang: "curl" + source: | + curl http://localhost:1337/v1/assistants/{assistant_id} \ + -H "Content-Type: application/json" \ + post: + operationId: modifyAssistant + tags: + - Assistants + summary: Modify assistant + description: | + Modifies an assistant. Equivalent to OpenAI's modify assistant. + parameters: + - in: path + name: assistant_id + required: true + schema: + type: string + example: asst_abc123 + description: | + The ID of the assistant to modify. + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + name: + type: string + description: "Name of the assistant." + example: "Physics Tutor" + instructions: + type: string + description: "A system prompt for the assistant." + example: Be concise! + responses: + "200": + description: + content: + application/json: + schema: + $ref: "specs/assistants.yaml#/components/schemas/ModifyAssistantResponse" + x-codeSamples: + - lang: "curl" + source: | + curl http://localhost:1337/v1/assistants/{assistant_id} \ + -H "Content-Type: application/json" \ + -d '{ + "models": [ + { + "model_id": "model_0" + } + ], + "name": "Physics Tutor", + "instructions": "Be concise!", + }' + + delete: + operationId: deleteAssistant + tags: + - Assistants + summary: Delete assistant + description: | + Delete an assistant. Equivalent to OpenAI's delete assistant. + parameters: + - in: path + name: assistant_id + required: true + schema: + type: string + example: asst_abc123 + description: | + The ID of the assistant to delete. + responses: + "200": + description: Deletion status + content: + application/json: + schema: + $ref: "specs/assistants.yaml#/components/schemas/DeleteAssistantResponse" + x-codeSamples: + - lang: "curl" + source: | + curl -X DELETE http://localhost:1337/v1/assistants/{assistant_id} ### MESSAGES /threads/{thread_id}/messages: @@ -533,18 +745,14 @@ paths: role: type: string description: | - "Role of the sender, either 'user' or 'assistant'." - - OpenAI compatible + Role of the sender, either 'user' or 'assistant'. example: "user" enum: ["user", "assistant"] content: type: string description: | - "Text content of the message." - - OpenAI compatible - example: "How does AI work? Explain it in simple terms." + Text content of the message. + example: How does AI work? Explain it in simple terms. required: - role - content @@ -558,12 +766,12 @@ paths: x-codeSamples: - lang: "curl" source: | - curl -X POST http://localhost:1337/v1/threads/{thread_id}/messages \ - -H "Content-Type: application/json" \ - -d '{ - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }' + curl -X POST http://localhost:1337/v1/threads/{thread_id}/messages \ + -H "Content-Type: application/json" \ + -d '{ + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }' /threads/{thread_id}/messages/{message_id}: get: @@ -582,7 +790,6 @@ paths: example: thread_abc123 description: | The ID of the thread containing the message. - - in: path name: message_id required: true @@ -602,8 +809,8 @@ paths: x-codeSamples: - lang: "curl" source: | - curl http://localhost:1337/v1/threads/{thread_id}/messages/{message_id} \ - -H "Content-Type: application/json" + curl http://localhost:1337/v1/threads/{thread_id}/messages/{message_id} \ + -H "Content-Type: application/json" /threads/{thread_id}/messages/{message_id}/files: get: @@ -611,8 +818,8 @@ paths: tags: - Messages summary: | - List message files - description: | + List message files + description: | Returns a list of message files. Equivalent to OpenAI's list message files. parameters: - in: path @@ -630,9 +837,9 @@ paths: schema: type: string example: msg_abc123 - description: | - The ID of the message whose files are to be listed. - + description: | + The ID of the message whose files are to be listed. + responses: "200": description: List of files retrieved successfully @@ -681,7 +888,7 @@ paths: example: file-abc123 description: | The ID of the file to retrieve. - + responses: "200": description: File retrieved successfully @@ -708,7 +915,20 @@ x-webhooks: content: application/json: schema: - $ref: 'specs/models.yaml#/components/schemas/ModelObject' + $ref: "specs/models.yaml#/components/schemas/ModelObject" + AssistantObject: + post: + summary: The assistant object + description: | + Build assistants that can call models and use tools to perform tasks. Equivalent to OpenAI's assistants object. + operationId: AssistantObjects + tags: + - Assistants + requestBody: + content: + application/json: + schema: + $ref: "specs/assistants.yaml#/components/schemas/AssistantObject" MessageObject: post: summary: The message object @@ -721,7 +941,7 @@ x-webhooks: content: application/json: schema: - $ref: 'specs/messages.yaml#/components/schemas/MessageObject' + $ref: "specs/messages.yaml#/components/schemas/MessageObject" ThreadObject: post: summary: The thread object @@ -733,4 +953,4 @@ x-webhooks: content: application/json: schema: - $ref: 'specs/threads.yaml#/components/schemas/ThreadObject' + $ref: "specs/threads.yaml#/components/schemas/ThreadObject" diff --git a/docs/openapi/specs/assistant.yaml b/docs/openapi/specs/assistant.yaml deleted file mode 100644 index 95b4cd22d..000000000 --- a/docs/openapi/specs/assistant.yaml +++ /dev/null @@ -1,59 +0,0 @@ -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/assistants.yaml b/docs/openapi/specs/assistants.yaml new file mode 100644 index 000000000..687fb12ff --- /dev/null +++ b/docs/openapi/specs/assistants.yaml @@ -0,0 +1,329 @@ +components: + schemas: + AssistantObject: + type: object + properties: + 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." + example: 1698984975 + name: + type: string + description: "Name of the assistant." + example: "Math Tutor" + description: + type: string + description: "Description of the assistant. Can be null." + example: null + avatar: + type: string + description: "URL of the assistant's avatar. Jan-specific property." + example: "https://pic.png" + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + instructions: + type: string + description: "A system prompt for the assistant." + example: Be concise + 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." + + ListAssistantsResponse: + + CreateAssistantResponse: + type: object + properties: + 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." + example: 1698984975 + name: + type: string + description: "Name of the assistant." + example: "Math Tutor" + description: + type: string + description: "Description of the assistant. Can be null." + example: null + avatar: + type: string + description: "URL of the assistant's avatar. Jan-specific property." + example: "https://pic.png" + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + instructions: + type: string + description: "A system prompt for the assistant." + example: Be concise + 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." + + RetrieveAssistantResponse: + type: object + properties: + 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." + example: 1698984975 + name: + type: string + description: "Name of the assistant." + example: "Math Tutor" + description: + type: string + description: "Description of the assistant. Can be null." + example: null + avatar: + type: string + description: "URL of the assistant's avatar. Jan-specific property." + example: "https://pic.png" + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + instructions: + type: string + description: "A system prompt for the assistant." + example: Be concise + 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." + + ModifyAssistantObject: + type: object + properties: + 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." + example: 1698984975 + name: + type: string + description: "Name of the assistant." + example: "Math Tutor" + description: + type: string + description: "Description of the assistant. Can be null." + example: null + avatar: + type: string + description: "URL of the assistant's avatar. Jan-specific property." + example: "https://pic.png" + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + instructions: + type: string + description: "A system prompt for the assistant." + example: Be concise + 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." + + ModifyAssistantResponse: + type: object + properties: + 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." + example: 1698984975 + name: + type: string + description: "Name of the assistant." + example: "Physics Tutor" + description: + type: string + description: "Description of the assistant. Can be null." + example: null + avatar: + type: string + description: "URL of the assistant's avatar. Jan-specific property." + example: "https://pic.png" + models: + type: array + description: "List of models associated with the assistant. Jan-specific property." + items: + type: object + properties: + model_id: + type: string + example: model_0 + instructions: + type: string + description: "A system prompt for the assistant." + example: Be concise! + 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." + + DeleteAssistantResponse: + type: object + properties: + id: + type: string + description: "The identifier of the deleted assistant." + example: asst_abc123 + object: + type: string + description: "Type of the object, indicating the assistant has been deleted." + example: assistant.deleted + deleted: + type: boolean + description: "Indicates whether the assistant was successfully deleted." + example: true diff --git a/docs/openapi/specs/chat.yaml b/docs/openapi/specs/chat.yaml index 05444c444..166a6bd6c 100644 --- a/docs/openapi/specs/chat.yaml +++ b/docs/openapi/specs/chat.yaml @@ -109,8 +109,6 @@ components: description: | Set probability threshold for more relevant outputs - - ChatCompletionResponse: type: object description: Description of the response structure diff --git a/docs/openapi/specs/messages.yaml b/docs/openapi/specs/messages.yaml index b99fc4221..3ab578f0c 100644 --- a/docs/openapi/specs/messages.yaml +++ b/docs/openapi/specs/messages.yaml @@ -44,7 +44,6 @@ components: description: | "Type of content, e.g., 'text'." - text: type: object properties: @@ -207,7 +206,7 @@ components: data: type: array items: - $ref: '#/components/schemas/ListMessageObject' + $ref: "#/components/schemas/ListMessageObject" first_id: type: string description: "Identifier of the first message in the list." @@ -315,4 +314,4 @@ components: data: type: array items: - $ref: '#/components/schemas/MessageFileObject' \ No newline at end of file + $ref: "#/components/schemas/MessageFileObject" diff --git a/docs/openapi/specs/models.yaml b/docs/openapi/specs/models.yaml index 97ced0b59..1bd7e65d7 100644 --- a/docs/openapi/specs/models.yaml +++ b/docs/openapi/specs/models.yaml @@ -130,7 +130,7 @@ components: created: type: integer format: int64 - description: | + description: | "Unix timestamp representing the creation time of the model." example: "1253935178" @@ -307,7 +307,7 @@ components: - source_url - parameters - metadata - + DeleteModelResponse: type: object properties: @@ -324,7 +324,6 @@ components: description: "Indicates whether the model was successfully deleted." example: true - StartModelResponse: type: object properties: @@ -380,4 +379,3 @@ components: type: string description: "The current state of the model after the start operation." example: "downloaded" - diff --git a/docs/openapi/specs/threads.yaml b/docs/openapi/specs/threads.yaml index c009381e3..0c3a30ce8 100644 --- a/docs/openapi/specs/threads.yaml +++ b/docs/openapi/specs/threads.yaml @@ -17,15 +17,14 @@ components: example: thread title: type: string - description: | + description: | "A brief summary or description of the thread, defaults to an empty string." - example: "funny physics joke" assistants: type: array - description: | - + description: | + items: properties: assistant_id: @@ -33,7 +32,6 @@ components: description: | The identifier of assistant, defaults to "jan" - example: jan model: type: object @@ -41,20 +39,17 @@ components: id: type: string description: | - + example: ... - settings: + settings: type: object description: | Defaults to and overrides assistant.json's "settings" (and if none, then model.json "settings") - - parameters: type: object description: | Defaults to and overrides assistant.json's "parameters" (and if none, then model.json "parameters") - created: type: integer format: int64 @@ -143,7 +138,6 @@ components: type: string description: | "Array of file IDs associated with the message, if any." - ModifyThreadResponse: type: object @@ -181,4 +175,4 @@ components: deleted: type: boolean description: "Indicates whether the thread was successfully deleted." - example: true \ No newline at end of file + example: true