binance-quant-engine 0.1.1__tar.gz → 0.1.2__tar.gz

{binance_quant_engine-0.1.1 → binance_quant_engine-0.1.2}/PKG-INFO

@@ -1,18 +1,32 @@
 Metadata-Version: 2.5
 Name: binance-quant-engine
-Version: 0.1.1
+Version: 0.1.2
 Summary: Strategy-agnostic Binance USDT-M futures backtest & execution engine — no-look-ahead, backtest/live parity, optional MCP server
-Project-URL: Homepage, https://pypi.org/project/binance-quant-engine/
+Project-URL: Homepage, https://github.com/younghwan91/binance-quant-engine
 Project-URL: Repository, https://github.com/younghwan91/binance-quant-engine
+Project-URL: Documentation, https://github.com/younghwan91/binance-quant-engine/blob/main/docs/USAGE.md
+Project-URL: Bug Tracker, https://github.com/younghwan91/binance-quant-engine/issues
+Project-URL: Changelog, https://github.com/younghwan91/binance-quant-engine/releases
 Author-email: Younghwan Chae <chyohw97@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: algo-trading,backtest,binance,execution,futures,mcp,quant,trading
+Keywords: algo-trading,algorithmic-trading,backtest,backtesting,binance,binance-futures,crypto,cryptocurrency,execution,futures,mcp,model-context-protocol,quant,quantitative-trading,trading,trading-bot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.26
 Requires-Dist: pandas>=2.0
 Provides-Extra: dev
 Requires-Dist: mcp>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: python-binance>=1.0.29; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -112,12 +126,12 @@ flowchart LR
     subgraph Decide["binance_quant_engine/strategy/ — decide"]
         PROTO{{"TradingStrategy\n(PEP 544 protocol)"}}
         SQZ["demo_squeeze.py\nSqueezeStrategy"]
-        PROTO -.implements.-> SQZ
+        PROTO -.->|"implements"| SQZ
     end
 
     CSV --> BT
     SYN --> BT
-    CACHE -.caches.-> CSV
+    CACHE -.->|"caches"| CSV
 
     subgraph Measure["binance_quant_engine/backtest/ — measure"]
         BT["vectorized.run_backtest()\nhands close[:t+1] only\n(no look-ahead)"]
@@ -139,9 +153,9 @@ flowchart LR
     subgraph MCP["binance_quant_engine/mcp/ — optional (.[mcp])"]
         SRV["server.py\nrun_demo_backtest · backtest_csv"]
     end
-    BT -.callable via.-> SRV
+    BT -.->|"callable via"| SRV
 
-    PROTO ==same interface\n(backtest = live)==> HOST
+    PROTO ==>|"same interface<br/>(backtest = live)"| HOST
     ALGO --> BINANCE[("Binance USDT-M\nFutures Algo Order API")]
 ```
 

{binance_quant_engine-0.1.1 → binance_quant_engine-0.1.2}/README.md

@@ -88,12 +88,12 @@ flowchart LR
     subgraph Decide["binance_quant_engine/strategy/ — decide"]
         PROTO{{"TradingStrategy\n(PEP 544 protocol)"}}
         SQZ["demo_squeeze.py\nSqueezeStrategy"]
-        PROTO -.implements.-> SQZ
+        PROTO -.->|"implements"| SQZ
     end
 
     CSV --> BT
     SYN --> BT
-    CACHE -.caches.-> CSV
+    CACHE -.->|"caches"| CSV
 
     subgraph Measure["binance_quant_engine/backtest/ — measure"]
         BT["vectorized.run_backtest()\nhands close[:t+1] only\n(no look-ahead)"]
@@ -115,9 +115,9 @@ flowchart LR
     subgraph MCP["binance_quant_engine/mcp/ — optional (.[mcp])"]
         SRV["server.py\nrun_demo_backtest · backtest_csv"]
     end
-    BT -.callable via.-> SRV
+    BT -.->|"callable via"| SRV
 
-    PROTO ==same interface\n(backtest = live)==> HOST
+    PROTO ==>|"same interface<br/>(backtest = live)"| HOST
     ALGO --> BINANCE[("Binance USDT-M\nFutures Algo Order API")]
 ```
 

{binance_quant_engine-0.1.1 → binance_quant_engine-0.1.2}/pyproject.toml

@@ -4,13 +4,30 @@ build-backend = "hatchling.build"
 
 [project]
 name = "binance-quant-engine"
-version = "0.1.1"
+version = "0.1.2"
 description = "Strategy-agnostic Binance USDT-M futures backtest & execution engine — no-look-ahead, backtest/live parity, optional MCP server"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
