agi-python 0.0.1__py3-none-any.whl

agi/__init__.py

@@ -0,0 +1,70 @@
+"""Official Python SDK for AGI.tech API.
+
+The agi package provides a complete Python SDK for the AGI.tech API,
+enabling developers to create and manage AI agent sessions that can perform
+complex web tasks.
+
+Example:
+    >>> from agi import AGIClient
+    >>>
+    >>> client = AGIClient(api_key="your_api_key")
+    >>>
+    >>> with client.session("agi-0") as session:
+    ...     result = session.run_task(
+    ...         "Find three nonstop SFO→JFK flights next month under $450"
+    ...     )
+    ...     print(result)
+"""
+
+from agi.client import AGIClient
+from agi.exceptions import (
+    AgentExecutionError,
+    AGIError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+from agi.types.results import Screenshot, TaskMetadata, TaskResult
+from agi.types.sessions import (
+    DeleteResponse,
+    ExecuteStatusResponse,
+    MessageResponse,
+    MessagesResponse,
+    NavigateResponse,
+    ScreenshotResponse,
+    SessionResponse,
+    SSEEvent,
+    SuccessResponse,
+)
+from agi.types.shared import EventType, MessageType, SessionStatus, SnapshotMode
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AGIClient",
+    "AGIError",
+    "APIError",
+    "AgentExecutionError",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "SessionResponse",
+    "SSEEvent",
+    "MessageResponse",
+    "MessagesResponse",
+    "ExecuteStatusResponse",
+    "DeleteResponse",
+    "NavigateResponse",
+    "Screenshot",
+    "ScreenshotResponse",
+    "SuccessResponse",
+    "TaskResult",
+    "TaskMetadata",
+    "EventType",
+    "MessageType",
+    "SessionStatus",
+    "SnapshotMode",
+]

agi/_http.py

@@ -0,0 +1,135 @@
+"""HTTP client for AGI API."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from agi.exceptions import (
+    AGIError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+
+
+class HTTPClient:
+    """HTTP client with retry logic and error handling."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.agi.tech",
+        timeout: int = 60,
+        max_retries: int = 3,
+    ):
+        """Initialize HTTP client.
+
+        Args:
+            api_key: API key for authentication
+            base_url: Base URL for API
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts for 5xx errors
+        """
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+        self._max_retries = max_retries
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Make HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: Request path
+            **kwargs: Additional arguments for httpx.request()
+
+        Returns:
+            HTTP response
+
+        Raises:
+            AGIError: On API errors
+        """
+        last_exception: httpx.HTTPStatusError | None = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = self._client.request(method, path, **kwargs)
+                response.raise_for_status()
+                return response
+
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code >= 500 and attempt < self._max_retries - 1:
+                    wait_time = 2**attempt
+                    time.sleep(wait_time)
+                    last_exception = e
+                    continue
+
+                self._handle_error(e.response)
+                raise
+
+            except (httpx.RequestError, httpx.TimeoutException) as e:
+                if attempt < self._max_retries - 1:
+                    wait_time = 2**attempt
+                    time.sleep(wait_time)
+                    continue
+                raise APIError(f"Request failed: {str(e)}") from e
+
+        if last_exception:
+            raise APIError(f"Max retries exceeded: {str(last_exception)}") from last_exception
+
+        raise APIError("Request failed")
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Map HTTP errors to SDK exceptions.
+
+        Args:
+            response: HTTP response with error status
+
+        Raises:
+            Specific AGIError subclass based on status code
+        """
+        status_code = response.status_code
+
+        try:
+            error_data = response.json()
+            error_message = error_data.get("detail", response.text)
+        except Exception:
+            error_message = response.text
+
+        if status_code == 401:
+            raise AuthenticationError(f"Authentication failed: {error_message}")
+        elif status_code == 403:
+            raise PermissionError(f"Permission denied: {error_message}")
+        elif status_code == 404:
+            raise NotFoundError(f"Resource not found: {error_message}")
+        elif status_code == 429:
+            raise RateLimitError(f"Rate limit exceeded: {error_message}")
+        elif status_code >= 500:
+            raise APIError(f"Server error ({status_code}): {error_message}")
+        else:
+            raise AGIError(f"API error ({status_code}): {error_message}")
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> HTTPClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

