hgraph-analytics 0.8.5__tar.gz

hgraph_analytics-0.8.5/.gitignore

@@ -0,0 +1,7 @@
+/build/
+/build-*/
+/cmake-build-*/
+/dist/
+/.venv/
+__pycache__/
+*.pyc

hgraph_analytics-0.8.5/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.8.0
+
+- Move `diff`, `count`, `clip`, `ewma`, `center_of_mass_to_alpha`,
+  `span_to_alpha`, and `pct_change` from core into `hgraph-analytics`.
+- Extend the C++-first `pct_change` graph with observation-count periods and an
+  explicit divide-by-zero policy.

hgraph_analytics-0.8.5/CMakeLists.txt

@@ -0,0 +1,117 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(hgraph_analytics VERSION 0.8.0 LANGUAGES CXX)
+
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+include(CTest)
+
+option(HGRAPH_ANALYTICS_BUILD_PYTHON "Build the optional Python authoring bridge" OFF)
+option(HGRAPH_ANALYTICS_WARNINGS_AS_ERRORS
+    "Treat hgraph-analytics compiler warnings as errors"
+    ${HGRAPH_WARNINGS_AS_ERRORS})
+
+if(HGRAPH_ANALYTICS_BUILD_PYTHON)
+    find_package(Python 3.12 COMPONENTS
+        Interpreter Development.Module Development.SABIModule REQUIRED)
+endif()
+
+if(NOT TARGET hgraph::core)
+    find_package(hgraph CONFIG REQUIRED)
+endif()
+
+if(HGRAPH_ANALYTICS_BUILD_PYTHON)
+    get_target_property(_hgraph_analytics_core_links hgraph::options INTERFACE_LINK_LIBRARIES)
+    if("Python::Python" IN_LIST _hgraph_analytics_core_links)
+        message(FATAL_ERROR
+            "The selected hgraph SDK embeds a specific Python interpreter and "
+            "cannot produce an ABI3 hgraph-analytics wheel; use the SDK installed "
+            "by an hgraph stable-ABI wheel")
+    endif()
+endif()
+
+add_library(hgraph_analytics
+    src/operators.cpp
+)
+add_library(hgraph::analytics ALIAS hgraph_analytics)
+
+get_target_property(HGRAPH_ANALYTICS_LIBRARY_TYPE hgraph_analytics TYPE)
+if(HGRAPH_ANALYTICS_LIBRARY_TYPE STREQUAL "STATIC_LIBRARY")
+    target_compile_definitions(hgraph_analytics PUBLIC HGRAPH_ANALYTICS_STATIC_DEFINE)
+endif()
+
+target_compile_features(hgraph_analytics PUBLIC cxx_std_23)
+target_link_libraries(hgraph_analytics PUBLIC hgraph::core)
+target_include_directories(hgraph_analytics
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
+set_target_properties(hgraph_analytics PROPERTIES
+    EXPORT_NAME analytics
+    POSITION_INDEPENDENT_CODE ON
+)
+
+if(MSVC)
+    target_compile_options(hgraph_analytics PRIVATE /W4 /permissive-)
+    if(HGRAPH_ANALYTICS_WARNINGS_AS_ERRORS)
+        target_compile_options(hgraph_analytics PRIVATE /WX)
+    endif()
+else()
+    target_compile_options(hgraph_analytics PRIVATE -Wall -Wextra -Wpedantic)
+    if(HGRAPH_ANALYTICS_WARNINGS_AS_ERRORS)
+        target_compile_options(hgraph_analytics PRIVATE -Werror)
+    endif()
+endif()
+
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
+
+if(HGRAPH_ANALYTICS_BUILD_PYTHON)
+    if(NOT COMMAND hgraph_add_python_module OR NOT TARGET hgraph::nanobind)
+        message(FATAL_ERROR
+            "HGRAPH_ANALYTICS_BUILD_PYTHON requires a Python-enabled installed hgraph SDK")
+    endif()
+    hgraph_add_python_module(_hgraph_analytics STABLE_ABI NOMINSIZE src/python_module.cpp)
+    target_link_libraries(_hgraph_analytics PRIVATE hgraph::analytics)
+    install(TARGETS _hgraph_analytics
+        COMPONENT Python
+        LIBRARY DESTINATION hgraph_analytics
+        RUNTIME DESTINATION hgraph_analytics
+    )
+endif()
+
+install(TARGETS hgraph_analytics
+    EXPORT hgraphAnalyticsTargets
+    COMPONENT Development
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    COMPONENT Development FILES_MATCHING PATTERN "*.h")
+
+write_basic_package_version_file(
+    "${PROJECT_BINARY_DIR}/hgraph-analyticsConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+)
+configure_package_config_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/hgraph-analyticsConfig.cmake.in"
+    "${PROJECT_BINARY_DIR}/hgraph-analyticsConfig.cmake"
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/hgraph-analytics
+)
+
+install(EXPORT hgraphAnalyticsTargets
+    FILE hgraphAnalyticsTargets.cmake
+    NAMESPACE hgraph::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/hgraph-analytics
+    COMPONENT Development
+)
+install(FILES
+    "${PROJECT_BINARY_DIR}/hgraph-analyticsConfig.cmake"
+    "${PROJECT_BINARY_DIR}/hgraph-analyticsConfigVersion.cmake"
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/hgraph-analytics
+    COMPONENT Development
+)

hgraph_analytics-0.8.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Howard Henson
+
+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.

hgraph_analytics-0.8.5/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.2
+Name: hgraph-analytics
+Version: 0.8.5
+Summary: C++-first numerical analytics for hgraph
+License: MIT
+Project-URL: Homepage, https://github.com/hhenson/hgraph
+Project-URL: Repository, https://github.com/hhenson/hgraph.git
+Requires-Python: >=3.12
+Requires-Dist: hgraph>=0.8.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Description-Content-Type: text/markdown
+
+# hgraph-analytics
+
+C++-first numerical analytics for hgraph. The package owns the numerical
+analytical family migrated from core—`diff`, `count`, `clip`, `ewma`, and
+`pct_change`—plus the EWMA parameter conversion helpers.
+
+```python
+import hgraph as hg
+import hgraph_analytics as hga
+
+change = hga.pct_change(
+    value,
+    period=12,
+    divide_by_zero=hg.DivideByZero.NAN,
+)
+
+bounded = hga.clip(change, -0.25, 0.25)
+smoothed = hga.ewma(bounded, alpha=0.2)
+```
+
+The result is fractional: `0.05` denotes five percent. `period` counts valid
+source observations and must be positive. The operator does not infer
+dataframe ordering, elapsed-time sampling, market sessions, or financial price
+adjustment.
+
+Native consumers link `hgraph::analytics`, call
+`hgraph::analytics::register_analytics_operators()`, and wire
+the markers in `hgraph::analytics`, including `diff`, `count`, `clip`, `ewma`,
+and `pct_change`.
+
+See the hgraph user-guide migration note for the complete Python and C++ name
+mapping from the former core API.

hgraph_analytics-0.8.5/README.md

@@ -0,0 +1,32 @@
+# hgraph-analytics
+
+C++-first numerical analytics for hgraph. The package owns the numerical
+analytical family migrated from core—`diff`, `count`, `clip`, `ewma`, and
+`pct_change`—plus the EWMA parameter conversion helpers.
+
+```python
+import hgraph as hg
+import hgraph_analytics as hga
+
+change = hga.pct_change(
+    value,
+    period=12,
+    divide_by_zero=hg.DivideByZero.NAN,
+)
+
+bounded = hga.clip(change, -0.25, 0.25)
+smoothed = hga.ewma(bounded, alpha=0.2)
+```
+
+The result is fractional: `0.05` denotes five percent. `period` counts valid
+source observations and must be positive. The operator does not infer
+dataframe ordering, elapsed-time sampling, market sessions, or financial price
+adjustment.
+
+Native consumers link `hgraph::analytics`, call
+`hgraph::analytics::register_analytics_operators()`, and wire
+the markers in `hgraph::analytics`, including `diff`, `count`, `clip`, `ewma`,
+and `pct_change`.
+
+See the hgraph user-guide migration note for the complete Python and C++ name
+mapping from the former core API.

hgraph_analytics-0.8.5/cmake/hgraph-analyticsConfig.cmake.in

@@ -0,0 +1,8 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+find_dependency(hgraph CONFIG)
+
+include("${CMAKE_CURRENT_LIST_DIR}/hgraphAnalyticsTargets.cmake")
+
+check_required_components(hgraph-analytics)

hgraph_analytics-0.8.5/include/hgraph/analytics/export.h

@@ -0,0 +1,16 @@
+#ifndef HGRAPH_ANALYTICS_EXPORT_H
+#define HGRAPH_ANALYTICS_EXPORT_H
+
+#if defined(HGRAPH_ANALYTICS_STATIC_DEFINE)
+    #define HGRAPH_ANALYTICS_EXPORT
+#elif defined(_WIN32)
+    #if defined(hgraph_analytics_EXPORTS)
+        #define HGRAPH_ANALYTICS_EXPORT __declspec(dllexport)
+    #else
+        #define HGRAPH_ANALYTICS_EXPORT __declspec(dllimport)
+    #endif
+#else
+    #define HGRAPH_ANALYTICS_EXPORT __attribute__((visibility("default")))
+#endif
+
+#endif  // HGRAPH_ANALYTICS_EXPORT_H

hgraph_analytics-0.8.5/include/hgraph/analytics/operators.h

@@ -0,0 +1,124 @@
+#ifndef HGRAPH_ANALYTICS_OPERATORS_H
+#define HGRAPH_ANALYTICS_OPERATORS_H
+
+#include <hgraph/analytics/export.h>
+
+#include <hgraph/lib/std/operators/arithmetic.h>
+#include <hgraph/types/operator_dispatch.h>
+#include <hgraph/types/primitive_types.h>
+#include <hgraph/types/static_schema.h>
+
+namespace hgraph::analytics
+{
+    /** Subtract the preceding valid observation from the current observation.
+        The first valid observation warms the retained prior-value state and does
+        not produce output. Invalid cycles neither update that state nor trigger.
+        @param ts Integer or floating-point input stream.
+        @return Successive differences with the same scalar type as ``ts``.
+        @par Python example
+        @code{.py}
+        import hgraph_analytics as hga
+        change = hga.diff(price)
+        @endcode */
+    struct diff
+        : Operator<"hgraph.analytics.diff", In<"ts", TS<ScalarVar<"T">>>,
+                   Out<TS<ScalarVar<"T">>>>
+    {
+    };
+
+    /** Count valid input ticks cumulatively, with an optional reset signal.
+        A same-cycle reset is applied before a source tick is admitted. A reset-only
+        cycle clears state without producing output.
+        @param ts Signal or stream whose valid ticks are counted; values are ignored.
+        @param reset Optional signal that restarts the count from one on the next
+                     same-cycle or subsequent source tick.
+        @return Running integer tick count.
+        @par Python example
+        @code{.py}
+        import hgraph_analytics as hga
+        session_count = hga.count(updates, reset=session_start)
+        @endcode */
+    struct count
+        : Operator<"hgraph.analytics.count", In<"ts", SIGNAL>, Out<TS<Int>>>
+    {
+    };
+
+    /** Constrain each numeric observation to an inclusive range.
+        Bounds are fixed at wiring time and must share the resolved integer or
+        floating-point type of the input. The node has no warm-up state and emits
+        for every valid source tick.
+        @param ts Numeric input stream.
+        @param min Lower inclusive bound.
+        @param max Upper inclusive bound.
+        @return ``min`` below the range, ``max`` above it, otherwise ``ts``.
+        @throws std::invalid_argument during node start when ``min > max``.
+        @par Python example
+        @code{.py}
+        import hgraph_analytics as hga
+        bounded = hga.clip(ratio, 0.0, 1.0)
+        @endcode */
+    struct clip
+        : Operator<"hgraph.analytics.clip", In<"ts", TS<ScalarVar<"T">>>,
+                   Scalar<"min", ScalarVar<"T">>, Scalar<"max", ScalarVar<"T">>,
+                   Out<TS<ScalarVar<"T">>>>
+    {
+    };
+
+    /** Compute an exponentially weighted moving average of floating observations.
+        The first valid observation initializes the retained average. Each later
+        valid tick emits ``alpha * current + (1 - alpha) * previous``. Invalid
+        cycles neither update state nor trigger output.
+        @param ts Floating-point input stream.
+        @param alpha Wiring-time smoothing factor. Values are applied as supplied
+                     for compatibility with the migrated 0.8 operator.
+        @return Running exponentially weighted moving average.
+        @par Python example
+        @code{.py}
+        import hgraph_analytics as hga
+        smoothed = hga.ewma(price, alpha=0.2)
+        @endcode */
+    struct ewma
+        : Operator<"hgraph.analytics.ewma", In<"ts", TS<Float>>,
+                   Scalar<"alpha", Float>, Out<TS<Float>>>
+    {
+    };
+
+    /** Compute fractional change from an earlier valid observation.
+        For a positive observation-count ``period``, the result is
+        ``(current - prior) / prior``. The first ``period`` valid observations
+        produce no output. Invalid source cycles are not counted, and the graph
+        ticks only when a valid source observation arrives.
+        @param ts Integer or floating-point input stream.
+        @param period Positive valid-observation count fixed at wiring time;
+                      defaults to one. Durations and negative look-ahead periods
+                      are not supported.
+        @param divide_by_zero Wiring-time policy applied when the prior value is
+                              zero; defaults to ``DivideByZero::Error``.
+        @return Floating-point fractional change. ``0.05`` denotes five percent.
+        @throws std::invalid_argument while wiring when ``period`` is not positive.
+        @throws std::domain_error during evaluation for a zero prior value when
+                                  ``divide_by_zero`` is ``Error``.
+        @par Python example
+        @code{.py}
+        import hgraph as hg
+        import hgraph_analytics as hga
+
+        change = hga.pct_change(price, period=12,
+                                divide_by_zero=hg.DivideByZero.NAN)
+        @endcode */
+    struct pct_change
+        : Operator<"hgraph.analytics.pct_change",
+                   In<"ts", TS<ScalarVar<"T">>>,
+                   Scalar<"period", Int>,
+                   Scalar<"divide_by_zero", stdlib::DivideByZero>,
+                   Out<TS<Float>>>
+    {
+    };
+
+    /** Register the hgraph-analytics overloads in the current hgraph registry.
+        Call once per registry lifetime after core standard operators are
+        available and before wiring analytics graphs. */
+    HGRAPH_ANALYTICS_EXPORT void register_analytics_operators();
+}  // namespace hgraph::analytics
+
+#endif  // HGRAPH_ANALYTICS_OPERATORS_H

hgraph_analytics-0.8.5/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = [
+    "scikit-build-core>=0.11",
+    "nanobind==2.13.0",
+    "pyarrow>=25,<26",
+    "hgraph>=0.8.0",
+]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "hgraph-analytics"
+version = "0.8.5"
+description = "C++-first numerical analytics for hgraph"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+dependencies = ["hgraph>=0.8.0"]
+
+[project.urls]
+Homepage = "https://github.com/hhenson/hgraph"
+Repository = "https://github.com/hhenson/hgraph.git"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.scikit-build]
+cmake.source-dir = "."
+cmake.args = [
+    "-DHGRAPH_ANALYTICS_BUILD_PYTHON=ON",
+    "-DBUILD_TESTING=OFF",
+]
+install.components = ["Python", "Development"]
+wheel.packages = ["python/hgraph_analytics"]
+wheel.py-api = "cp312"
+sdist.include = [
+    "CMakeLists.txt",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "cmake/**",
+    "include/**",
+    "python/**",
+    "src/**",
+    "tests/**",
+    "test_package/**",
+    "tools/**",
+]

