hgraph 0.0.1__tar.gz

hgraph-0.0.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+A small test case to show the issue is preferred. If not possible, provide whatever useful information
+you feel may be able to assist in narrowing down how to reproduce the issue.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment:**
+ - OS: [e.g. iOS]
+ - Python Version [e.g. 11.1]
+
+**Additional context**
+Add any other context about the problem here.

hgraph-0.0.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

hgraph-0.0.1/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

hgraph-0.0.1/.gitignore

@@ -0,0 +1,33 @@
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+.idea/*

hgraph-0.0.1/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-0.0.1/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.1
+Name: hgraph
+Version: 0.0.1
+Summary: A functional reactive engine
+Project-URL: Homepage, https://github.com/hhenson/hgraph
+Project-URL: Repository, https://github.com/hhenson/hgraph.git
+Author-email: Howard Henson <howard@henson.me.uk>
+License: 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.
+License-File: LICENSE
+Keywords: forward propogating graph,fpg,functional reactive programming,graph,reactive,time series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.11
+Requires-Dist: frozendict>=2.3.10
+Requires-Dist: more-itertools>=10.1.0
+Requires-Dist: sortedcontainers>=2.4.0
+Description-Content-Type: text/markdown
+
+# hg
+A functional reactive programming engine with a Python front-end.

hgraph-0.0.1/README.md

@@ -0,0 +1,2 @@
+# hg
+A functional reactive programming engine with a Python front-end.

hgraph-0.0.1/docs/concepts/forward_propogation_graph.md

@@ -0,0 +1,189 @@
+# Forward Propogation Graph
+
+## Introduction
+
+The forward propagation graph (FPG) is a directed acyclic graph (DAG). The graph
+is designed to evaluate the flow of data through the graph, where evaluation follows
+the rank order of the nodes in the graph.
+
+The graph has 3 types of nodes, namely: source, compute, and sink nodes.
+The source nodes are the entry points into the graph, they have only output edges
+with no input edges. Sink nodes are the leaves of the node and have no output edges.
+Finally, the compute nodes are found between the source and sink nodes. These nodes
+have both input and output edges.
+
+```plantuml
+@startditaa
+ +--------+
+ | Source |
+ +--------+
+     |
+     v
++---------+
+| Compute |
++---------+
+     |
+     v
+ +-------+
+ | Sink  |
+ +-------+
+@endditaa
+```
+
+The FPG graph is a time-series evaluation engine. That is the graph evaluates information
+over time, the time is typically set by the source nodes. There are two types of source
+nodes, namely: pull and push source nodes. The pull source nodes express there values
+as a tuple of time and value. The graph will evaluate itself asof the time emitted by
+a pull source node or wall clock time if the push source node has a value enqueue. 
+A push source node will be evaluated at either the time of the
+current engine time (as determined by the pull source node values) or at the 
+current wall clock time if there are no pending pull source nodes with values to be 
+evaluated before the current wall clock time.
+
+The graph is evaluated in waves, the time of the wave (or engine_time) is the time
+set by the source node. The wave is evaluated in rank order (defined by the topological
+sort order of the graph). Nodes with the same rank may be evaluated in any order, 
+although in most implementations, the nodes are flattened into a fully ordered list
+and will always be evaluated in that order during the life-time of the graph.
+
+Nodes are only evaluated if the output/s that the input/s of the node have been modified
+during the current wave. The value of the outputs of a node are always present.
+Thus, once a value is computed it will be available to the inputs of dependent nodes / inputs.
+The net result is that the graph only evaluates the path of change, but produces
+the same output as if every node were evaluated in each wave.
+
+The nodes of the graph obtain time from the graph context. The key information is
+engine_time, this is the time the graph is currently been evaluated for, the
+"wall clock" time (wall_clock_time) represent the current live time. The nodes
+of a graph may never refer to the system clock (e.g. datetime.now()), but rather
+should always reflect the time from the supplied execution context. This allows
+the graph to run in a simulation (or backtest) mode where the graph is fed 
+historical time-series data to the source nodes and the wall_clock_time is 
+treated as the engine_time + engine_lag (or the time taken to the point at which
+it is queried). The upshot of this is that the graph can be forced to re-run
+different input simulations using exactly the same logic as it would run in real-time,
+without having to weight for any artificially introduced delays. I have heard
+this referred to as "time-travel", "bullet-time" and "compressed-time".
+
+One of the key advantages of this design for software development is partially
+the performance based on reduced computation and largely the ability to run
+simulations or backtests without having to modify the logic. If the key use of the
+software is for backtest/simulation of computations over time-series data, there
+are potentially more efficient solutions, but if the code is designed to run
+in real time at least as often as in simulation mode, then this design provides
+a powerful tool to develop these type of solutions.
+
+## Graph Runtime
+
+The runtime graph represent the structure that is evaluated at runtime. This
+consists of the graph engine, graph context, graph and nodes.
+
+
+### Graph Engine
+
+```plantuml
+@startuml
+enum RunMode {
+    +REAL_TIME
+    +SIMULATION
+}
+```
+```plantuml
+interface GraphEngine {
+    +graph: Graph
+    +run_mode: RunMode
+    +run(start_time: datetime, end_time: datetime) -> None
+}
+@enduml
+```
+
+The ``GraphEngine`` is the component that is responsible for evaluating the graph.
+This contains the master run-loop. The run-loop evaluates the graph in the time
+range provided. The nature of the evaluation is deterimined by the ``run_mode``
+of the graph. In ``SIMULATION`` mode the graph will only support pull source nodes
+and will evaluate the graph in compressed-time. In ``REAL_TIME`` mode the graph
+will support both push and pull source nodes and will evaluate the graph
+using true wall clock time, that is in a push source node presents a time in the future,
+the engine will wait until the time is reached on the computers clock prior to performing
+the computation.
+
+Historical data can also be fed into the system, but in REAL_TIME mode, the graph will
+process push source node ticks at whatever time point the engine is when the tick arrives.
+
+### Graph Context
+
+```plantuml
+interface ExecutionContext {
+    +current_engine_time: datetime
+    +wall_clock_time: datetime
+    +engine_lag: timedelta
+    +next_cycle_engine_time: datetime
+    
+    +request_engine_stop()
+    +is_stop_requested() -> bool
+    
+    +add_before_evaluation_notification(fn: callback[[], None]) -> None
+    +add_after_evaluation_notification(fn: callback[[], None]) -> None
+}
+```
+
+The most important interface elements are present above. This is available to
+all components in the graph and provides state information about the evaluation
+of the graph, the most important being the current_engine_time and the wall_clock_time.
+
+The add_before_evaluation_notification and add_after_evaluation_notification are 
+useful to inject behavior that needs to be evaluated once either just after the
+evaluation of the wave or just before the next wave is started. This is used
+extensively by internal components of the graph as well to manage transient state
+such as TSS.added / TSS.removed. These are values that are only present for a 
+single wave of the graph and need to be cleared down at the end of the wave.
+
+The ExecutionContext is created and owned by the GraphEngine.
+There are a number of other key methods and properties on the context, but many
+are for internal use and in a C++ engine are unlikely to be exposed to the user.
+
+### Graph
+
+```plantuml
+interface Graph {
+    +graph_id: tuple[int, ...]
+    +nodes: List[Node]
+    +schedule: List[datetime]
+    +context: ExecutionContext
+    +schedule_node(node_ndx: int, time: datetime) -> None
+}
+```
+
+The graph contains the nodes that belong to the graph. This graph is not the same
+as that of the wiring structure, but is the flattened graph of all nodes that 
+are to be evaluated within a ``GraphExecutor``. The graph also contains the
+evaluation schedule for each node. This is list of datetime values that indicate
+the next time the node is scheduled to be evaluated at. The graph is responsible
+for scheduling the nodes for evaluation. This is exposed as the ``schedule_node``
+method on the class.
+
+### Nodes
+
+As disused in the introduction, there are three key node types: source, compute, 
+and sink nodes. Nodes in the graph are represented as classes within the internals
+of the system. The base class is as follows:
+
+```plantuml
+interface Node {
+    +node_ndx: int
+    +rank: int
+    +inputs: List[Edge]
+    +outputs: List[Edge]
+    +evaluate(context: ExecutionContext) -> None
+}
+```
+
+
+#### Source Nodes
+
+```plantuml
+interface SourceNode {
+    +value: Any
+    +time: datetime
+}
+```

hgraph-0.0.1/docs/python/component_signature.md

@@ -0,0 +1,56 @@
+Component Signature
+===================
+
+The component signature describes the interface shape of the component
+being defined. All components (graph or node) follow the same basic rules.
+
+The signature declares the following attributes:
+
+* The name of the node
+* The incoming edges (or time-series inputs)
+* The node configuration (or scalar values)
+* The outgoing edges (or time-series outputs)
+* Documentation of the component
+
+The component decorator provides additional meta-data, which will be
+discussed on a type-by-type basis.
+
+The basic component signature looks like this:
+
+```python
+
+@decorator
+def component_name(ts1: TIME_SERIES_TYPE, ..., s1: str, ...) -> TIME_SERIES_TYPE_2:
+    """
+    Documentation
+    """
+    ... # component behavior
+```
+
+The ``@decorator`` is the appropriate component decorator that indicates
+the type of component, for example: ``@graph`` or ``@compute_node``.
+
+ALL arguments MUST use the type annotations to indicate the expected type,
+this allows the component signature parser to build the appropriate
+meta-data for components shape. There is no requirement as to ordering
+of inputs (i.e. to separate time-series inputs from scalar inputs.), but
+by convention we will often accumulate the time-series inputs first and the
+scalar inputs last.
+
+The scalar inputs are considered as configuration information to the 
+component, the time-series inputs are the value inputs to the component.
+Time-series inputs vary over time, scalar inputs are fixed at time of
+wiring the node and may not change after that.
+
+It is possible for components to take no arguments (typically a source node).
+
+The output can take three forms, none in the case of components that
+terminate the flow of the graph (typically sink nodes), a single output,
+or an un-named bundle output. The latter is expressed as a dictionary or
+values, for example:
+
+```python
+@graph
+def my_component() -> {"out1": TS[str], "out2": TS[float]}:
+    ...
+```

hgraph-0.0.1/docs/python/node_signature.md

@@ -0,0 +1,94 @@
+Node Signature
+==============
+
+The node signatures extend the component signature in their ability to
+mark interest in special arguments to be provided as inputs.
+
+These special inputs are only useful to runtime behaviour and as such are
+not meaningful to graph components.
+
+These special inputs include:
+
+* context: ``ExecutionContext``
+* state: ``NodeState``
+* output: ``TSOut[str]`` (for example)
+
+The names of the arguments are user defined, but following the suggested
+names makes it easier to read the code (where sensible).
+
+These special variable must appear in the formal kwargs sections and be defined
+to have None as the default value, for example:
+
+```python
+@generator
+def const(value: SCALAR, context: ExecutionContext=None) -> TIME_SERIES_VALUE:
+    ...
+```
+
+The runtime engine will supply the instance values, but these can never be supplied
+during the wiring phase, as such setting these to None as kwargs allows the
+wiring builder detect misconfigurations more easily, and the kwarg aspect
+hides the value from the user.
+
+ExecutionContext
+----------------
+
+The execution context provides access to information about the state of
+the running graph, this includes useful attributes such as:
+
+* current_engine_time - The time the engine is evaluating the graph for.
+* wall_clock_time - The wall clock time as of now, in simulation mode this is not the computer clock.
+* engine_lag - The time taken till now to evaluate this loop (or wave) of the graph.
+
+NodeState
+---------
+
+Given the paradigm of evaluation of the graph is functional, all behaviour is
+stateless and should be idempotent. However, we also live in a stateful world,
+this allows the node to track state, in a stateless way. That is, the node
+is not the owner of it's state, but rather the state is provided to the node.
+For the most part the state provided is the state computed during the last
+evaluation of the node, but this can also be managed to deal with testing
+with assumed prior states, etc.
+The NodeState object is effectively a dictionary from the users point of view,
+with the ability to access keys using ``.<key>`` type syntax as well as ``['key']`` 
+syntax. The user can think of it as ``self``.
+
+Output
+------
+
+Ofttimes it useful to be able to see the previous state of the output when computing
+a new result, having access to the values of the outputs reduces anti-patterns where
+values are cached in state that could be read directly from the output node.
+
+The output can be directly typed using the <time-series-type>Out syntax to identify
+the output or use ``TIME_SERIES_OUTPUT`` to indicate the variable is to receive a reference
+to the outputs.
+
+In either case the output will be provided, but in the former, the IDE will be able to
+resolve the type signature and be able to provide auto-completion support. The latter mode
+will only have the most basic signature support.
+
+For example:
+
+```python
+
+@compute_node
+def count(ts: TIME_SERIES_TYPE, output: TSOut[int]) -> TS[int]:
+    return output.value + 1
+```
+
+Using the output it is also possible to set the output directly, for example:
+
+```python
+
+@compute_node
+def count(ts: TIME_SERIES_TYPE, output: TSOut[int]) -> TS[int]:
+    output.value += 1
+```
+
+In which case nothing is returned, but the output is updated. If the output is updated
+multiple times during the evaluation of the node, only on final *tick* is generated, the value
+of which is dependent on the output type, for example a TS type will only have the last
+value set being available, but a TSS type will show the net state of operations performed
+during the evaluation of the node.

hgraph-0.0.1/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hgraph"
+dynamic = ["version"]
+dependencies = [
+    #    "pytest>=7.4.3",
+    "frozendict>=2.3.10",
+    "more-itertools>=10.1.0",
+    "sortedcontainers>=2.4.0",
+]
+requires-python = ">=3.11"
+authors = [
+    { name = "Howard Henson", email = "howard@henson.me.uk" },
+]
+maintainers = [
+]
+description = "A functional reactive engine"
+readme = "README.md"
+license = { file = "LICENSE" }
+keywords = [
+    "reactive", "graph", "fpg", "forward propogating graph", "time series", "functional reactive programming",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: Implementation :: CPython",
+]
+
+[project.urls]
+Homepage = "https://github.com/hhenson/hgraph"
+Repository = "https://github.com/hhenson/hgraph.git"
+
+[tool.pytest.ini_options]
+minversion = "7.4.3"
+addopts = "-ra -q"
+testpaths = [
+    "test",
+]
+
+[tool.hatch.version]
+path = "src/hgraph/__about__.py"
+
+[tool.hatch.envs.default]
+dependencies = [
+  "coverage[toml]>=6.5",
+  "pytest",
+]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest {args:tests}"
+test-cov = "coverage run -m pytest {args:tests}"
+cov-report = [
+  "- coverage combine",
+  "coverage report",
+]
+cov = [
+  "test-cov",
+  "cov-report",
+]
+
+[[tool.hatch.envs.all.matrix]]
+python = ["3.11", "3.12"]
+
+[tool.hatch.envs.types]
+dependencies = [
+  "mypy>=1.0.0",
+]
+
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/hg tests}"
+
+[tool.coverage.run]
+source_pkgs = ["hgraph", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/hgraph/__about__.py",
+]
+
+[tool.coverage.paths]
+hg = ["src/hgraph", "*/hgraph/src/hg"]
+tests = ["tests", "*/hgraph/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+

hgraph-0.0.1/requirements.txt

@@ -0,0 +1,5 @@
+pytest>=7.4.3
+frozendict>=2.3.10
+scikit-build
+more-itertools>=10.1.0
+sortedcontainers>=2.4.0

hgraph-0.0.1/src/hgraph/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

hgraph-0.0.1/src/hgraph/__init__.py

@@ -0,0 +1,6 @@
+from hgraph._builder import *
+from hgraph._runtime import *
+from hgraph._types import *
+from hgraph._wiring import *
+from hgraph._impl import *
+

hgraph-0.0.1/src/hgraph/_builder/__init__.py

@@ -0,0 +1,7 @@
+from hgraph._builder._builder import *
+from hgraph._builder._graph_builder import *
+from hgraph._builder._input_builder import *
+from hgraph._builder._node_builder import *
+from hgraph._builder._output_builder import *
+from hgraph._builder._scalar_builder import *
+from hgraph._builder._ts_builder import *

hgraph-0.0.1/src/hgraph/_builder/_builder.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic
+
+ITEM = TypeVar('ITEM')
+
+__all__ = ("Builder",)
+
+
+class Builder(ABC, Generic[ITEM]):
+    """
+    The builder is responsible for constructing and initialising the item type it is responsible for.
+    It is also responsible for destroying and cleaning up the resources associated to the item.
+    These can be thought of as life-cycle methods.
+    """
+
+    @abstractmethod
+    def make_instance(self, **kwargs) -> ITEM:
+        """
+        Create a new instance of the item.
+        And additional attributes required for construction are passed in as kwargs.
+        Actual instance of the builder will fix these args for all instances of builder for the type.
+        """
+
+    @abstractmethod
+    def release_instance(self, item: ITEM):
+        """
+        Release the item and it's resources.
+        """
+