pkboost 2.0.2__tar.gz

pkboost-2.0.2/.gitignore

@@ -0,0 +1,69 @@
+# Rust
+/target/
+**/*.rs.bk
+*.pdb
+Cargo.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data files - exclude all datasets
+data/*.csv
+raw_data/*.csv
+*.pkl
+*.zip
+*.xlsx
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+*.so
+.pytest_cache/
+.ipynb_checkpoints/
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+
+# Build artifacts
+*.exe
+*.dll
+*.dylib
+
+# Documentation build
+/docs/_build/
+/site/
+FEATURE_LIST_PROGRESSIVE_PRECISION.md
+.gitignore
+NEXT_STEPS_COMPLETED.md
+.gitignore
+PROGRESSIVE_PRECISION_SUMMARY.md
+PROGRESSIVE_PRECISION_RESULTS.md
+three_way_comparison.csv
+THREEWAY_COMPARISON_RESULTS.md
+docs/PROGRESSIVE_PRECISION.md
+temp/val.csv
+temp/test_drift.csv
+.gitignore
+temp/train.csv
+temp/test.csv
+compare_16_drift_scenarios.py
+rust_code_with_structure.txt
+.gitignore
+all_rust_code.txt
+alb_metrics.csv
+
+all_rust_code.txt

pkboost-2.0.2/CHANGELOG_V2.0.2.md

@@ -0,0 +1,87 @@
+# PKBoost v2.0.2 Changelog
+
+## Release Date: November 2025
+
+## 🎯 Major Feature: Poisson Loss for Count Regression
+
+### New Capabilities
+- **Poisson Regression**: Full support for count-based targets (Y ∈ {0, 1, 2, ...})
+- **Log-Link Function**: Automatic exp() transformation for non-negative predictions
+- **Newton-Raphson Integration**: Seamless fit into existing optimization framework
+
+### Performance
+- **6.4% improvement** over MSE on synthetic Poisson data
+- Optimized for insurance claims, purchase counts, event frequency modeling
+
+### API
+```rust
+let mut model = PKBoostRegressor::auto(&x_train, &y_train)
+    .with_loss(RegressionLossType::Poisson);
+model.fit(&x_train, &y_train, None, true)?;
+let predictions = model.predict(&x_test)?;
+```
+
+### Files Added
+- `src/loss.rs` - Unified loss module with Poisson, MSE, Huber
+- `src/bin/test_poisson.rs` - Benchmark test for Poisson regression
+- `POISSON_LOSS.md` - Complete documentation and usage guide
+
+### Technical Details
+- Gradient: `exp(f) - y`
+- Hessian: `exp(f)`
+- Overflow prevention: Cap at 10^15
+- Hessian stability: Min 1e-6
+
+## 🔧 Improvements
+
+### Loss Module Refactoring
+- Consolidated loss functions into single module
+- Added `OptimizedShannonLoss` for backward compatibility
+- Unified gradient/hessian interface
+
+### Regression Enhancements
+- `RegressionLossType` enum now includes Poisson
+- `.with_loss()` builder method for easy loss selection
+- Automatic prediction transformation based on loss type
+
+## 📊 Benchmark Results
+
+**Synthetic Poisson Data** (5000 train, 1000 test):
+```
+True model: λ = exp(0.5 + 0.3·x₁ + 0.7·x₂)
+
+MSE Loss:     RMSE 1.653, MAE 1.202
+Poisson Loss: RMSE 1.548, MAE 1.143 (+6.4% improvement)
+```
+
+## 🐛 Bug Fixes
+- None (new feature release)
+
+## 📚 Documentation
+- Added comprehensive Poisson loss guide
+- Mathematical foundation and derivations
+- Usage examples and best practices
+- When to use Poisson vs MSE vs Huber
+
+## 🔮 Future Roadmap
+- Gamma Loss (continuous skewed data)
+- Tweedie Loss (insurance pricing)
+- Negative Binomial (overdispersed counts)
+
+## Breaking Changes
+- None (fully backward compatible)
+
+## Migration Guide
+No migration needed. Existing code continues to work. To use Poisson:
+```rust
+// Old (still works)
+let model = PKBoostRegressor::auto(&x, &y);
+
+// New (Poisson)
+let model = PKBoostRegressor::auto(&x, &y)
+    .with_loss(RegressionLossType::Poisson);
+```
+
+---
+
+**Full Changelog**: v2.0.1...v2.0.2

pkboost-2.0.2/CHANGELOG_V2.md

@@ -0,0 +1,184 @@
+# PKBoost v2.0 - Changelog
+
+## 🚀 Major Features Added
+
+### Multi-Class Classification
+- **One-vs-Rest (OvR) Strategy**: Parallel training of N binary classifiers
+- **Softmax Normalization**: Calibrated probability outputs
+- **Per-Class Auto-Tuning**: Each binary task optimized independently
+- **Real-World Validation**: 92.36% accuracy on Dry Bean dataset (7 classes)
+
+### Hierarchical Adaptive Boosting (HAB)
+- **Partition-Based Ensemble**: K-means clustering for specialized regions
+- **165x Faster Adaptation**: Selective retraining vs full model
+- **SimSIMD Integration**: SIMD-accelerated distance calculations
+- **Drift Detection**: Per-partition error monitoring with EMA
+- **Selective Metamorphosis**: Retrain only drifted partitions
+
+### Advanced Drift Features
+- **Drift Diagnostics**: Error entropy, temporal patterns, variance changes
+- **Metamorphosis Strategies**: Conservative, DataAware, FeatureAware
+- **Prediction Uncertainty**: Ensemble variance and confidence intervals
+- **2-17x Better Resilience**: vs XGBoost/LightGBM under drift
+
+## 📊 Benchmark Results
+
+### Dry Bean Dataset (Real-World, 7 Classes)
+| Model | Accuracy | Macro-F1 | Drift Resilience |
+|-------|----------|----------|------------------|
+| **PKBoost** | **92.36%** | **0.9360** | **-0.43%** degradation |
+| LightGBM | 92.36% | 0.9352 | -0.55% degradation |
+| XGBoost | 92.25% | 0.9347 | -0.91% degradation |
+
+**Key Achievement**: PKBoost wins on Macro-F1 (best minority class detection) and is 2.1x more drift-resilient than XGBoost.
+
+### Credit Card Fraud (Binary, 0.17% positive)
+| Model | PR-AUC | Drift Resilience |
+|-------|--------|------------------|
+| **PKBoost** | **0.878** | **-1.8%** degradation |
+| LightGBM | 0.793 | -42.5% degradation |
+| XGBoost | 0.745 | -31.8% degradation |
+
+**Key Achievement**: 17.7x better drift resilience than XGBoost on extreme imbalance.
+
+## 🔧 Performance Optimizations
+
+### Core Model (32-46% Speedup)
+- **Loop Unrolling**: 4x unroll in histogram building
+- **Conditional Entropy**: Skip calculation at depth > 4
+- **Smart Parallelism**: Only when n_features > 20 or n_samples > 5000
+- **Result**: Per-tree time reduced from 19.4ms to 13.2ms
+
+### HAB Architecture
+- **Parallel Specialist Training**: All classifiers train simultaneously
+- **SIMD Distance Calculations**: 18% faster with SimSIMD
+- **Batched Processing**: Memory-efficient for large datasets
+
+## 📚 Documentation
+
+### New Documents
+- **FEATURES.md**: Complete feature list (45 features)
+- **MULTICLASS.md**: Multi-class usage guide
+- **MULTICLASS_BENCHMARK_RESULTS.md**: Detailed comparison
+- **SHANNON_ANALYSIS.md**: Entropy impact analysis
+- **DRYBEAN_DRIFT_RESULTS.md**: Drift resilience study
+- **MULTICLASS_REALISTIC_RESULTS.md**: Honest assessment
+
+### Enhanced README
+- Multi-class usage examples
+- Decision guide flowchart
+- Performance benchmarks
+- Troubleshooting guide
+- API quick reference
+
+## 🐛 Bug Fixes
+- Fixed data leakage in synthetic multi-class dataset
+- Removed unused imports and dead code warnings
+- Fixed gradient explosion handling in Living Regressor
+- Improved error handling in HAB metamorphosis
+
+## 🔄 API Changes
+
+### New Classes
+```rust
+// Multi-class classification
+MultiClassPKBoost::new(n_classes)
+
+// Hierarchical Adaptive Boosting
+PartitionedClassifier::new(config)
+PartitionedClassifierBuilder::new()
+```
+
+### New Methods
+```rust
+// Batched prediction for large datasets
+model.predict_proba_batch(&x, batch_size)
+
+// Uncertainty quantification
+regressor.predict_with_uncertainty(&x)
+
+// Drift detection
+hab.observe_batch(&x, &y)  // Returns drifted partitions
+hab.metamorph_partitions(&partition_ids, &buffer_x, &buffer_y, verbose)
+```
+
+## 📈 Performance Summary
+
+| Metric | v1.0 | v2.0 | Improvement |
+|--------|------|------|-------------|
+| Multi-Class Support | ❌ | ✅ | New feature |
+| Drift Adaptation Speed | N/A | 165x faster | New feature |
+| Core Model Speed | Baseline | +32-46% | Optimized |
+| Macro-F1 (Imbalanced) | Good | **Best** | +5-7% vs competitors |
+| Drift Resilience | Good | **2-17x better** | vs XGBoost/LightGBM |
+
+## 🎯 Use Cases
+
+### Perfect For:
+- **Multi-class imbalanced problems** (fraud types, disease categories)
+- **Production systems with drift** (real-time fraud detection)
+- **Minority class critical** (medical diagnosis, anomaly detection)
+- **Zero-tuning deployment** (auto-configuration)
+
+### New Capabilities:
+- **7-class classification** with natural imbalance (Dry Bean: 26% to 3.8%)
+- **Real-time adaptation** with 165x faster retraining (HAB)
+- **Drift monitoring** with automatic detection and recovery
+- **Uncertainty quantification** for confidence-aware predictions
+
+## 🔮 Future Roadmap
+
+### Planned for v2.1:
+- [ ] SHAP-like values for interpretability
+- [ ] Kolmogorov-Smirnov test for drift detection
+- [ ] Platt scaling for probability calibration
+- [ ] Comprehensive error types (PKBoostError enum)
+- [ ] Serde support for model serialization
+
+### Under Consideration:
+- [ ] GPU acceleration for histogram building
+- [ ] Distributed training for massive datasets
+- [ ] AutoML integration for hyperparameter search
+- [ ] Python package (PyPI distribution)
+
+## 📝 Migration Guide (v1.0 → v2.0)
+
+### No Breaking Changes!
+All v1.0 code continues to work. New features are additive.
+
+### To Use New Features:
+```rust
+// Multi-class (new in v2.0)
+use pkboost::MultiClassPKBoost;
+let mut model = MultiClassPKBoost::new(n_classes);
+
+// HAB (new in v2.0)
+use pkboost::{PartitionedClassifier, PartitionConfig};
+let mut hab = PartitionedClassifier::new(PartitionConfig::default());
+
+// Batched prediction (new in v2.0)
+let probs = model.predict_proba_batch(&x_test, 1000)?;
+```
+
+## 🙏 Acknowledgments
+
+- **UCI Machine Learning Repository**: Dry Bean dataset
+- **Kaggle**: Credit Card fraud dataset
+- **SimSIMD**: SIMD-accelerated distance calculations
+- **Rayon**: Parallel processing framework
+
+## 📊 Statistics
+
+- **Total Features**: 45 (up from 30 in v1.0)
+- **Lines of Code**: ~6,500+ (up from ~5,000)
+- **Datasets Tested**: 12+ (including real-world)
+- **Benchmark Scripts**: 20+
+- **Documentation Pages**: 15+
+
+---
+
+**PKBoost v2.0**: The most comprehensive gradient boosting library for imbalanced multi-class problems under drift.
+
+**Release Date**: January 2025  
+**License**: MIT  
+**Author**: Pushp Kharat