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

uagents_core/config.py

@@ -4,18 +4,29 @@ DEFAULT_AGENTVERSE_URL = "agentverse.ai"
 DEFAULT_ALMANAC_API_PATH = "/v1/almanac"
 DEFAULT_REGISTRATION_PATH = "/v1/agents"
 DEFAULT_CHALLENGE_PATH = "/v1/auth/challenge"
+DEFAULT_MAILBOX_PATH = "/v1/submit"
+DEFAULT_PROXY_PATH = "/v1/proxy/submit"
 
 DEFAULT_MAX_ENDPOINTS = 10
 
+DEFAULT_REQUEST_TIMEOUT = 10
+
 AGENT_ADDRESS_LENGTH = 65
 AGENT_PREFIX = "agent"
 
 
 class AgentverseConfig(BaseModel):
     base_url: str = DEFAULT_AGENTVERSE_URL
-    protocol: str = "https"
     http_prefix: str = "https"
 
     @property
     def url(self) -> str:
         return f"{self.http_prefix}://{self.base_url}"
+
+    @property
+    def mailbox_endpoint(self) -> str:
+        return f"{self.url}{DEFAULT_MAILBOX_PATH}"
+
+    @property
+    def proxy_endpoint(self) -> str:
+        return f"{self.url}{DEFAULT_PROXY_PATH}"

uagents_core/contrib/protocols/chat/__init__.py

@@ -0,0 +1,124 @@
+"""
+This module contains the protocol specification for the agent chat protocol.
+"""
+
+from datetime import datetime
+from typing import Literal, TypedDict
+
+from pydantic.v1 import UUID4
+
+from uagents_core.models import Model
+from uagents_core.protocol import ProtocolSpecification
+
+
+class Metadata(TypedDict):
+    # primarily used with the `Resource` model. This field specifies the mime_type of
+    # resource that is being referenced. A full list can be found at `docs/mime_types.md`
+    mime_type: str
+
+    # the role of the resource
+    role: str
+
+
+class TextContent(Model):
+    type: Literal["text"]
+
+    # The text of the content. The format of this field is UTF-8 encoded strings. Additionally,
+    # markdown based formatting can be used and will be supported by most clients
+    text: str
+
+
+class Resource(Model):
+    # the uri of the resource
+    uri: str
+
+    # the set of metadata for this resource, for more detailed description of the set of
+    # fields see `docs/metadata.md`
+    metadata: dict[str, str]
+
+
+class ResourceContent(Model):
+    type: Literal["resource"]
+
+    # The resource id
+    resource_id: UUID4
+
+    # The resource or list of resource for this content. typically only a single
+    # resource will be sent, however, if there are accompanying resources like
+    # thumbnails and audio tracks these can be additionally referenced
+    #
+    # In the case of the a list of resources, the first element of the list is always
+    # considered the primary resource
+    resource: Resource | list[Resource]
+
+
+class MetadataContent(Model):
+    type: Literal["metadata"]
+
+    # the set of metadata for this content, for more detailed description of the set of
+    # fields see `docs/metadata.md`
+    metadata: dict[str, str]
+
+
+class StartSessionContent(Model):
+    type: Literal["start-session"]
+
+
+class EndSessionContent(Model):
+    type: Literal["end-session"]
+
+
+class StartStreamContent(Model):
+    type: Literal["start-stream"]
+
+    stream_id: UUID4
+
+
+class EndStreamContent(Model):
+    type: Literal["end-stream"]
+
+    stream_id: UUID4
+
+
+# The combined agent content types
+AgentContent = (
+    TextContent
+    | ResourceContent
+    | MetadataContent
+    | StartSessionContent
+    | EndSessionContent
+    | StartStreamContent
+    | EndStreamContent
+)
+
+
+class ChatMessage(Model):
+    # the timestamp for the message, should be in UTC
+    timestamp: datetime
+
+    # a unique message id that is generated from the message instigator
+    msg_id: UUID4
+
+    # the list of content elements in the chat
+    content: list[AgentContent]
+
+
+class ChatAcknowledgement(Model):
+    # the timestamp for the message, should be in UTC
+    timestamp: datetime
+
+    # the msg id that is being acknowledged
+    acknowledged_msg_id: UUID4
+
+    # optional acknowledgement metadata
+    metadata: dict[str, str] | None = None
+
+
+chat_protocol_spec = ProtocolSpecification(
+    name="AgentChatProtocol",
+    version="0.3.0",
+    interactions={
+        ChatMessage: {ChatAcknowledgement},
+        ChatAcknowledgement: set(),
+    },
+)