hgraph_analytics-0.8.5/python/hgraph_analytics/__init__.py

@@ -0,0 +1,88 @@
+"""C++-first numerical analytics for hgraph."""
+
+from __future__ import annotations
+
+from hgraph import DivideByZero, NUMBER, SIGNAL, TS, operator_function
+
+from . import _hgraph_analytics as _native
+
+
+_diff = operator_function("hgraph.analytics.diff")
+_count = operator_function("hgraph.analytics.count")
+_clip = operator_function("hgraph.analytics.clip")
+_ewma = operator_function("hgraph.analytics.ewma")
+_pct_change = operator_function("hgraph.analytics.pct_change")
+
+
+def diff(ts: TS[NUMBER]) -> TS[NUMBER]:
+    """Return the difference from the preceding valid observation."""
+
+    return _diff(ts)
+
+
+def count(ts: SIGNAL, reset: SIGNAL = None) -> TS[int]:
+    """Count valid input ticks, restarting when ``reset`` ticks."""
+
+    return _count(ts) if reset is None else _count(ts, reset)
+
+
+def clip(ts: TS[NUMBER], min_: NUMBER, max_: NUMBER) -> TS[NUMBER]:
+    """Constrain each input value to the inclusive ``[min_, max_]`` range."""
+
+    return _clip(ts, min_, max_)
+
+
+def ewma(ts: TS[float], alpha: float) -> TS[float]:
+    """Return the exponentially weighted moving average of ``ts``."""
+
+    return _ewma(ts, alpha)
+
+
+def center_of_mass_to_alpha(com: float) -> float:
+    """Convert a positive center of mass to an EWMA smoothing factor."""
+
+    if com <= 0:
+        raise ValueError(f"Center of mass must be positive, got {com}")
+    return 1.0 / (com + 1.0)
+
+
+def span_to_alpha(span: float) -> float:
+    """Convert a positive span to an EWMA smoothing factor."""
+
+    if span <= 0:
+        raise ValueError(f"Span must be positive, got {span}")
+    return 2.0 / (span + 1.0)
+
+
+def pct_change(
+    ts: TS[NUMBER],
+    period: int = 1,
+    divide_by_zero: DivideByZero = DivideByZero.ERROR,
+) -> TS[float]:
+    """Return fractional change from ``period`` valid observations earlier.
+
+    ``0.05`` denotes five percent. The first ``period`` observations do not
+    produce output, invalid input cycles are not counted, and output triggers
+    only on a valid input tick. ``period`` is a positive wiring-time observation
+    count and defaults to one. ``divide_by_zero`` is a wiring-time policy for a
+    zero prior value and defaults to ``DivideByZero.ERROR``. The retained state
+    is the core lag history for ``period`` observations.
+
+    A non-positive period raises ``WiringError`` while wiring. A zero prior
+    raises during evaluation under the default division policy. This operator
+    does not infer elapsed-time, dataframe-row, sampling, or financial-return
+    semantics.
+    """
+
+    return _pct_change(ts, period, divide_by_zero)
+
+
+__all__ = [
+    "center_of_mass_to_alpha",
+    "clip",
+    "count",
+    "diff",
+    "ewma",
+    "pct_change",
+    "span_to_alpha",
+]

