Python SDK

API Reference

Python SDK API Reference

This section provides comprehensive, detailed documentation for the Wyse Mate Python SDK. It covers the core Client class, its initialization process, and the various API services designed for seamless interaction with the Wyse Mate platform, along with all associated data models.

The Client Class: Your Gateway to the API

The Client class serves as the primary entry point for all API interactions. It intelligently manages authentication, dispatches HTTP requests, and parses responses, streamlining your integration efforts.

from wyse_mate import Client, ClientOptions

class Client:
    def __init__(self, options: Optional[ClientOptions] = None):
        # ... initialization logic ...

Client Initialization

To begin using the SDK, initialize the Client with an optional ClientOptions object. If no options are explicitly provided, the client will fall back to sensible default values.

ParameterTypeDescriptionDefault Value
optionsOptional[ClientOptions]An instance of ClientOptions to configure the client's behavior. For details, see the ClientOptions section below.None (uses SDK defaults)

Example: Initializing the Client

from wyse_mate import Client, ClientOptions
from wyse_mate.config import load_default_config

# Option 1: Load configuration from mate.yaml (Recommended for production)
config = load_default_config()
if config:
    client = Client(config)
    print("Client successfully initialized from mate.yaml.")
else:
    print("Warning: mate.yaml not found. Falling back to manual configuration.")
    # Option 2: Manual configuration (Replace "YOUR_API_KEY" with your actual key)
    client = Client(ClientOptions(
        api_key="YOUR_API_KEY",
        base_url="https://api.mate.wyseos.com",
        timeout=30,
        debug=False
    ))

print("Client instance ready.")

Accessible API Services

The Client object provides direct access to various API services as dedicated attributes. Each service encapsulates methods for interacting with a specific domain of the Wyse Mate API, promoting a clear and organized code structure.

  • client.user: Manages user-specific operations, such as API key management.
  • client.team: Facilitates team management, including listing, creating, and updating teams.
  • client.agent: Handles operations related to agents, such as retrieving agent lists and details.
  • client.session: Manages sessions, covering creation, retrieval of session information and messages.
  • client.browser: Provides functionalities for interacting with browser instances and their pages.

For in-depth information and usage examples for each service, refer to their dedicated sections:

Internal HTTP Request Methods

The Client class incorporates internal methods for handling the underlying HTTP communication. While you'll primarily interact with the higher-level service methods, understanding these internal functions can be beneficial for advanced use cases or debugging.

  • _do_request(method: str, endpoint: str, body: Optional[Dict] = None) -> requests.Response: This core internal method executes the actual HTTP request to the Wyse Mate API. It constructs the full request URL, sets necessary headers (including your API key), and manages potential network and API-specific errors.

  • get(endpoint: str, result_model: Type[T], params: Optional[Dict[str, str]] = None) -> T: Performs an HTTP GET request. The JSON response from the API is automatically deserialized into the specified Pydantic result_model.

  • get_paginated(endpoint: str, result_model: Type[T], params: Optional[Dict[str, str]] = None) -> T: A specialized GET request method designed for API endpoints that return paginated responses. It correctly extracts and deserializes the data from nested response structures.

  • post(endpoint: str, body: Optional[Dict] = None, result_model: Optional[Type[T]] = None) -> Optional[T]: Executes an HTTP POST request. You can provide an optional request body, and the method will deserialize the API's JSON response into the result_model if provided.

  • put(endpoint: str, body: Optional[Dict] = None, result_model: Optional[Type[T]] = None) -> Optional[T]: Performs an HTTP PUT request, similar to post, allowing for an optional request body and response deserialization into a result_model.

  • delete(endpoint: str) -> None: Executes an HTTP DELETE request. This method does not expect a response body.

ClientOptions Class: Customizing Client Behavior

The ClientOptions class allows you to fine-tune the behavior of your Client instance. This includes setting your API key, custom base URLs, timeouts, and more.

from wyse_mate.config import ClientOptions
from pydantic import BaseModel, Field
from typing import Optional, Any

class ClientOptions(BaseModel):
    api_key: str = Field(..., description="Your Wyse Mate API key.")
    base_url: Optional[str] = Field(None, description="The base URL for the Wyse Mate API.")
    timeout: Optional[int] = Field(None, description="Timeout for API requests in seconds.")
    user_agent: Optional[str] = Field(None, description="Custom User-Agent header for requests.")
    http_client: Any = Field(None, description="An optional custom HTTP client (e.g., requests.Session). For advanced use cases only.")
AttributeTypeDescriptionDefault Value
api_keystrYour Wyse Mate API key. This attribute is required.(None)
base_urlOptional[str]The base URL for the Wyse Mate API. Customize this for self-hosted instances or alternative environments.https://api.mate.wyseos.com
timeoutOptional[int]The maximum duration (in seconds) for API requests before timing out.30
user_agentOptional[str]A custom User-Agent string to include in HTTP request headers.wyse-mate-sdk-python/<version>
http_clientAnyAn optional custom HTTP client instance (e.g., a requests.Session object). This is for advanced use cases where fine-grained control over the HTTP client is needed.requests.Session()

Service-Specific API References

For detailed information on the methods and data models within each service, please refer to the following sections:

User Service API Reference

