pontem 0.0.0__tar.gz

pontem-0.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 Pontem AI, Inc.
+
+   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.

pontem-0.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: pontem
+Version: 0.0.0
+Summary: Pontem edge SDK — logs, metrics, and config for edge devices
+License: Apache-2.0
+License-File: LICENSE
+Keywords: edge,telemetry,metrics,logging,iot
+Author: Pontem AI, Inc.
+Author-email: support@pontem.ai
+Requires-Python: >=3.9
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://pontemai.com
+Project-URL: Repository, https://github.com/pontemai/pontem-python
+Description-Content-Type: text/markdown
+
+# Pontem Python SDK
+
+Pontem Python SDK for logs, metrics, and config on Pontem-managed edge devices. Zero runtime dependencies.
+
+## Installation
+
+```bash
+pip install pontem
+```
+
+<details>
+<summary>Internal / Artifact Registry</summary>
+
+One-time local setup:
+
+```bash
+pip install keyrings.google-artifactregistry-auth
+gcloud auth login
+```
+
+Add the registry to your project's `pyproject.toml`:
+
+```toml
+[[tool.poetry.source]]
+name = "pontem-python"
+url = "https://us-east1-python.pkg.dev/pontem-control-prod/pontem-python/simple/"
+priority = "supplemental"
+```
+
+Then install:
+
+```bash
+poetry add pontem --source pontem-python
+```
+
+</details>
+
+## Quick Start
+
+```python
+import pontem
+
+pontem.init(service_name="my-service")
+
+pontem.logger.info("model loaded", model="scoring_v3")
+
+pontem.metrics.count("detections", class_name="apple")
+
+with pontem.metrics.timer("model.inference"):
+    result = model.predict(frame)
+
+pontem.shutdown()
+```
+
+## Usage
+
+### Logging
+
+Structured logs with OTel-aligned severity levels. Each log is written to `logs.jsonl` in the emit directory.
+
+```python
+pontem.logger.info("model loaded", model="scoring_v3")
+pontem.logger.warn("high latency", latency_ms=120)
+pontem.logger.error("inference failed", error=str(e))
+```
+
+Available levels: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
+
+### Metrics
+
+Metrics are aggregated in memory and flushed periodically to `metrics.jsonl`. No I/O on the caller's thread.
+
+```python
+# Counters — incremented, flushed as a single sum
+pontem.metrics.count("detections", class_name="apple")
+pontem.metrics.count("bytes_sent", len(payload))
+
+# Histograms — records min/max/sum/count summary
+pontem.metrics.record("payload_size", len(data), unit="bytes")
+
+# Gauges — last value wins
+pontem.metrics.set_gauge("gpu_temp", 72.0, unit="celsius", gpu="0")
+
+# Timers — context manager or decorator, records to histogram
+with pontem.metrics.timer("model.inference"):
+    result = model.predict(frame)
+
+@pontem.metrics.timer("preprocessing")
+def preprocess(frame):
+    ...
+```
+
+### Config
+
+Reads agent-managed config from `/etc/pontem/config/config.json` (or `$PONTEM_CONFIG_DIR`).
+
+```python
+threshold = pontem.config("my_namespace", "model_threshold", default=0.85)
+
+# Reload after agent signals a config update
+pontem.config.reload()
+```
+
+### Shutdown
+
+Flushes remaining metrics and logs. Also registered via `atexit`.
+
+```python
+pontem.shutdown()
+```
+
+## Documentation
+
+See [docs/getting-started.md](docs/getting-started.md) for a comprehensive guide including full API reference, configuration options, and troubleshooting.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+

pontem-0.0.0/README.md

