Steps - LLM Magic

The Step class represents multi-modal messages that can contain multiple types of content including text, images, tool uses, and tool results. This is useful for complex interactions that combine different content types in a single message.

Step

A message containing an array of content items (text, images, tool uses, tool results). Location: src/Magic/Chat/Messages/Step.php:10

Constructor

role

Role

required

The role of the message sender (User, Assistant, or System)

content

array<ContentInterface>

required

Array of content items (Text, Image, ToolUse, or ToolResult instances)

Static Methods

user()

Create a user step message with content.

// With string content
Step::user('What is in this image?')

// With content array
Step::user([
    new Text('Analyze this image:'),
    Image::path('/path/to/image.jpg')
])

content

string|array<ContentInterface>

required

Either a string (converted to Text) or array of ContentInterface items

assistant()

Create an assistant step message.

// With string content
Step::assistant('I can see a cat in the image.')

// With content array
Step::assistant([
    new Text('Here is the analysis:'),
    ToolUse::make('analyze_image', ['url' => 'image.jpg'])
])

content

string|array<ContentInterface>

required

Either a string (converted to Text) or array of ContentInterface items

base64Image()

Create a user step with a base64-encoded image.

Step::base64Image($base64Data, 'image/jpeg')

base64Image

string

required

The base64-encoded image data

mime

string

required

The MIME type of the image (e.g., ‘image/jpeg’, ‘image/png’)

base64()

Alias for base64Image(). Create a user step with a base64-encoded image.

Step::base64($base64Data, 'image/png')

base64Image

string

required

The base64-encoded image data

mime

string

required

The MIME type of the image

Instance Methods

toArray()

Convert the step to an array representation.

$array = $step->toArray();
// ['role' => 'user', 'content' => [...]]

fromArray()

Create a Step instance from an array.

$step = Step::fromArray([
    'role' => 'user',
    'content' => [
        ['type' => 'text', 'text' => 'Hello'],
        ['type' => 'image', 'source' => [...]]
    ]
])

data

array

required

Array containing role and content data

Content Types

Content types implement the ContentInterface and represent different kinds of content within a Step message. Interface Location: src/Magic/Chat/Messages/Step/ContentInterface.php:8

Text

Text content within a step message. Location: src/Magic/Chat/Messages/Step/Text.php:7

Constructor

text

string

required

The text content

Static Methods

make()

Create a Text content instance.

Text::make('This is some text content')

text

string

required

The text content

fromArray()

Create from an array representation.

Text::fromArray(['text' => 'Hello world'])

data

array

required

Array with ‘text’ key

Usage Example

$step = Step::user([
    Text::make('Please analyze this:'),
    Text::make('Focus on the details.')
])

Image

Image content within a step message. Supports multiple input sources. Location: src/Magic/Chat/Messages/Step/Image.php:8

Constructor

imageBase64

string

required

The base64-encoded image data

mime

string

required

The MIME type of the image (e.g., ‘image/jpeg’, ‘image/png’, ‘image/webp’)

Static Methods

path()

Create an Image from a file path.

Image::path('/path/to/photo.jpg')

path

string

required

The file system path to the image

raw()

Create an Image from raw image contents.

Image::raw($imageContents, 'image/png')

contents

string

required

The raw image data

mime

string

required

The MIME type of the image

url()

Create an Image from a URL.

Image::url('https://example.com/image.jpg')

url

string

required

The URL of the image to fetch

disk()

Create an Image from a Laravel storage disk.

Image::disk('s3', 'uploads/photo.jpg')

disk

string

required

The storage disk name

path

string

required

The path on the disk

base64()

Create an Image from base64-encoded data.

Image::base64($base64String, 'image/jpeg')

base64

string

required

The base64-encoded image data

mime

string

required

The MIME type

fromArray()

Create from an array representation.

Image::fromArray([
    'source' => [
        'type' => 'base64',
        'media_type' => 'image/jpeg',
        'data' => $base64Data
    ]
])

data

array

required

Array with source information

Deprecated Methods

The following methods are deprecated but still available:

fromPath() - Use path() instead
fromContents() - Use raw() instead
fromUrl() - Use url() instead
fromDisk() - Use disk() instead

Usage Example

$step = Step::user([
    Text::make('What do you see in these images?'),
    Image::path('/photos/image1.jpg'),
    Image::url('https://example.com/image2.png')
])

ToolUse

Represents a tool use request within a step message. Location: src/Magic/Chat/Messages/Step/ToolUse.php:8

Constructor

call

ToolCall

required

The ToolCall instance containing the tool name, arguments, and ID

Static Methods

call()

Create a ToolUse from a ToolCall instance.

