Voice Agent Core
A flexible, conversational voice companion bot framework for Python. Easily build your own AI assistant by plugging in any LLM (OpenAI, Gemini, etc.) and using built-in voice tools. Great for personal productivity, home automation, or just having a friendly AI to talk to!
Features
- Conversational AI: Integrate any LLM (OpenAI, Gemini, etc.) for smart, natural conversations.
- Speech Recognition: Uses Whisper and SpeechRecognition for accurate voice input.
- Text-to-Speech: Responds with high-quality voice using TTS APIs and local fallback.
- Extensible Tools: Add your own Python functions as tools (play music, check weather, control apps, etc.).
- Easy API: Just provide an LLM handler and start your bot!
Requirements
- Python 3.8+
- System dependencies for audio:
- Linux:
sudo apt-get install portaudio19-dev ffmpeg - macOS:
brew install portaudio ffmpeg - Windows: Install FFmpeg and ensure it's in your PATH.
- Linux:
Installation
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install voice-agent-core
Quick Start: Your Own Companion Bot
Create a Python file (e.g., my_bot.py):
from voice_agent_core import VoiceCompanionBot
import datetime
def my_llm_handler(text):
if "date" in text or "time" in text:
now = datetime.datetime.now()
return {"type": "text_response", "content": f"The current date and time is: {now}"}
else:
return {"type": "text_response", "content": "I am your companion bot! You said: " + text}
bot = VoiceCompanionBot(llm_handler=my_llm_handler)
bot.listen_and_respond()
Run it:
python my_bot.py
Speak to your bot! It will respond with the date/time or echo your message.
Advanced: Use Any LLM (OpenAI Example)
from voice_agent_core import VoiceCompanionBot
import openai
def openai_llm_handler(text):
response = openai.ChatCompletion.create(
model="gpt-4",
messages=[{"role": "system", "content": "You are a helpful, friendly voice companion."},
{"role": "user", "content": text}]
)
return {"type": "text_response", "content": response.choices[0].message['content']}
bot = VoiceCompanionBot(llm_handler=openai_llm_handler)
bot.listen_and_respond()
Adding Custom Tools
You can add your own Python functions as tools. For example:
def get_weather(location):
# Your weather API logic here
return f"Weather in {location}: Sunny!"
tools = {"get_weather": get_weather}
bot = VoiceCompanionBot(llm_handler=my_llm_handler, tools=tools)
Your LLM handler should return:
{"type": "function_call", "call": {"name": "get_weather", "args": {"location": "London"}}}
The bot will call your tool and speak the result.
API Overview
VoiceCompanionBot(llm_handler, tools=None, speak_func=None, listen_func=None)llm_handler(text): function that takes user speech and returns a dict:{ "type": "function_call", "call": {"name": ..., "args": {...}} }{ "type": "text_response", "content": ... }
tools: dict of tool name to function (optional)speak_func: custom TTS function (optional)listen_func: custom speech recognition function (optional)
bot.listen_and_respond(): starts the main loop
License
MIT
For more details, see the API reference and examples above. Enjoy building your own AI companion!
Metadata
Release files for voice-agent-core 1.2.2
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 |
|---|---|---|---|---|
| voice_agent_core-1.2.2.tar.gz | 10.5 kB | Without provenance | Details for voice_agent_core-1.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| voice_agent_core-1.2.2-py3-none-any.whl | Python 3 | none | any | Details for voice_agent_core-1.2.2-py3-none-any.whl |
Total release size: 21.1 kB
Release files / voice_agent_core-1.2.2.tar.gz
| Download URL | voice_agent_core-1.2.2.tar.gz |
|---|---|
| Size | 10.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a1d72d02f0ea48acd39e4be30325e8855d6d841c718e8e0c0877faafbc38fcf
|
|
BLAKE2b-256 checksum How to use checksums |
d951ea72e7c53541fdc7aa20099245c7bed78ecd967f54aeb5c5abf81afd8ae1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.7
|
Release files / voice_agent_core-1.2.2-py3-none-any.whl
| Download URL | voice_agent_core-1.2.2-py3-none-any.whl |
|---|---|
| Size | 10.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
862042a56e4e3db75933442d81d3c16de2584444f4ae8789832ca569bfea8b19
|
|
BLAKE2b-256 checksum How to use checksums |
c5004d0feebbd2e4d3f80ef916f406fe8c9bbbdd235f760391e243035a7788f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.7
|
Security for voice-agent-core 1.2.2
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.