attp-client 0.0.1__py3-none-any.whl

attp_client/catalog.py

@@ -0,0 +1,59 @@
+from typing import Any, Callable, MutableMapping
+from attp_client.errors.not_found import NotFoundError
+from attp_client.tools import ToolsManager
+
+
+class AttpCatalog:
+    attached_tools: MutableMapping[str, Callable[..., Any]]
+    tool_name_to_id_symlink: MutableMapping[str, str]
+    
+    def __init__(
+        self,
+        id: int,
+        catalog_name: str,
+        manager: ToolsManager
+    ) -> None:
+        self.id = id
+        self.catalog_name = catalog_name
+        self.tool_manager = manager
+        self.attached_tools = {}
+        self.tool_name_to_id_symlink = {}
+    
+    async def attach_tool(
+        self,
+        callback: Callable[..., Any],
+        name: str, 
+        description: str | None = None,
+        schema_id: str | None = None,
+        *,
+        return_direct: bool = False,
+        schema_ver: str = "1.0",
+        timeout_ms: float = 20000,
+        idempotent: bool = False
+    ):
+        assigned_id = await self.tool_manager.register(
+            self.catalog_name,
+            name=name,
+            description=description,
+            schema_id=schema_id,
+            return_direct=return_direct,
+            schema_ver=schema_ver,
+            timeout_ms=timeout_ms,
+            idempotent=idempotent
+        )
+        
+        self.attached_tools[str(assigned_id)] = callback
+        self.tool_name_to_id_symlink[name] = str(assigned_id)
+        return assigned_id
+    
+    async def detatch_tool(
+        self,
+        name: str
+    ):
+        tool_id = self.tool_name_to_id_symlink.get(name)
+        
+        if not tool_id:
+            raise NotFoundError(f"Tool {name} not marked as registered and wasn't found in the catalog {self.catalog_name}.")
+        
+        await self.tool_manager.unregister(self.catalog_name, tool_id)
+        return tool_id

attp_client/client.py

@@ -0,0 +1,119 @@
+import asyncio
+from functools import cached_property
+from logging import Logger, getLogger
+from typing import Any, Callable, Literal
+from attp_core.rs_api import AttpClientSession, Limits
+from reactivex import Subject
+from attp_core.rs_api import PyAttpMessage
+
+from attp_client.catalog import AttpCatalog
+from attp_client.inference import AttpInferenceAPI
+from attp_client.interfaces.catalogs.catalog import ICatalogResponse
+from attp_client.misc.serializable import Serializable
+from attp_client.router import AttpRouter
+from attp_client.session import SessionDriver
+from attp_client.tools import ToolsManager
+from attp_client.types.route_mapping import AttpRouteMapping, RouteType
+
+class ATTPClient:
+    
+    is_connected: bool
+    client: AttpClientSession
+    session: SessionDriver | None
+    routes: list[AttpRouteMapping]
+    inference: AttpInferenceAPI
+    
+    def __init__(
+        self,
+        agt_token: str,
+        organization_id: int,
+        *,
+        connection_url: str | None = None,
+        max_retries: int = 20,
+        limits: Limits | None = None,
+        logger: Logger | None = None
+    ):
+        self.__agt_token = agt_token
+        self.organization_id = organization_id
+        self.connection_url = connection_url or "attp://localhost:6563"
+        
+        self.client = AttpClientSession(self.connection_url)
+        self.session = None
+        self.max_retries = max_retries
+        self.limits = limits or Limits(max_payload_size=50000)
+        self.logger = logger
+        
+        self.route_increment_index = 2
+        
+        self.responder = Subject[PyAttpMessage]()
+        self.routes = []
+    
+    async def connect(self):
+        # Open the connection
+        client = await self.client.connect(self.max_retries, self.limits)
+        
+        if not client.session:
+            raise ConnectionError("Failed to connect to ATTP server after 10 attempts!")
+        
+        self.session = SessionDriver(
+            client.session, 
+            agt_token=self.__agt_token, 
+            organization_id=self.organization_id,
+            # route_mappings=self.routes,
+            logger=self.logger or getLogger("Ascender Framework")
+        )
+        asyncio.create_task(self.session.start_listener())
+        # Send an authentication frame as soon as connection estabilishes with agenthub
+        await self.session.authenticate(self.routes)
+        asyncio.create_task(self.session.listen(self.responder))
+        
+        self.router = AttpRouter(self.responder, self.session)
+        self.inference = AttpInferenceAPI(self.router)
+
+    async def close(self):
+        if self.session:
+            await self.session.close()
+            self.session = None
+            self.is_connected = False
+
+    @cached_property
+    def tools(self):
+        return ToolsManager(self.router)
+    
+    async def catalog(self, catalog_name: str):
+        catalog = await self.router.send(
+            "tools:catalogs:specific", 
+            Serializable[dict[str, str]]({"catalog_name": catalog_name}),
+            timeout=10,
+            expected_response=ICatalogResponse
+        )
+        
+        return AttpCatalog(id=catalog.catalog_id, catalog_name=catalog_name, manager=self.tools)
+    
+    def add_event_handler(
+        self, 
+        pattern: str, 
+        route_type: RouteType,
+        callback: Callable[..., Any],
+    ):
+        if route_type in ["connect", "disconnect"]:
+            self.routes.append(
+                AttpRouteMapping(
+                    pattern=pattern,
+                    route_id=0,
+                    route_type=route_type,
+                    callback=callback
+                )
+            )
+            return
+        
+        self.routes.append(
+            AttpRouteMapping(
+                pattern=pattern, 
+                route_id=self.route_increment_index, 
+                route_type=route_type, 
+                callback=callback
+            )
+        )
+        
+        self.route_increment_index += 1

