uagents-core 0.3.2__tar.gz → 0.3.4__tar.gz

{uagents_core-0.3.2 → uagents_core-0.3.4}/PKG-INFO

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

{uagents_core-0.3.2 → uagents_core-0.3.4}/pyproject.toml

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

{uagents_core-0.3.2 → uagents_core-0.3.4}/uagents_core/config.py

@@ -7,6 +7,7 @@ DEFAULT_CHALLENGE_PATH = "/v1/auth/challenge"
 DEFAULT_MAILBOX_PATH = "/v1/submit"
 DEFAULT_PROXY_PATH = "/v1/proxy/submit"
 DEFAULT_STORAGE_PATH = "/v1/storage"
+DEFAULT_PAYMENTS_PATH = "/v1/payments"
 
 DEFAULT_MAX_ENDPOINTS = 10
 
@@ -35,3 +36,7 @@ class AgentverseConfig(BaseModel):
     @property
     def storage_endpoint(self) -> str:
         return f"{self.url}{DEFAULT_STORAGE_PATH}"
+
+    @property
+    def payments_endpoint(self) -> str:
+        return f"{self.url}{DEFAULT_PAYMENTS_PATH}"

{uagents_core-0.3.2 → uagents_core-0.3.4}/uagents_core/registration.py

@@ -73,6 +73,10 @@ class AgentRegistrationAttestation(VerifiableModel):
     metadata: dict[str, str | list[str] | dict[str, str]] | None = None
 
 
+class AgentRegistrationAttestationBatch(BaseModel):
+    attestations: list[AgentRegistrationAttestation]
+
+
 # Agentverse related models
 class RegistrationRequest(BaseModel):
     address: str

{uagents_core-0.3.2 → uagents_core-0.3.4}/uagents_core/storage.py

@@ -2,7 +2,6 @@ import base64
 import struct
 from datetime import datetime
 from secrets import token_bytes
-from typing import Optional
 
 import requests
 
