bdo-toolkit 1.0.6__tar.gz → 1.0.7__tar.gz

{bdo_toolkit-1.0.6/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.6
+Version: 1.0.7
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -60,16 +60,18 @@ no usable adapter is found. Discovery does not apply settings or verify decoding
 
 ## Capabilities
 
-bdo-toolkit exposes three passive workflows. Each can observe live traffic or
-replay a saved PCAP or PCAPNG file.
+bdo-toolkit exposes four passive workflows. Item activity, item state, and
+Solare support live capture and saved PCAP or PCAPNG replay. Grind tracking
+combines supported observations in one live session.
 
 | Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
 | Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
 | Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
 | Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+| Grind tracking | One capture for confirmed mob drops, with optional profile-based Agris and solo XP | [GrindSession](https://ychwu.github.io/bdo-toolkit/#grind-session) | Experimental |
 
-These workflows include synchronous and
+The standalone workflows include synchronous and
 [asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
 decoder health diagnostics, console and JSONL event writers, and a
 [command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact

{bdo_toolkit-1.0.6 → bdo_toolkit-1.0.7}/README.md

@@ -33,16 +33,18 @@ no usable adapter is found. Discovery does not apply settings or verify decoding
 
 ## Capabilities
 
-bdo-toolkit exposes three passive workflows. Each can observe live traffic or
-replay a saved PCAP or PCAPNG file.
+bdo-toolkit exposes four passive workflows. Item activity, item state, and
+Solare support live capture and saved PCAP or PCAPNG replay. Grind tracking
+combines supported observations in one live session.
 
 | Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
 | Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
 | Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
 | Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+| Grind tracking | One capture for confirmed mob drops, with optional profile-based Agris and solo XP | [GrindSession](https://ychwu.github.io/bdo-toolkit/#grind-session) | Experimental |
 
-These workflows include synchronous and
+The standalone workflows include synchronous and
 [asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
 decoder health diagnostics, console and JSONL event writers, and a
 [command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact

{bdo_toolkit-1.0.6 → bdo_toolkit-1.0.7}/src/bdo_toolkit/__init__.py

@@ -41,7 +41,7 @@ from .origin_learning import (
     promote_origin_candidates,
 )
 from .writers import ConsoleEventWriter, JsonlEventWriter
-from . import agris, solare
+from . import agris, grind, solare, xp
 from ._version import __version__
 
 __all__ = [
@@ -84,10 +84,12 @@ __all__ = [
     "__version__",
     "capture_live",
     "agris",
+    "grind",
     "fetch_opcode_profile",
     "load_opcode_profile",
     "promote_origin_candidates",
     "replay_pcap",
     "storage_location",
     "solare",
+    "xp",
 ]

{bdo_toolkit-1.0.6 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_engine.py

@@ -41,16 +41,20 @@ class _TeeScanner:
         primary: TargetMessageScanner,
         tap: Optional[FrameCollectorScanner],
         stream_observer: Optional[Callable[[bytes, PacketContext], None]],
+        unhinted_tap: Optional[FrameCollectorScanner] = None,
     ) -> None:
         self._primary = primary
         self._tap = tap
         self._stream_observer = stream_observer
+        self._unhinted_tap = unhinted_tap
 
     def feed(self, data, context) -> None:
         if self._stream_observer is not None:
             self._stream_observer(data, context)
         if self._tap is not None:
             self._tap.feed(data, context)
+        if self._unhinted_tap is not None:
+            self._unhinted_tap.feed(data, context)
         self._primary.feed(data, context)
 
     def scan_standalone(self, data, context) -> None:
@@ -58,6 +62,8 @@ class _TeeScanner:
             self._stream_observer(data, context)
         if self._tap is not None:
             self._tap.scan_standalone(data, context)
+        if self._unhinted_tap is not None:
+            self._unhinted_tap.scan_standalone(data, context)
         self._primary.scan_standalone(data, context)
 
     def can_anchor_at_start(self, data: bytes) -> bool:
@@ -69,6 +75,8 @@ class _TeeScanner:
     def reset(self) -> None:
         if self._tap is not None:
             self._tap.reset()
+        if self._unhinted_tap is not None:
+            self._unhinted_tap.reset()
         self._primary.reset()
 
 
@@ -189,6 +197,8 @@ class PacketEngine:
         message_observer: Optional[MessageObserver] = None,
         max_pending_segments: int = MAX_PENDING_SEGMENTS,
         max_pending_bytes: Optional[int] = None,
+        defer_gap_timeouts: bool = False,
+        unhinted_frame_observer: Optional[Callable[[BDOFrame], None]] = None,
     ) -> None:
         self.event_specs = tuple(event_specs)
         self.events_found = 0
@@ -203,7 +213,7 @@ class PacketEngine:
                 self.event_specs,
                 message_observer=message_observer,
             )
-            if frame_observer is None and stream_observer is None:
+            if frame_observer is None and stream_observer is None and unhinted_frame_observer is None:
                 return primary
             tap = (
                 FrameCollectorScanner(
@@ -213,7 +223,12 @@ class PacketEngine:
                 if frame_observer is not None
                 else None
             )
-            return _TeeScanner(primary, tap, stream_observer)
+            # Optional telemetry must keep its standalone synchronization
+            # authority. Item opcode hints are only for the existing item tap;
+            # accidental headers in a midstream prefix must not steer XP/Agris.
+            unhinted_tap = (FrameCollectorScanner(unhinted_frame_observer)
+                            if unhinted_frame_observer is not None else None)
+            return _TeeScanner(primary, tap, stream_observer, unhinted_tap)
 
         self._flow_manager = FlowManager(
             server_ports=server_ports,
@@ -226,6 +241,7 @@ class PacketEngine:
             idle_timeout=_ITEM_FLOW_IDLE_SECONDS,
             max_pending_segments=max_pending_segments,
             max_pending_bytes=max_pending_bytes,
+            defer_gap_timeouts=defer_gap_timeouts,
         )
         self._seen_event_keys: set[
             tuple[FlowKey, int, int, int, Optional[int], bytes]

bdo_toolkit-1.0.6/src/bdo_toolkit/agris/session.py → bdo_toolkit-1.0.7/src/bdo_toolkit/_observation_session.py

@@ -1,42 +1,45 @@
-"""Single-owner live Agris acquisition; no profiles or consumption accounting."""
+"""Private bounded observation-session lifecycle shared by Agris and solo XP."""
 from __future__ import annotations
 
 from collections.abc import Iterator
-from dataclasses import replace
 import math
 from pathlib import Path
 from queue import Empty, Full, Queue
 from threading import Event, Lock, Thread, current_thread
 import time
 from types import TracebackType
-from typing import Any, Callable
+from typing import Any, Callable, Protocol, Self
 
-from .._capture_backend import make_packet_handler, open_packet_writer
-from .._capture_options import LiveCaptureOptions
-from .._capture_runtime import CaptureEndpoint, CaptureStats, LivePacketCapture, _attach_cleanup_owner
-from ..capture import CaptureIntegrityError
-from ._capture import AgrisCaptureHealth, AgrisFlowManager
-from ._discovery import AgrisTracker
-from .models import AgrisBalance, AgrisDiscoveryOptions, AgrisStatus
+from ._capture_options import LiveCaptureOptions
+from ._capture_runtime import CaptureEndpoint, CaptureStats, LivePacketCapture, _attach_cleanup_owner
+from ._capture_backend import SegmentConsumer
+from .capture import CaptureIntegrityError
 
 
-class LiveAgrisSession:
-    """Continuous, single-consumer Agris balance stream with required cap input.
+class ObservationManager(SegmentConsumer, Protocol):
+    @property
+    def tcp_gap_resets(self) -> int: ...
+
+    def service_gaps(self, now: float) -> int: ...
+
 
-    One owner thread starts/stops acquisition, decodes packets, and services
-    deadlines even if the application stops polling. Native callbacks only
-    enqueue packets. Both queues are bounded: overflow is an explicit failure.
-    Every session cold-discovers an inferred layout; none is saved or reused.
+class ObservationSession[T, S]:
+    """Single owner for acquisition, bounded delivery, deadlines and cleanup.
+
+    Domains own their decoder, status/health view and clean-stop result policy.
+    Factories are explicit so existing domain test seams remain unchanged.
     """
 
     _JOIN_TIMEOUT = 15.0
     _START_TIMEOUT = 15.0
 
-    def __init__(self, *, expected_maximum_points: int,
-                 live_options: LiveCaptureOptions | None = None,
-                 discovery_options: AgrisDiscoveryOptions | None = None,
-                 capture_seconds: float | None = None,
-                 save_pcap: str | Path | None = None) -> None:
+    def __init__(self, *, label: str, snapshot: Callable[[], S],
+                 manager: ObservationManager, refresh: Callable[[float | None], None],
+                 live_options: LiveCaptureOptions | None,
+                 capture_seconds: float | None, save_pcap: str | Path | None,
+                 capture_factory: Callable[..., LivePacketCapture],
+                 handler_factory: Callable[..., Callable[[object], None]],
+                 writer_factory: Callable[..., Any]) -> None:
         if live_options is not None and not isinstance(live_options, LiveCaptureOptions):
             raise TypeError("live_options must be LiveCaptureOptions or None")
         if capture_seconds is not None and (isinstance(capture_seconds, bool)
@@ -44,12 +47,12 @@ class LiveAgrisSession:
                 or not math.isfinite(capture_seconds) or capture_seconds <= 0):
             raise ValueError("capture_seconds must be finite and positive")
         self._options = live_options or LiveCaptureOptions()
-        self._events: Queue[AgrisBalance] = Queue(self._options.event_queue_size)
+        self._label, self._snapshot, self._refresh = label, snapshot, refresh
+        self._capture_factory, self._handler_factory, self._writer_factory = capture_factory, handler_factory, writer_factory
+        self._events: Queue[T] = Queue(self._options.event_queue_size)
         self._packets: Queue[object] = Queue(self._options.packet_queue_size)
-        self._tracker = AgrisTracker(expected_maximum_points=expected_maximum_points,
-                                    options=discovery_options, on_balance=self._publish)
-        self._manager = AgrisFlowManager(self._tracker, self._options.ports, live=True)
-        self._status = self._tracker.snapshot()
+        self._manager = manager
+        self._status = snapshot()
         self._seconds = capture_seconds
         self._save_path = Path(save_pcap).expanduser().resolve() if save_pcap is not None else None
         if self._save_path is not None and self._save_path.suffix.lower() not in {".pcap", ".pcapng"}:
@@ -73,23 +76,8 @@ class LiveAgrisSession:
         self._stop_reason: str | None = None
         self._accepted = self._processed = self._packet_overflows = self._event_overflows = 0
 
-    @property
-    def status(self) -> AgrisStatus:
-        with self._state_lock:
-            status, error = self._status, self._error
-        return replace(status, status="invalid", balance=None, reason=str(error)) if error else status
-
-    @property
-    def health(self) -> AgrisCaptureHealth:
-        with self._state_lock:
-            return AgrisCaptureHealth(
-                packets_processed=self._processed, packets_accepted=self._accepted,
-                packet_queue_overflows=self._packet_overflows, event_queue_overflows=self._event_overflows,
-                tcp_gap_resets=self._manager.tcp_gap_resets, flow_state_evictions=self._manager.evictions,
-                pcap_received=self._stats.received, pcap_dropped=self._stats.dropped,
-                pcap_interface_dropped=self._stats.interface_dropped,
-                capture_buffer_bytes=self._stats.capture_buffer_bytes,
-                cleanup_incomplete=self._cleanup_incomplete)
+    def _on_clean_stop(self) -> None:
+        pass
 
     @property
     def endpoint(self) -> CaptureEndpoint | None:
@@ -138,22 +126,22 @@ class LiveAgrisSession:
         except Full:
             with self._state_lock:
                 self._packet_overflows += 1
-            error = CaptureIntegrityError("Agris packet queue overflow; capture incomplete")
+            error = CaptureIntegrityError(f"{self._label} packet queue overflow; capture incomplete")
             self._record_error(error)
             raise error
         with self._state_lock:
             self._accepted += 1
 
-    def _publish(self, balance: AgrisBalance) -> None:
+    def _publish(self, balance: T) -> None:
         try:
             self._events.put_nowait(balance)
         except Full as exc:
             with self._state_lock:
                 self._event_overflows += 1
-            raise CaptureIntegrityError("Agris balance queue overflow; consumer too slow") from exc
+            raise CaptureIntegrityError(f"{self._label} balance queue overflow; consumer too slow") from exc
 
     def _update_status(self) -> None:
-        status = self._tracker.snapshot()
+        status = self._snapshot()
         with self._state_lock:
             self._status = status
 
@@ -165,14 +153,14 @@ class LiveAgrisSession:
         with self._state_lock:
             self._stats = stats
         if (stats.dropped or 0) > 0 or (stats.interface_dropped or 0) > 0:
-            raise CaptureIntegrityError("Agris capture backend reported dropped packets")
+            raise CaptureIntegrityError(f"{self._label} capture backend reported dropped packets")
 
     def start(self) -> None:
         with self._lifecycle_lock:
             if self._start_attempted:
-                raise RuntimeError("Agris sessions are single-use")
+                raise RuntimeError(f"{self._label} sessions are single-use")
             self._start_attempted = True
-            worker = Thread(target=self._run, name="bdo-toolkit-agris", daemon=True)
+            worker = Thread(target=self._run, name=f"bdo-toolkit-{self._label.lower()}", daemon=True)
             self._worker = worker
             try:
                 worker.start()
@@ -183,7 +171,7 @@ class LiveAgrisSession:
                 raise
         try:
             if not self._ready.wait(self._START_TIMEOUT):
-                raise TimeoutError("Agris capture startup did not become ready")
+                raise TimeoutError(f"{self._label} capture startup did not become ready")
             self.raise_if_failed()
         except BaseException as primary:
             self._record_error(primary)
@@ -192,9 +180,9 @@ class LiveAgrisSession:
                 self.stop()
             except BaseException as cleanup:
                 if cleanup is not primary:
-                    primary.add_note(f"Agris startup cleanup also failed: {cleanup!r}")
+                    primary.add_note(f"{self._label} startup cleanup also failed: {cleanup!r}")
             if self.cleanup_incomplete:
-                _attach_cleanup_owner(primary, self, context="Agris startup")
+                _attach_cleanup_owner(primary, self, context=f"{self._label} startup")
             raise
 
     def _process(self, packet: object) -> None:
@@ -204,7 +192,7 @@ class LiveAgrisSession:
         if self.error is None:
             assert self._handler is not None
             self._handler(packet)
-            self._manager.refresh()
+            self._refresh(None)
             self._update_status()
         with self._state_lock:
             self._processed += 1
@@ -215,9 +203,9 @@ class LiveAgrisSession:
                 if self._save_path.exists():
                     raise FileExistsError(f"refusing to overwrite existing capture: {self._save_path}")
                 self._save_path.parent.mkdir(parents=True, exist_ok=True)
-                self._writer = open_packet_writer(self._save_path)
-            self._handler = make_packet_handler(self._manager)
-            self._capture = LivePacketCapture(capture_options=self._options, on_packet=self._accept)
+                self._writer = self._writer_factory(self._save_path)
+            self._handler = self._handler_factory(self._manager)
+            self._capture = self._capture_factory(capture_options=self._options, on_packet=self._accept)
             self._capture.start()
             self._capture_started = True
             self._capture.raise_if_failed()
@@ -227,7 +215,7 @@ class LiveAgrisSession:
             while not self._stop_requested.is_set():
                 self._capture.raise_if_failed()
                 if not self._capture.running:
-                    raise CaptureIntegrityError("Agris capture backend stopped unexpectedly")
+                    raise CaptureIntegrityError(f"{self._label} capture backend stopped unexpectedly")
                 if deadline is not None and time.monotonic() >= deadline:
                     with self._state_lock:
                         self._stop_reason = "duration"
@@ -243,7 +231,7 @@ class LiveAgrisSession:
                     if self._packets.empty():
                         now = time.time()
                         self._manager.service_gaps(now)
-                        self._manager.refresh(now)
+                        self._refresh(now)
                         self._update_status()
                 else:
                     self._process(packet)
@@ -271,7 +259,7 @@ class LiveAgrisSession:
             if incomplete:
                 with self._state_lock:
                     self._cleanup_incomplete = True
-                self._record_error(RuntimeError("Agris native cleanup is incomplete; retry stop()"))
+                self._record_error(RuntimeError(f"{self._label} native cleanup is incomplete; retry stop()"))
                 return
             try:
                 self._read_stats(final=True)
@@ -304,13 +292,15 @@ class LiveAgrisSession:
         with self._state_lock:
             self._cleanup_incomplete = False
             self._stop_reason = self._stop_reason or "requested"
+        if self.error is None:
+            self._on_clean_stop()
         self._stopped.set()
 
     def stop(self) -> None:
         if not self._start_attempted:
-            raise RuntimeError("Agris session was not started")
+            raise RuntimeError(f"{self._label} session was not started")
         if self._worker is current_thread():
-            raise RuntimeError("Agris stop() cannot join its decoder thread")
+            raise RuntimeError(f"{self._label} stop() cannot join its decoder thread")
         self._stop_requested.set()
         with self._lifecycle_lock:
             worker = self._worker
@@ -319,23 +309,23 @@ class LiveAgrisSession:
             if worker is not None and worker.is_alive():
                 with self._state_lock:
                     self._cleanup_incomplete = True
-                self._record_error(RuntimeError("Agris decoder cleanup timed out; retry stop()"))
+                self._record_error(RuntimeError(f"{self._label} decoder cleanup timed out; retry stop()"))
             elif self.cleanup_incomplete:
                 self._shutdown()
             error = self.error
             if error is not None:
                 if self.cleanup_incomplete:
-                    _attach_cleanup_owner(error, self, context="Agris stop")
+                    _attach_cleanup_owner(error, self, context=f"{self._label} stop")
                 raise error
 
-    def poll(self, timeout: float | None = None) -> AgrisBalance | None:
+    def poll(self, timeout: float | None = None) -> T | None:
         if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, (float, int))
                                     or not math.isfinite(timeout) or timeout < 0):
             raise ValueError("timeout must be finite and nonnegative")
         if not self._start_attempted:
-            raise RuntimeError("Agris session was not started")
+            raise RuntimeError(f"{self._label} session was not started")
         if not self._consumer_lock.acquire(blocking=False):
-            raise RuntimeError("Agris sessions support one balance consumer")
+            raise RuntimeError(f"{self._label} sessions support one balance consumer")
         try:
             deadline = None if timeout is None else time.monotonic() + timeout
             while True:
@@ -362,7 +352,7 @@ class LiveAgrisSession:
         finally:
             self._consumer_lock.release()
 
-    def events(self) -> Iterator[AgrisBalance]:
+    def events(self) -> Iterator[T]:
         while True:
             balance = self.poll()
             if balance is not None:
@@ -370,7 +360,7 @@ class LiveAgrisSession:
             elif self.stopped:
                 return
 
-    def __enter__(self) -> LiveAgrisSession:
+    def __enter__(self) -> Self:
         self.start()
         return self
 
@@ -382,5 +372,5 @@ class LiveAgrisSession:
             if exc_value is None:
                 raise
             if self.cleanup_incomplete:
-                _attach_cleanup_owner(exc_value, self, context="Agris context")
-            exc_value.add_note(f"Agris context cleanup also failed: {cleanup!r}")
+                _attach_cleanup_owner(exc_value, self, context=f"{self._label} context")
+            exc_value.add_note(f"{self._label} context cleanup also failed: {cleanup!r}")

{bdo_toolkit-1.0.6 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_profile_runtime.py

@@ -14,6 +14,8 @@ from .profiles import (
     OpcodeProfile,
     OriginCompanionFamily,
     ProfileError,
+    AgrisProfileLayout,
+    XPProfileLayout,
 )
 
 
@@ -39,6 +41,14 @@ def validate_runtime_profile(profile: OpcodeProfile) -> RuntimeProfileValidation
         )
     if profile.active is not True:
         raise ProfileError(f"Opcode profile is inactive: {profile.path}")
+    if profile.xp is not None:
+        if not isinstance(profile.xp, XPProfileLayout):
+            raise ProfileError("xp must be an XPProfileLayout")
+        profile.xp.__post_init__()
+    if profile.agris is not None:
+        if not isinstance(profile.agris, AgrisProfileLayout):
+            raise ProfileError("agris must be an AgrisProfileLayout")
+        profile.agris.__post_init__()
 
     loaded_specs = event_specs_from_profile(profile)
     decrement_specs = tuple(

{bdo_toolkit-1.0.6 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_reassembly.py

@@ -357,19 +357,23 @@ class TCPFlowState:
             and self.gap_started_at is not None
             and now - self.gap_started_at >= GAP_RESET_SECONDS
         ):
-            fin_sequence = _unwrap_tcp_sequence(
-                self.fin_sequence,
-                self.next_sequence,
-            )
-            if self.next_sequence < fin_sequence:
-                self.scanner.reset()
-                if self.on_gap_reset is not None:
-                    self.on_gap_reset(fin_sequence)
-                self.next_sequence = fin_sequence
-                self.gap_started_at = None
-                resets += 1
+            resets += self._resume_after_fin_gap()
         return resets
 
+    def _resume_after_fin_gap(self) -> bool:
+        """Report bytes proven missing by FIN, after pending payload is drained."""
+        if self.fin_sequence is None or self.next_sequence is None:
+            return False
+        fin_sequence = _unwrap_tcp_sequence(self.fin_sequence, self.next_sequence)
+        if self.next_sequence >= fin_sequence:
+            return False
+        self.scanner.reset()
+        if self.on_gap_reset is not None:
+            self.on_gap_reset(fin_sequence)
+        self.next_sequence = fin_sequence
+        self.gap_started_at = None
+        return True
+
     def _resume_after_gap(self) -> None:
         if not self.pending:
             return
@@ -394,6 +398,9 @@ class TCPFlowState:
         self._commit_unanchored()
         while self.pending:
             self._resume_after_gap()
+        # EOF alone cannot prove missing bytes. An observed FIN ahead of the
+        # drained stream can, even when shutdown precedes the live gap timer.
+        self._resume_after_fin_gap()
 
 
 class FlowManager:

{bdo_toolkit-1.0.6 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the BDO Toolkit release version."""
 
-__version__ = "1.0.6"
+__version__ = "1.0.7"

bdo_toolkit-1.0.7/src/bdo_toolkit/agris/__init__.py

@@ -0,0 +1,17 @@
+"""Passive Agris balances with explicit profile decoding or required-cap discovery."""
+from ..profiles import AgrisProfileLayout
+from ._calibration_models import AgrisCalibrationError, AgrisCalibrationResult, AgrisProfileUpdate
+from ._capture import AgrisCaptureHealth
+from .async_session import AsyncLiveAgrisSession
+from .models import AgrisBalance, AgrisDetectionError, AgrisDiscoveryOptions, AgrisLayout, AgrisStatus
+from .replay import AgrisReplay, replay_agris
+from .session import LiveAgrisSession
+from .calibration import calibrate_agris_live, calibrate_agris_and_update, update_agris_profile
+
+__all__ = [
+    "AgrisBalance", "AgrisCaptureHealth", "AgrisDetectionError", "AgrisDiscoveryOptions",
+    "AgrisLayout", "AgrisReplay", "AgrisStatus", "AsyncLiveAgrisSession",
+    "LiveAgrisSession", "replay_agris",
+    "AgrisProfileLayout", "AgrisCalibrationError", "AgrisCalibrationResult", "AgrisProfileUpdate",
+    "calibrate_agris_live", "calibrate_agris_and_update", "update_agris_profile",
+]

bdo_toolkit-1.0.7/src/bdo_toolkit/agris/_calibration_models.py

@@ -0,0 +1,70 @@
+"""Final Agris calibration evidence and explicit profile-write outcomes."""
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from ..profiles import AgrisProfileLayout
+from ._capture import AgrisCaptureHealth
+from ._validation import validate_expected_maximum_points
+from .models import AgrisDetectionError, AgrisStatus
+
+
+class AgrisCalibrationError(AgrisDetectionError):
+    """No final, clean discovered layout is available for persistence."""
+
+
+@dataclass(frozen=True)
+class AgrisCalibrationResult:
+    layout: AgrisProfileLayout
+    expected_maximum_points: int
+    observed_frames: int
+    health: AgrisCaptureHealth
+    completed_at: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.layout, AgrisProfileLayout):
+            raise TypeError("layout must be AgrisProfileLayout")
+        self.layout.__post_init__()
+        validate_expected_maximum_points(self.expected_maximum_points)
+        if type(self.observed_frames) is not int or self.observed_frames < 3:
+            raise AgrisCalibrationError("Calibration requires at least three observed frames")
+        if not isinstance(self.health, AgrisCaptureHealth) or not self.health.capture_is_clean or self.health.cleanup_incomplete:
+            raise AgrisCalibrationError("Calibration requires clean, completed capture")
+        if not isinstance(self.completed_at, str):
+            raise TypeError("completed_at must be an ISO timestamp")
+        try:
+            if datetime.fromisoformat(self.completed_at).tzinfo is None:
+                raise ValueError
+        except ValueError as exc:
+            raise ValueError("completed_at must be a timezone-aware ISO timestamp") from exc
+
+    def to_dict(self) -> dict[str, object]:
+        return {"layout": self.layout.to_dict(), "expected_maximum_points": self.expected_maximum_points,
+                "observed_frames": self.observed_frames, "health": self.health.to_dict(),
+                "completed_at": self.completed_at}
+
+
+@dataclass(frozen=True)
+class AgrisProfileUpdate:
+    path: Path
+    written: bool
+    backup_path: Path | None
+    layout: AgrisProfileLayout
+
+    def to_dict(self) -> dict[str, object]:
+        return {"path": str(self.path), "written": self.written,
+                "backup_path": str(self.backup_path) if self.backup_path else None,
+                "layout": self.layout.to_dict()}
+
+
+def final_calibration_result(status: AgrisStatus, health: AgrisCaptureHealth) -> AgrisCalibrationResult | None:
+    if status.status != "tracking" or status.balance is None or len(status.candidates) != 1:
+        return None
+    if not health.capture_is_clean or health.cleanup_incomplete:
+        return None
+    candidate = status.candidates[0]
+    layout = AgrisProfileLayout(opcode=candidate.opcode, message_length=candidate.message_length,
+                               remaining_offset=candidate.remaining_offset, maximum_offset=candidate.maximum_offset,
+                               observed_date=datetime.fromtimestamp(status.balance.observed_at, UTC).date().isoformat())
+    return AgrisCalibrationResult(layout, status.expected_maximum_points, status.observed_frames,
+                                  health, datetime.now(UTC).isoformat())