raidiantai-analytics 0.1.0__tar.gz

raidiantai_analytics-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- First release: send a tool's usage to Basecamp from a Python server with a tool key.

raidiantai_analytics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raidiant LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

raidiantai_analytics-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: raidiantai-analytics
+Version: 0.1.0
+Summary: Send a tool's usage to Raidiant AI from a Python server, with a tool key.
+Author: Raidiant LLC
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# raidiantai-analytics
+
+Send your tool's usage to Basecamp from a Python server or script, with a tool key.
+
+**Python 3.10 or later. Standard library only; no runtime dependencies. Server
+only:** it sends with a tool key, which is a server-side secret. Versions before
+1.0 may change; see the changelog.
+
+## Install
+
+```bash
+pip install raidiantai-analytics
+```
+
+## Quickstart
+
+You need a tool key and your company's Basecamp address (for example
+`https://<your-basecamp-address>`). This reads them from the environment as
+`BASECAMP_TOOL_KEY` and `BASECAMP_URL`. Use a test key while you build: it is
+checked and answered like a live key, and nothing is counted.
+
+```python
+import os
+
+from raidiantai_analytics import Analytics, CheckKeyOk, Diagnostic, email_identity
+
+
+def show(d: Diagnostic) -> None:
+    print(f"analytics: {d.code}" + (f" ({d.reason})" if d.reason else ""))
+
+
+# One client per process. It never raises: a missing or malformed option
+# makes it send nothing and is reported through on_diagnostic.
+analytics = Analytics(
+    key=os.environ.get("BASECAMP_TOOL_KEY"),
+    base_url=os.environ.get("BASECAMP_URL"),
+    # Without this, most problems would only be counted, not shown.
+    on_diagnostic=show,
+)
+
+# Check the key first, so a wrong, stopped or switched-off key shows up now
+# instead of as usage that never arrives.
+check = analytics.check_key()
+if not isinstance(check, CheckKeyOk):
+    print(f"The key check failed: {check.code}")
+elif check.status != "active" or not check.integrations_enabled:
+    print("The key is stopped, or integrations are off for your company.")
+else:
+    print(f"Sending for {check.tool_name} with a {check.mode} key.")
+
+# Once per meaningful completion of your tool's main job, for the person it was for.
+identity = email_identity("alice@example.com")
+if identity.ok:
+    analytics.for_actor(identity.actor).capture_use()
+
+# Send what is queued. `remaining` is how many events are still waiting.
+result = analytics.flush()
+print(f"{result.remaining} events still queued.")
+
+# This script is about to exit, so shut the client down.
+analytics.shutdown()
+```
+
+- Call `capture_use()` once per meaningful completion of your tool's main job.
+  Use `capture_custom(name, properties=...)` for anything else; it never counts.
+- Pass the `event_id` of your own work (`capture_use(event_id=...)`) when it can
+  repeat: a repeat with the same ID never counts twice.
+- Pass an email your application has verified.
+
+## Sending and shutting down
+
+Events are sent by a background thread, in batches. The thread never keeps the
+interpreter alive.
+
+- `analytics.flush()` sends what is queued and returns a result whose
+  `remaining` is how many events are still queued. `0` means the queue is empty,
+  not that everything arrived (refused or given-up events leave it too; see
+  `get_stats()`). Otherwise it is the number still queued when its deadline passed (10 seconds by default). Those events are not
+  lost; the client keeps trying. In serverless code, call `flush()` before your
+  handler returns.
+- `analytics.shutdown()` belongs **only where the process is about to exit**
+  (or use the client as a context manager, `with Analytics(...) as analytics:`).
+  It stops accepting events, sends what it can for up to 5 seconds, then
+  discards the rest; its `remaining` is how many it discarded. After it, every
+  capture is dropped. The package registers no `atexit` handler of its own.
+
+The queue is in memory, so a restart or crash loses what was still queued.
+
+## Keep the key secret
+
+- The key is a **server-side** secret. Read it from the server's environment or
+  a secret store; never ship it inside an app your users run.
+- **Never commit** it to a repository.
+- If it may have been exposed, **rotate** it at once: cancel it in Basecamp and
+  make a new one.
+
+## Your key and the full guide
+
+Both need a Basecamp sign-in:
+
+- **Your tool key:** your tool's page in Basecamp, on its **Integration** tab.
+- **The full guide:** `https://<your-basecamp-address>/docs/developers/sdk-python`,
+  covering what counts as a use, what can be lost and when, privacy, property
+  values, pausing, the network and every option. For help, start there.
+
+## Licence
+
+MIT. Copyright (c) 2026 Raidiant LLC. See `LICENSE`.

raidiantai_analytics-0.1.0/README.md

