Merge branch 'main' of github.com:devforth/adminforth

Author: Romper9

Changelog.md

@@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - badgeTooltip - now you can add a tooltip to the badge to explain what it means
 - ability to authorize not only subscription on websocket but filter out whom users message will be published (updated doc)
 - added ability to refresh menu item badge from the backend using websocket publish
+- fix bugs when e.g. UR (urdu) can't be recognized by LLM (define names explicitly)
+- make user menu switch shorter
 
 # Improved
 

README.md

@@ -11,7 +11,8 @@
 * [Full API reference](https://adminforth.dev/docs/api/).
 
 <div align="center">
-  <img src="https://github.com/user-attachments/assets/5921f5f3-feef-40a8-9b82-3df19ac2eedd" alt="Image description" width="800px">
+  <img src="https://github.com/user-attachments/assets/f507a46b-f282-4f81-97e0-32fceb002ded"
+ alt="Image description" width="800px">
 </div>
 
 Features:

adminforth/adapters/completion-adapter-open-ai-chat-gpt/index.ts

@@ -8,7 +8,10 @@ export default class CompletionAdapterOpenAIChatGPT
 
   constructor(options: AdapterOptions) {
     this.options = options;
-    if (!options.openAiApiKey) {
+  }
+
+  validate() {
+    if (!this.options.openAiApiKey) {
       throw new Error("openAiApiKey is required");
     }
   }

adminforth/adapters/completion-adapter-open-ai-chat-gpt/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/completion-adapter-open-ai-chat-gpt",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

adminforth/adapters/completion-adapter-open-ai-chat-gpt/package.json

@@ -7,13 +7,16 @@ export default class EmailAdapterAwsSes implements EmailAdapter {
 
   constructor(options: AdapterOptions) {
     this.options = options;
-    if (!options.region) {
+  }
+
+  validate() {
+    if (!this.options.region) {
       throw new Error("AWS SES region is required");
     }
-    if (!options.accessKeyId) {
+    if (!this.options.accessKeyId) {
       throw new Error("AWS SES accessKeyId is required");
     }
-    if (!options.secretAccessKey) {
+    if (!this.options.secretAccessKey) {
       throw new Error("AWS SES secretAccessKey is required");
     }
   }

adminforth/adapters/email-adapter-aws-ses/index.ts

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/email-adapter-aws-ses",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

adminforth/adapters/email-adapter-aws-ses/package-lock.json

@@ -628,4 +628,76 @@ import SubComponent from '@@/plugins/ChatGptPlugin/subComponent.vue';
 </script>
 ```
 
-Pay attention that `ChatGptPlugin` is a class name of your plugin so it should be used in path.
+Pay attention that `ChatGptPlugin` is a class name of your plugin so it should be used in path.
+
+
+## Using Adapters
+
+
+There are couple of adapter interfaces in AdminForth like `EmailAdapter` for sending emails and `CompletionAdapter`.
+Adapter is a way to provide same function from different vendors. For example plugin created in this guide uses exactly OpenAI API to get completion.
+But in fact OpenAI is not only one API provider for completion, so `CompletionAdapter` interface is created to be easily extended. 
+Here is code from AdminForth:
+
+```ts
+export interface CompletionAdapter {
+
+  validate();
+
+  complete(
+    content: string,
+    stop: string[],
+    maxTokens: number,
+  ): Promise<{
+    content?: string;
+    finishReason?: string;
+    error?: string;
+  }>;
+}
+```
+
+To use adapter in plugin you should define it in plugin options:
+
+```ts title='./af-plugin-any-complete/types.ts'
+
+import { CompletionAdapter } from "adminforth";
+
+export interface PluginOptions {
+  ...
+
+//diff-add
+  /**
+//diff-add
+   * Adapter for completion
+//diff-add
+   */
+//diff-add
+  adapter: CompletionAdapter;
+}
+```
+
+Then, in your plugin you should call `this.options.validate()`, this function will throw error if adminforth app developer did not pass
+required parameter (e.g. API token for OpenAI). You can do it in `modifyResourceConfig` but, then it will be called at build time (e.g. in Dockerfile). However build time not always has access to all environment variables including `OPENAI_API_KEY`.
+
+So we recommend calling validation in `validateConfigAfterDiscover` method because it called only in runtime on app start and not in build time.
+
+```ts title='./af-plugin-any-complete/index.ts'
+  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
+//diff-add
+    this.options.adapter.validate();
+
+    ...
+  }
+```
+
+If some issue with config will happen, validate method will throw error and instance will be crashed so AdminForth app developer will see error message in console and will have to fix it before starting app.
+
+Now you can simply use adapter:
+
+```ts title='./af-plugin-any-complete/index.ts'
+handler: async (a) => {
+  ...
+  const resp = await this.options.adapter.complete(content, ['.'], this.options.expert?.maxTokens || 50);
+  ...
+}
+```