Quick Start

This guide will help you get started with Maze Client SDK quickly. We assume you have already installed Maze following the installation guide.

Your First Workflow

Let’s create a simple workflow with two tasks that process text data.

Step 1: Define Your Tasks

First, define your task functions using the @task decorator:

from maze import MaClient, task

@task(
    inputs=["text"],
    outputs=["result"],
    resources={"cpu": 1, "cpu_mem": 128, "gpu": 0, "gpu_mem": 0}
)
def uppercase_text(params):
    """Convert text to uppercase"""
    text = params.get("text")
    return {"result": text.upper()}

@task(
    inputs=["text"],
    outputs=["result"],
    resources={"cpu": 1, "cpu_mem": 128, "gpu": 0, "gpu_mem": 0}
)
def add_prefix(params):
    """Add a prefix to the text"""
    text = params.get("text")
    return {"result": f"Processed: {text}"}

Step 2: Create a Workflow

Create a client and workflow instance:

# Connect to the Maze server
client = MaClient("http://localhost:8000")

# Create a new workflow
workflow = client.create_workflow()

Step 3: Add Tasks to the Workflow

Add tasks and define their dependencies by referencing task outputs:

# Add the first task
task1 = workflow.add_task(
    uppercase_text,
    inputs={"text": "hello world"}
)

# Add the second task that depends on the first
task2 = workflow.add_task(
    add_prefix,
    inputs={"text": task1.outputs["result"]}
)

Note

When you reference task1.outputs["result"] as input to task2, Maze automatically creates a dependency edge between them. This means task2 will only run after task1 completes.

Step 4: Run the Workflow

Execute the workflow and get results:

# Submit the workflow for execution
run_id = workflow.run()
print(f"Workflow started with run_id: {run_id}")

# Display results with automatic progress printing
result = workflow.show_results(run_id)

if result["workflow_completed"]:
    print(f"Workflow completed successfully!")
    print(f"Task results: {result['task_results']}")

Complete Example

Here’s the complete code in one place:

from maze import MaClient, task

# Define tasks
@task(
    inputs=["text"],
    outputs=["result"],
    resources={"cpu": 1, "cpu_mem": 128, "gpu": 0, "gpu_mem": 0}
)
def uppercase_text(params):
    text = params.get("text")
    return {"result": text.upper()}

@task(
    inputs=["text"],
    outputs=["result"],
    resources={"cpu": 1, "cpu_mem": 128, "gpu": 0, "gpu_mem": 0}
)
def add_prefix(params):
    text = params.get("text")
    return {"result": f"Processed: {text}"}

# Create client and workflow
client = MaClient("http://localhost:8000")
workflow = client.create_workflow()

# Add tasks
task1 = workflow.add_task(uppercase_text, inputs={"text": "hello world"})
task2 = workflow.add_task(add_prefix, inputs={"text": task1.outputs["result"]})

# Run and show results
run_id = workflow.run()
result = workflow.show_results(run_id)

if result["workflow_completed"]:
    print(f"Workflow completed!")
    print(f"Results: {result['task_results']}")

Expected Output

When you run this example, you should see output similar to:

Workflow started with run_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
🔗 Connected to server, starting workflow execution...
▶ Task started: 12345678
✓ Task completed: 12345678
  result: HELLO WORLD
▶ Task started: 87654321
✓ Task completed: 87654321
  result: Processed: HELLO WORLD
✅ Workflow execution completed!

Workflow completed!
Results: {
    'task_id_1': {'result': 'HELLO WORLD'},
    'task_id_2': {'result': 'Processed: HELLO WORLD'}
}

Next Steps

Now that you’ve created your first workflow, you can:

Learn more about maclient to understand different workflow patterns
Explore the maclient_api for detailed API documentation
Try creating more complex workflows with parallel execution
Experiment with different resource configurations for your tasks

Key Concepts to Remember

Tasks: Define your processing logic using the @task decorator
Workflows: Container for tasks and their dependencies
Automatic Dependencies: Referencing task outputs automatically creates edges
Run ID: Each workflow execution gets a unique run_id for result retrieval
Multiple Runs: Same workflow can be run multiple times with independent results
Result Methods: Use show_results(run_id) for formatted output or get_results(run_id) for raw messages
Client-side Caching: Results are cached automatically for efficient repeated queries