Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add GlobalSymbolsApi and docs fixes #6

Merged
merged 5 commits into from
Feb 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 56 additions & 41 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
```

Expand All @@ -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.

Expand Down Expand Up @@ -104,7 +114,7 @@ Return:

It returns an array of objects with the following properties:

```javascript
```typescript
[
{
id: number;
Expand All @@ -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[].
Expand Down Expand Up @@ -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/)
6 changes: 3 additions & 3 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 6 additions & 6 deletions src/engine.ts
Original file line number Diff line number Diff line change
@@ -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({
Expand Down Expand Up @@ -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,
Expand All @@ -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;
Expand Down
38 changes: 38 additions & 0 deletions src/types/global-symbols.d.ts
Original file line number Diff line number Diff line change
@@ -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[];