oep 0.1.0__py3-none-any.whl

oep/__init__.py

@@ -0,0 +1,13 @@
+"""``oep`` — the Open Experiment Protocol researcher-facing package.
+
+Today this ships one surface, :mod:`oep.conductor` (a conductor-mastered
+client for the ``oep-draft-network`` extension protocol). ``oep.data`` and
+``oep.assets`` are reserved names for future surfaces (documented only —
+no stub code ships here yet).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

oep/conductor/__init__.py

@@ -0,0 +1,53 @@
+"""``oep.conductor`` — conductor-mastered client for the ``oep-draft-network``
+extension protocol.
+
+Re-exports the full researcher-facing surface: the ``run_study`` generator
+front door (TLS and ``replay_transcript=`` supported), the class-API
+``serve_strategy``/``serve_replay`` front doors and the ``TrialStrategy``
+Protocol they drive, the ``Break``/``BREAK`` sentinel, the
+``TrialResult``/``TrialResultMeta``/``SessionSummary`` result types, and the
+package's public exception types (``errors`` itself is also re-exported as a
+submodule, so ``oep.conductor.errors.SomeError`` always works even for a
+name this module doesn't re-export directly).
+
+Protocol/transcript internals (the envelope codec, the session/sequencing
+state machine, transcript record/replay) are deliberately NOT part of this
+top-level surface — import them from ``oep.conductor.protocol`` /
+``oep.conductor.transcript`` directly if you need them.
+"""
+
+from __future__ import annotations
+
+from . import errors
+from .errors import (
+    ConductorConnectionLost,
+    ProtocolError,
+    SingleFlightViolation,
+    TranscriptMismatchError,
+    TrialSpecError,
+)
+from .generator import run_study
+from .protocol import PROTOCOL_VERSION
+from .results import SessionSummary, TrialResult, TrialResultMeta
+from .server import serve_replay, serve_strategy
+from .strategy import BREAK, Break, TrialParams, TrialStrategy
+
+__all__ = [
+    "run_study",
+    "serve_strategy",
+    "serve_replay",
+    "Break",
+    "BREAK",
+    "TrialParams",
+    "TrialStrategy",
+    "TrialResult",
+    "TrialResultMeta",
+    "SessionSummary",
+    "PROTOCOL_VERSION",
+    "TrialSpecError",
+    "ConductorConnectionLost",
+    "TranscriptMismatchError",
+    "SingleFlightViolation",
+    "ProtocolError",
+    "errors",
+]

oep/conductor/errors.py

@@ -0,0 +1,84 @@
+"""Exceptions raised by :mod:`oep.conductor`.
+
+All conductor-facing exceptions live here — every other module (the
+generator bridge, the ``server``/``strategy``/``protocol`` layers) imports
+from this module rather than defining its own; this is the single source of
+truth for the package's error contract, re-exported at ``oep.conductor``.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "TrialSpecError",
+    "ConductorConnectionLost",
+    "TranscriptMismatchError",
+    "SingleFlightViolation",
+    "ProtocolError",
+]
+
+
+class TrialSpecError(Exception):
+    """Raised when a value yielded by a study generator (or returned by a
+    :class:`~oep.conductor.strategy.TrialStrategy`) fails validation at the
+    yield site.
+
+    Per the package design's yield contract, every yielded value must be a
+    ``Break`` or a JSON-safe mapping with string keys and finite values
+    (NumPy scalars/arrays are narrowed first; anything else is rejected).
+    The message names the offending key path and type so a researcher can
+    find the bad value in their own study code without instrumenting it.
+    """
+
+
+class ConductorConnectionLost(Exception):
+    """Raised when the transport is lost mid-study (the runner disconnects,
+    or the socket errors out, before a ``done``/close was sent).
+
+    Guaranteed to carry a ``partial_summary`` attribute — a
+    ``SessionSummary`` with ``status="connection_lost"`` reflecting how far
+    the session got before the transport went away — so callers can recover
+    trial-completion accounting even from an abnormal end.
+    """
+
+    partial_summary: object
+
+
+class TranscriptMismatchError(Exception):
+    """Raised during ``replay_transcript=`` playback when a runner's
+    outbound message diverges from the transcript's next expectation (by
+    type or trial id — never timing/RT, which are expected to vary run to
+    run).
+
+    The message names the transcript line, what was expected, and what was
+    actually received.
+    """
+
+
+class SingleFlightViolation(RuntimeError):
+    """Raised by :meth:`~oep.conductor.protocol.ConductorSession.send_trial_spec_payload`
+    when a caller tries to send a new ``trialSpec`` before the preceding
+    one's ``trialResult`` has been received and accepted.
+
+    This is the sending-side enforcement of the extension spec's normative
+    Single-Flight Conductor Profile MUST. It signals a bug in the calling
+    strategy/loop, not a wire-level condition — a well-behaved conductor
+    should never trigger this in practice.
+    """
+
+
+class ProtocolError(RuntimeError):
+    """A protocol-level violation (seq gap, premature message, bad handshake).
+
+    Per the extension spec, any of these ends the run with reason ``error``
+    on this conductor's side too — there is no recovery path for them in
+    v0.1 (transparent reconnect is explicitly deferred).
+
+    This is public and researcher-facing: it escapes
+    :func:`~oep.conductor.generator.run_study` (and
+    :func:`~oep.conductor.server.serve_strategy`/
+    :func:`~oep.conductor.server.serve_replay`) whenever
+    :class:`~oep.conductor.protocol.ConductorSession` detects a sequence gap
+    or a premature/malformed handshake message -- see the package README's
+    failure-semantics section for what a researcher should do when they see
+    one.
+    """

