graphon 0.2.2__tar.gz → 0.3.1__tar.gz

{graphon-0.2.2 → graphon-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphon
-Version: 0.2.2
+Version: 0.3.1
 Summary: Graph execution engine for agentic AI workflows.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -73,7 +73,9 @@ make test
 ```
 
 `make dev` installs the project, syncs development dependencies, and sets up
-[`prek`](https://prek.j178.dev/) Git hooks.
+[`prek`](https://prek.j178.dev/) Git hooks. `make test` is the progressive
+local validation entrypoint: it formats, applies lint fixes, runs `ty check`,
+and then runs `pytest`.
 
 ## Run the Example Workflow
 
@@ -169,9 +171,10 @@ construction, input seeding, and streamed output handling.
 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.
+CI currently validates pull request titles, runs `make check` including
+`uv.lock` freshness validation, and runs `uv run pytest` on Python 3.12 and
+3.13. Python 3.14 is currently excluded because `unstructured` does not yet
+support it.
 
 ## License
 

{graphon-0.2.2 → graphon-0.3.1}/README.md

@@ -44,7 +44,9 @@ make test
 ```
 
 `make dev` installs the project, syncs development dependencies, and sets up
-[`prek`](https://prek.j178.dev/) Git hooks.
+[`prek`](https://prek.j178.dev/) Git hooks. `make test` is the progressive
+local validation entrypoint: it formats, applies lint fixes, runs `ty check`,
+and then runs `pytest`.
 
 ## Run the Example Workflow
 
@@ -140,9 +142,10 @@ construction, input seeding, and streamed output handling.
 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.
+CI currently validates pull request titles, runs `make check` including
+`uv.lock` freshness validation, and runs `uv run pytest` on Python 3.12 and
+3.13. Python 3.14 is currently excluded because `unstructured` does not yet
+support it.
 
 ## License
 

{graphon-0.2.2 → graphon-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'graphon'
-version = "0.2.2"
+version = "0.3.1"
 description = 'Graph execution engine for agentic AI workflows.'
 readme = 'README.md'
 license = 'Apache-2.0'
@@ -79,6 +79,7 @@ ignore-one-line-docstrings = true
 'tests/**/*.py' = [
     'S101',    # Assert statements used for pytest.
     'PLR2004', # Magic value used in test cases.
+    'PLC2701', # Allow import private members from graphon module.
 ]
 
 [tool.ty.environment]

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/file/file_manager.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import base64
 from collections.abc import Callable, Mapping
-from operator import attrgetter
+from typing import assert_never
 
 from graphon.model_runtime.entities.message_entities import (
     AudioPromptMessageContent,
@@ -40,15 +40,35 @@ def _get_file_transfer_method_value(file: File) -> str:
     return file.transfer_method.value
 
 
-_FILE_ATTRIBUTE_GETTERS: Mapping[FileAttribute, Callable[[File], object]] = {
+def _get_file_size(file: File) -> int:
+    return file.size
+
+
+def _get_file_name(file: File) -> str | None:
+    return file.filename
+
+
+def _get_file_mime_type(file: File) -> str | None:
+    return file.mime_type
+
+
+def _get_file_extension(file: File) -> str | None:
+    return file.extension
+
+
+def _get_file_related_id(file: File) -> str | None:
+    return file.related_id
+
+
+_FILE_ATTRIBUTE_GETTERS: Mapping[FileAttribute, Callable[[File], str | int | None]] = {
     FileAttribute.TYPE: _get_file_type_value,
-    FileAttribute.SIZE: attrgetter("size"),
-    FileAttribute.NAME: attrgetter("filename"),
-    FileAttribute.MIME_TYPE: attrgetter("mime_type"),
+    FileAttribute.SIZE: _get_file_size,
+    FileAttribute.NAME: _get_file_name,
+    FileAttribute.MIME_TYPE: _get_file_mime_type,
     FileAttribute.TRANSFER_METHOD: _get_file_transfer_method_value,
     FileAttribute.URL: _to_url,
-    FileAttribute.EXTENSION: attrgetter("extension"),
-    FileAttribute.RELATED_ID: attrgetter("related_id"),
+    FileAttribute.EXTENSION: _get_file_extension,
+    FileAttribute.RELATED_ID: _get_file_related_id,
 }
 _PROMPT_CONTENT_CLASS_BY_FILE_TYPE: Mapping[
     FileType,
@@ -121,7 +141,8 @@ def _download_file_content(file: File, /) -> bytes:
 
 
 def _get_encoded_string(f: File, /) -> str:
-    match f.transfer_method:
+    transfer_method = f.transfer_method
+    match transfer_method:
         case FileTransferMethod.REMOTE_URL:
             if f.remote_url is None:
                 msg = "Missing file remote_url"
@@ -138,6 +159,8 @@ def _get_encoded_string(f: File, /) -> str:
             data = _download_file_content(f)
         case FileTransferMethod.DATASOURCE_FILE:
             data = _download_file_content(f)
+        case _:
+            assert_never(transfer_method)
 
     return base64.b64encode(data).decode("utf-8")
 

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/file/models.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import base64
 import json
 from collections.abc import Mapping, Sequence
-from typing import Any
+from typing import Any, assert_never
 
 from pydantic import BaseModel, Field, model_validator
 
@@ -16,6 +16,10 @@ from .enums import FileTransferMethod, FileType
 _FILE_REFERENCE_PREFIX = "dify-file-ref:"
 
 
+class _FileConstructorConflictError(Exception):
+    """Raised when multiple constructor inputs disagree on file identity."""
+
+
 def sign_tool_file(
     *,
     tool_file_id: str,
@@ -113,7 +117,7 @@ class File(BaseModel):
         *,
         file_id: str | None = None,
         tenant_id: str | None = None,
-        file_type: FileType,
+        file_type: FileType | None = None,
         transfer_method: FileTransferMethod,
         remote_url: str | None = None,
         reference: str | None = None,
@@ -129,18 +133,39 @@ class File(BaseModel):
         tool_file_id: str | None = None,
         upload_file_id: str | None = None,
         datasource_file_id: str | None = None,
+        **legacy_kwargs: Any,
     ) -> None:
+        legacy_id = legacy_kwargs.pop("id", None)
+        legacy_type = legacy_kwargs.pop("type", None)
+        if legacy_kwargs:
+            unexpected_keys = ", ".join(sorted(legacy_kwargs))
+            msg = f"Unexpected keyword arguments: {unexpected_keys}"
+            raise TypeError(msg)
+
         legacy_record_id = (
             related_id or tool_file_id or upload_file_id or datasource_file_id
         )
+        if legacy_id is not None and file_id is not None and legacy_id != file_id:
+            msg = "Conflicting file identifiers"
+            raise _FileConstructorConflictError(msg)
+        if (
+            legacy_type is not None
+            and file_type is not None
+            and legacy_type != file_type
+        ):
+            msg = "Conflicting file types"
+            raise _FileConstructorConflictError(msg)
+
         normalized_reference = reference
         if normalized_reference is None and legacy_record_id is not None:
             normalized_reference = str(legacy_record_id)
         _, parsed_storage_key = _parse_reference(normalized_reference)
+        normalized_file_id = file_id if file_id is not None else legacy_id
+        normalized_file_type = file_type if file_type is not None else legacy_type
 
         super().__init__(
-            id=file_id,
-            type=file_type,
+            id=normalized_file_id,
+            type=normalized_file_type,
             transfer_method=transfer_method,
             remote_url=remote_url,
             reference=normalized_reference,
@@ -190,7 +215,8 @@ class File(BaseModel):
 
     @model_validator(mode="after")
     def validate_after(self) -> File:
-        match self.transfer_method:
+        transfer_method = self.transfer_method
+        match transfer_method:
             case FileTransferMethod.REMOTE_URL:
                 if not self.remote_url:
                     msg = "Missing file url"
@@ -213,6 +239,8 @@ class File(BaseModel):
                 if not self.reference:
                     msg = "Missing file reference"
                     raise ValueError(msg)
+            case _:
+                assert_never(transfer_method)
         return self
 
     @property

graphon-0.3.1/src/graphon/file/runtime.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from .protocols import WorkflowFileRuntimeProtocol
+
+
+class WorkflowFileRuntimeNotConfiguredError(RuntimeError):
+    """Raised when workflow file runtime dependencies were not configured."""
+
+
+def _not_configured_error() -> WorkflowFileRuntimeNotConfiguredError:
+    msg = (
+        "workflow file runtime is not configured; call "
+        "set_workflow_file_runtime(...) first"
+    )
+    return WorkflowFileRuntimeNotConfiguredError(msg)
+
+
+class WorkflowFileRuntimeRegistry:
+    """Small helper that keeps runtime configuration explicit."""
+
+    def __init__(
+        self,
+        runtime: WorkflowFileRuntimeProtocol | None = None,
+    ) -> None:
+        self._runtime = runtime
+
+    def set(
+        self,
+        runtime: WorkflowFileRuntimeProtocol,
+    ) -> WorkflowFileRuntimeProtocol:
+        self._runtime = runtime
+        return runtime
+
+    def peek(self) -> WorkflowFileRuntimeProtocol | None:
+        return self._runtime
+
+    def get(self) -> WorkflowFileRuntimeProtocol:
+        runtime = self.peek()
+        if runtime is None:
+            raise _not_configured_error()
+        return runtime
+
+
+_workflow_file_runtime_registry = WorkflowFileRuntimeRegistry()
+
+
+def configure_workflow_file_runtime(
+    runtime: WorkflowFileRuntimeProtocol,
+) -> WorkflowFileRuntimeProtocol:
+    """Compatibility alias for set_workflow_file_runtime()."""
+    return _workflow_file_runtime_registry.set(runtime)
+
+
+def set_workflow_file_runtime(runtime: WorkflowFileRuntimeProtocol) -> None:
+    _workflow_file_runtime_registry.set(runtime)
+
+
+def get_workflow_file_runtime() -> WorkflowFileRuntimeProtocol:
+    return _workflow_file_runtime_registry.get()
+
+
+def peek_workflow_file_runtime() -> WorkflowFileRuntimeProtocol | None:
+    return _workflow_file_runtime_registry.peek()

graphon-0.3.1/src/graphon/file/tool_file_parser.py

@@ -0,0 +1,59 @@
+from collections.abc import Callable
+from typing import Any
+
+ToolFileManagerFactory = Callable[[], Any]
+
+
+class ToolFileManagerFactoryNotSetError(RuntimeError):
+    """Raised when code requires a configured tool file manager factory."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Tool file manager factory is not configured. "
+            "Call set_tool_file_manager_factory(...)."
+        )
+
+
+class _ToolFileManagerFactoryRegistry:
+    """Store the active tool file manager factory behind an explicit API."""
+
+    def __init__(self) -> None:
+        self._factory: ToolFileManagerFactory | None = None
+
+    def get(self) -> ToolFileManagerFactory | None:
+        return self._factory
+
+    def require(self) -> ToolFileManagerFactory:
+        factory = self.get()
+        if factory is None:
+            raise ToolFileManagerFactoryNotSetError
+        return factory
+
+    def set(self, factory: ToolFileManagerFactory) -> None:
+        self._factory = factory
+
+
+_tool_file_manager_factory_registry = _ToolFileManagerFactoryRegistry()
+
+
+def get_tool_file_manager_factory() -> ToolFileManagerFactory | None:
+    return _tool_file_manager_factory_registry.get()
+
+
+def require_tool_file_manager_factory() -> ToolFileManagerFactory:
+    return _tool_file_manager_factory_registry.require()
+
+
+def set_tool_file_manager_factory(factory: ToolFileManagerFactory) -> None:
+    """Compatibility wrapper around the registry's explicit setter."""
+
+    _tool_file_manager_factory_registry.set(factory)
+
+
+__all__ = [
+    "ToolFileManagerFactory",
+    "ToolFileManagerFactoryNotSetError",
+    "get_tool_file_manager_factory",
+    "require_tool_file_manager_factory",
+    "set_tool_file_manager_factory",
+]

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph/graph.py

@@ -44,6 +44,12 @@ class NodeFactory(Protocol):
 class Graph:
     """Graph representation with nodes and edges for workflow execution."""
 
+    nodes: dict[str, Node]
+    edges: dict[str, Edge]
+    in_edges: dict[str, list[str]]
+    out_edges: dict[str, list[str]]
+    root_node: Node
+
     def __init__(
         self,
         *,

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/error_handler.py

@@ -2,7 +2,7 @@
 
 import logging
 import time
-from typing import final
+from typing import assert_never, final
 
 from graphon.enums import (
     ErrorStrategy as ErrorStrategyEnum,
@@ -88,6 +88,8 @@ class ErrorHandler:
                 return self._handle_fail_branch(event)
             case ErrorStrategyEnum.DEFAULT_VALUE:
                 return self._handle_default_value(event)
+            case _:
+                assert_never(strategy)
 
     def _handle_abort(self, event: NodeRunFailedEvent) -> None:
         """Handle error by aborting execution.

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/event_management/event_handlers.py

@@ -3,7 +3,7 @@
 import logging
 from collections.abc import Mapping
 from functools import singledispatchmethod
-from typing import TYPE_CHECKING, final
+from typing import final
 
 from graphon.enums import ErrorStrategy, NodeExecutionType, NodeState
 from graphon.graph.graph import Graph
@@ -39,11 +39,10 @@ from graphon.runtime.graph_runtime_state import (
     ResponseStreamCoordinatorProtocol,
 )
 
-if TYPE_CHECKING:
-    from ..error_handler import ErrorHandler
-    from ..graph_state_manager import GraphStateManager
-    from ..graph_traversal import EdgeProcessor
-    from .event_manager import EventManager
+from ..error_handler import ErrorHandler
+from ..graph_state_manager import GraphStateManager
+from ..graph_traversal.edge_processor import EdgeProcessor
+from .event_manager import EventManager
 
 logger = logging.getLogger(__name__)
 
@@ -62,10 +61,10 @@ class EventHandler:
         graph_runtime_state: GraphRuntimeState,
         graph_execution: GraphExecutionProtocol,
         response_coordinator: ResponseStreamCoordinatorProtocol,
-        event_collector: "EventManager",
-        edge_processor: "EdgeProcessor",
-        state_manager: "GraphStateManager",
-        error_handler: "ErrorHandler",
+        event_collector: EventManager,
+        edge_processor: EdgeProcessor,
+        state_manager: GraphStateManager,
+        error_handler: ErrorHandler,
     ) -> None:
         """Initialize the event handler registry.
 

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/graph_engine.py

@@ -9,8 +9,9 @@ from __future__ import annotations
 import logging
 import queue
 from collections.abc import Generator
-from typing import TYPE_CHECKING, final
+from typing import final
 
+from graphon.entities.graph_init_params import GraphInitParams
 from graphon.entities.workflow_start_reason import WorkflowStartReason
 from graphon.enums import NodeExecutionType
 from graphon.graph.graph import Graph
@@ -50,9 +51,6 @@ from .layers.base import GraphEngineLayer
 from .orchestration import Dispatcher, ExecutionCoordinator
 from .worker_management import WorkerPool
 
-if TYPE_CHECKING:
-    from graphon.entities.graph_init_params import GraphInitParams
-
 logger = logging.getLogger(__name__)
 
 

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/graph_traversal/edge_processor.py

@@ -1,7 +1,7 @@
 """Edge processing logic for graph traversal."""
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, final
+from typing import final
 
 from graphon.enums import NodeExecutionType
 from graphon.graph.edge import Edge
@@ -10,9 +10,7 @@ from graphon.graph_events.node import NodeRunStreamChunkEvent
 from graphon.runtime.graph_runtime_state import ResponseStreamCoordinatorProtocol
 
 from ..graph_state_manager import GraphStateManager
-
-if TYPE_CHECKING:
-    from .skip_propagator import SkipPropagator
+from .skip_propagator import SkipPropagator
 
 
 @final
@@ -29,7 +27,7 @@ class EdgeProcessor:
         graph: Graph,
         state_manager: GraphStateManager,
         response_coordinator: ResponseStreamCoordinatorProtocol,
-        skip_propagator: "SkipPropagator",
+        skip_propagator: SkipPropagator,
     ) -> None:
         """Initialize the edge processor.
 

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/layers/execution_limits.py

@@ -10,7 +10,7 @@ When limits are exceeded, the layer automatically aborts execution.
 import logging
 import time
 from enum import StrEnum
-from typing import final, override
+from typing import assert_never, final, override
 
 from graphon.graph_engine.entities.commands import AbortCommand, CommandType
 from graphon.graph_engine.layers.base import GraphEngineLayer
@@ -170,5 +170,4 @@ class ExecutionLimitsLayer(GraphEngineLayer):
                     f"{elapsed_time:.2f}s > {self.max_time}s"
                 )
             case _:
-                msg = f"Unsupported limit type: {limit_type}"
-                raise ValueError(msg)
+                assert_never(limit_type)

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/orchestration/dispatcher.py

@@ -4,7 +4,7 @@ import logging
 import queue
 import threading
 import time
-from typing import TYPE_CHECKING, final
+from typing import final
 
 from graphon.graph_events.base import GraphNodeEventBase
 from graphon.graph_events.node import (
@@ -14,11 +14,9 @@ from graphon.graph_events.node import (
 )
 
 from ..event_management import EventManager
+from ..event_management.event_handlers import EventHandler
 from .execution_coordinator import ExecutionCoordinator
 
-if TYPE_CHECKING:
-    from ..event_management import EventHandler
-
 logger = logging.getLogger(__name__)
 
 
@@ -39,7 +37,7 @@ class Dispatcher:
     def __init__(
         self,
         event_queue: queue.Queue[GraphNodeEventBase],
-        event_handler: "EventHandler",
+        event_handler: EventHandler,
         execution_coordinator: ExecutionCoordinator,
         event_emitter: EventManager | None = None,
     ) -> None:

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/ready_queue/factory.py

@@ -3,13 +3,9 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING
 
 from .in_memory import InMemoryReadyQueue
-from .protocol import ReadyQueueState
-
-if TYPE_CHECKING:
-    from .protocol import ReadyQueue
+from .protocol import ReadyQueue, ReadyQueueState
 
 _READY_QUEUE_BUILDERS: dict[str, tuple[Callable[[], ReadyQueue], str]] = {
     "InMemoryReadyQueue": (InMemoryReadyQueue, "1.0"),

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/graph_engine/response_coordinator/coordinator.py

@@ -1,14 +1,10 @@
-"""Main ResponseStreamCoordinator implementation.
-
-This module contains the public ResponseStreamCoordinator class that manages
-response streaming sessions and ensures ordered streaming of responses.
-"""
+from __future__ import annotations
 
 import logging
 from collections import deque
 from collections.abc import Sequence
 from threading import RLock
-from typing import Literal, final
+from typing import TYPE_CHECKING, Literal, final
 from uuid import uuid4
 
 from pydantic import BaseModel, Field
@@ -25,6 +21,9 @@ from graphon.runtime.variable_pool import VariablePool
 from .path import Path
 from .session import ResponseSession
 
+if TYPE_CHECKING:
+    from graphon.graph.graph import Graph
+
 logger = logging.getLogger(__name__)
 
 # Type definitions
@@ -78,7 +77,9 @@ class ResponseStreamCoordinator:
     Ensures ordered streaming of responses based on upstream node outputs and constants.
     """
 
-    def __init__(self, variable_pool: "VariablePool", graph: GraphProtocol) -> None:
+    def __init__(
+        self, variable_pool: VariablePool, graph: GraphProtocol | Graph
+    ) -> None:
         """Initialize coordinator with variable pool.
 
         Args:

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/http/__init__.py

@@ -1,7 +1,11 @@
 from .client import HttpClientMaxRetriesExceededError, HttpxHttpClient
 from .protocols import HttpClientProtocol, HttpResponseProtocol
 from .response import HttpHeaders, HttpResponse, HttpStatusError
-from .runtime import get_default_http_client, get_http_client, set_http_client
+from .runtime import (
+    get_default_http_client,
+    get_http_client,
+    set_http_client,
+)
 
 __all__ = [
     "HttpClientMaxRetriesExceededError",

{graphon-0.2.2 → graphon-0.3.1}/src/graphon/http/response.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import email.message
 from collections.abc import Iterator, Mapping
 from http import HTTPStatus
 from typing import TYPE_CHECKING, Any
@@ -84,11 +85,11 @@ class HttpResponse:
         if self._cached_text is not None:
             return self._cached_text
 
-        detected_encoding = charset_normalizer.from_bytes(self.content).best()
-        if detected_encoding and detected_encoding.encoding:
+        charset = self._extract_charset_from_content_type()
+        if charset:
             try:
-                self._cached_text = self.content.decode(detected_encoding.encoding)
-            except (UnicodeDecodeError, TypeError, LookupError):
+                self._cached_text = self.content.decode(charset, errors="replace")
+            except (TypeError, LookupError):
                 pass
             else:
                 return self._cached_text
@@ -97,9 +98,27 @@ class HttpResponse:
             self._cached_text = self._fallback_text
             return self._cached_text
 
+        detected_encoding = charset_normalizer.from_bytes(self.content).best()
+        if detected_encoding and detected_encoding.encoding:
+            try:
+                self._cached_text = self.content.decode(detected_encoding.encoding)
+            except (UnicodeDecodeError, TypeError, LookupError):
+                pass
+            else:
+                return self._cached_text
+
         self._cached_text = self.content.decode("utf-8", errors="replace")
         return self._cached_text
 
+    def _extract_charset_from_content_type(self) -> str | None:
+        content_type = self.headers.get("content-type", "")
+        if not content_type:
+            return None
+
+        message = email.message.Message()
+        message["content-type"] = content_type
+        return message.get_content_charset(failobj=None)
+
     def raise_for_status(self) -> None:
         if not self.is_success:
             raise HttpStatusError(self)

graphon-0.3.1/src/graphon/http/runtime.py

@@ -0,0 +1,20 @@
+from .client import HttpxHttpClient
+from .protocols import HttpClientProtocol
+
+_default_http_client: HttpClientProtocol = HttpxHttpClient()
+
+
+def set_http_client(http_client: HttpClientProtocol) -> None:
+    """Compatibility wrapper for replacing the process default client."""
+    global _default_http_client  # noqa: PLW0603
+    _default_http_client = http_client
+
+
+def get_http_client() -> HttpClientProtocol:
+    """Return the configured process default HTTP client."""
+    return _default_http_client
+
+
+def get_default_http_client() -> HttpClientProtocol:
+    """Return the process default HTTP client."""
+    return _default_http_client