3a4b67304f
* Added a **pyproject.toml** file to define project metadata and dependencies. * Added **run\_maestro.py** and **osworld\_run\_maestro.py** to provide the main execution logic. * Introduced multiple new modules, including **Evaluator**, **Controller**, **Manager**, and **Sub-Worker**, supporting task planning, state management, and data analysis. * Added a **tools module** containing utility functions and tool configurations to improve code reusability. * Updated the **README** and documentation with usage examples and module descriptions. These changes lay the foundation for expanding the Maestro project’s functionality and improving the user experience. Co-authored-by: Hiroid <guoliangxuan@deepmatrix.com>
Maestro Utilities
This directory contains various utility functions for the Maestro project to improve code reusability and maintainability.
File Structure
gui_agents/utils/
├── README.md # This document
├── file_utils.py # File operation utilities
├── id_utils.py # ID generation utilities
└── common_utils.py # Other common utilities
file_utils.py - File Operation Utilities
File Locking Mechanism
from gui_agents.utils.file_utils import locked
# Cross-platform file lock, supports Windows and Unix systems
with locked(file_path, "w") as f:
f.write("content")
Safe JSON Operations
from gui_agents.utils.file_utils import safe_write_json, safe_read_json
# Safely write JSON file (atomic operation)
safe_write_json(file_path, data)
# Safely read JSON file
data = safe_read_json(file_path, default={})
Safe Text Operations
from gui_agents.utils.file_utils import safe_write_text, safe_read_text
# Safely write text file (UTF-8 encoding)
safe_write_text(file_path, content)
# Safely read text file (automatic encoding detection)
content = safe_read_text(file_path)
File Management Tools
from gui_agents.utils.file_utils import ensure_directory, backup_file
# Ensure directory exists
ensure_directory(path)
# Create file backup
backup_path = backup_file(file_path, ".backup")
id_utils.py - ID Generation Utilities
UUID Generation
from gui_agents.utils.id_utils import generate_uuid, generate_short_id
# Generate complete UUID
uuid_str = generate_uuid() # "550e8400-e29b-41d4-a716-446655440000"
# Generate short ID
short_id = generate_short_id("task", 8) # "task550e8400"
Timestamp ID
from gui_agents.utils.id_utils import generate_timestamp_id
# Timestamp-based ID
ts_id = generate_timestamp_id("event") # "event1755576661494"
Hash ID
from gui_agents.utils.id_utils import generate_hash_id
# Content hash-based ID
hash_id = generate_hash_id("some content", "hash", 8) # "hasha1b2c3d4"
Composite ID
from gui_agents.utils.id_utils import generate_composite_id
# Composite ID (prefix + timestamp + UUID)
composite_id = generate_composite_id("task", True, True, "_") # "task_1755576661494_550e8400"
Usage in NewGlobalState
The new NewGlobalState class has been refactored to use these utility functions:
from gui_agents.utils.file_utils import safe_write_json, safe_read_json
from gui_agents.utils.id_utils import generate_uuid
class NewGlobalState:
def __init__(self, ...):
self.task_id = task_id or f"task-{generate_uuid()[:8]}"
def set_task(self, task_data):
safe_write_json(self.task_path, task_data)
def get_task(self):
return safe_read_json(self.task_path, {})