DhanHQ 3.0.0 → 3.1.0

data/lib/DhanHQ/risk/checks/options.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces option-specific risk rules (index-only, stop loss, target, risk-reward).
+      class Options
+        def self.run!(args:, instrument:, **_unused)
+          enforce_index!(instrument)
+          enforce_stop_loss!(args)
+          enforce_target!(args)
+          enforce_risk_reward!(args)
+        end
+
+        def self.enforce_index!(instrument)
+          return if instrument.instrument_type == "INDEX"
+
+          raise DhanHQ::RiskViolation, "Options only allowed on index"
+        end
+
+        def self.enforce_stop_loss!(args)
+          return if args["stop_loss"]
+
+          raise DhanHQ::RiskViolation, "Stop loss required"
+        end
+
+        def self.enforce_target!(args)
+          return if args["target"]
+
+          raise DhanHQ::RiskViolation, "Target required"
+        end
+
+        def self.enforce_risk_reward!(args)
+          stop_loss = args["stop_loss"].to_f
+          target = args["target"].to_f
+          return if target > stop_loss
+
+          raise DhanHQ::RiskViolation, "Invalid risk-reward"
+        end
+
+        private_class_method :enforce_index!, :enforce_stop_loss!,
+                             :enforce_target!, :enforce_risk_reward!
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/order_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Restricts order types to MARKET and LIMIT only.
+      class OrderType
+        VALID_TYPES = %w[MARKET LIMIT].freeze
+
+        def self.run!(args:, **_unused)
+          order_type = args["order_type"]
+          return unless order_type
+          return if VALID_TYPES.include?(order_type)
+
+          raise DhanHQ::RiskViolation, "Invalid order type"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/position_limits.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces maximum number of concurrent open positions.
+      class PositionLimits
+        MAX_OPEN_POSITIONS = 20
+
+        def self.run!(**_unused)
+          positions = DhanHQ::Models::Position.all
+          open_count = positions.count do |p|
+            p.net_qty.to_i != 0
+          end
+
+          return if open_count < MAX_OPEN_POSITIONS
+
+          raise DhanHQ::RiskViolation,
+                "Maximum #{MAX_OPEN_POSITIONS} open positions exceeded (#{open_count} open)"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/product_support.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Validates that the instrument supports the requested product type (BO/CO).
+      class ProductSupport
+        def self.run!(args:, instrument:, **_unused)
+          product_type = args["product_type"]
+          return unless product_type
+
+          enforce_bracket_support!(product_type, instrument)
+          enforce_cover_support!(product_type, instrument)
+        end
+
+        def self.enforce_bracket_support!(product_type, instrument)
+          return unless product_type == DhanHQ::Constants::ProductType::BO
+          return if instrument.bracket_flag == "Y"
+
+          raise DhanHQ::RiskViolation, "Bracket orders not supported"
+        end
+
+        def self.enforce_cover_support!(product_type, instrument)
+          return unless product_type == DhanHQ::Constants::ProductType::CO
+          return if instrument.cover_flag == "Y"
+
+          raise DhanHQ::RiskViolation, "Cover orders not supported"
+        end
+
+        private_class_method :enforce_bracket_support!, :enforce_cover_support!
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/quantity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces quantity and notional limits for MCP tool safety.
+      class Quantity
+        MAX_QUANTITY = 10
+        MAX_NOTIONAL = 100_000
+
+        def self.run!(args:, **_unused)
+          quantity = args["quantity"].to_i
+          raise DhanHQ::RiskViolation, "Quantity must be > 0" unless quantity.positive?
+          raise DhanHQ::RiskViolation, "Quantity exceeds limit" if quantity > MAX_QUANTITY
+
+          enforce_notional_limit!(quantity, args["price"])
+        end
+
+        def self.enforce_notional_limit!(quantity, price)
+          return unless price
+
+          notional = quantity * price.to_f
+          return if notional <= MAX_NOTIONAL
+
+          raise DhanHQ::RiskViolation, "Notional exceeds limit"
+        end
+
+        private_class_method :enforce_notional_limit!
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/trading_permission.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Blocks trading on instruments where buy_sell_indicator is not "A".
+      class TradingPermission
+        def self.run!(instrument:, **_unused)
+          return if instrument.buy_sell_indicator == "A"
+
+          raise DhanHQ::RiskViolation, "Trading disabled for instrument"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/pipeline.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    # Pre-execution risk pipeline that validates orders before they reach the broker.
+    #
+    # Runs a sequence of checks against the instrument and order arguments.
+    # Raises DhanHQ::RiskViolation on the first failure.
+    #
+    # @example Run equity risk checks
+    #   DhanHQ::Risk::Pipeline.run!(
+    #     instrument: instrument,
+    #     args: args,
+    #     now: Time.now,
+    #     type: :equity
+    #   )
+    #
+    # @example Run options risk checks
+    #   DhanHQ::Risk::Pipeline.run!(
+    #     instrument: instrument,
+    #     args: args,
+    #     now: Time.now,
+    #     type: :options
+    #   )
+    #
+    class Pipeline
+      CHECKS = [
+        Checks::TradingPermission,
+        Checks::AsmGsm,
+        Checks::ProductSupport,
+        Checks::OrderType,
+        Checks::Quantity,
+        Checks::MarketHours,
+        Checks::PositionLimits,
+        Checks::Concentration
+      ].freeze
+
+      OPTION_CHECKS = [
+        Checks::Options
+      ].freeze
+
+      DAILY_CHECKS = [
+        Checks::MaxLoss
+      ].freeze
+
+      # Run all applicable risk checks.
+      #
+      # @param instrument [Object] instrument with trading metadata
+      # @param args [Hash] order arguments (string keys)
+      # @param now [Time] current time for market hours check (default: Time.now)
+      # @param type [Symbol] :equity or :options
+      # @return [true] if all checks pass
+      # @raise [DhanHQ::RiskViolation] on first failure
+      # rubocop:disable Naming/PredicateMethod
+      def self.run!(instrument:, args:, now: Time.now, type: :equity)
+        run_checks!(CHECKS, instrument, args, now)
+        run_checks!(OPTION_CHECKS, instrument, args, now) if type == :options
+        run_checks!(DAILY_CHECKS, instrument, args, now)
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      def self.run_checks!(checks, instrument, args, now)
+        checks.each do |check|
+          check.run!(instrument: instrument, args: args, now: now)
+        end
+      end
+
+      private_class_method :run_checks!
+    end
+  end
+end

