openhands 0.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

openhands-1.0.1.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: openhands
+Version: 1.0.1
+Summary: OpenHands CLI - Terminal User Interface for OpenHands AI Agent
+Author-email: OpenHands Team <contact@all-hands.dev>
+License: MIT
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: openhands-sdk
+Requires-Dist: openhands-tools
+Requires-Dist: prompt-toolkit>=3
+Requires-Dist: typer>=0.17.4
+Description-Content-Type: text/markdown
+
+# OpenHands V1 CLI
+
+A **lightweight, modern CLI** to interact with the OpenHands agent (powered by [agent-sdk](https://github.com/All-Hands-AI/agent-sdk)). 
+
+The [OpenHands V0 CLI (legacy)](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/cli) is being deprecated.
+
+---
+
+## Quickstart
+
+- Prerequisites: Python 3.12+, curl
+- Install uv (package manager):
+  ```bash
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  # Restart your shell so "uv" is on PATH, or follow the installer hint
+  ```
+
+### Run the CLI locally
+```bash
+make install
+
+# Start the CLI
+make run
+# or
+uv run openhands
+```
+
+### Build a standalone executable
+```bash
+# Build (installs PyInstaller if needed)
+./build.sh --install-pyinstaller
+
+# The binary will be in dist/
+./dist/openhands            # macOS/Linux
+# dist/openhands.exe        # Windows
+```

openhands-1.0.1.dist-info/RECORD

@@ -0,0 +1,31 @@
+openhands_cli/__init__.py,sha256=AqdjE-Up0uBSDyHvNjF0zWHNmA4ps-lsQWFpUWCWNEc,187
+openhands_cli/agent_chat.py,sha256=FZ1NC31xJPXqyFGUtS-JqDI_HVP5155xEz59AHp3DIw,6224
+openhands_cli/gui_launcher.py,sha256=EnZGcZMQzOHLwkmiHcYvt4WX2HfK0aT6L0t5ADWEfT0,7198
+openhands_cli/llm_utils.py,sha256=eRhAjysm77GvzArKb-75agqTlR_4zzxTrYD1eQbgqbg,1606
+openhands_cli/locations.py,sha256=zG5OnpJiX0kQ1fprEsOSi_cNqydEvxunPBCTpNrVaJ0,438
+openhands_cli/pt_style.py,sha256=UxCxV-t88n5JjjYYMD0jf5apg4B5-WkfQ4EX_Eusj1I,1266
+openhands_cli/runner.py,sha256=Oc6WEaJ0S-zfsPf30U4ozWrnqquvD2bpwX3AUnStpfs,6157
+openhands_cli/setup.py,sha256=HWb2_6N6qgXvhIzh7jLecS7HA5EEcp7b3VroDxGiGz0,3799
+openhands_cli/simple_main.py,sha256=7MmX8DgSvlFURzYsNqcE2vQ2MtdYTr-V88JlBmJlWvo,1697
+openhands_cli/argparsers/main_parser.py,sha256=ceYNnktzp4xMwrsvQZl0Py6uG3atUgBsPFfqM7Cig9k,1677
+openhands_cli/argparsers/serve_parser.py,sha256=WU2ClG5idbs966zJ5GfBXiaMH50e0ryGC1vD24JyJJ8,900
+openhands_cli/listeners/__init__.py,sha256=T251L6mUEQdfk1x7-AWITlDjgVDwfW8XkyKQYK6Z5O0,180
+openhands_cli/listeners/loading_listener.py,sha256=9sbuy64iAPqgvNojS-3RlWvepmaMC3R6FqlhTdYFKv8,1995
+openhands_cli/listeners/pause_listener.py,sha256=FtWxj8T5r2lYIoquueeCf-3kF3zFMJ2e25wqOeF7QtM,2622
+openhands_cli/tui/__init__.py,sha256=2KA7nugQxpIj4sEVDJavBbGHqcnySJFSvbPu1WRonPg,84
+openhands_cli/tui/status.py,sha256=QNbS9OEK6d_c0P1eEQKfytuUF1R7uPxFl5nN-yv3cdA,3628
+openhands_cli/tui/tui.py,sha256=JBahocaunF0LwJJLkcCmwSZN9xydb3SmH7fb8Jw8rFc,3545
+openhands_cli/tui/utils.py,sha256=t7vJHU_AcLzuLTPku88Aqd51jyWY8HwH5Y2n-Bpa-WU,536
+openhands_cli/tui/settings/mcp_screen.py,sha256=LMdcGD6DfwZQ4jnp-KM4gYiPXfNGHHPAqtEAXLKZtmA,8215
+openhands_cli/tui/settings/settings_screen.py,sha256=CRekM2ZgWJ_YgzC-Jg1SgX2YeviU69Hb1cuzi5pVdio,7087
+openhands_cli/tui/settings/store.py,sha256=tTMvYbdu9gs4GDNBoHFGFJnwm1PfjShgsVoMDjpQJ2Y,3485
+openhands_cli/user_actions/__init__.py,sha256=Tf-lQj7-6bNl5rohSdcAFApkKbQb-N9JcKZgHa1HF60,501
+openhands_cli/user_actions/agent_action.py,sha256=0v6kQPh8iE4CGjARA8vVD_TqSpS-aiscE3ucLC7jlZA,3283
+openhands_cli/user_actions/exit_session.py,sha256=3u1CqWeYAEYfZi9BFh_dUwvy9aXXuvFbsZUHNGjVzuY,624
+openhands_cli/user_actions/settings_action.py,sha256=QqWj37CAlrkV6FW9SEmmwsvKzdGyUYv4DlGjUweKsmg,5707
+openhands_cli/user_actions/types.py,sha256=zMHoJqxmtbxAIq6O3RC-XoGzgbZzWZvRFNMOGW4MViQ,407
+openhands_cli/user_actions/utils.py,sha256=qPTgP_1shnWgA7itrzTyfEGb_meXO-zq98JzFMUqCx4,6362
+openhands-1.0.1.dist-info/METADATA,sha256=GV83vM7e_TD4avAskm3v-ZbwzJ_1EZ-A9jEAOzEF94I,1370
+openhands-1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openhands-1.0.1.dist-info/entry_points.txt,sha256=CltyhTfx4lPndNPQXrZZDj5LmXrYXykVyIqoedPXsas,61
+openhands-1.0.1.dist-info/RECORD,,

{openhands-0.0.0.dist-info → openhands-1.0.1.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

openhands-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openhands = openhands_cli.simple_main:main

openhands_cli/__init__.py

@@ -0,0 +1,8 @@
+"""OpenHands package."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("openhands")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

openhands_cli/agent_chat.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Agent chat functionality for OpenHands CLI.
+Provides a conversation interface with an AI agent using OpenHands patterns.
+"""
+
+import sys
+from datetime import datetime
+
+from openhands.sdk import (
+    Message,
+    TextContent,
+)
+from openhands.sdk.conversation.state import AgentExecutionStatus
+from prompt_toolkit import print_formatted_text
+from prompt_toolkit.formatted_text import HTML
+
+from openhands_cli.runner import ConversationRunner
+from openhands_cli.setup import MissingAgentSpec, setup_conversation, start_fresh_conversation
+from openhands_cli.tui.settings.mcp_screen import MCPScreen
+from openhands_cli.tui.settings.settings_screen import SettingsScreen
+from openhands_cli.tui.status import display_status
+from openhands_cli.tui.tui import (
+    display_help,
+    display_welcome,
+)
+from openhands_cli.user_actions import UserConfirmation, exit_session_confirmation
+from openhands_cli.user_actions.utils import get_session_prompter
+
+
+def _restore_tty() -> None:
+    """
+    Ensure terminal modes are reset in case prompt_toolkit cleanup didn't run.
+    - Turn off application cursor keys (DECCKM): ESC[?1l
+    - Turn off bracketed paste: ESC[?2004l
+    """
+    try:
+        sys.stdout.write('\x1b[?1l\x1b[?2004l')
+        sys.stdout.flush()
+    except Exception:
+        pass
+
+
+def _print_exit_hint(conversation_id: str) -> None:
+    """Print a resume hint with the current conversation ID."""
+    print_formatted_text(
+        HTML(f'<grey>Conversation ID:</grey> <yellow>{conversation_id}</yellow>')
+    )
+    print_formatted_text(
+        HTML(
+            f'<grey>Hint:</grey> run <gold>openhands --resume {conversation_id}</gold> '
+            'to resume this conversation.'
+        )
+    )
+
+
+
+def run_cli_entry(resume_conversation_id: str | None = None) -> None:
+    """Run the agent chat session using the agent SDK.
+
+
+    Raises:
+        AgentSetupError: If agent setup fails
+        KeyboardInterrupt: If user interrupts the session
+        EOFError: If EOF is encountered
+    """
+
+    try:
+        conversation = start_fresh_conversation(resume_conversation_id)
+    except MissingAgentSpec:
+        print_formatted_text(HTML('\n<yellow>Setup is required to use OpenHands CLI.</yellow>'))
+        print_formatted_text(HTML('\n<yellow>Goodbye! 👋</yellow>'))
+        return
+
+
+    display_welcome(conversation.id, bool(resume_conversation_id))
+
+    # Track session start time for uptime calculation
+    session_start_time = datetime.now()
+
+    # Create conversation runner to handle state machine logic
+    runner = ConversationRunner(conversation)
+    session = get_session_prompter()
+
+    # Main chat loop
+    while True:
+        try:
+            # Get user input
+            user_input = session.prompt(
+                HTML('<gold>> </gold>'),
+                multiline=False,
+            )
+
+            if not user_input.strip():
+                continue
+
+            # Handle commands
+            command = user_input.strip().lower()
+
+            message = Message(
+                role='user',
+                content=[TextContent(text=user_input)],
+            )
+
+            if command == '/exit':
+                exit_confirmation = exit_session_confirmation()
+                if exit_confirmation == UserConfirmation.ACCEPT:
+                    print_formatted_text(HTML('\n<yellow>Goodbye! 👋</yellow>'))
+                    _print_exit_hint(conversation.id)
+                    break
+
+            elif command == '/settings':
+                settings_screen = SettingsScreen(conversation)
+                settings_screen.display_settings()
+                continue
+
+            elif command == '/mcp':
+                mcp_screen = MCPScreen()
+                mcp_screen.display_mcp_info(conversation.agent)
+                continue
+
+            elif command == '/clear':
+                display_welcome(conversation.id)
+                continue
+
+            elif command == '/new':
+                try:
+                    # Start a fresh conversation (no resume ID = new conversation)
+                    conversation = setup_conversation()
+                    runner = ConversationRunner(conversation)
+                    display_welcome(conversation.id, resume=False)
+                    print_formatted_text(
+                        HTML('<green>✓ Started fresh conversation</green>')
+                    )
+                    continue
+                except Exception as e:
+                    print_formatted_text(
+                        HTML(f'<red>Error starting fresh conversation: {e}</red>')
+                    )
+                    continue
+
+            elif command == '/help':
+                display_help()
+                continue
+
+            elif command == '/status':
+                display_status(conversation, session_start_time=session_start_time)
+                continue
+
+            elif command == '/confirm':
+                runner.toggle_confirmation_mode()
+                new_status = (
+                    'enabled' if runner.is_confirmation_mode_active else 'disabled'
+                )
+                print_formatted_text(
+                    HTML(f'<yellow>Confirmation mode {new_status}</yellow>')
+                )
+                continue
+
+            elif command == '/resume':
+                if not (
+                    conversation.state.agent_status == AgentExecutionStatus.PAUSED
+                    or conversation.state.agent_status
+                    == AgentExecutionStatus.WAITING_FOR_CONFIRMATION
+                ):
+                    print_formatted_text(
+                        HTML('<red>No paused conversation to resume...</red>')
+                    )
+                    continue
+
+                # Resume without new message
+                message = None
+
+            runner.process_message(message)
+
+            print()  # Add spacing
+
+        except KeyboardInterrupt:
+            exit_confirmation = exit_session_confirmation()
+            if exit_confirmation == UserConfirmation.ACCEPT:
+                print_formatted_text(HTML('\n<yellow>Goodbye! 👋</yellow>'))
+                _print_exit_hint(conversation.id)
+                break
+
+    # Clean up terminal state
+    _restore_tty()

openhands_cli/argparsers/main_parser.py

@@ -0,0 +1,56 @@
+"""Main argument parser for OpenHands CLI."""
+
+import argparse
+
+
+def create_main_parser() -> argparse.ArgumentParser:
+    """Create the main argument parser with CLI as default and serve as subcommand.
+    
+    Returns:
+        The configured argument parser
+    """
+    parser = argparse.ArgumentParser(
+        description='OpenHands CLI - Terminal User Interface for OpenHands AI Agent',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+By default, OpenHands runs in CLI mode (terminal interface).
+Use 'serve' subcommand to launch the GUI server instead.
+
+Examples:
+  openhands                           # Start CLI mode
+  openhands --resume conversation-id  # Resume a conversation in CLI mode
+  openhands serve                     # Launch GUI server
+  openhands serve --gpu               # Launch GUI server with GPU support
+"""
+    )
+    
+    # CLI arguments at top level (default mode)
+    parser.add_argument(
+        '--resume',
+        type=str,
+        help='Conversation ID to resume'
+    )
+    
+    # Only serve as subcommand
+    subparsers = parser.add_subparsers(
+        dest='command',
+        help='Additional commands'
+    )
+    
+    # Add serve subcommand
+    serve_parser = subparsers.add_parser(
+        'serve',
+        help='Launch the OpenHands GUI server using Docker (web interface)'
+    )
+    serve_parser.add_argument(
+        '--mount-cwd',
+        action='store_true',
+        help='Mount the current working directory in the Docker container'
+    )
+    serve_parser.add_argument(
+        '--gpu',
+        action='store_true',
+        help='Enable GPU support in the Docker container'
+    )
+    
+    return parser

openhands_cli/argparsers/serve_parser.py

@@ -0,0 +1,31 @@
+"""Argument parser for serve subcommand."""
+
+import argparse
+
+
+def add_serve_parser(subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    """Add serve subcommand parser.
+    
+    Args:
+        subparsers: The subparsers object to add the serve parser to
+        
+    Returns:
+        The serve argument parser
+    """
+    serve_parser = subparsers.add_parser(
+        'serve',
+        help='Launch the OpenHands GUI server using Docker (web interface)'
+    )
+    serve_parser.add_argument(
+        '--mount-cwd',
+        help='Mount the current working directory into the GUI server container',
+        action='store_true',
+        default=False,
+    )
+    serve_parser.add_argument(
+        '--gpu',
+        help='Enable GPU support by mounting all GPUs into the Docker container via nvidia-docker',
+        action='store_true',
+        default=False,
+    )
+    return serve_parser

openhands_cli/gui_launcher.py

@@ -0,0 +1,220 @@
+"""GUI launcher for OpenHands CLI."""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from prompt_toolkit import print_formatted_text
+from prompt_toolkit.formatted_text import HTML
+from openhands_cli.locations import PERSISTENCE_DIR
+
+
+def _format_docker_command_for_logging(cmd: list[str]) -> str:
+    """Format a Docker command for logging with grey color.
+
+    Args:
+        cmd (list[str]): The Docker command as a list of strings
+
+    Returns:
+        str: The formatted command string in grey HTML color
+    """
+    cmd_str = ' '.join(cmd)
+    return f'<grey>Running Docker command: {cmd_str}</grey>'
+
+
+def check_docker_requirements() -> bool:
+    """Check if Docker is installed and running.
+
+    Returns:
+        bool: True if Docker is available and running, False otherwise.
+    """
+    # Check if Docker is installed
+    if not shutil.which('docker'):
+        print_formatted_text(
+            HTML('<ansired>❌ Docker is not installed or not in PATH.</ansired>')
+        )
+        print_formatted_text(
+            HTML(
+                '<grey>Please install Docker first: https://docs.docker.com/get-docker/</grey>'
+            )
+        )
+        return False
+
+    # Check if Docker daemon is running
+    try:
+        result = subprocess.run(
+            ['docker', 'info'], capture_output=True, text=True, timeout=10
+        )
+        if result.returncode != 0:
+            print_formatted_text(
+                HTML('<ansired>❌ Docker daemon is not running.</ansired>')
+            )
+            print_formatted_text(
+                HTML('<grey>Please start Docker and try again.</grey>')
+            )
+            return False
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError) as e:
+        print_formatted_text(
+            HTML('<ansired>❌ Failed to check Docker status.</ansired>')
+        )
+        print_formatted_text(HTML(f'<grey>Error: {e}</grey>'))
+        return False
+
+    return True
+
+
+def ensure_config_dir_exists() -> Path:
+    """Ensure the OpenHands configuration directory exists and return its path."""
+    path = Path(PERSISTENCE_DIR)
+    path.mkdir(exist_ok=True, parents=True)
+    return path
+
+
+def get_openhands_version() -> str:
+    """Get the OpenHands version for Docker images.
+
+    Returns:
+        str: The version string to use for Docker images
+    """
+    # For now, use 'latest' as the default version
+    # In the future, this could be read from a version file or environment variable
+    return os.environ.get('OPENHANDS_VERSION', 'latest')
+
+
+def launch_gui_server(mount_cwd: bool = False, gpu: bool = False) -> None:
+    """Launch the OpenHands GUI server using Docker.
+
+    Args:
+        mount_cwd: If True, mount the current working directory into the container.
+        gpu: If True, enable GPU support by mounting all GPUs into the container via nvidia-docker.
+    """
+    print_formatted_text(
+        HTML('<ansiblue>🚀 Launching OpenHands GUI server...</ansiblue>')
+    )
+    print_formatted_text('')
+
+    # Check Docker requirements
+    if not check_docker_requirements():
+        sys.exit(1)
+
+    # Ensure config directory exists
+    config_dir = ensure_config_dir_exists()
+
+    # Get the current version for the Docker image
+    version = get_openhands_version()
+    runtime_image = f'docker.all-hands.dev/all-hands-ai/runtime:{version}-nikolaik'
+    app_image = f'docker.all-hands.dev/all-hands-ai/openhands:{version}'
+
+    print_formatted_text(HTML('<grey>Pulling required Docker images...</grey>'))
+
+    # Pull the runtime image first
+    pull_cmd = ['docker', 'pull', runtime_image]
+    print_formatted_text(HTML(_format_docker_command_for_logging(pull_cmd)))
+    try:
+        subprocess.run(pull_cmd, check=True)
+    except subprocess.CalledProcessError:
+        print_formatted_text(
+            HTML('<ansired>❌ Failed to pull runtime image.</ansired>')
+        )
+        sys.exit(1)
+
+    print_formatted_text('')
+    print_formatted_text(
+        HTML('<ansigreen>✅ Starting OpenHands GUI server...</ansigreen>')
+    )
+    print_formatted_text(
+        HTML('<grey>The server will be available at: http://localhost:3000</grey>')
+    )
+    print_formatted_text(HTML('<grey>Press Ctrl+C to stop the server.</grey>'))
+    print_formatted_text('')
+
+    # Build the Docker command
+    docker_cmd = [
+        'docker',
+        'run',
+        '-it',
+        '--rm',
+        '--pull=always',
+        '-e',
+        f'SANDBOX_RUNTIME_CONTAINER_IMAGE={runtime_image}',
+        '-e',
+        'LOG_ALL_EVENTS=true',
+        '-v',
+        '/var/run/docker.sock:/var/run/docker.sock',
+        '-v',
+        f'{config_dir}:/.openhands',
+    ]
+
+    # Add GPU support if requested
+    if gpu:
+        print_formatted_text(
+            HTML('<ansigreen>🖥️ Enabling GPU support via nvidia-docker...</ansigreen>')
+        )
+        # Add the --gpus all flag to enable all GPUs
+        docker_cmd.insert(2, '--gpus')
+        docker_cmd.insert(3, 'all')
+        # Add environment variable to pass GPU support to sandbox containers
+        docker_cmd.extend(
+            [
+                '-e',
+                'SANDBOX_ENABLE_GPU=true',
+            ]
+        )
+
+    # Add current working directory mount if requested
+    if mount_cwd:
+        cwd = Path.cwd()
+        # Following the documentation at https://docs.all-hands.dev/usage/runtimes/docker#connecting-to-your-filesystem
+        docker_cmd.extend(
+            [
+                '-e',
+                f'SANDBOX_VOLUMES={cwd}:/workspace:rw',
+            ]
+        )
+
+        # Set user ID for Unix-like systems only
+        if os.name != 'nt':  # Not Windows
+            try:
+                user_id = subprocess.check_output(['id', '-u'], text=True).strip()
+                docker_cmd.extend(['-e', f'SANDBOX_USER_ID={user_id}'])
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                # If 'id' command fails or doesn't exist, skip setting user ID
+                pass
+        # Print the folder that will be mounted to inform the user
+        print_formatted_text(
+            HTML(
+                f'<ansigreen>📂 Mounting current directory:</ansigreen> <ansiyellow>{cwd}</ansiyellow> <ansigreen>to</ansigreen> <ansiyellow>/workspace</ansiyellow>'
+            )
+        )
+
+    docker_cmd.extend(
+        [
+            '-p',
+            '3000:3000',
+            '--add-host',
+            'host.docker.internal:host-gateway',
+            '--name',
+            'openhands-app',
+            app_image,
+        ]
+    )
+
+    try:
+        # Log and run the Docker command
+        print_formatted_text(HTML(_format_docker_command_for_logging(docker_cmd)))
+        subprocess.run(docker_cmd, check=True)
+    except subprocess.CalledProcessError as e:
+        print_formatted_text('')
+        print_formatted_text(
+            HTML('<ansired>❌ Failed to start OpenHands GUI server.</ansired>')
+        )
+        print_formatted_text(HTML(f'<grey>Error: {e}</grey>'))
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print_formatted_text('')
+        print_formatted_text(
+            HTML('<ansigreen>✓ OpenHands GUI server stopped successfully.</ansigreen>')
+        )
+        sys.exit(0)

openhands_cli/listeners/__init__.py

@@ -0,0 +1,4 @@
+from openhands_cli.listeners.loading_listener import LoadingContext
+from openhands_cli.listeners.pause_listener import PauseListener
+
+__all__ = ['PauseListener', 'LoadingContext']

openhands_cli/listeners/loading_listener.py

@@ -0,0 +1,63 @@
+"""
+Loading animation utilities for OpenHands CLI.
+Provides animated loading screens during agent initialization.
+"""
+
+import sys
+import threading
+import time
+
+
+def display_initialization_animation(text: str, is_loaded: threading.Event) -> None:
+    """Display a spinning animation while agent is being initialized.
+
+    Args:
+        text: The text to display alongside the animation
+        is_loaded: Threading event that signals when loading is complete
+    """
+    ANIMATION_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+    i = 0
+    while not is_loaded.is_set():
+        sys.stdout.write('\n')
+        sys.stdout.write(
+            f'\033[s\033[J\033[38;2;255;215;0m[{ANIMATION_FRAMES[i % len(ANIMATION_FRAMES)]}] {text}\033[0m\033[u\033[1A'
+        )
+        sys.stdout.flush()
+        time.sleep(0.1)
+        i += 1
+
+    sys.stdout.write('\r' + ' ' * (len(text) + 10) + '\r')
+    sys.stdout.flush()
+
+
+class LoadingContext:
+    """Context manager for displaying loading animations in a separate thread."""
+
+    def __init__(self, text: str):
+        """Initialize the loading context.
+
+        Args:
+            text: The text to display during loading
+        """
+        self.text = text
+        self.is_loaded = threading.Event()
+        self.loading_thread: threading.Thread | None = None
+
+    def __enter__(self) -> 'LoadingContext':
+        """Start the loading animation in a separate thread."""
+        self.loading_thread = threading.Thread(
+            target=display_initialization_animation,
+            args=(self.text, self.is_loaded),
+            daemon=True,
+        )
+        self.loading_thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Stop the loading animation and clean up the thread."""
+        self.is_loaded.set()
+        if self.loading_thread:
+            self.loading_thread.join(
+                timeout=1.0
+            )  # Wait up to 1 second for thread to finish