Qubx 1.1.1.dev1__tar.gz → 1.1.1.dev2__tar.gz

{qubx-1.1.1.dev1 → qubx-1.1.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Qubx
-Version: 1.1.1.dev1
+Version: 1.1.1.dev2
 Summary: Qubx - Quantitative Trading Framework
 Project-URL: homepage, https://xlydian.com
 Project-URL: repository, https://github.com/xLydianSoftware/Qubx

{qubx-1.1.1.dev1 → qubx-1.1.1.dev2}/src/qubx/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.1.1.dev1'
-__version_tuple__ = version_tuple = (1, 1, 1, 'dev1')
+__version__ = version = '1.1.1.dev2'
+__version_tuple__ = version_tuple = (1, 1, 1, 'dev2')
 
 __commit_id__ = commit_id = None

{qubx-1.1.1.dev1 → qubx-1.1.1.dev2}/src/qubx/backtester/management.py

@@ -50,7 +50,7 @@ import pandas as pd
 from qubx.core.metrics import TradingSessionResult
 from qubx.utils.misc import blue, cyan, green, magenta, red, yellow
 from qubx.utils.results import SimulationResultsSaver
-from qubx.utils.s3 import S3Client, is_cloud_path
+from qubx.utils.s3 import S3Client, is_account_uri, is_cloud_path
 
 
 class BacktestStorage:
@@ -105,8 +105,11 @@ class BacktestStorage:
         Initialize BacktestStorage.
 
         Args:
-            base_path: Root path for backtest storage (local dir or cloud URI)
-            storage_options: Cloud storage credentials dict. None = uses default_s3_account from settings.
+            base_path: Root path for backtest storage. Supports:
+                - Local directory: ``"/backtests/"``
+                - S3 URI: ``"s3://bucket/path"``
+                - Account URI: ``"r2:backtests"`` (resolved via ~/.qubx/config.json)
+            storage_options: Cloud storage credentials dict. Overrides account lookup.
         """
         try:
             import duckdb
@@ -117,6 +120,13 @@ class BacktestStorage:
                 "duckdb is required for BacktestStorage. "
                 "Install with: pip install 'qubx[storage]' or pip install duckdb"
             )
+
+        # Resolve account URI (e.g., "r2:backtests") to S3 path + credentials
+        if is_account_uri(base_path) and storage_options is None:
+            client, s3_path = S3Client.from_uri(base_path)
+            storage_options = client.storage_options
+            base_path = f"s3://{s3_path}"
+
         self.base_path = base_path.rstrip("/") + "/"
         self._is_cloud = is_cloud_path(base_path)
 
@@ -134,17 +144,37 @@ class BacktestStorage:
         self._conn.execute("INSTALL httpfs; LOAD httpfs;")
 
         opts = self._storage_options or {}
-        if "key" in opts:
-            self._conn.execute(f"SET s3_access_key_id='{opts['key']}';")
-        if "secret" in opts:
-            self._conn.execute(f"SET s3_secret_access_key='{opts['secret']}';")
+        if not opts or "key" not in opts:
+            return
+
+        # Resolve region
+        region = "auto"
+        if "client_kwargs" in opts:
+            region = opts["client_kwargs"].get("region_name", "auto")
+        elif "region" in opts:
+            region = opts["region"]
+
+        # Build CREATE SECRET with scope matching our base_path so it takes
+        # priority over any pre-existing broader secrets (e.g. from duckdb config).
+        scope = self.base_path.rstrip("/")
+        endpoint_clause = ""
+        url_style_clause = ""
         if "endpoint_url" in opts:
             endpoint = opts["endpoint_url"].removeprefix("https://").removeprefix("http://")
-            self._conn.execute(f"SET s3_endpoint='{endpoint}';")
-        if "client_kwargs" in opts:
-            region = opts["client_kwargs"].get("region_name")
-            if region:
-                self._conn.execute(f"SET s3_region='{region}';")
+            endpoint_clause = f"ENDPOINT '{endpoint}',"
+            url_style_clause = "URL_STYLE 'path',"
+
+        self._conn.execute(f"""
+            CREATE OR REPLACE SECRET qubx_s3 (
+                TYPE s3,
+                KEY_ID '{opts['key']}',
+                SECRET '{opts['secret']}',
+                {endpoint_clause}
+                {url_style_clause}
+                REGION '{region}',
+                SCOPE '{scope}'
+            )
+        """)
 
     def _glob(self, filename: str) -> str:
         """

{qubx-1.1.1.dev1 → qubx-1.1.1.dev2}/src/qubx/cli/commands.py

@@ -501,22 +501,13 @@ def browse(results_path: str | None):
         qubx browse s3://my-bucket/backtests/
     """
     from qubx.config import get_settings
-    from qubx.utils.s3 import S3Client, is_account_uri, is_cloud_path
 
     from .tui import run_backtest_browser
 
     if results_path is None:
         results_path = get_settings().default_browse_path or "results"
 
-    storage_options: dict | None = None
-    if is_account_uri(results_path):
-        client, s3_path = S3Client.from_uri(results_path)
-        storage_options = client.storage_options
-        results_path = f"s3://{s3_path}"
-    elif not is_cloud_path(results_path):
-        results_path = os.path.abspath(os.path.expanduser(results_path))
-
-    run_backtest_browser(results_path, storage_options=storage_options)
+    run_backtest_browser(results_path)
 
 
 @main.command()

{qubx-1.1.1.dev1 → qubx-1.1.1.dev2}/src/qubx/cli/tui.py

@@ -450,12 +450,10 @@ class BacktestResultsTree(Tree[BacktestTreeNode]):
     def __init__(
         self,
         root_path: str,
-        storage_options: dict | None = None,
         on_loaded: "callable | None" = None,
     ):
         self.root_path = root_path
-        self.storage_options = storage_options
-        self.storage = BacktestStorage(root_path, storage_options=storage_options)
+        self.storage = BacktestStorage(root_path)
         self._root_data = BacktestTreeNode("Backtest Results", root_path, self.storage)
         self._on_loaded = on_loaded
         super().__init__(self._root_data.name, data=self._root_data)
@@ -1073,10 +1071,9 @@ class BacktestBrowserApp(App):
     }
     """
 
-    def __init__(self, root_path: str, storage_options: dict | None = None):
+    def __init__(self, root_path: str):
         super().__init__()
         self.root_path = root_path
-        self.storage_options = storage_options
         self.current_results: list[dict[str, Any]] = []
         self.current_storage: BacktestStorage | None = None
         self._selected_result: dict[str, Any] | None = None
@@ -1099,7 +1096,7 @@ class BacktestBrowserApp(App):
         with Horizontal():
             with Vertical(id="tree-container", classes="box"):
                 yield Label("Backtest Results Tree")
-                yield BacktestResultsTree(self.root_path, storage_options=self.storage_options)
+                yield BacktestResultsTree(self.root_path)
 
             with Vertical(id="content-container", classes="box"):
                 with Horizontal(id="controls"):
@@ -1273,7 +1270,6 @@ class BacktestBrowserApp(App):
 
             new_tree = BacktestResultsTree(
                 self.root_path,
-                storage_options=self.storage_options,
                 on_loaded=self._restore_tree_state,
             )
             tree_container.mount(new_tree)
@@ -1564,10 +1560,10 @@ class BacktestBrowserApp(App):
         self.copy_to_clipboard(str(load_id))
         self.notify(f"Copied: {load_id}", timeout=3)
 
-def run_backtest_browser(root_path: str, storage_options: dict | None = None):
+def run_backtest_browser(root_path: str):
     """Run the backtest browser TUI application"""
     try:
-        app = BacktestBrowserApp(root_path, storage_options=storage_options)
+        app = BacktestBrowserApp(root_path)
         app.run()
     except Exception as e:
         logger.error(f"Failed to start backtest browser: {e}")

qubx-1.1.1.dev2/src/qubx/templates/repo/.claude/skills/simulation-explorer/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: simulation-explorer
+description: Use when loading, comparing, or debugging backtest simulation results — tearsheets, execution logs, portfolio analysis, log inspection, and diagnosing data issues.
+argument-hint: [backtest_path_or_paths] [question]
+---
+
+# Simulation Explorer
+
+You help load, compare, analyze, and debug backtest simulation results produced by `qubx simulate`.
+
+## Loading Results
+
+### From Python (notebook or script):
+```python
+from qubx.backtester.management import BacktestStorage
+from qubx.core.metrics import tearsheet
+
+# Account URI — uses named S3 account from ~/.qubx/config.json
+bs = BacktestStorage("r2:backtests")
+
+# Also supports direct S3 or local paths
+bs = BacktestStorage("s3://my-bucket/backtests")
+bs = BacktestStorage("results")  # local directory
+
+# Load a specific run
+r = bs.load("STRATEGY_CLASS/run_name/YYYYMMDD_HHMMSS")
+
+# Compare multiple runs
+r1 = bs.load("STRATEGY_CLASS/run1/20260320_120000")
+r2 = bs.load("STRATEGY_CLASS/run2/20260320_130000")
+tearsheet([r1, r2])
+```
+
+### From CLI:
+```bash
+# Browse results interactively (account URI)
+uv run qubx browse r2:backtests
+
+# Also works with S3 or local paths
+uv run qubx browse s3://my-bucket/backtests
+uv run qubx browse results/
+
+# Query results with filters
+uv run qubx backtests r2:backtests -w "sharpe > 1.5" -n 10
+```
+
+## Result Object API
+
+A loaded result `r` provides:
+
+| Property | Description |
+|----------|-------------|
+| `r.tearsheet()` | Full performance report |
+| `r.equity` | Equity curve (Series) |
+| `r.portfolio_log` | Portfolio state over time (DataFrame) |
+| `r.executions_log` | All executed trades (DataFrame) |
+| `r.signals_log` | All signals generated (DataFrame) |
+| `r.emitter_data` | Custom emitter data (if `enable_inmemory_emitter: true`) |
+
+### Common analysis patterns:
+
+```python
+# Equity curve
+r.equity.plot()
+
+# Positions over time
+r.portfolio_log.filter(like="_Pos")
+
+# Funding PnL per asset
+r.portfolio_log.filter(like="_Funding")
+
+# Funding PnL breakdown
+fp = r.get_funding_per_asset()
+fp.iloc[-1].sort_values(ascending=False).head(15).plot(kind="bar")
+
+# Trade list
+r.executions_log
+
+# Compare funding between runs
+from qubx.pandaz.utils import scols
+fp1 = r1.get_funding_per_asset()
+fp2 = r2.get_funding_per_asset()
+scols(
+    fp1["BTC"].rename("run1"),
+    fp2["BTC"].rename("run2"),
+).plot()
+```
+
+## Comparing Two Runs
+
+### Tearsheet comparison:
+```python
+tearsheet([r1, r2])
+```
+
+### Execution diff — find trades in one run but not the other:
+```python
+df1 = r1.executions_log.set_index(["symbol", "exchange"], append=True)
+df2 = r2.executions_log.set_index(["symbol", "exchange"], append=True)
+df_diff = df2[~df2.index.isin(df1.index)]
+len(df_diff)  # number of different executions
+df_diff.head()
+```
+
+## Debugging via Log Files
+
+Simulation logs are stored alongside results when run with `-L` flag:
+```
+STRATEGY_CLASS/run_name/YYYYMMDD_HHMMSS/
+├── run_name.log        # simulation log
+├── run_name.yml        # config used
+├── portfolio.parquet
+├── executions.parquet
+├── signals.parquet
+└── ...
+```
+
+### Log analysis patterns:
+
+```bash
+# Find selector activity (pair entries/exits)
+grep "selectors" /path/to/run.log
+
+# Compare selector lines between two runs
+diff <(grep "selectors" run1.log) <(grep "selectors" run2.log)
+
+# Find first divergence point
+paste <(grep "selectors" run1.log) <(grep "selectors" run2.log) | awk -F'\t' '$1 != $2 {print NR; exit}'
+
+# Check funding payment data
+grep "\[FP\]" /path/to/run.log | head -20
+
+# Check errors
+grep "❌" /path/to/run.log
+```
+
+## Running Simulations
+
+### From CLI:
+```bash
+# Basic simulation
+uv run qubx simulate configs/my_strategy.yaml -o s3://backtests -L
+
+# Override dates
+uv run qubx simulate configs/my_strategy.yaml -s 2026-01-01 -e 2026-03-01 -o s3://backtests -L
+
+# Custom run name
+uv run qubx simulate configs/my_strategy.yaml -o s3://backtests -n "baseline_v1" -L
+```
+
+### From notebook (quick iteration):
+```python
+from qubx.utils.runner.runner import simulate_config
+
+results = simulate_config(
+    "configs/my_strategy.yaml",
+    start="2026-01-15",
+    stop="2026-02-01",
+    # Override any strategy parameter:
+    max_pairs=3,
+    min_entry_ev=0,
+)
+r = results[0]
+r.tearsheet()
+```
+
+## Output Paths
+
+Results are organized as:
+```
+<output>/<strategy_class>/<config_name>/<YYYYMMDD_HHMMSS>/
+```
+
+- Local output: `-o results` or `-o /tmp/my_test`
+- Account URI: `-o r2:backtests` (uses named S3 account from `~/.qubx/config.json`)
+- S3 output: `-o s3://backtests`
+
+## Common Debugging Scenarios
+
+### Results differ between runs with same config
+1. Compare tearsheets: `tearsheet([r1, r2])`
+2. Find first selector divergence in logs
+3. Check if OHLC data or funding payment data differs at the divergence point
+4. Look for cache-related issues if prefetch is enabled
+
+### Strategy not trading
+1. Check if `on_event` fires: look for selector log lines
+2. Check `on_fit` timing: look for universe/pair discovery logs
+3. Verify funding payment data is available
+4. Check if `on_start` was called (requires market data for initial instruments)
+
+### Unexpected PnL
+1. Check `r.portfolio_log.filter(like="_Funding")` for funding PnL
+2. Check `r.portfolio_log.filter(like="_Pos")` for position changes
+3. Compare `r.executions_log` with expected trades
+4. Check spread PnL vs funding PnL breakdown