docs: add user and developer guides for extensions (#1657)
docs: add user and developer guides for extensions (#1657)
This commit is contained in:
Hieu
GitHub
commit
81e2b8d885
@ -20,3 +20,69 @@ keywords:
|
||||
:::caution
|
||||
This is currently under development.
|
||||
:::
|
||||
|
||||
In this guide, we'll walk you through the process of building your first extension and integrating it into Jan.
|
||||
|
||||
## Steps to Create Your First Extension
|
||||
|
||||
To create your own extension, you can follow the steps below:
|
||||
|
||||
1. Click the **Use this template** button at the top of the [extension-template repository](https://github.com/janhq/extension-template).
|
||||
2. Select **Create a new repository**.
|
||||
3. Choose an owner and name for your new repository.
|
||||
4. Click **Create repository**.
|
||||
5. Clone your new repository to your local machine.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
After you have cloned the repository to your local machine or codespace, you will need to perform some initial setup steps before you can develop your extension.
|
||||
|
||||
:::info
|
||||
|
||||
You will need to have a reasonably modern version of [Node.js](https://nodejs.org) handy. If you are using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or [`nvm`](https://github.com/nvm-sh/nvm), you can run `nodenv install` in the root of your repository to install the version specified in
|
||||
[`package.json`](https://github.com/janhq/extension-template/blob/main/package.json). Otherwise, 20.x or later should work!
|
||||
|
||||
:::
|
||||
|
||||
1. :hammer_and_wrench: Install the dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. :building_construction: Package the TypeScript for distribution
|
||||
|
||||
```bash
|
||||
npm run bundle
|
||||
```
|
||||
|
||||
3. :white_check_mark: Check your artifact
|
||||
|
||||
There will be a `.tgz` file in your extension directory now. This is the file you will need to import into Jan. You can import this file into Jan by following the instructions in the [Import Extension](https://jan.ai/guides/using-extensions/import-extensions/) guide.
|
||||
|
||||
## Update the Extension Metadata
|
||||
|
||||
The [`package.json`](https://github.com/janhq/extension-template/blob/main/package.json) file defines metadata about your extension, such as extension name, main entry, description and version.
|
||||
|
||||
When you copy this repository, update `package.json` with the name, and description for your extension.
|
||||
|
||||
## Update the Extension Code
|
||||
|
||||
The [`src/`](https://github.com/janhq/extension-template/tree/main/src) directory is the heart of your extension! This contains the source code that will be run when your extension extension functions are invoked. You can replace the contents of this directory with your own code.
|
||||
|
||||
There are a few things to keep in mind when writing your extension code:
|
||||
|
||||
- Most Jan Extension functions are processed asynchronously.
|
||||
In `index.ts`, you will see that the extension function will return a `Promise<any>`.
|
||||
|
||||
```typescript
|
||||
import { core } from "@janhq/core";
|
||||
|
||||
function onStart(): Promise<any> {
|
||||
return core.invokePluginFunc(MODULE_PATH, "run", 0);
|
||||
}
|
||||
```
|
||||
|
||||
For more information about the Jan Extension Core module, see the [documentation](https://github.com/janhq/jan/blob/main/core/README.md).
|
||||
|
||||
Now, go ahead and start customizing your extension! Happy coding!
|
||||
133
docs/docs/guides/06-using-extensions/01-extension-settings.md
Normal file
133
docs/docs/guides/06-using-extensions/01-extension-settings.md
Normal file
@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Extension Settings
|
||||
slug: /guides/using-extensions/extension-settings/
|
||||
description: Configure settings for extensions.
|
||||
keywords:
|
||||
[
|
||||
Jan AI,
|
||||
Jan,
|
||||
ChatGPT alternative,
|
||||
local AI,
|
||||
private AI,
|
||||
conversational AI,
|
||||
no-subscription fee,
|
||||
large language model,
|
||||
extension settings,
|
||||
]
|
||||
---
|
||||
|
||||
The current Jan Desktop Client has some default extensions built on top of this framework to enhance the user experience. In this guide, we will show you the list of default extensions and how to configure extension settings.
|
||||
|
||||
## Default Extensions
|
||||
|
||||
You can find the default extensions in the `Settings` > `Extensions`.
|
||||
|
||||
|
||||
|
||||
### List of Default Extensions
|
||||
|
||||
| Extension Name | Version | Description | Source Code Link |
|
||||
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
|
||||
| Assistant Extension | v1.0.0 | This extension enables assistants, including Jan, a default assistant that can call all downloaded models. | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/assistant-extension) |
|
||||
| Conversational Extension | v1.0.0 | This extension enables conversations and state persistence via your filesystem. | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/conversational-extension) |
|
||||
| Inference Nitro Extension | v1.0.0 | This extension embeds Nitro, a lightweight (3mb) inference engine written in C++. See [nitro.jan.ai](nitro.jan.ai) | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/inference-nitro-extension) |
|
||||
| Inference Openai Extension | v1.0.0 | This extension enables OpenAI chat completion API calls | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/inference-openai-extension) |
|
||||
| Inference Triton Trt Llm Extension | v1.0.0 | This extension enables Nvidia's TensorRT-LLM as an inference engine option. | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/inference-triton-trtllm-extension) |
|
||||
| Model Extension | v1.0.22 | Model Management Extension provides model exploration and seamless downloads. | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/model-extension) |
|
||||
| Monitoring Extension | v1.0.9 | This extension provides system health and OS level data. | [Link to Source](https://github.com/janhq/jan/tree/main/extensions/monitoring-extension) |
|
||||
|
||||
## Configure Extension Settings
|
||||
|
||||
You can configure the extension settings by modifying the `extensions.json` file under the `~/jan/extensions` directory including the following configurations:
|
||||
|
||||
- `_active`: true means the extension is enabled. If you want to disable an extension, you can set it to false.
|
||||
- `listeners`: {} is the default value for listeners.
|
||||
- `origin`: the path to the extension file.
|
||||
- `installOptions`: configure the installOptions with version and fullMetadata.
|
||||
- `name`: the name of the extension.
|
||||
- `version`: the version of the extension.
|
||||
- `main`: the path to the main file of the extension.
|
||||
- `description`: the description of the extension.
|
||||
- `url`: the url of the extension.
|
||||
|
||||
```json title="~/jan/extensions/extensions.json"
|
||||
{
|
||||
"@janhq/assistant-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-assistant-extension-1.0.0.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/assistant-extension",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"description": "This extension enables assistants, including Jan, a default assistant that can call all downloaded models",
|
||||
"url": "extension://@janhq/assistant-extension/dist/index.js"
|
||||
},
|
||||
"@janhq/conversational-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-conversational-extension-1.0.0.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/conversational-extension",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"description": "This extension enables conversations and state persistence via your filesystem",
|
||||
"url": "extension://@janhq/conversational-extension/dist/index.js"
|
||||
},
|
||||
"@janhq/inference-nitro-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-inference-nitro-extension-1.0.0.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/inference-nitro-extension",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"description": "This extension embeds Nitro, a lightweight (3mb) inference engine written in C++. See nitro.jan.ai",
|
||||
"url": "extension://@janhq/inference-nitro-extension/dist/index.js"
|
||||
},
|
||||
"@janhq/inference-openai-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-inference-openai-extension-1.0.0.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/inference-openai-extension",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"description": "This extension enables OpenAI chat completion API calls",
|
||||
"url": "extension://@janhq/inference-openai-extension/dist/index.js"
|
||||
},
|
||||
"@janhq/inference-triton-trt-llm-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-inference-triton-trt-llm-extension-1.0.0.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/inference-triton-trt-llm-extension",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"description": "This extension enables Nvidia's TensorRT-LLM as an inference engine option",
|
||||
"url": "extension://@janhq/inference-triton-trt-llm-extension/dist/index.js"
|
||||
},
|
||||
"@janhq/model-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-model-extension-1.0.22.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/model-extension",
|
||||
"version": "1.0.22",
|
||||
"main": "dist/index.js",
|
||||
"description": "Model Management Extension provides model exploration and seamless downloads",
|
||||
"url": "extension://@janhq/model-extension/dist/index.js"
|
||||
},
|
||||
"@janhq/monitoring-extension": {
|
||||
"_active": true,
|
||||
"listeners": {},
|
||||
"origin": "/Applications/Jan.app/Contents/Resources/app.asar.unpacked/pre-install/janhq-monitoring-extension-1.0.9.tgz",
|
||||
"installOptions": { "version": false, "fullMetadata": false },
|
||||
"name": "@janhq/monitoring-extension",
|
||||
"version": "1.0.9",
|
||||
"main": "dist/index.js",
|
||||
"description": "This extension provides system health and OS level data",
|
||||
"url": "extension://@janhq/monitoring-extension/dist/index.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Import Extensions
|
||||
slug: /guides/using-extensions/import-extensions/
|
||||
description: Import extensions into Jan.
|
||||
keywords:
|
||||
[
|
||||
Jan AI,
|
||||
Jan,
|
||||
ChatGPT alternative,
|
||||
local AI,
|
||||
private AI,
|
||||
conversational AI,
|
||||
no-subscription fee,
|
||||
large language model,
|
||||
using-models,
|
||||
]
|
||||
---
|
||||
@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Extension Settings
|
||||
slug: /guides/using-extensions/extension-settings/
|
||||
description: Configure settings for extensions.
|
||||
keywords:
|
||||
[
|
||||
Jan AI,
|
||||
Jan,
|
||||
ChatGPT alternative,
|
||||
local AI,
|
||||
private AI,
|
||||
conversational AI,
|
||||
no-subscription fee,
|
||||
large language model,
|
||||
using-models,
|
||||
]
|
||||
---
|
||||
29
docs/docs/guides/06-using-extensions/02-import-extensions.md
Normal file
29
docs/docs/guides/06-using-extensions/02-import-extensions.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Import Extensions
|
||||
slug: /guides/using-extensions/import-extensions/
|
||||
description: Import extensions into Jan.
|
||||
keywords:
|
||||
[
|
||||
Jan AI,
|
||||
Jan,
|
||||
ChatGPT alternative,
|
||||
local AI,
|
||||
private AI,
|
||||
conversational AI,
|
||||
no-subscription fee,
|
||||
large language model,
|
||||
import extensions,
|
||||
]
|
||||
---
|
||||
|
||||
Beside default extensions, you can import extensions into Jan by navigate to `Settings` > `Extensions` > `Manual Installation`. Then, the `~/jan/extensions/extensions.json` file will be updated automatically.
|
||||
|
||||
:::caution
|
||||
|
||||
You need to prepare the extension file in `.tgz` format to install.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
If you want to build your own extension, please refer to the [Build Your First Extension | Developer Documentation](/developer/build-extension/your-first-extension/).
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 429 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 MiB |
Loading…
x
Reference in New Issue
Block a user