Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

hivemind-persona-agent-plugin

An ovos-persona agent protocol for HiveMind-core. The hub answers natural-language utterances from an LLM or solver persona instead of a full OVOS skills stack.

Unlike the default hivemind-ovos-agent-plugin, this agent needs no OVOS skills stack and no messagebus service. It answers directly from the configured persona. It answers three kinds of message:

  • A BUS recognizer_loop:utterance, the message that hivemind-client terminal sends.
  • A BUS ovos.utterance.handle, the message that a voice satellite sends.
  • A QUERY or CASCADE.

The answer comes back sentence by sentence, so a satellite can start speaking before generation finishes.

Install

uv pip install --prerelease=allow hivemind-core hivemind-persona-agent-plugin

The plugin needs a hivemind-core alpha, so the install allows prereleases. A stable hivemind-core resolves to 4.0.0, which conflicts with the plugin.

Or from source:

git clone https://github.com/JarbasHiveMind/hivemind-persona-agent-plugin
cd hivemind-persona-agent-plugin
uv pip install --prerelease=allow hivemind-core -e .

Quickstart

1. Create a persona file

ovos-persona personas are JSON files. The solvers list holds plugin names. Each plugin reads its settings from the key of the same name. Here is a minimal LLM-backed persona:

{
  "name": "MyAssistant",
  "solvers": ["ovos-chat-openai-plugin"],
  "ovos-chat-openai-plugin": {
    "api_url": "http://localhost:8000/v1",
    "model": "local-model",
    "key": "none"
  }
}

Save it to ~/.config/ovos_persona/persona.json, or any path. You reference the path in the config below.

2. Configure hivemind-core

Edit ~/.config/hivemind-core/server.json:

{
  "agent_protocol": {
    "module": "hivemind-persona-agent-plugin",
    "hivemind-persona-agent-plugin": {
      "persona": "~/.config/ovos_persona/persona.json"
    }
  }
}

The persona value can be either:

  • a path to a persona JSON file (string, ~ expands), or
  • an inline persona config dict.

3. Start hivemind-core

hivemind-core listen

4. Allow the utterance topics for the satellite

A satellite can send only the message types its credential allows. Allow both utterance topics. A voice satellite sends ovos.utterance.handle, and hivemind-client terminal sends recognizer_loop:utterance. If a topic is not allowed, the hub replies with hive.policy.denied and code acl_disallowed_type.

hivemind-core add-client --name sat --access-key satkey --password "$(openssl rand -hex 16)" \
    --allow recognizer_loop:utterance --allow ovos.utterance.handle

The command prints the credentials. hivemind-core refuses a guessable password, so use a generated one, and copy it to the satellite.

Satellites that connect to this hub receive answers from the persona as speak messages, followed by ovos.utterance.handled.

Configuration

All keys live under "hivemind-persona-agent-plugin" in server.json.

Key Type Required Description
persona string or dict yes Path to a persona JSON file, or an inline persona config.

How utterances are answered

A BUS utterance reaches the agent bus. The plugin builds the conversation from the persona memory for the satellite's session, calls Persona.stream, and emits one speak reply per sentence, then ovos.utterance.handled. hivemind-core does not listen on the agent bus, so the plugin sends each reply to the peer named in its destination. Utterances of one session are answered one at a time, in arrival order, and a follow-up question sees the earlier turns of that session. A persona that fails or has no answer gets a spoken error sentence. A blank utterance is not sent to the persona.

A QUERY or CASCADE calls natural_language_query(utterance, lang) on the agent. The plugin yields each sentence as a chunk. A query carries no session, so the persona answers each one on its own. If the persona fails or has no answer, the plugin yields only the None sentinel. That is a decline: the hub escalates the query upstream, and at the top of the chain the originator receives hive.query.timeout with error: "no_answer". After an answer, the sentinel makes the hub send hive.query.complete.

See docs/query_flow.md for a detailed trace.

Documentation

License

Apache 2.0.

Credits

Developed by TigreGótico for OpenVoiceOS.

NGI0 Commons Fund

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.

Metadata

Release files for hivemind-persona-agent-plugin 0.0.6a1

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-persona-agent-plugin 0.0.6a1
File Size Uploaded Provenance Actions
hivemind_persona_agent_plugin-0.0.6a1.tar.gz 11.0 kB Without provenance Details for hivemind_persona_agent_plugin-0.0.6a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hivemind-persona-agent-plugin 0.0.6a1
File Interpreter ABI Platform Actions
hivemind_persona_agent_plugin-0.0.6a1-py3-none-any.whl Python 3 none any Details for hivemind_persona_agent_plugin-0.0.6a1-py3-none-any.whl

Total release size: 19.0 kB

Release files / hivemind_persona_agent_plugin-0.0.6a1.tar.gz

Download URL hivemind_persona_agent_plugin-0.0.6a1.tar.gz
Size 11.0 kB
Tags Source
SHA-256 checksum
How to use checksums
4d332077aca6bb3b9548462a0baa06284a4944e5743901e82885ddb55cb7ab37
BLAKE2b-256 checksum
How to use checksums
a9eed8d3ae11f34244b28a18393352d82f2dda4b8b20fa871274f2f9cb5f0a31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / hivemind_persona_agent_plugin-0.0.6a1-py3-none-any.whl

Download URL hivemind_persona_agent_plugin-0.0.6a1-py3-none-any.whl
Size 8.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
904312474e16c91dfbe2eab2406331c5c44484a1aaf249aed6c6e811c553dd85
BLAKE2b-256 checksum
How to use checksums
416b0b839a3d4b938babcceb48a2f0946fd5e570e3118d066f21649b138f81f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for hivemind-persona-agent-plugin 0.0.6a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page