hgraph_analytics-0.8.5/python/hgraph_analytics/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

hgraph_analytics-0.8.5/python/tests/test_distribution_audit.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import pytest
+
+ANALYTICS_ROOT = Path(__file__).resolve().parents[2]
+AUDIT_SCRIPT = ANALYTICS_ROOT / "tools/audit_distribution.py"
+
+
+@pytest.mark.parametrize("library_directory", ["lib", "lib64"])
+def test_wheel_audit_accepts_platform_library_directories(
+    tmp_path: Path, library_directory: str
+):
+    wheel = tmp_path / "hgraph_analytics-0.0.0-cp312-abi3-any.whl"
+    files = {
+        "hgraph_analytics/__init__.py": "",
+        "hgraph_analytics/py.typed": "",
+        "hgraph_analytics/_hgraph_analytics.abi3.so": "",
+        "include/hgraph/analytics/operators.h": "",
+        f"{library_directory}/libhgraph_analytics.a": "",
+        f"{library_directory}/cmake/hgraph-analytics/hgraph-analyticsConfig.cmake": "",
+        f"{library_directory}/cmake/hgraph-analytics/hgraphAnalyticsTargets.cmake": "",
+        "hgraph_analytics-0.0.0.dist-info/METADATA": (
+            "Metadata-Version: 2.2\n"
+            "Name: hgraph-analytics\n"
+            "Version: 0.0.0\n"
+            "Requires-Dist: hgraph\n"
+        ),
+    }
+    with zipfile.ZipFile(wheel, "w") as archive:
+        for name, contents in files.items():
+            archive.writestr(name, contents)
+
+    subprocess.run([sys.executable, AUDIT_SCRIPT, wheel], check=True)

