Initial open strategy plugins

Author: Pigbibi

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[test]'
+      - name: Run tests
+        run: python -m pytest -q
+      - name: Ruff
+        run: ruff check .

.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+data/output/
+*.pyc

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantStrategyLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,57 @@
+# QuantStrategyPlugins
+
+Open sidecar strategy plugins for QuantStrategyLab runtimes.
+
+The repository emits JSON signal artifacts that are consumed through
+`quant_platform_kit.common.strategy_plugins`. Platform repositories such as
+Interactive Brokers, Schwab, LongBridge, and Firstrade only load artifacts and
+send notifications; plugin research and signal generation live here.
+
+## What Is Public
+
+- Plugin source code and synthetic tests.
+- The artifact schema used by platform runtimes.
+- Example local TOML config with placeholder paths.
+
+## What Stays Out
+
+- Broker credentials, tokens, account IDs, and SMTP settings.
+- GCS bucket names, Cloud Run service names, and production deploy workflows.
+- Generated `data/output` artifacts and proprietary runtime configuration.
+- Non-public datasets. Tests use synthetic price histories.
+
+## Plugins
+
+- `crisis_response_shadow`: black-swan defense observer for leveraged US equity
+  strategies. It writes shadow-mode artifacts and never calls brokers.
+- `taco_rebound_shadow`: research-only rebound-budget observer. The generic
+  runner keeps it gated until promotion criteria are met.
+
+## Usage
+
+Run a plugin config:
+
+```bash
+qsp-run-strategy-plugins --config docs/examples/strategy_plugins.example.toml
+```
+
+Build a crisis response artifact directly from a local price-history CSV:
+
+```bash
+qsp-build-crisis-response-shadow-signal \
+  --prices data/input/price_history.csv \
+  --as-of 2026-05-22 \
+  --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow
+```
+
+Generated artifacts include `latest_signal.json`, dated JSON, dated CSV, and
+an evidence CSV. `latest_signal.json` is the file platform runtimes mount via
+`*_STRATEGY_PLUGIN_MOUNTS_JSON`.
+
+## Local Checks
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+ruff check .
+```

docs/examples/strategy_plugins.example.toml

@@ -0,0 +1,21 @@
+output_dir = "data/output/strategy_plugins"
+default_mode = "shadow"
+
+[[strategy_plugins]]
+strategy = "tqqq_growth_income"
+plugin = "crisis_response_shadow"
+enabled = true
+# The runner enforces plugin/strategy compatibility. This plugin is scoped to
+# TQQQ/SOXL leveraged equity black-swan defense strategies.
+# mode is optional when it matches default_mode; only shadow notification mode is supported.
+
+[strategy_plugins.inputs]
+prices = "data/output/crisis_response_shadow/input/price_history.csv"
+external_context = "data/output/crisis_response_shadow/input/external_context.csv"
+event_set = "full"
+financial_symbols = ["XLF", "KRE"]
+credit_pairs = ["HYG:IEF", "LQD:IEF"]
+rate_symbols = ["IEF", "TLT"]
+
+[strategy_plugins.outputs]
+output_dir = "data/output/tqqq_growth_income/plugins/crisis_response_shadow"

pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quant-strategy-plugins"
+version = "0.1.0"
+description = "Open sidecar strategy plugins that emit QuantPlatformKit-compatible signal artifacts."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "QuantStrategyLab" }
+]
+dependencies = [
+  "pandas>=2.0",
+  "yfinance>=0.2.40",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "ruff>=0.8"]
+
+[project.scripts]
+qsp-build-crisis-response-shadow-signal = "quant_strategy_plugins.crisis_response_shadow_plugin:main"
+qsp-build-taco-rebound-shadow-signal = "quant_strategy_plugins.taco_rebound_shadow_plugin:main"
+qsp-run-strategy-plugins = "quant_strategy_plugins.strategy_plugin_runner:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120

scripts/build_crisis_response_shadow_signal.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from quant_strategy_plugins.crisis_response_shadow_plugin import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/run_strategy_plugins.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from quant_strategy_plugins.strategy_plugin_runner import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/quant_strategy_plugins/__init__.py

@@ -0,0 +1,27 @@
+"""Open strategy plugin implementations for QuantStrategyLab runtimes."""
+
+from .crisis_response_shadow_plugin import (
+    SCHEMA_VERSION as CRISIS_RESPONSE_SHADOW_SCHEMA_VERSION,
+    SHADOW_PROFILE as CRISIS_RESPONSE_SHADOW_PROFILE,
+    build_crisis_response_shadow_signal,
+    write_crisis_response_shadow_outputs,
+)
+from .strategy_plugin_runner import run_configured_plugins
+from .taco_rebound_shadow_plugin import (
+    SCHEMA_VERSION as TACO_REBOUND_SHADOW_SCHEMA_VERSION,
+    TACO_REBOUND_PROFILE,
+    build_taco_rebound_shadow_signal,
+    write_taco_rebound_shadow_outputs,
+)
+
+__all__ = [
+    "CRISIS_RESPONSE_SHADOW_PROFILE",
+    "CRISIS_RESPONSE_SHADOW_SCHEMA_VERSION",
+    "TACO_REBOUND_PROFILE",
+    "TACO_REBOUND_SHADOW_SCHEMA_VERSION",
+    "build_crisis_response_shadow_signal",
+    "build_taco_rebound_shadow_signal",
+    "run_configured_plugins",
+    "write_crisis_response_shadow_outputs",
+    "write_taco_rebound_shadow_outputs",
+]

src/quant_strategy_plugins/artifacts.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+def sha256_file(path: str | Path) -> str:
+    hasher = hashlib.sha256()
+    with Path(path).open("rb") as fh:
+        while True:
+            chunk = fh.read(1024 * 1024)
+            if not chunk:
+                break
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def write_json(path: str | Path, payload: Mapping[str, Any]) -> Path:
+    resolved = Path(path)
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    resolved.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+    return resolved