DhanHQ 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf675947ad1be99c9af911e63ded9e131e85eec23703f9de3540c30a69b27749
-  data.tar.gz: 2248c7ea6c009e0017327d3483c2bf13354a4994bf7a4fc63b76519f44e93b07
+  metadata.gz: 3d9d117dd455fc2a006a98cf0532297688a247498f5a12e98fb609a355ffc195
+  data.tar.gz: 2334b0e16f35ecc00f414739f3d40da1cac7640ede1b64079248b35e02cc0851
 SHA512:
-  metadata.gz: e485bf1b92f5de3277b6cc611cc7f29035f70ccbea9c59bd8945c456382e5bc415795ba7d60f5d69b193c3c2d270a9cd2ed53502870fed6a4731e0b7fc2ac94d
-  data.tar.gz: eb094317cddd3d927bfbd54a8b0b8598b367217cf67c0a8fc1000d0f5258bd6009007bb6be30b36868746f1fa2b22037fad4a9ad872f3ca0b294bad388656b32
+  metadata.gz: 577d961c10faa0381d7e4f17a835688c181457bc7ed2222755123dd4cb7735431c1652af5d7026420c977b330863d9576354cc65c44aa1d7bc9342c1e759cce3
+  data.tar.gz: fc6ba43d2e0e37d8e87c19aa7b803330377aa7c38bff4f90c451192d410a94a9864ea887f90b8a5419c608e0ca57fcb8711bd462976568772318aee29abbcb45

data/.rubocop_todo.yml

@@ -90,8 +90,10 @@ Naming/MethodParameterName:
 Naming/PredicateMethod:
   Exclude:
     - 'lib/DhanHQ/models/forever_order.rb'
+    - 'lib/DhanHQ/models/iceberg_order.rb'
     - 'lib/DhanHQ/models/order.rb'
     - 'lib/DhanHQ/models/super_order.rb'
+    - 'lib/DhanHQ/models/twap_order.rb'
     - 'lib/DhanHQ/ws/singleton_lock.rb'
 
 # Offense count: 13
@@ -105,6 +107,11 @@ Naming/VariableNumber:
     - 'lib/DhanHQ/ws/market_depth/client.rb'
     - 'lib/DhanHQ/ws/orders/connection.rb'
 
+# Offense count: 1
+Naming/FileName:
+  Exclude:
+    - 'lib/DhanHQ.rb'
+
 # Offense count: 4
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:

data/lib/DhanHQ/agent/order_preview.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # Dry-run order validator and human-readable summary for agent workflows.
+    class OrderPreview
+      attr_reader :params, :errors
+
+      def initialize(params)
+        @params = DhanHQ::Agent::ToolRegistry.symbolize(params)
+        @errors = []
+        validate
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def to_h
+        {
+          valid: valid?,
+          errors: errors,
+          action: "place_order",
+          risk: "live_order_requires_confirmation",
+          requires: %w[orders:write DHANHQ_MCP_ENABLE_WRITES LIVE_TRADING],
+          summary: summary,
+          order: params
+        }
+      end
+
+      private
+
+      def validate
+        result = DhanHQ::Contracts::PlaceOrderContract.new.call(params)
+        @errors << result.errors.to_h if result.failure?
+        @errors << "correlation_id is recommended for agent-originated orders" if params[:correlation_id].to_s.empty?
+      end
+
+      def summary
+        side = params[:transaction_type]
+        qty = params[:quantity]
+        security = params[:security_id]
+        segment = params[:exchange_segment]
+        type = params[:order_type]
+        price = params[:price] ? " @ #{params[:price]}" : ""
+        "#{side} #{qty} of #{segment}:#{security} as #{type}#{price}"
+      end
+    end
+  end
+end

data/lib/DhanHQ/agent/policy.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # Permission policy for MCP and agent-skill integrations.
+    class Policy
+      READ_SCOPES = %w[portfolio:read market:read orders:read].freeze
+      WRITE_SCOPES = %w[orders:write orders:cancel alerts:write risk:write].freeze
+      ALL_SCOPES = (READ_SCOPES + WRITE_SCOPES).freeze
+
+      attr_reader :scopes
+
+      def initialize(scopes: [])
+        @scopes = Array(scopes).map(&:to_s).uniq.freeze
+        unknown = @scopes - ALL_SCOPES
+        raise ArgumentError, "Unknown agent scopes: #{unknown.join(", ")}" if unknown.any?
+      end
+
+      def self.read_only
+        new(scopes: READ_SCOPES)
+      end
+
+      def self.from_env
+        raw = ENV.fetch("DHANHQ_AGENT_SCOPES", READ_SCOPES.join(","))
+        new(scopes: raw.split(/[\s,]+/).reject(&:empty?))
+      end
+
+      def allow?(scope)
+        @scopes.include?(scope.to_s)
+      end
+
+      def require!(scope)
+        return true if allow?(scope)
+
+        raise DhanHQ::Error, "Agent scope required: #{scope}"
+      end
+
+      def writes_enabled?
+        ENV["DHANHQ_MCP_ENABLE_WRITES"] == "true" && ENV["LIVE_TRADING"] == "true"
+      end
+
+      def require_write!(scope)
+        require!(scope)
+        return true if writes_enabled?
+
+        raise DhanHQ::LiveTradingDisabledError,
+              "Agent write tools require DHANHQ_MCP_ENABLE_WRITES=true and LIVE_TRADING=true"
+      end
+    end
+  end
+end

data/lib/DhanHQ/agent/tool_registry.rb

@@ -0,0 +1,250 @@
+# 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
+        [
+          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" } } })
+        ].to_h { |tool_item| [tool_item.name, tool_item] }
+      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 = ->(arguments) { DhanHQ::Models::Order.place(arguments) }
+
+      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
+    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