investfly.models.strategy

Initialize strategy with optional configuration.

Args: config: Dictionary of strategy-specific parameters. Can contain any structure (numeric, list, string, nested dictionaries, etc.). Defaults to None if no configuration is provided.

Note: The dataService and context attributes are set by the execution engine before strategy methods are called. They should not be set manually in the constructor.

Set the data service for accessing market data and indicators.

This method is called by the execution engine to inject the data service into the strategy instance. The data service provides access to:

• Indicator computation (SMA, RSI, MACD, etc.)
• Market data (quotes, bars, financials, news)

Args: dataService: The strategy data service instance. This is a singleton service shared across all strategy executions.

Note: This method is typically called automatically by the execution engine. Strategies should not call this method directly.

Set the execution context for the strategy instance.

This method is called by the execution engine to inject the execution context into the strategy instance. The context contains:

• Portfolio: Current portfolio state with positions and balances
• Universe securities: List of securities in the strategy's trading universe

Args: context: The execution context containing portfolio and universe data.

Note: This method is typically called automatically by the execution engine. Strategies should not call this method directly.

Inject the runtime implementation of the public strategy helper contract.

Get the portfolio from the execution context.

Returns: The current portfolio state containing: - Open positions - Account balances - Portfolio performance metrics

Example:

portfolio = self.getPortfolio()
portfolio_value = portfolio.balances.currentValue
for position in portfolio.openPositions:
    print(f"{position.security.symbol}: {position.quantity} shares")

Get the universe securities from the execution context.

Returns: List of Security objects representing all securities in the strategy's trading universe. This is the resolved list based on the security universe selector returned by getSecurityUniverseSelector().

Example:

universe = self.getUniverseSecurities()
for security in universe:
    quote = self.dataService.getQuote(security)
    if quote:
        print(f"{security.symbol}: {quote.lastPrice}")

Get the state value for the given key.

Args: key: The key to get the state value for.

Returns: The state value for the given key.

Return the security universe selector for this strategy.

This method must be implemented by all strategy subclasses. It defines which securities the strategy will evaluate and trade.

Returns: A SecurityUniverseSelector object that defines the strategy's trading universe. The selector can specify: - A single security - A standard predefined list (e.g., S&P 500, NASDAQ 100) - A custom list of symbols - A fundamental query-based selection

Example:

# Single stock
return SecurityUniverseSelector.singleStock("AAPL")

# Standard list
return SecurityUniverseSelector.fromStandardList(StandardSymbolsList.SP_500)

# Custom list
return SecurityUniverseSelector.fromSymbols(
    SecurityType.STOCK, ["AAPL", "MSFT", "GOOGL"]
)

# Fundamental query
query = FinancialQuery(
    SecurityType.STOCK,
    FinancialCondition(FinancialField.MARKET_CAP, ComparisonOperator.GREATER_THAN, 1000000000)
)
return SecurityUniverseSelector.fromFinancialQuery(query)

Handle market data updates (bars/ticks).

This optional method is called whenever market data is updated for securities in the strategy's universe. To enable this callback, override this method and decorate it with @data_trigger.

The @data_trigger decorator specifies when this method should be called:

• type (DataType): The type of market data to trigger on. Currently supported: DataType.BARS (bar/candlestick data).
• barInterval (BarInterval, optional): Required for BARS type. Options: ONE_MINUTE, FIVE_MINUTE, FIFTEEN_MINUTE, THIRTY_MINUTE, SIXTY_MINUTE, ONE_DAY.

Args: updatedSecurities: List of Security objects that received market data updates triggering this callback. Strategies should iterate over this list instead of the full universe to process only securities with new data.

Returns: Optional list of TradeOrder objects to execute. Return None or an empty list if no trades should be placed.

Note: - If your logic requires Quote data (e.g., LastPrice), use @data_trigger(type=DataType.BARS, barInterval=BarInterval.ONE_MINUTE) to trigger on every 1-minute bar update, then access quotes using self.dataService.getQuote(security). - The method is called only for securities that have received updates, not for the entire universe.

Example:

@data_trigger(type=DataType.BARS, barInterval=BarInterval.ONE_DAY)
def onMarketData(self, updatedSecurities):
    orders = []
    for security in updatedSecurities:
        # Compute indicators
        sma = self.dataService.computeIndicatorSeries(
            "SMA", security, {"period": 20, "barInterval": BarInterval.ONE_DAY}
        )
        # Generate trade orders based on indicator values
        if sma.last.value > threshold:
            orders.append(TradeOrder(security, TradeType.BUY, OrderType.MARKET_ORDER))
    return orders if orders else None

