Getting Started

Welcome to Zuma! 👋 This guide will help you understand what Zuma is and how to use it in your Python projects.

Zuma is a Python framework that helps you build and manage workflow pipelines. Think of it like a recipe book - you can define a series of steps (like a recipe's instructions), and Zuma will help you execute them in the right order, handle any errors, and make sure everything runs smoothly.

What is a Workflow?

A workflow in Zuma is like a set of instructions that need to be followed in a specific order. For example, imagine you're building a data processing application that needs to:

1. Download data from a server
2. Clean and format the data
3. Save the results to a database

Each of these tasks would be a "step" in your workflow, and Zuma helps you organize and run these steps efficiently.

Installation

You can install Zuma using your preferred Python package manager:

# Using pip
pip install zuma-workflow

# Using Poetry
poetry add zuma-workflow

# Using Pipenv
pipenv install zuma-workflow

# Using uv
uv add zuma-workflow

Verifying Installation

To verify that Zuma is installed correctly, open a Python shell and try importing it:

from zuma import ZumaWorkflow
print("Zuma is installed successfully!")

Core Concepts

Let's understand the main building blocks of Zuma. Don't worry if it seems complex at first - we'll break it down with examples!

1. Workflow (ZumaWorkflow)

A workflow is the main container that holds all your steps. Think of it as a project manager that:

• Keeps track of all the steps
• Makes sure they run in the right order
• Handles any problems that come up
• Shares information between steps

from zuma import ZumaWorkflow

# Create a simple workflow
workflow = ZumaWorkflow(
    name="My First Workflow",  # Give your workflow a descriptive name
    steps=[
        # We'll add steps here
    ]
)

The diagram above shows a simple linear workflow where steps execute one after another. Each step can:

2. Steps (ZumaActionStep)

Steps are the individual tasks in your workflow. Each step:

• Has a specific job to do
• Can access data from previous steps
• Can pass data to next steps
• Can handle errors if something goes wrong

from zuma import ZumaActionStep

class DownloadDataStep(ZumaActionStep):
    """A step that downloads data from somewhere"""
    
    async def execute(self, context):
        # This is where you put your step's logic
        print(f"[{self.name}] Downloading data...")
        
        # Simulate downloading data
        data = {"user": "john", "age": 30}
        
        # Return data for next steps to use
        return {"downloaded_data": data}

class ProcessDataStep(ZumaActionStep):
    """A step that processes the downloaded data"""
    
    async def execute(self, context):
        # Get data from previous step
        data = context.get("downloaded_data")
        
        # Process the data
        processed_data = {
            "name": data["user"].upper(),
            "age_in_months": data["age"] * 12
        }
        
        return {"processed_data": processed_data}

3. Context

The context is like a shared notebook that all steps can read from and write to. It helps steps communicate with each other by passing data along.

For example, if Step A downloads some data and Step B needs to process it:

# Step A puts data in the context
async def execute(self, context):
    data = download_something()
    return {"my_data": data}  # This goes into the context

# Step B reads data from the context
async def execute(self, context):
    data = context.get("my_data")  # Get data from Step A
    result = process_data(data)
    return {"processed": result}

Basic Usage

Let's put everything together and create your first complete workflow! We'll build a simple workflow that processes user data.

Step 1: Create Your Steps

from zuma import ZumaWorkflow, ZumaActionStep, ZumaRunner
import asyncio

class FetchUserStep(ZumaActionStep):
    """Gets user data (simulated)"""
    async def execute(self, context):
        # Simulate fetching user data
        print("Fetching user data...")
        await asyncio.sleep(1)  # Simulate network delay
        
        user_data = {
            "name": "Alice",
            "age": 25,
            "city": "New York"
        }
        return {"user": user_data}

class ValidateUserStep(ZumaActionStep):
    """Validates the user data"""
    async def execute(self, context):
        user = context.get("user")
        
        # Simple validation
        if not user.get("name"):
            raise ValueError("User must have a name!")
        
        if not isinstance(user.get("age"), int):
            raise ValueError("Age must be a number!")
        
        return {"validated": True}

class ProcessUserStep(ZumaActionStep):
    """Processes the validated user data"""
    async def execute(self, context):
        user = context.get("user")
        
        # Do some processing
        processed_data = {
            "full_name": user["name"].upper(),
            "age_group": "adult" if user["age"] >= 18 else "minor",
            "location": user["city"]
        }
        
        return {"processed_user": processed_data}

Step 2: Create and Run the Workflow

# Create the workflow
workflow = ZumaWorkflow(
    "User Processing Workflow",
    steps=[
        FetchUserStep("Fetch User"),
        ValidateUserStep("Validate User"),
        ProcessUserStep("Process User")
    ]
)

# Create a runner
runner = ZumaRunner()

# Run the workflow
async def main():
    result = await runner.run_workflow(workflow)
    print("\nWorkflow completed!")
    print("Final result:", result)

# Run it!
if __name__ == "__main__":
    asyncio.run(main())

Step 3: Understanding the Output

When you run this workflow, you'll see output like:

Fetching user data...
[Fetch User] ✓ Completed
[Validate User] ✓ Completed
[Process User] ✓ Completed

Workflow completed!
Final result: {
    'user': {'name': 'Alice', 'age': 25, 'city': 'New York'},
    'validated': True,
    'processed_user': {
        'full_name': 'ALICE',
        'age_group': 'adult',
        'location': 'New York'
    }
}

Workflow Components

Zuma provides several special components to handle common workflow patterns. Let's look at each one:

1. Parallel Steps (ZumaParallelAction)

When you have multiple steps that can run at the same time (like processing different files), use ZumaParallelAction:

from zuma import ZumaParallelAction

# Define steps that can run in parallel
parallel_steps = ZumaParallelAction(
    "Process Files",
    steps=[
        ProcessCSVStep("Process CSV"),
        ProcessJSONStep("Process JSON"),
        ProcessXMLStep("Process XML")
    ],
    max_concurrency=2  # Run 2 steps at a time
)

The diagram above shows how parallel steps work. The workflow:

• Splits into multiple parallel paths
• Executes steps concurrently (up to max_concurrency)
• Waits for all steps to complete before continuing

2. Conditional Steps (ZumaConditionalStep)

Sometimes you need different steps based on certain conditions. Use ZumaConditionalStep for this:

def check_data_size(context):
    """Decide which processing path to take"""
    data_size = len(context.get("data", []))
    return data_size > 1000

# Create a conditional step
processing_step = ZumaConditionalStep(
    "Choose Processing Path",
    condition=check_data_size,
    true_component=BatchProcessStep("Batch Process"),  # For large data
    false_component=SimpleProcessStep("Simple Process")  # For small data
)

The diagram above illustrates conditional workflow branching:

• A condition is evaluated (data size in this case)
• Based on the result, one of two paths is taken
• Both paths eventually merge back to continue the workflow

3. Error Handling

Zuma helps you handle errors gracefully. You can:

• Retry failed steps
• Provide fallback steps
• Continue workflow even if some steps fail

class RetryableStep(ZumaActionStep):
    """A step that might fail but can retry"""
    
    def __init__(self, name):
        super().__init__(
            name=name,
            retries=3,  # Try up to 3 times
            retry_delay=1.0  # Wait 1 second between retries
        )
    
    async def execute(self, context):
        try:
            result = await some_risky_operation()
            return {"data": result}
        except Exception as e:
            raise ZumaExecutionError(f"Operation failed: {str(e)}")

# Create workflow with error handling
workflow = ZumaWorkflow(
    "Fault Tolerant Workflow",
    steps=[RetryableStep("Risky Step")],
    continue_on_failure=True  # Continue even if steps fail
)