attp_client/consts.py

@@ -0,0 +1 @@
+ATTP_VERSION=b"01"

attp_client/errors/attp_exception.py

@@ -0,0 +1,12 @@
+from typing import Any, Mapping
+
+from attp_client.interfaces.error import IErr
+
+
+class AttpException(Exception):
+    def __init__(self, code: str = "UnknownError", *, detail: Mapping[str, Any]) -> None:
+        self.code = code
+        self.detail = detail
+    
+    def to_ierr(self):
+        return IErr(detail={"code": self.code, **self.detail})

attp_client/errors/correlated_rpc_exception.py

@@ -0,0 +1,21 @@
+from typing import Any
+from uuid import UUID
+
+from attp_client.interfaces.error import IErr
+
+class CorrelatedRPCException(Exception):
+    correlation_id: UUID
+    def __init__(
+        self, 
+        correlation_id: bytes,
+        detail: dict[str, Any] | None = None,
+    ):
+        self.correlation_id = UUID(bytes=correlation_id)
+        self.detail = detail
+    
+    @staticmethod
+    def from_err_object(correlation_id: bytes, err: IErr):
+        return CorrelatedRPCException(correlation_id, err.detail)
+    
+    def __str__(self) -> str:
+        return f"[ATTPRPC ERR]: {self.detail}"

attp_client/errors/dead_session.py

@@ -0,0 +1,7 @@
+class DeadSessionError(Exception):
+    def __init__(self, organization_id: int) -> None:
+        super().__init__()
+        self.organization_id = organization_id
+    
+    def __str__(self) -> str:
+        return f"Cannot perform any actions over dead ATTP session (organization_id={self.organization_id})"

attp_client/errors/not_found.py

@@ -0,0 +1,2 @@
+class NotFoundError(Exception):
+    ...

attp_client/errors/serialization_error.py

@@ -0,0 +1,6 @@
+class SerializationError(Exception):
+    def __init__(self, detail: str) -> None:
+        self.detail = detail
+    
+    def __str__(self) -> str:
+        return f"Serialization fault: {self.detail}"

attp_client/errors/unauthenticated_error.py

@@ -0,0 +1,2 @@
+class UnauthenticatedError(Exception):
+    ...

attp_client/inference.py

