catboost-rust 0.4.0

# CatBoost Rust Bindings

Rust bindings for [CatBoost](https://catboost.ai/), a gradient boosting library for machine learning. This crate provides a safe and ergonomic Rust interface to CatBoost's C API.

## Features

- **Cross-platform**: Works on Linux, macOS, and Windows
- **Self-contained**: Downloads CatBoost binaries at runtime - no system dependencies required
- **Version control**: Specify different CatBoost versions via environment variable
- **Safe Rust API**: Memory-safe wrapper around CatBoost's C API
- **Multiple feature types**: Support for numeric, categorical, text, and embedding features
- **GPU support**: Optional GPU acceleration (requires `gpu` feature)

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
catboost-rust = "0.2.0"
```

For GPU support:

```toml
[dependencies]
catboost-rust = { version = "0.2.0", features = ["gpu"] }
```

## Quick Start

```rust
use catboost_rust::{Model, ObjectsOrderFeatures};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load a trained CatBoost model
    let model = Model::load("path/to/model.cbm")?;
    
    // Make predictions with numeric features
    let features = ObjectsOrderFeatures::new()
        .with_float_features(&[
            &[1.0, 2.0, 3.0, 4.0, 5.0],
            &[2.0, 3.0, 4.0, 5.0, 6.0],
        ]);
    
    let predictions = model.predict(features)?;
    println!("Predictions: {:?}", predictions);
    
    Ok(())
}
```

## Usage Examples

### Basic Usage

```rust
use catboost_rust::{Model, ObjectsOrderFeatures};

// Load model from file
let model = Model::load("model.cbm")?;

// Simple numeric features prediction
let features = ObjectsOrderFeatures::new()
    .with_float_features(&[&[1.0, 2.0, 3.0, 4.0, 5.0]]);

let predictions = model.predict(features)?;
```

### Categorical Features

```rust
use catboost_rust::{Model, ObjectsOrderFeatures};

let model = Model::load("model.cbm")?;

// Mixed numeric and categorical features
let features = ObjectsOrderFeatures::new()
    .with_float_features(&[&[1.0, 2.0, 3.0]])
    .with_cat_features(&[&["A", "B", "C"]]);

let predictions = model.predict(features)?;
```

### Text Features

```rust
use catboost_rust::{Model, ObjectsOrderFeatures};
use std::ffi::CString;

let model = Model::load("model.cbm")?;

let text_features = vec![
    CString::new("This is a sample text").unwrap(),
    CString::new("Another text sample").unwrap(),
];

let features = ObjectsOrderFeatures::new()
    .with_float_features(&[&[1.0, 2.0]])
    .with_text_features(&[&text_features]);

let predictions = model.predict(features)?;
```

### Embedding Features

```rust
use catboost_rust::{Model, ObjectsOrderFeatures};

let model = Model::load("model.cbm")?;

let embeddings = vec![
    vec![0.1, 0.2, 0.3, 0.4], // First embedding
    vec![0.5, 0.6, 0.7, 0.8], // Second embedding
];

let features = ObjectsOrderFeatures::new()
    .with_float_features(&[&[1.0, 2.0]])
    .with_embedding_features(&[&embeddings]);

let predictions = model.predict(features)?;
```

### Zero-Copy Buffer Loading (Recommended)

`Model::load_buffer_zero_copy` is the recommended way to load models from memory. Unlike `load_buffer`, it avoids copying the model data, resulting in lower memory usage, faster loading, and no internal memory pool leaks. Requires CatBoost v1.2.9+ (the default).

```rust
use catboost_rust::Model;
use std::fs;

let buffer = fs::read("model.cbm")?;
let model = Model::load_buffer_zero_copy(buffer)?;
```

The buffer is owned by the `Model` and freed automatically when it is dropped.

## Configuration

### CatBoost Version

You can specify which version of CatBoost to use by setting the `CATBOOST_VERSION` environment variable:

```bash
export CATBOOST_VERSION=1.2.8
cargo build
```

The default version is `1.2.8`.

### GPU Support

To enable GPU acceleration, compile with the `gpu` feature:

```bash
cargo build --features gpu
```

Then enable GPU evaluation in your code:

```rust
let model = Model::load("model.cbm")?;
model.enable_gpu_evaluation()?;
```

## Model Information

You can inspect model properties:

```rust
let model = Model::load("model.cbm")?;

println!("Float features: {}", model.get_float_features_count());
println!("Categorical features: {}", model.get_cat_features_count());
println!("Text features: {}", model.get_text_features_count());
println!("Embedding features: {}", model.get_embedding_features_count());
println!("Trees: {}", model.get_tree_count());
println!("Dimensions: {}", model.get_dimensions_count());
```

## Error Handling

The crate provides comprehensive error handling:

```rust
use catboost_rust::{Model, CatBoostError, CatBoostResult};

fn load_and_predict() -> CatBoostResult<Vec<f64>> {
    let model = Model::load("model.cbm")?;
    
    let features = ObjectsOrderFeatures::new()
        .with_float_features(&[&[1.0, 2.0, 3.0]]);
    
    model.predict(features)
}

match load_and_predict() {
    Ok(predictions) => println!("Success: {:?}", predictions),
    Err(CatBoostError { description }) => println!("Error: {}", description),
}
```

## Platform Support

This crate automatically downloads the appropriate CatBoost binary for your platform:

- **Linux**: x86_64, aarch64
- **macOS**: Universal binary (x86_64 + arm64)
- **Windows**: x86_64

## Building from Source

The crate downloads CatBoost binaries at runtime, so no system dependencies are required. However, if you want to build from source, you can set the `CATBOOST_BUILD_FROM_SOURCE` environment variable.

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Examples

See the `examples/` directory for more detailed usage examples:

- `basic_usage.rs` - Simple prediction examples
- `advanced_usage.rs` - Advanced features and model inspection

Run examples with:

```bash
cargo run --example basic_usage
cargo run --example advanced_usage
```