investing-algorithm-framework 9.0.0a2__tar.gz → 9.0.0a3__tar.gz

{investing_algorithm_framework-9.0.0a2 → investing_algorithm_framework-9.0.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 9.0.0a2
+Version: 9.0.0a3
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10,<4.0
@@ -10,25 +10,25 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Provides-Extra: all
 Provides-Extra: alpha-vantage
+Provides-Extra: aws
+Provides-Extra: azure
 Provides-Extra: polygon
 Provides-Extra: yahoo
 Requires-Dist: Flask (>=3.1.0)
 Requires-Dist: Flask-Cors (>=3.0.9,<7.0.0)
-Requires-Dist: Flask-Migrate (>=2.6.0)
 Requires-Dist: SQLAlchemy (>=2.0.18)
 Requires-Dist: alpha_vantage (>=3.0.0,<4.0.0) ; extra == "alpha-vantage" or extra == "all"
-Requires-Dist: azure-identity (>=1.19.0,<2.0.0)
-Requires-Dist: azure-mgmt-resource (>=23.2.0,<24.0.0)
-Requires-Dist: azure-mgmt-storage (>=21.2.1,<22.0.0)
-Requires-Dist: azure-mgmt-web (>=7.3.1,<8.0.0)
-Requires-Dist: azure-storage-blob (>=12.24.0,<13.0.0)
-Requires-Dist: boto3 (>=1.38.41,<2.0.0)
+Requires-Dist: azure-identity (>=1.19.0,<2.0.0) ; extra == "azure" or extra == "all"
+Requires-Dist: azure-mgmt-resource (>=23.2.0,<24.0.0) ; extra == "azure" or extra == "all"
+Requires-Dist: azure-mgmt-storage (>=21.2.1,<22.0.0) ; extra == "azure" or extra == "all"
+Requires-Dist: azure-mgmt-web (>=7.3.1,<8.0.0) ; extra == "azure" or extra == "all"
+Requires-Dist: azure-storage-blob (>=12.24.0,<13.0.0) ; extra == "azure" or extra == "all"
+Requires-Dist: boto3 (>=1.38.41,<2.0.0) ; extra == "aws" or extra == "all"
 Requires-Dist: ccxt (>=4.2.48)
 Requires-Dist: dependency-injector (>=4.40.0)
-Requires-Dist: jupyter (>=1.0.0)
+Requires-Dist: finterion-charts (==1.4.0)
 Requires-Dist: marshmallow (>=3.5.0)
 Requires-Dist: msgpack (>=1.0.0)
-Requires-Dist: plotly (>=6.1.2,<7.0.0)
 Requires-Dist: polars[numpy,pandas] (>=0.20.10)
 Requires-Dist: polygon-api-client (>=1.14.0,<2.0.0) ; extra == "polygon" or extra == "all"
 Requires-Dist: pyarrow (>=14.0.0)

investing_algorithm_framework-9.0.0a3/investing_algorithm_framework/app/algorithm_runner.py

@@ -0,0 +1,236 @@
+import json
+import logging
+import os
+import threading
+from datetime import datetime, timezone
+from typing import Optional
+
+from investing_algorithm_framework.domain import OperationalException
+
+logger = logging.getLogger("investing_algorithm_framework")
+
+NOT_STARTED = "NOT_STARTED"
+RUNNING = "RUNNING"
+STOPPING = "STOPPING"
+STOPPED = "STOPPED"
+
+CONTROL_FILE_NAME = "algorithm_control.json"
+
+
+class AlgorithmRunner:
+    """
+    Thread-safe controller that runs an ``EventLoopService`` in a
+    background thread so the trading algorithm can be started and
+    stopped on demand (e.g. from the web API) without killing the
+    process that hosts it.
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._thread: Optional[threading.Thread] = None
+        self._event_loop_service = None
+        self._run_kwargs = {}
+        self._status = NOT_STARTED
+        self._started_at = None
+        self._stopped_at = None
+        self._error = None
+        self._resource_directory = None
+        self._state_handler = None
+
+    def bind_persistence(self, resource_directory, state_handler=None) -> None:
+        """
+        Wires where the enabled/disabled control flag is persisted.
+
+        This is what makes ``enable()``/``disable()`` meaningful for
+        *stateless* deployments (AWS Lambda, Azure Functions): the
+        flag file lives inside ``resource_directory``, the same
+        directory a configured ``state_handler`` already uploads/
+        downloads on every run. Passing the state handler here makes a
+        toggle take effect immediately (pushed on the spot) instead of
+        waiting for the next natural save.
+        """
+        with self._lock:
+            self._resource_directory = resource_directory
+            self._state_handler = state_handler
+
+    def _control_file_path(self) -> Optional[str]:
+        if self._resource_directory is None:
+            return None
+        os.makedirs(self._resource_directory, exist_ok=True)
+        return os.path.join(self._resource_directory, CONTROL_FILE_NAME)
+
+    def get_control_state(self) -> dict:
+        """Returns the persisted enabled/disabled control state."""
+        default = {"enabled": True, "reason": None, "updated_at": None}
+        path = self._control_file_path()
+
+        if path is None or not os.path.exists(path):
+            return default
+
+        try:
+            with open(path, "r") as f:
+                return {**default, **json.load(f)}
+        except (OSError, ValueError) as e:
+            logger.warning(f"Could not read algorithm control file: {e}")
+            return default
+
+    def is_enabled(self) -> bool:
+        """Enabled by default when no control file has been written yet."""
+        return self.get_control_state().get("enabled", True)
+
+    def _persist_enabled(
+        self, enabled: bool, reason: Optional[str] = None
+    ) -> None:
+        path = self._control_file_path()
+
+        if path is None:
+            return
+
+        state = {
+            "enabled": enabled,
+            "reason": reason,
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+        with open(path, "w") as f:
+            json.dump(state, f)
+
+        if self._state_handler is not None:
+            try:
+                self._state_handler.save(self._resource_directory)
+            except Exception as e:
+                logger.warning(
+                    "Could not push algorithm control state via the "
+                    f"configured state handler: {e}"
+                )
+
+    def enable(self, reason: Optional[str] = None) -> None:
+        """Persists 'enabled', independent of any in-process thread."""
+        self._persist_enabled(True, reason=reason)
+
+    def disable(self, reason: Optional[str] = None) -> None:
+        """Persists 'disabled', independent of any in-process thread."""
+        self._persist_enabled(False, reason=reason)
+
+    def configure(self, event_loop_service, **run_kwargs) -> None:
+        """
+        Wires the event loop service (and any kwargs for its
+        ``start()`` method) that ``start``/``stop`` will control.
+        Safe to call again after a ``stop()`` to reconfigure before
+        the next ``start()``.
+        """
+        with self._lock:
+            self._event_loop_service = event_loop_service
+            self._run_kwargs = run_kwargs
+
+    @property
+    def status(self) -> str:
+        with self._lock:
+            return self._status
+
+    @property
+    def is_running(self) -> bool:
+        return self.status == RUNNING
+
+    def get_status_report(self) -> dict:
+        with self._lock:
+            return {
+                "status": self._status,
+                "started_at": self._started_at.isoformat()
+                if self._started_at else None,
+                "stopped_at": self._stopped_at.isoformat()
+                if self._stopped_at else None,
+                "error": self._error,
+            }
+
+    def start(self) -> bool:
+        """
+        Starts (or resumes) the algorithm loop in a background thread.
+
+        Returns:
+            bool: True if a new run was started, False if the
+                algorithm was already running.
+
+        Raises:
+            OperationalException: If the runner has not been
+                configured with an event loop service yet (i.e. the
+                app has never been run).
+        """
+        with self._lock:
+            if self._event_loop_service is None:
+                raise OperationalException(
+                    "The algorithm has not been initialized yet. Run "
+                    "the app at least once before starting it "
+                    "through the API."
+                )
+
+            if self._status == RUNNING:
+                self.enable()
+                return False
+
+            self._event_loop_service.reset_stop()
+            self._error = None
+            self._started_at = datetime.now(timezone.utc)
+            self._stopped_at = None
+            self._status = RUNNING
+            event_loop_service = self._event_loop_service
+            run_kwargs = self._run_kwargs
+
+        def _run():
+            try:
+                event_loop_service.start(**run_kwargs)
+            except Exception as e:
+                logger.error(f"Algorithm loop stopped with an error: {e}")
+                with self._lock:
+                    self._error = str(e)
+            finally:
+                with self._lock:
+                    self._status = STOPPED
+                    self._stopped_at = datetime.now(timezone.utc)
+
+        self._thread = threading.Thread(
+            name="Algorithm Loop", target=_run, daemon=True
+        )
+        self._thread.start()
+        self.enable()
+        return True
+
+    def stop(
+        self,
+        wait: bool = False,
+        timeout: float = 10,
+        reason: Optional[str] = None,
+    ) -> bool:
+        """
+        Signals the running algorithm loop to stop after its current
+        iteration completes, and persists 'disabled' regardless of
+        whether a loop is currently running in-process (this is what a
+        stateless/serverless deployment, e.g. AWS Lambda or Azure
+        Functions, checks on its next scheduled invocation).
+
+        Args:
+            wait: If True, blocks until the background thread has
+                actually exited (bounded by ``timeout`` seconds).
+            timeout: Max seconds to wait for the thread to exit when
+                ``wait`` is True.
+            reason: Optional human-readable reason, persisted alongside
+                the disabled state.
+
+        Returns:
+            bool: True if a running in-process loop was signaled to
+                stop, False if it was not running (the disabled state
+                is still persisted either way).
+        """
+        self.disable(reason=reason)
+
+        with self._lock:
+            if self._status != RUNNING:
+                return False
+            self._status = STOPPING
+            self._event_loop_service.request_stop()
+            thread = self._thread
+
+        if wait and thread is not None:
+            thread.join(timeout=timeout)
+
+        return True

{investing_algorithm_framework-9.0.0a2 → investing_algorithm_framework-9.0.0a3}/investing_algorithm_framework/app/app.py

@@ -787,6 +787,74 @@ class App:
             configuration_service.add_value(APP_MODE, AppMode.WEB.value)
             self._initialize_web()
 
+    def _bind_algorithm_control_persistence(self):
+        """
+        Wires the algorithm runner's enabled/disabled control file to
+        this app's resource directory (and state handler, if any).
+        Safe to call multiple times/from multiple entry points
+        (``run()``, ``start_algorithm()``, ``stop_algorithm()``,
+        ``is_algorithm_enabled()``) since it just re-binds the same
+        path.
+        """
+        algorithm_runner = self.container.algorithm_runner()
+        algorithm_runner.bind_persistence(
+            self.resource_directory_path, state_handler=self._state_handler
+        )
+        return algorithm_runner
+
+    def start_algorithm(self) -> bool:
+        """
+        Enables the algorithm and, if it is currently running live in
+        this process, resumes it. In a stateless deployment (AWS
+        Lambda, Azure Functions) there is no in-process loop to
+        resume — enabling it here is enough, since ``run()`` checks
+        this same persisted flag on every future invocation.
+
+        Returns:
+            bool: True if an in-process loop was (re)started, False
+                otherwise (already running, or no live loop to
+                resume).
+        """
+        algorithm_runner = self._bind_algorithm_control_persistence()
+
+        try:
+            return algorithm_runner.start()
+        except OperationalException:
+            # No live event loop configured yet (e.g. this app has
+            # never called `run()` in this process, or it's a
+            # stateless deployment) — persisting 'enabled' is enough.
+            algorithm_runner.enable()
+            return False
+
+    def stop_algorithm(self, reason: str = None, wait: bool = False) -> bool:
+        """
+        Disables the algorithm and, if it is currently running live in
+        this process, signals it to stop after its current iteration.
+        In a stateless deployment (AWS Lambda, Azure Functions), this
+        persists 'disabled' so the next scheduled invocation of
+        ``run()`` skips its iteration entirely.
+
+        Args:
+            reason: Optional human-readable reason to persist
+                alongside the disabled state.
+            wait: If True, blocks until the in-process loop (if any)
+                has actually exited.
+
+        Returns:
+            bool: True if an in-process loop was signaled to stop,
+                False otherwise (it wasn't running).
+        """
+        algorithm_runner = self._bind_algorithm_control_persistence()
+        return algorithm_runner.stop(reason=reason, wait=wait)
+
+    def is_algorithm_enabled(self) -> bool:
+        """Returns whether the algorithm is currently enabled."""
+        return self._bind_algorithm_control_persistence().is_enabled()
+
+    def get_algorithm_control_state(self) -> dict:
+        """Returns the persisted enabled/disabled control state."""
+        return self._bind_algorithm_control_persistence().get_control_state()
+
     def run(self, number_of_iterations: int = None):
         """
         Entry point to run the application. This method should be called to
@@ -834,6 +902,17 @@ class App:
             config = self.container.configuration_service().get_config()
             self._state_handler.load(config[RESOURCE_DIRECTORY])
 
+        algorithm_runner = self._bind_algorithm_control_persistence()
+
+        if not algorithm_runner.is_enabled():
+            control_state = algorithm_runner.get_control_state()
+            logger.info(
+                "Algorithm is disabled (stopped via the control API "
+                f"or control file, reason: {control_state.get('reason')})"
+                " — skipping this run."
+            )
+            return
+
         self.initialize_storage()
         logger.info("App initialization complete")
         event_loop_service = None
@@ -852,9 +931,12 @@ class App:
             self.initialize_services()
             self.initialize_portfolios()
 
-            if AppMode.WEB.equals(self.config[APP_MODE]) \
-                    and not (self._flask_app and self._flask_app.testing) \
-                    and number_of_iterations is None:
+            is_live_web_run = AppMode.WEB.equals(self.config[APP_MODE]) \
+                and not (self._flask_app and self._flask_app.testing) \
+                and number_of_iterations is None
+            flask_thread = None
+
+            if is_live_web_run:
                 logger.info("Running web")
                 flask_thread = threading.Thread(
                     name='Web App',
@@ -889,12 +971,28 @@ class App:
                 algorithm, trade_order_evaluator=trade_order_evaluator
             )
 
-            try:
-                event_loop_service.start(
-                    number_of_iterations=number_of_iterations
-                )
-            except KeyboardInterrupt:
-                exit(0)
+            if is_live_web_run:
+                # Run the event loop in its own background thread so
+                # the web API can start/stop it on demand (see
+                # `/api/algorithm/start` and `/api/algorithm/stop`)
+                # without killing the process. The main thread just
+                # keeps the process alive alongside the Flask thread.
+                algorithm_runner.configure(event_loop_service)
+                algorithm_runner.start()
+
+                try:
+                    while flask_thread.is_alive():
+                        flask_thread.join(timeout=1)
+                except KeyboardInterrupt:
+                    algorithm_runner.stop(wait=True)
+                    exit(0)
+            else:
+                try:
+                    event_loop_service.start(
+                        number_of_iterations=number_of_iterations
+                    )
+                except KeyboardInterrupt:
+                    exit(0)
         except Exception as e:
             logger.error(e)
             raise e
@@ -1547,9 +1645,8 @@ class App:
     ) -> Backtest:
         """
         Run vectorized backtests for a strategy. The provided
-        strategy needs to have its 'generate_buy_signals' and
-        'generate_sell_signals' methods implemented to support vectorized
-        backtesting.
+        strategy needs to have its 'generate_signal_series' method
+        implemented to support vectorized backtesting.
 
         Args:
             strategy (TradingStrategy) (Optional): The strategy object
@@ -2258,9 +2355,8 @@ class App:
     ) -> Backtest:
         """
         Run vectorized backtests for a strategy. The provided
-        strategy needs to have its 'generate_buy_signals' and
-        'generate_sell_signals' methods implemented to support vectorized
-        backtesting.
+        strategy needs to have its 'generate_signal_series' method
+        implemented to support vectorized backtesting.
 
         Args:
             strategy (TradingStrategy) (Optional): The strategy object

{investing_algorithm_framework-9.0.0a2 → investing_algorithm_framework-9.0.0a3}/investing_algorithm_framework/app/eventloop.py

@@ -1,4 +1,5 @@
 from datetime import datetime, timezone
+from threading import Event
 from time import sleep
 from typing import List, Set, Dict
 from logging import getLogger
@@ -81,12 +82,34 @@ class EventLoopService:
         self.data_sources = set()
         self.next_run_times = {}
         self._scheduled_function_last_runs = {}
+        self._task_last_runs = {}
         self.history = {}
 
         # One-shot flag: live-mode envelope validation runs once per
         # process. Reset by ``cleanup`` so a new run re-validates.
         self._pipelines_live_validated: bool = False
 
+        # Set by ``request_stop`` to gracefully break out of the live
+        # (unbounded) loop in ``start``. Cleared by ``reset_stop`` so
+        # the loop can be (re)started again afterwards.
+        self._stop_event = Event()
+
+    def request_stop(self) -> None:
+        """
+        Signals a running (unbounded) ``start()`` call to stop after
+        it finishes its current iteration. Safe to call from another
+        thread.
+        """
+        self._stop_event.set()
+
+    def reset_stop(self) -> None:
+        """Clears a previous stop request so ``start()`` can run again."""
+        self._stop_event.clear()
+
+    @property
+    def stop_requested(self) -> bool:
+        return self._stop_event.is_set()
+
     @staticmethod
     def _get_data_sources_for_iteration(
         strategy_data_sources
@@ -194,6 +217,52 @@ class EventLoopService:
 
         return due
 
+    def _get_tasks_by_ids(self, task_ids: List[str]):
+        """
+        Returns the tasks matching the given worker IDs. Unlike
+        ``_get_strategies``, an empty/None ``task_ids`` means "no
+        tasks are due" (not "all tasks") — the backtest schedule
+        always provides an explicit (possibly empty) list per tick.
+
+        Args:
+            task_ids: A list of task worker IDs to retrieve.
+
+        Returns:
+            List[Task]: The tasks matching the provided IDs.
+        """
+        if not task_ids:
+            return []
+
+        return [
+            self._tasks_lookup[task_id]
+            for task_id in task_ids
+            if task_id in self._tasks_lookup
+        ]
+
+    def _get_due_tasks(self, current_datetime=None):
+        """
+        Checks which tasks are due to run based on their Schedule.
+
+        Args:
+            current_datetime: Optional; the datetime to check against.
+                If None, uses the current datetime in UTC.
+
+        Returns:
+            List[Task]: A list of tasks that are due to run.
+        """
+        due = []
+
+        if current_datetime is None:
+            current_datetime = datetime.now(timezone.utc)
+
+        for task in self.tasks:
+            last_run = self._task_last_runs.get(task.worker_id)
+            if task.schedule.is_due(current_datetime, last_run):
+                due.append(task)
+                self._task_last_runs[task.worker_id] = current_datetime
+
+        return due
+
     def _get_due_scheduled_functions(self, current_datetime=None):
         """
         Returns a list of (strategy, ScheduledFunction) tuples whose
@@ -341,6 +410,10 @@ class EventLoopService:
             for strategy in self.strategies
         }
         self._scheduled_function_last_runs = {}
+        self._task_last_runs = {}
+        self._tasks_lookup = {
+            task.worker_id: task for task in self.tasks
+        }
 
         # Collect all data sources and initialize history
         for strategy in self.strategies:
@@ -419,11 +492,14 @@ class EventLoopService:
                     )
                     strategy_ids = schedule[current_time]["strategy_ids"]
                     strategies = self._get_strategies(strategy_ids)
+                    task_ids = schedule[current_time]["task_ids"]
+                    tasks = self._get_tasks_by_ids(task_ids)
                     sf_calls = schedule[current_time].get(
                         "scheduled_function_calls", []
                     )
                     self._run_iteration(
                         strategies=strategies,
+                        tasks=tasks,
                         scheduled_function_calls=sf_calls,
                     )
 
@@ -433,34 +509,45 @@ class EventLoopService:
                         INDEX_DATETIME, current_time
                     )
                     strategy_ids = schedule[current_time]["strategy_ids"]
-                    # task_ids = schedule[current_time]["task_ids"]
+                    task_ids = schedule[current_time]["task_ids"]
                     strategies = self._get_strategies(strategy_ids)
+                    tasks = self._get_tasks_by_ids(task_ids)
                     sf_calls = schedule[current_time].get(
                         "scheduled_function_calls", []
                     )
                     self._run_iteration(
                         strategies=strategies,
+                        tasks=tasks,
                         scheduled_function_calls=sf_calls,
                     )
         else:
             if number_of_iterations is None:
-                try:
-                    config = self._configuration_service.config
-                    current_time = config[INDEX_DATETIME]
-                    strategies = self._get_due_strategies(current_time)
-                    sf_calls = self._get_due_scheduled_functions(current_time)
-                    self._run_iteration(
-                        strategies=strategies,
-                        tasks=self.tasks,
-                        scheduled_function_calls=sf_calls,
-                    )
-                    current_time = datetime.now(timezone.utc)
-                    self._configuration_service.add_value(
-                        INDEX_DATETIME, current_time
-                    )
-                    sleep(1)
-                except KeyboardInterrupt:
-                    exit(0)
+                # Unbounded live loop: keeps iterating until a stop is
+                # requested (e.g. via ``request_stop()`` from the web
+                # API) or the process receives a KeyboardInterrupt.
+                while not self._stop_event.is_set():
+                    try:
+                        config = self._configuration_service.config
+                        current_time = config[INDEX_DATETIME]
+                        strategies = self._get_due_strategies(current_time)
+                        tasks = self._get_due_tasks(current_time)
+                        sf_calls = \
+                            self._get_due_scheduled_functions(current_time)
+                        self._run_iteration(
+                            strategies=strategies,
+                            tasks=tasks,
+                            scheduled_function_calls=sf_calls,
+                        )
+                        current_time = datetime.now(timezone.utc)
+                        self._configuration_service.add_value(
+                            INDEX_DATETIME, current_time
+                        )
+                    except KeyboardInterrupt:
+                        break
+                    # Wakes up immediately if a stop is requested
+                    # instead of always waiting out the full second.
+                    if self._stop_event.wait(1):
+                        break
             else:
 
                 if show_progress:
@@ -472,11 +559,12 @@ class EventLoopService:
                             config = self._configuration_service.config
                             current_time = config[INDEX_DATETIME]
                             strategies = self._get_due_strategies(current_time)
+                            tasks = self._get_due_tasks(current_time)
                             sf_calls = \
                                 self._get_due_scheduled_functions(current_time)
                             self._run_iteration(
                                 strategies=strategies,
-                                tasks=self.tasks,
+                                tasks=tasks,
                                 scheduled_function_calls=sf_calls,
                             )
                             current_time = datetime.now(timezone.utc)
@@ -492,11 +580,12 @@ class EventLoopService:
                         config = self._configuration_service.config
                         current_time = config[INDEX_DATETIME]
                         strategies = self._get_due_strategies(current_time)
+                        tasks = self._get_due_tasks(current_time)
                         sf_calls = \
                             self._get_due_scheduled_functions(current_time)
                         self._run_iteration(
                             strategies=strategies,
-                            tasks=self.tasks,
+                            tasks=tasks,
                             scheduled_function_calls=sf_calls,
                         )
                         current_time = datetime.now(timezone.utc)
@@ -747,17 +836,17 @@ class EventLoopService:
             ohlcv_data=orders_trades_update_ohlcv_data
         )
 
-        # Step 4: Run all tasks
-        for task in self.tasks:
-            task.run(data_object)
+        # Step 4: Run all due tasks. ``tasks`` is the caller-resolved,
+        # schedule-filtered list (see _get_due_tasks/_get_tasks_by_ids);
+        # fall back to every registered task only if no list was given.
+        for task in (self.tasks if tasks is None else tasks):
+            logger.info(f"Running task {task.worker_id}")
+            task.run(self.context)
 
         # Step 5: Run all strategies
         if not strategies:
             return
 
-        for task in self.tasks:
-            logger.info(f"Running task {task.__class__.__name__}")
-
         for strategy in strategies:
 
             if strategy.data_sources is not None: