hgraph
HGraph is a functional-reactive time-series engine with a Python-first user
experience and a native C++ runtime. Most users author and test graphs with the
hgraph Python package; library authors can use the C++ API directly when they
need native integration or maximum performance. Both paths wire and execute
through the same runtime.
Python package
The C++-backed runtime is published under the hgraph distribution name:
python -m pip install hgraph
The distribution exposes the supported hgraph authoring package and its
private native _hgraph extension. The 0.8 line replaces the Python runtime
maintained on the release/0.5 branch while retaining Python as the primary
public API. One wheel per supported platform covers CPython 3.12 and later
through the CPython stable ABI. The supported Python and platform policy is
recorded in docs/source/developer_guide/release_readiness.rst.
Start with docs/source/getting_started.rst
and use docs/source/reference/ for the supported
Python types, decorators, operators and modules.
Build & test
cmake -S . -B build # configure (fmt + Catch2 fetched if absent)
cmake --build build -j # build hgraph_core + tests
ctest --test-dir build --output-on-failure
Requires a C++23 compiler and CMake >= 3.25. Python/nanobind are not needed
for the default build (bindings are opt-in via -DHGRAPH_BUILD_PYTHON_BINDINGS=ON).
First-party extensions
First-party extensions are co-developed in extensions/ but remain separate
native and Python distributions. Kafka is built in-tree for development with
-DHGRAPH_BUILD_KAFKA_EXTENSION=ON, or independently from
extensions/kafka/ against an installed hgraph SDK. Its wheel is selected
from the uv workspace after making that matching SDK discoverable:
CMAKE_PREFIX_PATH=/path/to/hgraph/sdk \
uv build --wheel --package hgraph-kafka --python 3.12
The core build does not enable the extension by default and does not acquire a Kafka or librdkafka dependency.
Documentation
Sphinx docs live under docs/source (uv sync --extra docs, then
uv run sphinx-build -W -b html docs/source docs/_build/html):
- Getting started —
docs/source/getting_started.rst: install the wheel and run a first graph in Python. - User guide —
docs/source/user_guide/: the concepts the runtime implements and the primary Python authoring track (python/: quick start, common tasks, tutorial, programming model). Native C++ authoring is an advanced section for library authors. - Python API reference —
docs/source/reference/: curated reference pages plus a generated inventory of wildcard exports, lazy operators and public submodules. - Specification —
docs/source/specification/: a language-neutral definition of HGraph semantics. - Developer guide — the authoritative design records
(
docs/source/developer_guide/): architecture, data structures, wiring, nested graphs, mesh, services, error handling, operators, roadmap.
The narrative documentation's Python examples are executable. They are checked
against a real runtime by sphinx-build -b doctest, which needs an importable
hgraph; CI runs both that and the warning-free HTML build.
Contributing / AI sessions
AGENTS.md— canonical project direction: goals, build philosophy, source layout, dependency policy, git hygiene.CLAUDE.md— the operational working guide: the enforced design-first workflow (docs change in the same commit as code), guardrails, architecture map, and current state.plugins/hgraph-development/— installable hgraph development skills for downstream Codex and Claude projects.
Shared language sources
Run python3 tools/shared_artifacts.py before compiler, documentation or
contract-test work. See shared source setup.
1 maintainer
Metadata
1 maintainer
Release files for hgraph 0.8.31
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| hgraph-0.8.31.tar.gz | 7.5 MB | With provenance | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hgraph-0.8.31-cp312-abi3-win_amd64.whl | CPython 3.12 | abi3 | Windows x86-64 | Details |
| hgraph-0.8.31-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.12 | abi3 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| hgraph-0.8.31-cp312-abi3-macosx_26_0_arm64.whl | CPython 3.12 | abi3 | macOS 26.0+ ARM64 | Details |
Total release size: 49.5 MB
Release files / hgraph-0.8.31.tar.gz
| Download URL | hgraph-0.8.31.tar.gz |
|---|---|
| Size | 7.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
366f2c0e0c47779c997690138807e149b23fcb8b90cd5af34126e6cdc0608f31
|
|
BLAKE2b-256 checksum How to use checksums |
67b5c82aafb7c19a182ff6dced97b88edf48bfec2032ec24ad385e1e99a4358a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / hgraph-0.8.31-cp312-abi3-win_amd64.whl
| Download URL | hgraph-0.8.31-cp312-abi3-win_amd64.whl |
|---|---|
| Size | 18.8 MB |
| Tags | CPython 3.12 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
80a7cb9c08e7fd3989af317b2fda022220c45687cea361a8a44caf4a3f10b626
|
|
BLAKE2b-256 checksum How to use checksums |
068756137403f6696d72326735487fb0b0236d75d4c525e104e6d116a530c855
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / hgraph-0.8.31-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | hgraph-0.8.31-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 11.4 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
78b08521e11cfeb4b088e519e627f21b19171248ec36560a67779d344abe43b2
|
|
BLAKE2b-256 checksum How to use checksums |
2842921102b63a6900153b600353b3fc2c94dddd722a7133357b9a66acce5793
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / hgraph-0.8.31-cp312-abi3-macosx_26_0_arm64.whl
| Download URL | hgraph-0.8.31-cp312-abi3-macosx_26_0_arm64.whl |
|---|---|
| Size | 11.7 MB |
| Tags | CPython 3.12 abi3 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
6e335b99233d7bf7165f45a634b4dadbf1cf40a3f4dda474cc2e71cf2d9023a3
|
|
BLAKE2b-256 checksum How to use checksums |
2589a31f16e696b7e6d475bea64e199ca902f58fb9338b2cabe18be9f5cc8438
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logSecurity for hgraph 0.8.31
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 4 files in this release have been uploaded with provenance metadata.
Attestation for hgraph-0.8.31.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
