feat(hawk-sdk-python): adopt agentscope patterns — toolkit, plan, tracing, eval, discovery, memory

Add 6 new modules inspired by agentscope-ai/agentscope:
- toolkit: tool groups, middleware chain, async background execution
- plan: plan-as-tools with contextual hints for autonomous steering
- tracing: OTel decorator-based tracing (zero-cost when disabled)
- evaluate: agent benchmarking framework with N-run aggregation
- discovery: A2A agent discovery (file, HTTP well-known, composite)
- memory_tools: voluntary record/retrieve/forget as agent tools

Author: Patel230

src/hawk/__init__.py

@@ -13,9 +13,19 @@
     RateLimitError,
     ServiceUnavailableError,
 )
+from .plan import Plan, PlanNotebook, SubTask, SubTaskState
 from .retry import DEFAULT_RETRY_CONFIG, RetryConfig
 from .streaming import AsyncStreamReader, StreamReader
 from .tools import Tool, chat_with_tools, chat_with_tools_async, tool
+from .toolkit import BackgroundTask, ToolGroup, Toolkit
+from .tracing import (
+    configure_tracing,
+    detect_provider,
+    is_tracing_enabled,
+    trace,
+    trace_chat,
+    trace_tool,
+)
 from .types import (
     ChatRequest,
     ChatResponse,
@@ -31,6 +41,21 @@
     ToolCall,
     Usage,
 )
+from .discovery import (
+    AgentCard,
+    AgentResolver,
+    CompositeResolver,
+    FileResolver,
+    WellKnownResolver,
+)
+from .evaluate import (
+    BenchmarkResults,
+    EvalResult,
+    EvalTask,
+    run_benchmark,
+    run_benchmark_async,
+)
+from .memory_tools import MemoryTools
 from .workflow import AsyncWorkflow, Workflow
 
 __all__ = [
@@ -51,6 +76,15 @@
     "tool",
     "chat_with_tools",
     "chat_with_tools_async",
+    # Plan
+    "PlanNotebook",
+    "Plan",
+    "SubTask",
+    "SubTaskState",
+    # Toolkit
+    "Toolkit",
+    "ToolGroup",
+    "BackgroundTask",
     # Workflow
     "Workflow",
     "AsyncWorkflow",
@@ -71,6 +105,13 @@
     "StreamEventType",
     "ToolCall",
     "Usage",
+    # Tracing
+    "configure_tracing",
+    "detect_provider",
+    "is_tracing_enabled",
+    "trace",
+    "trace_chat",
+    "trace_tool",
     # Errors
     "HawkAPIError",
     "BadRequestError",
@@ -80,4 +121,18 @@
     "RateLimitError",
     "InternalServerError",
     "ServiceUnavailableError",
+    # Evaluate
+    "EvalTask",
+    "EvalResult",
+    "BenchmarkResults",
+    "run_benchmark",
+    "run_benchmark_async",
+    # Discovery
+    "AgentCard",
+    "AgentResolver",
+    "FileResolver",
+    "WellKnownResolver",
+    "CompositeResolver",
+    # Memory
+    "MemoryTools",
 ]

src/hawk/discovery.py

@@ -0,0 +1,194 @@
+"""Agent-to-Agent discovery protocol for Hawk.
+
+Enables agents to discover and communicate with other agents via
+multiple resolution strategies (HTTP well-known, file-based, registry).
+
+Usage:
+    from hawk.discovery import AgentCard, WellKnownResolver, FileResolver
+
+    resolver = WellKnownResolver()
+    card = await resolver.resolve("assistant-agent")
+    # card.endpoint -> "http://localhost:8080/v1/chat"
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Optional, Protocol
+
+
+@dataclass
+class AgentCard:
+    """Describes a discoverable agent's capabilities and endpoint."""
+    name: str
+    endpoint: str
+    description: str = ""
+    capabilities: list[str] = field(default_factory=list)
+    version: str = "1.0"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "endpoint": self.endpoint,
+            "description": self.description,
+            "capabilities": self.capabilities,
+            "version": self.version,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AgentCard":
+        return cls(
+            name=data["name"],
+            endpoint=data["endpoint"],
+            description=data.get("description", ""),
+            capabilities=data.get("capabilities", []),
+            version=data.get("version", "1.0"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+class AgentResolver(Protocol):
+    """Protocol for agent discovery resolvers."""
+
+    async def resolve(self, agent_name: str) -> Optional[AgentCard]:
+        """Resolve an agent name to its card."""
+        ...
+
+    async def list_agents(self) -> list[AgentCard]:
+        """List all known agents."""
+        ...
+
+    async def register(self, card: AgentCard) -> None:
+        """Register an agent card."""
+        ...
+
+
+class FileResolver:
+    """File-based agent discovery for local development.
+
+    Reads agent cards from a JSON file.
+
+    Usage:
+        resolver = FileResolver("/path/to/agents.json")
+        card = await resolver.resolve("my-agent")
+    """
+
+    def __init__(self, path: str = ".hawk/agents.json") -> None:
+        self._path = path
+        self._cards: dict[str, AgentCard] = {}
+        self._load()
+
+    def _load(self) -> None:
+        if os.path.exists(self._path):
+            with open(self._path) as f:
+                data = json.load(f)
+            for entry in data.get("agents", []):
+                card = AgentCard.from_dict(entry)
+                self._cards[card.name] = card
+
+    def _save(self) -> None:
+        os.makedirs(os.path.dirname(self._path) or ".", exist_ok=True)
+        data = {"agents": [c.to_dict() for c in self._cards.values()]}
+        with open(self._path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    async def resolve(self, agent_name: str) -> Optional[AgentCard]:
+        return self._cards.get(agent_name)
+
+    async def list_agents(self) -> list[AgentCard]:
+        return list(self._cards.values())
+
+    async def register(self, card: AgentCard) -> None:
+        self._cards[card.name] = card
+        self._save()
+
+
+class WellKnownResolver:
+    """HTTP-based agent discovery via well-known URLs.
+
+    Discovers agents by fetching {base_url}/.well-known/agent.json
+
+    Usage:
+        resolver = WellKnownResolver(["http://localhost:8080", "http://agent2:8080"])
+        card = await resolver.resolve("assistant")
+    """
+
+    def __init__(self, base_urls: Optional[list[str]] = None) -> None:
+        self._base_urls = base_urls or []
+        self._cache: dict[str, AgentCard] = {}
+
+    async def resolve(self, agent_name: str) -> Optional[AgentCard]:
+        if agent_name in self._cache:
+            return self._cache[agent_name]
+
+        for url in self._base_urls:
+            card = await self._fetch_card(url)
+            if card and card.name == agent_name:
+                self._cache[agent_name] = card
+                return card
+        return None
+
+    async def list_agents(self) -> list[AgentCard]:
+        cards = []
+        for url in self._base_urls:
+            card = await self._fetch_card(url)
+            if card:
+                cards.append(card)
+        return cards
+
+    async def register(self, card: AgentCard) -> None:
+        self._cache[card.name] = card
+        if card.endpoint not in self._base_urls:
+            self._base_urls.append(card.endpoint)
+
+    async def _fetch_card(self, base_url: str) -> Optional[AgentCard]:
+        try:
+            import httpx
+            url = f"{base_url.rstrip('/')}/.well-known/agent.json"
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                resp = await client.get(url)
+                if resp.status_code == 200:
+                    return AgentCard.from_dict(resp.json())
+        except Exception:
+            pass
+        return None
+
+
+class CompositeResolver:
+    """Chains multiple resolvers, returning the first match.
+
+    Usage:
+        resolver = CompositeResolver([
+            FileResolver(".hawk/agents.json"),
+            WellKnownResolver(["http://localhost:8080"]),
+        ])
+        card = await resolver.resolve("my-agent")
+    """
+
+    def __init__(self, resolvers: list[Any]) -> None:
+        self._resolvers = resolvers
+
+    async def resolve(self, agent_name: str) -> Optional[AgentCard]:
+        for resolver in self._resolvers:
+            card = await resolver.resolve(agent_name)
+            if card:
+                return card
+        return None
+
+    async def list_agents(self) -> list[AgentCard]:
+        seen = set()
+        cards = []
+        for resolver in self._resolvers:
+            for card in await resolver.list_agents():
+                if card.name not in seen:
+                    seen.add(card.name)
+                    cards.append(card)
+        return cards
+
+    async def register(self, card: AgentCard) -> None:
+        if self._resolvers:
+            await self._resolvers[0].register(card)