# ANNOTATE - Usage Guide

## 🎯 Quick Start

### Starting the Application
```bash
python ANNOTATE/web/app.py
```
Access at: **http://127.0.0.1:8051**

---

## 📊 Creating Annotations

### Method 1: Click to Mark (Recommended)
1. **Navigate** to the time period you want to annotate
2. **Click on the chart** at the entry point
   - You'll see "Entry marked" status
   - A temporary marker appears
3. **Click again** at the exit point
   - Annotation is saved automatically
   - Visual markers appear: ▲ (entry) and ▼ (exit)
   - P&L percentage is calculated and displayed

### What Gets Captured
When you create an annotation, the system captures:
-  **Entry timestamp and price**
-  **Exit timestamp and price**
-  **Full market state** (OHLCV for all 4 timeframes)
-  **Direction** (LONG/SHORT)
-  **P&L percentage**
-  **Market context** at both entry and exit

This ensures the annotation contains **exactly the same data** your models will see during training!

---

## ✏️ Editing Annotations

### Method 1: Click on P&L Label
1. **Click the P&L label** (the percentage with 🗑️ icon)
2. Choose action:
   - **1** - Move entry point
   - **2** - Move exit point
   - **3** - Delete annotation

### Method 2: From Sidebar
1. Find annotation in the right sidebar
2. Click the **eye icon** (👁️) to view
3. Click the **trash icon** (🗑️) to delete

### Moving Entry/Exit Points
1. Click on annotation → Choose "1" or "2"
2. The current point is removed
3. The other point stays as reference (grayed out)
4. **Click on chart** to set new position
5. Annotation is updated automatically

---

## 🎨 Visual Indicators

### On Charts
- **▲ Green Triangle** = LONG entry point
- **▲ Red Triangle** = SHORT entry point
- **▼ Green Triangle** = LONG exit point
- **▼ Red Triangle** = SHORT exit point
- **Dashed Line** = Connects entry to exit
- **P&L Label** = Shows profit/loss percentage
- **🗑️ Icon** = Click to edit/delete

### Color Coding
- **Green** = LONG trade (buy low, sell high)
- **Red** = SHORT trade (sell high, buy low)
- **Positive P&L** = Green text
- **Negative P&L** = Red text

---

## 🗂️ Managing Annotations

### Viewing All Annotations
- Right sidebar shows all annotations
- Sorted by creation time
- Shows: Direction, Timeframe, P&L, Timestamp

### Filtering
- Annotations are grouped by symbol
- Switch symbols using the dropdown

### Exporting
1. Click **download button** at top of annotation list
2. All annotations exported to JSON file
3. File includes full market context

---

## 📦 Generating Test Cases

### Automatic Generation
When you save an annotation, the system:
1.  Captures market state at entry time
2.  Captures market state at exit time
3.  Stores OHLCV data for all timeframes
4.  Calculates expected outcome (P&L, direction)

### Manual Generation
1. Find annotation in sidebar
2. Click **file icon** (📄)
3. Test case generated and saved to:
   ```
   ANNOTATE/data/test_cases/annotation_<id>.json
   ```

### Test Case Format
```json
{
  "test_case_id": "annotation_uuid",
  "symbol": "ETH/USDT",
  "timestamp": "2024-01-15T10:30:00Z",
  "action": "BUY",
  "market_state": {
    "ohlcv_1s": { /* 100 candles */ },
    "ohlcv_1m": { /* 100 candles */ },
    "ohlcv_1h": { /* 100 candles */ },
    "ohlcv_1d": { /* 100 candles */ }
  },
  "expected_outcome": {
    "direction": "LONG",
    "profit_loss_pct": 2.5,
    "entry_price": 2400.50,
    "exit_price": 2460.75
  }
}
```

---

## ⌨️ Keyboard Shortcuts

- **← Left Arrow** = Navigate backward in time
- **→ Right Arrow** = Navigate forward in time
- **Space** = Mark point (when chart focused)
- **Esc** = Cancel pending annotation

