TERMINAL_README.md

🚀 Manus AI-Style Terminal Integration

This document explains the real-time terminal streaming functionality added to the Data Extractor application.

📋 Overview

The terminal integration provides a Manus AI-style terminal interface with real-time command execution and streaming output, seamlessly integrated into the existing Gradio application.

🏗️ Architecture

Components

1. WebSocket Server (terminal_stream.py)

   • Handles real-time communication between frontend and backend
   • Manages command execution with streaming output
   • Supports multiple concurrent connections
   • Runs on port 8765

2. Frontend Terminal (static/terminal.html)

   • Beautiful Manus AI-inspired terminal interface
   • Real-time output streaming via WebSocket
   • Command history navigation
   • Keyboard shortcuts and controls

3. Gradio Integration (Modified app.py)

   • Added terminal tab to existing interface
   • Embedded terminal as iframe component
   • Auto-starts WebSocket server on application launch

🎨 Features

Terminal Interface

• Real-time Streaming: Live command output as it happens
• Command History: Navigate with ↑/↓ arrow keys
• Interrupt Support: Ctrl+C to stop running commands
• Auto-reconnect: Automatically reconnects on connection loss
• Status Indicators: Visual connection and execution status
• Responsive Design: Works on desktop and mobile

Security

• Command Sanitization: Uses shlex.split() for safe command parsing
• Process Isolation: Commands run in separate processes
• Error Handling: Robust error handling and logging

🚀 Usage

Starting the Application

python app.py

The terminal WebSocket server automatically starts on port 8765.

Accessing the Terminal

1. Open the Gradio interface (usually http://localhost:7860)
2. Click on the "💻 Terminal" tab
3. Start typing commands in the terminal interface

Keyboard Shortcuts

• Enter: Execute command
• ↑/↓: Navigate command history
• Ctrl+C: Interrupt running command
• Ctrl+L: Clear terminal screen
• Tab: Command completion (planned feature)

🔧 Configuration

WebSocket Server Settings

# In terminal_stream.py
WEBSOCKET_HOST = 'localhost'
WEBSOCKET_PORT = 8765

Terminal Appearance

Customize the terminal appearance by modifying the CSS in static/terminal.html:

/* Main terminal colors */
.terminal-container {
    background: linear-gradient(135deg, #0d1117 0%, #161b22 100%);
}

/* Command prompt */
.prompt {
    color: #58a6ff;
}

📡 WebSocket API

Client → Server Messages

Execute Command

{
    "type": "command",
    "command": "ls -la"
}

Interrupt Command

{
    "type": "interrupt"
}

Server → Client Messages

Command Output

{
    "type": "output",
    "data": "file1.txt\nfile2.txt",
    "stream": "stdout",
    "timestamp": "2024-01-01T12:00:00.000Z"
}

Command Completion

{
    "type": "command_complete",
    "exit_code": 0,
    "message": "Process exited with code 0",
    "timestamp": "2024-01-01T12:00:00.000Z"
}

🛠️ Development

Adding New Features

1. Server-side: Modify terminal_stream.py
2. Client-side: Update static/terminal.html
3. Integration: Adjust app.py if needed

Testing

# Test WebSocket server independently
python -c "from terminal_stream import run_websocket_server; run_websocket_server()"

# Test terminal interface
# Open static/terminal.html in browser

🔍 Troubleshooting

Common Issues

1. WebSocket Connection Failed

   • Check if port 8765 is available
   • Verify firewall settings
   • Check server logs for errors

2. Commands Not Executing

   • Verify WebSocket connection status
   • Check terminal logs for errors
   • Ensure proper command syntax

3. Terminal Not Loading

   • Check if static/terminal.html exists
   • Verify Gradio file serving configuration
   • Check browser console for errors

Debug Mode

Enable debug logging:

import logging
logging.getLogger('terminal_stream').setLevel(logging.DEBUG)

🚀 Advanced Usage

Custom Commands

Add custom command handlers in terminal_stream.py:

async def handle_custom_command(self, command):
    if command.startswith('custom:'):
        # Handle custom command
        await self.broadcast({
            'type': 'output',
            'data': 'Custom command executed',
            'stream': 'stdout'
        })
        return True
    return False

Integration with Workflow

Stream workflow logs to terminal:

# In workflow code
from terminal_stream import terminal_manager

async def log_to_terminal(message):
    await terminal_manager.broadcast({
        'type': 'output',
        'data': message,
        'stream': 'workflow'
    })

📚 Dependencies

• websockets: WebSocket server implementation
• asyncio: Async programming support
• subprocess: Command execution
• shlex: Safe command parsing

🎯 Future Enhancements

• Command auto-completion
• File upload/download via terminal
• Terminal themes and customization
• Multi-session support
• Terminal recording and playback
• Integration with workflow logging
• SSH/remote terminal support

📄 License

This terminal implementation is part of the Data Extractor project and follows the same license terms.