Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: threads and messages #681

Merged
merged 8 commits into from
Nov 22, 2023
Merged

docs: threads and messages #681

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift click to select a range
7565b87
docs: threads
0xSage Nov 21, 2023
cab49b7
docs: roughing in a messages spec
0xSage Nov 21, 2023
1a8977b
docs: nits
0xSage Nov 21, 2023
a43ce60
docs: nits
0xSage Nov 21, 2023
b1fade0
docs: patch
0xSage Nov 21, 2023
70a8ea2
docs: update threads and messages
0xSage Nov 22, 2023
17f46d6
docs: commented out api parts
0xSage Nov 22, 2023
ac1075f
docs: comments
0xSage Nov 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 165 additions & 85 deletions docs/docs/specs/messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 2,114 @@
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

`Messages` capture a conversation's content. This can include the content from LLM responses and other metadata from [chat completions](/specs/chats).

- Users and assistants can send multimedia messages.
- An [OpenAI Message API](https://platform.openai.com/docs/api-reference/messages) compatible endpoint at `localhost:3000/v1/messages`.

## Folder Structure

Messages are saved in the `/threads/{thread_id}` folder in `messages.jsonl` files

```sh
jan/
threads/
assistant_name_unix_timestamp/
...
messages.jsonl
jan_2341243134/
...
messages.jsonl
```

## `message.jsonl`

Individual messages are saved in `jsonl` format for indexing purposes.

## Message Object
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/object
```json
{
// Jan specific properties
"updatedAt": "...", // that's it I think
{...message_2}
{...message_1}
{...message_0}
```

// 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": []
}
### Examples

Here's a standard example `message` sent from a user.

```json
"id": "0", // Sequential or UUID
"object": "thread.message", // Defaults to "thread.message"
"created_at": 1698983503,
"thread_id": "thread_asdf", // Defaults to parent thread
"assistant_id": "jan", // Defaults to parent thread
"role": "user", // From either "user" or "assistant"
"content": [
{
"type": "text",
"text": {
"value": "Hi!?",
"annotations": []
}
],
"file_ids": [],
"assistant_id": "asst_ToSF7Gb04YMj8AMMm50ZLLtY",
"run_id": "run_BjylUJgDqYK9bOhy4yjAiMrn",
"metadata": {}
}
}
],
"metadata": {}, // Defaults to {}
// "run_id": "...", // Rather than `run` id abstraction
// "file_ids": [],
```

Here's an example `message` response from an assistant.

```json
"id": "0", // Sequential or UUID
"object": "thread.message", // Defaults to "thread.message"
"created_at": 1698983503,
"thread_id": "thread_asdf", // Defaults to parent thread
"assistant_id": "jan", // Defaults to parent thread
"role": "assistant", // From either "user" or "assistant"
"content": [ // Usually from Chat Completion obj
{
"type": "text",
"text": {
"value": "Hi! How can I help you today?",
"annotations": []
}
}
],
"metadata": {}, // Defaults to {}
// "run_id": "...", // KIV
// "file_ids": [], // KIV
// "usage": {} // KIV: saving chat completion properties https://platform.openai.com/docs/api-reference/chat/object
```

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

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

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",
Expand All @@ -75,9 132,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" \
Expand All @@ -86,93 147,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"
}
``` -->
12 changes: 6 additions & 6 deletions docs/docs/specs/models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 4,7 @@ title: Models

:::caution

Draft Specification: functionality has not been implemented yet.
This is currently under development.

:::

Expand Down Expand Up @@ -46,19 46,19 @@ jan/ # Jan root folder
- `model.json` contains metadata and default parameters used to run a model.
- The only required field is `source_url`.

### GGUF Example
### Example

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", ...]
Expand Down Expand Up @@ -95,7 95,7 @@ See [Jan Models API](https://jan.ai/api-reference#tag/Models)

:::caution

This is current under development.
This is currently under development.

:::

Expand Down
Loading