pamoja-kit 0.1.17__tar.gz

pamoja_kit-0.1.17/.gitignore

@@ -0,0 +1,13 @@
+# Native extensions are built per platform, not committed.
+*.so
+*.pyd
+*.dylib
+
+# Build and packaging output.
+dist/
+wheels/
+target/
+
+# Local virtual environments.
+.venv/
+venv/

pamoja_kit-0.1.17/LICENSE-MIT

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

pamoja_kit-0.1.17/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: pamoja-kit
+Version: 0.1.17
+Summary: Plain-language helper math: smoothing, calibration, PID and thermostat control, trend and surge prediction, rolling windows, kinematics, and geo.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/kit.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: iot,kit,pamoja,robotics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pamoja-native==0.1.17
+Description-Content-Type: text/markdown
+
+# pamoja-kit
+
+Plain-language helper math: smoothing, calibration, PID and thermostat control, trend and surge prediction, rolling windows, kinematics, and geo. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/kit.html)
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/kit.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+
+## Install
+
+```sh
+pip install pamoja-kit
+```
+
+```python
+from pamoja import kit
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/kit.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/kit.py):
+
+```python
+from pamoja.kit import Calibration, Median, Thermostat
+
+# A 4-20 mA process loop carries the level as a current: 4 mA is empty and 20 mA is full,
+# so the span is 16 mA and mid-scale is 12 mA, not 10.
+level = Calibration.two_point(4.0, 0.0, 20.0, 100.0)
+print(f"12 mA is {level.apply(12.0)}% full, 4 mA is {level.apply(4.0)}%")
+
+# The live zero is what makes a broken loop detectable: 0 mA is off the bottom of the
+# scale rather than an empty tank.
+broken = level.apply(0.0)
+print(f"a dead loop reads {broken}%, which is not a level at all")
+
+# A median window drops that sample outright, where an average would blend a quarter of
+# the range into every reading after it.
+filtered = Median()
+percent = 0.0
+for milliamps in (12.0, 12.0, 0.0, 12.0, 12.0):
+    percent = level.apply(filtered.update(milliamps))
+print(f"through the dropout, the level held at {percent}%")
+
+# A refill pump runs when the level falls below the deadband, which is the direction
+# heating names; nothing about it is specific to temperature. The deadband stops a level
+# sitting on the threshold from chattering the contactor.
+pump = Thermostat.heating(50.0, 10.0)
+for reading in (percent, 38.0, 45.0, 62.0):
+    running = "on" if pump.update(reading) else "off"
+    print(f"at {reading}% the pump is {running}")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-kit`](https://crates.io/crates/pamoja-kit) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_kit/index.html), [docs.rs](https://docs.rs/pamoja-kit), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-kit) |
+| TypeScript | [`@pamoja/kit`](https://www.npmjs.com/package/@pamoja/kit) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_kit.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-kit) |
+| Python | [`pamoja-kit`](https://pypi.org/project/pamoja-kit/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/kit.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-kit) |
+| C# | [`Pamoja.Kit`](https://www.nuget.org/packages/Pamoja.Kit) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Kit.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-kit) |
+
+## Documentation
+
+- [`pamoja.kit` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/kit.html), every class and function in this module.
+- [The Helpers guide](https://pamoja.molex.cloud/docs/guides/kit.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_kit-0.1.17/README.md

@@ -0,0 +1,74 @@
+# pamoja-kit
+
+Plain-language helper math: smoothing, calibration, PID and thermostat control, trend and surge prediction, rolling windows, kinematics, and geo. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/kit.html)
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/kit.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+
+## Install
+
+```sh
+pip install pamoja-kit
+```
+
+```python
+from pamoja import kit
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/kit.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/kit.py):
+
+```python
+from pamoja.kit import Calibration, Median, Thermostat
+
+# A 4-20 mA process loop carries the level as a current: 4 mA is empty and 20 mA is full,
+# so the span is 16 mA and mid-scale is 12 mA, not 10.
+level = Calibration.two_point(4.0, 0.0, 20.0, 100.0)
+print(f"12 mA is {level.apply(12.0)}% full, 4 mA is {level.apply(4.0)}%")
+
+# The live zero is what makes a broken loop detectable: 0 mA is off the bottom of the
+# scale rather than an empty tank.
+broken = level.apply(0.0)
+print(f"a dead loop reads {broken}%, which is not a level at all")
+
+# A median window drops that sample outright, where an average would blend a quarter of
+# the range into every reading after it.
+filtered = Median()
+percent = 0.0
+for milliamps in (12.0, 12.0, 0.0, 12.0, 12.0):
+    percent = level.apply(filtered.update(milliamps))
+print(f"through the dropout, the level held at {percent}%")
+
+# A refill pump runs when the level falls below the deadband, which is the direction
+# heating names; nothing about it is specific to temperature. The deadband stops a level
+# sitting on the threshold from chattering the contactor.
+pump = Thermostat.heating(50.0, 10.0)
+for reading in (percent, 38.0, 45.0, 62.0):
+    running = "on" if pump.update(reading) else "off"
+    print(f"at {reading}% the pump is {running}")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-kit`](https://crates.io/crates/pamoja-kit) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_kit/index.html), [docs.rs](https://docs.rs/pamoja-kit), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-kit) |
+| TypeScript | [`@pamoja/kit`](https://www.npmjs.com/package/@pamoja/kit) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_kit.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-kit) |
+| Python | [`pamoja-kit`](https://pypi.org/project/pamoja-kit/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/kit.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-kit) |
+| C# | [`Pamoja.Kit`](https://www.nuget.org/packages/Pamoja.Kit) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Kit.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-kit) |
+
+## Documentation
+
+- [`pamoja.kit` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/kit.html), every class and function in this module.
+- [The Helpers guide](https://pamoja.molex.cloud/docs/guides/kit.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_kit-0.1.17/pamoja/kit/__init__.py

@@ -0,0 +1,137 @@
+"""Idiomatic helper-math facade.
+
+The helpers are named for the goal rather than the technique, with the real
+algorithm one layer down: smooth a noisy reading, hold a value with a PID, warn
+before a tank runs dry, and notice when a tracked point leaves its area.
+
+They are synchronous and allocation-free in the core, so this module re-exports
+the generated classes rather than wrapping them. What it adds is a
+:class:`Coordinate` for the geo helpers, so a fix travels as one value instead of
+a pair of loose floats, and a :class:`Boundary` enum for the crossing states.
+"""
+
+from __future__ import annotations
+
+import enum
+from typing import NamedTuple
+
+from pamoja._native import Anomaly, Median, Trend, Window
+from pamoja._native import window_capacity as _window_capacity
+from pamoja._native import Calibration, Debounce, Depletion, Kalman, Pid, Ramp, Smoother, Surge, Thermostat
+from pamoja._native import Geofence as _NativeGeofence
+from pamoja._native import bearing_between as _bearing_between
+from pamoja._native import deadband
+from pamoja._native import distance_between as _distance_between
+
+#: How many readings a windowed helper keeps.
+WINDOW_CAPACITY = _window_capacity()
+
+__all__ = [
+    "Window",
+    "WINDOW_CAPACITY",
+    "Trend",
+    "Median",
+    "Anomaly",
+    "Boundary",
+    "Calibration",
+    "Coordinate",
+    "Debounce",
+    "Depletion",
+    "Geofence",
+    "Kalman",
+    "Pid",
+    "Ramp",
+    "Smoother",
+    "Surge",
+    "Thermostat",
+    "bearing_between",
+    "deadband",
+    "distance_between",
+]
+
+
+class Coordinate(NamedTuple):
+    """A latitude and longitude in degrees."""
+
+    #: Degrees north of the equator, negative for south.
+    latitude: float
+    #: Degrees east of the prime meridian, negative for west.
+    longitude: float
+
+
+class Boundary(str, enum.Enum):
+    """Where a fix sits relative to a :class:`Geofence`, including a crossing."""
+
+    #: The fix is inside the fence and was inside before, or is the first fix inside.
+    INSIDE = "Inside"
+    #: The fix is outside the fence and was outside before, or is the first fix outside.
+    OUTSIDE = "Outside"
+    #: The fix just crossed from inside to outside: the moment to raise a breach alert.
+    EXITED = "Exited"
+    #: The fix just crossed from outside back inside.
+    ENTERED = "Entered"
+
+
+class Geofence:
+    """Keeps a tracked point inside an area, and notices when it leaves.
+
+    A fence is a centre and a radius; feeding it successive fixes reports whether
+    each is inside or outside and, crucially, the single fix that crossed, so an
+    alert fires once on the crossing rather than on every fix while away.
+
+    Example::
+
+        pen = Geofence(Coordinate(-1.2921, 36.8219), 50.0)
+        pen.update(Coordinate(-1.2921, 36.8219))  # Boundary.INSIDE
+        pen.update(Coordinate(-1.2930, 36.8219))  # Boundary.EXITED
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, center: Coordinate, radius_m: float) -> None:
+        """Create a circular fence around a centre fix.
+
+        :param center: The centre of the fence.
+        :param radius_m: The fence radius, in metres.
+        """
+        self._native = _NativeGeofence(center.latitude, center.longitude, radius_m)
+
+    def update(self, point: Coordinate) -> Boundary:
+        """Feed a fix in and report where it sits, including a single crossing.
+
+        :param point: The latest fix.
+        :returns: The boundary state for this fix.
+        """
+        return Boundary(self._native.update(point.latitude, point.longitude))
+
+    def contains(self, point: Coordinate) -> bool:
+        """Report whether a fix lies inside, without recording a crossing.
+
+        :param point: The fix to test.
+        :returns: ``True`` if the fix is inside the fence.
+        """
+        return self._native.contains(point.latitude, point.longitude)
+
+
+def distance_between(origin: Coordinate, destination: Coordinate) -> float:
+    """Return the great-circle distance between two coordinates, in metres.
+
+    :param origin: The coordinate to measure from.
+    :param destination: The coordinate to measure to.
+    :returns: The distance in metres.
+    """
+    return _distance_between(
+        origin.latitude, origin.longitude, destination.latitude, destination.longitude
+    )
+
+
+def bearing_between(origin: Coordinate, destination: Coordinate) -> float:
+    """Return the initial bearing from one coordinate to another, in degrees.
+
+    :param origin: The coordinate to measure from.
+    :param destination: The coordinate to measure to.
+    :returns: The bearing in degrees, clockwise from north.
+    """
+    return _bearing_between(
+        origin.latitude, origin.longitude, destination.latitude, destination.longitude
+    )

pamoja_kit-0.1.17/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-kit"
+version = "0.1.17"
+description = "Plain-language helper math: smoothing, calibration, PID and thermostat control, trend and surge prediction, rolling windows, kinematics, and geo."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "kit"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.1.17",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/kit.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]