```markdown
# PKBoost Python Package

The official Python wrapper for PKBoost, providing seamless integration with Python's machine learning ecosystem.

## Installation

```bash
pip install pkboost
```

## Quick Start

```python
import pkboost
import pandas as pd
from sklearn.model_selection import train_test_split
from sklearn.metrics import precision_recall_curve, auc

# Load your data
data = pd.read_csv('your_data.csv')
X = data.drop('target', axis=1)
y = data['target']

# Split the data
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, stratify=y)

# Create and train PKBoost classifier
model = pkboost.PKBoostClassifier()
model.fit(X_train, y_train)

# Make predictions
y_pred_proba = model.predict_proba(X_test)[:, 1]

# Evaluate
precision, recall, _ = precision_recall_curve(y_test, y_pred_proba)
pr_auc = auc(recall, precision)
print(f"PR-AUC: {pr_auc:.4f}")
```

## PKBoostClassifier

The main classifier class with the following parameters:

```python
PKBoostClassifier(
    n_estimators=100,
    learning_rate=0.1,
    max_depth=6,
    min_samples_split=2,
    min_samples_leaf=1,
    subsample=1.0,
    colsample_bytree=1.0,
    reg_lambda=1.0,
    reg_alpha=0.0,
    random_state=None,
    n_jobs=-1,
    verbose=0
)
```

### Key Features

- **Automatic Hyperparameter Tuning**: Use `auto_tune=True` for automatic configuration
- **Early Stopping**: Monitor validation performance with `eval_set`
- **Feature Importance**: Access via `feature_importances_` attribute
- **Handles Imbalance**: Built-in class weighting for imbalanced datasets

## Advanced Usage

### With Early Stopping

```python
from sklearn.model_selection import train_test_split

# Split into train, validation, test
X_train, X_temp, y_train, y_temp = train_test_split(X, y, test_size=0.3, stratify=y)
X_val, X_test, y_val, y_test = train_test_split(X_temp, y_temp, test_size=0.5, stratify=y_temp)

model = pkboost.PKBoostClassifier(
    n_estimators=1000,  # Set high, early stopping will determine actual number
    early_stopping_rounds=50,
    verbose=10
)

model.fit(
    X_train, y_train,
    eval_set=[(X_val, y_val)],
    verbose=True
)
```

### Automatic Hyperparameter Tuning

```python
model = pkboost.PKBoostClassifier(auto_tune=True)
model.fit(X_train, y_train)
```

### Cross-Validation

```python
from sklearn.model_selection import cross_val_score

model = pkboost.PKBoostClassifier()
scores = cross_val_score(model, X, y, cv=5, scoring='average_precision')
print(f"Mean PR-AUC: {scores.mean():.4f} (+/- {scores.std() * 2:.4f})")
```

## PKBoostAdaptive

For streaming data and concept drift scenarios:

```python
from pkboost import PKBoostAdaptive

# Initialize adaptive model
adaptive_model = PKBoostAdaptive(
    drift_detection_sensitivity=0.01,
    adaptation_rate=0.1,
    max_retraining_interval=1000
)

# For streaming data
for batch_X, batch_y in data_stream:
    adaptive_model.partial_fit(batch_X, batch_y)
    
    # Check if drift detected
    if adaptive_model.drift_detected:
        print("Concept drift detected! Model is adapting...")
    
    # Get current predictions
    predictions = adaptive_model.predict_proba(batch_X)
```

## Handling Large Datasets

### Batch Training

```python
model = pkboost.PKBoostClassifier()

# Train in batches
batch_size = 1000
for i in range(0, len(X_train), batch_size):
    X_batch = X_train[i:i+batch_size]
    y_batch = y_train[i:i+batch_size]
    model.partial_fit(X_batch, y_batch)
```

### Memory-Efficient Data Types

```python
# Use memory-efficient data types
X = X.astype('float32')
model.fit(X_train, y_train)
```

## Integration with Scikit-Learn

### Pipeline Integration

```python
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.impute import SimpleImputer

pipeline = Pipeline([
    ('imputer', SimpleImputer(strategy='median')),
    ('scaler', StandardScaler()),
    ('classifier', pkboost.PKBoostClassifier())
])

pipeline.fit(X_train, y_train)
```

### Grid Search

```python
from sklearn.model_selection import GridSearchCV

param_grid = {
    'n_estimators': [100, 200, 500],
    'learning_rate': [0.01, 0.1, 0.2],
    'max_depth': [3, 6, 9]
}

grid_search = GridSearchCV(
    pkboost.PKBoostClassifier(),
    param_grid,
    cv=5,
    scoring='average_precision',
    n_jobs=-1
)

grid_search.fit(X_train, y_train)
print(f"Best parameters: {grid_search.best_params_}")
```

## Model Persistence

### Save and Load Models

```python
import joblib

# Save model
joblib.dump(model, 'pkboost_model.pkl')

# Load model
loaded_model = joblib.load('pkboost_model.pkl')
```

### Native PKBoost Serialization

```python
# Save model in native format
model.save_model('model.pkboost')

# Load native model
loaded_model = pkboost.PKBoostClassifier()
loaded_model.load_model('model.pkboost')
```

## Performance Tips

1. **Data Preprocessing**: Ensure numerical features are scaled and categorical features are encoded
2. **Early Stopping**: Always use early stopping to prevent overfitting
3. **Subsampling**: For large datasets, use `subsample < 1.0` for faster training
4. **Parallelism**: Set `n_jobs=-1` to use all available cores
5. **Memory**: Use `float32` data types for large datasets

## Troubleshooting

### Common Issues

**Memory Errors**: Reduce `n_estimators` or use smaller `subsample` value
**Slow Training**: Try reducing `max_depth` or increasing `learning_rate`
**Poor Performance**: Enable `auto_tune=True` or adjust class weights

### Debug Mode

```python
model = pkboost.PKBoostClassifier(verbose=10)
model.fit(X_train, y_train)
```

## API Reference

### Methods

- `fit(X, y, eval_set=None, verbose=False)`: Train the model
- `predict(X)`: Predict class labels
- `predict_proba(X)`: Predict class probabilities
- `score(X, y)`: Return accuracy score
- `get_feature_importances()`: Return feature importance scores

### Attributes

- `feature_importances_`: Array of feature importances
- `n_estimators_`: Number of estimators actually used
- `classes_`: Class labels
- `best_score_`: Best validation score during training

## Examples

See the `examples/` directory for complete working examples:

- `example_creditcard.py`: Credit card fraud detection
- `example_drift.py`: Concept drift handling
- `example_pipeline.py`: Full ML pipeline
- `example_hyperparameter_tuning.py`: Advanced tuning techniques

## Support

For issues and questions:
- GitHub Issues: [PKBoost Repository](https://github.com/Pushp-Kharat1/PkBoost)
- Documentation: [PKBoost Docs](https://pushp-kharat1.github.io/PkBoost/)

## Citation

If you use PKBoost in your research, please cite:

```bibtex
@software{pkboost2025,
  title={PKBoost: Adaptive Gradient Boosting for Concept Drift},
  author={Kharat, Pushp},
  year={2025},
  url={https://github.com/Pushp-Kharat1/PkBoost}
}
```
```