From a1a4294dd4a8364120d3f50adf27ac08ca5092a3 Mon Sep 17 00:00:00 2001 From: hiro Date: Fri, 24 Nov 2023 07:11:15 +0700 Subject: [PATCH 1/2] fix(spec): Update assistant spec --- docs/docs/specs/assistants.md | 337 +++++++++++++++++----------------- docs/sidebars.js | 2 +- 2 files changed, 171 insertions(+), 168 deletions(-) diff --git a/docs/docs/specs/assistants.md b/docs/docs/specs/assistants.md index a744d16bd..6ae443210 100644 --- a/docs/docs/specs/assistants.md +++ b/docs/docs/specs/assistants.md @@ -16,7 +16,7 @@ _Users can import an assistant from local directory_ - Wireframes here -_Users can configure assistant settings_ +_Users can configure assistant settings_ - Wireframes here @@ -25,34 +25,84 @@ _Users can configure assistant settings_ - `assistant.json` > OpenAI Equivalen: https://platform.openai.com/docs/api-reference/assistants/object +// KIV +```shell= +/$JANROOT + /models + /assistants + /jarvis # git push http://github.com/abentlen/jarvis + # TODO: n assistant to multiple assistants + /threads # Package threads with your Assistant + /threads +``` + +- Packaging + - An Assistant folder + ```json { // 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", + "version": 1, "created_at": 1698984975, - "name": "Math Tutor", + "name": "Math Tutor", // required "description": null, - "instructions": "...", - "tools": [ - { - "type": "retrieval" - }, - { - "type": "web_browsing" - } + // This one omitted from assistant.json but will be covered in API + // "instructions": "", // This is openAI compatible. But it should be passed to model[i] as LLM model + // "tools": [ + // { + // "type": "retrieval" + // }, + // { + // "type": "web_browsing" + // } + // ], + // "file_ids": [], + // "memory": true, + // Persistent Memory (remembers all threads, files) + // if False, then files, etc are stored at /thread level + "models": "*", // Jan - model picker (Default) + // v2 + // If model is specified, then use the below + // omitted means default + "models": [ + { "model_id": "", ..., "parameters": {} } + // v2 { "model_id": "", ... } ], - "file_ids": ["file_id"], - "models": [""], + // The idea here is for explicitly subscribing to event stream + // v3 + "events"*: { + "in": ["assistant:asst_abc123", "jan:*"], + "out": ["assistant:asst_abc123", "jan:*"] + }, + // Alternate: Simplified version? + "events": "*", + "events": [ + "onMessage", + "onThread", + { id: "onMessage", type: "out" } // Event configs + ] + // "threads": [] // Helpful for look up under ~/jan/thread/* "metadata": {} } ``` +### Assistant example src/index.ts +```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() +}) +``` + ### Assistant lifecycle Assistant has 4 states (enum) - `to_download` @@ -68,173 +118,126 @@ Assistant has 4 states (enum) ### 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 -} -``` ### 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" -} -``` ### 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 -{ - "id": "asst_abc123", - "object": "assistant.deleted", - "deleted": true, - "state": "to_download" -} -``` ## Assistants Filesystem -```sh -/assistants - /jan - assistant.json # Assistant configs (see below) +```shell +/jan + /models/ + /threads/ + threads-1/ # jan + thread-<>/ # chicken + thread-2/ # multi-assistant (v22) + /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) + # 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 + # `/threads` at root level + # `/models` at root level + /shakespeare + assistant.json + package.json + /src + index.js + process.js + /threads # if developer specifies + /chicken ``` + +### Example +- Jan Assistant json +TBU +- Custom assistant json + + + + + + + + + + +## Swagger file + +```yaml +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 +``` \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 035e51bd0..21db1bd14 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -69,7 +69,7 @@ const sidebars = { "specs/models", "specs/threads", "specs/messages", - // "specs/assistants", + "specs/assistants", // "specs/files", // "specs/jan", // "specs/fine-tuning", From 805141b1d9647f41bd00bbb20fe4f9cf7c7025e4 Mon Sep 17 00:00:00 2001 From: 0xSage Date: Fri, 24 Nov 2023 17:22:45 +0800 Subject: [PATCH 2/2] docs: polish --- docs/docs/specs/assistants.md | 271 ++++++++-------------------------- docs/sidebars.js | 2 +- 2 files changed, 66 insertions(+), 207 deletions(-) diff --git a/docs/docs/specs/assistants.md b/docs/docs/specs/assistants.md index 6ae443210..d584b66b0 100644 --- a/docs/docs/specs/assistants.md +++ b/docs/docs/specs/assistants.md @@ -2,96 +2,82 @@ 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 - -- `assistant.json` -> OpenAI Equivalen: https://platform.openai.com/docs/api-reference/assistants/object - -// KIV -```shell= -/$JANROOT - /models - /assistants - /jarvis # git push http://github.com/abentlen/jarvis - # TODO: n assistant to multiple assistants - /threads # Package threads with your Assistant - /threads +```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 ``` -- Packaging - - An Assistant folder +## `assistant.json` -```json +```js { - // Jan specific properties - "avatar": "https://lala.png", - - // OpenAI compatible properties: https://platform.openai.com/docs/api-reference/assistants - "id": "asst_abc123", - "object": "assistant", - "version": 1, + "id": "asst_abc123", // Defaults to foldername + "object": "assistant", // Always "assistant" + "version": 1, // Defaults to 1 "created_at": 1698984975, - "name": "Math Tutor", // required + "name": "Math Tutor", // Defaults to foldername "description": null, - // This one omitted from assistant.json but will be covered in API - // "instructions": "", // This is openAI compatible. But it should be passed to model[i] as LLM model - // "tools": [ - // { - // "type": "retrieval" - // }, - // { - // "type": "web_browsing" - // } - // ], - // "file_ids": [], - // "memory": true, - // Persistent Memory (remembers all threads, files) - // if False, then files, etc are stored at /thread level - "models": "*", // Jan - model picker (Default) - // v2 - // If model is specified, then use the below - // omitted means default - "models": [ - { "model_id": "", ..., "parameters": {} } - // v2 { "model_id": "", ... } + "avatar": "https://pic.png", + "models": [ // Defaults to "*" all models + { ...model_0 } ], - // The idea here is for explicitly subscribing to event stream - // v3 - "events"*: { - "in": ["assistant:asst_abc123", "jan:*"], - "out": ["assistant:asst_abc123", "jan:*"] - }, - // Alternate: Simplified version? - "events": "*", - "events": [ - "onMessage", - "onThread", - { id: "onMessage", type: "out" } // Event configs - ] - // "threads": [] // Helpful for look up under ~/jan/thread/* - "metadata": {} + "events": [], // Defaults to "*" + "metadata": {}, // Defaults to {} + // "tools": [], // Coming soon + // "file_ids": [], // Coming soon + // "memory/threads": true, // Coming soon } ``` -### Assistant example src/index.ts +### Examples + +Here's what the default Jan assistant's json file looks like: + +```js +{ + "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). +} +``` + +## 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 @@ -103,141 +89,14 @@ events.on('assistant:asst_abc123', (event) => async { }) ``` -### Assistant lifecycle -Assistant has 4 states (enum) -- `to_download` -- `downloading` -- `ready` -- `running` +## Tools -## Assistants API +> Coming soon -- 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. +## Functions -### Get list assistants -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/listAssistants +> Coming soon -### Get assistant -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/getAssistant +## Files -### Create an assistant -Create an assistant with models and instructions. -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/createAssistant - -### Modify an assistant -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/modifyAssistant - -### Delete Assistant -> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/deleteAssistant - -## Assistants Filesystem - -```shell -/jan - /models/ - /threads/ - threads-1/ # jan - thread-<>/ # chicken - thread-2/ # multi-assistant (v22) - /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 # if developer specifies - /chicken -``` - -### Example -- Jan Assistant json -TBU -- Custom assistant json - - - - - - - - - - -## Swagger file - -```yaml -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 -``` \ No newline at end of file +> Coming soon diff --git a/docs/sidebars.js b/docs/sidebars.js index c534931af..dd3e58f0c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -103,7 +103,7 @@ const sidebars = { "specs/models", "specs/threads", "specs/messages", - // "specs/assistants", + "specs/assistants", // "specs/files", // "specs/jan", // "specs/fine-tuning",