The UserService provides methods for managing user-specific resources, primarily focusing on API keys. You can access it via client.user.

from wyse_mate.services.user import UserService

class UserService:
    def __init__(self, client: "Client"):
        # ... initialization logic ...

Methods

list_api_keys

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

Retrieves a paginated list of API keys associated with the current user.

ParameterTypeDescriptionDefault Value
optionsOptional[ListOptions]Optional pagination options to control the number of results and current page.None (uses default page_num=1, page_size=10)

Returns:

PaginatedResponse[APIKey]: A paginated response object containing a list of APIKey objects.

Example:

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import ListOptions

client = Client(load_default_config()) # or initialize manually

# List all API keys (default pagination)
api_keys_response = client.user.list_api_keys()
print(f"Total API Keys: {api_keys_response.total}")
for key in api_keys_response.data:
    print(f"- {key.name} (ID: {key.id}, Last Used: {key.last_used_at})")

# List API keys with custom pagination
paginated_keys_response = client.user.list_api_keys(ListOptions(page_num=2, page_size=5))
print(f"API Keys on page 2 (size 5): {paginated_keys_response.total}")
for key in paginated_keys_response.data:
    print(f"- {key.name}")

Data Models

The following Pydantic models are used within the SDK to represent data structures for requests and responses.

APIKey

Represents information about an API key, including its unique identifier, name, creation timestamp, and last usage time.

from pydantic import BaseModel, Field
from datetime import datetime

class APIKey(BaseModel):
    id: int = Field(alias="id", description="The unique ID of the API key.")
    name: str = Field(description="The name given to the API key.")
    api_key: str = Field(alias="api_key", description="The actual API key string.")
    created_at: datetime = Field(alias="created_at", description="Timestamp when the API key was created.")
    last_used_at: datetime = Field(alias="last_used_at", description="Timestamp when the API key was last used.")
AttributeTypeDescription
idintThe unique ID of the API key.
namestrThe name given to the API key.
api_keystrThe actual API key string.
created_atdatetimeTimestamp when the API key was created.
last_used_atdatetimeTimestamp when the API key was last used.

ListOptions

This model defines parameters for controlling pagination in list operations, allowing you to specify the desired page number and size.

from pydantic import BaseModel, Field

class ListOptions(BaseModel):
    page_num: int = Field(default=1, ge=1, description="The page number to retrieve (1-indexed). Minimum value is 1.")
    page_size: int = Field(default=20, ge=1, le=100, description="The number of items per page. Minimum value is 1, maximum is 100.")
AttributeTypeDescriptionDefault Value
page_numintThe page number to retrieve (1-indexed).1
page_sizeintThe number of items per page (1-100).20

PaginatedResponse

A generic Pydantic model designed to encapsulate paginated API responses. It provides metadata about the pagination (page numbers, total counts) and the actual list of data items.

from pydantic import BaseModel, Field
from typing import List, Generic, TypeVar

T = TypeVar("T")

class PaginatedResponse(BaseModel, Generic[T]):
    page_num: int = Field(description="The current page number returned.")
    page_size: int = Field(description="The number of items per page.")
    total: int = Field(description="The total number of items available across all pages.")
    total_page: int = Field(description="The total number of pages available.")
    data: List[T] = Field(description="A list of items for the current page. The type `T` varies based on the specific API endpoint (e.g., `APIKey`, `TeamInfo`).")
AttributeTypeDescription
page_numintThe current page number.
page_sizeintThe number of items per page.
totalintThe total number of items available across all pages.
total_pageintThe total number of pages.
dataList[T]A list of items for the current page, where T is the type of the items (e.g., APIKey).

Team Service API Reference

The TeamService provides methods for managing teams within the Wyse Mate platform. Access this service via client.team.

from wyse_mate.services.team import TeamService

class TeamService:
    def __init__(self, client: "Client"):
        # ... initialization logic ...

Methods

get_list

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

Retrieves a paginated list of teams. You can optionally filter teams by their type.

ParameterTypeDescriptionDefault Value
team_typestrAn optional string to filter teams by their type (e.g., "personal", "shared"). Leave empty to retrieve all team types."all"
optionsOptional[ListOptions]Optional pagination settings (page_num, page_size).None (uses default page_num=1, page_size=10)

Returns:

PaginatedResponse[TeamInfo]: A paginated response object containing a list of TeamInfo objects.

Example: Listing Teams

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import ListOptions

client = Client(load_default_config()) # or initialize manually

# Retrieve all teams with default pagination
teams_response = client.team.get_list()
print(f"Total Teams: {teams_response.total}")
for team in teams_response.data:
    print(f"- {team.name} (ID: {team.team_id}, Type: {team.team_type})")

# Retrieve personal teams, with a custom page size of 5
personal_teams = client.team.get_list(team_type="personal", options=ListOptions(page_size=5))
print(f"Personal Teams (first 5): {len(personal_teams.data)}")
for team in personal_teams.data:
    print(f"- {team.name}")

get_info

get_info(team_id: str) -> TeamInfo

Retrieves detailed information for a specific team, identified by its unique ID.

ParameterTypeDescription
team_idstrThe unique identifier of the team whose details are to be retrieved.

Returns:

TeamInfo: An object containing comprehensive details about the specified team.

Example: Getting Team Information

