noirstack-cascade-sdk 0.1.3

Python SDK for Cascade workflow orchestration

Cascade SDK

The Cascade SDK is a standards-first Python library for workflow orchestration. It acts as a "Babel for Workflows," allowing you to define logic in Python and execute it across diverse orchestrators while maintaining strict compliance with industry standards like W3C PROV and CloudEvents.

Quick Start

Installation

pip install noirstack-cascade-sdk

1. Define Your Flow (Capture Mode)

Cascade uses Capture Mode to record workflow structures without executing them locally. Task calls are intercepted to build a serializable DAG.

In 0.1.x, data exchanged between tasks should be JSON-serializable primitives and containers (str, int, float, bool, dict, list, None). Avoid passing live runtime objects such as DB connections, open file handles, or custom class instances across task boundaries.

from cascade_sdk import task, flow

@task
def extract_metadata(file_path: str):
    return {"status": "processing", "path": file_path}

@flow
def ingestion_flow(path: str):
    return extract_metadata(path)

2. Register and Execute

from cascade_sdk import CascadeClient, wait_for_completion
from cascade_sdk.compiler import build_dag_from_flow

# Compile to a deterministic DAG
dag = build_dag_from_flow(ingestion_flow)

# Initialize the thin client
client = CascadeClient(base_url="http://localhost:3000", api_key="your_key")

# Register and trigger
flow_id = client.register_flow("data_pipeline", dag)
run_id = client.trigger_flow(flow_id, {"path": "/data/source.csv"})

# Wait for result
result = wait_for_completion(client, run_id)
print(f"Workflow Result: {result['result']}")

For asyncio environments, use wait_for_completion_async(...).

Standards and Compliance

Cascade is designed for regulated environments (financial, healthcare, federal) where auditability is non-negotiable.

• W3C PROV: Generate structured lineage describing agents, activities, and entities.
• CloudEvents: Interoperable event envelopes for system-wide triggers.
• NIST SP 800-204: Security guidance profile for microservice boundaries.
• OpenTelemetry: Native distributed tracing context propagation.

Human-in-the-Loop (HITL) Provenance

Capture manual interventions with the same rigor as automated tasks:

from cascade_sdk import build_prov_bundle

def log_approval(manager_email, run_id):
    # Generates a W3C-compliant audit trail for a manual decision
    return build_prov_bundle(
        agent={f"agent:{manager_email}": {"prov:type": "prov:Person"}},
        activity={"activity:approval": {"prov:type": "cascade:human_intervention"}},
        wasAssociatedWith={"activity:approval": f"agent:{manager_email}"}
    )

Note: build_prov_bundle() emits a minimal PROV-JSON document with the standard prov prefix. Keep prefixed keys consistent (for example prov:type) when adding domain-specific attributes.

Ecosystem Adapters

Migrate legacy workloads to Cascade without rewriting your logic. 0.1.0 supports:

• Airflow: airflow_dag_to_dag(dag)
• Argo: argo_workflow_to_dag(dict)
• BPMN 2.0: bpmn_xml_to_dag(xml_str)
• Others: Support for Kestra, Dagster, Mage, and more.

0.1.0 Considerations (Beta Status)

As an early public release, please note the following:

Known Limitation (Current)

• The SDK currently provides synchronous polling via wait_for_completion(...); async-native polling helpers are planned for 0.2.0.

• Synchronous Polling: wait_for_completion is currently blocking. Async support is planned for 0.2.0.

• Serialization: All data passed between tasks must be JSON-serializable.

• Thin Client: The SDK contains zero orchestration logic (no retries/caching); these are handled by the Cascade control plane.

• Optional Extras: Install specific adapters using extras: pip install "noirstack-cascade-sdk[airflow,standards]".

• HITL Resume Path: 0.1.x does not yet expose a first-class submit_task_output(...) helper. Resume/approval handoff is currently control-plane API specific.

Contributing

We are actively seeking feedback on the DAG Compiler and standards integrations.

Want to influence 0.2.0? If you encounter compiler edge cases or unclear DAG build errors on valid Python constructs, open an issue with a minimal code snippet and expected DAG behavior.

• Documentation: https://github.com/no1rstack/cascade-sdk-public
• Issue Tracker: https://github.com/no1rstack/cascade-sdk-public/issues

API Docs

• API_REFERENCE.md: concise reference for decorators, compiler, client methods, polling helpers, and standards utilities.

Created by Noir Stack LLC.