@@ -0,0 +1,118 @@
+# Pontem Python SDK
+
+Pontem Python SDK for logs, metrics, and config on Pontem-managed edge devices. Zero runtime dependencies.
+
+## Installation
+
+```bash
+pip install pontem
+```
+
+<details>
+<summary>Internal / Artifact Registry</summary>
+
+One-time local setup:
+
+```bash
+pip install keyrings.google-artifactregistry-auth
+gcloud auth login
+```
+
+Add the registry to your project's `pyproject.toml`:
+
+```toml
+[[tool.poetry.source]]
+name = "pontem-python"
+url = "https://us-east1-python.pkg.dev/pontem-control-prod/pontem-python/simple/"
+priority = "supplemental"
+```
+
+Then install:
+
+```bash
+poetry add pontem --source pontem-python
+```
+
+</details>
+
+## Quick Start
+
+```python
+import pontem
+
+pontem.init(service_name="my-service")
+
+pontem.logger.info("model loaded", model="scoring_v3")
+
+pontem.metrics.count("detections", class_name="apple")
+
+with pontem.metrics.timer("model.inference"):
+    result = model.predict(frame)
+
+pontem.shutdown()
+```
+
+## Usage
+
+### Logging
+
+Structured logs with OTel-aligned severity levels. Each log is written to `logs.jsonl` in the emit directory.
+
+```python
+pontem.logger.info("model loaded", model="scoring_v3")
+pontem.logger.warn("high latency", latency_ms=120)
+pontem.logger.error("inference failed", error=str(e))
+```
+
+Available levels: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
+
+### Metrics
+
+Metrics are aggregated in memory and flushed periodically to `metrics.jsonl`. No I/O on the caller's thread.
+
+```python
+# Counters — incremented, flushed as a single sum
+pontem.metrics.count("detections", class_name="apple")
+pontem.metrics.count("bytes_sent", len(payload))
+
+# Histograms — records min/max/sum/count summary
+pontem.metrics.record("payload_size", len(data), unit="bytes")
+
+# Gauges — last value wins
+pontem.metrics.set_gauge("gpu_temp", 72.0, unit="celsius", gpu="0")
+
+# Timers — context manager or decorator, records to histogram
+with pontem.metrics.timer("model.inference"):
+    result = model.predict(frame)
+
+@pontem.metrics.timer("preprocessing")
+def preprocess(frame):
+    ...
+```
+
+### Config
+
+Reads agent-managed config from `/etc/pontem/config/config.json` (or `$PONTEM_CONFIG_DIR`).
+
+```python
+threshold = pontem.config("my_namespace", "model_threshold", default=0.85)
+
+# Reload after agent signals a config update
+pontem.config.reload()
+```
+
+### Shutdown
+
+Flushes remaining metrics and logs. Also registered via `atexit`.
+
+```python
+pontem.shutdown()
+```
+
+## Documentation
+
+See [docs/getting-started.md](docs/getting-started.md) for a comprehensive guide including full API reference, configuration options, and troubleshooting.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

