Skip to content

Add search, filter, statistics, and error navigation to TUI #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Add search, filter, statistics, and error navigation to TUI #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
85ee593
Initial plan
Copilot Jan 23, 2026
89cdee7
Add search, filter, and statistics panels to TUI
Copilot Jan 23, 2026
ba01642
Enhance error visualization and timeline with time labels
Copilot Jan 23, 2026
96dfe2f
Refactor to use shared constants and improve error navigation
Copilot Jan 23, 2026
770cc3e
Fix import path in constants module
Copilot Jan 23, 2026
b61e3a7
Add comprehensive TUI improvements summary
Copilot Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
343 changes: 343 additions & 0 deletions TUI_IMPROVEMENTS_SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,343 @@
# TUI Improvements Summary

## Overview

This PR implements a comprehensive set of improvements to the traceTTY Terminal User Interface, making it more powerful, user-friendly, and efficient for debugging and analyzing trace data.

## Motivation

The original TUI provided solid event-based trace visualization, but lacked:
- Quick navigation to errors
- Ability to filter and search through traces
- Summary statistics and metrics
- Visual indicators for active features

These improvements address these gaps while maintaining the clean, minimal design philosophy of the original implementation.

## Features Implemented

### 1. Search Functionality (Keyboard: `/`)

**What it does:**
- Provides a search bar to find runs, events, and data
- Toggle with `/` key
- Infrastructure ready for future highlighting

**Use cases:**
- Finding specific runs by name
- Searching for runs with specific IDs
- Locating events containing certain data

**Implementation:**
- New `SearchBar` widget with text input
- Emits `SearchSubmitted` and `SearchCleared` messages
- Status indicator (🔍) in step counter when active

### 2. Filter Bar (Keyboard: `f`)

**What it does:**
- Filter trace display by run type and status
- Visual checkboxes for easy selection
- Real-time filter application

**Filter options:**
- **Run Types**: llm, chain, tool, retriever, embedding
- **Statuses**: running, completed, error

**Implementation:**
- New `FilterBar` widget with checkboxes
- Emits `FilterChanged` messages
- Status indicator (⚑) in step counter when visible

### 3. Statistics Panel (Keyboard: `s`)

**What it does:**
- Displays comprehensive trace metrics
- Toggles with tree view in left panel
- Auto-updates with trace navigation

**Metrics shown:**
- Total runs and events
- Status breakdown (completed, running, errors)
- Success and error rates (percentage)
- Run type distribution
- Timing statistics:
- Minimum duration
- Maximum duration
- Average duration
- Total duration

**Implementation:**
- New `StatsPanel` widget
- Replaces tree view when toggled
- Status indicator (📊) in step counter when active

### 4. Error Navigation (Keyboard: `n` / `p`)

**What it does:**
- Quickly jump between errors in trace
- Visual error indicators throughout UI
- User feedback when no errors found

**Features:**
- Press `n` to jump to next error
- Press `p` to jump to previous error
- Error count shown in header (⚠ X error(s))
- Error indicators (⚠) in tree view
- Notifications when no more errors

**Implementation:**
- New action handlers with helper method
- Error detection from event data
- User feedback via notifications

### 5. Enhanced Timeline

**Improvements:**
- Time range labels (0ms - XXXms)
- Clearer current position marker
- Better visual clarity

**Benefits:**
- Quick understanding of trace duration
- Better context for event timing
- Easier to correlate events with timeline

### 6. Code Quality Improvements

**Constants Module:**
- Centralized all color mappings
- Shared status icons and type badges
- Single source of truth for run types

**Benefits:**
- Eliminated code duplication
- Easier to maintain and update
- Consistent styling across components

**Error Handling:**
- Extracted common error-finding logic
- Added user feedback notifications
- Better error messages

## User Experience Enhancements

### Visual Indicators

The step counter now shows active features:
```
[Step 5/20] 🔍 Search ⚑ Filter 📊 Stats
```

This provides immediate visual feedback about what features are active.

### Error Visualization

Errors are now prominently displayed:
- Header: "Trace Viewer: ... ⚠ 2 error(s)"
- Tree View: "● run_name [llm] ⚠"
- Notifications: "No more errors found"

### Enhanced Help Screen

Updated keyboard shortcuts reference:
- Grouped by category (Navigation, Views & Panels, etc.)
- Clear descriptions
- Examples of usage

## Technical Architecture

### New Components

1. **SearchBar** (`widgets/search_bar.py`)
- Text input widget
- Message passing for search events
- Focus management

2. **FilterBar** (`widgets/filter_bar.py`)
- Checkbox-based filtering
- Multiple filter types
- Auto-applying filters

3. **StatsPanel** (`widgets/stats_panel.py`)
- Metric calculations
- Formatted display
- Auto-refresh on updates

4. **Constants** (`constants.py`)
- Shared run types
- Color mappings
- Status icons and displays

