Metadata-Version: 2.4
Name: hivemind-ovos-agent-plugin
Version: 0.1.0
Summary: OVOS agent protocol plugin for HiveMind-core
Author-email: jarbasAi <jarbasai@mailfence.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/JarbasHiveMind/hivemind-ovos-agent-plugin
Project-URL: Issues, https://github.com/JarbasHiveMind/hivemind-ovos-agent-plugin/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: ovos-bus-client<2.0.0,>=1.3.1
Requires-Dist: ovos-config<3.0.0,>=0.0.12
Requires-Dist: ovos-utils<1.0.0,>=0.8.2
Requires-Dist: hivemind-bus-client<1.0.0,>=0.7.0a2
Requires-Dist: hivemind-plugin-manager<1.0.0,>=0.3.0
Requires-Dist: pyee<13.0.0,>=8.1.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# HiveMind OVOS Agent Plugin

OVOS agent protocol plugin for [HiveMind-core](https://github.com/JarbasHiveMind/HiveMind-core).

Bridges HiveMind client messages to an [OpenVoiceOS](https://github.com/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

```bash
pip install hivemind-ovos-agent-plugin
```

Or from source:

```bash
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:

```json
{
  "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

```python
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/):

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

## License

Apache 2.0. See [LICENSE.md](LICENSE.md).
