Enhance Bitcoin Simulation CLI UX and Report Formatting

.Jules/palette.md

@@ -1,3 +1,17 @@
-## 2024-05-23 - CLI UX Enhancement
-**Learning:** Even in CLI apps, visual distinction (colors, emojis) significantly reduces cognitive load when scanning logs.
-**Action:** Use ANSI colors and consistent emojis for key events (success/failure) in future CLI tools.
+# Palette's UX Learnings - Bitcoin Trading Simulation
+
+## CLI Delight
+- **Visual Structure:** Using box-drawing characters (`┏`, `┃`, `┗`, `━`) helps separate the final report from the scrolling logs, making it easier for users to find the most important information.
+- **Emoji Semantics:**
+  - `🟢` and `🔴` are excellent for quick status indication (Buy/Sell, Profit/Loss).
+  - `🛒` (Buy) and `🏷️` (Sell) add a touch of personality to trade statistics.
+  - `🚀` and `📉` provide immediate feedback on strategy performance relative to benchmarks.
+- **Color Contrast:** Using `CYAN` for values and `BOLD` for headers improves readability in dense CLI output.
+
+## Accessibility
+- **No-Color Mode:** Always respect the `--no-color` flag by providing a fallback that removes ANSI escape codes while maintaining structure through spacing and symbols.
+- **Quiet Mode:** `quiet` flags should suppress high-volume output (like daily ledgers) but can still show the final result, as long as it's clearly documented.
+
+## Code Quality for UX
+- **Consolidated Styling:** A single `Colors` class with a `disable()` method ensures consistent styling across the application and easier maintenance for future theme changes.
+- **Data Clarity:** Providing "Strategy Return %" alongside absolute values helps users quickly grasp the magnitude of their performance without doing mental math.

bitcoin.py

@@ -0,0 +1,17 @@
+import requests
+
+
+def calculate_value(amount, price):
+    """Calculates the USD value of a given amount of BTC."""
+    return amount * price
+
+
+def get_bitcoin_price():
+    """Fetches the current BTC price from an API."""
+    # Simplified implementation for testing purposes
+    response = requests.get("https://api.coindesk.com/v1/bpi/currentprice.json")
+    if response.status_code == 200:
+        data = response.json()
+        return data["bpi"]["USD"]["rate_float"]
+    else:
+        raise ConnectionError("Failed to fetch price")

bitcoin_trading_simulation.py

@@ -1,38 +1,36 @@
 import argparse
 import numpy as np
 import pandas as pd
-import argparse
 
 
 class Colors:
     HEADER = '\033[95m'
     BLUE = '\033[94m'
+    CYAN = '\033[96m'
     GREEN = '\033[92m'
+    YELLOW = '\033[93m'
     RED = '\033[91m'
+    FAIL = '\033[91m'
+    WARNING = '\033[93m'
     ENDC = '\033[0m'
     BOLD = '\033[1m'
+    UNDERLINE = '\033[4m'
 
     @classmethod
     def disable(cls):
         cls.HEADER = ''
         cls.BLUE = ''
+        cls.CYAN = ''
         cls.GREEN = ''
+        cls.YELLOW = ''
         cls.RED = ''
+        cls.FAIL = ''
+        cls.WARNING = ''
         cls.ENDC = ''
         cls.BOLD = ''