hgraph_analytics-0.8.5/python/tests/test_pct_change.py

@@ -0,0 +1,106 @@
+import math
+
+import pytest
+
+import hgraph as hg
+import hgraph_analytics as hga
+
+
+def test_migrated_analytical_helpers():
+    assert hga.center_of_mass_to_alpha(1.0) == 0.5
+    assert hga.span_to_alpha(1.0) == 1.0
+    with pytest.raises(ValueError, match="Center of mass must be positive"):
+        hga.center_of_mass_to_alpha(0.0)
+    with pytest.raises(ValueError, match="Span must be positive"):
+        hga.span_to_alpha(0.0)
+
+
+def test_diff_count_clip_and_ewma():
+    assert hg.eval_node(hga.diff, [1, 2, 4, 7]) == [None, 1, 2, 3]
+    assert hg.eval_node(hga.count, [3, None, 2, 1]) == [1, None, 2, 3]
+    assert hg.eval_node(
+        hga.count,
+        [3, 2, 1],
+        reset=[None, True, None],
+        resolution_dict={"ts": hg.TS[int], "reset": hg.TS[bool]},
+    ) == [1, 1, 2]
+    assert hg.eval_node(
+        hga.count,
+        [3, None, 2, 1],
+        reset=[None, True, None],
+        resolution_dict={"ts": hg.TS[int], "reset": hg.TS[bool]},
+    ) == [1, None, 1, 2]
+    assert hg.eval_node(hga.clip, [-1, 1, 3], 0, 2) == [0, 1, 2]
+    assert hg.eval_node(hga.clip, [-1.0, 0.5, 2.0], 0.0, 1.0) == [
+        0.0,
+        0.5,
+        1.0,
+    ]
+    assert hg.eval_node(hga.ewma, [1.0, 2.0, 3.0, 4.0], 0.5) == [
+        1.0,
+        1.5,
+        2.25,
+        3.125,
+    ]
+
+
+def test_count_accepts_a_mapped_dictionary_signal():
+    @hg.graph
+    def app(tsd: hg.TSD[int, hg.TS[int]]) -> hg.TS[int]:
+        return hga.count(hg.map_(lambda value: value + 1, tsd))
+
+    assert hg.eval_node(
+        app,
+        [{1: 10}, {2: 20}, None, {1: hg.REMOVE}],
+    ) == [1, 2, None, 3]
+
+
+def test_clip_rejects_reversed_bounds():
+    with pytest.raises(Exception, match="min must be <= max"):
+        hg.eval_node(hga.clip, [1.0], 1.0, -1.0)
+
+
+def test_default_and_sparse_observations():
+    assert hg.eval_node(hga.pct_change, [1, 2, 3]) == [None, 1.0, 0.5]
+    assert hg.eval_node(hga.pct_change, [1, None, 2]) == [None, None, 1.0]
+
+
+def test_longer_period_and_float_input():
+    result = hg.eval_node(hga.pct_change, [10.0, 11.0, 12.0, 15.0], 2)
+    assert result[:2] == [None, None]
+    assert result[2:] == pytest.approx([0.2, 4.0 / 11.0])
+
+
+@pytest.mark.parametrize(
+    ("policy", "expected"),
+    [
+        (hg.DivideByZero.NAN, math.nan),
+        (hg.DivideByZero.ZERO, 0.0),
+        (hg.DivideByZero.ONE, 1.0),
+        (hg.DivideByZero.NONE, None),
+    ],
+)
+def test_zero_denominator_policies(policy, expected):
+    result = hg.eval_node(hga.pct_change, [0.0, 1.0, 2.0], 1, policy)
+    assert result[0] is None
+    if math.isnan(expected) if isinstance(expected, float) else False:
+        assert math.isnan(result[1])
+    else:
+        assert result[1] == expected
+    assert result[2] == 1.0
+
+
+def test_zero_denominator_error_is_the_default():
+    with pytest.raises(Exception, match="division by zero"):
+        hg.eval_node(hga.pct_change, [0.0, 1.0])
+
+
+@pytest.mark.parametrize("period", [0, -1])
+def test_period_must_be_positive(period):
+    with pytest.raises(hg.WiringError, match="period must be positive"):
+        hg.eval_node(hga.pct_change, [1.0, 2.0], period)
+
+
+def test_public_signature_and_fractional_units():
+    assert hga.pct_change.__name__ == "pct_change"
+    assert hg.eval_node(hga.pct_change, [100.0, 105.0]) == [None, 0.05]

