raidiantai-analytics 0.1.0__py3-none-any.whl

raidiantai_analytics/__init__.py

@@ -0,0 +1,42 @@
+"""Send a tool's usage to Raidiant AI from a Python server, with a tool key.
+
+Standard library only. Python 3.10 or later.
+"""
+
+from ._client import (
+    ActorHandle,
+    Analytics,
+    CaptureDropped,
+    CaptureInvalid,
+    CaptureQueued,
+    CaptureResult,
+    CheckKeyFailed,
+    CheckKeyOk,
+    CheckKeyResult,
+    DrainResult,
+    Stats,
+)
+from ._diagnostics import Diagnostic
+from ._identity import Actor, IdentityOk, IdentityRefused, email_identity
+from ._version import PACKAGE_NAME, __version__
+
+__all__ = [
+    "PACKAGE_NAME",
+    "Actor",
+    "ActorHandle",
+    "Analytics",
+    "CaptureDropped",
+    "CaptureInvalid",
+    "CaptureQueued",
+    "CaptureResult",
+    "CheckKeyFailed",
+    "CheckKeyOk",
+    "CheckKeyResult",
+    "Diagnostic",
+    "DrainResult",
+    "IdentityOk",
+    "IdentityRefused",
+    "Stats",
+    "__version__",
+    "email_identity",
+]

raidiantai_analytics/_admission.py

