Metadata-Version: 2.2
Name: hgraph
Version: 0.8.17
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

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:

```sh
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`](docs/source/getting_started.rst)
and use [`docs/source/reference/`](docs/source/reference/) for the supported
Python types, decorators, operators and modules.

## 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 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`](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.
- [`plugins/hgraph-development/`](plugins/hgraph-development/) — installable
  hgraph development skills for downstream Codex and Claude projects.
