# sklears-core

[![Crates.io](https://img.shields.io/crates/v/sklears-core.svg)](https://crates.io/crates/sklears-core)
[![Documentation](https://docs.rs/sklears-core/badge.svg)](https://docs.rs/sklears-core)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
[![Minimum Rust Version](https://img.shields.io/badge/rustc-1.70+-blue.svg)](https://www.rust-lang.org)

The foundational crate for sklears, providing core traits, types, and utilities that power the entire machine learning ecosystem. Production-ready with 100% test coverage.

> **Latest release:** `0.1.0-beta.1` (January 1, 2026). See the [workspace release notes](../../docs/releases/0.1.0-beta.1.md) for highlights and upgrade guidance.

## Overview

`sklears-core` provides the fundamental building blocks for all sklears algorithms:

- **Core Traits**: Comprehensive ML abstractions with type-safe state management
- **Advanced Type System**: Compile-time validation, phantom types, const generics
- **Performance Infrastructure**: SIMD, GPU support, memory pooling, parallel processing
- **Error Handling**: Rich error types with context propagation and recovery
- **Integration**: scikit-learn compatibility, format I/O, cross-framework support

## Status

- **Implementation**: 0.1.0-beta.1 ships with >99% of the planned v0.1 APIs implemented.
- **Validation**: Covered by the 11,292 passing workspace tests (69 skipped) executed on January 1, 2026.
- **Performance**: Pure Rust implementation with ongoing performance optimization via SIMD, threading, and cache-friendly layouts.
- **API Stability**: Breaking changes still possible before beta; stabilization roadmap tracked in the root `TODO.md`.

## Core Trait System

### Base Traits

#### `Estimator<State>`
The foundational trait for all ML models with compile-time state tracking:

```rust
pub trait Estimator<State = Untrained> {
    type Config;
    type Error: std::error::Error;
}
```

### Learning Traits

```rust
// Supervised learning
pub trait Fit<X, Y, State = Untrained> {
    type Fitted;
    fn fit(self, x: &X, y: &Y) -> Result<Self::Fitted>;
}

// Incremental/online learning
pub trait PartialFit<X, Y> {
    fn partial_fit(&mut self, x: &X, y: &Y) -> Result<()>;
}

// Unsupervised learning
pub trait FitTransform<X, Y = (), Output = X> {
    fn fit_transform(self, x: &X, y: Option<&Y>) -> Result<Output>;
}
```

### Prediction Traits

```rust
// Standard predictions
pub trait Predict<X, Output> {
    fn predict(&self, x: &X) -> Result<Output>;
}

// Probabilistic predictions
pub trait PredictProba<X, Output> {
    fn predict_proba(&self, x: &X) -> Result<Output>;
}

// Decision scores
pub trait DecisionFunction<X, Output> {
    fn decision_function(&self, x: &X) -> Result<Output>;
}
```

### Advanced Features

#### Async Trait Support
```rust
pub trait AsyncFit<X, Y> {
    async fn fit_async(self, x: &X, y: &Y) -> Result<Self::Fitted>;
}

pub trait AsyncPredict<X, Output> {
    async fn predict_async(&self, x: &X) -> Result<Output>;
}
```

#### GPU Acceleration
```rust
use sklears_core::gpu::GpuContext;

pub trait GpuAccelerated {
    fn to_gpu(self, ctx: &GpuContext) -> Result<Self::GpuVersion>;
}
```

## Type-Safe State Management

Prevent common ML errors at compile time:

```rust
use sklears_core::{Untrained, Trained};

// Model starts untrained
struct Model<State = Untrained> {
    config: Config,
    state: PhantomData<State>,
    weights_: Option<Weights>,
}

// Only untrained models can be fitted
impl Fit<X, Y> for Model<Untrained> {
    type Fitted = Model<Trained>;
    
    fn fit(self, x: &X, y: &Y) -> Result<Self::Fitted> {
        // Training logic...
        Ok(Model {
            config: self.config,
            state: PhantomData,
            weights_: Some(trained_weights),
        })
    }
}

// Only trained models can predict
impl Predict<X, Y> for Model<Trained> {
    fn predict(&self, x: &X) -> Result<Y> {
        let weights = self.weights_.as_ref().unwrap(); // Safe!
        // Prediction logic...
    }
}
```

This prevents:
- Calling `predict()` on untrained models
- Accessing parameters before fitting
- Double-fitting models
- All caught at compile time!

## Advanced Type System

### Compile-Time Validation
```rust
use sklears_core::validation::{ValidatedConfig, PositiveValidator};

#[derive(ValidatedConfig)]
struct HyperParams {
    #[validate(PositiveValidator)]
    learning_rate: f64,
    
    #[validate(RangeValidator { min: 0.0, max: 1.0 })]
    dropout: f64,
}
```

### Phantom Types for Safety
```rust
use sklears_core::phantom::{Classification, Regression};

struct Metrics<T> {
    _task: PhantomData<T>,
}

// Type-safe metric selection
impl Metrics<Classification> {
    fn accuracy(&self) -> f64 { ... }
}

impl Metrics<Regression> {
    fn mse(&self) -> f64 { ... }
}
```

## Performance Features

### SIMD Optimizations
```rust
use sklears_core::simd::SimdOps;

// Automatic SIMD acceleration
let distances = SimdOps::euclidean_distance_matrix(&points);
```

### Memory Efficiency
```rust
use sklears_core::memory::{MemoryPool, CacheOptimized};

// Memory pooling for allocations
let pool = MemoryPool::new(1_000_000);
let array = pool.allocate_array::<f64>(1000)?;

// Cache-friendly operations
let accumulator = CacheOptimizedAccumulator::new();
```

## Error Handling

Rich error types with context:

```rust
use sklears_core::{Result, SklearsError, validate};

fn train_model(x: &Array2<f64>, y: &Array1<f64>) -> Result<Model> {
    // Comprehensive validation
    validate::check_consistent_length(x, y)?;
    validate::check_finite(learning_rate, "learning_rate")?;
    validate::check_no_missing(x)?;
    
    // Error context propagation
    let model = complex_training(x, y)
        .context("Failed during gradient computation")?;
    
    Ok(model)
}
```

## Macro System

Powerful macros for boilerplate reduction:

```rust
// Quick dataset creation
let dataset = quick_dataset! {
    features: [[1.0, 2.0], [3.0, 4.0]],
    target: [0, 1],
    feature_names: ["x1", "x2"]
};

// ML-specific bounds
define_ml_float_bounds!(MLFloat: Float + NumCast + Sum);

// Automatic test generation
estimator_test_suite!(MyEstimator, {
    test_fit_predict: (X, y),
    test_persistence: true,
    test_clone: true,
});
```

## Integration & Compatibility

### scikit-learn API Compatibility
```rust
use sklears_core::sklearn_compat::SklearnEstimator;

// Drop-in replacement for sklearn models
let model = SklearnEstimator::from_sklearn(sklearn_model)?;
```

### Cross-Framework Support
```rust
// NumPy arrays
let np_array = array.to_numpy()?;

// PyTorch tensors
let tensor = array.to_torch_tensor()?;

// Polars DataFrames
let df = Dataset::from_polars(dataframe)?;
```

### Format I/O
Comprehensive format support:
- CSV, JSON, Parquet
- HDF5, NPY/NPZ
- Arrow, Feather
- ONNX, PMML, MLflow

## Builder Pattern

Consistent API across all estimators:

```rust
let model = LinearRegression::builder()
    .learning_rate(0.01)
    .max_iter(1000)
    .early_stopping(true)
    .validation_fraction(0.2)
    .n_jobs(4)
    .random_state(42)
    .build()?;
```

## Testing Infrastructure

### Property-Based Testing
```rust
use sklears_core::testing::properties;

proptest! {
    #[test]
    fn test_model_properties(
        x in array_strategy(),
        y in target_strategy()
    ) {
        properties::assert_fit_deterministic(&model, &x, &y);
        properties::assert_predict_shape(&model, &x, &y);
    }
}
```

### Mock Objects
```rust
use sklears_core::testing::MockEstimator;

let mock = MockEstimator::new()
    .expect_fit()
    .returning(|x, y| Ok(trained_model));
```

## Contributing

We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md).

## License

Licensed under the Apache License, Version 2.0.

## Citation

```bibtex
@software{sklears_core,
  title = {sklears-core: Type-Safe ML Foundation for Rust},
  author = {COOLJAPAN OU (Team KitaSan)},
  year = {2026},
  url = {https://github.com/cool-japan/sklears}
}
```