bitbullet 0.1.0__tar.gz

bitbullet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BitBullet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bitbullet-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: bitbullet
+Version: 0.1.0
+Summary: Composable data-science building blocks for tabular transformation, training, clustering, evaluation, and model metadata.
+Author-email: BitBullet <contact@bitbullet.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://bitbullet.ai
+Project-URL: Repository, https://gitlab.com/bitbullet/bitbullet
+Project-URL: Documentation, https://bitbullet.ai
+Project-URL: Issues, https://gitlab.com/bitbullet/bitbullet/-/issues
+Keywords: machine-learning,clustering,mlops,data-science,optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyarrow>=12.0.0
+Provides-Extra: inference-models
+Requires-Dist: xgboost>=1.7.0; extra == "inference-models"
+Requires-Dist: lightgbm>=3.3.0; extra == "inference-models"
+Provides-Extra: inference-cluster
+Requires-Dist: hdbscan>=0.8.33; extra == "inference-cluster"
+Requires-Dist: kmodes>=0.12.0; extra == "inference-cluster"
+Requires-Dist: umap-learn>=0.5.3; extra == "inference-cluster"
+Requires-Dist: prince>=0.13.0; extra == "inference-cluster"
+Provides-Extra: train
+Requires-Dist: xgboost>=1.7.0; extra == "train"
+Requires-Dist: lightgbm>=3.3.0; extra == "train"
+Requires-Dist: optuna>=3.0.0; extra == "train"
+Requires-Dist: shap>=0.42.0; extra == "train"
+Requires-Dist: tqdm>=4.65.0; extra == "train"
+Requires-Dist: psutil>=5.9.0; extra == "train"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7.0; extra == "viz"
+Requires-Dist: seaborn>=0.12.0; extra == "viz"
+Requires-Dist: plotly>=5.14.0; extra == "viz"
+Requires-Dist: ipywidgets>=8.0.0; extra == "viz"
+Requires-Dist: ipython>=8.0.0; extra == "viz"
+Provides-Extra: all
+Requires-Dist: xgboost>=1.7.0; extra == "all"
+Requires-Dist: lightgbm>=3.3.0; extra == "all"
+Requires-Dist: hdbscan>=0.8.33; extra == "all"
+Requires-Dist: kmodes>=0.12.0; extra == "all"
+Requires-Dist: umap-learn>=0.5.3; extra == "all"
+Requires-Dist: prince>=0.13.0; extra == "all"
+Requires-Dist: optuna>=3.0.0; extra == "all"
+Requires-Dist: shap>=0.42.0; extra == "all"
+Requires-Dist: tqdm>=4.65.0; extra == "all"
+Requires-Dist: psutil>=5.9.0; extra == "all"
+Requires-Dist: matplotlib>=3.7.0; extra == "all"
+Requires-Dist: seaborn>=0.12.0; extra == "all"
+Requires-Dist: plotly>=5.14.0; extra == "all"
+Requires-Dist: ipywidgets>=8.0.0; extra == "all"
+Requires-Dist: ipython>=8.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# 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.
+
+## Modules
+
+| Module | Purpose |
+| --- | --- |
+| `bitbullet.transform` | Fitted transformation pipelines for numerical, categorical, and datetime features. |
+| `bitbullet.train` | Supervised classification/regression training utilities, Optuna-backed search, feature selection, sample weights, threshold optimization, and training reports. |
+| `bitbullet.cluster` | K-Means, K-Modes, K-Prototypes, DBSCAN, GMM, gamma estimation, categorical weighting, K selection, profiling, and clustering metrics. |
+| `bitbullet.evaluate` | Structured classification, regression, and clustering evaluation numbers for reports and metadata. |
+| `bitbullet.model` | Model wrappers, model metadata, dataset metadata, and serialization helpers. |
+
+## Installation
+
+```bash
+pip install bitbullet
+```
+
+Optional extras keep installations lean:
+
+```bash
+pip install "bitbullet[inference-models]"   # LightGBM and XGBoost wrappers
+pip install "bitbullet[inference-cluster]"  # clustering extras such as kmodes
+pip install "bitbullet[train,viz]"          # training, SHAP, and plotting tools
+pip install "bitbullet[all]"                # complete SDK
+```
+
+Development install:
+
+```bash
+git clone https://gitlab.com/bitbullet/bitbullet.git
+cd bitbullet
+pip install -e ".[all,dev]"
+```
+
+## Transform Data
+
+```python
+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.
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+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()
+```
+
+## Cluster Data
+
+```python
+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
+
+```python
+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,
+)
+```
+
+## Design Boundary
+
+BitBullet SDK components do not know about hosted projects, users, queues,
+frontend pages, or product-specific container contracts. They provide the
+reusable data-science pieces: fitted state, metrics, metadata, and serializers.
+Higher-level services can compose those pieces into their own execution flows.
+
+## License
+
+MIT

bitbullet-0.1.0/README.md

@@ -0,0 +1,222 @@
+# 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.
+
+## Modules
+
+| Module | Purpose |
+| --- | --- |
+| `bitbullet.transform` | Fitted transformation pipelines for numerical, categorical, and datetime features. |
+| `bitbullet.train` | Supervised classification/regression training utilities, Optuna-backed search, feature selection, sample weights, threshold optimization, and training reports. |
+| `bitbullet.cluster` | K-Means, K-Modes, K-Prototypes, DBSCAN, GMM, gamma estimation, categorical weighting, K selection, profiling, and clustering metrics. |
+| `bitbullet.evaluate` | Structured classification, regression, and clustering evaluation numbers for reports and metadata. |
+| `bitbullet.model` | Model wrappers, model metadata, dataset metadata, and serialization helpers. |
+
+## Installation
+
+```bash
+pip install bitbullet
+```
+
+Optional extras keep installations lean:
+
+```bash
+pip install "bitbullet[inference-models]"   # LightGBM and XGBoost wrappers
+pip install "bitbullet[inference-cluster]"  # clustering extras such as kmodes
+pip install "bitbullet[train,viz]"          # training, SHAP, and plotting tools
+pip install "bitbullet[all]"                # complete SDK
+```
+
+Development install:
+
+```bash
+git clone https://gitlab.com/bitbullet/bitbullet.git
+cd bitbullet
+pip install -e ".[all,dev]"
+```
+
+## Transform Data
+
+```python
+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.
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+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()
+```
+
+## Cluster Data
+
+```python
+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
+
+```python
+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,
+)
+```
+
+## Design Boundary
+
+BitBullet SDK components do not know about hosted projects, users, queues,
+frontend pages, or product-specific container contracts. They provide the
+reusable data-science pieces: fitted state, metrics, metadata, and serializers.
+Higher-level services can compose those pieces into their own execution flows.
+
+## License
+
+MIT

bitbullet-0.1.0/bitbullet/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bitbullet-0.1.0/bitbullet/cluster/__init__.py

@@ -0,0 +1,34 @@
+"""
+BitBullet Cluster - Production-grade clustering engine for mixed data types.
+
+This package provides a comprehensive clustering solution with:
+- Support for mixed numerical and categorical data
+- Multiple clustering algorithms (K-Modes, K-Prototypes, K-Means, DBSCAN, GMM)
+- Data-driven feature weighting
+- Memory-efficient distance computation
+- Production-ready serialization
+- Comprehensive evaluation metrics
+- Beautiful visualizations
+"""
+
+from bitbullet.cluster.core.base import BaseClusterer, ClusterConfig, ClusterState
+from bitbullet.cluster.weights.categorical_weights import CategoricalWeights
+from bitbullet.cluster.weights.gamma_estimation import GammaEstimator
+from bitbullet.cluster.utils.sample_size import (
+    SampleSizeEstimator,
+    SampleSizeEstimate,
+    estimate_sample_size,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseClusterer",
+    "ClusterConfig",
+    "ClusterState",
+    "CategoricalWeights",
+    "GammaEstimator",
+    "SampleSizeEstimator",
+    "SampleSizeEstimate",
+    "estimate_sample_size",
+]