hgraph_analytics-0.8.5/src/operators.cpp

@@ -0,0 +1,148 @@
+#include <hgraph/analytics/operators.h>
+
+#include <hgraph/lib/std/operators/arithmetic.h>
+#include <hgraph/lib/std/operators/stream.h>
+#include <hgraph/types/graph_wiring.h>
+#include <hgraph/types/value/value.h>
+
+#include <algorithm>
+#include <stdexcept>
+#include <string_view>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace hgraph::analytics
+{
+    namespace
+    {
+        template <typename T>
+        struct diff_impl
+        {
+            static void eval(In<"ts", TS<T>> ts, RecordableState<TS<T>> prior,
+                             Out<TS<T>> out)
+            {
+                // Adjacent difference is O(1) per tick and retains only the
+                // preceding valid observation. State is advanced after output
+                // so both operands belong to consecutive accepted observations.
+                if (prior.valid()) { out.set(ts.value() - prior.value().template checked_as<T>()); }
+                prior.set(ts.value());
+            }
+        };
+
+        struct count_impl
+        {
+            static void eval(In<"ts", SIGNAL> ts, State<Int> running_count,
+                             Out<TS<Int>> out)
+            {
+                static_cast<void>(ts);
+                const Int next = running_count.get() + 1;
+                running_count.set(next);
+                out.set(next);
+            }
+        };
+
+        struct count_reset_impl
+        {
+            static void eval(In<"ts", SIGNAL, InputValidity::Unchecked> ts,
+                             In<"reset", SIGNAL, InputValidity::Unchecked> reset,
+                             State<Int> running_count, Out<TS<Int>> out)
+            {
+                // Reset wins on a shared cycle, then that cycle's source tick
+                // becomes observation one. A reset by itself intentionally does
+                // not tick the output.
+                if (reset.modified()) { running_count.set(Int{0}); }
+                if (!ts.modified()) { return; }
+                const Int next = running_count.get() + 1;
+                running_count.set(next);
+                out.set(next);
+            }
+        };
+
+        template <typename T>
+        struct clip_impl
+        {
+            static void start(Scalar<"min", T> minimum, Scalar<"max", T> maximum)
+            {
+                if (minimum.value() > maximum.value())
+                {
+                    throw std::invalid_argument(
+                        "hgraph.analytics.clip: min must be <= max");
+                }
+            }
+
+            static void eval(In<"ts", TS<T>> ts, Scalar<"min", T> minimum,
+                             Scalar<"max", T> maximum, Out<TS<T>> out)
+            {
+                out.set(std::clamp(ts.value(), minimum.value(), maximum.value()));
+            }
+        };
+
+        struct ewma_impl
+        {
+            static void eval(In<"ts", TS<Float>> ts, Scalar<"alpha", Float> alpha,
+                             RecordableState<TS<Float>> average, Out<TS<Float>> out)
+            {
+                // This is the migrated core recurrence, kept algebraically
+                // unchanged so the package move cannot alter floating-point
+                // rounding. It is O(1) per tick and initializes from the first
+                // observation.
+                const Float value = average.valid()
+                                        ? alpha.value() * ts.value() +
+                                              (Float{1.0} - alpha.value()) * average.value().checked_as<Float>()
+                                        : ts.value();
+                average.set(value);
+                out.set(value);
+            }
+        };
+
+        template <typename T>
+        struct pct_change_compose
+        {
+            static constexpr auto name = std::is_same_v<T, Int>
+                                             ? "hgraph.analytics.pct_change.int"
+                                             : "hgraph.analytics.pct_change.float";
+
+            static std::vector<std::pair<std::string_view, Value>> defaults()
+            {
+                return {
+                    {"period", Value{Int{1}}},
+                    {"divide_by_zero", Value{stdlib::DivideByZero::Error}},
+                };
+            }
+
+            static Port<TS<Float>> compose(
+                Wiring &w, NamedPort<"ts", TS<T>> ts,
+                Scalar<"period", Int> period,
+                Scalar<"divide_by_zero", stdlib::DivideByZero> divide_by_zero)
+            {
+                if (period.value() <= 0)
+                {
+                    throw std::invalid_argument(
+                        "hgraph.analytics.pct_change: period must be positive");
+                }
+
+                // The retained observation history and readiness contract stay
+                // in core lag. Reusing the same prior port for subtraction and
+                // division guarantees both operations observe one causal anchor.
+                auto prior = wire<stdlib::lag>(w, ts, period.value());
+                auto delta = wire<stdlib::sub_>(w, ts, prior);
+                return wire<stdlib::div_, TS<Float>>(
+                    w, delta, prior, divide_by_zero.value());
+            }
+        };
+    }  // namespace
+
+    void register_analytics_operators()
+    {
+        register_overload<diff, diff_impl<Int>>();
+        register_overload<diff, diff_impl<Float>>();
+        register_overload<count, count_impl>();
+        register_overload<count, count_reset_impl>();
+        register_overload<clip, clip_impl<Int>>();
+        register_overload<clip, clip_impl<Float>>();
+        register_overload<ewma, ewma_impl>();
+        register_graph_overload<pct_change, pct_change_compose<Int>>();
+        register_graph_overload<pct_change, pct_change_compose<Float>>();
+    }
+}  // namespace hgraph::analytics

