BitBullet

BitBullet is a Python data-science SDK for tabular machine learning workflows. It provides composable building blocks for transformation pipelines, model training, clustering, evaluation, and reproducible artifact metadata.

The SDK is intentionally workflow-friendly without being platform-specific. You can use the pieces step by step, wire them into notebooks, or embed them in your own services.

pip install bitbullet

Optional extras keep installations lean:

pip install "bitbullet[inference-models]"   # LightGBM and XGBoost wrappers
pip install "bitbullet[inference-cluster]"  # clustering extras (kmodes, umap, hdbscan)
pip install "bitbullet[train,viz]"          # training, SHAP, and plotting tools
pip install "bitbullet[all]"                # complete SDK

---

Modules

Module	Purpose
bitbullet.transform	Fitted transformation pipelines for numerical, categorical, and datetime features.
bitbullet.train	Supervised training with Optuna-backed search, feature selection, sample weights, threshold optimisation, and reports.
bitbullet.cluster	K-Means, K-Modes, K-Prototypes, DBSCAN, GMM, gamma estimation, categorical weighting, and clustering metrics.
bitbullet.evaluate	Structured classification and regression evaluation metrics ready for reports and metadata.
bitbullet.model	Model wrappers, metadata, dataset metadata, and serialization helpers.

---

Quick Examples

Transform Data

from bitbullet.transform import TransformPipeline

pipeline = TransformPipeline(name="credit_features")
pipeline.add("numerical", "standard_scale", columns=["income", "balance"])
pipeline.add("categorical", "onehot_encode", columns=["region"])

X_transformed = pipeline.fit_transform(X_train)
X_new = pipeline.transform(X_new_raw)
pipeline.save("artifacts/transform_pipeline.joblib")

Target-aware encoders receive y directly. target_encode is leakage-aware: fit_transform(..., y=...) returns out-of-fold training encodings, while later transform(...) calls use the stored full-training smoothed mapping.

pipeline = TransformPipeline()
pipeline.add(
    "categorical",
    "target_encode",
    columns=["merchant_category"],
    params={"target_type": "classification", "cv_folds": 5, "cv_strategy": "stratified"},
)
X_encoded = pipeline.fit_transform(X_train, y=y_train)

Train a Classifier

from bitbullet.train import TrainConfig, OptunaTrainer

config = TrainConfig(
    name="default_risk_lgbm",
    model_type="lgbm",
    task="binary_classification",
    n_trials=30,
    optimization_metric="roc_auc",
    optuna_sampler="tpe",  # tpe, random, grid, cmaes
)

trainer = OptunaTrainer(config)
model = trainer.fit(X_train, y_train, X_val=X_val, y_val=y_val)

print(trainer.best_params)
print(trainer.state.optimal_threshold)

Evaluate a Model

from bitbullet.evaluate import evaluate_classification

report = evaluate_classification(
    y_true=y_test,
    y_pred_proba=model.predict_proba(X_test),
    threshold=trainer.state.optimal_threshold or 0.5,
)
print(report.to_dict())

Cluster Data

from bitbullet.cluster.core import ClusterConfig
from bitbullet.cluster.algorithms.partitional import KPrototypesClusterer

config = ClusterConfig(
    name="customer_segments",
    algorithm_type="partitional",
    method="kprototypes",
    n_clusters=5,
    numerical_columns=["income", "spend"],
    categorical_columns=["region", "channel"],
)

clusterer = KPrototypesClusterer(config)
labels = clusterer.fit_predict(df)

Save a Model with Metadata

from bitbullet.model import ModelMetadata, ModelSerializer

metadata = ModelMetadata(
    name="default_risk_lgbm",
    model_type=model.model_type,
    framework=model.framework,
    task="binary_classification",
    metrics=report.metrics,
)
metadata.add_feature_schema(X_train)

ModelSerializer.save(
    model=model,
    path="artifacts/default_risk_lgbm.pkl",
    metadata=metadata,
    train_data=(X_train, y_train),
    test_data=(X_test, y_test),
    include_datasets=False,
)

License

MIT