DhanHQ 3.0.0 → 3.0.1

data/lib/DhanHQ/skills/base.rb

@@ -0,0 +1,132 @@
+# 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[: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
+
+        # 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 (override in subclasses).
+      def description
+        self.class.to_s
+      end
+
+      # List of parameter definitions for this skill.
+      def param_definitions
+        self.class.params
+      end
+
+      private
+
+      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

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to buy an ATM call option on an index.
+      #
+      # Steps: find instrument → get spot price → get option chain →
+      # select ATM strike → prepare trade intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("buy_atm_call",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50
+      #   )
+      #   puts result[:intent]
+      #
+      class BuyAtmCall < Base
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :stop_loss, type: :number, default: 100
+        param :target, type: :number, default: 200
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_atm_strike, priority: 4
+        step :prepare_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_atm_strike(ctx)
+          spot = ctx[:spot_price]
+          chain = ctx[:chain]
+
+          ce_options = chain.select do |opt|
+            opt[:option_type] == "CE" || opt["optionType"] == "CE"
+          end
+
+          atm = ce_options.min_by do |opt|
+            strike = opt[:strike] || opt["strike"]
+            (strike.to_f - spot).abs
+          end
+
+          ctx[:selected_option] = atm
+          ctx[:security_id] = atm[:security_id] || atm["securityId"]
+          ctx[:strike] = atm[:strike] || atm["strike"]
+          ctx[:premium] = atm[:last_price] || atm["lastPrice"] || atm[:ltp] || atm["ltp"]
+          ctx
+        end
+
+        def prepare_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "OPTIONS_BUY",
+            instrument: "#{ctx[:symbol]} #{ctx[:strike]} CE",
+            security_id: ctx[:security_id],
+            strike: ctx[:strike],
+            expiry: ctx[:expiry],
+            option_type: "CE",
+            quantity: ctx[:quantity],
+            premium: ctx[:premium],
+            stop_loss: ctx[:stop_loss],
+            target: ctx[:target],
+            note: "Prepared ATM call buy. Await human confirmation."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build an iron condor strategy (sell OTM CE + PE, buy further OTM CE + PE).
+      #
+      # Steps: find instrument → spot price → option chain → select strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("iron_condor",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50,
+      #     wing_width: 200
+      #   )
+      #
+      class IronCondor < Base
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :wing_width, type: :number, default: 200
+        param :max_loss, type: :number, default: 5000
+
+        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]
+          chain = ctx[:chain]
+          wing = ctx[:wing_width]
+
+          ce_options = chain.select { |o| (o[:option_type] || o["optionType"]) == "CE" }
+                            .sort_by { |o| (o[:strike] || o["strike"]).to_f }
+          pe_options = chain.select { |o| (o[:option_type] || o["optionType"]) == "PE" }
+                            .sort_by { |o| (o[:strike] || o["strike"]).to_f }
+
+          atm = ce_options.min_by { |o| (o[:strike] || o["strike"]).to_f - spot.to_f }
+
+          atm_strike = (atm[:strike] || atm["strike"]).to_f
+
+          short_ce = ce_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike + wing)).abs < 0.001 }
+          long_ce = ce_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike + (wing * 2))).abs < 0.001 }
+          short_pe = pe_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike - wing)).abs < 0.001 }
+          long_pe = pe_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike - (wing * 2))).abs < 0.001 }
+
+          raise ArgumentError, "Could not build iron condor — insufficient strikes in chain" unless short_ce && long_ce && short_pe && long_pe
+
+          ctx[:legs] = [
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "CE", strike: atm_strike + wing, security_id: short_ce[:security_id] || short_ce["securityId"] },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: atm_strike + (wing * 2), security_id: long_ce[:security_id] || long_ce["securityId"] },
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "PE", strike: atm_strike - wing, security_id: short_pe[:security_id] || short_pe["securityId"] },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: atm_strike - (wing * 2), security_id: long_pe[:security_id] || long_pe["securityId"] }
+          ]
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "IRON_CONDOR",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            wing_width: ctx[:wing_width],
+            max_loss: ctx[:max_loss],
+            legs: ctx[:legs],
+            note: "Iron condor prepared. Await human confirmation before execution."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# 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
+        step :fetch_positions, priority: 1
+        step :exit_positions, priority: 2
+
+        def fetch_positions(ctx)
+          ctx[:positions] = DhanHQ::Models::Position.all.reject do |p|
+            qty = begin
+              p[:net_quantity] || p["netQuantity"] || p.net_quantity
+            rescue StandardError
+              0
+            end
+            qty.to_i.zero?
+          end
+          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,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