pontem-0.0.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "pontem"
+version = "0.0.0"
+description = "Pontem edge SDK — logs, metrics, and config for edge devices"
+authors = [
+    {name = "Pontem AI, Inc.", email = "support@pontem.ai"},
+]
+license = {text = "Apache-2.0"}
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["edge", "telemetry", "metrics", "logging", "iot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://pontemai.com"
+Repository = "https://github.com/pontemai/pontem-python"
+
+[tool.poetry]
+packages = [{include = "pontem", from = "src"}]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+ruff = "^0.8"
+
+[tool.poetry-dynamic-versioning]
+enable = true
+vcs = "git"
+style = "semver"
+strict = false
+pattern = "^(?P<base>\\d+\\.\\d+\\.\\d+)$"
+bump = true
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"

pontem-0.0.0/src/pontem/__init__.py

@@ -0,0 +1,27 @@
+"""Pontem edge SDK.
+
+Zero dependencies.  One-line install, one-line instrumentation::
+
+    import pontem
+
+    pontem.init(service_name="my-service")
+    pontem.logger.info("model loaded", model="scoring_v3")
+
+    with pontem.metrics.timer("model.inference"):
+        result = model.predict(frame)
+
+    pontem.metrics.count("detections", class_name="apple")
+"""
+
+from pontem._config import config
+from pontem._metrics import metrics
+from pontem._sdk import init, shutdown
+from pontem.log import logger
+
+__all__ = [
+    "init",
+    "shutdown",
+    "logger",
+    "metrics",
+    "config",
+]

pontem-0.0.0/src/pontem/_config.py

@@ -0,0 +1,87 @@
+"""Configuration reader for Pontem agent-managed config."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, TypeVar, overload
+
+_logger = logging.getLogger("pontem.config")
+
+T = TypeVar("T")
+
+_DEFAULT_CONFIG_DIR = "/etc/pontem/config"
+
+
+class Config:
+    """Callable config reader with reload support.
+
+    Example::
+
+        import pontem
+
+        threshold = pontem.config("model_threshold", default=0.85)
+        pontem.config.reload()  # re-read from disk
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, Any] | None = None
+
+    def _load(self) -> dict[str, Any]:
+        """Load config from the agent-managed JSON file."""
+        if self._cache is not None:
+            return self._cache
+
+        config_dir = os.environ.get("PONTEM_CONFIG_DIR", _DEFAULT_CONFIG_DIR)
+        config_file = os.path.join(config_dir, "config.json")
+
+        try:
+            with open(config_file) as f:
+                self._cache = json.load(f)
+        except FileNotFoundError:
+            _logger.debug("No agent config at %s, using defaults", config_file)
+            self._cache = {}
+        except json.JSONDecodeError:
+            _logger.warning("Invalid JSON in %s, using defaults", config_file)
+            self._cache = {}
+
+        return self._cache
+
+    @overload
+    def __call__(self, namespace: str, key: str) -> str | None: ...
+
+    @overload
+    def __call__(self, namespace: str, key: str, *, default: T) -> T: ...
+
+    def __call__(self, namespace: str, key: str, *, default: Any = None) -> Any:
+        """Read a config value managed by the Pontem agent.
+
+        Example::
+
+            pontem.config("x:y:z", "keyA")
+            pontem.config("x:y:z", "keyA", default=0.85)
+
+        Args:
+            namespace: Namespace prefix (e.g. ``"x:y:z"``).
+            key: Config key (e.g. ``"keyA"``).
+            default: Fallback value if key is not found.
+        """
+        full_key = f"{namespace}:{key}"
+
+        data = self._load()
+        if full_key in data:
+            return data[full_key]
+
+        return default
+
+    def reload(self) -> None:
+        """Force re-read of config from disk on next access.
+
+        Call after the agent signals a config update (e.g. via inotify or
+        a SIGHUP handler).
+        """
+        self._cache = None
+
+
+config = Config()

pontem-0.0.0/src/pontem/_emit.py

