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_a = app.inspect.get_device("device-a")
device_b = app.inspect.get_device("device-b")

vertex_in = device_a.find_vertex_by_factory_label("port-in-1", vertex_type="In")
vertex_out = device_b.find_vertex_by_factory_label("port-out-1", vertex_type="Out")

for port in device_a.ports:
    print(port.label, port.edges)

# Setters stage edits locally; update() flushes them (auto-commit)
device_a.description = "Rack A leaf"
vertex_out.use_as_endpoint = True
app.inspect.update([device_a, vertex_out])

# Direct helpers for placement / edges
app.inspect.place_device(device_a.id, x=100, y=200)
app.inspect.connect(vertex_in.id, vertex_out.id, bidirectional=True)

# Batch setter edits + graph ops in one atomic transaction
with app.inspect.transaction() as tx:
    device_b.description = "Rack B spine"
    tx.update(device_b)  # stage setter edits into tx

    tx.place_device(device_b.id, x=400, y=200)
    tx.connect(vertex_in.id, vertex_out.id, 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 compare-and-commit conflict detection
  • Domain views: InspectDevice, InspectModule, InspectPort, InspectVertex, 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/): Developer-run locally only against a real instance; focused app suites under apps/ (including Inspect) and ordered cross-app workflows under workflows/. Artifacts are E2E- namespaced and cleaned by a session-start sweep
• 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/03_B_Inspect.md
• Architecture record: docs/architecture/inspect-app/ (concepts, models, endpoints, 10 ADRs)
• Future direction: docs/architecture/future/unified-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

[JonasScholl]

I have finished all my tasks and incorporated the feedback. From my end, it is ready to be merged.

[PaulWinterstein]

@JonasScholl
LGTM! Great work, Jonas. Thank you for the thorough implementation and documentation.