ha-voice-label-sync 0.2.0.dev0__py3-none-any.whl

ha_voice_label_sync-0.2.0.dev0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: ha-voice-label-sync
+Version: 0.2.0.dev0
+Summary: Generate voice assistant configuration from Home Assistant labels.
+Author: Philippe Le Bonhomme
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/flimo44/ha-voice-label-sync
+Project-URL: Documentation, https://github.com/flimo44/ha-voice-label-sync#readme
+Project-URL: Issues, https://github.com/flimo44/ha-voice-label-sync/issues
+Project-URL: Source, https://github.com/flimo44/ha-voice-label-sync
+Keywords: home-assistant,google-assistant,voice-assistant,automation,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<img width="1024" height="559" alt="image" src="https://github.com/user-attachments/assets/6918c5ae-b95b-4d81-9108-7b2cd8acd0fd" />
+
+### Automatically generate your voice assistant configuration from Home Assistant labels.
+
+[![Python checks](https://github.com/flimo44/ha-voice-label-sync/actions/workflows/python-check.yml/badge.svg?branch=main)](https://github.com/flimo44/ha-voice-label-sync/actions/workflows/python-check.yml)
+
+
+> 🚧 Early development project
+>
+> Feedback and ideas are welcome.
+
+## Why?
+
+Do you maintain dozens of Google Assistant entities manually?
+
+Managing voice assistant configurations manually quickly becomes difficult.
+
+HA Voice Label Sync automatically generates the required configuration from Home Assistant labels, making your labels the single source of truth.
+
+With the current release you can:
+
+Stop maintaining large YAML files manually.
+Avoid duplicated configuration.
+Keep Home Assistant as the only place where entities are managed.
+Generate your configuration in seconds.
+
+## Current Status
+
+## Project status
+
+HVLS is currently under active development.
+
+Latest stable release: `v0.1.2`
+
+Current development version: `0.2.0.dev0`
+
+Current capabilities:
+
+- Standalone CLI
+- Reusable Python core
+- Google Assistant YAML generation
+- Dry-run support
+- Safe atomic file writing
+- Automatic backups and retention
+- Initial Home Assistant integration skeleton
+
+Not yet available:
+
+- Full Home Assistant configuration UI
+- Home Assistant actions and buttons
+- Backup restoration from the UI
+- HACS installation
+
+HA Voice Label Sync has been designed to support multiple voice assistants.
+
+- Currently supported :
+
+
+      ✅ Google Assistant
+
+- Planned :
+
+      Amazon Alexa
+      Apple HomeKit
+
+Instead of maintaining a long list of exposed entities manually, simply assign a label in Home Assistant, run the script, and let HA Voice Label Sync generate the configuration for you.
+
+
+## Features
+
+- Select entities using a Home Assistant label
+- Generate `entity_config` for Google Assistant
+- Use Home Assistant friendly names
+- Use Home Assistant areas as Google rooms
+- Ignore disabled or hidden entities
+- Dry-run mode before writing the file
+
+## How it works
+
+
+```
+                           Home Assistant
+                                │
+                                ▼
+                              Labels
+                                │
+                                ▼
+                        Voice Assistant Sync
+                                │
+                         ┌──────┴───────┐
+                         │              │
+               Google Assistant    Amazon Alexa
+       
+```
+
+## Generated entity_config
+
+```yaml
+switch.prise_pompe:
+  expose: true
+  name: Pompe piscine
+  room: Piscine
+```
+
+
+Home Assistant configuration
+
+```yaml
+google_assistant:
+  project_id: YOUR_PROJECT_ID
+  service_account: !include google_key.json
+  report_state: true
+  expose_by_default: false
+  entity_config: !include google_assistant_entities.yaml
+```
+
+## Quick start
+
+Installation
+
+Option 1 – Download the script
+
+Download the latest version of ga_label_sync.py from the repository.
+
+Copy it to your Home Assistant scripts directory.
+
+Typical locations are:
+
+```text
+/config/scripts/
+
+or
+
+<home-assistant-config>/scripts/
+```
+
+depending on your Home Assistant installation.
+
+Option 2 – Clone the repository
+```bash
+git clone https://github.com/flimo44/ha-voice-label-sync.git
+```
+The script is located in:
+```text
+scripts/ga_label_sync.py
+```
+
+```Tip
+
+If you simply want to use the script, downloading scripts/ga_label_sync.py is enough.
+
+Cloning the repository is recommended only if you plan to follow development or contribute to the project.
+```
+
+Usage :
+
+### Step 1 — Add the label
+
+<img width="455" height="375" alt="Capture d&#39;écran 2026-06-26 201643" src="https://github.com/user-attachments/assets/a262942a-5fb1-4a84-b88e-5db12eb67be8" />
+
+
+### Step 2 — Preview the generated configuration
+
+
+<img width="555" height="172" alt="Capture d&#39;écran 2026-06-26 203136" src="https://github.com/user-attachments/assets/66ea6d63-983b-467b-9870-198d64b027bd" />
+
+```bash
+python3 /config/scripts/ga_label_sync.py --label "google_assistant" --dry-run
+```
+
+```
+# --- Couloir ---
+lock.serrure_maison:
+  expose: true
+  name: Serrure porte entrée
+  room: Couloir
+
+# --- Jardin ---
+switch.portail:
+  expose: true
+  name: Portail
+  room: Jardin
+
+# --- Piscine ---
+input_select.piscine_mode_gestion:
+  expose: true
+  name: "Piscine - Mode Gestion"
+  room: Piscine
+
+switch.piscine_chauffage:
+  expose: true
+  name: Pac Piscine
+  room: Piscine
+
+switch.prise_pompe2:
+  expose: true
+  name: Pompe piscine
+  room: Piscine
+```
+
+
+### Step 3 — Generate the file
+```bash
+python3 /config/scripts/ga_label_sync.py --label "google_assistant"
+```
+<img width="454" height="446" alt="Capture d&#39;écran 2026-06-26 200340" src="https://github.com/user-attachments/assets/6f0938ae-13e9-4856-9b4f-7db5e8290171" />
+
+
+### Step 4 — Restart Home Assistant
+
+
+
+### Step 5 — Synchronize Google Home
+
+
+Google Home before synchronization
+
+<img width="1080" height="2400" alt="Screenshot_2026-06-26-19-44-33-60_2d2bd67b5e15ae98c151ac739cd6881e" src="https://github.com/user-attachments/assets/a03d1005-fde8-4186-b8ea-da2f426c5a84" />
+
+Google Home after synchronization
+
+<img width="1080" height="2400" alt="Screenshot_2026-06-26-19-45-48-86_2d2bd67b5e15ae98c151ac739cd6881e" src="https://github.com/user-attachments/assets/5b4d96cc-9da9-4419-9d1f-f5eac4fbec8c" />
+
+License
+MIT

ha_voice_label_sync-0.2.0.dev0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ha_voice_label_sync-0.2.0.dev0.dist-info/licenses/LICENSE,sha256=ynISXJIpaGnb6casTM1HdJvEB5xdu2vqT9NBVEZKmHI,1064
+hvls/__init__.py,sha256=C3jbWnJlif0RF2f1Rmj0gyno2-POrO2DO759NmJnEUw,1108
+hvls/cli.py,sha256=taIaKg0938Cm1gWNKDGuA-PbUpNILE4kdMYnWOLTDwk,4063
+hvls/engine.py,sha256=kAndRxaYbv1ynl2XoEY1jcdm7qvyevVO9j7dP-C-5Qc,5040
+hvls/models.py,sha256=hxYqYjb1jtGPFvqV3G3xeCb-Gn_c9QPgIrWvAMZnNLY,2416
+hvls/orchestrator.py,sha256=W4RZvJjpiRDFFUev9MmlxwDJebiyyXL4nSUBfdOWoBc,2598
+hvls/registry.py,sha256=zp5NHRVVnDEP7q7vfOWBz0-vDViJDKqUTcfuTt9Ju-8,2422
+hvls/backends/__init__.py,sha256=WOFwd9yzl4wO4T6P-hxawN9hOAkY2duTk5Quit0dgUQ,172
+hvls/backends/google.py,sha256=8CQ5zyIxS-ahMSOxCgSAVQzKrsFSblC_urQmQR-nLBI,2122
+hvls/writers/__init__.py,sha256=X-4Cfb-BYzPG8cQb8z5a3RWLSPmyB28SsxeNnMHQPbw,311
+hvls/writers/filesystem.py,sha256=_aEYY4rqts-A-1Y9rInLBYorjoiVjEBksgaSuD9RzlU,4691
+ha_voice_label_sync-0.2.0.dev0.dist-info/METADATA,sha256=U0hl8nsQSsyNda_nv4vumSBidCwSXvVSOJo9lS-8UBI,6466
+ha_voice_label_sync-0.2.0.dev0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ha_voice_label_sync-0.2.0.dev0.dist-info/entry_points.txt,sha256=_hB7iAHYgG1zZS_LQhVakxjohB5aer31FQyUEK3DJZA,39
+ha_voice_label_sync-0.2.0.dev0.dist-info/top_level.txt,sha256=i0BQbMR6mHoKNWt8Cpjjf0aA0JDeWw6sxIx-1I8yhjs,5
+ha_voice_label_sync-0.2.0.dev0.dist-info/RECORD,,

ha_voice_label_sync-0.2.0.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ha_voice_label_sync-0.2.0.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hvls = hvls.cli:main

ha_voice_label_sync-0.2.0.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flimo44
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ha_voice_label_sync-0.2.0.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hvls

hvls/__init__.py

@@ -0,0 +1,45 @@
+"""Reusable core package for HA Voice Label Sync."""
+
+from .backends import render_google_assistant, yaml_escape
+from .engine import resolve_label_ids, select_entities, slugify
+from .models import (
+    FileWriteResult,
+    GenerationRequest,
+    GenerationResult,
+    SelectedEntity,
+    SelectionResult,
+    WorkflowResult,
+)
+from .orchestrator import WorkflowError, run_google_assistant_workflow
+from .registry import RegistryError, get_registry_items, load_json
+from .writers import (
+    FileWriterError,
+    apply_backup_retention,
+    atomic_write,
+    create_backup,
+    write_with_backup,
+)
+
+__all__ = [
+    "GenerationRequest",
+    "GenerationResult",
+    "RegistryError",
+    "SelectedEntity",
+    "SelectionResult",
+    "get_registry_items",
+    "load_json",
+    "resolve_label_ids",
+    "select_entities",
+    "slugify",
+    "render_google_assistant",
+    "yaml_escape",
+    "FileWriteResult",
+    "FileWriterError",
+    "apply_backup_retention",
+    "atomic_write",
+    "create_backup",
+    "write_with_backup",
+    "WorkflowError",
+    "WorkflowResult",
+    "run_google_assistant_workflow",
+]

hvls/backends/__init__.py

@@ -0,0 +1,8 @@
+"""Voice assistant backends provided by HVLS."""
+
+from .google import render_google_assistant, yaml_escape
+
+__all__ = [
+    "render_google_assistant",
+    "yaml_escape",
+]

hvls/backends/google.py

@@ -0,0 +1,87 @@
+"""Google Assistant YAML backend for HA Voice Label Sync."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from ..models import GenerationResult, SelectionResult
+
+YAML_RESERVED_WORDS = {
+    "y",
+    "yes",
+    "n",
+    "no",
+    "true",
+    "false",
+    "on",
+    "off",
+    "null",
+    "~",
+    "none",
+}
+
+YAML_QUOTING_PATTERN = r'[:#{}\[\],&*?|\-<>=!%@`"\']'
+
+
+def yaml_escape(value: object) -> str:
+    """Return a value safe for use as a YAML string scalar."""
+    text = str(value).strip()
+
+    if not text:
+        return '""'
+
+    if text.lower() in YAML_RESERVED_WORDS:
+        return json.dumps(text, ensure_ascii=False)
+
+    if re.fullmatch(r"[+-]?\d+(\.\d+)?", text):
+        return json.dumps(text, ensure_ascii=False)
+
+    if re.search(YAML_QUOTING_PATTERN, text):
+        return json.dumps(text, ensure_ascii=False)
+
+    return text
+
+
+def render_google_assistant(
+    selection: SelectionResult,
+) -> GenerationResult:
+    """Render selected entities as Google Assistant entity configuration.
+
+    Args:
+        selection: Neutral entities selected by the HVLS engine.
+
+    Returns:
+        Generated YAML and structured generation metadata.
+    """
+    lines = [
+        "# Fichier généré automatiquement.",
+        "# Ne pas modifier à la main.",
+        "# Ajouter/retirer l'étiquette HA pour gérer l'exposition Google Assistant.",
+        "",
+    ]
+
+    current_room: str | None | object = object()
+
+    for entity in selection.entities:
+        if entity.room != current_room:
+            current_room = entity.room
+            lines.append(f"# --- {entity.room or 'Sans pièce'} ---")
+
+        lines.append(f"{entity.entity_id}:")
+        lines.append("  expose: true")
+        lines.append(f"  name: {yaml_escape(entity.name)}")
+
+        if entity.room:
+            lines.append(f"  room: {yaml_escape(entity.room)}")
+
+        lines.append("")
+
+    content = "\n".join(lines).rstrip() + "\n"
+
+    return GenerationResult(
+        content=content,
+        entities=selection.entities,
+        domain_counts=dict(selection.domain_counts),
+        warnings=selection.warnings,
+    )

hvls/cli.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Command-line interface for HA Voice Label Sync."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import (  # noqa: E402
+    FileWriterError,
+    GenerationRequest,
+    RegistryError,
+    WorkflowError,
+    run_google_assistant_workflow,
+)
+
+CONFIG_DIRECTORY = Path("/config")
+STORAGE_DIRECTORY = CONFIG_DIRECTORY / ".storage"
+DEFAULT_OUTPUT_FILE = CONFIG_DIRECTORY / "google_assistant_entities.yaml"
+
+DEFAULT_DOMAINS = {
+    "light",
+    "switch",
+    "cover",
+    "climate",
+    "fan",
+    "input_boolean",
+    "input_select",
+    "scene",
+    "script",
+    "lock",
+    "vacuum",
+    "select",
+}
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    """Build and return the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Generate Google Assistant entity configuration from "
+            "Home Assistant labels."
+        )
+    )
+
+    parser.add_argument(
+        "--label",
+        default="google_assistant",
+        help="Home Assistant label used to select exposed entities.",
+    )
+
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=DEFAULT_OUTPUT_FILE,
+        help="Path of the generated YAML file.",
+    )
+
+    parser.add_argument(
+        "--storage",
+        type=Path,
+        default=STORAGE_DIRECTORY,
+        help="Path to the Home Assistant .storage directory.",
+    )
+
+    parser.add_argument(
+        "--domains",
+        nargs="*",
+        default=sorted(DEFAULT_DOMAINS),
+        help="Home Assistant domains to include.",
+    )
+
+    parser.add_argument(
+        "--backup-directory",
+        type=Path,
+        default=None,
+        help=(
+            "Directory used for backups. "
+            "Defaults to .hvls_backups beside the output file."
+        ),
+    )
+
+    parser.add_argument(
+        "--backup-retention",
+        type=int,
+        default=5,
+        help="Maximum number of backups to keep.",
+    )
+
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Display the generated YAML without writing any file.",
+    )
+
+    return parser
+
+
+def print_summary(result: object) -> None:
+    """Display a human-readable workflow summary."""
+    generation = result.generation
+
+    print(f"Total: {generation.entity_count} entités")
+
+    if generation.domain_counts:
+        detail = ", ".join(
+            f"{domain}: {count}"
+            for domain, count in sorted(generation.domain_counts.items())
+        )
+        print(f"Détail par domaine -> {detail}")
+
+    for warning in generation.warnings:
+        print(f"Attention : {warning}", file=sys.stderr)
+
+    if result.dry_run:
+        print()
+        print(generation.content, end="")
+        return
+
+    write_result = result.write_result
+
+    if write_result is None:
+        return
+
+    print(f"OK: fichier écrit dans {write_result.output_path}")
+    print(f"Octets écrits: {write_result.bytes_written}")
+
+    if write_result.backup_path is not None:
+        print(f"Sauvegarde créée: {write_result.backup_path}")
+
+
+def main() -> int:
+    """Run the HVLS command-line interface."""
+    parser = build_argument_parser()
+    args = parser.parse_args()
+
+    if args.backup_retention < 0:
+        parser.error("--backup-retention ne peut pas être négatif.")
+
+    request = GenerationRequest(
+        label=args.label,
+        domains=frozenset(args.domains),
+        output_path=args.output,
+        dry_run=args.dry_run,
+    )
+
+    try:
+        result = run_google_assistant_workflow(
+            request=request,
+            storage_path=args.storage,
+            backup_directory=args.backup_directory,
+            backup_retention=args.backup_retention,
+        )
+    except (
+        RegistryError,
+        FileWriterError,
+        WorkflowError,
+        OSError,
+        ValueError,
+    ) as exc:
+        print(f"Erreur : {exc}", file=sys.stderr)
+        return 1
+
+    print_summary(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hvls/engine.py

@@ -0,0 +1,178 @@
+"""Core entity selection engine for HA Voice Label Sync."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Collection
+from typing import Any
+
+from .models import GenerationRequest, SelectedEntity, SelectionResult
+from .registry import get_registry_items
+
+
+def slugify(value: str) -> str:
+    """Normalize a Home Assistant label for comparison."""
+    normalized = unicodedata.normalize("NFKD", value.strip().lower())
+    ascii_value = normalized.encode("ascii", "ignore").decode("ascii")
+    ascii_value = ascii_value.replace(" ", "_").replace("-", "_")
+    ascii_value = re.sub(r"[^a-z0-9_]", "", ascii_value)
+    return re.sub(r"_+", "_", ascii_value).strip("_")
+
+
+def resolve_label_ids(
+    labels: Collection[dict[str, Any]],
+    label_name: str,
+) -> tuple[frozenset[str], tuple[str, ...]]:
+    """Resolve a label name or normalized label identifier.
+
+    Args:
+        labels: Home Assistant label registry entries.
+        label_name: Label name or identifier requested by the user.
+
+    Returns:
+        Matching label identifiers and any generated warnings.
+    """
+    wanted_slug = slugify(label_name)
+    identifiers = {label_name, wanted_slug}
+    found = False
+
+    for label in labels:
+        name = str(label.get("name") or "")
+        label_id = str(label.get("label_id") or "")
+
+        if (
+            label_id == label_name
+            or name == label_name
+            or slugify(name) == wanted_slug
+        ):
+            if label_id:
+                identifiers.add(label_id)
+            found = True
+
+    warnings: tuple[str, ...] = ()
+
+    if not found:
+        warnings = (
+            f"No Home Assistant label matches '{label_name}'.",
+        )
+
+    return frozenset(identifiers), warnings
+
+
+def select_entities(
+    request: GenerationRequest,
+    entity_registry: dict[str, Any],
+    device_registry: dict[str, Any],
+    area_registry: dict[str, Any],
+    label_registry: dict[str, Any],
+) -> SelectionResult:
+    """Select Home Assistant entities matching a generation request.
+
+    This function performs no file writing and produces no backend-specific
+    configuration.
+
+    Args:
+        request: Selection and generation parameters.
+        entity_registry: Parsed Home Assistant entity registry.
+        device_registry: Parsed Home Assistant device registry.
+        area_registry: Parsed Home Assistant area registry.
+        label_registry: Parsed Home Assistant label registry.
+
+    Returns:
+        A structured selection result.
+    """
+    entity_entries = get_registry_items(entity_registry, "entities")
+    device_entries = get_registry_items(device_registry, "devices")
+    area_entries = get_registry_items(area_registry, "areas")
+    label_entries = get_registry_items(label_registry, "labels")
+
+    label_ids, warnings = resolve_label_ids(
+        label_entries,
+        request.label,
+    )
+
+    devices = {
+        str(device["id"]): device
+        for device in device_entries
+        if device.get("id")
+    }
+
+    areas: dict[str, str] = {}
+
+    for area in area_entries:
+        area_id = area.get("area_id") or area.get("id")
+
+        if not area_id:
+            continue
+
+        area_id = str(area_id)
+        areas[area_id] = str(area.get("name") or area_id)
+
+    selected: list[SelectedEntity] = []
+    domain_counts: dict[str, int] = {}
+
+    for entity in entity_entries:
+        entity_id = entity.get("entity_id")
+
+        if not isinstance(entity_id, str) or "." not in entity_id:
+            continue
+
+        domain, object_id = entity_id.split(".", 1)
+
+        if domain not in request.domains:
+            continue
+
+        if entity.get("disabled_by") or entity.get("hidden_by"):
+            continue
+
+        if entity.get("entity_category") in {"diagnostic", "config"}:
+            continue
+
+        entity_labels = set(entity.get("labels") or [])
+
+        if not entity_labels.intersection(label_ids):
+            continue
+
+        device_id = entity.get("device_id")
+        device = devices.get(str(device_id)) if device_id else None
+
+        name = (
+            entity.get("name")
+            or entity.get("original_name")
+            or object_id.replace("_", " ").title()
+        )
+
+        area_id = entity.get("area_id") or (device or {}).get("area_id")
+        room = areas.get(str(area_id)) if area_id else None
+
+        selected.append(
+            SelectedEntity(
+                entity_id=entity_id,
+                domain=domain,
+                name=str(name),
+                room=room,
+            )
+        )
+
+        domain_counts[domain] = domain_counts.get(domain, 0) + 1
+
+    selected.sort(
+        key=lambda item: (
+            item.room or "",
+            item.domain,
+            item.name,
+            item.entity_id,
+        )
+    )
+
+    if not selected:
+        warnings += (
+            "No entity matched the requested label and domains.",
+        )
+
+    return SelectionResult(
+        entities=tuple(selected),
+        domain_counts=domain_counts,
+        warnings=warnings,
+    )

hvls/models.py

@@ -0,0 +1,90 @@
+"""Internal data models used by the HVLS core engine."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SelectedEntity:
+    """Home Assistant entity selected for a voice assistant backend."""
+
+    entity_id: str
+    domain: str
+    name: str
+    room: str | None = None
+
+
+@dataclass(frozen=True)
+class GenerationRequest:
+    """Input parameters required to generate a backend configuration."""
+
+    label: str
+    domains: frozenset[str]
+    output_path: Path
+    dry_run: bool = False
+
+@dataclass(frozen=True)
+class SelectionResult:
+    """Structured result returned by the entity selection engine."""
+
+    entities: tuple[SelectedEntity, ...]
+    domain_counts: dict[str, int] = field(default_factory=dict)
+    warnings: tuple[str, ...] = ()
+
+    @property
+    def entity_count(self) -> int:
+        """Return the number of selected entities."""
+        return len(self.entities)
+
+    @property
+    def success(self) -> bool:
+        """Return whether at least one entity was selected."""
+        return self.entity_count > 0
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    """Structured result returned by the HVLS generation engine."""
+
+    content: str
+    entities: tuple[SelectedEntity, ...]
+    domain_counts: dict[str, int] = field(default_factory=dict)
+    warnings: tuple[str, ...] = ()
+
+    @property
+    def entity_count(self) -> int:
+        """Return the number of selected entities."""
+        return len(self.entities)
+
+    @property
+    def success(self) -> bool:
+        """Return whether generation produced at least one entity."""
+        return self.entity_count > 0
+
+@dataclass(frozen=True)
+class FileWriteResult:
+    """Structured result returned after writing generated configuration."""
+
+    output_path: Path
+    backup_path: Path | None
+    bytes_written: int
+    written_at: datetime
+
+@dataclass(frozen=True)
+class WorkflowResult:
+    """Structured result returned by an HVLS workflow execution."""
+
+    generation: GenerationResult
+    write_result: FileWriteResult | None
+    dry_run: bool
+
+    @property
+    def entity_count(self) -> int:
+        """Return the number of selected entities."""
+        return self.generation.entity_count
+
+    @property
+    def written(self) -> bool:
+        """Return whether generated content was written to disk."""
+        return self.write_result is not None

hvls/orchestrator.py

@@ -0,0 +1,92 @@
+"""Workflow orchestration for HA Voice Label Sync."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .backends import render_google_assistant
+from .engine import select_entities
+from .models import GenerationRequest, WorkflowResult
+from .registry import load_json
+from .writers import write_with_backup
+
+
+class WorkflowError(Exception):
+    """Raised when an HVLS workflow cannot be completed safely."""
+
+
+def run_google_assistant_workflow(
+    request: GenerationRequest,
+    storage_path: Path,
+    backup_directory: Path | None = None,
+    backup_retention: int = 5,
+) -> WorkflowResult:
+    """Run the complete Google Assistant generation workflow.
+
+    Args:
+        request: Generation parameters.
+        storage_path: Home Assistant ``.storage`` directory.
+        backup_directory: Optional directory used for backups.
+        backup_retention: Maximum number of backups to retain.
+
+    Returns:
+        Structured workflow result.
+
+    Raises:
+        WorkflowError: If writing is requested but no entity matches.
+    """
+    entity_registry = load_json(
+        storage_path / "core.entity_registry"
+    )
+    device_registry = load_json(
+        storage_path / "core.device_registry"
+    )
+    area_registry = load_json(
+        storage_path / "core.area_registry"
+    )
+    label_registry = load_json(
+        storage_path / "core.label_registry"
+    )
+
+    selection = select_entities(
+        request=request,
+        entity_registry=entity_registry,
+        device_registry=device_registry,
+        area_registry=area_registry,
+        label_registry=label_registry,
+    )
+
+    generation = render_google_assistant(selection)
+
+    if request.dry_run:
+        return WorkflowResult(
+            generation=generation,
+            write_result=None,
+            dry_run=True,
+        )
+
+    # Safety rule: an incorrect label must never silently replace an existing
+    # configuration with an empty generated file.
+    if generation.entity_count == 0:
+        raise WorkflowError(
+            "Generation returned no entity; output file was not modified."
+        )
+
+    resolved_backup_directory = (
+        backup_directory
+        if backup_directory is not None
+        else request.output_path.parent / ".hvls_backups"
+    )
+
+    write_result = write_with_backup(
+        output_path=request.output_path,
+        content=generation.content,
+        backup_directory=resolved_backup_directory,
+        retention=backup_retention,
+    )
+
+    return WorkflowResult(
+        generation=generation,
+        write_result=write_result,
+        dry_run=False,
+    )

hvls/registry.py

@@ -0,0 +1,91 @@
+"""Home Assistant registry reading utilities."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class RegistryError(Exception):
+    """Raised when a Home Assistant registry cannot be read."""
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    """Load and parse a Home Assistant JSON registry.
+
+    Args:
+        path: Path to the registry file.
+
+    Returns:
+        Parsed registry content.
+
+    Raises:
+        RegistryError: If the file is missing, unreadable or contains
+            invalid JSON.
+    """
+    if not path.exists():
+        raise RegistryError(f"Registry file not found: {path}")
+
+    if not path.is_file():
+        raise RegistryError(f"Registry path is not a file: {path}")
+
+    try:
+        with path.open("r", encoding="utf-8") as file:
+            data = json.load(file)
+    except json.JSONDecodeError as exc:
+        raise RegistryError(
+            f"Registry contains invalid JSON: {path} ({exc})"
+        ) from exc
+    except (OSError, UnicodeError) as exc:
+        raise RegistryError(
+            f"Unable to read registry: {path} ({exc})"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise RegistryError(
+            f"Registry root must be a JSON object: {path}"
+        )
+
+    return data
+
+
+def get_registry_items(
+    registry: dict[str, Any],
+    collection_name: str,
+) -> list[dict[str, Any]]:
+    """Return a named collection from a Home Assistant registry.
+
+    Home Assistant registry collections are normally stored under:
+
+        data -> collection_name
+
+    Args:
+        registry: Parsed Home Assistant registry.
+        collection_name: Name of the requested collection.
+
+    Returns:
+        Registry entries represented as dictionaries.
+
+    Raises:
+        RegistryError: If the collection exists but is not a list, or if
+            an entry is not a JSON object.
+    """
+    data = registry.get("data", {})
+
+    if not isinstance(data, dict):
+        raise RegistryError("Registry 'data' field must be an object")
+
+    items = data.get(collection_name, [])
+
+    if not isinstance(items, list):
+        raise RegistryError(
+            f"Registry collection '{collection_name}' must be a list"
+        )
+
+    if not all(isinstance(item, dict) for item in items):
+        raise RegistryError(
+            f"Registry collection '{collection_name}' contains invalid entries"
+        )
+
+    return items

hvls/writers/__init__.py

@@ -0,0 +1,17 @@
+"""Output writers provided by HVLS."""
+
+from .filesystem import (
+    FileWriterError,
+    apply_backup_retention,
+    atomic_write,
+    create_backup,
+    write_with_backup,
+)
+
+__all__ = [
+    "FileWriterError",
+    "apply_backup_retention",
+    "atomic_write",
+    "create_backup",
+    "write_with_backup",
+]

hvls/writers/filesystem.py

@@ -0,0 +1,183 @@
+"""Safe filesystem writer for generated HVLS configuration."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+from ..models import FileWriteResult
+
+
+class FileWriterError(Exception):
+    """Raised when generated configuration cannot be written safely."""
+
+
+def create_backup(
+    output_path: Path,
+    backup_directory: Path,
+) -> Path | None:
+    """Create a timestamped backup of an existing output file.
+
+    Args:
+        output_path: Generated configuration file to back up.
+        backup_directory: Directory where backups are stored.
+
+    Returns:
+        Path of the created backup, or ``None`` if the output file does
+        not exist yet.
+
+    Raises:
+        FileWriterError: If the backup cannot be created.
+    """
+    if not output_path.exists():
+        return None
+
+    if not output_path.is_file():
+        raise FileWriterError(
+            f"Output path is not a regular file: {output_path}"
+        )
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup_directory.mkdir(parents=True, exist_ok=True)
+
+    backup_path = backup_directory / (
+        f"{output_path.name}.{timestamp}.bak"
+    )
+
+    try:
+        shutil.copy2(output_path, backup_path)
+    except OSError as exc:
+        raise FileWriterError(
+            f"Unable to create backup {backup_path}: {exc}"
+        ) from exc
+
+    return backup_path
+
+
+def apply_backup_retention(
+    output_path: Path,
+    backup_directory: Path,
+    retention: int,
+) -> None:
+    """Keep only the newest backups for an output file.
+
+    A retention value of zero removes all matching backups.
+    """
+    if retention < 0:
+        raise ValueError("Backup retention cannot be negative")
+
+    if not backup_directory.exists():
+        return
+
+    pattern = f"{output_path.name}.*.bak"
+
+    try:
+        backups = sorted(
+            backup_directory.glob(pattern),
+            key=lambda path: path.stat().st_mtime,
+            reverse=True,
+        )
+
+        for backup in backups[retention:]:
+            backup.unlink()
+    except OSError as exc:
+        raise FileWriterError(
+            f"Unable to apply backup retention: {exc}"
+        ) from exc
+
+
+def atomic_write(
+    output_path: Path,
+    content: str,
+) -> int:
+    """Write text using a temporary file and atomic replacement.
+
+    The temporary file is created in the destination directory so that
+    the final ``os.replace`` operation remains atomic.
+
+    Args:
+        output_path: Destination file.
+        content: UTF-8 text to write.
+
+    Returns:
+        Number of UTF-8 bytes written.
+
+    Raises:
+        FileWriterError: If the destination cannot be written safely.
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    encoded_content = content.encode("utf-8")
+    temporary_path: Path | None = None
+
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=output_path.parent,
+            prefix=f".{output_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary_file:
+            temporary_path = Path(temporary_file.name)
+            temporary_file.write(encoded_content)
+            temporary_file.flush()
+            os.fsync(temporary_file.fileno())
+
+        os.replace(temporary_path, output_path)
+
+    except OSError as exc:
+        if temporary_path is not None:
+            try:
+                temporary_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+        raise FileWriterError(
+            f"Unable to write {output_path}: {exc}"
+        ) from exc
+
+    return len(encoded_content)
+
+
+def write_with_backup(
+    output_path: Path,
+    content: str,
+    backup_directory: Path,
+    retention: int = 5,
+) -> FileWriteResult:
+    """Back up the current file and atomically write new content.
+
+    Args:
+        output_path: Destination configuration file.
+        content: Generated configuration.
+        backup_directory: Backup storage directory.
+        retention: Maximum number of backups to retain.
+
+    Returns:
+        Structured information about the completed operation.
+    """
+    backup_path = create_backup(
+        output_path=output_path,
+        backup_directory=backup_directory,
+    )
+
+    bytes_written = atomic_write(
+        output_path=output_path,
+        content=content,
+    )
+
+    apply_backup_retention(
+        output_path=output_path,
+        backup_directory=backup_directory,
+        retention=retention,
+    )
+
+    return FileWriteResult(
+        output_path=output_path,
+        backup_path=backup_path,
+        bytes_written=bytes_written,
+        written_at=datetime.now(),
+    )