# ANNOTATE - Manual Trade Annotation UI

## 🎯 Overview

A professional web-based interface for manually marking profitable buy/sell signals on historical market data to generate high-quality training test cases for machine learning models.

**Status**:  **Production Ready** - Core features complete and tested

## ✨ Key Features

### 📊 Multi-Timeframe Visualization
- **4 synchronized charts**: 1s, 1m, 1h, 1d timeframes
- **Candlestick + Volume**: Professional trading view
- **Interactive navigation**: Zoom, pan, scroll
- **Hover details**: OHLCV information on hover

### 🎯 Trade Annotation
- **Click to mark**: Entry point (▲) and exit point (▼)
- **Visual feedback**: Color-coded markers (green=LONG, red=SHORT)
- **P&L calculation**: Automatic profit/loss percentage
- **Connecting lines**: Dashed lines between entry/exit
- **Edit/Delete**: Modify or remove annotations

### 📦 Test Case Generation
- **Realtime format**: Identical to training test cases
- **Market context**: Full OHLCV data for all timeframes
- **Data consistency**: Uses same DataProvider as training/inference
- **Auto-save**: Test cases saved to JSON files

###  Data Integration
- **Existing DataProvider**: No duplicate data fetching
- **Cached data**: Leverages existing cache
- **Same quality**: Identical data structure as models see
- **Multi-symbol**: Supports ETH/USDT, BTC/USDT

### 🎨 Professional UI
- **Dark theme**: Matches main dashboard
- **Template-based**: All HTML in separate files
- **Responsive**: Works on different screen sizes
- **Keyboard shortcuts**: Arrow keys for navigation

##  Quick Start

### Installation

```bash
# No additional dependencies needed
# Uses existing project dependencies
```

### Running the Application

```bash
# Start the annotation UI
python ANNOTATE/web/app.py

# Access at: http://127.0.0.1:8051
```

## 📖 Usage Guide

### 1. Navigate to Time Period
- **Date picker**: Jump to specific date/time
- **Quick ranges**: 1h, 4h, 1d, 1w buttons
- **Arrow keys**: ← → to scroll through time
- **Mouse**: Zoom with scroll wheel, pan by dragging

### 2. Mark a Trade
1. **Click on chart** at entry point
   - Entry marker (▲) appears
   - Status shows "Entry marked"
2. **Click again** at exit point
   - Exit marker (▼) appears
   - P&L calculated and displayed
   - Annotation saved automatically

### 3. Manage Annotations
- **View**: Click eye icon (👁️) to navigate to annotation
- **Generate test case**: Click file icon (📄)
- **Delete**: Click trash icon (🗑️)
- **Export**: Click download button to export all

### 4. Generate Test Cases
- Click **file icon** next to any annotation
- Test case generated with full market context
- Saved to `ANNOTATE/data/test_cases/`
- Ready for model training

## 📁 Project Structure

```
ANNOTATE/
├── web/                      # Web application
│   ├── app.py               # Main Flask/Dash application
│   ├── templates/           # Jinja2 HTML templates
│   │   ├── base_layout.html
│   │   ├── annotation_dashboard.html
│   │   └── components/
│   └── static/              # Static assets
│       ├── css/
│       ├── js/
│       └── images/
├── core/                    # Core business logic
│   ├── annotation_manager.py
│   ├── training_simulator.py
│   └── data_loader.py
├── data/                    # Data storage
│   ├── annotations/
│   ├── test_cases/
│   └── training_results/
└── tests/                   # Test files
```

## 🔧 API Endpoints

### Chart Data
```http
POST /api/chart-data
Content-Type: application/json

{
  "symbol": "ETH/USDT",
  "timeframes": ["1s", "1m", "1h", "1d"],
  "start_time": "2024-01-15T10:00:00Z",
  "end_time": "2024-01-15T11:00:00Z"
}
```

