feature: @janhq/plugin-core module & usage

[louis-menlo]

For now, it is quite hard for developers to write a plugin, since they have to register functions using function name as string. It is not well documented yet.

Maintain an npm module so developer can install in a plugin project, import module to retrieve all needed interfaces, types
The module should expose:

• Service Interfaces
• Inheritable methods such as: init, onStart, onDelete, onDestroy
• API: IPC, HTTP, FILE, main/utility process task executor, updater, ...
• UI: components, events ...

Action Items:

• @janhq/plugin-core module
• refactor web to use exported services from module
• refactor data-plugin to provide DAL & move model logics to model management plugin
• flatten product > modelVersion tables
• model-management plugin is a TS plugin now

Next phase:

• access core states (get current running model, current active conversation,...)
• ui services
• base plugin methods (onStart, onDestroy, onDispose)
• event listener

==========

@janhq/plugin-core

The module includes functions for communicating with core APIs, registering plugin extensions, and exporting type definitions.

Usage

Import the package

// javascript
const core = require("@janhq/plugin-core");

// typescript
import { core } from "@janhq/plugin-core";

Register Plugin Extensions

Every plugin must define an init function in its main entry file to initialize the plugin and register its extensions with the Jan platform.

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.

import { RegisterExtensionPoint, DataService } from "@janhq/plugin-core";

function getConversations() {
  // Your logic here
}

export function init({ register }: { register: RegisterExtensionPoint }) {
  register(DataService.GetConversations, getConversations.name, getConversations);
}

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/plugin-core library.

// index.ts
import { store, core } from "@janhq/plugin-core";

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.

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.

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.

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.

function deleteData() {
  const selector = { name: "meow" };
  store.deleteOne("conversations", selector);
  // Delete a document from the "conversations" collection.
}

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.

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.

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/plugin-core library.

// index.ts
import { core } from "@janhq/plugin-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.

// 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.

// 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.

// 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
• DataService
• InferenceService
• ModelManagementService
• SystemMonitoringService
• PreferenceService

StoreService

The StoreService enum represents available methods for managing the database store. It includes the following methods:

• CreateCollection: Creates a new collection in the data store.
• DeleteCollection: Deletes an existing collection from the data store.
• InsertOne: Inserts a new value into an existing collection in the data store.
• UpdateOne: Updates an existing value in an existing collection in the data store.
• UpdateMany: Updates multiple records in a collection in the data store.
• DeleteOne: Deletes an existing value from an existing collection in the data store.
• DeleteMany: Deletes multiple records in a collection in the data store.
• FindMany: Retrieves multiple records from a collection in the data store.
• FindOne: Retrieves a single record from a collection in the data store.

DataService

The DataService enum represents methods related to managing conversations and messages. It includes the following methods:

• GetConversations: Gets a list of conversations from the data store.
• CreateConversation: Creates a new conversation in the data store.
• DeleteConversation: Deletes an existing conversation from the data store.
• CreateMessage: Creates a new message in an existing conversation in the data store.
• UpdateMessage: Updates an existing message in an existing conversation in the data store.
• GetConversationMessages: Gets a list of messages for an existing conversation from the data store.

InferenceService

The InferenceService enum exports:

• InferenceUrl: The URL for the inference server.
• InitModel: Initializes a model for inference.
• StopModel: Stops a running inference model.

ModelManagementService

The ModelManagementService enum provides methods for managing models:

• GetDownloadedModels: Gets a list of downloaded models.
• GetAvailableModels: Gets a list of available models from data store.
• DeleteModel: Deletes a downloaded model.
• DownloadModel: Downloads a model from the server.
• SearchModels: Searches for models on the server.
• GetConfiguredModels: Gets configured models from the data store.
• StoreModel: Stores a model in the data store.
• UpdateFinishedDownloadAt: Updates the finished download time for a model in the data store.
• GetUnfinishedDownloadModels: Gets a list of unfinished download models from the data store.
• GetFinishedDownloadModels: Gets a list of finished download models from the data store.
• DeleteDownloadModel: Deletes a downloaded model from the data store.
• GetModelById: Gets a model by its ID from the data store.

PreferenceService

The PreferenceService enum provides methods for managing plugin preferences:

• ExperimentComponent: Represents the UI experiment component for a testing function.

SystemMonitoringService

The SystemMonitoringService enum includes methods for monitoring system resources:

• GetResourcesInfo: Gets information about system resources.
• GetCurrentLoad: Gets the current system load.

For more detailed information on each of these components, please refer to the source code.

[namchuai]

💯

[hiento09]

💯