Skip to content

Workflow Action

Workflow action interface for causaliq-workflow. A thin provider validates the action and its parameters, then delegates to the action class registered in ACTION_CLASSES; each action is a small class with its own validate and run methods.

Provider

workflow_action

CausalIQ Workflow Action for analysis operations.

This package implements the Action interface for causaliq-workflow integration, enabling graph migration, merging, evaluation, summarisation and plotting to be used in workflow definitions.

The provider class lives here; individual actions are implemented in actions/ and registered in ACTION_CLASSES, with shared type imports and fallback stubs in types.py and shared helper functions in helpers.py.

Modules:

  • actions –

    Analysis workflow action sub-package.

  • helpers –

    Shared helper functions for analysis workflow actions.

  • types –

    Canonical type imports and fallback stubs for workflow action support.

Classes:

AnalysisActionProvider

AnalysisActionProvider()

CausalIQ Analysis action provider for workflow integration.

Parameter validation and execution are delegated to the action class registered for each action in ACTION_CLASSES. Supports operations on causal graphs including: - migrate_trace: Convert legacy Trace files to GraphML format - merge_graphs: Merge multiple graphs into a PDG with probabilities - evaluate_graph: Compute structural metrics vs ground truth - best_graph: Extract the optimal DAG from cached graphs - summarise: Summarise numerical metrics into statistics - plot: Generate charts from a summarise CSV output

Methods:

  • run –

    Execute analysis action with action-specific dry-run handling.

  • validate_parameters –

    Validate action and parameters before execution.

run
run(
    action: str,
    parameters: Dict[str, Any],
    mode: str = "dry-run",
    context: Optional[WorkflowContext] = None,
    logger: Optional[WorkflowLogger] = None,
) -> ActionResult

Execute analysis action with action-specific dry-run handling.

Overrides base class to preserve action-specific dry-run behaviour that requires logger access for terminal output.

