Home Assistant Integration with File

[Mukesh-P]

Issue: #72
Changes Overview

🔧 Core SDK Enhancement

File: src/xai_sdk/tools.py (+25 lines)

• Added attachment_search() function - New server-side tool for searching uploaded file attachments
• Purpose: Enables Grok to query and retrieve information from uploaded files during conversations
• Parameters: limit (optional) - Maximum number of search results to return

📝 New Examples
Files:

• examples/aio/home_assistant_integration.py (+361 lines)
• examples/sync/home_assistant_integration.py (+360 lines)

Key Features Implemented

🏠 Home Assistant Integration

• File-based device context management - Upload device data as JSON files
• Server-side attachment search - Use attachment_search tool to query device information
• Interactive query interface - Command-line interface for testing device queries
• Sample device data - Realistic Home Assistant device structure with areas, entities, and attributes

🛠️ SDK Limitation Workarounds

• File usage in user messages - Workaround for system(file()) limitation
• System prompt as file attachment - Include comprehensive prompts via uploaded files
• Structured data handling - JSON device context files instead of system message content

🐛 Error Handling & Debugging

• Comprehensive error handling - Try-catch blocks for all file operations and API calls
• Debug output capabilities - Tool call logging, response streaming, and usage statistics
• Resource cleanup - Proper file deletion in finally blocks
• Verbose streaming options - Include options for detailed tool output

Technical Implementation

File Structure

├── src/xai_sdk/tools.py                    # Added attachment_search function
├── examples/aio/home_assistant_integration.py    # Async implementation
└── examples/sync/home_assistant_integration.py   # Sync implementation

Key Functions

• attachment_search(limit=None) - Creates attachment search tool
• upload_context_files() - Handles file upload and cleanup
• handle_home_assistant_query() - Processes queries with file attachments
• demo_attachment_search() - Demonstrates search functionality

Sample Usage

# Create attachment search tool
chat = client.chat.create(
    model="grok-4-fast",
    tools=[attachment_search(limit=20)],
    include=["attachment_search_call_output"]
)

# Query with file attachments
chat.append(user(
    "Device context:", 
    file(context_file_id),
    "How many devices are in the bedroom?"
))

Problem Resolution
Original Issues Addressed

1. ✅ Cannot use system(file()) - Workaround using user message file attachments
2. ✅ Cannot use tools = file() - Proper tool parameter usage with attachment_search
3. ✅ JSON upload in system messages - File-based context instead of message content
4. ✅ File search not working - Implemented attachment_search tool with proper usage
5. ✅ Poor debugging - Added comprehensive logging and error handling

• File operation safety - Temporary file creation and cleanup
• API call robustness - Exception handling for uploads and chat operations
• Resource management - Automatic cleanup of uploaded files
• User feedback - Clear error messages and progress indicators

Testing & Validation

• Syntax validation - Python compilation successful for sync version
• Import validation - All dependencies properly imported
• Functionality demonstration - Interactive examples with realistic device data

Impact & Benefits

• Enhanced SDK capabilities - New attachment search functionality
• Improved developer experience - Comprehensive examples and error handling
• Home Assistant integration - Ready-to-use smart home AI assistant examples
• Debugging improvements - Better visibility into tool calls and responses