BitBullet

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

Use individual modules step by step or compose them into notebooks, batch jobs, and Python services.

Full documentation and practical tutorials are available at developer.bitbullet.co.uk.

Modules

Installation

pip install bitbullet

Optional extras keep installations lean:

pip install "bitbullet[inference-models]"   # LightGBM and XGBoost wrappers
pip install "bitbullet[inference-cluster]"  # clustering extras such as kmodes
pip install "bitbullet[forecast-statistical]"  # optional StatsForecast adapter
pip install "bitbullet[train,viz]"          # training, SHAP, and plotting tools
pip install "bitbullet[all]"                # complete SDK

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)

Manual fixed-parameter training is available when you do not want a search:

config = TrainConfig(
    name="fixed_rf",
    model_type="random_forest",
    optimizer="manual",
    model_params={"n_estimators": 300, "max_depth": 20},
)

Optuna-backed grid and random search are explicit sampler choices:

config = TrainConfig(
    name="small_grid",
    model_type="lgbm",
    optuna_sampler="grid",
    search_space={
        "num_leaves": [31, 63],
        "learning_rate": [0.05, 0.1],
    },
)

Evaluate Classification

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,
)

metadata_ready = report.to_dict()

Train And Evaluate A Regressor

from bitbullet.evaluate import evaluate_regression
from bitbullet.train import TrainConfig, OptunaTrainer

config = TrainConfig(
    name="house_price_lgbm",
    model_type="lgbm",
    task="regression",
    n_trials=30,
    optimization_metric="rmse",  # minimize by default for regression
    optuna_sampler="tpe",
)

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

y_pred = model.predict(X_test)
report = evaluate_regression(
    y_true=y_test,
    y_pred=y_pred,
    n_features=X_train.shape[1],
)

metadata_ready = report.to_dict()

Forecast Ordered And Panel Data

from sklearn.linear_model import Ridge

from bitbullet.forecast import (
    ForecastConfig,
    ForecastFeatureBuilder,
    ForecastFrame,
    ForecastSchema,
    RollingFeature,
    TabularForecaster,
)

schema = ForecastSchema(
    time="date",
    targets="sales",
    entities="store",
    future_covariates=("promotion", "temperature"),
    cadence="D",
)
history = ForecastFrame(history_df, schema)
features = ForecastFeatureBuilder(
    target_lags=(1, 7),
    rolling_features=(RollingFeature("sales", window=7, lag=1),),
    calendar_features=("day_of_week_sin", "day_of_week_cos"),
)

forecaster = TabularForecaster(
    Ridge(alpha=1.0),
    config=ForecastConfig(horizons=(1, 2, 3), strategy="direct"),
    feature_builder=features,
).fit(history)

predictions = forecaster.forecast(future_df)

ForecastBacktester adds synchronized rolling-origin evaluation, while ConformalIntervalCalibrator and HierarchicalReconciler provide optional interval and aggregation layers. See the forecasting API guide and advanced forecasting tutorial for the complete workflow.

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"],
    params={
        "gamma": "huang",
        "categorical_weights": "relevance",
        "init": "Cao",
        "n_init": 10,
    },
)

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

print(clusterer.state.fitted_params["gamma_by_column"])
print(clusterer.state.fitted_params["categorical_weights_by_column"])

Save Models 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

Support

Questions and problem reports can be sent to contact@bitbullet.ai.