pygeai 0.1.6__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/vendor/a2a/utils/__init__.py

@@ -0,0 +1,40 @@
+"""Utility functions for the A2A Python SDK."""
+
+from a2a.utils.artifact import (
+    new_artifact,
+    new_data_artifact,
+    new_text_artifact,
+)
+from a2a.utils.helpers import (
+    append_artifact_to_task,
+    are_modalities_compatible,
+    build_text_artifact,
+    create_task_obj,
+)
+from a2a.utils.message import (
+    get_message_text,
+    get_text_parts,
+    new_agent_parts_message,
+    new_agent_text_message,
+)
+from a2a.utils.task import (
+    completed_task,
+    new_task,
+)
+
+
+__all__ = [
+    'append_artifact_to_task',
+    'are_modalities_compatible',
+    'build_text_artifact',
+    'completed_task',
+    'create_task_obj',
+    'get_message_text',
+    'get_text_parts',
+    'new_agent_parts_message',
+    'new_agent_text_message',
+    'new_artifact',
+    'new_data_artifact',
+    'new_task',
+    'new_text_artifact',
+]

pygeai/vendor/a2a/utils/artifact.py

@@ -0,0 +1,72 @@
+"""Utility functions for creating A2A Artifact objects."""
+
+import uuid
+
+from typing import Any
+
+from a2a.types import Artifact, DataPart, Part, TextPart
+
+
+def new_artifact(
+    parts: list[Part], name: str, description: str = ''
+) -> Artifact:
+    """Creates a new Artifact object.
+
+    Args:
+        parts: The list of `Part` objects forming the artifact's content.
+        name: The human-readable name of the artifact.
+        description: An optional description of the artifact.
+
+    Returns:
+        A new `Artifact` object with a generated artifactId.
+    """
+    return Artifact(
+        artifactId=str(uuid.uuid4()),
+        parts=parts,
+        name=name,
+        description=description,
+    )
+
+
+def new_text_artifact(
+    name: str,
+    text: str,
+    description: str = '',
+) -> Artifact:
+    """Creates a new Artifact object containing only a single TextPart.
+
+    Args:
+        name: The human-readable name of the artifact.
+        text: The text content of the artifact.
+        description: An optional description of the artifact.
+
+    Returns:
+        A new `Artifact` object with a generated artifactId.
+    """
+    return new_artifact(
+        [Part(root=TextPart(text=text))],
+        name,
+        description,
+    )
+
+
+def new_data_artifact(
+    name: str,
+    data: dict[str, Any],
+    description: str = '',
+) -> Artifact:
+    """Creates a new Artifact object containing only a single DataPart.
+
+    Args:
+        name: The human-readable name of the artifact.
+        data: The structured data content of the artifact.
+        description: An optional description of the artifact.
+
+    Returns:
+        A new `Artifact` object with a generated artifactId.
+    """
+    return new_artifact(
+        [Part(root=DataPart(data=data))],
+        name,
+        description,
+    )

pygeai/vendor/a2a/utils/errors.py

@@ -0,0 +1,69 @@
+"""Custom exceptions for A2A server-side errors."""
+
+from a2a.types import (
+    ContentTypeNotSupportedError,
+    InternalError,
+    InvalidAgentResponseError,
+    InvalidParamsError,
+    InvalidRequestError,
+    JSONParseError,
+    JSONRPCError,
+    MethodNotFoundError,
+    PushNotificationNotSupportedError,
+    TaskNotCancelableError,
+    TaskNotFoundError,
+    UnsupportedOperationError,
+)
+
+
+class A2AServerError(Exception):
+    """Base exception for A2A Server errors."""
+
+
+class MethodNotImplementedError(A2AServerError):
+    """Exception raised for methods that are not implemented by the server handler."""
+
+    def __init__(
+        self, message: str = 'This method is not implemented by the server'
+    ):
+        """Initializes the MethodNotImplementedError.
+
+        Args:
+            message: A descriptive error message.
+        """
+        self.message = message
+        super().__init__(f'Not Implemented operation Error: {message}')
+
+
+class ServerError(Exception):
+    """Wrapper exception for A2A or JSON-RPC errors originating from the server's logic.
+
+    This exception is used internally by request handlers and other server components
+    to signal a specific error that should be formatted as a JSON-RPC error response.
+    """
+
+    def __init__(
+        self,
+        error: (
+            JSONRPCError
+            | JSONParseError
+            | InvalidRequestError
+            | MethodNotFoundError
+            | InvalidParamsError
+            | InternalError
+            | TaskNotFoundError
+            | TaskNotCancelableError
+            | PushNotificationNotSupportedError
+            | UnsupportedOperationError
+            | ContentTypeNotSupportedError
+            | InvalidAgentResponseError
+            | None
+        ),
+    ):
+        """Initializes the ServerError.
+
+        Args:
+            error: The specific A2A or JSON-RPC error model instance.
+                   If None, an `InternalError` will be used when formatting the response.
+        """
+        self.error = error

