API
Open Dashboard

Import surface

Only ClientBase is documented on this page. db_handler, email_manager, settings, and send_email are re-exports — see db_handler, email_manager, and settings for their full method surfaces.

Importpython
from quantstrip import (
    ClientBase,      # base class for your client
    db_handler,      # DBHandler singleton
    email_manager,   # EmailManager singleton
    settings,        # Settings singleton
    send_email,      # shorthand for email_manager.send()
)

class ClientBase

Base class for every client. Subclass it, do your setup in __init__ (after calling super().__init__()), and schedule jobs on self.scheduler (a schedule.Scheduler). You never start it yourself — deploy the file through the Python IDE, which moves it into the live clients/ root directory, and service.py's main loop picks it up and starts it automatically.

Minimal clientpython
from quantstrip import ClientBase
import logging

logger = logging.getLogger(__name__)

class Client(ClientBase):
    def __init__(self, *args):
        super().__init__()
        self.display_name = "Default Client"
        self.client_category = "Other"
        self.scheduler.every(1).seconds.do(self.job)

    def job(self):
        try:
            logger.info(f"Hello from {self.display_name}")
        except Exception as e:
            logger.error(f"job failed: {e}", exc_info=True)
            self.notify_exception(f"{type(e).__name__}: {e}")
        finally:
            self.stop_client()

stop_client()

The one lifecycle method a client might realistically call on itself — typically from a job's finally block, to run once and then stop (a one-shot test client, for example; see the minimal example above). Sets the internal stop flag; the running main_loop thread exits on its next iteration.

start_client()

Resets lifecycle state — clears the stop flag, records the start timestamp, resets job_count and last_job_error, and stamps the initial heartbeat. Part of the platform's own start sequence, called automatically by run_client — not something a client calls itself.

get_resource_usage()

Returns None if the client hasn't been started yet. Otherwise a dict: cpu_percent · thread_count · last_heartbeat · job_count · last_job_error. Backs the stats shown in the Client Monitor.

run_client(client_id, thread_name = "Client - main_loop")

Called by service.py's main loop when a client is deployed — not something your own client code calls. Starts main_loop on a background thread and sets is_running = True. No-ops if already running, so a stray second call can't spawn a second thread sharing this instance's schedule.Scheduler, which isn't thread-safe.


main_loop()

Runs on the background thread started by run_client. Every 100ms: runs any pending jobs on self.scheduler, increments job_count, and updates the heartbeat. Continues until the stop flag is set.

A single job raising an exception is caught, logged, and recorded in last_job_error — it does not stop the loop, and notify_exception fires the generic alert email. An exception in the loop itself (outside a job) is fatal: it's logged, exception is set to a "FATAL: ..." string, and the client stops.

Warning

schedule's Job.run() calls your job function before advancing its own next_run. An uncaught exception inside a job freezes next_run in the past, and the job retries on every ~100ms tick instead of its real interval.

Wrap your job's entire body in its own try/except — don't rely on main_loop's outer catch to protect you from this.


notify_exception(error_message, traceback_text = None)

Sends the generic "this client hit an exception" alert email — the safety net main_loop falls back to for any client that doesn't already have its own more specific failure email. Throttled to at most once per failure streak. Recipient: a Settings entry named after the client's module under Settings/Notifications/Exception Alert Email, falling back to that folder's Default entry. Silently a no-op (logged once) if neither is configured.

clear_exception_throttle()

Call at the end of a job that has its own try/except and completed successfully. Without this, a client with its own try/except gets a fresh alert email on every poll tick after a failure instead of once per failure streak.

Job try/exceptpython
def job(self):
    try:
        ...
        self.clear_exception_throttle()
    except Exception as e:
        logger.error(f"job failed: {e}", exc_info=True)
        self.notify_exception(f"{type(e).__name__}: {e}")

Contract

  • Class name must be exactly Client — the loader uses getattr(module, "Client").
  • Constructor accepts *args — the service passes itself as the first argument during load; a strategy typically doesn't need it.
  • Set self.display_name — the name shown for this client in the Client Monitor.
  • Set self.client_category — which section of the Client Monitor this client is grouped under. If a section with that name already exists, the client joins it; otherwise the Monitor generates a new section for it. Defaults to "Other" if unset.
  • Schedule jobs on self.scheduler — the schedule library, one instance per client.
  • Wrap every job's full body in its own try/except — see the warning above.
  • Deploy through the Python IDE to go live — service.py's main loop starts it automatically; you don't call run_client() yourself.
Client Monitor grouping

"Strategy", "Trade Processing", and "Other" are the built-in sections, shown in that order. Any other self.client_category string gets its own new section.