agentverse-sdk 0.1.0__py3-none-any.whl

agentverse_sdk/__init__.py

@@ -0,0 +1,3 @@
+"""Agentverse SDK — connect any AI agent framework to Agentverse."""
+
+__version__ = "0.1.0"

agentverse_sdk/_common/av.py

@@ -0,0 +1,160 @@
+import json
+import logging
+from datetime import datetime, timezone
+from secrets import token_bytes
+from uuid import UUID
+
+import httpx
+import requests
+from pydantic import BaseModel
+from uagents_core.config import AgentverseConfig
+from uagents_core.contrib.protocols.chat import chat_protocol_spec
+from uagents_core.envelope import Envelope
+from uagents_core.identity import Identity, is_user_address
+from uagents_core.models import Model
+from uagents_core.protocol import ProtocolSpecification
+from uagents_core.registration import AgentStatusUpdate, RegistrationRequest
+from uagents_core.storage import compute_attestation
+from uagents_core.types import JsonStr
+from uagents_core.utils.messages import generate_message_envelope, parse_envelope_raw
+from uagents_core.utils.registration import (
+    _send_post_request_agentverse,
+)
+from uagents_core.utils.resolver import AlmanacResolver
+
+from agentverse_sdk._common.config import (
+    AGENT_AUTH_TOKEN_VALIDITY,
+    DEFAULT_HTTP_REQUESTS_TIMEOUT,
+)
+
+CHAT_PROTOCOL = ProtocolSpecification.compute_digest(chat_protocol_spec.manifest())
+
+
+for ch in ["uagents_core.utils.resolver", "uagents_core.utils.messages", "httpx"]:
+    logging.getLogger(ch).setLevel(logging.CRITICAL)
+
+
+def generate_agent_auth_token(id: Identity) -> str:
+    return compute_attestation(
+        id, datetime.now(timezone.utc), AGENT_AUTH_TOKEN_VALIDITY, token_bytes(32)
+    )
+
+
+def register_to_agentverse_sync(
+    request: RegistrationRequest,
+    headers: dict[str, str],
+    agentverse: AgentverseConfig,
+    timeout: int = DEFAULT_HTTP_REQUESTS_TIMEOUT,
+):
+    _send_post_request_agentverse(
+        url=agentverse.agents_api,
+        data=request,
+        headers=headers,
+        timeout=timeout,
+    )
+
+
+def verify_envelope(envelope: Envelope) -> bool:
+    try:
+        if is_user_address(envelope.sender):
+            return True
+        return envelope.verify()
+    except Exception:
+        return False
+
+
+async def set_agent_status(
+    agent: Identity,
+    active: bool,
+    agentverse: AgentverseConfig,
+    timeout: int = DEFAULT_HTTP_REQUESTS_TIMEOUT,
+):
+    update = AgentStatusUpdate(agent_identifier=agent.address, is_active=active)
+    update.sign(agent)
+
+    await _post_data(
+        url=f"{agentverse.almanac_api}/agents/{agent.address}/status",
+        data=update,
+        timeout=timeout,
+    )
+
+
+async def _post_data(
+    url: str,
+    data: BaseModel,
+    headers: dict[str, str] | None = None,
+    timeout: int = DEFAULT_HTTP_REQUESTS_TIMEOUT,
+) -> httpx.Response:
+    headers = headers or dict()
+    headers["Content-Type"] = "application/json"
+
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        response = await client.post(
+            url=url,
+            data=data.model_dump_json(),
+            headers=headers,
+        )
+        response.raise_for_status()
+
+        return response
+
+
+async def send_message_to_agent(
+    destination: str,
+    msg: Model,
+    sender: Identity,
+    *,
+    session_id: UUID | None = None,
+    agentverse_config: AgentverseConfig,
+    sync: bool = False,
+    timeout: int = DEFAULT_HTTP_REQUESTS_TIMEOUT,
+    response_type: type[Model] | set[type[Model]] | None = None,
+) -> Model | JsonStr | None:
+    resolver = AlmanacResolver(agentverse_config=agentverse_config)
+    _, endpoints = await resolver.resolve(destination)
+    if len(endpoints) == 0:
+        raise RuntimeError(f"Couldn't resolve endpoint for agent {destination}")
+
+    env = generate_message_envelope(
+        destination=destination,
+        message_schema_digest=Model.build_schema_digest(msg),
+        message_body=json.loads(msg.model_dump_json()),
+        sender=sender,
+        session_id=session_id,
+    )
+
+    headers = None
+    if sync:
+        headers = {"x-uagents-connection": "sync"}
+
+    response = await _post_data(
+        url=endpoints[0],
+        data=env,
+        headers=headers,
+        timeout=timeout,
+    )
+
+    if response.is_success and sync:
+        return parse_envelope_raw(response.text, response_type)
+
+    return None
+
+
+def _post_data_sync(
+    url: str,
+    data: BaseModel,
+    headers: dict[str, str] | None = None,
+    timeout: int = DEFAULT_HTTP_REQUESTS_TIMEOUT,
+) -> requests.Response:
+    headers = headers or dict()
+    headers["Content-Type"] = "application/json"
+
+    response = requests.post(
+        url=url,
+        data=json.dumps(data.model_dump(mode="json")),
+        headers=headers,
+        timeout=timeout,
+    )
+    response.raise_for_status()
+
+    return response

agentverse_sdk/_common/config.py

@@ -0,0 +1,4 @@
+DEFAULT_AGENTVERSE_CHAT_ENDPOINT = "/av/chat"
+DEFAULT_HTTP_REQUESTS_TIMEOUT = 10
+AGENT_AUTH_TOKEN_VALIDITY = 60 * 2
+DEFAULT_EMPTY_RESPONSE_TEXT = "Agent returned no response."

agentverse_sdk/_common/events.py

@@ -0,0 +1,210 @@
+import contextlib
+import functools
+import traceback
+from contextlib import asynccontextmanager
+from typing import Callable
+from uuid import uuid4
+
+from requests import HTTPError
+from uagents_core.contrib.protocols.chat import ChatMessage, TextContent
+from uagents_core.envelope import Envelope
+
+from agentverse_sdk._common.av import (
+    _post_data,
+    _post_data_sync,
+    generate_agent_auth_token,
+    send_message_to_agent,
+)
+from agentverse_sdk._common.helpers import utc_now
+from agentverse_sdk._common.logger import log_sdk, logger
+from agentverse_sdk._common.types import (
+    AgentBatchEvents,
+    AgentContext,
+    AgentStarletteState,
+    AgentUri,
+    EventCategory,
+)
+
+FAILED_INIT_ERROR_FORMAT = "Failed to initialize agentverse sdk ({})"
+
+
+def get_agent_address(agent: str | AgentUri) -> str | None:
+    if isinstance(agent, str):
+        try:
+            agent = AgentUri.from_str(agent)
+        except Exception:
+            return None
+
+    return agent.identity.address
+
+
+def _dispatch_event_sync(
+    agent: AgentUri | AgentStarletteState, events: AgentBatchEvents
+):
+    _post_data_sync(
+        url=f"{agent.agentverse.url}/v1/events",
+        data=events,
+        headers={"Authorization": f"Agent {generate_agent_auth_token(agent.identity)}"},
+    )
+
+
+async def dispatch_event(
+    agent: AgentUri | AgentStarletteState, events: AgentBatchEvents
+):
+    await _post_data(
+        url=f"{agent.agentverse.url}/v1/events",
+        data=events,
+        headers={"Authorization": f"Agent {generate_agent_auth_token(agent.identity)}"},
+    )
+
+
+@contextlib.contextmanager
+def handle_init_errors(uri: AgentUri):
+    try:
+        yield
+    except Exception as e:
+        logger.error("Init error suppressed: %s", e)
+        event = AgentBatchEvents.from_exception(e, traceback.format_exc())
+        try:
+            _dispatch_event_sync(uri, event)
+        except HTTPError as dispatch_exception:
+            log_sdk(
+                FAILED_INIT_ERROR_FORMAT.format(
+                    f"{dispatch_exception.response.status_code} at {utc_now().timestamp()}"
+                )
+            )
+        except Exception as generic_exception:
+            log_sdk(FAILED_INIT_ERROR_FORMAT.format(str(generic_exception)))
+
+
+def report_error(
+    ctx: AgentContext, category: EventCategory = "user", reraise: bool = False
+):
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                logger.error("Error reported: %s", e)
+                event = AgentBatchEvents.from_exception(
+                    e, traceback.format_exc(), category
+                )
+                if ctx.agent is not None:
+                    await dispatch_event_safe(ctx.agent.uri, event)
+                if reraise:
+                    raise e
+
+        return wrapper
+
+    return decorator
+
+
+class ChatProcessingError(Exception):
+    """Raised inside @report_error_reply functions to control error handling behavior."""
+
+    def __init__(
+        self,
+        message: str,
+        category: EventCategory = "system",
+        exc: Exception | None = None,
+    ):
+        self.reply_text = message
+        self.category = category
+        self.exc = exc
+        super().__init__(message)
+
+
+DEFAULT_ERROR_REPLY = "Agent failed to process request, please retry later."
+
+
+async def dispatch_event_safe(
+    agent: AgentUri | AgentStarletteState, event: AgentBatchEvents
+):
+    """Dispatch event to Agentverse. Swallows failures."""
+    try:
+        await dispatch_event(agent, event)
+    except Exception as e:
+        logger.error("Failed to dispatch event: %s", e)
+
+
+@asynccontextmanager
+async def chat_error_on_fail(
+    message: str,
+    category: EventCategory = "system",
+    include_exc: bool = True,
+):
+    """Wraps an operation. On failure, raises ChatProcessingError."""
+    try:
+        yield
+    except Exception as e:
+        raise ChatProcessingError(
+            message,
+            category=category,
+            exc=e if include_exc or category == "system" else None,
+        ) from e
+
+
+def report_error_reply(ctx: AgentContext, category: EventCategory = "system"):
+    """Decorator: on exception, dispatch event + send error reply."""
+
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        async def wrapper(self, env: Envelope, *args, **kwargs):
+            try:
+                return await func(self, env, *args, **kwargs)
+            except ChatProcessingError as e:
+                if e.exc:
+                    tb = "".join(traceback.format_exception(e.exc))
+                    await dispatch_event_safe(
+                        ctx.agent.uri,
+                        AgentBatchEvents.from_exception(e.exc, tb, e.category),
+                    )
+                else:
+                    await dispatch_event_safe(
+                        ctx.agent.uri,
+                        AgentBatchEvents.from_message(
+                            e.reply_text, e.category, "error"
+                        ),
+                    )
+                await _send_error_reply(ctx, env, e.reply_text)
+            except Exception as e:
+                await dispatch_event_safe(
+                    ctx.agent.uri,
+                    AgentBatchEvents.from_exception(
+                        e, traceback.format_exc(), category
+                    ),
+                )
+                await _send_error_reply(ctx, env, DEFAULT_ERROR_REPLY)
+
+        return wrapper
+
+    return decorator
+
+
+async def _send_error_reply(ctx: AgentContext, env: Envelope, text: str):
+    """Last-resort error reply. Self-guarded — never raises."""
+    if ctx.agent is None:
+        return
+    try:
+        await send_message_to_agent(
+            destination=env.sender,
+            msg=ChatMessage(
+                timestamp=utc_now(),
+                msg_id=uuid4(),
+                content=[TextContent(text=text)],
+            ),
+            sender=ctx.agent.uri.identity,
+            agentverse_config=ctx.agent.uri.agentverse,
+            session_id=env.session,
+        )
+    except Exception as e:
+        logger.error("Failed to send error reply to %s: %s", env.sender, e)
+        await dispatch_event_safe(
+            ctx.agent.uri,
+            AgentBatchEvents.from_message(
+                f"Failed to deliver error reply to {env.sender}: {e}",
+                "user",
+                "info",
+            ),
+        )

