abstractflow 0.1.0__tar.gz → 0.3.0__tar.gz

abstractflow-0.3.0/CHANGELOG.md

@@ -0,0 +1,174 @@
+# 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** (`abstractflow/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`.
+
+### 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.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 request → response contract for running a workflow as an AbstractCode agent
+  - Interface validation with required/recommended pin specifications (provider/model/tools/request/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 `abstractflow/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
+- In this monorepo, `abstractflow` contains a working Flow compiler/runner and VisualFlow execution utilities. Packaging/docs alignment is tracked in `docs/backlog/planned/093-framework-packaging-alignment-flow-runtime.md`.
+
+### Planned
+- Visual workflow editor with drag-and-drop interface
+- Real-time workflow execution and monitoring
+- Integration with AbstractCore for multi-provider LLM support
+- Custom node development SDK
+- Cloud deployment capabilities
+- Collaborative workflow development features
+
+## [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.0}/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.0}/MANIFEST.in

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

abstractflow-0.3.0/PKG-INFO

@@ -0,0 +1,413 @@
+Metadata-Version: 2.4
+Name: abstractflow
+Version: 0.3.0
+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 AI Workflow Generation**
+
+> **WIP** - Core workflow engine and visual editor are implemented and ready for use!
+
+AbstractFlow is an innovative Python library that enables visual, diagram-based creation and execution of AI workflows. Built on top of [AbstractCore](https://github.com/lpalbou/AbstractCore), it provides an intuitive interface for designing complex AI pipelines through interactive diagrams.
+
+## Monorepo note (Abstract Framework)
+
+This repository is the **Abstract Framework monorepo**. The implementation in `abstractflow/abstractflow/*` (Flow/FlowRunner/compiler) and `abstractflow/abstractflow/visual/*` (VisualFlow models + portable executor) is aligned with `docs/architecture.md`.
+
+Some parts of this README (and `abstractflow/pyproject.toml` / `abstractflow/CHANGELOG.md`) were originally written for a standalone placeholder package and may be out of sync with the monorepo implementation. See `docs/architecture.md` and planned backlog `docs/backlog/planned/093-framework-packaging-alignment-flow-runtime.md`.
+
+## 🎯 Vision
+
+AbstractFlow aims to democratize AI workflow creation by providing:
+
+- **Visual Workflow Design**: Create AI workflows using intuitive drag-and-drop diagrams
+- **Multi-Provider Support**: Leverage any LLM provider through AbstractCore's unified interface
+- **Real-time Execution**: Watch your workflows execute in real-time with live feedback
+- **Collaborative Development**: Share and collaborate on workflow designs
+- **Production Ready**: Deploy workflows to production with built-in monitoring and scaling
+
+## 🚀 Planned Features
+
+### Core Capabilities
+- **Diagram Editor**: Web-based visual editor for workflow creation
+- **Node Library**: Pre-built nodes for common AI operations (text generation, analysis, transformation)
+- **Custom Nodes**: Create custom nodes with your own logic and AI models
+- **Flow Control**: Conditional branching, loops, and parallel execution
+- **Data Transformation**: Built-in data processing and transformation capabilities
+
+### AI Integration
+- **Universal LLM Support**: Works with OpenAI, Anthropic, Ollama, and all AbstractCore providers
+- **Tool Calling**: Seamless integration with external APIs and services
+- **Structured Output**: Type-safe data flow between workflow nodes
+- **Streaming Support**: Real-time processing for interactive applications
+
+### Deployment & Monitoring
+- **Cloud Deployment**: One-click deployment to major cloud platforms
+- **Monitoring Dashboard**: Real-time workflow execution monitoring
+- **Version Control**: Git-based workflow versioning and collaboration
+- **API Generation**: Automatic REST API generation from workflows
+
+## 🏗️ Architecture
+
+AbstractFlow is built on a robust foundation:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Diagram UI    │    │  Workflow Engine │    │   AbstractCore  │
+│                 │────│                 │────│                 │
+│ Visual Editor   │    │ Execution Logic │    │ LLM Providers   │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+- **Frontend**: React-based diagram editor with real-time collaboration
+- **Backend**: Python workflow execution engine with FastAPI
+- **AI Layer**: AbstractCore for unified LLM provider access
+- **Storage**: Workflow definitions, execution history, and metadata
+
+## 🎨 Use Cases
+
+### Business Process Automation
+- Customer support ticket routing and response generation
+- Document analysis and summarization pipelines
+- Content creation and review workflows
+
+### Data Processing
+- Multi-step data analysis with AI insights
+- Automated report generation from raw data
+- Real-time data enrichment and validation
+
+### Creative Workflows
+- Multi-stage content creation (research → draft → review → publish)
+- Interactive storytelling and narrative generation
+- Collaborative writing and editing processes
+
+### Research & Development
+- Hypothesis generation and testing workflows
+- Literature review and synthesis automation
+- Experimental design and analysis pipelines
+
+## 🛠️ Technology Stack
+
+- **Core**: Python 3.10+ (aligns with AbstractRuntime)
+- **AI Integration**: [AbstractCore](https://github.com/lpalbou/AbstractCore) for LLM provider abstraction
+- **Web Framework**: FastAPI for high-performance API server
+- **Frontend**: React with TypeScript for the diagram editor
+- **Database**: PostgreSQL for workflow storage, Redis for caching
+- **Deployment**: Docker containers with Kubernetes support
+
+## 📦 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/lpalbou/AbstractFlow.git
+cd AbstractFlow
+
+# Install core dependencies
+pip install -e .
+
+# Or install with web editor dependencies
+pip install -e .[server]
+
+# Development installation (includes tests)
+pip install -e .[dev]
+```
+
+### Dependencies
+
+AbstractFlow requires:
+- Python 3.10+ (aligns with AbstractRuntime)
+- [AbstractRuntime](https://github.com/lpalbou/AbstractRuntime) - Workflow execution engine
+- [AbstractCore](https://github.com/lpalbou/AbstractCore) - LLM provider abstraction
+
+For the visual editor:
+- Node.js 18+ (for frontend)
+- FastAPI, uvicorn, websockets (for backend)
+
+## 🚀 Quick Start
+
+### Programmatic API
+
+```python
+from abstractflow import Flow, FlowRunner
+
+# Create a flow
+flow = Flow("my-workflow")
+
+# Add function nodes
+def double(x):
+    return x * 2
+
+def add_ten(x):
+    return x + 10
+
+flow.add_node("double", double, input_key="value", output_key="doubled")
+flow.add_node("add_ten", add_ten, input_key="doubled", output_key="result")
+
+# Connect nodes
+flow.add_edge("double", "add_ten")
+flow.set_entry("double")
+
+# Execute the flow
+runner = FlowRunner(flow)
+result = runner.run({"value": 5})
+print(result)  # {"value": 5, "doubled": 10, "result": 20}
+```
+
+### With Agents
+
+```python
+from abstractflow import Flow, FlowRunner
+from abstractagent import create_react_agent
+
+# Create an agent
+planner = create_react_agent(provider="ollama", model="qwen3:4b-instruct-2507-q4_K_M")
+
+# Create flow with agent node
+flow = Flow("agent-workflow")
+flow.add_node("plan", planner, input_key="task", output_key="plan")
+flow.set_entry("plan")
+
+# Run
+runner = FlowRunner(flow)
+result = runner.run({"task": "Plan a weekend trip to Paris"})
+print(result["plan"])
+```
+
+### Nested Flows (Subflows)
+
+```python
+# Create a subflow
+inner_flow = Flow("processing")
+inner_flow.add_node("step1", lambda x: x.upper())
+inner_flow.add_node("step2", lambda x: f"[{x}]")
+inner_flow.add_edge("step1", "step2")
+inner_flow.set_entry("step1")
+
+# Use subflow in parent flow
+outer_flow = Flow("main")
+outer_flow.add_node("preprocess", lambda x: x.strip())
+outer_flow.add_node("process", inner_flow)  # Subflow as node
+outer_flow.add_node("postprocess", lambda x: x + "!")
+outer_flow.add_edge("preprocess", "process")
+outer_flow.add_edge("process", "postprocess")
+outer_flow.set_entry("preprocess")
+
+runner = FlowRunner(outer_flow)
+result = runner.run({"input": "  hello  "})
+```
+
+## 🖥️ Visual Workflow Editor
+
+AbstractFlow includes a state-of-the-art web-based visual editor inspired by Unreal Engine Blueprints:
+
+### Features
+- **Blueprint-Style Nodes**: Drag-and-drop nodes with typed, colored pins
+- **Real-time Execution**: Watch workflows execute with live node highlighting via WebSocket
+- **Monaco Code Editor**: Write custom Python code directly in nodes
+- **Type-Safe Connections**: Pin type validation prevents incompatible connections
+- **Export/Import**: Save and load workflows as JSON
+
+### Blueprint-Style Pin Types
+
+| Type | Color | Shape | Description |
+|------|-------|-------|-------------|
+| **Execution** | White `#FFFFFF` | ▷ Triangle | Flow control |
+| **String** | Magenta `#FF00FF` | ○ Circle | Text data |
+| **Number** | Green `#00FF00` | ○ Circle | Integer/Float |
+| **Boolean** | Red `#FF0000` | ◇ Diamond | True/False |
+| **Object** | Cyan `#00FFFF` | ○ Circle | JSON objects |
+| **Array** | Orange `#FF8800` | □ Square | Collections |
+| **Agent** | Blue `#4488FF` | ⬡ Hexagon | Agent reference |
+| **Any** | Gray `#888888` | ○ Circle | Accepts any type |
+
+### Built-in Node Categories
+
+- **Core**: Agent, Subflow, Python Code
+- **Math**: Add, Subtract, Multiply, Divide, Modulo, Power, Abs, Round, Min, Max
+- **String**: Concat, Split, Join, Format, Uppercase, Lowercase, Trim, Substring, Length, Replace
+- **Control**: If/Else, Compare, NOT, AND, OR
+- **Data**: Get Property, Set Property, Merge Objects
+
+### Running the Visual Editor
+
+```bash
+# 1. Create virtual environment and install dependencies
+cd abstractflow
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Prefer editable installs over PYTHONPATH hacks so dependency wiring matches real installs.
+pip install -e "../abstractcore[tools]"
+pip install -e "../abstractruntime[abstractcore]"
+pip install -e "../abstractagent"
+pip install -e ".[server,agent]"
+
+# 2. Start backend server (run from web/ so `backend.*` is importable)
+cd web
+uvicorn backend.main:app --port 8080 --reload
+
+# 3. In a new terminal, start frontend dev server
+cd abstractflow/web/frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:3000 in your browser.
+
+**Production mode** (serve frontend from backend):
+```bash
+# Build frontend
+cd web/frontend && npm run build && cd ../..
+
+# Run backend only (serves frontend from dist/)
+cd web
+uvicorn backend.main:app --port 8080
+
+# Open http://localhost:8080
+```
+
+### Project Structure
+
+```
+web/
+├── backend/                    # FastAPI backend
+│   ├── main.py                 # App entry with CORS, static files
+│   ├── models.py               # Pydantic models (VisualNode, VisualEdge, VisualFlow)
+│   ├── routes/
+│   │   ├── flows.py            # Flow CRUD endpoints
+│   │   └── ws.py               # WebSocket for real-time execution
+│   └── services/
+│       ├── executor.py         # VisualFlow → AbstractFlow conversion
+│       ├── builtins.py         # 26 built-in function handlers
+│       └── code_executor.py    # Sandboxed Python execution
+├── frontend/                   # React + TypeScript frontend
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── Canvas.tsx      # React Flow canvas
+│   │   │   ├── NodePalette.tsx # Categorized node picker
+│   │   │   ├── PropertiesPanel.tsx
+│   │   │   ├── Toolbar.tsx     # Run/Save/Export/Import
+│   │   │   └── nodes/
+│   │   │       ├── BaseNode.tsx    # Blueprint-style node
+│   │   │       └── CodeNode.tsx    # Monaco editor node
+│   │   ├── hooks/
+│   │   │   ├── useFlow.ts      # Zustand state management
+│   │   │   └── useWebSocket.ts # Real-time updates
+│   │   ├── types/
+│   │   │   ├── flow.ts         # TypeScript types, PIN_COLORS
+│   │   │   └── nodes.ts        # Node templates
+│   │   └── styles/             # Dark theme CSS
+│   └── package.json
+└── requirements.txt            # Backend Python dependencies
+```
+
+## 🎯 Roadmap
+
+### Phase 1: Foundation ✅ Complete
+- [x] Core workflow engine (Flow, FlowNode, FlowEdge)
+- [x] Basic node types (Agent, Function, Subflow)
+- [x] Flow compilation to WorkflowSpec
+- [x] FlowRunner execution via Runtime
+- [x] State passing between nodes with dot notation
+
+### Phase 2: Visual Editor ✅ Complete
+- [x] Web-based diagram editor with React Flow
+- [x] Blueprint-style pins with colors and shapes
+- [x] 26 built-in function nodes (math, string, control, data)
+- [x] Custom Python code nodes with Monaco editor
+- [x] Export/Import JSON functionality
+- [x] Real-time execution updates via WebSocket
+
+### Phase 3: Advanced Features (Planned)
+- [ ] Custom node development SDK
+- [ ] Advanced flow control (loops, parallel execution)
+- [ ] Monitoring and analytics dashboard
+- [ ] Cloud deployment integration
+
+### Phase 4: Enterprise (Planned)
+- [ ] Enterprise security features
+- [ ] Advanced monitoring and alerting
+- [ ] Multi-tenant support
+- [ ] Professional services and support
+
+## 🤝 Contributing
+
+We welcome contributions from the community! Once development begins, you'll be able to:
+
+- Report bugs and request features
+- Submit pull requests for improvements
+- Create and share workflow templates
+- Contribute to documentation
+
+## 📄 License
+
+AbstractFlow will be released under the MIT License, ensuring it remains free and open-source for all users.
+
+## 🔗 Related Projects
+
+- **[AbstractCore](https://github.com/lpalbou/AbstractCore)**: The unified LLM interface powering AbstractFlow
+- **[AbstractCore Documentation](http://www.abstractcore.ai/)**: Comprehensive guides and API reference
+
+## 📞 Contact
+
+For early access, partnerships, or questions about AbstractFlow:
+
+- **GitHub**: [Issues and Discussions](https://github.com/lpalbou/AbstractFlow) (coming soon)
+- **Email**: Contact through AbstractCore channels
+- **Website**: [www.abstractflow.ai](http://www.abstractflow.ai) (coming soon)
+
+---
+
+**AbstractFlow** - Visualize, Create, Execute. The future of AI workflow development is here.
+
+> Built on top of [AbstractCore](https://github.com/lpalbou/AbstractCore)
+