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
BUSrecognizer_loop:utterance, the message thathivemind-client terminalsends. - A
BUSovos.utterance.handle, the message that a voice satellite sends. - A
QUERYorCASCADE.
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
docs/query_flow.md: how a query travels from satellite to persona and back.docs/configuration.md: configuration reference.docs/persona_format.md: how to write and configure an ovos-persona file.
Related projects
- ovos-persona: the solver-chain persona engine this plugin calls.
- HiveMind-core: the hub that loads this plugin.
- hivemind-ovos-agent-plugin: the default agent protocol, backed by a full OVOS skills stack.
License
Apache 2.0.
Credits
Developed by TigreGótico for OpenVoiceOS.
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.7a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hivemind_persona_agent_plugin-0.0.7a1.tar.gz | 11.0 kB | Without provenance | Details for hivemind_persona_agent_plugin-0.0.7a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hivemind_persona_agent_plugin-0.0.7a1-py3-none-any.whl | Python 3 | none | any | Details for hivemind_persona_agent_plugin-0.0.7a1-py3-none-any.whl |
Total release size: 19.0 kB
Release files / hivemind_persona_agent_plugin-0.0.7a1.tar.gz
| Download URL | hivemind_persona_agent_plugin-0.0.7a1.tar.gz |
|---|---|
| Size | 11.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bc9e020071a21bef40f661f6bbc2a1a616916c9f4662f5fff638515d1fde0c3f
|
|
BLAKE2b-256 checksum How to use checksums |
b47d66e80dc4b0c60004890679f5906534dc0646cea9e256232f97fea4afb9f9
|
| 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.7a1-py3-none-any.whl
| Download URL | hivemind_persona_agent_plugin-0.0.7a1-py3-none-any.whl |
|---|---|
| Size | 8.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ab20079d9c84446538bd596d71061912352d14cd2c2a8d7d58c3e0b5c08073a8
|
|
BLAKE2b-256 checksum How to use checksums |
46a5c54a2eca25432d08178c26b5e5717e1b65d0760026a0ce5ddcf7fa9680a3
|
| 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.7a1
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.