uipath-robot 0.0.3__py3-none-any.whl

uipath/robot/__init__.py

@@ -0,0 +1,472 @@
+"""UiPath Robot Package Initialization."""
+
+import asyncio
+import json
+import os
+import subprocess
+import uuid
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+
+from uipath.robot.infra import get_logger, init_logger
+from uipath.robot.models import (
+    Command,
+    HeartbeatData,
+    HeartbeatResponse,
+    JobError,
+    JobState,
+    SessionState,
+)
+from uipath.robot.services import OrchestratorService
+
+
+class Robot:
+    """Main Robot class to manage interactions with UiPath Orchestrator."""
+
+    def __init__(self, verbose: bool = False):
+        """Initialize the Robot with necessary services.
+
+        Args:
+            verbose: Enable verbose logging
+        """
+        self.logger = get_logger(verbose)
+        self.orchestrator = OrchestratorService()
+        self.heartbeat_interval = 5  # seconds
+        self.license_key: str | None = None
+
+        base_dir = Path.cwd() / ".uipath"
+        self.packages_dir = base_dir / "packages"
+        self.processes_dir = base_dir / "processes"
+
+        self.packages_dir.mkdir(parents=True, exist_ok=True)
+        self.processes_dir.mkdir(parents=True, exist_ok=True)
+
+    async def initialize(self) -> bool:
+        """Initialize the service by getting connection data and license key.
+
+        Returns:
+            True if initialization successful, False otherwise
+        """
+        self.logger.info("Initializing robot service")
+
+        self.license_key = await self.orchestrator.get_shared_connection_data()
+
+        if not self.license_key:
+            self.logger.error("Failed to get connection data")
+            return False
+
+        self.logger.success(f"Connected (key: {self.license_key[:10]}...)")
+        return True
+
+    def get_package_path(self, package_id: str, package_version: str) -> Path:
+        """Get the path for a package zip file."""
+        return self.packages_dir / f"{package_id}_{package_version}.zip"
+
+    def get_process_path(self, package_id: str, package_version: str) -> Path:
+        """Get the path for an extracted process."""
+        return self.processes_dir / f"{package_id}_{package_version}"
+
+    async def download_and_setup_package(
+        self, package_id: str, package_version: str, feed_id: str | None = None
+    ) -> Path | None:
+        """Download package if needed, extract it, and setup environment.
+
+        Args:
+            package_id: The package identifier
+            package_version: The package version
+            feed_id: Optional feed identifier
+
+        Returns:
+            Path to the extracted process directory, or None if failed
+        """
+        package_path = self.get_package_path(package_id, package_version)
+        process_path = self.get_process_path(package_id, package_version)
+
+        # Check if already downloaded and extracted
+        if process_path.exists():
+            self.logger.package_status(package_id, package_version, "cached")
+            return process_path
+
+        # Download package if not exists
+        if not package_path.exists():
+            self.logger.package_status(package_id, package_version, "downloading")
+            success = await self.orchestrator.download_package(
+                package_id,
+                package_version,
+                package_path,
+                feed_id,
+            )
+            if not success:
+                self.logger.error("Failed to download package")
+                return None
+            self.logger.debug(f"Downloaded to {package_path}", indent=1)
+
+        # Extract package - extract only the 'content' folder
+        self.logger.package_status(package_id, package_version, "extracting")
+        try:
+            process_path.mkdir(parents=True, exist_ok=True)
+
+            with zipfile.ZipFile(package_path, "r") as zip_ref:
+                # Get all files in the 'content' folder
+                content_files = [
+                    f for f in zip_ref.namelist() if f.startswith("content/")
+                ]
+
+                if not content_files:
+                    self.logger.error("No 'content' folder found in package")
+                    return None
+
+                # Extract each file, removing the 'content/' prefix
+                for file in content_files:
+                    if file == "content/":
+                        continue
+
+                    # Remove 'content/' prefix from the path
+                    target_path = file[len("content/") :]
+
+                    # Extract to process_path with adjusted path
+                    if target_path:
+                        source = zip_ref.open(file)
+                        target = process_path / target_path
+                        target.parent.mkdir(parents=True, exist_ok=True)
+
+                        with source, open(target, "wb") as target_file:
+                            target_file.write(source.read())
+
+            self.logger.package_status(package_id, package_version, "extracted")
+        except Exception as e:
+            self.logger.error(f"Failed to extract: {e}")
+            return None
+
+        # Setup virtual environment only if pyproject.toml exists
+        pyproject_path = process_path / "pyproject.toml"
+        if pyproject_path.exists():
+            self.logger.environment_setup("creating")
+            venv_path = process_path / ".venv"
+            try:
+                subprocess.run(
+                    ["uv", "venv", str(venv_path)],
+                    cwd=process_path,
+                    check=True,
+                    capture_output=True,
+                )
+
+                # Copy existing environment and add custom vars
+                env_with_temp = os.environ.copy()
+                env_with_temp["VIRTUAL_ENV"] = str(venv_path)
+                env_with_temp["TMPDIR"] = str(process_path / "temp")  # Linux/Mac
+                env_with_temp["TEMP"] = str(process_path / "temp")  # Windows
+                env_with_temp["TMP"] = str(process_path / "temp")  # Windows
+
+                (process_path / "temp").mkdir(exist_ok=True)
+
+                self.logger.environment_setup("syncing")
+                subprocess.run(
+                    ["uv", "sync"],
+                    cwd=process_path,
+                    env=env_with_temp,
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                )
+                self.logger.environment_setup("ready")
+
+            except subprocess.CalledProcessError as e:
+                self.logger.error(f"Environment setup failed: {e}")
+                self.logger.debug(f"stdout: {e.stdout}", indent=1)
+                self.logger.debug(f"stderr: {e.stderr}", indent=1)
+                return None
+            except Exception as e:
+                self.logger.error(f"Unexpected error: {e}")
+                return None
+        else:
+            self.logger.environment_setup("skipped")
+
+        return process_path
+
+    async def execute_process(self, process_path: Path, command: Command) -> None:
+        """Execute a process using uipath run.
+
+        Args:
+            process_path: Path to the process directory
+            command: The command data containing job details
+        """
+        assert self.license_key is not None
+        self.logger.process_execution("starting")
+        try:
+            # Create __uipath directory and uipath.json
+            uipath_dir = process_path / "__uipath"
+            uipath_dir.mkdir(exist_ok=True)
+
+            uipath_config = {
+                "runtime": self._parse_json_or_empty(command.data.internal_arguments),
+                "fpsProperties": self._parse_json_or_empty(command.data.fps_properties),
+                "fpsContext": self._parse_json_or_empty(command.data.fps_context),
+            }
+
+            uipath_json_path = uipath_dir / "uipath.json"
+            with open(uipath_json_path, "w") as f:
+                json.dump(uipath_config, f, indent=2)
+
+            # Prepare environment variables
+            env = os.environ.copy()
+            env["UIPATH_JOB_KEY"] = command.data.job_key
+            env["UIPATH_FOLDER_KEY"] = command.data.folder_key
+            env["UIPATH_FOLDER_PATH"] = command.data.fully_qualified_folder_name
+            env["UIPATH_PROCESS_UUID"] = command.data.process_key
+            env["VIRTUAL_ENV"] = str(process_path / ".venv")
+
+            trace_id = command.data.trace_id or str(uuid.uuid4())
+            env["UIPATH_TRACE_ID"] = trace_id
+            if command.data.parent_span_id:
+                env["UIPATH_PARENT_SPAN_ID"] = command.data.parent_span_id
+            if command.data.root_span_id:
+                env["UIPATH_ROOT_SPAN_ID"] = command.data.root_span_id
+
+            # Ensure required env vars are present
+            required_vars = [
+                "UIPATH_ACCESS_TOKEN",
+                "UIPATH_URL",
+                "UIPATH_TENANT_ID",
+                "UIPATH_ORGANIZATION_ID",
+            ]
+
+            missing_vars = [var for var in required_vars if not env.get(var)]
+            if missing_vars:
+                self.logger.error(f"Missing env vars: {', '.join(missing_vars)}")
+                return
+
+            await self.orchestrator.submit_job_state(
+                heartbeats=[
+                    HeartbeatData(
+                        robot_key=command.robot_key,
+                        robot_state=SessionState.BUSY,
+                        process_key=command.data.process_key,
+                        job_key=command.data.job_key,
+                        job_state=JobState.RUNNING,
+                        trace_id=trace_id,
+                    )
+                ],
+                license_key=self.license_key,
+            )
+
+            self.logger.process_execution("running")
+
+            cmd = ["uv", "run", "uipath", "run"]
+            if command.data.entry_point_path:
+                cmd.extend([command.data.entry_point_path])
+            if command.data.input_arguments:
+                cmd.extend([command.data.input_arguments])
+
+            result = subprocess.run(
+                cmd,
+                cwd=process_path,
+                env=env,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+
+            output_file = process_path / "__uipath" / "output.json"
+            if output_file.exists():
+                output_data: dict[str, Any] = {}
+                with open(output_file, "r") as f:
+                    output_data = json.load(f)
+
+                status = output_data.get("status", "successful")
+                output_args = json.dumps(output_data.get("output", {}))
+
+                if status == "successful":
+                    job_state = JobState.SUCCESSFUL
+                    error = None
+                    self.logger.process_execution("success", result.stdout.strip())
+                else:
+                    job_state = JobState.FAULTED
+                    error_data: dict[str, Any] = output_data.get("error", {})
+                    error = JobError(
+                        code=error_data.get("code", "PYTHON.PROCESS_FAILED"),
+                        title=error_data.get("title", "Process Failed"),
+                        category=error_data.get("category", "USER"),
+                        detail=error_data.get(
+                            "detail", "Process completed with failure status"
+                        ),
+                    )
+                    self.logger.process_execution("failed", error_data.get("detail"))
+            else:
+                # No output file, assume success
+                job_state = JobState.SUCCESSFUL
+                output_args = "{}"
+                error = None
+                self.logger.process_execution("success", result.stdout.strip())
+
+            await self.orchestrator.submit_job_state(
+                heartbeats=[
+                    HeartbeatData(
+                        robot_key=command.robot_key,
+                        robot_state=SessionState.AVAILABLE,
+                        process_key=command.data.process_key,
+                        job_key=command.data.job_key,
+                        job_state=job_state,
+                        output_arguments=output_args,
+                        error=error,
+                    )
+                ],
+                license_key=self.license_key,
+            )
+
+        except subprocess.CalledProcessError as e:
+            self.logger.process_execution("failed", e.stderr)
+            await self.orchestrator.submit_job_state(
+                heartbeats=[
+                    HeartbeatData(
+                        robot_key=command.robot_key,
+                        robot_state=SessionState.AVAILABLE,
+                        process_key=command.data.process_key,
+                        job_key=command.data.job_key,
+                        job_state=JobState.FAULTED,
+                        error=JobError(
+                            code="PYTHON.AGENT_EXECUTION_FAILED",
+                            title="Agent Execution Failed",
+                            category="SYSTEM",
+                            detail=e.stderr,
+                        ),
+                    )
+                ],
+                license_key=self.license_key,
+            )
+        except Exception as e:
+            self.logger.process_execution("failed", str(e))
+            await self.orchestrator.submit_job_state(
+                heartbeats=[
+                    HeartbeatData(
+                        robot_key=command.robot_key,
+                        robot_state=SessionState.AVAILABLE,
+                        process_key=command.data.process_key,
+                        job_key=command.data.job_key,
+                        job_state=JobState.FAULTED,
+                        error=JobError(
+                            code="PYTHON.AGENT_EXECUTION_FAILED",
+                            title="Agent Execution Failed",
+                            category="SYSTEM",
+                            detail=str(e),
+                        ),
+                    )
+                ],
+                license_key=self.license_key,
+            )
+
+    async def process_commands(self, response: HeartbeatResponse) -> None:
+        """Process commands from heartbeat response.
+
+        Args:
+            response: The heartbeat response containing commands
+        """
+        for command in response.commands:
+            if command.data.type == "StartProcess":
+                self.logger.job_start(
+                    command.data.job_key,
+                    command.data.package_id,
+                    command.data.package_version,
+                )
+
+                # Download and setup package
+                process_path = await self.download_and_setup_package(
+                    command.data.package_id,
+                    command.data.package_version,
+                    command.data.feed_id,
+                )
+
+                if process_path:
+                    # Execute the process asynchronously without blocking
+                    asyncio.create_task(
+                        self.execute_process(
+                            process_path,
+                            command,
+                        )
+                    )
+                else:
+                    self.logger.error("Failed to setup package")
+
+    def _parse_json_or_empty(self, raw_json: str | None) -> dict[str, Any]:
+        """Parse JSON string or return empty dict.
+
+        Args:
+            raw_json: JSON string to parse
+
+        Returns:
+            Parsed JSON as dict or empty dict if parsing fails
+        """
+        if not raw_json or not raw_json.strip():
+            return {}
+
+        try:
+            return json.loads(raw_json)
+        except (json.JSONDecodeError, Exception):
+            return {}
+
+    async def run(self) -> None:
+        """Main loop: Initialize once, then send heartbeats every 10 seconds."""
+        self.logger.section("UiPath Robot Service")
+
+        if not await self.initialize():
+            self.logger.error("Initialization failed")
+            return
+
+        assert self.license_key is not None
+
+        await self.orchestrator.start_service(self.license_key)
+        self.logger.success("Service started")
+
+        self.logger.info(f"Listening for jobs (heartbeat: {self.heartbeat_interval}s)")
+
+        try:
+            while True:
+                response = await self.orchestrator.heartbeat(self.license_key)
+                self.logger.heartbeat()
+
+                if response and response.commands:
+                    await self.process_commands(response)
+
+                await asyncio.sleep(self.heartbeat_interval)
+        finally:
+            self.logger.info("Stopping service...")
+            await self.orchestrator.stop_service(self.license_key)
+
+
+async def start_robot(verbose: bool = False) -> None:
+    """Run the robot service.
+
+    Args:
+        verbose: Enable verbose logging
+    """
+    robot = Robot(verbose=verbose)
+    await robot.run()
+
+
+def main() -> None:
+    """Main entry point for running the robot service."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="UiPath Robot Service")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging",
+    )
+    args = parser.parse_args()
+
+    load_dotenv()
+    init_logger(verbose=args.verbose)
+
+    try:
+        asyncio.run(start_robot(verbose=args.verbose))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

uipath/robot/infra/__init__.py

@@ -0,0 +1,5 @@
+"""UiPath Robot Infrastructure Package."""
+
+from uipath.robot.infra.logger import get_logger, init_logger
+
+__all__ = ["get_logger", "init_logger"]

uipath/robot/infra/logger.py

@@ -0,0 +1,181 @@
+"""CLI Logger for UiPath Robot."""
+
+from datetime import datetime
+from enum import Enum
+
+
+class LogLevel(Enum):
+    """Log levels with visual indicators."""
+
+    INFO = ("●", "\033[36m")  # Cyan dot
+    SUCCESS = ("✓", "\033[32m")  # Green checkmark
+    WARNING = ("⚠", "\033[33m")  # Yellow warning
+    ERROR = ("✗", "\033[31m")  # Red X
+    DEBUG = ("·", "\033[90m")  # Gray dot
+    SYSTEM = ("→", "\033[35m")  # Magenta arrow
+
+
+class CLILogger:
+    """Clean CLI logger with structured output."""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+
+    def __init__(self, verbose: bool = False):
+        """Initialize logger.
+
+        Args:
+            verbose: If True, show debug messages
+        """
+        self.verbose: bool = verbose
+        self._last_section: str | None = None
+
+    def _format_time(self) -> str:
+        """Get formatted timestamp."""
+        return datetime.now().strftime("%H:%M:%S")
+
+    def _log(self, level: LogLevel, message: str, indent: int = 0):
+        """Internal log method.
+
+        Args:
+            level: The log level
+            message: The message to log
+            indent: Indentation level (0-2)
+        """
+        if level == LogLevel.DEBUG and not self.verbose:
+            return
+
+        symbol, color = level.value
+        indent_str = "  " * indent
+        time_str = f"{self.DIM}{self._format_time()}{self.RESET}"
+
+        print(f"{time_str} {color}{symbol}{self.RESET} {indent_str}{message}")
+
+    def section(self, title: str):
+        """Print a section header.
+
+        Args:
+            title: Section title
+        """
+        if self._last_section:
+            print()  # Add spacing between sections
+        print(f"\n{self.BOLD}{title}{self.RESET}")
+        print("─" * len(title))
+        self._last_section = title
+
+    def info(self, message: str, indent: int = 0):
+        """Log info message."""
+        self._log(LogLevel.INFO, message, indent)
+
+    def success(self, message: str, indent: int = 0):
+        """Log success message."""
+        self._log(LogLevel.SUCCESS, message, indent)
+
+    def warning(self, message: str, indent: int = 0):
+        """Log warning message."""
+        self._log(LogLevel.WARNING, message, indent)
+
+    def error(self, message: str, indent: int = 0):
+        """Log error message."""
+        self._log(LogLevel.ERROR, message, indent)
+
+    def debug(self, message: str, indent: int = 0):
+        """Log debug message (only if verbose)."""
+        self._log(LogLevel.DEBUG, message, indent)
+
+    def system(self, message: str, indent: int = 0):
+        """Log system/internal message."""
+        self._log(LogLevel.SYSTEM, message, indent)
+
+    def job_start(self, job_key: str, package: str, version: str):
+        """Log job start with formatted output."""
+        self.section(f"Job {job_key[:8]}...")
+        self.info(f"Package: {self.BOLD}{package}{self.RESET} v{version}")
+
+    def heartbeat(self, count: int | None = None):
+        """Log heartbeat in a minimal way."""
+        if self.verbose:
+            msg = f"Heartbeat {count}" if count else "Heartbeat"
+            self.debug(msg)
+
+    def package_status(self, package: str, version: str, status: str):
+        """Log package download/extraction status.
+
+        Args:
+            package: Package ID
+            version: Package version
+            status: Status message (downloading/extracting/cached)
+        """
+        if status == "cached":
+            self.debug(f"Using cached {package}:{version}")
+        elif status == "downloading":
+            self.info(f"Downloading {package}:{version}")
+        elif status == "extracting":
+            self.info("Extracting package", indent=1)
+        elif status == "extracted":
+            self.success("Package ready", indent=1)
+
+    def environment_setup(self, status: str):
+        """Log environment setup status.
+
+        Args:
+            status: Status (creating/syncing/ready/skipped)
+        """
+        if status == "creating":
+            self.info("Creating virtual environment", indent=1)
+        elif status == "syncing":
+            self.info("Installing dependencies", indent=1)
+        elif status == "ready":
+            self.success("Environment ready", indent=1)
+        elif status == "skipped":
+            self.debug("No pyproject.toml, skipping venv", indent=1)
+
+    def process_execution(self, status: str, detail: str | None = None):
+        """Log process execution status.
+
+        Args:
+            status: Status (starting/running/success/failed)
+            detail: Optional detail message
+        """
+        if status == "starting":
+            self.info("Starting process execution")
+        elif status == "running":
+            self.system("Process running", indent=1)
+        elif status == "success":
+            self.success("Process completed successfully")
+            if detail:
+                self.debug(f"Output: {detail}", indent=1)
+        elif status == "failed":
+            self.error("Process execution failed")
+            if detail:
+                self.error(detail, indent=1)
+
+
+# Global logger instance
+_logger: CLILogger | None = None
+
+
+def get_logger(verbose: bool = False) -> CLILogger:
+    """Get or create the global logger instance.
+
+    Args:
+        verbose: Enable verbose logging
+
+    Returns:
+        The CLI logger instance
+    """
+    global _logger
+    if _logger is None:
+        _logger = CLILogger(verbose=verbose)
+    return _logger
+
+
+def init_logger(verbose: bool = False):
+    """Initialize the global logger.
+
+    Args:
+        verbose: Enable verbose logging
+    """
+    global _logger
+    _logger = CLILogger(verbose=verbose)

uipath/robot/models/__init__.py

@@ -0,0 +1,21 @@
+"""Models for the robot heartbeat functionality."""
+
+from .heartbeat import (
+    Command,
+    CommandData,
+    HeartbeatData,
+    HeartbeatResponse,
+    JobError,
+    JobState,
+    SessionState,
+)
+
+__all__ = [
+    "Command",
+    "CommandData",
+    "HeartbeatData",
+    "JobError",
+    "JobState",
+    "SessionState",
+    "HeartbeatResponse",
+]

uipath/robot/models/heartbeat.py

@@ -0,0 +1,166 @@
+"""Models for the heartbeat response from Orchestrator."""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class JobState(str, Enum):
+    """Job state enumeration."""
+
+    PENDING = "Pending"
+    RUNNING = "Running"
+    SUCCESSFUL = "Successful"
+    FAULTED = "Faulted"
+    STOPPING = "Stopping"
+    TERMINATING = "Terminating"
+    STOPPED = "Stopped"
+    SUSPENDED = "Suspended"
+    RESUMED = "Resumed"
+
+
+class SessionState(str, Enum):
+    """Robot session state enumeration."""
+
+    AVAILABLE = "Available"
+    BUSY = "Busy"
+    DISCONNECTED = "Disconnected"
+    UNRESPONSIVE = "Unresponsive"
+
+
+class ExecutionSettings(BaseModel):
+    """Execution settings for the robot."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class AuthSettings(BaseModel):
+    """Authentication settings for the robot."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class CommandData(BaseModel):
+    """Data payload for a robot command."""
+
+    model_config = ConfigDict(
+        extra="allow", validate_by_name=True, validate_by_alias=True
+    )
+
+    process_settings: Any = Field(None, alias="processSettings")
+    video_recording_settings: Any = Field(None, alias="videoRecordingSettings")
+    package_id: str = Field(alias="packageId")
+    package_version: str = Field(alias="packageVersion")
+    target_framework: str = Field(alias="targetFramework")
+    username: str | None = None
+    password: str | None = None
+    credential_connection_data: Any = Field(None, alias="credentialConnectionData")
+    credential_type: int = Field(alias="credentialType")
+    process_name: str = Field(alias="processName")
+    persistence_id: str | None = Field(None, alias="persistenceId")
+    resume_version: str | None = Field(None, alias="resumeVersion")
+    resume_source: str | None = Field(None, alias="resumeSource")
+    suspend_blob_type: str | None = Field(None, alias="suspendBlobType")
+    input_arguments: str = Field(alias="inputArguments")
+    input_file: str | None = Field(None, alias="inputFile")
+    default_input_arguments: str | None = Field(None, alias="defaultInputArguments")
+    environment_variables: str | None = Field(None, alias="environmentVariables")
+    internal_arguments: str = Field(alias="internalArguments")
+    entry_point_path: str = Field(alias="entryPointPath")
+    feed_id: str | None = Field(alias="feedId")
+    feed_url: str = Field(alias="feedUrl")
+    requires_user_interaction: bool = Field(alias="requiresUserInteraction")
+    source: str
+    profiling_options: dict[str, Any] | None = Field(
+        alias="profilingOptions", default=None
+    )
+    job_source: str = Field(alias="jobSource")
+    job_key: str = Field(alias="jobKey")
+    process_key: str = Field(alias="processKey")
+    folder_id: int = Field(alias="folderId")
+    fully_qualified_folder_name: str = Field(alias="fullyQualifiedFolderName")
+    folder_key: str = Field(alias="folderKey")
+    folder_path: str = Field(alias="folderPath")
+    fps_context: str | None = Field(None, alias="fpsContext")
+    fps_properties: str | None = Field(None, alias="fpsProperties")
+    trace_id: str | None = Field(None, alias="traceId")
+    parent_span_id: str | None = Field(None, alias="parentSpanId")
+    root_span_id: str | None = Field(None, alias="rootSpanId")
+    id: str
+    type: str
+
+
+class UserDetails(BaseModel):
+    """User details associated with the command."""
+
+    model_config = ConfigDict(extra="allow")
+
+    key: str
+    email: str
+
+
+class Command(BaseModel):
+    """Robot command from Orchestrator."""
+
+    model_config = ConfigDict(
+        extra="allow", validate_by_name=True, validate_by_alias=True
+    )
+
+    robot_key: str = Field(alias="robotKey")
+    username: str | None = None
+    robot_name: str = Field(alias="robotName")
+    robot_type: int = Field(alias="robotType")
+    machine_id: int = Field(alias="machineId")
+    has_license: bool = Field(alias="hasLicense")
+    is_external_licensed: bool = Field(alias="isExternalLicensed")
+    execution_settings: ExecutionSettings = Field(alias="executionSettings")
+    auth_settings: AuthSettings = Field(alias="authSettings")
+    data: CommandData
+    user_details: UserDetails = Field(alias="userDetails")
+
+
+class HeartbeatResponse(BaseModel):
+    """Response from the heartbeat endpoint containing robot commands."""
+
+    model_config = ConfigDict(
+        extra="allow", validate_by_name=True, validate_by_alias=True
+    )
+
+    commands: list[Command]
+    service_settings_stamp: str = Field(alias="serviceSettingsStamp")
+    is_unattended: bool = Field(alias="isUnattended")
+    is_unattended_licensed: bool = Field(alias="isUnattendedLicensed")
+
+
+class JobError(BaseModel):
+    """Job error details."""
+
+    model_config = ConfigDict(
+        extra="allow", validate_by_name=True, validate_by_alias=True
+    )
+
+    code: str
+    title: str
+    category: str
+    detail: str | None = None
+
+
+class HeartbeatData(BaseModel):
+    """Heartbeat data for job state submission."""
+
+    model_config = ConfigDict(
+        extra="allow", validate_by_name=True, validate_by_alias=True
+    )
+
+    robot_key: str = Field(alias="robotKey")
+    job_state: JobState = Field(alias="jobState")
+    job_key: str = Field(alias="jobKey")
+    info: str | None = None
+    process_key: str = Field(alias="processKey")
+    output_arguments: str | None = Field(None, alias="outputArguments")
+    robot_state: SessionState = Field(alias="robotState")
+    error: JobError | None = Field(None, alias="error")
+    trace_id: str | None = Field(None, alias="traceId")
+    parent_span_id: str | None = Field(None, alias="parentSpanId")
+    root_span_id: str | None = Field(None, alias="rootSpanId")

uipath/robot/services/__init__.py

@@ -0,0 +1,6 @@
+"""Init file for robot services."""
+
+from .identity import IdentityService
+from .orchestrator import OrchestratorService
+
+__all__ = ["IdentityService", "OrchestratorService"]

uipath/robot/services/identity.py

@@ -0,0 +1,79 @@
+"""Module for handling machine authentication and token management."""
+
+import os
+from datetime import datetime, timedelta
+from typing import Any
+
+import httpx
+
+
+class IdentityService:
+    """Service for handling machine authentication and token management."""
+
+    def __init__(self):
+        """Initialize the IdentityService with environment variables."""
+        self.client_id = os.getenv("MACHINE_CLIENT_ID")
+        self.client_secret = os.getenv("MACHINE_CLIENT_SECRET")
+        self.base_url = os.getenv("UIPATH_URL")
+        self.organization_id = os.getenv("UIPATH_ORGANIZATION_ID")
+        self.tenant_id = os.getenv("UIPATH_TENANT_ID")
+
+        if not all(
+            [
+                self.client_id,
+                self.client_secret,
+                self.base_url,
+                self.organization_id,
+                self.tenant_id,
+            ]
+        ):
+            raise ValueError(
+                "Missing required environment variables: MACHINE_CLIENT_ID, MACHINE_CLIENT_SECRET, UIPATH_URL, UIPATH_ORGANIZATION_ID, UIPATH_TENANT_ID"
+            )
+
+        self.access_token: str | None = None
+        self.token_expiry: datetime | None = None
+
+    async def get_token(self) -> str:
+        """Get Service-to-Service access token using client credentials."""
+        assert self.base_url is not None
+
+        token_endpoint = f"{self.base_url.rstrip('/')}/identity_/connect/token"
+
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "scope": "OrchestratorApiUserAccess",
+        }
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                token_endpoint,
+                data=data,
+            )
+            response.raise_for_status()
+
+            token_data: dict[str, Any] = response.json()
+            self.access_token = token_data["access_token"]
+
+            expires_in = token_data.get("expires_in", 3600)
+            self.token_expiry = datetime.now() + timedelta(seconds=expires_in - 60)
+
+            os.environ["MACHINE_ACCESS_TOKEN"] = self.access_token
+
+            print(f"[{datetime.now()}] Token acquired successfully")
+            return self.access_token
+
+    def is_token_expired(self) -> bool:
+        """Check if the current token is expired or about to expire."""
+        if not self.access_token or not self.token_expiry:
+            return True
+        return datetime.now() >= self.token_expiry
+
+    async def ensure_valid_token(self) -> str:
+        """Ensure we have a valid token, refresh if needed."""
+        if self.is_token_expired():
+            await self.get_token()
+        assert self.access_token is not None
+        return self.access_token

uipath/robot/services/orchestrator.py

@@ -0,0 +1,303 @@
+"""Orchestrator service to interact with UiPath Orchestrator APIs."""
+
+import base64
+import os
+import platform
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from uipath.robot.infra import get_logger
+from uipath.robot.models import HeartbeatData, HeartbeatResponse
+
+
+class OrchestratorService:
+    """Service for interacting with UiPath Orchestrator APIs."""
+
+    def __init__(self):
+        """Initialize the OrchestratorService with environment variables."""
+        self.logger = get_logger()
+
+        self.access_token = os.getenv("UIPATH_ACCESS_TOKEN")
+        self.base_url = os.getenv("UIPATH_URL")
+
+        if not self.access_token:
+            raise ValueError("Missing UIPATH_ACCESS_TOKEN environment variable")
+        if not self.base_url:
+            raise ValueError("Missing UIPATH_URL environment variable")
+
+    async def get_shared_connection_data(self) -> str | None:
+        """Get shared connection data from Orchestrator.
+
+        Returns:
+            License key string if successful, None otherwise
+        """
+        assert self.base_url is not None
+
+        url = f"{self.base_url.rstrip('/')}/orchestrator_/api/robotsservice/getsharedconnectiondata"
+
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, headers=headers)
+                response.raise_for_status()
+
+                data: dict[str, Any] = response.json()
+                license_key = data.get("licenseKey")
+
+                if license_key:
+                    return license_key
+                else:
+                    self.logger.error("No LicenseKey found in response")
+                    return None
+
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code == 401:
+                    self.logger.error("Unauthorized: Invalid or expired token")
+                elif e.response.status_code == 409:
+                    self.logger.error(f"Conflict error occurred: {e.response.text}")
+                else:
+                    self.logger.error(f"HTTP error: {e.response.status_code} - {e}")
+                return None
+            except httpx.HTTPError as e:
+                self.logger.error(f"Request failed: {e}")
+                return None
+            except Exception as e:
+                self.logger.error(f"Unexpected error: {e}")
+                return None
+
+    async def download_package(
+        self,
+        package_id: str,
+        package_version: str,
+        output_path: Path,
+        feed_id: str | None = None,
+    ) -> bool:
+        """Download a package from Orchestrator.
+
+        Args:
+            package_id: The package identifier
+            package_version: The package version
+            output_path: Path where to save the downloaded package
+
+        Returns:
+            True if successful, False otherwise
+        """
+        assert self.base_url is not None
+
+        url = f"{self.base_url.rstrip('/')}/orchestrator_/odata/Processes/UiPath.Server.Configuration.OData.DownloadPackage(key='{package_id}:{package_version}')"
+
+        params = {}
+
+        if feed_id:
+            params["feedId"] = feed_id
+
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+        }
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, params=params, headers=headers)
+                response.raise_for_status()
+
+                # Write the package content to file
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                with open(output_path, "wb") as f:
+                    f.write(response.content)
+
+                return True
+
+            except httpx.HTTPStatusError as e:
+                self.logger.error(
+                    f"Failed to download package - HTTP {e.response.status_code}: {e}"
+                )
+                return False
+            except httpx.HTTPError as e:
+                self.logger.error(f"Failed to download package - Request error: {e}")
+                return False
+            except Exception as e:
+                self.logger.error(f"Failed to download package - Unexpected error: {e}")
+                return False
+
+    async def heartbeat(self, license_key: str) -> HeartbeatResponse:
+        """Send heartbeat to Orchestrator.
+
+        Args:
+            license_key: The robot license key. If None, uses stored license_key.
+
+        Returns:
+            HeartbeatResponse object containing commands from Orchestrator
+        """
+        assert self.base_url is not None
+
+        url = f"{self.base_url.rstrip('/')}/orchestrator_/api/robotsservice/heartbeatv2"
+
+        headers = {
+            **self._get_robot_headers(license_key),
+        }
+
+        payload = {"CommandState": "All", "Heartbeats": []}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(url, headers=headers, json=payload)
+                response.raise_for_status()
+                data = response.json()
+                return HeartbeatResponse.model_validate(data)
+
+            except httpx.HTTPStatusError as e:
+                self.logger.error(
+                    f"Heartbeat failed - HTTP {e.response.status_code}: {e}"
+                )
+                raise e
+            except httpx.HTTPError as e:
+                self.logger.error(f"Heartbeat failed - Request error: {e}")
+                raise e
+            except Exception as e:
+                self.logger.error(f"Heartbeat failed - Unexpected error: {e}")
+                raise e
+
+    async def start_service(self, license_key: str) -> bool:
+        """Send start service request to Orchestrator.
+
+        Args:
+            license_key: The robot license key.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        assert self.base_url is not None
+
+        url = (
+            f"{self.base_url.rstrip('/')}/orchestrator_/api/robotsservice/startservice"
+        )
+
+        headers = {
+            **self._get_robot_headers(license_key),
+        }
+
+        payload: dict[str, Any] = {}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(url, headers=headers, json=payload)
+                response.raise_for_status()
+                return True
+
+            except httpx.HTTPStatusError as e:
+                self.logger.error(
+                    f"Start service failed - HTTP {e.response.status_code}: {e}"
+                )
+                return False
+            except httpx.HTTPError as e:
+                self.logger.error(f"Start service failed - Request error: {e}")
+                return False
+            except Exception as e:
+                self.logger.error(f"Start service failed - Unexpected error: {e}")
+                return False
+
+    async def stop_service(self, license_key: str) -> bool:
+        """Send stop service request to Orchestrator.
+
+        Args:
+            license_key: The robot license key.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        assert self.base_url is not None
+
+        url = f"{self.base_url.rstrip('/')}/orchestrator_/api/robotsservice/stopservice"
+
+        headers = {
+            **self._get_robot_headers(license_key),
+        }
+
+        payload: dict[str, Any] = {}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(url, headers=headers, json=payload)
+                response.raise_for_status()
+                return True
+
+            except httpx.HTTPStatusError as e:
+                self.logger.error(
+                    f"Stop service failed - HTTP {e.response.status_code}: {e}"
+                )
+                return False
+            except httpx.HTTPError as e:
+                self.logger.error(f"Stop service failed - Request error: {e}")
+                return False
+            except Exception as e:
+                self.logger.error(f"Stop service failed - Unexpected error: {e}")
+                return False
+
+    async def submit_job_state(
+        self, heartbeats: list[HeartbeatData], license_key: str
+    ) -> bool:
+        """Submit job states to Orchestrator.
+
+        Args:
+            heartbeats: List of heartbeat data containing job states
+            license_key: The robot license key
+
+        Returns:
+            True if successful, False otherwise
+        """
+        assert self.base_url is not None
+
+        url = f"{self.base_url.rstrip('/')}/orchestrator_/api/robotsservice/SubmitJobState"
+
+        headers = {
+            **self._get_robot_headers(license_key),
+        }
+
+        payload = [heartbeat.model_dump(by_alias=True) for heartbeat in heartbeats]
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(url, headers=headers, json=payload)
+                response.raise_for_status()
+                return True
+
+            except httpx.HTTPStatusError as e:
+                self.logger.error(
+                    f"Submit job state failed - HTTP {e.response.status_code}: {e}"
+                )
+                self.logger.error(f"Response: {e.response.text}")
+                return False
+            except httpx.HTTPError as e:
+                self.logger.error(f"Submit job state failed - Request error: {e}")
+                return False
+            except Exception as e:
+                self.logger.error(f"Submit job state failed - Unexpected error: {e}")
+                return False
+
+    def _get_robot_headers(self, license_key: str) -> dict[str, str]:
+        """Get robot-specific headers for heartbeat calls.
+
+        Args:
+            license_key: The robot license key
+
+        Returns:
+            Dictionary of robot headers
+        """
+        machine = platform.node()
+        hostname = f"{machine}-py"
+
+        return {
+            "X-ROBOT-VERSION": "24.10",
+            "X-ROBOT-MACHINE": hostname,
+            "X-ROBOT-MACHINE-ENCODED": base64.b64encode(
+                hostname.encode("utf-8")
+            ).decode("utf-8"),
+            "X-ROBOT-LICENSE": license_key,
+            "X-ROBOT-AGENT": "OS=Windows",
+        }

uipath_robot-0.0.3.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: uipath-robot
+Version: 0.0.3
+Summary: UiPath Robot Simulator
+Project-URL: Homepage, https://uipath.com
+Project-URL: Documentation, https://uipath.github.io/uipath-python/
+Maintainer-email: Cristian Pufu <cristian.pufu@uipath.com>
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Requires-Dist: uipath>=2.4.0
+Description-Content-Type: text/markdown
+
+# UiPath Robot
+
+[![PyPI downloads](https://img.shields.io/pypi/dm/uipath-robot.svg)](https://pypi.org/project/uipath-robot/)
+[![PyPI - Version](https://img.shields.io/pypi/v/uipath-robot)](https://img.shields.io/pypi/v/uipath-robot)
+[![Python versions](https://img.shields.io/pypi/pyversions/uipath-robot.svg)](https://pypi.org/project/uipath-robot/)
+
+Robot simulator

uipath_robot-0.0.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+uipath/robot/__init__.py,sha256=gepn5ptexouVNXPLg57lUh3hZk_mNKJigt228mn09Wg,17486
+uipath/robot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uipath/robot/infra/__init__.py,sha256=r3uLvwBRZ9KiAjKPv71bAAdCMXA2yD7TcJuYPir4n7s,147
+uipath/robot/infra/logger.py,sha256=rrHINv5zn18Cu41OAf1sSRPNisEmlST_zBDfmDnRr2s,5654
+uipath/robot/models/__init__.py,sha256=MrFMohE9xtbXZTYyvvUm2vKXhT46M1ykHciIl_xFyGI,345
+uipath/robot/models/heartbeat.py,sha256=_9SMyMfgJQYOWAZfnOObrPLwF4_zxZO0IPkM3NAzRhw,5677
+uipath/robot/services/__init__.py,sha256=zLA_yMsrXTexcCE_lIa3TkMb9aN-LUgHXxL1ddPR58w,175
+uipath/robot/services/identity.py,sha256=1PGrSBxtCyKhET8wpSl_-b3b2zkskYRTiV_NpDjnUnU,2774
+uipath/robot/services/orchestrator.py,sha256=obX2hFzmwtBVemX_k1nD4c64HaZNausXeWrNRFhBU3g,10342
+uipath_robot-0.0.3.dist-info/METADATA,sha256=oFOP7rCwsfehrgancc8szE2YOlVJlhU_4bhCzjcyjrU,1063
+uipath_robot-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+uipath_robot-0.0.3.dist-info/entry_points.txt,sha256=AvnQfA63XXwIbb4EuWYd_J2Iqc2zwX3MGNglfUIxMpw,60
+uipath_robot-0.0.3.dist-info/licenses/LICENSE,sha256=-KBavWXepyDjimmzH5fVAsi-6jNVpIKFc2kZs0Ri4ng,1058
+uipath_robot-0.0.3.dist-info/RECORD,,

uipath_robot-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

uipath_robot-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uipath-robot = uipath.robot.__init__:main

uipath_robot-0.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2025 UiPath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.