reliamesh-sdk 0.1.0__tar.gz

reliamesh_sdk-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

reliamesh_sdk-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+ReliaMesh Python SDK
+Copyright 2026 Prefiler Labs Private Limited
+
+Licensed under the Apache License, Version 2.0.

reliamesh_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: reliamesh-sdk
+Version: 0.1.0
+Summary: Content-minimizing reliability events for AI agents
+Author: Prefiler Labs Private Limited
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/PrefilerLabs/reliamesh
+Project-URL: Repository, https://github.com/PrefilerLabs/reliamesh
+Project-URL: Issues, https://github.com/PrefilerLabs/reliamesh/issues
+Project-URL: Documentation, https://github.com/PrefilerLabs/reliamesh/blob/main/sdk/python/README.md
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# ReliaMesh Python SDK
+
+Content-minimizing reliability events for AI agents. Python 3.12+, no runtime
+dependencies. Owned by Prefiler Labs Private Limited; Apache-2.0.
+
+For a published release, install from PyPI:
+
+```sh
+python -m pip install reliamesh-sdk==0.1.0
+```
+
+Or install from this source checkout:
+
+```sh
+python -m pip install ./sdk/python
+```
+
+```python
+import os
+from reliamesh_sdk import Client, event
+
+client = Client(
+    endpoint=os.environ["RELIAMESH_ENDPOINT"],
+    api_key=os.environ["RELIAMESH_API_KEY"],
+)
+client.emit(event(
+    deployment_id="production-eu1", agent_id="invoice-agent",
+    operation="validation", outcome="failure",
+    failure_type="malformed_output", model="model-alias", prompt_version="v3",
+    latency_ms=140, input_tokens=80, output_tokens=30,
+))
+client.flush()
+```
+
+Use opaque stable identifiers; never put customer content, secrets, email
+addresses, or raw prompts in identifier fields. The schema restricts shape, not
+meaning. Hashing predictable personal data does not make it safe.
+
+## Observe execution
+
+```python
+with client.observe(deployment_id="production-eu1", agent_id="invoice-agent",
+                    operation="tool", tool="document-validator", tool_version="2"):
+    run_tool()  # Your application function; return values are never inspected.
+client.flush()
+```
+
+The context manager records elapsed time, success or failure, and a generic
+exception classification. It never reads the exception message or stack. Original
+application exceptions propagate. A timeout is classified as `timeout`; other
+exceptions use the operation's generic failure type. Application validation must
+emit explicit events for malformed output, loops, fallback, retry escalation, or
+incomplete tasks. A successful HTTP call cannot establish task success.
+
+## Delivery contract
+
+- No default endpoint, network discovery, background thread, automatic exporter,
+  exit hook, or outbound telemetry. `emit` and `observe` enqueue locally;
+  `flush`, `summary`, and `incidents` initiate requests to your chosen endpoint.
+- Endpoints require HTTPS, except loopback HTTP for local use. Redirects are
+  rejected. TLS uses Python's normal certificate validation.
+- Default queue capacity: 1,000 events, at most 100 events and 128 KiB per request. Queue capacity is
+  configurable from 1 to 10,000. The queue lives only in memory.
+- Default socket timeout: 2 seconds, configurable up to 30 seconds. This bounds
+  individual socket operations, not the entire flush. Flush processes only the
+  number of events queued at entry, so concurrent producers cannot extend it
+  indefinitely.
+- Only HTTP 429 and 503 retry, up to two retries by default (maximum three).
+  Exponential delays are bounded to one second. Retry bodies and event IDs are
+  identical so the server can deduplicate them. Transport errors and other
+  statuses are not retried. The client verifies ingestion acknowledgement counts.
+- Default `failure_mode="drop"` drops invalid, overflowing, or unsuccessfully sent
+  events. `failure_mode="raise"` raises `SDKError`/`DeliveryError`. An attempted
+  failed batch is dropped in either mode. Raise mode leaves later batches queued.
+- Read `client.counters`: `enqueued`, `sent`, `dropped`, `failed_batches`,
+  `retries`, and `queued`. `sent` counts acknowledged input events, including
+  deduplicated events. Errors omit response bodies and credentials.
+- `summary()` and `incidents()` return decoded authenticated API responses;
+  read failures always raise `DeliveryError`.
+
+This is best-effort instrumentation, not durable message delivery. Export on a
+dedicated application worker or with `await asyncio.to_thread(client.flush)` in
+async applications. Do not call synchronous `flush()` on a latency-sensitive event
+loop. In-process queuing and counters are thread-safe; forked processes need their
+own client. Drain on a controlled shutdown if losing queued observations matters.
+
+## OpenTelemetry adapter
+
+`from_otel_attributes(attributes, deployment_id=..., agent_id=..., outcome=...)`
+constructs an event without exporting it or installing span processors. It maps
+selected standard names from the [OpenTelemetry GenAI attribute registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/):
+
+| Input | Event field |
+| --- | --- |
+| `gen_ai.provider.name` | `provider` |
+| `gen_ai.request.model` | `model` |
+| `gen_ai.usage.input_tokens` / `output_tokens` | `input_tokens` / `output_tokens` |
+| `telemetry.sdk.name` / `version` | `sdk` / `sdk_version` |
+| `gen_ai.operation.name` | `operation`, via the fixed map below |
+
+`chat`, `text_completion`, `generate_content`, and `embeddings` map to `model`;
+`invoke_agent` maps to `agent`; `execute_tool` maps to `tool`. Unknown operations
+require an explicit application mapping and raise `ValueError`.
+
+ReliaMesh-specific extensions `reliamesh.model.version`, `reliamesh.prompt.version`,
+`reliamesh.agent.version`, `reliamesh.framework.name`, `reliamesh.framework.version`,
+`reliamesh.tool.name`, and `reliamesh.tool.version` map to the corresponding flat
+event fields. These extensions are not official OpenTelemetry conventions.
+The caller explicitly supplies outcome, failure type, duration, and synthetic
+status. All unlisted attributes, messages, exception details, and span events are
+ignored. Invalid allowlisted values are rejected. Never pass prompt text as a
+version identifier.

