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

uagents_core/protocol.py

@@ -0,0 +1,166 @@
+import copy
+import hashlib
+import json
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ValidationInfo, field_validator
+
+from uagents_core.models import Model
+
+
+class ProtocolSpecification(BaseModel):
+    """
+    Specification for the interactions and roles of a protocol.
+
+    Args:
+        name (str): The name of the protocol.
+        version (str): The version of the protocol.
+        interactions (dict[type[Model], set[type[Model]]]): A mapping of models
+            to the corresponding set of models that are valid replies.
+        roles (dict[str, set[type[Model]]] | None): A mapping of role names to the set of
+            incoming message models that role needs to be implement handlers for.
+            If None, all models can be implemented by all roles.
+    """
+
+    name: str = ""
+    version: str = "0.1.0"
+    interactions: dict[type[Model], set[type[Model]]]
+    roles: dict[str, set[type[Model]]] | None = None
+
+    SPEC_VERSION: ClassVar = "1.0"
+
+    @field_validator("roles")
+    @classmethod
+    def validate_roles(cls, roles, info: ValidationInfo):
+        """
+        Ensure that all models included in roles are also included in the interactions.
+        """
+        if roles is None:
+            return roles
+
+        interactions: dict[type[Model], set[type[Model]]] = info.data["interactions"]
+        interaction_models = set(interactions.keys())
+
+        for role, models in roles.items():
+            invalid_models = models - interaction_models
+            if invalid_models:
+                model_names = [model.__name__ for model in invalid_models]
+                raise ValueError(
+                    f"Role '{role}' contains models that don't "
+                    f"exist in interactions: {model_names}"
+                )
+        return roles
+
+    @property
+    def digest(self) -> str:
+        """
+        Property to access the digest of the protocol's manifest.
+
+        Returns:
+            str: The digest of the protocol's manifest.
+        """
+        return self.manifest()["metadata"]["digest"]
+
+    def manifest(self, role: str | None = None) -> dict[str, Any]:
+        """
+        Generate the protocol's manifest, a long-form machine readable description of the
+        protocol details and interface.
+
+        Returns:
+            dict[str, Any]: The protocol's manifest.
+        """
+        metadata = {
+            "name": self.name,
+            "version": self.version,
+        }
+
+        manifest = {
+            "version": "1.0",
+            "metadata": {},
+            "models": [],
+            "interactions": [],
+        }
+
+        if self.roles and role is not None:
+            interactions = {
+                model: replies
+                for model, replies in self.interactions.items()
+                if model in self.roles[role]
+            }
+        else:
+            interactions = self.interactions
+
+        all_models: dict[str, type[Model]] = {}
+        reply_rules: dict[str, dict[str, type[Model]]] = {}
+
+        for model, replies in interactions.items():
+            model_digest = Model.build_schema_digest(model)
+            all_models[model_digest] = model
+            if len(replies) == 0:
+                reply_rules[model_digest] = {}
+            else:
+                for reply in replies:
+                    reply_digest = Model.build_schema_digest(reply)
+                    all_models[reply_digest] = reply
+                    if model_digest in reply_rules:
+                        reply_rules[model_digest][reply_digest] = reply
+                    else:
+                        reply_rules[model_digest] = {reply_digest: reply}
+
+        for schema_digest, model in all_models.items():
+            manifest["models"].append(
+                {"digest": schema_digest, "schema": model.schema()}
+            )
+
+        for request, responses in reply_rules.items():
+            manifest["interactions"].append(
+                {
+                    "type": "normal",
+                    "request": request,
+                    "responses": sorted(list(responses.keys())),
+                }
+            )
+
+        metadata["digest"] = self.compute_digest(manifest)
+
+        final_manifest: dict[str, Any] = copy.deepcopy(manifest)
+        final_manifest["metadata"] = metadata
+
+        return final_manifest
+
+    @staticmethod
+    def compute_digest(manifest: dict[str, Any]) -> str:
+        """
+        Compute the digest of a given manifest.
+
+        Args:
+            manifest (dict[str, Any]): The manifest to compute the digest for.
+
+        Returns:
+            str: The computed digest.
+        """
+        cleaned_manifest = {
+            "version": manifest["version"],
+            "metadata": {},
+            "models": sorted(manifest["models"], key=lambda x: x["digest"]),
+            "interactions": sorted(
+                manifest["interactions"], key=lambda x: x["request"]
+            ),
+        }
+        encoded: bytes = json.dumps(
+            obj=cleaned_manifest, indent=None, sort_keys=True
+        ).encode("utf8")
+        return f"proto:{hashlib.sha256(encoded).digest().hex()}"
+
+
+def is_valid_protocol_digest(digest: str) -> bool:
+    """
+    Check if the given string is a valid protocol digest.
+
+    Args:
+        digest (str): The digest to be checked.
+
+    Returns:
+        bool: True if the digest is valid; False otherwise.
+    """
+    return len(digest) == 70 and digest.startswith("proto:")

uagents_core/registration.py

@@ -1,21 +1,47 @@
 import hashlib
 import json
 import time
