abstractflow 0.1.0__tar.gz → 0.3.1__tar.gz

abstractflow-0.3.1/CHANGELOG.md

@@ -0,0 +1,178 @@
+# Changelog
+
+All notable changes to AbstractFlow will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **AbstractCode UI event demo flows** (`web/flows/*.json`):
+  - `acagent_message_demo.json`: `abstractcode.message`
+  - `acagent_ask_demo.json`: durable ask+wait via `wait_event.prompt`
+  - `acagent_tool_events_demo.json`: `abstractcode.tool_execution` + `abstractcode.tool_result`
+- **Tool observability wiring improvements (Visual nodes)**:
+  - `LLM Call` exposes `tool_calls` as a first-class output pin (same as `result.tool_calls`) for easier wiring into `Tool Calls` / `Emit Event`.
+  - `Agent` exposes best-effort `tool_calls` / `tool_results` extracted from its scratchpad trace (post-run ergonomics).
+- **Pure Utility Nodes (Runtime-backed)**:
+  - `Stringify JSON` (`stringify_json`): Render JSON (or JSON-ish strings) into text with a `mode` dropdown (`none` | `beautify` | `minified`). Implementation delegates to `abstractruntime.rendering.stringify_json` for consistent host behavior.
+  - `Agent Trace Report` (`agent_trace_report`): Render an agent scratchpad (`node_traces`) into a condensed Markdown timeline of LLM calls and tool actions (full tool args + results, no truncation). Implementation delegates to `abstractruntime.rendering.render_agent_trace_markdown`.
+
+### Changed
+- **Run Flow modal (array parameters)**: Array pins now render as a Blueprint-style item list (add/remove items) with a "Raw JSON (advanced)" escape hatch for non-string arrays.
+
+### Fixed
+- **FlowRunner SUBWORKFLOW auto-drive**: `FlowRunner.run()` no longer hangs if the runtime registry contains only subworkflow specs (common in unit tests). It now falls back to the runner’s own root `WorkflowSpec` when resuming/bubbling parents.
+
+## [0.3.1] - 2026-02-04
+
+### Added
+- **User-facing documentation set** for public release:
+  - Core docs: `README.md`, `docs/getting-started.md`, `docs/architecture.md`, `docs/api.md`, `docs/faq.md`
+  - Repo policies: `CONTRIBUTING.md`, `SECURITY.md`, `ACKNOWLEDMENTS.md`
+  - Agentic index: `llms.txt`, `llms-full.txt`
+
+### Changed
+- **Documentation accuracy + structure**: refreshed docs to match the implemented code (VisualFlow portability, runtime wiring, CLI bundle tooling, web editor layout) and improved cross-references for first-time users.
+
+## [0.3.0] - 2025-01-06
+
+### Added
+- **VisualFlow Interface System** (`abstractflow/visual/interfaces.py`): Declarative workflow interface markers for portable host validation, enabling workflows to be run as specialized capabilities with known IO contracts
+  - `abstractcode.agent.v1` interface: Host-configurable prompt → response contract for running a workflow as an AbstractCode agent
+  - Interface validation with required/recommended pin specifications (provider/model/tools/prompt/response)
+  - Auto-scaffolding support: enabling `abstractcode.agent.v1` auto-creates `On Flow Start` / `On Flow End` nodes with required pins
+- **Structured Output Support**: Visual `LLM Call` and `Agent` nodes accept optional `response_schema` input pin (JSON Schema object) for schema-conformant responses
+  - New literal node `JSON Schema` (`json_schema`) to author schema objects
+  - New `JsonSchemaNodeEditor` UI component for authoring schemas in the visual editor
+  - Pin-driven schema overrides node config and enables durable structured-output enforcement via AbstractRuntime `LLM_CALL`
+- **Tool Calling Infrastructure**:
+  - Visual `LLM Call` nodes support optional **tool calling** via `tools` allowlist input (pin or node config)
+  - Expose structured `result` output object (normalized LLM response including `tool_calls`, `usage`, `trace_id`)
+  - Inline tools dropdown in node UI (when `tools` pin not connected)
+  - Visual `Tool Calls` node (`tool_calls`) to execute tool call requests via AbstractRuntime `EffectType.TOOL_CALLS`
+  - New pure node `Tools Allowlist` (`tools_allowlist`) with inline multi-select for workflow-scope tool lists
+  - Dedicated `tools` pin type (specialized `string[]`) for `On Flow Start` parameters
+- **Control Flow & Loop Enhancements**:
+  - New control node `For` (`for`) for numeric loops with `start`/`end`/`step` inputs and `i`/`index` outputs
+  - `While` node now exposes `index` output pin (0-based iteration count) and `item:any` output pin for parity with `ForEach`
+  - `Loop` (Foreach) now invalidates cached pure-node outputs per-iteration (fixes scratchpad accumulation)
+- **Workflow Variables**:
+  - New pure node `Variable` (`var_decl`) to declare workflow-scope persistent variables with explicit types
+  - New pure node `Bool Variable` (`bool_var`) for boolean variables with typed outputs
+  - New execution node `Set Variables` (`set_vars`) to update multiple variables in a single step
+  - New execution node `Set Variable Property` (`set_var_property`) to update nested object properties
+  - `Get Variable` (`get_var`) reads from durable `run.vars` by dotted path
+  - `Set Variable` (`set_var`) updates `run.vars` with pass-through execution semantics
+- **Custom Events** (Blueprint-style):
+  - `On Event` listeners compiled into dedicated durable subworkflows (auto-started, session-scoped)
+  - `Emit Event` node dispatches durable events via AbstractRuntime
+- **Run History & Observability**:
+  - New web API endpoints: `/api/runs`, `/api/runs/{run_id}/history`, `/api/runs/{run_id}/artifacts/{artifact_id}`
+  - UI "Run History" picker (🕘) to open past runs and apply pause/resume/cancel controls
+  - Run modal shows clickable **run id** pill (hover → copy to clipboard)
+  - Run modal header token badge reflects cumulative LLM usage across entire run tree
+  - WebSocket events include JSON-safe ISO timestamp (`ts`)
+  - Runtime node trace entries streamed incrementally over WebSocket (`trace_update`)
+  - Agent details panel renders live sub-run trace with expandable prompts/responses/errors
+- **Pure Utility Nodes**:
+  - `Parse JSON` (`parse_json`) to convert JSON/JSON-ish strings into objects
+  - `coalesce` (first non-null selection by pin order)
+  - `string_template` (render `{{path.to.value}}` with filters: json, join, trim)
+  - `array_length`, `array_append`, `array_dedup`
+  - `Compare` (`compare`) now has `op` input pin supporting `==`, `>=`, `>`, `<=`, `<`
+  - `get` (Get Property) supports `default` input and safer nested path handling (e.g. `a[0].b`)
+- **Memory Node Enhancements**:
+  - `Memorize` (`memory_note`) adds optional `location` input
+  - `Memorize` supports **Keep in context** toggle to rehydrate notes into `context.messages`
+  - `Recall` (`memory_query`) adds `tags_mode` (all/any), `usernames`, `locations` inputs
+- **Subflow Enhancements**:
+  - `Subflow` supports **Inherit context** toggle to seed child run's `context.messages` from parent
+  - `multi_agent_state_machine` accepts `workspace_root` parameter to scope agent file/system tools
+- **Visual Execution Defaults**:
+  - Default **LLM HTTP timeout** (7200s, overrideable via `ABSTRACTFLOW_LLM_TIMEOUT_S`)
+  - Default **max output token cap** (4096, overrideable via `ABSTRACTFLOW_LLM_MAX_OUTPUT_TOKENS`)
+- **UI/UX Improvements**:
+  - Run preflight validation panel with itemized "Fix before running" checklist
+  - Node tooltips available in palette and on-canvas (hover > 1s)
+  - Node palette exposed transforms (`trim`, `substring`, `format`) and math ops (`modulo`, `power`)
+  - Enhanced `PropertiesPanel` with structured output configuration
+  - Improved `RunFlowModal` with better input validation and error display
+  - JSON validation and error handling across executor and frontend (`web/frontend/src/utils/validation.ts`)
+
+### Changed
+- **Workflow-Agent Interface UX**: Enabling `abstractcode.agent.v1` auto-scaffolds `On Flow Start` / `On Flow End` pins (provider/model/tools)
+- **Memory Nodes UX**: `memory_note` labeled **Memorize** (was Remember) to align with AbstractCode `/memorize`
+- **Flow Library Modal**: Flow name/description edited via inline pencil icons (removed Rename/Edit Description buttons)
+- **Run Modal UX**:
+  - String inputs default to 3-line textarea
+  - Modal actions pinned in footer (body scrolls)
+  - No truncation of sub-run/memory previews (full content on demand)
+  - JSON panels (`Raw JSON`, `Trace JSON`, `Scratchpad`) syntax-highlighted
+- **Node Palette Organization**:
+  - Removed **Effects** category
+  - Added **Memory** category (memories + file IO)
+  - Added **Math** category (after Variables)
+  - Moved **Delay** to **Events**
+  - Split into **Literals**, **Variables**, **Data** (renamed from "Data" to **Transforms**)
+  - Reordered **Control** nodes (loops → branching → conditions)
+  - `System Date/Time` moved to **Events**
+  - `Provider Catalog` + `Models Catalog` moved to **Literals**
+  - `Tool Calls` moved from **Effects** to **Core** (reordered: Subflow, Agent, LLM Call, Tool Calls, Ask User, Answer User)
+- **Models Catalog**: Removed deprecated `allowed_models` input pin (in-node multi-select synced with right panel)
+- **Node/Pin Tooltips**: Appear after 2s hover, rendered in overlay layer (no clipping)
+- **Python Code Nodes**: Include in-node **Edit Code** button; editor injects "Available variables" comment block
+- **Execution Highlighting**: Stronger, more diffuse bloom for readability during runs; afterglow decays smoothly (3s), highlights only taken edges
+- **Data Edges**: Colored by data type (based on source pin type)
+
+### Fixed
+- **Recursive Subflows**: Visual data-edge cache (`flow._node_outputs`) now isolated per `run_id` to prevent stale outputs leaking across nested runs (fixes self/mutual recursion with pure nodes like `compare`, `subtract`)
+- **Durable Persistence**: `on_flow_start` no longer leaks internal `_temp` into cached node outputs (prevented `RecursionError: maximum recursion depth exceeded`)
+- **WebSocket Run Controls**: Pause/resume/cancel no longer block on per-connection execution lock (responsive during long-running LLM/Agent nodes)
+- **WebSocket Resilience**:
+  - Controls resilient to transient disconnects (can send with explicit `run_id`, UI reconnects-and-sends)
+  - Execution resilient to UI disconnects (dropped connection doesn't cancel in-flight run)
+- **VisualFlow Execution**: Ignores unreachable/disconnected execution nodes (orphan `llm_call`/`subflow` can't fail initialization)
+- **Loop Nodes**:
+  - `Split` avoids spurious empty trailing items (e.g. `"A@@B@@"`) so `Loop` doesn't execute extra empty iteration
+  - Scheduler-node outputs in WebSocket `node_complete`: Loop/While/For sync persisted `{index,...}` outputs to `flow._node_outputs` (UI no longer shows stale index)
+- **Pure Node Behavior**:
+  - `Concat` infers stable pin order (a..z) when template metadata missing
+  - `Set Variable` defaulting for typed primitives: `boolean/number/string` pins default to `false/0/""` instead of `None`
+- **Agent Nodes**: Reset per-node state when re-entered (e.g. inside `Loop` iterations) so each iteration re-resolves inputs
+- **Run Modal Observability**:
+  - WebSocket `node_start`/`node_complete` events include `runId` (distinguish root vs child runs)
+  - Visual Agent nodes start ReAct subworkflow in **async+wait** mode for incremental ticking
+  - Run history replay synthesizes missing `node_complete` events for steps left open in durable ledger
+- **Canvas Highlighting**: Robust to fast child-run emissions (race with `node_start` before `runId` state update fixed)
+- **WebSocket Subworkflow Waits**: Correctly close waiting node when run resumes past `WAITING(reason=SUBWORKFLOW)`
+- **Web Run History**: Reliably shows persisted runs regardless of server working directory (backend defaults to `web/runtime` unless `ABSTRACTFLOW_RUNTIME_DIR` set)
+- **Cancel Run**: No longer surfaces as `flow_error` from `asyncio.CancelledError` (treated as expected control-plane operation)
+- **Markdown Code Blocks**: "Copy" now copies original raw code (preserves newlines/indentation) after syntax highlighting
+
+### Technical Details
+- **13 commits**, **48 files changed**: 12,142 insertions, 368 deletions
+- New module: `abstractflow/visual/interfaces.py` (347 lines)
+- New UI component: `web/frontend/src/components/JsonSchemaNodeEditor.tsx` (460 lines)
+- New tests: `test_visual_interfaces.py`, `test_visual_agent_structured_output_pin.py`, `test_visual_llm_call_structured_output_pin.py`, `test_visual_subflow_recursion.py`
+- Compiler enhancements: Interface validation, per-run cache isolation, structured output pin support
+- Executor optimizations: Performance improvements for VisualFlow execution
+- 12 new example workflow JSON files in `web/flows/`
+
+### Notes
+- This repository includes the published Python package (`abstractflow/`) and a reference visual editor app (`web/`).
+
+## [0.1.0] - 2025-01-15
+
+### Added
+- Initial placeholder package to reserve PyPI name
+- Basic project structure and packaging configuration
+- Comprehensive README with project vision and roadmap
+- MIT license and contribution guidelines
+- CLI placeholder with planned command structure
+
+### Notes
+- This is a placeholder release to secure the `abstractflow` name on PyPI
+- No functional code is included in this version
+- Follow the GitHub repository for development updates and release timeline

{abstractflow-0.1.0 → abstractflow-0.3.1}/LICENSE

@@ -19,3 +19,5 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+

{abstractflow-0.1.0 → abstractflow-0.3.1}/MANIFEST.in

@@ -24,3 +24,5 @@ exclude .pytest_cache
 exclude build
 exclude dist
 exclude *.egg-info
+
+

abstractflow-0.3.1/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: abstractflow
+Version: 0.3.1
+Summary: Diagram-based AI workflow generation built on AbstractCore
+Author-email: AbstractFlow Team <contact@abstractflow.ai>
+Maintainer-email: AbstractFlow Team <contact@abstractflow.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lpalbou/AbstractFlow
+Project-URL: Documentation, https://abstractflow.readthedocs.io
+Project-URL: Repository, https://github.com/lpalbou/AbstractFlow
+Project-URL: Bug Tracker, https://github.com/lpalbou/AbstractFlow/issues
+Project-URL: Changelog, https://github.com/lpalbou/AbstractFlow/blob/main/CHANGELOG.md
+Keywords: ai,workflow,diagram,llm,automation,visual-programming,abstractcore,machine-learning
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: AbstractRuntime>=0.4.0
+Requires-Dist: abstractcore[tools]>=2.6.8
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: agent
+Requires-Dist: abstractagent>=0.2.0; extra == "agent"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.100.0; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.23.0; extra == "server"
+Requires-Dist: websockets>=11.0.0; extra == "server"
+Provides-Extra: ui
+Requires-Dist: streamlit>=1.28.0; extra == "ui"
+Requires-Dist: plotly>=5.15.0; extra == "ui"
+Requires-Dist: networkx>=3.1.0; extra == "ui"
+Provides-Extra: all
+Requires-Dist: abstractflow[agent,dev,server,ui]; extra == "all"
+Dynamic: license-file
+
+# AbstractFlow
+
+Diagram-based, **durable** AI workflows for Python.
+
+AbstractFlow provides:
+- A portable workflow format (`VisualFlow` JSON) and helpers to execute it from any host (`abstractflow.visual`).
+- A simple programmatic API (`Flow`, `FlowRunner`) backed by **AbstractRuntime**.
+- A reference visual editor app in `web/` (FastAPI backend + React frontend).
+
+Project status: **Pre-alpha** (`pyproject.toml`: `Development Status :: 2 - Pre-Alpha`). Expect breaking changes.
+
+## Capabilities (implemented)
+
+- Execute programmatic flows (`Flow` → `FlowRunner`) with a default in-memory runtime.
+- Execute portable `VisualFlow` JSON from any host process (`abstractflow.visual`).
+- Durable waits and resumption via AbstractRuntime (e.g. user/event/schedule waits).
+- Package a flow tree as a WorkflowBundle (`.flow`) via the CLI.
+- Author/run VisualFlows in the reference web editor (`web/`).
+
+Evidence (code): `abstractflow/runner.py`, `abstractflow/visual/executor.py`, `abstractflow/cli.py`, `web/backend/routes/ws.py`.
+
+## Docs
+
+- Start here: `docs/getting-started.md`
+- API reference: `docs/api.md`
+- VisualFlow format: `docs/visualflow.md`
+- Visual editor: `docs/web-editor.md`
+- CLI: `docs/cli.md`
+- FAQ: `docs/faq.md`
+- Architecture: `docs/architecture.md`
+- Docs index: `docs/README.md`
+
+## Installation
+
+```bash
+pip install abstractflow
+```
+
+Requirements: Python **3.10+** (`pyproject.toml`: `requires-python`).
+
+Optional extras:
+- Agent nodes (ReAct workflows): `pip install "abstractflow[agent]"`
+- Dev tools (tests/formatting): `pip install "abstractflow[dev]"`
+
+Notes:
+- `abstractflow` depends on `AbstractRuntime` and `abstractcore[tools]` (see `pyproject.toml`).
+- Some VisualFlow node types require additional packages (e.g. `memory_kg_*` nodes need `abstractmemory`).
+
+## Quickstart (programmatic)
+
+```python
+from abstractflow import Flow, FlowRunner
+
+flow = Flow("linear")
+flow.add_node("double", lambda x: x * 2, input_key="value", output_key="doubled")
+flow.add_node("add_ten", lambda x: x + 10, input_key="doubled", output_key="final")
+flow.add_edge("double", "add_ten")
+flow.set_entry("double")
+
+result = FlowRunner(flow).run({"value": 5})
+print(result)  # {"success": True, "result": 20}
+```
+
+## Quickstart (execute a VisualFlow JSON)
+
+```python
+import json
+from abstractflow.visual import VisualFlow, execute_visual_flow
+
+with open("my-flow.json", "r", encoding="utf-8") as f:
+    vf = VisualFlow.model_validate(json.load(f))
+result = execute_visual_flow(vf, {"prompt": "Hello"}, flows={vf.id: vf})
+print(result)  # {"success": True, "waiting": False, "result": ...}
+```
+
+If your flow uses subflows, load all referenced `*.json` into the `flows={...}` mapping (see `docs/getting-started.md`).
+
+## Visual editor (from source)
+
+The visual editor is a dev/reference app in `web/` (not shipped as a Python package on PyPI).
+
+```bash
+git clone https://github.com/lpalbou/AbstractFlow.git
+cd AbstractFlow
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[server,agent]"
+
+# Terminal 1: Backend (FastAPI)
+cd web && python -m backend --reload --port 8080
+
+# Terminal 2: Frontend (Vite)
+cd web/frontend && npm install && npm run dev
+```
+
+Open the frontend at http://localhost:3003 (default Vite port). See `docs/web-editor.md`.
+
+## CLI (WorkflowBundle `.flow`)
+
+```bash
+abstractflow bundle pack web/flows/ac-echo.json --out /tmp/ac-echo.flow
+abstractflow bundle inspect /tmp/ac-echo.flow
+abstractflow bundle unpack /tmp/ac-echo.flow --dir /tmp/ac-echo
+```
+
+See `docs/cli.md` and `abstractflow/cli.py`.
+
+## Related projects
+
+- AbstractRuntime (durable execution kernel): https://github.com/lpalbou/AbstractRuntime
+- AbstractCore (providers/models/tools): https://github.com/lpalbou/AbstractCore
+- AbstractAgent (ReAct/CodeAct): https://github.com/lpalbou/AbstractAgent
+
+## Changelog
+
+See `CHANGELOG.md`.
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## Security
+
+See `SECURITY.md`.
+
+## Acknowledgments
+
+See `ACKNOWLEDMENTS.md`.
+
+## License
+
+MIT. See `LICENSE`.

abstractflow-0.3.1/README.md

@@ -0,0 +1,133 @@
+# AbstractFlow
+
+Diagram-based, **durable** AI workflows for Python.
+
+AbstractFlow provides:
+- A portable workflow format (`VisualFlow` JSON) and helpers to execute it from any host (`abstractflow.visual`).
+- A simple programmatic API (`Flow`, `FlowRunner`) backed by **AbstractRuntime**.
+- A reference visual editor app in `web/` (FastAPI backend + React frontend).
+
+Project status: **Pre-alpha** (`pyproject.toml`: `Development Status :: 2 - Pre-Alpha`). Expect breaking changes.
+
+## Capabilities (implemented)
+
+- Execute programmatic flows (`Flow` → `FlowRunner`) with a default in-memory runtime.
+- Execute portable `VisualFlow` JSON from any host process (`abstractflow.visual`).
+- Durable waits and resumption via AbstractRuntime (e.g. user/event/schedule waits).
+- Package a flow tree as a WorkflowBundle (`.flow`) via the CLI.
+- Author/run VisualFlows in the reference web editor (`web/`).
+
+Evidence (code): `abstractflow/runner.py`, `abstractflow/visual/executor.py`, `abstractflow/cli.py`, `web/backend/routes/ws.py`.
+
+## Docs
+
+- Start here: `docs/getting-started.md`
+- API reference: `docs/api.md`
+- VisualFlow format: `docs/visualflow.md`
+- Visual editor: `docs/web-editor.md`
+- CLI: `docs/cli.md`
+- FAQ: `docs/faq.md`
+- Architecture: `docs/architecture.md`
+- Docs index: `docs/README.md`
+
+## Installation
+
+```bash
+pip install abstractflow
+```
+
+Requirements: Python **3.10+** (`pyproject.toml`: `requires-python`).
+
+Optional extras:
+- Agent nodes (ReAct workflows): `pip install "abstractflow[agent]"`
+- Dev tools (tests/formatting): `pip install "abstractflow[dev]"`
+
+Notes:
+- `abstractflow` depends on `AbstractRuntime` and `abstractcore[tools]` (see `pyproject.toml`).
+- Some VisualFlow node types require additional packages (e.g. `memory_kg_*` nodes need `abstractmemory`).
+
+## Quickstart (programmatic)
+
+```python
+from abstractflow import Flow, FlowRunner
+
+flow = Flow("linear")
+flow.add_node("double", lambda x: x * 2, input_key="value", output_key="doubled")
+flow.add_node("add_ten", lambda x: x + 10, input_key="doubled", output_key="final")
+flow.add_edge("double", "add_ten")
+flow.set_entry("double")
+
+result = FlowRunner(flow).run({"value": 5})
+print(result)  # {"success": True, "result": 20}
+```
+
+## Quickstart (execute a VisualFlow JSON)
+
+```python
+import json
+from abstractflow.visual import VisualFlow, execute_visual_flow
+
+with open("my-flow.json", "r", encoding="utf-8") as f:
+    vf = VisualFlow.model_validate(json.load(f))
+result = execute_visual_flow(vf, {"prompt": "Hello"}, flows={vf.id: vf})
+print(result)  # {"success": True, "waiting": False, "result": ...}
+```
+
+If your flow uses subflows, load all referenced `*.json` into the `flows={...}` mapping (see `docs/getting-started.md`).
+
+## Visual editor (from source)
+
+The visual editor is a dev/reference app in `web/` (not shipped as a Python package on PyPI).
+
+```bash
+git clone https://github.com/lpalbou/AbstractFlow.git
+cd AbstractFlow
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[server,agent]"
+
+# Terminal 1: Backend (FastAPI)
+cd web && python -m backend --reload --port 8080
+
+# Terminal 2: Frontend (Vite)
+cd web/frontend && npm install && npm run dev
+```
+
+Open the frontend at http://localhost:3003 (default Vite port). See `docs/web-editor.md`.
+
+## CLI (WorkflowBundle `.flow`)
+
+```bash
+abstractflow bundle pack web/flows/ac-echo.json --out /tmp/ac-echo.flow
+abstractflow bundle inspect /tmp/ac-echo.flow
+abstractflow bundle unpack /tmp/ac-echo.flow --dir /tmp/ac-echo
+```
+
+See `docs/cli.md` and `abstractflow/cli.py`.
+
+## Related projects
+
+- AbstractRuntime (durable execution kernel): https://github.com/lpalbou/AbstractRuntime
+- AbstractCore (providers/models/tools): https://github.com/lpalbou/AbstractCore
+- AbstractAgent (ReAct/CodeAct): https://github.com/lpalbou/AbstractAgent
+
+## Changelog
+
+See `CHANGELOG.md`.
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## Security
+
+See `SECURITY.md`.
+
+## Acknowledgments
+
+See `ACKNOWLEDMENTS.md`.
+
+## License
+
+MIT. See `LICENSE`.

abstractflow-0.3.1/abstractflow/__init__.py

@@ -0,0 +1,91 @@
+"""AbstractFlow - Multi-agent orchestration layer for the Abstract Framework.
+
+AbstractFlow enables composition of agents into pipelines and coordinates
+their execution via AbstractRuntime. It provides:
+
+- Flow: Declarative flow definition with nodes and edges
+- FlowRunner: High-level interface for running flows
+- compile_flow: Convert Flow to WorkflowSpec for direct runtime usage
+
+Example:
+    >>> from abstractflow import Flow, FlowRunner
+    >>>
+    >>> # Define a simple flow
+    >>> flow = Flow("my_pipeline")
+    >>> flow.add_node("step1", lambda x: x * 2, input_key="value", output_key="doubled")
+    >>> flow.add_node("step2", lambda x: x + 10, input_key="doubled", output_key="result")
+    >>> flow.add_edge("step1", "step2")
+    >>> flow.set_entry("step1")
+    >>>
+    >>> # Run the flow
+    >>> runner = FlowRunner(flow)
+    >>> result = runner.run({"value": 5})
+    >>> print(result)  # {'result': 20, 'success': True}
+
+For agent-based flows:
+    >>> from abstractflow import Flow, FlowRunner
+    >>> from abstractagent import create_react_agent
+    >>>
+    >>> planner = create_react_agent(provider="ollama", model="qwen3:4b")
+    >>> executor = create_react_agent(provider="ollama", model="qwen3:4b")
+    >>>
+    >>> flow = Flow("plan_and_execute")
+    >>> flow.add_node("plan", planner, output_key="plan")
+    >>> flow.add_node("execute", executor, input_key="plan")
+    >>> flow.add_edge("plan", "execute")
+    >>> flow.set_entry("plan")
+    >>>
+    >>> runner = FlowRunner(flow)
+    >>> result = runner.run({"context": {"task": "Build a REST API"}})
+"""
+
+__version__ = "0.3.1"
+__author__ = "Laurent-Philippe Albou"
+__email__ = "contact@abstractflow.ai"
+__license__ = "MIT"
+
+# Core classes
+from .core.flow import Flow, FlowNode, FlowEdge
+
+# Compiler
+from .compiler import compile_flow
+
+# Runner
+from .runner import FlowRunner
+
+# Adapters (for advanced usage)
+from .adapters import (
+    create_function_node_handler,
+    create_agent_node_handler,
+    create_subflow_node_handler,
+)
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    "__email__",
+    "__license__",
+    # Core classes
+    "Flow",
+    "FlowNode",
+    "FlowEdge",
+    # Compiler
+    "compile_flow",
+    # Runner
+    "FlowRunner",
+    # Adapters
+    "create_function_node_handler",
+    "create_agent_node_handler",
+    "create_subflow_node_handler",
+]
+
+
+def get_version() -> str:
+    """Get the current version of AbstractFlow."""
+    return __version__
+
+
+def is_development_version() -> bool:
+    """Check if this is a development version."""
+    return False  # Now implemented!

{abstractflow-0.1.0 → abstractflow-0.3.1}/abstractflow/__main__.py

@@ -8,3 +8,5 @@ from .cli import main
 
 if __name__ == "__main__":
     exit(main())
+
+

abstractflow-0.3.1/abstractflow/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""AbstractFlow adapters for converting handlers to workflow nodes."""
+
+from .function_adapter import create_function_node_handler
+from .agent_adapter import create_agent_node_handler
+from .subflow_adapter import create_subflow_node_handler
+
+__all__ = [
+    "create_function_node_handler",
+    "create_agent_node_handler",
+    "create_subflow_node_handler",
+]

abstractflow-0.3.1/abstractflow/adapters/agent_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.agent_adapter import *  # noqa: F401,F403

abstractflow-0.3.1/abstractflow/adapters/control_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.control_adapter import *  # noqa: F401,F403

abstractflow-0.3.1/abstractflow/adapters/effect_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.effect_adapter import *  # noqa: F401,F403

abstractflow-0.3.1/abstractflow/adapters/event_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.event_adapter import *  # noqa: F401,F403

abstractflow-0.3.1/abstractflow/adapters/function_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.function_adapter import *  # noqa: F401,F403

abstractflow-0.3.1/abstractflow/adapters/subflow_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.subflow_adapter import *  # noqa: F401,F403

abstractflow-0.3.1/abstractflow/adapters/variable_adapter.py

@@ -0,0 +1,5 @@
+"""Re-export: AbstractRuntime VisualFlow compiler adapter."""
+
+from __future__ import annotations
+
+from abstractruntime.visualflow_compiler.adapters.variable_adapter import *  # noqa: F401,F403