private-assistant-commons 5.0.0

Common utilities and base functionalities for all skills in the Private Assistant ecosystem.

Private Assistant Commons

Owner: stkr22

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

📖 Full 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 requests
• process_request() - Main skill logic
• skill_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 dependencies
• uv run pytest - Run tests with coverage
• uv run ruff check . - Lint code
• uv run mypy src/ - Type check
• pre-commit run --all-files - Run all pre-commit hooks

License

GNU General Public License v3.0 - see LICENSE for details.