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–CausalIQ Analysis action provider for workflow integration.
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:
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.
-
EvaluateGraphAction–Evaluate a learned graph against a ground-truth reference.
-
MergeGraphsAction–Merge multiple graphs into a probabilistic DAG.
-
MigrateTraceAction–Migrate legacy trace files into GraphML graphs.
-
PlotAction–Generate a chart from a summarise CSV output.
-
SummariseAction–Summarise metric values from cache entries into a table.
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.