bdo-toolkit 1.0.3__tar.gz → 1.0.4__tar.gz

{bdo_toolkit-1.0.3/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.3
+Version: 1.0.4
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -104,6 +104,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.3 → bdo_toolkit-1.0.4}/README.md

@@ -77,6 +77,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.3 → bdo_toolkit-1.0.4}/src/bdo_toolkit/_async_sessions.py

@@ -9,6 +9,7 @@ thread and make cancellation deterministic.
 from __future__ import annotations
 
 import asyncio
+import math
 from collections import deque
 from concurrent.futures import ThreadPoolExecutor
 from functools import partial
@@ -16,12 +17,14 @@ from pathlib import Path
 from types import TracebackType
 from typing import AsyncIterator, Callable, Optional
 
+from ._async_utils import _await_preserving_future, _wait_ignoring_cancellation
 from ._capture_runtime import CaptureEndpoint, _attach_cleanup_owner
 from ._capture_options import LiveCaptureOptions, PacketCaptureOptions
 from .calibration import (
     DEFAULT_CALIBRATION_MAX_RETAINED_BYTES,
     DEFAULT_CALIBRATION_MAX_RETAINED_FRAMES,
     CalibrationResult,
+    CalibrationProgress,
     CalibrationRetention,
     CalibrationSession,
 )
@@ -33,28 +36,6 @@ from .origin_learning import CompanionObservation
 from .profiles import OpcodeProfile
 
 
-async def _wait_ignoring_cancellation[T](future: asyncio.Future[T]) -> T:
-    """Wait for an already-started operation, even after caller cancellation."""
-
-    while not future.done():
-        try:
-            # asyncio.wait() never propagates cancellation into ``future`` and
-            # does not create a cancelled shield wrapper that may later log an
-            # otherwise-retrieved worker exception on Python 3.14.
-            await asyncio.wait((future,))
-        except asyncio.CancelledError:
-            # Cleanup must settle before the original cancellation escapes.
-            continue
-    return future.result()
-
-
-async def _await_preserving_future[T](future: asyncio.Future[T]) -> T:
-    """Await without cancelling or wrapping the submitted worker future."""
-
-    await asyncio.wait((future,))
-    return future.result()
-
-
 def _thread_task[T](function: Callable[[], T]) -> asyncio.Task[T]:
     return asyncio.create_task(asyncio.to_thread(function))
 
@@ -390,6 +371,13 @@ class AsyncCalibrationSession:
     session.  Exiting the async context before ``stop()`` calls ``abort()`` and
     discards the unfinished calibration, matching the synchronous context
     manager's safety behavior.