Parameters:

  • action
    (str) –

    Action to perform.

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str, default: 'dry-run' ) –

    Execution mode ('dry-run', 'run', 'compare').

  • context
    (Optional[WorkflowContext], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[WorkflowLogger], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate_parameters
validate_parameters(action: str, parameters: Dict[str, Any]) -> None

Validate action and parameters before execution.

Checks the action is supported, rejects unknown parameters, then delegates to the action class registered for the action. Value errors raised by the action class are reported as validation errors.

Parameters:

  • action
    (str) –

    Action to perform.

  • parameters
    (Dict[str, Any]) –

    Parameter dictionary.

Raises:

  • ActionValidationError –

    If validation fails or the action is not supported.

Action registry

actions

Analysis workflow action sub-package.

Individual workflow actions live here as small single-responsibility classes. ACTION_CLASSES maps workflow action names to their classes so the provider can validate and execute them without knowing their details.

Modules:

  • base –

    Abstract base contract for individual analysis workflow actions.

  • best_graph –

    Best_graph workflow action.

  • evaluate_graph –

    Evaluate_graph workflow action.

  • merge_graphs –

    Merge_graphs workflow action.

  • migrate_trace –

    Migrate_trace workflow action.

  • plot –

    Plot workflow action.

  • summarise –

    Summarise workflow action.

Classes:

BestGraphAction

Extract the optimal DAG from a PDG.

Attributes:

  • action_name –

    Action name as used in workflow definitions.

  • pattern –

    Workflow action pattern used for cache validation.

Methods:

  • run –

    Execute optimal DAG extraction from a PDG.

  • validate –

    Validate best_graph parameters before execution.

run
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Execute optimal DAG extraction from a PDG.

Reads the PDG from the matched workflow cache entry (MAP pattern), extracts the optimal DAG and returns it as a GraphML object for the output cache.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate
validate(parameters: Dict[str, Any]) -> None

Validate best_graph parameters before execution.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ValueError –

    If a parameter is missing or invalid. The provider converts this to an ActionValidationError.

EvaluateGraphAction

Evaluate a learned graph against a ground-truth reference.

Attributes:

  • action_name –

    Action name as used in workflow definitions.

  • pattern –

    Workflow action pattern used for cache validation.

Methods:

  • run –

    Evaluate the matched entry graph against the reference graph.

  • validate –

    Validate evaluate_graph parameters before execution.

run
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Evaluate the matched entry graph against the reference graph.

MAP pattern action: exactly one graph arrives via the '_aggregation_entries' parameter, and the reference may be a single ground-truth graph file or a workflow cache (.db) whose entries share the input cache's key structure.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate
validate(parameters: Dict[str, Any]) -> None

Validate evaluate_graph parameters before execution.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ValueError –

    If a parameter is missing or invalid. The provider converts this to an ActionValidationError.

MergeGraphsAction

Merge multiple graphs into a probabilistic DAG.

Attributes:

  • action_name –

    Action name as used in workflow definitions.

  • pattern –

    Workflow action pattern used for cache validation.

Methods:

  • run –

    Execute graph merging to produce a PDG.

  • validate –

    Validate merge_graphs parameters before execution.

run
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Execute graph merging to produce a PDG.

Aggregation mode merges graphs from pre-scanned cache entries passed via '_aggregation_entries'; direct mode merges graphs read from the 'input' file paths (.graphml or .db files).

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate
validate(parameters: Dict[str, Any]) -> None

Validate merge_graphs parameters before execution.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ValueError –

    If a parameter is missing or invalid. The provider converts this to an ActionValidationError.

MigrateTraceAction

Migrate legacy trace files into GraphML graphs.

Attributes:

  • action_name –

    Action name as used in workflow definitions.

  • pattern –

    Workflow action pattern used for cache validation.

Methods:

  • run –

    Execute trace migration to GraphML graphs.

  • validate –

    Validate migrate_trace parameters before execution.

run
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Execute trace migration to GraphML graphs.

Migrates the matched trace files, returning exactly one GraphML object together with the flattened cache metadata. More than one matched graph is an error because the workflow matrix omitted a distinguishing dimension.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate
validate(parameters: Dict[str, Any]) -> None

Validate migrate_trace parameters before execution.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ValueError –

    If a parameter is missing or invalid. The provider converts this to an ActionValidationError.

PlotAction

Generate a chart from a summarise CSV output.

Attributes:

  • action_name –

    Action name as used in workflow definitions.

  • pattern –

    Workflow action pattern used for cache validation.

Methods:

  • run –

    Execute chart generation from a summarise CSV output.

  • validate –

    Validate plot parameters before execution.

run
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Execute chart generation from a summarise CSV output.

Reads the input CSV, builds the long-form data required by the legacy plotting functions and writes the output chart file.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate
validate(parameters: Dict[str, Any]) -> None

Validate plot parameters before execution.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ValueError –

    If a parameter is missing or invalid. The provider converts this to an ActionValidationError.

SummariseAction

Summarise metric values from cache entries into a table.

Attributes:

  • action_name –

    Action name as used in workflow definitions.

  • pattern –

    Workflow action pattern used for cache validation.

Methods:

  • run –

    Execute metric summarisation to a table file.

  • validate –

    Validate summarise parameters before execution.

run
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Execute metric summarisation to a table file.

Aggregation mode summarises the pre-scanned cache entries passed via '_aggregation_entries' per matrix combination; direct mode reads entries from the 'input' cache files and produces a single summary row.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Logger for reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

Raises:

  • ActionExecutionError –

    If execution fails.

validate
validate(parameters: Dict[str, Any]) -> None

Validate summarise parameters before execution.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ValueError –

    If a parameter is missing or invalid. The provider converts this to an ActionValidationError.

Base contract

base

Abstract base contract for individual analysis workflow actions.

Each analysis workflow action is implemented as a small class that validates its own parameters and executes a single action. The provider in the parent package delegates to these action classes.

Classes:

  • AnalysisAction –

    Base contract for a single analysis workflow action.

AnalysisAction

Base contract for a single analysis workflow action.

Attributes:

  • action_name (str) –

    Action name as used in workflow definitions.

  • pattern (ActionPattern) –

    Workflow action pattern used for cache validation.

  • required_parameters (Tuple[str, ...]) –

    Parameter names that must be provided.

Methods:

  • run –

    Execute the action and return its result.

  • validate –

    Validate parameters shared by all analysis actions.

run abstractmethod
run(
    parameters: Dict[str, Any],
    mode: str,
    context: Optional[Any] = None,
    logger: Optional[Any] = None,
) -> ActionResult

Execute the action and return its result.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

  • mode
    (str) –

    Execution mode ('dry-run', 'run' or 'compare').

  • context
    (Optional[Any], default: None ) –

    Workflow context for optimisation.

  • logger
    (Optional[Any], default: None ) –

    Optional logger for task execution reporting.

Returns:

  • ActionResult –

    Tuple of (status, metadata, objects).

validate
validate(parameters: Dict[str, Any]) -> None

Validate parameters shared by all analysis actions.

Parameters:

  • parameters
    (Dict[str, Any]) –

    Action parameter values.

Raises:

  • ActionValidationError –

    If a required parameter is missing.

Action classes

Shared types and helpers

causaliq_analysis.workflow_action.helpers holds the internal cache parsing, metadata flattening and graph-extraction helpers shared by the action classes. They are implementation details; the public API is the action classes listed above.

causaliq_analysis.workflow_action.types re-exports the workflow types (ActionPattern, ActionResult, ActionValidationError, and friends) from causaliq_core, with minimal fallback stubs used when causaliq-workflow is not installed.