DhanHQ 3.0.0 → 3.1.0

data/lib/DhanHQ/market_data/option_snapshot.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module MarketData
+    # A snapshot of option chain data for a single underlying.
+    #
+    # Wraps the raw OptionChain response into a convenient structure
+    # with typed accessors and helper methods for option analysis.
+    #
+    # @example Build a snapshot from OptionChain response
+    #   response = DhanHQ::Models::OptionChain.fetch(
+    #     underlying_scrip: 13,
+    #     underlying_seg: "IDX_I",
+    #     expiry: "2024-07-25"
+    #   )
+    #   snapshot = DhanHQ::MarketData::OptionSnapshot.from_response(response)
+    #   snapshot.calls_at(24000) #=> Array of call option data
+    #   snapshot.puts_at(24000) #=> Array of put option data
+    #
+    class OptionSnapshot
+      OptionLeg = Struct.new(:strike_price, :option_type, :ltp, :bid, :ask,
+                             :volume, :open_interest, :implied_volatility,
+                             :delta, :gamma, :theta, :vega) do
+        def call?
+          option_type == DhanHQ::Constants::OptionType::CALL
+        end
+
+        def put?
+          option_type == DhanHQ::Constants::OptionType::PUT
+        end
+
+        def itm?(spot_price)
+          return false unless spot_price
+
+          call? ? strike_price < spot_price : strike_price > spot_price
+        end
+
+        def otm?(spot_price)
+          return false unless spot_price
+
+          call? ? strike_price > spot_price : strike_price < spot_price
+        end
+
+        def atm?(spot_price)
+          return false unless spot_price
+
+          (strike_price - spot_price).abs < 1
+        end
+      end
+
+      attr_reader :underlying_scrip, :underlying_seg, :expiry, :legs, :spot_price, :fetched_at
+
+      def initialize(legs = [], metadata = {})
+        @underlying_scrip = metadata[:underlying_scrip]
+        @underlying_seg = metadata[:underlying_seg]
+        @expiry = metadata[:expiry]
+        @spot_price = metadata[:spot_price]
+        @legs = legs
+        @fetched_at = Time.now
+      end
+
+      # Build an OptionSnapshot from a raw OptionChain API response.
+      def self.from_response(response)
+        data = response.is_a?(Hash) ? (response[:data] || response["data"] || response) : response
+        return new([], {}) unless data.is_a?(Hash)
+
+        legs = parse_legs(data)
+        metadata = {
+          underlying_scrip: data[:underlyingScrip] || data["underlyingScrip"],
+          underlying_seg: data[:underlyingSeg] || data["underlyingSeg"],
+          expiry: data[:expiry] || data["expiry"],
+          spot_price: data[:spot] || data["spot"]
+        }
+
+        new(legs, metadata)
+      end
+
+      # Get all call option legs.
+      def calls
+        @legs.select(&:call?)
+      end
+
+      # Get all put option legs.
+      def puts
+        @legs.select(&:put?)
+      end
+
+      # Get all unique strike prices.
+      def strikes
+        @legs.map(&:strike_price).uniq.sort
+      end
+
+      # Get option legs at a specific strike price.
+      def at_strike(strike_price)
+        @legs.select { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get call option at a specific strike price.
+      def call_at(strike_price)
+        calls.find { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get put option at a specific strike price.
+      def put_at(strike_price)
+        puts.find { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get all ITM calls (calls with strike below spot).
+      def itm_calls
+        return [] unless @spot_price
+
+        calls.select { |leg| leg.itm?(@spot_price) }
+      end
+
+      # Get all OTM calls (calls with strike above spot).
+      def otm_calls
+        return [] unless @spot_price
+
+        calls.select { |leg| leg.otm?(@spot_price) }
+      end
+
+      # Get all ITM puts (puts with strike above spot).
+      def itm_puts
+        return [] unless @spot_price
+
+        puts.select { |leg| leg.itm?(@spot_price) }
+      end
+
+      # Get all OTM puts (puts with strike below spot).
+      def otm_puts
+        return [] unless @spot_price
+
+        puts.select { |leg| leg.otm?(@spot_price) }
+      end
+
+      # Find the ATM strike (closest to spot price).
+      def atm_strike
+        return nil unless @spot_price || strikes.any?
+
+        spot = @spot_price || strikes.first
+        strikes.min_by { |strike| (strike - spot).abs }
+      end
+
+      # Get the total open interest across all legs.
+      def total_oi
+        @legs.sum { |leg| leg.open_interest.to_i }
+      end
+
+      # Get the total volume across all legs.
+      def total_volume
+        @legs.sum { |leg| leg.volume.to_i }
+      end
+
+      # Calculate put-call ratio by open interest.
+      def pcr_by_oi
+        call_oi = calls.sum { |leg| leg.open_interest.to_i }
+        put_oi = puts.sum { |leg| leg.open_interest.to_i }
+        return 0.0 if call_oi.zero?
+
+        put_oi.to_f / call_oi
+      end
+
+      # Calculate put-call ratio by volume.
+      def pcr_by_volume
+        call_vol = calls.sum { |leg| leg.volume.to_i }
+        put_vol = puts.sum { |leg| leg.volume.to_i }
+        return 0.0 if call_vol.zero?
+
+        put_vol.to_f / call_vol
+      end
+
+      def self.parse_legs(data)
+        # Parse from the option chain structure
+        ce_data = data[:ce] || data["ce"] || {}
+        pe_data = data[:pe] || data["pe"] || {}
+
+        ce_strikes = ce_data[:strike] || ce_data["strike"] || []
+        pe_strikes = pe_data[:strike] || pe_data["strike"] || []
+
+        # Parse CE (call) and PE (put) legs
+        parse_option_legs(ce_data, DhanHQ::Constants::OptionType::CALL, ce_strikes) +
+          parse_option_legs(pe_data, DhanHQ::Constants::OptionType::PUT, pe_strikes)
+      end
+      private_class_method :parse_legs
+
+      def self.parse_option_legs(data, option_type, strikes)
+        return [] unless data.is_a?(Hash)
+
+        strikes.each_with_index.map do |strike, i|
+          build_leg(data, option_type, strike, i)
+        end
+      end
+      private_class_method :parse_option_legs
+
+      def self.build_leg(data, option_type, strike, index)
+        OptionLeg.new(
+          strike_price: strike.to_f,
+          option_type: option_type,
+          ltp: extract_value(data, :ltp, index),
+          bid: extract_value(data, :bid, index),
+          ask: extract_value(data, :ask, index),
+          volume: extract_value(data, :volume, index, as_integer: true),
+          open_interest: extract_value(data, :oi, index, as_integer: true),
+          implied_volatility: extract_value(data, :iv, index),
+          delta: extract_value(data, :delta, index),
+          gamma: extract_value(data, :gamma, index),
+          theta: extract_value(data, :theta, index),
+          vega: extract_value(data, :vega, index)
+        )
+      end
+      private_class_method :build_leg
+
+      def self.extract_value(data, key, index, as_integer: false)
+        values = data[key] || data[key.to_s] || []
+        value = values[index]
+        return nil if value.nil?
+
+        as_integer ? value.to_i : value.to_f
+      end
+      private_class_method :extract_value
+    end
+  end
+end

data/lib/DhanHQ/market_data.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "market_data/market_snapshot"
+require_relative "market_data/ohlc_series"
+require_relative "market_data/option_snapshot"
+
+module DhanHQ
+  # Higher-level abstractions for market data consumption.
+  #
+  # Provides typed wrappers around raw API responses for more convenient
+  # market data analysis and consumption.
+  #
+  # @example Quick market snapshot
+  #   response = DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => [11536])
+  #   snapshot = DhanHQ::MarketData::MarketSnapshot.from_response(response)
+  #   puts snapshot.ltp("NSE_EQ", "11536")
+  #
+  # @example Historical OHLC series
+  #   response = DhanHQ::Models::HistoricalData.daily(...)
+  #   series = DhanHQ::MarketData::OHLCSeries.from_response(response)
+  #   puts series.average_close
+  #
+  module MarketData
+  end
+end

data/lib/DhanHQ/mcp/server.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+require_relative "../agent"
+require_relative "../ai"
+
+module DhanHQ
+  module MCP
+    # Minimal MCP-compatible stdio JSON-RPC server for DhanHQ agent tools.
+    class Server
+      # Raised for an unrecognized top-level JSON-RPC method (maps to -32601).
+      class UnknownMethodError < StandardError; end
+      # Raised for a well-formed request with invalid/unknown params (maps to -32602).
+      class InvalidParamsError < StandardError; end
+
+      SUPPORTED_PROTOCOL_VERSIONS = ["2024-11-05"].freeze
+      DEFAULT_TOOL_CALL_TIMEOUT_SECONDS = 15
+
+      RESOURCES = [
+        { uri: "dhanhq://account/profile", name: "Dhan Profile", description: "Current account profile including client ID, PAN, name, and trading permissions",
+          mimeType: "application/json" },
+        { uri: "dhanhq://account/funds", name: "Fund Limits", description: "Available balance, used margin, and withdrawal capacity", mimeType: "application/json" },
+        { uri: "dhanhq://account/holdings", name: "Portfolio Holdings", description: "Current equity holdings with quantity, average price, and P&L", mimeType: "application/json" },
+        { uri: "dhanhq://account/positions", name: "Open Positions", description: "Current F&O and equity positions with net quantity and unrealized P&L",
+          mimeType: "application/json" },
+        { uri: "dhanhq://account/orders", name: "Recent Orders", description: "Recent order history with status, quantity, and fill details", mimeType: "application/json" },
+        { uri: "dhanhq://market/capabilities", name: "Agent Capabilities", description: "All available tools, scopes, risk levels, and version info", mimeType: "application/json" }
+      ].freeze
+
+      PROMPTS = [
+        { name: "portfolio_summary", description: "Generate a human-readable summary of your current portfolio, positions, and available funds" },
+        { name: "market_analysis", description: "Analyze current market conditions and generate a trading context summary" },
+        { name: "risk_report", description: "Review current risk exposure including open positions, P&L, and position limits" },
+        { name: "suggest_strategy", description: "Suggest a trading strategy based on current portfolio and market conditions" },
+        { name: "order_preview", description: "Preview an order before placing it with risk validation" }
+      ].freeze
+
+      def initialize(input: $stdin, output: $stdout, policy: DhanHQ::Agent::Policy.from_env,
+                     tool_call_timeout: DEFAULT_TOOL_CALL_TIMEOUT_SECONDS)
+        @input = input
+        @output = output
+        @policy = policy
+        @tool_call_timeout = tool_call_timeout
+      end
+
+      def run
+        @input.each_line { |line| handle_line(line) }
+      end
+
+      def handle_line(line)
+        request = JSON.parse(line)
+      rescue JSON::ParserError => e
+        respond(nil, nil, code: -32_700, message: "Parse error: #{e.message}")
+      else
+        handle_request(request)
+      end
+
+      private
+
+      def handle_request(request)
+        return unless request.key?("id") # JSON-RPC notification — must not receive a response
+
+        id = request["id"]
+        respond(id, dispatch(request["method"], request["params"] || {}))
+      rescue StandardError => e
+        respond(id, nil, code: error_code_for(e), message: e.message)
+      end
+
+      def error_code_for(error)
+        case error
+        when UnknownMethodError then -32_601
+        when InvalidParamsError then -32_602
+        else -32_603
+        end
+      end
+
+      def dispatch(method, params)
+        case method
+        when "initialize"
+          {
+            protocolVersion: negotiate_protocol_version(params["protocolVersion"]),
+            serverInfo: { name: "dhanhq-ruby", version: DhanHQ::VERSION },
+            capabilities: { tools: {}, resources: {}, prompts: {} }
+          }
+        when "tools/list"
+          { tools: DhanHQ::Agent::ToolRegistry.list.map { |t| mcp_tool(t) } }
+        when "tools/call"
+          { content: [{ type: "text", text: JSON.pretty_generate(serialize(call_tool(params))) }] }
+        when "resources/list"
+          { resources: resource_definitions }
+        when "resources/read"
+          resource = resources.find { |r| r[:uri] == params["uri"] }
+          raise InvalidParamsError, "Unknown resource: #{params["uri"]}" unless resource
+
+          { contents: [resource_read(resource)] }
+        when "prompts/list"
+          { prompts: prompt_definitions }
+        when "prompts/get"
+          prompt = prompts.find { |p| p[:name] == params["name"] }
+          raise InvalidParamsError, "Unknown prompt: #{params["name"]}" unless prompt
+
+          prompt_result(prompt, params.fetch("arguments", {}))
+        else
+          raise UnknownMethodError, "Unsupported MCP method: #{method}"
+        end
+      end
+
+      def negotiate_protocol_version(requested)
+        SUPPORTED_PROTOCOL_VERSIONS.include?(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS.last
+      end
+
+      def call_tool(params)
+        Timeout.timeout(@tool_call_timeout) do
+          DhanHQ::Agent::ToolRegistry.execute(
+            params.fetch("name"),
+            params.fetch("arguments", {}),
+            policy: @policy
+          )
+        end
+      rescue ArgumentError => e
+        raise InvalidParamsError, e.message
+      rescue Timeout::Error
+        raise "Tool call '#{params["name"]}' timed out after #{@tool_call_timeout}s " \
+              "(likely blocked on rate-limit backoff) — retry shortly"
+      end
+
+      def resources
+        RESOURCES
+      end
+
+      def prompts
+        PROMPTS
+      end
+
+      def resource_definitions
+        RESOURCES.map { |r| r.except(:handler) }
+      end
+
+      def resource_read(resource)
+        handler = resource_handler(resource[:uri])
+        data = handler.call
+        { uri: resource[:uri], mimeType: "application/json", text: JSON.pretty_generate(serialize(data)) }
+      end
+
+      def resource_handler(uri)
+        case uri
+        when "dhanhq://account/profile" then -> { DhanHQ::Models::Profile.fetch }
+        when "dhanhq://account/funds" then -> { DhanHQ::Models::Funds.fetch }
+        when "dhanhq://account/holdings" then -> { DhanHQ::Models::Holding.all }
+        when "dhanhq://account/positions" then -> { DhanHQ::Models::Position.all }
+        when "dhanhq://account/orders" then -> { DhanHQ::Models::Order.all }
+        when "dhanhq://market/capabilities" then -> { DhanHQ::Agent::ToolRegistry.capabilities }
+        else raise ArgumentError, "No handler for resource: #{uri}"
+        end
+      end
+
+      def prompt_definitions
+        PROMPTS.map { |p| { name: p[:name], description: p[:description], arguments: prompt_arguments(p[:name]) } }
+      end
+
+      def prompt_arguments(prompt_name)
+        case prompt_name
+        when "order_preview"
+          [{ name: "transaction_type", description: "BUY or SELL", required: true },
+           { name: "security_id", description: "Dhan security ID", required: true },
+           { name: "quantity", description: "Number of shares/lots", required: true },
+           { name: "exchange_segment", description: "NSE_EQ, NSE_FNO, etc.", required: true },
+           { name: "price", description: "Limit price (optional for MARKET)", required: false }]
+        when "market_analysis"
+          [{ name: "symbol", description: "Ticker symbol (e.g., NIFTY, RELIANCE)", required: false }]
+        else
+          []
+        end
+      end
+
+      def prompt_result(prompt, arguments)
+        case prompt[:name]
+        when "portfolio_summary"
+          holdings = DhanHQ::Models::Holding.all
+          positions = DhanHQ::Models::Position.all
+          funds = DhanHQ::Models::Funds.fetch
+          summary = DhanHQ::AI::PromptHelpers.portfolio_summary(holdings: holdings, positions: positions, funds: funds)
+          { messages: [{ role: "user", content: { type: "text", text: summary } }] }
+        when "market_analysis"
+          symbol = arguments["symbol"] || "NIFTY"
+          instrument = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, symbol)
+          security_id = instrument&.security_id&.to_i
+          if security_id
+            snapshot = DhanHQ::Models::MarketFeed.quote(DhanHQ::Constants::ExchangeSegment::IDX_I => [security_id])
+            text = "Market snapshot for #{symbol}: #{snapshot}"
+          else
+            text = "Could not resolve symbol #{symbol} to a security ID for market data."
+          end
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        when "risk_report"
+          positions = DhanHQ::Models::Position.all
+          text = DhanHQ::AI::PromptHelpers.risk_report(positions: positions)
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        when "order_preview"
+          preview = DhanHQ::Agent::OrderPreview.new(arguments)
+          text = preview.valid? ? "Order preview: #{preview.to_h[:summary]}" : "Validation errors: #{preview.errors.join(", ")}"
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        when "suggest_strategy"
+          positions = DhanHQ::Models::Position.all
+          funds = DhanHQ::Models::Funds.fetch
+          text = "Current portfolio: #{positions.size} open positions, Available: ₹#{funds.available_balance}. Review positions for strategy suggestions."
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        else
+          raise ArgumentError, "Unknown prompt: #{prompt[:name]}"
+        end
+      end
+
+      def mcp_tool(tool)
+        { name: tool[:name], description: "[#{tool[:risk]}] #{tool[:description]}", inputSchema: tool[:input_schema] }
+      end
+
+      def serialize(value)
+        case value
+        when Array then value.map { |v| serialize(v) }
+        when Hash then value.transform_values { |v| serialize(v) }
+        else
+          value.respond_to?(:attributes) ? value.attributes : value
+        end
+      end
+
+      def respond(id, result, code: nil, message: nil)
+        payload = { jsonrpc: "2.0", id: id }
+        code ? payload[:error] = { code: code, message: message } : payload[:result] = result
+        @output.puts(JSON.generate(payload))
+        @output.flush
+      end
+    end
+  end
+end

data/lib/DhanHQ/mcp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "mcp/server"
+
+module DhanHQ
+  # MCP namespace provides Model Context Protocol server for AI agent integration.
+  # Enables stdio-based JSON-RPC communication with AI tools and agents.
+  module MCP
+  end
+end

data/lib/DhanHQ/models/funds.rb

@@ -29,6 +29,18 @@ module DhanHQ
       attributes :available_balance, :sod_limit, :collateral_amount, :receiveable_amount, :utilized_amount,
                  :blocked_payout_amount, :withdrawable_balance
 
+      # Returns a concise prompt-friendly summary of funds.
+      def to_prompt
+        parts = []
+        parts << "available=₹#{available_balance}" if available_balance
+        parts << "utilized=₹#{utilized_amount}" if utilized_amount
+        parts << "withdrawable=₹#{withdrawable_balance}" if withdrawable_balance
+        parts << "collateral=₹#{collateral_amount}" if collateral_amount&.positive?
+        parts << "sod_limit=₹#{sod_limit}" if sod_limit
+        parts << "blocked_payout=₹#{blocked_payout_amount}" if blocked_payout_amount&.positive?
+        parts.join(", ")
+      end
+
       ##
       # Normalizes the typo'd `availabelBalance` key from the API response to `available_balance`.
       #

data/lib/DhanHQ/models/holding.rb

@@ -33,6 +33,48 @@ module DhanHQ
       attributes :exchange, :trading_symbol, :security_id, :isin, :total_qty,
                  :dp_qty, :t1_qty, :available_qty, :collateral_qty, :avg_cost_price
 
+      # Returns a concise prompt-friendly summary of the holding.
+      def to_prompt
+        parts = [
+          "#{total_qty}x #{trading_symbol || security_id}",
+          "on #{exchange}"
+        ]
+        parts << "avg_cost=#{avg_cost_price}" if avg_cost_price&.positive?
+        parts << "available=#{available_qty}" if available_qty
+        parts << "dp=#{dp_qty}" if dp_qty&.positive?
+        parts << "t1=#{t1_qty}" if t1_qty&.positive?
+        parts << "collateral=#{collateral_qty}" if collateral_qty&.positive?
+        parts << "isin=#{isin}" if isin
+        parts.join(", ")
+      end
+
+      # Returns true if this holding has pending T1 delivery.
+      def pending_delivery?
+        t1_qty.to_i.positive?
+      end
+
+      # Returns true if this holding is fully delivered (no T1).
+      def delivered?
+        t1_qty.to_i.zero?
+      end
+
+      # Returns true if any quantity is pledged as collateral.
+      def pledged?
+        collateral_qty.to_i.positive?
+      end
+
+      # Returns the percentage of holding that is pledged.
+      def pledge_percentage
+        return 0.0 if total_qty.to_i.zero?
+
+        (collateral_qty.to_i.to_f / total_qty.to_i * 100).round(2)
+      end
+
+      # Returns true if this holding is partially pledged.
+      def partially_pledged?
+        pledged? && collateral_qty.to_i < total_qty.to_i
+      end
+
       class << self
         ##
         # Provides a shared instance of the Holdings resource.