graphon 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphon
-Version: 0.2.2
+Version: 0.3.0
 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.0}/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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'graphon'
-version = "0.2.2"
+version = "0.3.0"
 description = 'Graph execution engine for agentic AI workflows.'
 readme = 'README.md'
 license = 'Apache-2.0'

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

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import base64
 from collections.abc import Callable, Mapping
-from operator import attrgetter
 
 from graphon.model_runtime.entities.message_entities import (
     AudioPromptMessageContent,
@@ -40,15 +39,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,

graphon-0.3.0/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.0/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.3.0/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

{graphon-0.2.2 → graphon-0.3.0}/src/graphon/model_runtime/README.md

@@ -1,6 +1,8 @@
 # Model Runtime
 
-This module provides the interface for invoking and authenticating various models, and offers Dify a unified information and credentials form rule for model providers.
+This module provides the interfaces for invoking and authenticating various
+models, and offers Dify a unified information and credentials form rule for
+model providers.
 
 - On one hand, it decouples models from upstream and downstream processes, facilitating horizontal expansion for developers,
 - On the other hand, it allows for direct display of providers and models in the frontend interface by simply defining them in the backend, eliminating the need to modify frontend logic.
@@ -32,19 +34,35 @@ This module provides the interface for invoking and authenticating various model
 
 ## Structure
 
-Model Runtime is divided into three layers:
+Model Runtime is divided into protocol and implementation layers:
 
-- The outermost layer is the factory method
+- Provider/runtime protocols
 
-  It provides methods for obtaining all providers, all model lists, getting provider instances, and authenticating provider/model credentials.
+  Shared provider concerns live in `protocols/provider_runtime.py`, while each
+  model capability has its own protocol module such as
+  `protocols/llm_runtime.py`, `protocols/text_embedding_runtime.py`, and
+  `protocols/tts_runtime.py`. Downstream runtimes can implement only the
+  capabilities they need instead of satisfying a single monolithic interface.
 
-- The second layer is the provider layer
+- Aggregate runtime protocol
 
-  It provides the current provider's model list, model instance obtaining, provider credential authentication, and provider configuration rule information, **allowing horizontal expansion** to support different providers.
+  `protocols/runtime.py` composes the individual capability protocols into
+  `ModelRuntime` for adapters that intentionally implement the full surface
+  area.
 
-- The bottom layer is the model layer
+- Provider factory
 
-  It offers direct invocation of various model types, predefined model configuration information, getting predefined/remote model lists, model credential authentication methods. Different models provide additional special methods, like LLM's pre-computed tokens method, cost information obtaining method, etc., **allowing horizontal expansion** for different models under the same provider (within supported model types).
+  `model_providers/model_provider_factory.py` now depends only on
+  `ModelProviderRuntime`. It handles provider discovery, provider/model schema
+  lookup, credential validation, provider icon lookup, and provider-level model
+  list projection without assuming any invocation capability.
+
+- Model wrappers
+
+  Capability wrappers such as `LargeLanguageModel`, `TextEmbeddingModel`,
+  `RerankModel`, `Speech2TextModel`, `ModerationModel`, and `TTSModel` depend
+  only on their matching capability protocol. Instantiate those wrappers
+  directly when you need invocation behavior.
 
 ## Documentation
 

graphon-0.3.0/src/graphon/model_runtime/__init__.py

@@ -0,0 +1,21 @@
+from graphon.model_runtime.protocols import (
+    LLMModelRuntime,
+    ModelProviderRuntime,
+    ModelRuntime,
+    ModerationModelRuntime,
+    RerankModelRuntime,
+    SpeechToTextModelRuntime,
+    TextEmbeddingModelRuntime,
+    TTSModelRuntime,
+)
+
+__all__ = [
+    "LLMModelRuntime",
+    "ModelProviderRuntime",
+    "ModelRuntime",
+    "ModerationModelRuntime",
+    "RerankModelRuntime",
+    "SpeechToTextModelRuntime",
+    "TTSModelRuntime",
+    "TextEmbeddingModelRuntime",
+]

{graphon-0.2.2 → graphon-0.3.0}/src/graphon/model_runtime/entities/llm_entities.py

@@ -5,7 +5,16 @@ from decimal import Decimal
 from enum import StrEnum
 from typing import Any, Self, TypedDict
 
-from pydantic import BaseModel, Field
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictFloat,
+    StrictInt,
+    TypeAdapter,
+    field_validator,
+    model_validator,
+)
 
 from graphon.model_runtime.entities.message_entities import (
     AssistantPromptMessage,
@@ -42,6 +51,41 @@ class LLMUsageMetadata(TypedDict, total=False):
     time_to_generate: float
 
 
+class _LLMUsageMetadataInput(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    prompt_tokens: StrictInt = 0
+    completion_tokens: StrictInt = 0
+    total_tokens: StrictInt = 0
+    prompt_unit_price: Decimal = Decimal(0)
+    completion_unit_price: Decimal = Decimal(0)
+    total_price: Decimal = Decimal(0)
+    currency: str = "USD"
+    prompt_price_unit: Decimal = Decimal(0)
+    completion_price_unit: Decimal = Decimal(0)
+    prompt_price: Decimal = Decimal(0)
+    completion_price: Decimal = Decimal(0)
+    latency: StrictInt | StrictFloat = 0.0
+    time_to_first_token: StrictInt | StrictFloat | None = None
+    time_to_generate: StrictInt | StrictFloat | None = None
+
+    @field_validator("currency", mode="before")
+    @classmethod
+    def _normalize_currency(cls, value: object) -> str:
+        return str(value)
+
+    @model_validator(mode="after")
+    def _derive_total_tokens(self) -> _LLMUsageMetadataInput:
+        if self.total_tokens == 0 and (
+            self.prompt_tokens > 0 or self.completion_tokens > 0
+        ):
+            self.total_tokens = self.prompt_tokens + self.completion_tokens
+        return self
+
+
+_LLM_USAGE_METADATA_INPUT_ADAPTER = TypeAdapter(_LLMUsageMetadataInput)
+
+
 class LLMUsage(ModelUsage):
     """Model class for llm usage."""
 
@@ -80,7 +124,7 @@ class LLMUsage(ModelUsage):
         )
 
     @classmethod
-    def from_metadata(cls, metadata: LLMUsageMetadata) -> LLMUsage:
+    def from_metadata(cls, metadata: Mapping[str, object]) -> LLMUsage:
         """Create LLMUsage instance from metadata dictionary with default values.
 
         Args:
@@ -90,35 +134,22 @@ class LLMUsage(ModelUsage):
             LLMUsage instance with values from metadata or defaults
 
         """
-        prompt_tokens = metadata.get("prompt_tokens", 0)
-        completion_tokens = metadata.get("completion_tokens", 0)
-        total_tokens = metadata.get("total_tokens", 0)
-
-        # If total_tokens is not provided but prompt and completion tokens are,
-        # calculate total_tokens
-        if total_tokens == 0 and (prompt_tokens > 0 or completion_tokens > 0):
-            total_tokens = prompt_tokens + completion_tokens
-
-        return cls(
-            prompt_tokens=prompt_tokens,
-            completion_tokens=completion_tokens,
-            total_tokens=total_tokens,
-            prompt_unit_price=Decimal(str(metadata.get("prompt_unit_price", 0))),
-            completion_unit_price=Decimal(
-                str(metadata.get("completion_unit_price", 0)),
-            ),
-            total_price=Decimal(str(metadata.get("total_price", 0))),
-            currency=metadata.get("currency", "USD"),
-            prompt_price_unit=Decimal(str(metadata.get("prompt_price_unit", 0))),
-            completion_price_unit=Decimal(
-                str(metadata.get("completion_price_unit", 0)),
-            ),
-            prompt_price=Decimal(str(metadata.get("prompt_price", 0))),
-            completion_price=Decimal(str(metadata.get("completion_price", 0))),
-            latency=metadata.get("latency", 0.0),
-            time_to_first_token=metadata.get("time_to_first_token"),
-            time_to_generate=metadata.get("time_to_generate"),
+        normalized_metadata = _LLM_USAGE_METADATA_INPUT_ADAPTER.validate_python(
+            metadata,
+        )
+        payload = normalized_metadata.model_dump(mode="python")
+        payload["latency"] = float(normalized_metadata.latency)
+        payload["time_to_first_token"] = (
+            float(normalized_metadata.time_to_first_token)
+            if normalized_metadata.time_to_first_token is not None
+            else None
+        )
+        payload["time_to_generate"] = (
+            float(normalized_metadata.time_to_generate)
+            if normalized_metadata.time_to_generate is not None
+            else None
         )
+        return cls.model_validate(payload)
 
     def plus(self, other: LLMUsage) -> LLMUsage:
         """Add two LLMUsage instances together.