uagents_core/contrib/protocols/subscriptions/__init__.py

@@ -0,0 +1,75 @@
+"""
+This module contains the protocol specification for agent subscription management.
+
+A chat agent that supports this protocol will be able to accept or reject paid
+subscription requests from other agents.
+"""
+
+from enum import Enum
+
+from uagents_core.models import Model
+from uagents_core.protocol import ProtocolSpecification
+
+
+class TierType(str, Enum):
+    FREE = "free"
+    PLUS = "plus"
+    PRO = "pro"
+
+
+class Tier(Model):
+    tier_id: str
+    tier_type: TierType
+    amount: str
+    currency: str
+
+
+class RequestAgentSubscriptionRenewal(Model):
+    # the system generated event id associated with this upgrade
+    update_id: str
+
+    # the tier this upgrade is subscribing to
+    tier: Tier
+
+
+class RequestAgentSubscriptionUpgrade(Model):
+    # the system generated event id associated with this upgrade
+    update_id: str
+
+    # the tier this upgrade is subscribing to
+    new_subscription: Tier
+
+    # previous subscription, None if it was the 'free' type
+    existing_subscription: Tier | None = None
+
+
+class AcceptAgentSubscriptionUpdate(Model):
+    # the update id associated with this upgrade
+    update_id: str
+
+
+class RejectAgentSubscriptionUpdate(Model):
+    # the update id associated with this upgrade
+    update_id: str
+
+
+subscription_protocol_spec = ProtocolSpecification(
+    name="AgentSubscriptionProtocol",
+    version="0.2.0",
+    interactions={
+        RequestAgentSubscriptionRenewal: {
+            AcceptAgentSubscriptionUpdate,
+            RejectAgentSubscriptionUpdate,
+        },
+        RequestAgentSubscriptionUpgrade: {
+            AcceptAgentSubscriptionUpdate,
+            RejectAgentSubscriptionUpdate,
+        },
+        AcceptAgentSubscriptionUpdate: set(),
+        RejectAgentSubscriptionUpdate: set(),
+    },
+    roles={
+        "requester": {AcceptAgentSubscriptionUpdate, RejectAgentSubscriptionUpdate},
+        "agent": {RequestAgentSubscriptionRenewal, RequestAgentSubscriptionUpgrade},
+    },
+)

uagents_core/envelope.py

@@ -3,17 +3,10 @@
 import base64
 import hashlib
 import struct
-import time
-from typing import List, Optional
 
-from pydantic import (
-    UUID4,
-    BaseModel,
-    Field,
-    field_serializer,
-)
+from pydantic import UUID4, BaseModel
 
-from uagents_core.crypto import Identity
+from uagents_core.identity import Identity
 from uagents_core.types import JsonStr
 
 
@@ -28,12 +21,12 @@ class Envelope(BaseModel):
         session (UUID4): The session UUID that persists for back-and-forth
         dialogues between agents.
         schema_digest (str): The schema digest for the enclosed message.
-        protocol_digest (Optional[str]): The digest of the protocol associated with the message
+        protocol_digest (str | None): The digest of the protocol associated with the message
         (optional).
-        payload (Optional[str]): The encoded message payload of the envelope (optional).
-        expires (Optional[int]): The expiration timestamp (optional).
-        nonce (Optional[int]): The nonce value (optional).
-        signature (Optional[str]): The envelope signature (optional).
+        payload (str | None): The encoded message payload of the envelope (optional).
+        expires (int | None): The expiration timestamp (optional).
+        nonce (int | None): The nonce value (optional).
+        signature (str | None): The envelope signature (optional).
     """
 
     version: int
@@ -41,13 +34,13 @@ class Envelope(BaseModel):
     target: str
     session: UUID4
     schema_digest: str
-    protocol_digest: Optional[str] = None
-    payload: Optional[str] = None
-    expires: Optional[int] = None
-    nonce: Optional[int] = None
-    signature: Optional[str] = None
+    protocol_digest: str | None = None
+    payload: str | None = None
+    expires: int | None = None
+    nonce: int | None = None
+    signature: str | None = None
 
-    def encode_payload(self, value: JsonStr):
+    def encode_payload(self, value: JsonStr) -> None:
         """
         Encode the payload value and store it in the envelope.
 
@@ -68,15 +61,12 @@ class Envelope(BaseModel):
 
         return base64.b64decode(self.payload).decode()
 
