hivemind-a2a-agent-plugin 0.1.0a2__tar.gz

hivemind_a2a_agent_plugin-0.1.0a2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,126 @@
+# 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/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-0.1.0a2/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-0.1.0a2/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/hivemind_a2a_agent_plugin.egg-info/PKG-INFO

@@ -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/hivemind_a2a_agent_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+hivemind_a2a_agent_plugin/__init__.py
+hivemind_a2a_agent_plugin/_client.py
+hivemind_a2a_agent_plugin/version.py
+hivemind_a2a_agent_plugin.egg-info/PKG-INFO
+hivemind_a2a_agent_plugin.egg-info/SOURCES.txt
+hivemind_a2a_agent_plugin.egg-info/dependency_links.txt
+hivemind_a2a_agent_plugin.egg-info/entry_points.txt
+hivemind_a2a_agent_plugin.egg-info/requires.txt
+hivemind_a2a_agent_plugin.egg-info/top_level.txt
+tests/test_client.py
+tests/test_protocol.py

hivemind_a2a_agent_plugin-0.1.0a2/hivemind_a2a_agent_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hivemind_a2a_agent_plugin-0.1.0a2/hivemind_a2a_agent_plugin.egg-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/hivemind_a2a_agent_plugin.egg-info/requires.txt

@@ -0,0 +1,17 @@
+ovos-utils<1.0.0,>=0.8.2
+hivemind-plugin-manager<1.0.0,>=0.5.0
+httpx>=0.25.0
+
+[dev]
+pytest
+pytest-cov
+fastapi
+uvicorn
+httpx
+
+[test]
+pytest
+pytest-cov
+fastapi
+uvicorn
+httpx

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

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

hivemind_a2a_agent_plugin-0.1.0a2/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hivemind-a2a-agent-plugin"
+dynamic = ["version"]
+description = "A2A agent protocol plugin for HiveMind-core"
+license = { text = "Apache-2.0" }
+readme = "README.md"
+authors = [
+    { name = "JarbasAi", email = "jarbasai@mailfence.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "ovos-utils>=0.8.2,<1.0.0",
+    "hivemind-plugin-manager>=0.5.0,<1.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+    "fastapi",
+    "uvicorn",
+    "httpx",
+]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "fastapi",
+    "uvicorn",
+    "httpx",
+]
+
+[project.urls]
+Homepage = "https://github.com/TigreGotico/hivemind-a2a-agent-plugin"
+Issues = "https://github.com/TigreGotico/hivemind-a2a-agent-plugin/issues"
+
+[project.entry-points."hivemind.agent.protocol"]
+"hivemind-a2a-agent-plugin" = "hivemind_a2a_agent_plugin:A2AAgentProtocol"
+
+[tool.setuptools.dynamic]
+version = { attr = "hivemind_a2a_agent_plugin.version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hivemind_a2a_agent_plugin*"]

hivemind_a2a_agent_plugin-0.1.0a2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hivemind_a2a_agent_plugin-0.1.0a2/tests/test_client.py

@@ -0,0 +1,241 @@
+"""Unit tests for the A2A client — mock HTTP, no real server."""
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from hivemind_a2a_agent_plugin._client import A2AClient, AgentCard, AgentSkill
+
+
+# ---------------------------------------------------------------------------
+# Helpers — build minimal JSON-RPC response bodies
+# ---------------------------------------------------------------------------
+
+def _send_response(text: str, rpc_id: str = "test-id") -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": rpc_id,
+        "result": {
+            "artifacts": [
+                {"parts": [{"type": "text", "text": text}]}
+            ]
+        },
+    }
+
+
+def _error_response(code: int, message: str, rpc_id: str = "test-id") -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": rpc_id,
+        "error": {"code": code, "message": message},
+    }
+
+
+AGENT_CARD_DICT = {
+    "name": "TestAgent",
+    "description": "A test agent",
+    "url": "http://localhost:9999",
+    "version": "1.0",
+    "capabilities": {"streaming": True},
+    "skills": [
+        {
+            "id": "qa",
+            "name": "Q&A",
+            "description": "Answers questions",
+            "tags": ["qa"],
+            "examples": ["What is 2+2?"],
+        }
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# AgentCard / AgentSkill parsing
+# ---------------------------------------------------------------------------
+
+class TestAgentCard:
+    def test_from_dict_basic(self):
+        card = AgentCard.from_dict(AGENT_CARD_DICT)
+        assert card.name == "TestAgent"
+        assert card.streaming is True
+        assert len(card.skills) == 1
+        assert card.skills[0].id == "qa"
+
+    def test_from_dict_no_capabilities(self):
+        d = {**AGENT_CARD_DICT, "capabilities": {}}
+        card = AgentCard.from_dict(d)
+        assert card.streaming is False
+
+    def test_from_dict_no_skills(self):
+        d = {**AGENT_CARD_DICT, "skills": []}
+        card = AgentCard.from_dict(d)
+        assert card.skills == []
+
+    def test_skill_from_dict(self):
+        skill = AgentSkill.from_dict(AGENT_CARD_DICT["skills"][0])
+        assert skill.id == "qa"
+        assert "qa" in skill.tags
+        assert skill.examples == ["What is 2+2?"]
+
+
+# ---------------------------------------------------------------------------
+# A2AClient.fetch_agent_card
+# ---------------------------------------------------------------------------
+
+class TestFetchAgentCard:
+    def test_fetch_success(self, httpx_mock):
+        httpx_mock.add_response(
+            method="GET",
+            url="http://localhost:9999/.well-known/agent.json",
+            json=AGENT_CARD_DICT,
+        )
+        client = A2AClient("http://localhost:9999")
+        card = client.fetch_agent_card()
+        assert card.name == "TestAgent"
+        assert card.streaming is True
+
+    def test_fetch_http_error(self, httpx_mock):
+        httpx_mock.add_response(
+            method="GET",
+            url="http://localhost:9999/.well-known/agent.json",
+            status_code=404,
+        )
+        client = A2AClient("http://localhost:9999")
+        with pytest.raises(httpx.HTTPStatusError):
+            client.fetch_agent_card()
+
+
+# ---------------------------------------------------------------------------
+# A2AClient.send_task
+# ---------------------------------------------------------------------------
+
+class TestSendTask:
+    def test_send_basic(self, httpx_mock):
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            json=_send_response("Paris is the capital of France."),
+        )
+        client = A2AClient("http://localhost:9999")
+        result = client.send_task("What is the capital of France?", lang="en-us")
+        assert result == "Paris is the capital of France."
+
+    def test_send_with_session(self, httpx_mock):
+        def _capture(request: httpx.Request):
+            body = json.loads(request.content)
+            assert body["params"]["sessionId"] == "sess-123"
+            return httpx.Response(200, json=_send_response("ok"))
+
+        httpx_mock.add_callback(_capture, method="POST", url="http://localhost:9999")
+        client = A2AClient("http://localhost:9999")
+        result = client.send_task("hello", session_id="sess-123")
+        assert result == "ok"
+
+    def test_send_rpc_error(self, httpx_mock):
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            json=_error_response(-32603, "internal error"),
+        )
+        client = A2AClient("http://localhost:9999")
+        with pytest.raises(RuntimeError, match="A2A RPC error"):
+            client.send_task("hello")
+
+    def test_send_empty_response(self, httpx_mock):
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            json={"jsonrpc": "2.0", "id": "x", "result": {}},
+        )
+        client = A2AClient("http://localhost:9999")
+        result = client.send_task("hello")
+        assert result == ""
+
+    def test_send_message_fallback(self, httpx_mock):
+        """result.message fallback path."""
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            json={
+                "jsonrpc": "2.0",
+                "id": "x",
+                "result": {
+                    "message": {"parts": [{"type": "text", "text": "fallback answer"}]}
+                },
+            },
+        )
+        client = A2AClient("http://localhost:9999")
+        result = client.send_task("hello")
+        assert result == "fallback answer"
+
+    def test_send_auth_header_forwarded(self, httpx_mock):
+        def _capture(request: httpx.Request):
+            assert request.headers["authorization"] == "Bearer secret"
+            return httpx.Response(200, json=_send_response("authed"))
+
+        httpx_mock.add_callback(_capture, method="POST", url="http://localhost:9999")
+        client = A2AClient("http://localhost:9999", auth_header="Bearer secret")
+        result = client.send_task("hello")
+        assert result == "authed"
+
+
+# ---------------------------------------------------------------------------
+# A2AClient.stream_task (SSE)
+# ---------------------------------------------------------------------------
+
+def _sse_body(*chunks: str, done: bool = True) -> bytes:
+    lines = []
+    for chunk in chunks:
+        event = {
+            "result": {
+                "delta": {"parts": [{"type": "text", "text": chunk}]}
+            }
+        }
+        lines.append(f"data: {json.dumps(event)}\n\n")
+    if done:
+        lines.append("data: [DONE]\n\n")
+    return "".join(lines).encode()
+
+
+class TestStreamTask:
+    def test_stream_basic(self, httpx_mock):
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            content=_sse_body("Hello", " world"),
+            headers={"Content-Type": "text/event-stream"},
+        )
+        client = A2AClient("http://localhost:9999", streaming=True)
+        chunks = list(client.stream_task("hi"))
+        assert chunks == ["Hello", " world"]
+
+    def test_stream_skips_empty_lines(self, httpx_mock):
+        body = b"data: \n\ndata: [DONE]\n\n"
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            content=body,
+            headers={"Content-Type": "text/event-stream"},
+        )
+        client = A2AClient("http://localhost:9999", streaming=True)
+        chunks = list(client.stream_task("hi"))
+        assert chunks == []
+
+    def test_stream_artifact_key(self, httpx_mock):
+        event = {
+            "result": {
+                "artifact": {"parts": [{"type": "text", "text": "artifact chunk"}]}
+            }
+        }
+        body = f"data: {json.dumps(event)}\n\ndata: [DONE]\n\n".encode()
+        httpx_mock.add_response(
+            method="POST",
+            url="http://localhost:9999",
+            content=body,
+            headers={"Content-Type": "text/event-stream"},
+        )
+        client = A2AClient("http://localhost:9999", streaming=True)
+        chunks = list(client.stream_task("hi"))
+        assert chunks == ["artifact chunk"]

hivemind_a2a_agent_plugin-0.1.0a2/tests/test_protocol.py

@@ -0,0 +1,134 @@
+"""Unit tests for A2AAgentProtocol — mock A2AClient, no HTTP."""
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hivemind_a2a_agent_plugin import A2AAgentProtocol
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _protocol(agent_url: str = "http://a2a.test", streaming: bool = False,
+              **extra) -> A2AAgentProtocol:
+    cfg = {"agent_url": agent_url, "streaming": streaming, **extra}
+    with patch("hivemind_a2a_agent_plugin._client.A2AClient") as MockClient:
+        instance = MockClient.return_value
+        instance.streaming = streaming
+        proto = A2AAgentProtocol(config=cfg)
+        proto._client = instance
+    return proto
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestProtocolInit:
+    def test_no_url_yields_error(self):
+        proto = A2AAgentProtocol(config={})
+        chunks = list(proto.natural_language_query("hello", "en-us"))
+        assert chunks[-1] is None
+        assert "not configured" in chunks[0].lower()
+
+    def test_url_creates_client(self):
+        with patch("hivemind_a2a_agent_plugin.A2AClient") as MockClient:
+            proto = A2AAgentProtocol(config={"agent_url": "http://a2a.test"})
+        MockClient.assert_called_once()
+        call_kwargs = MockClient.call_args
+        assert call_kwargs.kwargs["base_url"] == "http://a2a.test"
+
+
+class TestNaturalLanguageQueryBlocking:
+    def test_basic_answer(self):
+        proto = _protocol()
+        proto._client.streaming = False
+        proto._client.send_task.return_value = "Paris."
+
+        chunks = list(proto.natural_language_query("capital of France?", "en-us"))
+        assert chunks == ["Paris.", None]
+
+    def test_empty_response_fallback(self):
+        proto = _protocol()
+        proto._client.streaming = False
+        proto._client.send_task.return_value = ""
+
+        chunks = list(proto.natural_language_query("hello", "en-us"))
+        assert chunks[-1] is None
+        assert "empty" in chunks[0].lower()
+
+    def test_session_id_forwarded(self):
+        proto = _protocol()
+        proto._client.streaming = False
+        proto._client.send_task.return_value = "ok"
+
+        list(proto.natural_language_query("hi", "en-us", session_id="sid-42"))
+        call_kwargs = proto._client.send_task.call_args
+        assert call_kwargs.kwargs.get("session_id") == "sid-42"
+
+    def test_lang_forwarded(self):
+        proto = _protocol()
+        proto._client.streaming = False
+        proto._client.send_task.return_value = "ok"
+
+        list(proto.natural_language_query("hi", "pt-pt", session_id="x"))
+        call_kwargs = proto._client.send_task.call_args
+        assert call_kwargs.kwargs.get("lang") == "pt-pt"
+
+    def test_exception_yields_error_not_silence(self):
+        proto = _protocol()
+        proto._client.streaming = False
+        proto._client.send_task.side_effect = RuntimeError("connection refused")
+
+        chunks = list(proto.natural_language_query("hello", "en-us"))
+        assert chunks[-1] is None
+        assert len(chunks) == 2
+        assert "connection refused" in chunks[0].lower() or "error" in chunks[0].lower()
+
+    def test_rpc_error_yields_human_readable(self):
+        proto = _protocol()
+        proto._client.streaming = False
+        proto._client.send_task.side_effect = RuntimeError("A2A RPC error -32603: internal")
+
+        chunks = list(proto.natural_language_query("hello", "en-us"))
+        assert any("error" in c.lower() for c in chunks if c is not None)
+
+
+class TestNaturalLanguageQueryStreaming:
+    def _stream_proto(self, chunks_to_yield: List[str]) -> A2AAgentProtocol:
+        proto = _protocol(streaming=True)
+        proto._client.streaming = True
+        proto._client.stream_task.return_value = iter(chunks_to_yield)
+        return proto
+
+    def test_streaming_yields_chunks(self):
+        proto = self._stream_proto(["Hello", " world"])
+        chunks = list(proto.natural_language_query("hi", "en-us"))
+        assert chunks == ["Hello", " world", None]
+
+    def test_streaming_empty_fallback(self):
+        proto = self._stream_proto([])
+        chunks = list(proto.natural_language_query("hi", "en-us"))
+        assert chunks[-1] is None
+        assert "empty" in chunks[0].lower()
+
+    def test_streaming_exception_yields_error(self):
+        proto = _protocol(streaming=True)
+        proto._client.streaming = True
+        proto._client.stream_task.side_effect = Exception("SSE broken")
+        chunks = list(proto.natural_language_query("hi", "en-us"))
+        assert chunks[-1] is None
+        assert any("error" in c.lower() or "sse" in c.lower()
+                   for c in chunks if c)
+
+    def test_sentinel_always_last(self):
+        """None sentinel must be the last yielded value."""
+        proto = self._stream_proto(["a", "b", "c"])
+        chunks = list(proto.natural_language_query("q", "en-us"))
+        assert chunks[-1] is None
+        assert chunks[:-1] == ["a", "b", "c"]