Nicholai/jan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add assistants api reference (#801)

Browse Source 
docs: add assistants api reference (#801)
This commit is contained in:
Hieu 2023-12-08 18:33:20 +09:00 committed by GitHub
commit 9b00f6a31f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 621 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/docs/specs/engineering/assistants.md
View File

@ -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

336
docs/openapi/jan.yaml
View File

@ -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. <a href = "https://platform.openai.com/docs/api-reference/chat/create"> Equivalent to OpenAI's create chat completion. </a>
@ -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. <a href = "https://platform.openai.com/docs/api-reference/assistants/listAssistants"> Equivalent to OpenAI's list assistants. </a>
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. <a href = "https://platform.openai.com/docs/api-reference/assistants/createAssistant"> Equivalent to OpenAI's create assistants. </a>
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. <a href = "https://platform.openai.com/docs/api-reference/assistants/getAssistant"> Equivalent to OpenAI's retrieve assistants. </a>
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. <a href = "https://platform.openai.com/docs/api-reference/assistants/modifyAssistant"> Equivalent to OpenAI's modify assistant. </a>
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. <a href = "https://platform.openai.com/docs/api-reference/assistants/deleteAssistant"> Equivalent to OpenAI's delete assistant. </a>
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'."
<span style="color:#228B22">OpenAI compatible</span>
Role of the sender, either 'user' or 'assistant'.
example: "user"
enum: ["user", "assistant"]
content:
type: string
description: |
"Text content of the message."
<span style="color:#228B22">OpenAI compatible</span>
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. <a href = "https://platform.openai.com/docs/api-reference/messages/listMessageFiles"> Equivalent to OpenAI's list message files. </a>
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. <a href = "https://platform.openai.com/docs/api-reference/assistants"> Equivalent to OpenAI's assistants object. </a>
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"

59
docs/openapi/specs/assistant.yaml
View File

@ -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

329
docs/openapi/specs/assistants.yaml Normal file
View File

@ -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

2
docs/openapi/specs/chat.yaml
View File

@ -109,8 +109,6 @@ components:
description: |
Set probability threshold for more relevant outputs
ChatCompletionResponse:
type: object
description: Description of the response structure

5
docs/openapi/specs/messages.yaml
View File

@ -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'
$ref: "#/components/schemas/MessageFileObject"

6
docs/openapi/specs/models.yaml
View File

@ -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"

18
docs/openapi/specs/threads.yaml
View File

@ -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
example: true