a2a-lite 0.1.0__py3-none-any.whl

a2a_lite/human_loop.py

@@ -0,0 +1,284 @@
+"""
+Human-in-the-loop support (OPTIONAL).
+
+Allows agents to ask users for clarification mid-task.
+Uses A2A's "input-required" task state.
+
+Example (simple - no human loop needed):
+    @agent.skill("greet")
+    async def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+Example (with human-in-the-loop - opt-in):
+    @agent.skill("book_flight")
+    async def book_flight(destination: str, ctx: InteractionContext) -> str:
+        # Ask user for date
+        date = await ctx.ask("What date do you want to travel?")
+
+        # Ask for confirmation with options
+        confirm = await ctx.ask(
+            f"Book flight to {destination} on {date}?",
+            options=["Yes", "No", "Change date"]
+        )
+
+        if confirm == "Yes":
+            return f"Booked flight to {destination} on {date}!"
+        elif confirm == "Change date":
+            new_date = await ctx.ask("Enter new date:")
+            return f"Booked flight to {destination} on {new_date}!"
+        else:
+            return "Booking cancelled."
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Union
+from uuid import uuid4
+import asyncio
+
+
+@dataclass
+class InputRequest:
+    """Request for user input."""
+    id: str
+    prompt: str
+    options: Optional[List[str]] = None
+    input_type: str = "text"  # text, choice, confirm, file
+    required: bool = True
+    default: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "prompt": self.prompt,
+            "options": self.options,
+            "type": self.input_type,
+            "required": self.required,
+            "default": self.default,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class InputResponse:
+    """User's response to input request."""
+    request_id: str
+    value: Any
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class InteractionContext:
+    """
+    Context for human-in-the-loop interactions.
+
+    Passed to skills that need to ask users questions.
+
+    Example:
+        @agent.skill("wizard")
+        async def wizard(ctx: InteractionContext) -> str:
+            name = await ctx.ask("What's your name?")
+            age = await ctx.ask("How old are you?", input_type="number")
+            confirm = await ctx.confirm(f"Create profile for {name}, age {age}?")
+
+            if confirm:
+                return f"Created profile for {name}!"
+            return "Cancelled."
+    """
+
+    def __init__(
+        self,
+        task_id: str,
+        event_queue=None,
+        response_handler: Optional[Callable] = None,
+    ):
+        self.task_id = task_id
+        self._event_queue = event_queue
+        self._response_handler = response_handler
+        self._pending_requests: Dict[str, asyncio.Future] = {}
+
+    async def ask(
+        self,
+        prompt: str,
+        options: Optional[List[str]] = None,
+        input_type: str = "text",
+        required: bool = True,
+        default: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> str:
+        """
+        Ask the user a question and wait for response.
+
+        Args:
+            prompt: Question to ask
+            options: List of options (for choice type)
+            input_type: "text", "choice", "number", "file"
+            required: Whether input is required
+            default: Default value if not required
+            timeout: Timeout in seconds
+
+        Returns:
+            User's response
+
+        Example:
+            name = await ctx.ask("What's your name?")
+            choice = await ctx.ask("Pick one:", options=["A", "B", "C"])
+        """
+        request = InputRequest(
+            id=uuid4().hex,
+            prompt=prompt,
+            options=options,
+            input_type="choice" if options else input_type,
+            required=required,
+            default=default,
+        )
+
+        # Create future for response
+        future: asyncio.Future = asyncio.Future()
+        self._pending_requests[request.id] = future
+
+        # Send input-required event
+        await self._send_input_request(request)
+
+        # Wait for response
+        try:
+            if timeout:
+                response = await asyncio.wait_for(future, timeout=timeout)
+            else:
+                response = await future
+            return response.value
+        except asyncio.TimeoutError:
+            if default is not None:
+                return default
+            raise TimeoutError(f"No response received for: {prompt}")
+        finally:
+            self._pending_requests.pop(request.id, None)
+
+    async def confirm(
+        self,
+        prompt: str,
+        yes_label: str = "Yes",
+        no_label: str = "No",
+    ) -> bool:
+        """
+        Ask for yes/no confirmation.
+
+        Example:
+            if await ctx.confirm("Are you sure?"):
+                do_something()
+        """
+        response = await self.ask(
+            prompt,
+            options=[yes_label, no_label],
+            input_type="choice",
+        )
+        return response == yes_label
+
+    async def choose(
+        self,
+        prompt: str,
+        options: List[str],
+        allow_multiple: bool = False,
+    ) -> Union[str, List[str]]:
+        """
+        Ask user to choose from options.
+
+        Example:
+            color = await ctx.choose("Pick a color:", ["Red", "Blue", "Green"])
+        """
+        response = await self.ask(prompt, options=options, input_type="choice")
+        if allow_multiple and isinstance(response, str):
+            return [response]
+        return response
+
+    async def _send_input_request(self, request: InputRequest) -> None:
+        """Send input-required event via SSE."""
+        if self._event_queue:
+            from a2a.utils import new_agent_text_message
+            import json
+
+            msg = json.dumps({
+                "_type": "input_required",
+                "task_id": self.task_id,
+                "request": request.to_dict(),
+            })
+            await self._event_queue.enqueue_event(new_agent_text_message(msg))
+
+    def handle_response(self, request_id: str, value: Any) -> bool:
+        """
+        Handle incoming response from user.
+
+        Called by the executor when user responds.
+        """
+        future = self._pending_requests.get(request_id)
+        if future and not future.done():
+            response = InputResponse(request_id=request_id, value=value)
+            future.set_result(response)
+            return True
+        return False
+
+
+class ConversationMemory:
+    """
+    Simple conversation memory for multi-turn interactions.
+
+    Example:
+        @agent.skill("chat")
+        async def chat(message: str, memory: ConversationMemory) -> str:
+            # Get conversation history
+            history = memory.get_messages()
+
+            # Add user message
+            memory.add_user(message)
+
+            # Generate response (using history for context)
+            response = await generate_response(message, history)
+
+            # Add assistant response
+            memory.add_assistant(response)
+
+            return response
+    """
+
+    def __init__(self, max_messages: int = 100):
+        self._messages: List[Dict[str, str]] = []
+        self._max_messages = max_messages
+        self._metadata: Dict[str, Any] = {}
+
+    def add_user(self, content: str) -> None:
+        """Add user message."""
+        self._add_message("user", content)
+
+    def add_assistant(self, content: str) -> None:
+        """Add assistant message."""
+        self._add_message("assistant", content)
+
+    def add_system(self, content: str) -> None:
+        """Add system message."""
+        self._add_message("system", content)
+
+    def _add_message(self, role: str, content: str) -> None:
+        self._messages.append({"role": role, "content": content})
+        # Trim if over limit
+        if len(self._messages) > self._max_messages:
+            self._messages = self._messages[-self._max_messages:]
+
+    def get_messages(self) -> List[Dict[str, str]]:
+        """Get all messages."""
+        return list(self._messages)
+
+    def get_last(self, n: int = 10) -> List[Dict[str, str]]:
+        """Get last n messages."""
+        return self._messages[-n:]
+
+    def clear(self) -> None:
+        """Clear all messages."""
+        self._messages.clear()
+
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Set metadata."""
+        self._metadata[key] = value
+
+    def get_metadata(self, key: str, default: Any = None) -> Any:
+        """Get metadata."""
+        return self._metadata.get(key, default)

a2a_lite/middleware.py

@@ -0,0 +1,193 @@
+"""
+Middleware support for A2A Lite agents.
+
+Middleware allows you to add cross-cutting concerns like logging,
+authentication, rate limiting, etc.
+
+Example:
+    @agent.middleware
+    async def log_requests(ctx, next):
+        print(f"Request: {ctx.skill}")
+        result = await next()
+        print(f"Result: {result}")
+        return result
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+import asyncio
+
+
+@dataclass
+class MiddlewareContext:
+    """
+    Context passed to middleware functions.
+
+    Attributes:
+        skill: The skill being called (if determined)
+        params: The parameters for the skill
+        message: The raw message text
+        metadata: Arbitrary metadata dict for middleware to share data
+    """
+    skill: Optional[str] = None
+    params: Dict[str, Any] = field(default_factory=dict)
+    message: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class MiddlewareChain:
+    """
+    Manages the middleware execution chain.
+
+    Middleware functions are called in order, each receiving the context
+    and a `next` function to call the next middleware (or the final handler).
+    """
+
+    def __init__(self):
+        self._middlewares: List[Callable] = []
+
+    def add(self, middleware: Callable) -> None:
+        """Add a middleware function to the chain."""
+        self._middlewares.append(middleware)
+
+    async def execute(
+        self,
+        context: MiddlewareContext,
+        final_handler: Callable,
+    ) -> Any:
+        """
+        Execute the middleware chain.
+
+        Args:
+            context: The middleware context
+            final_handler: The final handler to call after all middleware
+
+        Returns:
+            The result from the handler (possibly modified by middleware)
+        """
+        # Build the chain from the end
+        async def call_final():
+            return await final_handler(context)
+
+        # Wrap each middleware around the next
+        next_fn = call_final
+        for middleware in reversed(self._middlewares):
+            next_fn = self._wrap_middleware(middleware, context, next_fn)
+
+        return await next_fn()
+
+    def _wrap_middleware(
+        self,
+        middleware: Callable,
+        context: MiddlewareContext,
+        next_fn: Callable,
+    ) -> Callable:
+        """Wrap a middleware function."""
+        async def wrapped():
+            if asyncio.iscoroutinefunction(middleware):
+                return await middleware(context, next_fn)
+            else:
+                return middleware(context, next_fn)
+        return wrapped
+
+
+# Built-in middleware helpers
+
+def logging_middleware(logger=None):
+    """
+    Create a logging middleware.
+
+    Example:
+        agent.add_middleware(logging_middleware())
+    """
+    import logging
+    log = logger or logging.getLogger("a2a_lite")
+
+    async def middleware(ctx: MiddlewareContext, next):
+        log.info(f"Calling skill: {ctx.skill} with params: {ctx.params}")
+        try:
+            result = await next()
+            log.info(f"Skill {ctx.skill} returned successfully")
+            return result
+        except Exception as e:
+            log.error(f"Skill {ctx.skill} failed: {e}")
+            raise
+
+    return middleware
+
+
+def timing_middleware():
+    """
+    Create a timing middleware that adds execution time to metadata.
+
+    Example:
+        agent.add_middleware(timing_middleware())
+    """
+    import time
+
+    async def middleware(ctx: MiddlewareContext, next):
+        start = time.perf_counter()
+        result = await next()
+        elapsed = time.perf_counter() - start
+        ctx.metadata["execution_time_ms"] = round(elapsed * 1000, 2)
+        return result
+
+    return middleware
+
+
+def retry_middleware(max_retries: int = 3, delay: float = 1.0):
+    """
+    Create a retry middleware for failed skill calls.
+
+    Example:
+        agent.add_middleware(retry_middleware(max_retries=3))
+    """
+    async def middleware(ctx: MiddlewareContext, next):
+        last_error = None
+        for attempt in range(max_retries):
+            try:
+                return await next()
+            except Exception as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    await asyncio.sleep(delay * (attempt + 1))
+        raise last_error
+
+    return middleware
+
+
+def rate_limit_middleware(requests_per_minute: int = 60):
+    """
+    Create a simple rate limiting middleware.
+
+    Example:
+        agent.add_middleware(rate_limit_middleware(requests_per_minute=100))
+    """
+    import time
+    from collections import deque
+
+    request_times = deque()
+
+    async def middleware(ctx: MiddlewareContext, next):
+        now = time.time()
+        minute_ago = now - 60
+
+        # Remove old requests
+        while request_times and request_times[0] < minute_ago:
+            request_times.popleft()
+
+        if len(request_times) >= requests_per_minute:
+            raise RateLimitExceeded(
+                f"Rate limit exceeded: {requests_per_minute} requests per minute"
+            )
+
+        request_times.append(now)
+        return await next()
+
+    return middleware
+
+
+class RateLimitExceeded(Exception):
+    """Raised when rate limit is exceeded."""
+    pass

a2a_lite/parts.py

@@ -0,0 +1,218 @@
+"""
+Multi-modal parts support (Text, File, Data).
+
+OPTIONAL - Only use if you need files or structured data.
+Simple text skills work without any of this.
+
+Example (simple - no parts needed):
+    @agent.skill("greet")
+    async def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+Example (with files - opt-in):
+    from a2a_lite import FilePart, DataPart
+
+    @agent.skill("summarize")
+    async def summarize(document: FilePart) -> str:
+        content = await document.read_text()
+        return summarize(content)
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Union
+from pathlib import Path
+
+
+@dataclass
+class TextPart:
+    """Simple text content."""
+    text: str
+
+    def to_a2a(self) -> Dict[str, Any]:
+        return {"type": "text", "text": self.text}
+
+    @classmethod
+    def from_a2a(cls, data: Dict) -> "TextPart":
+        return cls(text=data.get("text", ""))
+
+
+@dataclass
+class FilePart:
+    """
+    File content - can be bytes or a URI.
+
+    Example:
+        @agent.skill("process")
+        async def process(file: FilePart) -> str:
+            if file.is_uri:
+                # Download from URI
+                content = await fetch(file.uri)
+            else:
+                # Use bytes directly
+                content = file.data
+
+            return process_content(content)
+    """
+    name: str
+    mime_type: str = "application/octet-stream"
+    data: Optional[bytes] = None
+    uri: Optional[str] = None
+
+    @property
+    def is_uri(self) -> bool:
+        return self.uri is not None
+
+    @property
+    def is_bytes(self) -> bool:
+        return self.data is not None
+
+    async def read_bytes(self) -> bytes:
+        """Read file content as bytes."""
+        if self.data:
+            return self.data
+        if self.uri:
+            import httpx
+            async with httpx.AsyncClient() as client:
+                response = await client.get(self.uri)
+                response.raise_for_status()
+                return response.content
+        raise ValueError("FilePart has no data or URI")
+
+    async def read_text(self, encoding: str = "utf-8") -> str:
+        """Read file content as text."""
+        data = await self.read_bytes()
+        return data.decode(encoding)
+
+    def to_a2a(self) -> Dict[str, Any]:
+        if self.uri:
+            return {
+                "type": "file",
+                "file": {
+                    "name": self.name,
+                    "mimeType": self.mime_type,
+                    "uri": self.uri,
+                }
+            }
+        else:
+            return {
+                "type": "file",
+                "file": {
+                    "name": self.name,
+                    "mimeType": self.mime_type,
+                    "bytes": base64.b64encode(self.data or b"").decode(),
+                }
+            }
+
+    @classmethod
+    def from_a2a(cls, data: Dict) -> "FilePart":
+        file_data = data.get("file", {})
+        bytes_data = file_data.get("bytes")
+        return cls(
+            name=file_data.get("name", "unknown"),
+            mime_type=file_data.get("mimeType", "application/octet-stream"),
+            data=base64.b64decode(bytes_data) if bytes_data else None,
+            uri=file_data.get("uri"),
+        )
+
+    @classmethod
+    def from_path(cls, path: Union[str, Path], mime_type: Optional[str] = None) -> "FilePart":
+        """Create FilePart from a local file path."""
+        path = Path(path)
+        if mime_type is None:
+            import mimetypes
+            mime_type = mimetypes.guess_type(str(path))[0] or "application/octet-stream"
+        return cls(
+            name=path.name,
+            mime_type=mime_type,
+            data=path.read_bytes(),
+        )
+
+
+@dataclass
+class DataPart:
+    """
+    Structured JSON data.
+
+    Example:
+        @agent.skill("analyze")
+        async def analyze(data: DataPart) -> DataPart:
+            result = process(data.data)
+            return DataPart(data=result)
+    """
+    data: Dict[str, Any]
+    mime_type: str = "application/json"
+
+    def to_a2a(self) -> Dict[str, Any]:
+        return {
+            "type": "data",
+            "data": self.data,
+        }
+
+    @classmethod
+    def from_a2a(cls, data: Dict) -> "DataPart":
+        return cls(data=data.get("data", {}))
+
+
+@dataclass
+class Artifact:
+    """
+    Rich output artifact.
+
+    Use when you need more than just text/JSON return.
+
+    Example:
+        @agent.skill("generate_report")
+        async def generate_report(query: str) -> Artifact:
+            return Artifact(
+                name="report.pdf",
+                parts=[
+                    TextPart("Summary: ..."),
+                    FilePart.from_path("report.pdf"),
+                ],
+            )
+    """
+    name: Optional[str] = None
+    description: Optional[str] = None
+    parts: list = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def add_text(self, text: str) -> "Artifact":
+        """Add text to artifact."""
+        self.parts.append(TextPart(text=text))
+        return self
+
+    def add_file(self, file: FilePart) -> "Artifact":
+        """Add file to artifact."""
+        self.parts.append(file)
+        return self
+
+    def add_data(self, data: Dict[str, Any]) -> "Artifact":
+        """Add structured data to artifact."""
+        self.parts.append(DataPart(data=data))
+        return self
+
+    def to_a2a(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parts": [p.to_a2a() for p in self.parts],
+            "metadata": self.metadata,
+        }
+
+
+# Helper to parse incoming parts
+def parse_part(data: Dict) -> Union[TextPart, FilePart, DataPart]:
+    """Parse an A2A part dict into the appropriate Part type."""
+    part_type = data.get("type") or data.get("kind")
+
+    if part_type == "text":
+        return TextPart.from_a2a(data)
+    elif part_type == "file":
+        return FilePart.from_a2a(data)
+    elif part_type == "data":
+        return DataPart.from_a2a(data)
+    else:
+        # Default to text
+        return TextPart(text=str(data))