---

## 🎯 Best Practices

### 1. Be Selective
- Only mark **clear, high-confidence** trades
- Quality > Quantity
- Look for obvious patterns

### 2. Use Multiple Timeframes
- Check all 4 timeframes before marking
- Confirm pattern across timeframes
- Look for confluence

### 3. Document Your Reasoning
- Add notes to annotations (future feature)
- Explain why you marked the trade
- Note key indicators or patterns

### 4. Review Before Generating
- Verify entry/exit points are correct
- Check P&L calculation makes sense
- Ensure market context is complete

### 5. Organize by Strategy
- Group similar trade types
- Use consistent marking criteria
- Build a library of patterns

---

## 🔧 Troubleshooting

### Clicks Not Working
- **Issue**: Chart clicks don't register
- **Solution**: 
  - Make sure you're clicking on the **candlestick** (not volume bars)
  - Click on the **body or wick** of a candle
  - Avoid clicking on empty space

### Annotations Not Appearing
- **Issue**: Saved annotations don't show on charts
- **Solution**:
  - Refresh the page
  - Check the correct symbol is selected
  - Verify annotation is for the visible timeframe

### Can't Edit Annotation
- **Issue**: Edit mode not working
- **Solution**:
  - Click directly on the **P&L label** (percentage text)
  - Or use the sidebar icons
  - Make sure annotation mode is enabled

### Market Context Missing
- **Issue**: Test case has empty market_state
- **Solution**:
  - Ensure DataProvider has cached data
  - Check timestamp is within available data range
  - Verify all timeframes have data

---

## 💡 Tips & Tricks

### Tip 1: Quick Navigation
Use the **quick range buttons** (1h, 4h, 1d, 1w) to jump to different time periods quickly.

### Tip 2: Zoom for Precision
- **Scroll wheel** to zoom in/out
- **Drag** to pan
- Get precise entry/exit points

### Tip 3: Check All Timeframes
Before marking, scroll through all 4 charts to confirm the pattern is valid across timeframes.

### Tip 4: Start with Recent Data
Begin annotating recent data where you remember the market conditions clearly.

### Tip 5: Batch Export
Export annotations regularly to backup your work.

---

## 📊 Data Consistency

### Why It Matters
The annotation system uses the **same DataProvider** as your training and inference systems. This means:

 **Same data source**  
 **Same data quality**  
 **Same data structure**  
 **Same timeframes**  
 **Same caching**

### What This Guarantees
When you train a model on annotated data:
- The model sees **exactly** what you saw
- No data discrepancies
- No format mismatches
- Perfect consistency

---

## 🎓 Example Workflow

### Scenario: Mark a Breakout Trade

1. **Navigate** to ETH/USDT on 2024-01-15
2. **Identify** a breakout pattern on 1m chart
3. **Confirm** on 1h chart (uptrend)
4. **Click** at breakout point: $2400.50 (10:30:00)
5. **Click** at target: $2460.75 (10:35:00)
6. **Result**: LONG trade, +2.51% P&L
7. **Verify**: Check all timeframes show the pattern
8. **Generate**: Click file icon to create test case
9. **Train**: Use test case to train model

---

## 📝 Storage Locations

### Annotations
```
ANNOTATE/data/annotations/annotations_db.json
```

### Test Cases
```
ANNOTATE/data/test_cases/annotation_<id>.json
```

### Exports
```
ANNOTATE/data/annotations/export_<timestamp>.json
```

---

##  Next Steps

After creating annotations:

1. **Generate test cases** for all annotations
2. **Review test cases** to verify market context
3. **Train models** using the test cases
4. **Evaluate performance** with inference simulation
5. **Iterate** - mark more trades, refine patterns

---

## 📞 Support

For issues or questions:
- Check `ANNOTATE/README.md` for technical details
- Review `ANNOTATE/IMPLEMENTATION_SUMMARY.md` for architecture
- See `ANNOTATE/STATUS.md` for current status

---

**Happy Annotating!** 🎉