intelloptim 0.1.0__py3-none-any.whl

intelloptim/__init__.py

@@ -0,0 +1,51 @@
+"""intelloptim — black-box optimization client, algorithms and wire protocol.
+
+The recommended import alias is::
+
+    import intelloptim as intopt
+
+Ready to use after the import:
+
+- ``intopt.params``: the parameters that define a search space.
+- ``intopt.samplers`` and ``intopt.pruners``: the specs that configure how a
+  study samples and prunes.
+- ``intopt.objective``: decorator that registers an objective, optionally with
+  its study spec, so that ``intelloptim-worker`` can run it.
+
+Loaded on first access:
+
+- ``intopt.client``: the SDK that talks to a server (``Client``, ``Trial``,
+  ``TrialState``, the ``errors``).
+- ``intopt.algorithms``: resolves specs to Optuna samplers and pruners. It is
+  meant for servers and sampler plugins, and running a study does not need it.
+"""
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from intelloptim.core import pruners, samplers
+from intelloptim.core.objective import objective
+from intelloptim.version import __version__
+
+from . import params
+
+if TYPE_CHECKING:
+    from intelloptim import client
+
+_LAZY_SUBMODULES = frozenset({"algorithms", "client"})
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_SUBMODULES:
+        return importlib.import_module(f"{__name__}.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    "client",
+    "objective",
+    "params",
+    "pruners",
+    "samplers",
+]

intelloptim/_internal/__init__.py

@@ -0,0 +1,19 @@
+"""Internal modules shared by the client, the worker and the server.
+
+Nothing here is a public API: names and behaviour can change between releases
+without notice. Import these modules from their own path, for example
+``from intelloptim._internal.schemas import AskRequest``.
+
+Submodules:
+
+* :mod:`~intelloptim._internal.schemas` — request and response models of the
+  REST API, and the protocol version.
+* :mod:`~intelloptim._internal.hashing` — canonical serialisation and the
+  hashes that give studies their identity.
+* :mod:`~intelloptim._internal.logging` — logging configuration under the
+  ``intelloptim`` logger.
+* :mod:`~intelloptim._internal.audit` — audit records of security-relevant
+  events.
+"""
+
+__all__ = ["audit", "hashing", "logging", "schemas"]

intelloptim/_internal/audit.py

