polyrob 0.5.0__py3-none-any.whl

agents/task/README_PATH_MANAGEMENT.md

@@ -0,0 +1,141 @@
+# Task Path Management System
+
+## Overview
+
+The Task path management system provides a centralized way to handle file paths across the entire codebase. This ensures consistency, prevents path-related bugs, and simplifies multiuser support.
+
+## Key Components
+
+- **PathManager**: The central class for all path operations, accessed via the `pm()` singleton.
+- **Session Directories**: Structured directories for each session with standardized subdirectories.
+
+## Usage
+
+Always use the centralized path manager, which is accessed through the `pm()` function:
+
+```python
+from agents.task.path import pm
+
+# Clean a session ID to remove any unsafe characters
+clean_id = pm().clean_session_id(session_id)
+
+# Get the base directory for a session
+session_dir = pm().get_session_root(session_id)
+
+# Get subdirectories
+workspace_dir = pm().get_workspace_dir(session_id)
+screenshots_dir = pm().get_screenshots_dir(session_id)
+logs_dir = pm().get_logs_dir(session_id)
+data_dir = pm().get_data_dir(session_id)
+telemetry_dir = pm().get_telemetry_dir(session_id)
+history_dir = pm().get_history_dir(session_id)
+
+# Create a file path within a session subdirectory
+file_path = pm().create_file_path(session_id, "results", "output.json")
+```
+
+## Directory Structure
+
+Each session gets its own directory with subdirectories:
+
+```
+data/task/
+└── {user_id}/
+    └── {session_id}/
+        ├── workspace/   # For files created by the agent (user-facing)
+        ├── feed/        # For message feed (real-time events)
+        ├── screenshots/ # For saved screenshots
+        ├── logs/        # For log files
+        ├── artifacts/   # For build outputs, downloads
+        ├── memory/      # For conversation history
+        └── data/        # For structured data (internal, not user-facing)
+            ├── telemetry/   # For telemetry events
+            ├── history/     # For agent execution history
+            └── llm_usage/   # For LLM usage tracking
+```
+
+**Note:** The structure no longer includes a `sessions/` subdirectory. Sessions are stored directly under the user directory.
+
+**Key Distinction:**
+- `workspace/` = Files FOR the user (user-facing output)
+- `data/` = Internal agent tracking (not user-facing)
+
+## Best Practices
+
+1. **Always use the path manager**: Never construct paths manually using string concatenation or `os.path.join()`.
+2. **Clean session IDs**: Always use `pm().clean_session_id()` when handling user-provided session IDs.
+3. **Use standard subdirectories**: Stick to the standard subdirectories (`workspace`, `feed`, `screenshots`, `logs`, `data`).
+4. **Avoid hardcoded paths**: Don't hardcode paths like `data/task/` - the base directory could change. Always use PathManager methods.
+
+## For Advanced Use Cases
+
+The PathManager singleton is configured automatically. For testing, you can create temporary directories within the standard structure.
+
+## Path Manager API Reference
+
+| Method | Description |
+|--------|-------------|
+| `pm().clean_session_id(session_id)` | Sanitizes session ID |
+| `pm().get_session_root(session_id)` | Gets the session's root directory |
+| `pm().get_workspace_dir(session_id)` | Gets the session's workspace directory |
+| `pm().get_screenshots_dir(session_id)` | Gets the session's screenshots directory |
+| `pm().get_logs_dir(session_id)` | Gets the session's logs directory |
+| `pm().get_data_dir(session_id)` | Gets the session's data directory |
+| `pm().get_telemetry_dir(session_id)` | Gets the telemetry subdirectory |
+| `pm().get_history_dir(session_id)` | Gets the browser history subdirectory |
+| `pm().create_file_path(session_id, subdir, filename)` | Creates a file path in a subdirectory |
+
+## Migration Guide
+
+### Using the Centralized PathManager
+
+Always use the PathManager singleton through `pm()`:
+
+```python
+from agents.task.path import pm
+
+# Clean session IDs
+clean_id = pm().clean_session_id(session_id)
+
+# Get directories
+workspace = pm().get_workspace_dir(clean_id)
+telemetry = pm().get_telemetry_dir(clean_id)
+
+# Create file paths
+file_path = pm().create_file_path(clean_id, "workspace", "output.txt")
+```
+
+### Avoid Direct Path Construction
+
+Never construct paths manually:
+
+```python
+# Wrong - hardcoded path
+path = f"data/task/{user_id}/{session_id}/workspace/file.txt"
+
+# Right - use PathManager
+path = pm().create_file_path(session_id, "workspace", "file.txt", user_id=user_id)
+
+# Even simpler
+workspace_dir = pm().get_workspace_dir(session_id, user_id)
+path = workspace_dir / "file.txt"
+```
+
+## Thread Safety and Locking
+
+PathManager uses file locks to prevent race conditions during directory creation, making it safe for multi-threaded and multi-process environments.
+
+## Testing
+
+Run the path management tests:
+```
+pytest agents/task/agent/tests.py::TestPathManagement
+```
+
+## Troubleshooting
+
+If you see "Cannot access PathManager to determine proper data paths" errors, ensure:
+
+1. You have initialized SessionManager before using path functions
+2. Your code does not have circular imports
+3. You are using path_utils helpers instead of direct string concatenation 

