Inspect App

[JonasScholl]

This PR adds app.inspect, a new read/write interface to VideoIPath's Inspect surface (verified against 2025.4+). It is purely additive, app.topology and app.inventory are unchanged.

Inspect lets you:

• Read the live topology (devices, ports, edges, services) via a lazy, skeleton-first internal view
• Write topology changes through a commit-style model (single-shot helpers or batched transactions)
• Onboard devices into the topology (add_devices_to_topology, sync_devices, get_sync_info)

# Read (skeleton loads fast; ports hydrate on first access)
device = app.inspect.get_device("device-a")
for port in device.ports:
    print(port.label, port.edge)

# Write (auto-commit)
app.inspect.place_device("device-a", x=100, y=200)
app.inspect.connect("device-a.1.port-out-1", "device-b.0.port-in-1", bidirectional=True)

# Batched, atomic write
with app.inspect.transaction() as tx:
    tx.place_device("device-a", x=100, y=200)
    tx.connect(a_out, b_in, bidirectional=True)
    tx.commit()

Key design choices

Topic	Approach
Loading	Skeleton-first snapshot; per-device detail hydrates on demand (ADR-0007)
API surface	Collector endpoints only: no legacy nGraphElements / edgesByDevice (ADR-0008)
Writes	Staged change sets committed atomically (ADR-0006)
Concurrency	Compare-and-commit conflict detection before POST; rebase() to retry (ADR-0009)
Post-commit state	Targeted refresh of touched entities only (ADR-0010)

The snapshot is an internal implementation detail. Users interact only through app.inspect, not a snapshot object.

What's included

Application code

• New package: src/videoipath_automation_tool/apps/inspect/
  • InspectApp (read / write / actions mixins)
  • InspectAPI + typed Pydantic models
  • InspectSnapshot with lazy hydration and in-memory indexes
  • InspectTransaction with conflict detection (deepdiff)
  • Domain views: InspectDevice, InspectPort, InspectEdge, InspectService
• Wired into VideoIPathApp as a lazy app.inspect property (also exposed as _inspect_api in DEV mode)

Tests

• Unit tests (tests/inspect/): Offline, fixture-driven coverage for snapshot loading, queries, transactions, conflict handling, and API parsing (anonymized 2025.4.9 fixtures)
• E2E tests (tests/e2e/inspect/): Developer-run locally only against a real instance; each test builds and tears down its own mini-topology
• New Poetry scripts: poetry run test-unit, poetry run test-e2e, poetry run test
• CI now runs test-unit (e2e excluded by default via pytest marker)

Documentation

• User guide: docs/getting-started-guide/05_Inspect.md
• Architecture record: docs/inspect-app/ (concepts, models, endpoints, 10 ADRs, implementation plan)
• Future direction: docs/future/domain-architecture.md

Tooling / housekeeping

• .env.template replaces .env.example (e2e connection vars documented there)
• AGENTS.md and path-scoped Python agent rules (.claude/rules/, .cursor/rules/ symlinks)
• Minor REST connector tweak for Inspect collector calls

[PaulWinterstein]

description should be included here as well

[PaulWinterstein]

Is there a way to expose the possible icon types via IntelliSense? That would improve the developer experience.

[PaulWinterstein]

The app layer currently exposes too little information about ports. We need access to the full port/vertex data from Inspect, including the vertex kind and direction (Generic bidirectional, IP bidirectional, IP input, IP output, Codec/Video input, Codec/Video output), as well as the corresponding properties shown in the UI.

sWe also need a way to retrieve the original factory label, even if a manual label override has been set.

[PaulWinterstein]

Adding filter helpers for ports/vertices could improve the developer experience. Examples could be filtering vertices by slot/module, type, or properties such as Active, use_as_endpoint or control_level = Full.