This example demonstrates how to create and execute distributed tasks using Blazing Flow.
You'll learn how to:
- Initialize a Blazing Flow application
- Define steps and workflows
- Execute workflows with `app.run()` or direct invocation
- Wait for results with `.wait_result()`
- Proper resource cleanup

Basic Task Execution

Multi-step orchestration - the foundation of distributed workflows — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Basic Workflow

Filter rows and transform fields in a single Blazing step — lightweight inline data processing without a pipeline.

Data Processing Step

Multi-stage data pipeline with cleaning and normalization — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Data Transformation Workflow

This is the simplest possible Blazing Flow application. It demonstrates how to:
- Create a basic Blazing app
- Define a simple step and workflow
- Publish to the execution engine
- Execute and return a response

Hello World

Deploy ML models with Core infrastructure, orchestrate inference with Flow, and run predictions in Flow Sandbox — uses HTTPX.

ML Inference Pipeline

Parallel execution with asyncio.gather for concurrent processing — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Multi-Branch Workflow

Learn how to execute multiple tasks in parallel to dramatically improve throughput.
This example shows you how to:
- Create batch tasks efficiently
- Achieve 4-10x speedup with parallelization
- Optimize for different workload sizes
- Monitor concurrency levels

Parallel Execution

The simplest possible Blazing Flow example - a single processing step — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Simple Step

Basic arithmetic operations in a distributed step — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Step with Math

Protect endpoints with custom authentication (JWT, API keys, OAuth) — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

API with Authentication

The simplest possible endpoint: expose a workflow as a public HTTP API Built with uvicorn on Blazing Flow's distributed worker infrastructure.

Basic Calculator API

Process multiple items concurrently with result aggregation Built with uvicorn on Blazing Flow's distributed worker infrastructure.

Batch Processing API

Proper error handling with custom error responses Built with uvicorn on Blazing Flow's distributed worker infrastructure.

Error Handling in APIs

Expose a multi-step workflow that processes data through several stages Built with uvicorn on Blazing Flow's distributed worker infrastructure.

Multi-Step Data Pipeline API

Organize multiple endpoints with different paths and versions Built with FastAPI, uvicorn on Blazing Flow's distributed worker infrastructure.

Multiple Endpoints with Different Paths

Enable WebSocket for real-time progress updates from long-running workflows — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

WebSocket Real-Time Updates

Fetch data from multiple sources and aggregate into summary statistics — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Aggregating Results

Pass PyArrow Tables between steps — zero-copy columnar transfers with type-safe Arrow compute operations — uses Apache Arrow.

PyArrow DataFrames

Download, parse, validate, and import CSV files from cloud storage — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

CSV Import Pipeline

Complete Extract-Transform-Load pipeline for data warehousing — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

ETL Pipeline

Validate, enrich, and store incoming events with multi-step processing — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Event Processing Pipeline

When processing DataFrames larger than 1MB, Blazing automatically uses Apache Arrow Flight for 3-5x faster data transfer. This example shows how to work with large datasets without any special configuration - the optimization happens automatically.

Large DataFrame Processing with Arrow Flight

Distributed map-reduce for processing large datasets in chunks — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Map-Reduce Pattern

Generate PDF documents from templates with data from multiple sources — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

PDF Generation Workflow

Handle transient failures with automatic retry and exponential backoff — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Retry Logic with Exponential Backoff

Prevent workflows from hanging with asyncio.wait_for timeouts — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Timeout Handling

Validate input data and handle errors gracefully in workflows — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Validation & Error Handling

Blazing automatically optimizes execution by using different worker pools. Use `step_type='BLOCKING'` for CPU-intensive work and default (NON_BLOCKING) for I/O-bound operations. This prevents CPU tasks from blocking async I/O operations — uses HTTPX, NumPy.

CPU vs I/O Optimization with Worker Types

Fetch data from multiple sources in parallel, then combine results — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Fan-Out / Fan-In Pattern

Process multiple items concurrently with asyncio.gather — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Parallel Data Processing

Control concurrency with asyncio.Semaphore for rate limiting — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Rate-Limited API Calls

Implement a cache-aside pattern with Redis — check cache, compute on miss, store result, serve on hit.