from wyse_mate import Client
from wyse_mate.config import load_default_config

client = Client(load_default_config()) # or initialize manually

team_id_to_fetch = "your-team-id-here" # Replace with an actual team ID
try:
    team_details = client.team.get_info(team_id_to_fetch)
    print(f"Team Name: {team_details.name}")
    print(f"Team Description: {team_details.description}")
    print(f"Team Type: {team_details.team_type}")
    print(f"Number of Agents in Team: {len(team_details.agents)}")
except Exception as e:
    print(f"Error fetching team info: {e}")

TeamInfo Data Model

Represents comprehensive information about a team within the Wyse Mate platform.

from pydantic import BaseModel, Field
from datetime import datetime
from typing import List, Optional

class TeamInfo(BaseModel):
    team_id: str = Field(alias="team_id", description="Unique identifier of the team.")
    user_id: str = Field(alias="user_id", description="The ID of the user who owns or created the team.")
    avatar: str = Field(description="URL to the team's avatar image.")
    name: str = Field(description="The name of the team.")
    description: str = Field(description="A brief description of the team.")
    component_type: str = Field(alias="component_type", description="The type of component, typically 'team'.")
    team_type: str = Field(alias="team_type", description="The type of the team (e.g., 'personal', 'shared').")
    agents: List[AgentInfo] = Field(default_factory=list, description="A list of `AgentInfo` objects representing agents belonging to this team.") # Assuming AgentInfo is defined elsewhere
    termination: str = Field(description="The termination condition or type for the team.")
    model: ModelInfo = Field(description="Information about the AI model associated with the team.") # Assuming ModelInfo is defined elsewhere
    parameters: TeamParameters = Field(description="Configuration parameters specific to the team.") # Assuming TeamParameters is defined elsewhere
    created_at: datetime = Field(alias="created_at", description="Timestamp when the team was created.")
    updated_at: datetime = Field(alias="updated_at", description="Timestamp when the team was last updated.")
    deleted_at: int = Field(alias="deleted_at", description="Unix timestamp indicating when the team was deleted (0 if not deleted).")
AttributeTypeDescription
team_idstrUnique ID of the team.
user_idstrID of the user who owns or created the team.
avatarstrURL to the team's avatar image.
namestrName of the team.
descriptionstrDescription of the team.
component_typestrType of component (e.g., "team").
team_typestrType of the team (e.g., "personal", "shared").
agentsList[AgentInfo]A list of agents belonging to this team.
terminationstrTermination condition or type for the team.
modelModelInfoInformation about the AI model associated with the team.
parametersTeamParametersConfiguration parameters specific to the team.
created_atdatetimeTimestamp when the team was created.
updated_atdatetimeTimestamp when the team was last updated.
deleted_atintUnix timestamp when the team was deleted (0 if not deleted).

Agent Service API Reference

The AgentService provides methods for managing agents within the Wyse Mate platform. Access this service via client.agent.

from wyse_mate.services.agent import AgentService

class AgentService:
    def __init__(self, client: "Client"):
        # ... initialization logic ...

Methods

get_list

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

Retrieves a paginated list of agents. You can optionally filter agents by their type.

ParameterTypeDescriptionDefault Value
agent_typestrAn optional string to filter agents by their type (e.g., "coder", "designer"). Leave empty to retrieve all agent types."all"
optionsOptional[ListOptions]Optional pagination settings (page_num, page_size).None (uses default page_num=1, page_size=10)

Returns:

PaginatedResponse[AgentInfo]: A paginated response object containing a list of AgentInfo objects.

Example: Listing Agents

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import ListOptions

client = Client(load_default_config()) # or initialize manually

# Retrieve all agents with default pagination
agents_response = client.agent.get_list()
print(f"Total Agents: {agents_response.total}")
for agent in agents_response.data:
    print(f"- {agent.name} (ID: {agent.agent_id}, Type: {agent.agent_type})")

# Retrieve 'coder' agents, with a custom page size of 5
coder_agents = client.agent.get_list(agent_type="coder", options=ListOptions(page_size=5))
print(f"Coder Agents (first 5): {len(coder_agents.data)}")
for agent in coder_agents.data:
    print(f"- {agent.name}")

get_info

get_info(agent_id: str) -> AgentInfo

Retrieves detailed information for a specific agent, identified by its unique ID.

ParameterTypeDescription
agent_idstrThe unique identifier of the agent whose information is to be retrieved.

Returns:

AgentInfo: An object containing comprehensive details about the specified agent.

Example: Getting Agent Information

from wyse_mate import Client
from wyse_mate.config import load_default_config

client = Client(load_default_config()) # or initialize manually

agent_id_to_fetch = "your-agent-id-here" # Replace with an actual agent ID
try:
    agent_details = client.agent.get_info(agent_id_to_fetch)
    print(f"Agent Name: {agent_details.name}")
    print(f"Agent Description: {agent_details.description}")
    print(f"Agent Type: {agent_details.agent_type}")
    print(f"Associated Model: {agent_details.model.provider}/{agent_details.model.model_type}")
except Exception as e:
    print(f"Error fetching agent info: {e}")

AgentInfo Data Model

Represents comprehensive information about an agent within the Wyse Mate platform.

from pydantic import BaseModel, Field
from datetime import datetime

