Trias: A Fast and Smart Text Classifier

Trias is an innovative text classifier that empowers you to:

• Automatically infer categories from textual data.
• Train and update its model in real-time, allowing you to add training examples on the fly.
• Persist the trained model in a compact, portable, and compressed file.

Inspired by the ancient Greek prophetic nymphs known as the Trias (Cleodora, Melaina and Daphnis), this tool reimagines divination for the digital age. Just as the Trias interpreted omens to foresee the future, Trias processes large streams of text to generate insightful predictions.

Note: All Trias methods are asynchronous, so you can perform additional training and prediction simultaneously without blocking your application.

Installation

Install Trias via NPM:

npm install trias

Usage

Importing

import { Trias } from 'trias';

// or, using CommonJS:
const { Trias } = require('trias');

Initializing

Creating a new Trias instance.

const trias = new Trias({

    file: './my-model.trias', // Path to the model file
    create: true, // Initialize a new model if none exists
    n: 3, // Maximum n-gram length (1-3)
    language: 'en', // ISO 2-letter code for the language (e.g., 'en' for English)
    excludes: ['separator', 'live', 'unknown'], // Terms to exclude
    size: 4096 * 1024 // Maximum model size in bytes

});

Training

Train Trias asynchronously using text inputs paired with their corresponding category labels. In the example below, the train() method is used to update the model with new training data:

await trias.train([
    {
        input: "Dark clouds loom on the horizon.",
        output: ["pessimistic", "dark"]
    },
    {
        input: "The future holds great promise.",
        output: ["optimistic"]
    }
]);

You can invoke train() multiple times on the same model to perform incremental training. The model will continuously learn from the new data while retaining the most significant information if the total exceeds the predefined size.

Predicting

Predict the category of a new text asynchronously:

const prediction = await trias.predict("What does the future hold?");
console.log(prediction);
// Example output: "optimistic"

For a more detailed prediction with scores:

const predictions = await trias.predict("What does the future hold?", { as: "objects", amount: 2 });
console.log(predictions);
// Example output:
// [
//   { category: "optimistic", score: 0.8 },
//   { category: "pessimistic", score: 0.2 }
// ]

The amount option specifies the exact number of predictions the user wants, whereas limit automatically selects the most related categories up to a maximum of limit. This means that if there aren't enough strongly related categories, the function may return fewer than limit predictions.

When limit is provided, it disables the user-defined amount.

const predictions = await trias.predict("What does the future hold?", { as: "array", limit: 2 });
console.log(predictions);
// Example output:
// [
//   "optimistic"
// ]

For weighted predictions, pass an object where the keys are texts and the values are their weights:

const weightedPredictions = await trias.predict({
    "The future is bright": 2,
    "Challenges lie ahead": 1
});
console.log(weightedPredictions);

Saving

Save the instance's current state to the designated file:

await trias.save();

Resetting

Reset Trias by clearing all trained data:

trias.reset();

API Reference

Constructor Options

Methods

train(text, category)

Train the instance with a new example.

Parameters:

• text (string | object): The input text. You can also provide an object with an input property.
• category (string): The associated category or label for the text.

predict(text, options)

Asynchronously predicts the category of the input text.

Parameters:

• text (string | object): The input text for prediction.
• options (object):
  • as (string): Desired output format ('string', 'array', or 'objects').
  • amount (number): Maximum number of categories to return.

Returns: A prediction result in the specified format.

getRelatedGroups(categoryScores, options)

Get related groups of categories based on the input category scores.

Parameters:

• categoryScores (object): An object where keys are category names and values are their scores.
• options (object):
  • as (string): Desired output format ('string', 'array', or 'objects').
  • amount (number): Maximum number of categories to return.

Returns: Related groups of categories in the specified format.

save()

Asynchronously saves the current state of the model to the designated file.

reset()

Clears all trained data and resets the model.

Notes

• Trias may remove infrequently used omens to maintain the model within the specified size limit.
• You can review some examples of Trias usage in the test.js and test-alt.js files.