hivemind-a2a-agent-plugin 0.1.0a2__py3-none-any.whl

hivemind_a2a_agent_plugin/__init__.py

@@ -0,0 +1,157 @@
+"""HiveMind A2A agent protocol plugin.
+
+Bridges HiveMind natural-language queries to external A2A (Agent-to-Agent)
+agents.  Any utterance arriving from hive satellites is forwarded to a
+configured A2A server via JSON-RPC 2.0 (``tasks/send`` / ``tasks/sendSubscribe``),
+and the response is streamed back through the HiveMind session.
+
+The plugin is registered under the ``hivemind.agent.protocol`` entry-point
+group so hivemind-core discovers it automatically.
+"""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Dict, Iterator, Optional
+
+from ovos_utils.log import LOG
+
+from hivemind_plugin_manager.protocols import AgentProtocol
+
+from hivemind_a2a_agent_plugin._client import A2AClient
+from hivemind_a2a_agent_plugin.version import __version__
+
+# Default configuration keys (all live under hivemind → a2a_agent in
+# the OVOS config tree, but can also be supplied as plain kwargs).
+_CFG_URL = "agent_url"
+_CFG_AUTH = "auth_header"
+_CFG_TIMEOUT = "timeout"
+_CFG_STREAMING = "streaming"
+
+_DEFAULT_TIMEOUT = 60.0
+
+
+@dataclasses.dataclass()
+class A2AAgentProtocol(AgentProtocol):
+    """HiveMind agent protocol that delegates NL queries to an A2A agent.
+
+    Configuration (passed via ``config`` dict or the OVOS ``Configuration``
+    key ``"hivemind" → "a2a_agent"``):
+
+    .. code-block:: yaml
+
+       hivemind:
+         a2a_agent:
+           agent_url: "http://localhost:9999"
+           auth_header: "Bearer secret"   # optional
+           timeout: 60                    # seconds, optional
+           streaming: false               # prefer SSE when true, optional
+
+    The plugin is stateless with respect to the HiveMind client transport —
+    it only owns the outbound HTTP connection to the A2A server and maps
+    HiveMind session IDs to A2A ``sessionId`` values so conversation context
+    is preserved across multi-turn exchanges.
+    """
+
+    config: Dict[str, Any] = dataclasses.field(default_factory=dict)
+
+    # Internal state — not part of the public interface.
+    _client: Optional[A2AClient] = dataclasses.field(
+        default=None, init=False, repr=False, compare=False
+    )
+
+    def __post_init__(self) -> None:
+        # Merge OVOS global config if available, but explicit kwargs win.
+        try:
+            from ovos_config import Configuration
+            cfg_root = Configuration()
+            ovos_a2a = cfg_root.get("hivemind", {}).get("a2a_agent", {})
+        except Exception:  # pragma: no cover
+            ovos_a2a = {}
+
+        merged: Dict[str, Any] = {**ovos_a2a, **self.config}
+
+        url: Optional[str] = merged.get(_CFG_URL)
+        if not url:
+            LOG.warning(
+                "A2AAgentProtocol: no agent_url configured — "
+                "natural_language_query will return error answers"
+            )
+        else:
+            auth = merged.get(_CFG_AUTH)
+            timeout = float(merged.get(_CFG_TIMEOUT, _DEFAULT_TIMEOUT))
+            streaming = bool(merged.get(_CFG_STREAMING, False))
+            self._client = A2AClient(
+                base_url=url,
+                auth_header=auth,
+                timeout=timeout,
+                streaming=streaming,
+            )
+            LOG.info(f"A2AAgentProtocol: connected to A2A agent at {url}")
+
+    # ------------------------------------------------------------------
+    # AgentProtocol implementation
+    # ------------------------------------------------------------------
+
+    def natural_language_query(
+        self,
+        utterance: str,
+        lang: str,
+        session_id: Optional[str] = None,
+    ) -> "Iterator[Optional[str]]":
+        """Forward *utterance* to the A2A agent and yield response chunks.
+
+        Args:
+            utterance: The user's text, as received from a hive satellite.
+            lang:      BCP-47 language tag (e.g. ``"en-us"``).  Forwarded
+                       as context metadata so A2A agents can apply
+                       language-specific processing.
+            session_id: HiveMind session identifier; mapped 1-to-1 to the
+                        A2A ``sessionId`` so multi-turn context is preserved.
+
+        Yields:
+            Non-empty text chunks from the agent response, terminated by
+            ``None`` (the AgentProtocol sentinel).  On any error a
+            human-readable error string is yielded before the sentinel so
+            callers always get at least one answer.
+        """
+        if self._client is None:
+            yield "A2A agent not configured — no agent_url set."
+            yield None
+            return
+
+        LOG.debug(
+            f"A2AAgentProtocol: query lang={lang!r} session={session_id!r} "
+            f"utterance={utterance!r}"
+        )
+
+        try:
+            if self._client.streaming:
+                yielded_any = False
+                for chunk in self._client.stream_task(
+                    message_text=utterance,
+                    session_id=session_id,
+                    lang=lang,
+                ):
+                    if chunk:
+                        yielded_any = True
+                        yield chunk
+                if not yielded_any:
+                    yield "The A2A agent returned an empty streaming response."
+            else:
+                text = self._client.send_task(
+                    message_text=utterance,
+                    session_id=session_id,
+                    lang=lang,
+                )
+                if text:
+                    yield text
+                else:
+                    yield "The A2A agent returned an empty response."
+        except Exception as exc:
+            LOG.error(f"A2AAgentProtocol: error querying A2A agent: {exc}", exc_info=True)
+            yield f"Error contacting A2A agent: {exc}"
+
+        yield None
+
+
+__all__ = ["A2AAgentProtocol", "__version__"]

hivemind_a2a_agent_plugin/_client.py

@@ -0,0 +1,230 @@
+"""Thin A2A JSON-RPC 2.0 client.
+
+Vendored subset of ovos-a2a-solver-plugin's A2AClient so the HiveMind
+plugin has zero extra dependencies beyond ``httpx``.  If ovos-a2a-solver-plugin
+is importable its richer implementation is preferred at import time via the
+``__init__`` module; this copy is the fallback.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, Generator, List, Optional
+from urllib.parse import urljoin
+
+import httpx
+
+from ovos_utils.log import LOG
+
+
+@dataclass
+class AgentSkill:
+    """A capability advertised in an agent card."""
+    id: str
+    name: str
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    examples: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "AgentSkill":
+        return cls(
+            id=d.get("id", ""),
+            name=d.get("name", ""),
+            description=d.get("description", ""),
+            tags=d.get("tags", []),
+            examples=d.get("examples", []),
+        )
+
+
+@dataclass
+class AgentCard:
+    """Parsed A2A agent card (``/.well-known/agent.json``)."""
+    name: str
+    description: str
+    url: str
+    version: str = "1.0"
+    skills: List[AgentSkill] = field(default_factory=list)
+    streaming: bool = False
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "AgentCard":
+        skills = [AgentSkill.from_dict(s) for s in d.get("skills", [])]
+        caps = d.get("capabilities", {})
+        return cls(
+            name=d.get("name", ""),
+            description=d.get("description", ""),
+            url=d.get("url", ""),
+            version=d.get("version", "1.0"),
+            skills=skills,
+            streaming=caps.get("streaming", False),
+            raw=d,
+        )
+
+
+class A2AClient:
+    """Minimal A2A JSON-RPC 2.0 client.
+
+    Handles:
+    - Agent-card discovery (``GET /.well-known/agent.json``)
+    - Task submission via ``tasks/send`` (blocking)
+    - Streaming via ``tasks/sendSubscribe`` (SSE)
+
+    Args:
+        base_url:    Root URL of the A2A server.
+        auth_header: Optional ``Authorization`` header value.
+        timeout:     HTTP timeout in seconds (default 60).
+        streaming:   Prefer SSE streaming when True.
+    """
+
+    AGENT_CARD_PATH = "/.well-known/agent.json"
+    JSONRPC_VERSION = "2.0"
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_header: Optional[str] = None,
+        timeout: float = 60.0,
+        streaming: bool = False,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.streaming = streaming
+        headers: Dict[str, str] = {"Content-Type": "application/json"}
+        if auth_header:
+            headers["Authorization"] = auth_header
+        self._http = httpx.Client(headers=headers, timeout=timeout)
+
+    def fetch_agent_card(self) -> AgentCard:
+        """Fetch and parse ``/.well-known/agent.json``."""
+        url = self.base_url + self.AGENT_CARD_PATH
+        LOG.debug(f"A2AClient: fetching agent card from {url}")
+        resp = self._http.get(url)
+        resp.raise_for_status()
+        card = AgentCard.from_dict(resp.json())
+        LOG.debug(f"A2AClient: discovered agent '{card.name}' at {card.url}")
+        return card
+
+    def send_task(
+        self,
+        message_text: str,
+        session_id: Optional[str] = None,
+        lang: Optional[str] = None,
+        history: Optional[List[Dict[str, str]]] = None,
+    ) -> str:
+        """Submit a task (blocking) and return the final text response."""
+        rpc_id = str(uuid.uuid4())
+        parts: List[Dict[str, Any]] = [{"type": "text", "text": message_text}]
+        msg: Dict[str, Any] = {"role": "user", "parts": parts}
+        if lang:
+            msg["metadata"] = {"lang": lang}
+        params: Dict[str, Any] = {"id": rpc_id, "message": msg}
+        if session_id:
+            params["sessionId"] = session_id
+        if history:
+            params["history"] = [
+                {"role": t["role"],
+                 "parts": [{"type": "text", "text": t["content"]}]}
+                for t in history
+            ]
+
+        payload = {
+            "jsonrpc": self.JSONRPC_VERSION,
+            "id": rpc_id,
+            "method": "tasks/send",
+            "params": params,
+        }
+        resp = self._http.post(self.base_url, content=json.dumps(payload))
+        resp.raise_for_status()
+        return self._extract_text(resp.json(), rpc_id)
+
+    def stream_task(
+        self,
+        message_text: str,
+        session_id: Optional[str] = None,
+        lang: Optional[str] = None,
+        history: Optional[List[Dict[str, str]]] = None,
+    ) -> Generator[str, None, None]:
+        """Submit a task and yield text chunks via SSE (``tasks/sendSubscribe``)."""
+        rpc_id = str(uuid.uuid4())
+        parts: List[Dict[str, Any]] = [{"type": "text", "text": message_text}]
+        msg: Dict[str, Any] = {"role": "user", "parts": parts}
+        if lang:
+            msg["metadata"] = {"lang": lang}
+        params: Dict[str, Any] = {"id": rpc_id, "message": msg}
+        if session_id:
+            params["sessionId"] = session_id
+        if history:
+            params["history"] = [
+                {"role": t["role"],
+                 "parts": [{"type": "text", "text": t["content"]}]}
+                for t in history
+            ]
+
+        payload = {
+            "jsonrpc": self.JSONRPC_VERSION,
+            "id": rpc_id,
+            "method": "tasks/sendSubscribe",
+            "params": params,
+        }
+
+        with self._http.stream(
+            "POST", self.base_url,
+            content=json.dumps(payload),
+            headers={"Accept": "text/event-stream"},
+        ) as resp:
+            resp.raise_for_status()
+            for line in resp.iter_lines():
+                line = line.strip()
+                if not line or not line.startswith("data:"):
+                    continue
+                data_str = line[len("data:"):].strip()
+                if data_str == "[DONE]":
+                    break
+                try:
+                    event = json.loads(data_str)
+                except json.JSONDecodeError:
+                    continue
+                chunk = self._extract_stream_chunk(event)
+                if chunk:
+                    yield chunk
+
+    @staticmethod
+    def _extract_text(body: Dict[str, Any], rpc_id: str) -> str:
+        if "error" in body:
+            err = body["error"]
+            raise RuntimeError(
+                f"A2A RPC error {err.get('code')}: {err.get('message')}"
+            )
+        result = body.get("result", {})
+        for artifact in result.get("artifacts", []):
+            for part in artifact.get("parts", []):
+                if part.get("type") == "text":
+                    return part["text"]
+        msg = result.get("message", {})
+        for part in msg.get("parts", []):
+            if part.get("type") == "text":
+                return part["text"]
+        LOG.warning(f"A2AClient: could not extract text from response: {body}")
+        return ""
+
+    @staticmethod
+    def _extract_stream_chunk(event: Dict[str, Any]) -> str:
+        result = event.get("result", {})
+        for key in ("delta", "artifact"):
+            artifact = result.get(key, {})
+            for part in artifact.get("parts", []):
+                if part.get("type") == "text":
+                    return part["text"]
+        return ""
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "A2AClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

hivemind_a2a_agent_plugin/version.py

@@ -0,0 +1,8 @@
+# START_VERSION_BLOCK
+VERSION_MAJOR = 0
+VERSION_MINOR = 1
+VERSION_BUILD = 0
+VERSION_ALPHA = 2
+# END_VERSION_BLOCK
+
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}" + (f"a{VERSION_ALPHA}" if VERSION_ALPHA else "")

hivemind_a2a_agent_plugin-0.1.0a2.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: hivemind-a2a-agent-plugin
+Version: 0.1.0a2
+Summary: A2A agent protocol plugin for HiveMind-core
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/TigreGotico/hivemind-a2a-agent-plugin
+Project-URL: Issues, https://github.com/TigreGotico/hivemind-a2a-agent-plugin/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ovos-utils<1.0.0,>=0.8.2
+Requires-Dist: hivemind-plugin-manager<1.0.0,>=0.5.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: fastapi; extra == "test"
+Requires-Dist: uvicorn; extra == "test"
+Requires-Dist: httpx; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: fastapi; extra == "dev"
+Requires-Dist: uvicorn; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file
+
+# hivemind-a2a-agent-plugin
+
+A [HiveMind](https://github.com/JarbasHiveMind/HiveMind-core) agent-protocol plugin
+that bridges the hive to external
+[A2A (Agent-to-Agent)](https://google.github.io/A2A/) agents.
+
+Natural-language queries arriving from hive satellites are forwarded to a configured
+A2A server via JSON-RPC 2.0 (`tasks/send` or `tasks/sendSubscribe`), and the
+response is streamed back to the originating satellite.
+
+---
+
+## What is A2A?
+
+[A2A](https://google.github.io/A2A/) is an open protocol for agent interoperability.
+An A2A server:
+
+1. Publishes an **agent card** at `GET /.well-known/agent.json` describing its
+   capabilities, skills, and the URL that accepts tasks.
+2. Accepts **task** requests as JSON-RPC 2.0 at its root URL — either a blocking
+   `tasks/send` or a streaming `tasks/sendSubscribe` (SSE).
+
+Any compliant A2A server (LangChain agents, Google ADK, CrewAI, custom FastAPI
+services, …) works as a backend for this plugin.
+
+---
+
+## Installation
+
+```bash
+pip install hivemind-a2a-agent-plugin
+```
+
+The plugin registers itself under the `hivemind.agent.protocol` entry-point group
+so HiveMind-core discovers it automatically when it is installed.
+
+---
+
+## Configuration
+
+Add the following to your OVOS / HiveMind config (typically
+`~/.config/hivemind/hivemind.conf`):
+
+```json
+{
+  "hivemind": {
+    "agent_protocol": "hivemind-a2a-agent-plugin",
+    "a2a_agent": {
+      "agent_url": "http://localhost:9999",
+      "auth_header": "Bearer secret",
+      "timeout": 60,
+      "streaming": false
+    }
+  }
+}
+```
+
+| Key          | Default | Description                                          |
+|--------------|---------|------------------------------------------------------|
+| `agent_url`  | —       | **Required.** Root URL of the A2A server.            |
+| `auth_header`| —       | Optional `Authorization` header (e.g. `Bearer …`).  |
+| `timeout`    | `60`    | HTTP timeout in seconds.                             |
+| `streaming`  | `false` | Prefer `tasks/sendSubscribe` (SSE) when `true`.      |
+
+---
+
+## Hive wiring example
+
+```
+HiveMind master
+  └── hivemind-a2a-agent-plugin  ←  loaded as agent_protocol
+        └── A2A server  (http://localhost:9999)
+              └── your LLM / agent / tool backend
+
+Satellite (voice client, phone, …)
+  → "what's the capital of France?"
+  → HiveMind master receives utterance
+  → plugin forwards to A2A server via tasks/send
+  → A2A server responds: "Paris is the capital of France."
+  → HiveMind master streams answer back to satellite
+```
+
+**Start a minimal FastAPI A2A server and the HiveMind master:**
+
+```bash
+# 1. run the example mock A2A server (also used by e2e tests)
+uvicorn tests.e2e.mock_a2a_server:app --port 9999
+
+# 2. configure hivemind-core to use this plugin (see above)
+# 3. start hivemind-core
+hivemind-core listen
+```
+
+---
+
+## Session / context mapping
+
+The plugin maps the HiveMind `session_id` directly to the A2A `sessionId` parameter
+so multi-turn conversations are kept in context on the A2A server side.  No extra
+state is stored in the plugin; the A2A server owns conversation history.
+
+---
+
+## Error handling
+
+The plugin never silences errors.  If the A2A server is unreachable, returns an
+empty response, or returns a JSON-RPC error object, a human-readable error string
+is yielded to the satellite so the user always receives a reply.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/TigreGotico/hivemind-a2a-agent-plugin
+cd hivemind-a2a-agent-plugin
+pip install -e ".[dev]"
+pytest tests/          # unit tests (no server needed)
+pytest tests/e2e/      # e2e tests (spins up a FastAPI mock server in-process)
+```
+
+## Credits
+
+Funded by [NGI0 Commons Fund](https://nlnet.nl/project/OpenVoiceOS) / [NLnet](https://nlnet.nl)
+under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429),
+through the European Commission's [Next Generation Internet](https://ngi.eu) programme.

hivemind_a2a_agent_plugin-0.1.0a2.dist-info/RECORD

@@ -0,0 +1,9 @@
+hivemind_a2a_agent_plugin/__init__.py,sha256=ua_J2a-6DOWpJFOje5-FkVF2tOCSJexQ57U0YkZ-MUE,5795
+hivemind_a2a_agent_plugin/_client.py,sha256=f62WCe1uPXgON8sgVO__difY54cLUFOBgpeipQkRpto,7698
+hivemind_a2a_agent_plugin/version.py,sha256=7c51Az-oGaEN_y0AvP9KO0mPZdqtsC6jApogoAQ2ya8,229
+hivemind_a2a_agent_plugin-0.1.0a2.dist-info/licenses/LICENSE,sha256=CCh66Pv-YGCzi6ysUq5rGBsPZ2Vew0zEq-d-xDJZd-M,737
+hivemind_a2a_agent_plugin-0.1.0a2.dist-info/METADATA,sha256=mTUpAXl5whu0AHREVH5yUpiOTIgBZ-RmigiCodzGf_g,4979
+hivemind_a2a_agent_plugin-0.1.0a2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hivemind_a2a_agent_plugin-0.1.0a2.dist-info/entry_points.txt,sha256=DFhcZN-HxWF2l9UaaGVHlZjkwbrSqIT7JqLSSIAzBnY,97
+hivemind_a2a_agent_plugin-0.1.0a2.dist-info/top_level.txt,sha256=P0_ME7kyTGv9vWK3whGMgtuJtXQHtzM2Nmtm1mJonY4,26
+hivemind_a2a_agent_plugin-0.1.0a2.dist-info/RECORD,,

hivemind_a2a_agent_plugin-0.1.0a2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hivemind_a2a_agent_plugin-0.1.0a2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hivemind.agent.protocol]
+hivemind-a2a-agent-plugin = hivemind_a2a_agent_plugin:A2AAgentProtocol

hivemind_a2a_agent_plugin-0.1.0a2.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2024 JarbasAi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hivemind_a2a_agent_plugin-0.1.0a2.dist-info/top_level.txt

@@ -0,0 +1 @@
+hivemind_a2a_agent_plugin