Merge pull request #131 from QuantStrategyLab/feat/dca-compat-mode

feat: DCA compat mode

Author: Pigbibi

src/quant_platform_kit/common/execution_capabilities.py

@@ -5,6 +5,13 @@
 FRACTIONAL_SHARE_EXECUTION_CAPABILITY = "fractional_share_execution"
 FRACTIONAL_SHARE_EXECUTION_SKIP_REASON = "fractional_share_execution_required"
 
+# When a platform does NOT natively support fractional shares, DCA / notional
+# strategies can still run by converting each notional buy into a minimum
+# 1-share (US) or 1-lot (HK) order.  This compat mode is signalled via
+# ``notional_buy_compat_mode_enabled()`` so the execution layer knows to
+# floor-up notional amounts instead of placing true fractional orders.
+NOTIONAL_TO_WHOLE_SHARE_COMPAT_SKIP_REASON = "notional_to_whole_share_compat"
+
 
 def definition_requires_fractional_share_execution(definition: StrategyDefinition) -> bool:
     return FRACTIONAL_SHARE_EXECUTION_CAPABILITY in frozenset(definition.compatible_capabilities)
@@ -20,6 +27,15 @@ def fractional_share_execution_unsupported_reason(
     strategy_catalog: StrategyCatalog,
     capability_matrix: PlatformCapabilityMatrix,
 ) -> str | None:
+    """Return a reason string if *profile* requires fractional shares but the
+    platform does **not** support them natively.
+
+    When the platform lacks ``fractional_share_execution`` but a strategy
+    still needs to place notional orders, callers should check
+    ``notional_buy_compat_mode_enabled()`` — if that returns ``True`` the
+    execution layer should convert each notional buy into a minimum
+    whole-share (or whole-lot) order instead of skipping the strategy.
+    """
     normalized_profile = normalize_profile_name(profile)
     definition = strategy_catalog.definitions.get(normalized_profile)
     if definition is None:
@@ -28,3 +44,25 @@ def fractional_share_execution_unsupported_reason(
         if not platform_supports_fractional_share_execution(capability_matrix=capability_matrix):
             return FRACTIONAL_SHARE_EXECUTION_SKIP_REASON
     return None
+
+
+def notional_buy_compat_mode_enabled(
+    profile: str,
+    *,
+    strategy_catalog: StrategyCatalog,
+    capability_matrix: PlatformCapabilityMatrix,
+) -> bool:
+    """Return ``True`` when *profile* requires fractional execution but the
+    platform does **not** support it natively.
+
+    In compat mode the execution layer should convert each notional buy
+    intent into a minimum 1‑share (US) or 1‑lot (HK) order, falling back
+    to skipping the order if the notional amount is smaller than one unit.
+    """
+    normalized_profile = normalize_profile_name(profile)
+    definition = strategy_catalog.definitions.get(normalized_profile)
+    if definition is None:
+        return False
+    if not definition_requires_fractional_share_execution(definition):
+        return False
+    return not platform_supports_fractional_share_execution(capability_matrix=capability_matrix)

src/quant_platform_kit/common/strategies.py

@@ -384,7 +384,14 @@ def _matches_platform_capability_matrix(
     adapter_capabilities = frozenset(runtime_adapter.available_capabilities)
     if definition.compatible_capabilities - adapter_capabilities:
         return False
-    if adapter_capabilities - capability_matrix.supported_capabilities:
+    # ``fractional_share_execution`` is a *soft* capability: when a platform
+    # does not natively support it, the execution layer can still run the
+    # strategy in compat mode by converting notional buys to minimum
+    # whole-share / whole-lot orders.  Drop only that capability before
+    # checking the platform matrix so DCA profiles remain eligible.
+    _soft_caps = frozenset({"fractional_share_execution"})
+    _hard_adapter_caps = adapter_capabilities - _soft_caps
+    if _hard_adapter_caps - capability_matrix.supported_capabilities:
         return False
 
     return True

tests/test_execution_capabilities.py

@@ -109,7 +109,10 @@ def test_capability_matrix_excludes_fractional_dca_profiles(self) -> None:
             runtime_adapter_loader=lambda profile: adapters[profile],
         )
 
-        self.assertEqual(eligible, frozenset())
+        # ``fractional_share_execution`` is a soft capability — profiles that
+        # require it are still eligible even when the platform lacks native
+        # support (compat mode converts notional → whole-share orders).
+        self.assertEqual(eligible, frozenset({"ibit_smart_dca"}))
 
 
 if __name__ == "__main__":