@@ -0,0 +1,218 @@
+"""Host admission: may this host value become wire text at all?
+
+One iterative traversal that copies the host's value into a snapshot (each
+member read once, through the base type's own methods, so no method a host
+subclass overrides runs), admitting exactly None, bool, an int (not bool) with
+|n| <= 2^53, a finite float, a str with no high-then-low surrogate pair, a
+list or tuple, and a dict whose keys are all str. int, float and str
+subclasses are admitted and copied as their base type. Everything else is
+refused as `invalid_event` at its path. Two representability limits apply
+during the same walk: nesting depth (the event is depth 1) and a running size
+count L, a strict lower bound on the canonical text's UTF-8 bytes, refused as
+`event_too_large` at "" once it passes the ceiling.
+
+L accounting, in traversal order (pre-order, an object's key visited just
+before its member, members in ECMAScript key order): every value adds 1, plus
+its code points if it is a str; a container adds its member count when it is
+entered, before any of its members are read; every key adds its code points.
+Inside one value the checks run: size, then type, then depth, then the member
+count. The snapshot holds only exact types, its dicts already in ECMAScript
+key order.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from . import _text
+from ._contract import CONTRACT
+
+ADMISSION_SIZE_CEILING: int = CONTRACT["sdk_limits"]["ADMISSION_SIZE_CEILING"]
+ADMISSION_DEPTH_CEILING: int = CONTRACT["sdk_limits"]["ADMISSION_DEPTH_CEILING"]
+_MAX_SAFE = 2**53
+
+
+@dataclass(frozen=True)
+class AdmissionRefusal:
+    reason: str  # "invalid_event" | "event_too_large"
+    path: str
+
+
+@dataclass(frozen=True)
+class Admitted:
+    value: Any
+    count: int
+
+
+@dataclass(frozen=True)
+class Refused:
+    refusal: AdmissionRefusal
+    count: int
+
+
+class _Probe:
+    """The most recent traversal's final count, for tests that measure where the walk stopped."""
+
+    last_count = 0
+    strings_scanned = 0
+
+
+admission_probe = _Probe()
+
+# Work items. ("value", value, path, depth, setter); ("key", key); setter writes the copy.
+_VALUE = 0
+_KEY = 1
+
+
+def admit(root: Any) -> Admitted | Refused:
+    """Admit and snapshot `root` (the whole event). Never recurses and never calls host code."""
+    count = 0
+    ceiling = ADMISSION_SIZE_CEILING
+    holder: list[Any] = [None]
+
+    def set_root(x: Any) -> None:
+        holder[0] = x
+
+    stack: list[tuple[Any, ...]] = [(_VALUE, root, "", 1, set_root)]
+
+    def too_large() -> Refused:
+        admission_probe.last_count = count
+        return Refused(AdmissionRefusal("event_too_large", ""), count)
+
+    def invalid(path: str) -> Refused:
+        admission_probe.last_count = count
+        return Refused(AdmissionRefusal("invalid_event", path), count)
+
+    while stack:
+        item = stack.pop()
+        if item[0] == _KEY:
+            # A key that is not a str, or a str holding a surrogate pair, is the
+            # holding object's fault: its path is the holder's.
+            _, k, holder_path = item
+            if k is _NOT_A_STR:
+                return invalid(holder_path)
+            n = len(k)
+            if n > ceiling - count:
+                count = ceiling + 1
+                return too_large()
+            count += n
+            admission_probe.strings_scanned += 1
+            if _text.has_surrogate_pair(k):
+                return invalid(holder_path)
+            continue
+
+        _, v, path, depth, setter = item
+        t = type(v)
+
+        # 1. Size.
+        count += 1
+        is_str = issubclass(t, str)
+        if is_str:
+            n = str.__len__(v)
+            if n > ceiling - count:
+                # Counted only up to one past the ceiling: the verdict is the same.
+                count = ceiling + 1
+                return too_large()
+            count += n
+        if count > ceiling:
+            return too_large()
+
+        # 2. Type.
+        if v is None or t is bool:
+            setter(v)
+            continue
+        if is_str:
+            s = v if t is str else str.__str__(v)
+            admission_probe.strings_scanned += 1
+            if _text.has_surrogate_pair(s):
+                return invalid(path)
+            setter(s)
+            continue
+        if issubclass(t, int):
+            i = v if t is int else int.__int__(v)
+            if i > _MAX_SAFE or i < -_MAX_SAFE:
+                return invalid(path)
+            setter(i)
+            continue
+        if issubclass(t, float):
+            f = v if t is float else float.__float__(v)
+            if not math.isfinite(f):
+                return invalid(path)
+            setter(f)
+            continue
+
+        is_list = issubclass(t, list)
+        if is_list or issubclass(t, tuple):
+            # 3. Depth.
+            if depth > ADMISSION_DEPTH_CEILING:
+                return invalid(path)
+            # 4. Member count, on entry.
+            length = list.__len__(v) if is_list else tuple.__len__(v)
+            count += length
+            if count > ceiling:
+                return too_large()
+            members = list.copy(v) if is_list else list(tuple.__iter__(v))
+            copy: list[Any] = [None] * len(members)
+            setter(copy)
+            for i in range(len(members) - 1, -1, -1):
+                stack.append((_VALUE, members[i], _text.child_path(path, i), depth + 1, _list_setter(copy, i)))
+            continue
+
+        if issubclass(t, dict):
+            if depth > ADMISSION_DEPTH_CEILING:
+                return invalid(path)
+            length = dict.__len__(v)
+            count += length
+            if count > ceiling:
+                return too_large()
+            pairs = [(_key_name(k), m) for k, m in dict.items(v)]
+            ordered = _text._es_key_order(pairs, name=lambda p: p[0])
+            obj: dict[str, Any] = {}
+            setter(obj)
+            for i in range(len(ordered) - 1, -1, -1):
+                k, m = ordered[i]
+                member_path = path if k is _NOT_A_STR else _text.child_path(path, k)
+                stack.append((_VALUE, m, member_path, depth + 1, _dict_setter(obj, k)))
+                stack.append((_KEY, k, path))
+            continue
+
+        return invalid(path)
+
+    admission_probe.last_count = count
+    return Admitted(holder[0], count)
+
+
+class _NotAStr:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<not a str>"
+
+
+_NOT_A_STR: Any = _NotAStr()
+
+
+def _key_name(k: Any) -> Any:
+    t = type(k)
+    if t is str:
+        return k
+    if issubclass(t, str):
+        return str.__str__(k)
+    return _NOT_A_STR
+
+
+def _list_setter(copy: list[Any], i: int) -> Any:
+    def set_item(x: Any) -> None:
+        copy[i] = x
+
+    return set_item
+
+
+def _dict_setter(obj: dict[str, Any], k: Any) -> Any:
+    def set_member(x: Any) -> None:
+        if k is not _NOT_A_STR:
+            obj[k] = x
+
+    return set_member