Running & Inspecting Flows¶

Running a Flow¶

From the CLI¶

The simplest way to execute a flow:

hbia run flows/create_user.yaml --handlers vertices

flows/create_user.yaml — Path to the flow definition file.
--handlers vertices — Python module where handler functions live. HBIA imports them to resolve handler: paths.

From Python¶

For programmatic execution, use run_flow():

from honey_badgeria.back.runtime import run_flow
from honey_badgeria.back.dsl import load_graph_from_yaml

graph = load_graph_from_yaml("flows/create_user.yaml")

result = run_flow(
    graph,
    flow_name="create_user",
    handlers={
        "normalize": normalize_fn,
        "validate": validate_fn,
        "save": save_fn,
    },
    initial_data={"name": "alice", "email": "alice@example.com"},
)

# Result contains all outputs from all vertices
print(result["save.user_id"])

Handler Resolution¶

Handlers can be provided in three ways:

Dictionary mapping — Map vertex names to callables:

handlers={"normalize": normalize_fn, "validate": validate_fn}

Dotted path strings — In YAML, handler: vertices.users.normalize is resolved at runtime via import.
Callable resolver — A function that receives a name and returns a callable:
```
handlers=lambda name: my_module.get_handler(name)
```

Execution Modes¶

Three independently configurable flags control how the engine executes vertices:

result = run_flow(
    graph,
    handlers={...},
    initial_data={...},
    cache_enabled=True,       # Use SHA-256 hash-based caching
    parallel_enabled=True,    # Run same-stage vertices in parallel
    async_enabled=False,      # Use async handlers
    max_workers=4,            # Thread pool size for parallel mode
)

Mode	Default	When to Use
Serial (default)	Enabled	Simplest, safest. Good for debugging.
Parallel	Disabled	CPU-bound work, independent vertices
Async	Disabled	I/O-bound work with many network calls

These can be combined:

Serial + Cache — Cache pure vertex results, execute one at a time.
Parallel + Sync — Run independent stages concurrently with threads.
Parallel + Async — Maximum throughput for I/O-heavy pipelines.

Configuration Priority¶

Settings are resolved in this order (highest priority first):

Per-call arguments — run_flow(..., cache_enabled=True)
Settings object — Settings(CACHE_ENABLED=True)
Environment variables — HBIA_CACHE_ENABLED=true
Defaults — False for all feature flags

Async Execution¶

For async handlers, use run_flow_async():

result = await run_flow_async(
    graph,
    handlers={
        "fetch": async_fetch_fn,
        "process": async_process_fn,
    },
    initial_data={...},
    async_enabled=True,
)

Inspecting Flows¶

Topology Inspection¶

See how HBIA will execute the flow — vertices, stages, and connections:

hbia inspect flows/payment.yaml

Output shows:

All vertices with their handlers and effects
Execution stages (which vertices run in which order)
Source vertices (entry points)
Sink vertices (terminal nodes)
Edge list

For machine-readable output:

hbia inspect flows/payment.yaml --json

Human-Readable Explanation¶

Get a narrative description of the flow:

hbia explain flows/payment.yaml

The explainer produces a readable summary including vertex count, edge count, sources, sinks, execution stages, and the complete edge list.

Listing All Flows¶

hbia flow-list

Lists all flow definitions found in the project's configured flow directory.

Visualization¶

ASCII Art¶

ASCII visualization that works in any terminal:

hbia viz flows/payment.yaml --ascii

╔═══════════════════════════════════════════════════════╗
║  HBIA DAG
║  flows: payment
║  4 vertices · 3 edges
╚═══════════════════════════════════════════════════════╝

  ┌── Step 1  ─────────────────────────────────────────┐
  │  ▶ validate_card  → validate
  └────────────────────────────────────────────────────┘
       ↓  reserve_funds

  ┌── Step 2  ─────────────────────────────────────────┐
  │     reserve_funds  → reserve
  └────────────────────────────────────────────────────┘
       ↓  charge

  Connections
  ─────────────────────────────────────────────────────
  validate_card  ──▶  reserve_funds
  reserve_funds  ──▶  charge
  charge         ──▶  confirm

Graphviz¶

For proper graphical rendering (requires the viz extra):

hbia viz flows/payment.yaml

This generates SVG/PNG files using Graphviz. HBIA auto-detects which renderer is available — if Graphviz is installed, it uses that. Otherwise, it falls back to ASCII.

You can also render programmatically:

from honey_badgeria.visualization import DagVisualizer

viz = DagVisualizer(graph)
svg = viz.render(output="graph", title="Payment Flow")

Validation & Linting¶

DSL Validation¶

Checks YAML structure, required fields, and reference integrity:

hbia validate flows/payment.yaml

Graph Validation¶

Checks the constructed graph for structural issues:

hbia graph-validate flows/payment.yaml

Catches:

Cycles — DAGs cannot have circular dependencies.
Missing edge endpoints — References to vertices that don't exist.
Disconnected atomic groups — Atomic group members must form a connected subgraph.

Linting¶

Best-practice checks for AI-friendly graph definitions:

hbia lint flows/
hbia lint flows/ --strict    # Treat warnings as errors

Lint codes:

Code	Severity	Issue
`E001`	Error	Vertex referenced in `next` not defined
`E002`	Error	Flow has zero edges (disconnected)
`W001`	Warning	Missing `effect` field
`W002`	Warning	Missing `version` field
`W003`	Warning	Missing `handler` field
`W005`	Warning	Missing `outputs` declaration
`W006`	Warning	Vertex name not in `snake_case`
`W007`	Warning	Single-vertex flow (incomplete pipeline)

Health & Diagnostics¶

Health Check¶

Scan for tech debt and structural issues across your project:

hbia health

Doctor¶

Verify your environment is correctly set up:

hbia doctor

Checks Python version, installed packages, available extras, and configuration validity.

What's Next?¶

Testing Flows