DhanHQ 3.0.0 → 3.1.0

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a protective put strategy (buy stock, buy OTM put).
+      #
+      # Steps: find instrument → spot price → option chain →
+      # select OTM put → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("protective_put",
+      #     symbol: "RELIANCE",
+      #     expiry: "2026-01-30",
+      #     quantity: 100
+      #   )
+      #
+      class ProtectivePut < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a protective put: buy the underlying equity, buy an OTM put as downside insurance."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 100
+        param :strike_offset, type: :number, default: 2.0
+        param :max_premium_pct, type: :number, default: 3.0
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_otm_put, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::NSE_EQ, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_otm_put(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+          offset_pct = ctx[:strike_offset] / 100.0
+          max_prem = ctx[:max_premium_pct] / 100.0
+
+          target_strike = spot * (1 - offset_pct)
+          otm_put = nearest_strike(chain, target_strike)
+
+          raise ArgumentError, "Could not find suitable OTM put strike near #{target_strike}" unless otm_put
+
+          premium = leg_premium(otm_put, "PE").to_f
+          premium_pct = premium / spot
+
+          raise ArgumentError, "Put premium #{premium_pct * 100}% exceeds max #{ctx[:max_premium_pct]}%" if premium_pct > max_prem
+
+          ctx[:put_strike] = otm_put[:strike]
+          ctx[:put_security_id] = leg_security_id(otm_put, "PE")
+          ctx[:put_premium] = premium
+          ctx[:equity_security_id] = ctx[:instrument].security_id
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "PROTECTIVE_PUT",
+            symbol: ctx[:symbol],
+            quantity: ctx[:quantity],
+            legs: [
+              { action: DhanHQ::Constants::TransactionType::BUY, instrument_type: DhanHQ::Constants::InstrumentType::EQUITY, security_id: ctx[:equity_security_id],
+                quantity: ctx[:quantity] },
+              { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: ctx[:put_strike], security_id: ctx[:put_security_id], quantity: ctx[:quantity], premium: ctx[:put_premium] }
+            ],
+            note: "Protective put prepared: Buy #{ctx[:quantity]} #{ctx[:symbol]}, Buy #{ctx[:quantity]} #{ctx[:put_strike]} PE. Await human confirmation."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to exit all open positions at market price.
+      #
+      # Steps: fetch positions → exit each position → summarize results.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("square_off_all")
+      #   puts result[:exited_count]
+      #
+      class SquareOffAll < Base
+        risk "destructive_write"
+        scope "orders:write"
+        description "Exit all open positions at market price."
+
+        step :fetch_positions, priority: 1
+        step :exit_positions, priority: 2
+
+        def fetch_positions(ctx)
+          ctx[:positions] = DhanHQ::Models::Position.all.reject { |p| p.net_qty.to_i.zero? }
+          ctx
+        end
+
+        def exit_positions(ctx)
+          results = ctx[:positions].map do
+            DhanHQ::Models::Position.exit_all!
+          rescue StandardError => e
+            { error: e.message }
+          end
+
+          ctx[:exit_results] = results
+          ctx[:exited_count] = results.count { |r| !(r.is_a?(Hash) && r.key?(:error)) }
+          ctx[:failed_count] = results.count { |r| r.is_a?(Hash) && r.key?(:error) }
+          ctx
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# 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
+        risk "destructive_write"
+        scope "orders:write"
+        description "Exit a specific open position by symbol and exchange segment."
+
+        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|
+            p.exchange_segment.to_s == ctx[:exchange_segment].to_s && p.trading_symbol.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
+          ctx[:trading_symbol] = target.trading_symbol
+          ctx[:net_quantity] = target.net_qty.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/straddle.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a long straddle (buy ATM call + buy ATM put).
+      #
+      # Steps: find instrument → spot price → option chain →
+      # select ATM strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("straddle",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 25
+      #   )
+      #
+      class Straddle < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a long straddle: buy ATM call + buy ATM put at the same strike."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 25
+        param :stop_loss, type: :number, default: 300
+        param :target, type: :number, default: 600
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_atm_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)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_atm_strikes(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+
+          atm = nearest_strike(chain, spot)
+          raise ArgumentError, "Could not find ATM strike" unless atm
+
+          ctx[:atm_strike] = atm[:strike]
+          ctx[:ce_security_id] = leg_security_id(atm, "CE")
+          ctx[:pe_security_id] = leg_security_id(atm, "PE")
+          ctx[:ce_premium] = leg_premium(atm, "CE")
+          ctx[:pe_premium] = leg_premium(atm, "PE")
+          ctx[:total_premium] = ctx[:ce_premium].to_f + ctx[:pe_premium].to_f
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "STRADDLE",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            legs: [
+              { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: ctx[:atm_strike], security_id: ctx[:ce_security_id], premium: ctx[:ce_premium] },
+              { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: ctx[:atm_strike], security_id: ctx[:pe_security_id], premium: ctx[:pe_premium] }
+            ],
+            total_premium: ctx[:total_premium],
+            break_even_upside: ctx[:atm_strike].to_f + ctx[:total_premium],
+            break_even_downside: ctx[:atm_strike].to_f - ctx[:total_premium],
+            stop_loss: ctx[:stop_loss],
+            target: ctx[:target],
+            note: "Long straddle prepared. Await human confirmation."
+          }
+          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
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a long strangle: buy OTM call + buy OTM put around the current spot price."
+
+        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)
+          ctx[:spot_price] = ctx[:instrument].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_strike = spot * (1 + offset)
+          pe_strike = spot * (1 - offset)
+
+          long_ce = nearest_strike(chain, ce_strike)
+          long_pe = nearest_strike(chain, pe_strike)
+
+          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]
+          ctx[:pe_strike] = long_pe[:strike]
+          ctx[:ce_security_id] = leg_security_id(long_ce, "CE")
+          ctx[:pe_security_id] = leg_security_id(long_pe, "PE")
+          ctx[:ce_premium] = leg_premium(long_ce, "CE")
+          ctx[:pe_premium] = leg_premium(long_pe, "PE")
+          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