RAG Use Cases

Practical use cases where RAG enhances accuracy and relevance.

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": "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.output_text)

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 (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": """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"],
        }
    ]
)

print(response.result)

Output Example:

Compressor Preheating Logic Explanation
Initial Power-Up and 'Ch' Display:

Upon powering up the system, the display shows 'Ch'. This indicates that the compressor is not ready for operation.
The 'Ch' display is a signal that the system is checking the compressor's temperature before allowing operation.
2.5-Hour Heat Period:

If the compressor is not at the required temperature for operation, the 'Ch' indicator will continue to flicker.
During this time, the Crank Case Heater (CCH) will heat the compressor for 2.5 hours.
After this period, if the compressor is sufficiently heated, the 'Ch' indicator will disappear, allowing the system to operate.
6-Hour Power Requirement for First Installations:

For systems being installed and operated for the first time, it is necessary to apply power 6 hours before operation.
This ensures that the compressor is adequately preheated and ready for operation.
Clearing the 'Ch' Indicator:

The 'Ch' indicator will clear once the compressor reaches the appropriate temperature for operation, either after the 2.5-hour heating period or after the initial 6-hour power application for new installations.
Safety and Bypass Considerations:

It is not safe to bypass the preheating process as it ensures the compressor is at a safe operating temperature, preventing potential damage.
Customer-Friendly ETA Message:

"Your system is preparing to operate safely. Please allow up to 2.5 hours for preheating. For new installations, ensure the system has been powered for at least 6 hours before use. Thank you for your patience."
Source Attribution
This information is based on the documentation from "SYSTEM_AIR_CONDITIONER.pdf" provided by Samsung Electronics, specifically sections related to compressor preheating and initial power-up proceduresure safe operation. It will be ready to use in approximately 2.5 hours, or 6 hours if this is the first installation. Thank you for your patience!"

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