Cache Service

This example demonstrates the connector pattern used in production Blazing
applications. Connectors provide a standardized way to interact with external
services (REST APIs, databases, etc.) with built-in features:

- Connection pooling
- Throttling and rate limiting
- Authentication management
- Health checks

**Pattern:**
1. Define connector configurations
2. Create a service that receives connector_instances
3. Service methods use connectors to access external resources

Connector Integration Patterns

Connect to PostgreSQL and perform database operations with SQLAlchemy — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Database Service

Drain an email queue in configurable batches using Redis LIST operations — rate-limited bulk sending.

Email Queue Processor

Send transactional emails via SMTP using a Blazing service — templating, retries, and delivery confirmation.

Email Service

Process GitHub webhooks with signature validation and event handling — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

GitHub Webhook Handler

Send notifications across email, SMS, and push channels simultaneously — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Multi-Channel Notification

Call external REST APIs with httpx and handle responses — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

REST API Service

Handle Stripe payment webhooks with signature verification — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Stripe Payment Webhook

This example demonstrates batch processing patterns inspired by financial data
pipelines. Process hundreds of stocks efficiently with:

- Batch processing with configurable sizes
- Throttling to respect API rate limits
- Resilient error handling (partial failures don't stop the batch)
- Progress tracking and reporting

**Use Cases:**
- Daily stock price updates
- Portfolio rebalancing workflows
- Market data synchronization
- Financial indicator calculations

Batch Stock Processing

Batch delete expired database records on a schedule — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Cleanup Expired Records

Scheduled job to generate and distribute daily reports via email — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Daily Report Generation

Process event streams from Kafka in batches with aggregation — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Event Stream Processor

Monitor system health across database, cache, and external APIs — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Health Check Workflow

This example demonstrates how to organize large Blazing applications using
the modular registration pattern. Instead of defining all steps and workflows
in a single file, you can split them into domain-specific modules.

**Pattern:**
```python
# In main.py:
app = Blazing(...)
register_trading_module(app)
register_analytics_module(app)
register_reporting_module(app)
await app.publish()
```

**Benefits:**
- Clean separation of concerns
- Domain-driven design
- Easy to test individual modules
- Scalable codebase organization
- Conditional feature registration

Modular Registration Pattern

User code making concurrent service calls for performance — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Sandbox: Async Service Calls

The simplest sandbox example: let users write transformation logic while your infrastructure stays protected — uses WebAssembly.

Sandbox: Basic User-Provided Transform

Let user code process data while keeping database credentials safe — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Sandbox: Service Bridge with Database

Safely run different tenants' code in isolated sandboxes — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Sandbox: Multi-Tenant Data Processing

Let users integrate with external APIs while keeping API keys safe — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Sandbox: Service Bridge with REST APIs

Examples of malicious code that fails in the sandbox — demonstrates Blazing Flow's distributed step execution model with typed inputs and structured outputs.

Sandbox: Security Validation

The `sandboxed=True` parameter runs your step in a WebAssembly sandbox with complete isolation. Perfect for executing user-provided code in multi-tenant platforms - the code has zero access to your infrastructure, network, or filesystem.

Sandboxed Step Execution

This example shows how to build a trading strategy platform with two sides:

**YOUR SIDE (Platform Owner):**
- Define services your users can access (MarketDataService)
- Define a workflow that uses run_sandboxed() to execute user code
- Register with Blazing and publish

**YOUR USER'S SIDE (End Users):**
- Write strategy functions using your services
- Submit code as a string
- Get results back safely

**Security Model (5 Layers - ALL HANDLED BY run_sandboxed()):**
1. AST validation - blocks dangerous imports/builtins
2. Cryptographic signing - HMAC-SHA256 prevents tampering
3. Signature verification - server validates before execution
4. Bytecode validation - blocks dangerous opcodes
5. Pyodide WASM sandbox - no network/filesystem access

Trading Strategy Sandbox

Demonstrates three equivalent patterns for invoking workflows and retrieving results: wait_result() one-liner, handle.result() for deferred fetch, and run() by name for string-based dispatch.

API Execution Patterns

Use @batched to auto-collect individual step calls into GPU-efficient batches — transparent to callers.

Batched Steps

Shows how registered workflows become callable attributes on the app object, enabling natural invocation syntax like app.my_workflow(x=10).wait_result() without string-based dispatch.

Callable Workflows

Demonstrates how to register steps, workflows, and services using decorators, then use the async context manager (async with app:) to cleanly manage service lifecycle and cleanup.

Decorators and Context Manager

Call @app.step and @app.workflow decorated functions as plain Python — no backend, no publish(), no infrastructure required. The recommended pattern for unit testing and local development.

Direct Function Call

Demonstrates the synchronous API for running workflows by name — app.publish_sync() and app.run_sync('workflow_name', **kwargs) — for use in non-async calling contexts.

run_sync by Name

Demonstrates SyncBlazing — the fully synchronous Blazing client — for workflows that must run without any async/await in the calling code, such as scripts and synchronous web frameworks.

SyncBlazing Quickstart

Shows how to use wait_result_sync() on a workflow execution handle for blocking result retrieval in synchronous contexts — useful when mixing sync and async code in the same application.

wait_result_sync Helper

Demonstrates handle lifecycle methods: handle.wait() to block until completion, handle.wait_result() to retrieve the return value, and handle.cancel() to abort an in-flight workflow execution.

Workflow Handle wait()/cancel()

Shows how to pin specific service versions when registering a workflow using the version_pins parameter, ensuring stable deployments by preventing automatic service upgrades from affecting a workflow.

Workflow Version Pins

Demonstrates a sandboxed step calling a trusted service in the same workflow — a cross-boundary pattern where Pyodide-isolated code accesses a trusted service via the services= injection mechanism.

Depth Across Boundaries

Shows how to query the GET /v1/metrics/depth HTTP endpoint after running a workflow to retrieve operations_scanned and other depth statistics for monitoring step execution depth — uses HTTPX.

Depth Metrics API

Demonstrates querying depth statistics (max_depth, avg_depth, depth_distribution) from the Blazing metrics API after running workflows to understand step nesting patterns — uses HTTPX.

Depth Statistics Metrics

Creates a simple parent workflow calling a single child step to demonstrate Blazing's depth tracking — how the system records parent-child relationships between workflow and step executions.

Depth Tracking Basics

Builds a chain of three steps where each calls the previous (step_c → step_b → step_a) to demonstrate how Blazing tracks and records multi-level step depth across a call chain.

Depth Tracking Chain

Routes trusted and sandboxed steps to different executors within one workflow — trusted NON-BLOCKING steps run in the main executor while sandboxed NON-BLOCKING steps run in Pyodide isolation.

Mixed Executor Routing

Blends a CPU-bound BLOCKING step and an async I/O-bound step in a single workflow using asyncio.gather, demonstrating how Blazing routes different load profiles to appropriate executor pools.

Mixed Load Profile

Implements a workflow-driven state machine using a while loop — each iteration calls a step that advances the state until a terminal condition is reached, demonstrating looping patterns in Blazing.

State Machine Loop

Demonstrates behavior differences between trusted and sandboxed NON-BLOCKING workers by running the same input through both and comparing results — trusted steps run in the main process, sandboxed in Pyodide.

Worker Type Isolation

Runs all four worker type combinations — trusted BLOCKING, trusted NON-BLOCKING, sandboxed BLOCKING, and sandboxed NON-BLOCKING — in one workflow to demonstrate how step_type and sandboxed flags control executor routing.

Worker Types Overview

One workflow, four worker types — trusted sync (BLOCKING), trusted async (NON_BLOCKING), and two sandboxed async (NON_BLOCKING_SANDBOXED) steps all calling the same MathOpsService, demonstrating that services['Name'] works identically across all executors.

Worker Types with Services

Executes a user-submitted expression string inside a sandboxed step with restricted builtins, demonstrating how to safely evaluate dynamic code while preventing access to dangerous Python built-in functions.

Dynamic Code Execution (Sandboxed)

Execute user-submitted functions through a 5-layer security pipeline: AST validation, HMAC signing, signature verification, bytecode inspection, and Pyodide sandbox isolation.

Dynamic Code Security

Declare outbound network rules on services — exact hostnames, wildcard subdomains, CIDR blocks, or deny-all — uses HTTPX.

Egress Policy

Runs a compute step inside the Pyodide WASM sandbox using @app.step(sandboxed=True), isolating the workload from the main executor process while still returning results to the workflow.

Isolated Execution

Demonstrates retry logic around sandboxed workloads using a try/except loop — if the sandboxed step raises an exception, the workflow waits and retries up to three times before propagating the error.

Isolated Execution with Retry

Shows how to install extra Python packages into the Pyodide sandbox using the sandbox_dependencies=['numpy'] parameter, making them available inside sandboxed steps without exposing them to trusted workers.

Pyodide Sandbox Dependencies

Fires five sandboxed compute tasks simultaneously using asyncio.gather to stress the Pyodide sandbox executor, demonstrating concurrent sandbox execution and verifying that all tasks complete correctly under parallel load.

Pyodide Parallel Stress

The simplest sandboxed step example: marks a step with @app.step(sandboxed=True) to run it in Pyodide WASM isolation, demonstrating the minimal configuration needed for sandbox execution.

Sandboxed Step Basics

Protect Blazing endpoints with a FastAPI middleware API key check.

Source: greenfield

API Key Middleware

Integrates a Blazing workflow into an ASGI server using create_asgi_app() and uvicorn.run(), exposing a /hello endpoint backed by a registered workflow for direct HTTP access.

ASGI Server Integration

Attach a custom exception handler to the ASGI app.

Source: greenfield Built with FastAPI, uvicorn on Blazing Flow's distributed worker infrastructure.

Custom Exception Handler

Creates an ASGI app from a Blazing workflow using @app.endpoint() and create_asgi_app(), making the workflow directly callable via HTTP through FastAPI or any Starlette-compatible ASGI server.

Framework Endpoints (ASGI)

Exposes a GET endpoint using @app.endpoint(path='/greet', method='GET') that reads URL query parameters and returns a greeting — demonstrates query param binding for Blazing HTTP endpoints — uses FastAPI, uvicorn.

GET Endpoint with Query Params

Mounts the Blazing ASGI sub-application at a /blazing path prefix inside a larger FastAPI app using api.mount(), allowing Blazing workflows and custom FastAPI routes to coexist in one server process.

Mount Blazing in FastAPI

Exposes both GET and POST endpoints in a single Blazing app — a GET /status endpoint for health checks and a POST /echo endpoint for request mirroring, demonstrating multi-method endpoint registration — uses uvicorn.

Multiple HTTP Methods

Exposes a Blazing workflow as a real HTTP endpoint using @app.endpoint() and create_asgi_app(), serving live HTTP requests via uvicorn — the foundation for production API deployment.

Real HTTP Endpoints

Use progress_bar to emit SSE updates while iterating.

Source: greenfield Built with uvicorn on Blazing Flow's distributed worker infrastructure.

Streaming Progress Bar

Serve a streaming FastAPI route alongside Blazing endpoints.

Source: greenfield

Streaming Sidecar Route

Stream progress updates from a workflow using SSE response_mode="stream".

Source: greenfield — uses uvicorn.

Streaming Workflow Progress

Register scheduled jobs with SchedulerConnector using cron expressions or fixed intervals.

Cron & Periodic Scheduler

Share state and pass messages between service instances with DictConnector (key-value store) and QueueConnector (async FIFO queue) — coordinating workers across deployments and tenants.

Distributed Dict & Queue

Use OpenAIConnector in services for chat, streaming, tool calling, and multi-turn conversations.

OpenAI LLM Connector

Uses LocalDictService to persist workflow state in an in-memory key-value store without external dependencies — ideal for local development and testing patterns that will use Redis in production.

Local Dict Connector

Registers two services (MathService and StringService) in a single workflow step, demonstrating how a step accesses multiple services via the services= dict injection and chains their results.

Local Multiple Services

Runs a two-step pipeline where compute_sum aggregates a list using MathService.add() and compute_product scales the result using MathService.multiply(), demonstrating multi-step service reuse.

Categories

Products

Difficulty

Local Service Multistep