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>
122 lines
2.8 KiB
Markdown
122 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
from gui_agents.utils.id_utils import generate_timestamp_id
|
|
|
|
# Timestamp-based ID
|
|
ts_id = generate_timestamp_id("event") # "event1755576661494"
|
|
```
|
|
|
|
### Hash ID
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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, {})
|
|
```
|