Skip to content

README.md

Latest commit

 

History

History
114 lines (83 loc) · 7.08 KB

README.md

File metadata and controls

114 lines (83 loc) · 7.08 KB
Raw

QuantRuntimeSettings

QSL architecture role

  • Layer: ops/tooling.
  • Responsibility: central runtime settings and compatibility control plane.
  • Owns: platform-config.json, compat bundles, dependency matrix, switch tooling.
  • Consumes: all runtime platforms and internal dependency consumers.
  • Must not: submit broker orders or replace strategy evidence gates.

Chinese README

Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only.

What this repository is

QuantRuntimeSettings is a QuantStrategyLab runtime settings package. It defines schemas and tooling for versioned runtime settings shared across QuantStrategyLab platforms.

It supports the system but does not decide which strategy should be live. Strategy eligibility remains in the strategy and snapshot repositories; broker execution remains in the platform repositories.

Design boundary

  • Keep contracts stable and versioned where downstream repositories depend on them.
  • Prefer backward-compatible changes unless a coordinated migration is planned.
  • Keep secrets and environment-specific settings outside the shared library code.
  • Document changes that affect multiple platforms or strategy packages.

Repository layout

  • python/: Python tooling (scripts, tests, pyproject.toml) — validation, code generation, deployment scripts.
  • web/: JavaScript web app (Cloudflare Workers strategy switch console).
  • compat/: QSL compatibility manifests (bundle matrix and repo tier rules).
  • schemas/: JSON Schema files shared by both Python and JS.
  • tests/: JavaScript unit/integration tests.
  • .github/workflows/: CI, scheduled jobs, release, or deployment workflows.
  • docs/ARCHITECTURE.md: Detailed architecture documentation.

QSL compatibility manifest (phase 1)

This repository is the central manifest source for QSL compatibility checks.

  • qsl.toml: current repo QSL metadata (tier, upgrade_ring, bundle).
  • scripts/check_qsl_compat.py: validate a repo's QSL compliance in pyproject.toml/uv.lock against central bundle.
  • python/scripts/qslctl.py: unified QSL version-control CLI for repo checks, workspace checks, ring reports/plans, and matrix generation.
  • scripts/render_qsl_dependency_graph.py: render dependency graph for review.
  • compat/bundles/2026.07.3.toml: current compatibility bundle baseline (CalVer).
  • compat/repo-tiers.toml: repo tier and upgrade ring policy notes.
  • QSL compatibility docs

Quick start

python3 python/scripts/runtime_settings.py validate
python3 -m unittest discover -s python/tests -v

Manual Strategy Switch

.github/workflows/manual-strategy-switch.yml provides a central manual switch entrypoint. It builds a transient runtime target from workflow inputs, validates it with python/scripts/runtime_settings.py, and writes GitHub variables into the target platform repository. It supports longbridge, ibkr, schwab, firstrade, qmt, and binance.

Recommended flow:

  1. Run once with apply=false to preview the assignments.
  2. Check repository, environment, strategy_profile, service_name, execution_mode, and plugin mounts.
  3. Re-run with apply=true and confirm_apply=APPLY to write variables.
  4. For a Cloud Run platform, set trigger_platform_sync=true and confirm_apply=APPLY_AND_SYNC to dispatch its environment sync workflow.

Example:

platform=longbridge
target_name=sg
strategy_profile=tqqq_growth_income
execution_mode=live
plugin_mode=auto
apply=true
trigger_platform_sync=true
confirm_apply=APPLY_AND_SYNC

Notes:

  • This is a GitHub Actions workflow_dispatch form, not a public web app. The default apply=false mode only previews assignments and writes nothing remotely.
  • LongBridge defaults to environment-scoped variables; target_name=sg resolves to longbridge-sg. When a repository-level multi-service target list exists, the same switch also updates its exact service entry.
  • Multi-service targets use service_name as their primary identity. Multiple services may share one account_scope; a switch never selects a sibling service by account scope.
  • CLOUD_RUN_SERVICE_TARGETS_JSON supports both a bare array and an object with targets. New services require the explicit allow_create mode.
  • Schwab defaults to repository-scoped variables.
  • Firstrade defaults to repository-scoped variables; target_name=live uses firstrade-quant-service and account_scope=US.
  • IBKR service_targets_mode=auto patches the exact existing service entry inside CLOUD_RUN_SERVICE_TARGETS_JSON; account scope is only a fallback for a legacy entry with no service identity. Other services are preserved and an unknown target fails closed. Use allow_create only when intentionally provisioning a new target.
  • Cross-repository variable writes and workflow dispatches require a RUNTIME_SETTINGS_GH_TOKEN secret in this repository with sufficient target-repository variable/workflow permissions. The workflow does not fall back to the default github.token for remote writes.
  • LongBridge, IBKR, Schwab, and Firstrade service_targets_mode=auto checks the target repository's multi-service inventory, so even preview mode requires RUNTIME_SETTINGS_GH_TOKEN.
  • Binance runs through an Oracle Cloud VPS self-hosted runner. Repository variable writes are consumed by the next externally scheduled main.yml dispatch; the central switch does not dispatch that runtime workflow because it may execute live trading. A strategy cadence change also requires a separate review of the external VPS scheduler.
  • QMT remains dry-run only and has no live deployment configuration. Its generated target can stage repository variables, but trigger_platform_sync=true is rejected.
  • The workflow is bound to the runtime-strategy-switch GitHub Environment. For a personal system, required reviewers are optional; prefer storing RUNTIME_SETTINGS_GH_TOKEN as an Environment secret and rely on preview, confirmation text, and a least-privilege token for day-to-day safety.
  • Follow the simplified permission-control plan before enabling real switches: docs/manual_strategy_switch_permission_control.zh-CN.md.

Useful docs

Community and security

  • See CONTRIBUTING.md for pull request scope, local verification, and documentation expectations.
  • Follow CODE_OF_CONDUCT.md for maintainer and contributor conduct.
  • Report credential, automation, broker, exchange, or cloud-resource vulnerabilities through SECURITY.md; do not open public issues for secrets or live-execution risk.

License

See LICENSE.