Merge pull request #6 from cboard-org/chore/streamline-readme

Streamline docs and license

README.md

@@ -1,6 +1,6 @@
 # Cboard AI Engine
 
-This is a engine for the Cboard AI builder that is used to generate the boards content suggestions and create new pictograms if is necessary.
+This engine powers the Cboard AI builder, designed to generate content suggestions for boards and create new pictograms as necessary.
 
 With a simple prompt, it will generate a list of pictograms that can be used to create an AAC board. Each pictogram will be associated with a text description and a image.
 
@@ -10,25 +10,23 @@ The images are retrieved from the [Global Symbols](https://www.globalsymbols.com
 
 - [Installation](#installation)
 - [Usage](#usage)
-    - [Initialization](#initialization)
+  - [Initialization](#initialization)
 - [Methods](#methods)
-    - [getSuggestionsAndProcessPictograms](#getSuggestionsAndProcessPictograms)
-    - [getSuggestions](#getSuggestions)
-    - [pictonizer](#pictonizer)
+  - [getSuggestionsAndProcessPictograms](#getSuggestionsAndProcessPictograms)
+  - [getSuggestions](#getSuggestions)
+  - [pictonizer](#pictonizer)
 - [Error Handling](#error-handling)
 - [License](#license)
 
-
-
 ## Installation
 
-```
+```bash
 npm install cboard-ai-engine
 ```
 
 or
 
-```
+```bash
 yarn install cboard-ai-engine
 ```
 
@@ -37,42 +35,54 @@ yarn install cboard-ai-engine
 The code below shows how to get started using the Cboard AI Engine.
 
 ```javascript
-
-    import { initEngine } from 'cboard-ai-engine';
-
-    const engineInstance = initEngine({ openAIConfiguration, globalSymbolsApiURL, pictonizerApiURL });
-
-    const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(prompt, maxSuggestions, symbolSet, language);
+import { initEngine } from "cboard-ai-engine";
+
+const engineInstance = initEngine({
+  openAIConfiguration,
+  globalSymbolsApiURL,
+  pictonizerApiURL,
+});
+
+const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(
+  prompt,
+  maxSuggestions,
+  symbolSet,
+  language,
+);
 ```
 
 ### Initialization
 
 ```javascript
-    const engineInstance = initEngine({ openAIConfiguration: ConfigurationParameters, globalSymbolsApiURL: string, pictonizerApiURL: string });
+const engineInstance = initEngine({
+  openAIConfiguration,
+  globalSymbolsApiURL,
+  pictonizerApiURL,
+});
 ```
 
 The `initEngine` function is used to initialize the engine. Takes an object with the following properties as its only argument:
 
-
 - `openAIConfiguration`: Object with the OpenAI configuration. Required.
 
 ```javascript
-    const openAIConfiguration = {
-        apiKey: 'your openai api key',
-        basePath: 'https://your-openai-base-path.com',
-        baseOptions: {
-            headers: { 'api-key': 'your openai api key'},
-            params: {'api-version': '2022-12-01'}
-        }
-    }
+const openAIConfiguration = {
+  apiKey: "your openai api key",
+  basePath: "https://your-openai-base-path.com",
+  baseOptions: {
+    headers: { "api-key": "your openai api key" },
+    params: { "api-version": "2022-12-01" },
+  },
+};
 ```
+
 - `globalSymbolsApiURL`: The Global Symbols API URL. Default is `https://www.globalsymbols.com/api/v1/labels/search/`. Optional.
 
 - `pictonizerApiURL`: The Cboard Pictonizer API URL. Optional.
 
 Return:
 
- It returns an instance of the engine  with the following methods:
+It returns an instance of the engine with the following methods:
 
 - `getSuggestionsAndProcessPictograms`: This method is used to get the suggestions and process the pictograms. It returns a list of items that can be used to create an AAC board. Each item is associated with a text description and a pictogram.
 
@@ -104,7 +114,7 @@ Return:
 
 It returns an array of objects with the following properties:
 
-```javascript
+```typescript
     [
         {
             id: number;
@@ -114,8 +124,9 @@ It returns an array of objects with the following properties:
         }
     ]
 ```
-Where: 
-
+
+Where:
+
 - `id`: The pictogram id. Type: number.
 
 - `picto`: The pictogram URL. Type: string[].
@@ -165,45 +176,49 @@ It returns an stringified object with the following properties:
 ```javascript
     {
         images: images.map((image: any) => ({
-          data: image, 
+          data: image,
           width: width,
           height: height,
         })),
         prompt: prompt,
     };
 ```
 
-If no URL is passed on the `pictonizerApiURL` parameter, it will return: 
+If no URL is passed on the `pictonizerApiURL` parameter, it will return:
 
 ```javascript
     {
         images: [{ data: "ERROR Generating Pictogram" }],
         prompt: imagePrompt,
     };
 ```
+
 And no error will be thrown.
 
 ## Error Handling
 
 When an error occurs, an error will be thrown. It is recommended to use a try/catch block to handle it.
 
-
 ```javascript
-    try {
-        const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(prompt, maxSuggestions, symbolSet, language);
-    } catch (error) {
-        console.error(error);
-    }
+try {
+  const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(
+    prompt,
+    maxSuggestions,
+    symbolSet,
+    language,
+  );
+} catch (error) {
+  console.error(error);
+}
 ```
-    NOTE: Is not needed on the initialization method.
 
+    NOTE: Is not needed on the initialization method.
 
 ## License
 
 Copyright © 2024 Cboard
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.
 
-* Code - [GPLv3](https://github.com/cboard-org/cboard/blob/master/LICENSE.txt)
-* ARASAAC Symbols - [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
-
+- Code - [GPLv3](https://github.com/cboard-org/cboard/blob/master/LICENSE.txt)
+- ARASAAC Symbols - [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)

src/engine.ts

@@ -1,12 +1,12 @@
-import { Configuration, OpenAIApi } from "openai";
+import { Configuration, OpenAIApi, ConfigurationParameters } from "openai";
 import axios, { AxiosRequestConfig } from "axios";
 import { txt2imgBody, DEFAULT_GLOBAL_SYMBOLS_URL } from "./constants";
-import { ConfigurationParameters } from "openai";
+import { LabelsSearchApiResponse } from "./types/global-symbols";
 
 const globalConfiguration = {
   openAIInstance: {} as OpenAIApi,
   globalSymbolsURL: DEFAULT_GLOBAL_SYMBOLS_URL,
-  pictonizerURL:"",
+  pictonizerURL: "",
 };
 
 export function init({
@@ -85,7 +85,7 @@ async function fetchPictogramsURLs(
 ): Promise<Pictogram[]> {
   try {
     const requests = words.map((word) =>
-      axios.get(globalConfiguration.globalSymbolsURL, {
+      axios.get<LabelsSearchApiResponse>(globalConfiguration.globalSymbolsURL, {
         params: {
           query: word,
           symbolSet: symbolSet,
@@ -109,10 +109,10 @@ async function fetchPictogramsURLs(
     );
 
     const pictogramsList: Pictogram[] = dataList.map((data) => ({
-      id: data[0].id,
+      id: data[0].id?.toString(),
       text: data[0].text,
       locale: data[0].language,
-      picto: data.map((picto: any) => picto.picto.image_url),
+      picto: data.map((label) => label.picto.image_url),
     }));
 
     return pictogramsList;

src/types/global-symbols.d.ts

@@ -0,0 +1,38 @@
+type LabelSearchResponse = {
+  id: number;
+  text: string;
+  text_diacritised: string;
+  description: string;
+  language: string;
+  picto: Pictogram;
+};
+
+type Pictogram = {
+  id: number;
+  symbolset_id: number;
+  part_of_speech: string;
+  image_url: string;
+  native_format: string;
+  adaptable: string;
+  symbolset: SymbolSet;
+};
+
+type SymbolSet = {
+  id: number;
+  slug: string;
+  name: string;
+  publisher: string;
+  publisher_url: string;
+  status: string;
+  licence: Licence;
+  featured_level: number;
+};
+
+type Licence = {
+  name: string;
+  url: string;
+  version: string;
+  properties: string;
+};
+
+export type LabelsSearchApiResponse = LabelSearchResponse[];