agentverse_sdk/_common/helpers.py

@@ -0,0 +1,5 @@
+from datetime import datetime, timezone
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)

agentverse_sdk/_common/logger.py

@@ -0,0 +1,76 @@
+import logging
+
+SDK_WARN = 99
+
+logger = logging.getLogger("agentverse-sdk")
+logger.setLevel(logging.CRITICAL)
+
+
+class _AlignedFormatter(logging.Formatter):
+    def format(self, record):
+        record.levelprefix = f"{record.levelname}:".ljust(10)
+        return super().format(record)
+
+
+class _SDKWarnFilter(logging.Filter):
+    def filter(self, record):
+        if record.levelno == SDK_WARN:
+            record.levelname = "WARNING"
+        return True
+
+
+logger.addFilter(_SDKWarnFilter())
+
+
+_FMT = "%(levelprefix)s [sdk] %(message)s"
+
+
+def _make_formatter():
+    try:
+        from uvicorn.logging import DefaultFormatter
+
+        fmt = DefaultFormatter(_FMT)
+        fmt.level_name_colors[SDK_WARN] = fmt.level_name_colors[logging.WARNING]
+        return fmt
+    except (ImportError, AttributeError):
+        return _AlignedFormatter(_FMT)
+
+
+def _has_structlog():
+    try:
+        import structlog.stdlib
+
+        return any(
+            isinstance(h.formatter, structlog.stdlib.ProcessorFormatter)
+            for h in logging.getLogger().handlers
+        )
+    except ImportError:
+        return False
+
+
+class _SmartHandler(logging.StreamHandler):
+    """Emits with our formatter until structlog appears, then steps aside."""
+
+    _structlog_active = False
+
+    def emit(self, record):
+        if not self._structlog_active and _has_structlog():
+            self._structlog_active = True
+            logger.propagate = True
+        if self._structlog_active:
+            return
+        super().emit(record)
+
+
+def configure(level: int):
+    logger.setLevel(level)
+    if not logger.handlers:
+        handler = _SmartHandler()
+        handler.setLevel(0)
+        handler.setFormatter(_make_formatter())
+        logger.addHandler(handler)
+        logger.propagate = False
+
+
+def log_sdk(msg: str, *args):
+    logger.log(SDK_WARN, msg, *args)

