API Reference

This section is for advanced users who want to extend Bukka or inspect the code behind the CLI.

Most users should stay on the CLI pages. The modules below are the implementation details.

Core modules

Project module

class bukka.project.Project(name, dataset_path=None, target_column=None, skip_venv=False, enable_mlflow=False, mlflow_tracking_uri=None, backend='polars', problem_type='auto', train_size=0.8, stratify=True, strata=None, dummy=False, tpot=False)

Bases: object

Represents a data science or ML project, managing its file structure and environment setup.

This class orchestrates project creation, environment setup, and pipeline generation for machine learning projects.

Parameters:

• name (str) – The name of the project (used as the project path).

• dataset_path (str | None) – The path to the original dataset file (optional).

• target_column (str | None) – The name of the target column in the dataset (optional).

• skip_venv (bool, optional) – Whether to skip virtual environment creation. Defaults to False.

• enable_mlflow (bool, optional) – Whether to enable MLflow experiment tracking. Defaults to False.

• mlflow_tracking_uri (str | None, optional) – MLflow tracking URI (optional). Defaults to file-based tracking in mlruns/.

• backend (str, optional) – Dataframe backend to use via Narwhals (e.g., ‘polars’, ‘pyarrow’, ‘modin’, ‘cudf’, ‘dask’). Defaults to ‘polars’.

• problem_type (str, optional) – ML problem type specification. Defaults to ‘auto’.

• train_size (float, optional) – Proportion of data for training split. Defaults to 0.8.

• stratify (bool, optional) – Whether to stratify the train/test split. Defaults to True.

• strata (list[str] | None, optional) – Column(s) to use for stratification. Defaults to None.

• dummy (bool)

• tpot (bool)

Examples

>>> proj = Project(
...     name="my_project",
...     dataset_path="data.csv",
...     target_column="target",
...     backend="pyarrow",
...     problem_type="binary_classification"
... )
>>> proj.run()

>>> # With MLflow enabled
>>> proj = Project(
...     name="tracked_project",
...     dataset_path="data.csv",
...     target_column="target",
...     enable_mlflow=True
... )
>>> proj.run()

__init__(name, dataset_path=None, target_column=None, skip_venv=False, enable_mlflow=False, mlflow_tracking_uri=None, backend='polars', problem_type='auto', train_size=0.8, stratify=True, strata=None, dummy=False, tpot=False)

Initialize a Project instance.

Parameters:

• name (str) – The name of the project (used as the project path).

• dataset_path (str | None) – The path to the original dataset file (optional).

• target_column (str | None) – The name of the target column (optional).

• skip_venv (bool) – Whether to skip virtual environment creation.

• enable_mlflow (bool) – Whether to enable MLflow experiment tracking.

• mlflow_tracking_uri (str | None) – MLflow tracking URI (optional).

• backend (str) – Dataframe backend to use (default: ‘polars’).

• problem_type (str) – ML problem type (default: ‘auto’).

• train_size (float) – Train/test split ratio (default: 0.8).

• stratify (bool) – Whether to stratify the split (default: True).

• strata (list[str] | None) – Column(s) for stratification (default: None).

• dummy (bool) – Whether to add a dummy model (default: False).

• tpot (bool) – Whether to add a TPOT model (default: False).

Return type:

None

run()

Run the project setup: build the file skeleton and set up the environment.

Return type:

None

Data management

Dataset Module

class bukka.data_management.dataset.Dataset(target_column, file_manager, strata=None, stratify=True, train_size=0.8, feature_columns=None, backend='polars')

Bases: object

Dataset class for managing and splitting datasets for expert systems.

This class loads, splits, and manages datasets using Narwhals for dataframe abstraction. It writes train/test splits as Parquet files and exposes schema and feature metadata.

Parameters:

• target_column (str) – The name of the target column in the dataset.

• file_manager (file_manager.FileManager) – An instance of FileManager to handle file paths and dataset storage.

• strata (list[str] | str | None, optional) – Column(s) to use for stratified splitting. Defaults to None.

• stratify (bool, optional) – Whether to stratify the split. Defaults to True.

• train_size (float, optional) – Proportion of the dataset to include in the train split. Defaults to 0.8.

• feature_columns (list[str] | None, optional) – List of feature column names. If None, all columns except the target are used. Defaults to None.

