🔌 References

This section provides comprehensive documentation for the SDK, covering the core Client, configuration options, API services, and all associated data models.

🚀 Client: The Heart of the SDK

The Client class is the primary entry point for all interactions with the WyseOS API. It handles authentication, request dispatching, and response parsing to streamline your integration.

Initialization

To start, initialize the Client with an optional ClientOptions object. If no options are provided, the SDK will use default values.

from wyseos.mate import Client, ClientOptions
from wyseos.mate.config import load_config

# Option 1: Load configuration from mate.yaml (Recommended)
try:
    config = load_config()
    client = Client(config)
    print("✅ Client initialized from mate.yaml.")
except FileNotFoundError:
    print("⚠️ mate.yaml not found. Manually configuring client.")
    # Option 2: Manual configuration
    client = Client(ClientOptions(api_key="YOUR_API_KEY"))

print("Client instance is ready to use.")

Accessible API Services

The Client object provides direct access to various API services as attributes:

• client.user: 👤 Manages user-specific operations like API keys.
• client.team: 👥 Facilitates team management.
• client.agent: 🤖 Handles operations related to agents.
• client.session: 💬 Manages session creation, information, and messages.
• client.browser: 🌐 Provides functionalities for interacting with browser instances.

🔧 ClientOptions: Configuring Your Client

The ClientOptions class allows you to fine-tune the behavior of your Client instance.

🛠️ API Services

Here you'll find detailed references for each service available through the Client.

👤 User Service

Access via client.user. Manages user-related resources, primarily API keys.

Methods

list_api_keys

Retrieves a paginated list of API keys for the current user.

list_api_keys(options: Optional[ListOptions] = None) -> PaginatedResponse[APIKey]

Example:

# List the first 5 API keys
api_keys = client.user.list_api_keys(ListOptions(page_size=5))
for key in api_keys.data:
    print(f"- {key.name} (Last Used: {key.last_used_at})")

Data Models

• APIKey: Represents an API key.

  Attribute	Type	Description
  name	str	The name of the API key.
  api_key	str	The actual API key string.
  created_at	datetime	Timestamp of creation.
  last_used_at	datetime	Timestamp of last use.

👥 Team Service

Access via client.team. Manages teams.

Methods

get_list

Retrieves a paginated list of teams, optionally filtered by type.

get_list(team_type: str = "", options: Optional[ListOptions] = None) -> PaginatedResponse[TeamInfo]

get_info

Retrieves detailed information for a specific team.

get_info(team_id: str) -> TeamInfo

Data Models

• TeamInfo: Represents a team.

  Attribute	Type	Description
  team_id	str	Unique ID of the team.
  user_id	str	ID of the owner user.
  avatar	str	URL to the team's avatar.
  name	str	Name of the team.
  description	str	Description of the team.
  team_type	str	Type of team (e.g., "personal").
  agents	List[AgentInfo]	List of agents in the team.
  model	ModelInfo	The AI model associated with the team.
  parameters	TeamParameters	Configuration parameters for the team.
  created_at	datetime	Timestamp of creation.
  updated_at	datetime	Timestamp of last update.

🤖 Agent Service

Access via client.agent. Manages agents.

Methods

get_list

Retrieves a paginated list of agents, optionally filtered by type.

get_list(agent_type: str = "", options: Optional[ListOptions] = None) -> PaginatedResponse[AgentInfo]

get_info

Retrieves detailed information for a specific agent.

get_info(agent_id: str) -> AgentInfo

Data Models

• AgentInfo: Represents an agent.

  Attribute	Type	Description
  agent_id	str	Unique ID of the agent.
  name	str	Name of the agent.
  description	str	Description of the agent.
  system_message	str	The system prompt for the agent.
  model	ModelInfo	The AI model associated with the agent.
  agent_type	str	Type of agent (e.g., "coder").
  parameters	AgentParameters	Configuration parameters for the agent.
  created_at	datetime	Timestamp of creation.
  updated_at	datetime	Timestamp of last update.