@@ -0,0 +1,131 @@
+import asyncio
+from logging import Logger, getLogger
+from typing import Any, Sequence
+from uuid import UUID
+from attp_client.interfaces.inference.message import IMessageResponse, IMessageDTOV2
+from attp_client.misc.serializable import Serializable
+from attp_client.router import AttpRouter
+
+
+class AttpInferenceAPI:
+    """
+    AttpInferenceAPI provides methods to interact with the inference API of the AgentHub.
+    """
+    def __init__(
+        self,
+        router: AttpRouter,
+        logger: Logger = getLogger("Ascender Framework")
+    ) -> None:
+        self.router = router
+        self.logger = logger
+    
+    async def invoke_inference(
+        self,
+        agent_id: int | None = None,
+        agent_name: str | None = None,
+        *,
+        input_configuration: dict[str, Any] | None = None,
+        messages: Sequence[IMessageDTOV2] | None = None,
+        stream: bool = False,
+        timeout: float = 200
+    ) -> IMessageResponse:
+        """
+        Invoke inference for a specific agent by its ID or name.
+    
+        Parameters
+        ----------
+        agent_id : int | None, optional
+            The ID of the agent to invoke inference for, by default None
+        agent_name : str | None, optional
+            The name of the agent to invoke inference for, by default None
+            _description_, by default None
+        input_configuration : dict[str, Any] | None, optional
+            The configuration for the input, by default None
+        messages : Sequence[IMessageDTOV2] | None, optional
+            The messages to include in the inference, by default None
+        stream : bool, optional
+            Whether to stream the response, by default False
+        timeout : float, optional
+            The timeout for the request, by default 200
+
+        Returns
+        -------
+        IMessageResponse
+            The response from the inference request.
+
+        Raises
+        ------
+        ValueError
+            If neither 'agent_id' nor 'agent_name' is provided.
+        ValueError
+            If both 'agent_id' and 'agent_name' are provided.
+        """
+        
+        if not agent_id and not agent_name:
+            raise ValueError("Required at least one identification specifier, 'agent_id' or 'agent_name'")
+        
+        if agent_id and agent_name:
+            raise ValueError("Cannot find agent by two identification specifiers, use only one!")
+        
+        response = await self.router.send("messages:inference:invoke", Serializable[dict[str, Any]]({
+            "agent_id": agent_id,
+            "agent_name": agent_name,
+            "input_configuration": input_configuration,
+            "messages": [message.model_dump(mode="json") for message in (messages or [])],
+            "stream": stream
+        }), timeout=timeout, expected_response=IMessageResponse)
+        
+        return response
+    
+    async def invoke_chat_inference(
+        self, 
+        messages: Sequence[IMessageDTOV2], 
+        chat_id: UUID,
+        stream: bool = False,
+        timeout: float = 200,
+    ) -> IMessageResponse:
+        """
+        Invoke inference for a specific chat by its chat_id.
+
+        Parameters
+        ----------
+        messages : Sequence[IMessageDTOV2]
+            The messages to include in the inference.
+        chat_id : UUID
+            The ID of the chat to invoke inference for.
+        stream : bool, optional
+            Whether to stream the response, by default False.
+        timeout : float, optional
+            The timeout for the request, by default 200.
+
+        Returns
+        -------
+        IMessageResponse
+            The response from the inference request.
+        """
+        for message in messages:
+            await self.router.send("messages:append", message, timeout=5)
+        
+        response = await self.router.send(
+            "messages:chat:invoke", 
+            Serializable[dict[str, Any]]({"chat_id": str(chat_id), "stream": stream}),
+            timeout=timeout,
+            # expected_response=IMessageResponse
+        )
+        
+        return response
+
+    async def append_message(self, message: IMessageDTOV2 | Sequence[IMessageDTOV2]) -> None:
+        """
+        Append a message or a sequence of messages to the current chat.
+        
+        Parameters
+        ----------
+        message : IMessageDTOV2 | Sequence[IMessageDTOV2]
+            The message or messages to append.
+        """
+        if isinstance(message, Sequence):
+            for msg in message:
+                await self.router.emit("messages:append", msg)
+        else:
+            await self.router.emit("messages:append", message)

attp_client/interfaces/catalogs/catalog.py

@@ -0,0 +1,6 @@
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class ICatalogResponse(FixedBaseModel):
+    catalog_id: int
+    organization_id: int

attp_client/interfaces/error.py

@@ -0,0 +1,6 @@
+from typing import Any
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class IErr(FixedBaseModel):
+    detail: dict[str, Any]

attp_client/interfaces/handshake/auth.py

@@ -0,0 +1,9 @@
+from typing import Annotated
+from pydantic import Field
+from typing_extensions import Doc
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class IAuth(FixedBaseModel):
+    token: Annotated[str | None, Doc("Provided AGT token for authentication")] = Field(None)
+    organization_id: Annotated[int, Doc("ID of organization.")]

attp_client/interfaces/handshake/hello.py

@@ -0,0 +1,13 @@
+from typing import Annotated
+from pydantic import Field
+from typing_extensions import Doc
+
+from attp_client.interfaces.route_mappings import IRouteMapping
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class IHello(FixedBaseModel):
+    proto: Annotated[str, Doc("Protocol ID")] = Field("ATTP")
+    ver: Annotated[str, Doc("Semver for example: 1.0")] = Field("1.0")
+    caps: Annotated[list[str], Doc("Capability flags e.g. ['schemas/json', 'stream', 'hb']")] = Field(default_factory=list)
+    mapping: Annotated[list[IRouteMapping], Doc("Router pattern mappings, ATTP for optimization uses numbers and IDs for routing requests instead of human friendly patterns")] 

