# Portfolio Assistant Demo - Chart Additions Plan

## Overview

This document outlines the planned additions of charts to the Portfolio Assistant demo to make it more visually compelling and useful. These additions will be implemented after the necessary DTOs and chart type support are added to the codebase.

## Planned Chart Additions

### 1. Line Chart - Portfolio Performance Over Time

**Location:** After portfolio strategy description, before "Current Portfolio Exposures" section

**Purpose:** 
- Provide historical context for the portfolio
- Show performance trends over time
- Help users understand why rebalancing might be needed

**Data to Display:**
- X-axis: Time periods (e.g., monthly or quarterly over 1-3 years)
- Y-axis: Portfolio value or cumulative return (%)
- Series: Portfolio performance, optionally with benchmark comparison

**Example Flow:**
```
Portfolio Strategy Description
  ↓
[Line Chart: Portfolio Performance Over Time] ← NEW
  ↓
Current Portfolio Exposures (table)
```

**Implementation Requirements:**
- Add `line_chart` block type support
- Create `LineChartData` DTO with:
  - `x_categories`: list of time periods
  - `y_values`: list of series (each series is a list of values)
  - `x_label`: string (e.g., "Time")
  - `y_label`: string (e.g., "Portfolio Value")
  - Optional: `series_labels` for multiple series

---

### 2. Slider-Adjustable Side-by-Side Bar Chart - Risk/Allocation Relationship

**Location:** During risk adjustment flow, after the risk slider is displayed

**Purpose:**
- Visualize how portfolio allocation changes with different risk levels
- Show current allocation vs. target allocation at selected risk level
- Provide real-time feedback as user adjusts risk slider

**Data to Display:**
- X-axis: Asset classes/sectors (Bonds, Equities, Cash, etc.)
- Two series: 
  - "Current Allocation" (static)
  - "Target at Risk X" (updates based on slider value)
- Y-axis: Allocation percentage (0-100%)

**Example Flow:**
```
Risk Adjustment Prompt
  ↓
[Risk Slider: 1-10] ← Existing
  ↓
[Side-by-Side Bar Chart: Current vs Target Allocation] ← NEW (updates with slider)
  ↓
"Updating risk level..." action
```

**Implementation Requirements:**
- Extend `BarChartData` DTO to support:
  - Slider binding/relationship
  - Dynamic updates based on external state (slider value)
  - Mechanism to link chart data to slider value
  
**Design Considerations:**
- How should the chart receive slider updates? (event-driven, reactive, etc.)
- Should the chart be a single block that updates, or multiple blocks?
- How do we structure the data to support multiple risk levels?
  - Option A: Pre-compute all risk levels, chart selects based on slider
  - Option B: Chart receives slider value and computes target allocation
  - Option C: Chart is updated via separate events as slider changes

**Proposed Data Structure:**
```json
{
  "block_type": "bar_chart",
  "data": {
    "x_categories": ["Bonds", "Equities", "Cash"],
    "y_values": [
      [30, 65, 5],   // Current allocation (static)
      [30, 65, 5]    // Target allocation (updates with slider)
    ],
    "colour_categories": ["Current", "Target at Risk 7"],
    "x_label": "Asset Class",
    "y_label": "Allocation %",
    "slider_binding": {
      "slider_block_id": "risk-level",
      "value_mapping": {
        "1": [[60, 30, 10]],
        "2": [[55, 35, 10]],
        // ... mappings for each risk level
        "10": [[10, 85, 5]]
      }
    }
  }
}
```

---

## Implementation Order

### Phase 1: Line Chart Support
1. Add `line_chart` to block type Literal in `Event` model
2. Create `LineChartData` DTO in `block_data.py`
3. Implement `line_chart` block factory in `blocks/line_chart.py`
4. Add tests in `test_blocks.py`
5. Add line chart to demo JSON

### Phase 2: Slider-Adjustable Bar Chart Support
1. Design DTO structure for slider-binding (see considerations above)
2. Extend `BarChartData` or create new variant
3. Implement update mechanism (event-driven vs reactive)
4. Add tests for slider-bound charts
5. Add slider-adjustable bar chart to demo JSON

### Phase 3: Demo Integration
1. Add line chart after portfolio strategy descriptions (all three portfolio flows)
2. Add slider-adjustable bar chart in risk adjustment flows (all three risk adjustment branches)
3. Ensure chart data aligns with existing table data for consistency
4. Test full demo flow

---

## Data Consistency Notes

- Line chart data should be consistent with portfolio performance mentioned in strategy descriptions
- Bar chart allocation data should align with:
  - Current exposures tables
  - Rebalancing strategy tables
  - Risk level descriptions (e.g., Risk 7 = Moderate-High)

---

## Open Questions

1. **Line Chart:**
   - Should we show multiple series (portfolio vs benchmark)?
   - What time period is most useful? (1Y, 3Y, 5Y?)
   - Should we show absolute values or percentage returns?

2. **Slider-Adjustable Bar Chart:**
   - Should updates be immediate (as slider moves) or on slider release?
   - How do we handle the initial state before slider interaction?
   - Should we show a third series for "Change" (target - current)?

3. **General:**
   - Should charts replace tables or complement them?
   - Do we need chart titles/captions in the DTOs?

---

## References

- Current demo: `portfolio_assistant_stream.json`
- Bar chart implementation: `src/yera/chat/blocks/bar_chart.py`
- Block data models: `src/yera/chat/models/block_data.py`
- Event model: `src/yera/chat/models/event.py`