pygeai/vendor/a2a/utils/helpers.py

@@ -0,0 +1,176 @@
+"""General utility functions for the A2A Python SDK."""
+
+import logging
+
+from collections.abc import Callable
+from typing import Any
+from uuid import uuid4
+
+from a2a.types import (
+    Artifact,
+    MessageSendParams,
+    Part,
+    Task,
+    TaskArtifactUpdateEvent,
+    TaskState,
+    TaskStatus,
+    TextPart,
+)
+from a2a.utils.errors import ServerError, UnsupportedOperationError
+from a2a.utils.telemetry import trace_function
+
+
+logger = logging.getLogger(__name__)
+
+
+@trace_function()
+def create_task_obj(message_send_params: MessageSendParams) -> Task:
+    """Create a new task object from message send params.
+
+    Generates UUIDs for task and context IDs if they are not already present in the message.
+
+    Args:
+        message_send_params: The `MessageSendParams` object containing the initial message.
+
+    Returns:
+        A new `Task` object initialized with 'submitted' status and the input message in history.
+    """
+    if not message_send_params.message.contextId:
+        message_send_params.message.contextId = str(uuid4())
+
+    return Task(
+        id=str(uuid4()),
+        contextId=message_send_params.message.contextId,
+        status=TaskStatus(state=TaskState.submitted),
+        history=[message_send_params.message],
+    )
+
+
+@trace_function()
+def append_artifact_to_task(task: Task, event: TaskArtifactUpdateEvent) -> None:
+    """Helper method for updating a Task object with new artifact data from an event.
+
+    Handles creating the artifacts list if it doesn't exist, adding new artifacts,
+    and appending parts to existing artifacts based on the `append` flag in the event.
+
+    Args:
+        task: The `Task` object to modify.
+        event: The `TaskArtifactUpdateEvent` containing the artifact data.
+    """
+    if not task.artifacts:
+        task.artifacts = []
+
+    new_artifact_data: Artifact = event.artifact
+    artifact_id: str = new_artifact_data.artifactId
+    append_parts: bool = event.append or False
+
+    existing_artifact: Artifact | None = None
+    existing_artifact_list_index: int | None = None
+
+    # Find existing artifact by its id
+    for i, art in enumerate(task.artifacts):
+        if art.artifactId == artifact_id:
+            existing_artifact = art
+            existing_artifact_list_index = i
+            break
+
+    if not append_parts:
+        # This represents the first chunk for this artifact index.
+        if existing_artifact_list_index is not None:
+            # Replace the existing artifact entirely with the new data
+            logger.debug(
+                f'Replacing artifact at id {artifact_id} for task {task.id}'
+            )
+            task.artifacts[existing_artifact_list_index] = new_artifact_data
+        else:
+            # Append the new artifact since no artifact with this index exists yet
+            logger.debug(
+                f'Adding new artifact with id {artifact_id} for task {task.id}'
+            )
+            task.artifacts.append(new_artifact_data)
+    elif existing_artifact:
+        # Append new parts to the existing artifact's part list
+        logger.debug(
+            f'Appending parts to artifact id {artifact_id} for task {task.id}'
+        )
+        existing_artifact.parts.extend(new_artifact_data.parts)
+    else:
+        # We received a chunk to append, but we don't have an existing artifact.
+        # we will ignore this chunk
+        logger.warning(
+            f'Received append=True for nonexistent artifact index {artifact_id} in task {task.id}. Ignoring chunk.'
+        )
+
+
+def build_text_artifact(text: str, artifact_id: str) -> Artifact:
+    """Helper to create a text artifact.
+
+    Args:
+        text: The text content for the artifact.
+        artifact_id: The ID for the artifact.
+
+    Returns:
+        An `Artifact` object containing a single `TextPart`.
+    """
+    text_part = TextPart(text=text)
+    part = Part(root=text_part)
+    return Artifact(parts=[part], artifactId=artifact_id)
+
+
+def validate(
+    expression: Callable[[Any], bool], error_message: str | None = None
+) -> Callable:
+    """Decorator that validates if a given expression evaluates to True.
+
+    Typically used on class methods to check capabilities or configuration
+    before executing the method's logic. If the expression is False,
+    a `ServerError` with an `UnsupportedOperationError` is raised.
+
+    Args:
+        expression: A callable that takes the instance (`self`) as its argument
+                    and returns a boolean.
+        error_message: An optional custom error message for the `UnsupportedOperationError`.
+                       If None, the string representation of the expression will be used.
+    """
+
+    def decorator(function: Callable) -> Callable:
+        def wrapper(self: Any, *args, **kwargs) -> Any:
+            if not expression(self):
+                final_message = error_message or str(expression)
+                logger.error(f'Unsupported Operation: {final_message}')
+                raise ServerError(
+                    UnsupportedOperationError(message=final_message)
+                )
+            return function(self, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def are_modalities_compatible(
+    server_output_modes: list[str] | None, client_output_modes: list[str] | None
+) -> bool:
+    """Checks if server and client output modalities (MIME types) are compatible.
+
+    Modalities are compatible if:
+    1. The client specifies no preferred output modes (client_output_modes is None or empty).
+    2. The server specifies no supported output modes (server_output_modes is None or empty).
+    3. There is at least one common modality between the server's supported list and the client's preferred list.
+
+    Args:
+        server_output_modes: A list of MIME types supported by the server/agent for output.
+                             Can be None or empty if the server doesn't specify.
+        client_output_modes: A list of MIME types preferred by the client for output.
+                             Can be None or empty if the client accepts any.
+
+    Returns:
+        True if the modalities are compatible, False otherwise.
+    """
+    if client_output_modes is None or len(client_output_modes) == 0:
+        return True
+
+    if server_output_modes is None or len(server_output_modes) == 0:
+        return True
+
+    return any(x in server_output_modes for x in client_output_modes)

pygeai/vendor/a2a/utils/message.py

@@ -0,0 +1,83 @@
+"""Utility functions for creating and handling A2A Message objects."""
+
+import uuid
+
+from a2a.types import (
+    Message,
+    Part,
+    Role,
+    TextPart,
+)
+
+
+def new_agent_text_message(
+    text: str,
+    context_id: str | None = None,
+    task_id: str | None = None,
+) -> Message:
+    """Creates a new agent message containing a single TextPart.
+
+    Args:
+        text: The text content of the message.
+        context_id: The context ID for the message.
+        task_id: The task ID for the message.
+
+    Returns:
+        A new `Message` object with role 'agent'.
+    """
+    return Message(
+        role=Role.agent,
+        parts=[Part(root=TextPart(text=text))],
+        messageId=str(uuid.uuid4()),
+        taskId=task_id,
+        contextId=context_id,
+    )
+
+
+def new_agent_parts_message(
+    parts: list[Part],
+    context_id: str | None = None,
+    task_id: str | None = None,
+) -> Message:
+    """Creates a new agent message containing a list of Parts.
+
+    Args:
+        parts: The list of `Part` objects for the message content.
+        context_id: The context ID for the message.
+        task_id: The task ID for the message.
+
+    Returns:
+        A new `Message` object with role 'agent'.
+    """
+    return Message(
+        role=Role.agent,
+        parts=parts,
+        messageId=str(uuid.uuid4()),
+        taskId=task_id,
+        contextId=context_id,
+    )
+
+
+def get_text_parts(parts: list[Part]) -> list[str]:
+    """Extracts text content from all TextPart objects in a list of Parts.
+
+    Args:
+        parts: A list of `Part` objects.
+
+    Returns:
+        A list of strings containing the text content from any `TextPart` objects found.
+    """
+    return [part.root.text for part in parts if isinstance(part.root, TextPart)]
+
+
+def get_message_text(message: Message, delimiter: str = '\n') -> str:
+    """Extracts and joins all text content from a Message's parts.
+
+    Args:
+        message: The `Message` object.
+        delimiter: The string to use when joining text from multiple TextParts.
+
+    Returns:
+        A single string containing all text content, or an empty string if no text parts are found.
+    """
+    return delimiter.join(get_text_parts(message.parts))

pygeai/vendor/a2a/utils/task.py

@@ -0,0 +1,57 @@
+"""Utility functions for creating A2A Task objects."""
+
+import uuid
+
+from a2a.types import Artifact, Message, Task, TaskState, TaskStatus
+
+
+def new_task(request: Message) -> Task:
+    """Creates a new Task object from an initial user message.
+
+    Generates task and context IDs if not provided in the message.
+
+    Args:
+        request: The initial `Message` object from the user.
+
+    Returns:
+        A new `Task` object initialized with 'submitted' status and the input message in history.
+    """
+    return Task(
+        status=TaskStatus(state=TaskState.submitted),
+        id=(request.taskId if request.taskId else str(uuid.uuid4())),
+        contextId=(
+            request.contextId if request.contextId else str(uuid.uuid4())
+        ),
+        history=[request],
+    )
+
+
+def completed_task(
+    task_id: str,
+    context_id: str,
+    artifacts: list[Artifact],
+    history: list[Message] | None = None,
+) -> Task:
+    """Creates a Task object in the 'completed' state.
+
+    Useful for constructing a final Task representation when the agent
+    finishes and produces artifacts.
+
+    Args:
+        task_id: The ID of the task.
+        context_id: The context ID of the task.
+        artifacts: A list of `Artifact` objects produced by the task.
+        history: An optional list of `Message` objects representing the task history.
+
+    Returns:
+        A `Task` object with status set to 'completed'.
+    """
+    if history is None:
+        history = []
+    return Task(
+        status=TaskStatus(state=TaskState.completed),
+        id=task_id,
+        contextId=context_id,
+        artifacts=artifacts,
+        history=history,
+    )