# Sentiment Engine TUI

Textual-based Terminal User Interface for live monitoring of the Sentiment Analysis Engine.

## Features

### 📡 Live Info Fetches
Real-time stream of all incoming payloads from all sources:
- Timestamp, source ID, source type
- Extracted assets mentioned
- Title/preview of content
- Source credibility score
- Content length

### 📊 Live Parameters (Per Asset)
Per-asset sentiment parameters updating in real-time:
- **Fear State** (0-100) — color coded (red>70, yellow>40, green<40)
- **Greed State** (0-100) — color coded (green>70, yellow>40, red<40)
- **Sentiment Polarity** (-100 to +100)
- **Pump Score** (0-100) — entry veto threshold at 75
- **Dump Score** (0-100) — exit trigger at 70
- **Hype Velocity** — sentiment acceleration rate
- **Publication Velocity** — source frequency
- **Event Flags** — top 3 events with strength
- **Decay Factor** — temporal decay applied
- **Contributing Sources** — multi-source fusion count

Sorted by pump_score descending for quick risk identification.

### 🌍 Aggregate Parameters
Market-wide and industry-level aggregates:
- **Market Fear/Greed/Polarity/Hype/Pub Velocity**
- **Aggregate Pump/Dump Risk** — with color coding
- **Top 5 Pump/Dump Assets**
- **Dominant Events** — with strength and confidence
- **Industry Breakdown** — per-industry fear, greed, polarity, pump/dump risk, asset count

### ☁️ Word Cloud
Visual word frequency from recent payloads:
- Top 60 words sized by frequency
- Color-coded by frequency tier (bright_white/blue > yellow > green > cyan > dim)
- Asset mentions weighted 3x
- Stopwords filtered
- Updates every second from last 100 payloads

### 🔌 Source Connector Status
Live status of all 8 connector types:
- Running/Error/Unknown status with color coding
- Fetch counts (total, successful, errors)
- Last fetch timestamp
- Base credibility score

### 🎯 Live Event Feed
Real-time event detections:
- Timestamp, asset, event type
- Strength (0-100) with color coding
- Confidence percentage
- Source count
- Sorted by strength descending

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `q` | Quit |
| `p` | Pause/resume updates |
| `r` | Force refresh |
| `f` | Focus Info Fetches |
| `a` | Focus Asset Parameters |
| `m` | Focus Market Aggregate |
| `w` | Focus Word Cloud |
| `s` | Focus Source Status |
| `e` | Focus Event Feed |

## Running

```bash
# From sentiment_engine directory
pip install -e ".[tui]"

# Run TUI only
python scripts/run_tui.py

# Run engine + TUI together
python scripts/run_engine.py --tui

# Run engine only (headless)
python scripts/run_engine.py --engine-only
```

## Architecture

The TUI runs as a separate `asyncio` task alongside the main engine. It receives data via direct method calls:

```python
# From ingestion pipeline
tui_app.add_fetch(payload)

# From scoring engine
tui_app.update_assets(asset_signals)
tui_app.update_market(market, industries)

# From connector registry
tui_app.update_source_status(name, stats)
```

The TUI uses `textual` (v0.52+) with `rich` for rendering. All widgets are reactive and update at 1Hz via a timer.

## Integration with Engine

In `main.py`, the `SentimentEngine` can optionally start the TUI:

```python
engine = SentimentEngine()
await engine.initialize()
await engine.start()

# TUI runs in same process, shares event loop
tui_task = asyncio.create_task(run_tui())
await tui_task
```

For production deployment, run TUI in a separate terminal/screen session while the engine runs as a systemd service.