quant-signal-sdk 0.1.0__tar.gz

quant_signal_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Organization
+
+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.

quant_signal_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: quant-signal-sdk
+Version: 0.1.0
+Summary: Developer SDK for validating and publishing trading signals
+Author-email: Marcus SDK Team <dev@marcus.io>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marcusio/quant-signal-sdk
+Project-URL: Repository, https://github.com/marcusio/quant-signal-sdk
+Project-URL: Issues, https://github.com/marcusio/quant-signal-sdk/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: requests<3.0,>=2.32
+Requires-Dist: urllib3<3.0,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: market-data
+Requires-Dist: pandas<3.0,>=2.2; extra == "market-data"
+Requires-Dist: ccxt<6.0,>=4.0; extra == "market-data"
+Provides-Extra: ml
+Requires-Dist: joblib<2.0,>=1.3; extra == "ml"
+Requires-Dist: lightgbm<5.0,>=4.3; extra == "ml"
+Requires-Dist: numpy<3.0,>=1.26; extra == "ml"
+Requires-Dist: pandas<3.0,>=2.2; extra == "ml"
+Requires-Dist: scikit-learn<2.0,>=1.4; extra == "ml"
+Dynamic: license-file
+
+# Quant Signal SDK
+
+This repository now contains only the developer SDK package: `quant_signal_sdk`.
+
+Local executor client code has been moved to `local-executor-client` in the workspace.
+
+## Features
+- Pydantic signal models and enums (`SignalPayload`, `SignalSide`, `SignalAction`).
+- Retry-enabled HTTP transport (`NetworkClient`) using `requests` and `urllib3.Retry`.
+- Optional HMAC SHA-256 payload signing helper (`generate_hmac_signature`).
+- High-level API client (`QuantSignalClient`) for authenticated signal submission.
+- Minimal `BaseStrategy` contract for strategy inheritance.
+- In-memory portfolio backtest runner with OHLCV replay and execution-policy enforcement.
+
+## Quickstart
+```python
+from quant_signal_sdk import QuantSignalClient, SignalPayload
+
+client = QuantSignalClient(
+    base_url="https://api.example.com",
+    api_key="your-api-key",
+    signer_secret="optional-signing-secret",
+)
+
+signal = SignalPayload(
+    side="LONG",
+    action="OPEN_LONG",
+    symbol="BTCUSDT",
+    tp=72000,
+    sl=68500,
+    confidence_score=0.84,
+    metadata={"strategy": "trend_v1"},
+)
+
+result = client.send_signal(signal)
+print(result)
+```
+
+## Backtest
+
+Create a `my_bot.py` file that exports a strategy class or `STRATEGY` object with `on_event(...)`, then run:
+
+```bash
+quant-sdk backtest --bot-file my_bot.py --data-csv candles.csv --initial-cash 1000
+```
+
+The backtest engine replays OHLCV candles, queues signals for the next tick, and prints a simple portfolio summary when the run completes.
+
+If your OHLCV data is stored as Parquet (recommended per `GUIDE_DATA.md`), point the CLI at the Parquet file or directory. Example using the dataset layout in `GUIDE_DATA.md`:
+
+```powershell
+python -m quant_signal_sdk.cli backtest --bot-file my_bot.py \
+    --data-parquet "D:\Code\Projects\self-projects\macd-overlay - Copy\data\ohlcv\BTCUSDT.parquet" \
+    --timestamp-column timestamp --initial-cash 1000 --output-dir backtest_output_parquet --export-html
+```
+
+The CLI accepts either `--data-csv` (legacy) or `--data-parquet` (preferred). When a directory is passed to `--data-parquet` the first `*.parquet` file is used.
+
+## Requirements
+- Python 3.10+
+
+## Setup
+Install the library for local development:
+
+```bash
+pip install -e .
+```
+
+Install with SDK development tools:
+
+```bash
+pip install -e .[dev]
+```
+
+Install optional market-data helpers:
+
+```bash
+pip install -e .[market-data]
+```
+
+Install both dev and market-data extras together:
+
+```bash
+pip install -e .[dev,market-data]
+```
+
+After publishing to PyPI, users can install the released package with:
+
+```bash
+pip install quant-signal-sdk
+```
+
+## Tests
+```bash
+python -m unittest discover -s tests -v
+```
+
+## Release
+Build the distribution and validate the artifacts before upload:
+
+```bash
+python -m build --sdist --wheel
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## Example: register -> signer secret behavior
+
+When registering a bot via the example `examples/sample_bot.py`, the backend returns
+both an `apiKey` (runtime API key) and a `rawSecret` (signer secret). The example
+attaches the returned `rawSecret` to the `QuantSignalClient` as the `signer_secret`
+when the user did not already supply one. This ensures subsequent signal POSTs
+include the required `X-Timestamp` and `X-Signature` headers that the server
+validates.
+
+If you prefer to manage signing secrets yourself, pass `--bot-signer-secret` to
+the example and the returned `rawSecret` will not overwrite it.
+
+
+## Build
+```bash
+python -m build --sdist --wheel
+```
+
+## Contract Fixtures
+- SDK fixtures are versioned under `tests/fixtures/contracts`.
+- SDK compatibility checks are in `tests/test_contract_compatibility_sdk.py`.

quant_signal_sdk-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Quant Signal SDK
+
+This repository now contains only the developer SDK package: `quant_signal_sdk`.
+
+Local executor client code has been moved to `local-executor-client` in the workspace.
+
+## Features
+- Pydantic signal models and enums (`SignalPayload`, `SignalSide`, `SignalAction`).
+- Retry-enabled HTTP transport (`NetworkClient`) using `requests` and `urllib3.Retry`.
+- Optional HMAC SHA-256 payload signing helper (`generate_hmac_signature`).
+- High-level API client (`QuantSignalClient`) for authenticated signal submission.
+- Minimal `BaseStrategy` contract for strategy inheritance.
+- In-memory portfolio backtest runner with OHLCV replay and execution-policy enforcement.
+
+## Quickstart
+```python
+from quant_signal_sdk import QuantSignalClient, SignalPayload
+
+client = QuantSignalClient(
+    base_url="https://api.example.com",
+    api_key="your-api-key",
+    signer_secret="optional-signing-secret",
+)
+
+signal = SignalPayload(
+    side="LONG",
+    action="OPEN_LONG",
+    symbol="BTCUSDT",
+    tp=72000,
+    sl=68500,
+    confidence_score=0.84,
+    metadata={"strategy": "trend_v1"},
+)
+
+result = client.send_signal(signal)
+print(result)
+```
+
+## Backtest
+
+Create a `my_bot.py` file that exports a strategy class or `STRATEGY` object with `on_event(...)`, then run:
+
+```bash
+quant-sdk backtest --bot-file my_bot.py --data-csv candles.csv --initial-cash 1000
+```
+
+The backtest engine replays OHLCV candles, queues signals for the next tick, and prints a simple portfolio summary when the run completes.
+
+If your OHLCV data is stored as Parquet (recommended per `GUIDE_DATA.md`), point the CLI at the Parquet file or directory. Example using the dataset layout in `GUIDE_DATA.md`:
+
+```powershell
+python -m quant_signal_sdk.cli backtest --bot-file my_bot.py \
+    --data-parquet "D:\Code\Projects\self-projects\macd-overlay - Copy\data\ohlcv\BTCUSDT.parquet" \
+    --timestamp-column timestamp --initial-cash 1000 --output-dir backtest_output_parquet --export-html
+```
+
+The CLI accepts either `--data-csv` (legacy) or `--data-parquet` (preferred). When a directory is passed to `--data-parquet` the first `*.parquet` file is used.
+
+## Requirements
+- Python 3.10+
+
+## Setup
+Install the library for local development:
+
+```bash
+pip install -e .
+```
+
+Install with SDK development tools:
+
+```bash
+pip install -e .[dev]
+```
+
+Install optional market-data helpers:
+
+```bash
+pip install -e .[market-data]
+```
+
+Install both dev and market-data extras together:
+
+```bash
+pip install -e .[dev,market-data]
+```
+
+After publishing to PyPI, users can install the released package with:
+
+```bash
+pip install quant-signal-sdk
+```
+
+## Tests
+```bash
+python -m unittest discover -s tests -v
+```
+
+## Release
+Build the distribution and validate the artifacts before upload:
+
+```bash
+python -m build --sdist --wheel
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## Example: register -> signer secret behavior
+
+When registering a bot via the example `examples/sample_bot.py`, the backend returns
+both an `apiKey` (runtime API key) and a `rawSecret` (signer secret). The example
+attaches the returned `rawSecret` to the `QuantSignalClient` as the `signer_secret`
+when the user did not already supply one. This ensures subsequent signal POSTs
+include the required `X-Timestamp` and `X-Signature` headers that the server
+validates.
+
+If you prefer to manage signing secrets yourself, pass `--bot-signer-secret` to
+the example and the returned `rawSecret` will not overwrite it.
+
+
+## Build
+```bash
+python -m build --sdist --wheel
+```
+
+## Contract Fixtures
+- SDK fixtures are versioned under `tests/fixtures/contracts`.
+- SDK compatibility checks are in `tests/test_contract_compatibility_sdk.py`.

