Getting Started

Installation

Bukka is available on PyPI and can be installed with pip:

pip install bukka

Requirements:

  • Python >= 3.10

  • PyYAML >= 6.0

  • narwhals >= 1.0.0

  • numpy >= 2.0.0

Creating Your First Project

The quickest way to start is with the run command:

python -m bukka run --name my_project --dataset data.csv --target target_column

This creates the standard project scaffold:

  • A project folder with the Bukka layout.

  • A virtual environment unless you pass --skip-venv.

  • A copied dataset and train/test splits.

  • Starter files for configuration, data loading, and notebooks.

  • Optional extras such as MLflow, dummy, or TPOT files.

Example: Binary Classification

Predicting Titanic survival looks like this:

import subprocess
import tempfile
import os

# Create a sample CSV file
with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
    f.write('PassengerId,Survived,Pclass,Name,Sex,Age\\n')
    f.write('1,0,3,Mr. Owen Harris,male,22\\n')
    f.write('2,1,1,Mrs. John Bradley,female,38\\n')
    f.write('3,1,3,Miss. Laina,female,26\\n')
    csv_file = f.name

# The command would be:
# python -m bukka run --name titanic --dataset titanic.csv --target Survived

Example: Regression Project

Predicting a numeric target such as house price:

import tempfile

# Create a sample housing dataset
with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
    f.write('sqft,bedrooms,bathrooms,price\\n')
    f.write('1500,3,2,300000\\n')
    f.write('2000,4,3,450000\\n')
    f.write('1200,2,1,250000\\n')
    csv_file = f.name

# The command would be:
# python -m bukka run --name housing --dataset housing.csv --target price --problem-type regression

Using the Project Class

You can also use Bukka programmatically if you need to script the setup step:

from bukka.project import Project

# Create a project instance
proj = Project(
    name="my_ml_project",
    dataset_path=None,  # Can be added later
    backend="polars",
    problem_type="auto"
)

# Verify project properties
assert proj.name == "my_ml_project"
assert proj.backend == "polars"
assert proj.problem_type == "auto"
print("Project created successfully")

Project created successfully

Project Structure

When you create a project, Bukka generates this structure:

my_project/
├── .venv/                      # Virtual environment
├── data/                       # Data storage
│   ├── <dataset>               # Original dataset
│   ├── test/                   # Test split
│   └── train/                  # Training split
├── pipelines/                  # ML Pipelines
│   ├── __init__.py
│   ├── baseline/               # Baseline models
│   ├── candidate/              # Custom pipelines
│   └── generated/              # Auto-generated pipelines
├── notebooks/                  # Jupyter notebooks
│   └── starter_notebook.ipynb
├── utils/                      # Utilities
├── pyproject.toml
└── requirements.txt

Next Steps