@@ -0,0 +1,302 @@
+"""File-based telemetry emission.
+
+Writes structured JSONL to a directory the Pontem agent watches.
+The agent reads rotated files and ships them to the cloud.
+
+Layout::
+
+    $PONTEM_EMIT_DIR/
+        logs.jsonl                  <- active (SDK writes here)
+        logs.jsonl.1713100000.gz    <- rotated + compressed (agent picks up + deletes)
+        metrics.jsonl
+        metrics.jsonl.1713099000.gz
+
+Architecture::
+
+    Caller thread                    Background thread (pontem-emit)
+    ─────────────                    ──────────────────────────────
+    pontem.logger.info(...)            wakes every _flush_interval
+      → queue.put_nowait()            drains log queue → batch write
+      → returns (~2µs)               collects aggregated metrics
+                                      writes metric summaries
+    pontem.metrics.count(...)          single flush() across all files
+      → lock, dict += 1, unlock      checks sizes → rotate if needed
+      → returns (~100ns)             sleeps
+
+* **Non-blocking** — log emit enqueues to a bounded buffer; metric
+  calls just update in-memory aggregation state.
+* **Bounded disk** — files rotate at a size threshold; old rotated
+  files are pruned.
+* **Thread-safe** — multiple threads can call emit/count concurrently.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import os
+import queue
+import shutil
+import threading
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, TextIO
+
+_logger = logging.getLogger("pontem.emit")
+
+# -- Public state --------------------------------------------------------------
+
+_emit_dir: Path | None = None
+_resource: dict[str, Any] = {}
+
+# -- Defaults ------------------------------------------------------------------
+
+DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024  # 10 MB per channel file
+DEFAULT_MAX_ROTATED = 5  # keep last N rotated files per channel
+DEFAULT_FLUSH_INTERVAL = 1.0  # seconds between background flushes
+DEFAULT_QUEUE_SIZE = 10_000  # max buffered records before dropping
+
+# -- Internal state ------------------------------------------------------------
+
+_max_file_bytes = DEFAULT_MAX_FILE_BYTES
+_max_rotated = DEFAULT_MAX_ROTATED
+_flush_interval = DEFAULT_FLUSH_INTERVAL
+
+_queue: queue.Queue[tuple[str, str] | None] = queue.Queue(
+    maxsize=DEFAULT_QUEUE_SIZE,
+)
+_thread: threading.Thread | None = None
+_stop = threading.Event()
+
+# Periodic callbacks — called each cycle to collect aggregated data.
+# Each returns a list of (channel, record_dict) tuples.
+_periodic: list[Callable[[], list[tuple[str, dict[str, Any]]]]] = []
+
+# Accessed only from the writer thread:
+_files: dict[str, TextIO] = {}
+_file_sizes: dict[str, int] = {}
+
+
+def configure(
+    emit_dir: str | None = None,
+    resource: dict[str, Any] | None = None,
+    *,
+    max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+    max_rotated_files: int = DEFAULT_MAX_ROTATED,
+    flush_interval: float = DEFAULT_FLUSH_INTERVAL,
+) -> Path | None:
+    """Set up the emit directory and start the background writer.
+
+    Returns the resolved path, or ``None`` if no emit directory is set.
+    """
+    global _emit_dir, _resource, _thread
+    global _max_file_bytes, _max_rotated, _flush_interval
+
+    path = emit_dir or os.environ.get("PONTEM_EMIT_DIR")
+    if not path:
+        return None
+
+    _emit_dir = Path(path)
+    _emit_dir.mkdir(parents=True, exist_ok=True)
+    _resource = resource or {}
+
+    _max_file_bytes = max_file_bytes
+    _max_rotated = max_rotated_files
+    _flush_interval = flush_interval
+
+    # Start background writer if not already running.
+    if _thread is None or not _thread.is_alive():
+        _stop.clear()
+        _thread = threading.Thread(
+            target=_writer_loop,
+            daemon=True,
+            name="pontem-emit",
+        )
+        _thread.start()
+
+    return _emit_dir
+
+
+def register_periodic(
+    fn: Callable[[], list[tuple[str, dict[str, Any]]]],
+) -> None:
+    """Register a callback invoked each flush cycle.
+
+    The callback should return ``(channel, record_dict)`` tuples.
+    Used by ``_metrics._collect()`` to flush aggregated metrics.
+    """
+    _periodic.append(fn)
+
+
+def emit(channel: str, record: dict[str, Any]) -> None:
+    """Enqueue a telemetry record.  Non-blocking; drops if buffer full.
+
+    Used for logs (each record is unique).  Metrics use aggregation
+    instead — see ``_metrics.py``.
+    """
+    if _emit_dir is None:
+        return
+    record["timestamp"] = time.time()
+    record["resource"] = _resource
+    line = json.dumps(record, separators=(",", ":"), default=str)
+    try:
+        _queue.put_nowait((channel, line))
+    except queue.Full:
+        # Back-pressure: drop rather than block the caller.
+        _logger.debug("emit queue full, dropping record on %s", channel)
+
+
+def close() -> None:
+    """Drain remaining records, flush files, and stop the writer thread."""
+    global _thread, _emit_dir
+    _stop.set()
+    if _thread is not None:
+        _thread.join(timeout=5.0)
+        if _thread.is_alive():
+            _logger.warning(
+                "pontem-emit: writer thread did not exit in 5s, "
+                "buffered data may be lost"
+            )
+        _thread = None
+
+    # Thread has exited — safe to close files from this thread.
+    for f in _files.values():
+        try:
+            f.flush()
+            f.close()
+        except OSError:
+            pass
+    _files.clear()
+    _file_sizes.clear()
+    _emit_dir = None
+    _stop.clear()
+    _periodic.clear()
+
+    # Discard any stragglers left after thread timeout.
+    while not _queue.empty():
+        try:
+            _queue.get_nowait()
+        except queue.Empty:
+            break
+
+
+# -- Background writer ---------------------------------------------------------
+
+
+def _writer_loop() -> None:
+    """Drain queue, collect aggregated metrics, write, flush.  Daemon thread."""
+    while not _stop.is_set():
+        try:
+            _drain()
+            _collect_periodic()
+            _flush_all()
+        except Exception:
+            _logger.exception("pontem-emit: error in writer loop")
+        _stop.wait(_flush_interval)
+    # Final cycle before exit.
+    try:
+        _drain()
+        _collect_periodic()
+        _flush_all()
+    except Exception:
+        _logger.exception("pontem-emit: error in final flush")
+
+
+def _drain() -> None:
+    """Pull all available records from the queue and write in batches."""
+    batches: dict[str, list[str]] = {}
+    while True:
+        try:
+            item = _queue.get_nowait()
+        except queue.Empty:
+            break
+        if item is None:
+            continue
+        channel, line = item
+        batches.setdefault(channel, []).append(line)
+
+    for channel, lines in batches.items():
+        _write_lines(channel, lines)
+
+
+def _collect_periodic() -> None:
+    """Run registered periodic callbacks and write their output."""
+    for cb in _periodic:
+        batches: dict[str, list[str]] = {}
+        for channel, record in cb():
+            record["timestamp"] = time.time()
+            record["resource"] = _resource
+            line = json.dumps(record, separators=(",", ":"), default=str)
+            batches.setdefault(channel, []).append(line)
+        for channel, lines in batches.items():
+            _write_lines(channel, lines)
+
+
+def _flush_all() -> None:
+    """Single flush across all open file handles.
+
+    Called once per cycle — NOT per record or per channel.  Same
+    pattern as Java's AsyncAppender and Python's QueueListener.
+    """
+    for f in _files.values():
+        f.flush()
+
+
+def _write_lines(channel: str, lines: list[str]) -> None:
+    """Write a batch of serialized JSON lines, rotating if needed.
+
+    Does NOT flush — the caller flushes once after all channels
+    are written.
+    """
+    if _emit_dir is None:
+        return
+
+    f = _files.get(channel)
+    if f is None:
+        filepath = _emit_dir / channel
+        f = open(filepath, "a")  # noqa: SIM115
+        _files[channel] = f
+        _file_sizes[channel] = os.fstat(f.fileno()).st_size
+
+    payload = "\n".join(lines) + "\n"
+    f.write(payload)
+    _file_sizes[channel] = _file_sizes.get(channel, 0) + len(payload)
+
+    if _file_sizes[channel] >= _max_file_bytes:
+        _rotate(channel)
+
+
+def _rotate(channel: str) -> None:
+    """Close the active file, rename with timestamp, compress, prune old files."""
+    f = _files.pop(channel, None)
+    if f:
+        f.flush()
+        f.close()
+    _file_sizes.pop(channel, None)
+
+    if _emit_dir is None:
+        return
+
+    src = _emit_dir / channel
+    if src.exists():
+        dst = _emit_dir / f"{channel}.{time.time_ns()}"
+        src.rename(dst)
+        _compress_gz(dst)
+
+    # Prune oldest rotated files beyond the cap.
+    rotated = sorted(
+        _emit_dir.glob(f"{channel}.*"),
+        key=lambda p: p.stat().st_mtime,
+    )
+    while len(rotated) > _max_rotated:
+        rotated.pop(0).unlink()
+
+
+def _compress_gz(path: Path) -> None:
+    """Gzip-compress a file in place.  Replaces original with .gz."""
+    gz_path = Path(str(path) + ".gz")
+    with open(path, "rb") as f_in, gzip.open(gz_path, "wb") as f_out:
+        shutil.copyfileobj(f_in, f_out)
+    path.unlink()

pontem-0.0.0/src/pontem/_metrics.py

@@ -0,0 +1,241 @@
+"""Metrics instrumentation with client-side aggregation.
+
+Metrics are accumulated in memory and flushed periodically by the
+background emitter thread — the same pattern used by OTel's
+``PeriodicExportingMetricReader``, Prometheus client, and Micrometer.
+
+The caller's hot path is a lock + dict update (~100ns).  No JSON
+serialization, no queue, no disk I/O.
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from typing import Any
+
+# -- Aggregation state ---------------------------------------------------------
+
+_lock = threading.Lock()
+
+# Key: (name, unit, frozenset of attribute items)
+_Key = tuple[str, str, frozenset[tuple[str, Any]]]
+
+_EMPTY_ATTRS: frozenset[tuple[str, Any]] = frozenset()
+
+_counters: dict[_Key, float] = {}
+_gauges: dict[_Key, float] = {}
+_histograms: dict[_Key, _HistogramAcc] = {}
+
+
+class _HistogramAcc:
+    """Running min/max/sum/count accumulator for histogram values."""
+
+    __slots__ = ("count", "total", "mn", "mx")
+
+    def __init__(self) -> None:
+        self.count = 0
+        self.total = 0.0
+        self.mn = float("inf")
+        self.mx = float("-inf")
+
+    def add(self, value: float) -> None:
+        self.count += 1
+        self.total += value
+        if value < self.mn:
+            self.mn = value
+        if value > self.mx:
+            self.mx = value
+
+
+# -- Timer (private) -----------------------------------------------------------
+
+
+class _Timer:
+    """Time a block of code.  Context manager and decorator.
+
+    As context manager::
+
+        with pontem.metrics.timer("model.inference"):
+            result = model.predict(frame)
+
+    As decorator::
+
+        @pontem.metrics.timer("model.inference")
+        def predict(frame):
+            ...
+
+    Records elapsed seconds to a histogram.
+    """
+
+    def __init__(self, name: str, *, unit: str = "s", **attrs: Any) -> None:
+        self._name = name
+        self._unit = unit
+        self._attrs = attrs
+        self._start: float = 0
+
+    def __enter__(self) -> _Timer:
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(self, *exc: Any) -> bool:
+        elapsed = time.perf_counter() - self._start
+        key = (
+            self._name,
+            self._unit,
+            frozenset(self._attrs.items()) if self._attrs else _EMPTY_ATTRS,
+        )
+        with _lock:
+            acc = _histograms.get(key)
+            if acc is None:
+                acc = _HistogramAcc()
+                _histograms[key] = acc
+            acc.add(elapsed)
+        return False
+
+    def __call__(self, fn: Any) -> Any:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with _Timer(self._name, unit=self._unit, **self._attrs):
+                return fn(*args, **kwargs)
+
+        return wrapper
+
+
+# -- Public API ----------------------------------------------------------------
+
+
+class Metrics:
+    """Namespace for metric instrumentation functions."""
+
+    def count(self, name: str, amount: float = 1, **attrs: Any) -> None:
+        """Increment a counter.
+
+        Example::
+
+            pontem.metrics.count("detections", class_name="apple")
+            pontem.metrics.count("bytes_sent", len(payload))
+        """
+        key = (name, "", frozenset(attrs.items()) if attrs else _EMPTY_ATTRS)
+        with _lock:
+            _counters[key] = _counters.get(key, 0) + amount
+
+    def record(self, name: str, value: float, *, unit: str = "", **attrs: Any) -> None:
+        """Record a value to a histogram.
+
+        Accumulates count/sum/min/max and flushes as a summary each
+        interval — the standard approach used by OTel and Prometheus.
+
+        Example::
+
+            pontem.metrics.record("payload_size", len(data), unit="bytes")
+        """
+        key = (name, unit, frozenset(attrs.items()) if attrs else _EMPTY_ATTRS)
+        with _lock:
+            acc = _histograms.get(key)
+            if acc is None:
+                acc = _HistogramAcc()
+                _histograms[key] = acc
+            acc.add(value)
+
+    def set_gauge(
+        self, name: str, value: float, *, unit: str = "", **attrs: Any
+    ) -> None:
+        """Set a gauge to a point-in-time value.
+
+        Only the latest value per interval is emitted.
+
+        Example::
+
+            pontem.metrics.set_gauge("gpu_temperature", 72.0, unit="celsius", gpu="0")
+        """
+        key = (name, unit, frozenset(attrs.items()) if attrs else _EMPTY_ATTRS)
+        with _lock:
+            _gauges[key] = value
+
+    def timer(self, name: str, *, unit: str = "s", **attrs: Any) -> _Timer:
+        """Time a block of code.  Returns a context manager / decorator.
+
+        Example::
+
+            with pontem.metrics.timer("model.inference"):
+                result = model.predict(frame)
+        """
+        return _Timer(name, unit=unit, **attrs)
+
+
+metrics = Metrics()
+
+
+# -- Collection (called by the emit background thread) -------------------------
+
+
+def _collect() -> list[tuple[str, dict[str, Any]]]:
+    """Swap out accumulated metrics and return serializable records.
+
+    Returns a list of ``(channel, record_dict)`` tuples.  The emit
+    thread adds ``timestamp`` and ``resource`` before writing.
+
+    The lock is held only during the swap (O(1) reference swap) —
+    building output records happens outside the lock.
+    """
+    global _counters, _gauges, _histograms
+    with _lock:
+        counters = _counters
+        _counters = {}
+        gauges = _gauges
+        _gauges = {}
+        histograms = _histograms
+        _histograms = {}
+
+    results: list[tuple[str, dict[str, Any]]] = []
+
+    for (name, unit, attrs_frozen), total in counters.items():
+        rec: dict[str, Any] = {
+            "name": name,
+            "type": "counter",
+            "value": total,
+            "attributes": dict(attrs_frozen),
+        }
+        if unit:
+            rec["unit"] = unit
+        results.append(("metrics.jsonl", rec))
+
+    for (name, unit, attrs_frozen), value in gauges.items():
+        rec = {
+            "name": name,
+            "type": "gauge",
+            "value": value,
+            "attributes": dict(attrs_frozen),
+        }
+        if unit:
+            rec["unit"] = unit
+        results.append(("metrics.jsonl", rec))
+
+    for (name, unit, attrs_frozen), acc in histograms.items():
+        rec = {
+            "name": name,
+            "type": "histogram",
+            "value": {
+                "count": acc.count,
+                "sum": acc.total,
+                "min": acc.mn,
+                "max": acc.mx,
+            },
+            "attributes": dict(attrs_frozen),
+        }
+        if unit:
+            rec["unit"] = unit
+        results.append(("metrics.jsonl", rec))
+
+    return results
+
+
+def _reset() -> None:
+    """Clear all aggregation state.  Used by tests."""
+    global _counters, _gauges, _histograms
+    with _lock:
+        _counters = {}
+        _gauges = {}
+        _histograms = {}

