Move scoring display to scoring tab

[hherb]

Move Scoring Display to Scoring Tab with Progressive Display

Summary

This PR moves scoring results from the Literature tab to a dedicated Scoring tab with progressive display. Documents now appear in the Scoring tab as they are scored, and citations appear in the Citations tab as they are extracted. Progress bars indicate progress for both operations.

Changes

UI Changes

• Literature tab: Now shows search results only (documents before scoring) - unchanged from search
• Scoring tab: Full implementation with:
  • Progress bar showing "Scoring document X/Y"
  • Documents displayed progressively as each is scored
  • Summary label showing "N documents scored | M highly relevant"
• Citations tab: Enhanced with:
  • Progress bar showing "Extracting citation X/Y"
  • Citations displayed progressively as each is extracted

Files Modified

File	Changes
tab_builders.py	Replaced Scoring tab placeholder with full implementation; added progress bar to Citations tab
workflow_thread.py	Added progressive display signals (document_scored, citation_progress, citation_extracted); added _extract_citations_progressive() method
workflow_handlers.py	Added handlers for progressive display signals; updated _on_scoring_progress to use Scoring tab
tab_updaters.py	Added add_single_scored_document() and add_single_citation() for progressive card additions
research_tab.py	Added scoring_refs attribute to store Scoring tab widget references

Technical Details

New Signals (WorkflowThread)

• document_scored(doc, score_result, current, total) - emitted per document during scoring
• citation_progress(current, total) - emitted during citation extraction for progress bar
• citation_extracted(citation, current, total) - emitted per citation as extracted

Progressive Display Flow

1. Scoring: For each document scored, emit document_scored → handler adds card to Scoring tab
2. Citation: For each document processed, emit citation_progress → update progress bar
3. Citation: For each citation extracted, emit citation_extracted → handler adds card to Citations tab

Golden Rules Compliance

• ✓ Rule 2 (No magic numbers): Uses executor.citation_extraction_threshold instead of hardcoded 0.7
• ✓ Rule 6 (Type hints): All parameters have type hints
• ✓ Rule 7 (Docstrings): All functions have docstrings
• ✓ Rule 8 (Error handling): All errors caught, logged, and handled gracefully
• ✓ Rule 9 (No inline stylesheets): Uses StyleSheets.progress_bar(ui)
• ✓ Rule 10 (No hardcoded pixels): Uses ui.* constants
• ✓ Rule 11 (Pure functions): Created reusable add_single_scored_document, add_single_citation

Test Plan

• Run research workflow and verify Scoring tab shows documents progressively
• Verify progress bar updates correctly during scoring
• Verify Literature tab shows unscored search results
• Verify Citations tab shows citations progressively with progress bar
• Verify summary labels update correctly at completion
• Test cancellation during scoring/citation extraction
• Verify no regressions in counterfactual analysis or final report

[claude]

Claude finished @hherb's task —— View job

---

PR Review: Move Scoring Display to Scoring Tab

I'm reviewing this pull request for code quality, potential issues, and best practices compliance.

Tasks

• Read repository guidelines (CLAUDE.md)
• Review modified files for code quality
• Check progressive display implementation
• Assess thread safety and signal handling
• Evaluate performance considerations
• Check for potential bugs and security issues
• Provide comprehensive feedback

Code Quality Assessment

Overall Assessment: ✅ EXCELLENT
This PR demonstrates excellent code quality with thoughtful architecture, proper error handling, and adherence to the project's golden rules.

Positive Aspects

🏗️ Architecture & Design

• Clean Separation of Concerns: Tab builders, updaters, handlers, and thread logic are properly separated
• Progressive Display: Well-implemented real-time UI updates as documents are processed
• Signal/Slot Architecture: Proper Qt signal handling with type-safe connections
• Factory Pattern Usage: Consistent document card creation via QtDocumentCardFactory

📏 Code Standards Compliance

• ✅ Golden Rule 2: Uses executor.citation_extraction_threshold instead of magic number 0.7
• ✅ Golden Rule 6: All parameters have proper type hints
• ✅ Golden Rule 7: Comprehensive docstrings throughout
• ✅ Golden Rule 8: Robust error handling with try/catch blocks and logging
• ✅ Golden Rule 9: Uses centralized StyleSheets.progress_bar(ui)
• ✅ Golden Rule 10: DPI-aware sizing with ui.* constants

🔧 Implementation Quality

• Type Safety: Proper type hints and validation (isinstance(s.get('score'), (int, float)))
• Error Resilience: Graceful handling of widget cleanup and signal disconnection
• Memory Management: Proper widget lifecycle with setParent(None) and deleteLater()
• Performance: Efficient incremental updates without full tab refreshes

Technical Analysis

📡 Signal Flow (tab_builders.py)

# Clean builder pattern with consistent structure
def build_scoring_tab(ui: UIConstants) -> tuple[QWidget, TabRefs]:
    # Proper progress bar setup with format strings
    progress_bar.setFormat("Scoring document %v/%m")  # ✅ User-friendly format

🔄 Progressive Display (tab_updaters.py)

def add_single_scored_document(...) -> Optional[QWidget]:
    # Intelligent layout management
    if index == 1:
        _remove_empty_label_and_stretch(layout, empty_label)  # ✅ Clean state transitions
    
    # Safe insertion before trailing stretch
    insert_pos = layout.count()
    if last_item and last_item.spacerItem():
        insert_pos = layout.count() - 1  # ✅ Preserves layout structure

🧵 Thread Safety (workflow_thread.py)

def _extract_citations_progressive(self, scored_documents, score_threshold):
    # Safe signal emission from worker thread
    self.citation_progress.emit(current, total)  # ✅ Thread-safe Qt signals

🎛️ Handler Coordination (workflow_handlers.py)

@Slot(object, object, int, int)
def _on_document_scored(self, doc: dict, score_result: dict, current: int, total: int):
    # Type-safe signal handling with proper error boundaries
    try:
        add_single_scored_document(...)  # ✅ Isolated error handling
    except Exception as e:
        self.logger.error(f"Error adding scored document card: {e}", exc_info=True)

Minor Suggestions

📊 Progress Bar Enhancement (tab_builders.py:282)

# Current: Basic format
progress_bar.setFormat("Scoring document %v/%m")

# Suggestion: Add percentage for better UX
progress_bar.setFormat("Scoring document %v/%m (%p%)")

🧹 Layout Cleanup Optimization (tab_updaters.py:45)

def clear_layout_widgets(layout: Union[QVBoxLayout, QHBoxLayout, QLayout]) -> None:
    # Current implementation is safe but could batch deletions
    # Consider: widgets_to_delete = [] + batch deleteLater() for better performance

🔍 Type Guard Enhancement (workflow_handlers.py:430)

# Current: Good validation
if isinstance(s.get('score'), (int, float)) and s.get('score', 0) >= threshold

# Suggestion: Extract to helper for reusability  
def is_high_scoring(score_result: dict, threshold: float) -> bool:
    score = score_result.get('score')
    return isinstance(score, (int, float)) and score >= threshold

Security & Performance

🔒 Security: ✅ No security concerns

• Safe signal/slot connections
• Proper input validation
• No SQL injection or XSS risks

⚡ Performance: ✅ Well optimized

• Incremental Updates: Cards added individually instead of full rebuilds
• Layout Efficiency: Smart insertion before trailing stretch items
• Memory Management: Proper Qt object lifecycle handling
• Thread Safety: Qt signals handle cross-thread communication safely

Test Coverage Suggestions

# Recommended unit tests for new functionality:
def test_progressive_scoring_display():
    """Test documents appear in Scoring tab as they're scored"""

def test_citation_progress_bar():
    """Test progress bar updates during citation extraction"""

def test_empty_state_transitions():
    """Test UI transitions from empty to populated states"""

def test_layout_cleanup():
    """Test proper widget cleanup in progressive display"""

Conclusion

This is a high-quality implementation that enhances user experience with progressive display while maintaining code excellence. The separation of concerns, error handling, and adherence to project standards are exemplary.

Recommendation: ✅ APPROVE

The implementation is production-ready and adds significant value to the user experience without introducing technical debt or security concerns.

---