@@ -34,38 +33,57 @@ def compute_attestation(
 class ExternalStorage:
     def __init__(
         self,
-        identity: Optional[Identity] = None,
-        storage_url: Optional[str] = None,
-        api_token: Optional[str] = None,
+        *,
+        identity: Identity | None = None,
+        storage_url: str | None = None,
+        api_token: str | None = None,
     ):
         self.identity = identity
         self.api_token = api_token
+        if not (identity or api_token):
+            raise ValueError(
+                "Either an identity or an API token must be provided for authentication"
+            )
         self.storage_url = storage_url or AgentverseConfig().storage_endpoint
 
     def _make_attestation(self) -> str:
         nonce = token_bytes(32)
         now = datetime.now()
-        return compute_attestation(self.identity, now, 3600, nonce)
+        if not self.identity:
+            raise RuntimeError("No identity available to create attestation")
+        return compute_attestation(
+            identity=self.identity,
+            validity_start=now,
+            validity_secs=3600,
+            nonce=nonce,
+        )
 
     def _get_auth_header(self) -> dict:
         if self.api_token:
             return {"Authorization": f"Bearer {self.api_token}"}
-        elif self.identity:
+        if self.identity:
             return {"Authorization": f"Agent {self._make_attestation()}"}
-        else:
-            raise RuntimeError("No identity or API token available for authentication")
+        raise RuntimeError("No identity or API token available for authentication")
 
     def upload(
-        self, asset_id: str, content: bytes, mime_type: str = "text/plain"
+        self,
+        asset_id: str,
+        asset_content: bytes,
+        mime_type: str = "text/plain",
     ) -> dict:
         url = f"{self.storage_url}/assets/{asset_id}/contents/"
         headers = self._get_auth_header()
         headers["Content-Type"] = "application/json"
         payload = {
-            "contents": base64.b64encode(content).decode(),
+            "contents": base64.b64encode(asset_content).decode(),
             "mime_type": mime_type,
         }
-        response = requests.put(url, json=payload, headers=headers)
+        response = requests.put(
+            url=url,
+            json=payload,
+            headers=headers,
+            timeout=10,
+        )
         if response.status_code != 200:
             raise RuntimeError(
                 f"Upload failed: {response.status_code}, {response.text}"
@@ -76,8 +94,11 @@ class ExternalStorage:
     def download(self, asset_id: str) -> dict:
         url = f"{self.storage_url}/assets/{asset_id}/contents/"
         headers = self._get_auth_header()
-
-        response = requests.get(url, headers=headers)
+        response = requests.get(
+            url=url,
+            headers=headers,
+            timeout=10,
+        )
         if response.status_code != 200:
             raise RuntimeError(
                 f"Download failed: {response.status_code}, {response.text}"
@@ -104,7 +125,12 @@ class ExternalStorage:
             "lifetime_hours": lifetime_hours,
         }
 
-        response = requests.post(url, json=payload, headers=headers)
+        response = requests.post(
+            url=url,
+            json=payload,
+            headers=headers,
+            timeout=10,
+        )
         if response.status_code != 201:
             raise RuntimeError(
                 f"Asset creation failed: {response.status_code}, {response.text}"
@@ -114,7 +140,7 @@ class ExternalStorage:
 
     def set_permissions(
         self, asset_id: str, agent_address: str, read: bool = True, write: bool = True
-    ):
+    ) -> dict:
         if not self.api_token:
             raise RuntimeError("API token required to set permissions")
         url = f"{self.storage_url}/assets/{asset_id}/permissions/"
@@ -126,7 +152,12 @@ class ExternalStorage:
             "write": write,
         }
 
-        response = requests.put(url, json=payload, headers=headers)
+        response = requests.put(
+            url=url,
+            json=payload,
+            headers=headers,
+            timeout=10,
+        )
         if response.status_code != 200:
             raise RuntimeError(
                 f"Set permissions failed: {response.status_code}, {response.text}"

{uagents_core-0.3.2 → uagents_core-0.3.4}/uagents_core/utils/registration.py

@@ -19,6 +19,7 @@ from uagents_core.logger import get_logger
 from uagents_core.protocol import is_valid_protocol_digest
 from uagents_core.registration import (
     AgentRegistrationAttestation,
+    AgentRegistrationAttestationBatch,
     AgentStatusUpdate,
     AgentUpdates,
     AgentverseConnectRequest,
@@ -27,11 +28,33 @@ from uagents_core.registration import (
     RegistrationRequest,
     RegistrationResponse,
 )
-from uagents_core.types import AgentEndpoint
+from uagents_core.types import AddressPrefix, AgentEndpoint
 
 logger = get_logger("uagents_core.utils.registration")
 
 
+class AgentRegistrationInput:
+    identity: Identity
+    prefix: str | None = None
+    endpoints: list[str]
+    protocol_digests: list[str]
+    metadata: dict[str, str | list[str] | dict[str, str]] | None = None
+
+    def __init__(
+        self,
+        identity: Identity,
+        endpoints: list[str],
+        protocol_digests: list[str],
+        prefix: AddressPrefix | None = None,
+        metadata: dict[str, str | list[str] | dict[str, str]] | None = None,
+    ):
+        self.identity = identity
+        self.prefix = prefix
+        self.endpoints = endpoints
+        self.protocol_digests = protocol_digests
+        self.metadata = metadata
+
+
 def _send_post_request(
     url: str,
     data: BaseModel,
@@ -63,11 +86,32 @@ def _send_post_request(
     return False, None
 
 
+def _build_signed_attestation(
+    item: AgentRegistrationInput,
+) -> AgentRegistrationAttestation:
+    agent_endpoints: list[AgentEndpoint] = [
+        AgentEndpoint(url=endpoint, weight=1) for endpoint in item.endpoints
+    ]
+
+    attestation = AgentRegistrationAttestation(
+        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,
+    )
+
+    attestation.sign(item.identity)
+    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,
@@ -77,6 +121,7 @@ def register_in_almanac(
 
     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
@@ -95,10 +140,6 @@ def register_in_almanac(
             )
             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):
@@ -112,22 +153,18 @@ def register_in_almanac(
     agentverse_config = agentverse_config or AgentverseConfig()
     almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
 
-    # get the agent address
-    agent_address = identity.address
-
     # create the attestation
-    attestation = AgentRegistrationAttestation(
-        agent_identifier=agent_address,
-        protocols=protocol_digests,
-        endpoints=agent_endpoints,
+    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())
 
-    # sign the attestation
-    attestation.sign(identity)
-
     # submit the attestation to the API
     status, _ = _send_post_request(
         url=f"{almanac_api}/agents", data=attestation, timeout=timeout
@@ -135,6 +172,94 @@ def register_in_almanac(
     return status
 
 
+def register_batch_in_almanac(
+    items: list[AgentRegistrationInput],
+    *,
+    agentverse_config: AgentverseConfig | None = None,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
+    validate_all_before_registration: bool = False,
+) -> tuple[bool, list[str]]:
+    """
+    Register multiple identities with the Almanac API to make them discoverable by other agents.
+
+    The return value is a 2-tuple including:
+    * (bool) Whether the registration request was both attempted and successful.
+    * (list[str]) A list of addresses of identities that failed validation.
+
+    If `validate_all_before_registration` is `True`, no registration request will be sent
+    unless all identities pass validation.
+
+    Args:
+        items (list[AgentRegistrationInput]): The list of identities to register.
+            See `register_in_almanac` for details about attributes in `AgentRegistrationInput`.
+        agentverse_config (AgentverseConfig): The configuration for the agentverse API
+        timeout (int): The timeout for the request
+    """
+    invalid_identities: list[str] = []
+    attestations: list[AgentRegistrationAttestation] = []
+
+    for item in items:
+        # check endpoints
+        if not item.endpoints:
+            logger.warning(
+                f"No endpoints provided for {item.identity.address}; skipping registration",
+            )
+            invalid_identities.append(item.identity.address)
+        for endpoint in item.endpoints:
+            result = urllib.parse.urlparse(endpoint)
+            if not all([result.scheme, result.netloc]):
+                logger.error(
+                    msg=f"Invalid endpoint provided for {item.identity.address}; "
+                    + "skipping registration",
+                    extra={"endpoint": endpoint},
+                )
+                invalid_identities.append(item.identity.address)
+
+        # check protocol digests
+        for proto_digest in item.protocol_digests:
+            if not is_valid_protocol_digest(proto_digest):
+                logger.error(
+                    msg=f"Invalid protocol digest provided for {item.identity.address}; "
+                    + "skipping registration",
+                    extra={"protocol_digest": proto_digest},
+                )
+                invalid_identities.append(item.identity.address)
+
+    # Remove duplicates
+    invalid_identities = sorted(list(set(invalid_identities)))
+
+    for item in items:
+        if item.identity.address not in invalid_identities:
+            attestations.append(_build_signed_attestation(item))
+
+    if validate_all_before_registration and invalid_identities:
+        return False, invalid_identities
+
+    # get the almanac API endpoint
+    agentverse_config = agentverse_config or AgentverseConfig()
+    almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
+
+    logger.info(
+        msg="Bulk registering with Almanac API",
+        extra={
+            "agent_addresses": [
+                attestation.agent_identifier for attestation in attestations
+            ]
+        },
+    )
+    attestation_batch = AgentRegistrationAttestationBatch(
+        attestations=attestations,
+    )
+
+    # 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
+
+
 # associate user account with your agent
 def register_in_agentverse(
     request: AgentverseConnectRequest,

uagents_core-0.3.4/uagents_core/utils/subscriptions.py

@@ -0,0 +1,82 @@
+"""
+This module provides methods related to agent bases subscriptions.
+
+Example usage:
+```
+from uagents_core.contrib.protocols.subscriptions import TierType
+
+@protocol.on_message(ChatMessage)
+async def handle_message(ctx: Context, sender: str, msg: ChatMessage):
+    subscription_tier = get_subscription_tier(
+        identity=ctx.agent.identity,
+        requester_address=sender
+    )
+
+    if subscription_tier == TierType.PLUS:
+        ...
+
+    if subscription_tier == TierType.PRO:
+        ...
+
+    ...
+```
+
+"""
+
+from datetime import datetime
+from secrets import token_bytes
+
+import requests
+
+from uagents_core.config import AgentverseConfig
+from uagents_core.contrib.protocols.subscriptions import TierType
+from uagents_core.identity import Identity
+from uagents_core.logger import get_logger
+from uagents_core.storage import compute_attestation
+
+logger = get_logger("uagents_core.utils.subscriptions")
+
+
+def get_subscription_tier(
+    identity: Identity,
+    requester_address: str,
+    agentverse_config: AgentverseConfig | None = None,
+) -> TierType:
+    """
+    Get the subscription tier of the requester for a specific agent.
+
+    This function is used to verify the type of subscription before processing
+    an incoming message.
+
+    Args:
+        identity (Identity): The identity of the agent that is requested.
+        requester_address (str): The address of the requester to check.
+        agentverse_config (AgentverseConfig | None): The configuration for the Agentverse.
+            If not provided, defaults to a new instance of AgentverseConfig.
+
+    Returns:
+        TierType: The subscription tier type of the requester.
+    """
+    if not agentverse_config:
+        agentverse_config = AgentverseConfig()
+    attestation: str = compute_attestation(
+        identity=identity,
+        validity_start=datetime.now(),
+        validity_secs=60,
+        nonce=token_bytes(nbytes=32),
+    )
+    url: str = (
+        f"{agentverse_config.payments_endpoint}/subscriptions"
+        + f"/{identity.address}/{requester_address}"
+    )
+    headers: dict[str, str] = {"Authorization": f"Agent {attestation}"}
+
+    try:
+        response = requests.get(url=url, headers=headers, timeout=10)
+        response.raise_for_status()
+    except requests.RequestException as e:
+        logger.error(f"Failed to get subscription tier: {e}")
+        return TierType.FREE
+
+    data: dict = response.json()
+    return data.get("tier_type", TierType.FREE)