Private Assistant Commons
Common utilities and base classes for building distributed voice assistant skills in a Private Assistant ecosystem. This library provides the foundation for creating modular, MQTT-based skills that process voice commands for home automation.
Key Features
- BaseSkill Framework: Abstract base class with distributed processing, certainty-based filtering, and task management
- MQTT Communication: Structured message handling using Pydantic models with automatic reconnection
- Location Awareness: Support for room-based command routing and targeting
- Audio Integration: Configurable alerts and responses through voice bridge system
- Performance Metrics: Built-in monitoring with Prometheus export and health checking for production deployments
- Optional Persistence: PostgreSQL integration for skills requiring state storage
Quick Start
Installation
pip install private-assistant-commons
Basic Skill Example
from private_assistant_commons import BaseSkill, IntentRequest, IntentType
class LightControlSkill(BaseSkill):
async def calculate_certainty(self, intent_request: IntentRequest) -> float:
intent = intent_request.classified_intent
if intent.intent_type in (IntentType.DEVICE_ON, IntentType.DEVICE_OFF):
return intent.confidence
return 0.0
async def process_request(self, intent_request: IntentRequest) -> None:
await self.send_response("Lights controlled!", intent_request.client_request)
async def skill_preparations(self) -> None:
self.logger.info("Light skill ready")
Documentation
- Architecture Guide - System design, components, and data flow
- Usage Guide - Examples, patterns, and best practices
- API Reference - Complete API documentation
System Overview
Private Assistant Commons enables building a distributed voice assistant system where:
- Skills run independently and decide whether to handle requests based on confidence scores
- Communication via MQTT using structured Pydantic messages
- No central coordinator - skills compete based on certainty thresholds
- Room-based targeting distinguishes command origin from target locations
- Local deployment typically on Kubernetes with STT/TTS APIs
Architecture
User Voice → Local Client → Voice Bridge → STT API → MQTT Broker
↓
Intent Analysis Engine ← MQTT Broker ← Skills (distributed processing)
↓
Voice Bridge ← TTS API ← MQTT Broker ← Skill Responses
↓
Local Client → Audio Output
Skills inherit from BaseSkill and implement:
calculate_certainty()- Confidence scoring for requestsprocess_request()- Main skill logicskill_preparations()- Initialization setup
Development
Prerequisites
- Python 3.12+
- UV package manager
Setup
# Clone and setup environment
git clone <repository-url>
cd private-assistant-commons-py
uv sync --group dev
# Run tests
uv run pytest
# Format and lint
uv run ruff format .
uv run ruff check .
# Type checking
uv run mypy src/
Essential Commands
uv sync --group dev- Install/update dependenciesuv run pytest- Run tests with coverageuv run ruff check .- Lint codeuv run mypy src/- Type checkpre-commit run --all-files- Run all pre-commit hooks
License
GNU General Public License v3.0 - see LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for private-assistant-commons 6.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| private_assistant_commons-6.3.0.tar.gz | 42.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| private_assistant_commons-6.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 92.3 kB
Release files / private_assistant_commons-6.3.0.tar.gz
| Download URL | private_assistant_commons-6.3.0.tar.gz |
|---|---|
| Size | 42.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0edac0b6b8a2d6b573fa68e440ff868039a618abd093beff0af6c67ae57ade3
|
|
BLAKE2b-256 checksum How to use checksums |
a65591c7d07f71464f274b70d91b014122a1d40cf6bbd58441ecfc89ae35452a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 31, 2026.
Transparency logRelease files / private_assistant_commons-6.3.0-py3-none-any.whl
| Download URL | private_assistant_commons-6.3.0-py3-none-any.whl |
|---|---|
| Size | 49.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
369049600b975f32904d1b75b6237b2f435b6164028fcc3d46331d82770c1807
|
|
BLAKE2b-256 checksum How to use checksums |
fb2016a7268641efa4a07ee87a0587fa5c783e35fd689f85e7d923bc2588568f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 31, 2026.
Transparency log