class AgentInfo(BaseModel):
    agent_id: str = Field(alias="agent_id", description="Unique identifier of the agent.")
    user_id: str = Field(alias="user_id", description="The ID of the user who owns or created the agent.")
    avatar: str = Field(description="URL to the agent's avatar image.")
    name: str = Field(description="The name of the agent.")
    description: str = Field(description="A brief description of the agent.")
    system_message: str = Field(alias="system_message", description="The system prompt message for the agent.")
    component_type: str = Field(alias="component_type", description="The type of component, typically 'agent'.")
    model: ModelInfo = Field(description="Information about the AI model associated with the agent.")
    agent_type: str = Field(alias="agent_type", description="The type of the agent (e.g., 'coder', 'designer').")
    parameters: AgentParameters = Field(description="Configuration parameters specific to the agent.")
    created_at: datetime = Field(alias="created_at", description="Timestamp when the agent was created.")
    updated_at: datetime = Field(alias="updated_at", description="Timestamp when the agent was last updated.")
AttributeTypeDescription
agent_idstrUnique ID of the agent.
user_idstrID of the user who owns or created the agent.
avatarstrURL to the agent's avatar image.
namestrName of the agent.
descriptionstrDescription of the agent.
system_messagestrThe system prompt message for the agent.
component_typestrType of component (e.g., "agent").
modelModelInfoInformation about the AI model associated with the agent.
agent_typestrType of the agent (e.g., "coder", "designer").
parametersAgentParametersConfiguration parameters specific to the agent.
created_atdatetimeTimestamp when the agent was created.
updated_atdatetimeTimestamp when the agent was last updated.

ModelInfo Data Model

Provides essential information about an AI model used by agents or teams, including its provider, type, and timestamps.

from pydantic import BaseModel, Field

class ModelInfo(BaseModel):
    system_model_id: str = Field(alias="system_model_id", description="The system-wide unique ID for the model.")
    provider: str = Field(description="The provider of the AI model (e.g., 'openai', 'google').")
    model_type: str = Field(alias="model_type", description="The type or name of the model (e.g., 'gpt-4', 'gemini-pro').")
    icon_url: str = Field(alias="icon_url", description="URL to the model's icon image.")
    created_at: str = Field(alias="created_at", description="Timestamp when the model information was created.")
    updated_at: str = Field(alias="updated_at", description="Timestamp when the model information was last updated.")
AttributeTypeDescription
system_model_idstrThe system-wide unique ID for the model.
providerstrThe provider of the AI model (e.g., "openai", "google").
model_typestrThe type or name of the model (e.g., "gpt-4", "gemini-pro").
icon_urlstrURL to the model's icon.
created_atstrTimestamp when the model information was created.
updated_atstrTimestamp when the model information was last updated.

AgentParameters Data Model

Defines the configurable parameters that influence an agent's behavior and output.

from pydantic import BaseModel, Field

class AgentParameters(BaseModel):
    system_prompt_role: str = Field(alias="system_prompt_role", description="The role aspect of the system prompt, guiding the agent's persona.")
    system_prompt_task_skill: str = Field(alias="system_prompt_task_skill", description="The task skill aspect of the system prompt, defining the agent's area of expertise.")
    temperature: float = Field(alias="temperature", description="Controls the randomness and creativity of the agent's output. Higher values result in more diverse and unpredictable responses.")
AttributeTypeDescription
system_prompt_rolestrThe role aspect of the system prompt.
system_prompt_task_skillstrThe task skill aspect of the system prompt.
temperaturefloatControls the randomness of the agent's output. Higher values mean more random output.

Session Service API Reference

The SessionService manages interactions related to sessions, including their creation, retrieval of detailed information, and management of messages within them. Access this service via client.session.

from wyse_mate.services.session import SessionService

class SessionService:
    def __init__(self, client: "Client"):
        # ... initialization logic ...

Methods

create

create(request: CreateSessionRequest) -> CreateSessionResponse

Initiates and creates a new session on the Wyse Mate platform.

ParameterTypeDescription
requestCreateSessionRequestThe request body containing details for creating the session.

Returns:

CreateSessionResponse: An object encapsulating the unique ID of the newly created session.

Example: Creating a New Session

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import CreateSessionRequest

client = Client(load_default_config()) # or initialize manually

try:
    # Replace 'your-team-id' with an actual team ID from your Wyse Mate account
    create_session_req = CreateSessionRequest(
        team_id="your-team-id",
        task="Describe the current weather in London."
    )
    session_response = client.session.create(create_session_req)
    print(f"New Session Created with ID: {session_response.session_id}")
except Exception as e:
    print(f"Error creating session: {e}")

get_info

get_info(session_id: str) -> SessionInfo

Retrieves comprehensive details about a specific session using its unique ID.

ParameterTypeDescription
session_idstrThe unique identifier of the session to retrieve information for.

Returns:

SessionInfo: An object containing detailed information about the specified session.

Example: Getting Session Information

from wyse_mate import Client
from wyse_mate.config import load_default_config

client = Client(load_default_config()) # or initialize manually

session_id_to_fetch = "your-session-id-here" # Replace with an actual session ID
try:
    session_details = client.session.get_info(session_id_to_fetch)
    print(f"Session Name: {session_details.name}")
    print(f"Session Status: {session_details.status}")
    print(f"Session Duration: {session_details.duration} seconds")
