Skip to content

Commit

Permalink
docs: roughing in a messages spec
Browse files Browse the repository at this point in the history
0xSage committed Nov 21, 2023
1 parent 7565b87 commit cab49b7
Showing 3 changed files with 132 additions and 103 deletions.
208 changes: 122 additions & 86 deletions docs/docs/specs/messages.md
Original file line number Diff line number Diff line change
@@ -2,57 +2,70 @@
title: Messages
---

:::warning
:::caution

Draft Specification: functionality has not been implemented yet.

Feedback: [HackMD: Threads Spec](https://hackmd.io/BM_8o_OCQ-iLCYhunn2Aug)
This is currently under development.

:::

Messages are within `threads` and capture additional metadata.
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages
## Overview

## Message Object
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/object
```json
{
// Jan specific properties
"updatedAt": "...", // that's it I think
`Messages` are in `threads` and capture additional metadata:

// OpenAI compatible properties: https://platform.openai.com/docs/api-reference/messages)
"id": "msg_dKYDWyQvtjDBi3tudL1yWKDa",
"object": "thread.message",
"created_at": 1698983503,
"thread_id": "thread_RGUhOuO9b2nrktrmsQ2uSR6I",
"role": "assistant",
"content": [
{
"type": "text",
"text": {
"value": "Hi! How can I help you today?",
"annotations": []
}
- Users can ...

## Folder Structure

- `Message` objects are in `thread.json` files under `messages` property. See [threads](./threads.md)

## `message` object

### Example

Here's a standard example `message` json.

```json
"id": "0", // Sequential or UUID?
"object": "thread.message", // Defaults to "thread.message"
"created_at": 1698983503,
"thread_id": "thread_asdf", // Defaults to parent thread
"role": "assistant", // Defaults to "user" or "assistant"
"content": [
{
"type": "text",
"text": {
"value": "Hi! How can I help you today?",
"annotations": []
}
],
"file_ids": [],
"assistant_id": "asst_ToSF7Gb04YMj8AMMm50ZLLtY",
"run_id": "run_BjylUJgDqYK9bOhy4yjAiMrn",
"metadata": {}
}
}
],
"assistant_id": "...",
"run_id": "...", // The `run` resulting in this message
"metadata": {}, // Defaults to {}
// "file_ids": [],
```

## Messages API
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages
## API Reference

Jan's Threads API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally.

See [Jan Messages API](https://jan.ai/api-reference#tag/Messages)

<!-- TODO clean this part up into API -->

### 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",
@@ -75,9 +88,13 @@ Messages are within `threads` and capture additional metadata.
"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" \
@@ -86,93 +103,112 @@ Messages are within `threads` and capture additional metadata.
"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": []
}
{
"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": {}
}
}
],
"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": []
}
{
"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": {}
}
}
],
"file_ids": [],
"assistant_id": null,
"run_id": null,
"metadata": {}
}
```

### Modify message

> Jan: TODO: Do we need to modify message? Or let user create new message?
# Get message file

> OpenAI Equivalent: https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id}
- 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"
}
{
"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"
}
```
{
"id": "file-abc123",
"object": "thread.message.file",
"created_at": 1699061776,
"message_id": "msg_abc123"
}
```
6 changes: 3 additions & 3 deletions docs/docs/specs/models.md
Original file line number Diff line number Diff line change
@@ -53,12 +53,12 @@ Here's a standard example `model.json` for a GGUF model.
- `source_url`: https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/.

```json
"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf",
"type": "model", // Defaults to "model"
"version": "1", // Defaults to 1
"id": "zephyr-7b" // Defaults to foldername
"object": "model", // Defaults to "model"
"source_url": "https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/blob/main/zephyr-7b-beta.Q4_K_M.gguf",
"name": "Zephyr 7B" // Defaults to foldername
"owned_by": "you" // Defaults to you
"version": "1", // Defaults to 1
"created": 1231231 // Defaults to file creation time
"description": ""
"state": enum[null, "downloading", "ready", "starting", "stopping", ...]
21 changes: 7 additions & 14 deletions docs/docs/specs/threads.md
Original file line number Diff line number Diff line change
@@ -41,23 +41,16 @@ jan/
Here's a standard example `thread.json` for a conversation between the user and the default Jan assistant.

```json
"type": "thread", // Defaults to "thread"
"id": "thread_....", // Defaults to foldername
"object": "thread", // Defaults to "thread"
"summary": "funny physics joke", // Defaults to ""
"assistants": ["jan"], // Defaults to "jan"
"created": 1231231 // Defaults to file creation time
"metadata": {}, // Defaults to {}
"messages": [
{...message_0}, {...message_1}
],
"model_id": "...", // Do we need this property?
// Overrides assistant.settings && model.settings
"settings": {
...
},
// Overrides assistant.settings && model.settings
"parameters": {
...
},
"messages": [],
"model_id": "...", // Defaults to assistant.model ???
"settings": {}, // Defaults to and overrides assistant.settings
"parameters": {}, // Defaults to and overrides assistant.settings
```

## API Reference
@@ -66,7 +59,7 @@ Jan's Threads API is compatible with [OpenAI's Threads API](https://platform.ope

See [Jan Threads API](https://jan.ai/api-reference#tag/Threads)

<!-- TODO clean this part up into api -->
<!-- TODO clean this part up into API -->

### Get thread

0 comments on commit cab49b7

Please sign in to comment.