+
+    ``stop_on_complete=True`` enables automatic finalization. ``await wait()``
+    observes completion without stopping on timeout or cancellation. ``progress``,
+    ``result``, ``stopped``, and ``stop_reason`` expose the synchronous owner's
+    state. ``on_update`` is synchronous on that owner's worker or finalizing
+    thread; use ``loop.call_soon_threadsafe`` for async/UI state.
+    ``request_stop()`` is synchronous and callback-safe.
     """
 
     def __init__(
@@ -403,6 +391,8 @@ class AsyncCalibrationSession:
         min_confidence: float = 0.80,
         max_retained_frames: int = DEFAULT_CALIBRATION_MAX_RETAINED_FRAMES,
         max_retained_bytes: int = DEFAULT_CALIBRATION_MAX_RETAINED_BYTES,
+        stop_on_complete: bool = False,
+        on_update: Callable[[CalibrationProgress], object] | None = None,
     ) -> None:
         self._session = CalibrationSession(
             item_id=item_id,
@@ -413,6 +403,8 @@ class AsyncCalibrationSession:
             min_confidence=min_confidence,
             max_retained_frames=max_retained_frames,
             max_retained_bytes=max_retained_bytes,
+            stop_on_complete=stop_on_complete,
+            on_update=on_update,
         )
         self._active = False
         self._terminal_action: str | None = None
@@ -470,7 +462,69 @@ class AsyncCalibrationSession:
     def result(self) -> CalibrationResult | None:
         """Completed result, including one preserved across cancellation."""
 
-        return self._result
+        if self._result is not None:
+            return self._result
+        if self._active and getattr(self._session, "stopped", False):
+            return self._session.result
+        return None
+
+    @property
+    def progress(self) -> CalibrationProgress | None:
+        return self._session.progress
+
+    @property
+    def stopped(self) -> bool:
+        return self._session.stopped
+
+    @property
+    def stop_reason(self) -> str | None:
+        return self._session.stop_reason
+
+    def request_stop(self) -> None:
+        """Callback-safe request; callbacks run on the synchronous worker."""
+        self._session.request_stop()
+
+    async def wait(self, timeout: float | None = None) -> CalibrationResult | None:
+        """Await completion; timeout/cancellation leaves capture running.
+
+        Cancellation settles the one bounded pending wait before escaping.
+        An enclosing async context still performs its usual cleanup on exit.
+        """
+        if timeout is not None and (
+            isinstance(timeout, bool) or not isinstance(timeout, (int, float))
+            or not math.isfinite(timeout) or timeout < 0
+        ):
+            raise ValueError("timeout must be finite and non-negative")
+        loop = asyncio.get_running_loop()
+        deadline = None if timeout is None else loop.time() + timeout
+        terminal_poll = False
+        while True:
+            remaining = None if deadline is None else max(0.0, deadline - loop.time())
+            wait_seconds = 0.2 if remaining is None else min(0.2, remaining)
+            if terminal_poll:
+                wait_seconds = 0.0
+            task = _thread_task(partial(self._session.wait, wait_seconds))
+            try:
+                result = await _await_preserving_future(task)
+            except asyncio.CancelledError:
+                try:
+                    await _wait_ignoring_cancellation(task)
+                except BaseException:
+                    pass
+                raise
+            if result is not None:
+                self._result = result
+                return result
+            if terminal_poll:
+                return None  # Terminal discard, without a result or error.
+            if self.stopped:
+                # Completion may have raced the empty poll's delivery. Re-read
+                # through wait() to retrieve the final result or raise its error,
+                # using the same cancellation-safe worker path as ordinary polls.
+                terminal_poll = True
+                continue
+            if deadline is not None and loop.time() >= deadline:
+                return None
 
     async def start(self) -> None:
         """Begin calibration capture without blocking the event loop."""
@@ -581,6 +635,10 @@ class AsyncCalibrationSession:
             self._active = self._session.cleanup_incomplete
             raise
         else:
+            # Automatic finalization may have won the race with context exit.
+            # Preserve that completed result even when nobody awaited wait().
+            if getattr(self._session, "stopped", False):
+                self._result = self._session.result
             self._active = False
 
     async def abort(self) -> None:

bdo_toolkit-1.0.4/src/bdo_toolkit/_async_utils.py

@@ -0,0 +1,25 @@
+"""Cancellation-safe waits shared by asynchronous session facades."""
+
+import asyncio
+
+
+async def _wait_ignoring_cancellation[T](future: asyncio.Future[T]) -> T:
+    """Wait for an already-started operation, even after caller cancellation."""
+
+    while not future.done():
+        try:
+            # asyncio.wait() never propagates cancellation into ``future`` and
+            # does not create a cancelled shield wrapper that may later log an
+            # otherwise-retrieved worker exception on Python 3.14.
+            await asyncio.wait((future,))
+        except asyncio.CancelledError:
+            # Cleanup must settle before the original cancellation escapes.
+            continue
+    return future.result()
+
+
+async def _await_preserving_future[T](future: asyncio.Future[T]) -> T:
+    """Await without cancelling or wrapping the submitted worker future."""
+
+    await asyncio.wait((future,))
+    return future.result()

bdo_toolkit-1.0.4/src/bdo_toolkit/_calibration/__init__.py

@@ -0,0 +1,4 @@
+"""Private calibration inference, passive capture, and profile persistence.
+
+Internal modules do not import the public ``bdo_toolkit.calibration`` facade.
+"""

bdo_toolkit-1.0.4/src/bdo_toolkit/_calibration/_constants.py

@@ -0,0 +1,42 @@
+"""Private calibration constants implementation."""
+
+from __future__ import annotations
+
+from .._protocol import (
+    CHARACTER_LOAD_CONTEXT,
+    SOURCE_CONTEXT_LABELS,
+    STORAGE_DELTA_CONTEXTS,
+)
+
+
+CALIBRATION_ACTIONS = (
+    "loot-preview",
+    "storage-to-inventory",
+    "inventory-to-storage",
+)
+DEFAULT_CALIBRATION_MAX_RETAINED_FRAMES = 50_000
+DEFAULT_CALIBRATION_MAX_RETAINED_BYTES = 64 * 1024 * 1024
+_CALIBRATION_MAX_ACTIVE_FLOWS = 64
+OPCODE_PROFILE_EVENTS = (
+    "LOOT_PREVIEW",
+    "INVENTORY_TRANSFER",
+    "SOURCE_CONTAINER_DECREMENT",
+    "SOURCE_STACK_DECREMENT",
+    "SOURCE_ITEM_REFERENCE",
+    "STORAGE_ITEM_DELTA",
+)
+_FAMILY_LABELS = {
+    "into_inventory": "storage->inventory",
+    "into_storage": "inventory->storage",
+}
+REFERENCE_FRAME_MAX_LENGTH = 128
+SOURCE_DECREMENT_FRAME_MAX_LENGTH = 512
+_HIGH_ENTROPY_CONTEXTS = tuple(
+    value
+    for value in SOURCE_CONTEXT_LABELS
+    if value != CHARACTER_LOAD_CONTEXT and value not in STORAGE_DELTA_CONTEXTS
+)
+_EXPECTED_FAMILY = {
+    "storage-to-inventory": "into_inventory",
+    "inventory-to-storage": "into_storage",
+}

bdo_toolkit-1.0.4/src/bdo_toolkit/_calibration/_formatting.py

@@ -0,0 +1,65 @@
+"""Private calibration formatting implementation."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Iterable
+from ._constants import OPCODE_PROFILE_EVENTS
+from ._records import _Options
+from .models import MessageSpec
+
+
+def _dedupe_message_specs(specs: Iterable[MessageSpec]) -> list[MessageSpec]:
+    output: list[MessageSpec] = []
+    seen: set[tuple[object, ...]] = set()
+    for spec in specs:
+        key = spec.dedupe_key()
+        if key in seen:
+            continue
+        seen.add(key)
+        output.append(spec)
+    return output
+
+
+def _confidence_label(score: float) -> str:
+    level = "high" if score >= 0.90 else "medium"
+    return f"calibrated-{level}"
+
+
+def _calibration_source(options: _Options, action: str) -> str:
+    parts = [f"calibrate {action}", f"item_id={options.item_id}"]
+    if options.quantity is not None:
+        parts.append(f"qty={options.quantity}")
+    return " ".join(parts)
+
+
+def _iso_timestamp(timestamp: float) -> str:
+    return (
+        dt.datetime.fromtimestamp(timestamp, tz=dt.UTC)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def _utc_now_text() -> str:
+    return (
+        dt.datetime.now(tz=dt.UTC)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def _events_for_action(action: str) -> tuple[str, ...]:
+    if action == "loot-preview":
+        return ("LOOT_PREVIEW",)
+    if action == "storage-to-inventory":
+        return ("INVENTORY_TRANSFER", "SOURCE_CONTAINER_DECREMENT")
+    if action == "inventory-to-storage":
+        return (
+            "SOURCE_STACK_DECREMENT",
+            "SOURCE_ITEM_REFERENCE",
+            "STORAGE_ITEM_DELTA",
+        )
+    # ``auto`` observes both transfer directions but never owns the separate
+    # loot-preview workflow.
+    return tuple(event for event in OPCODE_PROFILE_EVENTS if event != "LOOT_PREVIEW")