​
What is AI21 Maestro’s Validated Output?

One of AI21 Maestro’s core capabilities is providing validated output, which addresses a critical problem that even advanced language models can struggle with - consistently following complex instructions that include multiple constraints.

AI21 Maestro ensures your language model’s outputs meet your specific requirements. Instead of relying on prompts to work reliably on their own, it uses computational resources to validate and refine outputs until they satisfy your constraints.

AI21 Maestro’s Validated Output addresses this by:

  • Validating outputs against your explicit requirements
  • Automatically fixes outputs that don’t meet the requirements
  • Provides a report on requirement fulfillment with detailed scores

​
Key Concepts

  • Requirements: Explicit constraints you define for your outputs (e.g., format, tone, content rules).
  • Budget: Controls computational effort and trade-offs—higher budgets use more resources (increasing cost and latency) to achieve better adherence to requirements (high/medium/low).
  • Requirements Report: Provides detailed scoring and feedback on how well each requirement was met.
  • Model Agnostic: Maestro works with both AI21’s first-party models and popular third-party models (e.g., GPT-4, Claude, Gemini)—choose the model that best fits your needs.

​
Basic Usage

Simple Example

import os
from ai21 import AI21Client

client = AI21Client(api_key=os.getenv("AI21_API_KEY"))

# create_and_poll() returns after the processing ended or the default timeout is passed
run = client.beta.maestro.runs.create_and_poll(
    input="Write a Python function to calculate fibonacci numbers",
    requirements=[
        {
            "name": "function_length",
            "description": "The function should be no more than 10 lines long"
        },
        {
            "name": "include_docstring",
            "description": "Include a Google-style docstring explaining the function"
        }
    ],
    budget="low",
    include=["requirements_result"]
)

# Result is available immediately when this returns
print(f"Result: {run.result}")
print(f"Requirements Score: {run.requirements_result.score}")

Understanding Asynchronous Execution

Maestro runs execute asynchronously in the backend. The create() method returns immediately with a run ID, while processing happens in the background:

import os
import time
from ai21 import AI21Client

client = AI21Client(api_key=os.getenv("AI21_API_KEY"))

# create() returns immediately, processing happens asynchronously
run = client.beta.maestro.runs.create(
    input="Write a marketing email",
    requirements=[{"name": "word_count", "description": "use 150-200 words"}],
    budget="low"
)

print(f"Run ID: {run.id}")  # Available immediately
print(f"Status: {run.status}")  # "in_progress"

# Poll for completion manually
while run.status == "in_progress":
    time.sleep(5)
    run = client.beta.maestro.runs.retrieve(run.id)

print(f"Final result: {run.result}")

​
Budget Levels

  • Low: Lower latency and lighter approach for getting a validated output
  • Medium: Balanced approach with moderate fix attempts
  • High: Maximum reliability with multiple fix attempts and parallel processing

​
Quick Tips

  1. Be Specific: Write clear, measurable requirements
  2. Start Small: Begin with 2-3 requirements and expand
  3. Use the Playground: Test your requirements in our web interface before implementing
  4. Check Scores: Review requirement scores to understand what’s working

​
Next Steps

  • Log in to AI21 Studio and experiment the Maestro Playground.
  • Set up a 3rd party model in AI21 Studio’s Model Integrations Page.
  • Read the Complete Walkthrough Guide for advanced usage patterns.
  • Explore the API Reference for full parameter details.
  • If you have any technical questions about Maestro, feel free to reach out to our support team via email or click the chat icon in the lower right corner.