ADR-007: Pipeline Introspection

Status: ✅ Done

Date: 2026-03-17

Author: David G

Related Issues: #22, #20

Context

During development of the Stage-based pipeline architecture, there was no way to visualize:

The structure of the pipeline (which stages are connected)
Signal flow between stages
Real-time performance metrics (execution times, frame rates)

This made debugging and development of the pipeline system difficult.

Decision

Implement a PipelineIntrospectionSource DataSource that introspects Pipeline instances and renders ASCII visualization:

DAG visualization: ASCII diagram showing stages and their connections
Signal flow: Shows data moving between stages
Execution times: Per-stage timing information
Frame history: Sparkline of recent frame times
Stage breakdown: Bar chart of time spent in each stage

Implementation

Location: engine/data_sources/pipeline_introspection.py

from engine.data_sources.pipeline_introspection import PipelineIntrospectionSource

# Usage
source = PipelineIntrospectionSource(pipeline=my_pipeline)
items = source.fetch()  # Returns ASCII visualization lines

The source can be used like any other DataSource in the pipeline, enabling debug views to be displayed alongside normal content.

Alternatives Considered

Separate debug UI: Would require additional rendering logic
Logging-based metrics: Less visual, harder to interpret
External tooling: Would require separate tool, not integrated

Consequences

Positive: Developers can visualize pipeline structure at runtime
Positive: Performance issues are easier to identify
Positive: Can be used as a DataSource like any other
Negative: Adds small overhead when enabled (negligible)

References

engine/data_sources/pipeline_introspection.py
engine/data_sources/sources.py (base DataSource class)
Pipeline Introspection Demo: engine/pipeline/pipeline_introspection_demo.py