reliamesh_sdk-0.1.0/README.md

@@ -0,0 +1,112 @@
+# ReliaMesh Python SDK
+
+Content-minimizing reliability events for AI agents. Python 3.12+, no runtime
+dependencies. Owned by Prefiler Labs Private Limited; Apache-2.0.
+
+For a published release, install from PyPI:
+
+```sh
+python -m pip install reliamesh-sdk==0.1.0
+```
+
+Or install from this source checkout:
+
+```sh
+python -m pip install ./sdk/python
+```
+
+```python
+import os
+from reliamesh_sdk import Client, event
+
+client = Client(
+    endpoint=os.environ["RELIAMESH_ENDPOINT"],
+    api_key=os.environ["RELIAMESH_API_KEY"],
+)
+client.emit(event(
+    deployment_id="production-eu1", agent_id="invoice-agent",
+    operation="validation", outcome="failure",
+    failure_type="malformed_output", model="model-alias", prompt_version="v3",
+    latency_ms=140, input_tokens=80, output_tokens=30,
+))
+client.flush()
+```
+
+Use opaque stable identifiers; never put customer content, secrets, email
+addresses, or raw prompts in identifier fields. The schema restricts shape, not
+meaning. Hashing predictable personal data does not make it safe.
+
+## Observe execution
+
+```python
+with client.observe(deployment_id="production-eu1", agent_id="invoice-agent",
+                    operation="tool", tool="document-validator", tool_version="2"):
+    run_tool()  # Your application function; return values are never inspected.
+client.flush()
+```
+
+The context manager records elapsed time, success or failure, and a generic
+exception classification. It never reads the exception message or stack. Original
+application exceptions propagate. A timeout is classified as `timeout`; other
+exceptions use the operation's generic failure type. Application validation must
+emit explicit events for malformed output, loops, fallback, retry escalation, or
+incomplete tasks. A successful HTTP call cannot establish task success.
+
+## Delivery contract
+
+- No default endpoint, network discovery, background thread, automatic exporter,
+  exit hook, or outbound telemetry. `emit` and `observe` enqueue locally;
+  `flush`, `summary`, and `incidents` initiate requests to your chosen endpoint.
+- Endpoints require HTTPS, except loopback HTTP for local use. Redirects are
+  rejected. TLS uses Python's normal certificate validation.
+- Default queue capacity: 1,000 events, at most 100 events and 128 KiB per request. Queue capacity is
+  configurable from 1 to 10,000. The queue lives only in memory.
+- Default socket timeout: 2 seconds, configurable up to 30 seconds. This bounds
+  individual socket operations, not the entire flush. Flush processes only the
+  number of events queued at entry, so concurrent producers cannot extend it
+  indefinitely.
+- Only HTTP 429 and 503 retry, up to two retries by default (maximum three).
+  Exponential delays are bounded to one second. Retry bodies and event IDs are
+  identical so the server can deduplicate them. Transport errors and other
+  statuses are not retried. The client verifies ingestion acknowledgement counts.
+- Default `failure_mode="drop"` drops invalid, overflowing, or unsuccessfully sent
+  events. `failure_mode="raise"` raises `SDKError`/`DeliveryError`. An attempted
+  failed batch is dropped in either mode. Raise mode leaves later batches queued.
+- Read `client.counters`: `enqueued`, `sent`, `dropped`, `failed_batches`,
+  `retries`, and `queued`. `sent` counts acknowledged input events, including
+  deduplicated events. Errors omit response bodies and credentials.
+- `summary()` and `incidents()` return decoded authenticated API responses;
+  read failures always raise `DeliveryError`.
+
+This is best-effort instrumentation, not durable message delivery. Export on a
+dedicated application worker or with `await asyncio.to_thread(client.flush)` in
+async applications. Do not call synchronous `flush()` on a latency-sensitive event
+loop. In-process queuing and counters are thread-safe; forked processes need their
+own client. Drain on a controlled shutdown if losing queued observations matters.
+
+## OpenTelemetry adapter
+
+`from_otel_attributes(attributes, deployment_id=..., agent_id=..., outcome=...)`
+constructs an event without exporting it or installing span processors. It maps
+selected standard names from the [OpenTelemetry GenAI attribute registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/):
+
+| Input | Event field |
+| --- | --- |
+| `gen_ai.provider.name` | `provider` |
+| `gen_ai.request.model` | `model` |
+| `gen_ai.usage.input_tokens` / `output_tokens` | `input_tokens` / `output_tokens` |
+| `telemetry.sdk.name` / `version` | `sdk` / `sdk_version` |
+| `gen_ai.operation.name` | `operation`, via the fixed map below |
+
+`chat`, `text_completion`, `generate_content`, and `embeddings` map to `model`;
+`invoke_agent` maps to `agent`; `execute_tool` maps to `tool`. Unknown operations
+require an explicit application mapping and raise `ValueError`.
+
+ReliaMesh-specific extensions `reliamesh.model.version`, `reliamesh.prompt.version`,
+`reliamesh.agent.version`, `reliamesh.framework.name`, `reliamesh.framework.version`,
+`reliamesh.tool.name`, and `reliamesh.tool.version` map to the corresponding flat
+event fields. These extensions are not official OpenTelemetry conventions.
+The caller explicitly supplies outcome, failure type, duration, and synthetic
+status. All unlisted attributes, messages, exception details, and span events are
+ignored. Invalid allowlisted values are rejected. Never pass prompt text as a
+version identifier.