agentverse_sdk/_common/starlette.py

@@ -0,0 +1,120 @@
+import functools
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import Callable, cast
+
+from starlette import status
+from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from uagents_core.contrib.protocols.chat import (
+    ChatAcknowledgement,
+    ChatMessage,
+)
+from uagents_core.envelope import Envelope
+from uagents_core.utils.messages import parse_envelope
+
+from agentverse_sdk._common.av import set_agent_status, verify_envelope
+from agentverse_sdk._common.events import dispatch_event, report_error
+from agentverse_sdk._common.logger import logger
+from agentverse_sdk._common.types import (
+    AgentBatchEvents,
+    AgentContext,
+    AgentStarletteState,
+    EventCategory,
+)
+
+
+async def parse_chat_message_from_request(
+    request: Request, verify: bool, expected_address: str | None = None
+) -> tuple[Envelope, ChatMessage | ChatAcknowledgement]:
+    malformed_exc = HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail="Malformed envelope or chat message",
+    )
+
+    try:
+        env = Envelope.model_validate(await request.json())
+        if verify and not verify_envelope(env):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid envelope"
+            )
+        if expected_address is not None and env.target != expected_address:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Wrong destination address",
+            )
+        msg = cast(
+            ChatMessage | ChatAcknowledgement | str,
+            parse_envelope(env, {ChatMessage, ChatAcknowledgement}),
+        )
+        if isinstance(msg, str):
+            raise malformed_exc
+
+        return env, msg
+    except Exception as e:
+        raise malformed_exc from e
+
+
+@asynccontextmanager
+async def agent_status_lifespan(app: Starlette):
+    if hasattr(app.state, "agent"):
+        agent = app.state.agent
+        try:
+            await set_agent_status(agent.identity, True, agent.agentverse)
+            await dispatch_event(
+                agent, AgentBatchEvents.from_message("Agent Started")
+            )
+        except Exception as e:
+            logger.error("Failed to report agent start: %s", e)
+    yield
+    if hasattr(app.state, "agent"):
+        agent = app.state.agent
+        try:
+            await set_agent_status(agent.identity, False, agent.agentverse)
+            await dispatch_event(
+                agent, AgentBatchEvents.from_message("Agent Stopped")
+            )
+        except Exception as e:
+            logger.error("Failed to report agent stop: %s", e)
+
+
+Lifespan = Callable[[Starlette], AbstractAsyncContextManager[None]]
+
+
+def setup_agent_status_lifespan(
+    existing_lifespan: Lifespan | None = None,
+) -> Lifespan:
+    if existing_lifespan is None:
+        return agent_status_lifespan
+
+    @asynccontextmanager
+    async def combined_lifespan(app: Starlette):
+        async with agent_status_lifespan(app), existing_lifespan(app):
+            yield
+
+    return combined_lifespan
+
+
+def set_app_state(app: Starlette, agent: AgentStarletteState):
+    app.state.agent = agent
+
+
+def report_error_starlette(ctx: AgentContext, category: EventCategory = "user"):
+    def decorator(func: Callable):
+        reported = report_error(ctx, category, reraise=True)(func)
+
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await reported(*args, **kwargs)
+            except HTTPException:
+                raise
+            except Exception as e:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Failed to process request",
+                ) from e
+
+        return wrapper
+
+    return decorator