• backend (str)

file_manager

File manager instance for data paths.

Type:

file_manager.FileManager

target_column

Name of the target column.

Type:

str

feature_columns

List of feature column names.

Type:

list[str]

data_schema

Schema of the training data (column names mapped to PyArrow data types).

Type:

dict[str, pyarrow.DataType]

train_df

Training data split.

Type:

Narwhals DataFrame

test_df

Test data split.

Type:

Narwhals DataFrame

Examples

>>> from bukka.utils.files.file_manager import FileManager
>>> from pathlib import Path
>>> fm = FileManager(project_name='my_project', dataset_path=Path('data.csv'))
>>> dataset = Dataset(
...     target_column='label',
...     file_manager=fm,
...     train_size=0.7,
...     stratify=True
... )
>>> print(dataset.feature_columns)
['feat1', 'feat2', 'feat3']
>>> print(dataset.data_schema)
{'feat1': int64, 'feat2': double, 'label': int64}

identify_multicollinearity_train(columns=None, threshold=0.8)

Identify multicollinear features in the training dataset.

Computes pairwise correlations between numerical columns and returns pairs with absolute correlation above the specified threshold.

Parameters:

• columns (list[str], optional) – List of column names to check for multicollinearity. If None, uses all feature columns. Defaults to None.

• threshold (float, optional) – Correlation threshold above which column pairs are considered multicollinear. Defaults to 0.8.

Returns:

List of tuples with correlated column pairs and their correlation coefficient. Each tuple is (col1, col2, correlation).

Return type:

list[tuple[str, str, float]]

Examples

>>> dataset = Dataset(
...     target_column='label',
...     file_manager=fm
... )
>>> pairs = dataset.identify_multicollinearity_train(['feat1', 'feat2', 'feat3'])
>>> print(pairs)
[('feat1', 'feat2', 0.95), ('feat2', 'feat3', 0.87)]

>>> # Use default feature columns and custom threshold
>>> pairs = dataset.identify_multicollinearity_train(threshold=0.9)

get_varied_scale_train(column_name)

Calculate the range of a column in the training dataset.

Computes the range (maximum value minus minimum value) for a numerical column to assess scale variation.

Parameters:

column_name (str) – Name of the column to analyze. Must be a numerical column.

Returns:

The range of the column (max - min).

Return type:

float

Examples

>>> dataset = Dataset(
...     target_column='label',
...     file_manager=fm
... )
>>> scale = dataset.get_varied_scale_train('price')
>>> print(scale)
950.75

>>> # Check scale for multiple columns
>>> for col in ['price', 'quantity', 'weight']:
...     scale = dataset.get_varied_scale_train(col)
...     print(f"{col}: {scale}")

check_varied_scale_train(column_name, threshold)

Check if a column has varied scale in the training dataset.

Determines whether a numerical column’s range exceeds a specified threshold, indicating that scaling might be beneficial.

Parameters:

• column_name (str) – Name of the column to check. Must be a numerical column.

• threshold (float) – The threshold value for determining varied scale. If the column’s range (max - min) exceeds this value, returns True.

Returns:

True if the column’s range exceeds the threshold, False otherwise.

Return type:

bool

Examples

>>> dataset = Dataset(
...     target_column='label',
...     file_manager=fm
... )
>>> has_varied = dataset.check_varied_scale_train('price', 100)
>>> print(has_varied)
True

>>> # Check multiple columns for scaling needs
>>> for col in ['price', 'age', 'quantity']:
...     needs_scaling = dataset.check_varied_scale_train(col, threshold=100)
...     if needs_scaling:
...         print(f"{col} needs scaling")

get_column_null_count(column)

Get the count of null values in a column from the training dataset.

Parameters:

column (str) – Name of the column to check.

Returns:

The count of null values in the column.

Return type:

int

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> null_count = dataset.get_column_null_count('age')
>>> print(null_count)
5

type_of_column(column)

Get the simplified data type of a column from the training dataset.

Parameters:

column (str) – Name of the column to check.

Returns:

The simplified data type: ‘int’, ‘float’, ‘string’, or backend-specific type name.

Return type:

str

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> dtype = dataset.type_of_column('age')
>>> print(dtype)
'int'

has_outliers(column, z_threshold=3)