-from typing import Dict, List, Optional, Union
+from abc import ABC, abstractmethod
+from typing import Any
 
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, Field
 
-from uagents_core.crypto import Identity
-from uagents_core.types import AddressPrefix, AgentEndpoint, AgentType
-from uagents_core.utils.communication import parse_identifier
+from uagents_core.identity import Identity, parse_identifier
+from uagents_core.types import AddressPrefix, AgentEndpoint, AgentInfo, AgentType
 
 
+class AgentRegistrationPolicy(ABC):
+    @abstractmethod
+    async def register(
+        self,
+        agent_identifier: str,
+        identity: Identity,
+        protocols: list[str],
+        endpoints: list[AgentEndpoint],
+        metadata: dict[str, Any] | None = None,
+    ):
+        raise NotImplementedError
+
+
+class BatchRegistrationPolicy(ABC):
+    @abstractmethod
+    async def register(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def add_agent(self, agent_info: AgentInfo, identity: Identity):
+        raise NotImplementedError
+
+
+# Registration models
 class VerifiableModel(BaseModel):
-    agent_identifier: str
-    signature: Optional[str] = None
-    timestamp: Optional[int] = None
+    agent_identifier: str = Field(
+        validation_alias=AliasChoices("agent_identifier", "agent_address")
+    )
+    signature: str | None = None
+    timestamp: int | None = None
 
-    def sign(self, identity: Identity):
+    def sign(self, identity: Identity) -> None:
         self.timestamp = int(time.time())
         digest = self._build_digest()
         self.signature = identity.sign_digest(digest)
@@ -23,7 +49,9 @@ class VerifiableModel(BaseModel):
     def verify(self) -> bool:
         _, _, agent_address = parse_identifier(self.agent_identifier)
         return self.signature is not None and Identity.verify_digest(
-            agent_address, self._build_digest(), self.signature
+            address=agent_address,
+            digest=self._build_digest(),
+            signature=self.signature,
         )
 
     def _build_digest(self) -> bytes:
@@ -38,25 +66,27 @@ class VerifiableModel(BaseModel):
         return sha256.digest()
 
 
+# AlmanacAPI related models
 class AgentRegistrationAttestation(VerifiableModel):
-    protocols: List[str]
-    endpoints: List[AgentEndpoint]
-    metadata: Optional[Dict[str, Union[str, Dict[str, str]]]] = None
+    protocols: list[str]
+    endpoints: list[AgentEndpoint]
+    metadata: dict[str, str | dict[str, str]] | None = None
 
 
+# Agentverse related models
 class RegistrationRequest(BaseModel):
     address: str
-    prefix: Optional[AddressPrefix] = "test-agent"
+    prefix: AddressPrefix | None = "test-agent"
     challenge: str
     challenge_response: str
     agent_type: AgentType
-    endpoint: Optional[str] = None
+    endpoint: str | None = None
 
 
 class AgentverseConnectRequest(BaseModel):
     user_token: str
     agent_type: AgentType
-    endpoint: Optional[str] = None
+    endpoint: str | None = None
 
 
 class RegistrationResponse(BaseModel):
@@ -73,6 +103,7 @@ class ChallengeResponse(BaseModel):
 
 class AgentUpdates(BaseModel):
     name: str = Field(min_length=1, max_length=80)
-    readme: Optional[str] = Field(default=None, max_length=80000)
-    avatar_url: Optional[str] = Field(default=None, max_length=4000)
-    agent_type: Optional[AgentType] = "custom"
+    readme: str | None = Field(default=None, max_length=80000)
+    avatar_url: str | None = Field(default=None, max_length=4000)
+    short_description: str | None = Field(default=None, max_length=300)
+    agent_type: AgentType | None = "custom"

uagents_core/types.py

@@ -1,14 +1,50 @@
-from typing import Literal
+import uuid
+from enum import Enum
+from typing import Any, Literal
 
 from pydantic import BaseModel
 
 JsonStr = str
 
 AgentType = Literal["mailbox", "proxy", "custom"]
-
 AddressPrefix = Literal["agent", "test-agent"]
 
 
 class AgentEndpoint(BaseModel):
     url: str
     weight: int
+
+
+class AgentInfo(BaseModel):
+    address: str
+    prefix: AddressPrefix
+    endpoints: list[AgentEndpoint]
+    protocols: list[str]
+    metadata: dict[str, Any] | None = None
+
+
+class DeliveryStatus(str, Enum):
+    """Delivery status of a message."""
+
+    SENT = "sent"
+    DELIVERED = "delivered"
+    FAILED = "failed"
+
+
+class MsgStatus(BaseModel):
+    """
+    Represents the status of a sent message.
+
+    Attributes:
+        status (str): The delivery status of the message {'sent', 'delivered', 'failed'}.
+        detail (str): The details of the message delivery.
+        destination (str): The destination address of the message.
+        endpoint (str): The endpoint the message was sent to.
+        session (uuid.UUID | None): The session ID of the message.
+    """
+
+    status: DeliveryStatus
+    detail: str
+    destination: str
+    endpoint: str
+    session: uuid.UUID | None = None

uagents_core/utils/__init__.py

@@ -0,0 +1,5 @@
+"""
+Helper functions for working with the Fetch.ai uagents-core package.
+
+All methods in this module act synchronously / blocking.
+"""

uagents_core/utils/messages.py

@@ -0,0 +1,153 @@
+"""
+This module provides methods to enable an identity to interact with other agents.
+"""
+
+import json
+from typing import Any, Literal
+from uuid import UUID, uuid4
+
+import requests
+
+from uagents_core.config import DEFAULT_REQUEST_TIMEOUT, AgentverseConfig
+from uagents_core.envelope import Envelope
+from uagents_core.helpers import weighted_random_sample
+from uagents_core.identity import Identity
+from uagents_core.logger import get_logger
+from uagents_core.models import Model
+from uagents_core.types import DeliveryStatus, MsgStatus
+from uagents_core.utils.resolver import lookup_endpoint_for_agent
+
+logger = get_logger("uagents_core.utils.messages")
+
+
+def generate_message_envelope(
+    destination: str,
+    message_schema_digest: str,
+    message_body: Any,
+    sender: Identity,
+    *,
+    session_id: UUID | None = None,
+    protocol_digest: str | None = None,
+) -> Envelope:
+    """
+    Generate an envelope for a message to be sent to an agent.
+
+    Args:
+        destination (str): The address of the target agent.
+        message_schema_digest (str): The digest of the model that is being used
+        message_body (Any): The payload of the message.
+        sender (Identity): The identity of the sender.
+        session (UUID): The unique identifier for the dialogue between two agents
+        protocol_digest (str): The digest of the protocol that is being used
+    """
+    json_payload = json.dumps(message_body, separators=(",", ":"))
+
+    env = Envelope(
+        version=1,
+        sender=sender.address,
+        target=destination,
+        session=session_id or uuid4(),
+        schema_digest=message_schema_digest,
+        protocol_digest=protocol_digest,
+    )
+
+    env.encode_payload(json_payload)
+    env.sign(sender)
+
+    return env
+
+
+def send_message(
+    endpoint: str, envelope: Envelope, timeout: int = DEFAULT_REQUEST_TIMEOUT
+) -> requests.Response:
+    """
+    A helper function to send a message to an agent.
+
+    Args:
+        endpoint (str): The endpoint to send the message to.
+        envelope (Envelope): The envelope containing the message.
+        timeout (int, optional): Requests timeout. Defaults to DEFAULT_REQUEST_TIMEOUT.
+
+    Returns:
+        requests.Response: Response object from the request.
+    """
+    response = requests.post(
+        url=endpoint,
+        headers={"content-type": "application/json"},
+        data=envelope.model_dump_json(),
+        timeout=timeout,
+    )
+    response.raise_for_status()
+    return response
+
+
+def send_message_to_agent(
+    destination: str,
+    msg: Model,
+    sender: Identity,
+    *,
+    session_id: UUID | None = None,
+    strategy: Literal["first", "random", "all"] = "first",
+    agentverse_config: AgentverseConfig | None = None,
+) -> list[MsgStatus]:
+    """
+    Send a message to an agent with default settings.
+
+    Args:
+        destination (str): The address of the target agent.
+        msg (Model): The message to be sent.
+        sender (Identity): The identity of the sender.
+        session_id (UUID, optional): The unique identifier for the dialogue between two agents.
+        strategy (Literal["first", "random", "all"], optional): The strategy to use when
+            selecting an endpoint.
+        agentverse_config (AgentverseConfig, optional): The configuration for the agentverse.
+    """
+    agentverse_config = agentverse_config or AgentverseConfig()
+    endpoints = lookup_endpoint_for_agent(
+        agent_identifier=destination, agentverse_config=agentverse_config
+    )
+    if not endpoints:
+        logger.error("No endpoints found for agent", extra={"destination": destination})
+        return []
+
+    env = generate_message_envelope(
+        destination=destination,
+        message_schema_digest=Model.build_schema_digest(msg),
+        message_body=msg.model_dump(),
+        sender=sender,
+        session_id=session_id,
+    )
+    match strategy:
+        case "first":
+            endpoints = endpoints[:1]
+        case "random":
+            endpoints = weighted_random_sample(endpoints)
+
+    endpoints: list[str] = endpoints if strategy == "all" else endpoints[:1]
+
+    result: list[MsgStatus] = []
+    for endpoint in endpoints:
+        try:
+            response = send_message(endpoint, env)
+            logger.info("Sent message to agent", extra={"agent_endpoint": endpoint})
+            result.append(
+                MsgStatus(
+                    status=DeliveryStatus.SENT,
+                    detail=response.text,
+                    destination=destination,
+                    endpoint=endpoint,
+                    session=env.session,
+                )
+            )
+        except requests.RequestException as e:
+            logger.error("Failed to send message to agent", extra={"error": str(e)})
+            result.append(
+                MsgStatus(
+                    status=DeliveryStatus.FAILED,
+                    detail=response.text,
+                    destination=destination,
+                    endpoint=endpoint,
+                    session=env.session,
+                )
+            )
+    return result