Merge pull request #719 from janhq/docnits

docs: cleanup
janhq · Nov 24, 2023 · f3e3079 · f3e3079
2 parents 77f20db + ccf4b49
commit f3e3079
Show file tree

Hide file tree

Showing 12 changed files with 61 additions and 79 deletions.
diff --git a/docs/docs/api/assistant.md b/docs/docs/api/assistant.md
diff --git a/docs/docs/api/chat.md b/docs/docs/api/chat.md
diff --git a/docs/docs/api/files.md b/docs/docs/api/files.md
diff --git a/docs/docs/api/message.md b/docs/docs/api/message.md
diff --git a/docs/docs/api/model.md b/docs/docs/api/model.md
diff --git a/docs/docs/api/overview.md b/docs/docs/api/overview.md
diff --git a/docs/docs/api/thread.md b/docs/docs/api/thread.md
diff --git a/docs/docs/docs/extensions.md b/docs/docs/docs/extensions.md
@@ -1,3 +1,9 @@
 ---
-title: Extending Jan 
----
+title: Extending Jan
+---
+
+## Overview
+
+- Jan exports a developer SDK which lets you customize assistants, Jan app, and more.
+- Jan exports a AI-friendly UI kit which lets people customize the [Jan UI](/specs/user-interface).
+- Jan provisions a local AI server which lets you built external applications on other platforms.
diff --git a/docs/docs/specs/architecture.md b/docs/docs/specs/architecture.md
@@ -8,10 +8,19 @@ This page is still under construction, and should be read as a scratchpad
 
 :::
 
-- Jan is built using modules
-- Plugin architecture (on Pluggable-Electron)
+## Overview
 
-Jan is comprised of system-level modules that mirror OpenAI’s, exposing similar APIs and objects
+- 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 uses a local [file-based approach](/specs/file-based) for data persistence.
+
+## 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
@@ -26,24 +35,10 @@ Jan is comprised of system-level modules that mirror OpenAI’s, exposing simila
 | Threads    | Conversations | [/thread](/api/thread)       |
 | Messages   | Messages      | [/message](/api/message)     |
 
-## Concepts
-
-```mermaid
-graph LR
-    A1[("A User Integrators")] -->|uses| B1[assistant]
-    B1 -->|persist conversational history| C1[("thread A")]
-    B1 -->|executes| D1[("built-in tools as module")]
-    B1 -.->|uses| E1[model]
-    E1 -.->|model.json| D1
-    D1 --> F1[retrieval]
-    F1 -->|belongs to| G1[("web browsing")]
-    G1 --> H1[Google]
-    G1 --> H2[Duckduckgo]
-    F1 -->|belongs to| I1[("API calling")]
-    F1 --> J1[("knowledge files")]
-```
-- User/ Integrator
-- Assistant object
-- Model object
-- Thread object
-- Built-in tool object
+<!-- TODO: link npm modules -->
+
+## Extensions
+
+Extensions are feature level services that include both UI and logic implementation.
+
+<!-- TODO[@linh]: add all of @linh's specs here -->
diff --git a/docs/docs/specs/data-structures.md → docs/docs/specs/file-based.md b/docs/docs/specs/data-structures.md → docs/docs/specs/file-based.md
@@ -1,5 +1,5 @@
 ---
-title: Data Structures
+title: File-based Approach
 ---
 
 :::warning
@@ -41,3 +41,26 @@ janroot/               # Jan's root folder (e.g. ~/jan)
         /threads          # Assistants remember conversations in the future
         /models           # Users can upload custom models
 ```
+
+## Data Dependencies
+
+```mermaid
+graph LR
+    A1[("A User Integrators")] -->|uses| B1[assistant]
+    B1 -->|persist conversational history| C1[("thread A")]
+    B1 -->|executes| D1[("built-in tools as module")]
+    B1 -.->|uses| E1[model]
+    E1 -.->|model.json| D1
+    D1 --> F1[retrieval]
+    F1 -->|belongs to| G1[("web browsing")]
+    G1 --> H1[Google]
+    G1 --> H2[Duckduckgo]
+    F1 -->|belongs to| I1[("API calling")]
+    F1 --> J1[("knowledge files")]
+```
+
+- User/ Integrator
+- Assistant object
+- Model object
+- Thread object
+- Built-in tool object
diff --git a/docs/docs/specs/models.md b/docs/docs/specs/models.md
@@ -53,30 +53,30 @@ Here's a standard example `model.json` for a GGUF model.
 - `source_url`: https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/.
 
 ```js
-"id": "zephyr-7b"                   // Defaults to foldername
+"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
+"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": ""
+"created": 1231231,                 // Defaults to file creation time
+"description": null,                // Defaults to null
 "state": enum[null, "downloading", "ready", "starting", "stopping", ...]
 "format": "ggufv3",                 // Defaults to "ggufv3"
 "settings": {                       // Models are initialized with settings
     "ctx_len": "2048",
     "ngl": "100",
     "embedding": "true",
     "n_parallel": "4",
-}
+},
 "parameters": {                     // Models are called parameters
     "temperature": "0.7",
     "token_limit": "2048",
     "top_k": "0",
     "top_p": "1",
     "stream": "true"
 },
-"metadata": {}                      // Defaults to {}
+"metadata": {},                     // Defaults to {}
 "assets": [                         // Defaults to current dir
     "file://.../zephyr-7b-q4_k_m.bin",
 ]

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -52,37 +52,17 @@ const sidebars = {
     "docs/modules",
   ],
 
-  apiSidebar: [
-    "api/overview",
-    {
-      type: "category",
-      label: "Endpoints",
-      collapsible: true,
-      collapsed: false,
-      items: [
-        {
-          type: "autogenerated",
-          dirName: "api",
-        },
-      ],
-    },
-  ],
-
   specsSidebar: [
     {
       type: "category",
       label: "Overview",
       collapsible: true,
       collapsed: false,
-      items: [
-        "specs/architecture",
-        "specs/data-structures",
-        "specs/user-interface",
-      ],
+      items: ["specs/architecture", "specs/file-based", "specs/user-interface"],
     },
     {
       type: "category",
-      label: "Product",
+      label: "Product Specs",
       collapsible: true,
       collapsed: false,
       items: [
@@ -95,7 +75,7 @@ const sidebars = {
 
     {
       type: "category",
-      label: "Engineering",
+      label: "Engineering Specs",
       collapsible: true,
       collapsed: false,
       items: [