agentverse_sdk/_common/storage.py

@@ -0,0 +1,70 @@
+"""
+Async helper for uploading content to Agentverse External Storage.
+
+API reference: agentverse-core services/storage/src/api/routes/public/assets.py
+- POST /v1/storage/assets/ accepts Agent attestation auth (get_client dep)
+- Request body: NewAsset {contents (base64), mime_type, lifetime_hours (1-24)}
+- Response: 201 with Asset {asset_id (UUID)}; 403 if agent not delegated
+"""
+
+import base64
+import traceback
+
+import httpx
+
+from agentverse_sdk._common.av import generate_agent_auth_token
+from agentverse_sdk._common.events import dispatch_event_safe
+from agentverse_sdk._common.logger import logger
+from agentverse_sdk._common.types import AgentBatchEvents, AgentUri
+
+
+async def upload_to_storage(
+    content: bytes,
+    mime_type: str,
+    agent_uri: AgentUri,
+) -> str:
+    """Upload content to Agentverse storage, return an agent-storage:// URI."""
+    url = f"{agent_uri.agentverse.storage_api}/assets/"
+    headers = {
+        "Authorization": f"Agent {generate_agent_auth_token(agent_uri.identity)}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "contents": base64.b64encode(content).decode(),
+        "mime_type": mime_type,
+        "lifetime_hours": 24,
+    }
+
+    async with httpx.AsyncClient(timeout=10) as client:
+        response = await client.post(url, json=payload, headers=headers)
+
+    if response.status_code != 201:
+        raise RuntimeError(f"Storage upload failed: {response.status_code}")
+
+    asset_id = response.json()["asset_id"]
+
+    uri = f"agent-storage://{agent_uri.agentverse.base_url}/{asset_id}"
+    logger.debug(f"Uploaded to {uri}")
+    return uri
+
+
+
+async def upload_to_storage_safe(
+    content: bytes,
+    mime_type: str,
+    agent_uri: AgentUri,
+) -> str | None:
+    """Upload to storage, returning None on failure.
+
+    Logs the error and dispatches a system event so the Agentverse team
+    can detect storage service issues without user intervention.
+    """
+    try:
+        return await upload_to_storage(content, mime_type, agent_uri)
+    except Exception as e:
+        logger.error("Storage upload failed: %s", e)
+        await dispatch_event_safe(
+            agent_uri,
+            AgentBatchEvents.from_exception(e, traceback.format_exc(), "system"),
+        )
+        return None