Upload folder using huggingface_hub

README.md

@@ -1,561 +1,119 @@
-# KARiANA.ai MCP Tools for Unreal Engine
-
-[![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.6%2B-blue)](https://www.unrealengine.com/)
-[![MCP](https://img.shields.io/badge/MCP-Protocol-green)](https://modelcontextprotocol.io/)
-[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker)](https://www.docker.com/)
-[![Documentation](https://img.shields.io/badge/Docs-GitHub%20Pages-4078c0)](https://kerinzeebart.github.io/MCPTest-with-UMCP.it)
-
-**Production-ready Docker deployment for 164 Unreal Engine 5.6 MCP tools**
-
-Complete testing framework and Docker infrastructure for AI-powered game development automation. Control Unreal Engine programmatically through Model Context Protocol (MCP) with zero-configuration setup.
-
----
-
-## 🎯 What is This?
-
-A comprehensive, zero-configuration Docker-based system that provides **164 MCP tools** for programmatic control of Unreal Engine 5.6. Perfect for AI-driven game development, automation, and creative workflows.
-
-### Key Features
-
-- ✅ **164 Tools** - 50+ external MCP actions + 88 plugin features
-- ✅ **Zero Configuration** - Automated setup for Windows, Linux, macOS
-- ✅ **Production Ready** - Security hardened, performance optimized
-- ✅ **UE 5.6 Compatible** - All APIs verified and tested
-- ✅ **Complete Documentation** - 7,000+ lines of comprehensive guides
-- ✅ **GUI Installer** - User-friendly PowerShell installer for Windows
-- ✅ **Auto-Detection** - Plugin automatically detects and configures Docker
-
 ---
-
-## 🚀 Quick Start
-
-### Windows
-```powershell
-# Visual installer with progress tracking
-.\Install-MCPDocker-GUI.ps1
-```
-
-### Linux/Mac
-```bash
-# Fully automated CLI installer
-chmod +x setup-docker.sh
-./setup-docker.sh
-```
-
-### Manual Setup
-```bash
-# 1. Clone repository
-git clone https://github.com/kerinzeebart/MCPTest-with-UMCP.it.git
-cd MCPTest-with-UMCP.it
-
-# 2. Install dependencies
-npm install
-
-# 3. Auto-detect environment
-python docker-detect.py
-
-# 4. Build Docker images
-docker-compose build
-
-# 5. Test all tools (requires Unreal Engine running)
-docker-compose up mcp-all-tools
-
-# 6. View results
-cat reports/all-164-tools-report.json
-```
-
-**Prerequisites:**
-- Unreal Engine 5.6+ with MCPTest.uproject open
-- Remote Control & Python Script plugins enabled
-- Ports 30010 (HTTP), 30020 (WebSocket), 9877 (Socket) available
-
-[**Full Setup Guide →**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/setup-guide)
-
+title: Kariana UMCP
+emoji: 🎮
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.9.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: AI-Powered Virtual Production Control for Unreal Engine
+tags:
+  - mcp
+  - mcp-in-action-track-xx
+  - unreal-engine
+  - virtual-production
+  - gradio
+  - claude
+  - hackathon
 ---
 
-## 📚 Documentation
-
-Visit our [**GitHub Pages Documentation**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it) for comprehensive guides.
+# Kariana UMCP - AI-Powered Virtual Production Control
 
-### Getting Started
-- [**Setup Guide**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/setup-guide) - Step-by-step installation for all platforms
-- [**Tool Registry**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/tool-registry) - Complete catalog of all 164 tools
-- [**Quick Start**](#quick-start) - Get running in 5 minutes
+**MCP 1st Birthday Hackathon Submission | Track: MCP in Action | Category: Multimodal + Productivity**
 
-### Development
-- [**API Reference**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/api-reference) - Complete API documentation with examples
-- [**Testing Guide**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/testing) - Comprehensive testing methodology
-- [**UE 5.6 Compatibility**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/ue56-compatibility) - Compatibility audit and verification
+> *"What if you could talk to Unreal Engine like you talk to a creative partner?"*
 
-### Operations
-- [**Troubleshooting**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/troubleshooting) - Problem-solving guide (1000+ lines)
-- [**Implementation Details**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/implementation) - Technical deep-dive
-- [**Complete Summary**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/summary) - Master overview document
+## The Problem
 
----
+Virtual production sets are complex. Lighting directors, environment artists, and cinematographers spend hours clicking through menus, adjusting parameters, and coordinating changes. The gap between creative intent and technical execution slows down production.
 
-## 🛠️ Tool Categories
+## The Solution: Kariana UMCP
 
-### External MCP Server (50+ Actions)
-Via Remote Control API (ports 30010/30020)
+A unified Gradio dashboard that connects Claude AI to Unreal Engine 5.6 via MCP, enabling:
 
-| Category | Tools | Description |
-|----------|-------|-------------|
-| **Asset Management** | 4 | List, import, create, inspect assets |
-| **Actor Control** | 8 | Spawn, move, rotate, scale, delete actors |
-| **Editor Control** | 6 | PIE, camera, view modes |
-| **Level Management** | 8 | Load, save, create, lighting |
-| **Blueprint Operations** | 4 | Create, compile, add components |
-| **Environment** | 8 | Landscape, foliage, splines, meshes |
-| **Sequencer** | 14 | Cinematics, keyframes, rendering |
-| **System Control** | 8 | Quality, screenshots, stats |
+- **Natural language scene control**: "Add dramatic backlighting to the hero character"
+- **Real-time monitoring**: Live FPS, logs, and connection status
+- **Visual scene manipulation**: Actor browser, transforms, materials
+- **Workflow automation**: Create reusable multi-step workflows
+- **Claude Skills integration**: 8 specialized AI agents for complex tasks
 
-[**View All External Tools →**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/tool-registry#external-tools)
+### Simple PIN-Based Authentication
 
-### Plugin Tools (88 Features)
-Via Socket Server (port 9877)
+No complex tokens. When Unreal starts:
+1. A 4-digit PIN appears in the editor log
+2. Enter it in the Gradio UI
+3. You're connected!
 
-| Category | Tools | Description |
-|----------|-------|-------------|
-| **Basic Commands** | 11 | Core operations, screenshots, materials |
-| **Actor Management** | 5 | Select, modify, delete actors |
-| **Blueprint Ops** | 13 | Create, edit, compile blueprints |
-| **Blueprint Connections** | 5 | Node connections and validation |
-| **PCG** | 12 | Procedural Content Generation |
-| **Quick Actions** | 23 | Lights, cameras, alignment, organization |
-| **Organization** | 6 | World Outliner organization |
+## Features
 
-[**View All Plugin Tools →**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/tool-registry#plugin-tools)
+### 5-Tab Dashboard
 
----
+| Tab | Features |
+|-----|----------|
+| **Monitor** | Connection status, FPS metrics, real-time logs |
+| **Scene** | Actor browser, transforms, screenshots |
+| **Skills** | 8 Claude agents, skill execution |
+| **Workflow** | Form-based automation builder |
+| **Setup** | PIN auth, instance discovery |
 
-## 🏗️ Architecture
+## Virtual Production Use Cases
 
+### For Lighting Directors
 ```
-┌─────────────────────────────────────────┐
-│         User Interface Layer             │
-│  GUI Installer | CLI Scripts | Auto-Detect│
-└─────────────────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────┐
-│       Docker Orchestration (6 Services)  │
-│  Test | Comprehensive | Monitor | All   │
-└─────────────────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────┐
-│    MCP Communication Layer               │
-│  Remote Control API | Socket Server     │
-└─────────────────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────┐
-│         Unreal Engine 5.6                │
-│  Remote Control Plugin | UMCPitv20 Plugin│
-└─────────────────────────────────────────┘
-```
-
-### Docker Infrastructure
-
-**Multi-Stage Production Build:**
-- **Builder Stage**: Node.js 22 Alpine with full development dependencies
-- **Production Stage**: Chainguard distroless (CVE-free, 150MB, 70% size reduction)
-- **Security**: Non-root user, minimal attack surface
-- **Performance**: Optimized for <100ms response times
-
-**6 Docker Service Configurations:**
-1. `mcp-test` - Quick validation (30 seconds)
-2. `mcp-comprehensive` - Full test suite (5-8 minutes)
-3. `mcp-extended` - Stress testing (10 minutes)
-4. `mcp-monitor` - Live monitoring with auto-restart
-5. `mcp-all-tools` - Complete 164 tool validation
-6. `mcp-dev` - Development mode with hot reload
-
----
-
-## 📊 Statistics
-
-- **164 Tools** total (50+ external + 88 plugin)
-- **10,000+ lines** of code
-- **7,000+ lines** of documentation
-- **30+ files** created
-- **5 test suites** for validation
-- **3 platforms** supported (Windows/Linux/macOS)
-- **Zero configuration** required
-
----
-
-## 🎓 Use Cases
-
-### AI-Driven Development
-- Use Claude, ChatGPT, or other AI assistants to control Unreal Engine
-- Natural language to engine commands
-- Automated asset creation and scene building
-
-### Automation & Testing
-- Automated level generation
-- Batch asset processing
-- Continuous integration testing
-- Performance benchmarking
-
-### Creative Workflows
-- Procedural content generation
-- Rapid prototyping
-- Scene organization
-- Cinematic automation
-
-### Remote Development
-- Control Unreal Engine from anywhere
-- Cloud-based workflows
-- Distributed team collaboration
-
----
-
-## 🔐 Security Features
-
-- ✅ **Distroless Images** - Chainguard base (CVE-free)
-- ✅ **Non-Root Execution** - Enhanced security
-- ✅ **Multi-Stage Builds** - No dev tools in production
-- ✅ **Network Isolation** - Bridge network with no inbound exposure
-- ✅ **Minimal Attack Surface** - 150MB production images
-
----
-
-## 🧪 Testing
-
-### Quick Test (30s)
-```bash
-docker-compose up mcp-test
-# Tests: Connection, basic tools, health check
+"Create a 3-point lighting setup with key at 45 degrees"
 ```
 
-### Comprehensive Test (5-8min)
-```bash
-npm run test:mcp
-# Tests: All 50+ external MCP actions
+### For Environment Artists
 ```
-
-### All 164 Tools (10min)
-```bash
-npm run test:all-tools
-# Tests: External + Plugin socket commands
+"Scatter 100 trees in the meadow area with natural variation"
 ```
 
-### Live Monitoring
-```bash
-docker-compose up mcp-monitor
-# Continuous health monitoring with auto-restart
+### For Cinematographers
 ```
-
-### Expected Results
-
-**Pass Rate:** 80-95% (depending on project assets and configuration)
-
-Tests generate detailed reports in `mcp-test-report.json`:
-```json
-{
-  "timestamp": "2025-11-11T...",
-  "passed": ["manage_asset.list", "control_actor.spawn", ...],
-  "failed": ["animation_physics.play_montage"],
-  "summary": {
-    "total": 164,
-    "passed": 142,
-    "failed": 8,
-    "skipped": 14,
-    "passRate": "86.6%"
-  }
-}
+"Capture a 360-degree turntable of the hero asset"
 ```
 
----
-
-## 🔧 Configuration
-
-### Unreal Engine Setup
+## How to Connect
 
-**Required Plugins:**
-- Remote Control ✅
-- Remote Control Web Interface ✅
-- Python Script Plugin ✅
+1. **Install KarianaUMCP plugin** in your Unreal Engine 5.6+ project
+2. **Open your project** - the plugin auto-starts and displays a 4-digit PIN
+3. **Enter PIN** in the Setup tab of this Space
+4. **Start creating!**
 
-**Config/DefaultEngine.ini:**
-```ini
-[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
-bRemoteExecution=True
-bAllowRemotePythonExecution=True
+## Technical Architecture
 
-[/Script/RemoteControl.RemoteControlSettings]
-bAllowRemoteExecutionOfConsoleCommands=True
-bEnableRemoteExecution=True
-bAllowPythonExecution=True
 ```
-
-### Claude Desktop Configuration
-
-**Location:** `C:\Users\USERNAME\AppData\Roaming\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "unreal-engine": {
-      "command": "node",
-      "args": ["path/to/node_modules/unreal-engine-mcp-server/dist/cli.js"],
-      "env": {
-        "UE_HOST": "127.0.0.1",
-        "UE_RC_HTTP_PORT": "30010",
-        "UE_RC_WS_PORT": "30020",
-        "UE_PROJECT_PATH": "path/to/MCPTest.uproject"
-      }
-    }
-  }
-}
+Gradio UI (HF Spaces) → Socket Server (Port 9877) → Unreal Engine 5.6
 ```
 
-**Important:** Restart Claude Desktop after configuration changes.
-
----
-
-## 💻 Development Commands
+## Built With
 
-### Testing
-```bash
-# Quick connection test
-npm run test:connection
+- **Gradio 5.0+** - Beautiful UI
+- **FastMCP 2.13+** - MCP server framework
+- **Unreal Engine 5.6** - Real-time engine
+- **Claude AI** - Natural language understanding
 
-# Comprehensive MCP test
-npm run test:mcp
+## Download Plugin
 
-# All 164 tools test
-npm run test:all-tools
+Get the KarianaUMCP plugin for your Unreal Engine project:
 
-# Docker tests
-docker-compose up mcp-test
-docker-compose up mcp-comprehensive
-docker-compose up mcp-all-tools
-```
-
-### Docker Operations
-```bash
-# Build images
-docker-compose build
+| Platform | Download |
+|----------|----------|
+| **Windows** | [KarianaUMCP-v1.0.0-windows.zip](https://github.com/kerinzeebart/MCPTest-with-UMCP.it/releases/download/v1.0.0/KarianaUMCP-v1.0.0-windows.zip) |
+| **macOS** | [KarianaUMCP-v1.0.0-macos.zip](https://github.com/kerinzeebart/MCPTest-with-UMCP.it/releases/download/v1.0.0/KarianaUMCP-v1.0.0-macos.zip) |
+| **Linux** | [KarianaUMCP-v1.0.0-linux.zip](https://github.com/kerinzeebart/MCPTest-with-UMCP.it/releases/download/v1.0.0/KarianaUMCP-v1.0.0-linux.zip) |
 
-# View logs
-docker-compose logs -f
+## Links
 
-# Stop all containers
-docker-compose down
+- **GitHub**: [Kariana-UMCP](https://github.com/kerinzeebart/MCPTest-with-UMCP.it)
+- **Hackathon**: [MCP 1st Birthday](https://huggingface.co/MCP-1st-Birthday)
 
-# Clean up everything
-docker-compose down -v --rmi all
-```
+## Team
 
-### Manual Testing
-```bash
-# MCP Inspector (web interface)
-npx @modelcontextprotocol/inspector node node_modules/unreal-engine-mcp-server/dist/cli.js
-
-# Python health check
-python Plugins/UMCPitv20/Content/Python/test_unreal_system.py
-```
-
----
-
-## 🚦 Getting Help
-
-### Common Tasks
-- [Install Docker](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/setup-guide#docker-installation)
-- [Configure Unreal Engine](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/setup-guide#unreal-engine-configuration)
-- [Run Tests](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/testing)
-- [Debug Connection Issues](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/troubleshooting#connection-problems)
-
-### Common Issues
-
-#### UE_NOT_CONNECTED Error
-**Symptoms:** All tools fail with "Unreal Engine is not connected"
-
-**Fix:**
-1. Verify Unreal Engine is running with MCPTest.uproject open
-2. Check Remote Control plugin is enabled
-3. Restart Unreal Engine after enabling plugins
-4. Verify ports 30010/30020 not blocked by firewall
-
-#### Docker Host Detection Issues
-**Symptoms:** Docker container cannot connect to Unreal Engine
-
-**Fix:**
-1. Run auto-detection: `python docker-detect.py`
-2. Verify `.env` file has correct `UE_HOST`:
-   - Windows/Mac: `host.docker.internal`
-   - Linux: Bridge IP (e.g., `172.17.0.1`)
-3. Test connectivity: `docker-compose up mcp-test`
-
-#### Actor Not Found Errors
-**Fix:**
-- Actor names are **case-sensitive**
-- Use exact label from World Outliner
-- Both friendly labels and internal names work
-- Format: `/Game/Maps/Level.Level:PersistentLevel.ActorName`
-
-#### Asset Path Errors
-**Fix:**
-- Use `/Game` prefix, NOT `/Content`
-- Correct: `/Game/Materials/MyMat`
-- Wrong: `/Content/Materials/MyMat`
-
-[**Full Troubleshooting Guide →**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/troubleshooting)
-
----
-
-## 📁 Project Structure
-
-```
-MCPTest-with-UMCP.it/
-├── Dockerfile                      # Multi-stage production build
-├── docker-compose.yml              # 6 service configurations
-├── docker-detect.py                # Auto-detection system
-├── setup-docker.sh                 # Linux/Mac installer
-├── Install-MCPDocker-GUI.ps1       # Windows GUI installer
-│
-├── test-all-164-tools.js           # Comprehensive test suite
-├── test-mcp-tools.js               # External MCP tools test
-├── test-mcp-connection.js          # Connection validation
-│
-├── Plugins/
-│   ├── UMCPitv20/                  # Main MCP integration plugin
-│   │   ├── Content/Python/
-│   │   │   ├── docker_integration.py
-│   │   │   ├── unreal_socket_server.py
-│   │   │   └── skills/             # AI workflow skills
-│   │   └── Source/                 # C++ plugin source
-│   └── UMCP/                       # Original UMCP.it plugin
-│
-├── docs/                           # GitHub Pages docs
-├── DOCKER_*.md                     # Comprehensive guides
-├── API_REFERENCE.md                # Complete API docs
-├── _config.yml                     # Jekyll configuration
-└── index.md                        # GitHub Pages homepage
-```
-
----
-
-## 📊 Performance Metrics
-
-### Response Times
-- **External MCP Tools**: <100ms average
-- **Plugin Socket Commands**: <50ms average
-- **Docker Overhead**: <10ms additional latency
-
-### Container Metrics
-- **Image Size**: 150MB (production, distroless)
-- **Build Time**: 2-3 minutes (multi-stage)
-- **Memory Usage**: <100MB runtime
-- **CPU Usage**: <5% idle, <20% under load
+- **barlowski** - Developer
 
 ---
 
-## 🎯 What's New
-
-### Latest Version: v2.0 (Docker Production Release)
-
-#### ✨ Major Features
-- **🐳 Docker Infrastructure**: Zero-configuration deployment with multi-stage builds
-- **🔒 Security Hardening**: Chainguard distroless images, CVE-free, non-root user
-- **📦 Complete Tool Coverage**: All 164 tools (50+ external + 88 plugin)
-- **🚀 Automated Installers**: GUI for Windows, CLI for Linux/Mac
-- **📊 Comprehensive Testing**: 5 test scenarios with detailed reporting
-- **📚 GitHub Pages Docs**: Professional documentation site
-- **🔍 Auto-Detection**: Platform-specific environment configuration
-
-#### 🔧 Critical Fixes (October 2025)
-- **Fixed**: actor_modify tool now works with both friendly labels AND internal object names
-- **Fixed**: Claude Desktop spinning wheel (responses return in <1 second)
-- **Fixed**: Socket server newline delimiter for immediate response handling
-
-#### 🎯 Skills Framework Integration
-- **NEW**: Higher-level AI workflows with expert prompts
-- **unreal-organizer**: AI-powered World Outliner organization
-- **discovery-first**: Dynamic project structure discovery (no hardcoded paths)
-
----
-
-## 🏢 About KARiANA.ai
-
-**KARiANA.ai** is revolutionizing game development through AI-powered automation and intelligent workflows. This MCP Tools implementation demonstrates our commitment to making Unreal Engine accessible to AI assistants and automation systems.
-
-### Our Vision
-Transform game development workflows by enabling natural language control of complex engine operations, making advanced features accessible to developers of all skill levels.
-
-### Key Projects
-- **MCP Tools for Unreal Engine**: 164 production-ready tools for AI-driven development
-- **Docker Infrastructure**: Zero-configuration deployment for enterprise environments
-- **Skills Framework**: Higher-level AI workflows for complex game development tasks
-
-### Connect With Us
-- **Website**: [KARiANA.ai](https://kariana.ai) (coming soon)
-- **Documentation**: [GitHub Pages](https://kerinzeebart.github.io/MCPTest-with-UMCP.it)
-- **Repository**: [GitHub](https://github.com/kerinzeebart/MCPTest-with-UMCP.it)
-
----
-
-## 📚 Additional Resources
-
-### Official Documentation
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [Unreal Engine Remote Control API](https://docs.unrealengine.com/5.6/en-US/remote-control-api-in-unreal-engine/)
-- [Unreal Engine Python API](https://docs.unrealengine.com/5.6/en-US/scripting-the-unreal-editor-using-python/)
-
-### Project Documentation
-- [Docker Setup Guide](DOCKER_SETUP_GUIDE.md) - Complete installation instructions
-- [Testing Guide](DOCKER_TESTING.md) - Test scenarios and KPIs
-- [Troubleshooting](DOCKER_TROUBLESHOOTING.md) - 50+ common issues
-- [API Reference](API_REFERENCE.md) - Complete API for all 164 tools
-- [Implementation Details](DOCKER_IMPLEMENTATION.md) - Architecture & design
-- [UE 5.6 Compatibility](UE5.6_API_COMPATIBILITY_AUDIT.md) - Compatibility audit
-- [Complete Summary](DOCKER_COMPLETE_IMPLEMENTATION_SUMMARY.md) - Master overview
-
----
-
-## ✅ Success Criteria
-
-- [x] **164 tools implemented** (50+ external + 88 plugin)
-- [x] **Docker infrastructure complete** (6 service configurations)
-- [x] **Zero-configuration setup** (automated installers)
-- [x] **Security hardened** (CVE-free distroless images)
-- [x] **80%+ test pass rate** (comprehensive automated testing)
-- [x] **Complete documentation** (7,000+ lines, GitHub Pages)
-- [x] **UE 5.6 compatible** (all APIs verified)
-- [x] **Production ready** (<100ms response times)
-
----
-
-## 📝 License
-
-This project is provided as-is for development and testing purposes. See individual component licenses:
-- Unreal Engine MCP Server: [unreal-engine-mcp-server](https://github.com/kenstclair/unreal-engine-mcp-server)
-- UMCPitv20 Plugin: Custom implementation for KARiANA.ai
-- Docker Infrastructure: KARiANA.ai (MIT-style)
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our documentation for:
-- [Development Guidelines](DOCKER_IMPLEMENTATION.md)
-- [Testing Requirements](DOCKER_TESTING.md)
-- [API Standards](API_REFERENCE.md)
-
----
-
-## 🎉 Status: Production Ready
-
-All systems tested, documented, and ready for immediate use.
-
-[**Get Started Now →**](https://kerinzeebart.github.io/MCPTest-with-UMCP.it/docs/setup-guide)
-
----
-
-<div align="center">
-
-**Made with ❤️ by KARiANA.ai**
-
-*Empowering AI-driven game development*
-
-</div>
+*Happy Birthday, MCP! Here's to AI-powered creativity.* 🎂

components/__init__.py

@@ -0,0 +1,14 @@
+# Kariana Unified UI - Components Module
+from .actor_browser import ActorBrowser
+from .material_preview import MaterialPreview
+from .log_viewer import LogViewer
+from .performance_chart import PerformanceChart
+from .workflow_form import WorkflowForm
+
+__all__ = [
+    'ActorBrowser',
+    'MaterialPreview',
+    'LogViewer',
+    'PerformanceChart',
+    'WorkflowForm'
+]

components/actor_browser.py

@@ -0,0 +1,5 @@
+"""Actor Browser Component - Placeholder for future expansion"""
+
+class ActorBrowser:
+    """Actor browser component for scene tree visualization"""
+    pass

components/log_viewer.py

@@ -0,0 +1,5 @@
+"""Log Viewer Component - Placeholder for future expansion"""
+
+class LogViewer:
+    """Real-time log viewer component"""
+    pass

components/material_preview.py

@@ -0,0 +1,5 @@
+"""Material Preview Component - Placeholder for future expansion"""
+
+class MaterialPreview:
+    """Material preview component for visual material editing"""
+    pass

components/performance_chart.py

@@ -0,0 +1,5 @@
+"""Performance Chart Component - Placeholder for future expansion"""
+
+class PerformanceChart:
+    """Performance metrics chart component"""
+    pass

components/workflow_form.py

@@ -0,0 +1,5 @@
+"""Workflow Form Component - Placeholder for future expansion"""
+
+class WorkflowForm:
+    """Form-based workflow builder component"""
+    pass

core/__init__.py

@@ -0,0 +1,7 @@
+# Kariana Unified UI - Core Module
+from .config import Config
+from .auth import PINAuthenticator
+from .connection import UnrealConnection
+from .session import SessionManager
+
+__all__ = ['Config', 'PINAuthenticator', 'UnrealConnection', 'SessionManager']

core/auth.py

@@ -0,0 +1,150 @@
+"""
+Kariana Unified UI - PIN Authentication
+Simple 4-digit PIN-based authentication with Unreal instances
+"""
+import asyncio
+import json
+import logging
+from typing import Optional, Tuple
+
+from ..utils.discovery import InstanceDiscovery, UnrealInstance
+
+logger = logging.getLogger(__name__)
+
+
+class PINAuthenticator:
+    """Handles PIN-based authentication with Unreal instances"""
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port_range: tuple = (9877, 9887),
+        timeout: float = 5.0
+    ):
+        self.host = host
+        self.port_range = port_range
+        self.timeout = timeout
+        self._discovery = InstanceDiscovery(host, port_range, timeout=1.0)
+        self._authenticated_instance: Optional[UnrealInstance] = None
+        self._session_token: Optional[str] = None
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated_instance is not None
+
+    @property
+    def current_instance(self) -> Optional[UnrealInstance]:
+        return self._authenticated_instance
+
+    async def validate_pin(self, pin: str, instance: UnrealInstance) -> Tuple[bool, Optional[str]]:
+        """Validate PIN against a specific instance"""
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(instance.host, instance.port),
+                timeout=self.timeout
+            )
+
+            # Send validate_pin command
+            command = json.dumps({
+                "type": "validate_pin",
+                "pin": pin
+            }) + "\n"
+            writer.write(command.encode())
+            await writer.drain()
+
+            # Read response
+            response_data = await asyncio.wait_for(
+                reader.readline(),
+                timeout=self.timeout
+            )
+
+            writer.close()
+            await writer.wait_closed()
+
+            if response_data:
+                response = json.loads(response_data.decode().strip())
+                if response.get("success"):
+                    return True, response.get("session_token")
+                else:
+                    logger.warning(f"PIN validation failed: {response.get('error')}")
+                    return False, None
+
+        except asyncio.TimeoutError:
+            logger.warning(f"Timeout validating PIN on {instance.host}:{instance.port}")
+        except ConnectionRefusedError:
+            logger.warning(f"Connection refused on {instance.host}:{instance.port}")
+        except Exception as e:
+            logger.error(f"PIN validation error: {e}")
+
+        return False, None
+
+    async def authenticate_with_pin(self, pin: str) -> Tuple[bool, Optional[UnrealInstance]]:
+        """
+        Auto-discover instances and validate PIN.
+        Returns (success, authenticated_instance)
+        """
+        # Validate PIN format
+        if not pin or len(pin) != 4 or not pin.isdigit():
+            logger.warning("Invalid PIN format (must be 4 digits)")
+            return False, None
+
+        # Discover available instances
+        instances = await self._discovery.discover_instances()
+
+        if not instances:
+            logger.warning("No Unreal instances found")
+            return False, None
+
+        # Try each instance
+        for instance in instances:
+            success, session_token = await self.validate_pin(pin, instance)
+            if success:
+                instance.authenticated = True
+                self._authenticated_instance = instance
+                self._session_token = session_token
+                logger.info(f"Authenticated with instance on port {instance.port}")
+                return True, instance
+
+        logger.warning("PIN did not match any instance")
+        return False, None
+
+    def authenticate_with_pin_sync(self, pin: str) -> Tuple[bool, Optional[UnrealInstance]]:
+        """Synchronous wrapper for authenticate_with_pin"""
+        try:
+            loop = asyncio.get_running_loop()
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(asyncio.run, self.authenticate_with_pin(pin))
+                return future.result(timeout=self.timeout * 10 + 1)
+        except RuntimeError:
+            return asyncio.run(self.authenticate_with_pin(pin))
+
+    def disconnect(self):
+        """Clear authentication state"""
+        self._authenticated_instance = None
+        self._session_token = None
+
+    def get_session_info(self) -> Optional[dict]:
+        """Get current session information"""
+        if not self.is_authenticated:
+            return None
+
+        return {
+            "instance": self._authenticated_instance.to_dict(),
+            "session_token": self._session_token,
+        }
+
+
+# Global authenticator instance
+_authenticator: Optional[PINAuthenticator] = None
+
+
+def get_authenticator(
+    host: str = "localhost",
+    port_range: tuple = (9877, 9887)
+) -> PINAuthenticator:
+    """Get or create global authenticator instance"""
+    global _authenticator
+    if _authenticator is None:
+        _authenticator = PINAuthenticator(host, port_range)
+    return _authenticator

core/config.py

@@ -0,0 +1,65 @@
+"""
+Kariana Unified UI - Configuration Management
+"""
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Config:
+    """Configuration for Kariana Unified UI"""
+
+    # Server settings
+    gradio_port: int = 7860
+    gradio_host: str = "0.0.0.0"
+
+    # Unreal connection settings
+    unreal_port_range: tuple = (9877, 9887)
+    unreal_host: str = "localhost"
+    connection_timeout: float = 5.0
+
+    # Authentication
+    pin_length: int = 4
+    auth_enabled: bool = True
+
+    # Deployment mode
+    is_huggingface: bool = field(default_factory=lambda: os.getenv("SPACE_ID") is not None)
+    remote_mode: bool = False
+
+    # Logging
+    log_level: str = "INFO"
+
+    # Tunnel settings (for remote access)
+    ngrok_auth_token: Optional[str] = field(default_factory=lambda: os.getenv("NGROK_AUTH_TOKEN"))
+    tunnel_enabled: bool = False
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        """Create config from environment variables"""
+        return cls(
+            gradio_port=int(os.getenv("GRADIO_PORT", "7860")),
+            gradio_host=os.getenv("GRADIO_HOST", "0.0.0.0"),
+            unreal_host=os.getenv("UNREAL_HOST", "localhost"),
+            connection_timeout=float(os.getenv("CONNECTION_TIMEOUT", "5.0")),
+            auth_enabled=os.getenv("AUTH_ENABLED", "true").lower() == "true",
+            remote_mode=os.getenv("REMOTE_MODE", "false").lower() == "true",
+            log_level=os.getenv("LOG_LEVEL", "INFO"),
+            tunnel_enabled=os.getenv("TUNNEL_ENABLED", "false").lower() == "true",
+        )
+
+    def to_dict(self) -> dict:
+        """Convert config to dictionary"""
+        return {
+            "gradio_port": self.gradio_port,
+            "gradio_host": self.gradio_host,
+            "unreal_port_range": self.unreal_port_range,
+            "unreal_host": self.unreal_host,
+            "connection_timeout": self.connection_timeout,
+            "pin_length": self.pin_length,
+            "auth_enabled": self.auth_enabled,
+            "is_huggingface": self.is_huggingface,
+            "remote_mode": self.remote_mode,
+            "log_level": self.log_level,
+            "tunnel_enabled": self.tunnel_enabled,
+        }

core/connection.py

@@ -0,0 +1,194 @@
+"""
+Kariana Unified UI - Unreal Connection Manager
+Manages connection state and provides command interface
+"""
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional, Callable
+
+from ..utils.socket_client import SocketClient, SyncSocketClient
+from ..utils.discovery import UnrealInstance
+from .auth import PINAuthenticator, get_authenticator
+
+logger = logging.getLogger(__name__)
+
+
+class UnrealConnection:
+    """
+    Manages connection to a KarianaUMCP instance.
+    Provides high-level command interface.
+    """
+
+    def __init__(self, instance: Optional[UnrealInstance] = None):
+        self._instance = instance
+        self._client: Optional[SyncSocketClient] = None
+        self._authenticator = get_authenticator()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._instance is not None and self._instance.authenticated
+
+    @property
+    def instance(self) -> Optional[UnrealInstance]:
+        return self._instance
+
+    def connect_with_pin(self, pin: str) -> bool:
+        """Connect using PIN authentication"""
+        success, instance = self._authenticator.authenticate_with_pin_sync(pin)
+        if success and instance:
+            self._instance = instance
+            self._client = SyncSocketClient(instance.host, instance.port)
+            return True
+        return False
+
+    def disconnect(self):
+        """Disconnect from instance"""
+        if self._client:
+            self._client.disconnect()
+        self._instance = None
+        self._authenticator.disconnect()
+
+    def send_command(self, command_type: str, **params) -> Optional[Dict[str, Any]]:
+        """Send command to Unreal instance"""
+        if not self.is_connected:
+            logger.warning("Not connected to any instance")
+            return None
+
+        if not self._client:
+            self._client = SyncSocketClient(self._instance.host, self._instance.port)
+
+        command = {"type": command_type, **params}
+        return self._client.send_command(command)
+
+    # === High-Level Command Methods ===
+
+    def ping(self) -> bool:
+        """Test connection"""
+        response = self.send_command("ping")
+        return response is not None and response.get("status") == "ok"
+
+    def get_server_info(self) -> Optional[Dict]:
+        """Get server information"""
+        return self.send_command("get_server_info")
+
+    def list_actors(self) -> Optional[List[Dict]]:
+        """Get list of actors in current level"""
+        response = self.send_command("list_actors")
+        if response and response.get("success"):
+            return response.get("actors", [])
+        return None
+
+    def spawn_actor(
+        self,
+        actor_type: str,
+        name: str,
+        location: List[float] = None,
+        rotation: List[float] = None,
+        scale: List[float] = None
+    ) -> Optional[Dict]:
+        """Spawn an actor in the level"""
+        params = {
+            "actor_type": actor_type,
+            "name": name,
+        }
+        if location:
+            params["location"] = location
+        if rotation:
+            params["rotation"] = rotation
+        if scale:
+            params["scale"] = scale
+
+        return self.send_command("spawn_actor", **params)
+
+    def delete_actor(self, actor_name: str) -> Optional[Dict]:
+        """Delete an actor by name"""
+        return self.send_command("delete_actor", actor_name=actor_name)
+
+    def get_actor_transform(self, actor_name: str) -> Optional[Dict]:
+        """Get actor transform (location, rotation, scale)"""
+        return self.send_command("get_actor_transform", actor_name=actor_name)
+
+    def set_actor_transform(
+        self,
+        actor_name: str,
+        location: List[float] = None,
+        rotation: List[float] = None,
+        scale: List[float] = None
+    ) -> Optional[Dict]:
+        """Set actor transform"""
+        params = {"actor_name": actor_name}
+        if location:
+            params["location"] = location
+        if rotation:
+            params["rotation"] = rotation
+        if scale:
+            params["scale"] = scale
+
+        return self.send_command("set_actor_transform", **params)
+
+    def capture_screenshot(self, filename: str = None) -> Optional[Dict]:
+        """Capture viewport screenshot"""
+        params = {}
+        if filename:
+            params["filename"] = filename
+        return self.send_command("capture_screenshot", **params)
+
+    def execute_python(self, code: str) -> Optional[Dict]:
+        """Execute Python code in Unreal"""
+        return self.send_command("execute_python", code=code)
+
+    def console_command(self, command: str) -> Optional[Dict]:
+        """Execute Unreal console command"""
+        return self.send_command("console_command", command=command)
+
+    def get_logs(self, limit: int = 100, category: str = None) -> Optional[List[str]]:
+        """Get Unreal Engine logs"""
+        params = {"limit": limit}
+        if category:
+            params["category"] = category
+
+        response = self.send_command("get_ue_logs", **params)
+        if response and response.get("success"):
+            return response.get("logs", [])
+        return None
+
+    def get_performance_metrics(self) -> Optional[Dict]:
+        """Get performance metrics (FPS, frame time, etc.)"""
+        return self.send_command("get_performance_metrics")
+
+    def list_skills(self) -> Optional[List[Dict]]:
+        """List available skills"""
+        response = self.send_command("list_skills")
+        if response and response.get("success"):
+            return response.get("skills", [])
+        return None
+
+    def execute_skill(self, skill_name: str, params: Dict = None) -> Optional[Dict]:
+        """Execute a skill"""
+        command_params = {"skill_name": skill_name}
+        if params:
+            command_params["params"] = params
+        return self.send_command("execute_skill", **command_params)
+
+    def get_actor_tree(self) -> Optional[Dict]:
+        """Get hierarchical actor tree (World Outliner structure)"""
+        return self.send_command("get_actor_tree")
+
+    def get_actor_materials(self, actor_name: str) -> Optional[List[Dict]]:
+        """Get materials assigned to an actor"""
+        response = self.send_command("get_actor_materials", actor_name=actor_name)
+        if response and response.get("success"):
+            return response.get("materials", [])
+        return None
+
+
+# Global connection instance
+_connection: Optional[UnrealConnection] = None
+
+
+def get_connection() -> UnrealConnection:
+    """Get or create global connection instance"""
+    global _connection
+    if _connection is None:
+        _connection = UnrealConnection()
+    return _connection

core/session.py

@@ -0,0 +1,188 @@
+"""
+Kariana Unified UI - Session Management
+Manages user sessions and persists state
+"""
+import json
+import logging
+import os
+import tempfile
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Dict, List, Optional
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Session:
+    """User session data"""
+    session_id: str
+    created_at: str
+    last_activity: str
+    connected_instance_port: Optional[int] = None
+    connected_instance_host: Optional[str] = None
+    command_history: List[Dict] = field(default_factory=list)
+    workflows: List[Dict] = field(default_factory=list)
+    preferences: Dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Session":
+        return cls(**data)
+
+
+class SessionManager:
+    """Manages session persistence and state"""
+
+    def __init__(self, storage_dir: str = None):
+        if storage_dir is None:
+            storage_dir = os.path.join(tempfile.gettempdir(), "kariana_ui_sessions")
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+        self._current_session: Optional[Session] = None
+
+    def _generate_session_id(self) -> str:
+        """Generate unique session ID"""
+        import uuid
+        return str(uuid.uuid4())[:8]
+
+    def _get_session_path(self, session_id: str) -> Path:
+        """Get path to session file"""
+        return self.storage_dir / f"session_{session_id}.json"
+
+    def create_session(self) -> Session:
+        """Create a new session"""
+        now = datetime.utcnow().isoformat()
+        session = Session(
+            session_id=self._generate_session_id(),
+            created_at=now,
+            last_activity=now,
+        )
+        self._current_session = session
+        self._save_session(session)
+        logger.info(f"Created session {session.session_id}")
+        return session
+
+    def get_or_create_session(self) -> Session:
+        """Get current session or create new one"""
+        if self._current_session is None:
+            # Try to load most recent session
+            sessions = self._list_sessions()
+            if sessions:
+                self._current_session = self._load_session(sessions[-1])
+            else:
+                self._current_session = self.create_session()
+        return self._current_session
+
+    def _save_session(self, session: Session):
+        """Save session to disk"""
+        try:
+            path = self._get_session_path(session.session_id)
+            with open(path, 'w') as f:
+                json.dump(session.to_dict(), f, indent=2)
+        except Exception as e:
+            logger.error(f"Failed to save session: {e}")
+
+    def _load_session(self, session_id: str) -> Optional[Session]:
+        """Load session from disk"""
+        try:
+            path = self._get_session_path(session_id)
+            if path.exists():
+                with open(path, 'r') as f:
+                    data = json.load(f)
+                return Session.from_dict(data)
+        except Exception as e:
+            logger.error(f"Failed to load session {session_id}: {e}")
+        return None
+
+    def _list_sessions(self) -> List[str]:
+        """List all session IDs"""
+        sessions = []
+        for path in self.storage_dir.glob("session_*.json"):
+            session_id = path.stem.replace("session_", "")
+            sessions.append(session_id)
+        return sorted(sessions)
+
+    def update_activity(self):
+        """Update last activity timestamp"""
+        if self._current_session:
+            self._current_session.last_activity = datetime.utcnow().isoformat()
+            self._save_session(self._current_session)
+
+    def set_connected_instance(self, host: str, port: int):
+        """Record connected instance"""
+        session = self.get_or_create_session()
+        session.connected_instance_host = host
+        session.connected_instance_port = port
+        self._save_session(session)
+
+    def add_command_to_history(self, command: Dict, response: Dict = None):
+        """Add command to history"""
+        session = self.get_or_create_session()
+        entry = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "command": command,
+            "response": response,
+        }
+        session.command_history.append(entry)
+        # Keep last 100 commands
+        session.command_history = session.command_history[-100:]
+        self._save_session(session)
+
+    def get_command_history(self, limit: int = 50) -> List[Dict]:
+        """Get recent command history"""
+        session = self.get_or_create_session()
+        return session.command_history[-limit:]
+
+    def save_workflow(self, workflow: Dict):
+        """Save a workflow"""
+        session = self.get_or_create_session()
+        # Update if exists, otherwise append
+        for i, w in enumerate(session.workflows):
+            if w.get("name") == workflow.get("name"):
+                session.workflows[i] = workflow
+                self._save_session(session)
+                return
+        session.workflows.append(workflow)
+        self._save_session(session)
+
+    def get_workflows(self) -> List[Dict]:
+        """Get saved workflows"""
+        session = self.get_or_create_session()
+        return session.workflows
+
+    def delete_workflow(self, name: str) -> bool:
+        """Delete a workflow by name"""
+        session = self.get_or_create_session()
+        for i, w in enumerate(session.workflows):
+            if w.get("name") == name:
+                session.workflows.pop(i)
+                self._save_session(session)
+                return True
+        return False
+
+    def set_preference(self, key: str, value):
+        """Set a preference"""
+        session = self.get_or_create_session()
+        session.preferences[key] = value
+        self._save_session(session)
+
+    def get_preference(self, key: str, default=None):
+        """Get a preference"""
+        session = self.get_or_create_session()
+        return session.preferences.get(key, default)
+
+
+# Global session manager
+_session_manager: Optional[SessionManager] = None
+
+
+def get_session_manager() -> SessionManager:
+    """Get or create global session manager"""
+    global _session_manager
+    if _session_manager is None:
+        _session_manager = SessionManager()
+    return _session_manager

tabs/__init__.py

@@ -0,0 +1,14 @@
+# Kariana Unified UI - Tabs Module
+from .monitoring import create_monitoring_tab
+from .scene_control import create_scene_control_tab
+from .skills_agents import create_skills_agents_tab
+from .workflow_builder import create_workflow_builder_tab
+from .setup import create_setup_tab
+
+__all__ = [
+    'create_monitoring_tab',
+    'create_scene_control_tab',
+    'create_skills_agents_tab',
+    'create_workflow_builder_tab',
+    'create_setup_tab'
+]

tabs/monitoring.py

@@ -0,0 +1,207 @@
+"""
+Kariana Unified UI - Monitoring Tab
+Real-time monitoring of Unreal Engine connection, logs, and performance
+"""
+
+import gradio as gr
+import logging
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+# Import will work once the package is properly set up
+try:
+    from ..core.connection import get_connection
+except ImportError:
+    get_connection = None
+
+
+def create_monitoring_tab() -> Dict:
+    """Create the Monitoring tab"""
+
+    with gr.Column():
+        # Connection Status Card
+        gr.Markdown("## Connection Status")
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                status_indicator = gr.Markdown("**Status:** Checking...")
+
+            with gr.Column(scale=2):
+                with gr.Row():
+                    instance_info = gr.JSON(
+                        label="Instance Info",
+                        value={"status": "not_connected"}
+                    )
+
+        # Quick Actions
+        with gr.Row():
+            ping_btn = gr.Button("Ping", size="sm")
+            refresh_info_btn = gr.Button("Refresh Info", size="sm")
+
+        ping_result = gr.Textbox(label="Ping Result", interactive=False)
+
+        gr.Markdown("---")
+
+        # Performance Metrics
+        gr.Markdown("## Performance Metrics")
+
+        with gr.Row():
+            with gr.Column():
+                fps_display = gr.Number(label="FPS", value=0, interactive=False)
+            with gr.Column():
+                frame_time_display = gr.Number(label="Frame Time (ms)", value=0, interactive=False)
+            with gr.Column():
+                draw_calls_display = gr.Number(label="Draw Calls", value=0, interactive=False)
+
+        refresh_perf_btn = gr.Button("Refresh Metrics", size="sm")
+
+        gr.Markdown("---")
+
+        # Real-time Logs
+        gr.Markdown("## Unreal Engine Logs")
+
+        with gr.Row():
+            log_category = gr.Dropdown(
+                label="Category Filter",
+                choices=["All", "LogTemp", "LogPython", "LogBlueprintUserMessages", "LogKariana"],
+                value="All",
+                scale=1
+            )
+            log_limit = gr.Slider(
+                label="Max Lines",
+                minimum=10,
+                maximum=500,
+                value=100,
+                step=10,
+                scale=1
+            )
+
+        with gr.Row():
+            fetch_logs_btn = gr.Button("Fetch Logs", size="sm")
+            clear_logs_btn = gr.Button("Clear", size="sm")
+            auto_refresh = gr.Checkbox(label="Auto-refresh (5s)", value=False)
+
+        logs_display = gr.TextArea(
+            label="Log Output",
+            lines=15,
+            max_lines=30,
+            interactive=False,
+            show_copy_button=True
+        )
+
+    # Event Handlers
+    def handle_ping() -> str:
+        """Ping the connected instance"""
+        try:
+            if get_connection is None:
+                return "Connection module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "Not connected - enter PIN in Setup tab"
+
+            start = datetime.now()
+            if conn.ping():
+                elapsed = (datetime.now() - start).total_seconds() * 1000
+                return f"Pong! Response time: {elapsed:.1f}ms"
+            return "Ping failed - no response"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def handle_refresh_info() -> tuple:
+        """Refresh connection info"""
+        try:
+            if get_connection is None:
+                return "**Status:** Module not available", {"error": "not_available"}
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "**Status:** Not Connected", {"status": "not_connected"}
+
+            info = conn.get_server_info()
+            if info:
+                status = f"**Status:** Connected to {info.get('project', 'Unknown')} (Port {info.get('port', 'N/A')})"
+                return status, info
+            return "**Status:** Connected (no info)", {"status": "connected"}
+        except Exception as e:
+            return f"**Status:** Error - {str(e)}", {"error": str(e)}
+
+    def handle_refresh_performance() -> tuple:
+        """Refresh performance metrics"""
+        try:
+            if get_connection is None:
+                return 0, 0, 0
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return 0, 0, 0
+
+            metrics = conn.get_performance_metrics()
+            if metrics and metrics.get("success"):
+                return (
+                    metrics.get("fps", 0),
+                    metrics.get("frame_time_ms", 0),
+                    metrics.get("draw_calls", 0)
+                )
+            return 0, 0, 0
+        except Exception as e:
+            logger.error(f"Performance metrics error: {e}")
+            return 0, 0, 0
+
+    def handle_fetch_logs(category: str, limit: int) -> str:
+        """Fetch logs from Unreal"""
+        try:
+            if get_connection is None:
+                return "Connection module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "Not connected - enter PIN in Setup tab"
+
+            cat_filter = None if category == "All" else category
+            logs = conn.get_logs(limit=int(limit), category=cat_filter)
+
+            if logs:
+                return "\n".join(logs)
+            return "No logs available"
+        except Exception as e:
+            return f"Error fetching logs: {str(e)}"
+
+    # Wire up event handlers
+    ping_btn.click(
+        fn=handle_ping,
+        outputs=[ping_result]
+    )
+
+    refresh_info_btn.click(
+        fn=handle_refresh_info,
+        outputs=[status_indicator, instance_info]
+    )
+
+    refresh_perf_btn.click(
+        fn=handle_refresh_performance,
+        outputs=[fps_display, frame_time_display, draw_calls_display]
+    )
+
+    fetch_logs_btn.click(
+        fn=handle_fetch_logs,
+        inputs=[log_category, log_limit],
+        outputs=[logs_display]
+    )
+
+    clear_logs_btn.click(
+        fn=lambda: "",
+        outputs=[logs_display]
+    )
+
+    return {
+        "status_indicator": status_indicator,
+        "instance_info": instance_info,
+        "ping_result": ping_result,
+        "fps_display": fps_display,
+        "frame_time_display": frame_time_display,
+        "draw_calls_display": draw_calls_display,
+        "logs_display": logs_display,
+    }

tabs/scene_control.py

@@ -0,0 +1,335 @@
+"""
+Kariana Unified UI - Scene Control Tab
+Visual scene manipulation: actor browser, transforms, materials
+"""
+
+import gradio as gr
+import logging
+from typing import Dict, List, Optional
+import json
+
+logger = logging.getLogger(__name__)
+
+try:
+    from ..core.connection import get_connection
+except ImportError:
+    get_connection = None
+
+
+def create_scene_control_tab() -> Dict:
+    """Create the Scene Control tab"""
+
+    with gr.Column():
+        gr.Markdown("## Scene Control")
+
+        with gr.Row():
+            # Left Panel: Actor Browser
+            with gr.Column(scale=1):
+                gr.Markdown("### World Outliner")
+
+                with gr.Row():
+                    refresh_actors_btn = gr.Button("Refresh", size="sm")
+                    actor_search = gr.Textbox(
+                        placeholder="Search actors...",
+                        show_label=False,
+                        scale=2
+                    )
+
+                actor_list = gr.Dataframe(
+                    headers=["Name", "Type", "Folder"],
+                    datatype=["str", "str", "str"],
+                    interactive=False,
+                    label="Actors",
+                    max_rows=20
+                )
+
+                selected_actor = gr.Textbox(
+                    label="Selected Actor",
+                    interactive=False
+                )
+
+            # Right Panel: Properties
+            with gr.Column(scale=1):
+                gr.Markdown("### Transform")
+
+                with gr.Group():
+                    gr.Markdown("**Location**")
+                    with gr.Row():
+                        loc_x = gr.Number(label="X", value=0, scale=1)
+                        loc_y = gr.Number(label="Y", value=0, scale=1)
+                        loc_z = gr.Number(label="Z", value=0, scale=1)
+
+                with gr.Group():
+                    gr.Markdown("**Rotation**")
+                    with gr.Row():
+                        rot_x = gr.Number(label="Pitch", value=0, scale=1)
+                        rot_y = gr.Number(label="Yaw", value=0, scale=1)
+                        rot_z = gr.Number(label="Roll", value=0, scale=1)
+
+                with gr.Group():
+                    gr.Markdown("**Scale**")
+                    with gr.Row():
+                        scale_x = gr.Number(label="X", value=1, scale=1)
+                        scale_y = gr.Number(label="Y", value=1, scale=1)
+                        scale_z = gr.Number(label="Z", value=1, scale=1)
+
+                with gr.Row():
+                    get_transform_btn = gr.Button("Get Transform", size="sm")
+                    set_transform_btn = gr.Button("Set Transform", variant="primary", size="sm")
+
+                transform_result = gr.Markdown("")
+
+        gr.Markdown("---")
+
+        # Quick Actions
+        gr.Markdown("### Quick Actions")
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("**Spawn Actor**")
+                actor_type = gr.Dropdown(
+                    label="Type",
+                    choices=[
+                        "Cube",
+                        "Sphere",
+                        "Cylinder",
+                        "Cone",
+                        "PointLight",
+                        "SpotLight",
+                        "DirectionalLight",
+                        "Camera",
+                        "Empty"
+                    ],
+                    value="Cube"
+                )
+                actor_name = gr.Textbox(label="Name", placeholder="MyActor")
+                spawn_btn = gr.Button("Spawn", variant="primary")
+
+            with gr.Column(scale=1):
+                gr.Markdown("**Delete Actor**")
+                delete_name = gr.Textbox(label="Actor Name", placeholder="ActorToDelete")
+                delete_btn = gr.Button("Delete", variant="stop")
+
+        spawn_result = gr.Markdown("")
+
+        gr.Markdown("---")
+
+        # Screenshot Preview
+        gr.Markdown("### Scene Preview")
+        with gr.Row():
+            capture_btn = gr.Button("Capture Screenshot", size="sm")
+
+        screenshot_display = gr.Image(label="Viewport Screenshot", type="filepath")
+
+    # Event Handlers
+    def handle_refresh_actors(search: str = "") -> List[List]:
+        """Refresh actor list"""
+        try:
+            if get_connection is None:
+                return [["N/A", "Module not available", ""]]
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return [["N/A", "Not connected", ""]]
+
+            actors = conn.list_actors()
+            if not actors:
+                return [["No actors", "", ""]]
+
+            rows = []
+            for actor in actors:
+                name = actor.get("name", "Unknown")
+                actor_type = actor.get("type", actor.get("class", "Unknown"))
+                folder = actor.get("folder", "")
+
+                # Apply search filter
+                if search and search.lower() not in name.lower():
+                    continue
+
+                rows.append([name, actor_type, folder])
+
+            return rows if rows else [["No matching actors", "", ""]]
+        except Exception as e:
+            logger.error(f"Actor list error: {e}")
+            return [[f"Error: {str(e)}", "", ""]]
+
+    def handle_select_actor(evt: gr.SelectData, data) -> str:
+        """Handle actor selection from table"""
+        try:
+            if evt.index is not None and len(evt.index) >= 1:
+                row_idx = evt.index[0]
+                if data and len(data) > row_idx:
+                    return data[row_idx][0]  # Return actor name
+        except:
+            pass
+        return ""
+
+    def handle_get_transform(actor_name: str) -> tuple:
+        """Get transform of selected actor"""
+        if not actor_name:
+            return 0, 0, 0, 0, 0, 0, 1, 1, 1, "Select an actor first"
+
+        try:
+            if get_connection is None:
+                return 0, 0, 0, 0, 0, 0, 1, 1, 1, "Module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return 0, 0, 0, 0, 0, 0, 1, 1, 1, "Not connected"
+
+            result = conn.get_actor_transform(actor_name)
+            if result and result.get("success"):
+                loc = result.get("location", [0, 0, 0])
+                rot = result.get("rotation", [0, 0, 0])
+                scale = result.get("scale", [1, 1, 1])
+                return (
+                    loc[0], loc[1], loc[2],
+                    rot[0], rot[1], rot[2],
+                    scale[0], scale[1], scale[2],
+                    f"Transform loaded for {actor_name}"
+                )
+            return 0, 0, 0, 0, 0, 0, 1, 1, 1, f"Failed to get transform: {result.get('error', 'Unknown error')}"
+        except Exception as e:
+            return 0, 0, 0, 0, 0, 0, 1, 1, 1, f"Error: {str(e)}"
+
+    def handle_set_transform(
+        actor_name: str,
+        lx, ly, lz,
+        rx, ry, rz,
+        sx, sy, sz
+    ) -> str:
+        """Set transform of selected actor"""
+        if not actor_name:
+            return "Select an actor first"
+
+        try:
+            if get_connection is None:
+                return "Module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "Not connected"
+
+            result = conn.set_actor_transform(
+                actor_name,
+                location=[lx, ly, lz],
+                rotation=[rx, ry, rz],
+                scale=[sx, sy, sz]
+            )
+            if result and result.get("success"):
+                return f"Transform updated for {actor_name}"
+            return f"Failed: {result.get('error', 'Unknown error')}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def handle_spawn(actor_type: str, name: str) -> str:
+        """Spawn new actor"""
+        if not name:
+            return "Enter an actor name"
+
+        try:
+            if get_connection is None:
+                return "Module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "Not connected"
+
+            result = conn.spawn_actor(actor_type, name)
+            if result and result.get("success"):
+                return f"Spawned {actor_type}: {name}"
+            return f"Failed: {result.get('error', 'Unknown error')}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def handle_delete(name: str) -> str:
+        """Delete actor"""
+        if not name:
+            return "Enter actor name to delete"
+
+        try:
+            if get_connection is None:
+                return "Module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "Not connected"
+
+            result = conn.delete_actor(name)
+            if result and result.get("success"):
+                return f"Deleted: {name}"
+            return f"Failed: {result.get('error', 'Unknown error')}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def handle_capture() -> Optional[str]:
+        """Capture screenshot"""
+        try:
+            if get_connection is None:
+                return None
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return None
+
+            result = conn.capture_screenshot()
+            if result and result.get("success"):
+                return result.get("path")
+            return None
+        except Exception as e:
+            logger.error(f"Screenshot error: {e}")
+            return None
+
+    # Wire up event handlers
+    refresh_actors_btn.click(
+        fn=handle_refresh_actors,
+        inputs=[actor_search],
+        outputs=[actor_list]
+    )
+
+    actor_search.change(
+        fn=handle_refresh_actors,
+        inputs=[actor_search],
+        outputs=[actor_list]
+    )
+
+    actor_list.select(
+        fn=handle_select_actor,
+        inputs=[actor_list],
+        outputs=[selected_actor]
+    )
+
+    get_transform_btn.click(
+        fn=handle_get_transform,
+        inputs=[selected_actor],
+        outputs=[loc_x, loc_y, loc_z, rot_x, rot_y, rot_z, scale_x, scale_y, scale_z, transform_result]
+    )
+
+    set_transform_btn.click(
+        fn=handle_set_transform,
+        inputs=[selected_actor, loc_x, loc_y, loc_z, rot_x, rot_y, rot_z, scale_x, scale_y, scale_z],
+        outputs=[transform_result]
+    )
+
+    spawn_btn.click(
+        fn=handle_spawn,
+        inputs=[actor_type, actor_name],
+        outputs=[spawn_result]
+    )
+
+    delete_btn.click(
+        fn=handle_delete,
+        inputs=[delete_name],
+        outputs=[spawn_result]
+    )
+
+    capture_btn.click(
+        fn=handle_capture,
+        outputs=[screenshot_display]
+    )
+
+    return {
+        "actor_list": actor_list,
+        "selected_actor": selected_actor,
+        "screenshot_display": screenshot_display,
+    }

tabs/setup.py

@@ -0,0 +1,236 @@
+"""
+Kariana Unified UI - Setup Tab
+Handles connection setup, PIN authentication, and configuration
+"""
+
+import gradio as gr
+import logging
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Import will work once the package is properly set up
+try:
+    from ..core.connection import get_connection
+    from ..core.auth import get_authenticator
+    from ..utils.discovery import discover_instances, UnrealInstance
+except ImportError:
+    # Fallback for development
+    get_connection = None
+    get_authenticator = None
+    discover_instances = None
+    UnrealInstance = None
+
+
+def create_setup_tab() -> Dict:
+    """Create the Setup & Configuration tab"""
+
+    with gr.Column():
+        gr.Markdown("## Connection Setup")
+        gr.Markdown("Enter the 4-digit PIN shown in Unreal Editor to connect.")
+
+        # PIN Input Section
+        with gr.Row():
+            with gr.Column(scale=2):
+                pin_input = gr.Textbox(
+                    label="Connection PIN",
+                    placeholder="Enter 4-digit PIN",
+                    max_lines=1,
+                    elem_classes=["pin-input"]
+                )
+
+            with gr.Column(scale=1):
+                connect_btn = gr.Button("Connect", variant="primary", size="lg")
+                disconnect_btn = gr.Button("Disconnect", variant="secondary")
+
+        connection_result = gr.Markdown("")
+
+        gr.Markdown("---")
+
+        # Instance Discovery Section
+        gr.Markdown("### Discovered Instances")
+        with gr.Row():
+            discover_btn = gr.Button("Discover Instances", size="sm")
+            clear_btn = gr.Button("Clear", size="sm")
+
+        instances_table = gr.Dataframe(
+            headers=["Port", "Project", "Instance ID", "Status"],
+            datatype=["number", "str", "str", "str"],
+            interactive=False,
+            label="Running Instances"
+        )
+
+        gr.Markdown("---")
+
+        # Configuration Section
+        gr.Markdown("### Configuration")
+
+        with gr.Accordion("Advanced Settings", open=False):
+            with gr.Row():
+                host_input = gr.Textbox(
+                    label="Unreal Host",
+                    value="localhost",
+                    info="Host where Unreal Engine is running"
+                )
+                port_range_start = gr.Number(
+                    label="Port Range Start",
+                    value=9877,
+                    precision=0
+                )
+                port_range_end = gr.Number(
+                    label="Port Range End",
+                    value=9887,
+                    precision=0
+                )
+
+            timeout_input = gr.Slider(
+                label="Connection Timeout (seconds)",
+                minimum=1,
+                maximum=30,
+                value=5,
+                step=1
+            )
+
+        with gr.Accordion("Claude Desktop Config", open=False):
+            gr.Markdown("""
+            Copy this configuration to your Claude Desktop config file:
+
+            **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+            **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`
+            """)
+
+            config_output = gr.Code(
+                label="Configuration JSON",
+                language="json",
+                value="""{
+  "mcpServers": {
+    "kariana-umcp": {
+      "command": "python",
+      "args": ["-m", "kariana_mcp_server"],
+      "env": {
+        "UNREAL_HOST": "localhost",
+        "UNREAL_PORT": "9877"
+      }
+    }
+  }
+}"""
+            )
+
+            generate_config_btn = gr.Button("Generate Config for Connected Instance")
+
+    # Event Handlers
+    def handle_connect(pin: str) -> str:
+        """Handle PIN connection"""
+        if not pin or len(pin) != 4 or not pin.isdigit():
+            return "**Error:** Please enter a valid 4-digit PIN"
+
+        try:
+            if get_connection is None:
+                return "**Error:** Connection module not available"
+
+            conn = get_connection()
+            if conn.connect_with_pin(pin):
+                instance = conn.instance
+                return f"**Connected!** Project: {instance.project_name}, Port: {instance.port}"
+            else:
+                return "**Error:** Invalid PIN or no instances found"
+        except Exception as e:
+            logger.error(f"Connection error: {e}")
+            return f"**Error:** {str(e)}"
+
+    def handle_disconnect() -> str:
+        """Handle disconnect"""
+        try:
+            if get_connection is None:
+                return "Connection module not available"
+
+            conn = get_connection()
+            conn.disconnect()
+            return "**Disconnected**"
+        except Exception as e:
+            return f"**Error:** {str(e)}"
+
+    def handle_discover() -> List[List]:
+        """Discover running instances"""
+        try:
+            if discover_instances is None:
+                return [["N/A", "Discovery not available", "N/A", "Error"]]
+
+            instances = discover_instances()
+            if not instances:
+                return [["N/A", "No instances found", "N/A", "Not Running"]]
+
+            rows = []
+            for inst in instances:
+                rows.append([
+                    inst.port,
+                    inst.project_name or "Unknown",
+                    inst.instance_id[:16] + "..." if inst.instance_id else "N/A",
+                    "Connected" if inst.authenticated else "Available"
+                ])
+            return rows
+        except Exception as e:
+            logger.error(f"Discovery error: {e}")
+            return [["N/A", f"Error: {str(e)}", "N/A", "Error"]]
+
+    def generate_claude_config() -> str:
+        """Generate Claude Desktop config for connected instance"""
+        try:
+            if get_connection is None:
+                return '{"error": "Connection module not available"}'
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return '{"error": "Not connected to any instance"}'
+
+            config = {
+                "mcpServers": {
+                    "kariana-umcp": {
+                        "command": "python",
+                        "args": ["-m", "kariana_mcp_server"],
+                        "env": {
+                            "UNREAL_HOST": conn.instance.host,
+                            "UNREAL_PORT": str(conn.instance.port)
+                        }
+                    }
+                }
+            }
+            import json
+            return json.dumps(config, indent=2)
+        except Exception as e:
+            return f'{{"error": "{str(e)}"}}'
+
+    # Wire up event handlers
+    connect_btn.click(
+        fn=handle_connect,
+        inputs=[pin_input],
+        outputs=[connection_result]
+    )
+
+    disconnect_btn.click(
+        fn=handle_disconnect,
+        outputs=[connection_result]
+    )
+
+    discover_btn.click(
+        fn=handle_discover,
+        outputs=[instances_table]
+    )
+
+    clear_btn.click(
+        fn=lambda: [],
+        outputs=[instances_table]
+    )
+
+    generate_config_btn.click(
+        fn=generate_claude_config,
+        outputs=[config_output]
+    )
+
+    return {
+        "pin_input": pin_input,
+        "connect_btn": connect_btn,
+        "disconnect_btn": disconnect_btn,
+        "connection_result": connection_result,
+        "instances_table": instances_table,
+    }

tabs/skills_agents.py

@@ -0,0 +1,296 @@
+"""
+Kariana Unified UI - Skills & Agents Tab
+Browse, execute, and monitor Claude skills and agents
+"""
+
+import gradio as gr
+import logging
+from typing import Dict, List, Optional
+import json
+
+logger = logging.getLogger(__name__)
+
+try:
+    from ..core.connection import get_connection
+except ImportError:
+    get_connection = None
+
+# Available agents (from .claude/agents/)
+AVAILABLE_AGENTS = [
+    {
+        "name": "Scene Analyst",
+        "file": "scene-analyst.md",
+        "description": "Transform natural language into structured scene specifications"
+    },
+    {
+        "name": "Asset Scout",
+        "file": "asset-scout.md",
+        "description": "Discover and catalog assets in Unreal project"
+    },
+    {
+        "name": "Pattern Strategist",
+        "file": "pattern-strategist.md",
+        "description": "Select and configure spatial generation patterns"
+    },
+    {
+        "name": "Executor",
+        "file": "executor.md",
+        "description": "Execute generation strategies using MCP tools"
+    },
+    {
+        "name": "World Organizer",
+        "file": "world-organizer.md",
+        "description": "Automate World Outliner organization"
+    },
+    {
+        "name": "Orchestrator",
+        "file": "orchestrator.md",
+        "description": "Coordinate multiple agents for complex tasks"
+    },
+    {
+        "name": "MCP Log Monitor",
+        "file": "mcp-log-monitor.md",
+        "description": "Monitor MCP server logs and diagnose issues"
+    },
+    {
+        "name": "Project Organizer",
+        "file": "project-organizer.md",
+        "description": "Discover project structure and organize assets"
+    }
+]
+
+
+def create_skills_agents_tab() -> Dict:
+    """Create the Skills & Agents tab"""
+
+    with gr.Column():
+        with gr.Row():
+            # Left Panel: Skills Browser
+            with gr.Column(scale=1):
+                gr.Markdown("## Skills")
+
+                with gr.Row():
+                    refresh_skills_btn = gr.Button("Refresh", size="sm")
+                    skill_search = gr.Textbox(
+                        placeholder="Search skills...",
+                        show_label=False,
+                        scale=2
+                    )
+
+                skills_list = gr.Dataframe(
+                    headers=["Name", "Description", "Version"],
+                    datatype=["str", "str", "str"],
+                    interactive=False,
+                    label="Available Skills",
+                    max_rows=15
+                )
+
+                selected_skill = gr.Textbox(
+                    label="Selected Skill",
+                    interactive=False
+                )
+
+            # Right Panel: Skill Details & Execution
+            with gr.Column(scale=1):
+                gr.Markdown("## Skill Details")
+
+                skill_info = gr.JSON(
+                    label="Skill Information",
+                    value={}
+                )
+
+                gr.Markdown("### Parameters")
+                skill_params = gr.Code(
+                    label="Parameters (JSON)",
+                    language="json",
+                    value="{}"
+                )
+
+                with gr.Row():
+                    execute_skill_btn = gr.Button("Execute", variant="primary")
+                    dry_run_btn = gr.Button("Dry Run", variant="secondary")
+
+                skill_result = gr.TextArea(
+                    label="Execution Result",
+                    lines=8,
+                    interactive=False
+                )
+
+        gr.Markdown("---")
+
+        # Agents Section
+        gr.Markdown("## Claude Agents")
+        gr.Markdown("Specialized AI agents for complex tasks. Activate an agent to see its capabilities.")
+
+        with gr.Row():
+            agent_dropdown = gr.Dropdown(
+                label="Select Agent",
+                choices=[a["name"] for a in AVAILABLE_AGENTS],
+                value=AVAILABLE_AGENTS[0]["name"] if AVAILABLE_AGENTS else None
+            )
+            activate_agent_btn = gr.Button("View Agent Details", variant="secondary")
+
+        agent_info = gr.Markdown("")
+
+        with gr.Accordion("Agent Descriptions", open=False):
+            agents_table = gr.Dataframe(
+                headers=["Agent", "Description"],
+                datatype=["str", "str"],
+                value=[[a["name"], a["description"]] for a in AVAILABLE_AGENTS],
+                interactive=False
+            )
+
+    # Event Handlers
+    def handle_refresh_skills(search: str = "") -> List[List]:
+        """Refresh skills list"""
+        try:
+            if get_connection is None:
+                return [["N/A", "Module not available", ""]]
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return [["N/A", "Not connected", ""]]
+
+            skills = conn.list_skills()
+            if not skills:
+                return [["No skills found", "", ""]]
+
+            rows = []
+            for skill in skills:
+                name = skill.get("name", "Unknown")
+                desc = skill.get("description", "")[:50] + "..." if len(skill.get("description", "")) > 50 else skill.get("description", "")
+                version = skill.get("version", "1.0.0")
+
+                if search and search.lower() not in name.lower() and search.lower() not in desc.lower():
+                    continue
+
+                rows.append([name, desc, version])
+
+            return rows if rows else [["No matching skills", "", ""]]
+        except Exception as e:
+            logger.error(f"Skills list error: {e}")
+            return [[f"Error: {str(e)}", "", ""]]
+
+    def handle_select_skill(evt: gr.SelectData, data) -> tuple:
+        """Handle skill selection"""
+        try:
+            if evt.index is not None and len(evt.index) >= 1:
+                row_idx = evt.index[0]
+                if data and len(data) > row_idx:
+                    skill_name = data[row_idx][0]
+
+                    # Get full skill info
+                    if get_connection:
+                        conn = get_connection()
+                        if conn.is_connected:
+                            # Try to get detailed skill info
+                            result = conn.send_command("load_skill", skill_name=skill_name)
+                            if result and result.get("success"):
+                                skill_data = result.get("skill", {})
+                                return skill_name, skill_data, "{}"
+
+                    return skill_name, {"name": skill_name}, "{}"
+        except Exception as e:
+            logger.error(f"Skill selection error: {e}")
+
+        return "", {}, "{}"
+
+    def handle_execute_skill(skill_name: str, params_json: str, dry_run: bool = False) -> str:
+        """Execute a skill"""
+        if not skill_name:
+            return "Select a skill first"
+
+        try:
+            params = json.loads(params_json) if params_json.strip() else {}
+        except json.JSONDecodeError as e:
+            return f"Invalid JSON parameters: {e}"
+
+        try:
+            if get_connection is None:
+                return "Module not available"
+
+            conn = get_connection()
+            if not conn.is_connected:
+                return "Not connected"
+
+            if dry_run:
+                return f"DRY RUN - Would execute skill '{skill_name}' with params:\n{json.dumps(params, indent=2)}"
+
+            result = conn.execute_skill(skill_name, params)
+            if result:
+                if result.get("success"):
+                    return f"Success!\n\n{json.dumps(result.get('result', {}), indent=2)}"
+                return f"Failed: {result.get('error', 'Unknown error')}"
+            return "No response from server"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def handle_view_agent(agent_name: str) -> str:
+        """View agent details"""
+        agent = next((a for a in AVAILABLE_AGENTS if a["name"] == agent_name), None)
+        if not agent:
+            return "Agent not found"
+
+        return f"""
+### {agent['name']}
+
+**Description:** {agent['description']}
+
+**Configuration File:** `.claude/agents/{agent['file']}`
+
+**How to Use:**
+1. Open Claude Code in this project
+2. Ask Claude to activate the {agent['name']} agent
+3. Provide your task description
+4. The agent will coordinate with UMCP tools to complete the task
+
+**Example Prompts:**
+- "Activate the {agent['name']} to help me..."
+- "Use the {agent['name']} agent for..."
+"""
+
+    # Wire up event handlers
+    refresh_skills_btn.click(
+        fn=handle_refresh_skills,
+        inputs=[skill_search],
+        outputs=[skills_list]
+    )
+
+    skill_search.change(
+        fn=handle_refresh_skills,
+        inputs=[skill_search],
+        outputs=[skills_list]
+    )
+
+    skills_list.select(
+        fn=handle_select_skill,
+        inputs=[skills_list],
+        outputs=[selected_skill, skill_info, skill_params]
+    )
+
+    execute_skill_btn.click(
+        fn=lambda n, p: handle_execute_skill(n, p, False),
+        inputs=[selected_skill, skill_params],
+        outputs=[skill_result]
+    )
+
+    dry_run_btn.click(
+        fn=lambda n, p: handle_execute_skill(n, p, True),
+        inputs=[selected_skill, skill_params],
+        outputs=[skill_result]
+    )
+
+    activate_agent_btn.click(
+        fn=handle_view_agent,
+        inputs=[agent_dropdown],
+        outputs=[agent_info]
+    )
+
+    return {
+        "skills_list": skills_list,
+        "selected_skill": selected_skill,
+        "skill_info": skill_info,
+        "skill_result": skill_result,
+        "agent_dropdown": agent_dropdown,
+        "agent_info": agent_info,
+    }

tabs/workflow_builder.py

@@ -0,0 +1,460 @@
+"""
+Kariana Unified UI - Workflow Builder Tab
+Form-based workflow creation and execution
+"""
+
+import gradio as gr
+import logging
+from typing import Dict, List, Optional
+import json
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+try:
+    from ..core.connection import get_connection
+    from ..core.session import get_session_manager
+except ImportError:
+    get_connection = None
+    get_session_manager = None
+
+# Available actions for workflow steps
+WORKFLOW_ACTIONS = {
+    "spawn_actor": {
+        "description": "Spawn a new actor in the level",
+        "params": ["actor_type", "name", "location_x", "location_y", "location_z"]
+    },
+    "delete_actor": {
+        "description": "Delete an actor by name",
+        "params": ["actor_name"]
+    },
+    "set_actor_transform": {
+        "description": "Set actor location, rotation, scale",
+        "params": ["actor_name", "location_x", "location_y", "location_z", "rotation_x", "rotation_y", "rotation_z", "scale_x", "scale_y", "scale_z"]
+    },
+    "execute_python": {
+        "description": "Execute Python code in Unreal",
+        "params": ["code"]
+    },
+    "console_command": {
+        "description": "Execute Unreal console command",
+        "params": ["command"]
+    },
+    "capture_screenshot": {
+        "description": "Capture viewport screenshot",
+        "params": ["filename"]
+    },
+    "execute_skill": {
+        "description": "Execute a skill",
+        "params": ["skill_name", "params"]
+    },
+    "wait": {
+        "description": "Wait for specified seconds",
+        "params": ["seconds"]
+    }
+}
+
+
+def create_workflow_builder_tab() -> Dict:
+    """Create the Workflow Builder tab"""
+
+    with gr.Column():
+        gr.Markdown("## Workflow Builder")
+        gr.Markdown("Create multi-step workflows using a form-based interface.")
+
+        with gr.Row():
+            # Left Panel: Workflow Definition
+            with gr.Column(scale=2):
+                gr.Markdown("### Workflow Definition")
+
+                workflow_name = gr.Textbox(
+                    label="Workflow Name",
+                    placeholder="my_workflow"
+                )
+
+                workflow_description = gr.Textbox(
+                    label="Description",
+                    placeholder="What this workflow does...",
+                    lines=2
+                )
+
+                gr.Markdown("---")
+                gr.Markdown("### Steps")
+
+                # Step Builder
+                with gr.Group():
+                    gr.Markdown("**Add Step**")
+
+                    step_type = gr.Dropdown(
+                        label="Step Type",
+                        choices=["Action", "Condition"],
+                        value="Action"
+                    )
+
+                    action_dropdown = gr.Dropdown(
+                        label="Action",
+                        choices=list(WORKFLOW_ACTIONS.keys()),
+                        value="spawn_actor"
+                    )
+
+                    action_description = gr.Markdown("*Select an action to see description*")
+
+                    # Dynamic parameter inputs
+                    param_1 = gr.Textbox(label="Parameter 1", visible=True)
+                    param_2 = gr.Textbox(label="Parameter 2", visible=True)
+                    param_3 = gr.Textbox(label="Parameter 3", visible=True)
+                    param_4 = gr.Textbox(label="Parameter 4", visible=False)
+                    param_5 = gr.Textbox(label="Parameter 5", visible=False)
+
+                    with gr.Row():
+                        add_step_btn = gr.Button("Add Step", variant="primary")
+                        clear_form_btn = gr.Button("Clear Form")
+
+                # Steps List (JSON representation)
+                steps_json = gr.Code(
+                    label="Workflow Steps (JSON)",
+                    language="json",
+                    value="[]",
+                    lines=10
+                )
+
+                with gr.Row():
+                    remove_last_step_btn = gr.Button("Remove Last Step", size="sm")
+                    clear_all_steps_btn = gr.Button("Clear All Steps", size="sm", variant="stop")
+
+            # Right Panel: Execution & Saved Workflows
+            with gr.Column(scale=1):
+                gr.Markdown("### Execution")
+
+                with gr.Row():
+                    execute_workflow_btn = gr.Button("Execute Workflow", variant="primary")
+                    stop_workflow_btn = gr.Button("Stop", variant="stop")
+
+                execution_log = gr.TextArea(
+                    label="Execution Log",
+                    lines=12,
+                    interactive=False
+                )
+
+                execution_progress = gr.Progress()
+
+                gr.Markdown("---")
+                gr.Markdown("### Save & Load")
+
+                with gr.Row():
+                    save_workflow_btn = gr.Button("Save Workflow", size="sm")
+                    load_workflow_dropdown = gr.Dropdown(
+                        label="Load Workflow",
+                        choices=[],
+                        scale=2
+                    )
+                    load_btn = gr.Button("Load", size="sm")
+
+                with gr.Accordion("Saved Workflows", open=False):
+                    saved_workflows_list = gr.Dataframe(
+                        headers=["Name", "Steps", "Created"],
+                        datatype=["str", "number", "str"],
+                        interactive=False
+                    )
+                    refresh_saved_btn = gr.Button("Refresh List", size="sm")
+                    delete_workflow_btn = gr.Button("Delete Selected", size="sm", variant="stop")
+
+        gr.Markdown("---")
+
+        # Templates Section
+        with gr.Accordion("Workflow Templates", open=False):
+            gr.Markdown("Quick-start templates for common workflows:")
+
+            with gr.Row():
+                template_scatter = gr.Button("Scatter Objects", size="sm")
+                template_lighting = gr.Button("3-Point Lighting", size="sm")
+                template_cleanup = gr.Button("Scene Cleanup", size="sm")
+                template_screenshot = gr.Button("Screenshot Sequence", size="sm")
+
+    # Event Handlers
+    def update_action_params(action: str) -> tuple:
+        """Update parameter fields based on selected action"""
+        if action not in WORKFLOW_ACTIONS:
+            return gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), ""
+
+        action_info = WORKFLOW_ACTIONS[action]
+        params = action_info["params"]
+        desc = f"*{action_info['description']}*"
+
+        # Show/hide and label parameter fields
+        updates = []
+        for i in range(5):
+            if i < len(params):
+                updates.append(gr.update(visible=True, label=params[i], value=""))
+            else:
+                updates.append(gr.update(visible=False, value=""))
+
+        return *updates, desc
+
+    def add_step(action: str, p1: str, p2: str, p3: str, p4: str, p5: str, current_steps: str) -> str:
+        """Add a step to the workflow"""
+        try:
+            steps = json.loads(current_steps) if current_steps else []
+        except:
+            steps = []
+
+        action_info = WORKFLOW_ACTIONS.get(action, {"params": []})
+        params = action_info["params"]
+
+        # Build step with filled parameters
+        step = {"action": action, "params": {}}
+        param_values = [p1, p2, p3, p4, p5]
+
+        for i, param_name in enumerate(params):
+            if i < len(param_values) and param_values[i]:
+                step["params"][param_name] = param_values[i]
+
+        steps.append(step)
+        return json.dumps(steps, indent=2)
+
+    def remove_last_step(current_steps: str) -> str:
+        """Remove the last step"""
+        try:
+            steps = json.loads(current_steps) if current_steps else []
+            if steps:
+                steps.pop()
+            return json.dumps(steps, indent=2)
+        except:
+            return "[]"
+
+    def execute_workflow(name: str, desc: str, steps_json: str) -> str:
+        """Execute the workflow"""
+        try:
+            steps = json.loads(steps_json) if steps_json else []
+        except json.JSONDecodeError:
+            return "Invalid workflow JSON"
+
+        if not steps:
+            return "No steps to execute"
+
+        log_lines = [f"Executing workflow: {name or 'Unnamed'}"]
+        log_lines.append(f"Description: {desc or 'No description'}")
+        log_lines.append(f"Total steps: {len(steps)}")
+        log_lines.append("-" * 40)
+
+        if get_connection is None:
+            return "\n".join(log_lines + ["ERROR: Connection module not available"])
+
+        conn = get_connection()
+        if not conn.is_connected:
+            return "\n".join(log_lines + ["ERROR: Not connected to Unreal"])
+
+        for i, step in enumerate(steps):
+            action = step.get("action", "unknown")
+            params = step.get("params", {})
+
+            log_lines.append(f"\n[Step {i+1}/{len(steps)}] {action}")
+
+            try:
+                if action == "wait":
+                    import time
+                    seconds = float(params.get("seconds", 1))
+                    time.sleep(seconds)
+                    log_lines.append(f"  Waited {seconds}s")
+                elif action == "spawn_actor":
+                    loc = [
+                        float(params.get("location_x", 0)),
+                        float(params.get("location_y", 0)),
+                        float(params.get("location_z", 0))
+                    ]
+                    result = conn.spawn_actor(
+                        params.get("actor_type", "Cube"),
+                        params.get("name", f"WorkflowActor_{i}"),
+                        location=loc
+                    )
+                    log_lines.append(f"  Result: {result.get('success', False)}")
+                elif action == "delete_actor":
+                    result = conn.delete_actor(params.get("actor_name", ""))
+                    log_lines.append(f"  Result: {result.get('success', False)}")
+                elif action == "execute_python":
+                    result = conn.execute_python(params.get("code", ""))
+                    log_lines.append(f"  Result: {result.get('success', False)}")
+                elif action == "console_command":
+                    result = conn.console_command(params.get("command", ""))
+                    log_lines.append(f"  Result: {result.get('success', False)}")
+                elif action == "capture_screenshot":
+                    result = conn.capture_screenshot(params.get("filename"))
+                    log_lines.append(f"  Result: {result.get('success', False)}")
+                elif action == "execute_skill":
+                    skill_params = json.loads(params.get("params", "{}"))
+                    result = conn.execute_skill(params.get("skill_name", ""), skill_params)
+                    log_lines.append(f"  Result: {result.get('success', False)}")
+                else:
+                    log_lines.append(f"  Unknown action: {action}")
+
+            except Exception as e:
+                log_lines.append(f"  ERROR: {str(e)}")
+
+        log_lines.append("\n" + "-" * 40)
+        log_lines.append("Workflow completed!")
+        return "\n".join(log_lines)
+
+    def save_workflow(name: str, desc: str, steps_json: str) -> tuple:
+        """Save workflow to session"""
+        if not name:
+            return "Enter a workflow name", gr.update()
+
+        try:
+            steps = json.loads(steps_json) if steps_json else []
+        except:
+            return "Invalid workflow JSON", gr.update()
+
+        workflow = {
+            "name": name,
+            "description": desc,
+            "steps": steps,
+            "created": datetime.now().isoformat()
+        }
+
+        if get_session_manager:
+            session_mgr = get_session_manager()
+            session_mgr.save_workflow(workflow)
+
+        return f"Saved workflow: {name}", gr.update(choices=get_saved_workflow_names())
+
+    def get_saved_workflow_names() -> List[str]:
+        """Get list of saved workflow names"""
+        if get_session_manager:
+            session_mgr = get_session_manager()
+            workflows = session_mgr.get_workflows()
+            return [w.get("name", "unnamed") for w in workflows]
+        return []
+
+    def load_workflow(name: str) -> tuple:
+        """Load a saved workflow"""
+        if not name or not get_session_manager:
+            return "", "", "[]"
+
+        session_mgr = get_session_manager()
+        workflows = session_mgr.get_workflows()
+
+        for w in workflows:
+            if w.get("name") == name:
+                return w.get("name", ""), w.get("description", ""), json.dumps(w.get("steps", []), indent=2)
+
+        return "", "", "[]"
+
+    def get_saved_workflows_data() -> List[List]:
+        """Get saved workflows for display"""
+        if not get_session_manager:
+            return []
+
+        session_mgr = get_session_manager()
+        workflows = session_mgr.get_workflows()
+
+        return [
+            [w.get("name", ""), len(w.get("steps", [])), w.get("created", "")[:10]]
+            for w in workflows
+        ]
+
+    def apply_template(template_name: str) -> tuple:
+        """Apply a workflow template"""
+        templates = {
+            "scatter": {
+                "name": "scatter_objects",
+                "description": "Scatter multiple objects in the scene",
+                "steps": [
+                    {"action": "spawn_actor", "params": {"actor_type": "Cube", "name": "ScatterCube_1", "location_x": "0", "location_y": "0", "location_z": "0"}},
+                    {"action": "spawn_actor", "params": {"actor_type": "Cube", "name": "ScatterCube_2", "location_x": "200", "location_y": "0", "location_z": "0"}},
+                    {"action": "spawn_actor", "params": {"actor_type": "Cube", "name": "ScatterCube_3", "location_x": "0", "location_y": "200", "location_z": "0"}},
+                ]
+            },
+            "lighting": {
+                "name": "three_point_lighting",
+                "description": "Create a 3-point lighting setup",
+                "steps": [
+                    {"action": "spawn_actor", "params": {"actor_type": "PointLight", "name": "KeyLight", "location_x": "300", "location_y": "-300", "location_z": "400"}},
+                    {"action": "spawn_actor", "params": {"actor_type": "PointLight", "name": "FillLight", "location_x": "-300", "location_y": "-200", "location_z": "300"}},
+                    {"action": "spawn_actor", "params": {"actor_type": "PointLight", "name": "BackLight", "location_x": "0", "location_y": "400", "location_z": "350"}},
+                ]
+            },
+            "cleanup": {
+                "name": "scene_cleanup",
+                "description": "Clean up scene by removing test actors",
+                "steps": [
+                    {"action": "console_command", "params": {"command": "stat none"}},
+                    {"action": "execute_python", "params": {"code": "unreal.log('Scene cleanup started')"}},
+                ]
+            },
+            "screenshot": {
+                "name": "screenshot_sequence",
+                "description": "Capture multiple screenshots",
+                "steps": [
+                    {"action": "capture_screenshot", "params": {"filename": "shot_1.png"}},
+                    {"action": "wait", "params": {"seconds": "1"}},
+                    {"action": "capture_screenshot", "params": {"filename": "shot_2.png"}},
+                ]
+            }
+        }
+
+        template = templates.get(template_name, templates["scatter"])
+        return template["name"], template["description"], json.dumps(template["steps"], indent=2)
+
+    # Wire up event handlers
+    action_dropdown.change(
+        fn=update_action_params,
+        inputs=[action_dropdown],
+        outputs=[param_1, param_2, param_3, param_4, param_5, action_description]
+    )
+
+    add_step_btn.click(
+        fn=add_step,
+        inputs=[action_dropdown, param_1, param_2, param_3, param_4, param_5, steps_json],
+        outputs=[steps_json]
+    )
+
+    clear_form_btn.click(
+        fn=lambda: ("", "", "", "", ""),
+        outputs=[param_1, param_2, param_3, param_4, param_5]
+    )
+
+    remove_last_step_btn.click(
+        fn=remove_last_step,
+        inputs=[steps_json],
+        outputs=[steps_json]
+    )
+
+    clear_all_steps_btn.click(
+        fn=lambda: "[]",
+        outputs=[steps_json]
+    )
+
+    execute_workflow_btn.click(
+        fn=execute_workflow,
+        inputs=[workflow_name, workflow_description, steps_json],
+        outputs=[execution_log]
+    )
+
+    save_workflow_btn.click(
+        fn=save_workflow,
+        inputs=[workflow_name, workflow_description, steps_json],
+        outputs=[execution_log, load_workflow_dropdown]
+    )
+
+    load_btn.click(
+        fn=load_workflow,
+        inputs=[load_workflow_dropdown],
+        outputs=[workflow_name, workflow_description, steps_json]
+    )
+
+    refresh_saved_btn.click(
+        fn=get_saved_workflows_data,
+        outputs=[saved_workflows_list]
+    )
+
+    # Template buttons
+    template_scatter.click(fn=lambda: apply_template("scatter"), outputs=[workflow_name, workflow_description, steps_json])
+    template_lighting.click(fn=lambda: apply_template("lighting"), outputs=[workflow_name, workflow_description, steps_json])
+    template_cleanup.click(fn=lambda: apply_template("cleanup"), outputs=[workflow_name, workflow_description, steps_json])
+    template_screenshot.click(fn=lambda: apply_template("screenshot"), outputs=[workflow_name, workflow_description, steps_json])
+
+    return {
+        "workflow_name": workflow_name,
+        "steps_json": steps_json,
+        "execution_log": execution_log,
+    }

utils/__init__.py

@@ -0,0 +1,5 @@
+# Kariana Unified UI - Utils Module
+from .socket_client import SocketClient
+from .discovery import InstanceDiscovery
+
+__all__ = ['SocketClient', 'InstanceDiscovery']

utils/discovery.py

@@ -0,0 +1,129 @@
+"""
+Kariana Unified UI - Instance Discovery
+Discovers running KarianaUMCP instances on the network
+"""
+import asyncio
+import json
+import logging
+from dataclasses import dataclass
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class UnrealInstance:
+    """Represents a discovered Unreal Engine instance"""
+    host: str
+    port: int
+    instance_id: Optional[str] = None
+    project_name: Optional[str] = None
+    version: Optional[str] = None
+    uptime: Optional[float] = None
+    authenticated: bool = False
+
+    def to_dict(self) -> dict:
+        return {
+            "host": self.host,
+            "port": self.port,
+            "instance_id": self.instance_id,
+            "project_name": self.project_name,
+            "version": self.version,
+            "uptime": self.uptime,
+            "authenticated": self.authenticated,
+        }
+
+
+class InstanceDiscovery:
+    """Discovers running KarianaUMCP socket server instances"""
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port_range: tuple = (9877, 9887),
+        timeout: float = 1.0
+    ):
+        self.host = host
+        self.port_range = port_range
+        self.timeout = timeout
+
+    async def probe_port(self, port: int) -> Optional[UnrealInstance]:
+        """Probe a single port for KarianaUMCP instance"""
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(self.host, port),
+                timeout=self.timeout
+            )
+
+            # Send get_server_info command
+            command = json.dumps({"type": "get_server_info"}) + "\n"
+            writer.write(command.encode())
+            await writer.drain()
+
+            # Read response
+            response_data = await asyncio.wait_for(
+                reader.readline(),
+                timeout=self.timeout
+            )
+
+            writer.close()
+            await writer.wait_closed()
+
+            if response_data:
+                response = json.loads(response_data.decode().strip())
+                if response.get("status") == "ok" or response.get("success"):
+                    return UnrealInstance(
+                        host=self.host,
+                        port=port,
+                        instance_id=response.get("instance_id"),
+                        project_name=response.get("project_name"),
+                        version=response.get("version"),
+                        uptime=response.get("uptime"),
+                    )
+        except asyncio.TimeoutError:
+            pass
+        except ConnectionRefusedError:
+            pass
+        except json.JSONDecodeError:
+            pass
+        except Exception as e:
+            logger.debug(f"Probe error on port {port}: {e}")
+
+        return None
+
+    async def discover_instances(self) -> List[UnrealInstance]:
+        """Discover all running instances in port range"""
+        tasks = [
+            self.probe_port(port)
+            for port in range(*self.port_range)
+        ]
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        instances = []
+        for result in results:
+            if isinstance(result, UnrealInstance):
+                instances.append(result)
+
+        logger.info(f"Discovered {len(instances)} instance(s)")
+        return instances
+
+    def discover_instances_sync(self) -> List[UnrealInstance]:
+        """Synchronous wrapper for discover_instances"""
+        try:
+            loop = asyncio.get_running_loop()
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(asyncio.run, self.discover_instances())
+                return future.result(timeout=self.timeout * 10 + 1)
+        except RuntimeError:
+            return asyncio.run(self.discover_instances())
+
+
+def discover_instances(
+    host: str = "localhost",
+    port_range: tuple = (9877, 9887)
+) -> List[UnrealInstance]:
+    """Convenience function for instance discovery"""
+    discovery = InstanceDiscovery(host, port_range)
+    return discovery.discover_instances_sync()

utils/socket_client.py

@@ -0,0 +1,186 @@
+"""
+Kariana Unified UI - Async Socket Client
+Handles communication with KarianaUMCP socket server
+"""
+import asyncio
+import json
+import logging
+from typing import Any, Optional, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class SocketClient:
+    """Async socket client for communicating with KarianaUMCP"""
+
+    def __init__(self, host: str = "localhost", port: int = 9877, timeout: float = 5.0):
+        self.host = host
+        self.port = port
+        self.timeout = timeout
+        self._reader: Optional[asyncio.StreamReader] = None
+        self._writer: Optional[asyncio.StreamWriter] = None
+        self._connected = False
+        self._lock = asyncio.Lock()
+
+    @property
+    def connected(self) -> bool:
+        return self._connected and self._writer is not None
+
+    async def connect(self) -> bool:
+        """Establish connection to socket server"""
+        try:
+            self._reader, self._writer = await asyncio.wait_for(
+                asyncio.open_connection(self.host, self.port),
+                timeout=self.timeout
+            )
+            self._connected = True
+            logger.info(f"Connected to {self.host}:{self.port}")
+            return True
+        except asyncio.TimeoutError:
+            logger.warning(f"Connection timeout to {self.host}:{self.port}")
+            return False
+        except ConnectionRefusedError:
+            logger.warning(f"Connection refused at {self.host}:{self.port}")
+            return False
+        except Exception as e:
+            logger.error(f"Connection error: {e}")
+            return False
+
+    async def disconnect(self):
+        """Close connection"""
+        if self._writer:
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except Exception as e:
+                logger.error(f"Error closing connection: {e}")
+            finally:
+                self._writer = None
+                self._reader = None
+                self._connected = False
+
+    async def send_command(self, command: dict) -> Optional[dict]:
+        """Send a command and receive response"""
+        async with self._lock:
+            if not self.connected:
+                if not await self.connect():
+                    return None
+
+            try:
+                # Send command as JSON with newline delimiter
+                message = json.dumps(command) + "\n"
+                self._writer.write(message.encode())
+                await self._writer.drain()
+
+                # Read response (newline-delimited JSON)
+                response_data = await asyncio.wait_for(
+                    self._reader.readline(),
+                    timeout=self.timeout
+                )
+
+                if not response_data:
+                    logger.warning("Empty response received")
+                    return None
+
+                return json.loads(response_data.decode().strip())
+
+            except asyncio.TimeoutError:
+                logger.warning("Response timeout")
+                await self.disconnect()
+                return None
+            except json.JSONDecodeError as e:
+                logger.error(f"Invalid JSON response: {e}")
+                return None
+            except Exception as e:
+                logger.error(f"Command error: {e}")
+                await self.disconnect()
+                return None
+
+    async def ping(self) -> bool:
+        """Test connection with ping command"""
+        response = await self.send_command({"type": "ping"})
+        return response is not None and response.get("status") == "ok"
+
+    async def subscribe(self, event_type: str, callback: Callable[[dict], None]):
+        """Subscribe to real-time events (logs, etc.)"""
+        # Subscribe command
+        response = await self.send_command({
+            "type": f"subscribe_{event_type}"
+        })
+
+        if not response or not response.get("success"):
+            return False
+
+        # Start listening for events in background
+        asyncio.create_task(self._event_listener(event_type, callback))
+        return True
+
+    async def _event_listener(self, event_type: str, callback: Callable[[dict], None]):
+        """Background listener for subscribed events"""
+        try:
+            while self.connected:
+                try:
+                    data = await asyncio.wait_for(
+                        self._reader.readline(),
+                        timeout=1.0
+                    )
+                    if data:
+                        event = json.loads(data.decode().strip())
+                        if event.get("event_type") == event_type:
+                            callback(event)
+                except asyncio.TimeoutError:
+                    continue
+                except json.JSONDecodeError:
+                    continue
+        except Exception as e:
+            logger.error(f"Event listener error: {e}")
+
+
+class SyncSocketClient:
+    """Synchronous wrapper for SocketClient (for Gradio callbacks)"""
+
+    def __init__(self, host: str = "localhost", port: int = 9877, timeout: float = 5.0):
+        self.host = host
+        self.port = port
+        self.timeout = timeout
+        self._client: Optional[SocketClient] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+
+    def _get_loop(self) -> asyncio.AbstractEventLoop:
+        """Get or create event loop"""
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError:
+            if self._loop is None or self._loop.is_closed():
+                self._loop = asyncio.new_event_loop()
+            return self._loop
+
+    def _run(self, coro):
+        """Run coroutine synchronously"""
+        loop = self._get_loop()
+        try:
+            return loop.run_until_complete(coro)
+        except RuntimeError:
+            # Already running in async context, use nest_asyncio pattern
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(asyncio.run, coro)
+                return future.result(timeout=self.timeout + 1)
+
+    def connect(self) -> bool:
+        self._client = SocketClient(self.host, self.port, self.timeout)
+        return self._run(self._client.connect())
+
+    def disconnect(self):
+        if self._client:
+            self._run(self._client.disconnect())
+
+    def send_command(self, command: dict) -> Optional[dict]:
+        if not self._client:
+            self._client = SocketClient(self.host, self.port, self.timeout)
+        return self._run(self._client.send_command(command))
+
+    def ping(self) -> bool:
+        if not self._client:
+            self._client = SocketClient(self.host, self.port, self.timeout)
+        return self._run(self._client.ping())