siloqy/docs/planning/DOLPHIN_Period_Tracking_Feature_Analysis.md

DOLPHIN System Period Tracking Feature Analysis

Overview

This document compiles all available information about adding 15m, 1H, and other period tracking capabilities to the DOLPHIN system, which currently tracks BULL% vs BEARS% in trade data.

Current DOLPHIN System Status

Based on the conversation data found:

Existing Functionality

• Current Output: Produces up_ratio/down_ratio based on 500 symbols
• Data Format: JSON with regime ("BULL"/"BEAR"), ratios, timestamp
• Sample Data Shows: Transitions like 76.3% bullish → 14.2% bullish (major regime shifts)
• Architecture: Part of SILOQY = DOLPHIN (regime detection) + JERICHO (FSM signals) + future HARLEQUIN (trading)

Current Data Structure

{
  "regime": "BULL",
  "up_ratio": 0.7627118644067796,
  "down_ratio": 0.23728813559322035,
  "total_symbols": 405,
  "timestamp": "2025-08-12T17:10:16.389625"
}

Proposed Period Tracking Enhancements

Missing Features Identified

From the conversation analysis, the following enhancements were discussed:

1. Bollinger Band Distance Calculations

   • Missing: BB distance calculations for BTC specifically
   • Need: BB proximity calculation as percentages
   • Proposed addition to data structure:

   {
     "bull_pct": 76.3,
     "bear_pct": 23.7, 
     "regime": "BULL",
     "timestamp": "...",
     "bb_dist_pct": 1.23  // NEW: distance to closest BB
   }
   

2. Time Period Tracking

   • 3m candles: Mentioned that "Jericho has been tested in Bitcoin 3m candles, yielding good results"
   • Period synchronization: DOLPHIN runs every ~5 seconds, JERICHO spec mentions 5-second SCANs
   • Multi-timeframe support: References to 15m, 1H periods for enhanced tracking

3. Historical Data Integration

   • Latest X Amount of Periods: Need to track recent period performance
   • Rolling Windows: Implementation of moving averages across different timeframes
   • Period-based Analysis: Track bull/bear percentages across multiple timeframes simultaneously

Technical Implementation Requirements

Data Structure Enhancements

The DOLPHIN system would need to expand its output to include:

{
  "regime": "BULL",
  "current_period": {
    "up_ratio": 0.7627,
    "down_ratio": 0.2373,
    "timestamp": "2025-08-12T17:10:16.389625"
  },
  "period_tracking": {
    "5m": {
      "latest_periods": [
        {"up_ratio": 0.76, "down_ratio": 0.24, "timestamp": "..."},
        {"up_ratio": 0.72, "down_ratio": 0.28, "timestamp": "..."}
      ],
      "average_bull_pct": 74.0,
      "trend": "BULLISH"
    },
    "15m": {
      "latest_periods": [...],
      "average_bull_pct": 71.5,
      "trend": "BULLISH"
    },
    "1H": {
      "latest_periods": [...],
      "average_bull_pct": 68.2,
      "trend": "NEUTRAL"
    }
  },
  "bb_analysis": {
    "btc_bb_distance_pct": 1.23,
    "proximity_status": "WATCHING"
  }
}

Integration Points

1. DOLPHIN → JERICHO: Enhanced JSON websocket with regime/ratios + BB distances + period analysis
2. Period Synchronization: Align DOLPHIN's ~5-second updates with JERICHO's 5-second SCANs
3. Multi-timeframe Analysis: Support for 5m, 15m, 1H, and potentially longer periods

Proposed Feature Specifications

1. Period Tracking Configuration

• Configurable Periods: 5m, 15m, 30m, 1H, 4H, 1D
• History Depth: Track latest X periods (configurable, default 20-50 periods)
• Rolling Calculations: Moving averages of bull/bear percentages across periods

2. Enhanced Analytics

• Trend Detection: Identify bullish/bearish trends across different timeframes
• Momentum Analysis: Rate of change in bull/bear percentages
• Cross-timeframe Correlation: Identify when multiple timeframes align

3. Alert System

• Regime Changes: Alert when regime changes across multiple timeframes
• Threshold Breaches: Configurable alerts for extreme bull/bear percentages
• Trend Reversals: Early warning system for potential trend changes

Implementation Priority

Phase 1: Basic Period Tracking

1. Add 15m and 1H period tracking to existing DOLPHIN output
2. Implement rolling window calculations for latest X periods
3. Basic trend detection (bullish/bearish/neutral)

Phase 2: Enhanced Analytics

1. Cross-timeframe correlation analysis
2. Momentum calculations and trend strength indicators
3. Integration with JERICHO FSM for enhanced signal generation

Phase 3: Advanced Features

1. Machine learning-based pattern recognition across periods
2. Predictive analytics for regime changes
3. Advanced alert and notification system

Notes and Limitations

Data Availability

• Limited specific conversation data about exact implementation details
• Most references are architectural rather than detailed specifications
• Need more detailed requirements gathering for specific period tracking needs

Technical Considerations

• Performance Impact: Adding multiple timeframe tracking will increase computational load
• Data Storage: Need to consider storage requirements for historical period data
• Real-time Processing: Ensure period calculations don't impact real-time performance

Recommendations

1. Start Simple: Begin with 15m and 1H tracking as proof of concept
2. Configurable Design: Make period selection and history depth configurable
3. Backward Compatibility: Ensure existing DOLPHIN consumers continue to work
4. Performance Monitoring: Implement metrics to monitor impact of new features
5. Gradual Rollout: Phase implementation to validate each component before adding complexity

Missing Information

The conversation dump did not contain detailed specifications for:

• Exact calculation methods for period aggregation
• Specific use cases for different timeframes
• Performance requirements and constraints
• Integration testing procedures
• User interface requirements for period tracking data

Recommendation: Conduct additional requirements gathering sessions to fill these gaps before implementation begins.