Añadir eventos

add_events permite que una estrategia de AQE se suscriba a flujos adicionales de eventos de datos de mercado, además del marco temporal principal de la estrategia. El primer flujo de eventos compatible es EventStreamType::Bar.

El marco temporal principal de la estrategia siempre se registra automáticamente a partir del marco temporal pasado a run_backtest(...) o configurado para la ejecución en vivo. Solo debes llamar a add_events cuando necesites marcos temporales adicionales de contexto, como 1m, 15m o 1h.

Uso básico

Registra los flujos de contexto en on_start:

use aq_engine::core::strategy::{EventStreamType, StrategyContext};
use aq_engine::core::utils::timeframe::{TimeFrame, TimeFrameUnit};

fn on_start(&mut self, ctx: &mut dyn StrategyContext) {
    ctx.add_events(
        EventStreamType::Bar,
        Some(TimeFrame::new(15, TimeFrameUnit::Minute)),
    );
}

AQE aplica ese flujo a todos los activos del universo cargado. Si la estrategia negocia BTC y ETH, se registra un flujo de velas de contexto de 15m para ambos símbolos.

La llamada a ctx.add_events(EventStreamType::Bar, None) se refiere al marco temporal principal y no duplica el flujo principal registrado automáticamente.

Opciones de eventos

Usa EventStreamRequest cuando necesites opciones:

use aq_engine::core::strategy::{EventStreamRequest, EventStreamType, StrategyContext};
use aq_engine::core::utils::timeframe::{TimeFrame, TimeFrameUnit};

fn on_start(&mut self, ctx: &mut dyn StrategyContext) {
    ctx.add_events_with_options(
        EventStreamRequest::bar(Some(TimeFrame::new(1, TimeFrameUnit::Hour)))
            .allow_trading(true),
    );
}

allow_trading controla la generación de insights de la estrategia y de los modelos alfa para ese flujo de eventos:

• false es el valor predeterminado de los flujos de contexto. AQE actualiza el historial y llama a on_bar, pero no llama a generate_insights del modelo alfa ni a generate_insights de la estrategia para ese evento de contexto.
• true permite ejecutar generate_insights del modelo alfa y generate_insights de la estrategia para ese evento de contexto.

La ejecución del bróker sigue la ruta de ejecución normal. Las velas de contexto están diseñadas para enriquecer el contexto de la estrategia y la generación de señales; no deben tratarse como un flujo independiente de ejecución de órdenes del bróker.

Claves del historial

El marco temporal principal conserva el símbolo base como clave del historial:

let main_history = ctx.history().get(symbol);

Los marcos temporales de contexto usan {symbol}:{timeframe}:

let feature_history = ctx.history().get("BTC:15m");
let faster_history = ctx.history().get("BTC:1m");
let hourly_history = ctx.history().get("ETH:1h");

Así, los datos de contexto se mantienen separados del historial principal de la estrategia. Los indicadores y el estado personalizado deben leer la clave que corresponda al evento o la señal que utilizan.

Leer el evento actual

Usa ctx.current_event() dentro de on_bar, los modelos alfa o generate_insights para inspeccionar el evento que AQE está procesando:

fn on_bar(&mut self, ctx: &mut dyn StrategyContext, symbol: &str, _bar: &BarData) {
    let Some(event) = ctx.current_event() else {
        return;
    };

    let history = ctx.history().get(&event.history_key);

    if event.is_feature {
        println!(
            "feature bar: {} {} history={} allow_trading={}",
            event.symbol,
            event.timeframe,
            event.history_key,
            event.allow_trading,
        );
    } else {
        println!("main bar: {symbol}");
    }
}

StrategyEventContext incluye:

• event_type
• symbol
• timeframe
• history_key
• is_feature
• allow_trading
• timestamp

El contexto permanece activo durante todo el procesamiento de la vela de ese evento: actualización del historial, actualización de indicadores, on_bar y generación de insights por parte del modelo alfa y de la estrategia cuando el evento permite generarlos.

Cuándo usar flujos de contexto

Usa flujos de contexto cuando una estrategia necesite más de una resolución de datos de mercado:

• una estrategia diaria que lee la estructura de 15m antes de generar una señal;
• una estrategia de 1h que usa filtros de volatilidad o liquidez de 1m;
• un marco temporal principal de ejecución con confirmación de un marco temporal superior.

Mantén el marco temporal principal como referencia temporal de la ejecución. Usa los flujos adicionales como contexto, salvo que permitas deliberadamente que generen insights.