-    def sign(self, identity: Identity):
+    def sign(self, identity: Identity) -> None:
         """
-        Sign the envelope with the provided identity.
+        Sign the envelope using the provided agent identity.
 
         Args:
-            identity (Identity): The identity to use for signing.
-
-        Raises:
-            ValueError: If the signature cannot be computed.
+            identity (Identity): The agent identity to sign the envelope.
         """
         try:
             self.signature = identity.sign_digest(self._digest())
@@ -96,7 +86,9 @@ class Envelope(BaseModel):
         """
         if self.signature is None:
             raise ValueError("Envelope signature is missing")
-        return Identity.verify_digest(self.sender, self._digest(), self.signature)
+        return Identity.verify_digest(
+            address=self.sender, digest=self._digest(), signature=self.signature
+        )
 
     def _digest(self) -> bytes:
         """
@@ -117,47 +109,3 @@ class Envelope(BaseModel):
         if self.nonce is not None:
             hasher.update(struct.pack(">Q", self.nonce))
         return hasher.digest()
-
-
-class EnvelopeHistoryEntry(BaseModel):
-    timestamp: int = Field(default_factory=lambda: int(time.time()))
-    version: int
-    sender: str
-    target: str
-    session: UUID4
-    schema_digest: str
-    protocol_digest: Optional[str] = None
-    payload: Optional[str] = None
-
-    @field_serializer("session")
-    def serialize_session(self, session: UUID4, _info):
-        return str(session)
-
-    @classmethod
-    def from_envelope(cls, envelope: Envelope):
-        return cls(
-            version=envelope.version,
-            sender=envelope.sender,
-            target=envelope.target,
-            session=envelope.session,
-            schema_digest=envelope.schema_digest,
-            protocol_digest=envelope.protocol_digest,
-            payload=envelope.decode_payload(),
-        )
-
-
-class EnvelopeHistory(BaseModel):
-    envelopes: List[EnvelopeHistoryEntry]
-
-    def add_entry(self, entry: EnvelopeHistoryEntry):
-        self.envelopes.append(entry)
-        self.apply_retention_policy()
-
-    def apply_retention_policy(self):
-        """Remove entries older than 24 hours"""
-        cutoff_time = time.time() - 86400
-        for e in self.envelopes:
-            if e.timestamp < cutoff_time:
-                self.envelopes.remove(e)
-            else:
-                break

uagents_core/helpers.py

