Major refactor: Multi-user Chrome MCP extension with remote server architecture

2025-08-21 20:09:57 +05:00
parent d97cad1736
commit 5d869f6a7c
125 changed files with 16249 additions and 11906 deletions
--- a/METADATA_LOGGING_GUIDE.md
+++ b/METADATA_LOGGING_GUIDE.md
@@ -0,0 +1,242 @@
+# Metadata Logging Guide for LiveKit Agent
+
+This guide explains how to use the comprehensive metadata logging system to debug and monitor user ID detection in LiveKit rooms.
+
+## 🎯 **Overview**
+
+The metadata logging system provides detailed insights into:
+- Room metadata content and structure
+- Participant metadata for all connected users
+- User ID detection results with source tracking
+- Comprehensive debugging information
+
+## 📋 **Features**
+
+### **1. Comprehensive Room Analysis**
+- Complete room metadata inspection
+- Participant count and details
+- Metadata parsing with error handling
+- User ID field detection across multiple formats
+
+### **2. Detailed Participant Logging**
+- Individual participant metadata analysis
+- Track publication information
+- Identity and connection details
+- Metadata validation and parsing
+
+### **3. User ID Search Results**
+- Priority-based user ID detection
+- Source tracking (participant vs room metadata)
+- Field name detection (`userId`, `user_id`, `userID`, etc.)
+- Comprehensive search reporting
+
+### **4. Debug Utilities**
+- Metadata snapshot saving
+- Real-time metadata monitoring
+- JSON validation and error reporting
+- Historical metadata tracking
+
+## 🚀 **Quick Start**
+
+### **Basic Usage**
+```python
+from metadata_logger import log_metadata
+
+# Quick comprehensive logging
+search_results = log_metadata(room, detailed=True, save_snapshot=False)
+
+if search_results["found"]:
+    print(f"User ID: {search_results['user_id']}")
+    print(f"Source: {search_results['source']}")
+```
+
+### **Advanced Usage**
+```python
+from metadata_logger import MetadataLogger
+
+# Create logger instance
+logger = MetadataLogger()
+
+# Detailed room analysis
+logger.log_room_metadata(room, detailed=True)
+
+# Extract user ID with detailed results
+search_results = logger.extract_user_id_from_metadata(room)
+logger.log_metadata_search_results(room, search_results)
+
+# Save snapshot for later analysis
+logger.save_metadata_snapshot(room, "debug_snapshot.json")
+```
+
+## 📊 **Sample Output**
+
+### **When User ID Found in Metadata:**
+```
+================================================================================
+                           ROOM METADATA ANALYSIS                            
+================================================================================
+Timestamp: 2024-01-15 14:30:38
+Room Name: provider_onboarding_room_SBy4hNBEVZ
+Room SID: RM_provider_onboarding_room_SBy4hNBEVZ
+
+❌ NO ROOM METADATA AVAILABLE
+
+👥 PARTICIPANTS: 1 remote participants
+
+--------------------------------------------------------------------------------
+                        PARTICIPANTS METADATA ANALYSIS                        
+--------------------------------------------------------------------------------
+
+🧑 PARTICIPANT #1
+   Identity: chrome_user_participant
+   SID: PA_chrome_user_participant
+   Name: Chrome Extension User
+   📋 METADATA FOUND:
+   Raw Metadata: {"userId":"user_1755117838_y76frrhg2258","source":"chrome_extension"}
+   Parsed Metadata: {
+         "userId": "user_1755117838_y76frrhg2258",
+         "source": "chrome_extension"
+      }
+   🎯 USER ID FOUND: userId = user_1755117838_y76frrhg2258
+   📌 source: chrome_extension
+
+🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍
+                              METADATA SEARCH RESULTS                              
+🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍
+
+Room: provider_onboarding_room_SBy4hNBEVZ
+Search completed at: 2024-01-15 14:30:38
+✅ USER ID FOUND!
+   Source: participant_metadata
+   User ID: user_1755117838_y76frrhg2258
+   Location: participant_1.userId
+   Full Metadata: {
+      "userId": "user_1755117838_y76frrhg2258",
+      "source": "chrome_extension"
+   }
+```
+
+### **When No User ID Found:**
+```
+❌ NO USER ID FOUND IN METADATA
+   Checked: ['participant_1', 'participant_2', 'room_metadata']
+   Participants checked: 2
+```
+
+## 🔧 **Integration with LiveKit Agent**
+
+The metadata logger is automatically integrated into the LiveKit agent:
+
+```python
+# In livekit_agent.py entrypoint method
+if self.metadata_logger:
+    # Log comprehensive metadata information
+    self.metadata_logger.log_room_metadata(ctx.room, detailed=True)
+    
+    # Extract user ID with detailed logging
+    search_results = self.metadata_logger.extract_user_id_from_metadata(ctx.room)
+    self.metadata_logger.log_metadata_search_results(ctx.room, search_results)
+    
+    if search_results["found"]:
+        chrome_user_id = search_results["user_id"]
+        user_id_source = "metadata"
+```
+
+## 🧪 **Testing**
+
+Run the test script to see all logging scenarios:
+
+```bash
+cd agent-livekit
+python test_metadata_logging.py
+```
+
+This will demonstrate:
+1. User ID in participant metadata
+2. User ID in room metadata  
+3. No user ID found
+4. Multiple user ID formats
+5. Invalid JSON handling
+
+## 📁 **Metadata Snapshots**
+
+Save complete metadata snapshots for debugging:
+
+```python
+# Save snapshot with timestamp
+logger.save_metadata_snapshot(room)
+
+# Save with custom filename
+logger.save_metadata_snapshot(room, "debug_session_123.json")
+```
+
+**Snapshot format:**
+```json
+{
+  "timestamp": "2024-01-15T14:30:38.123456",
+  "room": {
+    "name": "provider_onboarding_room_SBy4hNBEVZ",
+    "sid": "RM_provider_onboarding_room_SBy4hNBEVZ",
+    "metadata": null
+  },
+  "participants": [
+    {
+      "identity": "chrome_user_participant",
+      "sid": "PA_chrome_user_participant",
+      "name": "Chrome Extension User",
+      "metadata": "{\"userId\":\"user_1755117838_y76frrhg2258\"}"
+    }
+  ]
+}
+```
+
+## 🔄 **Real-time Monitoring**
+
+Monitor metadata changes in real-time:
+
+```python
+# Monitor every 5 seconds
+logger.monitor_metadata_changes(room, interval=5)
+```
+
+## 🎯 **User ID Field Detection**
+
+The system automatically detects user IDs in these field formats:
+- `userId` (preferred)
+- `user_id` (snake_case)
+- `userID` (camelCase)
+- `USER_ID` (uppercase)
+
+## 🚨 **Error Handling**
+
+The logger gracefully handles:
+- Invalid JSON metadata
+- Missing metadata fields
+- Network connection issues
+- Participant disconnections
+- Malformed room data
+
+## 📝 **Best Practices**
+
+1. **Use detailed logging during development**
+2. **Save snapshots for complex debugging scenarios**
+3. **Monitor metadata in real-time for dynamic rooms**
+4. **Check both participant and room metadata**
+5. **Validate JSON before setting metadata**
+
+## 🔍 **Troubleshooting**
+
+### **No metadata showing up:**
+- Check if participants have joined the room
+- Verify metadata was set when creating tokens/rooms
+- Ensure JSON is valid
+
+### **User ID not detected:**
+- Check field name format (`userId` vs `user_id`)
+- Verify metadata is properly JSON encoded
+- Check both participant and room metadata
+
+### **Logger not working:**
+- Ensure `metadata_logger.py` is in the same directory
+- Check import statements in `livekit_agent.py`
+- Verify LOCAL_MODULES_AVAILABLE is True