draftomen 0.3.0__py3-none-any.whl

draftomen/qt_gui.py

@@ -0,0 +1,338 @@
+"""Launch the Draftomen PySide6 and QML desktop application.
+Select the live application provider or deterministic mock provider explicitly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from time import monotonic
+from typing import Literal, cast
+
+from PySide6.QtCore import QTimer, QUrl
+from PySide6.QtGui import QFontDatabase, QGuiApplication
+from PySide6.QtQml import QQmlApplicationEngine
+from PySide6.QtQuickControls2 import QQuickStyle
+
+from draftomen import __version__
+from draftomen.carddb import (
+    CardDatabase,
+    build_card_database_from_bulk_file,
+    load_or_refresh_card_database,
+)
+from draftomen.cardimages import CardImageService, card_image_cache_dir
+from draftomen.mock_session import MOCK_SCENARIOS, MockLiveSession, MockScenario
+from draftomen.paths import resolve_player_log_path
+from draftomen.qt_adapter import (
+    GuiPreferencesAdapter,
+    LiveSessionAdapter,
+    SessionAdapter,
+    SessionFactory,
+)
+from draftomen.qt_mock import MockSessionAdapter
+from draftomen.session import LiveSession, SnapshotPublisher
+from draftomen.seventeen import (
+    DownloadProgressCallback,
+    SeventeenLandsData,
+    has_cached_17lands_data,
+    load_or_refresh_17lands_data,
+    metadata_augmenting_ratings_progress_loader,
+)
+
+
+SURFACES = ("live", "build", "backtest", "settings")
+ProviderName = Literal["live", "mock"]
+APPLICATION_NAME = "Draft Omen"
+
+
+def _configure_application_metadata(*, application: QGuiApplication) -> None:
+    """Set the Qt application metadata.
+    Use the canonical package name and version.
+    """
+    application.setApplicationName(APPLICATION_NAME)
+    application.setApplicationDisplayName(APPLICATION_NAME)
+    application.setApplicationVersion(__version__)
+    application.setOrganizationName(APPLICATION_NAME)
+
+
+def _qml_directory(*, executable_path: Path | None = None) -> Path:
+    """Resolve QML beside the source package or compiled bundle executable."""
+    source_directory = Path(__file__).with_name("qml")
+    if source_directory.is_dir():
+        return source_directory
+
+    bundle_executable = (
+        Path(sys.argv[0]) if executable_path is None else executable_path
+    )
+    return bundle_executable.resolve().parent / "qml"
+
+
+def _fixed_font_family() -> str:
+    if QGuiApplication.instance() is None:
+        raise RuntimeError(
+            "QGuiApplication must exist before resolving the fixed font."
+        )
+    return QFontDatabase.systemFont(QFontDatabase.SystemFont.FixedFont).family()
+
+
+def _parser(*, forced_provider: ProviderName | None = None) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Launch the Draft Omen desktop application.",
+    )
+    parser.add_argument(
+        "--provider",
+        choices=("live", "mock"),
+        default="live" if forced_provider is None else forced_provider,
+        help="Use production services or deterministic visual-development data.",
+    )
+    parser.add_argument(
+        "--scenario",
+        choices=MOCK_SCENARIOS,
+        default="ready",
+        help="Initial representative state in mock mode.",
+    )
+    parser.add_argument(
+        "--surface",
+        choices=SURFACES,
+        default="live",
+        help="Initial application surface.",
+    )
+    parser.add_argument("--width", type=int, default=1440)
+    parser.add_argument("--height", type=int, default=900)
+    parser.add_argument("--log-path", type=Path, default=None)
+    parser.add_argument("--app-dir", type=Path, default=None, help=argparse.SUPPRESS)
+    parser.add_argument(
+        "--bulk-file",
+        type=Path,
+        default=None,
+        help="Use a local Scryfall JSONL card database in live mode.",
+    )
+    parser.add_argument("--poll-interval", type=float, default=1.0)
+    parser.set_defaults(startup_scan=True)
+    parser.add_argument(
+        "--no-startup-scan",
+        dest="startup_scan",
+        action="store_false",
+        help="Skip live startup log recovery.",
+    )
+    parser.add_argument(
+        "--smoke-test",
+        action="store_true",
+        help="Render the window and exit automatically.",
+    )
+    parser.add_argument(
+        "--smoke-test-until-complete",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--screenshot",
+        type=Path,
+        help="Save the rendered window before exiting.",
+    )
+    return parser
+
+
+def _live_session_factory(
+    *,
+    log_path: Path | None,
+    app_dir: Path | None,
+    bulk_file: Path | None,
+    poll_interval: float,
+) -> SessionFactory:
+    def load_card_database() -> CardDatabase:
+        if bulk_file is not None:
+            return build_card_database_from_bulk_file(path=bulk_file)
+        return load_or_refresh_card_database(app_dir=app_dir)
+
+    def load_ratings(
+        set_code: str,
+        progress_callback: DownloadProgressCallback,
+        *,
+        refresh: bool,
+    ) -> SeventeenLandsData:
+        return load_or_refresh_17lands_data(
+            set_code=set_code,
+            app_dir=app_dir,
+            refresh=refresh,
+            progress_callback=progress_callback,
+        )
+
+    def factory(publish: SnapshotPublisher) -> LiveSession:
+        return LiveSession(
+            log_path=resolve_player_log_path(log_path=log_path),
+            card_database_loader=load_card_database,
+            app_dir=app_dir,
+            poll_interval=poll_interval,
+            snapshot_publisher=publish,
+            ratings_progress_loader_factory=lambda database: (
+                metadata_augmenting_ratings_progress_loader(
+                    database=database,
+                    load_ratings=load_ratings,
+                    app_dir=app_dir,
+                    persist_database=bulk_file is None,
+                )
+            ),
+            card_image_service=CardImageService(
+                cache_dir=card_image_cache_dir(app_dir=app_dir),
+                timeout_seconds=2.0,
+                max_attempts=1,
+            ),
+            ratings_cache_checker=lambda set_code: has_cached_17lands_data(
+                set_code=set_code,
+                app_dir=app_dir,
+            ),
+        )
+
+    return factory
+
+
+def _build_provider(*, args: argparse.Namespace) -> SessionAdapter:
+    if args.provider == "mock":
+        return MockSessionAdapter(
+            session=MockLiveSession(
+                scenario=cast(MockScenario, args.scenario),
+            )
+        )
+    if args.poll_interval <= 0:
+        raise ValueError("--poll-interval must be greater than zero.")
+    return LiveSessionAdapter(
+        session_factory=_live_session_factory(
+            log_path=args.log_path,
+            app_dir=args.app_dir,
+            bulk_file=args.bulk_file,
+            poll_interval=args.poll_interval,
+        ),
+        poll_interval_ms=max(1, round(args.poll_interval * 1000)),
+        startup_scan=args.startup_scan,
+    )
+
+
+def _finish_smoke_test(
+    *,
+    engine: QQmlApplicationEngine,
+    application: QGuiApplication,
+    screenshot: Path | None,
+) -> None:
+    root_objects = engine.rootObjects()
+    if not root_objects:
+        application.exit(1)
+        return
+    if screenshot is not None:
+        screenshot.parent.mkdir(parents=True, exist_ok=True)
+        image = root_objects[0].grabWindow()
+        if image.isNull() or not image.save(str(screenshot)):
+            application.exit(1)
+            return
+        print(f"Saved GUI screenshot to {screenshot}")
+    application.quit()
+
+
+def _finish_smoke_test_when_draft_completes(
+    *,
+    engine: QQmlApplicationEngine,
+    application: QGuiApplication,
+    provider: SessionAdapter,
+    screenshot: Path | None,
+    timeout_seconds: float = 10.0,
+) -> None:
+    deadline = monotonic() + timeout_seconds
+    timer = QTimer(application)
+
+    def stop_waiting() -> None:
+        timer.stop()
+        timer.timeout.disconnect(finish_when_ready)
+        timer.deleteLater()
+
+
+    def finish_when_ready() -> None:
+        status = provider.state.get("status", {})
+        if status.get("phase") == "draft_complete":
+            stop_waiting()
+            QTimer.singleShot(
+                0,
+                lambda: _finish_smoke_test(
+                    engine=engine,
+                    application=application,
+                    screenshot=screenshot,
+                ),
+            )
+        elif monotonic() >= deadline:
+            stop_waiting()
+            QTimer.singleShot(0, lambda: application.exit(1))
+
+    timer.setInterval(20)
+    timer.timeout.connect(finish_when_ready)
+    timer.start()
+
+def run_gui(
+    *,
+    argv: Sequence[str] | None = None,
+    forced_provider: ProviderName | None = None,
+) -> int:
+    args = _parser(forced_provider=forced_provider).parse_args(argv)
+    if forced_provider is not None:
+        args.provider = forced_provider
+
+    QQuickStyle.setStyle("Fusion")
+    application = QGuiApplication([sys.argv[0]])
+    _configure_application_metadata(application=application)
+
+    provider = _build_provider(args=args)
+    preferences = GuiPreferencesAdapter(app_dir=args.app_dir, parent=application)
+    engine = QQmlApplicationEngine()
+    qml_directory = _qml_directory()
+    engine.addImportPath(str(qml_directory))
+    context = engine.rootContext()
+    context.setContextProperty("sessionProvider", provider)
+    context.setContextProperty("guiPreferences", preferences)
+    context.setContextProperty("applicationTitle", APPLICATION_NAME)
+    context.setContextProperty("fixedFontFamily", _fixed_font_family())
+    context.setContextProperty("applicationVersion", __version__)
+    context.setContextProperty("initialSurface", args.surface)
+    context.setContextProperty("initialWindowWidth", args.width)
+    context.setContextProperty("initialWindowHeight", args.height)
+    engine.setInitialProperties({"provider": provider})
+
+    engine.load(QUrl.fromLocalFile(str(qml_directory / "Main.qml")))
+    if not engine.rootObjects():
+        return 1
+
+    if isinstance(provider, LiveSessionAdapter):
+        application.aboutToQuit.connect(provider.shutdown)
+        provider.start()
+
+    if args.smoke_test_until_complete:
+        _finish_smoke_test_when_draft_completes(
+            engine=engine,
+            application=application,
+            provider=provider,
+            screenshot=args.screenshot,
+        )
+    elif args.smoke_test or args.screenshot is not None:
+        QTimer.singleShot(
+            800,
+            lambda: _finish_smoke_test(
+                engine=engine,
+                application=application,
+                screenshot=args.screenshot,
+            ),
+        )
+    exit_code = application.exec()
+    preferences.shutdown()
+    if isinstance(provider, LiveSessionAdapter):
+        provider.shutdown()
+        provider.wait_for_shutdown()
+    del engine
+    return exit_code
+
+
+def main() -> int:
+    return run_gui()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

draftomen/qt_mock.py

@@ -0,0 +1,63 @@
+"""Launch the deterministic PySide6 and QML desktop mockup.
+The mock provider implements the same narrow contract as the live adapter.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from PySide6.QtCore import Property, QObject, Slot
+
+from draftomen.mock_session import MOCK_SCENARIOS, MockLiveSession, MockScenario
+from draftomen.qt_adapter import SessionAdapter
+from draftomen.session import LiveSessionCommand
+
+
+class MockSessionAdapter(SessionAdapter):
+    """Translate deterministic snapshots and explicit commands for QML.
+    The mock owns representative data only, never production behavior.
+    """
+
+    def __init__(
+        self,
+        *,
+        session: MockLiveSession,
+        parent: QObject | None = None,
+    ) -> None:
+        self._session = session
+        super().__init__(snapshot=session.snapshot, parent=parent)
+
+    @Property(bool, constant=True)
+    def mockMode(self) -> bool:
+        return True
+
+    @Property(str, notify=SessionAdapter.scenarioChanged)
+    def scenario(self) -> str:
+        return self._session.scenario
+
+    @Property("QStringList", constant=True)
+    def scenarios(self) -> list[str]:
+        return list(MOCK_SCENARIOS)
+
+    @Slot(str)
+    def selectScenario(self, scenario: str) -> None:
+        if scenario not in MOCK_SCENARIOS:
+            return
+        self._session.select_scenario(scenario=cast(MockScenario, scenario))
+        self.scenarioChanged.emit()
+        self._publish(snapshot=self._session.snapshot)
+
+    def _dispatch(self, *, command: LiveSessionCommand) -> None:
+        self._session.dispatch(command=command)
+        self._publish(snapshot=self._session.snapshot)
+
+
+def main() -> int:
+    from draftomen.qt_gui import run_gui
+
+    return run_gui(forced_provider="mock")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

