nt8-sdk/Specs/SDK/core_interfaces_package.md

Core Interfaces Package

IMPLEMENTATION CHECKLIST

Create these files exactly as specified:

File 1: src/NT8.Core/Common/Interfaces/IStrategy.cs

using NT8.Core.Common.Models;

namespace NT8.Core.Common.Interfaces;

/// <summary>
/// Core strategy interface - strategies implement signal generation only
/// The SDK handles all risk management, position sizing, and order execution
/// </summary>
public interface IStrategy
{
    /// <summary>
    /// Strategy metadata and configuration
    /// </summary>
    StrategyMetadata Metadata { get; }
    
    /// <summary>
    /// Initialize strategy with configuration and dependencies
    /// </summary>
    void Initialize(StrategyConfig config, IMarketDataProvider dataProvider, ILogger logger);
    
    /// <summary>
    /// Process new bar data and generate trading intent (if any)
    /// This is the main entry point for strategy logic
    /// </summary>
    StrategyIntent? OnBar(BarData bar, StrategyContext context);
    
    /// <summary>
    /// Process tick data for high-frequency strategies (optional)
    /// Most strategies can leave this as default implementation
    /// </summary>
    StrategyIntent? OnTick(TickData tick, StrategyContext context) => null;
    
    /// <summary>
    /// Get current strategy parameters for serialization
    /// </summary>
    Dictionary<string, object> GetParameters();
    
    /// <summary>
    /// Update strategy parameters from configuration
    /// </summary>
    void SetParameters(Dictionary<string, object> parameters);
}

File 2: src/NT8.Core/Common/Models/StrategyMetadata.cs

namespace NT8.Core.Common.Models;

/// <summary>
/// Strategy metadata - describes strategy capabilities and requirements
/// </summary>
public record StrategyMetadata(
    string Name,
    string Description,
    string Version,
    string Author,
    string[] Symbols,
    int RequiredBars
);

/// <summary>
/// Strategy configuration passed during initialization
/// </summary>
public record StrategyConfig(
    string Name,
    string Symbol,
    Dictionary<string, object> Parameters,
    RiskConfig RiskSettings,
    SizingConfig SizingSettings
);

File 3: src/NT8.Core/Common/Models/StrategyIntent.cs

namespace NT8.Core.Common.Models;

/// <summary>
/// Strategy trading intent - what the strategy wants to do
/// This is the output of strategy logic, input to risk management
/// </summary>
public record StrategyIntent(
    string Symbol,
    OrderSide Side,
    OrderType EntryType,
    double? LimitPrice,
    int StopTicks,
    int? TargetTicks,
    double Confidence,      // 0.0 to 1.0 - strategy confidence level
    string Reason,          // Human-readable reason for trade
    Dictionary<string, object> Metadata  // Additional strategy-specific data
)
{
    /// <summary>
    /// Unique identifier for this intent
    /// </summary>
    public string IntentId { get; init; } = Guid.NewGuid().ToString();
    
    /// <summary>
    /// Timestamp when intent was generated
    /// </summary>
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
    
    /// <summary>
    /// Validate intent has required fields
    /// </summary>
    public bool IsValid() => 
        !string.IsNullOrEmpty(Symbol) && 
        StopTicks > 0 && 
        Confidence is >= 0.0 and <= 1.0 &&
        Side != OrderSide.Flat &&
        !string.IsNullOrEmpty(Reason);
}

/// <summary>
/// Order side enumeration
/// </summary>
public enum OrderSide
{
    Buy = 1,
    Sell = -1,
    Flat = 0  // Close position
}

/// <summary>
/// Order type enumeration
/// </summary>
public enum OrderType
{
    Market,
    Limit,
    StopMarket,
    StopLimit
}

File 4: src/NT8.Core/Common/Models/StrategyContext.cs

namespace NT8.Core.Common.Models;

/// <summary>
/// Context information available to strategies
/// </summary>
public record StrategyContext(
    string Symbol,
    DateTime CurrentTime,
    Position CurrentPosition,
    AccountInfo Account,
    MarketSession Session,
    Dictionary<string, object> CustomData
);

/// <summary>
/// Current position information
/// </summary>
public record Position(
    string Symbol,
    int Quantity,
    double AveragePrice,
    double UnrealizedPnL,
    double RealizedPnL,
    DateTime LastUpdate
);

/// <summary>
/// Account information
/// </summary>
public record AccountInfo(
    double Equity,
    double BuyingPower,
    double DailyPnL,
    double MaxDrawdown,
    DateTime LastUpdate
);

/// <summary>
/// Market session information
/// </summary>
public record MarketSession(
    DateTime SessionStart,
    DateTime SessionEnd,
    bool IsRth, // Regular Trading Hours
    string SessionName
);

File 5: src/NT8.Core/Common/Models/MarketData.cs

namespace NT8.Core.Common.Models;

/// <summary>
/// Bar data model
/// </summary>
public record BarData(
    string Symbol,
    DateTime Time,
    double Open,
    double High,
    double Low,
    double Close,
    long Volume,
    TimeSpan BarSize
);

/// <summary>
/// Tick data model  
/// </summary>
public record TickData(
    string Symbol,
    DateTime Time,
    double Price,
    int Size,
    TickType Type
);

/// <summary>
/// Order fill model
/// </summary>
public record OrderFill(
    string OrderId,
    string Symbol,
    int Quantity,
    double FillPrice,
    DateTime FillTime,
    double Commission,
    string ExecutionId
);

public enum TickType
{
    Trade,
    Bid,
    Ask,
    Last
}

/// <summary>
/// Market data provider interface
/// </summary>
public interface IMarketDataProvider
{
    /// <summary>
    /// Subscribe to bar data
    /// </summary>
    void SubscribeBars(string symbol, TimeSpan barSize, Action<BarData> onBar);
    
    /// <summary>
    /// Subscribe to tick data
    /// </summary>
    void SubscribeTicks(string symbol, Action<TickData> onTick);
    
    /// <summary>
    /// Get historical bars
    /// </summary>
    Task<List<BarData>> GetHistoricalBars(string symbol, TimeSpan barSize, int count);
    
    /// <summary>
    /// Get current market price
    /// </summary>
    double? GetCurrentPrice(string symbol);
}

File 6: src/NT8.Core/Risk/IRiskManager.cs

using NT8.Core.Common.Models;

namespace NT8.Core.Risk;

/// <summary>
/// Risk management interface - validates and potentially modifies trading intents
/// This is the gatekeeper between strategy signals and order execution
/// </summary>
public interface IRiskManager
{
    /// <summary>
    /// Validate order intent against risk parameters
    /// Returns decision with allow/reject and any modifications
    /// </summary>
    RiskDecision ValidateOrder(StrategyIntent intent, StrategyContext context, RiskConfig config);
    
    /// <summary>
    /// Update risk state after order fill
    /// </summary>
    void OnFill(OrderFill fill);
    
    /// <summary>
    /// Update risk state with current P&L
    /// </summary>
    void OnPnLUpdate(double netPnL, double dayPnL);
    
    /// <summary>
    /// Emergency flatten all positions
    /// </summary>
    Task<bool> EmergencyFlatten(string reason);
    
    /// <summary>
    /// Get current risk status for monitoring
    /// </summary>
    RiskStatus GetRiskStatus();
}

/// <summary>
/// Risk validation result
/// </summary>
public record RiskDecision(
    bool Allow,
    string? RejectReason,
    StrategyIntent? ModifiedIntent,  // If risk manager modifies size/price
    RiskLevel RiskLevel,
    Dictionary<string, object> RiskMetrics
);

/// <summary>
/// Current risk system status
/// </summary>
public record RiskStatus(
    bool TradingEnabled,
    double DailyPnL,
    double DailyLossLimit,
    double MaxDrawdown,
    int OpenPositions,
    DateTime LastUpdate,
    List<string> ActiveAlerts
);

/// <summary>
/// Risk level classification
/// </summary>
public enum RiskLevel
{
    Low,      // Normal trading
    Medium,   // Elevated caution
    High,     // Limited trading
    Critical  // Trading halted
}

/// <summary>
/// Risk configuration parameters
/// </summary>
public record RiskConfig(
    double DailyLossLimit,
    double MaxTradeRisk,
    int MaxOpenPositions,
    bool EmergencyFlattenEnabled
);

File 7: src/NT8.Core/Sizing/IPositionSizer.cs

using NT8.Core.Common.Models;

namespace NT8.Core.Sizing;

/// <summary>
/// Position sizing interface - determines contract quantity
/// </summary>
public interface IPositionSizer
{
    /// <summary>
    /// Calculate position size for trading intent
    /// </summary>
    SizingResult CalculateSize(StrategyIntent intent, StrategyContext context, SizingConfig config);