hivemind-ovos-agent-plugin 0.1.0

OVOS agent protocol plugin for HiveMind-core

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.