oep/conductor/generator.py

@@ -0,0 +1,416 @@
+"""``run_study`` — the generator front door, and the strict trial-spec
+normalization it enforces at the yield site (package design's §run_study,
+§Yield contract, §Break, §Terminal-state semantics).
+
+This module has three parts:
+
+- :func:`normalize_trial_params` — a pure, socket-free function implementing
+  the yield contract's strict-JSON + NumPy-narrowing rules exactly.
+- :class:`_GeneratorStrategy` — the private bridge adapting a zero-argument
+  generator *factory* (the researcher's ``study`` callable) onto the
+  :class:`~oep.conductor.strategy.TrialStrategy` shape consumed by
+  :func:`~oep.conductor.server.serve_strategy`.
+- :func:`run_study` — composes the bridge with ``serve_strategy``, plus the
+  kwarg validation documented in the package design's ``run_study`` signature
+  block.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import math
+import ssl
+from pathlib import Path
+from typing import Any, Callable, Generator, Mapping, Optional
+
+from .errors import TrialSpecError
+from .results import SessionSummary, TrialResult
+from .server import serve_replay, serve_strategy
+from .strategy import Break, TrialParams
+
+__all__ = ["run_study", "normalize_trial_params"]
+
+
+# ---------------------------------------------------------------------------
+# Yield contract: strict-JSON + NumPy narrowing (pure, socket-free)
+# ---------------------------------------------------------------------------
+
+#: The four numpy ABC family names we recognize by walking a value's class
+#: hierarchy (``type(x).__mro__``) — chosen to mirror numpy's own abstract
+#: base classes (``numpy.integer``, ``numpy.floating``, ``numpy.bool_``,
+#: ``numpy.ndarray``) WITHOUT importing numpy and WITHOUT the generic
+#: ``hasattr(x, "tolist")`` duck-typing the spec explicitly rules out: origin
+#: is decided by ``__module__``, kind is decided by class *name* ancestry.
+#: ``bool_`` covers numpy <2.0's class name; numpy >=2.0 renamed the scalar
+#: type's own ``__name__`` to plain ``bool`` (``numpy.bool_`` is now just an
+#: alias) — both are checked so this works across numpy major versions.
+_NUMPY_NDARRAY = "ndarray"
+_NUMPY_BOOL_NAMES = frozenset({"bool_", "bool"})
+_NUMPY_INTEGER = "integer"
+_NUMPY_FLOATING = "floating"
+
+
+#: Returned by :func:`_numpy_kind` for a NumPy-origin value whose class
+#: hierarchy doesn't match any of the four recognized kinds (e.g. a complex
+#: or structured scalar) -- distinct from ``None``, which means "not
+#: NumPy-origin at all" and falls through to the ordinary JSON-type checks.
+_NUMPY_UNKNOWN = "unknown"
+
+
+def _numpy_kind(value: Any) -> Optional[str]:
+    """Classify a NumPy-origin value's kind (one of ``"ndarray"``,
+    ``"bool_"``, ``"integer"``, ``"floating"``, or :data:`_NUMPY_UNKNOWN`),
+    or ``None`` if ``value`` isn't NumPy-origin at all (see module docstring
+    for the detection strategy)."""
+    origin_type = type(value)
+    if not origin_type.__module__.startswith("numpy"):
+        return None
+    ancestor_names = {klass.__name__ for klass in origin_type.__mro__}
+    if _NUMPY_NDARRAY in ancestor_names:
+        return _NUMPY_NDARRAY
+    if ancestor_names & _NUMPY_BOOL_NAMES:
+        return "bool_"
+    if _NUMPY_INTEGER in ancestor_names:
+        return _NUMPY_INTEGER
+    if _NUMPY_FLOATING in ancestor_names:
+        return _NUMPY_FLOATING
+    return _NUMPY_UNKNOWN  # NumPy-origin but not one of the four recognized kinds
+
+
+def _check_finite(value: float, path: str) -> None:
+    if math.isnan(value) or math.isinf(value):
+        raise TrialSpecError(
+            f"{path}: non-finite float ({value!r}) is not JSON-safe "
+            "(NaN/Infinity are rejected by the yield contract's strict-JSON rule)"
+        )
+
+
+def _normalize_value(value: Any, *, path: str) -> Any:
+    kind = _numpy_kind(value)
+    if kind == _NUMPY_NDARRAY:
+        # .tolist() then the RESULT is recursively re-validated -- so an
+        # object-dtype array with an unsupported element fails element-by-
+        # element with a clear path, rather than passing opaquely.
+        return _normalize_value(value.tolist(), path=path)
+    if kind == "bool_":
+        return bool(value)
+    if kind == _NUMPY_INTEGER:
+        return int(value)
+    if kind == _NUMPY_FLOATING:
+        converted = float(value)
+        _check_finite(converted, path)
+        return converted
+    if kind is not None:
+        # NumPy-origin but not integer/floating/bool_/ndarray (e.g. a
+        # complex or structured scalar) -- no safe narrowing rule for it.
+        raise TrialSpecError(
+            f"{path}: unsupported NumPy type {type(value).__name__!r} "
+            "(only integer/floating/bool_/ndarray are narrowed)"
+        )
+
+    # bool MUST be checked before int -- bool is an int subclass in Python.
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        _check_finite(value, path)
+        return value
+    if isinstance(value, str) or value is None:
+        return value
+    if isinstance(value, Mapping):
+        return normalize_trial_params(value, path=path)
+    if isinstance(value, (list, tuple)):
+        # Tuples normalize to lists per the yield contract.
+        return [_normalize_value(item, path=f"{path}[{i}]") for i, item in enumerate(value)]
+
+    raise TrialSpecError(f"{path}: unsupported type {type(value).__name__!r} is not JSON-safe")
+
+
+def normalize_trial_params(mapping: Mapping[str, Any], *, path: str = "") -> dict:
+    """Validate and normalize one yielded trial-params mapping, per the
+    package design's §Yield contract, EXACTLY:
+
+    - NumPy-origin values are narrowed (`np.integer` -> ``int``,
+      `np.floating` -> ``float``, `np.bool_` -> ``bool``, `np.ndarray` ->
+      ``.tolist()`` then recursively re-validated) without ever importing
+      numpy.
+    - Strict JSON: non-finite floats (``nan``/``inf``/``-inf``) are
+      rejected; mapping keys must be ``str``; tuples normalize to lists;
+      any other type raises :class:`~oep.conductor.errors.TrialSpecError`
+      naming the offending key path and type.
+
+    Returns a **brand-new** ``dict``/``list`` tree built entirely from
+    immutable leaves (``str``/``int``/``float``/``bool``/``None``) -- this
+    is already the deep-copied snapshot the spec requires (later mutation
+    of the researcher's original mapping, or of anything they hold onto,
+    cannot reach the normalized values transmitted here).
+
+    Raises at the call site (no partial results): validation failures
+    propagate as :class:`~oep.conductor.errors.TrialSpecError`, letting the
+    generator bridge's ``next_trial()`` surface them as a study failure
+    (terminal-state "failed" path).
+    """
+    if not isinstance(mapping, Mapping):
+        raise TrialSpecError(
+            f"{path or '<trial>'}: expected a mapping, got {type(mapping).__name__!r}"
+        )
+
+    result: dict[str, Any] = {}
+    for key, value in mapping.items():
+        if not isinstance(key, str):
+            key_path = f"{path}.<{key!r}>" if path else f"<{key!r}>"
+            raise TrialSpecError(
+                f"{key_path}: mapping keys must be str, got {type(key).__name__!r}"
+            )
+        child_path = f"{path}.{key}" if path else key
+        result[key] = _normalize_value(value, path=child_path)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# _GeneratorStrategy: factory -> TrialStrategy bridge
+# ---------------------------------------------------------------------------
+
+
+def _reject_if_already_started(study: Any) -> None:
+    """Factory-only enforcement, shared by :func:`run_study`'s up-front
+    validation and :class:`_GeneratorStrategy`'s own constructor (so the
+    bridge is safe even if constructed directly, not just via
+    ``run_study``)."""
+    if inspect.isgenerator(study):
+        raise TypeError(
+            "run_study expects the generator FUNCTION itself, not an "
+            "already-started generator -- call run_study(study), not "
+            "run_study(study()). study is a zero-argument callable that "
+            "returns a fresh generator each time it is invoked."
+        )
+
+
+class _GeneratorStrategy:
+    """Bridges a zero-argument generator *factory* (the researcher's
+    ``study`` callable) onto the
+    :class:`~oep.conductor.strategy.TrialStrategy` shape, implementing it
+    structurally (``next_trial``/``update``) -- no inheritance from the
+    ``Protocol`` is required or used.
+
+    - The generator is instantiated **inside the session**, i.e. lazily on
+      the first :meth:`next_trial` call, not in ``__init__`` -- so calling
+      ``run_study`` never runs a byte of the researcher's generator body
+      before a runner has actually connected. Each :func:`run_study` call
+      constructs a fresh ``_GeneratorStrategy``, so a fresh generator (fresh
+      state) results.
+    - **Send contract:** after a trial yield, the next resume sends the
+      ``TrialResult`` captured via :meth:`update`. After a :class:`Break`
+      yield, ``update`` is never called (matching the class-API break
+      lifecycle) -- so the next resume instead sends ``None``, per the
+      spec's break-resume rule.
+    - **Yield validation happens here, at the yield site:** every mapping
+      value the generator yields is passed through
+      :func:`normalize_trial_params` before being returned to
+      ``serve_strategy`` for transmission; a
+      :class:`~oep.conductor.errors.TrialSpecError` propagates straight out
+      of :meth:`next_trial`, which ``serve_strategy`` treats like any other
+      strategy failure (terminal-state "failed": close without ``done``,
+      re-raise).
+    - **Terminal capture:** the generator's ``StopIteration.value`` is
+      captured and exposed via the :meth:`strategy_result` method -- the
+      additive seam :func:`~oep.conductor.server.serve_strategy` looks for
+      (see that module's ``_capture_strategy_result`` helper) to populate
+      ``SessionSummary.strategy_result``. It stays ``None`` if the session
+      never reaches normal completion (failure/connection-loss paths).
+    """
+
+    def __init__(
+        self, study: Optional[Callable[[], Generator[Any, Any, Any]]]
+    ) -> None:
+        _reject_if_already_started(study)
+        if study is None or not callable(study):
+            raise TypeError(
+                "study must be a zero-argument callable returning a generator "
+                f"(a generator FUNCTION), got {study!r}"
+            )
+        self._factory = study
+        self._gen: Optional[Generator[Any, Any, Any]] = None
+        self._started = False
+        self._pending_send: Any = None
+        self._result: Any = None
+
+    def strategy_result(self) -> Any:
+        """The generator's ``StopIteration.value`` (``None`` unless/until
+        the session completes normally) -- the additive seam
+        ``serve_strategy`` reads for ``SessionSummary.strategy_result``."""
+        return self._result
+
+    def next_trial(self) -> TrialParams | Break | None:
+        if self._gen is None:
+            self._gen = self._factory()
+            if not inspect.isgenerator(self._gen):
+                raise TypeError(
+                    "study() must return a generator (study must be a generator "
+                    f"function, i.e. contain a `yield`) -- got "
+                    f"{type(self._gen).__name__!r}"
+                )
+
+        try:
+            if not self._started:
+                self._started = True
+                value = next(self._gen)
+            else:
+                value = self._gen.send(self._pending_send)
+        except StopIteration as stop:
+            self._result = stop.value
+            return None
+
+        if isinstance(value, Break):
+            # update() is never called for a break -- the next resume must
+            # send None, per the spec's break-resume rule.
+            self._pending_send = None
+            return value
+
+        return normalize_trial_params(value)
+
+    def update(self, result: TrialResult) -> None:
+        self._pending_send = result
+
+
+# ---------------------------------------------------------------------------
+# run_study
+# ---------------------------------------------------------------------------
+
+
+def _validate_run_study_kwargs(
+    *,
+    study: Any,
+    ssl_context: Optional[ssl.SSLContext],
+    ssl_cert: str | Path | None,
+    ssl_key: str | Path | None,
+    record_transcript: str | Path | None,
+    replay_transcript: str | Path | None,
+) -> None:
+    """All ``ValueError``/``TypeError`` validation for :func:`run_study`'s
+    kwargs, run before any socket opens."""
+    if record_transcript is not None and replay_transcript is not None:
+        raise ValueError(
+            "record_transcript= and replay_transcript= are mutually exclusive "
+            "-- a session is either recorded or replayed, never both."
+        )
+    if ssl_cert is not None and ssl_key is None:
+        raise ValueError("ssl_cert= requires ssl_key= (they must be supplied together).")
+    if ssl_key is not None and ssl_cert is None:
+        raise ValueError("ssl_key= requires ssl_cert= (they must be supplied together).")
+    if ssl_context is not None and (ssl_cert is not None or ssl_key is not None):
+        raise ValueError(
+            "ssl_context= is mutually exclusive with ssl_cert=/ssl_key= -- pass "
+            "full control via ssl_context=, or the beginner pair, never both."
+        )
+    if study is None and replay_transcript is None:
+        raise TypeError(
+            "run_study(study=None) is legal only together with replay_transcript= "
+            "(replay never executes a study) -- pass a zero-argument generator "
+            "function, e.g. run_study(my_study)."
+        )
+    if study is not None:
+        _reject_if_already_started(study)
+
+
+def _resolve_ssl_context(
+    ssl_context: Optional[ssl.SSLContext],
+    ssl_cert: str | Path | None,
+    ssl_key: str | Path | None,
+) -> Optional[ssl.SSLContext]:
+    """Resolve ``run_study``'s TLS kwargs into a single ``ssl.SSLContext``
+    (or ``None``), per the package design's §run_study: ``ssl_context`` is
+    used verbatim; ``ssl_cert``+``ssl_key`` (already validated as a pair by
+    :func:`_validate_run_study_kwargs`) build a default
+    ``ssl.PROTOCOL_TLS_SERVER`` context via ``load_cert_chain``. Serving
+    with either one flips the logged/summarized scheme to ``wss://`` (see
+    :func:`~oep.conductor.server.serve_strategy`/:func:`~oep.conductor.server.serve_replay`)."""
+    if ssl_context is not None:
+        return ssl_context
+    if ssl_cert is not None and ssl_key is not None:
+        context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        context.load_cert_chain(certfile=str(ssl_cert), keyfile=str(ssl_key))
+        return context
+    return None
+
+
+def run_study(
+    study: Optional[Callable[[], Generator[TrialParams | Break, Optional[TrialResult], Any]]],
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    ssl_context: Optional[ssl.SSLContext] = None,
+    ssl_cert: str | Path | None = None,
+    ssl_key: str | Path | None = None,
+    record_transcript: str | Path | None = None,
+    replay_transcript: str | Path | None = None,
+    logger: Optional[logging.Logger] = None,
+) -> SessionSummary:
+    """Run a researcher's ``study`` generator as one conductor-mastered
+    ``oep-draft-network`` session -- the package's ~15-line hello world
+    (package design §run_study).
+
+    ``study`` is a **zero-argument factory** returning a fresh generator
+    (never an already-started generator -- see the factory-only
+    ``TypeError`` below); it yields :data:`~oep.conductor.strategy.TrialParams`
+    mappings (validated and normalized per :func:`normalize_trial_params`)
+    or a :class:`~oep.conductor.strategy.Break`, and receives back a
+    :class:`~oep.conductor.results.TrialResult` (or ``None``, after a
+    break completes). ``study=None`` is legal ONLY together with
+    ``replay_transcript=`` (replay never executes a study); every other
+    combination with a missing ``study`` is a ``TypeError`` at call time,
+    raised before any socket is opened.
+
+    Kwarg validation (raised before any socket opens): ``record_transcript``/
+    ``replay_transcript`` are mutually exclusive; ``ssl_cert``/``ssl_key``
+    must be supplied together and are mutually exclusive with
+    ``ssl_context`` -- all as ``ValueError``.
+
+    TLS: ``ssl_context``, if given, is used verbatim; ``ssl_cert``+
+    ``ssl_key`` together build a default ``ssl.PROTOCOL_TLS_SERVER`` context
+    (see :func:`_resolve_ssl_context`). Either one serves ``wss://`` instead
+    of ``ws://`` (reflected in the served scheme's logs/summary).
+
+    Replay: ``replay_transcript=`` serves a REAL socket session driven by a
+    canned ``.jsonl`` transcript instead of ``study`` -- see
+    :func:`~oep.conductor.server.serve_replay` for the full contract
+    (package design §Replay contract). Notably this is the one path where
+    ``study=None`` is legal, and it is dispatched before
+    :class:`_GeneratorStrategy` is ever constructed.
+    """
+    _validate_run_study_kwargs(
+        study=study,
+        ssl_context=ssl_context,
+        ssl_cert=ssl_cert,
+        ssl_key=ssl_key,
+        record_transcript=record_transcript,
+        replay_transcript=replay_transcript,
+    )
+
+    resolved_ssl_context = _resolve_ssl_context(ssl_context, ssl_cert, ssl_key)
+
+    if replay_transcript is not None:
+        return asyncio.run(
+            serve_replay(
+                replay_transcript,
+                host=host,
+                port=port,
+                ssl_context=resolved_ssl_context,
+                logger=logger,
+            )
+        )
+
+    strategy = _GeneratorStrategy(study)
+    return asyncio.run(
+        serve_strategy(
+            strategy,
+            host=host,
+            port=port,
+            ssl_context=resolved_ssl_context,
+            record_transcript=record_transcript,
+            logger=logger,
+        )
+    )