Skip to main content

​
Initialize the Client

from ai21 import AI21Client

client = AI21Client(api_key="YOUR_API_KEY")

​
Technical Troubleshooting Assistant

Challenge:
Support engineers often receive error codes from customers and must quickly identify the root cause. They typically need to search across scattered manuals, outdated notes, or legacy documentation, which is a slow process that delays issue resolution.

​
Baseline Chat Model (Without RAG)

When the model is prompted without access to contextual documents, it produces a general or incomplete answer, often missing key technical details. Input Prompt 
response = client.responses.create(
    model=["jamba-large"],
    input=[
        {"role": "user", "content": "What does error code E47 mean for the Model X air conditioner?"}
    ]
)

print(response.output_text)
Chat Model Output 
Error code E47 typically indicates a system malfunction or airflow issue. Check the filter or restart the unit.
⚠️ Issues Identified:
  • Lacks source attribution or evidence
  • Provides generic advice not aligned with the specific product version
  • Risks outdated or inaccurate troubleshooting guidance

​
AI21 Maestro with RAG (File Search Enabled)

When RAG is enabled with File Search, Maestro retrieves relevant technical documentation before generating a response, grounding the answer in the correct product data.

Before running the example:
Download the reference manual used in this example:
📄 air_conditioner_troubleshooting.pdf

Upload it to your File Library in Maestro. The document will be automatically indexed for File Search, allowing Maestro to retrieve the correct sections during troubleshooting.

Step 1: Upload a file (Python SDK) 
file_from_disk = client.library.files.create(
    file_path="/path/to/your/local/system_air_conditioner.pdf",  # Replace with your file path
    labels=["technical", "manual"]  # Example labels; can be any descriptive tags
)
Step 2: Use the file in a Maestro run 
response = client.beta.maestro.runs.create_and_poll(
    models=["jamba-large"],
    input=[
        {
            "role": "user",
            "content": """What does error code E47 mean for the Model X air conditioner? 
            Please provide recommended steps and safety guidance."""
        }
    ],
    tools=[
        {
            "type": "file_search",
            "labels": ["technical", "manual"],
        }
    ]
)

print(response.result)
Output Example: 
Error code E47 indicates a refrigerant pressure imbalance in Model X units manufactured after 2023.
Recommended actions:
1. Check the pressure sensor connection (see Section 4.2 of the Troubleshooting Manual).
2. Verify that firmware version 3.4 or later is installed.
Source: air_conditioner_troubleshooting.pdf, page 18
✅ Improvements:
  • Provides specific, accurate steps
  • References the correct documentation and version
  • Includes source attribution for validation and traceability

​
AI21 Maestro with RAG + Requirements

Adding requirements further improves reliability and structure by guiding the model to format and qualify its answers based on internal policy. Input Prompt 
response = client.beta.maestro.runs.create(
    model=["jamba-large"],
    input=[
        {
            "role": "user",
            "content": "What does error code E47 mean for the Model X air conditioner?"
        }
    ],
    tools=[
        {
            "type": "file_search",
            "labels": ["technical", "manual"]
        }
    ],
    requirements=[
        {
            "name": "GroundedAnswer",
            "description": "Use data from the attached manual; quote code labels and thresholds.",
            "is_mandatory": True
        },
        {
            "name": "OrderedDiagnosis",
            "description": "If multiple causes are possible, order them by likelihood and cross-check against sensor readings or phase conditions.",
            "is_mandatory": False
        },
        {
            "name": "SafetyFlagging",
            "description": "Flag and clearly label actions restricted to qualified technicians.",
            "is_mandatory": True
        },
        {
            "name": "StructuredOutput",
            "description": "End with a plain-language customer summary followed by a detailed technical checklist for field technicians.",
            "is_mandatory": False
        }
    ]
)

print(response.output_text)

​
Using data_sources

When you include data_sources, you explicitly tell Maestro to includethe data sources in the output. 
response = client.beta.maestro.runs.create(
    model=["jamba-large"],
    input=[
        {
            "role": "user",
            "content": """What does error code E47 mean for the Model X air conditioner?
Provide safety instructions and step-by-step technician guidance."""
        }
    ],
    tools=[
        {
            "type": "file_search",
            "labels": ["technical", "manual"]
        }
    ],
    requirements=[
        {
            "name": "GroundedAnswer",
            "description": "Use data from the attached manual; quote code labels and thresholds.",
            "is_mandatory": True
        },
        {
            "name": "OrderedDiagnosis",
            "description": "If multiple causes are possible, order them by likelihood and cross-check against sensor readings or phase conditions.",
            "is_mandatory": False
        },
        {
            "name": "SafetyFlagging",
            "description": "Flag and clearly label actions restricted to qualified technicians.",
            "is_mandatory": True
        },
        {
            "name": "StructuredOutput",
            "description": "End with a plain-language customer summary followed by a detailed technical checklist for field technicians.",
            "is_mandatory": False
        }
    ],
    include=["data_sources"]
)

print(response.output_text)
AI21 Maestro (RAG + Requirements) Output 
Error code E47 indicates a refrigerant pressure imbalance detected by the high-pressure sensor.

Safety notice: Only qualified HVAC technicians should adjust pressure or replace sensors.

Customer summary:
The system detected a pressure issue that prevents safe operation. Please allow a service technician to inspect the unit.

Technician checklist:
- Inspect high-pressure sensor connection (Manual §4.2)
- Check refrigerant level and valve state
- Verify firmware version 3.4+
- Clear error code after verification

Source: air_conditioner_troubleshooting.pdf
✅ Final Outcome
  • Combines document grounding with operational requirements
  • Produces structured, role-specific responses
  • Balances customer communication and technician detail

​
Requirements for Reproducing the Example

  • Download and upload the 📄 air_conditioner_troubleshooting.pdf file to your File Library.
  • Enable File Search in your Maestro configuration.
  • Use the Python SDK for consistency with other examples.
  • Ensure documents are up-to-date to maintain accuracy.