teachable-machine.js/README.md

A robust and optimized JavaScript library for integrating Google's Teachable Machine models, supporting various image sources and providing efficient classification capabilities.

# Teachable Machine.js

A robust and optimized JavaScript library for integrating Google's Teachable Machine models, supporting various image sources and providing efficient classification capabilities. This library is designed for developers who need to incorporate pre-trained Teachable Machine models into their applications with ease and high performance.

## Features

*   **TensorFlow.js Integration:** Leverages the power of TensorFlow.js for efficient model loading and inference.
*   **Multiple Image Sources:** Supports image classification from:
    *   HTTP/HTTPS URLs
    *   Base64 Data URIs
    *   Local file paths
*   **Optimized Image Processing:** Uses `sharp` for fast and efficient image decoding and resizing.
*   **Top K Class Prediction:** Easily retrieves the most probable classes with their confidence scores.
*   **Memory Management:** Includes a `dispose` method to clean up TensorFlow.js tensors and free up memory.
*   **Robust Error Handling:** Comprehensive error handling for model loading, image fetching, and processing.
*   **Bun.js Compatibility:** Designed to work seamlessly with Bun.js for high-performance JavaScript runtime environments.

## Installation

To use this library in your project, you need to install the necessary dependencies.

```bash
npm add @tensorflow/tfjs sharp got
bun add @tensorflow/tfjs sharp got
```

## Usage

### 1. Import the Library

You can import the `OptimizedTeachableMachine` class from `lib-got.js` (or `lib.js` if you prefer `node-fetch` over `got`).

```javascript
import OptimizedTeachableMachine from './lib-got.js';
// Or if you prefer node-fetch:
// import OptimizedTeachableMachine from './lib.js';
```

### 2. Load Your Teachable Machine Model

You need the URL to your Teachable Machine model. This URL typically ends with a `/` and contains `model.json` and `metadata.json` files.

```javascript
const MODEL_URL = "https://teachablemachine.withgoogle.com/models/r6BBk-hiN/";

console.log("Loading model...");
const model = await OptimizedTeachableMachine.create({ modelUrl: MODEL_URL });
console.log("Model loaded successfully!");
console.log("-----------------------------------------");
```

### 3. Classify an Image

You can classify images from various sources:

#### From a URL

```javascript
const IMAGE_URL = "https://media-blog.sashido.io/content/images/2020/09/SashiDo_Dog.jpg";

console.log("Running model...");
const predictions = await model.classify({ imageUrl: IMAGE_URL });
console.log("Classification results:");
console.log(predictions);
```

#### From a Local File Path

Make sure the file path is correct and accessible.

```javascript
const LOCAL_IMAGE_PATH = "./img.png"; // Assuming img.png is in the same directory

console.log("Running model with local image...");
const localPredictions = await model.classify({ imageUrl: LOCAL_IMAGE_PATH });
console.log("Local image classification results:");
console.log(localPredictions);
```

#### From a Base64 Data URI

```javascript
// Replace with your actual Base64 image data
const BASE64_IMAGE_DATA = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="; 

console.log("Running model with Base64 image...");
const base64Predictions = await model.classify({ imageUrl: BASE64_IMAGE_DATA });
console.log("Base64 image classification results:");
console.log(base64Predictions);
```

### 4. Dispose of the Model

It's crucial to dispose of the model and its associated tensors when you are done with it to free up memory.

```javascript
console.log("Classification is finished. Resetting model data...");
model.dispose();
console.log("Model resetted successfully!");
```

## Example (`example.js`)

A complete example demonstrating how to use the library is provided in `example.js`:

```javascript
import teachablemachine from './lib-got.js';

const MODEL_URL = "https://teachablemachine.withgoogle.com/models/r6BBk-hiN/";
const IMAGE_URL = "https://media-blog.sashido.io/content/images/2020/09/SashiDo_Dog.jpg";

console.log("Loading model...");
const model = await teachablemachine.create({ modelUrl: MODEL_URL });

console.log("Model loaded successfully!");
console.log("-----------------------------------------");

console.log("Running model...");

const predictions = await model.classify({ imageUrl: IMAGE_URL });
console.log("Classification results:");
console.log(predictions)

console.log("Classification is finished. Resetting model data...")
model.dispose();
console.log("Model resetted successfully!")
```

To run the example:

```bash
bun run example.js
```

## API Reference

### `OptimizedTeachableMachine` Class

#### `constructor(model)`

*   `model`: `tf.LayersModel` - The loaded TensorFlow.js model instance.

#### `static async create({ modelUrl })`

Asynchronously creates and initializes an `OptimizedTeachableMachine` instance.

*   `modelUrl`: `string` - The base URL where `model.json` and `metadata.json` files are located.
*   **Returns:** `Promise<OptimizedTeachableMachine>` - A promise that resolves to a new instance of `OptimizedTeachableMachine`.
*   **Throws:** `Error` - If the model URL is missing, metadata cannot be loaded, or labels are invalid.

#### `async classify({ imageUrl })`

Classifies an image from a given URL or path.

*   `imageUrl`: `string` - The URL (HTTP/HTTPS, Base64 data URI) or local file path of the image to classify.
*   **Returns:** `Promise<Array<{class: string, score: number}>>` - A promise that resolves to an array of top K classes with their scores, sorted in descending order of score. Each object in the array has:
    *   `class`: `string` - The label of the predicted class.
    *   `score`: `number` - The confidence score for the prediction.

#### `dispose()`

Disposes of the loaded TensorFlow.js model and its associated tensors from memory. This is crucial for preventing memory leaks, especially in long-running applications or when models are frequently loaded and unloaded.

## Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

## License

This project is licensed under the Apache-2.0 License. See the `LICENSE` file for details.