@@ -0,0 +1,349 @@
+"""Audit events: a small, stable record of security-relevant actions.
+
+Each function below records one kind of event (a login, a token change, a study
+stopped or rebuilt) as a structured log record on the ``intelloptim.audit``
+logger. Event and field names do not change between releases, so operators can
+filter and alert on them.
+
+Every record carries:
+
+* ``event_category="audit"`` — tells audit records apart from operational ones.
+* ``event`` — short, stable name such as ``"login.success"``,
+  ``"token.issued"`` or ``"study.stopped"``.
+* ``outcome`` — ``"success"`` or ``"failure"``.
+* ``actor`` — who acted: a user id, a token prefix, ``"system"`` for background
+  work or ``"anonymous"``.
+* extra fields specific to the event, such as ``study_id`` or ``reason``.
+
+Records are written to the main log stream, marked with ``event_category=audit``,
+unless ``INTELLOPTIM_AUDIT_FILE`` sends them to a file of their own (see
+:mod:`intelloptim._internal.logging`). Tokens are identified by their prefix
+only, never in full.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Mapping, Optional
+
+from intelloptim._internal.logging import ROOT_LOGGER_NAME, get_logger
+
+_STANDARD_FIELDS = frozenset({"event_category", "event", "outcome", "actor"})
+
+# Names ``extra=`` cannot use: the standard fields above and the attributes of a
+# LogRecord (``logging`` raises ``KeyError`` on those, and ``message`` and
+# ``asctime`` are set by the formatters).
+_RESERVED_FIELDS = (
+    _STANDARD_FIELDS
+    | frozenset(logging.makeLogRecord({}).__dict__)
+    | {"message", "asctime"}
+)
+
+
+def get_audit_logger() -> logging.Logger:
+    """Return the ``intelloptim.audit`` logger, configuring logging if needed.
+
+    Returns:
+        logging.Logger: The logger all audit records are written to.
+    """
+    get_logger("audit")
+    return logging.getLogger(f"{ROOT_LOGGER_NAME}.audit")
+
+
+def emit(
+    event: str,
+    *,
+    outcome: str,
+    actor: Optional[str] = None,
+    extra: Optional[Mapping[str, Any]] = None,
+    message: Optional[str] = None,
+    level: int = logging.INFO,
+) -> None:
+    """Write one audit record.
+
+    The functions below call this with the right event name and fields; call it
+    directly only for an event they do not cover.
+
+    Args:
+        event (str): Short stable name, for example ``"login.success"``. Dots
+            group related events.
+        outcome (str): ``"success"`` or ``"failure"``.
+        actor (Optional[str]): Who acted: a user id or a token prefix.
+            ``None`` means ``"anonymous"``.
+        extra (Optional[Mapping[str, Any]]): Additional structured fields, for
+            example ``{"study_id": "..."}``. They are merged into the record
+            and must not reuse the names of the standard fields or of
+            :class:`logging.LogRecord` attributes.
+        message (Optional[str]): Human-readable summary; defaults to *event*.
+        level (int): Log level. Use :data:`logging.WARNING` for failures and
+            suspicious activity.
+
+    Raises:
+        ValueError: If *extra* uses a reserved field name. Nothing is logged.
+    """
+    if extra:
+        clashes = sorted(_RESERVED_FIELDS & set(extra))
+        if clashes:
+            raise ValueError(
+                f"audit extra fields use reserved names: {', '.join(clashes)}"
+            )
+    payload: Dict[str, Any] = {
+        "event_category": "audit",
+        "event": event,
+        "outcome": outcome,
+        "actor": actor or "anonymous",
+    }
+    if extra:
+        payload.update(extra)
+    get_audit_logger().log(level, message or event, extra=payload)
+
+
+def login_success(*, user_id: str, email: str) -> None:
+    """Record a successful login (event ``login.success``).
+
+    Args:
+        user_id (str): Id of the user who logged in; becomes the actor.
+        email (str): Email the user logged in with.
+    """
+    emit("login.success", outcome="success", actor=user_id, extra={"email": email})
+
+
+def login_failure(*, email: str, reason: str) -> None:
+    """Record a failed login (event ``login.failure``, level ``WARNING``).
+
+    Args:
+        email (str): Email the attempt used. The actor is ``"anonymous"``, since
+            the user is not authenticated.
+        reason (str): Why the login failed, for example ``"invalid-credentials"``.
+    """
+    emit(
+        "login.failure",
+        outcome="failure",
+        actor="anonymous",
+        extra={"email": email, "reason": reason},
+        level=logging.WARNING,
+    )
+
+
+def logout(*, user_id: str) -> None:
+    """Record a logout (event ``logout``).
+
+    Args:
+        user_id (str): Id of the user who logged out; becomes the actor.
+    """
+    emit("logout", outcome="success", actor=user_id)
+
+
+def token_issued(*, user_id: str, token_prefix: str, name: str) -> None:
+    """Record the creation of an API token (event ``token.issued``).
+
+    Args:
+        user_id (str): Id of the user who owns the token; becomes the actor.
+        token_prefix (str): First characters of the token, enough to identify it
+            in a log. Never pass the full token.
+        name (str): Label the user gave the token.
+    """
+    emit(
+        "token.issued",
+        outcome="success",
+        actor=user_id,
+        extra={"token_prefix": token_prefix, "token_name": name},
+    )
+
+
+def token_revoked(*, user_id: str, token_prefix: str) -> None:
+    """Record that an API token was revoked (event ``token.revoked``).
+
+    Args:
+        user_id (str): Id of the user who owns the token; becomes the actor.
+        token_prefix (str): Prefix identifying the token. Never pass the full
+            token.
+    """
+    emit(
+        "token.revoked",
+        outcome="success",
+        actor=user_id,
+        extra={"token_prefix": token_prefix},
+    )
+
+
+def token_deleted(*, user_id: str, token_prefix: str) -> None:
+    """Record that an API token was deleted (event ``token.deleted``).
+
+    Args:
+        user_id (str): Id of the user who owns the token; becomes the actor.
+        token_prefix (str): Prefix identifying the token. Never pass the full
+            token.
+    """
+    emit(
+        "token.deleted",
+        outcome="success",
+        actor=user_id,
+        extra={"token_prefix": token_prefix},
+    )
+
+
+def token_authentication_failure(*, prefix: str, reason: str) -> None:
+    """Record a request rejected for its token (event ``token.auth_failed``).
+
+    The record has level ``WARNING``.
+
+    Args:
+        prefix (str): Prefix of the token that was presented. The actor is
+            ``"prefix:<prefix>"``, or ``"anonymous"`` if the prefix is empty.
+        reason (str): Why authentication failed, for example ``"invalid-or-revoked"``.
+    """
+    emit(
+        "token.auth_failed",
+        outcome="failure",
+        actor=f"prefix:{prefix}" if prefix else "anonymous",
+        extra={"reason": reason},
+        level=logging.WARNING,
+    )
+
+
+def study_created(*, study_id: str, user_id: str, name: str) -> None:
+    """Record the creation of a study (event ``study.created``).
+
+    Args:
+        study_id (str): Id of the new study.
+        user_id (str): Id of the user who created it; becomes the actor.
+        name (str): Study name, stored in the record as ``study_name``.
+    """
+    emit(
+        "study.created",
+        outcome="success",
+        actor=user_id,
+        extra={"study_id": study_id, "study_name": name},
+    )
+
+
+def study_stopped(*, study_id: str, user_id: str) -> None:
+    """Record that a study was stopped (event ``study.stopped``).
+
+    Args:
+        study_id (str): Id of the stopped study.
+        user_id (str): Id of the user who stopped it; becomes the actor.
+    """
+    emit(
+        "study.stopped",
+        outcome="success",
+        actor=user_id,
+        extra={"study_id": study_id},
+    )
+
+
+def trial_enqueued(*, study_id: str, user_id: str, trial_number: int) -> None:
+    """Record a trial injected with a known result (event ``trial.enqueued``).
+
+    Only trials added together with an objective value are recorded: they enter
+    the study as completed and shape what the sampler learns. The value and the
+    parameters are not part of the record.
+
+    Args:
+        study_id (str): Id of the study that received the trial.
+        user_id (str): Id of the user who injected it; becomes the actor.
+        trial_number (int): Zero-based position of the new trial in the study.
+    """
+    emit(
+        "trial.enqueued",
+        outcome="success",
+        actor=user_id,
+        extra={"study_id": study_id, "trial_number": trial_number},
+    )
+
+
+def quota_exhausted(*, user_id: str, calls_per_month: int, refused: int = 1) -> None:
+    """Record calls refused because the monthly quota is used up.
+
+    The event is ``quota.exhausted``, with outcome ``failure`` and level
+    ``WARNING``. A client that keeps retrying makes many refusals, so the caller
+    may log one record for several of them and report their number in *refused*.
+
+    Args:
+        user_id (str): Id of the user whose quota is exhausted; becomes the
+            actor.
+        calls_per_month (int): The user's effective monthly limit.
+        refused (int): Number of refused calls this record stands for.
+    """
+    emit(
+        "quota.exhausted",
+        outcome="failure",
+        actor=user_id,
+        extra={"calls_per_month": calls_per_month, "refused": refused},
+        level=logging.WARNING,
+    )
+
+
+def study_access_denied(*, study_id: str, user_id: str, action: str) -> None:
+    """Record a request for a study that belongs to someone else.
+
+    The event is ``study.access_denied``, with outcome ``failure`` and level
+    ``WARNING``. The caller answers 404 as if the study did not exist, so this
+    record is the only trace that the study does exist.
+
+    Args:
+        study_id (str): Id of the study that was requested.
+        user_id (str): Id of the user who asked; becomes the actor.
+        action (str): What was attempted: ``"read"``, ``"stop"``, ``"delete"``
+            or ``"rebuild"``.
+    """
+    emit(
+        "study.access_denied",
+        outcome="failure",
+        actor=user_id,
+        extra={"study_id": study_id, "action": action},
+        level=logging.WARNING,
+    )
+
+
+def study_rebuild_started(*, study_id: str, user_id: Optional[str] = None) -> None:
+    """Record the start of a sampler rebuild (event ``study.rebuild.started``).
+
+    Args:
+        study_id (str): Id of the study being rebuilt.
+        user_id (Optional[str]): Id of the user who triggered the rebuild, or
+            ``None`` if the server started it, in which case the actor is
+            ``"system"``.
+    """
+    emit(
+        "study.rebuild.started",
+        outcome="success",
+        actor=user_id or "system",
+        extra={"study_id": study_id},
+    )
+
+
+def study_rebuild_finished(*, study_id: str, user_id: Optional[str] = None) -> None:
+    """Record the end of a sampler rebuild (event ``study.rebuild.finished``).
+
+    Args:
+        study_id (str): Id of the rebuilt study.
+        user_id (Optional[str]): Id of the user who triggered the rebuild, or
+            ``None`` if the server started it, in which case the actor is
+            ``"system"``.
+    """
+    emit(
+        "study.rebuild.finished",
+        outcome="success",
+        actor=user_id or "system",
+        extra={"study_id": study_id},
+    )
+
+
+__all__ = [
+    "login_failure",
+    "login_success",
+    "logout",
+    "quota_exhausted",
+    "study_access_denied",
+    "study_created",
+    "study_rebuild_finished",
+    "study_rebuild_started",
+    "study_stopped",
+    "token_authentication_failure",
+    "token_deleted",
+    "token_issued",
+    "token_revoked",
+    "trial_enqueued",
+]

intelloptim/_internal/hashing.py

@@ -0,0 +1,255 @@
+"""Canonical serialisation and hashing that give studies their identity.
+
+A study is content-addressed: its id is the SHA-256 of a canonical string built
+from the owner's key, the study name and the full study configuration. Equal
+inputs give equal ids in every process, so independent clients that submit the
+same configuration land on the same study.
+
+The owner key (``study_key``) is an opaque, stable identifier of a user or a
+group, never the API token itself; the server resolves it from the token. The
+SDK only computes :func:`config_digest`, the same hash without key and name,
+which it sends with every request so the server can detect a configuration that
+differs between clients.
+
+The output is identical across Python versions, operating systems and CPU
+architectures.
+
+Canonical form:
+
+* Dict keys are sorted lexicographically at every depth.
+* Sequences keep their declared order (parameter order is meaningful).
+* Floats are written with :func:`repr` (shortest round-trippable form), so
+  ``1`` and ``1.0`` hash differently.
+* No whitespace and no trailing newline; the output is ASCII only.
+* ``NaN`` and infinities are rejected: they have no useful meaning in a study.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from typing import TYPE_CHECKING, Any, Mapping, Sequence, Tuple
+
+if TYPE_CHECKING:
+    from intelloptim._internal.schemas import StudyResolveRequest
+
+_HASH_PREFIX = "suid:"
+
+
+def canonicalize(value: Any) -> str:
+    """Serialise *value* to its canonical string.
+
+    The result is valid JSON: dict keys are sorted, non-ASCII characters are
+    escaped as ``\\uXXXX`` and lists and tuples give the same output.
+
+    Args:
+        value (Any): A composition of ``None``, ``bool``, ``int``, ``float``,
+            ``str``, ``list``/``tuple`` and mappings with ``str`` keys. Convert
+            pydantic models with ``model_dump(mode="json")`` first.
+
+    Returns:
+        str: The canonical string: ASCII only, no whitespace.
+
+    Raises:
+        TypeError: If *value* contains an unsupported type, for example a
+            ``set``, ``bytes`` or a custom object.
+        ValueError: If a ``float`` is ``NaN`` or infinite, or a mapping has a
+            non-``str`` key.
+    """
+    return _emit(value)
+
+
+def study_id(
+    study_key: str,
+    study_name: str,
+    direction: str,
+    parameters: Sequence[Mapping[str, Any]],
+    sampler_spec: Mapping[str, Any],
+    pruner_spec: Mapping[str, Any],
+) -> str:
+    """Compute the content-addressed id of a study.
+
+    Callers that submit equivalent specifications with the same ``study_key``
+    get the same id. Any difference in the name, direction, parameters, sampler
+    or pruner, or a different key, gives a different id. The key keeps the
+    studies of different users and groups apart without putting the API token in
+    the hash. :func:`study_identity` computes this id, and the digest, directly
+    from a resolve request.
+
+    Args:
+        study_key (str): Opaque key (UUID4 hex) of the calling user or group,
+            resolved by the server; never the raw API token.
+        study_name (str): Human-readable study name.
+        direction (str): ``"minimize"`` or ``"maximize"``.
+        parameters (Sequence[Mapping[str, Any]]): Declared search space as
+            parameter dicts in declared order, each with a ``kind`` field.
+        sampler_spec (Mapping[str, Any]): Sampler spec dict (``kind`` plus its
+            settings).
+        pruner_spec (Mapping[str, Any]): Pruner spec dict (``kind`` plus its
+            settings).
+
+    Returns:
+        str: ``"suid:"`` followed by 64 hex characters (69 in total).
+    """
+    # Key names and values are hashed: renaming one changes every study id.
+    payload = {
+        "study_key": study_key,
+        "study_name": study_name,
+        "direction": direction,
+        "parameters": list(parameters),
+        "sampler_spec": dict(sampler_spec),
+        "pruner_spec": dict(pruner_spec),
+    }
+    return _digest(canonicalize(payload))
+
+
+def config_digest(
+    direction: str,
+    parameters: Sequence[Mapping[str, Any]],
+    sampler_spec: Mapping[str, Any],
+    pruner_spec: Mapping[str, Any],
+) -> str:
+    """Compute the digest of a study configuration, without owner or name.
+
+    Clients send it with every study request. The server compares it with the
+    digest of the stored configuration and answers ``409 Conflict`` on a
+    mismatch, which catches two clients that think they share a study but hold
+    different configurations. It hashes the same fields as :func:`study_id`
+    minus ``study_key`` and ``study_name``, so it is the same for every owner.
+
+    Args:
+        direction (str): ``"minimize"`` or ``"maximize"``.
+        parameters (Sequence[Mapping[str, Any]]): Declared search space as
+            parameter dicts in declared order.
+        sampler_spec (Mapping[str, Any]): Sampler spec dict (``kind`` plus its
+            settings).
+        pruner_spec (Mapping[str, Any]): Pruner spec dict (``kind`` plus its
+            settings).
+
+    Returns:
+        str: ``"suid:"`` followed by 64 hex characters.
+    """
+    # Key names and values are hashed: renaming one changes every digest.
+    payload = {
+        "direction": direction,
+        "parameters": list(parameters),
+        "sampler_spec": dict(sampler_spec),
+        "pruner_spec": dict(pruner_spec),
+    }
+    return _digest(canonicalize(payload))
+
+
+def study_identity(study_key: str, request: "StudyResolveRequest") -> Tuple[str, str]:
+    """Compute ``(study_id, config_digest)`` from a resolve request.
+
+    The specs are serialised with ``model_dump(mode="json")``, so default values
+    such as ``log=False`` are part of the hash and a spec that relies on a
+    default gets the same id as one that sets it explicitly.
+
+    Args:
+        study_key (str): Opaque key of the calling user or group, resolved by
+            the server from the bearer token; never the raw token.
+        request (StudyResolveRequest): The resolve request, or any object with
+            the same fields.
+
+    Returns:
+        Tuple[str, str]: ``(study_id, config_digest)``. Only the id depends on
+        ``study_key`` and the study name.
+    """
+    parameters = [p.model_dump(mode="json") for p in request.parameters]
+    direction = request.direction
+    sampler_spec = request.sampler_spec.model_dump(mode="json")
+    pruner_spec = request.pruner_spec.model_dump(mode="json")
+    suid = study_id(
+        study_key=study_key,
+        study_name=request.study_name,
+        direction=direction,
+        parameters=parameters,
+        sampler_spec=sampler_spec,
+        pruner_spec=pruner_spec,
+    )
+    digest = config_digest(
+        direction=direction,
+        parameters=parameters,
+        sampler_spec=sampler_spec,
+        pruner_spec=pruner_spec,
+    )
+    return suid, digest
+
+
+def _digest(canonical: str) -> str:
+    """Return ``"suid:"`` plus the SHA-256 hex digest of a canonical string."""
+    h = hashlib.sha256(canonical.encode("ascii")).hexdigest()
+    return f"{_HASH_PREFIX}{h}"
+
+
+def _emit(value: Any) -> str:
+    """Serialise one value recursively; see :func:`canonicalize`."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise ValueError(
+                "NaN and infinite floats are not allowed in canonical form"
+            )
+        return repr(value)
+    if isinstance(value, str):
+        return _emit_string(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_emit(v) for v in value) + "]"
+    if isinstance(value, Mapping):
+        items: list[tuple[str, Any]] = []
+        for k, v in value.items():
+            if not isinstance(k, str):
+                raise ValueError(
+                    f"dict keys must be str, got {type(k).__name__}: {k!r}"
+                )
+            items.append((k, v))
+        items.sort(key=lambda kv: kv[0])
+        body = ",".join(f"{_emit_string(k)}:{_emit(v)}" for k, v in items)
+        return "{" + body + "}"
+    raise TypeError(f"unsupported type for canonicalization: {type(value).__name__}")
+
+
+def _emit_string(value: str) -> str:
+    """Quote *value* and escape it to printable ASCII.
+
+    Quote, backslash and the usual control characters use their short escapes;
+    every other character outside ``0x20``-``0x7E`` becomes ``\\uXXXX``, and
+    characters above ``U+FFFF`` a surrogate pair, as in JSON.
+    """
+    out = ['"']
+    for ch in value:
+        code = ord(ch)
+        if ch == '"':
+            out.append('\\"')
+        elif ch == "\\":
+            out.append("\\\\")
+        elif ch == "\b":
+            out.append("\\b")
+        elif ch == "\f":
+            out.append("\\f")
+        elif ch == "\n":
+            out.append("\\n")
+        elif ch == "\r":
+            out.append("\\r")
+        elif ch == "\t":
+            out.append("\\t")
+        elif code > 0xFFFF:
+            offset = code - 0x10000
+            high = 0xD800 + (offset >> 10)
+            low = 0xDC00 + (offset & 0x3FF)
+            out.append(f"\\u{high:04x}\\u{low:04x}")
+        elif code < 0x20 or code > 0x7E:
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+__all__ = ["config_digest", "study_identity"]