draftomen/ranking.py

@@ -0,0 +1,126 @@
+"""Shared ranking modes for scored draft cards.
+Keep UI sorting and backtest recommendations explicit and consistent.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypeAlias
+
+from draftomen.pickengine import ScoredCard
+
+RankingMode: TypeAlias = Literal["win_rate", "score", "alsa", "mv"]
+
+DEFAULT_RANKING_MODE: RankingMode = "score"
+RANKING_MODES: tuple[RankingMode, ...] = ("score", "win_rate", "alsa", "mv")
+RANKING_LABELS: dict[RankingMode, str] = {
+    "win_rate": "17L WR",
+    "score": "DO Score",
+    "alsa": "ALSA",
+    "mv": "MV",
+}
+
+
+def validate_ranking_mode(*, ranking_mode: str) -> RankingMode:
+    """Return a supported ranking mode or fail loudly.
+    Callers use this before producing user-visible recommendations.
+    """
+
+    if ranking_mode in RANKING_MODES:
+        return ranking_mode  # type: ignore[return-value]
+
+    allowed = ", ".join(RANKING_MODES)
+    raise ValueError(f"Unsupported ranking mode {ranking_mode!r}; expected one of {allowed}.")
+
+
+def ranking_label(*, ranking_mode: str) -> str:
+    """Return the user-facing label for one ranking mode.
+    Unknown values are validated so labels never silently lie.
+    """
+
+    return RANKING_LABELS[validate_ranking_mode(ranking_mode=ranking_mode)]
+
+
+def rank_scored_cards(
+    *,
+    cards: tuple[ScoredCard, ...],
+    ranking_mode: str,
+) -> tuple[ScoredCard, ...]:
+    """Return scored cards ordered by the selected ranking mode.
+    Ties remain deterministic and prefer stronger DO scores where useful.
+    """
+
+    mode = validate_ranking_mode(ranking_mode=ranking_mode)
+    if mode == "win_rate":
+        return tuple(sorted(cards, key=_win_rate_sort_key))
+
+    if mode == "score":
+        return tuple(sorted(cards, key=_score_sort_key))
+
+    if mode == "alsa":
+        return tuple(sorted(cards, key=_alsa_sort_key))
+
+    return tuple(sorted(cards, key=_mana_value_sort_key))
+
+
+def _win_rate_sort_key(
+    card: ScoredCard,
+) -> tuple[bool, bool, float, int, float, int]:
+    win_rate = card.rating.gih_win_rate
+    if win_rate is None:
+        return (
+            card.freely_available_basic,
+            True,
+            0.0,
+            -card.score,
+            -card.raw_score,
+            card.original_index,
+        )
+
+    return (
+        card.freely_available_basic,
+        False,
+        -win_rate,
+        -card.score,
+        -card.raw_score,
+        card.original_index,
+    )
+
+
+def _score_sort_key(
+    card: ScoredCard,
+) -> tuple[bool, int, int, float, float, int]:
+    return (
+        card.freely_available_basic,
+        card.score_sort_index,
+        -card.score,
+        -card.raw_score,
+        -card.base_rating,
+        card.original_index,
+    )
+
+
+def _alsa_sort_key(card: ScoredCard) -> tuple[bool, float, int, float, int]:
+    alsa = card.rating.average_last_seen_at
+    sort_alsa = float("inf") if alsa is None else alsa
+    return (
+        card.freely_available_basic,
+        sort_alsa,
+        -card.score,
+        -card.raw_score,
+        card.original_index,
+    )
+
+
+def _mana_value_sort_key(
+    card: ScoredCard,
+) -> tuple[bool, float, int, float, int]:
+    mana_value = card.card.mana_value
+    sort_mana_value = float("inf") if mana_value is None else mana_value
+    return (
+        card.freely_available_basic,
+        sort_mana_value,
+        -card.score,
+        -card.raw_score,
+        card.original_index,
+    )
+