except Exception as e:
    print(f"Error fetching session info: {e}")

get_messages

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

Retrieves a paginated list of messages from a specific session. You can apply optional filters to narrow down the results.

ParameterTypeDescriptionDefault Value
session_idstrThe unique ID of the session from which to retrieve messages.
page_numintThe page number to retrieve (1-indexed).1
page_sizeintThe number of messages to return per page.20
filterOptional[MessageFilter]An optional MessageFilter object to apply specific criteria (e.g., by role, content, or timestamp range).None

Returns:

GetMessagesResponse: An object containing a paginated list of MessageResponse objects, along with pagination metadata.

Example: Retrieving Session Messages

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import MessageFilter

client = Client(load_default_config()) # or initialize manually

session_id_to_fetch = "your-session-id-here" # Replace with an actual session ID
try:
    # Retrieve all messages for a session (using default pagination)
    messages_response = client.session.get_messages(session_id_to_fetch)
    print(f"Total Messages in session: {messages_response.total_count}")
    for message in messages_response.messages:
        print(f"[{message.source}] {message.content[:100]}...")

    # Retrieve messages from a specific role (e.g., 'assistant')
    filtered_messages = client.session.get_messages(
        session_id_to_fetch,
        filter=MessageFilter(role="assistant")
    )
    print(f"Assistant Messages in session: {filtered_messages.total_count}")

except Exception as e:
    print(f"Error fetching messages: {e}")

get_between_messages

get_between_messages(session_id: str, from_message_id: str, to_message_id: str) -> GetMessagesResponse

Retrieves a sequence of messages from a session that fall between two specified message IDs (inclusive).

ParameterTypeDescription
session_idstrThe unique ID of the session containing the messages.
from_message_idstrThe ID of the starting message in the desired range (inclusive).
to_message_idstrThe ID of the ending message in the desired range (inclusive).

Returns:

GetMessagesResponse: An object containing the messages within the specified range. Note that pagination metadata (page_num, page_size, total_page) might not be relevant or populated for this specific endpoint, only total_count, has_next, has_prev and data will be relevant.

Example: Retrieving Messages Between Two IDs

from wyse_mate import Client
from wyse_mate.config import load_default_config

client = Client(load_default_config()) # or initialize manually

session_id_to_fetch = "your-session-id-here" # Replace with an actual session ID
from_msg_id = "message-id-1" # Replace with an actual message ID from the session
to_msg_id = "message-id-2"   # Replace with another actual message ID from the session

try:
    messages_between = client.session.get_between_messages(
        session_id_to_fetch, from_msg_id, to_msg_id
    )
    print(f"Messages between {from_msg_id} and {to_msg_id}: {messages_between.total_count} found.")
    for message in messages_between.messages:
        print(f"[{message.source}] {message.content[:100]}...")

except Exception as e:
    print(f"Error fetching messages between IDs: {e}")

update_session_name

update_session_name(request: UpdateSessionNameRequest) -> None

Modifies the title (name) of an existing session.

ParameterTypeDescription
requestUpdateSessionNameRequestThe request body containing the session ID and the new title.

Example: Updating a Session's Name

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import UpdateSessionNameRequest

client = Client(load_default_config()) # or initialize manually

session_id_to_update = "your-session-id-here" # Replace with an actual session ID
new_session_name = "My Updated Session Title"

try:
    update_req = UpdateSessionNameRequest(
        session_id=session_id_to_update,
        title=new_session_name
    )
    client.session.update_session_name(update_req)
    print(f"Session {session_id_to_update} name successfully updated to \"{new_session_name}\".")
except Exception as e:
    print(f"Error updating session name: {e}")

Session Service Data Models

CreateSessionRequest Data Model

Defines the structure for requests to create a new session.

from pydantic import BaseModel, Field
from typing import Optional

class CreateSessionRequest(BaseModel):
    team_id: str = Field(alias="team_id", description="The unique identifier of the team associated with the new session.")
    task: Optional[str] = Field(default="", description="The initial task or objective for the session. This will guide the agents' actions.")
    title: Optional[str] = Field(None, description="An optional, human-readable title for the new session.")
AttributeTypeDescriptionDefault Value
team_idstrThe ID of the team associated with the session.
taskOptional[str]The initial task or objective for the session.""
titleOptional[str]An optional title for the new session.None

CreateSessionResponse Data Model

Represents the response received after successfully creating a new session.

from pydantic import BaseModel, Field

class CreateSessionResponse(BaseModel):
    session_id: str = Field(alias="session_id", description="The unique identifier of the newly created session.")
AttributeTypeDescription
session_idstrThe unique ID of the newly created session.

SessionInfo Data Model

Provides comprehensive information and current status about a specific session.

from pydantic import BaseModel, Field
from datetime import datetime
from typing import Any, List, Optional, Dict

