jesse 3.2.0__tar.gz → 3.2.1__tar.gz

{jesse-3.2.0/jesse.egg-info → jesse-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jesse
-Version: 3.2.0
+Version: 3.2.1
 Summary: A trading framework for cryptocurrencies
 Home-page: https://jesse.trade
 Author: Saleh Mir

{jesse-3.2.0 → jesse-3.2.1}/jesse/mcp/agent_rules.md

@@ -113,6 +113,7 @@ High-signal Jesse strategy-authoring gotchas (full detail in jesse://strategy):
 - Inside `on_open_position`, check `self.is_long` / `self.is_short` before setting `self.stop_loss` / `self.take_profit`.
 - On **spot**, shorting is unsupported: `should_short()` must return `False`, leverage is always `1`, and `stop_loss`/`take_profit` must be set in `on_open_position()` (not `go_long()`).
 - Size from `self.available_margin` (or balance/capital), price, and `self.fee_rate` via sizing utilities (`size_to_qty`, `risk_to_qty`) — never hardcode a fixed quantity.
+- Market hours, sessions, "skip weekends", or a stock-linked instrument on a 24/7 exchange: define `trading_hours()` returning a dict with `timezone` and `hours` (days always explicit, no preset names), gate entries with `self.is_trading_hours`, and feed entry indicators `utils.filter_candles_by_hours(self.candles, self.trading_hours())`. Never hand-roll UTC-hour math or reassign `self.candles`, and never gate `update_position()`/exits by the schedule. See the Trading Hours section of jesse://strategy.
 
 For full structure, lifecycle, and complete runnable examples see jesse://strategy and jesse://strategy_examples.
 

{jesse-3.2.0 → jesse-3.2.1}/jesse/mcp/resources/candle.md

@@ -4,7 +4,9 @@ This reference covers candle import and management operations in Jesse.
 
 ## Data Requirements
 
-Historical candle data is required for backtesting strategies. Import data for all route exchanges, symbols, and timeframes before running backtests.
+Historical candle data is required for backtesting strategies. Import data for every route's exchange and symbol before running backtests.
+
+Jesse imports and stores **one-minute candles only**, for every source (crypto exchanges, Massive, Custom Data). In backtests, optimization, Monte Carlo, significance tests and research, every other timeframe is generated from those minutes at run time, so a single import per exchange and symbol covers every timeframe a route or `get_candles()` asks for. Live and paper sessions are different: by default each timeframe's candles come from the exchange, and only when the live setting `generate_candles_from_1m` is enabled are bigger timeframes generated locally from one-minute candles. Timeframes are never imported, so when checking coverage only confirm that the symbol's data spans the backtest dates plus warm-up.
 
 ## Import Process
 
@@ -82,7 +84,7 @@ simulation settings.
   currency (`USD` vs `USDT`)
 - `delete_source` (optional, default false): remove the original in the same transaction
 
-Rules: every stored timeframe is copied; the call is refused (HTTP 409) when the target already
+Rules: the whole stored one-minute series is copied, which is everything a backtest needs for any timeframe; the call is refused (HTTP 409) when the target already
 holds candles, so series are never merged; deleting the source turns the copy into a rename, but
 provider updates only work under the original exchange name, so confirm with the user first.
 
@@ -98,11 +100,28 @@ Imports historical candle data from exchanges.
 - `start_date`: Start date in YYYY-MM-DD format
 - `import_id` (optional): Import ID for retrying failed imports
 
-**Supported Timeframes:**
-1m, 3m, 5m, 15m, 30m, 45m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1D, 3D, 1W, 1M
+**Timeframes:** the import has no timeframe parameter. One-minute candles are stored, and in
+backtests and the other research modes the timeframes usable in routes and `get_candles()` (1m,
+3m, 5m, 15m, 30m, 45m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1D, 3D, 1W, 1M) are all built from them at run
+time. Live sessions fetch each timeframe from the exchange unless `generate_candles_from_1m` is on.
 
 **Returns:** Import result with status and import ID
 
+## Traditional Markets and Gapped Data
+
+Massive sources and Custom Data describe markets that close, so their one-minute series has real
+gaps (nights, weekends, holidays; pre-market and after-hours bars are kept where the provider has
+them). Jesse never fabricates candles for a closure:
+
+- Backtests detect gapped data automatically and replay only the candles that exist. Bigger
+  timeframes are built from the observed minutes in clock-aligned buckets.
+- Warm-up is counted in **completed observed candles** of the route's timeframe, not calendar
+  time, so import noticeably more history than a crypto backtest would need.
+- A resting order crossed by an opening gap fills at the **open price**, not at its own price.
+- Metrics for these sources annualize on 252 observations by default instead of 365.
+- To trade a stock-linked instrument on a 24/7 exchange with matching indicator history, use the
+  trading-hours helpers described in `jesse://strategy`.
+
 ## Usage Examples
 
 ### Basic Import

{jesse-3.2.0 → jesse-3.2.1}/jesse/mcp/resources/strategy.md

@@ -59,6 +59,7 @@ result = create_strategy("MyStrategy", strategy_code)
 
 - **before()**: Runs before the strategy logic each candle.
 - **after()**: Runs after the strategy logic each candle.
+- **trading_hours()**: Returns the market schedule dict (or `None`) for strategies that respect a market's hours; feeds `self.is_trading_hours`. See **Trading Hours** below.
 - **update_chart()**: Calculates chart-only values. Runs once per completed candle in backtests and approximately once per second on the forming candle in live/paper sessions. See **jesse://charts**.
 
 ## Strategy Execution Model (every candle)
@@ -273,6 +274,7 @@ The `Position` object exposes: `entry_price`, `qty`, `opened_at`, `value`, `type
 | `is_spot_trading` / `is_futures_trading` | bool | Market type checks. |
 | `is_backtesting` / `is_livetrading` / `is_papertrading` | bool | Run-mode checks. |
 | `is_live` | bool | True if live **or** paper trading. |
+| `is_trading_hours` | bool | True when `self.time` is inside the schedule returned by `trading_hours()`; always True when that returns `None`. |
 | `hp` | dict | Hyperparameter values keyed by name (see Optimization). |
 | `vars` | dict | Per-strategy scratch dict. |
 | `shared_vars` | dict | Dict shared across all routes (cross-route communication). |
@@ -287,6 +289,7 @@ The `Position` object exposes: `entry_price`, `qty`, `opened_at`, `value`, `type
 | `watch_list()` | Return a list of `(label, value)` tuples surfaced in live/paper monitoring. |
 | `hyperparameters()` | Return the list of optimizable parameters (see Optimization). |
 | `dna()` | Return a DNA string to apply optimized hyperparameters. |
+| `trading_hours()` | Return the market schedule dict, or `None` (default) for no schedule. See Trading Hours. |
 | `filters()` | Return a list of filter **methods** (not called) that must all pass before entry. *Optional — prefer plain `if` conditions in `should_long`/`should_short`; only define when asked.* |
 | `add_line_to_candle_chart(...)` etc. | Interactive chart series and levels. Use them from `update_chart()`; see `jesse://charts`. |
 
@@ -363,6 +366,72 @@ def big_trend(self):
 
 Lookahead bias is handled internally even across timeframes: the closing price of a higher-timeframe candle is never from the future, so you do not need to manually shift to a previous value.
 
+## Trading Hours (market sessions)
+
+Use this whenever the user wants entries limited to a market's hours, days or session, wants to
+skip weekends/holidays, or trades a **stock-linked instrument on a 24/7 crypto exchange**. The
+typical reason: stock history used for backtesting has gaps (nights, weekends, holidays), while
+the 24/7 exchange feed does not, so the same indicator would see two different histories.
+
+Three building blocks. **The engine enforces nothing**; you place them yourself:
+
+```python
+from jesse.strategies import Strategy, cached
+import jesse.indicators as ta
+from jesse import utils
+
+def trading_hours(self):
+    # dict, or None for "no schedule" (then is_trading_hours is always True and the
+    # filter returns its input unchanged)
+    return {'timezone': 'America/New_York', 'hours': {'Mon-Fri': '09:30-16:00'}}
+
+@property
+@cached
+def session_candles(self):
+    return utils.filter_candles_by_hours(self.candles, self.trading_hours())
+
+def should_long(self) -> bool:
+    if not self.is_trading_hours:
+        return False
+    return self.close > ta.donchian(self.session_candles[:-1]).upperband
+```
+
+Schedule dict keys:
+
+| Key | Required | Value |
+|---|---|---|
+| `timezone` | yes | IANA name (`'America/New_York'`, `'Asia/Tokyo'`, `'UTC'`). DST is handled. |
+| `hours` | yes | dict: day spec → `'HH:MM-HH:MM'` or a list of windows. Day specs: `'Mon-Fri'`, `'Sun-Thu'`, `'Mon,Wed,Fri'`, `'Sun'`. **Unlisted days are closed.** |
+| `closed` | no | list of ISO dates (`'2026-11-26'`) treated as closed (holidays). |
+| `overrides` | no | dict: ISO date → window(s) for that one day (early closes). |
+
+Windows are half-open (`open <= t < close`), an end earlier than the start wraps past midnight,
+and `'00:00-24:00'` is a whole day. More schedules:
+
+```python
+{'timezone': 'Asia/Riyadh', 'hours': {'Sun-Thu': '10:00-15:00'}}                    # Tadawul
+{'timezone': 'Asia/Tokyo', 'hours': {'Mon-Fri': ['09:00-11:30', '12:30-15:30']}}     # lunch break
+{'timezone': 'UTC', 'hours': {'Mon-Fri': '00:00-24:00'}}                            # crypto, skip weekends
+```
+
+Rules:
+
+- `self.is_trading_hours` is true when `self.time` is inside the schedule. Gate **entries** with it
+  (`should_long`/`should_short`). Do **not** gate `update_position()` or exits: stop-loss and
+  take-profit stay on the exchange and position management must keep running 24/7.
+- Feed entry indicators the **filtered** candles. Gating entries while still passing raw
+  `self.candles` to indicators leaves off-hours candles in the signal.
+- Never assign to `self.candles` and never hand-roll UTC-hour arithmetic (it breaks at DST
+  changes). `self.price`, `self.close` and `self.current_candle` always stay live.
+- There are no preset names such as `'NYSE'`; always return the dict. Holidays go in `closed`.
+- `trading_hours()` is a method so it may depend on `self`, e.g. `if self.is_backtesting: return None`
+  or a closing hour taken from `self.hp` for optimization. Using the same dict in backtest and
+  live makes the indicator history match in both.
+- Unfilled entry at the close is the user's policy: `def should_cancel_entry(self): return not self.is_trading_hours`
+  cancels it, returning `False` leaves it working overnight.
+
+A complete class is in `jesse://strategy_examples` (SessionBreakout).
+
 ## Charting Helpers
 
 These `Strategy` methods add lines and levels to interactive backtest, paper,
@@ -466,6 +535,7 @@ def dna(self):
 - **No dead variables** — don't compute a `stop_loss`/value you never use. If you only set the stop later in `on_open_position()` and don't use it for sizing, don't define it in `go_long()`.
 - **Check position type in `on_open_position()`** — branch on `self.is_long` / `self.is_short` before setting `stop_loss`/`take_profit`.
 - **`on_close_position` takes two args** — `def on_close_position(self, order, closed_trade) -> None`.
+- **Market hours: gate entries *and* filter candles** — for session-bound or stock-linked instruments use `trading_hours()` + `self.is_trading_hours` + `utils.filter_candles_by_hours(...)`. Don't write manual UTC-hour checks, don't reassign `self.candles`, and don't gate `update_position()`/exits by the schedule.
 
 ## Utility Functions (used in strategies)
 

{jesse-3.2.0 → jesse-3.2.1}/jesse/mcp/resources/strategy_examples.md

@@ -3,7 +3,8 @@
 A library of complete, copy-pasteable Jesse strategies that demonstrate real,
 verified API patterns: trend filters, ATR-based stops, partial take-profits,
 trailing stops, lifecycle hooks, multi-timeframe candles, optimization
-hyperparameters, live-monitoring watch lists, and multi-route pairs trading.
+hyperparameters, live-monitoring watch lists, multi-route pairs trading, and
+market trading hours.
 
 These are illustrative reference strategies, NOT financial advice. They exist to
 show *how the API is used*, not to recommend any particular trading approach.
@@ -1023,3 +1024,79 @@ class PairsTrading2(Strategy):
         if self.shared_vars["s2-position"] == 0:
             self.liquidate()
 ```
+
+---
+
+## Example 9 — SessionBreakout (trading hours)
+
+A Donchian breakout on a **stock-linked instrument traded on a 24/7 crypto exchange** (spot, long
+only). Entries are decided only during the US regular session and every entry indicator reads
+session candles only, so nights, weekends and the drift in between never reach the signal. The
+position itself is managed around the clock: exits are set in `on_open_position()` (spot rule),
+stay on the exchange, and the trailing stop in `update_position()` keeps following the live price
+outside the session.
+
+Features shown: `trading_hours()`, `self.is_trading_hours` as the entry gate,
+`utils.filter_candles_by_hours` behind a `@cached` property, the cancel-at-close policy in
+`should_cancel_entry`, and exits that deliberately ignore the schedule.
+
+```py
+from jesse.strategies import Strategy, cached
+import jesse.indicators as ta
+from jesse import utils
+
+# Days are always explicit; unlisted days are closed. Holidays would go in a 'closed' list.
+US_EQUITIES = {'timezone': 'America/New_York', 'hours': {'Mon-Fri': '09:30-16:00'}}
+
+
+class SessionBreakout(Strategy):
+    def trading_hours(self):
+        # Same schedule in backtest and live so the indicator history matches in both.
+        return US_EQUITIES
+
+    @property
+    @cached
+    def session_candles(self):
+        # The only history the entry indicators see
+        return utils.filter_candles_by_hours(self.candles, self.trading_hours())
+
+    @property
+    def donchian(self):
+        # Previous channel (exclude the current candle)
+        return ta.donchian(self.session_candles[:-1])
+
+    @property
+    def atr(self):
+        return ta.atr(self.session_candles)
+
+    def should_long(self) -> bool:
+        # Never decide an entry outside the session
+        if not self.is_trading_hours:
+            return False
+        return self.close > self.donchian.upperband
+
+    def should_short(self) -> bool:
+        return False
+
+    def should_cancel_entry(self) -> bool:
+        # An entry that did not fill by the close is cancelled, not left working overnight
+        return not self.is_trading_hours
+
+    def go_long(self):
+        qty = utils.size_to_qty(self.balance, self.price, fee_rate=self.fee_rate)
+        self.buy = qty, self.price
+
+    def go_short(self):
+        pass
+
+    def on_open_position(self, order) -> None:
+        if self.is_long:
+            self.stop_loss = self.position.qty, self.position.entry_price - 2 * self.atr
+            self.take_profit = self.position.qty, self.position.entry_price + 3 * self.atr
+
+    def update_position(self):
+        # Runs on every candle, day or night: the exchange never closes, so the stop
+        # trails the live price. Do NOT gate this with is_trading_hours.
+        if self.is_long:
+            self.stop_loss = self.position.qty, max(self.average_stop_loss, self.price - 2 * self.atr)
+```

{jesse-3.2.0 → jesse-3.2.1}/jesse/mcp/resources/utilities.md

@@ -221,6 +221,41 @@ from jesse.constants import TIMEFRAME_PRIORITY
 primary_timeframe = TIMEFRAME_PRIORITY[0]  # '1D'
 ```
 
+## Trading Hours
+
+Schedule-aware helpers for markets that close (see the Trading Hours section of `jesse://strategy`
+for the schedule dict: required `timezone` and `hours`, optional `closed` and `overrides`).
+
+### filter_candles_by_hours(candles, hours)
+
+Returns only the candles whose open time falls inside the schedule, in their original order.
+Pure function: the candle store and `self.candles` are never modified, nothing is resampled.
+
+**Parameters:**
+- `candles`: Numpy candle array (`self.candles`, a `self.get_candles(...)` result, research candles)
+- `hours`: Schedule dict, or `None` to return the input unchanged
+
+**Returns:** Numpy candle array (rows may be non-contiguous in time)
+
+**Example:**
+```python
+@property
+@cached
+def session_candles(self):
+    return utils.filter_candles_by_hours(self.candles, self.trading_hours())
+```
+
+### is_in_trading_hours(timestamp, hours)
+
+Whether a UTC-millisecond timestamp falls inside the schedule. Always `True` when `hours` is
+`None`. Inside a strategy prefer `self.is_trading_hours`, which is this applied to `self.time`.
+
+**Parameters:**
+- `timestamp`: UTC milliseconds
+- `hours`: Schedule dict, or `None`
+
+**Returns:** bool
+
 ## Precision Helpers
 
 ### subtract_floats(float1, float2)

{jesse-3.2.0 → jesse-3.2.1}/jesse/mcp/tools/candles.py

@@ -131,8 +131,13 @@ def register_candles_tools(mcp):
         "failed", or "cancelled". After "finished", optionally verify with
         get_existing_candles(). Use cancel_candle_import(import_id) to stop it.
 
-        All supported timeframes are imported automatically: 1m, 3m, 5m, 15m, 30m,
-        45m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1D, 3D, 1W, 1M.
+        Only one-minute candles are imported and stored, for every source. In backtests,
+        optimization, Monte Carlo, significance tests and research, all other timeframes
+        (3m, 5m, 15m, 30m, 45m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1D, 3D, 1W, 1M) are generated
+        from them at run time, so one import per exchange and symbol covers every
+        timeframe; there is no timeframe parameter. (Live sessions do not rely on imported
+        candles for this: they fetch each timeframe from the exchange unless the live
+        setting `generate_candles_from_1m` is enabled.)
 
         Parameters:
             exchange (str): Exchange name. Supported values:
@@ -706,7 +711,8 @@ def register_candles_tools(mcp):
         Use this when the user wants to backtest data they already imported as if it belonged
         to a different market, for example run Massive Stocks "SPY-USD" under
         "Binance Perpetual Futures" as "SPY-USDT" to use that exchange's futures simulation.
-        Every stored timeframe is copied. `target_exchange` must be a backtesting-capable
+        The whole stored one-minute series is copied (backtests generate every other timeframe
+        from it at run time, so they follow automatically). `target_exchange` must be a backtesting-capable
         exchange name exactly as Jesse lists it, and `target_symbol` defaults to `symbol`;
         set it when the target market quotes in another currency (USD vs USDT).
 

jesse-3.2.1/jesse/version.py

@@ -0,0 +1 @@
+__version__ = "3.2.1"

{jesse-3.2.0 → jesse-3.2.1/jesse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jesse
-Version: 3.2.0
+Version: 3.2.1
 Summary: A trading framework for cryptocurrencies
 Home-page: https://jesse.trade
 Author: Saleh Mir

{jesse-3.2.0 → jesse-3.2.1}/setup.py

@@ -3,7 +3,7 @@ from pathlib import Path
 from setuptools import setup, find_packages
 
 # also change in version.py
-VERSION = "3.2.0"
+VERSION = "3.2.1"
 DESCRIPTION = "A trading framework for cryptocurrencies"
 BASE_DIR = Path(__file__).resolve().parent
 

{jesse-3.2.0 → jesse-3.2.1}/tests/test_mcp_resources.py

@@ -79,3 +79,72 @@ def test_strategy_tool_descriptions_expose_update_chart_lifecycle():
     assert create_docs is not None and 'forming candle in live/paper sessions' in create_docs
     assert read_docs is not None and 'visualization-only chart calculations' in read_docs
     assert write_docs is not None and 'intrabar live/paper updates' in write_docs
+
+
+def test_strategy_resource_documents_the_trading_hours_api():
+    mcp = FakeMCP()
+
+    register_resources(mcp)
+
+    strategy = mcp.resources['jesse://strategy']()
+    assert '## Trading Hours' in strategy
+    assert 'def trading_hours(self):' in strategy
+    assert '`is_trading_hours`' in strategy
+    assert 'utils.filter_candles_by_hours(self.candles, self.trading_hours())' in strategy
+    # every key the schedule validator accepts must be documented
+    for key in ('`timezone`', '`hours`', '`closed`', '`overrides`'):
+        assert key in strategy
+    # the two rules an assistant most easily gets wrong
+    assert 'The engine enforces nothing' in strategy
+    assert 'Do **not** gate `update_position()` or exits' in strategy
+
+
+def test_documented_trading_hours_names_exist_in_the_real_api():
+    from jesse import utils
+    from jesse.services.trading_hours import _ALLOWED_KEYS
+    from jesse.strategies import Strategy
+
+    assert callable(utils.filter_candles_by_hours)
+    assert callable(utils.is_in_trading_hours)
+    assert callable(Strategy.trading_hours)
+    assert isinstance(Strategy.is_trading_hours, property)
+    assert _ALLOWED_KEYS == {'timezone', 'hours', 'closed', 'overrides'}
+
+
+def test_utilities_and_examples_resources_cover_trading_hours():
+    mcp = FakeMCP()
+
+    register_resources(mcp)
+
+    utilities = mcp.resources['jesse://utilities']()
+    assert '### filter_candles_by_hours(candles, hours)' in utilities
+    assert '### is_in_trading_hours(timestamp, hours)' in utilities
+
+    examples = mcp.resources['jesse://strategy_examples']()
+    assert 'class SessionBreakout(Strategy):' in examples
+    assert 'if not self.is_trading_hours:' in examples
+
+
+def test_candle_docs_state_that_only_one_minute_candles_are_imported():
+    mcp = FakeMCP()
+
+    register_resources(mcp)
+
+    candle = mcp.resources['jesse://candle']()
+    assert 'one-minute candles only' in candle
+    assert 'Timeframes are never imported' in candle
+    assert 'timeframes are imported automatically' not in candle.lower()
+
+    from jesse.mcp.tools import candles as candle_tools
+    import inspect
+
+    source = inspect.getsource(candle_tools)
+    assert 'Only one-minute candles are imported and stored' in source
+    assert 'timeframes are imported automatically' not in source.lower()
+
+
+def test_packaged_agent_rules_mention_trading_hours():
+    rules = _load_packaged_rules()
+
+    assert 'self.is_trading_hours' in rules
+    assert 'utils.filter_candles_by_hours(self.candles, self.trading_hours())' in rules

jesse-3.2.0/jesse/version.py

@@ -1 +0,0 @@
-__version__ = "3.2.0"