uagents-core 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

uagents_core/utils/registration.py

@@ -1,16 +1,22 @@
+"""
+This module provides methods to register your identity with the Fetch.ai services.
+"""
+
 import urllib.parse
-from typing import List, Optional
 
 import requests
+from pydantic import BaseModel
 
 from uagents_core.config import (
     DEFAULT_ALMANAC_API_PATH,
     DEFAULT_CHALLENGE_PATH,
     DEFAULT_REGISTRATION_PATH,
+    DEFAULT_REQUEST_TIMEOUT,
     AgentverseConfig,
 )
-from uagents_core.crypto import Identity
+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.registration import (
     AgentRegistrationAttestation,
     AgentUpdates,
@@ -25,22 +31,77 @@ from uagents_core.types import AgentEndpoint
 logger = get_logger("uagents_core.utils.registration")
 
 
+def _send_post_request(
+    url: str,
+    data: BaseModel,
+    *,
+    headers: dict[str, str] | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+) -> tuple[bool, requests.Response | None]:
+    final_headers: dict[str, str] = {"content-type": "application/json"}
+    if headers:
+        final_headers.update(headers)
+    try:
+        response: requests.Response = requests.post(
+            url=url,
+            headers=final_headers,
+            data=data.model_dump_json(),
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return True, response
+    except requests.RequestException as e:
+        logger.error(
+            msg="Error submitting request",
+            extra={"url": url, "data": data.model_dump_json()},
+            exc_info=e,
+        )
+    return False, None
+
+
 def register_in_almanac(
-    request: AgentverseConnectRequest,
     identity: Identity,
+    endpoints: list[str],
+    protocol_digests: list[str],
     *,
-    protocol_digests: List[str],
-    agentverse_config: Optional[AgentverseConfig] = None,
-):
+    agentverse_config: AgentverseConfig | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+) -> bool:
     """
-    Register the agent with the Almanac API.
+    Register the identity with the Almanac API to make it discoverable by other agents.
 
     Args:
-        request (AgentverseConnectRequest): The request containing the agent details.
         identity (Identity): The identity of the agent.
-        protocol_digest (List[str]): The digest of the protocol that the agent supports
+        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
     """
+    # check endpoints
+    if not endpoints:
+        logger.warning("No endpoints provided; skipping registration")
+        return False
+    for endpoint in endpoints:
+        result = urllib.parse.urlparse(endpoint)
+        if not all([result.scheme, result.netloc]):
+            logger.error(
+                msg="Invalid endpoint provided; skipping registration",
+                extra={"endpoint": endpoint},
+            )
+            return False
+
+    agent_endpoints: list[AgentEndpoint] = [
+        AgentEndpoint(url=endpoint, weight=1) for endpoint in endpoints
+    ]
+
+    # check protocol digests
+    for proto_digest in protocol_digests:
+        if not is_valid_protocol_digest(proto_digest):
+            logger.error(
+                msg="Invalid protocol digest provided; skipping registration",
+                extra={"protocol_digest": proto_digest},
+            )
+            return False
 
     # get the almanac API endpoint
     agentverse_config = agentverse_config or AgentverseConfig()
@@ -49,83 +110,51 @@ def register_in_almanac(
     # get the agent address
     agent_address = identity.address
 
-    registration_metadata = {
-        "almanac_endpoint": almanac_api,
-        "agent_address": agent_address,
-        "agent_endpoint": request.endpoint or "",
-        "protocol_digest": ",".join(protocol_digests),
-    }
-    if request.endpoint is None:
-        if request.agent_type == "mailbox":
-            request.endpoint = f"{agentverse_config.url}/v1/submit"
-        elif request.agent_type == "proxy":
-            request.endpoint = f"{agentverse_config.url}/v1/proxy/submit"
-
-    if request.endpoint is None:
-        logger.warning(
-            "No endpoint provided for agent registration",
-            extra=registration_metadata,
-        )
-        return
-
-    logger.info(
-        "Registering with Almanac API",
-        extra=registration_metadata,
-    )
-
     # create the attestation
     attestation = AgentRegistrationAttestation(
         agent_identifier=agent_address,
         protocols=protocol_digests,
-        endpoints=[
-            AgentEndpoint(url=request.endpoint, weight=1),
-        ],
+        endpoints=agent_endpoints,
         metadata=None,
     )
 
+    logger.info(msg="Registering with Almanac API", extra=attestation.model_dump())
+
     # sign the attestation
     attestation.sign(identity)
 
     # submit the attestation to the API
-    r = requests.post(
-        f"{almanac_api}/agents",
-        headers={"content-type": "application/json"},
-        data=attestation.model_dump_json(),
-    )
-    r.raise_for_status()
-    logger.debug(
-        "Agent attestation submitted",
-        extra=registration_metadata,
+    status, _ = _send_post_request(
+        url=f"{almanac_api}/agents", data=attestation, timeout=timeout
     )
+    return status
 
 
+# associate user account with your agent
 def register_in_agentverse(
     request: AgentverseConnectRequest,
     identity: Identity,
-    agent_details: Optional[AgentUpdates] = None,
     *,
-    agentverse_config: Optional[AgentverseConfig] = None,
-):
+    agent_details: AgentUpdates | None = None,
+    agentverse_config: AgentverseConfig | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+) -> bool:
     """
-    Register the agent with the Agentverse API.
+    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 (Optional[AgentUpdates]): The agent details to update.
-        agentverse_config (AgentverseConfig): The configuration for the agentverse API
-    Returns:
-        None
+        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
     """
-
-    # API endpoints
     agentverse_config = agentverse_config or AgentverseConfig()
     registration_api = urllib.parse.urljoin(
         agentverse_config.url, DEFAULT_REGISTRATION_PATH
     )
     challenge_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_CHALLENGE_PATH)
 
-    # get the agent address
     agent_address = identity.address
 
     registration_metadata = {
@@ -138,87 +167,106 @@ def register_in_agentverse(
     }
 
     # check to see if the agent exists
-    r = requests.get(
+    response = requests.get(
         f"{registration_api}/{agent_address}",
         headers={
             "content-type": "application/json",
             "authorization": f"Bearer {request.user_token}",
         },
+        timeout=timeout,
     )
 
     # if it doesn't then create it
-    if r.status_code == 404:
+    if response.status_code == 404:
         logger.debug(
-            "Agent did not exist on agentverse; registering it",
+            msg="Agent does not exist on agentverse; registering it...",
             extra=registration_metadata,
         )
 
         challenge_request = ChallengeRequest(address=identity.address)
         logger.debug(
-            "Requesting mailbox access challenge",
-            extra=registration_metadata,
+            msg="Requesting mailbox access challenge", extra=registration_metadata
         )
-        r = requests.post(
-            challenge_api,
-            data=challenge_request.model_dump_json(),
-            headers={
-                "content-type": "application/json",
-                "Authorization": f"Bearer {request.user_token}",
-            },
+        status, response = _send_post_request(
+            url=challenge_api,
+            data=challenge_request,
+            headers={"authorization": f"Bearer {request.user_token}"},
+            timeout=timeout,
         )
-        r.raise_for_status()
-        challenge = ChallengeResponse.model_validate_json(r.text)
+        if not status or not response:
+            logger.error(
+                msg="Error requesting mailbox access challenge",
+                extra=registration_metadata,
+            )
+            return False
+
+        challenge = ChallengeResponse.model_validate_json(response.text)
         registration_payload = RegistrationRequest(
             address=identity.address,
             challenge=challenge.challenge,
             challenge_response=identity.sign(challenge.challenge.encode()),
             endpoint=request.endpoint,
             agent_type=request.agent_type,
-        ).model_dump_json()
-        r = requests.post(
-            registration_api,
-            headers={
-                "content-type": "application/json",
-                "authorization": f"Bearer {request.user_token}",
-            },
+        )
+        status, response = _send_post_request(
+            url=registration_api,
             data=registration_payload,
+            headers={"authorization": f"Bearer {request.user_token}"},
+            timeout=timeout,
         )
-        if r.status_code == 409:
+        if not status or not response:
+            logger.error(
+                msg="Error registering agent with Agentverse",
+                extra=registration_metadata,
+            )
+            return False
+        if response.status_code == 409:
             logger.info(
-                "Agent already registered with Agentverse",
+                msg="Agent already registered with Agentverse",
                 extra=registration_metadata,
             )
         else:
-            r.raise_for_status()
-            registration_response = RegistrationResponse.model_validate_json(r.text)
+            registration_response = RegistrationResponse.model_validate_json(
+                response.text
+            )
             if registration_response.success:
                 logger.info(
-                    f"Successfully registered as {request.agent_type} agent in Agentverse",
+                    msg=f"Successfully registered as {request.agent_type} agent in Agentverse",
                     extra=registration_metadata,
                 )
+
     if not agent_details:
         logger.debug(
-            "No agent details provided; skipping agent update",
+            msg="No agent details provided; skipping agent update",
             extra=registration_metadata,
         )
-        return
+        return True
 
-    # update the readme and the title of the agent to make it easier to find
+    # update the readme and the name of the agent to make it easier to find
     logger.debug(
-        "Registering agent title and readme with Agentverse",
-        extra=registration_metadata,
-    )
-    update = AgentUpdates(name=agent_details.name, readme=agent_details.readme)
-    r = requests.put(
-        f"{registration_api}/{agent_address}",
-        headers={
-            "content-type": "application/json",
-            "authorization": f"Bearer {request.user_token}",
-        },
-        data=update.model_dump_json(),
-    )
-    r.raise_for_status()
-    logger.info(
-        "Completed registering agent with Agentverse",
+        msg="Registering agent details with Agentverse",
         extra=registration_metadata,
     )
+    try:
+        response = requests.put(
+            url=f"{registration_api}/{agent_address}",
+            headers={
+                "content-type": "application/json",
+                "authorization": f"Bearer {request.user_token}",
+            },
+            data=agent_details.model_dump_json(),
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        logger.info(
+            msg="Completed registering agent with Agentverse",
+            extra=registration_metadata,
+        )
+        return True
+    except requests.RequestException as e:
+        logger.error(
+            msg="Error registering agent with Agentverse",
+            extra=registration_metadata,
+            exc_info=e,
+        )
+        return False

uagents_core/utils/resolver.py

@@ -0,0 +1,73 @@
+"""This module provides methods to resolve an agent address."""
+
+import urllib.parse
+from typing import Any
+
+import requests
+
+from uagents_core.config import (
+    DEFAULT_ALMANAC_API_PATH,
+    DEFAULT_MAX_ENDPOINTS,
+    DEFAULT_REQUEST_TIMEOUT,
+    AgentverseConfig,
+)
+from uagents_core.helpers import weighted_random_sample
+from uagents_core.identity import parse_identifier
+from uagents_core.logger import get_logger
+
+logger = get_logger("uagents_core.utils.resolver")
+
+
+def lookup_endpoint_for_agent(
+    agent_identifier: str,
+    *,
+    max_endpoints: int = DEFAULT_MAX_ENDPOINTS,
+    agentverse_config: AgentverseConfig | None = None,
+) -> list[str]:
+    """
+    Resolve the endpoints for an agent using the Almanac API.
+
+    Args:
+        destination (str): The destination address to look up.
+
+    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)
+
+    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:
+        response = requests.get(
+            url=f"{almanac_api}/agents/{agent_address}", timeout=DEFAULT_REQUEST_TIMEOUT
+        )
+        response.raise_for_status()
+    except requests.RequestException as e:
+        request_meta["exception"] = e
+        logger.error(msg="Error looking up agent endpoint", extra=request_meta)
+        return []
+
+    request_meta["response_status"] = response.status_code
+    logger.info(
+        msg="Got response looking up agent endpoint",
+        extra=request_meta,
+    )
+
+    endpoints: list = response.json().get("endpoints", [])
+
+    if len(endpoints) > 0:
+        urls = [val.get("url") for val in endpoints]
+        weights = [val.get("weight") for val in endpoints]
+        return weighted_random_sample(
+            items=urls,
+            weights=weights,
+            k=min(max_endpoints, len(endpoints)),
+        )
+
+    return []

{uagents_core-0.1.2.dist-info → uagents_core-0.2.0.dist-info}/METADATA

@@ -1,27 +1,27 @@
 Metadata-Version: 2.3
 Name: uagents-core
-Version: 0.1.2
+Version: 0.2.0
 Summary: Core components for agent based systems
 License: Apache 2.0
 Author: Ed FitzGerald
 Author-email: edward.fitzgerald@fetch.ai
-Requires-Python: >=3.9,<3.13
+Requires-Python: >=3.10,<4.0
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: aiohttp (>=3.8.3,<4.0.0)
-Requires-Dist: bech32 (>=1.2.0,<2.0.0)
-Requires-Dist: ecdsa (>=0.19.0,<0.20.0)
-Requires-Dist: msgpack (>=1.0.4,<2.0.0)
-Requires-Dist: pydantic (>=2.8,<2.9)
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: bech32 (>=1.2.0,<2.0)
+Requires-Dist: ecdsa (>=0.19.0,<1.0)
+Requires-Dist: pydantic (>=2.8,<3.0)
 Requires-Dist: requests (>=2.32.3,<3.0)
-Requires-Dist: rich (>=13.9.4,<14.0.0)
-Requires-Dist: structlog (>=24.4.0,<25.0.0)
+Project-URL: Documentation, https://fetch.ai/docs
+Project-URL: Homepage, https://fetch.ai
+Project-URL: Repository, https://github.com/fetchai/uAgents
 Description-Content-Type: text/markdown
 
-# UAgents-Core
+# uAgents-Core
 
 Core definitions and functionalities to build agent which can interact and integrate with Fetch.ai ecosystem and agent marketplace.
+

uagents_core-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+uagents_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uagents_core/config.py,sha256=mvCXtvt_efDbmoTcw0JNHymWZGOtXxIYXlrooWfbY1Q,798
+uagents_core/contrib/protocols/chat/__init__.py,sha256=EAt2uQeaZtrSEdt2SiFyqFcC4nxKtyoJRaHhjKtwngw,3032
+uagents_core/contrib/protocols/subscriptions/__init__.py,sha256=HsxWzLOvP83a7RkHRx8y_uXTJzJtuuBcyRNj33TT7xA,1944
+uagents_core/envelope.py,sha256=eGq-Te-z2nRQVJIPqRdf-h48hGwg7IOKptIQZKYKqFU,3527
+uagents_core/helpers.py,sha256=Nfl3V5Vl_23O4Ewtwlsh0v5rxthkZPm6b4BvsLGDKn8,943
+uagents_core/identity.py,sha256=YHI3rromJ27DGF3X102MGkuvBIZ6usAaMutlDLdVaL0,6185
+uagents_core/logger.py,sha256=5XLs3-XpKDeoSwtAE5pEM9h6x3pUPNbb0T0J7KvFmG0,877
+uagents_core/models.py,sha256=fxsFjRochkJUdgPltT1HWgBl-9K-HVQWl8sSMVgeJFY,1066
+uagents_core/protocol.py,sha256=T9jasOkltne33E16Y7VrqcB2moWVsv-Qh4XLZotyz8g,5428
+uagents_core/registration.py,sha256=h7ha58H7XbLQ__qOHMKVnHShzMlWfd2xrK9fRdgfb9w,2953
+uagents_core/types.py,sha256=_W3EN1wEIRFxuhhBxyZxQH_dA_3AtoPPReIzrgcTUHc,1167
+uagents_core/utils/__init__.py,sha256=v0MaxDYCTtQlwbblEHCfLtbeTnA2hCmKKJk7mlcE20U,135
+uagents_core/utils/messages.py,sha256=O4Fk8KULi523ruynEw1ZxAxFKi4ex816R4a_Q1E24O8,5056
+uagents_core/utils/registration.py,sha256=ny_2Svz1RLgMcH0WgBlzWKhZnhN25Yuni2eHFksoMjU,9039
+uagents_core/utils/resolver.py,sha256=X18oe-WPU_6pfTc6x_Oa69kZQYCMidkaSeCs68Poaik,2169
+uagents_core-0.2.0.dist-info/METADATA,sha256=OAsIUaGEiH9rehxRlGedKly53jQk1-GjEqA7Q-cwud0,1009
+uagents_core-0.2.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+uagents_core-0.2.0.dist-info/RECORD,,

{uagents_core-0.1.2.dist-info → uagents_core-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.0.1
+Generator: poetry-core 2.1.1
 Root-Is-Purelib: true
 Tag: py3-none-any

uagents_core/communication.py

@@ -1,76 +0,0 @@
-import random
-from typing import Any, List, Optional, Tuple
-
-from uagents_core.config import (
-    AGENT_ADDRESS_LENGTH,
-    AGENT_PREFIX,
-)
-from uagents_core.crypto import is_user_address
-
-
-def weighted_random_sample(
-    items: List[Any], weights: Optional[List[float]] = None, k: int = 1, rng=random
-) -> List[Any]:
-    """
-    Weighted random sample from a list of items without replacement.
-
-    Ref: Efraimidis, Pavlos S. "Weighted random sampling over data streams."
-
-    Args:
-        items (List[Any]): The list of items to sample from.
-        weights (Optional[List[float]]): The optional list of weights for each item.
-        k (int): The number of items to sample.
-        rng (random): The random number generator.
-
-    Returns:
-        List[Any]: The sampled items.
-    """
-    if weights is None:
-        return rng.sample(items, k=k)
-    values = [rng.random() ** (1 / w) for w in weights]
-    order = sorted(range(len(items)), key=lambda i: values[i])
-    return [items[i] for i in order[-k:]]
-
-
-def is_valid_address(address: str) -> bool:
-    """
-    Check if the given string is a valid address.
-
-    Args:
-        address (str): The address to be checked.
-
-    Returns:
-        bool: True if the address is valid; False otherwise.
-    """
-    return is_user_address(address) or (
-        len(address) == AGENT_ADDRESS_LENGTH and address.startswith(AGENT_PREFIX)
-    )
-
-
-def parse_identifier(identifier: str) -> Tuple[str, str, str]:
-    """
-    Parse an agent identifier string into prefix, name, and address.
-
-    Args:
-        identifier (str): The identifier string to be parsed.
-
-    Returns:
-        Tuple[str, str, str]: A Tuple containing the prefix, name, and address as strings.
-    """
-
-    prefix = ""
-    name = ""
-    address = ""
-
-    if "://" in identifier:
-        prefix, identifier = identifier.split("://", 1)
-
-    if "/" in identifier:
-        name, identifier = identifier.split("/", 1)
-
-    if is_valid_address(identifier):
-        address = identifier
-    else:
-        name = identifier
-
-    return prefix, name, address