### Save Annotation
```http
POST /api/save-annotation
Content-Type: application/json

{
  "symbol": "ETH/USDT",
  "timeframe": "1m",
  "entry": {"timestamp": "...", "price": 2400.50},
  "exit": {"timestamp": "...", "price": 2460.75}
}
```

### Generate Test Case
```http
POST /api/generate-test-case
Content-Type: application/json

{
  "annotation_id": "uuid-string"
}
```

### Available Models
```http
GET /api/available-models
```

## 🔗 Integration with Main System

### Import in Main Dashboard
```python
from ANNOTATE.core.annotation_manager import AnnotationManager
from ANNOTATE.core.training_simulator import TrainingSimulator
from ANNOTATE.core.data_loader import HistoricalDataLoader

# Initialize with existing components
annotation_mgr = AnnotationManager()
training_sim = TrainingSimulator(orchestrator)
data_loader = HistoricalDataLoader(data_provider)

# Use generated test cases
test_cases = annotation_mgr.get_test_cases()
```

### Data Flow
```
ANNOTATE UI → HistoricalDataLoader → DataProvider (existing)
                                          ↓
                                    Training/Inference
```

## 📊 Test Case Format

Generated test cases match the realtime format:

```json
{
  "test_case_id": "annotation_uuid",
  "symbol": "ETH/USDT",
  "timestamp": "2024-01-15T10:30:00Z",
  "action": "BUY",
  "market_state": {
    "ohlcv_1s": {
      "timestamps": [...],
      "open": [...],
      "high": [...],
      "low": [...],
      "close": [...],
      "volume": [...]
    },
    "ohlcv_1m": {...},
    "ohlcv_1h": {...},
    "ohlcv_1d": {...}
  },
  "expected_outcome": {
    "direction": "LONG",
    "profit_loss_pct": 2.5,
    "entry_price": 2400.50,
    "exit_price": 2460.75,
    "holding_period_seconds": 300
  },
  "annotation_metadata": {
    "annotator": "manual",
    "confidence": 1.0,
    "notes": "",
    "created_at": "2024-01-15T11:00:00Z"
  }
}
```

## 🎓 Best Practices

### Marking Trades
1. **Be selective**: Only mark clear, high-confidence trades
2. **Use multiple timeframes**: Confirm patterns across timeframes
3. **Add notes**: Document why you marked the trade
4. **Review before generating**: Verify entry/exit points are correct

### Test Case Generation
1. **Generate after marking**: Create test cases immediately
2. **Verify market context**: Check that OHLCV data is complete
3. **Organize by strategy**: Use notes to categorize trade types
4. **Export regularly**: Backup annotations periodically

### Model Training
1. **Start with quality**: Better to have fewer high-quality annotations
2. **Diverse scenarios**: Mark different market conditions
3. **Balance directions**: Include both LONG and SHORT trades
4. **Test incrementally**: Train with small batches first

## 🐛 Troubleshooting

### Charts not loading
- Check DataProvider is initialized
- Verify data is available for selected timeframes
- Check browser console for errors

### Annotations not saving
- Ensure `ANNOTATE/data/annotations/` directory exists
- Check file permissions
- Verify JSON format is valid

### Test cases missing market context
- Confirm DataProvider has cached data
- Check timestamp is within available data range
- Verify all timeframes have data

## 📚 Documentation

- **Implementation Summary**: `ANNOTATE/IMPLEMENTATION_SUMMARY.md`
- **Progress Tracking**: `ANNOTATE/PROGRESS.md`
- **Spec Files**: `.kiro/specs/manual-trade-annotation-ui/`

## 🎯 Future Enhancements

- [ ] Real-time model training integration
- [ ] Inference simulation with playback
- [ ] Performance metrics dashboard
- [ ] Annotation templates
- [ ] Collaborative annotation
- [ ] Advanced filtering and search
- [ ] Annotation quality scoring

## 📄 License

Part of the AI Trading System project.

## 🙏 Acknowledgments

Built with:
- Flask & Dash for web framework
- Plotly for interactive charts
- Bootstrap for UI components
- Existing DataProvider for data consistency