DhanHQ 3.0.0 → 3.0.1

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 = "3.0.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"

data/lib/dhan_hq/agent.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../DhanHQ/agent"

data/lib/dhan_hq/mcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../DhanHQ/mcp"

data/lib/dhan_hq.rb

@@ -38,10 +38,35 @@ module DhanHQ
   LOADER.collapse(File.join(__dir__, "DhanHQ", "helpers"))
   LOADER.ignore(
     File.join(__dir__, "DhanHQ", "errors.rb"),
-    File.join(__dir__, "DhanHQ", "version.rb")
+    File.join(__dir__, "DhanHQ", "version.rb"),
+    File.join(__dir__, "DhanHQ", "risk.rb")
   )
   LOADER.setup
 
+  # Eager-load risk utilities (PositionSizer, SLCalculator, TrailManager)
+  # and the pre-execution risk pipeline so they are available immediately.
+  require_relative "DhanHQ/risk"
+  require_relative "DhanHQ/risk/checks/trading_permission"
+  require_relative "DhanHQ/risk/checks/asm_gsm"
+  require_relative "DhanHQ/risk/checks/product_support"
+  require_relative "DhanHQ/risk/checks/order_type"
+  require_relative "DhanHQ/risk/checks/quantity"
+  require_relative "DhanHQ/risk/checks/market_hours"
+  require_relative "DhanHQ/risk/checks/options"
+  require_relative "DhanHQ/risk/pipeline"
+
+  # Skills layer: multi-step trading workflows
+  require_relative "DhanHQ/skills"
+  require_relative "DhanHQ/skills/base"
+  require_relative "DhanHQ/skills/registry"
+  require_relative "DhanHQ/skills/workflow"
+  require_relative "DhanHQ/skills/builtin/buy_atm_call"
+  require_relative "DhanHQ/skills/builtin/square_off_all"
+  require_relative "DhanHQ/skills/builtin/square_off_position"
+  require_relative "DhanHQ/skills/builtin/iron_condor"
+  require_relative "DhanHQ/skills/builtin/strangle"
+  DhanHQ::Skills::Registry.load_builtins
+
   class Error < StandardError; end
 
   class << self
@@ -131,7 +156,7 @@ module DhanHQ
 
       url = "#{base_url.to_s.chomp("/")}/auth/dhan/token"
       conn = ::Faraday.new(url: url) do |c|
-        c.response :json, content_type: /\bjson$/
+        c.request :url_encoded
         c.adapter ::Faraday.default_adapter
       end
 

data/lib/ta/technical_analysis.rb

@@ -125,7 +125,9 @@ module TA
     def normalize_from_date(from_date, to_date, days_back)
       if (from_date.nil? || from_date.to_s.strip.empty?) && days_back&.to_i&.positive?
         to_d = Date.parse(to_date)
-        n_back = [days_back.to_i - 1, 0].max
+        # Dhan historical API to_date is non-inclusive. To get N trading days,
+        # we must go back N trading days from the non-inclusive to_date.
+        n_back = days_back.to_i
         return MarketCalendar.trading_days_ago(to_d, n_back).strftime("%Y-%m-%d")
       end
       if from_date && !from_date.to_s.strip.empty?

data/skills/dhanhq-ruby/SKILL.md

@@ -0,0 +1,74 @@
+# DhanHQ Ruby SDK Skill
+
+Use this skill when an agent needs to write, review, or operate Ruby code using the `DhanHQ` gem.
+
+## Safety rules
+
+- Prefer read-only tools and SDK calls unless the user explicitly asks to trade.
+- Resolve instruments before trading with `DhanHQ::Models::Instrument.search` and use the returned `security_id` plus `exchange_segment`.
+- Preview every order with `DhanHQ::Agent::OrderPreview` before any live order placement.
+- Never place, modify, or cancel orders unless both `DHANHQ_MCP_ENABLE_WRITES=true` and `LIVE_TRADING=true` are set and the user has clearly confirmed the action.
+- Include a `correlation_id` for every agent-originated order.
+- Do not ask for or print access tokens.
+
+## Setup
+
+```ruby
+require "dhan_hq"
+require "dhan_hq/agent"
+
+DhanHQ.configure_with_env
+```
+
+Required environment variables:
+
+- `DHAN_CLIENT_ID`
+- `DHAN_ACCESS_TOKEN`
+
+Optional agent variables:
+
+- `DHANHQ_AGENT_SCOPES`, comma-separated scopes such as `portfolio:read,market:read,orders:read`
+- `DHANHQ_MCP_ENABLE_WRITES=true` for agent write tools
+- `LIVE_TRADING=true` for any live trading write
+
+## Common calls
+
+```ruby
+DhanHQ::Models::Profile.fetch
+DhanHQ::Models::Funds.fetch
+DhanHQ::Models::Holding.all
+DhanHQ::Models::Position.all
+DhanHQ::Models::Order.all
+DhanHQ::Models::Trade.today
+DhanHQ::Models::Instrument.search("RELIANCE", segments: ["NSE_EQ"], limit: 5)
+DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => ["2885"])
+```
+
+## Order preview
+
+```ruby
+preview = DhanHQ::Agent::OrderPreview.new(
+  transaction_type: "BUY",
+  exchange_segment: "NSE_EQ",
+  product_type: "INTRADAY",
+  order_type: "MARKET",
+  validity: "DAY",
+  security_id: "2885",
+  quantity: 1,
+  correlation_id: "agent-20260702-001"
+)
+
+preview.to_h
+```
+
+## MCP server
+
+The gem includes a stdio MCP executable:
+
+```bash
+dhanhq-mcp
+```
+
+Start with read-only scopes. Add write scopes only for explicitly confirmed trading sessions.
+
+See the references directory for focused workflows.

data/skills/dhanhq-ruby/references/market_data.md

@@ -0,0 +1,3 @@
+# Market data with agents
+
+Use `DhanHQ::Models::Instrument.search` to resolve a query to Dhan security IDs, then call `DhanHQ::Models::MarketFeed.ltp`, `.ohlc`, or `.quote` with an exchange-segment keyed payload.

data/skills/dhanhq-ruby/references/orders.md

@@ -0,0 +1,7 @@
+# Orders with agents
+
+1. Search or otherwise verify the instrument.
+2. Build order params using Dhan constants and API docs.
+3. Run `DhanHQ::Agent::OrderPreview.new(params).to_h`.
+4. Ask the user to confirm the preview.
+5. Place only if `DHANHQ_MCP_ENABLE_WRITES=true`, `LIVE_TRADING=true`, and `orders:write` scope are present.