+        cls.UNDERLINE = ''
 
 
-class Colors:
-    HEADER = '\033[95m'
-    BLUE = '\033[94m'
-    CYAN = '\033[96m'
-    GREEN = '\033[92m'
-    WARNING = '\033[93m'
-    FAIL = '\033[91m'
-    ENDC = '\033[0m'
-    BOLD = '\033[1m'
-    UNDERLINE = '\033[4m'
-
 def simulate_bitcoin_prices(days=60, initial_price=50000, volatility=0.02):
     """
     Simulates Bitcoin prices for a given number of days using Geometric Brownian Motion.
@@ -87,9 +85,8 @@ def simulate_trading(signals, initial_cash=10000, quiet=False):
     portfolio['total_value'] = float(initial_cash)
 
     if not quiet:
-        print(f"{Colors.HEADER}{Colors.BOLD}------ Daily Trading Ledger ------{Colors.ENDC}")
+        print(f"\n{Colors.HEADER}{Colors.BOLD}------ Daily Trading Ledger ------{Colors.ENDC}")
 
-    print(f"\n{Colors.HEADER}{Colors.BOLD}------ Daily Trading Ledger ------{Colors.ENDC}")
     for i, row in signals.iterrows():
         if i > 0:
             portfolio.loc[i, 'cash'] = portfolio.loc[i-1, 'cash']
@@ -100,14 +97,19 @@ def simulate_trading(signals, initial_cash=10000, quiet=False):
             btc_to_buy = portfolio.loc[i, 'cash'] / row['price']
             portfolio.loc[i, 'btc'] += btc_to_buy
             portfolio.loc[i, 'cash'] -= btc_to_buy * row['price']
-            print(f"{Colors.GREEN}🟢 Day {i}: Buy {btc_to_buy:.4f} BTC at ${row['price']:.2f}{Colors.ENDC}")
+            if not quiet:
+                print(f"{Colors.GREEN}🟢 Day {i}: Buy {btc_to_buy:.4f} BTC at ${row['price']:.2f}{Colors.ENDC}")
 
         # Sell signal
         elif row['positions'] == -2.0:
             if portfolio.loc[i, 'btc'] > 0:
                 cash_received = portfolio.loc[i, 'btc'] * row['price']
                 portfolio.loc[i, 'cash'] += cash_received
-                print(f"{Colors.FAIL}🔴 Day {i}: Sell {portfolio.loc[i, 'btc']:.4f} BTC at ${row['price']:.2f}{Colors.ENDC}")
+                if not quiet:
+                    msg = (f"{Colors.FAIL}🔴 Day {i}: Sell "
+                           f"{portfolio.loc[i, 'btc']:.4f} BTC at "
+                           f"${row['price']:.2f}{Colors.ENDC}")
+                    print(msg)
                 portfolio.loc[i, 'btc'] = 0
 
         portfolio.loc[i, 'total_value'] = portfolio.loc[i, 'cash'] + portfolio.loc[i, 'btc'] * row['price']
@@ -150,16 +152,40 @@ def simulate_trading(signals, initial_cash=10000, quiet=False):
     initial_cash = args.initial_cash
     profit = final_value - initial_cash
 
+    # Calculate trade stats
+    btc_diff = portfolio['btc'].diff()
+    buys = (btc_diff > 0).sum()
+    sells = (btc_diff < 0).sum()
+    total_trades = buys + sells
+
     # Compare with buy and hold strategy
     buy_and_hold_btc = args.initial_cash / prices.iloc[0]
     buy_and_hold_value = buy_and_hold_btc * prices.iloc[-1]
-
-    print(f"\n{Colors.HEADER}{Colors.BOLD}------ Final Portfolio Performance ------{Colors.ENDC}")
-    print(f"Initial Cash: ${initial_cash:.2f}")
-    print(f"Final Portfolio Value: ${final_value:.2f}")
+
+    # Final Summary Report
+    print(f"\n{Colors.HEADER}{Colors.BOLD}┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓{Colors.ENDC}")
+    print(f"{Colors.HEADER}{Colors.BOLD}┃       FINAL SIMULATION PERFORMANCE REPORT      ┃{Colors.ENDC}")
+    print(f"{Colors.HEADER}{Colors.BOLD}┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛{Colors.ENDC}")
+
+    print(f"  • Initial Investment:    {Colors.CYAN}${initial_cash:,.2f}{Colors.ENDC}")
+    print(f"  • Final Portfolio Value:  {Colors.CYAN}${final_value:,.2f}{Colors.ENDC}")
+
     if profit >= 0:
-        print(f"{Colors.GREEN}💰 Profit/Loss: ${profit:.2f}{Colors.ENDC}")
+        print(f"  • Profit/Loss:           {Colors.GREEN}🟢 +${profit:,.2f}{Colors.ENDC}")
+    else:
+        print(f"  • Profit/Loss:           {Colors.FAIL}🔴 -${abs(profit):,.2f}{Colors.ENDC}")
+
+    print(f"  • Strategy Return:       {((final_value/initial_cash - 1) * 100):.2f}%")
+    print(f"  • Buy & Hold Return:     {((buy_and_hold_value/initial_cash - 1) * 100):.2f}%")
+
+    print(f"\n{Colors.BOLD}  --- Trade Statistics ---{Colors.ENDC}")
+    print(f"  • Total Trades:          {total_trades}")
+    print(f"  • Buys:                  {buys} 🛒")
+    print(f"  • Sells:                 {sells} 🏷️")
+
+    print(f"\n{Colors.HEADER}{Colors.BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{Colors.ENDC}")
+    if final_value > buy_and_hold_value:
+        print(f"{Colors.GREEN}{Colors.BOLD}  🚀 Strategy OUTPERFORMED Buy & Hold!{Colors.ENDC}")
     else:
-        print(f"{Colors.FAIL}📉 Profit/Loss: ${profit:.2f}{Colors.ENDC}")
-    print(f"Buy and Hold Strategy Value: ${buy_and_hold_value:.2f}")
-    print(f"{Colors.HEADER}-----------------------------------------{Colors.ENDC}")
+        print(f"{Colors.YELLOW}{Colors.BOLD}  📉 Buy & Hold was more effective this time.{Colors.ENDC}")
+    print(f"{Colors.HEADER}{Colors.BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{Colors.ENDC}")

requirements.txt

@@ -1,2 +1,3 @@
 numpy
 pandas
+requests

test_bitcoin.py

@@ -2,6 +2,7 @@
 from unittest.mock import patch
 from bitcoin import get_bitcoin_price, calculate_value
 
+
 # Test 1: Verify the calculation logic
 def test_calculate_value():
     """Ensure BTC to USD conversion math is correct."""
@@ -10,10 +11,12 @@ def test_calculate_value():
     expected = 125000.0
     assert calculate_value(amount, price) == expected
 
+
 # Test 2: Verify handling of zero amount
 def test_calculate_value_zero():
     assert calculate_value(0, 50000.0) == 0.0
 
+
 # Test 3: Mocking an API response
 @patch('bitcoin.requests.get')
 def test_get_bitcoin_price(mock_get):
@@ -23,10 +26,11 @@ def test_get_bitcoin_price(mock_get):
         "bpi": {"USD": {"rate_float": 62000.50}}
     }
     mock_get.return_value.status_code = 200
-    
+
     price = get_bitcoin_price()
     assert price == 62000.50
 
+
 # Test 4: Handling API failure
 @patch('bitcoin.requests.get')
 def test_get_price_api_error(mock_get):

test_bitcoin_trading.py

@@ -12,19 +12,29 @@ def reset_colors():
     original_colors = {
         'HEADER': Colors.HEADER,
         'BLUE': Colors.BLUE,
+        'CYAN': Colors.CYAN,
         'GREEN': Colors.GREEN,
+        'YELLOW': Colors.YELLOW,
         'RED': Colors.RED,
+        'FAIL': Colors.FAIL,
+        'WARNING': Colors.WARNING,
         'ENDC': Colors.ENDC,
         'BOLD': Colors.BOLD,
+        'UNDERLINE': Colors.UNDERLINE,
     }
     yield
     # Restore colors
     Colors.HEADER = original_colors['HEADER']
     Colors.BLUE = original_colors['BLUE']
+    Colors.CYAN = original_colors['CYAN']
     Colors.GREEN = original_colors['GREEN']
+    Colors.YELLOW = original_colors['YELLOW']
     Colors.RED = original_colors['RED']
+    Colors.FAIL = original_colors['FAIL']
+    Colors.WARNING = original_colors['WARNING']
     Colors.ENDC = original_colors['ENDC']
     Colors.BOLD = original_colors['BOLD']
+    Colors.UNDERLINE = original_colors['UNDERLINE']
 
 
 def test_simulate_trading_quiet_mode(capsys):
@@ -59,6 +69,8 @@ def test_colors_disable(reset_colors):
     assert Colors.HEADER == ""
     assert Colors.GREEN == ""
     assert Colors.RED == ""
+    assert Colors.FAIL == ""
+    assert Colors.CYAN == ""
 
 
 def test_simulation_integration():

test_simulation.py

@@ -1,7 +1,9 @@
-import pytest
 import pandas as pd
 import numpy as np
-from bitcoin_trading_simulation import simulate_bitcoin_prices, calculate_moving_averages, generate_trading_signals
+from bitcoin_trading_simulation import (
+    simulate_bitcoin_prices, calculate_moving_averages, generate_trading_signals
+)
+
 
 def test_simulate_bitcoin_prices():
     days = 10
@@ -10,13 +12,15 @@ def test_simulate_bitcoin_prices():
     assert isinstance(prices, pd.Series)
     assert prices.name == 'Price'
 
+
 def test_calculate_moving_averages():
     prices = pd.Series([100, 101, 102, 103, 104, 105, 106, 107, 108, 109], name='Price')
     signals = calculate_moving_averages(prices, short_window=3, long_window=5)
     assert 'short_mavg' in signals.columns
     assert 'long_mavg' in signals.columns
     assert not signals['short_mavg'].isnull().all()
 
+
 def test_generate_trading_signals():
     # Create dummy signals DataFrame
     data = {