Add brokerage Financial Advisor account services - Feature 9707 fav2

Algorithm/Properties/AssemblyInfo.cs

@@ -1,4 +1,5 @@
 using System.Reflection;
+using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
 // General Information about an assembly is controlled through the following 
@@ -7,11 +8,13 @@
 [assembly: AssemblyTitle("QuantConnect.Algorithm")]
 [assembly: AssemblyProduct("QuantConnect.Algorithm")]
 [assembly: AssemblyCulture("")]
+[assembly: InternalsVisibleTo("QuantConnect.Lean.Engine")]
+[assembly: InternalsVisibleTo("QuantConnect.Tests")]
 
 // Setting ComVisible to false makes the types in this assembly not visible 
 // to COM components.  If you need to access a type in this assembly from 
 // COM, set the ComVisible attribute to true on that type.
 [assembly: ComVisible(false)]
 
 // The following GUID is for the ID of the typelib if this project is exposed to COM
-[assembly: Guid("5396be58-69fe-437e-8dd1-92c2aa7e9f14")]
+[assembly: Guid("5396be58-69fe-437e-8dd1-92c2aa7e9f14")]

Algorithm/QCAlgorithm.Python.cs

@@ -41,6 +41,92 @@ public partial class QCAlgorithm
     {
         private readonly Dictionary<IntPtr, PythonIndicator> _pythonIndicators = new Dictionary<IntPtr, PythonIndicator>();
 
+        /// <summary>
+        /// Requests an asynchronous replacement of an existing account group's allocation vector from a Python
+        /// dictionary using the version tokens from the supplied observed snapshot.
+        /// </summary>
+        /// <remarks>
+        /// Account-group mutations are available only after algorithm initialization completes and warm-up finishes.
+        /// Account-identifier case handling is brokerage-defined. A provider may reject identifiers that differ only
+        /// by case as duplicates.
+        /// A request issued during or after <see cref="OnEndOfAlgorithm"/> may be accepted but is not
+        /// guaranteed to reach the broker or publish a result. Algorithms must not request configuration
+        /// mutations during teardown.
+        /// </remarks>
+        /// <param name="groupName">Existing managed account group to update.</param>
+        /// <param name="accountAllocationValues">
+        /// Python dictionary containing the complete allocation vector, keyed by account identifier. Values must be
+        /// convertible to <see cref="decimal"/>.
+        /// </param>
+        /// <param name="observedSnapshot">Ready snapshot observed while calculating the requested values.</param>
+        /// <returns>
+        /// True when the request was accepted for asynchronous processing while the algorithm is running;
+        /// otherwise, false.
+        /// </returns>
+        [DocumentationAttribute(LiveTrading)]
+        public bool RequestBrokerageAccountGroupAllocationUpdate(
+            string groupName,
+            PyObject accountAllocationValues,
+            BrokerageAccountSnapshot observedSnapshot)
+        {
+            ArgumentNullException.ThrowIfNull(accountAllocationValues);
+            ArgumentNullException.ThrowIfNull(observedSnapshot);
+
+            var allocations = new Dictionary<string, decimal>(StringComparer.Ordinal);
+            using (Py.GIL())
+            {
+                if (!PyDict.IsDictType(accountAllocationValues))
+                {
+                    throw new ArgumentException(
+                        "Account allocation values must be a Python dictionary.",
+                        nameof(accountAllocationValues));
+                }
+
+                using var iterator = accountAllocationValues.GetIterator();
+                foreach (PyObject key in iterator)
+                {
+                    using (key)
+                    {
+                        if (!PyString.IsStringType(key))
+                        {
+                            throw new ArgumentException(
+                                "Account allocation dictionary keys must be strings.",
+                                nameof(accountAllocationValues));
+                        }
+
+                        var accountId = (string)key.AsManagedObject(typeof(string));
+                        ValidateBrokerageIdentifier(
+                            accountId,
+                            nameof(accountAllocationValues));
+                        using var value = accountAllocationValues.GetItem(key);
+                        decimal allocation;
+                        try
+                        {
+                            allocation = (decimal)value.AsManagedObject(typeof(decimal));
+                        }
+                        catch (Exception exception)
+                        {
+                            throw new ArgumentException(
+                                $"Allocation value for account '{accountId}' must be numeric.",
+                                nameof(accountAllocationValues),
+                                exception);
+                        }
+                        if (!allocations.TryAdd(accountId, allocation))
+                        {
+                            throw new ArgumentException(
+                                $"Allocation account identifier '{accountId}' is duplicated.",
+                                nameof(accountAllocationValues));
+                        }
+                    }
+                }
+            }
+
+            return RequestBrokerageAccountGroupAllocationUpdate(
+                groupName,
+                allocations,
+                observedSnapshot);
+        }
+
         /// <summary>
         /// PandasConverter for this Algorithm
         /// </summary>

AlgorithmFactory/Python/Wrappers/AlgorithmPythonWrapper.cs

@@ -47,7 +47,8 @@ namespace QuantConnect.AlgorithmFactory.Python.Wrappers
     /// <summary>
     /// Creates and wraps the algorithm written in python.
     /// </summary>
-    public class AlgorithmPythonWrapper : BasePythonWrapper<IAlgorithm>, IAlgorithm
+    public class AlgorithmPythonWrapper : BasePythonWrapper<IAlgorithm>, IAlgorithm,
+        IBrokerageAccountServiceConsumer
     {
         private readonly dynamic _onData;
         private readonly dynamic _onMarginCall;
@@ -679,6 +680,22 @@ public void OnEndOfTimeStep()
         /// </summary>
         public bool GetLocked() => _baseAlgorithm.GetLocked();
 
+        [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1033:Interface methods should be callable by child types",
+            Justification = "Engine-only service injection must not be exposed to Python algorithms.")]
+        void IBrokerageAccountServiceConsumer.SetBrokerageAccountStateProvider(IBrokerageAccountStateProvider provider) =>
+            ((IBrokerageAccountServiceConsumer)_baseAlgorithm).SetBrokerageAccountStateProvider(provider);
+
+        [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1033:Interface methods should be callable by child types",
+            Justification = "Engine-only service injection must not be exposed to Python algorithms.")]
+        void IBrokerageAccountServiceConsumer.SetBrokerageAccountGroupManager(IBrokerageAccountGroupManager manager) =>
+            ((IBrokerageAccountServiceConsumer)_baseAlgorithm).SetBrokerageAccountGroupManager(manager);
+
+        [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1033:Interface methods should be callable by child types",
+            Justification = "Engine-only service injection must not be exposed to Python algorithms.")]
+        void IBrokerageAccountServiceConsumer.SetBrokerageAccountGroupAllocationManager(
+            IBrokerageAccountGroupAllocationManager manager) =>
+            ((IBrokerageAccountServiceConsumer)_baseAlgorithm).SetBrokerageAccountGroupAllocationManager(manager);
+
         /// <summary>
         /// Gets a read-only dictionary with all current parameters
         /// </summary>

