Provisioning: declarative device configuration for VideoIPath

[JonasScholl]

Adds videoipath_automation_tool.provisioning, a standalone declarative configuration layer over the VideoIPath SDK. Provisioning automates device configuration in an Infrastructure as Code style; blueprints are the reusable YAML templates used within that layer. Callers supply device facts, typed inputs, selected variants, and concrete external edges.

VideoIPathApp neither imports nor exposes the feature. Construct the engine explicitly:

from videoipath_automation_tool.provisioning import (
    ProvisioningDevice,
    ProvisioningEngine,
)

engine = ProvisioningEngine(app)
plan = engine.plan(
    ProvisioningDevice(
        key="device-a",
        label="device-a",
        management_address="192.0.2.10",
    ),
    "matrox-convertip.yml",
)
print(plan.summary())
result = plan.apply()

Changes

• Blueprint documents: strict, safe YAML loading, typed inputs, defaults and ordered variant overlays, driver/processor validation, and a generated JSON Schema. Blueprint remains the name of the template model.
• Plan and apply: ProvisioningPlan provides a read-only preview of managed-field changes. Apply rechecks captured baselines and runs inventory → inventory_readiness → topology_sync → discovery → topology → module_tags → verification. ProvisioningApplyError retains known IDs, successful operations, and phase outcomes; there is no automatic rollback.
• Staged readiness: wait up to 10 seconds for Inventory reachability, then start an independent 60-second budget for topology addition, synchronization, and required ports/vertices. require_reachable=False supports mock/static devices. Topology-changing Inventory updates stop with replan_required=True.
• Naming and processors: Text / Field / Join naming blocks, a per-engine ProcessorRegistry, and the built-in Matrox ConvertIP processor.
• External edges: ProvisioningDevice.edges and ProvisioningEdge describe instance-specific connections through reusable port mappings. Device, vertex, and edge changes share the Inspect transaction; missing peers remain deferred and require a new plan.
• SDK support: bulk Inventory address lookups for conflict checks and a typed missing-status error for single-attempt readiness polling. YAML parsing uses PyYAML.
• Documentation and examples: architecture notes and ADRs in docs/architecture/provisioning/, the 05_Provisioning.md getting-started chapter, examples in docs/examples/07_provisioning/, and updated repository guidance.

The Python package, engine, plan, device, app protocol, and feature error names use Provisioning. Template-specific names such as Blueprint and the blueprint schema retain their meaning. Migration guidance documents the renamed API and replacement of discovery_timeout with the two readiness options; old API names have no compatibility aliases.

Validation

• Offline coverage under tests/provisioning/ exercises loading, validation, inputs, variants, naming, processors, planning, apply, edges, staged readiness, and recovery with fake Inventory/Inspect state.
• Opt-in live-server workflows under tests/e2e/provisioning/ cover lifecycle, external edges, and recovery using mock devices. They are excluded from the default offline suite.
• CI tests pass on Python 3.11, 3.12, 3.13, and 3.14 for revision d4a3273.