RAG Use Cases

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.beta.maestro.runs.create_and_poll(
    model="jamba-large",
    input=[
        {
            "role": "user",
            "content": """After power-up, the display shows Ch and won’t allow operation. Explain the compressor preheating logic (2.5-hour heat, first-install requires 6 hours of power applied), the condition for Ch to clear, and what is or isn’t safe to bypass. Provide a customer-friendly ETA message."""
        }
    ]
)

print(response.result)

Chat Model Output

Display 'Ch' indicates the compressor is in preheating mode to protect it from damage. Preheating lasts 2.5 hours under normal conditions and 6 hours for first-time installation (requires continuous power). The 'Ch' clears automatically once preheating completes; do not bypass this safety process.

⚠️ 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 + Requirements

Adding requirements further improves reliability and structure by guiding the model to format and qualify its answers based on internal policy.

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
)

Input Prompt

response = client.beta.maestro.runs.create_and_poll(
    models=["jamba-large"],
    input=[
        {
            "role": "user",
            "content": "After power-up, the display shows Ch and won’t allow operation. Explain the compressor preheating logic (2.5-hour heat, first-install requires 6 hours of power applied), the condition for Ch to clear, and what is or isn’t safe to bypass. Provide a customer-friendly ETA message"
        }
    ],
    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.result)

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_and_poll(
    models=["jamba-large"],
    input=[
        {
            "role": "user",
            "content": """After power-up, the display shows Ch and won’t allow operation. Explain the compressor preheating logic (2.5-hour heat, first-install requires 6 hours of power applied), the condition for Ch to clear, and what is or isn’t safe to bypass. Provide a customer-friendly ETA message"""
        }
    ],
    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.result)

AI21 Maestro (RAG + Requirements) Output

Answer In Context
Compressor Preheating Logic
Preheating Duration: The compressor preheating logic involves a 2.5-hour heating period. This is necessary when the system is powered up and the display shows "Ch". During this time, the crankcase heater (CCH) heats the compressor.
First Installation Requirement: For first-time installations, it is required to apply power for 6 hours before operation to ensure proper preheating.
Condition for Clearing "Ch": The "Ch" indicator will clear once the compressor has been sufficiently heated for 2.5 hours, allowing the system to operate normally.
Possible Causes and Checks
Cause 1: Insufficient Preheating: Most likely, the system hasn't completed the 2.5-hour preheating. Ensure the CCH is operational.
Cause 2: Sensor Malfunction: Check the temperature sensor readings to ensure they reflect actual conditions.
Cause 3: Phase Error: Verify that the phase conditions are correct, as incorrect phase can prevent operation.
Safety and Bypass Considerations
Bypassing Preheating: It is not safe to bypass the preheating process as it is crucial for the protection of the compressor. Bypassing could lead to compressor damage or reduced efficiency.
Restricted Actions: Any attempt to bypass or modify the preheating logic should be performed only by qualified technicians.
Customer-Friendly ETA Message
"Your air conditioning system is currently in a preheating phase to ensure optimal performance and longevity. This process typically takes about 2.5 hours. For new installations, please ensure the system has been powered for at least 6 hours before operation. Thank you for your patience."

Technical Checklist for Field Technicians
Verify Power Application: Ensure that power has been applied for the required duration (6 hours for first-time installations).
Check Crankcase Heater (CCH): Confirm that the CCH is functioning correctly and heating the compressor.
Monitor "Ch" Indicator: Ensure the "Ch" indicator clears after the preheating period.
Sensor Readings: Cross-check temperature sensor readings to confirm proper heating.
Phase Conditions: Verify that phase conditions are correct and there are no phase errors.
Qualified Technician Actions: Any adjustments or bypassing of the preheating logic should be performed by a qualified technician only

✅ 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.

Getting Started

AI21 Maestro

Foundation Models

Private AI

AI21 Studio

Model Preparation

Usage

AI Ethics & Data Transperancy

Additional Resources

Initialize the Client

Technical Troubleshooting Assistant

Baseline Chat Model (Without RAG)

AI21 Maestro with RAG + Requirements

Using `data_sources`

Requirements for Reproducing the Example

​Initialize the Client

​Technical Troubleshooting Assistant

​Baseline Chat Model (Without RAG)

​AI21 Maestro with RAG + Requirements

​Using data_sources

​Requirements for Reproducing the Example

Initialize the Client

Technical Troubleshooting Assistant

Baseline Chat Model (Without RAG)

AI21 Maestro with RAG + Requirements

Using `data_sources`

Requirements for Reproducing the Example