quant_signal_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quant-signal-sdk"
+version = "0.1.0"
+description = "Developer SDK for validating and publishing trading signals"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+authors = [
+  { name = "Marcus SDK Team", email = "dev@marcus.io" }
+]
+license = "MIT"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "pydantic>=2.7,<3.0",
+  "requests>=2.32,<3.0",
+  "urllib3>=2.2,<3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/marcusio/quant-signal-sdk"
+Repository = "https://github.com/marcusio/quant-signal-sdk"
+Issues = "https://github.com/marcusio/quant-signal-sdk/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+  "pytest-mock>=3.10",
+  "pyright>=1.1",
+  "build>=1.0",
+  "twine>=4.0",
+]
+
+market-data = [
+  "pandas>=2.2,<3.0",
+  "ccxt>=4.0,<6.0",
+]
+
+ml = [
+  "joblib>=1.3,<2.0",
+  "lightgbm>=4.3,<5.0",
+  "numpy>=1.26,<3.0",
+  "pandas>=2.2,<3.0",
+  "scikit-learn>=1.4,<2.0",
+]
+
+[project.scripts]
+quant-sdk = "quant_signal_sdk.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pyright]
+extraPaths = ["src"]

quant_signal_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quant_signal_sdk-0.1.0/src/quant_signal_sdk/__init__.py