agi/_session_context.py

@@ -0,0 +1,345 @@
+"""Session context manager for high-level API."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from agi.exceptions import AgentExecutionError
+from agi.types.results import Screenshot, TaskMetadata, TaskResult
+
+if TYPE_CHECKING:
+    from agi.client import AGIClient
+    from agi.types.sessions import (
+        ExecuteStatusResponse,
+        MessagesResponse,
+        NavigateResponse,
+        SSEEvent,
+        SuccessResponse,
+    )
+
+
+class SessionContext:
+    """High-level session context manager matching docs pattern.
+
+    This provides the simple API shown in documentation:
+        with client.session("agi-0") as session:
+            result = session.run_task("Find cheapest iPhone 15...")
+
+    Example:
+        >>> from agi import AGIClient
+        >>> client = AGIClient(api_key="...")
+        >>>
+        >>> with client.session("agi-0") as session:
+        ...     result = session.run_task("Find flights SFO→JFK under $450")
+        ...     print(result)
+    """
+
+    def __init__(
+        self,
+        client: AGIClient,
+        agent_name: str = "agi-0",
+        **create_kwargs: Any,
+    ):
+        """Initialize session context.
+
+        Args:
+            client: AGIClient instance
+            agent_name: Agent model to use
+            **create_kwargs: Additional arguments for session creation
+                (webhook_url, goal, max_steps, restore_from_environment_id)
+        """
+        self._client = client
+        self._agent_name = agent_name
+        self._create_kwargs = create_kwargs
+        self.session_id: str | None = None
+        self.vnc_url: str | None = None
+        self.agent_url: str | None = None
+
+    def __enter__(self) -> SessionContext:
+        """Create session on context entry.
+
+        Returns:
+            SessionContext instance
+        """
+        response = self._client.sessions.create(
+            agent_name=self._agent_name,
+            **self._create_kwargs,
+        )
+        self.session_id = response.session_id
+        self.vnc_url = response.vnc_url
+        self.agent_url = response.agent_url
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Delete session on context exit."""
+        if self.session_id:
+            try:
+                self._client.sessions.delete(self.session_id)
+            except Exception:
+                pass
+
+    def run_task(
+        self,
+        task: str,
+        start_url: str | None = None,
+        timeout: int = 600,
+        poll_interval: float = 3.0,
+    ) -> TaskResult:
+        """Send task and wait for completion using polling.
+
+        This is the primary method matching the docs example.
+        It sends the task message and polls for completion status.
+
+        Args:
+            task: Natural language task description
+            start_url: Optional starting URL for the task
+            timeout: Maximum time to wait in seconds (default: 600)
+            poll_interval: Polling interval in seconds (default: 3.0)
+
+        Returns:
+            TaskResult with data and metadata
+
+        Raises:
+            AgentExecutionError: If task fails or times out
+            ValueError: If session not created
+
+        Example:
+            >>> with client.session("agi-0") as session:
+            ...     result = session.run_task(
+            ...         "Find three nonstop SFO→JFK flights next month under $450"
+            ...     )
+            ...     print(result.data)
+            ...     print(f"Duration: {result.metadata.duration}s")
+        """
+        if not self.session_id:
+            raise ValueError("Session not created. Use context manager 'with' statement.")
+
+        self._client.sessions.send_message(
+            self.session_id,
+            message=task,
+            start_url=start_url,
+        )
+
+        start_time = time.time()
+
+        while True:
+            elapsed = time.time() - start_time
+            if elapsed > timeout:
+                raise AgentExecutionError(
+                    f"Task exceeded timeout of {timeout}s (elapsed: {elapsed:.1f}s)"
+                )
+
+            status_response = self._client.sessions.get_status(self.session_id)
+
+            if status_response.status in ("finished", "waiting_for_input"):
+                messages_response = self._client.sessions.get_messages(self.session_id)
+                messages = messages_response.messages
+
+                # Find DONE or QUESTION message
+                done_msg = None
+                for msg in messages:
+                    if msg.type in ("DONE", "QUESTION"):
+                        done_msg = msg
+                        break
+
+                if not done_msg:
+                    raise AgentExecutionError(
+                        f"Task status '{status_response.status}' but no DONE/QUESTION message found."
+                    )
+
+                # Extract task data
+                content = done_msg.content
+                if isinstance(content, dict):
+                    data = content
+                else:
+                    data = {"content": content} if content else {}
+
+                duration = time.time() - start_time
+                steps = sum(1 for msg in messages if msg.type in ("THOUGHT", "QUESTION", "DONE"))
+
+                metadata = TaskMetadata(
+                    task_id=done_msg.id,
+                    session_id=self.session_id,
+                    duration=duration,
+                    cost=0.0,
+                    timestamp=datetime.now(),
+                    steps=steps,
+                    success=True,
+                )
+
+                return TaskResult(data=data, metadata=metadata)
+
+            if status_response.status == "error":
+                messages_response = self._client.sessions.get_messages(self.session_id)
+
+                error_details = "Unknown error"
+                for msg in messages_response.messages:
+                    if msg.type == "ERROR":
+                        if isinstance(msg.content, str):
+                            error_details = msg.content if msg.content else "Unknown error"
+                        else:
+                            error_details = str(msg.content)
+                        break
+
+                raise AgentExecutionError(f"Task failed: {error_details}")
+
+            time.sleep(poll_interval)
+
+    def pause(self) -> SuccessResponse:
+        """Pause task execution.
+
+        Returns:
+            SuccessResponse confirming pause
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.pause(self.session_id)
+
+    def resume(self) -> SuccessResponse:
+        """Resume paused task.
+
+        Returns:
+            SuccessResponse confirming resume
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.resume(self.session_id)
+
+    def cancel(self) -> SuccessResponse:
+        """Cancel task execution.
+
+        Returns:
+            SuccessResponse confirming cancellation
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.cancel(self.session_id)
+
+    def navigate(self, url: str) -> NavigateResponse:
+        """Navigate browser to URL.
+
+        Args:
+            url: URL to navigate to
+
+        Returns:
+            NavigateResponse with current URL
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.navigate(self.session_id, url)
+
+    def screenshot(self) -> Screenshot:
+        """Get browser screenshot.
+
+        Returns:
+            Screenshot with decoded image data and save() method
+
+        Example:
+            >>> screenshot = session.screenshot()
+            >>> screenshot.save("page.png")
+            >>> print(f"Size: {screenshot.width}x{screenshot.height}")
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+
+        response = self._client.sessions.screenshot(self.session_id)
+        return Screenshot.from_base64(
+            base64_data=response.screenshot, url=response.url, title=response.title
+        )
+
+    def send_message(
+        self,
+        message: str,
+        start_url: str | None = None,
+        config_updates: dict[str, Any] | None = None,
+    ) -> SuccessResponse:
+        """Send message to agent to start a task or respond to questions.
+
+        Args:
+            message: Message content (task instruction or response)
+            start_url: Optional starting URL for the task
+            config_updates: Optional configuration updates
+
+        Returns:
+            SuccessResponse confirming message sent
+
+        Example:
+            >>> with client.session("agi-0") as session:
+            ...     session.send_message("Find flights from SFO to JFK under $450")
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.send_message(
+            self.session_id, message, start_url, config_updates
+        )
+
+    def get_status(self) -> ExecuteStatusResponse:
+        """Get current execution status of the session.
+
+        Returns:
+            ExecuteStatusResponse with status ("running", "finished", etc.)
+
+        Example:
+            >>> with client.session("agi-0") as session:
+            ...     session.send_message("Research topic...")
+            ...     status = session.get_status()
+            ...     print(status.status)
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.get_status(self.session_id)
+
+    def get_messages(self, after_id: int = 0, sanitize: bool = True) -> MessagesResponse:
+        """Get messages from the session.
+
+        Args:
+            after_id: Return messages with ID > after_id (for polling)
+            sanitize: Filter out system messages, prompts, and images
+
+        Returns:
+            MessagesResponse with messages list and status
+
+        Example:
+            >>> with client.session("agi-0") as session:
+            ...     messages = session.get_messages(after_id=0)
+            ...     for msg in messages.messages:
+            ...         print(f"[{msg.type}] {msg.content}")
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        return self._client.sessions.get_messages(self.session_id, after_id, sanitize)
+
+    def stream_events(
+        self,
+        event_types: list[str] | None = None,
+        sanitize: bool = True,
+        include_history: bool = True,
+    ) -> Iterator[SSEEvent]:
+        """Stream real-time events from the session via Server-Sent Events.
+
+        Args:
+            event_types: Filter specific event types (e.g., ["thought", "done"])
+            sanitize: Filter out system messages
+            include_history: Include historical messages on connection
+
+        Yields:
+            SSEEvent objects with id, event type, and data
+
+        Example:
+            >>> with client.session("agi-0") as session:
+            ...     session.send_message("Research company XYZ")
+            ...     for event in session.stream_events():
+            ...         if event.event == "thought":
+            ...             print(f"Agent: {event.data}")
+            ...         elif event.event == "done":
+            ...             print(f"Result: {event.data}")
+            ...             break
+        """
+        if not self.session_id:
+            raise ValueError("Session not created")
+        yield from self._client.sessions.stream_events(
+            self.session_id, event_types, sanitize, include_history
+        )