class SessionInfo(BaseModel):
    session_id: str = Field(alias="session_id", description="Unique identifier of the session.")
    status: str = Field(description="The current operational status of the session (e.g., 'active', 'completed', 'error').")
    browser_id: str = Field(alias="browser_id", description="The ID of the browser instance associated with this session.")
    team_id: str = Field(alias="team_id", description="The ID of the team that owns this session.")
    intent_id: str = Field(alias="intent_id", description="An identifier related to the original intent or goal of the session.")
    name: str = Field(description="The human-readable title or name of the session.")
    task: List[UserTaskMessage] = Field(alias="task", description="A list of `UserTaskMessage` objects representing the tasks defined for this session.")
    task_result: Dict[str, Any] = Field(alias="task_result", description="A dictionary containing the outcome or result of the session's task.")
    messages: List[MessageResponse] = Field(default_factory=list, description="A list of `MessageResponse` objects representing all messages exchanged within this session.")
    duration: int = Field(description="The total duration of the session in seconds.")
    error_message: str = Field(alias="error_message", description="Any error message or details if the session terminated abnormally.")
    attachments: List[Any] = Field(default_factory=list, description="A list of attachments (e.g., files, images) associated with the session.")
    platform: str = Field(description="The platform on which the session is running.")
    visibility: str = Field(description="The visibility setting for the session (e.g., 'private', 'public').")
    created_at: str = Field(alias="created_at", description="Timestamp when the session was created.")
    updated_at: str = Field(alias="updated_at", description="Timestamp when the session was last updated.")
AttributeTypeDescription
session_idstrUnique ID of the session.
statusstrCurrent status of the session (e.g., "active", "completed").
browser_idstrID of the browser instance associated with the session.
team_idstrID of the team associated with the session.
intent_idstrID related to the original intent or goal.
namestrThe title or name of the session.
taskList[UserTaskMessage]A list of user task messages for the session.
task_resultDict[str, Any]Dictionary containing the result of the session's task.
messagesList[MessageResponse]A list of messages within the session.
durationintDuration of the session in seconds.
error_messagestrAny error message associated with the session.
attachmentsList[Attachments]List of attachments related to the session.
platformstrThe platform where the session is running.
visibilitystrVisibility setting for the session (e.g., "private", "public").
created_atstrTimestamp when the session was created.
updated_atstrTimestamp when the session was last updated.

GetMessagesResponse Data Model

Represents a paginated response containing a list of messages retrieved from a session.

from pydantic import BaseModel, Field
from typing import List

class GetMessagesResponse(BaseModel):
    messages: List[MessageResponse] = Field(description="A list of `MessageResponse` objects for the current page.")
    total_count: int = Field(description="The total number of messages available in the session, across all pages.")
    has_next: bool = Field(default=False, description="Indicates whether there are more messages available on subsequent pages.")
    has_prev: bool = Field(default=False, description="Indicates whether there are messages available on previous pages.")
AttributeTypeDescription
messagesList[MessageResponse]A list of MessageResponse objects for the current page.
total_countintThe total number of messages in the session.
has_nextboolIndicates if there are more messages on subsequent pages.
has_prevboolIndicates if there are messages on previous pages.

MessageFilter Data Model

Used to define criteria for filtering messages when retrieving them from a session, allowing for precise queries based on role, content, or time range.

from pydantic import BaseModel, Field
from typing import Optional
from datetime import datetime

class MessageFilter(BaseModel):
    role: Optional[str] = Field(None, description="Filters messages by the sender's role (e.g., 'user', 'assistant', 'system').")
    content: Optional[str] = Field(None, description="Filters messages containing this specific content string (case-insensitive). ")
    from_timestamp: Optional[datetime] = Field(None, description="Filters messages created after this timestamp (inclusive).")
    to_timestamp: Optional[datetime] = Field(None, description="Filters messages created before this timestamp (inclusive).")
AttributeTypeDescription
roleOptional[str]Filters messages by the sender's role (e.g., "user", "assistant", "system").
contentOptional[str]Filters messages containing this content string.
from_timestampOptional[datetime]Filters messages created after this timestamp (inclusive).
to_timestampOptional[datetime]Filters messages created before this timestamp (inclusive).

MessageResponse Data Model

Represents a single message exchanged within a session, containing details such as sender, content, type, and associated attachments.

from pydantic import BaseModel, Field
from typing import Any, List

class MessageResponse(BaseModel):
    message_id: str = Field(alias="message_id", description="Unique identifier of the message.")
    source: str = Field(description="The source entity of the message (e.g., 'user', 'agent').")
    source_type: str = Field(alias="source_type", description="The type of the source (e.g., 'human', 'llm').")
    source_component: str = Field(alias="source_component", description="The specific component or ID that generated the message (e.g., an agent's ID or user's ID).")
    content: str = Field(description="The main textual content of the message.")
    message: Any = Field(alias="message", description="The raw, unparsed message data. Its structure can vary significantly based on the message type.")
    type: str = Field(alias="type", description="The category or nature of the message (e.g., 'text', 'plan', 'tool_code').")
    created_at: str = Field(alias="created_at", description="Timestamp when the message was created.")
    attachments: List[Any] = Field(default_factory=list, description="A list of attachments (e.g., files, images) associated with the message.")
    session_round: int = Field(alias="session_round", description="The round number within the session to which this message belongs.")
