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: assistant spec #707

Merged
merged 3 commits into from
Nov 24, 2023
Merged

docs: assistant spec #707

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift click to select a range
a1a4294
fix(spec): Update assistant spec
hiro-v Nov 24, 2023
51f9fcc
Merge branch 'main' into fix/spec_assistants_v1
0xSage Nov 24, 2023
805141b
docs: polish
0xSage Nov 24, 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
288 changes: 75 additions & 213 deletions docs/docs/specs/assistants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,239 2,101 @@
title: "Assistants"
---

Assistants can use models and tools.
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants
- Jan's `Assistants` are even more powerful than OpenAI due to customizable code in `index.js`
:::caution

## User Stories
This is currently under development.

_Users can download an assistant via a web URL_
:::

- Wireframes here
## Overview

_Users can import an assistant from local directory_
In Jan, assistants are `primary` entities with the following capabilities:

- Wireframes here
- Assistants can use `models`, `tools`, handle and emit `events`, and invoke `custom code`.
- Users can create custom assistants with saved `model` settings and parameters.
- An [OpenAI Assistants API](https://platform.openai.com/docs/api-reference/assistants) compatible endpoint at `localhost:3000/v1/assistants`.
- Jan ships with a default assistant called "Jan" that lets you use all models.

_Users can configure assistant settings_
## Folder Structure

- Wireframes here

## Assistant Object
```yaml
/jan
/models/
/threads/
/assistants
/jan # An assistant available to you by default
assistant.json # See below
/src # Assistants can invoke custom code
index.js # Entrypoint
process.js # For server processes (needs better name)
package.json # Import any npm libraries, e.g. Langchain, Llamaindex
/shakespeare # You can create custom assistants
assistant.json
/chicken_man
```

- `assistant.json`
> OpenAI Equivalen: https://platform.openai.com/docs/api-reference/assistants/object
## `assistant.json`

```json
```js
{
// Jan specific properties
"avatar": "https://lala.png",
"thread_location": "ROOT/threads", // Default to root (optional field)
// TODO: add moar

// OpenAI compatible properties: https://platform.openai.com/docs/api-reference/assistants
"id": "asst_abc123",
"object": "assistant",
"id": "asst_abc123", // Defaults to foldername
"object": "assistant", // Always "assistant"
"version": 1, // Defaults to 1
"created_at": 1698984975,
"name": "Math Tutor",
"name": "Math Tutor", // Defaults to foldername
"description": null,
"instructions": "...",
"tools": [
{
"type": "retrieval"
},
{
"type": "web_browsing"
}
"avatar": "https://pic.png",
"models": [ // Defaults to "*" all models
{ ...model_0 }
],
"file_ids": ["file_id"],
"models": ["<model_id>"],
"metadata": {}
"events": [], // Defaults to "*"
"metadata": {}, // Defaults to {}
// "tools": [], // Coming soon
// "file_ids": [], // Coming soon
// "memory/threads": true, // Coming soon
}
```

### Assistant lifecycle
Assistant has 4 states (enum)
- `to_download`
- `downloading`
- `ready`
- `running`

## Assistants API

- 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
{
"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
}
```
### Examples

### Get assistant
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/getAssistant
- Example request
```shell
curl {JAN_URL}/v1/assistants/{assistant_id} \
-H "Content-Type: application/json"
```
- Example response
```json
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1699009709,
"name": "HR Helper",
"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"
}
```
Here's what the default Jan assistant's json file looks like:

### Create an assistant
Create an assistant with models and instructions.
> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/createAssistant
- Example request
```shell
curl -X POST {JAN_URL}/v1/assistants \
-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"
}
```
### 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"
}
```
### 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
```js
{
"id": "asst_abc123",
"object": "assistant.deleted",
"deleted": true,
"state": "to_download"
"name": "Jan",
"description": "A global assistant that lets you chat with all downloaded models",
"avatar": "https://jan.ai/img/logo.svg",
// All other properties are not explicitly declared and use the default values (see above).
}
```

## Assistants Filesystem

```sh
/assistants
/jan
assistant.json # Assistant configs (see below)

# 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)

# `/threads` at root level
# `/models` at root level
/shakespeare
assistant.json
package.json
/src
index.js
process.js

/threads # Assistants remember conversations in the future
/models # Users can upload custom models
/finetuned-model
## Events

Jan assistants can respond to event hooks. More powerfully, Jan assistants can register their own pubsub, so other entities, like other assistants can respond to your assistants events.

## Custom Code

Jan assistants are Turing complete. This means you can write freeform code, and use any dependencies, when customizing your assistant.

```typescript
import {events, models} from "@janhq/core"
import {retrieval} from "@hiro/best-rag-ever" // This can be featured on Jan hub but install from npm

events.on('assistant:asst_abc123', (event) => async {
const result = models[0].process(event)
events.emit("assistant:asst_abc123", result)
resolve()
})
```

## Tools

> Coming soon

## Functions

> Coming soon

## Files

> Coming soon
2 changes: 1 addition & 1 deletion docs/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 103,7 @@ const sidebars = {
"specs/models",
"specs/threads",
"specs/messages",
// "specs/assistants",
"specs/assistants",
// "specs/files",
// "specs/jan",
// "specs/fine-tuning",
Expand Down