Check if a column has outliers in the training dataset.

Parameters:

• column (str) – Name of the column to check.

• z_threshold (float, optional) – Number of standard deviations from mean to consider as outlier. Defaults to 3.

Returns:

True if outliers are detected, False otherwise.

Return type:

bool

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> has_outliers = dataset.has_outliers('price')
>>> print(has_outliers)
True

get_unq_count(column)

Get the count of unique values in a column from the training dataset.

Parameters:

column (str) – Name of the column to analyze.

Returns:

The number of unique values in the column.

Return type:

int

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> unique_count = dataset.get_unq_count('category')
>>> print(unique_count)
5

has_inconsistent_categorical_data(column, threshold=0.1)

Check if a categorical column has inconsistent data in the training dataset.

Parameters:

• column (str) – Name of the column to check.

• threshold (float, optional) – Threshold for unique value ratio. Defaults to 0.1.

Returns:

True if inconsistent categorical data is detected, False otherwise.

Return type:

bool

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> is_inconsistent = dataset.has_inconsistent_categorical_data('category')
>>> print(is_inconsistent)
True

has_multicollinearity(columns=None, threshold=0.8)

Check if the training dataset has multicollinearity among columns.

Parameters:

• columns (list[str], optional) – List of column names to check. If None, uses feature_columns.

• threshold (float, optional) – Correlation threshold for detecting multicollinearity. Defaults to 0.8.

Returns:

True if any pair of columns has correlation above threshold.

Return type:

bool

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> has_multi = dataset.has_multicollinearity()
>>> print(has_multi)
True

is_text_column(column, min_avg_length=50)

Check if a column contains text data suitable for NLP tasks.

Parameters:

• column (str) – Name of the column to check.

• min_avg_length (int, optional) – Minimum average string length to be considered text. Defaults to 50.

Returns:

True if the column appears to contain text data, False otherwise.

Return type:

bool

Examples

>>> dataset = Dataset(target_column='label', file_manager=fm)
>>> is_text = dataset.is_text_column('description')
>>> print(is_text)
True

Coding utilities

Configuration writer

class bukka.coding.write_config.ConfigWriter(output_path, backend_name, file_manager, enable_mlflow=False, mlflow_tracking_uri=None)

Bases: object

Generates and writes a configuration file for a Bukka project.

This class constructs a Python source file containing configuration settings for the Bukka project, such as the DataFrame backend to use and optional MLflow configuration.

Parameters:

• output_path (str) – The file path where the configuration file will be written.

• backend_name (str) – The name of the DataFrame backend to use with Narwhals (e.g., ‘pyarrow’, ‘modin’, ‘cudf’, ‘dask’).

• file_manager (FileManager) – Manager for project file paths and directory structure.

• enable_mlflow (bool, optional) – Whether to include MLflow configuration (default: False).

• mlflow_tracking_uri (str | None, optional) – MLflow tracking URI. If None and enable_mlflow is True, defaults to mlruns directory (default: None).

Examples

>>> writer = ConfigWriter(output_path="config.py", backend_name="pyarrow", file_manager=fm)
>>> writer.write_config()  # Writes the config file with pyarrow backend

write_config()

Write the configuration file to the configured output path.

Generates Python source code from the template and writes it to the specified file. Conditionally includes MLflow configuration.

Examples

>>> writer = ConfigWriter(output_path="config.py", backend_name="pyarrow", file_manager=fm)
>>> writer.write_config()  # Writes the config file with pyarrow backend

Return type:

None

Starter notebook writer

class bukka.coding.write_starter_notebook.StarterNotebookWriter(output_path, venv_path=None, target_column=None, problem_type='auto', enable_mlflow=False)

Bases: object

Generates and writes a starter Jupyter notebook for a Bukka project.

This class constructs a Python source file containing a Jupyter notebook with pre-defined cells to help users get started with their Bukka project.

Parameters:

• output_path (str) – The file path where the notebook will be written.

• venv_path (str | Path | None, optional) – The path to the virtual environment. If provided, the notebook will be configured to use the Python interpreter from this environment.

• target_column (str | None, optional) – The name of the target column for supervised learning tasks. If None, generates notebook code for unsupervised learning.

• problem_type (str, optional) – The type of ML problem (‘regression’, ‘classification’, ‘auto’, etc.). Defaults to ‘auto’.

