"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(scheduling): add adaptive sleep-hint seam to the kernel
shadowinlifedfdd5b0cfbef
diff --git a/agent/src/scheduling/kernel.py b/agent/src/scheduling/kernel.pyindex e46bcda5e..661c1901b 100644--- a/agent/src/scheduling/kernel.py+++ b/agent/src/scheduling/kernel.py@@ -14,7 +14,10 @@ Responsibilities (the complete list):with a ``task.cancel()`` fallback so shutdown never waits a full tick;* :meth:`SchedulerKernel._run` / :meth:`SchedulerKernel._sleep_or_wake` —the tick loop with per-tick exception isolation and an ``asyncio.Event``- wakeup that shortens the inter-tick sleep;+ wakeup that shortens the inter-tick sleep; the sleep is the fixed+ ``tick_interval_ms`` unless a consumer-provided ``sleep_hint_fn`` replaces+ it with an adaptive "next deadline" hint (the seam the live runtime+ scheduler's ``min(next_due - now, max_recheck)`` sleep adopts);* :meth:`SchedulerKernel.request_wake` — thread-safe, coalescing request tocut the current sleep short;* :meth:`SchedulerKernel.retry_delay_ms` — bounded exponential backoff;@@ -39,7 +42,7 @@ import loggingimport timefrom typing import Optional-from src.scheduling.types import NowFn, OnTickFn+from src.scheduling.types import NowFn, OnTickFn, SleepHintFnlogger = logging.getLogger(__name__)@@ -68,8 +71,10 @@ class SchedulerKernel:The loop calls ``on_tick(now_ms)`` once per tick, isolates its exceptions(one failing tick never kills the loop; ``asyncio.CancelledError``- propagates so :meth:`stop` stays bounded), then sleeps- ``tick_interval_ms`` unless a :meth:`request_wake` shortens the sleep.+ propagates so :meth:`stop` stays bounded), then sleeps — the fixed+ ``tick_interval_ms``, or when ``sleep_hint_fn`` is injected, the hint it+ returns for the post-tick clock — unless a :meth:`request_wake` shortens+ the sleep.Due-ness, next-run advancement and per-job error recording are theconsumer's own ``on_tick`` composition — the kernel stores the retry@@ -87,11 +92,13 @@ class SchedulerKernel:retry_max_delay_ms: int = DEFAULT_RETRY_MAX_DELAY_MS,on_tick: Optional[OnTickFn] = None,task_name: str = DEFAULT_TASK_NAME,+ sleep_hint_fn: Optional[SleepHintFn] = None,) -> None:"""Initialize the kernel.Args:- tick_interval_ms: Poll interval for the background loop.+ tick_interval_ms: Poll interval for the background loop. Also the+ fallback sleep when ``sleep_hint_fn`` is set but raises.now_fn: Injectable wall-clock source returning epoch milliseconds.enabled: When false, :meth:`start` and :meth:`stop` are no-ops.max_consecutive_failures: Failures allowed before a consumer@@ -101,6 +108,12 @@ class SchedulerKernel:retry_max_delay_ms: Upper bound for exponential retry backoff.on_tick: Async callable invoked once per tick with ``now_ms``.task_name: Name of the background ``asyncio`` task.+ sleep_hint_fn: Optional consumer-provided "next deadline" sleep+ hint. Called after each tick with a freshly read ``now_ms``;+ its return value (clamped non-negative) replaces+ ``tick_interval_ms`` as the inter-tick sleep, letting an+ adaptive-sleep consumer keep its sleep shape. A hint that+ raises is logged and falls back to ``tick_interval_ms``.Raises:ValueError: If the retry policy is invalid.@@ -119,6 +132,7 @@ class SchedulerKernel:self._retry_max_delay_ms = retry_max_delay_msself._on_tick = on_tickself._task_name = task_name+ self._sleep_hint_fn = sleep_hint_fnself._loop: asyncio.AbstractEventLoop | None = Noneself._task: asyncio.Task | None = Noneself._wakeup: asyncio.Event | None = None@@ -161,6 +175,11 @@ class SchedulerKernel:"""Return the injected per-tick callback (the only one the loop calls)."""return self._on_tick+ @property+ def sleep_hint_fn(self) -> Optional[SleepHintFn]:+ """Return the injected adaptive-sleep hint, or ``None`` for fixed-tick."""+ return self._sleep_hint_fn+# -- lifecycle ------------------------------------------------------------@property@@ -168,6 +187,15 @@ class SchedulerKernel:"""Return whether the background loop task is active."""return self._task is not None and not self._task.done()+ @property+ def task(self) -> asyncio.Task | None:+ """Return the background loop task, or ``None`` when not started.++ Read-only handle for owners that must await or inspect the loop task+ itself (e.g. a driver coroutine parking on the scheduler's lifetime).+ """+ return self._task+def start(self) -> None:"""Start the background loop.@@ -224,7 +252,23 @@ class SchedulerKernel:logger.error("scheduler kernel tick failed", exc_info=True)if self._stopping:break- await self._sleep_or_wake(self._tick_interval_ms)+ await self._sleep_or_wake(self._next_sleep_ms())++ def _next_sleep_ms(self) -> int:+ """Return the inter-tick sleep: the consumer's hint, or the fixed tick.++ The hint is read against a freshly sampled clock (post-tick), so an+ adaptive consumer computes its deadline against the same "now" shape+ its own loop would have. A raising hint is logged and demoted to the+ fixed tick — a buggy hint slows the loop down but never kills it.+ """+ if self._sleep_hint_fn is None:+ return self._tick_interval_ms+ try:+ return max(0, self._sleep_hint_fn(self._now_fn()))+ except Exception:+ logger.error("scheduler kernel sleep hint failed; using fixed tick", exc_info=True)+ return self._tick_interval_msasync def _sleep_or_wake(self, sleep_ms: int) -> None:wakeup = self._wakeupdiff --git a/agent/src/scheduling/types.py b/agent/src/scheduling/types.pyindex 22e36cc0f..2fad19e20 100644--- a/agent/src/scheduling/types.py+++ b/agent/src/scheduling/types.py@@ -44,3 +44,15 @@ NowFn = Callable[[], int]#: kernel isolates exceptions per tick (one failing tick never kills the#: loop); ``asyncio.CancelledError`` propagates so ``stop()`` stays bounded.OnTickFn = Callable[[int], Awaitable[None]]++#: Consumer-provided "next deadline" sleep hint, in epoch-ms and duration-ms.+#: Called by the kernel after each tick with a freshly read ``now_ms``; the+#: return value replaces the fixed ``tick_interval_ms`` as the inter-tick+#: sleep (clamped to be non-negative). This is the seam that lets an+#: adaptive-sleep consumer — one that sleeps until the earliest job deadline+#: rather than polling on a fixed cadence — adopt the kernel without giving+#: up its sleep shape. The kernel never interprets the number: bounding the+#: sleep (e.g. a max re-check cap) is the consumer's own composition. A hint+#: that raises is logged and falls back to ``tick_interval_ms`` so a buggy+#: hint cannot kill the loop.+SleepHintFn = Callable[[int], int]diff --git a/agent/tests/scheduling/test_kernel_sleep_hint.py b/agent/tests/scheduling/test_kernel_sleep_hint.pynew file mode 100644index 000000000..2ebe36d1c--- /dev/null+++ b/agent/tests/scheduling/test_kernel_sleep_hint.py@@ -0,0 +1,180 @@+"""Tests for the kernel's adaptive-sleep extension (``sleep_hint_fn``) and the+read-only ``task`` property — the seam the live runtime scheduler adopts in+step 2 of the scheduler unification.++House style (see test_kernel.py): async scenarios are driven with+``asyncio.run`` — no pytest-asyncio in this repo — with an injected ``now_fn``+instead of the wall clock, ``asyncio.sleep(0)`` yield loops or+``asyncio.Event`` handshakes instead of real waiting, and+``asyncio.wait_for`` timeouts so a wedged kernel fails the test instead of+hanging the suite.+"""++from __future__ import annotations++import asyncio+import itertools++import pytest++from src.scheduling.kernel import SchedulerKernel+++def test_sleep_hint_replaces_the_fixed_tick() -> None:+ """A 60s fixed tick would never reach the second tick inside the timeout;+ the hint shortens the inter-tick sleep to 1ms."""+ ticks: list[int] = []++ async def scenario() -> None:+ second = asyncio.Event()++ async def on_tick(now_ms: int) -> None:+ ticks.append(now_ms)+ if len(ticks) >= 2:+ second.set()++ kernel = SchedulerKernel(+ tick_interval_ms=60_000,+ now_fn=lambda: 1000,+ on_tick=on_tick,+ sleep_hint_fn=lambda now_ms: 1,+ )+ kernel.start()+ await asyncio.wait_for(second.wait(), timeout=2.0)+ await asyncio.wait_for(kernel.stop(), timeout=5.0)++ asyncio.run(scenario())++ assert len(ticks) >= 2+++def test_sleep_hint_receives_a_fresh_post_tick_now() -> None:+ """The hint is sampled against a freshly read clock, after the tick."""+ clock = itertools.count(1000, 1000)+ tick_nows: list[int] = []+ hint_nows: list[int] = []++ async def scenario() -> None:+ second = asyncio.Event()++ async def on_tick(now_ms: int) -> None:+ tick_nows.append(now_ms)+ if len(tick_nows) >= 2:+ second.set()++ def hint(now_ms: int) -> int:+ hint_nows.append(now_ms)+ return 1++ kernel = SchedulerKernel(+ tick_interval_ms=60_000, now_fn=lambda: next(clock), on_tick=on_tick, sleep_hint_fn=hint+ )+ kernel.start()+ await asyncio.wait_for(second.wait(), timeout=2.0)+ await asyncio.wait_for(kernel.stop(), timeout=5.0)++ asyncio.run(scenario())++ assert tick_nows[:2] == [1000, 3000]+ assert hint_nows[0] == 2000+++def test_negative_sleep_hint_is_clamped_to_zero() -> None:+ kernel = SchedulerKernel(sleep_hint_fn=lambda now_ms: -5)+ assert kernel._next_sleep_ms() == 0+++def test_next_sleep_ms_without_a_hint_is_the_fixed_tick() -> None:+ kernel = SchedulerKernel(tick_interval_ms=4321)+ assert kernel.sleep_hint_fn is None+ assert kernel._next_sleep_ms() == 4321+++def test_raising_sleep_hint_falls_back_to_the_fixed_tick() -> None:+ def bad_hint(now_ms: int) -> int:+ raise RuntimeError("boom")++ kernel = SchedulerKernel(tick_interval_ms=999, sleep_hint_fn=bad_hint)+ assert kernel._next_sleep_ms() == 999+++def test_raising_sleep_hint_does_not_kill_the_loop() -> None:+ ticks: list[int] = []++ async def scenario() -> None:+ third = asyncio.Event()++ async def on_tick(now_ms: int) -> None:+ ticks.append(now_ms)+ if len(ticks) >= 3:+ third.set()++ def bad_hint(now_ms: int) -> int:+ raise RuntimeError("boom")++ kernel = SchedulerKernel(tick_interval_ms=1, on_tick=on_tick, sleep_hint_fn=bad_hint)+ kernel.start()+ await asyncio.wait_for(third.wait(), timeout=5.0)+ assert kernel.is_running+ await asyncio.wait_for(kernel.stop(), timeout=5.0)++ asyncio.run(scenario())++ assert len(ticks) >= 3+++def test_sleep_hint_fn_is_exposed_read_only() -> None:+ def hint(now_ms: int) -> int:+ return 7++ kernel = SchedulerKernel(sleep_hint_fn=hint)+ assert kernel.sleep_hint_fn is hint+ with pytest.raises(AttributeError):+ kernel.sleep_hint_fn = None # read-only property+++def test_task_property_tracks_the_loop_lifecycle() -> None:+ async def scenario() -> None:+ kernel = SchedulerKernel(tick_interval_ms=60_000)+ assert kernel.task is None+ kernel.start()+ assert kernel.task is not None+ assert not kernel.task.done()+ await asyncio.wait_for(kernel.stop(), timeout=5.0)+ assert kernel.task is None++ asyncio.run(scenario())+++def test_wakeup_still_shortens_a_hinted_sleep() -> None:+ """request_wake cuts a long hinted sleep short — the hint does not+ disarm the wakeup path."""+ ticks: list[int] = []++ async def scenario() -> None:+ second = asyncio.Event()++ async def on_tick(now_ms: int) -> None:+ ticks.append(now_ms)+ if len(ticks) >= 2:+ second.set()++ kernel = SchedulerKernel(+ tick_interval_ms=60_000,+ now_fn=lambda: 1000,+ on_tick=on_tick,+ sleep_hint_fn=lambda now_ms: 60_000,+ )+ kernel.start()+ for _ in range(1000):+ await asyncio.sleep(0)+ if ticks:+ break+ assert ticks, "first tick did not run"+ kernel.request_wake()+ await asyncio.wait_for(second.wait(), timeout=2.0)+ await asyncio.wait_for(kernel.stop(), timeout=5.0)++ asyncio.run(scenario())++ assert len(ticks) >= 2