pontem-0.0.0/src/pontem/_sdk.py

@@ -0,0 +1,100 @@
+"""SDK initialization and lifecycle."""
+
+from __future__ import annotations
+
+import atexit
+import importlib.metadata
+import logging
+import os
+from typing import Any
+
+from pontem import _emit
+
+_initialized = False
+_logger = logging.getLogger("pontem.sdk")
+
+# Environment variables the Pontem agent sets on managed devices.
+_AGENT_ENV_MAP = {
+    "device.id": "PONTEM_DEVICE_ID",
+    "pontem.tenant.id": "PONTEM_TENANT_ID",
+    "pontem.config.version": "PONTEM_CONFIG_VERSION",
+}
+
+
+def _infer_service_version(service_name: str) -> str | None:
+    """Read version from installed package metadata.
+
+    Tries the name as-is, then underscore ↔ hyphen normalization.
+    """
+    candidates = {service_name}
+    candidates.add(service_name.replace("_", "-"))
+    candidates.add(service_name.replace("-", "_"))
+
+    for name in candidates:
+        try:
+            return importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError:
+            continue
+    return None
+
+
+def init(
+    *,
+    service_name: str,
+    service_version: str | None = None,
+    emit_dir: str | None = None,
+) -> None:
+    """Initialize the Pontem SDK.
+
+    Call once at startup.
+
+    Telemetry is written as JSONL to the emit directory, which the
+    Pontem agent watches and forwards to the cloud.
+
+    Args:
+        service_name: Identifies this service in all emitted telemetry.
+        service_version: Override auto-detected version.
+        emit_dir: Override ``PONTEM_EMIT_DIR`` env var and the default
+            ``/opt/pontem/<service_name>/var/log``.
+    """
+    global _initialized
+    if _initialized:
+        _logger.warning("pontem.init() already called, ignoring")
+        return
+    service_version = service_version or _infer_service_version(service_name)
+
+    # Resource attributes — attached to every emitted record.
+    resource: dict[str, Any] = {"service.name": service_name}
+    if service_version:
+        resource["service.version"] = service_version
+    for attr_key, env_var in _AGENT_ENV_MAP.items():
+        val = os.environ.get(env_var)
+        if val:
+            resource[attr_key] = val
+
+    # Default emit dir: /opt/pontem/<service_name>/var/log
+    if not emit_dir and not os.environ.get("PONTEM_EMIT_DIR"):
+        emit_dir = f"/opt/pontem/{service_name}/var/log"
+
+    path = _emit.configure(emit_dir, resource)
+    if path:
+        _logger.debug("pontem emit dir: %s", path)
+    else:
+        _logger.debug("emit dir could not be configured")
+
+    # Register metrics aggregation flush with the emit thread.
+    from pontem import _metrics
+
+    _emit.register_periodic(_metrics._collect)
+
+    atexit.register(shutdown)
+    _initialized = True
+
+
+def shutdown() -> None:
+    """Flush aggregated metrics, drain logs, and close emit files."""
+    global _initialized
+    if not _initialized:
+        return
+    _emit.close()
+    _initialized = False

