oagi-core 0.9.1__py3-none-any.whl → 0.10.0__py3-none-any.whl

oagi/__init__.py

@@ -6,6 +6,7 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 import importlib
+from typing import TYPE_CHECKING
 
 from oagi.client import AsyncClient, SyncClient
 from oagi.exceptions import (
@@ -19,40 +20,82 @@ from oagi.exceptions import (
     RequestTimeoutError,
     ServerError,
     ValidationError,
+    check_optional_dependency,
 )
 from oagi.task import Actor, AsyncActor, AsyncShortTask, AsyncTask, ShortTask, Task
-from oagi.types import (
-    AsyncActionHandler,
-    AsyncImageProvider,
-    ImageConfig,
+from oagi.types import ImageConfig
+from oagi.types.models import (
+    ErrorDetail,
+    ErrorResponse,
+    GenerateResponse,
+    LLMResponse,
+    UploadFileResponse,
 )
-from oagi.types.models import ErrorDetail, ErrorResponse, LLMResponse
 
-# Lazy imports for pyautogui-dependent modules
-# These will only be imported when actually accessed
-_LAZY_IMPORTS = {
-    "AsyncPyautoguiActionHandler": "oagi.handler.async_pyautogui_action_handler",
-    "AsyncScreenshotMaker": "oagi.handler.async_screenshot_maker",
-    "PILImage": "oagi.handler.pil_image",
-    "PyautoguiActionHandler": "oagi.handler.pyautogui_action_handler",
-    "PyautoguiConfig": "oagi.handler.pyautogui_action_handler",
-    "ScreenshotMaker": "oagi.handler.screenshot_maker",
-    # Agent modules (to avoid circular imports)
-    "TaskerAgent": "oagi.agent.tasker",
-    # Server modules (optional - requires server dependencies)
-    "create_app": "oagi.server.main",
-    "ServerConfig": "oagi.server.config",
-    "sio": "oagi.server.socketio_server",
+# Lazy imports for optional dependency modules
+# Format: name -> (module_path, package_to_check, extra_name)
+# package_to_check is None if no optional dependency is required
+_LAZY_IMPORTS_DATA: dict[str, tuple[str, str | None, str | None]] = {
+    # Desktop handlers (require pyautogui/PIL)
+    "AsyncPyautoguiActionHandler": (
+        "oagi.handler.async_pyautogui_action_handler",
+        "pyautogui",
+        "desktop",
+    ),
+    "AsyncScreenshotMaker": ("oagi.handler.async_screenshot_maker", "PIL", "desktop"),
+    "PILImage": ("oagi.handler.pil_image", "PIL", "desktop"),
+    "PyautoguiActionHandler": (
+        "oagi.handler.pyautogui_action_handler",
+        "pyautogui",
+        "desktop",
+    ),
+    "PyautoguiConfig": (
+        "oagi.handler.pyautogui_action_handler",
+        "pyautogui",
+        "desktop",
+    ),
+    "ScreenshotMaker": ("oagi.handler.screenshot_maker", "PIL", "desktop"),
+    # Agent modules (lazy to avoid circular imports)
+    "AsyncDefaultAgent": ("oagi.agent.default", None, None),
+    "TaskerAgent": ("oagi.agent.tasker", None, None),
+    "AsyncAgentObserver": ("oagi.agent.observer.agent_observer", None, None),
+    # Server modules (require server dependencies)
+    "create_app": ("oagi.server.main", "socketio", "server"),
+    "ServerConfig": ("oagi.server.config", "pydantic_settings", "server"),
+    "sio": ("oagi.server.socketio_server", "socketio", "server"),
 }
 
+if TYPE_CHECKING:
+    from oagi.agent.default import AsyncDefaultAgent
+    from oagi.agent.observer.agent_observer import AsyncAgentObserver
+    from oagi.agent.tasker import TaskerAgent
+    from oagi.handler.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
+    from oagi.handler.async_screenshot_maker import AsyncScreenshotMaker
+    from oagi.handler.pil_image import PILImage
+    from oagi.handler.pyautogui_action_handler import (
+        PyautoguiActionHandler,
+        PyautoguiConfig,
+    )
+    from oagi.handler.screenshot_maker import ScreenshotMaker
+    from oagi.server.config import ServerConfig
+    from oagi.server.main import create_app
+    from oagi.server.socketio_server import sio
+
 
 def __getattr__(name: str):
-    """Lazy import for pyautogui-dependent modules."""
-    if name in _LAZY_IMPORTS:
-        module_name = _LAZY_IMPORTS[name]
-        module = importlib.import_module(module_name)
+    """Lazy import for optional dependency modules with helpful error messages."""
+    if name in _LAZY_IMPORTS_DATA:
+        module_path, package, extra = _LAZY_IMPORTS_DATA[name]
+        if package is not None:
+            check_optional_dependency(package, name, extra)
+        module = importlib.import_module(module_path)
         return getattr(module, name)
-    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all public names including lazy imports."""
+    return sorted(set(globals().keys()) | set(_LAZY_IMPORTS_DATA.keys()))
 
 
 __all__ = [
@@ -67,14 +110,15 @@ __all__ = [
     "AsyncShortTask",  # Deprecated
     "AsyncClient",
     # Agent classes
+    "AsyncDefaultAgent",
     "TaskerAgent",
-    # Async protocols
-    "AsyncActionHandler",
-    "AsyncImageProvider",
+    "AsyncAgentObserver",
     # Configuration
     "ImageConfig",
     # Response models
     "LLMResponse",
+    "GenerateResponse",
+    "UploadFileResponse",
     "ErrorResponse",
     "ErrorDetail",
     # Exceptions
@@ -88,17 +132,16 @@ __all__ = [
     "ServerError",
     "RequestTimeoutError",
     "ValidationError",
-    # Lazy imports
-    # Image classes
+    # Lazy imports - Image classes
     "PILImage",
-    # Handler classes
+    # Lazy imports - Handler classes
     "PyautoguiActionHandler",
     "PyautoguiConfig",
     "ScreenshotMaker",
-    # Async handler classes
+    # Lazy imports - Async handler classes
     "AsyncPyautoguiActionHandler",
     "AsyncScreenshotMaker",
-    # Server modules (optional)
+    # Lazy imports - Server modules (optional)
     "create_app",
     "ServerConfig",
     "sio",

oagi/agent/__init__.py

@@ -9,6 +9,7 @@
 # Import factories to trigger registration
 from . import factories  # noqa: F401
 from .default import AsyncDefaultAgent
+from .observer import AsyncAgentObserver
 from .protocol import Agent, AsyncAgent
 from .registry import (
     async_agent_register,
@@ -21,6 +22,7 @@ from .tasker import TaskeeAgent, TaskerAgent
 __all__ = [
     "Agent",
     "AsyncAgent",
+    "AsyncAgentObserver",
     "AsyncDefaultAgent",
     "TaskerAgent",
     "TaskeeAgent",

oagi/agent/default.py

@@ -10,14 +10,24 @@ import logging
 
 from .. import AsyncActor
 from ..types import (
+    ActionEvent,
     AsyncActionHandler,
     AsyncImageProvider,
-    AsyncStepObserver,
+    AsyncObserver,
+    Image,
+    StepEvent,
 )
 
 logger = logging.getLogger(__name__)
 
 
+def _serialize_image(image: Image | str) -> bytes | str:
+    """Convert an image to bytes or keep URL as string."""
+    if isinstance(image, str):
+        return image
+    return image.read()
+
+
 class AsyncDefaultAgent:
     """Default asynchronous agent implementation using OAGI client."""
 
@@ -25,10 +35,10 @@ class AsyncDefaultAgent:
         self,
         api_key: str | None = None,
         base_url: str | None = None,
-        model: str = "lux-v1",
-        max_steps: int = 30,
-        temperature: float | None = None,
-        step_observer: AsyncStepObserver | None = None,
+        model: str = "lux-actor-1",
+        max_steps: int = 20,
+        temperature: float | None = 0.5,
+        step_observer: AsyncObserver | None = None,
     ):
         self.api_key = api_key
         self.base_url = base_url
@@ -50,7 +60,8 @@ class AsyncDefaultAgent:
             await self.actor.init_task(instruction, max_steps=self.max_steps)
 
             for i in range(self.max_steps):
-                logger.debug(f"Executing step {i + 1}/{self.max_steps}")
+                step_num = i + 1
+                logger.debug(f"Executing step {step_num}/{self.max_steps}")
 
                 # Capture current state
                 image = await image_provider()
@@ -60,11 +71,17 @@ class AsyncDefaultAgent:
 
                 # Log reasoning
                 if step.reason:
-                    logger.info(f"Step {i + 1}: {step.reason}")
+                    logger.info(f"Step {step_num}: {step.reason}")
 
-                # Notify observer if present
-                if self.step_observer and step.actions:
-                    await self.step_observer.on_step(i + 1, step.reason, step.actions)
+                # Emit step event
+                if self.step_observer:
+                    await self.step_observer.on_event(
+                        StepEvent(
+                            step_num=step_num,
+                            image=_serialize_image(image),
+                            step=step,
+                        )
+                    )
 
                 # Execute actions if any
                 if step.actions:
@@ -78,11 +95,27 @@ class AsyncDefaultAgent:
                         logger.info(
                             f"  [{action.type.value}] {action.argument}{count_suffix}"
                         )
-                    await action_handler(step.actions)
+
+                    error = None
+                    try:
+                        await action_handler(step.actions)
+                    except Exception as e:
+                        error = str(e)
+                        raise
+
+                    # Emit action event
+                    if self.step_observer:
+                        await self.step_observer.on_event(
+                            ActionEvent(
+                                step_num=step_num,
+                                actions=step.actions,
+                                error=error,
+                            )
+                        )
 
                 # Check if task is complete
                 if step.stop:
-                    logger.info(f"Task completed successfully after {i + 1} steps")
+                    logger.info(f"Task completed successfully after {step_num} steps")
                     return True
 
             logger.warning(

oagi/agent/factories.py

@@ -17,7 +17,7 @@ from .registry import async_agent_register
 def create_default_agent(
     api_key: str | None = None,
     base_url: str | None = None,
-    model: str = "lux-v1",
+    model: str = "lux-actor-1",
     max_steps: int = 20,
     temperature: float = 0.1,
     step_observer: AsyncStepObserver | None = None,
@@ -32,13 +32,32 @@ def create_default_agent(
     )
 
 
+@async_agent_register(mode="thinker")
+def create_thinker_agent(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str = "lux-thinker-1",
+    max_steps: int = 100,
+    temperature: float = 0.1,
+    step_observer: AsyncStepObserver | None = None,
+) -> AsyncAgent:
+    return AsyncDefaultAgent(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+        step_observer=step_observer,
+    )
+
+
 @async_agent_register(mode="tasker")
 def create_planner_agent(
     api_key: str | None = None,
     base_url: str | None = None,
-    model: str = "lux-v1",
+    model: str = "lux-actor-1",
     max_steps: int = 30,
-    temperature: float = 0.0,
+    temperature: float = 0.1,
     reflection_interval: int = 20,
     step_observer: AsyncStepObserver | None = None,
 ) -> AsyncAgent:

oagi/agent/observer/__init__.py

@@ -0,0 +1,38 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from ...types import (
+    ActionEvent,
+    AsyncObserver,
+    BaseEvent,
+    ImageEvent,
+    LogEvent,
+    ObserverEvent,
+    PlanEvent,
+    SplitEvent,
+    StepEvent,
+)
+from .agent_observer import AsyncAgentObserver, ExportFormat
+from .exporters import export_to_html, export_to_json, export_to_markdown
+
+__all__ = [
+    "ActionEvent",
+    "AsyncAgentObserver",
+    "AsyncObserver",
+    "BaseEvent",
+    "ExportFormat",
+    "ImageEvent",
+    "LogEvent",
+    "ObserverEvent",
+    "PlanEvent",
+    "SplitEvent",
+    "StepEvent",
+    "export_to_html",
+    "export_to_json",
+    "export_to_markdown",
+]

oagi/agent/observer/agent_observer.py

@@ -0,0 +1,99 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from enum import Enum
+
+from ...types import LogEvent, ObserverEvent, SplitEvent
+from .exporters import export_to_html, export_to_json, export_to_markdown
+
+
+class ExportFormat(str, Enum):
+    """Supported export formats."""
+
+    MARKDOWN = "markdown"
+    HTML = "html"
+    JSON = "json"
+
+
+class AsyncAgentObserver:
+    """Records agent execution events and exports to various formats.
+
+    This class implements the AsyncObserver protocol and provides
+    functionality for recording events during agent execution and
+    exporting them to Markdown or HTML formats.
+    """
+
+    def __init__(self) -> None:
+        self.events: list[ObserverEvent] = []
+
+    async def on_event(self, event: ObserverEvent) -> None:
+        """Record an event.
+
+        Args:
+            event: The event to record.
+        """
+        self.events.append(event)
+
+    def add_log(self, message: str) -> None:
+        """Add a custom log message.
+
+        Args:
+            message: The log message to add.
+        """
+        self.events.append(LogEvent(message=message))
+
+    def add_split(self, label: str = "") -> None:
+        """Add a visual separator.
+
+        Args:
+            label: Optional label for the separator.
+        """
+        self.events.append(SplitEvent(label=label))
+
+    def clear(self) -> None:
+        """Clear all recorded events."""
+        self.events.clear()
+
+    def get_events_by_step(self, step_num: int) -> list[ObserverEvent]:
+        """Get all events for a specific step.
+
+        Args:
+            step_num: The step number to filter by.
+
+        Returns:
+            List of events for the specified step.
+        """
+        return [
+            event
+            for event in self.events
+            if hasattr(event, "step_num") and event.step_num == step_num
+        ]
+
+    def export(
+        self,
+        format: ExportFormat | str,
+        path: str,
+        images_dir: str | None = None,
+    ) -> None:
+        """Export recorded events to a file.
+
+        Args:
+            format: Export format (markdown, html, json)
+            path: Path to the output file.
+            images_dir: Directory to save images (markdown only).
+        """
+        if isinstance(format, str):
+            format = ExportFormat(format.lower())
+
+        match format:
+            case ExportFormat.MARKDOWN:
+                export_to_markdown(self.events, path, images_dir)
+            case ExportFormat.HTML:
+                export_to_html(self.events, path)
+            case ExportFormat.JSON:
+                export_to_json(self.events, path)

oagi/agent/observer/events.py

@@ -0,0 +1,28 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+# Re-export from types for convenience
+from ...types import (
+    ActionEvent,
+    BaseEvent,
+    ImageEvent,
+    LogEvent,
+    ObserverEvent,
+    SplitEvent,
+    StepEvent,
+)
+
+__all__ = [
+    "ActionEvent",
+    "BaseEvent",
+    "ImageEvent",
+    "LogEvent",
+    "ObserverEvent",
+    "SplitEvent",
+    "StepEvent",
+]