Add experimental inference runtime API envelope

flashdreams/flashdreams/runtime/__init__.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Experimental inference runtime API envelope.
+
+This package defines the small v0 boundary above ``flashdreams.infra``. It is
+intentionally additive while integrations migrate onto it.
+"""
+
+from flashdreams.runtime.config import ExecutionBackend, InferenceConfig, Precision
+from flashdreams.runtime.inputs import (
+    InputField,
+    ModelInputs,
+    ModelInputSchema,
+    TimeWindow,
+    UserInputEvent,
+    UserInputs,
+    UserInputSchema,
+)
+from flashdreams.runtime.interfaces import (
+    InferenceRuntime,
+    InferenceSession,
+    ModelAdapter,
+    StepRequest,
+    StepResult,
+)
+from flashdreams.runtime.mapping import IdentityInputMapping, InputMapping
+from flashdreams.runtime.metrics import (
+    InMemoryMetricsRecorder,
+    MetricsRecorder,
+    NullMetricsRecorder,
+    RuntimeMetricSample,
+)
+from flashdreams.runtime.output import NullOutputTarget, OutputArtifact, OutputTarget
+
+__all__ = [
+    "ExecutionBackend",
+    "IdentityInputMapping",
+    "InferenceConfig",
+    "InferenceRuntime",
+    "InferenceSession",
+    "InMemoryMetricsRecorder",
+    "InputField",
+    "InputMapping",
+    "MetricsRecorder",
+    "ModelAdapter",
+    "ModelInputs",
+    "ModelInputSchema",
+    "NullMetricsRecorder",
+    "NullOutputTarget",
+    "OutputArtifact",
+    "OutputTarget",
+    "Precision",
+    "RuntimeMetricSample",
+    "StepRequest",
+    "StepResult",
+    "TimeWindow",
+    "UserInputEvent",
+    "UserInputs",
+    "UserInputSchema",
+]

flashdreams/flashdreams/runtime/config.py

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Runtime-facing configuration envelope."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, Mapping
+
+ExecutionBackend = Literal["local", "local-distributed", "external", "hosted"]
+"""Execution backend families the v0 envelope leaves room for."""
+
+Precision = Literal["auto", "fp32", "fp16", "bf16"]
+"""Coarse runtime precision choices."""
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class InferenceConfig:
+    """Model/runtime execution settings.
+
+    Prompts, user controls, browser settings, output paths, and benchmark
+    directories intentionally live outside this object.
+    """
+
+    model_id: str
+    """Stable model or adapter identity."""
+
+    preset_id: str | None = None
+    """Optional preset identity under :attr:`model_id`."""
+
+    checkpoint: str | Path | None = None
+    """Optional checkpoint or model-asset selector understood by the adapter."""
+
+    backend: ExecutionBackend = "local"
+    """Runtime backend family."""
+
+    device: str | None = None
+    """Optional device selector such as ``cuda`` or ``cuda:0``."""
+
+    precision: Precision = "auto"
+    """Preferred compute precision."""
+
+    compile: bool | None = None
+    """Whether model compilation is requested, disabled, or left to the adapter."""
+
+    cuda_graph: bool | None = None
+    """Whether CUDA graph capture is requested, disabled, or left to the adapter."""
+
+    attention_backend: str | None = None
+    """Optional attention implementation selector."""
+
+    cache_policy: str | None = None
+    """Optional cache policy selector."""
+
+    runtime_options: Mapping[str, Any] = field(default_factory=dict)
+    """Adapter/backend-specific runtime options."""
+
+    resource_hints: Mapping[str, Any] = field(default_factory=dict)
+    """Cheap resource hints for launchers, schedulers, or hosted backends."""
+
+    def __post_init__(self) -> None:
+        if not self.model_id.strip():
+            raise ValueError("InferenceConfig.model_id must be non-empty.")

flashdreams/flashdreams/runtime/inputs.py

@@ -0,0 +1,144 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""User- and model-input envelopes for the experimental runtime API."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class TimeWindow:
+    """Half-open time window in canonical seconds."""
+
+    start_s: float
+    end_s: float
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.start_s) or not math.isfinite(self.end_s):
+            raise ValueError("TimeWindow bounds must be finite seconds.")
+        if self.start_s < 0 or self.end_s < 0:
+            raise ValueError("TimeWindow bounds must be non-negative.")
+        if self.end_s < self.start_s:
+            raise ValueError("TimeWindow.end_s must be >= start_s.")
+
+    def contains(self, timestamp_s: float) -> bool:
+        """Return whether ``timestamp_s`` falls within this half-open window."""
+        return self.start_s <= timestamp_s < self.end_s
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class InputField:
+    """Lightweight schema field for user snapshots or model inputs."""
+
+    name: str
+    required: bool = True
+    semantic_type: str | None = None
+    description: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError("InputField.name must be non-empty.")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class UserInputSchema:
+    """Minimal metadata for controls an app, transport, or trace can provide."""
+
+    event_kinds: frozenset[str] = field(default_factory=frozenset)
+    snapshot_fields: tuple[InputField, ...] = ()
+    description: str = ""
+
+    def supports_event_kinds(self, kinds: Iterable[str]) -> bool:
+        """Return whether every requested event kind is declared supported."""
+        requested = frozenset(kinds)
+        if not requested:
+            return True
+        return requested.issubset(self.event_kinds)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ModelInputSchema:
+    """Minimal metadata for model-facing initial and per-step inputs."""
+
+    initial_fields: tuple[InputField, ...] = ()
+    step_fields: tuple[InputField, ...] = ()
+    description: str = ""
+
+    def missing_initial(self, inputs: "ModelInputs") -> tuple[str, ...]:
+        """Return required initial fields absent from ``inputs``."""
+        return _missing_required(self.initial_fields, inputs.initial)
+
+    def missing_step(self, inputs: "ModelInputs") -> tuple[str, ...]:
+        """Return required per-step fields absent from ``inputs``."""
+        return _missing_required(self.step_fields, inputs.step)
+
+    def require_initial(self, inputs: "ModelInputs") -> None:
+        """Raise if required initial fields are absent."""
+        missing = self.missing_initial(inputs)
+        if missing:
+            raise ValueError(f"Missing required initial model input(s): {missing}")
+
+    def require_step(self, inputs: "ModelInputs") -> None:
+        """Raise if required per-step fields are absent."""
+        missing = self.missing_step(inputs)
+        if missing:
+            raise ValueError(f"Missing required step model input(s): {missing}")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class UserInputEvent:
+    """Timestamped user-facing input event."""
+
+    timestamp_s: float
+    kind: str
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    source: str | None = None
+    event_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.timestamp_s) or self.timestamp_s < 0:
+            raise ValueError("UserInputEvent.timestamp_s must be finite and >= 0.")
+        if not self.kind.strip():
+            raise ValueError("UserInputEvent.kind must be non-empty.")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class UserInputs:
+    """Transport-neutral user inputs for live, replayed, synthetic, or no-op runs."""
+
+    events: tuple[UserInputEvent, ...] = ()
+    snapshot: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def window(self, time_window: TimeWindow) -> "UserInputs":
+        """Return inputs with events filtered to ``time_window``."""
+        return UserInputs(
+            events=tuple(
+                event for event in self.events if time_window.contains(event.timestamp_s)
+            ),
+            snapshot=self.snapshot,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ModelInputs:
+    """Model-facing input payloads split by initial and per-step use."""
+
+    initial: Mapping[str, Any] = field(default_factory=dict)
+    step: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def with_step(self, step: Mapping[str, Any]) -> "ModelInputs":
+        """Return a copy with replaced per-step payload."""
+        return ModelInputs(initial=self.initial, step=step, metadata=self.metadata)
+
+
+def _missing_required(
+    fields: tuple[InputField, ...], payload: Mapping[str, Any]
+) -> tuple[str, ...]:
+    return tuple(field.name for field in fields if field.required and field.name not in payload)

flashdreams/flashdreams/runtime/interfaces.py

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Protocols for model adapters, runtimes, and sessions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Mapping, Protocol, runtime_checkable
+
+from flashdreams.runtime.config import InferenceConfig
+from flashdreams.runtime.inputs import (
+    ModelInputs,
+    ModelInputSchema,
+    TimeWindow,
+    UserInputSchema,
+)
+
+if TYPE_CHECKING:
+    from flashdreams.runtime.mapping import InputMapping
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class StepRequest:
+    """Model-session request for the next step's inputs."""
+
+    step_index: int
+    model_input_schema: ModelInputSchema | None = None
+    user_input_window: TimeWindow | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.step_index < 0:
+            raise ValueError("StepRequest.step_index must be >= 0.")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class StepResult:
+    """Generated output and metadata for one inference step."""
+
+    step_index: int
+    output: Any = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    metrics: Mapping[str, float | int] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.step_index < 0:
+            raise ValueError("StepResult.step_index must be >= 0.")
+
+
+@runtime_checkable
+class InferenceSession(Protocol):
+    """One rollout or stream with isolated cache/state."""
+
+    def next_step_request(self) -> StepRequest:
+        """Describe the model inputs needed for the next call to :meth:`step`."""
+        ...
+
+    def step(self, inputs: ModelInputs) -> StepResult:
+        """Run one sequential inference step."""
+        ...
+
+    def reset(self, inputs: ModelInputs | None = None) -> None:
+        """Reset this session's rollout state when the backend supports it."""
+        ...
+
+    def close(self) -> None:
+        """Release per-session resources."""
+        ...
+
+
+@runtime_checkable
+class InferenceRuntime(Protocol):
+    """Heavyweight reusable runtime created from :class:`InferenceConfig`."""
+
+    def start_session(self, inputs: ModelInputs) -> InferenceSession:
+        """Create an isolated session from initial model inputs."""
+        ...
+
+    def close(self) -> None:
+        """Release model/backend resources."""
+        ...
+
+
+@runtime_checkable
+class ModelAdapter(Protocol):
+    """Model-specific boundary that connects FlashDreams to a model runtime."""
+
+    @property
+    def model_id(self) -> str:
+        """Stable model or adapter identity."""
+        ...
+
+    @property
+    def model_input_schema(self) -> ModelInputSchema:
+        """Initial and per-step model input requirements."""
+        ...
+
+    @property
+    def user_input_schema(self) -> UserInputSchema | None:
+        """User input capabilities this adapter can map directly, if any."""
+        ...
+
+    def default_input_mapping(self) -> "InputMapping | None":
+        """Return the adapter's default user-to-model input mapping, if any."""
+        ...
+
+    def validate_config(self, config: InferenceConfig) -> None:
+        """Fail early for unsupported runtime settings."""
+        ...
+
+    def create_runtime(self, config: InferenceConfig) -> InferenceRuntime:
+        """Initialize and return the heavyweight runtime."""
+        ...