Feature/flowchart

[hanan-nana]

Add Context Flowchart Feature

Overview

Added a context flowchart feature that visualizes conversation flow by analyzing chat sessions and generating directed acyclic graphs (DAGs) using Google AI (Gemini 2.5 Flash Lite).

Key Features

1. Flowchart Generation

• Automatic Generation: Flowcharts are generated automatically when analyzing sessions (pressing 'a' in TUI)
• Google AI Integration: Uses Gemini 2.5 Flash Lite to analyze conversation context and create meaningful work flow representations
• Smart Grouping: Groups related Q&A pairs into coherent work contexts rather than individual message pairs
• Token Optimization: Truncates message content to 200 characters to reduce API costs while maintaining context

2. CLI Commands

# Generate flowchart for a session
retrochat flowchart generate <session_id>

# View flowchart
retrochat flowchart show <session_id>

# Delete flowchart
retrochat flowchart delete <session_id>

3. TUI Integration

• Toggle View: Press 'f' key in session detail view to toggle flowchart display
• Side Panel: Flowchart renders in a dedicated side panel with Unicode box-drawing characters
• Proper Text Encapsulation: Boxes automatically adjust width to properly contain text content
• Background Generation: Flowchart generation runs in background without blocking UI

4. Data Model

• Flowchart: Main entity with nodes, edges, and metadata
• FlowchartNode: Represents work contexts with message references
• FlowchartEdge: Defines relationships (sequential, branch, merge, loop)
• DAG Validation: Prevents cycles while allowing loops for conversation flow

5. Database Schema

CREATE TABLE flowcharts (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    nodes TEXT NOT NULL, -- JSON array
    edges TEXT NOT NULL, -- JSON array
    created_at TEXT NOT NULL DEFAULT (datetime('now', 'utc')),
    token_usage INTEGER,
    FOREIGN KEY (session_id) REFERENCES chat_sessions(id) ON DELETE CASCADE
);

Technical Implementation

Architecture

• Service Layer: FlowchartService handles Google AI integration and business logic
• Repository Layer: FlowchartRepository manages database operations
• UI Layer: FlowchartRenderer handles TUI visualization
• Event System: Integrated with existing TUI event handling

Key Components

• src/models/flowchart.rs - Data structures and DAG validation
• src/services/flowchart_service.rs - Google AI integration and prompt engineering
• src/tui/flowchart_renderer.rs - Unicode-based flowchart rendering
• src/cli/flowchart.rs - CLI command implementation
• migrations/008_add_flowcharts.sql - Database schema

Prompt Engineering

• Optimized prompts to generate 8-15 meaningful work contexts
• Emphasizes grouping related messages into single nodes
• Enforces strict JSON output format with proper field validation
• Focuses on work phases rather than individual Q&A pairs

Configuration

• Environment Variable: Requires GOOGLE_AI_API_KEY to be set
• Model: Uses gemini-2.5-flash-lite for cost-effective analysis
• Token Limits: Optimized to use ~22k tokens for 700+ message sessions

Usage Examples

CLI Usage

# Generate flowchart for a session
cargo run -- flowchart generate 37ea10c0-e95d-418d-af6d-28532f5d9387

# View the generated flowchart
cargo run -- flowchart show 37ea10c0-e95d-418d-af6d-28532f5d9387

TUI Usage

1. Navigate to session detail view
2. Press 'a' to analyze session (generates flowchart in background)
3. Press 'f' to toggle flowchart view
4. Flowchart displays in side panel with work context visualization

Benefits

• Visual Context Understanding: Quickly understand conversation flow and work contexts
• Efficient Analysis: Reduces complex conversations to 8-15 meaningful work phases
• Cost Effective: Optimized token usage with smart content truncation
• Integrated Experience: Seamlessly integrated with existing TUI and CLI workflows