@@ -0,0 +1,75 @@
+"""Public API for quant_signal_sdk.
+
+The package intentionally exposes a minimal surface area: `QuantSignalClient`,
+the `SignalPayload` model and enums, `BaseStrategy`, and the `generate_hmac_signature`
+helper. Example/demo bots and heavy deps (CCXT usage) live under `examples/`.
+"""
+from .client import QuantSignalClient
+from .models import (
+    MarginMode,
+    MarketType,
+    OrderType,
+    ExecutionPolicies,
+    SignalAction,
+    SignalPayload,
+    SignalSide,
+    SignalStatus,
+)
+from .signing import generate_hmac_signature
+from .strategy import BaseStrategy
+from .data_provider import DataProvider, CcxtDataProvider
+from .feature_engineer import FeatureEngineer
+from .interfaces import BaseDispatcher, BaseFeed, MarketEvent, PortfolioContext, Signal
+from .runner import Runner
+from .adapters import BaseTrigger, CronTrigger, DataFrameFeed, IntervalTrigger, LiveHTTPDispatcher, LiveRESTFeed, MockDispatcher, ParquetReplayFeed, ScheduledRESTFeed
+from .runtime.backtest import BacktestConfig, BacktestFill, BacktestOrder, BacktestReport, OhlcvReplayFeed, PortfolioBacktestRunner
+from .core_strategy import FundingArbitrageConfig, FundingArbitrageStrategy
+from .data_loader import BundleLoader, BundleManifest
+from .translator import SignalTranslator, BoundaryValidationException, RiskManager, PercentageRiskManager
+
+__all__ = [
+    "QuantSignalClient",
+    "MarginMode",
+    "MarketType",
+    "OrderType",
+    "ExecutionPolicies",
+    "SignalAction",
+    "SignalPayload",
+    "SignalSide",
+    "SignalStatus",
+    "generate_hmac_signature",
+    "BaseStrategy",
+    "DataProvider",
+    "CcxtDataProvider",
+    "FeatureEngineer",
+    "BaseDispatcher",
+    "BaseFeed",
+    "BaseStrategy",
+    "MarketEvent",
+    "PortfolioContext",
+    "Signal",
+    "Runner",
+    "BacktestConfig",
+    "BacktestFill",
+    "BacktestOrder",
+    "BacktestReport",
+    "BaseTrigger",
+    "DataFrameFeed",
+    "CronTrigger",
+    "OhlcvReplayFeed",
+    "IntervalTrigger",
+    "PortfolioBacktestRunner",
+    "LiveHTTPDispatcher",
+    "LiveRESTFeed",
+    "MockDispatcher",
+    "ParquetReplayFeed",
+    "ScheduledRESTFeed",
+    "BundleLoader",
+    "BundleManifest",
+    "FundingArbitrageConfig",
+    "FundingArbitrageStrategy",
+    "SignalTranslator",
+    "BoundaryValidationException",
+    "RiskManager",
+    "PercentageRiskManager",
+]

