sideline/docs/GRAPH_SYSTEM_SUMMARY.md

Graph-Based Pipeline System - Implementation Summary

Overview

Implemented a graph-based scripting language to replace the verbose XYZStage naming convention in Mainline's pipeline architecture. The new system represents pipelines as nodes and connections, providing a more intuitive way to define, configure, and orchestrate pipelines.

Files Created

Core Graph System

• engine/pipeline/graph.py - Core graph abstraction (Node, Connection, Graph classes)
• engine/pipeline/graph_adapter.py - Adapter to convert Graph to Pipeline with existing Stage classes
• engine/pipeline/graph_toml.py - TOML-based graph configuration loader

Tests

• tests/test_graph_pipeline.py - Comprehensive test suite (17 tests, all passing)
• examples/graph_dsl_demo.py - Demo script showing the new DSL
• examples/test_graph_integration.py - Integration test verifying pipeline execution
• examples/pipeline_graph.toml - Example TOML configuration file

Documentation

• docs/graph-dsl.md - Complete DSL documentation with examples
• docs/GRAPH_SYSTEM_SUMMARY.md - This summary document

Key Features

1. Graph Abstraction

• Node Types: source, camera, effect, position, display, render, overlay
• Connections: Directed edges between nodes with automatic dependency resolution
• Validation: Cycle detection and disconnected node warnings

2. DSL Syntax Options

TOML Configuration

[nodes.source]
type = "source"
source = "headlines"

[nodes.camera]
type = "camera"
mode = "scroll"

[nodes.noise]
type = "effect"
effect = "noise"
intensity = 0.5

[nodes.display]
type = "display"
backend = "terminal"

[connections]
list = ["source -> camera -> noise -> display"]

Python API

from engine.pipeline.graph import Graph, NodeType
from engine.pipeline.graph_adapter import graph_to_pipeline

graph = Graph()
graph.node("source", NodeType.SOURCE, source="headlines")
graph.node("camera", NodeType.CAMERA, mode="scroll")
graph.node("noise", NodeType.EFFECT, effect="noise", intensity=0.5)
graph.node("display", NodeType.DISPLAY, backend="terminal")
graph.chain("source", "camera", "noise", "display")

pipeline = graph_to_pipeline(graph)

Dictionary/JSON Input

from engine.pipeline.graph_adapter import dict_to_pipeline

data = {
    "nodes": {
        "source": "headlines",
        "noise": {"type": "effect", "effect": "noise", "intensity": 0.5},
        "display": {"type": "display", "backend": "terminal"}
    },
    "connections": ["source -> noise -> display"]
}

pipeline = dict_to_pipeline(data)

3. Pipeline Integration

The graph system integrates with the existing pipeline architecture:

• Auto-injection: Pipeline automatically injects required stages (camera_update, render, etc.)
• Capability Resolution: Uses existing capability-based dependency system
• Type Safety: Validates data flow between stages (TEXT_BUFFER, SOURCE_ITEMS, etc.)
• Backward Compatible: Works alongside existing preset system

4. Node Configuration

Node Type	Config Options	Example
source	source: "headlines", "poetry", "empty"	{"type": "source", "source": "headlines"}
camera	mode: "scroll", "feed", "horizontal", etc. speed: float	{"type": "camera", "mode": "scroll", "speed": 1.0}
effect	effect: effect name intensity: 0.0-1.0	{"type": "effect", "effect": "noise", "intensity": 0.5}
position	mode: "absolute", "relative", "mixed"	{"type": "position", "mode": "mixed"}
display	backend: "terminal", "null", "websocket"	{"type": "display", "backend": "terminal"}

Implementation Details

Graph Adapter Logic

1. Node Mapping: Converts graph nodes to appropriate Stage classes
2. Effect Intensity: Sets effect intensity globally (consistent with existing architecture)
3. Camera Creation: Maps mode strings to Camera factory methods
4. Dependencies: Effects automatically depend on render.output
5. Type Flow: Ensures TEXT_BUFFER flow between render and effects

Validation

• Disconnected Nodes: Warns about nodes without connections
• Cycle Detection: Detects circular dependencies using DFS
• Type Validation: Pipeline validates inlet/outlet type compatibility

Files Modified

Core Pipeline

• engine/pipeline/controller.py - Pipeline class (no changes needed, uses existing architecture)
• engine/pipeline/graph_adapter.py - Added effect intensity setting, fixed PositionStage creation
• engine/app/pipeline_runner.py - Added graph config support

Documentation

• AGENTS.md - Updated with task tracking

Test Results

17 tests passed in 0.23s
- Graph creation and manipulation
- Connection handling and validation
- TOML loading and parsing
- Pipeline conversion and execution
- Effect intensity configuration
- Camera mode mapping
- Positioning mode support

Usage Examples

Running with Graph Config

python -c "
from engine.effects.plugins import discover_plugins
from engine.pipeline.graph_toml import load_pipeline_from_toml

discover_plugins()
pipeline = load_pipeline_from_toml('examples/pipeline_graph.toml')
"

Integration with Pipeline Runner

# The pipeline runner now supports graph configs
# (Implementation in progress)

Benefits

1. Simplified Configuration: No need to manually create Stage instances
2. Visual Representation: Graph structure is easier to understand than class hierarchy
3. Automatic Dependency Resolution: Pipeline handles stage ordering automatically
4. Flexible Composition: Easy to add/remove/modify pipeline stages
5. Backward Compatible: Existing presets and stages continue to work

Future Enhancements

1. CLI Integration: Add --graph-config flag to mainline command
2. Visual Builder: Web-based drag-and-drop pipeline editor
3. Script Execution: Support for loops, conditionals, and timing in graph scripts
4. Parameter Binding: Real-time sensor-to-parameter bindings in graph config
5. Pipeline Inspection: Visual DAG representation with metrics