DhanHQ 3.1.0 → 3.2.1

data/lib/DhanHQ/agent/tool_registry.rb

@@ -2,35 +2,17 @@
 
 module DhanHQ
   module Agent
-    # Machine-readable tool metadata shared by MCP and agent skills.
+    # Registry and dispatcher for the tools exposed to MCP clients 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
+    # Holds the catalogue (which tools exist, at what scope and risk) and enforces
+    # {DhanHQ::Agent::Policy} on every call. The tools themselves are described by
+    # {DhanHQ::Agent::ToolSchemas} and carried out by {DhanHQ::Agent::ToolHandlers};
+    # each tool is a {DhanHQ::Agent::Tool}.
     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
+        @tools ||= ToolCatalogue.all.freeze
       end
 
       def find(name)
@@ -43,12 +25,17 @@ module DhanHQ
 
       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))
+        tool.write? ? policy.require_write!(tool.scope) : policy.require!(tool.scope)
+        tool.handler.call(KeyCoercion.symbolize(arguments))
+      end
+
+      # Coerces JSON-delivered argument keys to symbols.
+      # Part of this module's surface because {DhanHQ::Agent::OrderPreview} calls it.
+      #
+      # @param value [Hash, Array, Object]
+      # @return [Hash, Array, Object]
+      def symbolize(value)
+        KeyCoercion.symbolize(value)
       end
 
       # Returns capability manifest for the agent runtime.
@@ -63,237 +50,6 @@ module DhanHQ
           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/tool_schemas.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # JSON Schema fragments describing the input each agent tool accepts.
+    #
+    # Pure data: no API calls, no policy, no state. Kept apart from
+    # {DhanHQ::Agent::ToolRegistry} so that adding an endpoint means editing a schema
+    # here and a handler in {DhanHQ::Agent::ToolHandlers}, rather than growing one
+    # module that does registration, schema description and dispatch at once.
+    module ToolSchemas
+      module_function
+
+      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
+
+      # Global Stocks orders carry no exchange segment, product type or validity, and
+      # quantity is fractional. AMOUNT orders replace quantity with a dollar amount.
+      def global_order_schema
+        {
+          type: "object",
+          required: %w[transaction_type order_type security_id],
+          properties: {
+            transaction_type: enum(%w[BUY SELL]),
+            order_type: enum(DhanHQ::Constants::GlobalStocks::OrderType::ALL),
+            security_id: { type: "string" },
+            quantity: { type: "number", exclusiveMinimum: 0 },
+            price: { type: "number", minimum: 0 },
+            trigger_price: { type: "number" },
+            stop_loss_price: { type: "number" },
+            target_price: { type: "number" },
+            amount: { type: "number", description: "Dollar value for AMOUNT orders" },
+            correlation_id: { type: "string" }
+          },
+          additionalProperties: true
+        }
+      end
+
+      def global_estimate_schema
+        {
+          type: "object",
+          required: %w[security_id transaction_type price quantity],
+          properties: {
+            security_id: { type: "string" },
+            transaction_type: enum(%w[BUY SELL]),
+            price: { type: "number", minimum: 0 },
+            quantity: { type: "number", exclusiveMinimum: 0 }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def multi_order_schema
+        {
+          type: "object",
+          required: ["orders"],
+          properties: {
+            orders: {
+              type: "array",
+              minItems: 1,
+              maxItems: DhanHQ::Contracts::MultiOrderContract::MAX_ORDERS,
+              items: {
+                type: "object",
+                required: %w[sequence transaction_type exchange_segment],
+                properties: {
+                  sequence: { type: "string" },
+                  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" }
+                },
+                additionalProperties: true
+              }
+            }
+          },
+          additionalProperties: false
+        }
+      end
+
+      def enum(values)
+        { type: "string", enum: values }
+      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
+    end
+  end
+end

data/lib/DhanHQ/ai/prompt_helpers.rb

@@ -41,14 +41,20 @@ module DhanHQ
       # @param funds [DhanHQ::Models::Funds] Funds data
       # @return [String] Portfolio summary
       def self.portfolio_summary(holdings:, positions:, funds:)
+        # Array() so a missing collection renders as an empty section instead of
+        # raising. `funds` was already guarded; these two were not, and a prompt
+        # helper failing hard on an empty portfolio is the wrong trade.
+        all_holdings = Array(holdings)
+        open_positions = Array(positions).select(&:open?)
+
         lines = ["=== Portfolio Summary ==="]
         lines << "Funds: #{funds.to_prompt}" if funds
         lines << ""
-        lines << "Holdings (#{holdings.size}):"
-        holdings.each { |h| lines << "  #{h.to_prompt}" }
+        lines << "Holdings (#{all_holdings.size}):"
+        all_holdings.each { |holding| lines << "  #{holding.to_prompt}" }
         lines << ""
-        lines << "Open Positions (#{positions.count(&:open?)}):"
-        positions.select(&:open?).each { |p| lines << "  #{p.to_prompt}" }
+        lines << "Open Positions (#{open_positions.size}):"
+        open_positions.each { |position| lines << "  #{position.to_prompt}" }
         lines.join("\n")
       end
 
@@ -95,13 +101,17 @@ module DhanHQ
       # @param risk_params [Hash] Risk parameters
       # @return [String] Risk report
       def self.risk_report(positions:, risk_params: {})
+        # P&L is summed across every position; only the count is restricted to open
+        # ones, since a closed position still contributed realised P&L today.
+        all_positions = Array(positions)
+
         lines = ["=== Risk Report ==="]
-        total_unrealized = positions.sum { |p| p.unrealized_profit.to_f }
-        total_realized = positions.sum { |p| p.realized_profit.to_f }
+        total_unrealized = all_positions.sum { |position| position.unrealized_profit.to_f }
+        total_realized = all_positions.sum { |position| position.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 << "Open Positions: #{all_positions.count(&:open?)}"
 
         lines << "Max Drawdown: #{risk_params[:max_drawdown]}%" if risk_params[:max_drawdown]