• enable_mlflow (bool, optional) – Whether to include MLflow experiment tracking examples. Defaults to False.

Examples

>>> writer = StarterNotebookWriter(output_path="starter_notebook.ipynb")
>>> writer.write_notebook()  # Writes the starter notebook to file
>>>
>>> # With virtual environment and supervised learning
>>> writer = StarterNotebookWriter(
...     output_path="starter_notebook.ipynb",
...     venv_path=".venv",
...     target_column="target",
...     problem_type="regression",
...     enable_mlflow=True
... )
>>> writer.write_notebook()  # Writes notebook configured for the venv

write_notebook()

Write the starter Jupyter notebook to the configured output path.

Return type:

None

Pipeline writer

class bukka.coding.write_pipeline.PipelineWriter(pipeline_steps, output_path)

Bases: TemplateBaseClass

Build a pipeline plan from identified problems and chosen solutions.

The writer takes pipeline steps and generates a complete sklearn Pipeline with appropriate imports, instantiations, ColumnTransformer (if needed), and final Pipeline definition.

Parameters:

• pipeline_steps (list[tuple[Any, Any]]) – List of tuples where each tuple contains (solution_object, problem_object). Solution objects must have fetch_import(), fetch_instantiation(), and name attributes. Problem objects must have problem_type and features attributes.

• output_path (str | Path) – The file path where the generated pipeline code will be written.

pipeline_steps

The pipeline steps to be processed.

Type:

list[tuple[Any, Any]]

imports

Set of import statements extracted from solutions.

Type:

set[str]

instantiations

Dictionary mapping variable names to instantiation code.

Type:

dict[str, str]

pipeline_definition

The complete generated pipeline code.

Type:

str

Examples

>>> from bukka.expert_system.solution import Solution
>>> from bukka.expert_system.problems import Problem
>>> from pathlib import Path
>>>
>>> # Create a transformer solution
>>> scaler = Solution(
...     name="scaler",
...     function_import="from sklearn.preprocessing import StandardScaler",
...     function_name="StandardScaler",
...     function_kwargs={}
... )
>>>
>>> # Create a problem for the transformer
>>> scaling_problem = Problem(
...     problem_name="Scaling",
...     description="Features need scaling",
...     features=["age", "income"],
...     solutions=[scaler],
...     problem_type="transformer"
... )
>>>
>>> # Create pipeline steps
>>> pipeline_steps = [(scaler, scaling_problem)]
>>>
>>> # Write the pipeline
>>> writer = PipelineWriter(
...     pipeline_steps=pipeline_steps,
...     output_path=Path("my_pipeline.py")
... )
>>> writer.write_code()  # Generates and writes the pipeline code

Notes

This class avoids strong typing on solution objects because the project’s Solution wrappers vary; it performs several runtime checks to extract import strings, instantiation text and step names.

__init__(pipeline_steps, output_path)

Create a PipelineWriter.

Parameters:

• pipeline_steps (list[tuple[Any, Any]]) – List of (solution_object, problem_object) tuples to include in the pipeline.

• output_path (str | Path) – The file path where the generated pipeline code will be written.

Return type:

None

Examples

>>> from pathlib import Path
>>> writer = PipelineWriter(
...     pipeline_steps=[],
...     output_path=Path("empty_pipeline.py")
... )

PyProject TOML writer

class bukka.coding.write_pyproject_toml.PyprojectTomlWriter(file_manager, project_name='bukka_project')

Bases: TemplateBaseClass

Writes a pyproject.toml file to make Bukka-generated projects pip-installable.

This class extends TemplateBaseClass to generate a pyproject.toml file with package metadata, dependencies, and build configuration. The generated file enables users to run ‘pip install -e .’ in the project directory.

Parameters:

• file_manager (FileManager) – The FileManager instance containing all project paths.

• project_name (str, optional) – The name of the project. Default is “bukka_project”.

• target_column (str, optional) – The name of the target column for ML tasks. Default is “target”.

Examples

>>> from bukka.logistics.files.file_manager import FileManager
>>> from pathlib import Path
>>> file_manager = FileManager(
...     project_path=Path("my_project"),
...     orig_dataset=Path("data.csv")
... )
>>> writer = PyprojectTomlWriter(
...     file_manager=file_manager,
...     project_name="my_ml_project",
...     target_column="label"
... )
>>> writer.write_class()  # Writes pyproject.toml to project root