• ModelInfo: Represents an AI model.

  Attribute	Type	Description
  provider	str	The model provider (e.g., "openai").
  model_type	str	The model name (e.g., "gpt-4").

• AgentParameters: Agent configuration.

  Attribute	Type	Description
  temperature	float	Controls the randomness of the output.

💬 Session Service

Access via client.session. Manages sessions and messages.

Methods

create

Creates a new session.

create(request: CreateSessionRequest) -> CreateSessionResponse

get_info

Retrieves detailed information for a specific session.

get_info(session_id: str) -> SessionInfo

get_messages

Retrieves a paginated list of messages from a session.

get_messages(session_id: str, page_num: int = 1, page_size: int = 20, filter: Optional[MessageFilter] = None) -> GetMessagesResponse

update_session_name

Updates the name of a session.

update_session_name(request: UpdateSessionNameRequest) -> None

Data Models

• CreateSessionRequest: Request to create a session.

  Attribute	Type	Description
  team_id	str	The ID of the team to use for the session.
  task	str	The initial task for the session.

• SessionInfo: Represents a session.

  Attribute	Type	Description
  session_id	str	Unique ID of the session.
  status	str	Current status (e.g., "running").
  name	str	The name of the session.
  intent_id	Optional[str]	ID related to the session's goal.
  task	List[UserTaskMessage]	The task(s) for the session.
  messages	List[MessageResponse]	A list of messages within the session.

• MessageResponse: Represents a single message.

  Attribute	Type	Description
  message_id	str	Unique ID of the message.
  source	str	The source of the message (e.g., "agent").
  content	str	The content of the message.
  type	str	The type of message (e.g., "text", "plan").

🌐 Browser Service

Access via client.browser. Manages browser instances.

Methods

get_info

Retrieves detailed information for a specific browser instance.

get_info(browser_id: str) -> BrowserInfo

list_browsers

Retrieves a list of browser instances for a session.

list_browsers(session_id: str, options: Optional[ListOptions] = None) -> ListBrowsersResponse

release_browser

Releases a browser instance.

release_browser(browser_id: str) -> None

list_browser_pages

Retrieves a list of open pages in a browser.

list_browser_pages(browser_id: str, options: Optional[ListOptions] = None) -> ListBrowserPagesResponse

Data Models

• BrowserInfo: Represents a browser instance.

  Attribute	Type	Description
  browser_id	str	Unique ID of the browser.
  session_id	str	ID of the associated session.
  status	str	Current status (e.g., "open").
  width	int	Browser width in pixels.
  height	int	Browser height in pixels.
  pages	List[BrowserPageInfo]	A list of open pages in the browser.

• BrowserPageInfo: Represents a single browser page.

  Attribute	Type	Description
  page_id	str	Unique ID of the page.
  url	str	The current URL of the page.
  status	str	Loading status (e.g., "completed").

🤖 TaskRunner: Simplified Task Execution

New in v0.2.1 - The TaskRunner interface revolutionizes WebSocket operations by reducing complex implementation from 400+ lines to just 10-20 lines of code.

Accessing TaskRunner

TaskRunner is accessed through the WebSocketClient:

from wyseos.mate.websocket import WebSocketClient

ws_client = WebSocketClient(
    base_url=client.base_url,
    api_key=client.api_key,
    session_id=session.session_id
)

task_runner = ws_client.create_task_runner(client, session)

🎯 TaskExecutionOptions

Configuration class for fine-tuning task execution behavior.

Example Usage:

from wyseos.mate.websocket import TaskExecutionOptions

# Performance-optimized configuration
fast_options = TaskExecutionOptions(
    auto_accept_plan=True,
    capture_screenshots=False,    # Faster execution
    completion_timeout=180        # 3-minute timeout
)

