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.
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.
The images are retrieved from the Global Symbols website, and the text descriptions are generated using the OpenAI Node API Library. If the image is not found, the engine will create a new pictogram using the Cboard Pictonizer.
Table of Contents
Installation
npm install cboard-ai-engine
or
yarn install cboard-ai-engine
Usage
The code below shows how to get started using the Cboard AI Engine.
import { initEngine } from 'cboard-ai-engine'; const engineInstance = initEngine({ openAIConfiguration, globalSymbolsApiURL, pictonizerApiURL }); const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(prompt, maxSuggestions, symbolSet, language);
Initialization
const engineInstance = initEngine({ openAIConfiguration: ConfigurationParameters, globalSymbolsApiURL: string, pictonizerApiURL: string });
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.
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 ishttps://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:
-
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. -
getSuggestions: This method is used to get the words suggestions. -
pictonizer: This method is used to generate a new pictogram using the Cboard Pictonizer.
Methods
getSuggestionsAndProcessPictograms
const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(prompt: string, maxSuggestions: number, symbolSet: string, language: string) => Promise<Array<{id: number, picto: string[], text: string, locale: string}>>;
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.
Parameters:
-
prompt: The prompt to be used to generate the suggestions. Required. Type: string. -
maxSuggestions: The maximum number of suggestions to be returned. Default is 10. Optional. Type: number. -
symbolSet: The symbol set to be used. Default isARASAAC. Optional. Type: string. -
language: The language to be used. Default iseng. Optional. Type: string.
Return:
It returns an array of objects with the following properties:
[ { id: number; picto: string[]; text: string; locale: string; } ]
Where:
-
id: The pictogram id. Type: number. -
picto: The pictogram URL. Type: string[]. -
text: The text description. Type: string. -
locale: The language. Type: string.
getSuggestions
const suggestions = await engineInstance.getSuggestions(prompt: string, maxSuggestions: number) => Promise<Array<string>>;
This method is used to get the words suggestions.
Parameters:
-
prompt: The prompt to be used to generate the suggestions. Required. Type: string. -
maxSuggestions: The maximum number of suggestions to be returned. Default is 10. Optional. Type: number.
Return:
It returns an array of strings with the suggestions.
pictonizer
const pictogram = await engineInstance.pictonizer(imagePrompt: string, language: string) => Promise<string>;
This method is used to generate a new pictogram using the Cboard Pictonizer.
Parameters:
-
imagePrompt: The prompt to be used to generate the pictogram. Required. Type: string. -
language: The language to be used. Default iseng. Optional. Type: string.
Return:
NOTE: This needs to be fixed, needs to be an array of strings that contains just the URL of the pictogram.
It returns an stringified object with the following properties:
{ images: images.map((image: any) => ({ data: image, width: width, height: height, })), prompt: prompt, };
If no URL is passed on the pictonizerApiURL parameter, it will return:
{ 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.
try { const suggestions = await engineInstance.getSuggestionsAndProcessPictograms(prompt, maxSuggestions, symbolSet, language); } catch (error) { console.error(error); }
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
- ARASAAC Symbols - CC BY-NC-SA 4.0