Nicholai/jan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: store, events, ref docs

Browse Source
This commit is contained in:
0xSage 2023-10-27 10:59:45 +07:00
parent 85e460c848
commit 0b488446ee
9 changed files with 103 additions and 273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/docs/apps/azure-openai.md Normal file
View File

@ -0,0 +1,4 @@
---
sidebar_position: 1
title: "Azure OpenAI integration"
---

4
docs/docs/apps/rag.md Normal file
View File

@ -0,0 +1,4 @@
---
sidebar_position: 1
title: "Data retrieval app"
---

272
docs/docs/reference/coreservice.md
View File

@ -1,278 +1,20 @@
--- ---
sidebar_position: 1 sidebar_position: 1
title: "@janhq/core" title: "CoreService"
--- ---
## @janhq/core `CoreService` provides an interface for implementing custom methods in Jan.
It lets you define shared behavior across your custom application, like your app handles state, models, or inferencing behavior.
> The module includes functions for communicating with core APIs, registering plugin extensions, and exporting type definitions.
## Usage ## Usage
### Import the package
```js ```js
// javascript import { CoreService, ... } from "@janhq/core";
const core = require("@janhq/core");
// typescript
import * as core from "@janhq/core";
``` ```
### Register Plugin Extensions ## CoreService
Every plugin must define an `init` function in its main entry file to initialize the plugin and register its extensions with the Jan platform. The `CoreService` type bundles the following services:
You can `register` any function as a plugin extension using `CoreServiceAPI` below. For example, the `DataService.GetConversations` entry name can be used to register a function that retrieves conversations.
Once the extension is registered, it can be used by other plugins or components in the Jan platform. For example, a UI component might use the DataService.GetConversations extension to retrieve a list of conversations to display to the user.
```js
import { RegisterExtensionPoint, DataService } from "@janhq/core";
function getConversations() {
// Your logic here
}
export function init({ register }: { register: RegisterExtensionPoint }) {
register(DataService.GetConversations, getConversations.name, getConversations);
}
```
### Interact with Local Data Storage
The Core API allows you to interact with local data storage. Here are a couple of examples of how you can use it:
#### Insert Data
You can use the store.insertOne function to insert data into a specific collection in the local data store.
```js
import { store } from "@janhq/core";
function insertData() {
store.insertOne("conversations", { name: "meow" });
// Insert a new document with { name: "meow" } into the "conversations" collection.
}
```
#### Get Data
To retrieve data from a collection in the local data store, you can use the `store.findOne` or `store.findMany` function. It allows you to filter and retrieve documents based on specific criteria.
store.getOne(collectionName, key) retrieves a single document that matches the provided key in the specified collection.
store.getMany(collectionName, selector, sort) retrieves multiple documents that match the provided selector in the specified collection.
```js
import { store } from "@janhq/core";
function getData() {
const selector = { name: "meow" };
const data = store.findMany("conversations", selector);
// Retrieve documents from the "conversations" collection that match the filter.
}
```
#### Update Data
You can update data in the local store using these functions:
store.updateOne(collectionName, key, update) updates a single document that matches the provided key in the specified collection.
store.updateMany(collectionName, selector, update) updates multiple documents that match the provided selector in the specified collection.
```js
function updateData() {
const selector = { name: "meow" };
const update = { name: "newName" };
store.updateOne("conversations", selector, update);
// Update a document in the "conversations" collection.
}
```
#### Delete Data
You can delete data from the local data store using these functions:
store.deleteOne(collectionName, key) deletes a single document that matches the provided key in the specified collection.
store.deleteMany(collectionName, selector) deletes multiple documents that match the provided selector in the specified collection.
```js
function deleteData() {
const selector = { name: "meow" };
store.deleteOne("conversations", selector);
// Delete a document from the "conversations" collection.
}
```
### Events
You can subscribe to NewMessageRequest events by defining a function to handle the event and registering it with the events object:
```js
import { events } from "@janhq/core";
function handleMessageRequest(message: NewMessageRequest) {
// Your logic here. For example:
// const response = openai.createChatCompletion({...})
}
function registerListener() {
events.on(EventName.OnNewMessageRequest, handleMessageRequest);
}
// Register the listener function with the relevant extension points.
export function init({ register }) {
registerListener();
}
```
In this example, we're defining a function called handleMessageRequest that takes a NewMessageRequest object as its argument. We're also defining a function called registerListener that registers the handleMessageRequest function as a listener for NewMessageRequest events using the on method of the events object.
```js
import { events } from "@janhq/core";
function handleMessageRequest(data: NewMessageRequest) {
// Your logic here. For example:
const response = openai.createChatCompletion({...})
const message: NewMessageResponse = {
...data,
message: response.data.choices[0].message.content
}
// Now emit event so the app can display in the conversation
events.emit(EventName.OnNewMessageResponse, message)
}
```
### Preferences
To register plugin preferences, you can use the preferences object from the @janhq/core package. Here's an example of how to register and retrieve plugin preferences:
```js
import { PluginService, preferences } from "@janhq/core";
const pluginName = "your-first-plugin";
const preferenceKey = "";
const preferenceName = "Your First Preference";
const preferenceDescription = "This is for example only";
const defaultValue = "";
export function init({ register }: { register: RegisterExtensionPoint }) {
// Register preference update handlers. E.g. update plugin instance with new configuration
register(PluginService.OnPreferencesUpdate, pluginName, onPreferencesUpdate);
// Register plugin preferences. E.g. Plugin need apiKey to connect to your service
preferences.registerPreferences <
string >
(register, pluginName, preferenceKey, preferenceName, preferenceDescription, defaultValue);
}
```
In this example, we're registering preference update handlers and plugin preferences using the preferences object. We're also defining a PluginName constant to use as the name of the plugin.
To retrieve the values of the registered preferences, we're using the get method of the preferences object and passing in the name of the plugin and the name of the preference.
```js
import { preferences } from "@janhq/core";
const pluginName = "your-first-plugin";
const preferenceKey = "apiKey";
const setup = async () => {
// Retrieve apiKey
const apiKey: string = (await preferences.get(pluginName, preferenceKey)) ?? "";
};
```
### Access Core API
To access the Core API in your plugin, you can follow the code examples and explanations provided below.
##### Import Core API and Store Module
In your main entry code (e.g., `index.ts`), start by importing the necessary modules and functions from the `@janhq/core` library.
```js
// index.ts
import * as core from "@janhq/core";
```
#### Perform File Operations
The Core API also provides functions to perform file operations. Here are a couple of examples:
#### Download a File
You can download a file from a specified URL and save it with a given file name using the core.downloadFile function.
```js
function downloadModel(url: string, fileName: string) {
core.downloadFile(url, fileName);
}
```
#### Delete a File
To delete a file, you can use the core.deleteFile function, providing the path to the file you want to delete.
```js
function deleteModel(filePath: string) {
core.deleteFile(path);
}
```
#### Execute plugin module in main process
To execute a plugin module in the main process of your application, you can follow the steps outlined below.
##### Import the `core` Object
In your main process code (e.g., `index.ts`), start by importing the `core` object from the `@janhq/core` library.
```js
// index.ts
import * as core from "@janhq/core";
```
##### Define the Module Path
Specify the path to the plugin module you want to execute. This path should lead to the module file (e.g., module.js) that contains the functions you wish to call.
```js
// index.ts
const MODULE_PATH = "data-plugin/dist/module.js";
```
##### Define the Function to Execute
Create a function that will execute a function defined in your plugin module. In the example provided, the function `getConversationMessages` is created to invoke the `getConvMessages` function from the plugin module.
```js
// index.ts
function getConversationMessages(id: number) {
return core.invokePluginFunc(MODULE_PATH, "getConvMessages", id);
}
export function init({ register }: { register: RegisterExtensionPoint }) {
register(DataService.GetConversationMessages, getConversationMessages.name, getConversationMessages);
}
```
##### Define Your Plugin Module
In your plugin module (e.g., module.ts), define the logic for the function you wish to execute. In the example, the function getConvMessages is defined with a placeholder comment indicating where your logic should be implemented.
```js
// module.ts
function getConvMessages(id: number) {
// Your logic here
}
module.exports = {
getConvMessages,
};
```
## CoreService API
The `CoreService` type is an exported union type that includes:
- `StoreService` - `StoreService`
- `DataService` - `DataService`
@ -350,4 +92,4 @@ The `PluginService` enum includes plugin cycle handlers:
- `OnStart`: Handler for starting. E.g. Create a collection. - `OnStart`: Handler for starting. E.g. Create a collection.
- `OnPreferencesUpdate`: Handler for preferences update. E.g. Update instances with new configurations. - `OnPreferencesUpdate`: Handler for preferences update. E.g. Update instances with new configurations.
For more detailed information on each of these components, please refer to the source code. For more detailed information on each of these components, please refer to the source code.

