Metadata-Version: 2.2
Name: hgraph
Version: 0.8.2
Summary: C++-first functional reactive runtime for time-series processing
Keywords: reactive,graph,forward propagating graph,time series,functional reactive programming,c++
Author-Email: Howard Henson <howard@henson.me.uk>, Alexander Balabin <balabin@me.com>, Simon Young <whepstead@gmail.com>, Tope Olukemi <tolukemi@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Project-URL: Homepage, https://github.com/hhenson/hgraph
Project-URL: Repository, https://github.com/hhenson/hgraph.git
Project-URL: Issues, https://github.com/hhenson/hgraph/issues
Requires-Python: >=3.12
Requires-Dist: frozendict>=2.4
Requires-Dist: numpy>=2.0
Requires-Dist: pyarrow<26,>=25
Requires-Dist: polars>=1.32
Requires-Dist: pyyaml>=6
Provides-Extra: python
Requires-Dist: nanobind==2.13.0; extra == "python"
Provides-Extra: test
Requires-Dist: boto3>=1.34; extra == "test"
Requires-Dist: connectorx>=0.4.5; extra == "test"
Requires-Dist: deltalake>=1.0; extra == "test"
Requires-Dist: duckdb>=1.4; extra == "test"
Requires-Dist: hypothesis>=6; extra == "test"
Requires-Dist: pandas>=2.0; extra == "test"
Requires-Dist: packaging>=24; extra == "test"
Requires-Dist: polars[rtcompat]>=1.32; extra == "test"
Requires-Dist: perspective-python>=3.8; extra == "test"
Requires-Dist: psutil>=5.9; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: sqlalchemy>=2.0; extra == "test"
Requires-Dist: tornado>=6.5; extra == "test"
Requires-Dist: trove-classifiers; extra == "test"
Provides-Extra: parity
Requires-Dist: hypothesis>=6; extra == "parity"
Provides-Extra: web
Requires-Dist: tornado>=6.5; extra == "web"
Provides-Extra: sql
Requires-Dist: connectorx>=0.4.5; extra == "sql"
Requires-Dist: duckdb>=1.4; extra == "sql"
Requires-Dist: pandas>=2.0; extra == "sql"
Requires-Dist: polars>=1.32; extra == "sql"
Requires-Dist: sqlalchemy>=2.0; extra == "sql"
Provides-Extra: snowflake
Requires-Dist: adbc-driver-snowflake>=1.8; extra == "snowflake"
Provides-Extra: delta
Requires-Dist: boto3>=1.34; extra == "delta"
Requires-Dist: deltalake>=1.0; extra == "delta"
Requires-Dist: polars>=1.32; extra == "delta"
Provides-Extra: perspective
Requires-Dist: perspective-python>=3.8; extra == "perspective"
Requires-Dist: psutil>=5.9; extra == "perspective"
Requires-Dist: tornado>=6.5; extra == "perspective"
Provides-Extra: dataframe
Requires-Dist: polars>=1.32; extra == "dataframe"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=1.0; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == "docs"
Requires-Dist: pybtex-apa-style>=1.3; extra == "docs"
Provides-Extra: dev
Requires-Dist: cmake>=3.26; extra == "dev"
Requires-Dist: ninja; extra == "dev"
Requires-Dist: nanobind==2.13.0; extra == "dev"
Requires-Dist: packaging>=24; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: sphinx>=7.4; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "dev"
Requires-Dist: myst-parser>=2.0; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid>=1.0; extra == "dev"
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == "dev"
Requires-Dist: pybtex-apa-style>=1.3; extra == "dev"
Requires-Dist: scikit-build-core>=0.12; extra == "dev"
Requires-Dist: trove-classifiers; extra == "dev"
Description-Content-Type: text/markdown

# hgraph

A clean-slate, **C++-first** implementation of the
[hgraph](https://github.com/hhenson/hgraph) functional-reactive time-series
runtime. The C++ runtime is the source of truth. Python provides wiring
compatibility and supports Python-authored nodes running inside that runtime.

## Python package

The C++-backed runtime is published under the `hgraph` distribution name:

```sh
python -m pip install hgraph
```

The distribution exposes the `hgraph` import package and the native `_hgraph`
extension. Version 0.8.0 replaces the Python-first runtime maintained on the
`release/0.5` branch. 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`.

## Build & test

```sh
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:

```sh
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, then the Python authoring track (`python/`: quick start, tutorial,
  programming model) or the C++ one (`cpp/`: authoring nodes, graphs, and the
  `eval_node` harness).
- **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`](AGENTS.md) — canonical project direction: goals, build
  philosophy, source layout, dependency policy, git hygiene.
- [`CLAUDE.md`](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.