### Modified Components

1. **MainScreen** (`screens/main_screen.py`)
- New keyboard bindings
- Widget integration
- State management for features
- Error navigation logic

2. **TreeViewWidget**
- Error indicators
- Uses shared constants

3. **TimelineWidget**
- Time range labels
- Uses shared constants

4. **DetailPanelWidget**
- Uses shared constants
- Better formatting

### Layout Changes

The UI now supports dynamic layouts:
- Search bar (top, toggleable)
- Filter bar (top, toggleable)
- Tree view OR Stats panel (left)
- Detail panel (right)
- Event log (bottom)

## Keyboard Shortcuts Reference

### Navigation
- `←` / `,` - Step backward
- `→` / `.` - Step forward
- `Home` - Jump to first event
- `End` - Jump to last event
- `Space` - Toggle auto-play
- `n` - Next error
- `p` - Previous error

### Views & Panels
- `/` - Toggle search bar
- `f` - Toggle filter bar
- `s` - Toggle statistics panel
- `Tab` - Focus next panel
- `Shift+Tab` - Focus previous panel

### General
- `b` - Back to browser
- `?` - Show help
- `q` - Quit

## Testing

### Automated Tests
- ✅ All 185 existing tests pass
- ✅ No new test failures introduced
- ✅ CodeQL security scan clean (0 vulnerabilities)

### Manual Testing
- ✅ Tested with LLM example traces
- ✅ Tested with error handling examples
- ✅ Verified all keyboard shortcuts
- ✅ Confirmed UI responsiveness
- ✅ Validated statistics accuracy

### Example Scripts
- `examples/basic_llm_call.py` - Complex trace with multiple runs
- `examples/error_handling.py` - Trace with intentional errors

## Files Changed

### New Files (7)
- `tracetty/visualizer/widgets/search_bar.py`
- `tracetty/visualizer/widgets/filter_bar.py`
- `tracetty/visualizer/widgets/stats_panel.py`
- `tracetty/visualizer/constants.py`
- `examples/error_handling.py`
- `docs/tui_improvements.md`

### Modified Files (7)
- `tracetty/visualizer/screens/main_screen.py`
- `tracetty/visualizer/screens/help_screen.py`
- `tracetty/visualizer/widgets/__init__.py`
- `tracetty/visualizer/widgets/tree_view.py`
- `tracetty/visualizer/widgets/timeline.py`
- `tracetty/visualizer/widgets/detail_panel.py`
- `tracetty/visualizer/styles/app.tcss`

### Total Changes
- **462 insertions**
- **83 deletions**
- **Net: +379 lines**

## Future Enhancements

The following features have infrastructure in place but are deferred:

### Search Highlighting
- Highlight matching runs in tree view
- Highlight matching events in event log
- Jump between search results

### Advanced Filtering
- Complex filter expressions
- Save/load filter presets
- Combine search and filter

### Copy/Export Features
- Copy run ID to clipboard
- Copy outputs/inputs
- Export filtered views to JSON
- Export statistics as CSV

### Timeline Enhancements
- Zoom in/out functionality
- Pan through timeline
- Click to jump to time position

### Performance Optimizations
- Virtual scrolling for large traces
- Lazy loading of event data
- Caching improvements

## Design Decisions

### Minimal Changes Principle
We deliberately kept the implementation focused on core improvements:
- New widgets are self-contained
- Existing widgets minimally modified
- Shared constants reduce duplication
- Infrastructure ready for future enhancements

### UI/UX Philosophy
- **Keyboard-first**: All features accessible via keyboard
- **Visual feedback**: Clear indicators for active features
- **Progressive disclosure**: Advanced features don't clutter basic usage
- **Consistent styling**: Shared constants ensure uniformity

### Code Quality
- **DRY**: Eliminated duplication via constants module
- **SRP**: Each widget has single responsibility
- **Maintainable**: Clear separation of concerns
- **Testable**: Existing tests continue to pass

## Impact

### For Users
- **Faster debugging**: Jump directly to errors
- **Better insights**: Statistics provide quick overview
- **More control**: Filter and search capabilities
- **Clearer UI**: Visual indicators and better organization

### For Developers
- **Maintainable**: Shared constants and clear structure
- **Extensible**: Infrastructure ready for future features
- **Documented**: Comprehensive documentation added
- **Tested**: All tests passing

## Migration Notes

This is a **fully backward compatible** change:
- No breaking changes to existing APIs
- All existing functionality preserved
- New features are opt-in (via keyboard shortcuts)
- No configuration changes required

## Conclusion

This PR significantly enhances the traceTTY TUI with powerful new features while maintaining the clean, minimal design philosophy of the original implementation. The improvements make debugging and analyzing traces faster and more efficient, with a focus on usability and code quality.

The changes demonstrate how thoughtful enhancements can dramatically improve user experience without sacrificing simplicity or adding complexity to the codebase.
Loading