clustex/README.md

Clustex is a lightweight text classification package designed to efficiently categorize text based on similarity metrics and learned token weights.

# Clustex Documentation

Clustex is a lightweight text classification package designed to efficiently categorize text based on similarity metrics and learned token weights.

## Constructor

`new Classifier(classifications: string[], learningRate?: number, threshold?: number)`

Creates a new classifier instance.

- Parameters:
    - `classifications` (string[]): An array of classification labels.
    - `learningRate` (number, optional): Influences how quickly token weights adjust. Default is `1`.
    - `threshold` (number, optional): The minimum similarity score for tokens to influence classification. Default is `0.8`.

### Example:

```js
const classifier = new Classifier(["positive", "negative"], 0.5, 0.9);
```

## Methods

`classify(text: string) → string`

Determines the most probable classification for the provided `text`.

- Parameters:
    - `text` (string): The input text to be classified.
- Returns:
    - The classification label with the highest probability.

### Example:

```js
const classifier = new Classifier(["positive", "negative"]);
classifier.example("This is amazing!", "positive");
console.log(classifier.classify("Such a wonderful day!")); 
// Output: "positive"
```

`chance(text: string) → Object`

Returns an object with classification probabilities for the given `text`.

- Parameters:
    - `text` (string): The input text to analyze.
- Returns:
    - An object mapping classification labels to their probabilities.

### Example:

```js
const classifier = new Classifier(["spam", "normal"]);
classifier.example("Buy now!", "spam");
console.log(classifier.chance("Limited-time offer!"));
// Output: { spam: 0.85, normal: 0.15 }
```

`example(text: string, classification: string) → Classifier`

Trains the classifier with an example sentence and its corresponding classification.

- Parameters:
    - `text` (string): The example sentence.
    - `classification` (string): The label associated with the sentence.
- Returns:
    - The classifier instance (`this`) for method chaining.

### Example:

```js
const classifier = new Classifier(["positive", "negative"]);
classifier
  .example("This is fantastic!", "positive")
  .example("I hate this.", "negative");
```

`stable(stableLearning: StableLearning) → Classifier`

Applies a new config from a `StableLearning` instance to the instance.

- Parameters:
    - `stableLearning` (StableLearning): StableLearning instance.
- Returns:
    - The classifier instance (`this`) for method chaining.

### Example:

```js
const classifier = new Classifier(["positive", "negative"]);
const stable = new Classifier.StableLearning(classifier);
stable
  .example("This is fantastic!", "positive")
  .example("I hate this.", "negative");
classifier.stable(stable);
```

`dataset(name: string, iterations: number = 1) → Classifier`

Loads a predefined dataset and trains the classifier using its entries.

- Parameters:
    - `name` (string): The dataset name.
    - `iterations` (number, optional): Number of training iterations. Defaults to 1.
- Returns:
    - The classifier instance (`this`) for method chaining.

### Example:

```js
const classifier = new Classifier();
classifier.dataset("news", 3).classify("Breaking: new policy announced");
```

`datasets`

A static array listing available dataset names.

### Example:

```js
console.log(Classifier.datasets);
// Output: ["news", "spam", "tone", "importance"]
```

## StableLearning

`Classifier.StableLearning`

A wrapper class that maintains a reversible training dataset and reinforces classifier stability through repeated forward and reverse passes.

## Constructor:

```js
new Classifier.StableLearning(classifier: Classifier)
```

## Method:

`example(text: string, classification: string) → this`

Trains on an example while replaying all past examples (forward and reverse) to reinforce learning.

## License

MIT License