Merge Hiro's Architecture docs
This commit is contained in:
Daniel
commit
55d8aba03a
3
docs/docs/guide/server.md
Normal file
3
docs/docs/guide/server.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
---
|
||||||
|
title: API Server
|
||||||
|
---
|
||||||
@ -2,4 +2,40 @@
|
|||||||
title: Architecture
|
title: Architecture
|
||||||
---
|
---
|
||||||
|
|
||||||
- [ ] Add Architecture Diagram here
|
## Concepts
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
A1[("A User Integrators")] -->|uses| B1[assistant]
|
||||||
|
B1 -->|persist conversational history| C1[("thread A")]
|
||||||
|
B1 -->|executes| D1[("built-in tools as module")]
|
||||||
|
B1 -.->|uses| E1[model]
|
||||||
|
E1 -.->|model.json| D1
|
||||||
|
D1 --> F1[retrieval]
|
||||||
|
F1 -->|belongs to| G1[("web browsing")]
|
||||||
|
G1 --> H1[Google]
|
||||||
|
G1 --> H2[Duckduckgo]
|
||||||
|
F1 -->|belongs to| I1[("API calling")]
|
||||||
|
F1 --> J1[("knowledge files")]
|
||||||
|
```
|
||||||
|
- User/ Integrator
|
||||||
|
- Assistant object
|
||||||
|
- Model object
|
||||||
|
- Thread object
|
||||||
|
- Built-in tool object
|
||||||
|
|
||||||
|
## File system
|
||||||
|
```sh
|
||||||
|
janroot/
|
||||||
|
assistants/
|
||||||
|
assistant-a/
|
||||||
|
assistant.json
|
||||||
|
src/
|
||||||
|
index.ts
|
||||||
|
threads/
|
||||||
|
thread-a/
|
||||||
|
thread-b
|
||||||
|
models/
|
||||||
|
model-a/
|
||||||
|
model.json
|
||||||
|
```
|
||||||
@ -2,188 +2,239 @@
|
|||||||
title: "Assistants"
|
title: "Assistants"
|
||||||
---
|
---
|
||||||
|
|
||||||
:::warning
|
Assistants can use models and tools.
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants
|
||||||
Draft Specification: functionality has not been implemented yet.
|
- Jan's `Assistants` are even more powerful than OpenAI due to customizable code in `index.js`
|
||||||
|
|
||||||
Feedback: [HackMD: Assistants Spec](https://hackmd.io/KKAznzZvS668R6Vmyf8fCg)
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
|
|
||||||
## User Stories
|
## User Stories
|
||||||
|
|
||||||
_Users can chat with an assistant_
|
_Users can download an assistant via a web URL_
|
||||||
|
|
||||||
- [Wireframes - show asst object properties]
|
- Wireframes here
|
||||||
- See [Threads Spec](https://hackmd.io/BM_8o_OCQ-iLCYhunn2Aug)
|
|
||||||
|
|
||||||
_Users can use Jan - the default assistant_
|
_Users can import an assistant from local directory_
|
||||||
|
|
||||||
- [Wireframes here - show model picker]
|
- Wireframes here
|
||||||
- See [Default Jan Object](#Default-Jan-Example)
|
|
||||||
|
|
||||||
_Users can create an assistant from scratch_
|
_Users can configure assistant settings_
|
||||||
|
|
||||||
- [Wireframes here - show create asst flow]
|
- Wireframes here
|
||||||
- Users can select any model for an assistant. See Model Spec
|
|
||||||
|
|
||||||
_Users can create an assistant from an existing assistant_
|
## Assistant Object
|
||||||
|
|
||||||
- [Wireframes showing asst edit mode]
|
- `assistant.json`
|
||||||
|
> OpenAI Equivalen: https://platform.openai.com/docs/api-reference/assistants/object
|
||||||
## Jan Assistant Object
|
|
||||||
|
|
||||||
- A `Jan Assistant Object` is a "representation of an assistant"
|
|
||||||
- Objects are defined by `assistant-uuid.json` files in `json` format
|
|
||||||
- Objects are designed to be compatible with `OpenAI Assistant Objects` with additional properties needed to run on our infrastructure.
|
|
||||||
- ALL object properties are optional, i.e. users should be able to use an assistant declared by an empty `json` file.
|
|
||||||
|
|
||||||
| Property | Type | Description | Validation |
|
|
||||||
| ------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------- |
|
|
||||||
| `object` | enum: `model`, `assistant`, `thread`, `message` | The Jan Object type | Defaults to `assistant` |
|
|
||||||
| `name` | string | A vanity name. | Defaults to filename |
|
|
||||||
| `description` | string | A vanity description. | Max `n` chars. Defaults to `""` |
|
|
||||||
| `models` | array | A list of Model Objects that the assistant can use. | Defaults to ALL models |
|
|
||||||
| `metadata` | map | This can be useful for storing additional information about the object in a structured format. | Defaults to `{}` |
|
|
||||||
| `tools` | array | TBA. | TBA |
|
|
||||||
| `files` | array | TBA. | TBA |
|
|
||||||
|
|
||||||
### Generic Example
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
// janroot/assistants/example/example.json
|
{
|
||||||
"name": "Homework Helper",
|
// Jan specific properties
|
||||||
|
"avatar": "https://lala.png",
|
||||||
|
"thread_location": "ROOT/threads", // Default to root (optional field)
|
||||||
|
// TODO: add moar
|
||||||
|
|
||||||
// Option 1 (default): all models in janroot/models are available via Model Picker
|
// OpenAI compatible properties: https://platform.openai.com/docs/api-reference/assistants
|
||||||
"models": [],
|
"id": "asst_abc123",
|
||||||
|
"object": "assistant",
|
||||||
// Option 2: creator can configure custom parameters on existing models in `janroot/models` &&
|
"created_at": 1698984975,
|
||||||
// Option 3: creator can package a custom model with the assistant
|
"name": "Math Tutor",
|
||||||
"models": [{ ...modelObject1 }, { ...modelObject2 }],
|
"description": null,
|
||||||
|
"instructions": "...",
|
||||||
|
"tools": [
|
||||||
|
{
|
||||||
|
"type": "retrieval"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "web_browsing"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"file_ids": ["file_id"],
|
||||||
|
"models": ["<model_id>"],
|
||||||
|
"metadata": {}
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Default Jan Example
|
### Assistant lifecycle
|
||||||
|
Assistant has 4 states (enum)
|
||||||
|
- `to_download`
|
||||||
|
- `downloading`
|
||||||
|
- `ready`
|
||||||
|
- `running`
|
||||||
|
|
||||||
- Every user install has a default "Jan Assistant" declared below.
|
## Assistants API
|
||||||
> Q: can we omit most properties in `jan.json`? It's all defaults anyway.
|
|
||||||
|
|
||||||
|
- What would modifying Assistant do? (doesn't mutate `index.js`?)
|
||||||
|
- By default, `index.js` loads `assistant.json` file and executes exactly like so. This supports builders with little time to write code.
|
||||||
|
- The `assistant.json` is 1 source of truth for the definitions of `models` and `built-in tools` that they can use it without writing more code.
|
||||||
|
|
||||||
|
### Get list assistants
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/listAssistants
|
||||||
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl {JAN_URL}/v1/assistants?order=desc&limit=20 \
|
||||||
|
-H "Content-Type: application/json"
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
```json
|
```json
|
||||||
// janroot/assistants/jan/jan.json
|
{
|
||||||
"description": "Use Jan to chat with all models",
|
"object": "list",
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"id": "asst_abc123",
|
||||||
|
"object": "assistant",
|
||||||
|
"created_at": 1698982736,
|
||||||
|
"name": "Coding Tutor",
|
||||||
|
"description": null,
|
||||||
|
"models": ["model_zephyr_7b", "azure-openai-gpt4-turbo"],
|
||||||
|
"instructions": "You are a helpful assistant designed to make me better at coding!",
|
||||||
|
"tools": [],
|
||||||
|
"file_ids": [],
|
||||||
|
"metadata": {},
|
||||||
|
"state": "ready"
|
||||||
|
},
|
||||||
|
],
|
||||||
|
"first_id": "asst_abc123",
|
||||||
|
"last_id": "asst_abc789",
|
||||||
|
"has_more": false
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Filesystem
|
### Get assistant
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/getAssistant
|
||||||
- Everything needed to represent & run an assistant is packaged into an `Assistant folder`.
|
- Example request
|
||||||
- The folder is standalone and can be easily zipped, imported, and exported, e.g. to Github.
|
```shell
|
||||||
- The folder always contains an `Assistant Object`, declared in an `assistant-uuid.json`.
|
curl {JAN_URL}/v1/assistants/{assistant_id} \
|
||||||
- The folder and file must share the same name: `assistant-uuid`
|
-H "Content-Type: application/json"
|
||||||
- In the future, the folder will contain all of the resources an assistant needs to run, e.g. custom model binaries, pdf files, custom code, etc.
|
```
|
||||||
|
- Example response
|
||||||
```sh
|
```json
|
||||||
janroot/
|
{
|
||||||
assistants/
|
"id": "asst_abc123",
|
||||||
jan/ # Assistant Folder
|
"object": "assistant",
|
||||||
jan.json # Assistant Object
|
"created_at": 1699009709,
|
||||||
homework-helper/ # Assistant Folder
|
"name": "HR Helper",
|
||||||
homework-helper.json # Assistant Object
|
"description": null,
|
||||||
|
"models": ["model_zephyr_7b", "azure-openai-gpt4-turbo"],
|
||||||
|
"instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
|
||||||
|
"tools": [
|
||||||
|
{
|
||||||
|
"type": "retrieval"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"file_ids": [
|
||||||
|
"file-abc123"
|
||||||
|
],
|
||||||
|
"metadata": {},
|
||||||
|
"state": "ready"
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Custom Code
|
### Create an assistant
|
||||||
|
Create an assistant with models and instructions.
|
||||||
> Not in scope yet. Sharing as a preview only.
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/createAssistant
|
||||||
|
- Example request
|
||||||
- Assistants can call custom code in the future
|
```shell
|
||||||
- Custom code extends beyond `function calling` to any features that can be implemented in `/src`
|
curl -X POST {JAN_URL}/v1/assistants \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
```sh
|
-d {
|
||||||
example/ # Assistant Folder
|
"instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
|
||||||
example.json # Assistant Object
|
"name": "Math Tutor",
|
||||||
package.json
|
"tools": [{"type": "retrieval"}],
|
||||||
src/
|
"model": ["model_zephyr_7b", "azure-openai-gpt4-turbo"]
|
||||||
index.ts
|
}
|
||||||
helpers.ts
|
|
||||||
```
|
```
|
||||||
|
- Example response
|
||||||
### Knowledge Files
|
```json
|
||||||
|
{
|
||||||
> Not in scope yet. Sharing as a preview only
|
"id": "asst_abc123",
|
||||||
|
"object": "assistant",
|
||||||
- Assistants can do `retrieval` in future
|
"created_at": 1698984975,
|
||||||
|
"name": "Math Tutor",
|
||||||
```sh
|
"description": null,
|
||||||
|
"model": ["model_zephyr_7b", "azure-openai-gpt4-turbo"]
|
||||||
example/ # Assistant Folder
|
"instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
|
||||||
example.json # Assistant Object
|
"tools": [
|
||||||
files/
|
{
|
||||||
|
"type": "retrieval"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"file_ids": [],
|
||||||
|
"metadata": {},
|
||||||
|
"state": "ready"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Modify an assistant
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/modifyAssistant
|
||||||
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl -X POST {JAN_URL}/v1/assistants/{assistant_id} \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d {
|
||||||
|
"instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
|
||||||
|
"name": "Math Tutor",
|
||||||
|
"tools": [{"type": "retrieval"}],
|
||||||
|
"model": ["model_zephyr_7b", "azure-openai-gpt4-turbo"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "asst_abc123",
|
||||||
|
"object": "assistant",
|
||||||
|
"created_at": 1698984975,
|
||||||
|
"name": "Math Tutor",
|
||||||
|
"description": null,
|
||||||
|
"model": ["model_zephyr_7b", "azure-openai-gpt4-turbo"]
|
||||||
|
"instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
|
||||||
|
"tools": [
|
||||||
|
{
|
||||||
|
"type": "retrieval"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"file_ids": [],
|
||||||
|
"metadata": {},
|
||||||
|
"state": "ready"
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Jan API
|
|
||||||
|
|
||||||
### Assistant API Object
|
|
||||||
|
|
||||||
#### `GET /v1/assistants/{assistant_id}`
|
|
||||||
|
|
||||||
- The `Jan Assistant Object` maps into the `OpenAI Assistant Object`.
|
|
||||||
- Properties marked with `*` are compatible with the [OpenAI `assistant` object](https://platform.openai.com/docs/api-reference/assistants)
|
|
||||||
- Note: The `Jan Assistant Object` has additional properties when retrieved via its API endpoint.
|
|
||||||
- https://platform.openai.com/docs/api-reference/assistants/getAssistant
|
|
||||||
|
|
||||||
| Property | Type | Public Description | Jan Assistant Object (`a`) Property |
|
|
||||||
| ---------------- | -------------- | ------------------------------------------------------------------------- | ----------------------------------- |
|
|
||||||
| `id`\* | string | Assistant uuid, also the name of the Jan Assistant Object file: `id.json` | `json` filename |
|
|
||||||
| `object`\* | string | Always "assistant" | `a.object` |
|
|
||||||
| `created_at`\* | integer | Timestamp when assistant was created. | `a.json` creation time |
|
|
||||||
| `name`\* | string or null | A display name | `a.name` or `id` |
|
|
||||||
| `description`\* | string or null | A description | `a.description` |
|
|
||||||
| `model`\* | string | Text | `a.models[0].name` |
|
|
||||||
| `instructions`\* | string or null | Text | `a.models[0].parameters.prompt` |
|
|
||||||
| `tools`\* | array | TBA | `a.tools` |
|
|
||||||
| `file_ids`\* | array | TBA | `a.files` |
|
|
||||||
| `metadata`\* | map | TBA | `a.metadata` |
|
|
||||||
| `models` | array | TBA | `a.models` |
|
|
||||||
|
|
||||||
### Create Assistant
|
|
||||||
|
|
||||||
#### `POST /v1/assistants`
|
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/assistants/createAssistant
|
|
||||||
|
|
||||||
### Retrieve Assistant
|
|
||||||
|
|
||||||
#### `GET v1/assistants/{assistant_id}`
|
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/assistants/getAssistant
|
|
||||||
|
|
||||||
### Modify Assistant
|
|
||||||
|
|
||||||
#### `POST v1/assistants/{assistant_id}`
|
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/assistants/modifyAssistant
|
|
||||||
|
|
||||||
### Delete Assistant
|
### Delete Assistant
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/deleteAssistant
|
||||||
|
`- Example request
|
||||||
|
```shell
|
||||||
|
curl -X DELETE {JAN_URL}/v1/assistant/model-zephyr-7B
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "asst_abc123",
|
||||||
|
"object": "assistant.deleted",
|
||||||
|
"deleted": true,
|
||||||
|
"state": "to_download"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
#### `DELETE v1/assistants/{assistant_id}`
|
## Assistants Filesystem
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/assistants/deleteAssistant
|
```sh
|
||||||
|
/assistants
|
||||||
|
/jan
|
||||||
|
assistant.json # Assistant configs (see below)
|
||||||
|
|
||||||
### List Assistants
|
# For any custom code
|
||||||
|
package.json # Import npm modules
|
||||||
|
# e.g. Langchain, Llamaindex
|
||||||
|
/src # Supporting files (needs better name)
|
||||||
|
index.js # Entrypoint
|
||||||
|
process.js # For electron IPC processes (needs better name)
|
||||||
|
|
||||||
#### `GET v1/assistants`
|
# `/threads` at root level
|
||||||
|
# `/models` at root level
|
||||||
|
/shakespeare
|
||||||
|
assistant.json
|
||||||
|
package.json
|
||||||
|
/src
|
||||||
|
index.js
|
||||||
|
process.js
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/assistants/listAssistants
|
/threads # Assistants remember conversations in the future
|
||||||
|
/models # Users can upload custom models
|
||||||
### CRUD Assistant.Models
|
/finetuned-model
|
||||||
|
```
|
||||||
- This is a Jan-only endpoint, since Jan supports the ModelPicker, i.e. an `assistant` can be created to run with many `models`.
|
|
||||||
|
|
||||||
#### `POST /v1/assistants/{assistant_id}/models`
|
|
||||||
|
|
||||||
#### `GET /v1/assistants/{assistant_id}/models`
|
|
||||||
|
|
||||||
#### `GET /v1/assistants/{assistant_id}/models/{model_id}`
|
|
||||||
|
|
||||||
#### `DELETE /v1/assistants/{assistant_id}/models`
|
|
||||||
|
|
||||||
Note: There's no need to implement `Modify Assistant.Models`
|
|
||||||
|
|||||||
@ -12,24 +12,5 @@ Chats are essentially inference requests to a model
|
|||||||
|
|
||||||
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/chat
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/chat
|
||||||
|
|
||||||
## Chat Object
|
- This should reference Nitro ChatCompletion API page to reduce duplication.
|
||||||
|
- We are fine with adding Jan API for this but it makes sense to use Nitro as reference as Nitro is default inference engine for Jan in this release
|
||||||
- Equivalent to: https://platform.openai.com/docs/api-reference/chat/object
|
|
||||||
|
|
||||||
## Chat API
|
|
||||||
|
|
||||||
See [/chat](/api/chat)
|
|
||||||
|
|
||||||
- Equivalent to: https://platform.openai.com/docs/api-reference/chat
|
|
||||||
|
|
||||||
```sh
|
|
||||||
POST https://localhost:1337/v1/chat/completions
|
|
||||||
|
|
||||||
TODO:
|
|
||||||
# Figure out how to incorporate tools
|
|
||||||
```
|
|
||||||
|
|
||||||
## Chat Filesystem
|
|
||||||
|
|
||||||
- Chats will be persisted to `messages` within `threads`
|
|
||||||
- There is no data structure specific to Chats
|
|
||||||
@ -31,6 +31,20 @@ Files can be used by `threads`, `assistants` and `fine-tuning`
|
|||||||
```
|
```
|
||||||
|
|
||||||
## File API
|
## File API
|
||||||
|
### List Files
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/files/list
|
||||||
|
|
||||||
|
### Upload file
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/files/create
|
||||||
|
|
||||||
|
### Delete file
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/files/delete
|
||||||
|
|
||||||
|
### Retrieve file
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/files/retrieve
|
||||||
|
|
||||||
|
### Retrieve file content
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/files/retrieve-contents
|
||||||
|
|
||||||
## Files Filesystem
|
## Files Filesystem
|
||||||
|
|
||||||
@ -45,5 +59,4 @@ Files can be used by `threads`, `assistants` and `fine-tuning`
|
|||||||
/threads
|
/threads
|
||||||
/jan-12938912
|
/jan-12938912
|
||||||
/files # thread-specific files
|
/files # thread-specific files
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|||||||
4
docs/docs/specs/fine-tuning.md
Normal file
4
docs/docs/specs/fine-tuning.md
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
---
|
||||||
|
title: "Fine tuning"
|
||||||
|
---
|
||||||
|
Todo: @hiro
|
||||||
@ -11,17 +11,14 @@ Feedback: [HackMD: Threads Spec](https://hackmd.io/BM_8o_OCQ-iLCYhunn2Aug)
|
|||||||
:::
|
:::
|
||||||
|
|
||||||
Messages are within `threads` and capture additional metadata.
|
Messages are within `threads` and capture additional metadata.
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages
|
||||||
- Equivalent to: https://platform.openai.com/docs/api-reference/messages
|
|
||||||
|
|
||||||
## Message Object
|
## Message Object
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/object
|
||||||
- Equivalent to: https://platform.openai.com/docs/api-reference/messages/object
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
// Jan specific properties
|
// Jan specific properties
|
||||||
"updatedAt": "..." // that's it I think
|
"updatedAt": "...", // that's it I think
|
||||||
|
|
||||||
// OpenAI compatible properties: https://platform.openai.com/docs/api-reference/messages)
|
// OpenAI compatible properties: https://platform.openai.com/docs/api-reference/messages)
|
||||||
"id": "msg_dKYDWyQvtjDBi3tudL1yWKDa",
|
"id": "msg_dKYDWyQvtjDBi3tudL1yWKDa",
|
||||||
@ -46,16 +43,136 @@ Messages are within `threads` and capture additional metadata.
|
|||||||
```
|
```
|
||||||
|
|
||||||
## Messages API
|
## Messages API
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages
|
||||||
|
|
||||||
- Equivalent to: https://platform.openai.com/docs/api-reference/messages
|
### 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",
|
||||||
|
"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": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### 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" \
|
||||||
|
-d '{
|
||||||
|
"role": "user",
|
||||||
|
"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": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"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": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"file_ids": [],
|
||||||
|
"assistant_id": null,
|
||||||
|
"run_id": null,
|
||||||
|
"metadata": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
```sh
|
### Modify message
|
||||||
POST https://api.openai.com/v1/threads/{thread_id}/messages # create msg
|
> Jan: TODO: Do we need to modify message? Or let user create new message?
|
||||||
GET https://api.openai.com/v1/threads/{thread_id}/messages # list messages
|
|
||||||
GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}
|
|
||||||
|
|
||||||
# Get message file
|
# Get message file
|
||||||
GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id}
|
> OpenAI Equivalent: https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id}
|
||||||
# List message files
|
- Example request
|
||||||
GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files
|
```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"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
# 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"
|
||||||
|
}
|
||||||
```
|
```
|
||||||
@ -46,7 +46,7 @@ _Users can override run settings at runtime_
|
|||||||
| `object` | enum: `model`, `assistant`, `thread`, `message` | Type of the Jan Object. Always `model` | Defaults to "model" |
|
| `object` | enum: `model`, `assistant`, `thread`, `message` | Type of the Jan Object. Always `model` | Defaults to "model" |
|
||||||
| `name` | string | A vanity name | Defaults to filename |
|
| `name` | string | A vanity name | Defaults to filename |
|
||||||
| `description` | string | A vanity description of the model | Defaults to "" |
|
| `description` | string | A vanity description of the model | Defaults to "" |
|
||||||
| `state` | enum[`running` , `stopped`, `not-downloaded` , `downloading`] | Needs more thought | Defaults to `not-downloaded` |
|
| `state` | enum[`to_download` , `downloading`, `ready` , `running`] | Needs more thought | Defaults to `to_download` |
|
||||||
| `parameters` | map | Defines default model run parameters used by any assistant. | Defaults to `{}` |
|
| `parameters` | map | Defines default model run parameters used by any assistant. | Defaults to `{}` |
|
||||||
| `metadata` | map | Stores additional structured information about the model. | Defaults to `{}` |
|
| `metadata` | map | Stores additional structured information about the model. | Defaults to `{}` |
|
||||||
| `metadata.engine` | enum: `llamacpp`, `api`, `tensorrt` | The model backend used to run model. | Defaults to "llamacpp" |
|
| `metadata.engine` | enum: `llamacpp`, `api`, `tensorrt` | The model backend used to run model. | Defaults to "llamacpp" |
|
||||||
@ -83,10 +83,11 @@ Additionally, Jan supports importing popular formats. For example, if you provid
|
|||||||
|
|
||||||
Supported URL formats with custom importers:
|
Supported URL formats with custom importers:
|
||||||
|
|
||||||
- `huggingface/thebloke`: `TODO: URL here`
|
- `huggingface/thebloke`: [Link](https://huggingface.co/TheBloke/Llama-2-7B-GGUF)
|
||||||
|
- `huggingface/thebloke`: [Link](https://huggingface.co/TheBloke/Llama-2-7B-GGUF)
|
||||||
- `janhq`: `TODO: put URL here`
|
- `janhq`: `TODO: put URL here`
|
||||||
- `azure_openai`: `TODO: put URL here`
|
- `azure_openai`: `https://docs-test-001.openai.azure.com/openai.azure.com/docs-test-001/gpt4-turbo`
|
||||||
- `openai`: `TODO: put URL here`
|
- `openai`: `api.openai.com`
|
||||||
|
|
||||||
### Generic Example
|
### Generic Example
|
||||||
|
|
||||||
@ -98,52 +99,66 @@ Supported URL formats with custom importers:
|
|||||||
// Note: Default fields omitted for brevity
|
// Note: Default fields omitted for brevity
|
||||||
"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf",
|
"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf",
|
||||||
"parameters": {
|
"parameters": {
|
||||||
"ctx_len": 2048,
|
"init": {
|
||||||
"ngl": 100,
|
"ctx_len": "2048",
|
||||||
"embedding": true,
|
"ngl": "100",
|
||||||
"n_parallel": 4,
|
"embedding": "true",
|
||||||
|
"n_parallel": "4",
|
||||||
"pre_prompt": "A chat between a curious user and an artificial intelligence",
|
"pre_prompt": "A chat between a curious user and an artificial intelligence",
|
||||||
"user_prompt": "USER: ",
|
"user_prompt": "USER: ",
|
||||||
"ai_prompt": "ASSISTANT: "
|
"ai_prompt": "ASSISTANT: "
|
||||||
|
},
|
||||||
|
"runtime": {
|
||||||
"temperature": "0.7",
|
"temperature": "0.7",
|
||||||
"token_limit": "2048",
|
"token_limit": "2048",
|
||||||
"top_k": "..",
|
"top_k": "0",
|
||||||
"top_p": "..",
|
"top_p": "1",
|
||||||
|
"stream": "true"
|
||||||
|
}
|
||||||
},
|
},
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"quantization": "..",
|
"engine": "llamacpp",
|
||||||
"size": "..",
|
"quantization": "Q3_K_L",
|
||||||
|
"size": "7B",
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Example: multiple binaries
|
### Example: multiple binaries
|
||||||
|
|
||||||
- Model has multiple binaries
|
- Model has multiple binaries `model-llava-1.5-ggml.json`
|
||||||
- See [source](https://huggingface.co/mys/ggml_llava-v1.5-13b)
|
- See [source](https://huggingface.co/mys/ggml_llava-v1.5-13b)
|
||||||
|
|
||||||
```json
|
```json
|
||||||
"source_url": "https://huggingface.co/mys/ggml_llava-v1.5-13b"
|
"source_url": "https://huggingface.co/mys/ggml_llava-v1.5-13b",
|
||||||
|
"parameters": {"init": {}, "runtime": {}}
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"binaries": "..", // TODO: what should this property be
|
"mmproj_binary": "https://huggingface.co/mys/ggml_llava-v1.5-13b/blob/main/mmproj-model-f16.gguf",
|
||||||
|
"ggml_binary": "https://huggingface.co/mys/ggml_llava-v1.5-13b/blob/main/ggml-model-q5_k.gguf",
|
||||||
|
"engine": "llamacpp",
|
||||||
|
"quantization": "Q5_K"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Example: Azure API
|
### Example: Azure API
|
||||||
|
|
||||||
- Using a remote API to access model
|
- Using a remote API to access model `model-azure-openai-gpt4-turbo.json`
|
||||||
- See [source](https://learn.microsoft.com/en-us/azure/ai-services/openai/quickstart?tabs=command-line%2Cpython&pivots=rest-api)
|
- See [source](https://learn.microsoft.com/en-us/azure/ai-services/openai/quickstart?tabs=command-line%2Cpython&pivots=rest-api)
|
||||||
|
|
||||||
```json
|
```json
|
||||||
"source_url": "https://docs-test-001.openai.azure.com/openai.azure.com/docs-test-001/gpt4-turbo",
|
"source_url": "https://docs-test-001.openai.azure.com/openai.azure.com/docs-test-001/gpt4-turbo",
|
||||||
"parameters": {
|
"parameters": {
|
||||||
|
"init" {
|
||||||
"API-KEY": "",
|
"API-KEY": "",
|
||||||
"DEPLOYMENT-NAME": "",
|
"DEPLOYMENT-NAME": "",
|
||||||
"api-version": "2023-05-15",
|
"api-version": "2023-05-15"
|
||||||
|
},
|
||||||
|
"runtime": {
|
||||||
"temperature": "0.7",
|
"temperature": "0.7",
|
||||||
"max_tokens": "2048",
|
"max_tokens": "2048",
|
||||||
"presence_penalty": "0",
|
"presence_penalty": "0",
|
||||||
"top_p": "1",
|
"top_p": "1",
|
||||||
"stream": "true"
|
"stream": "true"
|
||||||
|
}
|
||||||
}
|
}
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"engine": "api",
|
"engine": "api",
|
||||||
@ -155,7 +170,7 @@ Supported URL formats with custom importers:
|
|||||||
- Everything needed to represent a `model` is packaged into an `Model folder`.
|
- Everything needed to represent a `model` is packaged into an `Model folder`.
|
||||||
- The `folder` is standalone and can be easily zipped, imported, and exported, e.g. to Github.
|
- The `folder` is standalone and can be easily zipped, imported, and exported, e.g. to Github.
|
||||||
- The `folder` always contains at least one `Model Object`, declared in a `json` format.
|
- The `folder` always contains at least one `Model Object`, declared in a `json` format.
|
||||||
- The `folder` and `file` do not have to share the same name
|
- The `folder` and `file` do not have to share the same name
|
||||||
- The model `id` is made up of `folder_name/filename` and is thus always unique.
|
- The model `id` is made up of `folder_name/filename` and is thus always unique.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
@ -170,11 +185,9 @@ Supported URL formats with custom importers:
|
|||||||
```
|
```
|
||||||
|
|
||||||
### Default ./model folder
|
### Default ./model folder
|
||||||
|
|
||||||
- Jan ships with a default model folders containing recommended models
|
- Jan ships with a default model folders containing recommended models
|
||||||
- Only the Model Object `json` files are included
|
- Only the Model Object `json` files are included
|
||||||
- Users must later explicitly download the model binaries
|
- Users must later explicitly download the model binaries
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
models/
|
models/
|
||||||
mistral-7b/
|
mistral-7b/
|
||||||
@ -182,7 +195,6 @@ models/
|
|||||||
hermes-7b/
|
hermes-7b/
|
||||||
hermes-7b.json
|
hermes-7b.json
|
||||||
```
|
```
|
||||||
|
|
||||||
### Multiple quantizations
|
### Multiple quantizations
|
||||||
|
|
||||||
- Each quantization has its own `Jan Model Object` file
|
- Each quantization has its own `Jan Model Object` file
|
||||||
@ -193,7 +205,6 @@ llama2-7b-gguf/
|
|||||||
llama2-7b-gguf-Q3_K_L.json
|
llama2-7b-gguf-Q3_K_L.json
|
||||||
.bin
|
.bin
|
||||||
```
|
```
|
||||||
|
|
||||||
### Multiple model partitions
|
### Multiple model partitions
|
||||||
|
|
||||||
- A Model that is partitioned into several binaries use just 1 file
|
- A Model that is partitioned into several binaries use just 1 file
|
||||||
@ -204,8 +215,7 @@ llava-ggml/
|
|||||||
.proj
|
.proj
|
||||||
ggml
|
ggml
|
||||||
```
|
```
|
||||||
|
### Your locally fine-tuned model
|
||||||
### ?? whats this example for?
|
|
||||||
|
|
||||||
- ??
|
- ??
|
||||||
|
|
||||||
@ -214,67 +224,149 @@ llama-70b-finetune/
|
|||||||
llama-70b-finetune-q5.json
|
llama-70b-finetune-q5.json
|
||||||
.bin
|
.bin
|
||||||
```
|
```
|
||||||
|
|
||||||
## Jan API
|
## Jan API
|
||||||
|
|
||||||
### Model API Object
|
### Model API Object
|
||||||
|
|
||||||
- The `Jan Model Object` maps into the `OpenAI Model Object`.
|
- The `Jan Model Object` maps into the `OpenAI Model Object`.
|
||||||
- Properties marked with `*` are compatible with the [OpenAI `model` object](https://platform.openai.com/docs/api-reference/models)
|
- Properties marked with `*` are compatible with the [OpenAI `model` object](https://platform.openai.com/docs/api-reference/models)
|
||||||
- Note: The `Jan Model Object` has additional properties when retrieved via its API endpoint.
|
- Note: The `Jan Model Object` has additional properties when retrieved via its API endpoint.
|
||||||
- https://platform.openai.com/docs/api-reference/models/object
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/models/object
|
||||||
|
|
||||||
| Property | Type | Public Description | Jan Model Object (`m`) Property |
|
### Model lifecycle
|
||||||
| ------------- | -------------- | ----------------------------------------------------------- | -------------------------------------------- |
|
Model has 4 states (enum)
|
||||||
| `id`\* | string | Model uuid; also the file location under `/models` | `folder/filename` |
|
- `to_download`
|
||||||
| `object`\* | string | Always "model" | `m.object` |
|
- `downloading`
|
||||||
| `created`\* | integer | Timestamp when model was created. | `m.json` creation time |
|
- `ready`
|
||||||
| `owned_by`\* | string | The organization that owns the model. | grep author from `m.source_url` OR $(whoami) |
|
- `running`
|
||||||
| `name` | string or null | A display name | `m.name` or filename |
|
|
||||||
| `description` | string | A vanity description of the model | `m.description` |
|
|
||||||
| `state` | enum | | |
|
|
||||||
| `parameters` | map | Defines default model run parameters used by any assistant. | |
|
|
||||||
| `metadata` | map | Stores additional structured information about the model. | |
|
|
||||||
|
|
||||||
### List models
|
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/models/list
|
|
||||||
|
|
||||||
TODO: @hiro
|
|
||||||
|
|
||||||
### Get Model
|
### Get Model
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/models/retrieve
|
||||||
- https://platform.openai.com/docs/api-reference/models/retrieve
|
- Example request
|
||||||
|
```shell
|
||||||
TODO: @hiro
|
curl {JAN_URL}/v1/models/{model_id}
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "model-zephyr-7B",
|
||||||
|
"object": "model",
|
||||||
|
"created_at": 1686935002,
|
||||||
|
"owned_by": "thebloke",
|
||||||
|
"state": "running",
|
||||||
|
"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf",
|
||||||
|
"parameters": {
|
||||||
|
"ctx_len": 2048,
|
||||||
|
"ngl": 100,
|
||||||
|
"embedding": true,
|
||||||
|
"n_parallel": 4,
|
||||||
|
"pre_prompt": "A chat between a curious user and an artificial intelligence",
|
||||||
|
"user_prompt": "USER: ",
|
||||||
|
"ai_prompt": "ASSISTANT: ",
|
||||||
|
"temperature": "0.7",
|
||||||
|
"token_limit": "2048",
|
||||||
|
"top_k": "0",
|
||||||
|
"top_p": "1",
|
||||||
|
},
|
||||||
|
"metadata": {
|
||||||
|
"engine": "llamacpp",
|
||||||
|
"quantization": "Q3_K_L",
|
||||||
|
"size": "7B",
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### List models
|
||||||
|
Lists the currently available models, and provides basic information about each one such as the owner and availability.
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/models/list
|
||||||
|
- Example request
|
||||||
|
```shell=
|
||||||
|
curl {JAN_URL}/v1/models
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"object": "list",
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"id": "model-zephyr-7B",
|
||||||
|
"object": "model",
|
||||||
|
"created_at": 1686935002,
|
||||||
|
"owned_by": "thebloke",
|
||||||
|
"state": "running"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "ft-llama-70b-gguf",
|
||||||
|
"object": "model",
|
||||||
|
"created_at": 1686935002,
|
||||||
|
"owned_by": "you",
|
||||||
|
"state": "stopped"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "model-azure-openai-gpt4-turbo",
|
||||||
|
"object": "model",
|
||||||
|
"created_at": 1686935002,
|
||||||
|
"owned_by": "azure_openai",
|
||||||
|
"state": "running"
|
||||||
|
},
|
||||||
|
],
|
||||||
|
"object": "list"
|
||||||
|
}
|
||||||
|
```
|
||||||
### Delete Model
|
### Delete Model
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/models/delete
|
||||||
- https://platform.openai.com/docs/api-reference/models/delete
|
`- Example request
|
||||||
|
```shell
|
||||||
TODO: @hiro
|
curl -X DELETE {JAN_URL}/v1/models/{model_id}
|
||||||
|
```
|
||||||
### Get Model State
|
- Example response
|
||||||
|
```json
|
||||||
> Jan-only endpoint
|
{
|
||||||
> TODO: @hiro
|
"id": "model-zephyr-7B",
|
||||||
|
"object": "model",
|
||||||
### Get Model Metadata
|
"deleted": true,
|
||||||
|
"state": "to_download"
|
||||||
> Jan-only endpoint
|
}
|
||||||
> TODO: @hiro
|
```
|
||||||
|
|
||||||
### Download Model
|
|
||||||
|
|
||||||
> Jan-only endpoint
|
|
||||||
> TODO: @hiro
|
|
||||||
|
|
||||||
### Start Model
|
### Start Model
|
||||||
|
|
||||||
> Jan-only endpoint
|
> Jan-only endpoint
|
||||||
> TODO: @hiro
|
The request to start `model` by changing model state from `ready` to `running`
|
||||||
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl -X PUT {JAN_URL}/v1/models{model_id}/start
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "model-zephyr-7B",
|
||||||
|
"object": "model",
|
||||||
|
"state": "running"
|
||||||
|
}
|
||||||
|
```
|
||||||
### Stop Model
|
### Stop Model
|
||||||
|
|
||||||
> Jan-only endpoint
|
> Jan-only endpoint
|
||||||
> TODO: @hiro
|
The request to start `model` by changing model state from `running` to `ready`
|
||||||
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl -X PUT {JAN_URL}/v1/models/{model_id}/stop
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "model-zephyr-7B",
|
||||||
|
"object": "model",
|
||||||
|
"state": "ready"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Download Model
|
||||||
|
> Jan-only endpoint
|
||||||
|
The request to download `model` by changing model state from `to_download` to `downloading` then `ready`once it's done.
|
||||||
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl -X POST {JAN_URL}/v1/models/
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "model-zephyr-7B",
|
||||||
|
"object": "model",
|
||||||
|
"state": "downloading"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -14,13 +14,9 @@ Feedback: [HackMD: Threads Spec](https://hackmd.io/BM_8o_OCQ-iLCYhunn2Aug)
|
|||||||
|
|
||||||
_Users can chat with an assistant in a thread_
|
_Users can chat with an assistant in a thread_
|
||||||
|
|
||||||
- See [Messages Spec]
|
- See [Messages Spec](./messages.md)
|
||||||
|
|
||||||
_Users can change model in a new thread_
|
_Users can change assistant and model parameters in a thread_
|
||||||
|
|
||||||
- Wireframes here
|
|
||||||
|
|
||||||
_Users can change model parameters in a thread_
|
|
||||||
|
|
||||||
- Wireframes of
|
- Wireframes of
|
||||||
|
|
||||||
@ -38,7 +34,7 @@ _Users can delete all thread history_
|
|||||||
| Property | Type | Description | Validation |
|
| Property | Type | Description | Validation |
|
||||||
| ---------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
|
| ---------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
|
||||||
| `object` | enum: `model`, `assistant`, `thread`, `message` | The Jan Object type | Defaults to `thread` |
|
| `object` | enum: `model`, `assistant`, `thread`, `message` | The Jan Object type | Defaults to `thread` |
|
||||||
| `models` | array | An array of Jan Model Objects. Threads can "override" an assistant's model run parameters. Thread-level model parameters are directly saved in the `thread.models` property! (see Models spec) | Defaults to `assistant.models` |
|
| `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 `[]` |
|
| `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 `{}` |
|
| `metadata` | map | Useful for storing additional information about the object in a structured format. | Defaults to `{}` |
|
||||||
|
|
||||||
@ -46,6 +42,7 @@ _Users can delete all thread history_
|
|||||||
|
|
||||||
```json
|
```json
|
||||||
// janroot/threads/jan_1700123404.json
|
// janroot/threads/jan_1700123404.json
|
||||||
|
"assistants": ["assistant-123"],
|
||||||
"messages": [
|
"messages": [
|
||||||
{...message0}, {...message1}
|
{...message0}, {...message1}
|
||||||
],
|
],
|
||||||
@ -56,7 +53,7 @@ _Users can delete all thread history_
|
|||||||
|
|
||||||
## Filesystem
|
## Filesystem
|
||||||
|
|
||||||
- `Jan Thread Objects`' `json` files always has the naming schema: `assistant_uuid` + `unix_time_thread_created_at. See below.
|
- `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.
|
- 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.
|
- The folder is standalone and can be easily zipped, exported, and cleared.
|
||||||
|
|
||||||
@ -68,67 +65,129 @@ janroot/
|
|||||||
```
|
```
|
||||||
|
|
||||||
## Jan API
|
## Jan API
|
||||||
|
### Get thread
|
||||||
### Thread API Object
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/threads/getThread
|
||||||
|
- Example request
|
||||||
#### `GET /v1/threads/{thread_id}`
|
```shell
|
||||||
|
curl {JAN_URL}/v1/threads/{thread_id}
|
||||||
- The `Jan Thread Object` maps into the `OpenAI Thread Object`.
|
```
|
||||||
- Properties marked with `*` are compatible with the [OpenAI `thread` object](https://platform.openai.com/docs/api-reference/threads)
|
- Example response
|
||||||
- Note: The `Jan Thread Object` has additional properties when retrieved via its API endpoint.
|
```json
|
||||||
- https://platform.openai.com/docs/api-reference/threads/getThread
|
{
|
||||||
|
"id": "thread_abc123",
|
||||||
| Property | Type | Public Description | Jan Thread Object (`t`) Property |
|
"object": "thread",
|
||||||
| -------------- | ------- | ------------------------------------------------------------------- | -------------------------------- |
|
"created_at": 1699014083,
|
||||||
| `id`\* | string | Thread uuid, also the name of the Jan Thread Object file: `id.json` | `json` filename |
|
"assistants": ["assistant-001"],
|
||||||
| `object`\* | string | Always "thread" | `t.object` |
|
"metadata": {},
|
||||||
| `created_at`\* | integer | | `json` file creation time |
|
"messages": []
|
||||||
| `metadata`\* | map | | `t.metadata` |
|
}
|
||||||
| `models` | array | | `t.models` |
|
```
|
||||||
| `messages` | array | | `t.messages` |
|
|
||||||
|
|
||||||
### Create Thread
|
### Create Thread
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/threads/createThread
|
||||||
#### `POST /v1/threads`
|
- Example request
|
||||||
|
```shell
|
||||||
- https://platform.openai.com/docs/api-reference/threads/createThread
|
curl -X POST {JAN_URL}/v1/threads \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
### Retrieve Thread
|
-d '{
|
||||||
|
"messages": [{
|
||||||
#### `GET v1/threads/{thread_id}`
|
"role": "user",
|
||||||
|
"content": "Hello, what is AI?",
|
||||||
- https://platform.openai.com/docs/api-reference/threads/getThread
|
"file_ids": ["file-abc123"]
|
||||||
|
}, {
|
||||||
|
"role": "user",
|
||||||
|
"content": "How does AI work? Explain it in simple terms."
|
||||||
|
}]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 'thread_abc123',
|
||||||
|
"object": 'thread',
|
||||||
|
"created_at": 1699014083,
|
||||||
|
"metadata": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
### Modify Thread
|
### Modify Thread
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/threads/modifyThread
|
||||||
#### `POST v1/threads/{thread_id}`
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl -X POST {JAN_URL}/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."
|
||||||
|
}]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 'thread_abc123',
|
||||||
|
"object": 'thread',
|
||||||
|
"created_at": 1699014083,
|
||||||
|
"metadata": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
- https://platform.openai.com/docs/api-reference/threads/modifyThread
|
- https://platform.openai.com/docs/api-reference/threads/modifyThread
|
||||||
|
|
||||||
### Delete Thread
|
### Delete Thread
|
||||||
|
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/threads/deleteThread
|
||||||
#### `DELETE v1/threads/{thread_id}`
|
- Example request
|
||||||
|
```shell
|
||||||
- https://platform.openai.com/docs/api-reference/threads/deleteThread
|
curl -X DELETE {JAN_URL}/v1/threads/{thread_id}
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "thread_abc123",
|
||||||
|
"object": "thread.deleted",
|
||||||
|
"deleted": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### List Threads
|
### List Threads
|
||||||
|
|
||||||
> This is a Jan-only endpoint, not supported by OAI yet.
|
> This is a Jan-only endpoint, not supported by OAI yet.
|
||||||
|
- Example request
|
||||||
|
```shell
|
||||||
|
curl {JAN_URL}/v1/threads \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
```
|
||||||
|
- Example response
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"id": "thread_abc123",
|
||||||
|
"object": "thread",
|
||||||
|
"created_at": 1699014083,
|
||||||
|
"assistants": ["assistant-001"],
|
||||||
|
"metadata": {},
|
||||||
|
"messages": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "thread_abc456",
|
||||||
|
"object": "thread",
|
||||||
|
"created_at": 1699014083,
|
||||||
|
"assistants": ["assistant-002", "assistant-002"],
|
||||||
|
"metadata": {},
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
#### `GET v1/threads`
|
### Get & Modify `Thread.Assistants`
|
||||||
|
-> Can achieve this goal by calling `Modify Thread` API
|
||||||
|
|
||||||
### Get & Modify `Thread.Models`
|
#### `GET v1/threads/{thread_id}/assistants`
|
||||||
|
-> Can achieve this goal by calling `Get Thread` API
|
||||||
|
|
||||||
> This is a Jan-only endpoint, not supported by OAI yet.
|
#### `POST v1/threads/{thread_id}/assistants/{assistant_id}`
|
||||||
|
-> Can achieve this goal by calling `Modify Assistant` API with `thread.assistant[]`
|
||||||
#### `GET v1/threads/{thread_id}/models`
|
|
||||||
|
|
||||||
#### `POST v1/threads/{thread_id}/models/{model_id}`
|
|
||||||
|
|
||||||
- Since users can change model parameters in an existing thread
|
|
||||||
|
|
||||||
### List `Thread.Messages`
|
### List `Thread.Messages`
|
||||||
|
-> Can achieve this goal by calling `Get Thread` API
|
||||||
> This is a Jan-only endpoint, not supported by OAI yet.
|
|
||||||
|
|
||||||
#### `GET v1/threads/{thread_id}/messages`
|
|
||||||
|
|||||||
@ -58,15 +58,13 @@ const config = {
|
|||||||
],
|
],
|
||||||
],
|
],
|
||||||
|
|
||||||
// Only for react live
|
|
||||||
themes: ["@docusaurus/theme-live-codeblock"],
|
themes: ["@docusaurus/theme-live-codeblock"],
|
||||||
|
|
||||||
// The classic preset will relay each option entry to the respective sub plugin/theme.
|
// The classic preset will relay each option entry to the respective sub plugin/theme.
|
||||||
presets: [
|
presets: [
|
||||||
[
|
[
|
||||||
"classic",
|
"@docusaurus/preset-classic",
|
||||||
/** @type {import('@docusaurus/preset-classic').Options} */
|
{
|
||||||
({
|
|
||||||
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
|
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
|
||||||
docs: {
|
docs: {
|
||||||
routeBasePath: "/",
|
routeBasePath: "/",
|
||||||
@ -97,7 +95,7 @@ const config = {
|
|||||||
},
|
},
|
||||||
// Will be passed to @docusaurus/plugin-content-pages (false to disable)
|
// Will be passed to @docusaurus/plugin-content-pages (false to disable)
|
||||||
// pages: {},
|
// pages: {},
|
||||||
}),
|
},
|
||||||
],
|
],
|
||||||
// Redoc preset
|
// Redoc preset
|
||||||
[
|
[
|
||||||
@ -119,9 +117,7 @@ const config = {
|
|||||||
],
|
],
|
||||||
|
|
||||||
// Docs: https://docusaurus.io/docs/api/themes/configuration
|
// Docs: https://docusaurus.io/docs/api/themes/configuration
|
||||||
themeConfig:
|
themeConfig: {
|
||||||
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
|
|
||||||
({
|
|
||||||
image: "img/jan-social-card.png",
|
image: "img/jan-social-card.png",
|
||||||
// Only for react live
|
// Only for react live
|
||||||
liveCodeBlock: {
|
liveCodeBlock: {
|
||||||
@ -177,7 +173,7 @@ const config = {
|
|||||||
disableSwitch: false,
|
disableSwitch: false,
|
||||||
respectPrefersColorScheme: false,
|
respectPrefersColorScheme: false,
|
||||||
},
|
},
|
||||||
}),
|
},
|
||||||
};
|
};
|
||||||
|
|
||||||
module.exports = config;
|
module.exports = config;
|
||||||
|
|||||||
@ -17,7 +17,7 @@
|
|||||||
"@docusaurus/core": "^2.4.3",
|
"@docusaurus/core": "^2.4.3",
|
||||||
"@docusaurus/preset-classic": "^2.4.3",
|
"@docusaurus/preset-classic": "^2.4.3",
|
||||||
"@docusaurus/theme-live-codeblock": "^2.4.3",
|
"@docusaurus/theme-live-codeblock": "^2.4.3",
|
||||||
"@docusaurus/theme-mermaid": "^3.0.0",
|
"@docusaurus/theme-mermaid": "^2.4.3",
|
||||||
"@headlessui/react": "^1.7.17",
|
"@headlessui/react": "^1.7.17",
|
||||||
"@heroicons/react": "^2.0.18",
|
"@heroicons/react": "^2.0.18",
|
||||||
"@mdx-js/react": "^1.6.22",
|
"@mdx-js/react": "^1.6.22",
|
||||||
|
|||||||
@ -34,7 +34,7 @@ const sidebars = {
|
|||||||
label: "Using Jan",
|
label: "Using Jan",
|
||||||
collapsible: true,
|
collapsible: true,
|
||||||
collapsed: true,
|
collapsed: true,
|
||||||
items: ["guide/models"],
|
items: ["guide/models", "guide/server"],
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
type: "category",
|
type: "category",
|
||||||
@ -70,6 +70,7 @@ const sidebars = {
|
|||||||
"specs/assistants",
|
"specs/assistants",
|
||||||
"specs/files",
|
"specs/files",
|
||||||
"specs/jan",
|
"specs/jan",
|
||||||
|
"specs/fine-tuning",
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
|
|||||||
2612
docs/yarn.lock
2612
docs/yarn.lock
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user