Skip to main content

​
Overview

The Magic::ask() method provides the simplest way to get answers from an LLM. It’s perfect for straightforward questions that require a concise response.

​
Basic Usage

1

Ask a simple question

The most basic usage returns a string answer:
use Mateffy\Magic;

$answer = Magic::ask('What is the capital of France?');
// -> "The capital of France is Paris."
By default, Magic::ask() returns a full sentence response.
2

Get concise answers

For short, direct answers without full sentences, set the $sentence parameter to false:
$answer = Magic::ask(
    'What is the capital of France?',
    sentence: false
);
// -> "Paris"
3

Customize the model

Specify a different model using the $model parameter:
$answer = Magic::ask(
    'What is the capital of France?',
    model: 'google/gemini-2.0-flash-lite'
);

​
Structured Data Extraction

You can also extract structured data by providing a JSON schema: 
use Mateffy\Magic;

$data = Magic::ask(
    'Extract the name and age from: John is 25 years old',
    schema: [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'age' => ['type' => 'integer'],
        ],
        'required' => ['name', 'age'],
    ]
);

// Returns: ['name' => 'John', 'age' => 25]
When using a custom schema, the response is automatically structured according to your schema definition.

​
Schema Type Options

The $schema parameter accepts standard JSON Schema types:
  • string - Default, returns a text response
  • integer - Returns a numeric value
  • boolean - Returns true/false
  • array - Returns an array of items
  • object - Returns a structured object

​
Example: Extracting Numbers

$year = Magic::ask(
    'When was the Eiffel Tower built?',
    schema: ['type' => 'integer'],
    sentence: false
);
// -> 1889

​
Example: Extracting Arrays

$cities = Magic::ask(
    'List the capital cities of France, Germany, and Italy',
    schema: [
        'type' => 'array',
        'items' => ['type' => 'string']
    ]
);
// -> ['Paris', 'Berlin', 'Rome']

​
How It Works

Under the hood, Magic::ask() from src/Magic.php:50:
  1. Creates a chat session with optimized system instructions
  2. Uses the extract tool to enforce the output schema
  3. Configures response style based on the $sentence parameter
  4. Returns the extracted value directly
Magic::ask() is designed for single-turn questions. For multi-turn conversations, use Magic::chat() instead.

​
Best Practices

  • Quick factual questions
  • Simple data extraction
  • One-off LLM queries
  • Prototyping and testing
  • Multi-turn conversations
  • Complex interactions requiring tools
  • Streaming responses
  • Custom message history
  • Magic::function() - For type-safe function-like LLM calls (src/Magic.php:117)
  • Magic::chat() - For full conversational interactions
  • Magic::extract() - For document extraction with custom strategies

​
Next Steps

Multimodal Chat

Learn to chat with images using Step\Image

Document Extraction

Extract structured data from documents

Build docs developers (and LLMs) love

Get started for freeTalk to us