API reference (high-level)¶

This page documents the public Python API surface of the abstractflow package.

Version¶

abstractflow.__version__ (string)
abstractflow.get_version() (helper)

Evidence: ../abstractflow/_version.py, ../abstractflow/init.py, ../pyproject.toml.

Programmatic flows¶

Flow IR¶

Flow, FlowNode, and FlowEdge are re-exported from AbstractRuntime so there is a single source of truth for semantics. These APIs are available with abstractflow[apple] or abstractflow[gpu].

from abstractflow import Flow, FlowNode, FlowEdge

Evidence: ../abstractflow/core/flow.py, ../abstractflow/init.py.

FlowRunner¶

FlowRunner compiles a Flow to a runtime WorkflowSpec and executes it using an AbstractRuntime Runtime. Available with abstractflow[apple] or abstractflow[gpu].

from abstractflow import FlowRunner

Key behaviors: - Creates a default in-memory runtime when you don’t provide one. - Normalizes completion output into {"success": bool, "result": ...}. - Returns {"waiting": True, ...} if the flow blocks on durable input. - Provides start(...), step(...), and resume(...) for host-driven execution loops.

Evidence: ../abstractflow/runner.py.

Compilation¶

Compilation functions are delegated to AbstractRuntime’s VisualFlow compiler and re-exported: Requires abstractflow[apple] or abstractflow[gpu].

from abstractflow import compile_flow

Advanced compilation helpers are also re-exported (typically used by hosts/tools, not most end users):

from abstractflow.compiler import compile_visualflow, compile_visualflow_tree

Evidence: ../abstractflow/compiler.py, ../abstractflow/init.py.

Visual flows (VisualFlow JSON)¶

Models¶

Pydantic models for the portable JSON format:

from abstractflow.visual import VisualFlow, VisualNode, VisualEdge, NodeType, PinType

Evidence: ../abstractflow/visual/models.py, ../abstractflow/visual/init.py.

Execute a VisualFlow¶

Use execute_visual_flow(...) for a simple “run and return a result” call:

Requires abstractflow[apple].

from abstractflow.visual import execute_visual_flow

For advanced use cases (custom stores/tool execution, or access to run state/ledger), build a runner:

Requires abstractflow[apple].

from abstractflow.visual import create_visual_runner

Utilities:

Requires abstractflow[apple] for runtime flow-spec conversion.

from abstractflow.visual import visual_to_flow

Evidence: ../abstractflow/visual/executor.py, getting-started.md.

Interfaces/contracts (optional)¶

If a host expects a specific IO contract, VisualFlows can declare interface markers in VisualFlow.interfaces.

from abstractflow.visual.interfaces import (
    ABSTRACTCODE_AGENT_V1,
    validate_visual_flow_interface,
    apply_visual_flow_interface_scaffold,
)

Evidence: ../abstractflow/visual/interfaces.py.

Workflow bundles (`.flow`)¶

WorkflowBundle helpers are available as a thin wrapper around AbstractRuntime’s bundle implementation: Requires abstractflow[apple].

from abstractflow.workflow_bundle import (
    pack_workflow_bundle,
    inspect_workflow_bundle,
    unpack_workflow_bundle,
)

Evidence: ../abstractflow/workflow_bundle.py, cli.md.

Gateway editor contract¶

The React editor is a thin client for AbstractGateway's versioned discovery contract:

GET /api/gateway/discovery/capabilities

It reads capabilities.contracts.flow_editor for VisualFlow CRUD/publish, run input schema, run start, ledger stream, artifact, and prompt-cache endpoints. The browser calls same-origin /api/gateway/*; the Flow static server/Vite/Python host proxy those requests to Gateway and inject the configured bearer token.

Evidence: ../web/frontend/src/hooks/useGatewayCapabilities.ts, ../web/frontend/src/utils/gatewayClient.ts, ../web/backend/main.py.

Adapters (advanced)¶

If you build custom hosts or want direct control over node handler construction, adapters are re-exported:

from abstractflow.adapters import (
    create_function_node_handler,
    create_agent_node_handler,
    create_subflow_node_handler,
)

Evidence: ../abstractflow/adapters/.

CLI¶

The abstractflow CLI entry point is declared in pyproject.toml (project.scripts) and implemented in: - ../abstractflow/cli.py

The CLI includes: - WorkflowBundle tools: abstractflow bundle ... - Visual editor backend runner (optional): abstractflow serve ... (requires abstractflow[apple] or abstractflow[gpu])

Evidence: ../pyproject.toml, ../abstractflow/cli.py, ../web/backend/cli.py.