npm package: @kolasai/clean-talk-client
Description: This repository hosts the js client for Kolas.Ai's Clean Talk public API, making it easy for developers to integrate Kolas.Ai’s machine learning services into your applications.
Author: Kolas.Ai
Latest version: 1.0.6

# Clean Talk JS Client for Kolas.Ai Public API

Welcome to the **Kolas.Ai Public API** documentation! This repository hosts the JS client for Kolas.Ai's Clean Talk public API, making it easy for developers to integrate Kolas.Ai’s machine learning services into your applications.

## Overview

Clean Talk API is designed to classify message categories based on a trained dataset within a configured project. Use this API to accurately categorize messages into types like "Neutral", "Insult", "Spam" , etc. We support different languages, including English, Russian, Ukrainian, and we can add any languages by request (message to info@kolas.ai).

### Key Features
- **Predict Message Categories**: Use the `/predictions/predict` endpoint to sync classify messages based on your project-specific datasets and `/predictions/asyncPredict` endpoint to async classify messages.
- **High Accuracy**: Predictions include probability scores, giving you confidence in the classification results.
- **OAuth2 Authentication**: Secure access via OAuth2 client credentials flow.

## Usage

The Kolas.Ai API follows the OpenAPI 3.1 standard. To get started:

1. Create a new account on the [Kolas.Ai platform](https://app.kolas.ai/register).
2. Create a new project [Clean Talk](https://app.kolas.ai/projects/create) and configure your datasets.
3. **Authentication**: Obtain an access token using OAuth2 client credentials.
4. **Make Predictions**: Send a POST request to `/predictions/predict` (or `/predictions/asyncPredict`) with your `projectId` and messages.
5. **Receive Predictions**: Retrieve predicted categories and their probabilities in the API response.

## Installation
You can install the CleanTalk JS client via Composer. Run the following command in your project directory:

```bash
npm i @kolasai/clean-talk-client
```
- GitHub.com: [https://github.com/kolasai/clean-talk-js-client](https://github.com/kolasai/clean-talk-js-client)
- NPMjs.com: [https://www.npmjs.com/package/@kolasai/clean-talk-client](https://www.npmjs.com/package/@kolasai/clean-talk-client)

## Authentication

This API uses **OAuth2 client credentials** for secure access. You’ll need to request a token using your client credentials from the Kolas.Ai platform.

```ts
import { KolasAiOAuthClient } from '@kolasai/clean-talk-client';

const oauthClient = new KolasAiOAuthClient();
const authResult = await oauthClient.auth(YOUR_CLIENT_ID, YOUR_CLIENT_SECRET);

```

`authResult` contains the access token and expires_in information, which you will use to authenticate your API requests. You need to update token after its expiration.

### Example for Sync Request
Once you have your access token, you can make a request like this:

```ts
import { CleanTalkPredictionClient, PredictRequest, Message } from '@kolasai/clean-talk-client';

const client = new CleanTalkPredictionClient(authResult.getAccessToken());
const response = await client.predict(
    new PredictRequest(
        YOUR_PROJECT_ID,
        [
            new Message('11177c92-1266-4817-ace5-cda430481111', 'Hello world!'),
            new Message('22277c92-1266-4817-ace5-cda430482222', 'Good buy world!'),
        ]
    )
);

for (const prediction of response.getPredictions()) {
    console.log(`MessageId: ${prediction.getMessageId()}`);
    console.log(`Message: ${prediction.getMessage()}`);
    console.log(`Prediction: ${prediction.getPrediction()}`);
    console.log(`Probability: ${prediction.getProbability()}`);
    console.log(`Categories: ${prediction.getCategories().join(', ')}`);
}
```

### Example Response

```txt
MessageId: 11177c92-1266-4817-ace5-cda430481111
Message: Hello world!
Prediction: Neutral
Probability: 0.9036153107882
Categories: Insult, Neutral, Spam

MessageId: 22277c92-1266-4817-ace5-cda430482222
Message: Good buy world!
Prediction: Neutral
Probability: 0.99374455213547
Categories: Insult, Neutral, Spam
```

### Example for Async Request
Once you have your access token, you can make a request like this:

```ts
import { PredictRequest, Message } from '@kolasai/clean-talk-client';

await client.asyncPredict(new PredictRequest(
    YOUR_PROJECT_ID,
    [
        new Message('11177c92-1266-4817-ace5-cda430483333', 'Hello world!'),
        new Message('22277c92-1266-4817-ace5-cda430484444', 'Good buy world!'),
    ]
));
```

Responses will be sent to the configured webhook URL in your project settings.

## Documentation Links
- [Kolas.Ai OpenAPI schema](https://github.com/kolasai/public-openapi): Explore our OpenAPI specification.
- [Kolas.Ai Platform Documentation](https://kolas.ai/documentation/): Learn more about configuring projects and using Kolas.Ai’s platform.

## License

This API specification is released under the **Apache 2.0 License**. See the [LICENSE](https://www.apache.org/licenses/LICENSE-2.0.html) for more details.

__

Feel free to explore, test, and integrate Kolas.Ai's API, and reach out with any questions!