51
docs/docs/reference/events.md Normal file
View File

@ -0,0 +1,51 @@
---
sidebar_position: 2
title: "events"
---
`events` lets you receive events about actions that take place in the app, like when a user sends a new message.
You can then implement custom logic handlers for such events.
## Usage
```js
import { events } from "@janhq/core";
```
## EventName
The `EventName` enum bundles the following events:
- `OnNewConversation`
- `OnNewMessageRequest`
- `OnNewMessageResponse`
- `OnMessageResponseUpdate`
- `OnDownloadUpdate`
- `OnDownloadSuccess`
- `OnDownloadError`
## event.on
Adds an observer for an event.
```js
const on: (eventName: string, handler: Function) => void = (eventName, handler);
```
## event.emit
Emits an event.
```js
const emit: (eventName: string, object: any) => void = (eventName, object);
```
## event.off
Removes an observer for an event.
```js
const off: (eventName: string, handler: Function) => void =
(eventName, handler);
```

6
docs/docs/reference/models_catalog.md → docs/docs/reference/model-catalog.md
View File

@ -1,9 +1,10 @@
--- ---
sidebar_position: 1 sidebar_position: 3
title: "@janhq/models" title: "Model catalog"
--- ---
### Install ### Install
Using yarn: Using yarn:
```shell ```shell
@ -43,6 +44,7 @@ console.log(MODEL_CATALOG_URL);
``` ```
### How to contribute ### How to contribute
1. Go to [Jan Models](https://github.com/janhq/models) 1. Go to [Jan Models](https://github.com/janhq/models)
2. Create an Issue for new model (template incoming) 2. Create an Issue for new model (template incoming)
3. Create a PR for new model familly (See [The Bloke zephyr 7B alpha GGUF](https://github.com/janhq/models/blob/main/TheBloke-zephyr-7B-alpha-GGUF.json)) to `main` branch 3. Create a PR for new model familly (See [The Bloke zephyr 7B alpha GGUF](https://github.com/janhq/models/blob/main/TheBloke-zephyr-7B-alpha-GGUF.json)) to `main` branch

6
docs/docs/reference/plugins_catalog.md
View File

@ -1,6 +0,0 @@
---
sidebar_position: 1
title: "@janhq/plugins"
---
To be updated. In the mean time, please refer to our [ADR 007 - Plugin catalog](https://github.com/janhq/jan/blob/main/adr/adr-007-jan-plugin-catalog.md)

6
docs/docs/reference/preferences.md Normal file
View File

@ -0,0 +1,6 @@
---
sidebar_position: 4
title: "preferences"
---
## Usage

15
docs/docs/reference/store.md Normal file
View File

@ -0,0 +1,15 @@
---
sidebar_position: 3
title: "store"
---
`store` is a helper library for working with Jan app's local storage database.
Jan ships with a [pouchDB](https://pouchdb.com/) client side noSQL db to persist usage state
store (logic from @data-plugin which implements StoreService)
## Usage
```js
import { store } from "@janhq/core";
```

12
docs/sidebars.js
View File

@ -71,6 +71,18 @@ const sidebars = {
}, },
], ],
}, },
{
type: "category",
label: "Apps",
collapsible: true,
collapsed: false,
items: [
{
type: "autogenerated",
dirName: "apps",
},
],
},
{ {
type: "category", type: "category",
label: "Tutorials", label: "Tutorials",