graphon 0.1.2__tar.gz → 0.2.0__tar.gz

graphon-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: graphon
+Version: 0.2.0
+Summary: Graph execution engine for agentic AI workflows.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Dist: charset-normalizer>=2.1
+Requires-Dist: httpx>=0.28
+Requires-Dist: json-repair>=0.55
+Requires-Dist: jsonschema>=4
+Requires-Dist: orjson>=3
+Requires-Dist: pandas[excel]>=2.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-extra-types>=2
+Requires-Dist: pypdfium2>=5
+Requires-Dist: python-docx>=1.2
+Requires-Dist: pyyaml>=6
+Requires-Dist: tiktoken>=0.12
+Requires-Dist: transformers>=4
+Requires-Dist: typing-extensions>=4.10.0
+Requires-Dist: unstructured[docx,epub,md,ppt,pptx]>=0.21
+Requires-Dist: pypandoc>=1.13
+Requires-Dist: webvtt-py>=0.5
+Requires-Python: >=3.12, <3.14
+Project-URL: source, https://github.com/langgenius/graphon
+Project-URL: homepage, https://github.com/langgenius/graphon
+Project-URL: issues, https://github.com/langgenius/graphon/issues
+Description-Content-Type: text/markdown
+
+# Graphon
+
+Graphon is a Python graph execution engine for agentic AI workflows.
+
+The repository is still evolving, but it already contains a working execution
+engine, built-in workflow nodes, model runtime abstractions, integration
+protocols, and a runnable end-to-end example.
+
+## Highlights
+
+- Queue-based `GraphEngine` orchestration with event-driven execution
+- Graph parsing, validation, and fluent graph building
+- Shared runtime state, variable pool, and workflow execution domain models
+- Built-in node implementations for common workflow patterns
+- Pluggable model runtime interfaces, including a local `SlimRuntime`
+- HTTP, file, tool, and human-input integration protocols
+- Extensible engine layers and external command channels
+
+Repository modules currently cover node types such as `start`, `end`, `answer`,
+`llm`, `if-else`, `code`, `template-transform`, `question-classifier`,
+`http-request`, `tool`, `variable-aggregator`, `variable-assigner`, `loop`,
+`iteration`, `parameter-extractor`, `document-extractor`, `list-operator`, and
+`human-input`.
+
+## Quick Start
+
+Graphon is currently easiest to evaluate from a source checkout.
+
+### Requirements
+
+- Python 3.12 or 3.13
+- [`uv`](https://docs.astral.sh/uv/)
+- `make`
+
+Python 3.14 is currently unsupported because `unstructured`, which backs part
+of the document extraction stack, currently declares `Requires-Python: <3.14`.
+
+### Set up the repository
+
+```bash
+make dev
+source .venv/bin/activate
+make test
+```
+
+`make dev` installs the project, syncs development dependencies, and sets up
+[`prek`](https://prek.j178.dev/) Git hooks.
+
+## Run the Example Workflow
+
+The repository includes a minimal runnable example at
+[`examples/graphon_openai_slim`](examples/graphon_openai_slim).
+
+It builds and executes this workflow:
+
+```text
+start -> llm -> output
+```
+
+To run it:
+
+```bash
+make dev
+source .venv/bin/activate
+cd examples/graphon_openai_slim
+cp .env.example .env
+python3 workflow.py "Explain Graphon in one short sentence."
+```
+
+Before running the example, fill in the required values in `.env`.
+
+The example currently expects:
+
+- an `OPENAI_API_KEY`
+- a `SLIM_PLUGIN_ID`
+- a local `dify-plugin-daemon-slim` setup or equivalent Slim runtime
+
+For the exact environment variables and runtime notes, see
+[examples/graphon_openai_slim/README.md](examples/graphon_openai_slim/README.md).
+
+## How Graphon Fits Together
+
+At a high level, Graphon usage looks like this:
+
+1. Build or load a graph and instantiate nodes into a `Graph`.
+2. Prepare `GraphRuntimeState` and seed the `VariablePool`.
+3. Configure model, file, HTTP, tool, or human-input adapters as needed.
+4. Run `GraphEngine` and consume emitted graph events.
+5. Read final outputs from runtime state.
+
+The bundled example follows exactly that path. The execution loop is centered
+around `GraphEngine.run()`:
+
+```python
+engine = GraphEngine(
+    workflow_id="example-start-llm-output",
+    graph=graph,
+    graph_runtime_state=graph_runtime_state,
+    command_channel=InMemoryChannel(),
+)
+
+for event in engine.run():
+    ...
+```
+
+See
+[examples/graphon_openai_slim/workflow.py](examples/graphon_openai_slim/workflow.py)
+for the full example, including `SlimRuntime`, `SlimPreparedLLM`, graph
+construction, input seeding, and streamed output handling.
+
+## Project Layout
+
+- `src/graphon/graph`: graph structures, parsing, validation, and builders
+- `src/graphon/graph_engine`: orchestration, workers, command channels, and
+  layers
+- `src/graphon/runtime`: runtime state, read-only wrappers, and variable pool
+- `src/graphon/nodes`: built-in workflow node implementations
+- `src/graphon/model_runtime`: provider/model abstractions and Slim runtime
+- `src/graphon/graph_events`: event models emitted during execution
+- `src/graphon/http`: HTTP client abstractions and default implementation
+- `src/graphon/file`: workflow file models and file runtime helpers
+- `src/graphon/protocols`: public protocol re-exports for integrations
+- `examples/`: runnable examples
+- `tests/`: unit and integration-style coverage
+
+## Internal Docs
+
+- [CONTRIBUTING.md](CONTRIBUTING.md): contributor workflow, CI, commit/PR rules
+- [examples/graphon_openai_slim/README.md](examples/graphon_openai_slim/README.md):
+  runnable example setup
+- [src/graphon/model_runtime/README.md](src/graphon/model_runtime/README.md):
+  model runtime overview
+- [src/graphon/graph_engine/layers/README.md](src/graphon/graph_engine/layers/README.md):
+  engine layer extension points
+- [src/graphon/graph_engine/command_channels/README.md](src/graphon/graph_engine/command_channels/README.md):
+  local and distributed command channels
+
+## Development
+
+Contributor setup, tooling details, CLA notes, and commit/PR conventions live
+in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+CI currently validates commit messages, pull request titles, formatting, lint,
+and tests on Python 3.12 and 3.13. Python 3.14 is currently excluded because
+`unstructured` does not yet support it.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

graphon-0.2.0/README.md

@@ -0,0 +1,149 @@
+# Graphon
+
+Graphon is a Python graph execution engine for agentic AI workflows.
+
+The repository is still evolving, but it already contains a working execution
+engine, built-in workflow nodes, model runtime abstractions, integration
+protocols, and a runnable end-to-end example.
+
+## Highlights
+
+- Queue-based `GraphEngine` orchestration with event-driven execution
+- Graph parsing, validation, and fluent graph building
+- Shared runtime state, variable pool, and workflow execution domain models
+- Built-in node implementations for common workflow patterns
+- Pluggable model runtime interfaces, including a local `SlimRuntime`
+- HTTP, file, tool, and human-input integration protocols
+- Extensible engine layers and external command channels
+
+Repository modules currently cover node types such as `start`, `end`, `answer`,
+`llm`, `if-else`, `code`, `template-transform`, `question-classifier`,
+`http-request`, `tool`, `variable-aggregator`, `variable-assigner`, `loop`,
+`iteration`, `parameter-extractor`, `document-extractor`, `list-operator`, and
+`human-input`.
+
+## Quick Start
+
+Graphon is currently easiest to evaluate from a source checkout.
+
+### Requirements
+
+- Python 3.12 or 3.13
+- [`uv`](https://docs.astral.sh/uv/)
+- `make`
+
+Python 3.14 is currently unsupported because `unstructured`, which backs part
+of the document extraction stack, currently declares `Requires-Python: <3.14`.
+
+### Set up the repository
+
+```bash
+make dev
+source .venv/bin/activate
+make test
+```
+
+`make dev` installs the project, syncs development dependencies, and sets up
+[`prek`](https://prek.j178.dev/) Git hooks.
+
+## Run the Example Workflow
+
+The repository includes a minimal runnable example at
+[`examples/graphon_openai_slim`](examples/graphon_openai_slim).
+
+It builds and executes this workflow:
+
+```text
+start -> llm -> output
+```
+
+To run it:
+
+```bash
+make dev
+source .venv/bin/activate
+cd examples/graphon_openai_slim
+cp .env.example .env
+python3 workflow.py "Explain Graphon in one short sentence."
+```
+
+Before running the example, fill in the required values in `.env`.
+
+The example currently expects:
+
+- an `OPENAI_API_KEY`
+- a `SLIM_PLUGIN_ID`
+- a local `dify-plugin-daemon-slim` setup or equivalent Slim runtime
+
+For the exact environment variables and runtime notes, see
+[examples/graphon_openai_slim/README.md](examples/graphon_openai_slim/README.md).
+
+## How Graphon Fits Together
+
+At a high level, Graphon usage looks like this:
+
+1. Build or load a graph and instantiate nodes into a `Graph`.
+2. Prepare `GraphRuntimeState` and seed the `VariablePool`.
+3. Configure model, file, HTTP, tool, or human-input adapters as needed.
+4. Run `GraphEngine` and consume emitted graph events.
+5. Read final outputs from runtime state.
+
+The bundled example follows exactly that path. The execution loop is centered
+around `GraphEngine.run()`:
+
+```python
+engine = GraphEngine(
+    workflow_id="example-start-llm-output",
+    graph=graph,
+    graph_runtime_state=graph_runtime_state,
+    command_channel=InMemoryChannel(),
+)
+
+for event in engine.run():
+    ...
+```
+
+See
+[examples/graphon_openai_slim/workflow.py](examples/graphon_openai_slim/workflow.py)
+for the full example, including `SlimRuntime`, `SlimPreparedLLM`, graph
+construction, input seeding, and streamed output handling.
+
+## Project Layout
+
+- `src/graphon/graph`: graph structures, parsing, validation, and builders
+- `src/graphon/graph_engine`: orchestration, workers, command channels, and
+  layers
+- `src/graphon/runtime`: runtime state, read-only wrappers, and variable pool
+- `src/graphon/nodes`: built-in workflow node implementations
+- `src/graphon/model_runtime`: provider/model abstractions and Slim runtime
+- `src/graphon/graph_events`: event models emitted during execution
+- `src/graphon/http`: HTTP client abstractions and default implementation
+- `src/graphon/file`: workflow file models and file runtime helpers
+- `src/graphon/protocols`: public protocol re-exports for integrations
+- `examples/`: runnable examples
+- `tests/`: unit and integration-style coverage
+
+## Internal Docs
+
+- [CONTRIBUTING.md](CONTRIBUTING.md): contributor workflow, CI, commit/PR rules
+- [examples/graphon_openai_slim/README.md](examples/graphon_openai_slim/README.md):
+  runnable example setup
+- [src/graphon/model_runtime/README.md](src/graphon/model_runtime/README.md):
+  model runtime overview
+- [src/graphon/graph_engine/layers/README.md](src/graphon/graph_engine/layers/README.md):
+  engine layer extension points
+- [src/graphon/graph_engine/command_channels/README.md](src/graphon/graph_engine/command_channels/README.md):
+  local and distributed command channels
+
+## Development
+
+Contributor setup, tooling details, CLA notes, and commit/PR conventions live
+in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+CI currently validates commit messages, pull request titles, formatting, lint,
+and tests on Python 3.12 and 3.13. Python 3.14 is currently excluded because
+`unstructured` does not yet support it.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

graphon-0.2.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = 'graphon'
+version = "0.2.0"
+description = 'Graph execution engine for agentic AI workflows.'
+readme = 'README.md'
+license = 'Apache-2.0'
+license-files = ['LICENSE']
+# Keep Python support aligned with `unstructured`, which currently declares
+# `Requires-Python: <3.14,>=3.11`.
+requires-python = '>=3.12,<3.14'
+dependencies = [
+    'charset-normalizer>=2.1',
+    'httpx>=0.28',
+    'json-repair>=0.55',
+    'jsonschema>=4',
+    'orjson>=3',
+    'pandas[excel]>=2.1',
+    'pydantic>=2.7',
+    'pydantic-extra-types>=2',
+    'pypdfium2>=5',
+    'python-docx>=1.2',
+    'pyyaml>=6',
+    'tiktoken>=0.12',
+    'transformers>=4',
+    'typing-extensions>=4.10.0',
+    'unstructured[docx,epub,md,ppt,pptx]>=0.21',
+    'pypandoc>=1.13',
+    'webvtt-py>=0.5',
+]
+
+[project.urls]
+source = 'https://github.com/langgenius/graphon'
+homepage = 'https://github.com/langgenius/graphon'
+issues = 'https://github.com/langgenius/graphon/issues'
+
+[dependency-groups]
+dev = [
+    'pytest',
+    'pytest-cov',
+    'pytest-mock',
+    'pytest-xdist',
+    'ruff',
+    'prek',
+    'ty',
+]
+
+[build-system]
+requires = ['uv_build~=0.11']
+build-backend = 'uv_build'
+
+[tool.uv]
+default-groups = ['dev']
+
+[tool.ruff]
+fix = true
+preview = true
+required-version = '>=0.15'
+
+[tool.ruff.lint]
+select = ['ALL']
+ignore = [
+    'COM812',  # Conflicts with `ruff format`.
+    'ERA001',  # False positives are common.
+    'TC',      # Runtime use of typing constructs is common now.
+    'CPY',     # Covered by the standalone LICENSE file.
+    'PLR0913', # Explicit is better than implicit.
+    'PLR0917', # Complex is better than complicated.
+    'PLR6301', # Violates the usual practice.
+    'D',       # Too verbose.
+    'FBT',     # Too strict.
+    'TID252',  # Too absolute.
+    'ANN401',  # We hope to enforce this, but typing is still evolving.
+]
+
+[tool.ruff.lint.pydoclint]
+ignore-one-line-docstrings = true
+
+[tool.ruff.lint.per-file-ignores]
+'tests/**/*.py' = [
+    'S101',    # Assert statements used for pytest.
+    'PLR2004', # Magic value used in test cases.
+]
+
+[tool.ty.environment]
+python-platform = "linux"
+
+[tool.pytest]
+minversion = '9.0'
+addopts = ['-n', 'auto']
+testpaths = ['tests']

{graphon-0.1.2 → graphon-0.2.0}/src/graphon/entities/base_node_data.py

@@ -4,15 +4,14 @@ import json
 from abc import ABC
 from builtins import type as type_
 from enum import StrEnum
-from typing import Any, Union
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from graphon.entities.exc import DefaultValueTypeError
 from graphon.enums import ErrorStrategy, NodeType
 
-# Project supports Python 3.11+, where `typing.Union[...]` is valid in `isinstance`.
-_NumberType = Union[int, float]
+_NumberType = int | float
 
 
 class RetryConfig(BaseModel):
@@ -43,12 +42,13 @@ class DefaultValue(BaseModel):
     key: str
 
     @staticmethod
-    def _parse_json(value: str):
+    def _parse_json(value: str) -> Any:
         """Unified JSON parsing handler"""
         try:
             return json.loads(value)
-        except json.JSONDecodeError:
-            raise DefaultValueTypeError(f"Invalid JSON format for value: {value}")
+        except json.JSONDecodeError as error:
+            msg = f"Invalid JSON format for value: {value}"
+            raise DefaultValueTypeError(msg) from error
 
     @staticmethod
     def _validate_array(value: Any, element_type: type_ | tuple[type_, ...]) -> bool:
@@ -62,8 +62,9 @@ class DefaultValue(BaseModel):
         """Unified number conversion handler"""
         try:
             return float(value)
-        except ValueError:
-            raise DefaultValueTypeError(f"Cannot convert to number: {value}")
+        except ValueError as error:
+            msg = f"Cannot convert to number: {value}"
+            raise DefaultValueTypeError(msg) from error
 
     @model_validator(mode="after")
     def validate_value_type(self) -> DefaultValue:
@@ -103,7 +104,8 @@ class DefaultValue(BaseModel):
             if self.type == DefaultValueType.ARRAY_FILES:
                 # Handle files type
                 return self
-            raise DefaultValueTypeError(f"Unsupported type: {self.type}")
+            msg = f"Unsupported type: {self.type}"
+            raise DefaultValueTypeError(msg)
 
         # Handle string input cases
         if isinstance(self.value, str) and self.type != DefaultValueType.STRING:
@@ -111,18 +113,19 @@ class DefaultValue(BaseModel):
 
         # Validate base type
         if not isinstance(self.value, validator["type"]):
-            raise DefaultValueTypeError(
-                f"Value must be {validator['type'].__name__} type for {self.value}"
-            )
+            msg = f"Value must be {validator['type'].__name__} type for {self.value}"
+            raise DefaultValueTypeError(msg)
 
         # Validate array element types
-        if validator["type"] == list and not self._validate_array(
-            self.value, validator["element_type"]
+        if validator["type"] is list and not self._validate_array(
+            self.value,
+            validator["element_type"],
         ):
-            raise DefaultValueTypeError(
+            msg = (
                 f"All elements must be {validator['element_type'].__name__} "
                 f"for {self.value}"
             )
+            raise DefaultValueTypeError(msg)
 
         return self
 
@@ -154,9 +157,15 @@ class BaseNodeData(ABC, BaseModel):
         return {}
 
     def __getitem__(self, key: str) -> Any:
-        """
-        Dict-style access without calling model_dump() on every lookup.
+        """Dict-style access without calling model_dump() on every lookup.
         Prefer using model fields and Pydantic's extra storage.
+
+        Returns:
+            The declared field value or compatibility extra stored under `key`.
+
+        Raises:
+            KeyError: If `key` is neither a declared field nor a stored extra.
+
         """
         # First, check declared model fields
         if key in self.__class__.model_fields:
@@ -172,9 +181,7 @@ class BaseNodeData(ABC, BaseModel):
         raise KeyError(key)
 
     def get(self, key: str, default: Any = None) -> Any:
-        """
-        Dict-style .get() without calling model_dump() on every lookup.
-        """
+        """Dict-style .get() without calling model_dump() on every lookup."""
         if key in self.__class__.model_fields:
             return getattr(self, key)
 

{graphon-0.1.2 → graphon-0.2.0}/src/graphon/entities/graph_config.py

@@ -1,16 +1,11 @@
 from __future__ import annotations
 
-import sys
+from typing import TypedDict
 
 from pydantic import TypeAdapter, with_config
 
 from graphon.entities.base_node_data import BaseNodeData
 
-if sys.version_info >= (3, 12):
-    from typing import TypedDict
-else:
-    from typing_extensions import TypedDict
-
 
 @with_config(extra="allow")
 class NodeConfigDict(TypedDict):

{graphon-0.1.2 → graphon-0.2.0}/src/graphon/entities/pause_reason.py

@@ -1,6 +1,6 @@
 from collections.abc import Mapping
 from enum import StrEnum, auto
-from typing import Annotated, Any, Literal, TypeAlias
+from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, Field
 
@@ -45,6 +45,7 @@ class SchedulingPause(BaseModel):
     message: str
 
 
-PauseReason: TypeAlias = Annotated[
-    HumanInputRequired | SchedulingPause, Field(discriminator="TYPE")
+type PauseReason = Annotated[
+    HumanInputRequired | SchedulingPause,
+    Field(discriminator="TYPE"),
 ]

{graphon-0.1.2 → graphon-0.2.0}/src/graphon/entities/workflow_execution.py

@@ -1,5 +1,4 @@
-"""
-Domain entities for workflow execution.
+"""Domain entities for workflow execution.
 
 Models describe graph runtime state and avoid infrastructure-specific details.
 """
@@ -16,9 +15,7 @@ from graphon.enums import WorkflowExecutionStatus, WorkflowType
 
 
 class WorkflowExecution(BaseModel):
-    """
-    Domain model for a workflow execution within the graph runtime.
-    """
+    """Domain model for a workflow execution within the graph runtime."""
 
     id_: str = Field(...)
     workflow_id: str = Field(...)
@@ -40,8 +37,7 @@ class WorkflowExecution(BaseModel):
 
     @property
     def elapsed_time(self) -> float:
-        """
-        Calculate elapsed time in seconds.
+        """Calculate elapsed time in seconds.
         If workflow is not finished, use current time.
         """
         end_time = self.finished_at or datetime.now(UTC).replace(tzinfo=None)

{graphon-0.1.2 → graphon-0.2.0}/src/graphon/entities/workflow_node_execution.py

@@ -1,5 +1,4 @@
-"""
-Domain entities for workflow node execution.
+"""Domain entities for workflow node execution.
 
 These models capture node-level execution state for the graph runtime without
 describing storage or application-layer concerns.
@@ -19,8 +18,7 @@ from graphon.enums import (
 
 
 class WorkflowNodeExecution(BaseModel):
-    """
-    Domain model for workflow node execution.
+    """Domain model for workflow node execution.
 
     This model represents the graph-level record of a node execution and
     contains only execution state relevant to the runtime.
@@ -89,15 +87,22 @@ class WorkflowNodeExecution(BaseModel):
     def get_truncated_process_data(self) -> Mapping[str, Any] | None:
         return self._truncated_process_data
 
-    def set_truncated_inputs(self, truncated_inputs: Mapping[str, Any] | None):
+    def set_truncated_inputs(
+        self,
+        truncated_inputs: Mapping[str, Any] | None,
+    ) -> None:
         self._truncated_inputs = truncated_inputs
 
-    def set_truncated_outputs(self, truncated_outputs: Mapping[str, Any] | None):
+    def set_truncated_outputs(
+        self,
+        truncated_outputs: Mapping[str, Any] | None,
+    ) -> None:
         self._truncated_outputs = truncated_outputs
 
     def set_truncated_process_data(
-        self, truncated_process_data: Mapping[str, Any] | None
-    ):
+        self,
+        truncated_process_data: Mapping[str, Any] | None,
+    ) -> None:
         self._truncated_process_data = truncated_process_data
 
     def get_response_inputs(self) -> Mapping[str, Any] | None:
@@ -107,15 +112,15 @@ class WorkflowNodeExecution(BaseModel):
         return self.inputs
 
     @property
-    def inputs_truncated(self):
+    def inputs_truncated(self) -> bool:
         return self._truncated_inputs is not None
 
     @property
-    def outputs_truncated(self):
+    def outputs_truncated(self) -> bool:
         return self._truncated_outputs is not None
 
     @property
-    def process_data_truncated(self):
+    def process_data_truncated(self) -> bool:
         return self._truncated_process_data is not None
 
     def get_response_outputs(self) -> Mapping[str, Any] | None:
@@ -136,15 +141,15 @@ class WorkflowNodeExecution(BaseModel):
         process_data: Mapping[str, Any] | None = None,
         outputs: Mapping[str, Any] | None = None,
         metadata: Mapping[WorkflowNodeExecutionMetadataKey, Any] | None = None,
-    ):
-        """
-        Update the model from mappings.
+    ) -> None:
+        """Update the model from mappings.
 
         Args:
             inputs: The inputs to update
             process_data: The process data to update
             outputs: The outputs to update
             metadata: The metadata to update
+
         """
         if inputs is not None:
             self.inputs = dict(inputs)