AttributeTypeDescription
message_idstrUnique ID of the message.
sourcestrThe source of the message (e.g., "user", "agent").
source_typestrThe type of the source (e.g., "human", "llm").
source_componentstrThe specific component that generated the message (e.g., agent ID, user ID).
contentstrThe main content of the message.
messageAnyThe raw, unparsed message data. This can vary based on message type.
typestrThe type of message (e.g., "text", "plan", "tool_code").
created_atstrTimestamp when the message was created.
attachmentsList[Attachments]A list of attachments associated with the message.
session_roundintThe round number within the session the message belongs to.

UserTaskMessage Data Model

Represents a user-defined task or input message provided within a session.

from pydantic import BaseModel, Field
from typing import Any, Optional, Dict

class UserTaskMessage(BaseModel):
    role: str = Field(description="The role of the sender, typically 'user'.")
    content: str = Field(description="The textual content of the user's task message.")
    metadata: Optional[Dict[str, Any]] = Field(None, description="An optional dictionary for additional, custom metadata related to the message.")
AttributeTypeDescription
rolestrThe role of the sender (e.g., "user").
contentstrThe content of the user task message.
metadataOptional[Dict[str, Any]]Optional dictionary for additional metadata.

UpdateSessionNameRequest Data Model

Defines the request structure for updating the name (title) of an existing session.

from pydantic import BaseModel, Field

class UpdateSessionNameRequest(BaseModel):
    session_id: str = Field(description="The unique identifier of the session to be updated.")
    title: str = Field(description="The new title or name for the session.")
AttributeTypeDescription
session_idstrThe ID of the session to update.
titlestrThe new title or name for the session.

Browser Service API Reference

The BrowserService offers methods for managing browser instances and their associated web pages within the Wyse Mate platform. Access this service via client.browser.

from wyse_mate.services.browser import BrowserService

class BrowserService:
    def __init__(self, client: "Client"):
        # ... initialization logic ...

Methods

get_info

get_info(browser_id: str) -> BrowserInfo

Retrieves comprehensive details about a specific browser instance, identified by its unique ID.

ParameterTypeDescription
browser_idstrThe unique identifier of the browser whose information is to be retrieved.

Returns:

BrowserInfo: An object containing detailed information about the specified browser.

Example: Getting Browser Information

from wyse_mate import Client
from wyse_mate.config import load_default_config

client = Client(load_default_config()) # or initialize manually

browser_id_to_fetch = "your-browser-id-here" # Replace with an actual browser ID
try:
    browser_details = client.browser.get_info(browser_id_to_fetch)
    print(f"Browser Status: {browser_details.status}")
    print(f"Browser Resolution: {browser_details.width}x{browser_details.height}")
    print(f"Associated Session ID: {browser_details.session_id}")
except Exception as e:
    print(f"Error fetching browser info: {e}")

list_browsers

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

Retrieves a list of all browser instances, with an option to filter them by a specific session ID. Pagination is supported.

ParameterTypeDescriptionDefault Value
session_idstrThe unique ID of the session to filter browser instances by.
optionsOptional[ListOptions]Optional pagination settings (page_num, page_size).None (uses default page_num=1, page_size=20)

Returns:

ListBrowsersResponse: An object containing a list of BrowserInfo objects and the total count.

Example: Listing Browsers

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import ListOptions

client = Client(load_default_config()) # or initialize manually

session_id_to_filter = "your-session-id-here" # Replace with an actual session ID
try:
    browsers_response = client.browser.list_browsers(session_id=session_id_to_filter)
    print(f"Total Browsers for session {session_id_to_filter}: {browsers_response.total}")
    for browser in browsers_response.browsers:
        print(f"- Browser ID: {browser.browser_id}, Status: {browser.status}")

    # List browsers with a custom page size of 2
    paginated_browsers = client.browser.list_browsers(
        session_id=session_id_to_filter, options=ListOptions(page_size=2)
    )
    print(f"Browsers for session {session_id_to_filter} (first 2): {len(paginated_browsers.browsers)} found.")

except Exception as e:
    print(f"Error listing browsers: {e}")

release_browser

release_browser(browser_id: str) -> None

Releases a specific browser instance, making it available for reuse or ensuring its proper closure if no longer required.

ParameterTypeDescription
browser_idstrThe unique identifier of the browser instance to release.

Example: Releasing a Browser

from wyse_mate import Client
from wyse_mate.config import load_default_config

client = Client(load_default_config()) # or initialize manually

browser_id_to_release = "your-browser-id-here" # Replace with an actual browser ID
try:
    client.browser.release_browser(browser_id_to_release)
    print(f"Browser {browser_id_to_release} released successfully.")
except Exception as e:
    print(f"Error releasing browser: {e}")

list_browser_pages

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

Retrieves a list of all currently open pages within a specified browser instance. Pagination is supported.

ParameterTypeDescriptionDefault Value
browser_idstrThe unique ID of the browser whose pages are to be listed.
optionsOptional[ListOptions]Optional pagination settings (page_num, page_size).None (uses default page_num=1, page_size=20)

Returns:

ListBrowserPagesResponse: An object containing a list of BrowserPageInfo objects and the total count of pages.

Example: Listing Browser Pages

from wyse_mate import Client
from wyse_mate.config import load_default_config
from wyse_mate.models import ListOptions

client = Client(load_default_config()) # or initialize manually