$toolCall = new ToolCall(
    name: 'search_database',
    arguments: ['query' => 'users'],
    id: 'call_123'
);
ToolUse::call($toolCall)

call

ToolCall

required

The tool call to wrap

make()

Create a ToolUse with inline parameters.

ToolUse::make(
    name: 'get_weather',
    arguments: ['city' => 'London'],
    id: 'call_456'
)

name

string

required

The name of the tool to use

arguments

array

default:"[]"

The arguments to pass to the tool

string

default:"null"

Optional unique identifier for the tool use

fromArray()

Create from an array representation.

ToolUse::fromArray([
    'call' => [
        'name' => 'search',
        'arguments' => ['q' => 'test'],
        'id' => 'call_789'
    ]
])

data

array

required

Array with ‘call’ key containing ToolCall data

Usage Example

$step = Step::assistant([
    Text::make('Let me search for that information.'),
    ToolUse::make('search', ['query' => 'Laravel Magic'])
])

ToolResult

Represents the result of a tool execution within a step message. Location: src/Magic/Chat/Messages/Step/ToolResult.php:8

Constructor

call

ToolCall

required

The original ToolCall that this result corresponds to

output

mixed

default:"null"

The result of the tool execution (can be string, array, or other data)

Static Methods

output()

Create a ToolResult with the execution output.

ToolResult::output($toolCall, ['results' => [...]])

call

ToolCall

required

The original tool call

output

mixed

required

The tool execution result

fromArray()

Create from an array representation.

ToolResult::fromArray([
    'call' => [
        'name' => 'search',
        'arguments' => ['q' => 'test'],
        'id' => 'call_123'
    ],
    'output' => 'Search results...'
])

data

array

required

Array with ‘call’ and ‘output’ keys

Usage Example

$step = Step::user([
    ToolResult::output(
        $toolCall,
        'Found 5 results matching your query.'
    )
])

Complete Example

Here’s a complete example showing how to use Steps with multiple content types:

use Mateffy\Magic\Chat\Messages\Step;
use Mateffy\Magic\Chat\Messages\Step\Text;
use Mateffy\Magic\Chat\Messages\Step\Image;
use Mateffy\Magic\Chat\Messages\Step\ToolUse;
use Mateffy\Magic\Chat\Messages\Step\ToolResult;
use Mateffy\Magic\Chat\Messages\ToolCall;

// User sends a multi-modal message
$userStep = Step::user([
    Text::make('Can you analyze this product image and check inventory?'),
    Image::path('/uploads/product.jpg')
]);

// Assistant responds with text and a tool use
$assistantStep = Step::assistant([
    Text::make('I can see the product. Let me check the inventory.'),
    ToolUse::make('check_inventory', ['sku' => 'PROD-123'])
]);

// User provides tool result
$toolCall = new ToolCall(
    name: 'check_inventory',
    arguments: ['sku' => 'PROD-123'],
    id: 'call_001'
);

$resultStep = Step::user([
    ToolResult::output($toolCall, ['in_stock' => true, 'quantity' => 45])
]);

// Assistant provides final response
$finalStep = Step::assistant([
    Text::make('The product is in stock with 45 units available.')
]);

Array Serialization

All Step content types can be converted to and from arrays:

$step = Step::user([
    Text::make('Hello'),
    Image::path('/image.jpg')
]);

$array = $step->toArray();
// [
//     'role' => 'user',
//     'content' => [
//         ['type' => 'text', 'text' => 'Hello'],
//         ['type' => 'image', 'source' => [...]]
//     ]
// ]

$restored = Step::fromArray($array);

Core API

Messages

Tools

Models & Providers

​Step

​Constructor

​Static Methods

​user()

​assistant()

​base64Image()

​base64()

​Instance Methods

​toArray()

​fromArray()

​Content Types

​Text

​Constructor

​Static Methods

make()

fromArray()

​Usage Example

​Image

​Constructor

​Static Methods

path()

raw()

url()

disk()

base64()

fromArray()

​Deprecated Methods

​Usage Example

​ToolUse

​Constructor

​Static Methods

call()

make()

fromArray()

​Usage Example

​ToolResult

​Constructor

​Static Methods

output()

fromArray()

​Usage Example

​Complete Example

​Array Serialization

Build docs developers (and LLMs) love

Step

Constructor

Static Methods

user()

assistant()

base64Image()

base64()

Instance Methods

toArray()

fromArray()

Content Types

Text

Constructor

Static Methods

Usage Example

Image

Constructor

Static Methods

Deprecated Methods

Usage Example

ToolUse

Constructor

Static Methods

Usage Example

ToolResult

Constructor

Static Methods

Usage Example

Complete Example

Array Serialization