uagents-core 0.3.7__tar.gz → 0.3.8__tar.gz

{uagents_core-0.3.7 → uagents_core-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uagents-core
-Version: 0.3.7
+Version: 0.3.8
 Summary: Core components for agent based systems
 License: Apache 2.0
 Author: Ed FitzGerald

{uagents_core-0.3.7 → uagents_core-0.3.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uagents-core"
-version = "0.3.7"
+version = "0.3.8"
 description = "Core components for agent based systems"
 authors = [
     { name = "Ed FitzGerald", email = "edward.fitzgerald@fetch.ai" },

{uagents_core-0.3.7 → uagents_core-0.3.8}/uagents_core/types.py

@@ -1,5 +1,6 @@
 import uuid
 from abc import ABC, abstractmethod
+from datetime import datetime
 from enum import Enum
 from typing import Any, Literal
 
@@ -26,6 +27,32 @@ class AgentInfo(BaseModel):
     port: int | None = None
 
 
+class AgentRecord(BaseModel):
+    address: str
+    weight: float
+
+
+class DomainRecord(BaseModel):
+    name: str
+    agents: list[AgentRecord]
+
+
+class DomainStatus(Enum):
+    Registered = "Registered"
+    Pending = "Pending"
+    Checking = "Checking"
+    Updating = "Updating"
+    Deleting = "Deleting"
+    Failed = "Failed"
+
+
+class Domain(BaseModel):
+    name: str
+    status: DomainStatus
+    expiry: datetime | None = None
+    assigned_agents: list[AgentRecord]
+
+
 class DeliveryStatus(str, Enum):
     """Delivery status of a message."""
 

{uagents_core-0.3.7 → uagents_core-0.3.8}/uagents_core/utils/registration.py

@@ -2,10 +2,12 @@
 This module provides methods to register your identity with the Fetch.ai services.
 """
 
+from typing import Literal
 import urllib.parse
 
 import requests
-from pydantic import BaseModel
+from pydantic import BaseModel, Field, model_validator
+from json import JSONDecodeError
 
 from uagents_core.config import (
     DEFAULT_ALMANAC_API_PATH,
@@ -14,9 +16,10 @@ from uagents_core.config import (
     DEFAULT_REQUEST_TIMEOUT,
     AgentverseConfig,
 )
+from uagents_core.contrib.protocols.chat import chat_protocol_spec
 from uagents_core.identity import Identity
 from uagents_core.logger import get_logger
-from uagents_core.protocol import is_valid_protocol_digest
+from uagents_core.protocol import ProtocolSpecification, is_valid_protocol_digest
 from uagents_core.registration import (
     AgentRegistrationAttestation,
     AgentRegistrationAttestationBatch,
@@ -26,9 +29,8 @@ from uagents_core.registration import (
     ChallengeRequest,
     ChallengeResponse,
     RegistrationRequest,
-    RegistrationResponse,
 )
-from uagents_core.types import AddressPrefix, AgentEndpoint
+from uagents_core.types import AddressPrefix, AgentEndpoint, AgentType
 
 logger = get_logger("uagents_core.utils.registration")
 
@@ -55,35 +57,125 @@ class AgentRegistrationInput:
         self.metadata = metadata
 
 
-def _send_post_request(
+class AgentverseRegistrationRequest(BaseModel):
+    """
+    A model containing all information for a user to register
+    their pre-existing agent to Agentverse.
+    """
+
+    name: str = Field(description="Agent name in Agentverse")
+    endpoint: str = Field(
+        description="Endpoint where the existing agent is accessible at."
+    )
+    protocols: list[str] = Field(
+        description="List of protocols supported by the agent."
+    )
+    type: AgentType = Field(
+        default="custom", description="Agentverse registration type"
+    )
+    description: str | None = Field(
+        default=None,
+        description="Agent short description, shown on its Agentverse profile.",
+    )
+    readme: str | None = Field(default=None, description="Agent skills description.")
+    avatar_url: str | None = Field(
+        default=None,
+        description="Agent avatar url to be shown on its Agentverse profile.",
+    )
+    active: bool = Field(default=True, description="Set agent as active immediatly")
+
+    @model_validator(mode="after")
+    def check_request(self) -> "AgentverseRegistrationRequest":
+        # check endpoint
+        result = urllib.parse.urlparse(self.endpoint)
+        if not all([result.scheme, result.netloc]):
+            raise ValueError(f"Invalid endpoint provided: {self.endpoint}")
+
+        # check protocol digests
+        for proto_digest in self.protocols:
+            if not is_valid_protocol_digest(proto_digest):
+                raise ValueError(
+                    f"Invalid protocol digest provided: {proto_digest}",
+                )
+        return self
+
+
+class RegistrationRequestCredentials(BaseModel):
+    agentverse_api_key: str = Field(
+        description="Agentverse API key generated by the owner of the agent"
+    )
+    agent_seed_phrase: str = Field(
+        description="The secret seed phrase used to create the agent identity"
+    )
+
+
+class AgentverseRequestException(Exception):
+    def __init__(self, *args, from_exc: Exception):
+        self.from_exc = from_exc
+        super().__init__(*args)
+
+
+def _send_http_request_agentverse(
+    request_type: Literal["post", "put"],
     url: str,
     data: BaseModel,
     *,
     headers: dict[str, str] | None = None,
     timeout: int = DEFAULT_REQUEST_TIMEOUT,
-) -> tuple[bool, requests.Response | None]:
+) -> requests.Response:
     final_headers: dict[str, str] = {"content-type": "application/json"}
     if headers:
         final_headers.update(headers)
+
+    send_request = requests.post if request_type == "post" else requests.put
+
     try:
-        response: requests.Response = requests.post(
+        response: requests.Response = send_request(
             url=url,
             headers=final_headers,
             data=data.model_dump_json(),
             timeout=timeout,
         )
         response.raise_for_status()
-        return True, response
-    except requests.RequestException as e:
-        error_detail = getattr(e, "response", None)
-        if error_detail is not None:
-            error_detail = error_detail.text
-        logger.error(
-            msg=f"Error submitting request: {error_detail}",
-            extra={"url": url, "data": data.model_dump_json()},
-            exc_info=e,
-        )
-    return False, None
+    except Exception as e:
+        err_msg = ""
+
+        if isinstance(e, requests.ConnectionError):
+            err_msg += f"Connection error {e.strerror}."
+        elif isinstance(e, requests.Timeout):
+            err_msg += "Operation timed out."
+        elif isinstance(e, requests.HTTPError):
+            code = e.response.status_code
+            try:
+                content = e.response.json()["detail"]
+            except (JSONDecodeError, KeyError):
+                content = e.response.content.decode()
+            if code in [401, 406, 409]:
+                err_msg += content
+            elif code == 500:
+                err_msg += "Unexpected server error."
+            else:
+                err_msg += f"HTTP error: {code} {content}"
+        elif isinstance(e, requests.RequestException):
+            err_msg += f"Unexpected request error: {e}."
+        else:
+            err_msg += f"Unexpected error: {e}."
+
+        raise AgentverseRequestException(err_msg, from_exc=e)
+
+    return response
+
+
+def _send_post_request_agentverse(
+    url: str,
+    data: BaseModel,
+    *,
+    headers: dict[str, str] | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+) -> requests.Response:
+    return _send_http_request_agentverse(
+        "post", url, data, headers=headers, timeout=timeout
+    )
 
 
 def _build_signed_attestation(
@@ -94,9 +186,11 @@ def _build_signed_attestation(
     ]
 
     attestation = AgentRegistrationAttestation(
-        agent_identifier=f"{item.prefix}://{item.identity.address}"
-        if item.prefix
-        else item.identity.address,
+        agent_identifier=(
+            f"{item.prefix}://{item.identity.address}"
+            if item.prefix
+            else item.identity.address
+        ),
         protocols=item.protocol_digests,
         endpoints=agent_endpoints,
         metadata=item.metadata,
@@ -106,6 +200,49 @@ def _build_signed_attestation(
     return attestation
 
 
+def _register_in_almanac(
+    identity: Identity,
+    endpoints: list[str],
+    protocol_digests: list[str],
+    metadata: dict[str, str | list[str] | dict[str, str]] | None = None,
+    prefix: AddressPrefix | None = None,
+    *,
+    agentverse_config: AgentverseConfig | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+) -> requests.Response:
+    """
+    Register the identity with the Almanac API to make it discoverable by other agents.
+
+    Args:
+        identity (Identity): The identity of the agent.
+        prefix (AddressPrefix | None): The prefix for the agent identifier.
+        endpoints (list[str]): The endpoints that the agent can be reached at.
+        protocol_digests (list[str]): The digests of the protocol that the agent supports
+        agentverse_config (AgentverseConfig): The configuration for the agentverse API
+        timeout (int): The timeout for the request
+    """
+    # get the almanac API endpoint
+    agentverse_config = agentverse_config or AgentverseConfig()
+    almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
+
+    # create the attestation
+    item = AgentRegistrationInput(
+        identity=identity,
+        prefix=prefix,
+        endpoints=endpoints,
+        protocol_digests=protocol_digests,
+        metadata=metadata,
+    )
+    attestation = _build_signed_attestation(item)
+
+    logger.info(msg="Registering with Almanac API", extra=attestation.model_dump())
+
+    # submit the attestation to the API
+    return _send_post_request_agentverse(
+        url=f"{almanac_api}/agents", data=attestation, timeout=timeout
+    )
+
+
 def register_in_almanac(
     identity: Identity,
     endpoints: list[str],
@@ -149,27 +286,21 @@ def register_in_almanac(
             )
             return False
 
-    # get the almanac API endpoint
-    agentverse_config = agentverse_config or AgentverseConfig()
-    almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
-
-    # create the attestation
-    item = AgentRegistrationInput(
-        identity=identity,
-        prefix=prefix,
-        endpoints=endpoints,
-        protocol_digests=protocol_digests,
-        metadata=metadata,
-    )
-    attestation = _build_signed_attestation(item)
-
-    logger.info(msg="Registering with Almanac API", extra=attestation.model_dump())
+    try:
+        _register_in_almanac(
+            identity,
+            endpoints,
+            protocol_digests,
+            metadata,
+            prefix,
+            agentverse_config=agentverse_config,
+            timeout=timeout,
+        )
+        return True
+    except AgentverseRequestException as e:
+        logger.error(msg=str(e), exc_info=e.from_exc)
 
-    # submit the attestation to the API
-    status, _ = _send_post_request(
-        url=f"{almanac_api}/agents", data=attestation, timeout=timeout
-    )
-    return status
+    return False
 
 
 def register_batch_in_almanac(
@@ -252,23 +383,27 @@ def register_batch_in_almanac(
     )
 
     # submit the attestation to the API
-    status, _ = _send_post_request(
-        url=f"{almanac_api}/agents/batch",
-        data=attestation_batch,
-        timeout=timeout,
-    )
-    return status, invalid_identities
+    try:
+        _send_post_request_agentverse(
+            url=f"{almanac_api}/agents/batch",
+            data=attestation_batch,
+            timeout=timeout,
+        )
+        return True, invalid_identities
+    except AgentverseRequestException as e:
+        logger.error(msg=str(e), exc_info=e.from_exc)
 
+    return False, invalid_identities
 
-# associate user account with your agent
-def register_in_agentverse(
+
+def _register_in_agentverse(
     request: AgentverseConnectRequest,
     identity: Identity,
     *,
     agent_details: AgentUpdates | None = None,
     agentverse_config: AgentverseConfig | None = None,
     timeout: int = DEFAULT_REQUEST_TIMEOUT,
-) -> bool:
+):
     """
     Register an agent in Agentverse and update its details if provided.
 
@@ -317,18 +452,18 @@ def register_in_agentverse(
         logger.debug(
             msg="Requesting mailbox access challenge", extra=registration_metadata
         )
-        status, response = _send_post_request(
-            url=challenge_api,
-            data=challenge_request,
-            headers={"authorization": f"Bearer {request.user_token}"},
-            timeout=timeout,
-        )
-        if not status or not response:
-            logger.error(
-                msg="Error requesting mailbox access challenge",
-                extra=registration_metadata,
+        try:
+            response = _send_post_request_agentverse(
+                url=challenge_api,
+                data=challenge_request,
+                headers={"authorization": f"Bearer {request.user_token}"},
+                timeout=timeout,
+            )
+        except AgentverseRequestException as e:
+            raise AgentverseRequestException(
+                f"failed to request proof-of-ownership challenge. {str(e)}",
+                from_exc=e.from_exc,
             )
-            return False
 
         challenge = ChallengeResponse.model_validate_json(response.text)
         registration_payload = RegistrationRequest(
@@ -338,34 +473,20 @@ def register_in_agentverse(
             endpoint=request.endpoint,
             agent_type=request.agent_type,
         )
-        status, response = _send_post_request(
+
+        response = _send_post_request_agentverse(
             url=registration_api,
             data=registration_payload,
             headers={"authorization": f"Bearer {request.user_token}"},
             timeout=timeout,
         )
-        if not status or not response:
-            logger.error(
-                msg="Error registering agent with Agentverse",
-                extra=registration_metadata,
-            )
-            return False
-        else:
-            registration_response = RegistrationResponse.model_validate_json(
-                response.text
-            )
-            if registration_response.success:
-                logger.info(
-                    msg=f"Successfully registered as {request.agent_type} agent in Agentverse",
-                    extra=registration_metadata,
-                )
 
     if not agent_details:
         logger.debug(
             msg="No agent details provided; skipping agent update",
             extra=registration_metadata,
         )
-        return True
+        return
 
     # update the readme and the name of the agent to make it easier to find
     logger.debug(
@@ -373,31 +494,55 @@ def register_in_agentverse(
         extra=registration_metadata,
     )
     try:
-        response = requests.put(
+        response = _send_http_request_agentverse(
+            request_type="put",
             url=f"{registration_api}/{agent_address}",
             headers={
                 "content-type": "application/json",
                 "authorization": f"Bearer {request.user_token}",
             },
-            data=agent_details.model_dump_json(),
+            data=agent_details,
             timeout=timeout,
         )
-        response.raise_for_status()
-        logger.info(
-            msg="Completed registering agent with Agentverse",
-            extra=registration_metadata,
+    except AgentverseRequestException as e:
+        logger.warning(f"failed to upload agent details. {str(e)}")
+
+
+# associate user account with your agent
+def register_in_agentverse(
+    request: AgentverseConnectRequest,
+    identity: Identity,
+    *,
+    agent_details: AgentUpdates | None = None,
+    agentverse_config: AgentverseConfig | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+) -> bool:
+    """
+    Register an agent in Agentverse and update its details if provided.
+
+    Args:
+        request (AgentverseConnectRequest): The request containing the agent details.
+        identity (Identity): The identity of the agent.
+        agent_details (AgentUpdates | None): The agent details to update.
+        agentverse_config (AgentverseConfig | None): The configuration for the agentverse API
+        timeout (int): The timeout for the requests
+    """
+    try:
+        _register_in_agentverse(
+            request,
+            identity,
+            agent_details=agent_details,
+            agentverse_config=agentverse_config,
+            timeout=timeout,
         )
         return True
-    except requests.RequestException as e:
-        logger.error(
-            msg="Error registering agent with Agentverse",
-            extra=registration_metadata,
-            exc_info=e,
-        )
-        return False
+    except AgentverseRequestException as e:
+        logger.error(msg=str(e), exc_info=e.from_exc)
+
+    return False
 
 
-def update_agent_status(active: bool, identity: Identity):
+def _update_agent_status(active: bool, identity: Identity):
     """
     Update the agent's active/inactive status in the Almanac API.
 
@@ -417,15 +562,108 @@ def update_agent_status(active: bool, identity: Identity):
         extra=status_update.model_dump(),
     )
 
-    status, _ = _send_post_request(
+    _send_post_request_agentverse(
         url=f"{almanac_api}/agents/{identity.address}/status",
         data=status_update,
     )
 
-    if status:
-        logger.info(
-            msg=f"Agent status updated to {'active' if active else 'inactive'}",
-            extra={"agent_address": identity.address},
+
+def update_agent_status(active: bool, identity: Identity) -> bool:
+    """
+    Update the agent's active/inactive status in the Almanac API.
+
+    Args:
+        active (bool): The status of the agent.
+        identity (Identity): The identity of the agent.
+    """
+    try:
+        _update_agent_status(active, identity)
+        return True
+    except AgentverseRequestException as e:
+        logger.error(msg=str(e), exc_info=e.from_exc)
+
+    return False
+
+
+def register_agent(
+    agent_registration: AgentverseRegistrationRequest,
+    agentverse_config: AgentverseConfig,
+    credentials: RegistrationRequestCredentials,
+):
+    identity = Identity.from_seed(credentials.agent_seed_phrase, 0)
+    endpoints = [agent_registration.endpoint]
+    protos = agent_registration.protocols
+
+    connect_request = AgentverseConnectRequest(
+        user_token=credentials.agentverse_api_key,
+        agent_type=agent_registration.type,
+        endpoint=endpoints[0],
+    )
+
+    agent_details = AgentUpdates(
+        name=agent_registration.name,
+        readme=agent_registration.readme,
+        avatar_url=agent_registration.avatar_url,
+        short_description=agent_registration.description,
+        agent_type=agent_registration.type,
+    )
+
+    # register the agent to almanac
+    try:
+        logger.info("registering to Almanac...")
+        _register_in_almanac(
+            identity, endpoints, protos, agentverse_config=agentverse_config
         )
+        logger.info("successfully registered to Almanac.")
+    except AgentverseRequestException as e:
+        logger.error(f"failed to register to Almanac. {str(e)}")
+        return
+
+    # register the agent to agentverse
+    try:
+        logger.info("registering to Agentverse...")
+        _register_in_agentverse(
+            connect_request,
+            identity,
+            agent_details=agent_details,
+            agentverse_config=agentverse_config,
+        )
+        logger.info("successfully registered to Agentverse.")
+    except AgentverseRequestException as e:
+        logger.error(f"failed to register to Agentverse. {str(e)}")
+        return
+
+    # set agent as active
+    if agent_registration.active:
+        try:
+            logger.info("setting agent as active...")
+            _update_agent_status(True, identity)
+            logger.info("successfully set agent to active.")
+        except AgentverseRequestException as e:
+            logger.warning(f"failed to set agent as active. {str(e)}")
+
+
+def register_chat_agent(
+    name: str,
+    endpoint: str,
+    active: bool,
+    credentials: RegistrationRequestCredentials,
+    description: str | None = None,
+    readme: str | None = None,
+    avatar_url: str | None = None,
+):
+    chat_protocol = [
+        ProtocolSpecification.compute_digest(chat_protocol_spec.manifest())
+    ]
+    request = AgentverseRegistrationRequest(
+        name=name,
+        endpoint=endpoint,
+        protocols=chat_protocol,
+        active=active,
+        description=description,
+        readme=readme,
+        avatar_url=avatar_url,
+    )
+    config = AgentverseConfig()
 
-    return status
+    register_agent(request, config, credentials)

{uagents_core-0.3.7 → uagents_core-0.3.8}/uagents_core/utils/resolver.py

@@ -14,11 +14,55 @@ from uagents_core.config import (
 from uagents_core.helpers import weighted_random_sample
 from uagents_core.identity import parse_identifier
 from uagents_core.logger import get_logger
-from uagents_core.types import Resolver
+from uagents_core.types import Domain, Resolver
 
 logger = get_logger("uagents_core.utils.resolver")
 
 
+def lookup_address_for_domain(
+    agent_identifier: str,
+    *,
+    agentverse_config: AgentverseConfig | None = None,
+) -> str | None:
+    agentverse_config = agentverse_config or AgentverseConfig()
+    almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
+
+    prefix, domain, _ = parse_identifier(agent_identifier)
+    if not domain:
+        logger.error(
+            "No domain provided in agent identifier",
+            extra={"identifier": agent_identifier},
+        )
+        return None
+
+    params = {"prefix": prefix} if prefix else None
+    try:
+        response = requests.get(
+            url=f"{almanac_api}/domains/{domain}",
+            timeout=DEFAULT_REQUEST_TIMEOUT,
+            params=params,
+        )
+        response.raise_for_status()
+    except requests.RequestException as e:
+        logger.error(
+            msg="Error looking up domain",
+            extra={"domain": domain, "exception": str(e)},
+        )
+        return None
+
+    domain_record = Domain.model_validate(response.json())
+
+    agent_records = domain_record.assigned_agents
+    if len(agent_records) == 0:
+        return None
+    elif len(agent_records) == 1:
+        return agent_records[0].address
+    else:
+        addresses = [val.address for val in agent_records]
+        weights = [val.weight for val in agent_records]
+        return weighted_random_sample(addresses, weights=weights, k=1)[0]
+
+
 def lookup_endpoint_for_agent(
     agent_identifier: str,
     *,
@@ -34,19 +78,36 @@ def lookup_endpoint_for_agent(
     Returns:
         List[str]: The endpoint(s) for the agent.
     """
-    _, _, agent_address = parse_identifier(agent_identifier)
 
     agentverse_config = agentverse_config or AgentverseConfig()
     almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
 
+    prefix, domain, agent_address = parse_identifier(agent_identifier)
+
+    if not agent_address:
+        if domain:
+            agent_address = lookup_address_for_domain(
+                agent_identifier=agent_identifier,
+                agentverse_config=agentverse_config,
+            )
+        else:
+            logger.error(
+                "No address or domain provided in identifier",
+                extra={"identifier": agent_identifier},
+            )
+            return []
+
     request_meta: dict[str, Any] = {
         "agent_address": agent_address,
         "lookup_url": almanac_api,
     }
     logger.debug(msg="looking up endpoint for agent", extra=request_meta)
     try:
+        params = {"prefix": prefix} if prefix else None
         response = requests.get(
-            url=f"{almanac_api}/agents/{agent_address}", timeout=DEFAULT_REQUEST_TIMEOUT
+            url=f"{almanac_api}/agents/{agent_address}",
+            params=params,
+            timeout=DEFAULT_REQUEST_TIMEOUT,
         )
         response.raise_for_status()
     except requests.RequestException as e: