Merge pull request #744 from janhq/fix508

docs: update specs/product

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 has a modular architecture and is largely built on top of its own modules.
-- Jan 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
-
-Jan exports modules that mirror OpenAI’s, exposing similar APIs and objects:
-
-- 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 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)     |
-
-<!-- TODO: link npm modules -->
 
 ## Extensions
 
-Extensions are feature level services that include both UI and logic implementation.
+Jan has an Extensions API inspired by VSCode. In fact, most of Jan's core services are built as extensions.
 
-<!-- TODO[@linh]: add all of @linh's specs here -->
+Jan supports the following OpenAI compatible extensions:
+
+| 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 -->
+
+## Modules
+
+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.
+
+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.

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

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
 

docs/docs/specs/engineering/files.md

@@ -1,5 +1,6 @@
 ---
 title: "Files"
+slug: /specs/files
 ---
 
 :::warning

docs/docs/specs/engineering/fine-tuning.md

@@ -0,0 +1,6 @@
+---
+title: "Fine-tuning"
+slug: /specs/finetuning
+---
+
+Todo: @hiro

docs/docs/specs/engineering/messages.md

@@ -1,5 +1,6 @@
 ---
 title: Messages
+slug: /specs/messages
 ---
 
 :::caution

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

docs/docs/specs/engineering/prompts.md

@@ -1,5 +1,6 @@
 ---
 title: Prompts
+slug: /specs/prompts
 ---
 
 - [ ] /prompts folder

docs/docs/specs/engineering/threads.md

@@ -1,5 +1,6 @@
 ---
 title: Threads
+slug: /specs/threads
 ---
 
 :::caution

docs/docs/specs/fine-tuning.md

@@ -1,4 +0,0 @@
----
-title: "Fine-tuning"
----
-Todo: @hiro

docs/docs/specs/home.md

@@ -1,3 +0,0 @@
----
-title: Home
----

docs/docs/specs/hub.md

@@ -1,3 +0,0 @@
----
-title: Hub
----

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`

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)

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

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

docs/docs/specs/settings.md

@@ -1,5 +0,0 @@
----
-title: Settings
----
-
-- [ ] .jan folder in jan root

docs/docs/specs/system-monitor.md

@@ -1,3 +0,0 @@
----
-title: System Monitor
----

docs/sidebars.js

@@ -66,10 +66,10 @@ const sidebars = {
       collapsible: true,
       collapsed: false,
       items: [
-        "specs/home",
+        "specs/product/chat",
-        "specs/hub",
+        "specs/product/hub",
-        "specs/system-monitor",
+        "specs/product/system-monitor",
-        "specs/settings",
+        "specs/product/settings",
       ],
     },
 
@@ -79,16 +79,16 @@ const sidebars = {
       collapsible: true,
       collapsed: false,
       items: [
-        "specs/chats",
+        "specs/engineering/chats",
-        "specs/models",
+        "specs/engineering/models",
-        "specs/threads",
+        "specs/engineering/threads",
-        "specs/messages",
+        "specs/engineering/messages",
-        "specs/assistants",
+        "specs/engineering/assistants",
-        // "specs/files",
+        // "specs/engineering/files",
-        // "specs/jan",
+        // "specs/engineering/jan",
-        // "specs/fine-tuning",
+        // "specs/engineering/fine-tuning",
-        // "specs/settings",
+        // "specs/engineering/settings",
-        // "specs/prompts",
+        // "specs/engineering/prompts",
       ],
     },
   ],