hgraph_analytics-0.8.5/src/python_module.cpp

@@ -0,0 +1,11 @@
+#include <hgraph/analytics/operators.h>
+
+#include <nanobind/nanobind.h>
+
+namespace nb = nanobind;
+
+NB_MODULE(_hgraph_analytics, module)
+{
+    hgraph::analytics::register_analytics_operators();
+    module.doc() = "Native hgraph-analytics operator registration";
+}

hgraph_analytics-0.8.5/test_package/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(hgraph_analytics_consumer LANGUAGES CXX)
+
+include(CTest)
+
+find_package(hgraph-analytics CONFIG REQUIRED)
+
+add_executable(hgraph_analytics_consumer main.cpp)
+target_compile_features(hgraph_analytics_consumer PRIVATE cxx_std_23)
+target_link_libraries(hgraph_analytics_consumer PRIVATE hgraph::analytics)
+
+# A wheel-installed SDK exposes Python conversion hooks whose symbols are
+# supplied by the host interpreter for extension modules. A standalone native
+# executable using that SDK must embed Python; a Python-disabled native install
+# exports no nanobind target and remains interpreter-free.
+if(TARGET hgraph::nanobind AND NOT TARGET Python::Python)
+    find_package(Python 3.12 COMPONENTS Interpreter Development.Embed REQUIRED)
+endif()
+if(TARGET Python::Python)
+    target_link_libraries(hgraph_analytics_consumer PRIVATE Python::Python)
+endif()
+
+add_test(NAME hgraph_analytics_consumer COMMAND hgraph_analytics_consumer)

hgraph_analytics-0.8.5/test_package/main.cpp

@@ -0,0 +1,40 @@
+#include <hgraph/analytics/operators.h>
+
+#include <hgraph/lib/std/operators/conversion.h>
+#include <hgraph/lib/std/operators/registration.h>
+#include <hgraph/types/graph_wiring.h>
+
+namespace
+{
+    namespace hg = hgraph;
+    namespace hga = hgraph::analytics;
+
+    struct InstalledConsumerGraph
+    {
+        static constexpr auto name = "installed_hgraph_analytics_consumer";
+
+        static void compose(hg::Wiring &w)
+        {
+            auto input = hg::wire<hg::stdlib::const_, hg::TS<hg::Float>>(
+                w, hg::Float{100.0});
+            auto reset = hg::wire<hg::stdlib::const_, hg::TS<hg::Bool>>(
+                w, hg::Bool{false});
+            static_cast<void>(hg::wire<hga::diff>(w, input));
+            static_cast<void>(hg::wire<hga::count>(w, input));
+            static_cast<void>(hg::wire<hga::count>(w, input, reset));
+            static_cast<void>(hg::wire<hga::clip>(
+                w, input, hg::Float{0.0}, hg::Float{200.0}));
+            static_cast<void>(hg::wire<hga::ewma>(w, input, hg::Float{0.2}));
+            static_cast<void>(hg::wire<hga::pct_change, hg::TS<hg::Float>>(
+                w, input, hg::Int{12}, hg::stdlib::DivideByZero::Nan));
+        }
+    };
+}  // namespace
+
+int main()
+{
+    hgraph::stdlib::register_standard_operators();
+    hgraph::analytics::register_analytics_operators();
+    auto graph = hgraph::build_graph<InstalledConsumerGraph>();
+    return graph.node_count() == 0 ? 1 : 0;
+}

hgraph_analytics-0.8.5/tests/CMakeLists.txt