Common/Brokerages/BrokerageAccountCollection.cs

@@ -0,0 +1,95 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Linq;
+
+namespace QuantConnect.Brokerages
+{
+    internal static class BrokerageAccountCollection
+    {
+        public static IReadOnlyList<string> CopyIdentifiers(
+            IEnumerable<string> identifiers,
+            string parameterName)
+        {
+            var result = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var identifier in identifiers ?? Enumerable.Empty<string>())
+            {
+                ValidateIdentifier(identifier, parameterName);
+                if (!result.Add(identifier))
+                {
+                    throw new ArgumentException(
+                        $"Identifier '{identifier}' is duplicated.",
+                        parameterName);
+                }
+            }
+            return Array.AsReadOnly(
+                result.OrderBy(identifier => identifier, StringComparer.OrdinalIgnoreCase).ToArray());
+        }
+
+        public static IReadOnlyDictionary<string, TValue> CopyDictionary<TValue>(
+            IReadOnlyDictionary<string, TValue> source,
+            string parameterName,
+            Func<TValue, string> valueIdentifier = null,
+            StringComparer comparer = null)
+        {
+            var result = new Dictionary<string, TValue>(
+                comparer ?? StringComparer.OrdinalIgnoreCase);
+            if (source == null)
+            {
+                return new ReadOnlyDictionary<string, TValue>(result);
+            }
+
+            foreach (var pair in source)
+            {
+                ValidateIdentifier(pair.Key, parameterName);
+                var identifier = pair.Key;
+                if (valueIdentifier != null)
+                {
+                    var expectedIdentifier = valueIdentifier(pair.Value);
+                    if (string.IsNullOrEmpty(expectedIdentifier) ||
+                        !identifier.Equals(expectedIdentifier, StringComparison.OrdinalIgnoreCase))
+                    {
+                        throw new ArgumentException(
+                            $"Dictionary key '{identifier}' does not match its value identifier '{expectedIdentifier}'.",
+                            parameterName);
+                    }
+                }
+
+                if (!result.TryAdd(identifier, pair.Value))
+                {
+                    throw new ArgumentException(
+                        $"Dictionary identifier '{identifier}' is duplicated.",
+                        parameterName);
+                }
+            }
+
+            return new ReadOnlyDictionary<string, TValue>(result);
+        }
+
+        public static void ValidateIdentifier(string identifier, string parameterName)
+        {
+            if (string.IsNullOrWhiteSpace(identifier) ||
+                !identifier.Equals(identifier.Trim(), StringComparison.Ordinal))
+            {
+                throw new ArgumentException(
+                    "Identifiers must be non-empty and contain no leading or trailing whitespace.",
+                    parameterName);
+            }
+        }
+    }
+}

