DhanHQ 2.8.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d2ca9bd3c9c4f61504d06e8b2736baf9ded579d04bb21523a9e0c5fe9a74298
-  data.tar.gz: a981472b44efa9c86c1daa83461c27985664a0682022d3aa4b3e925a950788aa
+  metadata.gz: 3d9d117dd455fc2a006a98cf0532297688a247498f5a12e98fb609a355ffc195
+  data.tar.gz: 2334b0e16f35ecc00f414739f3d40da1cac7640ede1b64079248b35e02cc0851
 SHA512:
-  metadata.gz: 03b2f01541f005e6d9ebd4d706023cf553b17bb80327f480f350e5d465a582006b0fc199cc541a804631a71a034b8cd454c8c715e962b95794df665e75eb0a63
-  data.tar.gz: e7320d2ae5e332238cf0e11bcd0f29ecd368772242019567f5dcb525e4b8baa9e71c5191b51b25724cd090ac82fb113524bb0578480f1bf71b82834bc74cda6d
+  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/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [3.0.0] - 2026-05-19
+
+### Breaking Changes
+
+- **TA and analysis modules are now opt-in**. `require 'dhan_hq'` no longer auto-loads `DhanHQ::Analysis::*` or `TA::*`. Explicitly require what you need:
+  ```ruby
+  require 'dhan_hq/analysis'  # OptionsBuyingAdvisor, MultiTimeframeAnalyzer
+  require 'dhan_hq/ta'        # TA::TechnicalAnalysis, TA::Fetcher, TA::Candles
+  ```
+
+### Changed
+
+- `exe/DhanHQ` now correctly uses `require "dhan_hq"` (was the old `require "DhanHQ"`).
+- Gemspec file renamed back to `DhanHQ.gemspec` (was `dhan_hq.gemspec`) to resolve RubyGems "too similar" name collision and ensure successful push of the `DhanHQ` gem.
+- Updated all `Gemfile` references and installation docs to use `DhanHQ` while maintaining `require 'dhan_hq'` for standard Ruby conventions.
+- SimpleCov now tracks all `lib/**/*.rb` files (was models-only).
+
+---
+
 ## [2.8.0] - 2026-03-21
 
 ### Added

data/README.md

@@ -153,16 +153,23 @@ gem install DhanHQ
 
 **`bundle update` / `bundle install` warnings** — If you see "Local specification for rexml-3.2.8 has different dependencies" or "Unresolved or ambiguous specs during Gem::Specification.reset: psych", the bundle still completes successfully. To clear the rexml warning once, run: `gem cleanup rexml`. The psych message is a known Bundler quirk and can be ignored.
 
-### ⚠️ Breaking Change (v2.1.5+)
+### Gem name vs require path
 
-The require statement changed:
+RubyGems normalizes names, so `DhanHQ` and `dhan_hq` refer to the same slot — the published name stays `DhanHQ` and will never change. The require path has used snake_case since v2.1.5:
 
 ```ruby
-# Before         # Now
-require 'DhanHQ'  →  require 'dhan_hq'
+# Gemfile              # Ruby file
+gem 'DhanHQ'           require 'dhan_hq'
 ```
 
-The gem name in your Gemfile stays `DhanHQ` — only the `require` changes.
+### Optional features
+
+The core SDK (`require 'dhan_hq'`) only loads the API client. Technical analysis and the options advisor are opt-in:
+
+```ruby
+require 'dhan_hq/analysis'  # DhanHQ::Analysis::OptionsBuyingAdvisor, MultiTimeframeAnalyzer
+require 'dhan_hq/ta'        # TA::TechnicalAnalysis, TA::Fetcher, TA::Candles
+```
 
 ---
 
@@ -485,6 +492,10 @@ bundle exec rubocop       # lint
 bin/console               # interactive console
 ```
 
+## Disclaimer
+
+This gem is an independent, community-maintained project and is **not officially affiliated with, endorsed by, or supported by Dhan (Mirae Asset Capital Markets)**. Trading in financial instruments carries significant risk. Use this SDK at your own risk and always verify order placement in a sandbox environment before going live.
+
 ## License
 
 [MIT](LICENSE.txt)

data/docs/RAILS_WEBSOCKET_INTEGRATION.md

@@ -19,7 +19,7 @@ This guide provides comprehensive instructions for integrating DhanHQ WebSocket
 
 ```ruby
 # Gemfile
-gem 'dhan_hq'
+gem 'DhanHQ'
 ```
 
 ### 2. Configure DhanHQ

data/docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md

@@ -18,7 +18,7 @@ This guide provides comprehensive instructions for integrating DhanHQ WebSocket
 ### 1. Install the Gem
 
 ```bash
-gem install dhan_hq
+gem install DhanHQ
 ```
 
 ### 2. Basic Configuration

data/docs/TECHNICAL_ANALYSIS.md

@@ -65,7 +65,7 @@ indicators = TA::TechnicalAnalysis.new.compute_from_file(
 ## Analyze Multi-Timeframe Bias
 
 ```ruby
-require "DhanHQ"
+require "dhan_hq/analysis"
 
 analyzer = DhanHQ::Analysis::MultiTimeframeAnalyzer.new(data: indicators)
 summary = analyzer.call

data/exe/DhanHQ

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "DhanHQ"
+require "dhan_hq"

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