@@ -0,0 +1,108 @@
+# raidiantai-analytics
+
+Send your tool's usage to Basecamp from a Python server or script, with a tool key.
+
+**Python 3.10 or later. Standard library only; no runtime dependencies. Server
+only:** it sends with a tool key, which is a server-side secret. Versions before
+1.0 may change; see the changelog.
+
+## Install
+
+```bash
+pip install raidiantai-analytics
+```
+
+## Quickstart
+
+You need a tool key and your company's Basecamp address (for example
+`https://<your-basecamp-address>`). This reads them from the environment as
+`BASECAMP_TOOL_KEY` and `BASECAMP_URL`. Use a test key while you build: it is
+checked and answered like a live key, and nothing is counted.
+
+```python
+import os
+
+from raidiantai_analytics import Analytics, CheckKeyOk, Diagnostic, email_identity
+
+
+def show(d: Diagnostic) -> None:
+    print(f"analytics: {d.code}" + (f" ({d.reason})" if d.reason else ""))
+
+
+# One client per process. It never raises: a missing or malformed option
+# makes it send nothing and is reported through on_diagnostic.
+analytics = Analytics(
+    key=os.environ.get("BASECAMP_TOOL_KEY"),
+    base_url=os.environ.get("BASECAMP_URL"),
+    # Without this, most problems would only be counted, not shown.
+    on_diagnostic=show,
+)
+
+# Check the key first, so a wrong, stopped or switched-off key shows up now
+# instead of as usage that never arrives.
+check = analytics.check_key()
+if not isinstance(check, CheckKeyOk):
+    print(f"The key check failed: {check.code}")
+elif check.status != "active" or not check.integrations_enabled:
+    print("The key is stopped, or integrations are off for your company.")
+else:
+    print(f"Sending for {check.tool_name} with a {check.mode} key.")
+
+# Once per meaningful completion of your tool's main job, for the person it was for.
+identity = email_identity("alice@example.com")
+if identity.ok:
+    analytics.for_actor(identity.actor).capture_use()
+
+# Send what is queued. `remaining` is how many events are still waiting.
+result = analytics.flush()
+print(f"{result.remaining} events still queued.")
+
+# This script is about to exit, so shut the client down.
+analytics.shutdown()
+```
+
+- Call `capture_use()` once per meaningful completion of your tool's main job.
+  Use `capture_custom(name, properties=...)` for anything else; it never counts.
+- Pass the `event_id` of your own work (`capture_use(event_id=...)`) when it can
+  repeat: a repeat with the same ID never counts twice.
+- Pass an email your application has verified.
+
+## Sending and shutting down
+
+Events are sent by a background thread, in batches. The thread never keeps the
+interpreter alive.
+
+- `analytics.flush()` sends what is queued and returns a result whose
+  `remaining` is how many events are still queued. `0` means the queue is empty,
+  not that everything arrived (refused or given-up events leave it too; see
+  `get_stats()`). Otherwise it is the number still queued when its deadline passed (10 seconds by default). Those events are not
+  lost; the client keeps trying. In serverless code, call `flush()` before your
+  handler returns.
+- `analytics.shutdown()` belongs **only where the process is about to exit**
+  (or use the client as a context manager, `with Analytics(...) as analytics:`).
+  It stops accepting events, sends what it can for up to 5 seconds, then
+  discards the rest; its `remaining` is how many it discarded. After it, every
+  capture is dropped. The package registers no `atexit` handler of its own.
+
+The queue is in memory, so a restart or crash loses what was still queued.
+
+## Keep the key secret
+
+- The key is a **server-side** secret. Read it from the server's environment or
+  a secret store; never ship it inside an app your users run.
+- **Never commit** it to a repository.
+- If it may have been exposed, **rotate** it at once: cancel it in Basecamp and
+  make a new one.
+
+## Your key and the full guide
+
+Both need a Basecamp sign-in:
+
+- **Your tool key:** your tool's page in Basecamp, on its **Integration** tab.
+- **The full guide:** `https://<your-basecamp-address>/docs/developers/sdk-python`,
+  covering what counts as a use, what can be lost and when, privacy, property
+  values, pausing, the network and every option. For help, start there.
+
+## Licence
+
+MIT. Copyright (c) 2026 Raidiant LLC. See `LICENSE`.

raidiantai_analytics-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "raidiantai-analytics"
+dynamic = ["version"]
+description = "Send a tool's usage to Raidiant AI from a Python server, with a tool key."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Raidiant LLC" }]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "raidiantai_analytics._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+raidiantai_analytics = ["py.typed"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "UP", "I"]
+ignore = ["B904"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/raidiantai_analytics/_contract.py" = ["E501"]
+# The test suite's directory is written as the glob "test[s]" because this file ships
+# in the sdist, whose public-hygiene check refuses a plain test-directory path.
+"test[s]/**" = ["E501", "B011", "B017"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/raidiantai_analytics"]

raidiantai_analytics-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

raidiantai_analytics-0.1.0/src/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-0.1.0/src/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