a2a-lite 0.1.0__py3-none-any.whl

a2a_lite/auth.py

@@ -0,0 +1,344 @@
+"""
+Authentication support (OPTIONAL).
+
+By default, A2A Lite agents have no authentication.
+Add auth when you need it for enterprise deployments.
+
+Example (simple - no auth):
+    agent = Agent(name="Bot", description="Open bot")
+    agent.run()  # Anyone can access
+
+Example (with API key - opt-in):
+    from a2a_lite.auth import APIKeyAuth
+
+    agent = Agent(
+        name="SecureBot",
+        auth=APIKeyAuth(keys=["secret-key-123"]),
+    )
+
+Example (with OAuth2 - opt-in):
+    from a2a_lite.auth import OAuth2Auth
+
+    agent = Agent(
+        name="EnterpriseBot",
+        auth=OAuth2Auth(
+            issuer="https://auth.company.com",
+            audience="my-agent",
+        ),
+    )
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set
+import hashlib
+import hmac
+import time
+
+
+class AuthProvider(ABC):
+    """Base class for authentication providers."""
+
+    @abstractmethod
+    async def authenticate(self, request: "AuthRequest") -> "AuthResult":
+        """Authenticate a request."""
+        pass
+
+    @abstractmethod
+    def get_scheme(self) -> Dict[str, Any]:
+        """Get A2A security scheme for agent card."""
+        pass
+
+
+@dataclass
+class AuthRequest:
+    """Incoming authentication request."""
+    headers: Dict[str, str]
+    query_params: Dict[str, str] = field(default_factory=dict)
+    body: Optional[bytes] = None
+    method: str = "POST"
+    path: str = "/"
+
+
+@dataclass
+class AuthResult:
+    """Authentication result."""
+    authenticated: bool
+    user_id: Optional[str] = None
+    scopes: Set[str] = field(default_factory=set)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+
+    @classmethod
+    def success(
+        cls,
+        user_id: str,
+        scopes: Optional[Set[str]] = None,
+        **metadata,
+    ) -> "AuthResult":
+        return cls(
+            authenticated=True,
+            user_id=user_id,
+            scopes=scopes or set(),
+            metadata=metadata,
+        )
+
+    @classmethod
+    def failure(cls, error: str) -> "AuthResult":
+        return cls(authenticated=False, error=error)
+
+
+class NoAuth(AuthProvider):
+    """No authentication (default)."""
+
+    async def authenticate(self, request: AuthRequest) -> AuthResult:
+        return AuthResult.success(user_id="anonymous")
+
+    def get_scheme(self) -> Dict[str, Any]:
+        return {}
+
+
+class APIKeyAuth(AuthProvider):
+    """
+    Simple API key authentication.
+
+    Example:
+        auth = APIKeyAuth(
+            keys=["key1", "key2"],
+            header="X-API-Key",  # or use query param
+        )
+    """
+
+    def __init__(
+        self,
+        keys: List[str],
+        header: str = "X-API-Key",
+        query_param: Optional[str] = None,
+    ):
+        self.keys = set(keys)
+        self.header = header
+        self.query_param = query_param
+
+    async def authenticate(self, request: AuthRequest) -> AuthResult:
+        # Check header
+        key = request.headers.get(self.header)
+
+        # Check query param
+        if not key and self.query_param:
+            key = request.query_params.get(self.query_param)
+
+        if not key:
+            return AuthResult.failure("API key required")
+
+        if key not in self.keys:
+            return AuthResult.failure("Invalid API key")
+
+        # Use hash of key as user ID
+        user_id = hashlib.sha256(key.encode()).hexdigest()[:16]
+        return AuthResult.success(user_id=user_id)
+
+    def get_scheme(self) -> Dict[str, Any]:
+        return {
+            "type": "apiKey",
+            "in": "header" if not self.query_param else "query",
+            "name": self.header if not self.query_param else self.query_param,
+        }
+
+
+class BearerAuth(AuthProvider):
+    """
+    Bearer token authentication.
+
+    For custom token validation (JWT, etc).
+
+    Example:
+        def validate_token(token: str) -> Optional[str]:
+            # Your validation logic
+            if is_valid(token):
+                return get_user_id(token)
+            return None
+
+        auth = BearerAuth(validator=validate_token)
+    """
+
+    def __init__(
+        self,
+        validator: Callable[[str], Optional[str]],
+        header: str = "Authorization",
+    ):
+        self.validator = validator
+        self.header = header
+
+    async def authenticate(self, request: AuthRequest) -> AuthResult:
+        auth_header = request.headers.get(self.header, "")
+
+        if not auth_header.startswith("Bearer "):
+            return AuthResult.failure("Bearer token required")
+
+        token = auth_header[7:]  # Remove "Bearer "
+
+        user_id = self.validator(token)
+        if user_id is None:
+            return AuthResult.failure("Invalid token")
+
+        return AuthResult.success(user_id=user_id)
+
+    def get_scheme(self) -> Dict[str, Any]:
+        return {
+            "type": "http",
+            "scheme": "bearer",
+        }
+
+
+class OAuth2Auth(AuthProvider):
+    """
+    OAuth2/OIDC authentication.
+
+    Validates JWT tokens from an OAuth2 provider.
+
+    Example:
+        auth = OAuth2Auth(
+            issuer="https://auth.company.com",
+            audience="my-agent",
+        )
+
+    Requires: pip install pyjwt[crypto]
+    """
+
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        jwks_uri: Optional[str] = None,
+        algorithms: List[str] = None,
+    ):
+        self.issuer = issuer
+        self.audience = audience
+        self.jwks_uri = jwks_uri or f"{issuer}/.well-known/jwks.json"
+        self.algorithms = algorithms or ["RS256"]
+        self._jwks_client = None
+
+    async def authenticate(self, request: AuthRequest) -> AuthResult:
+        auth_header = request.headers.get("Authorization", "")
+
+        if not auth_header.startswith("Bearer "):
+            return AuthResult.failure("Bearer token required")
+
+        token = auth_header[7:]
+
+        try:
+            import jwt
+            from jwt import PyJWKClient
+
+            # Get JWKS client (cached)
+            if self._jwks_client is None:
+                self._jwks_client = PyJWKClient(self.jwks_uri)
+
+            # Get signing key
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+
+            # Decode and validate
+            payload = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=self.algorithms,
+                audience=self.audience,
+                issuer=self.issuer,
+            )
+
+            user_id = payload.get("sub", payload.get("email", "unknown"))
+            scopes = set(payload.get("scope", "").split())
+
+            return AuthResult.success(
+                user_id=user_id,
+                scopes=scopes,
+                claims=payload,
+            )
+
+        except ImportError:
+            return AuthResult.failure(
+                "OAuth2 requires pyjwt: pip install pyjwt[crypto]"
+            )
+        except Exception as e:
+            return AuthResult.failure(f"Token validation failed: {str(e)}")
+
+    def get_scheme(self) -> Dict[str, Any]:
+        return {
+            "type": "oauth2",
+            "flows": {
+                "authorizationCode": {
+                    "authorizationUrl": f"{self.issuer}/authorize",
+                    "tokenUrl": f"{self.issuer}/oauth/token",
+                    "scopes": {},
+                }
+            },
+        }
+
+
+class CompositeAuth(AuthProvider):
+    """
+    Try multiple auth providers (first success wins).
+
+    Example:
+        auth = CompositeAuth([
+            APIKeyAuth(keys=["admin-key"]),
+            OAuth2Auth(issuer="..."),
+        ])
+    """
+
+    def __init__(self, providers: List[AuthProvider]):
+        self.providers = providers
+
+    async def authenticate(self, request: AuthRequest) -> AuthResult:
+        errors = []
+
+        for provider in self.providers:
+            result = await provider.authenticate(request)
+            if result.authenticated:
+                return result
+            if result.error:
+                errors.append(result.error)
+
+        return AuthResult.failure("; ".join(errors) or "Authentication failed")
+
+    def get_scheme(self) -> Dict[str, Any]:
+        # Return first provider's scheme
+        if self.providers:
+            return self.providers[0].get_scheme()
+        return {}
+
+
+# Auth middleware helper
+def require_auth(scopes: Optional[List[str]] = None):
+    """
+    Decorator to require authentication for a skill.
+
+    Example:
+        @agent.skill("admin_action")
+        @require_auth(scopes=["admin"])
+        async def admin_action(data: str, auth: AuthResult) -> str:
+            return f"Admin {auth.user_id} did something"
+    """
+    required_scopes = set(scopes or [])
+
+    def decorator(func: Callable) -> Callable:
+        async def wrapper(*args, auth: AuthResult = None, **kwargs):
+            if auth is None or not auth.authenticated:
+                return {"error": "Authentication required"}
+
+            if required_scopes and not required_scopes.issubset(auth.scopes):
+                return {
+                    "error": "Insufficient permissions",
+                    "required": list(required_scopes),
+                    "provided": list(auth.scopes),
+                }
+
+            return await func(*args, auth=auth, **kwargs)
+
+        wrapper.__wrapped__ = func
+        wrapper.__requires_auth__ = True
+        wrapper.__required_scopes__ = required_scopes
+        return wrapper
+
+    return decorator

a2a_lite/cli.py

@@ -0,0 +1,336 @@
+"""
+Command-line interface for A2A Lite.
+"""
+import asyncio
+import json
+from pathlib import Path
+from typing import Optional, List
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+app = typer.Typer(
+    name="a2a-lite",
+    help="A2A Lite - Simplified Agent-to-Agent Protocol SDK",
+    add_completion=False,
+)
+console = Console()
+
+
+@app.command()
+def init(
+    name: str = typer.Argument(..., help="Project name"),
+    path: Optional[Path] = typer.Option(None, help="Directory to create project in"),
+):
+    """
+    Initialize a new A2A Lite agent project.
+
+    Creates a new directory with a basic agent template.
+    """
+    project_path = path or Path(name)
+    project_path.mkdir(exist_ok=True)
+
+    # Create agent.py
+    agent_template = '''"""
+{name} - A2A Lite Agent
+
+Run with: python agent.py
+"""
+from a2a_lite import Agent
+
+agent = Agent(
+    name="{name}",
+    description="A simple A2A Lite agent",
+    version="1.0.0",
+)
+
+
+@agent.skill("hello", description="Say hello to someone")
+async def hello(name: str = "World") -> str:
+    """Greets the provided name."""
+    return f"Hello, {{name}}!"
+
+
+@agent.skill("echo", description="Echo back the input")
+async def echo(message: str) -> dict:
+    """Echoes the input message."""
+    return {{"received": message, "echoed": True}}
+
+
+if __name__ == "__main__":
+    agent.run(port=8787)
+'''
+
+    (project_path / "agent.py").write_text(
+        agent_template.format(name=name)
+    )
+
+    # Create pyproject.toml
+    safe_name = name.lower().replace(" ", "-").replace("_", "-")
+    pyproject = f'''[project]
+name = "{safe_name}"
+version = "0.1.0"
+description = "A2A Agent: {name}"
+requires-python = ">=3.10"
+dependencies = [
+    "a2a-lite>=0.1.0",
+]
+'''
+    (project_path / "pyproject.toml").write_text(pyproject)
+
+    # Create README
+    readme = f'''# {name}
+
+An A2A Lite agent.
+
+## Running
+
+```bash
+cd {project_path}
+uv run agent.py
+```
+
+## Testing
+
+```bash
+a2a-lite test http://localhost:8787 hello -p name=World
+```
+'''
+    (project_path / "README.md").write_text(readme)
+
+    console.print(Panel(
+        f"[green]✅ Created project: {name}[/]\n\n"
+        f"[dim]Files created:[/]\n"
+        f"  • {project_path}/agent.py\n"
+        f"  • {project_path}/pyproject.toml\n"
+        f"  • {project_path}/README.md\n\n"
+        f"[bold]Next steps:[/]\n"
+        f"  cd {project_path}\n"
+        f"  uv run agent.py",
+        title="🚀 A2A Lite Project Created",
+        border_style="green",
+    ))
+
+
+@app.command()
+def inspect(
+    url: str = typer.Argument(..., help="Agent URL (e.g., http://localhost:8787)"),
+):
+    """
+    Inspect an A2A agent's capabilities.
+
+    Fetches and displays the agent card.
+    """
+    import httpx
+
+    async def _inspect():
+        async with httpx.AsyncClient() as client:
+            # Fetch agent card
+            card_url = f"{url.rstrip('/')}/.well-known/agent.json"
+            response = await client.get(card_url, timeout=10.0)
+            response.raise_for_status()
+            card = response.json()
+
+            # Display
+            table = Table(title=f"📋 {card.get('name', 'Unknown')} v{card.get('version', '?')}")
+            table.add_column("Skill", style="cyan")
+            table.add_column("Description", style="dim")
+            table.add_column("Tags", style="green")
+
+            for skill in card.get('skills', []):
+                table.add_row(
+                    skill.get('name', skill.get('id', '?')),
+                    skill.get('description', '-'),
+                    ", ".join(skill.get('tags', [])) or "-",
+                )
+
+            console.print(f"\n[dim]URL: {card.get('url', url)}[/]")
+            console.print(f"[dim]Description: {card.get('description', '-')}[/]\n")
+            console.print(table)
+
+    try:
+        asyncio.run(_inspect())
+    except httpx.HTTPError as e:
+        console.print(f"[red]Error: Could not connect to {url}[/]")
+        console.print(f"[dim]{e}[/]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def test(
+    url: str = typer.Argument(..., help="Agent URL"),
+    skill: str = typer.Argument(..., help="Skill name to invoke"),
+    params: Optional[List[str]] = typer.Option(
+        None, "--param", "-p",
+        help="Parameters as key=value pairs"
+    ),
+):
+    """
+    Test an agent skill.
+
+    Example: a2a-lite test http://localhost:8787 hello -p name=World
+    """
+    import httpx
+    from uuid import uuid4
+
+    # Parse parameters
+    param_dict = {}
+    for p in (params or []):
+        if "=" in p:
+            key, value = p.split("=", 1)
+            # Try to parse as JSON for complex types
+            try:
+                param_dict[key] = json.loads(value)
+            except json.JSONDecodeError:
+                param_dict[key] = value
+
+    async def _test():
+        async with httpx.AsyncClient() as client:
+            # Build request
+            message = json.dumps({
+                "skill": skill,
+                "params": param_dict,
+            })
+
+            request_body = {
+                "jsonrpc": "2.0",
+                "method": "message/send",
+                "id": uuid4().hex,
+                "params": {
+                    "message": {
+                        "role": "user",
+                        "parts": [{"type": "text", "text": message}],
+                        "messageId": uuid4().hex,
+                    }
+                }
+            }
+
+            response = await client.post(
+                url,
+                json=request_body,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            result = response.json()
+
+            # Extract and display result
+            console.print("\n[bold green]Response:[/]")
+            console.print_json(json.dumps(result, indent=2))
+
+    try:
+        asyncio.run(_test())
+    except httpx.HTTPError as e:
+        console.print(f"[red]Error: {e}[/]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def discover(
+    timeout: float = typer.Option(5.0, help="Discovery timeout in seconds"),
+):
+    """
+    Discover A2A agents on the local network.
+
+    Uses mDNS to find agents advertising themselves.
+    """
+    from .discovery import AgentDiscovery
+
+    async def _discover():
+        console.print("[dim]Scanning local network...[/]\n")
+
+        discovery = AgentDiscovery()
+        agents = await discovery.discover(timeout=timeout)
+
+        if not agents:
+            console.print("[yellow]No agents found.[/]")
+            console.print("[dim]Make sure agents are running with discovery enabled (enable_discovery=True).[/]")
+            return
+
+        table = Table(title=f"🔍 Found {len(agents)} Agent(s)")
+        table.add_column("Name", style="cyan")
+        table.add_column("URL", style="blue")
+        table.add_column("Properties", style="dim")
+
+        for agent in agents:
+            table.add_row(
+                agent.name,
+                agent.url,
+                json.dumps(agent.properties) if agent.properties else "-",
+            )
+
+        console.print(table)
+
+    asyncio.run(_discover())
+
+
+@app.command()
+def serve(
+    file: Path = typer.Argument(..., help="Python file containing the agent"),
+    port: int = typer.Option(8787, help="Port to run on"),
+    reload: bool = typer.Option(False, "--reload", "-r", help="Enable hot reload"),
+    discovery: bool = typer.Option(False, "--discovery", "-d", help="Enable mDNS discovery"),
+):
+    """
+    Run an agent from a Python file.
+
+    The file should define an 'agent' variable of type Agent.
+    """
+    import importlib.util
+    import sys
+
+    # Load the module
+    file = file.resolve()
+    spec = importlib.util.spec_from_file_location("agent_module", file)
+    if spec is None or spec.loader is None:
+        console.print(f"[red]Error: Could not load {file}[/]")
+        raise typer.Exit(1)
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["agent_module"] = module
+
+    # Change to the file's directory for relative imports
+    original_cwd = Path.cwd()
+    try:
+        import os
+        os.chdir(file.parent)
+        spec.loader.exec_module(module)
+    finally:
+        os.chdir(original_cwd)
+
+    # Find the agent
+    if not hasattr(module, 'agent'):
+        console.print("[red]Error: No 'agent' variable found in file[/]")
+        console.print("[dim]Make sure your file defines: agent = Agent(...)[/]")
+        raise typer.Exit(1)
+
+    agent = module.agent
+    agent.run(port=port, reload=reload, enable_discovery=discovery)
+
+
+@app.command()
+def version():
+    """Show A2A Lite version."""
+    from . import __version__
+    console.print(f"A2A Lite v{__version__}")
+
+
+@app.callback()
+def main():
+    """
+    A2A Lite - Simplified A2A Protocol SDK
+
+    Build A2A agents with minimal boilerplate.
+    """
+    pass
+
+
+if __name__ == "__main__":
+    app()

a2a_lite/decorators.py

@@ -0,0 +1,32 @@
+"""
+Decorator definitions and skill metadata.
+"""
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List
+
+
+@dataclass
+class SkillDefinition:
+    """Metadata for a registered skill."""
+    name: str
+    description: str
+    handler: Callable
+    input_schema: Dict[str, Any]
+    output_schema: Dict[str, Any]
+    tags: List[str] = field(default_factory=list)
+    is_async: bool = False
+    is_streaming: bool = False
+    needs_task_context: bool = False
+    needs_interaction: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "tags": self.tags,
+            "input_schema": self.input_schema,
+            "output_schema": self.output_schema,
+            "is_streaming": self.is_streaming,
+            "needs_interaction": self.needs_interaction,
+        }