data/lib/DhanHQ/risk.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Risk management utilities for position sizing and order risk calculation.
+  module Risk
+    # Calculate optimal position size based on risk parameters.
+    #
+    # Supports multiple sizing methods:
+    # - Fixed risk percentage of account
+    # - Kelly criterion
+    # - Volatility-based sizing
+    #
+    # @example Calculate position size with 2% risk
+    #   size = DhanHQ::Risk::PositionSizer.calculate(
+    #     account_balance: 100_000,
+    #     risk_percent: 2.0,
+    #     entry_price: 2500,
+    #     stop_loss_price: 2450
+    #   )
+    #   #=> 40
+    #
+    class PositionSizer
+      # Calculate position size based on fixed risk percentage.
+      #
+      # @param account_balance [Float] Total account balance
+      # @param risk_percent [Float] Percentage of account to risk per trade (e.g., 2.0 for 2%)
+      # @param entry_price [Float] Planned entry price
+      # @param stop_loss_price [Float] Planned stop loss price
+      # @param lot_size [Integer] Lot size for the instrument (default: 1)
+      # @return [Integer] Number of shares/lots to trade
+      def self.calculate(account_balance:, risk_percent:, entry_price:, stop_loss_price:, lot_size: 1)
+        return 0 if account_balance <= 0 || entry_price <= 0 || stop_loss_price <= 0
+        return 0 if entry_price == stop_loss_price
+
+        risk_amount = account_balance * (risk_percent / 100.0)
+        risk_per_share = (entry_price - stop_loss_price).abs
+
+        return 0 if risk_per_share.zero?
+
+        raw_shares = (risk_amount / risk_per_share).floor
+        (raw_shares / lot_size).floor * lot_size
+      end
+
+      # Calculate position size using Kelly Criterion.
+      #
+      # @param win_rate [Float] Historical win rate (0.0 to 1.0)
+      # @param avg_win [Float] Average winning trade amount
+      # @param avg_loss [Float] Average losing trade amount (positive number)
+      # @param account_balance [Float] Total account balance
+      # @param entry_price [Float] Planned entry price
+      # @param fraction [Float] Kelly fraction to use (default: 0.5 for half-Kelly)
+      # @return [Integer] Number of shares to trade
+      def self.kelly(win_rate:, avg_win:, avg_loss:, account_balance:, entry_price:, fraction: 0.5)
+        return 0 if account_balance <= 0 || entry_price <= 0
+        return 0 if avg_loss.zero? || win_rate <= 0 || win_rate >= 1
+
+        # Kelly formula: f = (bp - q) / b
+        # where b = avg_win/avg_loss, p = win_rate, q = 1 - win_rate
+        b = avg_win / avg_loss
+        kelly_fraction = ((b * win_rate) - (1 - win_rate)) / b
+
+        return 0 if kelly_fraction <= 0
+
+        # Apply fractional Kelly
+        adjusted_fraction = kelly_fraction * fraction
+        risk_amount = account_balance * adjusted_fraction
+        shares = (risk_amount / entry_price).floor
+
+        [shares, 0].max
+      end
+
+      # Calculate position size based on volatility (ATR-based).
+      #
+      # @param account_balance [Float] Total account balance
+      # @param risk_percent [Float] Percentage of account to risk per trade
+      # @param entry_price [Float] Planned entry price
+      # @param atr [Float] Current ATR value
+      # @param atr_multiplier [Float] Multiplier for ATR-based stop (default: 2.0)
+      # @param lot_size [Integer] Lot size for the instrument (default: 1)
+      # @return [Integer] Number of shares/lots to trade
+      def self.volatility_based(account_balance:, risk_percent:, entry_price:, atr:, atr_multiplier: 2.0, lot_size: 1)
+        return 0 if account_balance <= 0 || entry_price <= 0 || atr <= 0
+
+        stop_distance = atr * atr_multiplier
+        stop_loss_price = entry_price - stop_distance
+
+        calculate(
+          account_balance: account_balance,
+          risk_percent: risk_percent,
+          entry_price: entry_price,
+          stop_loss_price: stop_loss_price,
+          lot_size: lot_size
+        )
+      end
+    end
+
+    # Calculate stop loss and take profit levels.
+    #
+    # @example Calculate stop loss
+    #   levels = DhanHQ::Risk::SLCalculator.stop_loss(
+    #     entry_price: 2500,
+    #     risk_percent: 2.0,
+    #     atr: 50
+    #   )
+    #   #=> { fixed: 2450, atr_based: 2400 }
+    #
+    class SLCalculator
+      # Calculate fixed percentage stop loss.
+      #
+      # @param entry_price [Float] Entry price
+      # @param risk_percent [Float] Risk percentage (e.g., 2.0 for 2%)
+      # @return [Float] Stop loss price
+      def self.percentage(entry_price:, risk_percent:)
+        return 0.0 if entry_price <= 0 || risk_percent <= 0
+
+        entry_price * (1 - (risk_percent / 100.0))
+      end
+
+      # Calculate ATR-based stop loss.
+      #
+      # @param entry_price [Float] Entry price
+      # @param atr [Float] Current ATR value
+      # @param multiplier [Float] ATR multiplier (default: 2.0)
+      # @return [Float] Stop loss price
+      def self.atr_based(entry_price:, atr:, multiplier: 2.0)
+        return 0.0 if entry_price <= 0 || atr <= 0
+
+        entry_price - (atr * multiplier)
+      end
+
+      # Calculate support-based stop loss.
+      #
+      # @param entry_price [Float] Entry price
+      # @param support_levels [Array<Float>] Array of support levels
+      # @param buffer [Float] Buffer below support (default: 0.5%)
+      # @return [Float] Stop loss price (below nearest support)
+      def self.support_based(entry_price:, support_levels:, buffer: 0.005)
+        return 0.0 if entry_price <= 0 || support_levels.nil? || support_levels.empty?
+
+        # Find nearest support below entry price
+        valid_supports = support_levels.select { |s| s < entry_price }
+        return 0.0 if valid_supports.empty?
+
+        nearest_support = valid_supports.max
+        nearest_support * (1 - buffer)
+      end
+
+      # Calculate take profit based on risk-reward ratio.
+      #
+      # @param entry_price [Float] Entry price
+      # @param stop_loss_price [Float] Stop loss price
+      # @param risk_reward_ratio [Float] Desired risk:reward ratio (e.g., 2.0 for 1:2)
+      # @return [Float] Take profit price
+      def self.take_profit(entry_price:, stop_loss_price:, risk_reward_ratio: 2.0)
+        return 0.0 if entry_price <= 0 || stop_loss_price <= 0
+
+        risk = (entry_price - stop_loss_price).abs
+        entry_price + (risk * risk_reward_ratio)
+      end
+
+      # Calculate trailing stop level.
+      #
+      # @param highest_price [Float] Highest price since entry
+      # @param atr [Float] Current ATR value
+      # @param multiplier [Float] ATR multiplier (default: 2.0)
+      # @return [Float] Trailing stop price
+      def self.trailing_stop(highest_price:, atr:, multiplier: 2.0)
+        return 0.0 if highest_price <= 0 || atr <= 0
+
+        highest_price - (atr * multiplier)
+      end
+    end
+
+    # Manage trailing stop updates.
+    #
+    # @example Create trail manager
+    #   trail = DhanHQ::Risk::TrailManager.new(
+    #     entry_price: 2500,
+    #     initial_stop: 2450,
+    #     atr: 50,
+    #     trail_multiplier: 2.0
+    #   )
+    #   trail.update(2600) #=> { stop: 2500, triggered: false }
+    #
+    class TrailManager
+      attr_reader :entry_price, :initial_stop, :current_stop, :highest_price, :atr, :trail_multiplier
+
+      def initialize(entry_price:, initial_stop:, atr:, trail_multiplier: 2.0)
+        @entry_price = entry_price
+        @initial_stop = initial_stop
+        @current_stop = initial_stop
+        @highest_price = entry_price
+        @atr = atr
+        @trail_multiplier = trail_multiplier
+      end
+
+      # Update trail with new price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Hash] Hash with :stop, :highest, :triggered
+      def update(current_price)
+        return { stop: @current_stop, highest: @highest_price, triggered: false } if current_price <= 0
+
+        # Update highest price
+        @highest_price = current_price if current_price > @highest_price
+
+        # Calculate new trailing stop
+        new_stop = @highest_price - (@atr * @trail_multiplier)
+
+        # Stop can only move up, never down
+        @current_stop = new_stop if new_stop > @current_stop
+
+        # Check if stop is triggered
+        triggered = current_price <= @current_stop
+
+        {
+          stop: @current_stop,
+          highest: @highest_price,
+          triggered: triggered
+        }
+      end
+
+      # Check if stop is triggered at current price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Boolean]
+      def triggered?(current_price)
+        current_price <= @current_stop
+      end
+
+      # Calculate profit from entry to current price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Float] Profit per share
+      def profit(current_price)
+        current_price - entry_price
+      end
+
+      # Calculate profit percentage from entry to current price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Float] Profit percentage
+      def profit_percent(current_price)
+        return 0.0 if entry_price.zero?
+
+        (profit(current_price) / entry_price * 100).round(2)
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/base.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    # Base class for all trading skills.
+    #
+    # Provides a DSL for defining parameters, steps, and execution logic.
+    # Skills are stateless — context is passed through and returned.
+    #
+    # @example
+    #   class BuyAtmCall < DhanHQ::Skills::Base
+    #     param :symbol, type: :string, required: true
+    #     param :expiry, type: :string, required: true
+    #     param :quantity, type: :integer, default: 50
+    #
+    #     step :find_instrument
+    #     step :get_spot_price
+    #     step :prepare_intent
+    #
+    #     def find_instrument(ctx)
+    #       ctx[:instrument] = DhanHQ::Models::Instrument.find("IDX_I", ctx[:symbol])
+    #       ctx
+    #     end
+    #
+    #     def get_spot_price(ctx)
+    #       ctx[:spot_price] = ctx[:instrument].ltp
+    #       ctx
+    #     end
+    #
+    #     def prepare_intent(ctx)
+    #       ctx[:intent] = { symbol: ctx[:symbol], spot: ctx[:spot_price] }
+    #       ctx
+    #     end
+    #   end
+    #
+    class Base
+      class << self
+        # Define a parameter for this skill.
+        #
+        # @param name [Symbol] parameter name
+        # @param type [Symbol] :string, :integer, :number, :boolean
+        # @param required [Boolean] whether the parameter is required
+        # @param default [Object] default value if not provided
+        def param(name, type: :string, required: false, default: nil, description: nil)
+          @params ||= {}
+          @params[name] = { type: type, required: required, default: default, description: description }
+        end
+
+        # Define a step in the skill execution sequence.
+        #
+        # @param name [Symbol] method name to call
+        # @param priority [Integer] execution order (lower = earlier)
+        def step(name, priority: 10)
+          @steps ||= []
+          @steps << { name: name, priority: priority }
+          @steps.sort_by! { |s| s[:priority] }
+        end
+
+        # MCP risk level for this skill (defaults to the most conservative tier
+        # so a skill that forgets to declare one fails safe/write-gated).
+        #
+        # @param level [String, nil] one of read_only, trade_adjacent_read, live_write, destructive_write
+        def risk(level = nil)
+          level ? (@risk = level) : (@risk || "destructive_write")
+        end
+
+        # MCP policy scope required to invoke this skill.
+        #
+        # @param value [String, nil] e.g. "orders:read", "orders:write"
+        def scope(value = nil)
+          value ? (@scope = value) : (@scope || "orders:write")
+        end
+
+        # Human-readable description shown to MCP/LLM clients in tools/list.
+        #
+        # @param text [String, nil] one-line summary of what the skill does
+        def description(text = nil)
+          text ? (@description = text) : @description
+        end
+
+        # Accessor for defined parameters.
+        def params
+          @params || {}
+        end
+
+        # Accessor for defined steps.
+        def steps
+          @steps || []
+        end
+
+        # Validate that all required parameters are present.
+        #
+        # @param args [Hash] provided parameters
+        # @raise [ArgumentError] if required parameters are missing
+        def validate_params!(args)
+          params.each do |name, config|
+            next unless config[:required]
+
+            value = args[name] || args[name.to_s]
+            next unless value.nil?
+
+            raise ArgumentError, "Missing required parameter: #{name}"
+          end
+        end
+      end
+
+      # Execute the skill with the given arguments.
+      #
+      # @param args [Hash] skill parameters (symbol or string keys)
+      # @return [Hash] context with all accumulated state
+      # @raise [ArgumentError] if required parameters are missing
+      def call(args = {})
+        ctx = build_context(args)
+        self.class.validate_params!(ctx)
+
+        self.class.steps.each do |step|
+          result = send(step[:name], ctx)
+          ctx = result if result.is_a?(Hash)
+        end
+
+        ctx
+      end
+
+      # Skill name (defaults to class name).
+      def name
+        self.class.name || self.class.to_s
+      end
+
+      # Skill description (declare via the class-level `description` macro; falls back to class name).
+      def description
+        self.class.description || self.class.to_s
+      end
+
+      # List of parameter definitions for this skill.
+      def param_definitions
+        self.class.params
+      end
+
+      private
+
+      # Real DhanHQ::Models::OptionChain#fetch shape: { last_price:, strikes: [{ strike:, call: {...}, put: {...} }] }.
+      # Nearest strike to a target price — always returns an entry (never nil) unless the chain is empty.
+      def nearest_strike(chain, target_price)
+        strikes = chain[:strikes]
+        return nil if strikes.nil? || strikes.empty?
+
+        strikes.min_by { |s| (s[:strike].to_f - target_price.to_f).abs }
+      end
+
+      # Exact strike match within tolerance — nil if no strike sits on that price.
+      def find_strike(chain, target_price, tolerance: 0.001)
+        strikes = chain[:strikes]
+        return nil if strikes.nil? || strikes.empty?
+
+        strikes.find { |s| (s[:strike].to_f - target_price.to_f).abs < tolerance }
+      end
+
+      def leg_side(strike_entry, option_type)
+        option_type == "CE" ? strike_entry[:call] : strike_entry[:put]
+      end
+
+      def leg_security_id(strike_entry, option_type)
+        leg_side(strike_entry, option_type)[:security_id]
+      end
+
+      def leg_premium(strike_entry, option_type)
+        leg_side(strike_entry, option_type)[:last_price]
+      end
+
+      def build_context(args)
+        ctx = {}
+
+        self.class.params.each do |name, config|
+          value = args[name] || args[name.to_s]
+          value = config[:default] if value.nil? && config[:default]
+          ctx[name] = value
+        end
+
+        ctx
+      end
+    end
+  end
+end