agi-python 0.0.1__py3-none-any.whl

agi/types/results.py

@@ -0,0 +1,183 @@
+"""Result types for task execution."""
+
+from __future__ import annotations
+
+import base64
+from datetime import datetime
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+T = TypeVar("T")
+
+
+class Screenshot(BaseModel):
+    """
+    Browser screenshot with image data and metadata.
+
+    Capture the current browser state as an image. Use session.screenshot()
+    to obtain a screenshot, then save it to disk with the save() method.
+
+    Example:
+        >>> screenshot = session.screenshot()
+        >>> screenshot.save("screenshot.png")
+        >>> print(f"Size: {screenshot.width}x{screenshot.height}")
+        >>> print(f"URL: {screenshot.url}")
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    data: bytes = Field(description="Screenshot image data")
+    format: str = Field(default="png", description="Image format (png, jpg)")
+    timestamp: datetime = Field(description="Screenshot timestamp")
+    width: int = Field(description="Image width in pixels")
+    height: int = Field(description="Image height in pixels")
+    url: str = Field(description="Current page URL")
+    title: str = Field(description="Current page title")
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, value: datetime, _info: Any) -> str:
+        """Serialize datetime to ISO format string."""
+        return value.isoformat()
+
+    @field_serializer("data")
+    def serialize_data(self, value: bytes, _info: Any) -> str:
+        """Serialize bytes to hex string."""
+        return value.hex()
+
+    def save(self, path: str) -> None:
+        """Save screenshot to file.
+
+        Args:
+            path: File path to save to (e.g., "screenshot.png")
+
+        Example:
+            >>> screenshot = session.screenshot()
+            >>> screenshot.save("page.png")
+        """
+        with open(path, "wb") as f:
+            f.write(self.data)
+
+    @classmethod
+    def from_base64(
+        cls, base64_data: str, url: str, title: str, timestamp: datetime | None = None
+    ) -> Screenshot:
+        """Create Screenshot from base64 data URL.
+
+        Args:
+            base64_data: Base64-encoded data URL (e.g., "data:image/jpeg;base64,...")
+            url: Current page URL
+            title: Current page title
+            timestamp: Screenshot timestamp (defaults to now)
+
+        Returns:
+            Screenshot instance with decoded image data
+        """
+        # Parse data URL format: "data:image/jpeg;base64,..."
+        if "," in base64_data:
+            header, encoded = base64_data.split(",", 1)
+        else:
+            # Assume it's just base64 without header
+            encoded = base64_data
+            header = "data:image/png;base64"
+
+        # Decode base64 to bytes
+        image_data = base64.b64decode(encoded)
+
+        # Determine format from header
+        if "jpeg" in header.lower() or "jpg" in header.lower():
+            fmt = "jpg"
+        else:
+            fmt = "png"
+
+        # Extract image dimensions
+        width, height = cls._get_image_dimensions(image_data, fmt)
+
+        return cls(
+            data=image_data,
+            format=fmt,
+            timestamp=timestamp or datetime.now(),
+            width=width,
+            height=height,
+            url=url,
+            title=title,
+        )
+
+    @staticmethod
+    def _get_image_dimensions(data: bytes, fmt: str) -> tuple[int, int]:
+        """Extract width and height from image data.
+
+        Args:
+            data: Raw image bytes
+            fmt: Image format (png, jpg)
+
+        Returns:
+            Tuple of (width, height)
+        """
+        try:
+            if fmt == "png":
+                # PNG: width/height at bytes 16-24
+                if len(data) >= 24:
+                    width = int.from_bytes(data[16:20], byteorder="big")
+                    height = int.from_bytes(data[20:24], byteorder="big")
+                    return width, height
+            elif fmt in ("jpg", "jpeg"):
+                # JPEG: scan for SOF0 marker (0xFFC0)
+                i = 0
+                while i < len(data) - 9:
+                    if data[i] == 0xFF and data[i + 1] == 0xC0:
+                        height = int.from_bytes(data[i + 5 : i + 7], byteorder="big")
+                        width = int.from_bytes(data[i + 7 : i + 9], byteorder="big")
+                        return width, height
+                    i += 1
+        except Exception:
+            pass
+
+        # Fallback if parsing fails
+        return 0, 0
+
+
+class TaskMetadata(BaseModel):
+    """
+    Task execution metadata and performance metrics.
+
+    Contains information about how the task was executed, including duration,
+    number of steps, and success status. Access via result.metadata.
+
+    Example:
+        >>> result = session.run_task("Find hotels in Paris")
+        >>> print(f"Duration: {result.metadata.duration}s")
+        >>> print(f"Steps taken: {result.metadata.steps}")
+        >>> print(f"Success: {result.metadata.success}")
+    """
+
+    task_id: str | int = Field(description="Unique task identifier")
+    session_id: str | None = Field(default=None, description="Session ID if applicable")
+    duration: float = Field(description="Execution time in seconds")
+    cost: float = Field(default=0.0, description="Task cost in USD (not yet provided by API)")
+    timestamp: datetime = Field(description="Task completion timestamp")
+    steps: int = Field(description="Number of steps executed")
+    success: bool = Field(description="Whether task succeeded")
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, value: datetime, _info: Any) -> str:
+        """Serialize datetime to ISO format string."""
+        return value.isoformat()
+
+
+class TaskResult(BaseModel, Generic[T]):
+    """
+    Result of task execution.
+
+    The data field contains the task output, typically as a dictionary.
+    Metadata provides execution information like duration and steps.
+
+    Example:
+        >>> result = session.run_task("Compare flight prices from NYC to London")
+        >>> print(result.data)  # Dict with flight comparison data
+        >>> print(f"Duration: {result.metadata.duration}s")
+        >>> print(f"Steps: {result.metadata.steps}")
+    """
+
+    data: T = Field(description="Task output data")
+    metadata: TaskMetadata = Field(description="Execution metadata")

agi/types/sessions.py

@@ -0,0 +1,119 @@
+"""Session-related type definitions."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from agi.types.shared import EventType, MessageType, SessionStatus
+
+# Request Models
+
+
+class CreateSessionRequest(BaseModel):
+    """Request to create a new session."""
+
+    agent_name: str = Field(default="agi-0", description="Agent model to use")
+    webhook_url: str | None = Field(
+        default=None, description="Webhook URL for session event notifications"
+    )
+    goal: str | None = Field(default=None, description="Task goal (optional, can be set later)")
+    max_steps: int = Field(default=100, description="Maximum number of agent steps")
+    restore_from_environment_id: str | None = Field(
+        default=None, description="Environment UUID to restore from"
+    )
+
+
+class SendMessageRequest(BaseModel):
+    """Request to send a message to the agent."""
+
+    message: str = Field(..., description="Message content")
+    start_url: str | None = Field(default=None, description="Optional starting URL")
+    config_updates: dict[str, Any] | None = Field(
+        default=None, description="Optional configuration updates"
+    )
+
+
+class NavigateRequest(BaseModel):
+    """Request to navigate browser to a URL."""
+
+    url: str = Field(..., description="URL to navigate to")
+
+
+# Response Models
+
+
+class SessionResponse(BaseModel):
+    """Response containing session information."""
+
+    session_id: str = Field(..., description="Session UUID")
+    vnc_url: str | None = Field(None, description="VNC URL for browser access")
+    agent_url: str | None = Field(None, description="Agent service URL (desktop mode)")
+    agent_name: str = Field(..., description="Agent name")
+    status: str = Field(..., description="Session status")
+    created_at: datetime = Field(..., description="Session creation timestamp")
+    environment_id: str | None = Field(None, description="Environment UUID for restore")
+    goal: str | None = Field(None, description="Task goal")
+
+
+class ExecuteStatusResponse(BaseModel):
+    """Response containing task execution status."""
+
+    status: SessionStatus = Field(..., description="Current execution status")
+
+
+class MessageResponse(BaseModel):
+    """Single message from agent."""
+
+    id: int = Field(..., description="Message ID")
+    type: MessageType = Field(..., description="Message type")
+    content: str | dict[str, Any] | list[dict[str, Any]] = Field(..., description="Message content")
+    timestamp: str = Field(..., description="ISO timestamp")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class MessagesResponse(BaseModel):
+    """Response containing message stream and status."""
+
+    messages: list[MessageResponse] = Field(default_factory=list, description="List of messages")
+    status: str = Field(..., description="Current execution status")
+    has_agent: bool = Field(True, description="Whether agent is connected")
+
+
+class SSEEvent(BaseModel):
+    """Server-Sent Event from real-time stream."""
+
+    id: str | None = Field(None, description="Event ID")
+    event: EventType = Field(..., description="Event type")
+    data: dict[str, Any] = Field(..., description="Event data")
+
+
+class NavigateResponse(BaseModel):
+    """Response from navigation request."""
+
+    current_url: str = Field(..., description="Current URL after navigation")
+
+
+class ScreenshotResponse(BaseModel):
+    """Response containing screenshot data."""
+
+    screenshot: str = Field(..., description="Base64-encoded JPEG data URL")
+    url: str = Field(..., description="Current page URL")
+    title: str = Field(..., description="Current page title")
+
+
+class SuccessResponse(BaseModel):
+    """Generic success response."""
+
+    success: bool = Field(True, description="Operation success")
+    message: str = Field(..., description="Success message")
+
+
+class DeleteResponse(BaseModel):
+    """Response from delete operation."""
+
+    success: bool = Field(True, description="Operation success")
+    deleted: bool = Field(True, description="Whether resource was deleted")
+    message: str = Field(..., description="Response message")