>>> # Custom configuration
>>> writer = PyprojectTomlWriter(
...     file_manager=file_manager,
...     project_name="classification_project",
...     target_column="churn"
... )
>>> writer.write_class()

__init__(file_manager, project_name='bukka_project')

Initialize the PyprojectTomlWriter with file manager and configuration.

Parameters:

• file_manager (FileManager) – The FileManager instance containing all project paths.

• project_name (str, optional) – The name of the project. Default is “bukka_project”.

Return type:

None

Examples

>>> file_manager = FileManager(Path("project"), Path("data.csv"))
>>> writer = PyprojectTomlWriter(file_manager, project_name="demo")

Data reader writer

class bukka.coding.write_data_reader_class.DataReaderWriter(file_manager, target_column=None)

Bases: object

Generates and writes a DataReader class for loading train/test parquet files.

This class constructs a Python source file containing a DataReader class with pre-configured file paths for training and testing datasets.

Parameters:

• file_handler (FileHandler) – Handler providing paths to data files and the target output location.

• file_manager (FileManager)

• target_column (str | None)

Examples

>>> from bukka.logistics.files.file_manager import FileHandler
>>> file_handler = FileHandler(project_name="my_project")
>>> writer = DataReaderWriter(file_handler)
>>> writer.write_class()  # Writes DataReader class to file

write_code()

Write the DataReader class to the configured output path.

Generates Python source code from the template and writes it to the file specified by file_manager.data_reader_path.

Examples

>>> writer = DataReaderWriter(file_manager)
>>> writer.write_class()

Return type:

None

MLflow setup

MLflow setup file generator for Bukka projects.

This module creates a setup file for MLflow experiment tracking integration.

class bukka.coding.write_mlflow_setup.MLflowSetupWriter(file_manager, project_name, tracking_uri=None)

Bases: TemplateBaseClass

Generates MLflow setup file for a Bukka project.

This class creates a Python file that configures MLflow experiment tracking with project-specific settings.

Parameters:

• file_manager (FileManager) – Manager for project file paths and directory structure.

• project_name (str) – Name of the project for experiment naming.

• tracking_uri (str | None, optional) – MLflow tracking URI. If None, defaults to file-based tracking in the project’s mlruns directory.

Examples

>>> from bukka.utils.files.file_manager import FileManager
>>> file_manager = FileManager(project_path="my_project", orig_dataset=None)
>>> writer = MLflowSetupWriter(file_manager, "my_project")
>>> writer.write_code()

__init__(file_manager, project_name, tracking_uri=None)

Initialize the MLflow setup writer.

Parameters:

• file_manager (FileManager) – Manager for project file paths and directory structure.

• project_name (str) – Name of the project for experiment naming.

• tracking_uri (str | None, optional) – MLflow tracking URI. If None, defaults to file-based tracking in the project’s mlruns directory (default: None).

Jupyter utilities

class bukka.coding.utils.jupyter_handler.JupyterWriter(filename, venv_path=None)

Bases: object

Parameters:

• filename (str)

• venv_path (str | Path | None)

add_cell(cell_content, cell_type='code')

Write a cell to the Jupyter notebook.

Parameters:

• cell_content (str) – The content of the cell.

• cell_type (str) – The type of the cell, either ‘code’ or ‘markdown’.

Return type:

None

write_notebook()

Write the Jupyter notebook to file.

Return type:

None

Template handler

class bukka.coding.utils.template_handler.TemplateBaseClass(template, output_path, kwargs, expected_args=None)

Bases: object

Base class for handling template-based code generation.

This class provides functionality to fill string templates with provided arguments and write the resulting code to a file. It uses Python’s str.format() method to substitute placeholders in the template with actual values.

Parameters:

• template (str)

• output_path (str | Path)

• kwargs (dict[str, Any])

• expected_args (list[str] | None)

template

The template string containing placeholders for formatting.

Type:

str

output_path

The file path where the generated code will be written.

Type:

str | Path

kwargs

Dictionary of keyword arguments to fill the template placeholders.

Type:

dict[str, Any]

expected_args

