a2a-lite 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

a2a_lite/testing.py

@@ -3,21 +3,61 @@ Testing utilities for A2A Lite agents.
 
 Makes testing agents as simple as:
 
-    from a2a_lite.testing import TestClient
+    from a2a_lite.testing import AgentTestClient
 
     def test_my_agent():
-        client = TestClient(agent)
+        client = AgentTestClient(agent)
         result = client.call("greet", name="World")
         assert result == "Hello, World!"
 """
 from __future__ import annotations
 
 import json
+from dataclasses import dataclass
 from typing import Any, Dict, Optional
 from uuid import uuid4
 
 
-class TestClient:
+@dataclass
+class TestResult:
+    """
+    Structured result from a test client call.
+
+    Provides multiple ways to access the result:
+    - .data — parsed Python object (dict, list, int, str, etc.)
+    - .text — raw text string
+    - .json() — parse text as JSON (raises on invalid JSON)
+    - .raw_response — the full A2A response dict
+    """
+    _data: Any
+    _text: str
+    raw_response: Dict[str, Any]
+
+    @property
+    def data(self) -> Any:
+        """The parsed result value."""
+        return self._data
+
+    @property
+    def text(self) -> str:
+        """The raw text representation."""
+        return self._text
+
+    def json(self) -> Any:
+        """Parse the text as JSON."""
+        return json.loads(self._text)
+
+    def __eq__(self, other: Any) -> bool:
+        """Allow direct comparison with the data value for convenience."""
+        if isinstance(other, TestResult):
+            return self._data == other._data
+        return self._data == other
+
+    def __repr__(self) -> str:
+        return f"TestResult(data={self._data!r})"
+
+
+class AgentTestClient:
     """
     Simple test client for A2A Lite agents.
 
@@ -29,7 +69,7 @@ class TestClient:
             return a + b
 
         # In your test
-        client = TestClient(agent)
+        client = AgentTestClient(agent)
         assert client.call("add", a=2, b=3) == 5
     """
 
@@ -89,7 +129,7 @@ class TestClient:
         # Extract the actual result from A2A response
         return self._extract_result(data)
 
-    def _extract_result(self, response: Dict) -> Any:
+    def _extract_result(self, response: Dict) -> TestResult:
         """Extract the skill result from A2A response."""
         if "error" in response:
             raise TestClientError(response["error"])
@@ -103,11 +143,12 @@ class TestClient:
                 text = part.get("text", "")
                 # Try to parse as JSON
                 try:
-                    return json.loads(text)
+                    data = json.loads(text)
                 except json.JSONDecodeError:
-                    return text
+                    data = text
+                return TestResult(_data=data, _text=text, raw_response=response)
 
-        return result
+        return TestResult(_data=result, _text=json.dumps(result), raw_response=response)
 
     def get_agent_card(self) -> Dict[str, Any]:
         """
@@ -173,7 +214,7 @@ class TestClient:
                 result = await gen
                 results.append(result)
 
-        asyncio.get_event_loop().run_until_complete(run_handler())
+        asyncio.run(run_handler())
         return results
 
 
@@ -183,13 +224,13 @@ class TestClientError(Exception):
 
 
 # Async version for async tests
-class AsyncTestClient:
+class AsyncAgentTestClient:
     """
     Async test client for A2A Lite agents.
 
     Example:
         async def test_my_agent():
-            client = AsyncTestClient(agent)
+            client = AsyncAgentTestClient(agent)
             result = await client.call("greet", name="World")
             assert result == "Hello, World!"
     """
@@ -243,7 +284,7 @@ class AsyncTestClient:
 
         return self._extract_result(data)
 
-    def _extract_result(self, response: Dict) -> Any:
+    def _extract_result(self, response: Dict) -> TestResult:
         """Extract the skill result from A2A response."""
         if "error" in response:
             raise TestClientError(response["error"])
@@ -255,11 +296,12 @@ class AsyncTestClient:
             if part.get("kind") == "text" or part.get("type") == "text":
                 text = part.get("text", "")
                 try:
-                    return json.loads(text)
+                    data = json.loads(text)
                 except json.JSONDecodeError:
-                    return text
+                    data = text
+                return TestResult(_data=data, _text=text, raw_response=response)
 
