Metadata-Version: 2.4
Name: noirstack-cascade-sdk
Version: 0.1.2
Summary: Python SDK for Cascade workflow orchestration
Author: Noir Stack LLC, Hira Barton
License-Expression: MIT
Project-URL: Homepage, https://github.com/no1rstack/cascade-sdk-public
Project-URL: Documentation, https://github.com/no1rstack/cascade-sdk-public
Project-URL: Repository, https://github.com/no1rstack/cascade-sdk-public
Project-URL: Issues, https://github.com/no1rstack/cascade-sdk-public/issues
Keywords: workflow,orchestration,dag,task,flow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Provides-Extra: standards
Requires-Dist: cloudevents>=1.11.0; extra == "standards"
Requires-Dist: opentelemetry-api>=1.24.0; extra == "standards"
Requires-Dist: jsonschema>=4.22.0; extra == "standards"
Provides-Extra: airflow
Requires-Dist: apache-airflow>=2.8.0; extra == "airflow"
Provides-Extra: orchestrators
Requires-Dist: dagster>=1.7.0; extra == "orchestrators"
Requires-Dist: luigi>=3.5.0; extra == "orchestrators"
Dynamic: license-file

# Cascade SDK

[![PyPI version](https://img.shields.io/pypi/v/noirstack-cascade-sdk.svg)](https://pypi.org/project/noirstack-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

```bash
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.

```python
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

```python
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']}")
```

## Standards and Compliance

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

- **[W3C PROV](https://www.w3.org/TR/prov-overview/):** Generate structured lineage describing agents, activities, and entities.
- **[CloudEvents](https://cloudevents.io/):** Interoperable event envelopes for system-wide triggers.
- **[NIST SP 800-204](https://csrc.nist.gov/publications/detail/sp/800-204/final):** Security guidance profile for microservice boundaries.
- **[OpenTelemetry](https://opentelemetry.io/):** Native distributed tracing context propagation.

### Human-in-the-Loop (HITL) Provenance

Capture manual interventions with the same rigor as automated tasks:

```python
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

Created by **Noir Stack LLC**.