Common/Brokerages/BrokerageAccountDirectoryEntry.cs

@@ -0,0 +1,88 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+using System.Collections.Generic;
+using Newtonsoft.Json;
+
+namespace QuantConnect.Brokerages
+{
+    /// <summary>
+    /// Immutable directory entry for an account discovered through a multi-account brokerage connection.
+    /// </summary>
+    public class BrokerageAccountDirectoryEntry
+    {
+        /// <summary>
+        /// Gets the brokerage account identifier.
+        /// </summary>
+        public string AccountId { get; }
+
+        /// <summary>
+        /// Gets the account's relationship to the brokerage connection.
+        /// </summary>
+        public BrokerageAccountRelationship Relationship { get; }
+
+        /// <summary>
+        /// Gets every discovered group containing the account.
+        /// </summary>
+        public IReadOnlyList<string> GroupNames { get; }
+
+        /// <summary>
+        /// Gets the brokerage-reported account type when account state was collected and the brokerage supplied it;
+        /// otherwise, an empty string.
+        /// </summary>
+        public string AccountType { get; }
+
+        /// <summary>
+        /// Gets the brokerage-provided account-family code, when available.
+        /// </summary>
+        public string FamilyCode { get; }
+
+        /// <summary>
+        /// Gets the brokerage-provided account alias, when available.
+        /// </summary>
+        public string AccountAlias { get; }
+
+        /// <summary>
+        /// Initializes an immutable brokerage account directory entry.
+        /// </summary>
+        /// <param name="accountId">Brokerage account identifier.</param>
+        /// <param name="relationship">Relationship to the brokerage connection.</param>
+        /// <param name="groupNames">Discovered groups containing the account.</param>
+        /// <param name="accountType">
+        /// Brokerage-reported account type, or an empty string when not collected or not supplied.
+        /// </param>
+        /// <param name="familyCode">Brokerage-provided account-family code.</param>
+        /// <param name="accountAlias">Brokerage-provided account alias.</param>
+        [JsonConstructor]
+        public BrokerageAccountDirectoryEntry(
+            string accountId,
+            BrokerageAccountRelationship relationship,
+            IEnumerable<string> groupNames,
+            string accountType = "",
+            string familyCode = "",
+            string accountAlias = "")
+        {
+            BrokerageAccountCollection.ValidateIdentifier(accountId, nameof(accountId));
+            AccountId = accountId;
+            Relationship = relationship;
+            GroupNames = BrokerageAccountCollection.CopyIdentifiers(
+                groupNames,
+                nameof(groupNames));
+            AccountType = accountType?.Trim() ?? string.Empty;
+            FamilyCode = familyCode?.Trim() ?? string.Empty;
+            AccountAlias = accountAlias?.Trim() ?? string.Empty;
+        }
+    }
+}