# Debug-friendly configuration  
debug_options = TaskExecutionOptions(
    auto_accept_plan=False,       # Manual plan approval
    capture_screenshots=True,     # Visual debugging
    enable_event_logging=True,    # Detailed logs
    completion_timeout=600        # Extended timeout
)

📊 TaskResult

Comprehensive result object returned by TaskRunner operations.

Example Usage:

result = task_runner.run_task("Analyze market trends", "wyse_mate")

if result.success:
    print(f"✅ Task completed in {result.session_duration:.1f}s")
    print(f"📝 Answer: {result.final_answer}")
    print(f"📊 Messages processed: {result.message_count}")
    
    # Access screenshots if captured
    if result.screenshots:
        print(f"📸 {len(result.screenshots)} screenshots captured")
else:
    print(f"❌ Task failed: {result.error}")

🚀 TaskRunner Methods

run_task()

Execute a task with full automation and return comprehensive results.

Signature:

def run_task(
    task: str,
    team_id: str,
    options: Optional[TaskExecutionOptions] = None
) -> TaskResult

Parameters:

Example:

# Simple automated execution
result = task_runner.run_task(
    "Research renewable energy trends",
    "wyse_mate"
)

# Advanced configuration
result = task_runner.run_task(
    "Analyze competitor pricing strategies",
    "analysis_team",
    TaskExecutionOptions(
        auto_accept_plan=True,
        capture_screenshots=True,
        completion_timeout=600
    )
)

run_interactive_session()

Start an interactive session that allows real-time user input and guidance.

Signature:

def run_interactive_session(
    initial_task: str,
    team_id: str,
    options: Optional[TaskExecutionOptions] = None
) -> None

Parameters:

Example:

# Start interactive session
task_runner.run_interactive_session(
    "Help me research market opportunities",
    "research_team",
    TaskExecutionOptions(
        auto_accept_plan=False,  # Manual approval for interactive use
        capture_screenshots=True,
        max_user_input_timeout=300  # 5-minute user input timeout
    )
)

🔌 WebSocketClient Enhancements

New in v0.2.1 - Additional methods for TaskRunner integration.

create_task_runner()

Factory method to create a TaskRunner instance with proper initialization.

Signature:

def create_task_runner(client: Client, session: SessionInfo) -> TaskRunner

Parameters:

Example:

from wyseos.mate.websocket import WebSocketClient

ws_client = WebSocketClient(
    base_url=client.base_url,
    api_key=client.api_key,
    session_id=session.session_id,
    heartbeat_interval=30
)

# Create TaskRunner - replaces 400+ lines of manual WebSocket setup
task_runner = ws_client.create_task_runner(client, session)

🎯 Migration from Legacy WebSocket Code

Before (v0.2.0 and earlier):

# 400+ lines of complex WebSocket message handling
def websocket_operations(client, session, task):
    msg_list = []
    plan_state = None
    
    def on_message(message):
        # Complex message handling logic...
        msg_type = WebSocketClient.get_message_type(message)
        if msg_type == MessageType.TEXT:
            # Handle text messages...
        elif msg_type == MessageType.PLAN:
            # Handle plan messages...
        # ... 350+ more lines
    
    ws_client = WebSocketClient(...)
    ws_client.set_message_handler(on_message)
    # ... more complex setup

After (v0.2.1+):

# Simple 3-line solution
task_runner = ws_client.create_task_runner(client, session)
result = task_runner.run_task(task, team_id)
print(f"Result: {result.final_answer}")

📚 Pagination

These models are used across multiple services.

• ListOptions: Defines pagination parameters.

  Attribute	Type	Description	Default
  page_num	int	The page number to retrieve (1-indexed).	1
  page_size	int	The number of items per page (1-100).	20

• PaginatedResponse[T]: A generic container for paginated API responses.

  Attribute	Type	Description
  page_num	int	The current page number.
  page_size	int	The number of items per page.
  total	int	The total number of items across all pages.
  total_page	int	The total number of pages.
  data	List[T]	A list of items for the current page.