pontem-0.0.0/src/pontem/log.py

@@ -0,0 +1,106 @@
+"""Structured logging.
+
+Types::
+
+    from pontem.log import Level
+    Level.DEBUG  # 5
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+from typing import Any
+
+from pontem import _emit
+
+_stdlib_logger = logging.getLogger("pontem")
+
+
+class Level(enum.IntEnum):
+    """Log severity levels.
+
+    Values map to OpenTelemetry SeverityNumber (1-24 scale).
+    https://opentelemetry.io/docs/specs/otel/logs/data-model/#severity-fields
+    """
+
+    TRACE = 1
+    DEBUG = 5
+    INFO = 9
+    WARN = 13
+    ERROR = 17
+    FATAL = 21
+
+
+_PY_LEVEL = {
+    Level.TRACE: logging.DEBUG,
+    Level.DEBUG: logging.DEBUG,
+    Level.INFO: logging.INFO,
+    Level.WARN: logging.WARNING,
+    Level.ERROR: logging.ERROR,
+    Level.FATAL: logging.CRITICAL,
+}
+
+
+class Logger:
+    """Structured logger with level helpers.
+
+    Example::
+
+        import pontem
+
+        pontem.logger.info("model loaded", model="scoring_v3")
+        pontem.logger.warn("high latency", latency_ms=120)
+
+    Severity levels are available as attributes::
+
+        pontem.logger.TRACE  # 1
+        pontem.logger.INFO   # 9
+    """
+
+    TRACE = Level.TRACE
+    DEBUG = Level.DEBUG
+    INFO = Level.INFO
+    WARN = Level.WARN
+    ERROR = Level.ERROR
+    FATAL = Level.FATAL
+
+    def _log(self, level: int, msg: str, **attrs: Any) -> None:
+        py_level = _PY_LEVEL.get(level, logging.INFO)
+        _stdlib_logger.log(py_level, msg, extra=attrs)
+
+        try:
+            severity_text = Level(level).name
+        except ValueError:
+            severity_text = "INFO"
+
+        _emit.emit(
+            "logs.jsonl",
+            {
+                "severityNumber": level,
+                "severityText": severity_text,
+                "body": msg,
+                "attributes": attrs or {},
+            },
+        )
+
+    def trace(self, msg: str, **attrs: Any) -> None:
+        self._log(Level.TRACE, msg, **attrs)
+
+    def debug(self, msg: str, **attrs: Any) -> None:
+        self._log(Level.DEBUG, msg, **attrs)
+
+    def info(self, msg: str, **attrs: Any) -> None:
+        self._log(Level.INFO, msg, **attrs)
+
+    def warn(self, msg: str, **attrs: Any) -> None:
+        self._log(Level.WARN, msg, **attrs)
+
+    def error(self, msg: str, **attrs: Any) -> None:
+        self._log(Level.ERROR, msg, **attrs)
+
+    def fatal(self, msg: str, **attrs: Any) -> None:
+        self._log(Level.FATAL, msg, **attrs)
+
+
+logger = Logger()