attp_client/interfaces/handshake/ready.py

@@ -0,0 +1,11 @@
+from typing import Annotated, Sequence
+from typing_extensions import Doc
+
+from attp_client.interfaces.route_mappings import IRouteMapping
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class IReady(FixedBaseModel):
+    session: Annotated[str, Doc("Server-issued session id (per connection)")] # REQUIRED
+    server_time: Annotated[str | None, Doc("Server ISO time for skew hints")] = None
+    server_routes: Sequence[IRouteMapping]

attp_client/interfaces/inference/enums/message_data_type.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class MessageDataTypeEnum(Enum):
+    """
+    Enumeration for data types available to be sent by users/AI
+    """
+
+    JPEG_IMAGE = 'jpeg_image'  # .jpeg .jpg
+    FFMPEG_VIDEO = 'ffmpeg_video'  # mp4
+    PLAIN_TEXT = 'plain_text'  # txt, that would be also a simple chat message
+    WAVE_AUDIO = 'wave_audio'  # wav
+    PLACEHOLDER_KEY = 'placeholder_key'
+    NONE = 'none'

attp_client/interfaces/inference/enums/message_emergency_type.py

@@ -0,0 +1,11 @@
+from enum import Enum
+
+
+
+class MessageEmergencyTypeEnum(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    IMMEDIATE = "immediate"
+
+

attp_client/interfaces/inference/enums/message_type.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+
+class MessageTypeEnum(Enum):
+    TOOL_STATE_EVENT = 'tool_state_event'
+
+    OPERATOR_CALLED_EVENT = 'operator_called_event'
+
+    SYSTEM_EVENT = 'system_event'  # user is created, or added to chat or smth
+    SYSTEM_MESSAGE = 'system_message'
+
+    USER_MESSAGE = 'user_message'
+    AI_MESSAGE = 'ai_message'
+    #
+    OPERATOR_MESSAGE = 'operator_message'
+    CUSTOMER_MESSAGE = 'customer_message'
+
+    PLACEHOLDER_MESSAGE = 'placeholder_message'  # content is the key for placeholder

attp_client/interfaces/inference/message.py

@@ -0,0 +1,51 @@
+from typing import Literal
+from uuid import UUID
+from attp_client.interfaces.inference.enums.message_emergency_type import MessageEmergencyTypeEnum
+from attp_client.interfaces.inference.enums.message_type import MessageTypeEnum
+from attp_client.interfaces.inference.tool import ToolV2
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class BaseMessage(FixedBaseModel):
+    def __init__(self, *args, **kwargs):
+        super().__init__(**kwargs)
+
+class IAttachmentDTO(BaseMessage):
+    file_id: int
+
+class IMessageDTOV2(FixedBaseModel):
+    """
+    The DTO Object of Message in AgentHub, contains message content and tool execution data.
+    """
+    content: dict | str | None
+    message_type: MessageTypeEnum
+    attachments: list[IAttachmentDTO] | None = None
+
+    reply_to_message_id: int | None = None
+    chat_id: UUID
+    agent_id: int | None = None
+    user_id: int | None = None
+    client_id: str | None = None
+
+    tool_called: ToolV2 | None = None
+    tool_status: Literal['started', 'finished', 'error'] | None = None
+    tool_started_input: str | None = None
+    tool_finished_output: str | None = None
+    tool_error_detail: str | None = None
+
+    specialist_required: MessageEmergencyTypeEnum | None = None
+
+    def to_wrap(self) -> dict:
+        w = self.model_dump()
+        del w['attachments']
+
+        return w
+
+
+class IMessageResponse(IMessageDTOV2):
+    """
+    Response model of AgentHub Message, it represents [MessageDTO](agenthub/dtos/message_dto.py).
+    But it contains additional value as ID
+    """
+    id: int
+    """ID of Message in database"""

attp_client/interfaces/inference/tool.py

@@ -0,0 +1,6 @@
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class ToolV2(FixedBaseModel):
+    name: str
+    db_id: int | None = None

attp_client/interfaces/route_mappings.py

@@ -0,0 +1,12 @@
+from attp_client.types.route_mapping import AttpRouteMapping, RouteType
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+
+class IRouteMapping(FixedBaseModel):
+    pattern: str
+    route_id: int
+    route_type: RouteType
+    
+    @staticmethod
+    def from_route_mapper(mapper: AttpRouteMapping):
+        return IRouteMapping(pattern=mapper.pattern, route_id=mapper.route_id, route_type=mapper.route_type)

attp_client/misc/fixed_basemodel.py

@@ -0,0 +1,63 @@
+from typing import Any, Self
+
+import msgpack
+from pydantic import BaseModel
+
+
+class FixedBaseModel(BaseModel):
+    @classmethod
+    def serialize(cls, entity, **kwargs):
+        serialized_data = {
+            key: value
+            for key, value in entity.__dict__.items()
+            if not callable(value) and not key.startswith('_')
+        }
+
+        for key, value in kwargs.items():
+            serialized_data[key] = value
+
+        # noinspection PyArgumentList
+        pydantic_instance = cls(**serialized_data)
+
+        return pydantic_instance
+
+    @classmethod
+    def s(cls, entity, **kwargs) -> Self:
+        return cls.serialize(entity, **kwargs)
+
+    @classmethod
+    def mps(
+        cls, 
+        obj: bytes,
+        strict: bool | None = None,
+        from_attributes: bool | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+        mp_configs: dict[str, Any] | None = None
+    ):
+        """
+        Message Pack Serialize
+        
+        Serializes and unpacks the model from the binary by utilizing Message Pack library.
+
+        Opposite method: `mpd(...)`
+
+        Parameters
+        ----------
+        obj : bytes
+            Binary packed by Message Pack object.
+        """
+        obj = msgpack.unpackb(obj, **(mp_configs or {}))
+        
+        return cls.model_validate(obj, strict=strict, from_attributes=from_attributes, context=context, by_alias=by_alias, by_name=by_name)
+    
+    def mpd(self, mp_configs: dict[str, Any] | None = None, **kwargs) -> bytes | None:
+        """
+        Message Pack Dump
+        
+        Dumps and packs the model to the binary by utilizing Message Pack library.
+        
+        Opposite method: `mps(...)`
+        """
+        return msgpack.packb(self.model_dump(mode="json", **kwargs), **(mp_configs or {}))

attp_client/misc/serializable.py

@@ -0,0 +1,69 @@
+import inspect
+from typing import Any, Generic, Self, TypeVar, final
+
+import msgpack
+from pydantic import TypeAdapter
+
+from attp_client.misc.fixed_basemodel import FixedBaseModel
+
+T = TypeVar("T")
+
+
+class Serializable(Generic[T]):
+    def __init__(self, data: T, enable_validation: bool = False) -> None:
+        self.data = data
+        self.enable_validation = enable_validation
+    
+        self.validate()
+    
+    def validate(self):
+        if isinstance(self.data, FixedBaseModel) and self.enable_validation:
+            self.data = self.data.model_dump(mode="json")
+    
+    @staticmethod
+    def deserialize(obj: bytes, mp_configs: dict[str, Any] | None = None) -> Any:
+        return msgpack.unpackb(obj, **(mp_configs or {}))
+    
+    def serialize(self, mp_configs: dict[str, Any] | None = None) -> bytes | None:
+        return msgpack.packb(self.data, **(mp_configs or {}))
+    
+    @final
+    @classmethod
+    def mps(
+        cls, 
+        obj: bytes,
+        mp_configs: dict[str, Any] | None = None
+    ) -> Self:
+        """
+        Message Pack Serialize
+        
+        Deserializes and unpacks the model from the binary by utilizing Message Pack library.
+
+        Opposite method: `mpd(...)`
+
+        Parameters
+        ----------
+        obj : bytes
+            Binary packed by Message Pack object.
+        """
+        return cls(data=cls.deserialize(obj, mp_configs=mp_configs))
+    
+    @final
+    def mpd(self, mp_configs: dict[str, Any] | None = None) -> bytes | None:
+        """
+        Message Pack Dump
+        
+        Dumps and packs the model to the binary by utilizing Message Pack library.
+        
+        Opposite method: `mps(...)`
+        """
+        return self.serialize(mp_configs)
+    
+    def __setattr__(self, name: str, value: Any) -> None:
+        caller = inspect.stack()[1].function
+        if caller == "__init__" or caller.startswith("_"):
+            super().__setattr__(name, value)
+            return
+        
+        if name in ["data"]:
+            raise TypeError(f"'Serializable' object does not support data mutation for attribute '{name}'")