Handle scheduled time-based events.

Custom strategies may decorate any number of scheduled methods with @scheduled(TriggerSchedule...). The execution engine discovers all decorated callbacks through getScheduledCallbacks() and passes a ScheduleEvent to each callback.

Returns: Optional list of TradeOrder objects to execute. Return None or an empty list if no trades should be placed.

Note: - Multiple methods can be decorated with @scheduled to run distinct jobs at distinct schedule patterns. - The event argument includes the callback name, the schedule, the scheduled time, the actual evaluation time, and whether the callback is executing inside a backtest.

Example:

@scheduled(TriggerSchedule.daily("10:00"))
def rebalanceDaily(self, event: ScheduleEvent):
    orders = []
    portfolio = self.getPortfolio()
    return orders

@scheduled(TriggerSchedule.interval(5, days=ScheduleDayMode.EVERYDAY, window=ScheduleWindow("09:00", "13:00")))
def checkPositions(self, event: ScheduleEvent):
    return None

Return all scheduled callbacks exposed by this strategy instance.

Return runtime-managed position, lifecycle, and portfolio behavior.

The same contract models used by configuration-driven strategies are accepted here. The runtime evaluates the policy in live trading and backtests; user strategy code supplies inputs and consumes planned orders without owning the algorithms.

Constant for retrieving all available bars.

Retrieve historical bars for a security.

For futures products, pass the product-level Security such as Security("MNQ", SecurityType.FUTURE). This returns the continuous back-adjusted series formed by stitching bars across successive contracts. Individual contract-level historical bars are not available through this method.

Args: security: The Security object for which to fetch bars. barInterval: The interval of bars to retrieve (e.g., ONE_MINUTE, ONE_DAY). numBars: Number of bars to return. Use StrategyDataService.ALL_BARS to retrieve all available bars.

Returns: List of Bar objects containing OHLC data in chronological order (oldest first).

Raises: NoDataException: If the requested data is not available.

Retrieve fundamental financial metrics for the given symbol.

Args: symbol: The stock symbol (e.g., "AAPL", "MSFT").

Returns: Dictionary mapping FinancialField enums to their corresponding values.

Retrieve the latest quote for the given security.

For futures, security can be a product-level Security (returns the expiry-safe active-contract quote from the product-keyed live cache) or a specific Future contract. Live execution can also resolve a contract-symbol Security such as Security("MNQM26", SecurityType.FUTURE) to a direct contract quote for any active contract returned by listFutures(). Backtests intentionally reject concrete contract quotes because the available futures history is product-level and back-adjusted.

Args: security: The Security (or Future) for which to retrieve the quote.

Returns: Quote object containing the latest market data.

List active futures contracts for a product, sorted by ascending expiry.

List broker/vendor-listed expirations for live option contract selection.

Return the listed option chain for one underlying and expiration.

Retrieve latest news articles for the given security.

Args: security: The Security object for which to retrieve news.

Returns: List of StockNews objects containing news articles.

Compute a technical indicator series for a given security.

This method computes a technical indicator (e.g., SMA, RSI, MACD) and returns a series of indicator values over time. The series can be used for analysis, signal generation, and crossover detection.

The indicatorId parameter is declared as a string (not an enum) to support both standard indicators provided by Investfly and custom indicators defined by users. For standard indicators, the string value must match one of the values from the StandardIndicatorId enum.