reliamesh_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reliamesh-sdk"
+version = "0.1.0"
+description = "Content-minimizing reliability events for AI agents"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{name = "Prefiler Labs Private Limited"}]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/PrefilerLabs/reliamesh"
+Repository = "https://github.com/PrefilerLabs/reliamesh"
+Issues = "https://github.com/PrefilerLabs/reliamesh/issues"
+Documentation = "https://github.com/PrefilerLabs/reliamesh/blob/main/sdk/python/README.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

reliamesh_sdk-0.1.0/setup.cfg

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

reliamesh_sdk-0.1.0/src/reliamesh_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""Explicit, content-minimizing reliability instrumentation. No implicit exports."""
+
+from .client import Client, DeliveryError, SDKError
+from .events import event, from_otel_attributes, validate_event
+
+__version__ = "0.1.0"
+__all__ = ["Client", "DeliveryError", "SDKError", "event", "from_otel_attributes", "validate_event"]

reliamesh_sdk-0.1.0/src/reliamesh_sdk/client.py

@@ -0,0 +1,224 @@
+"""Bounded synchronous delivery with explicit endpoints and explicit flush."""
+
+import ipaddress
+import json
+import math
+import threading
+import time
+from collections import deque
+from contextlib import contextmanager
+from http.client import HTTPException
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .events import event, validate_event
+
+
+class SDKError(Exception):
+    """SDK error with no telemetry values or secrets in its message."""
+
+
+class DeliveryError(SDKError):
+    """A bounded export failed. Response bodies are intentionally omitted."""
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def _endpoint(value: str) -> str:
+    try:
+        parsed = urlsplit(value)
+        hostname = parsed.hostname
+        port = parsed.port
+        if (not hostname or parsed.username is not None or parsed.password is not None
+                or parsed.query or parsed.fragment or "\\" in value
+                or any(ord(character) <= 32 for character in value)
+                or (port is not None and not 1 <= port <= 65535)):
+            raise ValueError
+        try:
+            local = ipaddress.ip_address(hostname).is_loopback
+        except ValueError:
+            local = hostname == "localhost"
+        if parsed.scheme != "https" and not (parsed.scheme == "http" and local):
+            raise ValueError
+    except (ValueError, TypeError, AttributeError):
+        raise ValueError("endpoint must be HTTPS or loopback HTTP without credentials/query/fragment") from None
+    return value.rstrip("/")
+
+
+class Client:
+    """No worker, persistence, automatic shutdown hook, or implicit cloud endpoint.
+
+    `emit` and `observe` only enqueue. `flush` performs synchronous I/O and drops
+    each attempted batch after success or final failure. `failure_mode='raise'`
+    additionally raises for invalid events, a full queue, or delivery failure.
+    """
+
+    def __init__(self, *, endpoint: str, api_key: str, timeout: float = 2.0,
+                 max_retries: int = 2, queue_capacity: int = 1000,
+                 failure_mode: str = "drop"):
+        self.endpoint = _endpoint(endpoint)
+        if (not isinstance(api_key, str) or not 1 <= len(api_key) <= 512
+                or any(not 33 <= ord(character) <= 126 for character in api_key)):
+            raise ValueError("api_key must be nonempty visible ASCII")
+        if type(timeout) not in (int, float) or not 0 < timeout <= 30 or not math.isfinite(timeout):
+            raise ValueError("timeout must be greater than zero and at most 30 seconds")
+        if type(max_retries) is not int or not 0 <= max_retries <= 3:
+            raise ValueError("max_retries must be between zero and three")
+        if type(queue_capacity) is not int or not 1 <= queue_capacity <= 10000:
+            raise ValueError("queue_capacity must be between one and 10000")
+        if failure_mode not in ("drop", "raise"):
+            raise ValueError("failure_mode must be drop or raise")
+        self._api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.queue_capacity = queue_capacity
+        self.failure_mode = failure_mode
+        self._queue = deque()
+        self._lock = threading.Lock()
+        self._flush_lock = threading.Lock()
+        self._opener = build_opener(_NoRedirect())
+        self._counts = dict(enqueued=0, sent=0, dropped=0, failed_batches=0, retries=0)
+
+    @property
+    def counters(self) -> dict:
+        with self._lock:
+            return {**self._counts, "queued": len(self._queue)}
+
+    def _increment(self, name, count=1):
+        with self._lock:
+            self._counts[name] += count
+
+    def emit(self, value) -> bool:
+        """Validate and enqueue a copy. This method performs no network activity."""
+        try:
+            validated = validate_event(value)
+        except (ValueError, TypeError):
+            self._increment("dropped")
+            if self.failure_mode == "raise":
+                raise SDKError("event rejected by local validation") from None
+            return False
+        with self._lock:
+            if len(self._queue) >= self.queue_capacity:
+                self._counts["dropped"] += 1
+                if self.failure_mode == "raise":
+                    raise SDKError("event queue is full")
+                return False
+            self._queue.append(validated)
+            self._counts["enqueued"] += 1
+        return True
+
+    def _request(self, path: str, payload: dict | None = None) -> dict | list:
+        encoded = None if payload is None else json.dumps(payload, separators=(",", ":"), allow_nan=False).encode()
+        headers = {"Authorization": "Bearer " + self._api_key,
+                   "Accept": "application/json", "User-Agent": "reliamesh-sdk/0.1.0"}
+        if encoded is not None:
+            headers["Content-Type"] = "application/json"
+        # _endpoint restricts schemes; redirects cannot forward credentials.
+        request = Request(self.endpoint + path, data=encoded, headers=headers)  # noqa: S310
+        for attempt in range(self.max_retries + 1):
+            try:
+                with self._opener.open(request, timeout=self.timeout) as response:
+                    body = response.read(1_048_577)
+                    if len(body) > 1_048_576:
+                        raise DeliveryError("server response exceeds SDK size limit")
+                    result = json.loads(body)
+                    if not isinstance(result, (dict, list)):
+                        raise DeliveryError("server returned an invalid response")
+                    return result
+            except HTTPError as exc:
+                status = exc.code
+                exc.close()
+                if status in (429, 503) and attempt < self.max_retries:
+                    self._increment("retries")
+                    time.sleep(min(0.2 * 2**attempt, 1.0))
+                    continue
+                raise DeliveryError(f"request failed with HTTP {status}") from None
+            except (URLError, OSError, ValueError, HTTPException):
+                raise DeliveryError("request failed or returned invalid JSON") from None
+        raise DeliveryError("request failed")
+
+    def flush(self) -> int:
+        """Send at most the queue present at entry, in batches of 100 events.
+
+        Only HTTP 429 and 503 retry; retries reuse the identical event IDs/body.
+        Delivery is best effort, not a durable delivery guarantee. Unattempted
+        batches remain queued if raise mode stops a flush on the first failure.
+        """
+        sent = 0
+        with self._flush_lock:
+            with self._lock:
+                remaining = len(self._queue)
+            while remaining:
+                with self._lock:
+                    batch = []
+                    payload_size = len(b'{"events":[]}')
+                    while len(batch) < min(100, remaining):
+                        candidate = self._queue[0]
+                        event_size = len(json.dumps(candidate, separators=(",", ":"), allow_nan=False).encode())
+                        addition = event_size + bool(batch)
+                        if batch and payload_size + addition > 131_072:
+                            break
+                        batch.append(self._queue.popleft())
+                        payload_size += addition
+                remaining -= len(batch)
+                try:
+                    result = self._request("/v1/events", {"events": batch})
+                    if (not isinstance(result, dict) or result.get("schema_version") != "1.0"
+                            or type(result.get("accepted")) is not int
+                            or type(result.get("duplicates")) is not int
+                            or result["accepted"] < 0 or result["duplicates"] < 0
+                            or result["accepted"] + result["duplicates"] != len(batch)):
+                        raise DeliveryError("server returned an invalid ingestion acknowledgement")
+                except DeliveryError:
+                    self._increment("failed_batches")
+                    self._increment("dropped", len(batch))
+                    if self.failure_mode == "raise":
+                        raise
+                else:
+                    sent += len(batch)
+                    self._increment("sent", len(batch))
+        return sent
+
+    def summary(self) -> dict | list:
+        """Retrieve authenticated tenant summary; failures always raise DeliveryError."""
+        return self._request("/v1/summary")
+
+    def incidents(self) -> dict | list:
+        """Retrieve authenticated tenant incidents; failures always raise DeliveryError."""
+        return self._request("/v1/incidents")
+
+    @contextmanager
+    def observe(self, *, deployment_id: str, agent_id: str, operation: str = "agent",
+                synthetic: bool = False, **measurements):
+        """Measure duration and classify exceptions without reading their messages.
+
+        Does not infer semantic success. Emit explicit failure events for invalid
+        outputs, incomplete tasks, loops, fallback, or other application findings.
+        """
+        start = time.perf_counter()
+        outcome, failure_type = "success", None
+        try:
+            yield
+        except BaseException as exc:
+            outcome = "failure"
+            failure_type = "timeout" if isinstance(exc, TimeoutError) else {
+                "agent": "agent_error", "model": "model_error", "tool": "tool_error",
+                "validation": "validation_failure",
+            }.get(operation, "unknown")
+            raise
+        finally:
+            try:
+                self.emit(event(deployment_id=deployment_id, agent_id=agent_id,
+                                operation=operation, outcome=outcome, failure_type=failure_type,
+                                latency_ms=min((time.perf_counter() - start) * 1000, 86_400_000),
+                                synthetic=synthetic, **measurements))
+            except (SDKError, ValueError, TypeError) as exc:
+                if not isinstance(exc, SDKError):
+                    self._increment("dropped")
+                # Never replace the original application exception.
+                if outcome == "success" and self.failure_mode == "raise":
+                    raise SDKError("observation could not be recorded") from None

reliamesh_sdk-0.1.0/src/reliamesh_sdk/events.py

@@ -0,0 +1,129 @@
+"""Schema 1.0 event construction without third-party dependencies."""
+
+import math
+import re
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}\Z")
+OPERATIONS = frozenset({"agent", "model", "tool", "validation"})
+FAILURE_TYPES = frozenset({
+    "agent_error", "model_error", "tool_error", "malformed_output", "validation_failure",
+    "timeout", "retry_exhausted", "retry_explosion", "loop_detected", "fallback_activated",
+    "task_incomplete", "unknown",
+})
+IDENTIFIERS = frozenset({
+    "deployment_id", "agent_id", "provider", "model", "model_version", "framework",
+    "framework_version", "sdk", "sdk_version", "tool", "tool_version", "prompt_version",
+    "agent_version",
+})
+COUNTERS = {"input_tokens": 10**9, "output_tokens": 10**9, "retry_count": 10**6}
+REQUIRED = frozenset({"schema_version", "event_id", "timestamp", "deployment_id", "agent_id",
+                      "operation", "outcome"})
+FIELDS = REQUIRED | IDENTIFIERS | COUNTERS.keys() | {"failure_type", "latency_ms", "synthetic"}
+
+
+def validate_event(value: Mapping) -> dict:
+    """Copy and validate an event; error text never includes supplied values."""
+    if not isinstance(value, Mapping) or set(value) - FIELDS or REQUIRED - set(value):
+        raise ValueError("event has missing or unsupported fields")
+    result = dict(value)
+    if result["schema_version"] != "1.0":
+        raise ValueError("unsupported event schema version")
+    try:
+        if not isinstance(result["event_id"], str):
+            raise ValueError
+        result["event_id"] = str(UUID(result["event_id"]))
+    except (ValueError, TypeError, AttributeError):
+        raise ValueError("event_id must be a UUID") from None
+    try:
+        timestamp = datetime.fromisoformat(result["timestamp"])
+        if timestamp.tzinfo is None or timestamp.utcoffset() is None:
+            raise ValueError
+        result["timestamp"] = timestamp.astimezone(UTC).isoformat()
+    except (ValueError, TypeError, OverflowError):
+        raise ValueError("timestamp must be an ISO 8601 time with timezone") from None
+    for key in IDENTIFIERS & result.keys():
+        if not isinstance(result[key], str) or not IDENTIFIER.fullmatch(result[key]):
+            raise ValueError("event identifiers must use 1-64 safe ASCII characters")
+    if not isinstance(result["operation"], str) or result["operation"] not in OPERATIONS:
+        raise ValueError("unsupported operation")
+    if result["outcome"] not in ("success", "failure"):
+        raise ValueError("unsupported outcome")
+    failure = result.get("failure_type")
+    if result["outcome"] == "failure":
+        if not isinstance(failure, str) or failure not in FAILURE_TYPES:
+            raise ValueError("failure outcome requires a supported failure_type")
+    elif failure is not None:
+        raise ValueError("success outcome must not include a failure_type")
+    for key, maximum in COUNTERS.items():
+        if key in result and (type(result[key]) is not int or not 0 <= result[key] <= maximum):
+            raise ValueError("event counter is outside allowed bounds")
+    if "latency_ms" in result:
+        latency = result["latency_ms"]
+        if (type(latency) not in (int, float) or not 0 <= latency <= 86_400_000
+                or not math.isfinite(latency)):
+            raise ValueError("latency_ms is outside allowed bounds")
+    if "synthetic" in result and type(result["synthetic"]) is not bool:
+        raise ValueError("synthetic must be boolean")
+    return result
+
+
+def event(*, deployment_id: str, agent_id: str, operation: str, outcome: str,
+          failure_type: str | None = None, timestamp: datetime | None = None,
+          event_id: str | None = None, synthetic: bool = False, **measurements) -> dict:
+    """Construct a strict protocol event. Unknown metadata is rejected, never exported."""
+    result = {
+        "schema_version": "1.0", "event_id": event_id or str(uuid4()),
+        "timestamp": (timestamp if timestamp is not None else datetime.now(UTC)).isoformat(),
+        "deployment_id": deployment_id, "agent_id": agent_id,
+        "operation": operation, "outcome": outcome, "synthetic": synthetic,
+    }
+    if failure_type is not None:
+        result["failure_type"] = failure_type
+    if set(measurements) & result.keys():
+        raise ValueError("duplicate event fields")
+    result.update(measurements)
+    return validate_event(result)
+
+
+_OTEL_FIELDS = {
+    "gen_ai.provider.name": "provider",
+    "gen_ai.request.model": "model",
+    "gen_ai.usage.input_tokens": "input_tokens",
+    "gen_ai.usage.output_tokens": "output_tokens",
+    "telemetry.sdk.name": "sdk",
+    "telemetry.sdk.version": "sdk_version",
+    "reliamesh.model.version": "model_version",
+    "reliamesh.prompt.version": "prompt_version",
+    "reliamesh.agent.version": "agent_version",
+    "reliamesh.framework.name": "framework",
+    "reliamesh.framework.version": "framework_version",
+    "reliamesh.tool.name": "tool",
+    "reliamesh.tool.version": "tool_version",
+}
+_OTEL_OPERATIONS = {
+    "chat": "model", "text_completion": "model", "generate_content": "model",
+    "embeddings": "model", "invoke_agent": "agent", "execute_tool": "tool",
+}
+
+
+def from_otel_attributes(attributes: Mapping, *, deployment_id: str, agent_id: str,
+                         outcome: str, failure_type: str | None = None,
+                         latency_ms: float | None = None, synthetic: bool = False) -> dict:
+    """Pure whitelist mapping; does not export, inspect spans, or capture content.
+
+    `reliamesh.*` names are local extensions, not official OTel conventions.
+    The caller explicitly supplies the outcome and failure classification.
+    """
+    operation = attributes.get("gen_ai.operation.name")
+    if not isinstance(operation, str) or operation not in _OTEL_OPERATIONS:
+        raise ValueError("unsupported OpenTelemetry operation; map it explicitly")
+    selected = {target: attributes[source] for source, target in _OTEL_FIELDS.items()
+                if source in attributes}
+    if latency_ms is not None:
+        selected["latency_ms"] = latency_ms
+    return event(deployment_id=deployment_id, agent_id=agent_id,
+                 operation=_OTEL_OPERATIONS[operation], outcome=outcome,
+                 failure_type=failure_type, synthetic=synthetic, **selected)

reliamesh_sdk-0.1.0/src/reliamesh_sdk.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: reliamesh-sdk
+Version: 0.1.0
+Summary: Content-minimizing reliability events for AI agents
+Author: Prefiler Labs Private Limited
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/PrefilerLabs/reliamesh
+Project-URL: Repository, https://github.com/PrefilerLabs/reliamesh
+Project-URL: Issues, https://github.com/PrefilerLabs/reliamesh/issues
+Project-URL: Documentation, https://github.com/PrefilerLabs/reliamesh/blob/main/sdk/python/README.md
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# ReliaMesh Python SDK
+
+Content-minimizing reliability events for AI agents. Python 3.12+, no runtime
+dependencies. Owned by Prefiler Labs Private Limited; Apache-2.0.
+
+For a published release, install from PyPI:
+
+```sh
+python -m pip install reliamesh-sdk==0.1.0
+```
+
+Or install from this source checkout:
+
+```sh
+python -m pip install ./sdk/python
+```
+
+```python
+import os
+from reliamesh_sdk import Client, event
+
+client = Client(
+    endpoint=os.environ["RELIAMESH_ENDPOINT"],
+    api_key=os.environ["RELIAMESH_API_KEY"],
+)
+client.emit(event(
+    deployment_id="production-eu1", agent_id="invoice-agent",
+    operation="validation", outcome="failure",
+    failure_type="malformed_output", model="model-alias", prompt_version="v3",
+    latency_ms=140, input_tokens=80, output_tokens=30,
+))
+client.flush()
+```
+
+Use opaque stable identifiers; never put customer content, secrets, email
+addresses, or raw prompts in identifier fields. The schema restricts shape, not
+meaning. Hashing predictable personal data does not make it safe.
+
+## Observe execution
+
+```python
+with client.observe(deployment_id="production-eu1", agent_id="invoice-agent",
+                    operation="tool", tool="document-validator", tool_version="2"):
+    run_tool()  # Your application function; return values are never inspected.
+client.flush()
+```
+
+The context manager records elapsed time, success or failure, and a generic
+exception classification. It never reads the exception message or stack. Original
+application exceptions propagate. A timeout is classified as `timeout`; other
+exceptions use the operation's generic failure type. Application validation must
+emit explicit events for malformed output, loops, fallback, retry escalation, or
+incomplete tasks. A successful HTTP call cannot establish task success.
+
+## Delivery contract
+
+- No default endpoint, network discovery, background thread, automatic exporter,
+  exit hook, or outbound telemetry. `emit` and `observe` enqueue locally;
+  `flush`, `summary`, and `incidents` initiate requests to your chosen endpoint.
+- Endpoints require HTTPS, except loopback HTTP for local use. Redirects are
+  rejected. TLS uses Python's normal certificate validation.
+- Default queue capacity: 1,000 events, at most 100 events and 128 KiB per request. Queue capacity is
+  configurable from 1 to 10,000. The queue lives only in memory.
+- Default socket timeout: 2 seconds, configurable up to 30 seconds. This bounds
+  individual socket operations, not the entire flush. Flush processes only the
+  number of events queued at entry, so concurrent producers cannot extend it
+  indefinitely.
+- Only HTTP 429 and 503 retry, up to two retries by default (maximum three).
+  Exponential delays are bounded to one second. Retry bodies and event IDs are
+  identical so the server can deduplicate them. Transport errors and other
+  statuses are not retried. The client verifies ingestion acknowledgement counts.
+- Default `failure_mode="drop"` drops invalid, overflowing, or unsuccessfully sent
+  events. `failure_mode="raise"` raises `SDKError`/`DeliveryError`. An attempted
+  failed batch is dropped in either mode. Raise mode leaves later batches queued.
+- Read `client.counters`: `enqueued`, `sent`, `dropped`, `failed_batches`,
+  `retries`, and `queued`. `sent` counts acknowledged input events, including
+  deduplicated events. Errors omit response bodies and credentials.
+- `summary()` and `incidents()` return decoded authenticated API responses;
+  read failures always raise `DeliveryError`.
+
+This is best-effort instrumentation, not durable message delivery. Export on a
+dedicated application worker or with `await asyncio.to_thread(client.flush)` in
+async applications. Do not call synchronous `flush()` on a latency-sensitive event
+loop. In-process queuing and counters are thread-safe; forked processes need their
+own client. Drain on a controlled shutdown if losing queued observations matters.
+
+## OpenTelemetry adapter
+
+`from_otel_attributes(attributes, deployment_id=..., agent_id=..., outcome=...)`
+constructs an event without exporting it or installing span processors. It maps
+selected standard names from the [OpenTelemetry GenAI attribute registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/):
+
+| Input | Event field |
+| --- | --- |
+| `gen_ai.provider.name` | `provider` |
+| `gen_ai.request.model` | `model` |
+| `gen_ai.usage.input_tokens` / `output_tokens` | `input_tokens` / `output_tokens` |
+| `telemetry.sdk.name` / `version` | `sdk` / `sdk_version` |
+| `gen_ai.operation.name` | `operation`, via the fixed map below |
+
+`chat`, `text_completion`, `generate_content`, and `embeddings` map to `model`;
+`invoke_agent` maps to `agent`; `execute_tool` maps to `tool`. Unknown operations
+require an explicit application mapping and raise `ValueError`.
+
+ReliaMesh-specific extensions `reliamesh.model.version`, `reliamesh.prompt.version`,
+`reliamesh.agent.version`, `reliamesh.framework.name`, `reliamesh.framework.version`,
+`reliamesh.tool.name`, and `reliamesh.tool.version` map to the corresponding flat
+event fields. These extensions are not official OpenTelemetry conventions.
+The caller explicitly supplies outcome, failure type, duration, and synthetic
+status. All unlisted attributes, messages, exception details, and span events are
+ignored. Invalid allowlisted values are rejected. Never pass prompt text as a
+version identifier.

reliamesh_sdk-0.1.0/src/reliamesh_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+NOTICE
+README.md
+pyproject.toml
+src/reliamesh_sdk/__init__.py
+src/reliamesh_sdk/client.py
+src/reliamesh_sdk/events.py
+src/reliamesh_sdk.egg-info/PKG-INFO
+src/reliamesh_sdk.egg-info/SOURCES.txt
+src/reliamesh_sdk.egg-info/dependency_links.txt
+src/reliamesh_sdk.egg-info/top_level.txt

reliamesh_sdk-0.1.0/src/reliamesh_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

reliamesh_sdk-0.1.0/src/reliamesh_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+reliamesh_sdk