browser_id_for_pages = "your-browser-id-here" # Replace with an actual browser ID
try:
    pages_response = client.browser.list_browser_pages(browser_id_for_pages)
    print(f"Total Pages for browser {browser_id_for_pages}: {pages_response.total}")
    for page in pages_response.pages:
        print(f"- Page Index: {page.index}, URL: {page.url}, Status: {page.status}")

    # List pages with a custom page size of 1
    paginated_pages = client.browser.list_browser_pages(
        browser_id_for_pages, options=ListOptions(page_size=1)
    )
    print(f"Pages for browser {browser_id_for_pages} (first page, 1 item): {len(paginated_pages.pages)} found.")

except Exception as e:
    print(f"Error listing browser pages: {e}")

Browser Service Data Models

BrowserInfo Data Model

Represents comprehensive information about a browser instance within the Wyse Mate platform.

from pydantic import BaseModel, Field
from typing import List, Optional

class BrowserInfo(BaseModel):
    browser_id: str = Field(alias="browser_id", description="Unique identifier of the browser instance.")
    user_id: str = Field(alias="user_id", description="The ID of the user who owns this browser instance.")
    session_id: str = Field(alias="session_id", description="The ID of the session this browser is associated with.")
    status: str = Field(description="The current operational status of the browser (e.g., 'open', 'closed', 'error').")
    width: int = Field(description="The width of the browser window in pixels.")
    height: int = Field(description="The height of the browser window in pixels.")
    ws_endpoint: str = Field(alias="ws_endpoint", description="The WebSocket endpoint for direct interaction with this browser instance.")
    solve_captcha: bool = Field(alias="solve_captcha", description="Indicates whether automated CAPTCHA solving is enabled for this browser.")
    timezone: str = Field(description="The timezone configured for the browser instance.")
    user_agent: str = Field(alias="user_agent", description="The User-Agent string that the browser presents.")
    duration_seconds: int = Field(alias="duration_seconds", description="The total duration (in seconds) that the browser has been active.")
    created_at: str = Field(alias="created_at", description="Timestamp when the browser instance was created.") # Or datetime
    pages: List[BrowserPageInfo] = Field(default_factory=list, description="A list of `BrowserPageInfo` objects representing all open pages within this browser instance.")
AttributeTypeDescription
browser_idstrUnique ID of the browser instance.
user_idstrID of the user who owns the browser.
session_idstrID of the session the browser is associated with.
statusstrCurrent status of the browser (e.g., "open", "closed").
widthintWidth of the browser window in pixels.
heightintHeight of the browser window in pixels.
ws_endpointstrWebSocket endpoint for direct browser interaction.
solve_captchaboolIndicates if captcha solving is enabled for this browser.
timezonestrThe timezone configured for the browser.
user_agentstrThe User-Agent string used by the browser.
duration_secondsintHow long the browser has been active in seconds.
created_atstrTimestamp when the browser instance was created.
pagesList[BrowserPageInfo]A list of open pages within this browser instance.

BrowserPageInfo Data Model

Provides information about a single web page open within a browser instance.

from pydantic import BaseModel, Field

class BrowserPageInfo(BaseModel):
    index: int = Field(description="The numerical index of the page within its browser instance.")
    url: str = Field(description="The current URL of the web page.")
    status: str = Field(description="The loading status of the page (e.g., 'loading', 'completed').")
    video_url: str = Field(alias="video_url", description="URL to a video recording of the page's activity, if available.")
    ws_debugger_url: str = Field(alias="ws_debugger_url", description="The WebSocket debugger URL for this specific page, allowing for low-level interaction.")
    front_debugger_url: str = Field(alias="front_debugger_url", description="The frontend debugger URL for direct browser tool access.")
    page_id: str = Field(alias="page_id", description="Unique identifier of the browser page.")
    debugger_host: str = Field(alias="debugger_host", description="The host address for the debugger service.")
AttributeTypeDescription
indexintThe index of the page within the browser.
urlstrThe current URL of the page.
statusstrThe loading status of the page (e.g., "loading", "completed").
video_urlstrURL to a video recording of the page (if available).
ws_debugger_urlstrWebSocket debugger URL for the page.
front_debugger_urlstrFrontend debugger URL for the page.
page_idstrUnique ID of the page.
debugger_hoststrThe host for the debugger.

ListBrowsersResponse Data Model

Encapsulates a response containing a list of browser instances and their total count.

from pydantic import BaseModel, Field
from typing import List

class ListBrowsersResponse(BaseModel):
    browsers: List[BrowserInfo] = Field(description="A list of `BrowserInfo` objects, each representing an available browser instance.")
    total: int = Field(description="The total number of browser instances available.")
AttributeTypeDescription
browsersList[BrowserInfo]A list of BrowserInfo objects.
totalintThe total number of browser instances available.

ListBrowserPagesResponse Data Model

Represents a response containing a list of pages for a specific browser instance, along with the total count.

from pydantic import BaseModel, Field
from typing import List

class ListBrowserPagesResponse(BaseModel):
    pages: List[BrowserPageInfo] = Field(description="A list of `BrowserPageInfo` objects, each representing an open page within the browser.")
    total: int = Field(description="The total number of pages found for the specified browser.")
AttributeTypeDescription
pagesList[BrowserPageInfo]A list of BrowserPageInfo objects.
totalintThe total number of pages for the browser.