Merge pull request #744 from janhq/fix508

docs: update specs/product
janhq · Nov 28, 2023 · 460cb33 · 460cb33
2 parents 0ffc81e + 64daa31
commit 460cb33
Show file tree

Hide file tree

Showing 23 changed files with 132 additions and 58 deletions.
diff --git a/docs/docs/specs/architecture.md b/docs/docs/specs/architecture.md
@@ -1,5 +1,6 @@
 ---
 title: Architecture
+slug: /specs
 ---
 
 :::warning
@@ -10,35 +11,28 @@ This page is still under construction, and should be read as a scratchpad
 
 ## Overview
 
-- Jan built a modular infrastructure on top of Electron, in order to support extensions and AI functionality.
-- Jan is largely built on top of its own modules.
+- Jan has a modular architecture and is largely built on top of its own modules.
 - Jan uses a local [file-based approach](/specs/file-based) for data persistence.
+- Jan currently supports an Electron-based [Desktop UI](https://github.com/janhq/jan) and a C++ inference engine called [Nitro](https://nitro.jan.ai/docs/).
 
-## Modules
-
-Modules are low level, system services. It is similar to OS kernel modules, in that `modules` provide abstractions to device level, basic functionality like the filesystem, device system, databases, AI inference engines, etc.
-
-## Pluggable Modules
+## Extensions
 
-Jan exports modules that mirror OpenAI’s, exposing similar APIs and objects:
+Jan has an Extensions API inspired by VSCode. In fact, most of Jan's core services are built as extensions.
 
-- Modules are modular, atomic implementations of a single OpenAI-compatible endpoint
-- Modules can be swapped out for alternate implementations
-  - The default `messages` module persists messages in thread-specific `.json`
-  - `messages-postgresql` uses Postgres for production-grade cloud-native environments
+Jan supports the following OpenAI compatible extensions:
 
-| Jan Module | Description   | API Docs                     |
-| ---------- | ------------- | ---------------------------- |
-| Chat       | Inference     | [/chat](/api/chat)           |
-| Models     | Models        | [/model](/api/model)         |
-| Assistants | Apps          | [/assistant](/api/assistant) |
-| Threads    | Conversations | [/thread](/api/thread)       |
-| Messages   | Messages      | [/message](/api/message)     |
+| Jan Module | Description   | API Docs                                      |
+| ---------- | ------------- | --------------------------------------------- |
+| Chat       | Inference     | [/chats](/api-reference/#tag/Chat-Completion) |
+| Models     | Models        | [/models](/api-reference/#tag/Models)         |
+| Assistants | Apps          | [/assistants](/api-reference/#tag/Assistants) |
+| Threads    | Conversations | [/threads](/api-reference/#tag/Threads)       |
+| Messages   | Messages      | [/messages](/api-reference/#tag/Messages)     |
 
 <!-- TODO: link npm modules -->
 
-## Extensions
+## Modules
 
-Extensions are feature level services that include both UI and logic implementation.
+Modules are low level, system services. It is similar to OS kernel modules. Modules provide abstractions to basic, device level functionality like working with the filesystem, device system, databases, AI inference engines, etc.
 
-<!-- TODO[@linh]: add all of @linh's specs here -->
+Jan follows the [dependency inversion principle](https://en.wikipedia.org/wiki/Dependency_inversion_principle) such that `modules` expose the interfaces that `extensions` can then implement.
diff --git a/docs/docs/specs/assistants.md → docs/docs/specs/engineering/assistants.md b/docs/docs/specs/assistants.md → docs/docs/specs/engineering/assistants.md
@@ -1,5 +1,6 @@
 ---
 title: "Assistants"
+slug: /specs/assistants
 ---
 
 :::caution
@@ -14,7 +15,7 @@ In Jan, assistants are `primary` entities with the following capabilities:
 
 - 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`.
+- An [OpenAI Assistants API](https://platform.openai.com/docs/api-reference/assistants) compatible endpoint at `localhost:1337/v1/assistants`.
 - Jan ships with a default assistant called "Jan" that lets you use all models.
 
 ## Folder Structure
@@ -49,6 +50,7 @@ In Jan, assistants are `primary` entities with the following capabilities:
   "models": [                         // Defaults to "*" all models
       { ...model_0 }
   ],
+  "instructions": "Be concise",       // A system prompt for the assistant
   "events": [],                       // Defaults to "*"
   "metadata": {},                     // Defaults to {}
   // "tools": [],                     // Coming soon

diff --git a/docs/docs/specs/chats.md → docs/docs/specs/engineering/chats.md b/docs/docs/specs/chats.md → docs/docs/specs/engineering/chats.md
@@ -1,5 +1,6 @@
 ---
 title: Chats
+slug: /specs/chats
 ---
 
 :::caution
@@ -13,7 +14,7 @@ This is currently under development.
 In Jan, `chats` are LLM responses in the form of OpenAI compatible `chat completion objects`.
 
 - Models take a list of messages and return a model-generated response as output.
-- An [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) compatible endpoint at `localhost:3000/v1/chats`.
+- An [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) compatible endpoint at `localhost:1337/v1/chats`.
 
 ## Folder Structure
 

diff --git a/docs/docs/specs/files.md → docs/docs/specs/engineering/files.md b/docs/docs/specs/files.md → docs/docs/specs/engineering/files.md
@@ -1,5 +1,6 @@
 ---
 title: "Files"
+slug: /specs/files
 ---
 
 :::warning

diff --git a/docs/docs/specs/engineering/fine-tuning.md b/docs/docs/specs/engineering/fine-tuning.md
@@ -0,0 +1,6 @@
+---
+title: "Fine-tuning"
+slug: /specs/finetuning
+---
+
+Todo: @hiro
diff --git a/docs/docs/specs/messages.md → docs/docs/specs/engineering/messages.md b/docs/docs/specs/messages.md → docs/docs/specs/engineering/messages.md
@@ -1,5 +1,6 @@
 ---
 title: Messages
+slug: /specs/messages
 ---
 
 :::caution

diff --git a/docs/docs/specs/models.md → docs/docs/specs/engineering/models.md b/docs/docs/specs/models.md → docs/docs/specs/engineering/models.md
@@ -1,5 +1,6 @@
 ---
 title: Models
+slug: /specs/models
 ---
 
 :::caution
@@ -13,7 +14,7 @@ This is currently under development.
 In Jan, models are primary entities with the following capabilities:
 
 - Users can import, configure, and run models locally.
-- An [OpenAI Model API](https://platform.openai.com/docs/api-reference/models) compatible endpoint at `localhost:3000/v1/models`.
+- An [OpenAI Model API](https://platform.openai.com/docs/api-reference/models) compatible endpoint at `localhost:1337/v1/models`.
 - Supported model formats: `ggufv3`, and more.
 
 ## Folder Structure

diff --git a/docs/docs/specs/prompts.md → docs/docs/specs/engineering/prompts.md b/docs/docs/specs/prompts.md → docs/docs/specs/engineering/prompts.md
@@ -1,7 +1,8 @@
 ---
 title: Prompts
+slug: /specs/prompts
 ---
 
 - [ ] /prompts folder
 - [ ] How to add to prompts
-- [ ] Assistants can have suggested Prompts
+- [ ] Assistants can have suggested Prompts
diff --git a/docs/docs/specs/threads.md → docs/docs/specs/engineering/threads.md b/docs/docs/specs/threads.md → docs/docs/specs/engineering/threads.md
@@ -1,5 +1,6 @@
 ---
 title: Threads
+slug: /specs/threads
 ---
 
 :::caution

diff --git a/docs/docs/specs/fine-tuning.md b/docs/docs/specs/fine-tuning.md
diff --git a/docs/docs/specs/home.md b/docs/docs/specs/home.md
diff --git a/docs/docs/specs/hub.md b/docs/docs/specs/hub.md
diff --git a/docs/docs/specs/img/chat-screen.png b/docs/docs/specs/img/chat-screen.png
diff --git a/docs/docs/specs/img/hub-screen.png b/docs/docs/specs/img/hub-screen.png
diff --git a/docs/docs/specs/img/settings-screen.png b/docs/docs/specs/img/settings-screen.png
diff --git a/docs/docs/specs/img/system-screen.png b/docs/docs/specs/img/system-screen.png
diff --git a/docs/docs/specs/product/chat.md b/docs/docs/specs/product/chat.md
@@ -0,0 +1,17 @@
+---
+title: Chat
+slug: /specs/chat
+---
+
+## Overview
+
+A home screen for users to chat with [assistants](/specs/assistants) via conversation [threads](/specs/threads).
+
+![alt text](../img/chat-screen.png)
+
+## User Stories
+
+<!-- Can also be used as a QA Checklist -->
+
+- Users can chat with `Jan` the default assistant
+- Users can customize chat settings like model parameters via both the GUI & `thread.json`
diff --git a/docs/docs/specs/product/hub.md b/docs/docs/specs/product/hub.md
@@ -0,0 +1,18 @@
+---
+title: Hub
+slug: /specs/hub
+---
+
+## Overview
+
+The Hub is like a store for everything, where users can discover and download models, assistants, and more.
+
+![alt text](../img/hub-screen.png)
+
+## User Stories
+
+<!-- Can also be used as a QA Checklist -->
+
+- Users can discover recommended models (Jan ships with a few preconfigured `model.json` files)
+- Users can download models suitable for their devices, e.g. compatible with their RAM
+- Users can download models via a HuggingFace URL (coming soon)
diff --git a/docs/docs/specs/product/settings.md b/docs/docs/specs/product/settings.md
@@ -0,0 +1,32 @@
+---
+title: Settings
+slug: /specs/settings
+---
+
+## Overview
+
+A settings page for users to add extensions, configure model settings, change app appearance, add keyboard shortcuts, and a plethora of other personalizations.
+
+![alt text](../img/settings-screen.png)
+
+## User Stories
+
+<!-- Can also be used as a QA Checklist -->
+
+### General Settings
+
+- Users can customize `port` number
+- Users can customize `janroot` folder location
+
+### Extensions Settings
+
+- Users can add, delete, and configure extensions
+
+### Model Settings
+
+- Users can configure default model parameters and settings
+- Users can delete models
+
+### Appearance
+
+- Users can set color themes and dark/light modes
diff --git a/docs/docs/specs/product/system-monitor.md b/docs/docs/specs/product/system-monitor.md
@@ -0,0 +1,17 @@
+---
+title: System Monitor
+slug: /specs/system-monitor
+---
+
+## Overview
+
+An activity screen to monitor system health and running models.
+
+![alt text](../img/system-screen.png)
+
+## User Stories
+
+<!-- Can also be used as a QA Checklist -->
+
+- Users can see disk and ram utilization
+- Users can start and stop models based on system health
diff --git a/docs/docs/specs/settings.md b/docs/docs/specs/settings.md
diff --git a/docs/docs/specs/system-monitor.md b/docs/docs/specs/system-monitor.md
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -66,10 +66,10 @@ const sidebars = {
       collapsible: true,
       collapsed: false,
       items: [
-        "specs/home",
-        "specs/hub",
-        "specs/system-monitor",
-        "specs/settings",
+        "specs/product/chat",
+        "specs/product/hub",
+        "specs/product/system-monitor",
+        "specs/product/settings",
       ],
     },
 
@@ -79,16 +79,16 @@ const sidebars = {
       collapsible: true,
       collapsed: false,
       items: [
-        "specs/chats",
-        "specs/models",
-        "specs/threads",
-        "specs/messages",
-        "specs/assistants",
-        // "specs/files",
-        // "specs/jan",
-        // "specs/fine-tuning",
-        // "specs/settings",
-        // "specs/prompts",
+        "specs/engineering/chats",
+        "specs/engineering/models",
+        "specs/engineering/threads",
+        "specs/engineering/messages",
+        "specs/engineering/assistants",
+        // "specs/engineering/files",
+        // "specs/engineering/jan",
+        // "specs/engineering/fine-tuning",
+        // "specs/engineering/settings",
+        // "specs/engineering/prompts",
       ],
     },
   ],