quant_signal_sdk-0.1.0/src/quant_signal_sdk/adapters.py

@@ -0,0 +1,13 @@
+from .runtime.adapters import BaseTrigger, CronTrigger, DataFrameFeed, IntervalTrigger, LiveHTTPDispatcher, LiveRESTFeed, MockDispatcher, ParquetReplayFeed, ScheduledRESTFeed
+
+__all__ = [
+	"BaseTrigger",
+	"CronTrigger",
+	"DataFrameFeed",
+	"IntervalTrigger",
+	"LiveHTTPDispatcher",
+	"LiveRESTFeed",
+	"MockDispatcher",
+	"ParquetReplayFeed",
+	"ScheduledRESTFeed",
+]

quant_signal_sdk-0.1.0/src/quant_signal_sdk/ccxt_client.py

@@ -0,0 +1,41 @@
+"""Small CCXT wrapper to fetch OHLCV data for strategies.
+
+`ccxt` is an optional dependency. If it's not installed the module will raise
+an ImportError with instructions to install the `market-data` extra.
+"""
+from typing import List
+
+try:
+    import ccxt  # type: ignore
+except Exception as exc:  # ImportError or other import-time errors
+    ccxt = None  # type: ignore
+    _CCXT_IMPORT_ERROR = exc
+
+
+class CCXTClient:
+    def __init__(self, exchange_id: str = "binance"):
+        if ccxt is None:
+            raise ImportError(
+                "ccxt is not installed. Install it with: `pip install .[market-data]` "
+                "or `pip install ccxt`."
+            ) from _CCXT_IMPORT_ERROR
+
+        if not hasattr(ccxt, exchange_id):
+            raise ValueError(f"Unknown exchange: {exchange_id}")
+        self.exchange = getattr(ccxt, exchange_id)()
+        try:
+            self.exchange.load_markets()
+        except Exception:
+            # best-effort, some test envs may not allow network calls
+            pass
+
+    def fetch_ohlcv(self, symbol: str, timeframe: str = "1m", limit: int = 100) -> List[List[float]]:
+        """Return OHLCV rows as provided by ccxt: [timestamp, open, high, low, close, volume]
+
+        Raises ccxt.BaseError on network / exchange errors.
+        """
+        return self.exchange.fetch_ohlcv(symbol, timeframe=timeframe, limit=limit)
+
+
+def close_prices_from_ohlcv(ohlcv: List[List[float]]) -> List[float]:
+    return [float(row[4]) for row in ohlcv if len(row) >= 5]