stageflow-framework 0.1.0__py3-none-any.whl

stageflow/testing.py

@@ -0,0 +1,59 @@
+import asyncio
+from dataclasses import dataclass
+from typing import Sequence
+
+from stageflow.core.context import Context
+from stageflow.core.pipeline import Pipeline
+from stageflow.core.session import Session, SessionResult
+from stageflow.core.event import Event
+
+
+@dataclass
+class PipelineTestSpec:
+    pipeline: dict | Pipeline
+    inputs: Sequence[dict]
+    payload: dict | None = None
+    expected_result: dict | None = None
+    expected_artifacts: dict | None = None
+    expected_history: list[str] | None = None  # sequence of stage_id/node_id seen in events
+
+
+async def run_pipeline_test(spec: PipelineTestSpec) -> tuple[SessionResult, list[Event]]:
+    pipeline = spec.pipeline if isinstance(spec.pipeline, Pipeline) else Pipeline.from_dict(spec.pipeline)
+    events: list[Event] = []
+
+    def handler(ev: Event):
+        events.append(ev)
+
+    session = Session(id="test", pipeline=pipeline, context=Context(payload=spec.payload or {}), event_handler=handler)
+
+    async def feed_inputs():
+        for inp in spec.inputs:
+            delay = inp.get("delay", 0)
+            if delay:
+                await asyncio.sleep(delay)
+            wait_for_listener = inp.get("wait_for_listener", True)
+            if wait_for_listener:
+                waited = 0.0
+                while inp["type"] not in session._waiting and waited < 1.0:
+                    await asyncio.sleep(0.01)
+                    waited += 0.01
+            await session.input(inp["type"], inp.get("payload", {}))
+
+    run_task = asyncio.create_task(session.run())
+    await asyncio.gather(run_task, feed_inputs())
+    result = run_task.result()
+
+    if spec.expected_result is not None:
+        if result.result != spec.expected_result:
+            raise AssertionError(f"Expected result {spec.expected_result}, got {result.result}")
+    if spec.expected_artifacts is not None:
+        for k, v in spec.expected_artifacts.items():
+            if result.artifacts.get(k) != v:
+                raise AssertionError(f"Expected artifact {k}={v}, got {result.artifacts.get(k)}")
+    if spec.expected_history is not None:
+        seen = [ev.stage_id or ev.node_id for ev in events if (ev.stage_id or ev.node_id)]
+        if seen != spec.expected_history:
+            raise AssertionError(f"Expected history {spec.expected_history}, got {seen}")
+
+    return result, events

stageflow_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: stageflow-framework
+Version: 0.1.0
+Summary: StageFlow: Pipeline framework for stages
+Author: lethargy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml
+Requires-Dist: jsonschema>=4.0.0
+
+# StageFlow
+
+StageFlow is a lightweight framework for describing and running JSON pipelines with nodes, stages, and schema validation.
+
+## Features
+- Node types: `stage`, `condition`, `parallel`, `map`, `subpipeline`, `terminal`.
+- Custom stages (async `run`) with documented arguments/config/outputs.
+- Input waiting (`wait_input`), event history, session snapshots.
+- Built-in stages for dict/list/string/logic utilities.
+- Pipeline JSON Schema (stage enum injected on the fly) and HTML doc generator.
+
+## Installation
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install stageflow-framework
+# or for local dev:
+# pip install -e .
+```
+Requires Python 3.10+.
+
+## Quickstart
+1) Register your stage:
+```python
+from stageflow.core.stage import BaseStage, register_stage
+
+@register_stage("HelloStage")
+class HelloStage(BaseStage):
+    """
+    description: "Custom stage example"
+    arguments:
+      name: string
+    outputs:
+      greeting: string
+    """
+    async def run(self):
+        name = self.get_arguments().get("name", "world")
+        self.set_outputs({"greeting": f"Hello, {name}!"})
+```
+
+2) Describe a pipeline in JSON:
+```python
+pipeline_dict = {
+    "entry": "start",
+    "nodes": [
+        {
+            "id": "start",
+            "type": "stage",
+            "stage": "HelloStage",
+            "arguments": {"name": "user_name"},
+            "outputs": {"greeting": "greeting"},
+            "next": "finish",
+        },
+        {
+            "id": "finish",
+            "type": "terminal",
+            "result": {"status": "ok"},
+            "artifacts": ["greeting"],
+        },
+    ],
+}
+```
+
+3) Run:
+```python
+import asyncio
+from stageflow.core.pipeline import Pipeline
+from stageflow.core.session import Session
+from stageflow.core.context import Context
+
+async def main():
+    pipe = Pipeline.from_dict(pipeline_dict)
+    session = Session(id="demo", pipeline=pipe, context=Context(payload={"user_name": "Alice"}))
+    result = await session.run()
+    print(result.result)        # {'status': 'ok'}
+    print(result.artifacts)     # {'greeting': 'Hello, Alice!'}
+
+asyncio.run(main())
+```
+
+## Docs and schema generation
+- Programmatic:
+```python
+from stageflow.docs.html import generate_docs_assets
+
+html_page, pipeline_schema, stages_json = generate_docs_assets()
+# html_page — ready-to-serve HTML
+# pipeline_schema — dict with JSON Schema (stage enum injected)
+# stages_json — raw JSON with stage specs
+```
+- CLI (prints JSON payload with `html`, `pipeline_schema`, `stages_json` to stdout):
+```bash
+python scripts/generate_docs_html.py > docs_assets.json
+```
+If needed, persist the `html` from the JSON payload yourself.
+
+## Tests
+```bash
+python -m unittest
+```
+
+## Node types overview
+- `stage`: Executes a registered Stage. Fields: `stage` (name), `config`/`arguments`/`outputs` mappings, `next`, optional `fallback`.
+- `condition`: List of `{if, then}` branches (JsonLogic conditions), optional `else`.
+- `parallel`: Runs several children; `policy` = `all|any`, `cancel_on_error` flag, optional `next`.
+- `map`: Iterates over items path, runs body node for each item (sequential/parallel), collects mapped outputs.
+- `subpipeline`: Invokes nested pipeline by id, with `inputs` mapping, `artifact_outputs`, optional `result_output`, `next`.
+- `terminal`: Ends execution, returns `result` and selects `artifacts`.
+
+### Node types in detail
+- **Stage node**
+  - Required: `id`, `type="stage"`, `stage` (registered stage name).
+  - Data flow: `arguments` map context paths -> stage inputs; `outputs` map stage return keys -> context paths.
+  - Control flow: `next` points to following node; optional `fallback` node is used on stage exceptions.
+  - Stage class declares `skipable`, `allowed_events`, `allowed_inputs`, `timeout`, `retries`.
+- **Condition node**
+  - Required: `id`, `type="condition"`, non-empty `conditions` list.
+  - Each condition: `{ "if": <JsonLogic>, "then": "<node id>" }`; first matched branch wins.
+  - Optional `else` target if no branch matches.
+- **Parallel node**
+  - Required: `id`, `type="parallel"`, non-empty `children` (node ids).
+  - `policy`: `all` (default) waits all children; `any` completes on first success.
+  - `cancel_on_error`: whether to cancel siblings on failure.
+  - `next`: node id to continue after parallel finishes.
+- **Map node**
+  - Required: `id`, `type="map"`, `items` (context path with iterable), `body` (node id).
+  - `mode`: `sequential` (default) or `parallel` for body executions.
+  - `output_map`: map of body outputs -> target context paths for aggregated results.
+  - `item_path`/`index_path`: where to inject current item/index into context for body runs.
+  - `cancel_on_error`: abort remaining iterations on error.
+  - `next`: node id after all iterations finish.
+- **Subpipeline node**
+  - Required: `id`, `type="subpipeline"`, `subpipeline_id` (key in `subpipelines` dict of pipeline).
+  - `inputs`: context mapping passed into subpipeline root context.
+  - `artifact_outputs`: map subpipeline artifacts -> parent context paths.
+  - `result_output`: path in parent context to store subpipeline `result`.
+  - `next`: next node in parent pipeline.
+- **Terminal node**
+  - Required: `id`, `type="terminal"`.
+  - `result`: arbitrary object returned as final result.
+  - `artifacts`: list of context paths that will be returned as artifacts map.
+
+## Built-in stages
+- Vars: `SetValueStage`, `CopyValueStage`, `IncrementStage`, `MergeDictStage`.
+- Dicts: `PickKeysStage`, `DropKeysStage`.
+- Lists: `AppendListStage`, `ExtendListStage`, `FilterListStage`, `UniqueListStage`, `PopListStage`.
+- Strings: `ConcatStage`, `TemplateStage`.
+- Logic: `AssertStage`, `FailStage`, `LogStage`, `SleepStage`.
+
+Each stage docstring describes arguments/config/outputs; they are also available via `generate_docs_assets()` / `stages_json`.
+
+## Useful refs
+- `stageflow/core` — core (pipeline, session, nodes, context).
+- `stageflow/builtins` — built-in stages.
+- `stageflow/docs` — schema/HTML generation helpers.
+- `scripts/` — helpers (docs generator wrapper).
+- `tests/` — unit tests.

stageflow_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+stageflow/__init__.py,sha256=c_CM46gP_3mau3XAcV8J1LZIs2KTcavBqdk4B6zdvvo,761
+stageflow/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+stageflow/testing.py,sha256=VYrSOx_5uuQ5dMsV18KF4JpvVIjQ0nrtCo7tqQi6Ak0,2345
+stageflow/builtins/__init__.py,sha256=PItXwajwpwwFX5LK8h6rnPCTtPv0L4HNnyJ3YPZIpE0,764
+stageflow/builtins/dicts.py,sha256=SeuuxCBV8S2Tn84HlkKjaBN1ysE81qv1NEV4xmr9puA,1750
+stageflow/builtins/lists.py,sha256=JLlYnkvk_HQukDLj2XyfaNJxIG0vItmLeXlVs1DtBy8,2099
+stageflow/builtins/lists_extra.py,sha256=vwKYbbacXfG1UjlW2RegQL4EPIxm6EDdkCxYIfH35Ps,3333
+stageflow/builtins/logic.py,sha256=EnWKjHBx4sDnehDNTWx6psQR0vztCS3JGRcOihMKQcs,2302
+stageflow/builtins/strings.py,sha256=ifIhGBu6WTLAwsNJ0FUj8hxdBeZVqJeYg05P7Kq9BeU,2520
+stageflow/builtins/vars.py,sha256=3ChqXZuX0tIj5mZr5INny7IFMu2bROEHvvS8KI0JnPc,3411
+stageflow/core/__init__.py,sha256=dWxd8eOZ8HxR66bQ0yqvWxVij6rnrbc68OBUG3AchMw,471
+stageflow/core/context.py,sha256=Yql-6YH-1l4GtD70RS-jzcontD0mlA-owSZGCvuRKNA,2606
+stageflow/core/event.py,sha256=xTwCicmAuWoxsYrDXAVl7JgSQ3hVh47MolBVf_K_jC8,1892
+stageflow/core/jsonlogic.py,sha256=J8gqzD1-r0bJflseVdmB_JQB0GebnAUMJoZE8u52xmY,1543
+stageflow/core/node.py,sha256=y03NTPcPvufNd-khjSigXXkT_cBGNSdJe2eVGGuKW3E,7117
+stageflow/core/pipeline.py,sha256=efb1lL2jkZOWsBue3-e_ubyz7kLFEbXaNBg-7SFJ-A8,4867
+stageflow/core/session.py,sha256=fk_WUuy9gDlcB_CPlbumjaqfR-PKLX-QAX_VxnZ-yZg,15835
+stageflow/core/stage.py,sha256=rnJSvbFKY7J06LN-CvciElhbxZK7uMUT5xeaZpGAyJo,5884
+stageflow/core/utils.py,sha256=aemH1oakRQxRWREjzjWZ28CSlvp75320vwAtv3eYXx4,2207
+stageflow/docs/__init__.py,sha256=0-9v4s_MgVOR9Z2jNPspbPf4SWORJ0HDxdPN04Qa7RY,132
+stageflow/docs/html.py,sha256=DDtvCsjwAIEwg1MVUJ1p6jQM1uIQ2-QWK7Y-hXGUbLE,19319
+stageflow/docs/schema.py,sha256=1Hg_U7-OWVSn3y4Wp4TSbuKSxb0Hz8SHZBjLSmZ2JSc,1153
+stageflow/docs/schemas/pipeline.json,sha256=ZnLjk9jcVI8olq7oo23MPbDnWa0ouj5kZrAl-zK3Z4M,4073
+stageflow_framework-0.1.0.dist-info/METADATA,sha256=7fNsfkFtFxWpvAmOblyYb12JGg75YUl6RinNFJS3S8c,6369
+stageflow_framework-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+stageflow_framework-0.1.0.dist-info/top_level.txt,sha256=byrtG44gmksw0XJXpaoPbYl38Px2_9Ww2BcRDmjBVZ0,10
+stageflow_framework-0.1.0.dist-info/RECORD,,

stageflow_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stageflow_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stageflow