DhanHQ 2.8.0 → 3.0.1

data/lib/DhanHQ/skills/builtin/square_off_position.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to exit a specific position by symbol.
+      #
+      # Steps: find position → exit position → return result.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("square_off_position",
+      #     symbol: "NIFTY",
+      #     exchange_segment: "IDX_I"
+      #   )
+      #
+      class SquareOffPosition < Base
+        param :symbol, type: :string, required: true
+        param :exchange_segment, type: :string, required: true
+
+        step :find_position, priority: 1
+        step :exit_position, priority: 2
+
+        def find_position(ctx)
+          positions = DhanHQ::Models::Position.all
+          target = positions.find do |p|
+            seg = p[:exchange_segment] || p["exchange_segment"]
+            sym = p[:trading_symbol] || p["tradingSymbol"] || p[:symbol] || p["symbol"]
+            seg.to_s == ctx[:exchange_segment].to_s && sym.to_s.upcase == ctx[:symbol].to_s.upcase
+          end
+
+          raise ArgumentError, "No open position found for #{ctx[:symbol]} on #{ctx[:exchange_segment]}" unless target
+
+          ctx[:position] = target
+          ctx[:security_id] = target[:security_id] || target["securityId"]
+          ctx[:trading_symbol] = target[:trading_symbol] || target["tradingSymbol"]
+          ctx[:net_quantity] = (target[:net_quantity] || target["netQuantity"] || target.net_quantity).to_i
+          ctx
+        end
+
+        def exit_position(ctx)
+          ctx[:exit_result] = DhanHQ::Models::Position.exit_all!
+          ctx[:exited] = true
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/builtin/strangle.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a long strangle (buy OTM CE + buy OTM PE).
+      #
+      # Steps: find instrument → spot price → option chain → select strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("strangle",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50,
+      #     offset_pct: 1.0
+      #   )
+      #
+      class Strangle < Base
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :offset_pct, type: :number, default: 1.0
+        param :stop_loss, type: :number, default: 200
+        param :target, type: :number, default: 400
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_strikes, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ltp = ctx[:instrument].ltp
+          ctx[:spot_price] = ltp[:ltp] || ltp["ltp"]
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_strikes(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+          offset = ctx[:offset_pct] / 100.0
+
+          ce_options = chain.select { |o| (o[:option_type] || o["optionType"]) == "CE" }
+          pe_options = chain.select { |o| (o[:option_type] || o["optionType"]) == "PE" }
+
+          ce_strike = spot * (1 + offset)
+          pe_strike = spot * (1 - offset)
+
+          long_ce = ce_options.min_by { |o| ((o[:strike] || o["strike"]).to_f - ce_strike).abs }
+          long_pe = pe_options.min_by { |o| ((o[:strike] || o["strike"]).to_f - pe_strike).abs }
+
+          raise ArgumentError, "Could not find suitable CE strike near #{ce_strike}" unless long_ce
+          raise ArgumentError, "Could not find suitable PE strike near #{pe_strike}" unless long_pe
+
+          ctx[:ce_strike] = long_ce[:strike] || long_ce["strike"]
+          ctx[:pe_strike] = long_pe[:strike] || long_pe["strike"]
+          ctx[:ce_security_id] = long_ce[:security_id] || long_ce["securityId"]
+          ctx[:pe_security_id] = long_pe[:security_id] || long_pe["securityId"]
+          ctx[:ce_premium] = long_ce[:last_price] || long_ce["lastPrice"] || long_ce[:ltp]
+          ctx[:pe_premium] = long_pe[:last_price] || long_pe["lastPrice"] || long_pe[:ltp]
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "STRANGLE",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            legs: [
+              { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: ctx[:ce_strike], security_id: ctx[:ce_security_id], premium: ctx[:ce_premium] },
+              { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: ctx[:pe_strike], security_id: ctx[:pe_security_id], premium: ctx[:pe_premium] }
+            ],
+            stop_loss: ctx[:stop_loss],
+            target: ctx[:target],
+            note: "Long strangle prepared. Await human confirmation."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/registry.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    # Registry for skill definitions.
+    #
+    # Maps skill names to their classes. Skills are registered explicitly
+    # or discovered via conventions.
+    #
+    # @example Register a skill
+    #   DhanHQ::Skills::Registry.register("buy_atm_call", BuyAtmCall)
+    #
+    # @example Find a skill
+    #   skill = DhanHQ::Skills::Registry.find("buy_atm_call")
+    #   result = skill.call(symbol: "NIFTY", expiry: "2026-01-30")
+    #
+    class Registry
+      class << self
+        # Register a skill class by name.
+        #
+        # @param name [String] skill name
+        # @param klass [Class] skill class inheriting from Base
+        # @raise [ArgumentError] if the class is not a Base subclass
+        def register(name, klass)
+          raise ArgumentError, "Skill class must inherit from DhanHQ::Skills::Base" unless klass < Base
+
+          skills[name.to_s] = klass
+        end
+
+        # Find a skill by name.
+        #
+        # @param name [String] skill name
+        # @return [Class] the skill class
+        # @raise [KeyError] if skill is not found
+        def find(name)
+          skills.fetch(name.to_s) { raise KeyError, "Unknown skill: #{name}" }
+        end
+
+        # Execute a skill by name with the given arguments.
+        #
+        # @param name [String] skill name
+        # @param args [Hash] skill parameters
+        # @return [Hash] context with all accumulated state
+        def call(name, args = {})
+          find(name).new.call(args)
+        end
+
+        # List all registered skill names.
+        #
+        # @return [Array<String>]
+        def names
+          skills.keys.sort
+        end
+
+        # List all registered skills with metadata.
+        #
+        # @return [Array<Hash>]
+        def list
+          skills.map do |name, klass|
+            instance = klass.new
+            {
+              name: name,
+              description: instance.description,
+              params: instance.param_definitions,
+              steps: klass.steps.map { |s| s[:name] }
+            }
+          end
+        end
+
+        # Clear all registered skills (for testing).
+        def clear!
+          @skills = {}
+        end
+
+        # Load built-in skills from the builtin directory and register them.
+        def load_builtins
+          Dir[File.join(__dir__, "builtin", "*.rb")].each do |file|
+            require file
+          end
+
+          # Auto-register any Builtin classes that inherit from Base
+          DhanHQ::Skills::Builtin.constants.each do |const_name|
+            klass = DhanHQ::Skills::Builtin.const_get(const_name)
+            next unless klass.is_a?(Class) && klass < Base
+
+            name = const_name.to_s
+                             .gsub(/([a-z])([A-Z])/, '\1_\2')
+                             .downcase
+            register(name, klass) unless skills.key?(name)
+          end
+        end
+
+        private
+
+        def skills
+          @skills ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/workflow.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    # Workflow orchestrates multi-step skill execution with branching and error handling.
+    #
+    # A workflow is a sequence of steps that can succeed, fail, or branch
+    # based on the result of each step.
+    #
+    # @example Define a workflow
+    #   workflow = DhanHQ::Skills::Workflow.new do
+    #     step :check_funds do |ctx|
+    #       funds = DhanHQ::Models::Funds.fetch
+    #       ctx[:available_balance] = funds[:available_balance]
+    #       ctx
+    #     end
+    #
+    #     step :validate_margin do |ctx|
+    #       raise "Insufficient margin" if ctx[:available_balance] < 10_000
+    #       ctx
+    #     end
+    #
+    #     step :place_order do |ctx|
+    #       ctx[:order] = DhanHQ::Models::Order.place(ctx[:order_params])
+    #       ctx
+    #     end
+    #   end
+    #
+    #   result = workflow.call(order_params: { ... })
+    #
+    class Workflow
+      Step = Struct.new(:name, :block, :priority)
+
+      attr_reader :name, :steps
+
+      def initialize(name: "workflow", &block)
+        @name = name
+        @steps = []
+        instance_eval(&block) if block
+      end
+
+      # Define a step in the workflow.
+      #
+      # @param name [Symbol] step name
+      # @param priority [Integer] execution order (lower = earlier)
+      # @param block [Proc] step implementation
+      def step(name, priority: 10, &block)
+        @steps << Step.new(name, block, priority)
+        @steps.sort_by!(&:priority)
+      end
+
+      # Execute the workflow with the given context.
+      #
+      # @param ctx [Hash] initial context
+      # @return [Hash] final context after all steps
+      # @raise [RuntimeError] if any step fails
+      def call(ctx = {})
+        @steps.each do |step|
+          result = step.block.call(ctx)
+          ctx = result if result.is_a?(Hash)
+        end
+        ctx
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Multi-step trading workflows built on top of MCP tools.
+  #
+  # Skills compose individual tool calls into reusable trading strategies.
+  # Each skill defines a sequence of steps that execute in order, with
+  # context passed between steps.
+  #
+  # @example Define a custom skill
+  #   class MySkill < DhanHQ::Skills::Base
+  #     param :symbol, type: :string, required: true
+  #     param :quantity, type: :integer, default: 1
+  #
+  #     step :find_instrument
+  #     step :place_order
+  #
+  #     def find_instrument(ctx)
+  #       ctx[:instrument] = DhanHQ::Models::Instrument.find("NSE_EQ", ctx[:symbol])
+  #     end
+  #
+  #     def place_order(ctx)
+  #       DhanHQ::Models::Order.place(security_id: ctx[:instrument].security_id, quantity: ctx[:quantity])
+  #     end
+  #   end
+  #
+  module Skills
+  end
+end

data/lib/DhanHQ/strategy/base.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Strategy framework for building and backtesting trading strategies.
+  #
+  # Provides a DSL for defining entry/exit rules, risk management,
+  # and signal generation.
+  #
+  # @example Define a simple strategy
+  #   class MyStrategy < DhanHQ::Strategy::Base
+  #     entry_rule :golden_cross do |data|
+  #       data.sma(20).last > data.sma(50).last &&
+  #         data.sma(20).last(2) <= data.sma(50).last(2)
+  #     end
+  #
+  #     exit_rule :death_cross do |data|
+  #       data.sma(20).last < data.sma(50).last
+  #     end
+  #   end
+  #
+  module Strategy
+    # Signal represents a trading signal generated by a strategy.
+    #
+    # @attr_reader [Symbol] type Signal type (:buy, :sell, :hold)
+    # @attr_reader [Float] strength Signal strength (0.0 to 1.0)
+    # @attr_reader [Hash] metadata Additional signal metadata
+    Signal = Struct.new(:type, :strength, :metadata) do
+      def buy?
+        type == :buy
+      end
+
+      def sell?
+        type == :sell
+      end
+
+      def hold?
+        type == :hold
+      end
+
+      def to_prompt
+        parts = ["signal=#{type}", "strength=#{strength}"]
+        parts << "reason=#{metadata[:reason]}" if metadata[:reason]
+        parts.join(", ")
+      end
+    end
+
+    # Base class for all strategies.
+    #
+    # Provides DSL for defining entry/exit rules and risk management.
+    class Base
+      attr_reader :name, :params, :position
+
+      def initialize(name: self.class.name, params: {})
+        @name = name
+        @params = params
+        @position = nil
+        @entry_rules = {}
+        @exit_rules = {}
+        @risk_rules = {}
+        @signals = []
+      end
+
+      # Define an entry rule.
+      #
+      # @param name [Symbol] Rule name
+      # @param priority [Integer] Rule priority (lower = higher priority)
+      # @param block [Proc] Rule condition block
+      def self.entry_rule(name, priority: 10, &block)
+        @entry_rules ||= {}
+        @entry_rules[name] = { priority: priority, block: block }
+      end
+
+      # Define an exit rule.
+      #
+      # @param name [Symbol] Rule name
+      # @param priority [Integer] Rule priority (lower = higher priority)
+      # @param block [Proc] Rule condition block
+      def self.exit_rule(name, priority: 10, &block)
+        @exit_rules ||= {}
+        @exit_rules[name] = { priority: priority, block: block }
+      end
+
+      # Define a risk rule.
+      #
+      # @param name [Symbol] Rule name
+      # @param block [Proc] Risk check block
+      def self.risk_rule(name, &block)
+        @risk_rules ||= {}
+        @risk_rules[name] = block
+      end
+
+      # Get all entry rules for this strategy class.
+      def self.entry_rules
+        @entry_rules || {}
+      end
+
+      # Get all exit rules for this strategy class.
+      def self.exit_rules
+        @exit_rules || {}
+      end
+
+      # Get all risk rules for this strategy class.
+      def self.risk_rules
+        @risk_rules || {}
+      end
+
+      # Evaluate entry rules against market data.
+      #
+      # @param data [DhanHQ::MarketData::OHLCSeries] Market data series
+      # @return [DhanHQ::Strategy::Signal] Generated signal
+      def evaluate_entry(data)
+        sorted_rules = self.class.entry_rules.sort_by { |_, v| v[:priority] }
+
+        sorted_rules.each do |rule_name, rule|
+          result = rule[:block].call(data, params)
+          next unless result
+
+          signal = Signal.new(
+            type: :buy,
+            strength: calculate_strength(result),
+            metadata: { rule: rule_name, data: data }
+          )
+          @signals << signal
+          return signal
+        end
+
+        Signal.new(type: :hold, strength: 0.0, metadata: { reason: :no_entry_signal })
+      end
+
+      # Evaluate exit rules against market data.
+      #
+      # @param data [DhanHQ::MarketData::OHLCSeries] Market data series
+      # @return [DhanHQ::Strategy::Signal] Generated signal
+      def evaluate_exit(data)
+        sorted_rules = self.class.exit_rules.sort_by { |_, v| v[:priority] }
+
+        sorted_rules.each do |rule_name, rule|
+          result = rule[:block].call(data, params)
+          next unless result
+
+          signal = Signal.new(
+            type: :sell,
+            strength: calculate_strength(result),
+            metadata: { rule: rule_name, data: data }
+          )
+          @signals << signal
+          return signal
+        end
+
+        Signal.new(type: :hold, strength: 0.0, metadata: { reason: :no_exit_signal })
+      end
+
+      # Check all risk rules.
+      #
+      # @param context [Hash] Risk check context
+      # @return [Array<Symbol>] List of violated rule names
+      def check_risks(context)
+        violations = []
+
+        self.class.risk_rules.each do |rule_name, block|
+          result = block.call(context, params)
+          violations << rule_name unless result
+        end
+
+        violations
+      end
+
+      # Get all signals generated by this strategy.
+      def signals
+        @signals.dup
+      end
+
+      # Get the last signal.
+      def last_signal
+        @signals.last
+      end
+
+      private
+
+      def calculate_strength(result)
+        case result
+        when true then 1.0
+        when Numeric then result.clamp(0.0, 1.0)
+        else 0.5
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/strategy.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "strategy/base"
+
+module DhanHQ
+  # Strategy framework for building and backtesting trading strategies.
+  #
+  # Provides a DSL for defining entry/exit rules, risk management,
+  # and signal generation.
+  #
+  # @example Define a simple strategy
+  #   class GoldenCross < DhanHQ::Strategy::Base
+  #     entry_rule :golden_cross do |data, _params|
+  #       sma_20 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 20)
+  #       sma_50 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 50)
+  #
+  #       sma_20.last && sma_50.last &&
+  #         sma_20.last > sma_50.last &&
+  #         sma_20[-2] && sma_50[-2] &&
+  #         sma_20[-2] <= sma_50[-2]
+  #     end
+  #
+  #     exit_rule :death_cross do |data, _params|
+  #       sma_20 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 20)
+  #       sma_50 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 50)
+  #
+  #       sma_20.last && sma_50.last && sma_20.last < sma_50.last
+  #     end
+  #
+  #     risk_rule :max_drawdown do |context, _params|
+  #       context[:drawdown].abs < 0.1
+  #     end
+  #   end
+  #
+  #   strategy = GoldenCross.new
+  #   signal = strategy.evaluate_entry(data)
+  #
+  module Strategy
+  end
+end

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "2.8.0"
+  VERSION = "3.0.1"
 end

data/lib/DhanHQ/ws/decoder.rb

@@ -26,21 +26,45 @@ module DhanHQ
         segstr = Segments.from_code(pkt[:exchange_segment])
         sid    = pkt[:security_id].to_s
 
-        # pp pkt
-        case kind
-        when :ticker
+        dispatch(pkt, kind, segstr, sid)
+      rescue StandardError => e
+        DhanHQ.logger&.debug("[DhanHQ::WS::Decoder] #{e.class}: #{e.message}")
+        nil
+      end
+
+      class << self
+        private
+
+        def dispatch(pkt, kind, segstr, sid)
+          case kind
+          when :ticker      then decode_ticker(pkt, segstr, sid)
+          when :quote       then decode_quote(pkt, segstr, sid)
+          when :full        then decode_full(pkt, segstr, sid)
+          when :oi          then decode_oi(pkt, segstr, sid)
+          when :prev_close  then decode_prev_close(pkt, segstr, sid)
+          when :depth_bid, :depth_ask then decode_depth(pkt, kind, segstr, sid)
+          when :disconnect then handle_disconnect(pkt, segstr, sid)
+          else handle_unknown(pkt)
+          end
+        end
+
+        def decode_ticker(pkt, segstr, sid)
           {
             kind: :ticker, segment: segstr, security_id: sid,
             ltp: pkt[:ltp].to_f, ts: pkt[:ltt]&.to_i
           }
-        when :quote
+        end
+
+        def decode_quote(pkt, segstr, sid)
           {
             kind: :quote, segment: segstr, security_id: sid,
             ltp: pkt[:ltp].to_f, ts: pkt[:ltt]&.to_i, atp: pkt[:atp].to_f,
             vol: pkt[:volume].to_i, ts_buy_qty: pkt[:total_buy_qty].to_i, ts_sell_qty: pkt[:total_sell_qty].to_i,
             day_open: pkt[:day_open]&.to_f, day_high: pkt[:day_high]&.to_f, day_low: pkt[:day_low]&.to_f, day_close: pkt[:day_close]&.to_f
           }
-        when :full
+        end
+
+        def decode_full(pkt, segstr, sid)
           out = {
             kind: :full, segment: segstr, security_id: sid,
             ltp: pkt[:ltp].to_f, ts: pkt[:ltt]&.to_i, atp: pkt[:atp].to_f,
@@ -48,35 +72,49 @@ module DhanHQ
             oi: pkt[:open_interest]&.to_i, oi_high: pkt[:highest_open_interest]&.to_i, oi_low: pkt[:lowest_open_interest]&.to_i,
             day_open: pkt[:day_open]&.to_f, day_high: pkt[:day_high]&.to_f, day_low: pkt[:day_low]&.to_f, day_close: pkt[:day_close]&.to_f
           }
-          # First depth level (if present)
-          if (md = pkt[:market_depth]).respond_to?(:[]) && md[0]
-            lvl = md[0]
-            out[:bid] = lvl.respond_to?(:bid_price) ? lvl.bid_price.to_f : nil
-            out[:ask] = lvl.respond_to?(:ask_price) ? lvl.ask_price.to_f : nil
-          end
+          merge_depth(out, pkt[:market_depth])
           out
-        when :oi
+        end
+
+        def decode_oi(pkt, segstr, sid)
           { kind: :oi, segment: segstr, security_id: sid, oi: pkt[:open_interest].to_i }
-        when :prev_close
+        end
+
+        def decode_prev_close(pkt, segstr, sid)
           { kind: :prev_close, segment: segstr, security_id: sid, prev_close: pkt[:prev_close].to_f,
             oi_prev: pkt[:oi_prev].to_i }
-        when :depth_bid, :depth_ask
+        end
+
+        def decode_depth(pkt, kind, segstr, sid)
           {
             kind: kind, segment: segstr, security_id: sid,
             bid_quantity: pkt[:bid_quantity], ask_quantity: pkt[:ask_quantity],
             no_of_bid_orders: pkt[:no_of_bid_orders], no_of_ask_orders: pkt[:no_of_ask_orders],
             bid: pkt[:bid_price], ask: pkt[:ask_price]
           }
-        when :disconnect
+        end
+
+        def handle_disconnect(pkt, segstr, sid)
           DhanHQ.logger&.warn("[DhanHQ::WS] disconnect code=#{pkt[:disconnection_code]} seg=#{segstr} sid=#{sid}")
           nil
-        else
+        end
+
+        def handle_unknown(pkt)
           DhanHQ.logger&.debug("[DhanHQ::WS] unknown feed kind code=#{pkt[:feed_response_code]}")
           nil
         end
-      rescue StandardError => e
-        DhanHQ.logger&.debug("[DhanHQ::WS::Decoder] #{e.class}: #{e.message}")
-        nil
+
+        def merge_depth(out, market_depth)
+          return unless market_depth.respond_to?(:[]) && market_depth[0]
+
+          lvl = market_depth[0]
+          out[:bid] = lvl.respond_to?(:bid_price) ? lvl.bid_price.to_f : nil
+          out[:ask] = lvl.respond_to?(:ask_price) ? lvl.ask_price.to_f : nil
+          return unless lvl.respond_to?(:bid_quantity) && lvl.respond_to?(:ask_quantity)
+
+          out[:bid_qty] = lvl.bid_quantity.to_i
+          out[:ask_qty] = lvl.ask_quantity.to_i
+        end
       end
     end
   end

data/lib/DhanHQ.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "dhan_hq"