A comprehensive guide to AI21 Maestro’s Validated Output capabilities.
AI21 Maestro is an intelligent agentic system designed to handle complex AI workflows.
This guide focuses specifically on the Validated Output, with practical examples ranging from basic usage to advanced scenarios.
Traditional LLM interactions often look like this:
Python
Copy
Ask AI
# Traditional approach - unreliableresponse = client.complete( prompt="""Write a Python function that: - Calculates fibonacci numbers - Is under 10 lines - Has proper docstrings - Uses descriptive variable names""")# Sometimes works perfectly, sometimes doesn't follow all constraints
Maestro’s instruction following enhancer uses a Generate → Validate → Fix cycle:
Generate: Creates initial response following your requirements
Validate: Evaluates and scores each requirement (0.0 to 1.0)
Fix: Refines output for requirements that scored < 1.0
Repeat: Continues until all requirements are met or budget is exhausted
This systematic approach to instruction following is part of Maestro’s broader agentic architecture, designed to handle complex workflows with reliability and precision.
The Input parameterYou can pass a string to Maestro as an input and it will be treated as a user message.
Python
Copy
Ask AI
from ai21 import AI21Clientclient = AI21Client(api_key="your-api-key")# The following function will block until the default timeout is reachedclient.beta.maestro.runs.create_and_poll( input="Explain quantum computing to a 10-year-old", requirements=[ { "name": "reading_level", "description": "Use simple words appropriate for a 10-year-old" }, { "name": "length", "description": "Keep explanation under 100 words" } ])
Alternatively you can pass an input as an array of message to support multiple turns in a conversation.
Python
Copy
Ask AI
input=[ { "role": "user", "content": "Explain quantum computing to a 10-year-old", }, { "role": "assistant", "content": 'Quantum computing is like a super-smart computer that uses tiny things called "qubits" instead of regular bits. While regular bits are like tiny switches that can be off (0) or on (1), qubits can be both at the same time! This helps quantum computers solve really hard problems much faster than normal computers by trying many possibilities at once', }, { "role": "user", "content": "Translate this to spanish", }, ],
requirements = [ { "name": "word_count", "description": "Response must be exactly between 150-200 words" }, { "name": "json_format", "description": "Output must be valid JSON with 'title' and 'content' fields" }, { "name": "no_technical_jargon", "description": "Avoid technical terms; explain concepts in plain English" }]
Requirements to Avoid:
Python
Copy
Ask AI
# Too vague{"name": "good_quality", "description": "Make it good"}# Contradictory{"name": "short_and_detailed", "description": "Be brief but very detailed"}# Unmeasurable{"name": "creative", "description": "Be creative and original"}
Enable detailed reporting by including requirements_result:
Python
Copy
Ask AI
run = client.beta.maestro.runs.create_and_poll( input="Write a product review for a smartphone", requirements=[ {"name": "word_count", "description": "use 200-250 words"}, {"name": "pros_and_cons", "description": "Include both pros and cons sections"}, {"name": "rating", "description": "End with a 1-5 star rating. For example: (★★★★☆)"} ], include=["requirements_result"], budget="low")print(f"Result: {run.result}")# Analyze the resultsprint(f"Overall Score: {run.requirements_result["score"]}")print(f"Completion Reason: {run.requirements_result["finish_reason"]}")print("Requirements Results:")for req in run.requirements_result["requirements"]: print(f" {req["name"]}: {req["score"]}") print(f" Issue: {req["reason"]}")
Sample Output Analysis
Python
Copy
Ask AI
# Example outputOverall Score: 0.67Completion Reason: Budget exhaustedword_count: 1.0pros_and_cons: 1.0rating: 0.6 Issue: Rating format is '4 out of 5' instead of star format (★★★★☆)
This tells you:
2 out of 3 requirements were perfectly met
The rating requirement needs refinement
You might need a higher budget or clearer requirement