-        return result
+        return TestResult(_data=result, _text=json.dumps(result), raw_response=response)
 
     async def close(self):
         """Close the client."""

a2a_lite/utils.py

@@ -5,6 +5,22 @@ from typing import Any, Dict, Type, get_origin, get_args, Union
 import inspect
 
 
+def _is_or_subclass(hint: Any, target_class: Type) -> bool:
+    """
+    Check if a type hint is, or is a subclass of, the target class.
+
+    Works with raw classes and string annotations.
+    """
+    try:
+        if hint is target_class:
+            return True
+        if isinstance(hint, type) and issubclass(hint, target_class):
+            return True
+    except TypeError:
+        pass
+    return False
+
+
 def type_to_json_schema(python_type: Type) -> Dict[str, Any]:
     """
     Convert Python type to JSON Schema.

a2a_lite-0.2.1.dist-info/METADATA

@@ -0,0 +1,526 @@
+Metadata-Version: 2.4
+Name: a2a-lite
+Version: 0.2.1
+Summary: Simplified wrapper for Google's A2A Protocol SDK
+Author: A2A Lite Contributors
+License-Expression: Apache-2.0
+Keywords: a2a,agents,ai,protocol,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: a2a-sdk[http-server]>=0.2.6
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: starlette>=0.40.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: watchfiles>=0.20.0
+Requires-Dist: zeroconf>=0.80.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# A2A Lite - Python
+
+**Build A2A agents in 8 lines. Add enterprise features when you need them.**
+
+Wraps the official [A2A Python SDK](https://github.com/a2aproject/a2a-python) with a simple, intuitive API.
+
+```python
+from a2a_lite import Agent
+
+agent = Agent(name="Bot", description="My bot")
+
+@agent.skill("greet")
+async def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+agent.run()
+```
+
+---
+
+## Installation
+
+```bash
+pip install a2a-lite
+# or
+uv add a2a-lite
+```
+
+**Requirements:** Python 3.10+
+
+---
+
+## Quick Start
+
+### 1. Create an agent
+
+```python
+from a2a_lite import Agent
+
+agent = Agent(name="Calculator", description="Does math")
+
+@agent.skill("add")
+async def add(a: int, b: int) -> int:
+    return a + b
+
+@agent.skill("multiply")
+async def multiply(a: int, b: int) -> int:
+    return a * b
+
+agent.run(port=8787)
+```
+
+### 2. Test it
+
+```python
+from a2a_lite import Agent, AgentTestClient
+
+agent = Agent(name="Calculator", description="Does math")
+
+@agent.skill("add")
+async def add(a: int, b: int) -> int:
+    return a + b
+
+client = AgentTestClient(agent)
+result = client.call("add", a=2, b=3)
+assert result == 5
+```
+
+### 3. Call it
+
+```bash
+curl -X POST http://localhost:8787/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "id": "1",
+    "params": {
+      "message": {
+        "role": "user",
+        "parts": [{"type": "text", "text": "{\"skill\": \"add\", \"params\": {\"a\": 2, \"b\": 3}}"}],
+        "messageId": "msg-1"
+      }
+    }
+  }'
+```
+
+---
+
+## Progressive Complexity
+
+### Level 1: Basic Skills
+
+```python
+from a2a_lite import Agent
+
+agent = Agent(name="Bot", description="A bot")
+
+@agent.skill("greet")
+async def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+agent.run()
+```
+
+### Level 2: Pydantic Models (Just Works)
+
+Pass dicts from callers — they're auto-converted to Pydantic models:
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    email: str
+
+@agent.skill("create_user")
+async def create_user(user: User) -> dict:
+    # 'user' is already a User instance — auto-converted from dict!
+    return {"id": 1, "name": user.name}
+```
+
+Lists of models work too:
+
+```python
+from typing import List
+
+@agent.skill("count_users")
+async def count_users(users: List[User]) -> int:
+    return len(users)
+```
+
+### Level 3: Streaming (Just Yield)
+
+```python
+@agent.skill("chat", streaming=True)
+async def chat(message: str):
+    for word in message.split():
+        yield word + " "
+```
+
+### Level 4: Middleware
+
+```python
+@agent.middleware
+async def log_requests(ctx, next):
+    print(f"Calling: {ctx.skill}")
+    result = await next()
+    print(f"Result: {result}")
+    return result
+```
+
+Built-in middleware:
+
+```python
+from a2a_lite import logging_middleware, timing_middleware, retry_middleware, rate_limit_middleware
+
+agent.use(logging_middleware)
+agent.use(timing_middleware)
+agent.use(rate_limit_middleware(max_per_minute=60))
+agent.use(retry_middleware(max_retries=3))
+```
+
+### Level 5: Human-in-the-Loop
+
+```python
+from a2a_lite import InteractionContext
+
+@agent.skill("wizard")
+async def wizard(ctx: InteractionContext) -> dict:
+    name = await ctx.ask("What's your name?")
+    role = await ctx.ask("Role?", options=["Dev", "Manager"])
+
+    if await ctx.confirm(f"Create {name} as {role}?"):
+        return {"created": name}
+    return {"cancelled": True}
+```
+
+### Level 6: File Handling
+
+```python
+from a2a_lite import FilePart
+
+@agent.skill("summarize")
+async def summarize(doc: FilePart) -> str:
+    content = await doc.read_text()
+    return f"Summary: {content[:100]}..."
+```
+
+### Level 7: Task Tracking
+
+```python
+from a2a_lite import TaskContext
+
+agent = Agent(name="Bot", description="A bot", task_store="memory")
+
+@agent.skill("process")
+async def process(data: str, task: TaskContext) -> str:
+    await task.update("working", "Starting...", progress=0.0)
+
+    for i in range(10):
+        await task.update("working", f"Step {i}/10", progress=i/10)
+
+    return "Done!"
+```
+
+### Level 8: Authentication
+
+```python
+from a2a_lite import Agent, APIKeyAuth
+
+agent = Agent(
+    name="SecureBot",
+    description="A secure bot",
+    auth=APIKeyAuth(keys=["secret-key-1", "secret-key-2"]),
+)
+```
+
+API keys are hashed in memory using SHA-256 — plaintext keys are never stored.
+
+Other auth providers:
+
+```python
+from a2a_lite.auth import BearerAuth, OAuth2Auth
+
+# Bearer/JWT
+agent = Agent(
+    name="Bot", description="A bot",
+    auth=BearerAuth(secret="your-jwt-secret"),
+)
+
+# OAuth2
+agent = Agent(
+    name="Bot", description="A bot",
+    auth=OAuth2Auth(issuer="https://auth.example.com", audience="my-api"),
+)
+```
+
+### Level 9: CORS and Production Mode
+
+```python
+agent = Agent(
+    name="Bot",
+    description="A bot",
+    cors_origins=["https://myapp.com", "https://admin.myapp.com"],
+    production=True,  # Warns if running over HTTP
+)
+```
+
+### Level 10: Webhooks
+
+```python
+@agent.on_complete
+async def notify(skill_name, result):
+    print(f"Skill {skill_name} completed with: {result}")
+```
+
+---
+
+## Testing
+
+### AgentTestClient
+
+The synchronous test client for use with pytest:
+
+```python
+from a2a_lite import Agent, AgentTestClient
+
+agent = Agent(name="Bot", description="Test")
+
+@agent.skill("greet")
+async def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+@agent.skill("info")
+async def info(name: str, age: int) -> dict:
+    return {"name": name, "age": age}
+
+
+def test_simple_result():
+    client = AgentTestClient(agent)
+    result = client.call("greet", name="World")
+    # Simple values support direct equality
+    assert result == "Hello, World!"
+
+
+def test_dict_result():
+    client = AgentTestClient(agent)
+    result = client.call("info", name="Alice", age=30)
+    # Access dict results via .data
+    assert result.data["name"] == "Alice"
+    assert result.data["age"] == 30
+
+
+def test_text_access():
+    client = AgentTestClient(agent)
+    result = client.call("greet", name="World")
+    # .text gives the raw string
+    assert result.text == '"Hello, World!"'
+
+
+def test_list_skills():
+    client = AgentTestClient(agent)
+    skills = client.list_skills()
+    assert "greet" in skills
+    assert "info" in skills
+```
+
+### TestResult
+
+Every `client.call()` returns a `TestResult` with:
+
+| Property | Description |
+|----------|-------------|
+| `.data` | Parsed Python object (dict, list, int, str, etc.) |
+| `.text` | Raw text string from the response |
+| `.json()` | Parse text as JSON (raises on invalid JSON) |
+| `.raw_response` | Full A2A response dict |
+
+`TestResult` supports direct equality comparison for simple values (`result == 5`), but use `.data` for subscripting (`result.data["key"]`).
+
+### AsyncAgentTestClient
+
+For async test frameworks:
+
+```python
+import pytest
+from a2a_lite import AsyncAgentTestClient
+
+@pytest.mark.asyncio
+async def test_async():
+    client = AsyncAgentTestClient(agent)
+    result = await client.call("greet", name="World")
+    assert result == "Hello, World!"
+    await client.close()
+```
+
+### Streaming Tests
+
+```python
+def test_streaming():
+    client = AgentTestClient(agent)
+    results = client.stream("chat", message="hello world")
+    assert len(results) == 2
+```
+
+---
+
+## Task Store
+
+The `TaskStore` provides async-safe task lifecycle management:
+
+```python
+from a2a_lite.tasks import TaskStore, TaskStatus
+
+store = TaskStore()
+
+# All operations are async and thread-safe
+task = await store.create(task_id="task-1", skill="process")
+task = await store.get("task-1")
+await store.update("task-1", status=TaskStatus.WORKING, progress=0.5)
+tasks = await store.list()
+await store.delete("task-1")
+```
+
+---
+
+## Agent Discovery
+
+Find agents on your local network via mDNS:
+
+```python
+from a2a_lite import AgentDiscovery
+
+# Advertise your agent
+agent.run(port=8787, enable_discovery=True)
+
+# Discover other agents
+discovery = AgentDiscovery()
+agents = await discovery.discover(timeout=5.0)
+for a in agents:
+    print(f"{a.name} at {a.url}")
+```
+
+---
+
+## CLI
+
+```bash
+a2a-lite init my-agent          # Create new project
+a2a-lite serve agent.py         # Run agent from file
+a2a-lite serve agent.py -r      # Run with hot reload
+a2a-lite inspect http://...     # View agent capabilities
+a2a-lite test http://... skill  # Test a skill
+a2a-lite discover               # Find local agents
+a2a-lite version                # Show version
+```
+
+---
+
+## Full API Reference
+
+### Agent
+
+```python
+Agent(
+    name: str,                          # Required
+    description: str,                   # Required
+    version: str = "1.0.0",
+    url: str = None,                    # Override auto-detected URL
+    auth: AuthProvider = None,          # Authentication provider
+    task_store: str | TaskStore = None, # "memory" or custom TaskStore
+    cors_origins: List[str] = None,     # CORS allowed origins
+    production: bool = False,           # Enable production warnings
+    enable_discovery: bool = False,     # mDNS discovery
+)
+```
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `@agent.skill(name, **config)` | Register a skill via decorator |
+| `@agent.middleware` | Register middleware via decorator |
+| `agent.use(middleware)` | Register middleware function |
+| `@agent.on_complete` | Register completion hook |
+| `agent.run(port=8787)` | Start the server |
+| `agent.get_app()` | Get the ASGI app (for custom deployment) |
+
+### Skill Decorator
+
+```python
+@agent.skill(
+    name: str,                    # Skill name (required)
+    description: str = None,      # Human-readable description
+    tags: List[str] = None,       # Categorization tags
+    streaming: bool = False,      # Enable streaming
+)
+```
+
+### Auth Providers
+
+| Provider | Usage |
+|----------|-------|
+| `APIKeyAuth(keys=[...])` | API key auth (keys hashed with SHA-256) |
+| `BearerAuth(secret=...)` | JWT/Bearer token auth |
+| `OAuth2Auth(issuer=..., audience=...)` | OAuth2 auth |
+| `NoAuth()` | No auth (default) |
+
+### Special Parameter Types
+
+These are auto-injected when detected in skill signatures:
+
+| Type | Description |
+|------|-------------|
+| `TaskContext` | Task lifecycle management (requires `task_store`) |
+| `InteractionContext` | Human-in-the-loop interactions |
+| `FilePart` | File upload handling |
+
+---
+
+## Examples
+
+| Example | What it shows |
+|---------|---------------|
+| [01_hello_world.py](examples/01_hello_world.py) | Simplest agent (8 lines) |
+| [02_calculator.py](examples/02_calculator.py) | Multiple skills |
+| [06_pydantic_models.py](examples/06_pydantic_models.py) | Auto Pydantic conversion |
+| [08_streaming.py](examples/08_streaming.py) | Streaming responses |
+| [09_testing.py](examples/09_testing.py) | Testing your agents |
+| [11_human_in_the_loop.py](examples/11_human_in_the_loop.py) | Ask user questions |
+| [12_file_handling.py](examples/12_file_handling.py) | Handle files |
+| [13_task_tracking.py](examples/13_task_tracking.py) | Progress updates |
+| [14_with_auth.py](examples/14_with_auth.py) | Authentication |
+
+---
+
+## 100% A2A Protocol Compatible
+
+A2A Lite wraps the official A2A Python SDK. Every feature maps to real A2A protocol concepts:
+
+| A2A Lite | A2A Protocol |
+|----------|--------------|
+| `@agent.skill()` | Agent Skills |
+| `streaming=True` | SSE Streaming |
+| `InteractionContext.ask()` | `input-required` state |
+| `TaskContext.update()` | Task lifecycle states |
+| `FilePart` | A2A File parts |
+| `APIKeyAuth` / `BearerAuth` | Security schemes |
+
+---
+
+## License
+
+Apache 2.0

a2a_lite-0.2.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+a2a_lite/__init__.py,sha256=5bFZw7LapphdqfvMvyKfyEthe_kH4iigeGChd5h3TI4,3520
+a2a_lite/agent.py,sha256=WyHe9aA_BYkzIXRjN5byoRc-vItCyL6YLDiyfX5gfPU,17053
+a2a_lite/auth.py,sha256=bjPu_xnAxmfK5_dkqYz5mHouAjHqJFWlfYMqn-S1-A4,10177
+a2a_lite/cli.py,sha256=D46mGduJb8AcZz8WRczNx5OzvIGxqZ7H-4fLCy2LpX8,9043
+a2a_lite/decorators.py,sha256=VdinkddmF61IS8TkjdSfHGdn3nDKwepcIjWZPZBKg3w,1050
+a2a_lite/discovery.py,sha256=BxpiJAUDxIyI2gvsLhjmHte5c9ax5Qf1hbBQnyAmxLQ,4508
+a2a_lite/executor.py,sha256=zkTotenRNa7wlHh6pnIcS546fx5laSgoVIxZizE7SQI,13218
+a2a_lite/human_loop.py,sha256=XAqxp-k8I7TNyuLqqNmLEqABHqcAUiKYCL8n3W5StaY,8685
+a2a_lite/middleware.py,sha256=c6jb9aFfyTf-JY6KjqaSgFJmpzqbHLC6Q1h9NNteqzo,5545
+a2a_lite/parts.py,sha256=qVRiD-H9_NlMPk-R0gTUiGVQ77E2poiuBWAUyAyAoTI,6177
+a2a_lite/streaming.py,sha256=RFv9EJYnhwkT0h1Wovkj4EXwFzCgHdaA-h7WpPaaONo,2329
+a2a_lite/tasks.py,sha256=UpmDP-VGIQ1LodBNq4zx2pJElQ31gOJOAduHFBVyxOA,7039
+a2a_lite/testing.py,sha256=blugOpPKNThlbFTTSCyBVHb7tgQH79RH8z7Vo45hGbg,8953
+a2a_lite/utils.py,sha256=CnkO6HH9oKEXymbJG2ohdt1ESxldQ3fkmcYVO-o9R_k,3841
+a2a_lite/webhooks.py,sha256=t6ebT3jVBEKFpjhBnPI-nuQWIUKQUbJm24phXOBnNKA,6158
+a2a_lite-0.2.1.dist-info/METADATA,sha256=5QLYvcVJh3qwri1zR3Gg-so5YLaAXXAIr-TvvhAg9UM,12583
+a2a_lite-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+a2a_lite-0.2.1.dist-info/entry_points.txt,sha256=BONfFqZbCntNal2iwlTJAE09gCUvurfvqslMYVYh4is,46
+a2a_lite-0.2.1.dist-info/RECORD,,