Documentation Index
Fetch the complete documentation index at: https://docs.ai21.com/llms.txt
Use this file to discover all available pages before exploring further.
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)
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.
- 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
)
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)
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.
