# OVOS-Persona
The **`PersonaPipeline`** brings multi-persona management to OpenVoiceOS (OVOS), enabling interactive conversations with virtual assistants. 🎙️ With personas, you can customize how queries are handled by assigning specific solvers to each persona.
---
## 🚀 TLDR - Quick Start
- update core and install persona
```bash
pip install -U ovos-core>=0.5.1 ovos-persona
```
- install/update plugins and skills
```bash
pip install -U skill-wolfie ovos-skill-wikipedia ovos-skill-wikihow skill-wordnet ovos-openai-plugin
```
- uninstall chatgpt skill
```bash
pip uninstall skill-ovos-fallback-chatgpt
```
- edit mycroft.conf
> ⚠️ don't just copy paste, the `"..."` is a placeholder and invalid. adjust to your existing pipeline config
```json
{
"intents": {
"persona": {
"handle_fallback": true,
"default_persona": "Remote Llama"
},
"pipeline": [
"stop_high",
"converse",
"ocp_high",
"padatious_high",
"adapt_high",
"ovos-persona-pipeline-plugin-high",
"ocp_medium",
"...",
"fallback_medium",
"ovos-persona-pipeline-plugin-low",
"fallback_low"
]
}
}
```
- restart ovos
- check logs to see persona loading, ensure there are no errors
```bash
cat ~/.local/state/mycroft/skills.log | grep persona
```
- read the intents section below
- 🎉
---
## ✨ Features
- **🧑💻 Multiple Personas**: Manage a list of personas, each with its unique solvers.
- **🔄 Dynamic Switching**: Seamlessly switch between personas as needed.
- **💬 Conversational**: Let personas handle utterances directly for richer interaction.
- **🎨 Personalize**: Create your own personas with simple `.json` files.
---
## 🛠️ Installation
```bash
pip install ovos-persona
```
---
## 🗣️ Persona Intents
The Persona Service supports a set of core voice intents to manage persona interactions seamlessly. These intents correspond to the **messagebus events** but are designed for **voice-based activation**.
These intents provide **out-of-the-box functionality** for controlling the Persona Service, ensuring smooth integration with the conversational pipeline and enhancing user experience.
### **List Personas**
**Example Utterances**:
- "What personas are available?"
- "Can you list the personas?"
- "What personas can I use?"
### **Check Active Persona**
**Example Utterances**:
- "Who am I talking to right now?"
- "Is there an active persona?"
- "Which persona is in use?"
### **Activate a Persona**
**Example Utterances**:
- "Connect me to {persona}"
- "Enable {persona}"
- "Awaken the {persona} assistant"
- "Start a conversation with {persona}"
- "Let me chat with {persona}"
### **Single-Shot Persona Questions**
Enables users to query a persona directly without entering an interactive session.
**Example Utterances**:
- "Ask {persona} what they think about {utterance}"
- "What does {persona} say about {utterance}?"
- "Query {persona} for insights on {utterance}"
- "Ask {persona} for their perspective on {utterance}"
### **Stop Conversation**
**Example Utterances**:
- "Stop the interaction"
- "Terminate persona"
- "Deactivate the chatbot"
- "Go dormant"
- "Enough talking"
- "Shut up"
---
## 📖 Pipeline Configuration
When a persona is active you have 2 options:
- send all utterances to the persona and ignore all skills
- let high confidence skills match before using persona
Where to place `"ovos-persona-pipeline-plugin-high"` in your pipeline depends on the desired outcome
Additionally, you have `"ovos-persona-pipeline-plugin-low"` to handle utterances even when a persona isnt explicitly active
##### Option 1: send all utterances to active persona
In this scenario the persona will most likely fail to perform actions like playing music, telling the time and setting alarms.
You will need to explicitly deactivate a persona to use that functionality, the persona has **full control** over the user utterances
Add the persona pipeline to your mycroft.conf **before** the `_high` pipeline matchers
> ⚠️ don't just copy paste, the `"..."` is a placeholder and invalid. adjust to your existing pipeline config
```json
{
"intents": {
"pipeline": [
"ovos-persona-pipeline-plugin-high",
"stop_high",
"converse",
"ocp_high",
"padatious_high",
"adapt_high",
"...",
"fallback_low"
]
}
}
```
##### Option 2: let high confidence skills match before using persona
With this option you still allow skills to trigger even when a persona is active, not all answers are handled by the persona in this case
Add the persona pipeline to your mycroft.conf **after** the `_high` pipeline matchers
> ⚠️ don't just copy paste, the `"..."` is a placeholder and invalid. adjust to your existing pipeline config
```json
{
"intents": {
"pipeline": [
"stop_high",
"converse",
"ocp_high",
"padatious_high",
"adapt_high",
"ovos-persona-pipeline-plugin-high",
"ocp_medium",
"...",
"fallback_low"
]
}
}
```
##### Extra Option: as fallback skill
You can configure ovos-persona to handle utterances when all skills fail even if a persona is not active, this is handled via `"ovos-persona-pipeline-plugin-low"`
> ⚠️ don't just copy paste, the `"..."` is a placeholder and invalid. adjust to your existing pipeline config
```json
{
"intents": {
"persona": {
"handle_fallback": true,
"default_persona": "Remote Llama"
},
"pipeline": [
"...",
"fallback_medium",
"ovos-persona-pipeline-plugin-low",
"fallback_low"
]
}
}
```
> ⚠️ `"ovos-persona-pipeline-plugin-low"` is meant to replace [ovos-skill-fallback-chatgpt](https://github.com/OpenVoiceOS/ovos-skill-fallback-chatgpt)
---
## 🔧 Creating a Persona
Personas are configured using JSON files. These can be:
1️⃣ Provided by **plugins** (e.g., [OpenAI plugin](https://github.com/OpenVoiceOS/ovos-openai-plugin/pull/12)).
2️⃣ Created as **user-defined JSON files** in `~/.config/ovos_persona`.
Personas rely on [solver plugins](https://openvoiceos.github.io/ovos-technical-manual/solvers/), which attempt to answer queries in sequence until a response is found.
🛠️ **Example:** Using a local OpenAI-compatible server.
Save this in `~/.config/ovos_persona/llm.json`:
```json
{
"name": "My Local LLM",
"solvers": [
"ovos-solver-openai-plugin"
],
"ovos-solver-openai-plugin": {
"api_url": "https://llama.smartgic.io/v1",
"key": "sk-xxxx",
"persona": "helpful, creative, clever, and very friendly."
}
}
```
> 💡 **Tip**: Personas don't have to use LLMs! Even without a GPU, you can leverage simpler solvers.
🛠️ **Example:** OldSchoolBot:
```json
{
"name": "OldSchoolBot",
"solvers": [
"ovos-solver-wikipedia-plugin",
"ovos-solver-ddg-plugin",
"ovos-solver-plugin-wolfram-alpha",
"ovos-solver-wordnet-plugin",
"ovos-solver-rivescript-plugin",
"ovos-solver-failure-plugin"
],
"ovos-solver-plugin-wolfram-alpha": {"appid": "Y7353-xxxxxx"}
}
```
**Behavior**:
- 🌐 Searches online (Wikipedia, Wolfram Alpha, etc.).
- 📖 Falls back to offline word lookups via WordNet.
- 🤖 Uses local chatbot (RiveScript) for chitchat.
- ❌ The "failure" solver ensures errors are gracefully handled and we always get a response.
---
## 📡 HiveMind Integration
This project includes a native [hivemind-plugin-manager](https://github.com/JarbasHiveMind/hivemind-plugin-manager) integration, providing seamless interoperability with the HiveMind ecosystem.
- **Agent Protocol**: Provides `hivemind-persona-agent-plugin` allowing to connect satellites directly to a persona
---
## 🤝 Contributing
Got ideas or found bugs?
Submit an issue or create a pull request to help us improve! 🌟
Raw data
{
"_id": null,
"home_page": "https://github.com/OpenVoiceOS/ovos-persona",
"name": "ovos-persona",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "jarbasai",
"author_email": "jarbasai@mailfence.com",
"download_url": "https://files.pythonhosted.org/packages/28/2f/fb2a8eb50e4a7804995a71639b417e82a36c003d6ea5785b8f8ee16f001d/ovos-persona-0.6.13.tar.gz",
"platform": null,
"description": "# OVOS-Persona\n\nThe **`PersonaPipeline`** brings multi-persona management to OpenVoiceOS (OVOS), enabling interactive conversations with virtual assistants. \ud83c\udf99\ufe0f With personas, you can customize how queries are handled by assigning specific solvers to each persona. \n\n---\n\n## \ud83d\ude80 TLDR - Quick Start\n\n- update core and install persona\n ```bash\n pip install -U ovos-core>=0.5.1 ovos-persona\n ```\n- install/update plugins and skills\n ```bash\n pip install -U skill-wolfie ovos-skill-wikipedia ovos-skill-wikihow skill-wordnet ovos-openai-plugin\n ```\n- uninstall chatgpt skill\n ```bash\n pip uninstall skill-ovos-fallback-chatgpt\n ```\n- edit mycroft.conf\n > \u26a0\ufe0f don't just copy paste, the `\"...\"` is a placeholder and invalid. adjust to your existing pipeline config\n ```json\n {\n \"intents\": {\n \"persona\": {\n \"handle_fallback\": true,\n \"default_persona\": \"Remote Llama\"\n },\n \"pipeline\": [\n \"stop_high\",\n \"converse\",\n \"ocp_high\",\n \"padatious_high\",\n \"adapt_high\",\n \"ovos-persona-pipeline-plugin-high\",\n \"ocp_medium\",\n \"...\",\n \"fallback_medium\",\n \"ovos-persona-pipeline-plugin-low\",\n \"fallback_low\"\n ]\n }\n }\n ```\n- restart ovos\n- check logs to see persona loading, ensure there are no errors\n ```bash\n cat ~/.local/state/mycroft/skills.log | grep persona\n ```\n- read the intents section below\n- \ud83c\udf89\n \n---\n\n## \u2728 Features\n\n- **\ud83e\uddd1\u200d\ud83d\udcbb Multiple Personas**: Manage a list of personas, each with its unique solvers. \n- **\ud83d\udd04 Dynamic Switching**: Seamlessly switch between personas as needed. \n- **\ud83d\udcac Conversational**: Let personas handle utterances directly for richer interaction. \n- **\ud83c\udfa8 Personalize**: Create your own personas with simple `.json` files.\n\n---\n\n## \ud83d\udee0\ufe0f Installation\n\n```bash\npip install ovos-persona\n```\n\n---\n\n## \ud83d\udde3\ufe0f Persona Intents\n\nThe Persona Service supports a set of core voice intents to manage persona interactions seamlessly. These intents correspond to the **messagebus events** but are designed for **voice-based activation**. \n\nThese intents provide **out-of-the-box functionality** for controlling the Persona Service, ensuring smooth integration with the conversational pipeline and enhancing user experience.\n\n### **List Personas**\n\n**Example Utterances**:\n- \"What personas are available?\"\n- \"Can you list the personas?\"\n- \"What personas can I use?\"\n\n### **Check Active Persona**\n\n**Example Utterances**:\n\n- \"Who am I talking to right now?\"\n- \"Is there an active persona?\"\n- \"Which persona is in use?\"\n\n### **Activate a Persona**\n\n**Example Utterances**:\n- \"Connect me to {persona}\" \n- \"Enable {persona}\" \n- \"Awaken the {persona} assistant\" \n- \"Start a conversation with {persona}\" \n- \"Let me chat with {persona}\" \n\n\n### **Single-Shot Persona Questions**\n\nEnables users to query a persona directly without entering an interactive session. \n\n**Example Utterances**:\n- \"Ask {persona} what they think about {utterance}\" \n- \"What does {persona} say about {utterance}?\" \n- \"Query {persona} for insights on {utterance}\" \n- \"Ask {persona} for their perspective on {utterance}\" \n\n\n### **Stop Conversation**\n\n**Example Utterances**:\n- \"Stop the interaction\" \n- \"Terminate persona\" \n- \"Deactivate the chatbot\" \n- \"Go dormant\" \n- \"Enough talking\" \n- \"Shut up\" \n\n---\n\n\n## \ud83d\udcd6 Pipeline Configuration\n\nWhen a persona is active you have 2 options:\n- send all utterances to the persona and ignore all skills\n- let high confidence skills match before using persona\n\nWhere to place `\"ovos-persona-pipeline-plugin-high\"` in your pipeline depends on the desired outcome\n\nAdditionally, you have `\"ovos-persona-pipeline-plugin-low\"` to handle utterances even when a persona isnt explicitly active\n\n\n##### Option 1: send all utterances to active persona\n\nIn this scenario the persona will most likely fail to perform actions like playing music, telling the time and setting alarms. \n\nYou will need to explicitly deactivate a persona to use that functionality, the persona has **full control** over the user utterances\n\nAdd the persona pipeline to your mycroft.conf **before** the `_high` pipeline matchers\n\n> \u26a0\ufe0f don't just copy paste, the `\"...\"` is a placeholder and invalid. adjust to your existing pipeline config\n```json\n{\n \"intents\": {\n \"pipeline\": [\n \"ovos-persona-pipeline-plugin-high\",\n \"stop_high\",\n \"converse\",\n \"ocp_high\",\n \"padatious_high\",\n \"adapt_high\",\n \"...\",\n \"fallback_low\"\n ]\n }\n}\n```\n\n##### Option 2: let high confidence skills match before using persona\n\nWith this option you still allow skills to trigger even when a persona is active, not all answers are handled by the persona in this case\n\nAdd the persona pipeline to your mycroft.conf **after** the `_high` pipeline matchers\n\n> \u26a0\ufe0f don't just copy paste, the `\"...\"` is a placeholder and invalid. adjust to your existing pipeline config\n```json\n{\n \"intents\": {\n \"pipeline\": [\n \"stop_high\",\n \"converse\",\n \"ocp_high\",\n \"padatious_high\",\n \"adapt_high\",\n \"ovos-persona-pipeline-plugin-high\",\n \"ocp_medium\",\n \"...\",\n \"fallback_low\"\n ]\n }\n}\n```\n\n##### Extra Option: as fallback skill\n\nYou can configure ovos-persona to handle utterances when all skills fail even if a persona is not active, this is handled via `\"ovos-persona-pipeline-plugin-low\"`\n\n> \u26a0\ufe0f don't just copy paste, the `\"...\"` is a placeholder and invalid. adjust to your existing pipeline config\n\n```json\n{\n \"intents\": {\n \"persona\": {\n \"handle_fallback\": true,\n \"default_persona\": \"Remote Llama\"\n },\n \"pipeline\": [\n \"...\",\n \"fallback_medium\",\n \"ovos-persona-pipeline-plugin-low\",\n \"fallback_low\"\n ]\n }\n}\n```\n\n> \u26a0\ufe0f `\"ovos-persona-pipeline-plugin-low\"` is meant to replace [ovos-skill-fallback-chatgpt](https://github.com/OpenVoiceOS/ovos-skill-fallback-chatgpt)\n\n---\n\n## \ud83d\udd27 Creating a Persona\n\nPersonas are configured using JSON files. These can be: \n1\ufe0f\u20e3 Provided by **plugins** (e.g., [OpenAI plugin](https://github.com/OpenVoiceOS/ovos-openai-plugin/pull/12)). \n2\ufe0f\u20e3 Created as **user-defined JSON files** in `~/.config/ovos_persona`. \n\nPersonas rely on [solver plugins](https://openvoiceos.github.io/ovos-technical-manual/solvers/), which attempt to answer queries in sequence until a response is found. \n\n\ud83d\udee0\ufe0f **Example:** Using a local OpenAI-compatible server. \nSave this in `~/.config/ovos_persona/llm.json`: \n```json\n{\n \"name\": \"My Local LLM\",\n \"solvers\": [\n \"ovos-solver-openai-plugin\"\n ],\n \"ovos-solver-openai-plugin\": {\n \"api_url\": \"https://llama.smartgic.io/v1\",\n \"key\": \"sk-xxxx\",\n \"persona\": \"helpful, creative, clever, and very friendly.\"\n }\n}\n```\n\n> \ud83d\udca1 **Tip**: Personas don't have to use LLMs! Even without a GPU, you can leverage simpler solvers. \n\n\ud83d\udee0\ufe0f **Example:** OldSchoolBot: \n```json\n{\n \"name\": \"OldSchoolBot\",\n \"solvers\": [\n \"ovos-solver-wikipedia-plugin\",\n \"ovos-solver-ddg-plugin\",\n \"ovos-solver-plugin-wolfram-alpha\",\n \"ovos-solver-wordnet-plugin\",\n \"ovos-solver-rivescript-plugin\",\n \"ovos-solver-failure-plugin\"\n ],\n \"ovos-solver-plugin-wolfram-alpha\": {\"appid\": \"Y7353-xxxxxx\"}\n}\n```\n**Behavior**:\n- \ud83c\udf10 Searches online (Wikipedia, Wolfram Alpha, etc.). \n- \ud83d\udcd6 Falls back to offline word lookups via WordNet. \n- \ud83e\udd16 Uses local chatbot (RiveScript) for chitchat. \n- \u274c The \"failure\" solver ensures errors are gracefully handled and we always get a response.\n\n---\n\n## \ud83d\udce1 HiveMind Integration\n\nThis project includes a native [hivemind-plugin-manager](https://github.com/JarbasHiveMind/hivemind-plugin-manager) integration, providing seamless interoperability with the HiveMind ecosystem.\n\n- **Agent Protocol**: Provides `hivemind-persona-agent-plugin` allowing to connect satellites directly to a persona\n \n\n---\n\n\n## \ud83e\udd1d Contributing\n\nGot ideas or found bugs? \nSubmit an issue or create a pull request to help us improve! \ud83c\udf1f \n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "persona pipeline for ovos",
"version": "0.6.13",
"project_urls": {
"Homepage": "https://github.com/OpenVoiceOS/ovos-persona"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "778bb641abe989610226d3c4da10ead6736a6cf48d87e9dbcbca8ccce6fcf310",
"md5": "37e813ea87e43bb79720f3804e503b9a",
"sha256": "9e64432e2f9a788892c1e1461b9ef6c8ef5e97dc9e45092eb01143a080bbae33"
},
"downloads": -1,
"filename": "ovos_persona-0.6.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37e813ea87e43bb79720f3804e503b9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 62155,
"upload_time": "2025-02-27T17:07:57",
"upload_time_iso_8601": "2025-02-27T17:07:57.469502Z",
"url": "https://files.pythonhosted.org/packages/77/8b/b641abe989610226d3c4da10ead6736a6cf48d87e9dbcbca8ccce6fcf310/ovos_persona-0.6.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "282ffb2a8eb50e4a7804995a71639b417e82a36c003d6ea5785b8f8ee16f001d",
"md5": "e98c1be06ebe9dfe1fae60e687a21839",
"sha256": "960b26c44e210930b7ec24a6490399d97f642c772bba31850a5a8c5c4ffa1c40"
},
"downloads": -1,
"filename": "ovos-persona-0.6.13.tar.gz",
"has_sig": false,
"md5_digest": "e98c1be06ebe9dfe1fae60e687a21839",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40712,
"upload_time": "2025-02-27T17:07:59",
"upload_time_iso_8601": "2025-02-27T17:07:59.285221Z",
"url": "https://files.pythonhosted.org/packages/28/2f/fb2a8eb50e4a7804995a71639b417e82a36c003d6ea5785b8f8ee16f001d/ovos-persona-0.6.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-27 17:07:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OpenVoiceOS",
"github_project": "ovos-persona",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "ovos-plugin-manager",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.8.3"
]
]
},
{
"name": "ovos-openai-plugin",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.0.0"
]
]
},
{
"name": "ovos-solver-failure-plugin",
"specs": []
},
{
"name": "ovos-utils",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.7.0"
]
]
},
{
"name": "langcodes",
"specs": []
}
],
"lcname": "ovos-persona"
}
JSON