@@ -0,0 +1,30 @@
+from random import Random
+from typing import Any
+
+
+def weighted_random_sample(
+    items: list[Any],
+    weights: list[float] | None = None,
+    k: int = 1,
+    rng: Random | None = None,
+) -> 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 (list[float]] | None) 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.
+    """
+    rng = rng or Random()
+    if weights is None:
+        return rng.sample(items, k=k)
+    values: list[Any] = [rng.random() ** (1 / w) for w in weights]
+    order: list[int] = sorted(range(len(items)), key=lambda i: values[i])
+    return [items[i] for i in order[-k:]]

uagents_core/{crypto.py → identity.py}

@@ -2,24 +2,31 @@ import base64
 import hashlib
 import struct
 from secrets import token_bytes
-from typing import Tuple, Union
 
 import bech32
 import ecdsa
 from ecdsa.util import sigencode_string_canonize
 
+from uagents_core.config import AGENT_ADDRESS_LENGTH, AGENT_PREFIX
+
 USER_PREFIX = "user"
 SHA_LENGTH = 256
 
 
-def _decode_bech32(value: str) -> Tuple[str, bytes]:
+def _decode_bech32(value: str) -> tuple[str, bytes]:
     prefix, data_base5 = bech32.bech32_decode(value)
-    data = bytes(bech32.convertbits(data_base5, 5, 8, False))
-    return prefix, data
+    if not data_base5 or not prefix:
+        raise ValueError("Unable to decode value")
+    converted = bech32.convertbits(data_base5, 5, 8, False)
+    if not converted:
+        raise ValueError("Unable to convert value")
+    return prefix, bytes(converted)
 
 
 def _encode_bech32(prefix: str, value: bytes) -> str:
     value_base5 = bech32.convertbits(value, 8, 5)
+    if not value_base5:
+        raise ValueError("Unable to convert value")
     return bech32.bech32_encode(prefix, value_base5)
 
 
@@ -28,7 +35,7 @@ def is_user_address(address: str) -> bool:
 
 
 def generate_user_address() -> str:
-    return _encode_bech32(USER_PREFIX, token_bytes(32))
+    return _encode_bech32(prefix=USER_PREFIX, value=token_bytes(32))
 
 
 def _key_derivation_hash(prefix: str, index: int) -> bytes:
@@ -52,7 +59,7 @@ def derive_key_from_seed(seed, prefix, index) -> bytes:
     return hasher.digest()
 
 
-def encode_length_prefixed(value: Union[str, int, bytes]) -> bytes:
+def encode_length_prefixed(value: str | int | bytes) -> bytes:
     if isinstance(value, str):
         encoded = value.encode()
     elif isinstance(value, int):
@@ -76,7 +83,7 @@ class Identity:
         self._sk = signing_key
 
         # build the address
-        pub_key_bytes = self._sk.get_verifying_key().to_string(encoding="compressed")
+        pub_key_bytes = self._sk.get_verifying_key().to_string("compressed")  # type: ignore
         self._address = _encode_bech32("agent", pub_key_bytes)
         self._pub_key = pub_key_bytes.hex()
 
@@ -155,3 +162,46 @@ class Identity:
         verifying_key = ecdsa.VerifyingKey.from_string(pk_data, curve=ecdsa.SECP256k1)
 
         return verifying_key.verify_digest(sig_data, digest)
+
+
+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

uagents_core/logger.py

@@ -1,37 +1,36 @@
 import logging
-import os
-
-import structlog
-
-_log_level_map = {
-    "NOTSET": logging.NOTSET,
-    "DEBUG": logging.DEBUG,
-    "INFO": logging.INFO,
-    "WARNING": logging.WARNING,
-    "ERROR": logging.ERROR,
-    "CRITICAL": logging.CRITICAL,
-}
-
-_log_level = os.getenv("LOG_LEVEL", "INFO")
-
-
-structlog.configure(
-    processors=[
-        structlog.contextvars.merge_contextvars,
-        structlog.processors.add_log_level,
-        structlog.processors.StackInfoRenderer(),
-        structlog.dev.set_exc_info,
-        structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S", utc=False),
-        structlog.dev.ConsoleRenderer(),
-    ],
-    wrapper_class=structlog.make_filtering_bound_logger(
-        _log_level_map.get(_log_level, logging.INFO)
-    ),
-    context_class=dict,
-    logger_factory=structlog.PrintLoggerFactory(),
-    cache_logger_on_first_use=False,
+import sys
+
+logging.basicConfig(level=logging.INFO)
+
+
+formatter = logging.Formatter(
+    fmt="%(asctime)s,%(msecs)03d %(name)s %(levelname)s %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
 )
 
 
-def get_logger(logger_name: str):
-    return structlog.get_logger(logger_name)
+def get_logger(
+    logger_name: str | None = None,
+    level: int | str = logging.INFO,
+    log_file: str | None = "uagents_core.log",
+) -> logging.Logger:
+    """
+    Get a logger with the given name.
+
+    If no name is specified, the root logger is returned.
+    """
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(level)
+
+    log_handler = logging.StreamHandler(sys.stdout)
+    log_handler.setFormatter(formatter)
+    logger.addHandler(log_handler)
+
+    if log_file:
+        log_handler = logging.FileHandler(log_file)
+        log_handler.setFormatter(formatter)
+        logger.addHandler(log_handler)
+
+    logger.propagate = False
+    return logger

uagents_core/models.py

@@ -1,7 +1,8 @@
 import hashlib
-from typing import Any, Dict, Type, Union
+from typing import Any
 
 from pydantic.v1 import BaseModel, Field  # noqa
+from typing_extensions import Self
 
 
 # reverting back to pydantic v1 BaseModel for backwards compatibility
@@ -13,19 +14,19 @@ class Model(BaseModel):
     def model_dump_json(self) -> str:
         return self.json()
 
-    def model_dump(self) -> Dict[str, Any]:
+    def model_dump(self) -> dict[str, Any]:
         return self.dict()
 
     @classmethod
-    def model_validate_json(cls, obj: Any) -> "Model":
+    def model_validate_json(cls, obj: Any) -> Self:
         return cls.parse_raw(obj)
 
     @classmethod
-    def model_validate(cls, obj: Union[Dict[str, Any], "Model"]) -> "Model":
+    def model_validate(cls, obj: dict[str, Any] | Self) -> Self:
         return cls.parse_obj(obj)
 
     @staticmethod
-    def build_schema_digest(model: Union["Model", Type["Model"]]) -> str:
+    def build_schema_digest(model: BaseModel | type[BaseModel]) -> str:
         schema = model.schema_json(indent=None, sort_keys=True)
         digest = hashlib.sha256(schema.encode("utf8")).digest().hex()
 
@@ -36,3 +37,6 @@ class ErrorMessage(Model):
     """Error message model"""
 
     error: str
+
+
+ERROR_MESSAGE_DIGEST = Model.build_schema_digest(ErrorMessage)