API

Debugging Algorithms

class Debugger(max_iter=1000, origin=None, separator='|', send='5557', receive='5558', function=None)

Creates pipeline instances to be run based on execution history and finds root causes of failure.

This is the base interface for all debugging algorithms in BugDoc library. It takes an entry point of a pipeline and a description of the parameter space to generate new instances and return root causes.

Supports two modes: - Standalone mode: Pass a callable function directly. No ZMQ dependency required. - ZMQ mode: Use traditional ZMQ-based communication with external worker process.

Build a new debugging algorithm object.

Parameters

max_iter: int

Maximum number of instances to be created.

origin: None or str

Additional provenance information to be added to the history of pipeline instances.

separator: str

Character to be used as separator between data fields that are sent as string to debugger worker.

send: str

Socket port used to send messages to worker (ZMQ mode only).

receive: str

Socket port used to receive messages from worker (ZMQ mode only).

function: callable or None

Standalone mode: A callable that takes a parameter dictionary and returns a result. If provided, uses direct function execution instead of ZMQ communication.

process_standalone_results()

For standalone mode: process pending results.

Call this method where you would normally handle poller results. Returns the next pending result or None.

has_pending_results()

Check if there are pending results in standalone mode.

poll_results(timeout=10000)

Poll for results in a mode-agnostic way.

In standalone mode, returns pending results immediately. In ZMQ mode, uses the ZMQ poller.

Parameters

timeout: int

Timeout in milliseconds for ZMQ mode. Ignored in standalone mode.

Returns

dict or None

In standalone mode: next pending result as experiment list, or None if no pending In ZMQ mode: socket dict from poller, or empty dict on timeout

get_result_from_poll(socks)

Extract result from poll response in a mode-agnostic way.

Parameters

socks: dict

Result from poll_results()

Returns

list or None

The experiment result [param1, param2, …, result], or None if no result

close()

Clean up resources.

class StackedShortcut(created_instances=False, k=4, max_iter=1000, origin=None, separator='|', send='5557', receive='5558')

Build a new debugging algorithm object.

Parameters

max_iter: int

Maximum number of instances to be created.

origin: None or str

Additional provenance information to be added to the history of pipeline instances.

separator: str

Character to be used as separator between data fields that are sent as string to debugger worker.

send: str

Socket port used to send messages to worker (ZMQ mode only).

receive: str

Socket port used to receive messages from worker (ZMQ mode only).

function: callable or None

Standalone mode: A callable that takes a parameter dictionary and returns a result. If provided, uses direct function execution instead of ZMQ communication.

class Shortcut(max_iter=1000, origin=None, separator='|', send='5557', receive='5558')

Build a new debugging algorithm object.

Parameters

max_iter: int

Maximum number of instances to be created.

origin: None or str

Additional provenance information to be added to the history of pipeline instances.

separator: str

Character to be used as separator between data fields that are sent as string to debugger worker.

send: str

Socket port used to send messages to worker (ZMQ mode only).

receive: str

Socket port used to receive messages from worker (ZMQ mode only).

function: callable or None

Standalone mode: A callable that takes a parameter dictionary and returns a result. If provided, uses direct function execution instead of ZMQ communication.

class DebuggingDecisionTrees(return_num_instances=False, first_solution=False, num_tests=10000, use_score=False, max_iter=10000, origin=None, separator='|', send='5557', receive='5558', function=None)

Creates pipeline instances to be run based on a decision tree fitted on execution history and finds root causes of failure.

This algorithm fits a decision tree using parameters as features and results of pipelines as target. The results are boolean evaluations of success (True) or fail (False). It takes an entry point of a pipeline and a description of the parameter space to generate new instances and return root causes of failure.

Build a new debugging debugging decision trees algorithm object.

Parameters

return_num_instances: bool

Whether return the number of new instances were created or not.

num_tests: int

Maximum number of instances to run in each iteration of the algorithm.

use_score: bool

Whether using a goodness score to order the instances to be run. The goodness score, for each parameter-value, is defined by the ratio of successful and failing instances in which a given parameter-values appears.

Utils

load_combinatorial(input_dict, max_pair_product=10000)

Load a combinatorial design with a scalable fallback.

If the two largest domains are too large, reduce them to a smaller representative subset before calling generate_tuples().

record_pipeline_run(filename, values, parameters, result, origin=None)

Parameters:

• filename

• values

• parameters

• result

• origin

Returns: