HiveMind OVOS Agent Plugin

OVOS agent protocol plugin for HiveMind-core.

Bridges HiveMind client messages to an OpenVoiceOS message bus. HiveMind clients connect to a hivemind-core listener, and this plugin forwards their Mycroft Message payloads to a local OVOS bus (and routes OVOS responses back to the originating client).

Installation

pip install hivemind-ovos-agent-plugin

Or from source:

git clone https://github.com/JarbasHiveMind/hivemind-ovos-agent-plugin
cd hivemind-ovos-agent-plugin
pip install -e .

Usage

The plugin registers itself as a HiveMind agent protocol via the hivemind.agent.protocol entry point group, with name hivemind-ovos-agent-plugin.

In your hivemind-core configuration:

{
  "agent_protocol": {
    "hivemind-ovos-agent-plugin": {
      "host": "127.0.0.1",
      "port": 8181
    }
  }
}

hivemind-core will discover the plugin via its entry point and instantiate the OVOSAgentProtocol class with the supplied config. The plugin connects to the OVOS message bus at the given host/port (defaulting to 127.0.0.1:8181).

Direct programmatic use

from hivemind_ovos_agent_plugin import OVOSAgentProtocol

agent = OVOSAgentProtocol(config={"host": "127.0.0.1", "port": 8181})
# pass `agent` to your HiveMindListenerProtocol

How it works

The plugin owns two callbacks on the OVOS bus:

hive.send.downstream — emitted by OVOS components that want to push a HiveMessage to a connected HiveMind client. The plugin wraps the payload in a HiveMessage and dispatches it to the right peer, or fans it out for PROPAGATE/BROADCAST types.
message (catch-all) — every internal OVOS bus message is inspected. If its context["destination"] lists a connected HiveMind peer, the plugin forwards it back to that peer wrapped as a HiveMessageType.BUS message. This is where client isolation is enforced: a client never sees responses meant for another client.

Upstream traffic (client → OVOS bus) is handled by hivemind-core itself; this plugin only handles the downstream half.

Documentation

Full developer documentation lives in docs/:

docs/architecture.md — how the plugin fits between HiveMind and OVOS.
docs/configuration.md — every config knob.
docs/message_flow.md — end-to-end message lifecycle.
docs/development.md — running tests, releasing.

License

Apache 2.0. See LICENSE.md.

Metadata

Release files for hivemind-ovos-agent-plugin 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hivemind-ovos-agent-plugin 0.1.0
File	Size	Uploaded
hivemind_ovos_agent_plugin-0.1.0.tar.gz	10.4 kB	May 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hivemind-ovos-agent-plugin 0.1.0
File	Interpreter	ABI	Platform	Reset
hivemind_ovos_agent_plugin-0.1.0-py3-none-any.whl 9.0 kB May 18, 2026	Python 3	none	any	Details

Total release size: 19.3 kB

Release files / hivemind_ovos_agent_plugin-0.1.0.tar.gz

Download URL	hivemind_ovos_agent_plugin-0.1.0.tar.gz
Size	10.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`377fc1cf8010a1608deb1a1067cdcf74efbe265db5ce43857489c55ad10889d9`
BLAKE2b-256 checksum How to use checksums	`6776d474ebc9ae1ae80da28e932821e2ee76c2f4e16fd5bf2da4b91033e2f039`
Upload date	May 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / hivemind_ovos_agent_plugin-0.1.0-py3-none-any.whl

Download URL	hivemind_ovos_agent_plugin-0.1.0-py3-none-any.whl
Size	9.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c563a35a206e4d5232ca37ab4e32065fe9513715d2bac39f2c327ac83b32354d`
BLAKE2b-256 checksum How to use checksums	`495e1fe06cb6cbef5065b1776f45a68098dc51357e2533c426e316124a75c7c5`
Upload date	May 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`