agi/types/shared.py

@@ -0,0 +1,26 @@
+"""Shared type definitions."""
+
+from typing import Literal
+
+# Session status types
+SessionStatus = Literal["ready", "running", "waiting_for_input", "paused", "finished", "error"]
+
+# Message types
+MessageType = Literal["THOUGHT", "QUESTION", "USER", "DONE", "ERROR", "LOG"]
+
+# SSE Event types
+EventType = Literal[
+    "step",
+    "thought",
+    "question",
+    "done",
+    "error",
+    "log",
+    "paused",
+    "resumed",
+    "heartbeat",
+    "user",  # User message events
+]
+
+# Snapshot mode types
+SnapshotMode = Literal["none", "memory", "filesystem"]

agi_python-0.0.1.dist-info/METADATA

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: agi-python
+Version: 0.0.1
+Summary: Official Python SDK for AGI.tech API
+Author-email: AGI Inc <kaushik@theagi.company>
+Maintainer-email: AGI Inc <kaushik@theagi.company>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/agi-inc/agi-python
+Project-URL: Documentation, https://docs.agi.tech
+Project-URL: Repository, https://github.com/agi-inc/agi-python
+Project-URL: Issues, https://github.com/agi-inc/agi-python/issues
+Project-URL: Changelog, https://github.com/agi-inc/agi-python/releases
+Keywords: agi,automation,browser,ai,agent,api,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://cdn.prod.website-files.com/67be56277f6d514dcad939e2/67e48dd1cdab04c17a311669_logo-agi-white.png" alt="AGI" width="120"/>
+
+<h1>AGI Python SDK</h1>
+
+<p>
+  <a href="https://www.theagi.company/">Website</a> •
+  <a href="https://docs.agi.tech">Documentation</a> •
+  <a href="https://platform.agi.tech">Platform</a> •
+  <a href="https://theagi.company/blog">Blog</a>
+</p>
+
+---
+
+**AI agent that actually works on the web.**
+
+<br />
+
+</div>
+
+```python
+from agi import AGIClient
+
+client = AGIClient()
+
+with client.session("agi-0") as session:
+    result = session.run_task(
+        "Find three nonstop flights from SFO to JFK next month under $450. "
+        "Return flight times, airlines, and booking links."
+    )
+    print(result)
+```
+
+<br />
+
+> Powered by [AGI.tech](https://agi.tech) - the world's most capable computer agent. Trusted by [Visa](https://www.theagi.company/blog/agi-inc-visa) for agentic commerce. Evaluated with [REAL Bench](https://www.theagi.company/blog/introducing-real-bench).
+
+<br />
+
+## Installation
+
+```bash
+pip install agi-python
+```
+
+Get your API key at [platform.agi.tech](https://platform.agi.tech/api-keys)
+
+```bash
+export AGI_API_KEY="your-api-key"
+```
+
+## Quick Start
+
+### Simple Task
+
+```python
+from agi import AGIClient
+
+client = AGIClient()
+
+with client.session("agi-0") as session:
+    result = session.run_task("Find the cheapest iPhone 15 on Amazon")
+    print(result)
+```
+
+### Real-Time Event Streaming
+
+```python
+with client.session("agi-0") as session:
+    session.send_message("Research the top 5 AI companies in 2025")
+
+    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
+```
+
+### Session Control
+
+```python
+with client.session("agi-0") as session:
+    session.send_message("Long research task...")
+
+    # Control execution
+    session.pause()    # Pause the agent
+    session.resume()   # Resume later
+    session.cancel()   # Or cancel
+```
+
+---
+
+## Core Concepts
+
+*Understanding the building blocks of agi*
+
+### Sessions: The Container for Tasks
+
+Every task runs inside a **session** - an isolated browser environment:
+
+```python
+# Context manager (recommended) - automatic cleanup
+with client.session("agi-0") as session:
+    session.run_task("Find flights...")
+
+# Manual management - full control
+session = client.sessions.create(agent_name="agi-0")
+client.sessions.send_message(session.session_id, "task")
+client.sessions.delete(session.session_id)
+```
+
+▸ Use context managers for most tasks. Use manual management when you need fine-grained control.
+
+### Available Agents
+
+- **agi-0** - General purpose agent (recommended)
+- **agi-0-fast** - Faster agent for simple tasks
+- **agi-1** - Advanced agent with enhanced capabilities
+
+See [docs.agi.tech](https://docs.agi.tech) for the full list.
+
+---
+
+## Features
+
+- **Natural Language** - Describe tasks in plain English, no selectors or scraping code
+- **Real-Time Streaming** - Watch agent execution live with Server-Sent Events
+- **Session Control** - Pause, resume, or cancel long-running tasks
+- **Browser Control** - Navigate and screenshot for visual debugging
+- **Type-Safe** - Full type hints with Pydantic validation
+- **Production-Ready** - Built-in retries, automatic cleanup, comprehensive error handling
+
+---
+
+## Common Use Cases
+
+### Price Monitoring
+
+Monitor product prices and availability across retailers.
+
+```python
+with client.session("agi-0") as session:
+    result = session.run_task(
+        "Go to amazon.com and search for 'Sony WH-1000XM5'. "
+        "Get the current price, check if it's in stock, and return the product rating. "
+        "Return as JSON with fields: price, in_stock, rating, url."
+    )
+```
+
+### Lead Generation
+
+Extract structured data from public sources.
+
+```python
+with client.session("agi-0") as session:
+    result = session.run_task(
+        "Go to ycombinator.com/companies, find companies in the 'AI' category "
+        "from the latest batch. For the first 10 companies, get their name, "
+        "description, and website. Return as a JSON array."
+    )
+```
+
+### Flight Booking Research
+
+```python
+with client.session("agi-0") as session:
+    result = session.run_task(
+        "Find three nonstop SFO→JFK flights next month under $450. "
+        "Compare prices on Google Flights, Kayak, and Expedia. "
+        "Return flight details and booking links."
+    )
+```
+
+<details>
+<summary><b>Browser Control</b> – Navigate and take screenshots for visual debugging</summary>
+
+<br />
+
+```python
+with client.session("agi-0") as session:
+    # Navigate to specific URL
+    session.navigate("https://amazon.com")
+
+    # Get screenshot for debugging
+    screenshot = session.screenshot()
+    print(screenshot.url)    # Current page URL
+    print(screenshot.title)  # Page title
+    # screenshot.screenshot contains base64 JPEG data
+```
+
+</details>
+
+<details>
+<summary><b>Session Snapshots</b> – Preserve authentication and browser state</summary>
+
+<br />
+
+```python
+# Create session and save environment
+session1 = client.sessions.create(agent_name="agi-0")
+# ... do some work ...
+client.sessions.delete(session1.session_id, save_snapshot_mode="filesystem")
+
+# Later, restore from saved environment
+session2 = client.sessions.create(
+    agent_name="agi-0",
+    restore_from_environment_id=session1.environment_id
+)
+# Authentication state and cookies preserved!
+```
+
+</details>
+
+<details>
+<summary><b>Advanced Session Management</b> – Full control over session lifecycle</summary>
+
+<br />
+
+```python
+# Create session manually
+session = client.sessions.create(
+    agent_name="agi-0-fast",
+    webhook_url="https://yourapp.com/webhook",
+    max_steps=200
+)
+
+# Send message
+client.sessions.send_message(
+    session.session_id,
+    "Find flights from SFO to JFK under $450"
+)
+
+# Check status
+status = client.sessions.get_status(session.session_id)
+print(status.status)  # "running", "finished", etc.
+
+# List all sessions
+sessions = client.sessions.list()
+
+# Delete when done
+client.sessions.delete(session.session_id)
+```
+
+</details>
+
+<details>
+<summary><b>Webhooks</b> – Get notified when tasks complete</summary>
+
+<br />
+
+```python
+session = client.sessions.create(
+    agent_name="agi-0",
+    webhook_url="https://yourapp.com/webhook"
+)
+
+# Your webhook will receive events:
+# POST https://yourapp.com/webhook
+# {
+#   "event": "done",
+#   "session_id": "sess_...",
+#   "data": {...}
+# }
+```
+
+</details>
+
+---
+
+## Error Handling
+
+<details>
+<summary><b>Robust error handling with detailed debugging</b></summary>
+
+<br />
+
+```python
+from agi import (
+    AGIClient,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    AgentExecutionError
+)
+
+client = AGIClient()
+
+try:
+    with client.session("agi-0") as session:
+        result = session.run_task("Find flights...")
+except AuthenticationError:
+    print("Invalid API key")
+except NotFoundError:
+    print("Session not found")
+except RateLimitError:
+    print("Rate limit exceeded - please retry")
+except AgentExecutionError as e:
+    print(f"Task failed: {e}")
+    # Debug at VNC URL if available
+except AGIError as e:
+    print(f"API error: {e}")
+```
+
+</details>
+
+---
+
+## Documentation & Resources
+
+**Learn More**
+- [API Reference](https://docs.agi.tech) – Complete API documentation
+- [Code Examples](./examples) – Working examples for common tasks
+- [GitHub Issues](https://github.com/agi-inc/agi-python/issues) – Report bugs or request features
+
+**Get Help**
+- [Platform](https://platform.agi.tech) – Manage API keys and monitor usage
+- [Documentation](https://docs.agi.tech) – Guides and tutorials
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.