-keywords = ["quant", "backtest", "trading", "binance", "futures", "execution", "algo-trading", "mcp"]
+keywords = [
+    "quant", "quantitative-trading", "backtest", "backtesting", "trading",
+    "binance", "binance-futures", "crypto", "cryptocurrency", "futures",
+    "algo-trading", "algorithmic-trading", "trading-bot", "execution", "mcp",
+    "model-context-protocol",
+]
 authors = [{ name = "Younghwan Chae", email = "chyohw97@gmail.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
 dependencies = [
     "numpy>=1.26",
     "pandas>=2.0",
@@ -20,21 +37,25 @@ dependencies = [
 # Live execution talks to Binance USDT-M Futures; not needed for backtests.
 live = ["python-binance>=1.0.29"]
 mcp = ["mcp>=1.0"]
-dev = ["pytest>=8.0", "ruff>=0.6", "python-binance>=1.0.29", "mcp>=1.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.6", "python-binance>=1.0.29", "mcp>=1.0"]
 
 [project.scripts]
 bqe-backtest = "binance_quant_engine.backtest.vectorized:main"
 binance-quant-engine-mcp = "binance_quant_engine.mcp.server:main"
 
 [project.urls]
-Homepage = "https://pypi.org/project/binance-quant-engine/"
+Homepage = "https://github.com/younghwan91/binance-quant-engine"
 Repository = "https://github.com/younghwan91/binance-quant-engine"
+Documentation = "https://github.com/younghwan91/binance-quant-engine/blob/main/docs/USAGE.md"
+"Bug Tracker" = "https://github.com/younghwan91/binance-quant-engine/issues"
+Changelog = "https://github.com/younghwan91/binance-quant-engine/releases"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/binance_quant_engine"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+asyncio_mode = "strict"
 
 [tool.ruff]
 line-length = 100

{binance_quant_engine-0.1.1 → binance_quant_engine-0.1.2}/src/binance_quant_engine/__init__.py

@@ -1,3 +1,3 @@
 """Binance Quant Engine — a strategy-agnostic crypto-futures backtest & execution engine."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

binance_quant_engine-0.1.2/tests/test_brackets.py

@@ -0,0 +1,161 @@
+"""Integration tests for BracketMixin against a fake host.
+
+Exercises the mixin the way the live bot actually drives it — through
+``self`` — rather than testing the extracted :mod:`utils` functions in
+isolation. This is what proves the two correctness fixes upstreamed from
+the private system (tick-safe activationPrice, REJECTED as terminal) are
+actually wired into the code path a real bot calls, not just correct as
+standalone functions.
+"""
+
+from __future__ import annotations
+
+from binance_quant_engine.execution.brackets import BracketMixin
+from binance_quant_engine.execution.host import TrailConfig
+
+
+class FakeAlgoApi:
+    def __init__(self):
+        self.placed: list[dict] = []
+        self.next_algo_id = 1
+        self.raise_on_place: Exception | None = None
+        self.get_order_response: dict | None = None
+
+    def place_order(self, params: dict) -> dict:
+        if self.raise_on_place is not None:
+            raise self.raise_on_place
+        self.placed.append(params)
+        algo_id = self.next_algo_id
+        self.next_algo_id += 1
+        return {"algoId": algo_id}
+
+    def cancel_order(self, algo_id: int) -> dict:
+        return {"algoId": algo_id, "status": "CANCELLED"}
+
+    def get_order(self, algo_id: int) -> dict:
+        return self.get_order_response or {}
+
+
+class FakeDiscord:
+    def __init__(self):
+        self.messages: list[str] = []
+
+    def send(self, content: str) -> None:
+        self.messages.append(content)
+
+
+class FakeHost(BracketMixin):
+    """Minimal concrete implementation of ScalperProtocol for tests."""
+
+    def __init__(self, *, paper_mode: bool = False, tick_size: float = 0.01, price_precision: int = 2):
+        self.paper_mode = paper_mode
+        self.client = None
+        self.discord = FakeDiscord()
+        self.strategy = None
+        self.trail_config = TrailConfig()
+        self._algo_api = FakeAlgoApi()
+        self._tick_size = tick_size
+        self._price_precision = price_precision
+
+    def get_symbol_info(self, symbol: str) -> dict:
+        return {"tick_size": self._tick_size, "price_precision": self._price_precision}
+
+    def _round_qty(self, qty: float, symbol: str) -> float:
+        return qty
+
+    def _save_state(self) -> None:
+        pass
+
+
+def test_paper_mode_stop_loss_never_calls_algo_api():
+    host = FakeHost(paper_mode=True)
+    algo_id = host._place_server_stop_loss(
+        "BTCUSDT", signal=1, quantity=1.0, entry_price=100.0, move_size=0.05, stop_mult=1.0
+    )
+    assert algo_id.startswith("paper_sl_")
+    assert host._algo_api.placed == []
+
+
+def test_stop_loss_prices_are_tick_rounded():
+    # tick_size=0.01 forces a price like 95.037 to round to 95.04.
+    host = FakeHost(tick_size=0.01, price_precision=2)
+    host._place_server_stop_loss(
+        "BTCUSDT", signal=1, quantity=1.0, entry_price=100.037, move_size=0.05, stop_mult=1.0
+    )
+    assert len(host._algo_api.placed) == 1
+    params = host._algo_api.placed[0]
+    trigger = float(params["triggerPrice"])
+    limit = float(params["price"])
+    assert round(trigger / 0.01) * 0.01 == round(trigger, 10)  # exactly on the tick grid
+    assert round(limit / 0.01) * 0.01 == round(limit, 10)
+
+
+def test_stop_loss_negative_stop_mult_aborts_without_calling_api():
+    host = FakeHost()
+    algo_id = host._place_server_stop_loss(
+        "BTCUSDT", signal=1, quantity=1.0, entry_price=100.0, move_size=0.05, stop_mult=-1.0
+    )
+    assert algo_id is None
+    assert host._algo_api.placed == []
+
+
+def test_take_profit_invariant_guards_reject_bad_inputs():
+    host = FakeHost()
+    assert host._place_server_take_profit(
+        "BTCUSDT", signal=1, quantity=1.0, entry_price=100.0, move_size=0.05, target_retrace=0.0
+    ) is None
+    assert host._algo_api.placed == []
+
+
+def test_trailing_stop_activation_price_is_tick_rounded():
+    # An activation price that lands off the 0.1 tick grid must be snapped
+    # before it reaches params — this is the exact bug fixed vs. the
+    # quantbox-engine predecessor.
+    host = FakeHost(tick_size=0.1, price_precision=1)
+    host._place_trailing_stop_market(
+        "BTCUSDT", side="SELL", quantity=1.0, callback_rate=1.0, activation_price=100.037
+    )
+    assert len(host._algo_api.placed) == 1
+    activation = float(host._algo_api.placed[0]["activationPrice"])
+    assert activation == 100.0  # 100.037 snapped to the nearest 0.1 tick
+
+
+def test_algo_order_would_trigger_returns_sentinel():
+    host = FakeHost()
+    host._algo_api.raise_on_place = Exception("APIError(code=-2021): Order would immediately trigger")
+    result = host._place_algo_order(
+        "BTCUSDT", side="SELL", order_type="STOP", quantity=1.0, trigger_price=100.0
+    )
+    assert result == "WOULD_TRIGGER"
+
+
+def test_cancel_server_order_treats_unknown_order_as_success():
+    import json
+
+    from binance.exceptions import BinanceAPIException
+
+    class _FakeResponse:
+        status_code = 400
+
+    class _Raiser:
+        def cancel_order(self, algo_id):
+            body = json.dumps({"code": -2011, "msg": "Unknown order sent."})
+            raise BinanceAPIException(_FakeResponse(), 400, body)
+
+    host = FakeHost()
+    host._algo_api = _Raiser()
+    assert host._cancel_server_stop_loss("BTCUSDT", "12345") is True
+
+
+def test_check_order_filled_recognizes_rejected_as_dead():
+    # The exact upstreamed fix: quantbox-engine's predecessor set didn't
+    # include REJECTED, so a rejected algo order stayed "tracked" forever.
+    host = FakeHost()
+    host._algo_api.get_order_response = {"algoStatus": "REJECTED"}
+    result = host._check_order_filled("BTCUSDT", "999")
+    assert result == {"status": "CANCELLED", "algoId": "999"}
+
+
+def test_verify_algo_order_active_paper_mode_is_always_working():
+    host = FakeHost(paper_mode=True)
+    assert host._verify_algo_order_active("999", "BTCUSDT") == "WORKING"

binance_quant_engine-0.1.2/tests/test_mcp_stdio_e2e.py

@@ -0,0 +1,35 @@
+"""End-to-end smoke test: spawn the actual `binance-quant-engine-mcp` process
+and speak real MCP-over-stdio to it, instead of calling the tool functions
+in-process. This is what proves the packaged entry point (not just the
+Python module) works for a real MCP client.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+
+import pytest
+
+pytest.importorskip("mcp")
+
+from mcp import ClientSession, StdioServerParameters  # noqa: E402
+from mcp.client.stdio import stdio_client  # noqa: E402
+
+
+@pytest.mark.asyncio
+async def test_mcp_server_entry_point_lists_and_calls_tools():
+    exe = shutil.which("binance-quant-engine-mcp") or sys.executable
+    args = [] if exe != sys.executable else ["-m", "binance_quant_engine.mcp.server"]
+
+    params = StdioServerParameters(command=exe, args=args)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = await session.list_tools()
+            names = {t.name for t in tools.tools}
+            assert {"run_demo_backtest", "backtest_csv", "describe_strategy_protocol"} <= names
+
+            result = await session.call_tool("run_demo_backtest", {"n_bars": 400, "seed": 3})
+            assert not result.is_error