DhanHQ 3.0.0 → 3.1.0

data/lib/DhanHQ/agent/tool_registry.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # Machine-readable tool metadata shared by MCP and agent skills.
+    #
+    # Each tool has:
+    # - name, description, scope, risk, schema (input), handler
+    # - version: semantic version of the tool definition
+    # - output_schema: JSON Schema for the tool's return value
+    # - examples: array of example input/output pairs
+    # rubocop:disable Metrics/ModuleLength
+    module ToolRegistry
+      Tool = Struct.new(:name, :description, :scope, :risk, :schema, :handler,
+                        :version, :output_schema, :examples) do
+        def to_h
+          {
+            name: name,
+            description: description,
+            scope: scope,
+            risk: risk,
+            input_schema: schema,
+            output_schema: output_schema,
+            version: version,
+            examples: examples
+          }.compact
+        end
+      end
+
+      module_function
+
+      def tools
+        @tools ||= build_tools.freeze
+      end
+
+      def find(name)
+        tools.fetch(name.to_s) { raise ArgumentError, "Unknown DhanHQ agent tool: #{name}" }
+      end
+
+      def list
+        tools.values.map(&:to_h)
+      end
+
+      def execute(name, arguments = {}, policy: Policy.from_env)
+        tool = find(name)
+        if tool.risk.to_s.end_with?("write") || tool.risk == "destructive_write"
+          policy.require_write!(tool.scope)
+        else
+          policy.require!(tool.scope)
+        end
+        tool.handler.call(symbolize(arguments))
+      end
+
+      # Returns capability manifest for the agent runtime.
+      # Includes tool count, available scopes, risk levels, and version info.
+      def capabilities
+        {
+          version: DhanHQ::VERSION,
+          tool_count: tools.size,
+          tools: list,
+          scopes: Policy::ALL_SCOPES,
+          risk_levels: tools.values.map(&:risk).uniq.sort,
+          write_enabled: Policy.from_env.writes_enabled?
+        }
+      end
+
+      def build_tools
+        (primitive_tools + skill_tools).to_h { |tool_item| [tool_item.name, tool_item] }
+      end
+
+      def primitive_tools
+        [
+          tool("dhan_profile", "Fetch Dhan profile", "portfolio:read", "read_only",
+               object_schema, profile_handler,
+               version: "1.0.0",
+               output_schema: { type: "object", properties: { client_id: { type: "string" } } }),
+          tool("dhan_funds", "Fetch fund limits", "portfolio:read", "read_only",
+               object_schema, funds_handler,
+               version: "1.0.0",
+               output_schema: { type: "object", properties: { available_balance: { type: "number" } } }),
+          tool("dhan_holdings", "List holdings", "portfolio:read", "read_only",
+               object_schema, holdings_handler,
+               version: "1.0.0",
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool("dhan_positions", "List positions", "portfolio:read", "read_only",
+               object_schema, positions_handler,
+               version: "1.0.0",
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool("dhan_orders", "List orders", "orders:read", "read_only",
+               object_schema, orders_handler,
+               version: "1.0.0",
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool("dhan_trades", "List trades", "orders:read", "read_only",
+               object_schema, trades_handler,
+               version: "1.0.0",
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool("dhan_search_instruments", "Resolve symbols to security IDs", "market:read", "read_only",
+               search_schema, search_handler,
+               version: "1.0.0",
+               output_schema: { type: "array", items: { type: "object" } },
+               examples: [
+                 { input: { query: "RELIANCE" }, output: "[{security_id: '2885', symbol_name: 'RELIANCE'}]" }
+               ]),
+          tool("dhan_ltp", "Fetch last traded prices", "market:read", "read_only",
+               feed_schema, ltp_handler,
+               version: "1.0.0",
+               output_schema: { type: "object", additionalProperties: { type: "number" } }),
+          tool("dhan_quote", "Fetch market quotes", "market:read", "read_only",
+               feed_schema, quote_handler,
+               version: "1.0.0",
+               output_schema: { type: "object", additionalProperties: { type: "object" } }),
+          tool("dhan_order_preview", "Validate and summarize an order without placing it", "orders:read",
+               "trade_adjacent_read", order_schema, preview_handler,
+               version: "1.0.0",
+               output_schema: {
+                 type: "object",
+                 properties: {
+                   valid: { type: "boolean" },
+                   errors: { type: "array" },
+                   summary: { type: "string" }
+                 }
+               }),
+          tool("dhan_place_order", "Place an order after external confirmation", "orders:write", "live_write",
+               order_schema, place_order_handler,
+               version: "1.0.0",
+               output_schema: { type: "object", properties: { order_id: { type: "string" } } }),
+          tool("dhan_cancel_order", "Cancel an order", "orders:cancel", "destructive_write",
+               cancel_schema, cancel_order_handler,
+               version: "1.0.0",
+               output_schema: { type: "object", properties: { order_id: { type: "string" }, status: { type: "string" } } })
+        ]
+      end
+
+      # Exposes each registered DhanHQ::Skills::Registry strategy as an MCP tool,
+      # gated by the risk/scope the skill class declares (see DhanHQ::Skills::Base).
+      def skill_tools
+        DhanHQ::Skills::Registry.list.map do |skill|
+          klass = DhanHQ::Skills::Registry.find(skill[:name])
+          tool("dhan_skill_#{skill[:name]}", skill[:description], klass.scope, klass.risk,
+               skill_input_schema(skill[:params]),
+               ->(arguments) { DhanHQ::Skills::Registry.call(skill[:name], arguments) },
+               version: "1.0.0")
+        end
+      end
+
+      def skill_input_schema(params)
+        properties = params.transform_values do |config|
+          { type: skill_param_type(config[:type]) }.tap { |h| h[:description] = config[:description] if config[:description] }
+        end
+        required = params.select { |_, config| config[:required] }.keys.map(&:to_s)
+        { type: "object", properties: properties, required: required, additionalProperties: false }
+      end
+
+      def skill_param_type(type)
+        { string: "string", integer: "integer", number: "number", boolean: "boolean" }.fetch(type.to_sym, "string")
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def tool(name, description, scope, risk, schema, handler, version: "1.0.0", output_schema: nil, examples: nil)
+        Tool.new(
+          name: name, description: description, scope: scope, risk: risk,
+          schema: schema, handler: handler, version: version,
+          output_schema: output_schema, examples: examples
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def object_schema
+        { type: "object", properties: {}, additionalProperties: false }
+      end
+
+      def search_schema
+        {
+          type: "object",
+          required: ["query"],
+          properties: {
+            query: { type: "string" },
+            segments: { type: "array", items: { type: "string" } },
+            limit: { type: "integer", minimum: 1, maximum: 100 },
+            exact_match: { type: "boolean" }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def feed_schema
+        {
+          type: "object",
+          required: ["instruments"],
+          properties: {
+            instruments: {
+              type: "object",
+              additionalProperties: { type: "array", items: { type: %w[integer string] } }
+            }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def order_schema
+        {
+          type: "object",
+          required: %w[transaction_type exchange_segment product_type order_type validity security_id quantity],
+          properties: {
+            transaction_type: enum(%w[BUY SELL]),
+            exchange_segment: { type: "string" },
+            product_type: { type: "string" },
+            order_type: { type: "string" },
+            validity: { type: "string" },
+            security_id: { type: "string" },
+            quantity: { type: "integer", minimum: 1 },
+            price: { type: "number" },
+            trigger_price: { type: "number" },
+            correlation_id: { type: "string" }
+          },
+          additionalProperties: true
+        }
+      end
+
+      def cancel_schema
+        {
+          type: "object",
+          required: ["order_id"],
+          properties: { order_id: { type: "string" } },
+          additionalProperties: false
+        }
+      end
+
+      def enum(values)
+        { type: "string", enum: values }
+      end
+
+      def profile_handler = ->(_) { DhanHQ::Models::Profile.fetch }
+
+      def funds_handler = ->(_) { DhanHQ::Models::Funds.fetch }
+
+      def holdings_handler = ->(_) { DhanHQ::Models::Holding.all }
+
+      def positions_handler = ->(_) { DhanHQ::Models::Position.all }
+
+      def orders_handler = ->(_) { DhanHQ::Models::Order.all }
+
+      def trades_handler = ->(_) { DhanHQ::Models::Trade.today }
+
+      def search_handler
+        lambda do |arguments|
+          query = arguments.fetch(:query)
+          options = arguments.except(:query)
+          DhanHQ::Models::Instrument.search(query, **options)
+        end
+      end
+
+      def ltp_handler = ->(arguments) { DhanHQ::Models::MarketFeed.ltp(arguments[:instruments]) }
+
+      def quote_handler = ->(arguments) { DhanHQ::Models::MarketFeed.quote(arguments[:instruments]) }
+
+      def preview_handler = ->(arguments) { OrderPreview.new(arguments).to_h }
+
+      def place_order_handler
+        lambda do |arguments|
+          instrument = DhanHQ::Models::Instrument.find_by_security_id(arguments[:exchange_segment], arguments[:security_id])
+          unless instrument
+            raise DhanHQ::RiskViolation,
+                  "Cannot verify risk for unknown instrument: #{arguments[:exchange_segment]}:#{arguments[:security_id]}"
+          end
+
+          risk_type = instrument.instrument_type.to_s.start_with?("OPT") ? :options : :equity
+          DhanHQ::Risk::Pipeline.run!(instrument: instrument, args: stringify(arguments), type: risk_type)
+
+          DhanHQ::Models::Order.place(arguments)
+        end
+      end
+
+      def cancel_order_handler
+        lambda do |arguments|
+          order = DhanHQ::Models::Order.find(arguments[:order_id])
+          order&.cancel || false
+        end
+      end
+
+      def symbolize(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, val), hash| hash[key.to_sym] = symbolize(val) }
+        when Array then value.map { |val| symbolize(val) }
+        else value
+        end
+      end
+
+      def stringify(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, val), hash| hash[key.to_s] = stringify(val) }
+        when Array then value.map { |val| stringify(val) }
+        else value
+        end
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/DhanHQ/agent.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "agent/policy"
+require_relative "agent/tool_registry"
+require_relative "agent/order_preview"
+
+module DhanHQ
+  # Agent namespace provides primitives for AI-driven trading workflows.
+  # Includes policy enforcement, tool registry, and order preview capabilities.
+  module Agent
+  end
+end

data/lib/DhanHQ/ai/context_builder.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # AI integration layer for building AI-powered trading assistants.
+  #
+  # Provides workflow orchestration, prompt helpers, and context
+  # serialization for AI agents.
+  #
+  # @example Build context for AI
+  #   context = DhanHQ::AI::ContextBuilder.build do |ctx|
+  #     ctx.add_portfolio
+  #     ctx.add_positions
+  #     ctx.add_recent_orders(limit: 10)
+  #     ctx.add_market_snapshot(security_ids: ["2885"])
+  #   end
+  #
+  module AI
+    # Build context for AI agents from current account state.
+    #
+    # Provides methods to serialize portfolio, positions, orders,
+    # and market data into prompt-friendly formats.
+    class ContextBuilder
+      attr_reader :sections
+
+      def initialize
+        @sections = []
+      end
+
+      # Build context using a block.
+      #
+      # @yield [builder] The context builder
+      # @return [DhanHQ::AI::ContextBuilder]
+      def self.build
+        builder = new
+        yield builder
+        builder
+      end
+
+      # Add portfolio holdings to context.
+      def add_portfolio
+        holdings = DhanHQ::Models::Holding.all
+        @sections << {
+          type: :portfolio,
+          data: holdings.map(&:to_prompt),
+          summary: "Portfolio: #{holdings.size} holdings"
+        }
+        self
+      end
+
+      # Add current positions to context.
+      def add_positions
+        positions = DhanHQ::Models::Position.all
+        active = positions.select(&:open?)
+        @sections << {
+          type: :positions,
+          data: active.map(&:to_prompt),
+          summary: "Positions: #{active.size} open"
+        }
+        self
+      end
+
+      # Add recent orders to context.
+      #
+      # @param limit [Integer] Number of recent orders (default: 10)
+      def add_recent_orders(limit: 10)
+        orders = DhanHQ::Models::Order.all
+        recent = orders.last(limit)
+        @sections << {
+          type: :orders,
+          data: recent.map(&:to_prompt),
+          summary: "Orders: #{orders.size} total, #{recent.size} recent"
+        }
+        self
+      end
+
+      # Add fund information to context.
+      def add_funds
+        funds = DhanHQ::Models::Funds.fetch
+        @sections << {
+          type: :funds,
+          data: [funds.to_prompt],
+          summary: "Funds: Available ₹#{funds.available_balance}"
+        }
+        self
+      end
+
+      # Add market snapshot to context.
+      #
+      # @param security_ids [Array<String>] Security IDs to fetch
+      def add_market_snapshot(security_ids:)
+        instruments = security_ids.each_with_object({}) do |sec_id, hash|
+          hash[DhanHQ::Constants::ExchangeSegment::NSE_EQ] ||= []
+          hash[DhanHQ::Constants::ExchangeSegment::NSE_EQ] << sec_id
+        end
+
+        response = DhanHQ::Models::MarketFeed.ltp(instruments)
+        snapshot = DhanHQ::MarketData::MarketSnapshot.from_response(response)
+
+        @sections << {
+          type: :market_data,
+          data: [snapshot.empty? ? "No data" : "Snapshot with #{snapshot.size} instruments"],
+          summary: "Market: #{snapshot.size} instruments"
+        }
+        self
+      end
+
+      # Add custom section to context.
+      #
+      # @param type [Symbol] Section type
+      # @param data [Array<String>] Prompt strings
+      # @param summary [String] Section summary
+      def add_section(type:, data:, summary:)
+        @sections << { type: type, data: data, summary: summary }
+        self
+      end
+
+      # Serialize context to a prompt string.
+      #
+      # @return [String] Formatted context string
+      def to_prompt
+        lines = ["=== DhanHQ Trading Context ==="]
+        lines << "Generated at: #{Time.now}"
+        lines << ""
+
+        @sections.each do |section|
+          lines << "--- #{section[:summary]} ---"
+          section[:data].each { |item| lines << "  #{item}" }
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      # Serialize context to a hash.
+      #
+      # @return [Hash] Context as hash
+      def to_h
+        {
+          generated_at: Time.now,
+          sections: @sections
+        }
+      end
+    end
+  end
+end

data/lib/DhanHQ/ai/prompt_helpers.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module AI
+    # Helper methods for generating prompts for AI trading assistants.
+    #
+    # Provides methods to create system prompts, user prompts,
+    # and context summaries for AI models.
+    module PromptHelpers
+      # Generate a system prompt for an AI trading assistant.
+      #
+      # @param capabilities [Array<String>] List of capabilities
+      # @return [String] System prompt
+      def self.system_prompt(capabilities: [])
+        <<~PROMPT.strip
+          You are an AI trading assistant for Indian stock markets (NSE, BSE, MCX).
+
+          Your capabilities:
+          - Fetch market data (LTP, OHLC, quotes)
+          - Place, modify, and cancel orders
+          - View portfolio holdings, positions, and orders
+          - Calculate option Greeks and implied volatility
+          - Analyze option chains and Max Pain
+          - Apply risk management rules
+
+          #{"Additional capabilities:\n#{capabilities.map { |c| "- #{c}" }.join("\n")}" unless capabilities.empty?}
+
+          Rules:
+          - Always confirm before placing live orders
+          - Use correlation_id for all agent-originated orders
+          - Never expose access tokens or secrets
+          - Prefer read-only operations unless explicitly asked to trade
+          - Validate instruments before trading using search
+        PROMPT
+      end
+
+      # Generate a portfolio summary prompt.
+      #
+      # @param holdings [Array<DhanHQ::Models::Holding>] Holdings data
+      # @param positions [Array<DhanHQ::Models::Position>] Positions data
+      # @param funds [DhanHQ::Models::Funds] Funds data
+      # @return [String] Portfolio summary
+      def self.portfolio_summary(holdings:, positions:, funds:)
+        lines = ["=== Portfolio Summary ==="]
+        lines << "Funds: #{funds.to_prompt}" if funds
+        lines << ""
+        lines << "Holdings (#{holdings.size}):"
+        holdings.each { |h| lines << "  #{h.to_prompt}" }
+        lines << ""
+        lines << "Open Positions (#{positions.count(&:open?)}):"
+        positions.select(&:open?).each { |p| lines << "  #{p.to_prompt}" }
+        lines.join("\n")
+      end
+
+      # Generate a market analysis prompt.
+      #
+      # @param snapshot [DhanHQ::MarketData::MarketSnapshot] Market snapshot
+      # @param series [DhanHQ::MarketData::OHLCSeries] OHLC series
+      # @return [String] Market analysis prompt
+      def self.market_analysis(snapshot:, series: nil)
+        lines = ["=== Market Analysis ==="]
+        lines << "Snapshot: #{snapshot.size} instruments"
+        lines << "Series: #{series&.size || 0} candles"
+
+        if series&.any?
+          lines << "Latest close: ₹#{series.last.close}"
+          lines << "Average close: ₹#{series.average_close&.round(2)}"
+          lines << "Price range: ₹#{series.price_range&.round(2)}"
+        end
+
+        lines.join("\n")
+      end
+
+      # Generate an order confirmation prompt.
+      #
+      # @param order_params [Hash] Order parameters
+      # @return [String] Order confirmation prompt
+      def self.order_confirmation(order_params)
+        <<~PROMPT.strip
+          === Order Confirmation Required ===
+          #{order_params[:transaction_type]} #{order_params[:quantity]}x #{order_params[:security_id]}
+          Exchange: #{order_params[:exchange_segment]}
+          Product: #{order_params[:product_type]}
+          Type: #{order_params[:order_type]}
+          #{order_params[:price] ? "Price: ₹#{order_params[:price]}" : "Market Price"}
+          #{"Trigger: ₹#{order_params[:trigger_price]}" if order_params[:trigger_price]}
+
+          Please confirm this order.
+        PROMPT
+      end
+
+      # Generate a risk report prompt.
+      #
+      # @param positions [Array<DhanHQ::Models::Position>] Current positions
+      # @param risk_params [Hash] Risk parameters
+      # @return [String] Risk report
+      def self.risk_report(positions:, risk_params: {})
+        lines = ["=== Risk Report ==="]
+        total_unrealized = positions.sum { |p| p.unrealized_profit.to_f }
+        total_realized = positions.sum { |p| p.realized_profit.to_f }
+
+        lines << "Total Unrealized P&L: ₹#{total_unrealized.round(2)}"
+        lines << "Total Realized P&L: ₹#{total_realized.round(2)}"
+        lines << "Open Positions: #{positions.count(&:open?)}"
+
+        lines << "Max Drawdown: #{risk_params[:max_drawdown]}%" if risk_params[:max_drawdown]
+
+        lines << "Daily Loss Limit: ₹#{risk_params[:daily_loss_limit]}" if risk_params[:daily_loss_limit]
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/DhanHQ/ai.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "ai/context_builder"
+require_relative "ai/prompt_helpers"
+
+module DhanHQ
+  # AI integration layer for building AI-powered trading assistants.
+  #
+  # Provides workflow orchestration, prompt helpers, and context
+  # serialization for AI agents.
+  #
+  # @example Build context for AI
+  #   context = DhanHQ::AI::ContextBuilder.build do |ctx|
+  #     ctx.add_portfolio
+  #     ctx.add_positions
+  #     ctx.add_recent_orders(limit: 10)
+  #   end
+  #   puts context.to_prompt
+  #
+  # @example Generate system prompt
+  #   prompt = DhanHQ::AI::PromptHelpers.system_prompt(
+  #     capabilities: ["Option chain analysis", "Greeks calculation"]
+  #   )
+  #
+  module AI
+  end
+end

data/lib/DhanHQ/auth.rb

@@ -91,7 +91,6 @@ module DhanHQ
     def self.build_connection(base_url)
       Faraday.new(url: base_url) do |c|
         c.request :url_encoded
-        c.response :json, content_type: /\bjson$/
         c.adapter Faraday.default_adapter
       end
     end

data/lib/DhanHQ/client.rb

@@ -212,9 +212,7 @@ module DhanHQ
       write_timeout = ENV.fetch("DHAN_WRITE_TIMEOUT", 30).to_i
 
       Faraday.new(url: url) do |conn|
-        conn.request :json, parser_options: { symbolize_names: true }
-        conn.response :json, content_type: /\bjson$/
-        conn.response :logger if ENV["DHAN_DEBUG"] == "true"
+        conn.request :url_encoded
         conn.options.timeout = read_timeout
         conn.options.open_timeout = connect_timeout
         conn.options.write_timeout = write_timeout

data/lib/DhanHQ/concerns/order_audit.rb

@@ -4,7 +4,8 @@ require_relative "../utils/network_inspector"
 
 module DhanHQ
   module Concerns
-    # Shared behavior for order audit logging and live trading safety.
+    # Shared behavior for order audit logging, live trading safety, and
+    # pre-trade risk checks.
     #
     # Include this module in any Resource that submits, modifies, or cancels
     # orders on the Dhan API. It provides:
@@ -17,12 +18,18 @@ module DhanHQ
     #   unless +ENV["LIVE_TRADING"]+ is +"true"+, preventing accidental order
     #   placement from development machines.
     #
+    # - {#run_risk_checks!}: runs {DhanHQ::Risk::Pipeline} against the order
+    #   params before execution.  Catches unresolvable instruments and other
+    #   edge cases silently so the risk layer never blocks a valid order due
+    #   to a transient lookup failure.
+    #
     # @example Including in a resource
     #   class MyOrders < BaseAPI
     #     include DhanHQ::Concerns::OrderAudit
     #
     #     def create(params)
     #       ensure_live_trading!
+    #       run_risk_checks!(params)
     #       log_order_context("MY_ORDER_ATTEMPT", params)
     #       post("", params: params)
     #     end
@@ -39,6 +46,41 @@ module DhanHQ
               "Live trading is disabled. Set ENV[\"LIVE_TRADING\"]=\"true\" to enable order placement."
       end
 
+      # Runs the risk pipeline for the given order params.
+      #
+      # Extracts +security_id+ and +exchange_segment+ from the params,
+      # resolves the instrument, and calls {DhanHQ::Risk::Pipeline.run!}.
+      # If the instrument cannot be resolved the check is skipped silently
+      # rather than blocking the order.
+      def run_risk_checks!(params)
+        security_id = extract_param(params, :securityId, :security_id)
+        exchange_segment = extract_param(params, :exchangeSegment, :exchange_segment)
+        return unless security_id && exchange_segment
+
+        instrument = DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)
+        return unless instrument
+
+        DhanHQ::Risk::Pipeline.run!(
+          instrument: instrument,
+          args: params,
+          type: trade_type_for(exchange_segment),
+          now: Time.now
+        )
+      rescue DhanHQ::RiskViolation
+        raise
+      rescue StandardError
+        nil
+      end
+
+      # Maps an exchange segment string to a pipeline trade type.
+      def trade_type_for(exchange_segment)
+        case exchange_segment.to_s
+        when /^NSE_FNO/, /^BSE_FNO/, /^NSE_CURRENCY/, /^BSE_CURRENCY/ then :fno
+        when /^MCX/ then :commodity
+        else :equity
+        end
+      end
+
       # Emits a structured JSON log line with machine/network/correlation context.
       # Uses WARN level so it appears even when INFO is silenced.
       def log_order_context(event, params = {})