agents/task/__init__.py

@@ -0,0 +1,162 @@
+"""
+AutoV2 Agent Framework
+
+This package provides advanced agent capabilities for autonomous tasks.
+
+Usage:
+    from agents.task import pm, get_session_manager
+
+    # Clean a session ID
+    clean_id = pm().clean_session_id(session_id)
+    
+    # Get session manager
+    session_mgr = get_session_manager()
+    
+    # Create a session
+    session_id = session_mgr.create_session()
+"""
+
+from core.version import __version__  # noqa: F401  (project version SSOT)
+
+from typing import TYPE_CHECKING
+
+# Lazy package (PEP 562): importing any `agents.task.*` leaf (e.g. agents.task.constants,
+# the import-light flag/config module) must NOT eager-load the agent session/orchestrator
+# stack (which pulls the LLM SDKs). The helpers below resolve on first attribute access so
+# `from agents.task import pm, get_session_manager` keeps working unchanged.
+# See docs/plans/2026-06-26-runtime-architecture-finalization-FUSION.md (P1b).
+_LAZY_ATTRS = {
+    "pm": (".path", "pm"),
+    "get_safe_singleton": (".path", "get_safe_singleton"),
+    "send_telemetry": (".utils", "send_telemetry"),
+    "get_session_manager": (".agent.session", "get_session_manager"),
+}
+
+if TYPE_CHECKING:  # static analysis / IDEs only — no runtime import
+    from agents.task.path import pm, get_safe_singleton
+    from agents.task.utils import send_telemetry
+    from agents.task.agent.session import get_session_manager
+
+
+def __getattr__(name: str):
+    """PEP 562 lazy resolution; caches into globals() so it fires once per name."""
+    if name in _LAZY_ATTRS:
+        import importlib
+        module_path, attr = _LAZY_ATTRS[name]
+        value = getattr(importlib.import_module(module_path, __name__), attr)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_ATTRS))
+
+# Session ID best practices
+"""
+STANDARD PATTERN FOR SESSION ID HANDLING:
+
+1. Always clean session IDs at the entry point of public methods:
+   ```python
+   def my_method(self, session_id: str):
+       clean_id = pm().clean_session_id(session_id)
+       # Use clean_id for all operations
+   ```
+
+2. Always use pm().clean_session_id() as the canonical cleaning method
+   
+3. When extracting session ID from agent_id:
+   ```python
+   if '_' in agent_id:
+       session_id = agent_id.split('_', 1)[1]
+       clean_id = pm().clean_session_id(session_id)
+   ```
+   
+4. Never perform string transformations directly on session IDs
+"""
+
+from typing import Optional, Dict, Any
+
+def capture_llm_request(
+    component: str,
+    purpose: str,
+    model_name: str,
+    duration_seconds: float,
+    success: bool,
+    token_count: Optional[int] = None,
+    session_id: Optional[str] = None,
+    prompt_tokens: Optional[int] = None,
+    completion_tokens: Optional[int] = None,
+    cached_tokens: Optional[int] = None,
+    agent_id: Optional[str] = None,
+    total_tokens: Optional[int] = None,
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    **kwargs  # Accept any additional kwargs for forward compatibility
+) -> str:
+    """
+    Capture details about an LLM request for telemetry and monitoring.
+
+    This is a thin wrapper around ProductTelemetry.capture_llm_usage to support
+    existing tests and code that depends on this function.
+
+    Args:
+        component: Component using the LLM (agent, planner, etc.)
+        purpose: Purpose of the request (next_action, planning, etc.)
+        model_name: Name of the model used
+        duration_seconds: Duration of the request in seconds
+        success: Whether the request succeeded
+        token_count: Total token count (if available)
+        session_id: Session ID for tracking
+        prompt_tokens: Number of tokens in the prompt (if available)
+        completion_tokens: Number of tokens in the completion (if available)
+        cached_tokens: Number of cached prompt tokens (for prompt caching cost calculation)
+        agent_id: Optional agent ID for explicit tracking
+        total_tokens: Total tokens (alternative to token_count)
+        temperature: Temperature setting used for the request
+        max_tokens: Max tokens setting used for the request
+        **kwargs: Additional parameters for forward compatibility
+
+    Returns:
+        str: The request_id used for this telemetry entry
+    """
+    try:
+        # Import here to avoid circular imports
+        from agents.task.telemetry.service import ProductTelemetry
+        
+        # Get telemetry service
+        telemetry = ProductTelemetry()
+        
+        # Use total_tokens if provided and token_count is not
+        if total_tokens and not token_count:
+            token_count = total_tokens
+        
+        # Prepare parameters dict with additional metadata
+        parameters = {}
+        if temperature is not None:
+            parameters['temperature'] = temperature
+        if max_tokens is not None:
+            parameters['max_tokens'] = max_tokens
+        # Add any other kwargs to parameters
+        for key, value in kwargs.items():
+            if key not in ['total_tokens']:  # Skip already handled
+                parameters[key] = value
+        
+        # Forward to capture_llm_usage method and return the request_id
+        return telemetry.capture_llm_usage(
+            component=component,
+            purpose=purpose,
+            model_name=model_name,
+            duration_seconds=duration_seconds,
+            success=success,
+            token_count=token_count,
+            session_id=session_id,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            cached_tokens=cached_tokens,
+            agent_id=agent_id,
+            parameters=parameters if parameters else None
+        )
+    except Exception as e:
+        # Silently fail for telemetry functions to avoid breaking main code
+        return ""