Args: indicatorId: The identifier of the indicator to compute. Must be a string value. For standard indicators supported by Investfly, use one of the values from StandardIndicatorId enum:

    **Moving Averages:**
    - "SMA": Simple Moving Average
    - "EMA": Exponential Moving Average

    **Momentum Indicators:**
    - "RSI": Relative Strength Index
    - "ROC": Rate of Change
    - "CMO": Chande Momentum Oscillator
    - "CMO_SMOOTHED": Smoothed CMO
    - "PPO": Percentage Price Oscillator
    - "ULTIMATE_OSC": Ultimate Oscillator

    **Trend Indicators:**
    - "MACD": Moving Average Convergence Divergence
    - "MACDS": MACD Signal Line
    - "ADX": Average Directional Index
    - "PLUS_DI": Plus Directional Indicator
    - "MINUS_DI": Minus Directional Indicator
    - "PSAR": Parabolic SAR

    **Volatility Indicators:**
    - "ATR": Average True Range
    - "STD_DEV": Standard Deviation
    - "UPPER_BBAND": Upper Bollinger Band
    - "LOWER_BBAND": Lower Bollinger Band
    - "BBAND": Bollinger Bands (composite, for charts only)

    **Oscillators:**
    - "CCI": Commodity Channel Index
    - "WILLIAM_R": Williams' %R
    - "FAST_STOCHASTIC_OSC": Fast Stochastic Oscillator
    - "SLOW_STOCHASTIC_OSC": Slow Stochastic Oscillator
    - "STOCHASTICS": Stochastic (composite, for charts only)

    **Price Indicators:**
    - "MEDIAN_PRICE": Median Price
    - "TYPICAL_PRICE": Typical Price
    - "MAX": Maximum value over period
    - "MIN": Minimum value over period

    **Candlestick Patterns:**
    - "DOJI": Doji pattern
    - "HAMMER": Hammer pattern
    - "INVERTED_HAMMER": Inverted Hammer pattern
    - "DRAGONFLY_DOJI": Dragonfly Doji pattern
    - "GRAVESTONE_DOJI": Gravestone Doji pattern
    - "HANGING_MAN": Hanging Man pattern
    - "BULLISH": Bullish pattern
    - "BEARISH": Bearish pattern

    **Support/Resistance:**
    - "SUPPORT": Support level
    - "RESISTANCE": Resistance level

    **Other:**
    - "AVGVOLUME": Average Volume
    - "HIGH52WEEK": 52-Week High
    - "LOW52WEEK": 52-Week Low
    - "DRAWDOWN": Drawdown
    - "PRICECHANGEPCT": Price Change Percentage

    For custom indicators, use the custom indicator ID string as
    defined when the indicator was created.

security: The security for which to compute the indicator.
params: Dictionary of parameters for the indicator computation.
    Common parameters include:
    - "period" (int): Period for the indicator (e.g., 20 for SMA(20)).
    - "barInterval" (BarInterval): Bar interval for the data source.
    - Indicator-specific parameters (e.g., "fast_period", "slow_period"
      for MACD).

Returns: IndicatorSeries object containing the computed indicator values. The series provides methods for: - Accessing the latest value: series.last.value - Converting to list: series.toList() - Crossover detection: series.cross_over(other), series.cross_under(other)

Note: - The indicatorId parameter is a string type (not StandardIndicatorId enum) to support both standard and custom indicators. - When using standard indicators, the string value must exactly match one of the StandardIndicatorId enum values (see investfly.models.indicator.IndicatorEnums.StandardIndicatorId). - Custom indicators can be referenced by their custom ID string.

Example:

# Compute 20-period SMA on daily bars (standard indicator)
sma20 = self.dataService.computeIndicatorSeries(
    "SMA",  # Must match StandardIndicatorId.SMA.value
    security,
    {"period": 20, "barInterval": BarInterval.ONE_DAY}
)

# Compute 14-period RSI (standard indicator)
rsi = self.dataService.computeIndicatorSeries(
    "RSI",  # Must match StandardIndicatorId.RSI.value
    security,
    {"period": 14, "barInterval": BarInterval.ONE_DAY}
)

# Compute custom indicator
custom_indicator = self.dataService.computeIndicatorSeries(
    "MY_CUSTOM_INDICATOR",  # Custom indicator ID
    security,
    {"param1": 10, "barInterval": BarInterval.ONE_DAY}
)

# Check for crossover
if sma20.cross_over(rsi):
    # SMA crossed above RSI - bullish signal
    pass

# Access latest value
current_rsi = rsi.last.value

Run a market query using a market query request.

This method executes a screener query to find securities that match the given filter expression. The query is executed against the universe of securities available to this strategy.

Args: request: MarketQueryRequest containing: - securityFilterExpression: SecurityFilterExpression with filter criteria. The expression can include filters on: - Quote fields (price, volume, etc.) - Financial data (market cap, P/E ratio, etc.) - Technical indicators (SMA, RSI, etc.) - sortBy: Optional SortBySpec for sorting and limiting results.

Returns: List of Security objects that match the filter criteria. Returns an empty list if no securities match.

Example:

from investfly.models.strategy.SecurityFilterExpression import SecurityFilterExpression
from investfly.models.strategy.MarketQueryRequest import MarketQueryRequest
from investfly.models.strategy.DataParams import DataParam, DataType
from investfly.models.marketdata.QuoteField import QuoteField

# Create a filter expression: price > 100
filter_expr = SecurityFilterExpression("price > 100")
price_param = DataParam(DataType.QUOTE, quoteField=QuoteField.LAST_PRICE)
filter_expr.addDataParam("price", price_param)

# Create market query request
query_request = MarketQueryRequest(securityFilterExpression=filter_expr)

# Run the query
matching_securities = self.dataService.runMarketQuery(query_request)
for security in matching_securities:
    print(f"Found: {security.symbol}")