List of expected argument names for the template.

Type:

list[str]

Examples

>>> from pathlib import Path
>>> template = '''
... class {class_name}:
...     def __init__(self):
...         self.value = {default_value}
... '''
>>> kwargs = {'class_name': 'MyClass', 'default_value': 42}
>>> handler = TemplateBaseClass(
...     template=template,
...     output_path='output.py',
...     kwargs=kwargs,
...     expected_args=['class_name', 'default_value']
... )
>>> handler.write_class()  # Writes the filled template to 'output.py'

>>> # Using Path objects
>>> output_path = Path('generated') / 'my_class.py'
>>> handler = TemplateBaseClass(
...     template=template,
...     output_path=output_path,
...     kwargs={'class_name': 'AnotherClass', 'default_value': 100}
... )
>>> filled = handler._fill_template()
>>> print(filled)
class AnotherClass:
    def __init__(self):
        self.value = 100

__init__(template, output_path, kwargs, expected_args=None)

Initialize the template handler.

Parameters:

• template (str) – The template string containing placeholders in the format {placeholder_name}.

• output_path (str | Path) – The file path where the generated code will be written.

• kwargs (dict[str, Any]) – Dictionary mapping placeholder names to their replacement values.

• expected_args (list[str] | None, optional) – List of expected argument names for validation purposes. If None, an empty list is used. Default is None.

Return type:

None

Examples

>>> template = "def {func_name}(): return {value}"
>>> handler = TemplateBaseClass(
...     template=template,
...     output_path='func.py',
...     kwargs={'func_name': 'get_answer', 'value': 42}
... )

write_code()

Fill the template and write the resulting code to the output file.

This method fills the template with the provided kwargs and writes the resulting code to the file specified in output_path. The file is created if it doesn’t exist, or overwritten if it does.

Examples

>>> template = "x = {value}"
>>> handler = TemplateBaseClass(
...     template=template,
...     output_path='config.py',
...     kwargs={'value': 123}
... )
>>> handler.write_class()
>>> # File 'config.py' now contains: "x = 123"

Return type:

None

make_python_string_variable_safe(var_name, lowercase=False)

Convert a string into a valid Python variable name.

This method replaces spaces and special characters in the input string with underscores, ensuring the resulting string adheres to Python’s variable naming conventions.

Parameters:

• var_name (str) – The input string to be converted into a valid Python variable name.

• lowercase (bool)

Returns:

A valid Python variable name derived from the input string.

Return type:

str

Examples

>>> handler = TemplateBaseClass(
...     template="",
...     output_path="",
...     kwargs={}
... )
>>> safe_name = handler.make_python_string_variable_safe("my variable-name!")
>>> print(safe_name)
my_variable_name_

Utilities

Logger

class bukka.utils.bukka_logger.BukkaLogger(name, log_level=10)

Bases: object

A custom wrapper around Python’s standard logging logger that adds custom message formatting capabilities based on a specified format level.

The formatting levels mimic typical Markdown or HTML heading structures (p, h4, h3, h2, h1) for visual distinction in logs.

Parameters:

• name (str)

• log_level (int)

logger

The underlying standard library logger instance.

Type:

logging.Logger

__init__(name, log_level=10)

Initializes the BukkaLogger.

Parameters:

• name (str) – The name to use for the underlying logging.Logger instance. Typically the module name (__name__).

• log_level (int)

Return type:

None

debug(msg, format_level='p')

Logs a message with level DEBUG, after formatting.

Parameters:

• msg (Any) – The message to be logged. It will be converted to a string by the logging system.

• format_level (str, optional) – The formatting level to apply (‘p’, ‘h4’, ‘h3’, ‘h2’, ‘h1’). Defaults to ‘p’ (paragraph/plain).

Return type:

None

info(msg, format_level='p')

Logs a message with level INFO, after formatting.

Parameters:

• msg (Any) – The message to be logged.

• format_level (str, optional) – The formatting level to apply. Defaults to ‘p’.

Return type:

None

warn(msg, format_level='p')

Logs a message with level WARNING, after formatting.

Parameters:

• msg (Any) – The message to be logged.

• format_level (str, optional) – The formatting level to apply. Defaults to ‘p’.

Return type:

None

error(msg, format_level='p')

Logs a message with level ERROR, after formatting.