agents/task/agent/__init__.py

@@ -0,0 +1,70 @@
+"""
+Agent module initialization.
+
+This module exposes the Agent, SessionManager, and other core components.
+"""
+
+# Import centralized path manager first to avoid circular dependencies
+from agents.task.path import pm
+
+# Import core components
+from agents.task.agent.service import Agent
+from agents.task.agent.session import SessionManager
+from agents.task.agent.orchestrator import SessionOrchestrator
+from agents.task.agent.sub_agent_manager import SubAgentManager
+from agents.task.path import get_safe_singleton
+
+# Re-export core components
+__all__ = [
+    "Agent",
+    "SessionManager",
+    "SessionOrchestrator",
+    "SubAgentManager",
+]
+
+# Perform initialization tasks
+def _initialize():
+    """Perform module initialization tasks like session cleanup"""
+    try:
+        import logging
+        logger = logging.getLogger("task.agent_init")
+        logger.info("Running agent module initialization")
+        
+        # Import SessionManager here to avoid circular imports
+        from agents.task.agent.session import SessionManager
+        
+        try:
+            # Get the SessionManager instance
+            session_manager = get_safe_singleton(SessionManager)()
+            logger.info("SessionManager instance initialized")
+            
+        except Exception as e:
+            logger.error(f"SessionManager initialization failed: {e}")
+            # We'll continue without a session manager - the application should
+            # handle this gracefully by using direct path utilities
+            
+        # Log completion
+        logger.info("Agent module initialization complete")
+    except Exception as e:
+        # Use basic logging if we can't get the logger
+        try:
+            import logging
+            logging.getLogger("task").warning(f"Agent module initialization failed: {e}")
+        except:
+            # Last resort - we can't do anything else
+            print(f"CRITICAL: Agent module initialization failed: {e}")
+
+# Run initialization only if AUTO_AGENT_INIT environment variable is set.
+# SA-08: use the core.env SSOT parser (canonical falsey-set semantics) instead of an
+# ad-hoc truthy-set that silently ignored AUTO_AGENT_INIT=on.
+from core.env import bool_env as _bool_env
+if _bool_env('AUTO_AGENT_INIT', False):
+    _initialize()
+else:
+    # Log that we're skipping initialization 
+    try:
+        import logging
+        logger = logging.getLogger("task.agent_init")
+        logger.debug("Skipping agent module initialization (AUTO_AGENT_INIT not set)")
+    except:
+        pass