agi/_sse.py

@@ -0,0 +1,77 @@
+"""Server-Sent Events (SSE) streaming client."""
+
+import json
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+from agi.types.sessions import SSEEvent
+
+if TYPE_CHECKING:
+    from agi._http import HTTPClient
+
+
+class SSEClient:
+    """Client for handling Server-Sent Events streams."""
+
+    def __init__(self, http: "HTTPClient"):
+        """Initialize SSE client.
+
+        Args:
+            http: HTTP client instance
+        """
+        self._http = http
+
+    def stream(self, path: str, params: dict[str, Any] | None = None) -> Iterator[SSEEvent]:
+        """Connect to SSE endpoint and yield events.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Yields:
+            SSEEvent objects
+
+        Example:
+            >>> for event in sse.stream("/v1/sessions/123/events"):
+            ...     if event.event == "done":
+            ...         break
+        """
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+
+        with self._http._client.stream("GET", path, params=clean_params) as response:
+            response.raise_for_status()
+
+            event_id: str | None = None
+            event_type: str | None = None
+            data_lines: list[str] = []
+
+            for line in response.iter_lines():
+                line = line.strip()
+
+                if not line:
+                    if event_type and data_lines:
+                        data_str = "".join(data_lines)
+                        try:
+                            data = json.loads(data_str)
+                        except json.JSONDecodeError:
+                            data = {"content": data_str}
+
+                        yield SSEEvent(
+                            id=event_id,
+                            event=event_type,  # type: ignore
+                            data=data,
+                        )
+
+                        event_id = None
+                        event_type = None
+                        data_lines = []
+                    continue
+
+                if line.startswith("id:"):
+                    event_id = line[3:].strip()
+                elif line.startswith("event:"):
+                    event_type = line[6:].strip()
+                elif line.startswith("data:"):
+                    data_lines.append(line[5:].strip())
+                elif line.startswith(":"):
+                    continue