@@ -0,0 +1,17 @@
+add_executable(hgraph_analytics_tests
+    test_pct_change.cpp
+)
+
+target_compile_features(hgraph_analytics_tests PRIVATE cxx_std_23)
+target_link_libraries(hgraph_analytics_tests PRIVATE hgraph::analytics)
+
+if(MSVC)
+    target_compile_options(hgraph_analytics_tests PRIVATE /W4 /permissive-)
+else()
+    target_compile_options(hgraph_analytics_tests PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+add_test(NAME hgraph_analytics_tests COMMAND hgraph_analytics_tests)
+if(COMMAND hgraph_configure_test_runtime_paths)
+    hgraph_configure_test_runtime_paths(hgraph_analytics_tests)
+endif()

hgraph_analytics-0.8.5/tests/test_pct_change.cpp

@@ -0,0 +1,256 @@
+#include <hgraph/analytics/operators.h>
+
+#include <hgraph/lib/std/operators/registration.h>
+#include <hgraph/lib/testing/eval_node.h>
+
+#include <cmath>
+#include <cstddef>
+#include <iostream>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace
+{
+    using namespace hgraph;
+    using namespace hgraph::analytics;
+    using namespace hgraph::testing;
+
+    inline constexpr std::nullopt_t none = std::nullopt;
+
+    template <typename T, typename U>
+    [[nodiscard]] std::optional<T> optional_value(U &&value)
+    {
+        return T{std::forward<U>(value)};
+    }
+
+    template <typename T>
+    [[nodiscard]] std::optional<T> optional_value(std::nullopt_t)
+    {
+        return std::nullopt;
+    }
+
+    template <typename T, typename... Args>
+    [[nodiscard]] std::vector<std::optional<T>> values(Args &&...args)
+    {
+        std::vector<std::optional<T>> output;
+        output.reserve(sizeof...(Args));
+        (output.push_back(optional_value<T>(std::forward<Args>(args))), ...);
+        return output;
+    }
+
+    void require(bool condition, std::string message)
+    {
+        if (!condition) { throw std::runtime_error(std::move(message)); }
+    }
+
+    void require_output(
+        const std::vector<std::optional<Float>> &actual,
+        const std::vector<std::optional<Float>> &expected,
+        const std::string &label)
+    {
+        require(actual.size() == expected.size(), label + ": output size");
+        for (std::size_t index = 0; index < expected.size(); ++index)
+        {
+            require(actual[index].has_value() == expected[index].has_value(),
+                    label + ": readiness at index " + std::to_string(index));
+            if (expected[index].has_value())
+            {
+                require(std::abs(*actual[index] - *expected[index]) <= 1.0e-12,
+                        label + ": value at index " + std::to_string(index));
+            }
+        }
+    }
+
+    template <typename T>
+    void require_value_output(
+        const std::vector<std::optional<Value>> &actual,
+        const std::vector<std::optional<T>> &expected,
+        const std::string &label)
+    {
+        require(actual.size() == expected.size(), label + ": output size");
+        for (std::size_t index = 0; index < expected.size(); ++index)
+        {
+            require(actual[index].has_value() == expected[index].has_value(),
+                    label + ": readiness at index " + std::to_string(index));
+            if (!expected[index].has_value()) { continue; }
+            const T value = actual[index]->view().checked_as<T>();
+            if constexpr (std::is_floating_point_v<T>)
+            {
+                require(std::abs(value - *expected[index]) <= 1.0e-12,
+                        label + ": value at index " + std::to_string(index));
+            }
+            else
+            {
+                require(value == *expected[index],
+                        label + ": value at index " + std::to_string(index));
+            }
+        }
+    }
+
+    struct DefaultIntChange
+    {
+        static constexpr auto name = "analytics_default_int_change";
+
+        static Port<TS<Float>> compose(Wiring &w, Port<TS<Int>> ts)
+        {
+            return wire<pct_change, TS<Float>>(w, ts);
+        }
+    };
+
+    struct TwoPeriodFloatChange
+    {
+        static constexpr auto name = "analytics_two_period_float_change";
+
+        static Port<TS<Float>> compose(Wiring &w, Port<TS<Float>> ts)
+        {
+            return wire<pct_change, TS<Float>>(w, ts, Int{2});
+        }
+    };
+
+    template <stdlib::DivideByZero Policy>
+    struct ZeroPolicyChange
+    {
+        static constexpr auto name = "analytics_zero_policy_change";
+
+        static Port<TS<Float>> compose(Wiring &w, Port<TS<Float>> ts)
+        {
+            return wire<pct_change, TS<Float>>(w, ts, Int{1}, Policy);
+        }
+    };
+
+    struct InvalidPeriodChange
+    {
+        static constexpr auto name = "analytics_invalid_period_change";
+
+        static Port<TS<Float>> compose(Wiring &w, Port<TS<Float>> ts)
+        {
+            return wire<pct_change, TS<Float>>(w, ts, Int{0});
+        }
+    };
+
+    void test_default_and_sparse_observations()
+    {
+        require_output(eval_node<DefaultIntChange>(values<Int>(1, 2, 3)),
+                       {std::nullopt, 1.0, 0.5}, "default period");
+
+        require_output(eval_node<DefaultIntChange>(values<Int>(1, none, 2)),
+                       {std::nullopt, std::nullopt, 1.0}, "sparse observations");
+    }
+
+    void test_period_and_float_input()
+    {
+        require_output(
+            eval_node<TwoPeriodFloatChange>(
+                values<Float>(10.0, 11.0, 12.0, 15.0)),
+            {std::nullopt, std::nullopt, 0.2, 4.0 / 11.0},
+            "two-period change");
+    }
+
+    void test_zero_policies()
+    {
+        const auto nan = eval_node<ZeroPolicyChange<stdlib::DivideByZero::Nan>>(
+            values<Float>(0.0, 1.0));
+        require(nan.size() == 2 && !nan[0].has_value() && nan[1].has_value(),
+                "NaN policy output readiness");
+        require(std::isnan(*nan[1]),
+                "NaN policy result");
+
+        require_output(
+            eval_node<ZeroPolicyChange<stdlib::DivideByZero::Zero>>(
+                values<Float>(0.0, 1.0)),
+            {std::nullopt, 0.0}, "zero policy");
+        require_output(
+            eval_node<ZeroPolicyChange<stdlib::DivideByZero::One>>(
+                values<Float>(0.0, 1.0)),
+            {std::nullopt, 1.0}, "one policy");
+        require_output(
+            eval_node<ZeroPolicyChange<stdlib::DivideByZero::NoTick>>(
+                values<Float>(0.0, 1.0)),
+            {std::nullopt, std::nullopt}, "no-tick policy");
+
+        bool raised = false;
+        try
+        {
+            static_cast<void>(
+                eval_node<ZeroPolicyChange<stdlib::DivideByZero::Error>>(
+                    values<Float>(0.0, 1.0)));
+        }
+        catch (const std::exception &)
+        {
+            raised = true;
+        }
+        require(raised, "Error policy rejects a zero prior value");
+    }
+
+    void test_invalid_period()
+    {
+        bool raised = false;
+        try
+        {
+            static_cast<void>(eval_node<InvalidPeriodChange>(values<Float>(1.0)));
+        }
+        catch (const std::invalid_argument &)
+        {
+            raised = true;
+        }
+        require(raised, "non-positive period is rejected while wiring");
+    }
+
+    void test_migrated_analytical_operators()
+    {
+        require_value_output(eval_node<diff>(values<Int>(1, 2, 4, 7)),
+                             values<Int>(none, 1, 2, 3), "integer diff");
+        require_value_output(eval_node<diff>(values<Float>(1.0, 1.5, 3.0)),
+                             values<Float>(none, 0.5, 1.5), "floating diff");
+        require_value_output(eval_node<count>(values<Int>(3, none, 2, 1)),
+                             values<Int>(1, none, 2, 3), "count");
+        require_value_output(eval_node<count>(values<Int>(3, 2, 1),
+                                              values<Bool>(none, true, none)),
+                             values<Int>(1, 1, 2), "reset count");
+        require_value_output(eval_node<clip>(values<Int>(-1, 1, 3),
+                                             Int{0}, Int{2}),
+                             values<Int>(0, 1, 2), "integer clip");
+        require_value_output(eval_node<clip>(values<Float>(-1.0, 0.5, 2.0),
+                                             Float{0.0}, Float{1.0}),
+                             values<Float>(0.0, 0.5, 1.0), "floating clip");
+        require_value_output(eval_node<ewma>(values<Float>(1.0, 2.0, 3.0, 4.0),
+                                             Float{0.5}),
+                             values<Float>(1.0, 1.5, 2.25, 3.125), "ewma");
+
+        bool raised = false;
+        try
+        {
+            static_cast<void>(eval_node<clip>(
+                values<Float>(1.0), Float{1.0}, Float{-1.0}));
+        }
+        catch (const std::exception &)
+        {
+            raised = true;
+        }
+        require(raised, "clip rejects reversed bounds");
+    }
+}  // namespace
+
+int main()
+{
+    try
+    {
+        hgraph::stdlib::register_standard_operators();
+        hgraph::analytics::register_analytics_operators();
+        test_default_and_sparse_observations();
+        test_period_and_float_input();
+        test_zero_policies();
+        test_invalid_period();
+        test_migrated_analytical_operators();
+        return 0;
+    }
+    catch (const std::exception &error)
+    {
+        std::cerr << error.what() << '\n';
+        return 1;
+    }
+}

hgraph_analytics-0.8.5/tools/audit_distribution.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Audit hgraph-analytics wheels and source distributions."""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import itertools
+import tarfile
+import zipfile
+from pathlib import Path
+
+WHEEL_REQUIRED = (
+    "hgraph_analytics/__init__.py",
+    "hgraph_analytics/py.typed",
+    "include/hgraph/analytics/operators.h",
+    # GNUInstallDirs selects lib64 on manylinux, while macOS and Windows wheels
+    # use lib. Match the package-relative suffix so both layouts are audited.
+    "cmake/hgraph-analytics/hgraph-analyticsConfig.cmake",
+    "cmake/hgraph-analytics/hgraphAnalyticsTargets.cmake",
+)
+SDIST_REQUIRED = (
+    "CMakeLists.txt",
+    "cmake/hgraph-analyticsConfig.cmake.in",
+    "include/hgraph/analytics/operators.h",
+    "python/hgraph_analytics/__init__.py",
+    "python/hgraph_analytics/py.typed",
+    "src/operators.cpp",
+    "test_package/CMakeLists.txt",
+    "tests/test_pct_change.cpp",
+    "tools/audit_distribution.py",
+)
+
+
+def _assert_required(names: set[str], required: tuple[str, ...], path: Path) -> None:
+    for item in required:
+        if not any(name.endswith(f"/{item}") or name == item for name in names):
+            raise AssertionError(f"{path}: missing {item}")
+
+
+def _audit_wheel(path: Path) -> None:
+    with zipfile.ZipFile(path) as archive:
+        names = set(archive.namelist())
+        metadata_names = [name for name in names if name.endswith(".dist-info/METADATA")]
+        if len(metadata_names) != 1:
+            raise AssertionError(f"{path}: expected one METADATA file, got {metadata_names}")
+        metadata = archive.read(metadata_names[0]).decode()
+
+    _assert_required(names, WHEEL_REQUIRED, path)
+    native_modules = [
+        name
+        for name in names
+        if name.startswith("hgraph_analytics/_hgraph_analytics.")
+        and name.endswith((".so", ".pyd"))
+    ]
+    if len(native_modules) != 1:
+        raise AssertionError(
+            f"{path}: expected one native hgraph_analytics module, got {native_modules}"
+        )
+    analytics_libraries = [
+        name
+        for name in names
+        if Path(name).name.startswith(("libhgraph_analytics", "hgraph_analytics"))
+        and Path(name).suffix in {".a", ".lib"}
+    ]
+    if len(analytics_libraries) != 1:
+        raise AssertionError(
+            f"{path}: expected one native analytics library, got {analytics_libraries}"
+        )
+    forbidden = [
+        name
+        for name in names
+        if Path(name).name.startswith(
+            (
+                "hgraph_runtime",
+                "hgraph_stdlib",
+                "hgraph_wiring",
+                "libhgraph_runtime",
+                "libhgraph_stdlib",
+                "libhgraph_wiring",
+                "libnanobind-abi3",
+                "nanobind-abi3",
+            )
+        )
+    ]
+    if forbidden:
+        raise AssertionError(f"{path}: embeds core runtime libraries: {forbidden}")
+    if "Requires-Dist: hgraph" not in metadata:
+        raise AssertionError(f"{path}: does not declare the core distribution dependency")
+
+
+def _audit_sdist(path: Path) -> None:
+    with tarfile.open(path, "r:gz") as archive:
+        names = set(archive.getnames())
+    _assert_required(names, SDIST_REQUIRED, path)
+
+
+def _audit_distribution(path: Path) -> None:
+    if path.suffix == ".whl":
+        _audit_wheel(path)
+    elif path.name.endswith(".tar.gz"):
+        _audit_sdist(path)
+    else:
+        raise SystemExit(f"unsupported distribution: {path}")
+    print(f"audited {path}")
+
+
+def main() -> None:
+    arguments = argparse.ArgumentParser()
+    arguments.add_argument("distributions", nargs="+")
+    patterns = arguments.parse_args().distributions
+    matches = itertools.chain.from_iterable(glob.iglob(pattern) for pattern in patterns)
+    paths = sorted(map(Path, set(matches)))
+    if not paths:
+        raise SystemExit("no hgraph-analytics distributions matched")
+    for distribution in paths:
+        _audit_distribution(distribution)
+
+
+if __name__ == "__main__":
+    main()