Parameters:

• msg (Any) – The message to be logged.

• format_level (str, optional) – The formatting level to apply. Defaults to ‘p’.

Return type:

None

critical(msg, format_level='p')

Logs a message with level CRITICAL, after formatting.

Parameters:

• msg (Any) – The message to be logged.

• format_level (str, optional) – The formatting level to apply. Defaults to ‘p’.

Return type:

None

format_message(msg, format_level)

Applies a specific visual format to the log message based on the level.

Parameters:

• msg (str) – The original message string to be formatted.

• format_level (str) – The format identifier (‘p’, ‘h4’, ‘h3’, ‘h2’, ‘h1’). Case-insensitive.

Returns:

The formatted message string.

Return type:

str

Reference

File manager

class bukka.utils.files.file_manager.FileManager(project_path, orig_dataset)

Bases: object

Manages the creation and organization of a standardized project directory structure.

This class handles path construction for various project components (data, pipelines, scripts, virtual environment) and provides a method to build the directory skeleton and copy the initial dataset.

Parameters:

• project_path (str | Path)

• orig_dataset (str | Path)

project_path

The root directory of the project.

Type:

Path

orig_dataset

The path to the original dataset file provided by the user.

Type:

Path

data_path

Path to the main ‘data’ directory (project_path / ‘data’).

Type:

Path

train_data

Path to the ‘train’ data subdirectory (data_path / ‘train’).

Type:

Path

test_data

Path to the ‘test’ data subdirectory (data_path / ‘test’).

Type:

Path

pipes

Path to the main ‘pipelines’ directory (project_path / ‘pipelines’).

Type:

Path

generated_pipes

Path to the ‘generated’ pipelines subdirectory.

Type:

Path

baseline_pipes

Path to the ‘baseline’ pipelines subdirectory.

Type:

Path

candidate_pipes

Path to the ‘candidate’ pipelines subdirectory.

Type:

Path

virtual_env

Path to the project’s virtual environment directory (project_path / ‘.venv’).

Type:

Path

scripts

Path to the ‘scripts’ directory.

Type:

Path

mlflow_setup_path

Path for the ‘mlflow_setup.py’ file in scripts directory.

Type:

Path

mlflow_notebook_path

Path for the ‘mlflow_notebook.ipynb’ file.

Type:

Path

dataset_path

The final destination path for the copied dataset (data_path / dataset_filename).

Type:

Path

starter_notebook_path

Path for the ‘starter.ipynb’ file.

Type:

Path

requirements_path

Path for the ‘requirements.txt’ file.

Type:

Path

readme_path

Path for the ‘README.md’ file.

Type:

Path

gitignore_path

Path for the ‘.gitignore’ file.

Type:

Path

config_path

Path for the ‘config.py’ file.

Type:

Path

__init__(project_path, orig_dataset)

Initializes the FileManager with project and dataset paths.

Parameters:

• project_path (PathLike) – The path to the project’s root directory. Can be a string or a Path object.

• orig_dataset (PathLike) – The path to the original dataset file to be copied. Can be a string or a Path object.

Return type:

None

build_skeleton()

Creates the defined project directory structure and copies the dataset.

It systematically creates all necessary folders and adds __init__.py files to designated directories to treat them as Python packages. Finally, it copies the original dataset into the new data folder.

Return type:

None

Environment management

Environment module

class bukka.environment.environment.EnvironmentBuilder(file_manager, enable_mlflow=False)

Bases: object

Builds and configures a Python virtual environment for a Bukka project.

This class handles the creation of a virtual environment, installation of required packages from a requirements file, and optional editable installation of the project itself.

Parameters:

• file_manager (FileManager) – Manager for project file paths and directory structure.

• enable_mlflow (bool, optional) – Whether to include MLflow in the environment (default: False).

Examples

>>> from bukka.logistics.files.file_manager import FileManager
>>> file_manager = FileManager(project_name="my_project")
>>> env_builder = EnvironmentBuilder(file_manager)
>>> env_builder.build_environment()

build_environment()

Build the complete Python environment for the project.

Creates a virtual environment and installs all required packages specified in the requirements file.

Examples

>>> env_builder = EnvironmentBuilder(file_manager)
>>> env_builder.build_environment()

Preprocessing

Categorical processing