fairxai.project package

Submodules

fairxai.project.project module

class fairxai.project.project.Project(project_name: str, data: Any = None, dataset_metadata: dict | None = None, dataset_type: str | None = None, framework: str | None = None, model_path: str | None = None, model_params: Dict[str, Any] | None = None, workspace_path: str = './workspace', target_variable: str | None = None, categorical_columns: List[str] | None = None, ordinal_columns: List[str] | None = None, device: str = 'cpu', is_reload: bool = False, id: str = None)

Bases: object

Represents an explainability project binding a dataset, a trained model, and a set of compatible explainers. Supports saving/loading pipelines, explanations, and project metadata in a dedicated workspace.

This version uses the “framework-first” ModelFactory approach, where the user specifies the ML framework (sklearn, torch, etc.) and optionally a model file path. The correct black-box wrapper is automatically instantiated and loaded.

id

UUID of the project.

Type:

str

created_at

Timestamp of creation.

Type:

datetime

dataset_instance

The dataset instance (tabular, image, etc.).

Type:

Dataset

blackbox

Wrapped ML model.

Type:

Any

explainers

Compatible explainer classes.

Type:

List[Type[GenericExplainerAdapter]]

explanations

Stored explanation records.

Type:

List[Dict[str, Any]]

Initialize a new project or reload an existing one.

Either data (for new project) or dataset_metadata (for reload) must be provided.

Parameters:

• project_name – Name of the project

• data – Raw dataset to create the dataset instance (new project)

• dataset_metadata – Metadata to reload dataset (existing project)

• dataset_type – Dataset type (‘tabular’, ‘image’, ‘text’, ‘timeseries’)

• framework – ML framework (‘sklearn’, ‘torch’, etc.)

• model_path – Optional path to pre-trained model

• model_params – Optional parameters for model instantiation

• workspace_path – Base folder for project workspace

• target_variable – Name of target variable in dataset (optional)

• categorical_columns – Categorical columns (tabular only)

• ordinal_columns – Ordinal columns (tabular only)

• device – Device for Torch models (‘cpu’ or ‘cuda’)

• is_reload – If True, indicates that this project is being reloaded and folders should not be recreated

classmethod load_from_dict(project_metadata: Dict[str, Any]) → Project

Restore a project from metadata dictionary.

Parameters:

project_metadata – Project metadata dictionary.

Returns:

Project instance with dataset and blackbox reconstructed.

run_explanation_pipeline(pipeline: List[Dict[str, Any]]) → List[Dict[str, Any]]

Execute a user-defined explainability pipeline.

Each step should include:

• ‘explainer’: str (explainer class name)

• ‘mode’: ‘local’ | ‘global’ (optional; inferred if missing)

• ‘params’: dict (optional; ‘local’ requires ‘instance_index’)

Parameters:

pipeline – List of pipeline steps

Returns:

List of explanation records

run_pipeline_from_yaml(yaml_path: str) → List[Dict[str, Any]]

Load pipeline definition from YAML file and execute it.

Parameters:

yaml_path – Path to YAML file containing pipeline specification.

Returns:

List of explanation records

to_dict() → Dict[str, Any]

Return a serializable dictionary of project metadata.

fairxai.project.project_registry module

class fairxai.project.project_registry.ProjectRegistry(workspace_path: str)

Bases: object

Registry that manages explainability projects inside a workspace.

This registry does not eagerly load all projects into memory. Instead, during initialization it scans the workspace directory and registers all project folders that contain a valid project.json. Each project is then loaded on-demand only when required.

The registry maintains two types of information:

• the index of existing project IDs on disk (always populated)

• the loaded Project objects in memory (populated only after load_project)

Parameters:

workspace_path (str) – Base directory where all projects are stored.

Notes

This class ensures that each workspace path has exactly one registry instance (per-workspace singleton).

Initialize the registry and build the project index.

The index maps project IDs to either None (if not yet loaded) or a fully-loaded Project object.

Existing projects are detected by locating folders that contain a project.json file.

add(project: Project) → None

Add or update a loaded project in the registry.

Parameters:

project (Project) – The project instance to register.

clear() → None

Clear all loaded project instances from memory.

This does not remove project folders from disk.

find_by_name(name: str) → Dict[str, Any] | None

Retrieve project metadata by matching the project name.

Parameters:

name (str) – The project name to search for.

Returns:

Metadata of the first matching project, or None if no match is found.

Return type:

dict or None

get(project_id: str) → Project | None

Get project metadata (does not read from disk).

Parameters:

project_id (str) – ID of the project to retrieve.

Returns:

The loaded project instance, or None if not loaded yet.

Return type:

Project or None

get_metadata(project_id: str) → Dict[str, Any] | None

Retrieve metadata for a specific project by its ID.

Parameters:

project_id (str) – The unique identifier of the project.

Returns:

The parsed project.json content, or None if missing or invalid.

Return type:

dict or None

get_project_path(project_id: str) → str

Get the filesystem path of a project folder.

Parameters:

project_id (str)

Returns:

Path to the project’s directory.

Return type:

str

list_all() → List[Dict[str, Any]]

Return metadata for all projects on disk.

This method reads the project.json files directly without loading full Project objects into memory.

Returns:

A list of dictionaries containing project metadata.

Return type:

List[Dict[str, Any]]

load_project(project_id: str) → Project

Load a project from disk into memory.

Parameters:

project_id (str) – Unique project identifier.

Returns:

The fully loaded project instance.

Return type:

Project

Raises:

FileNotFoundError – If project.json does not exist.

remove(project_id: str) → None

Remove a project from the in-memory registry.

This does not delete the project from disk.

Parameters:

project_id (str) – The project ID to remove.

Module contents