jointfm-inference 0.9.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. jointfm_inference/__init__.py +19 -0
  2. jointfm_inference/cli.py +123 -0
  3. jointfm_inference/core/__init__.py +15 -0
  4. jointfm_inference/core/timing.py +170 -0
  5. jointfm_inference/core/version.py +45 -0
  6. jointfm_inference/data/__init__.py +15 -0
  7. jointfm_inference/data/adapters.py +190 -0
  8. jointfm_inference/data/time_index.py +256 -0
  9. jointfm_inference/data/types.py +110 -0
  10. jointfm_inference/model/__init__.py +15 -0
  11. jointfm_inference/model/checkpoint.py +250 -0
  12. jointfm_inference/model/inference/__init__.py +92 -0
  13. jointfm_inference/model/inference/_bounds.py +83 -0
  14. jointfm_inference/model/inference/adapter.py +225 -0
  15. jointfm_inference/model/inference/backend_registry.py +95 -0
  16. jointfm_inference/model/inference/capacity_envelope.py +126 -0
  17. jointfm_inference/model/inference/checkpoint.py +55 -0
  18. jointfm_inference/model/inference/conditional_query.py +740 -0
  19. jointfm_inference/model/inference/conditioning.py +572 -0
  20. jointfm_inference/model/inference/contract.py +436 -0
  21. jointfm_inference/model/inference/interval_conditioning.py +391 -0
  22. jointfm_inference/model/inference/jointfm_1_backend.py +250 -0
  23. jointfm_inference/model/inference/jointfm_1_grid.py +166 -0
  24. jointfm_inference/model/inference/session.py +159 -0
  25. jointfm_inference/model/inference/time_index.py +102 -0
  26. jointfm_inference/model/jointfm_1/__init__.py +15 -0
  27. jointfm_inference/model/jointfm_1/config.py +258 -0
  28. jointfm_inference/model/jointfm_1/encoder.py +267 -0
  29. jointfm_inference/model/jointfm_1/head.py +434 -0
  30. jointfm_inference/model/jointfm_1/input_scale.py +119 -0
  31. jointfm_inference/model/jointfm_1/loader.py +69 -0
  32. jointfm_inference/model/jointfm_1/marginals.py +548 -0
  33. jointfm_inference/model/jointfm_1/model.py +275 -0
  34. jointfm_inference/model/jointfm_1/pooling.py +83 -0
  35. jointfm_inference/model/jointfm_1/readouts.py +255 -0
  36. jointfm_inference/model/jointfm_1/sign_symmetry.py +109 -0
  37. jointfm_inference/model/jointfm_1/tail_map.py +444 -0
  38. jointfm_inference/model/linalg.py +230 -0
  39. jointfm_inference/model/precision.py +117 -0
  40. jointfm_inference/model/probe.py +545 -0
  41. jointfm_inference/model/profile.py +530 -0
  42. jointfm_inference/model/service/__init__.py +56 -0
  43. jointfm_inference/model/service/checkpoint_source.py +141 -0
  44. jointfm_inference/model/service/column_specs.py +160 -0
  45. jointfm_inference/model/service/conditions.py +247 -0
  46. jointfm_inference/model/service/config.py +307 -0
  47. jointfm_inference/model/service/constants.py +64 -0
  48. jointfm_inference/model/service/data_frames.py +224 -0
  49. jointfm_inference/model/service/errors.py +88 -0
  50. jointfm_inference/model/service/http_handler.py +226 -0
  51. jointfm_inference/model/service/http_service.py +818 -0
  52. jointfm_inference/model/service/scoring.py +119 -0
  53. jointfm_inference/model/service/serialization.py +111 -0
  54. jointfm_inference/model/service/server.py +92 -0
  55. jointfm_inference/model/service/time_conversion.py +35 -0
  56. jointfm_inference/model/service/validation.py +207 -0
  57. jointfm_inference/model/service/wire_schema/__init__.py +97 -0
  58. jointfm_inference/model/service/wire_schema/document.py +163 -0
  59. jointfm_inference/model/service/wire_schema/examples.py +145 -0
  60. jointfm_inference/model/service/wire_schema/fields.py +134 -0
  61. jointfm_inference/model/service/wire_schema/openapi.json +2621 -0
  62. jointfm_inference/model/service/wire_schema/request.py +422 -0
  63. jointfm_inference/model/service/wire_schema/response.py +551 -0
  64. jointfm_inference/model/service/wire_schema/vocabulary.py +188 -0
  65. jointfm_inference/py.typed +0 -0
  66. jointfm_inference-0.9.0.dist-info/METADATA +217 -0
  67. jointfm_inference-0.9.0.dist-info/RECORD +70 -0
  68. jointfm_inference-0.9.0.dist-info/WHEEL +4 -0
  69. jointfm_inference-0.9.0.dist-info/entry_points.txt +5 -0
  70. jointfm_inference-0.9.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,19 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Inference runner that serves JointFM checkpoints over HTTP."""
16
+
17
+ from importlib.metadata import version
18
+
19
+ __version__ = version("jointfm-inference")
@@ -0,0 +1,123 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """The ``jointfm-inference`` command: ``serve``, ``probe``, ``profile``, ``schema``.
16
+
17
+ ``serve`` takes no options: every setting is a ``JOINTFM_INFERENCE_*``
18
+ environment variable (``jointfm_inference.model.service.config``), so a local
19
+ process and a container read the same configuration file. ``profile`` loads
20
+ the checkpoint from the same settings. ``schema`` writes the OpenAPI document
21
+ of the HTTP contract, which needs no checkpoint.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import argparse
27
+ from collections.abc import Sequence
28
+ from pathlib import Path
29
+
30
+ from jointfm_inference.model import probe, profile
31
+ from jointfm_inference.model.service import server, wire_schema
32
+
33
+ SERVE_DESCRIPTION = (
34
+ "Serve one JointFM checkpoint over HTTP. Configured entirely through "
35
+ "JOINTFM_INFERENCE_* environment variables; JOINTFM_INFERENCE_CHECKPOINT_PATH "
36
+ "is required, and JOINTFM_INFERENCE_CHECKPOINT_VERSION defaults to the start "
37
+ "of the checkpoint's SHA-256 digest."
38
+ )
39
+ SCHEMA_DESCRIPTION = (
40
+ "Write the OpenAPI 3.1 document of the service's HTTP contract, generated "
41
+ "from the service's own code. With --check, write nothing and fail when the "
42
+ "file at --output differs from the document."
43
+ )
44
+
45
+
46
+ def _serve(arguments: argparse.Namespace) -> None:
47
+ """Run the HTTP service until the process is stopped."""
48
+ del arguments
49
+ server.main()
50
+
51
+
52
+ def _schema(arguments: argparse.Namespace) -> None:
53
+ """Write the OpenAPI document to ``--output``, or check that file with ``--check``.
54
+
55
+ Raises:
56
+ SystemExit: under ``--check``, when the file is missing or differs
57
+ from the document the code generates.
58
+ """
59
+ output = Path(arguments.output)
60
+ document = wire_schema.render_openapi()
61
+ if arguments.check:
62
+ if not output.is_file() or output.read_text(encoding="utf-8") != document:
63
+ raise SystemExit(
64
+ f"{output} is not the OpenAPI document the code generates; "
65
+ f"rewrite it with: jointfm-inference schema --output {output}"
66
+ )
67
+ print(f"{output} matches the generated OpenAPI document")
68
+ return
69
+ output.write_text(document, encoding="utf-8")
70
+ print(f"wrote {output}")
71
+
72
+
73
+ def build_parser() -> argparse.ArgumentParser:
74
+ """Return the parser of the ``jointfm-inference`` command and its subcommands."""
75
+ parser = argparse.ArgumentParser(
76
+ prog="jointfm-inference",
77
+ description=(
78
+ "Serve JointFM checkpoints, probe running services, profile "
79
+ "served-request latency, and write the service's OpenAPI document."
80
+ ),
81
+ )
82
+ commands = parser.add_subparsers(dest="command", required=True)
83
+ serve_parser = commands.add_parser(
84
+ "serve", help="Serve one checkpoint over HTTP", description=SERVE_DESCRIPTION
85
+ )
86
+ serve_parser.set_defaults(handler=_serve)
87
+ probe_parser = commands.add_parser(
88
+ "probe",
89
+ help="Check health and every return mode of running services",
90
+ description=probe.PROBE_DESCRIPTION,
91
+ )
92
+ probe.add_arguments(probe_parser)
93
+ probe_parser.set_defaults(handler=probe.run)
94
+ profile_parser = commands.add_parser(
95
+ "profile",
96
+ help="Time each stage of served requests on the configured checkpoint",
97
+ description=profile.PROFILE_DESCRIPTION,
98
+ )
99
+ profile.add_arguments(profile_parser)
100
+ profile_parser.set_defaults(handler=profile.run)
101
+ schema_parser = commands.add_parser(
102
+ "schema",
103
+ help="Write the OpenAPI document of the HTTP contract",
104
+ description=SCHEMA_DESCRIPTION,
105
+ )
106
+ schema_parser.add_argument(
107
+ "--output",
108
+ default=wire_schema.OPENAPI_FILE_NAME,
109
+ help="The file to write or check (default: %(default)s)",
110
+ )
111
+ schema_parser.add_argument(
112
+ "--check",
113
+ action="store_true",
114
+ help="Write nothing; fail when the file differs from the document",
115
+ )
116
+ schema_parser.set_defaults(handler=_schema)
117
+ return parser
118
+
119
+
120
+ def main(argv: Sequence[str] | None = None) -> None:
121
+ """Parse ``argv`` and run the selected subcommand."""
122
+ arguments = build_parser().parse_args(argv)
123
+ arguments.handler(arguments)
@@ -0,0 +1,15 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Package exports for core."""
@@ -0,0 +1,170 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Per-stage wall-clock timing of served requests.
16
+
17
+ Timing is off by default, and every timer is then a no-op that takes no clock
18
+ reading and never synchronizes a device, so the timers stay in the serving
19
+ path at no cost. :func:`set_enabled` turns it on for the process;
20
+ ``jointfm-inference profile`` does so around the requests it times.
21
+
22
+ While timing is on, each completed region appends its seconds to a
23
+ process-wide registry under its stage name, read with :func:`stage_seconds`
24
+ and emptied with :func:`clear_timings`, and logs
25
+ ``[timing] <name>: <seconds>s`` at ``DEBUG`` on the ``jointfm_inference.timing``
26
+ logger. A region left by an exception records nothing.
27
+
28
+ :class:`Timer` measures host wall time. :class:`CudaTimer` also synchronizes
29
+ its CUDA device before it starts and before it stops the clock, so a region
30
+ that launches kernels is charged with their run time instead of their launch;
31
+ unsynchronized, that run time would land in whichever later stage first waits
32
+ for the device, such as the copy of the response to the host. Each
33
+ synchronization stalls the host, so timers mark the few stage boundaries of
34
+ a request, never the inside of a per-sample loop.
35
+
36
+ The registry is shared by every thread, and a synchronization waits for all
37
+ work on its device, so a per-request split needs requests run one at a time.
38
+ """
39
+
40
+ from __future__ import annotations
41
+
42
+ import logging
43
+ import threading
44
+ import time
45
+ from types import TracebackType
46
+
47
+ import torch
48
+
49
+ # Stage names of one served request. A name that extends another names a part
50
+ # of that stage; the parts need not cover the whole stage.
51
+ REQUEST_STAGE = "service.request"
52
+ EXECUTE_STAGE = "inference.execute"
53
+ PREPARE_STAGE = "inference.prepare"
54
+ FORWARD_STAGE = "inference.forward"
55
+ ENCODER_STAGE = "inference.forward.encoder"
56
+ POOL_HEAD_STAGE = "inference.forward.pool_head"
57
+ READOUT_STAGE = "inference.readout"
58
+ SAMPLE_CHOLESKY_STAGE = "inference.readout.cholesky"
59
+ SAMPLE_GAUSSIAN_STAGE = "inference.readout.gaussian"
60
+ SAMPLE_GAMMA_STAGE = "inference.readout.gamma"
61
+ SAMPLE_ASSEMBLE_STAGE = "inference.readout.assemble"
62
+ SERIALIZE_STAGE = "service.serialize"
63
+ ENCODE_STAGE = "service.encode"
64
+
65
+ _LOGGER = logging.getLogger("jointfm_inference.timing")
66
+ _REGISTRY_LOCK = threading.Lock()
67
+ _STAGE_SECONDS: dict[str, list[float]] = {}
68
+ _ENABLED = False
69
+
70
+
71
+ def set_enabled(enabled: bool) -> None:
72
+ """Turn timing on or off for every timer in the process."""
73
+ global _ENABLED
74
+ _ENABLED = enabled
75
+
76
+
77
+ def is_enabled() -> bool:
78
+ """Return whether timers currently record."""
79
+ return _ENABLED
80
+
81
+
82
+ def clear_timings() -> None:
83
+ """Drop every recorded duration."""
84
+ with _REGISTRY_LOCK:
85
+ _STAGE_SECONDS.clear()
86
+
87
+
88
+ def stage_seconds() -> dict[str, list[float]]:
89
+ """Return a copy of the recorded durations, in seconds, by stage name."""
90
+ with _REGISTRY_LOCK:
91
+ return {name: list(values) for name, values in _STAGE_SECONDS.items()}
92
+
93
+
94
+ def _record(name: str, seconds: float) -> None:
95
+ """Append one duration under ``name`` and log it."""
96
+ with _REGISTRY_LOCK:
97
+ _STAGE_SECONDS.setdefault(name, []).append(seconds)
98
+ _LOGGER.debug("[timing] %s: %.6fs", name, seconds)
99
+
100
+
101
+ class Timer:
102
+ """Context manager that records the host wall time of its region."""
103
+
104
+ def __init__(self, name: str) -> None:
105
+ """Name the stage the region's duration is recorded under."""
106
+ self.name = name
107
+ self._start: float | None = None
108
+
109
+ def _synchronize(self) -> None:
110
+ """Wait for device work the region must be charged with; none on the host."""
111
+
112
+ def __enter__(self) -> Timer:
113
+ """Start the clock while timing is on."""
114
+ if _ENABLED:
115
+ self._synchronize()
116
+ self._start = time.perf_counter()
117
+ return self
118
+
119
+ def __exit__(
120
+ self,
121
+ exc_type: type[BaseException] | None,
122
+ exc_value: BaseException | None,
123
+ traceback: TracebackType | None,
124
+ ) -> None:
125
+ """Record the region unless it was not timed or raised."""
126
+ start, self._start = self._start, None
127
+ if start is None or exc_type is not None:
128
+ return
129
+ self._synchronize()
130
+ _record(self.name, time.perf_counter() - start)
131
+
132
+
133
+ class CudaTimer(Timer):
134
+ """Timer that synchronizes ``device`` at both ends when it is a CUDA device.
135
+
136
+ On any other device it measures host wall time like :class:`Timer`.
137
+ """
138
+
139
+ def __init__(self, name: str, device: torch.device) -> None:
140
+ """Name the stage and the device whose work the region launches."""
141
+ super().__init__(name)
142
+ self._device = device
143
+
144
+ def _synchronize(self) -> None:
145
+ """Wait for every kernel queued on the CUDA device."""
146
+ if self._device.type == "cuda":
147
+ torch.cuda.synchronize(self._device)
148
+
149
+
150
+ __all__ = [
151
+ "ENCODER_STAGE",
152
+ "ENCODE_STAGE",
153
+ "EXECUTE_STAGE",
154
+ "FORWARD_STAGE",
155
+ "POOL_HEAD_STAGE",
156
+ "PREPARE_STAGE",
157
+ "READOUT_STAGE",
158
+ "REQUEST_STAGE",
159
+ "SAMPLE_ASSEMBLE_STAGE",
160
+ "SAMPLE_CHOLESKY_STAGE",
161
+ "SAMPLE_GAMMA_STAGE",
162
+ "SAMPLE_GAUSSIAN_STAGE",
163
+ "SERIALIZE_STAGE",
164
+ "CudaTimer",
165
+ "Timer",
166
+ "clear_timings",
167
+ "is_enabled",
168
+ "set_enabled",
169
+ "stage_seconds",
170
+ ]
@@ -0,0 +1,45 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Version helpers for installed JointFM distributions."""
16
+
17
+ from __future__ import annotations
18
+
19
+ from importlib.metadata import PackageNotFoundError
20
+ from importlib.metadata import version as distribution_version
21
+
22
+
23
+ def package_version(distribution_name: str) -> str:
24
+ """Return the installed version for one Python distribution.
25
+
26
+ Args:
27
+ distribution_name: Installed distribution name as exposed through
28
+ ``importlib.metadata``.
29
+ Returns:
30
+ The installed version string.
31
+ Raises:
32
+ RuntimeError: The requested distribution metadata is unavailable.
33
+ """
34
+
35
+ try:
36
+ return distribution_version(distribution_name)
37
+ except PackageNotFoundError as error:
38
+ raise RuntimeError(
39
+ "Required package metadata is unavailable for "
40
+ f"'{distribution_name}'. Install that distribution before requesting "
41
+ "its version."
42
+ ) from error
43
+
44
+
45
+ __all__ = ["package_version"]
@@ -0,0 +1,15 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Canonical samples, request times, and DataFrame conversion."""
@@ -0,0 +1,190 @@
1
+ # Copyright 2026 DataRobot, Inc. and its affiliates.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Conversion of a request's history rows into a canonical sample."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import math
20
+ from dataclasses import dataclass
21
+ from typing import Sequence
22
+
23
+ import numpy as np
24
+ import pandas as pd
25
+ import torch
26
+
27
+ from jointfm_inference.data.time_index import (
28
+ absolute_datetime_positions,
29
+ positions_within_relative_step_tolerance,
30
+ )
31
+ from jointfm_inference.data.types import (
32
+ METADATA_COLUMN_NAMES_KEY,
33
+ METADATA_TIME_INDEX_KEY,
34
+ ROLES,
35
+ TIME_INDEX_MODES,
36
+ CanonicalSample,
37
+ RoleLiteral,
38
+ TimeIndexModeLiteral,
39
+ )
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class ColumnSpec:
44
+ """One numeric request column.
45
+
46
+ Attributes:
47
+ name: Column name in the request rows.
48
+ role: ``target`` or ``feature``; every column is forecast either way.
49
+ lower_bound: Optional lower bound every returned draw respects.
50
+ upper_bound: Optional upper bound every returned draw respects.
51
+ """
52
+
53
+ name: str
54
+ role: RoleLiteral = "feature"
55
+ lower_bound: float | None = None
56
+ upper_bound: float | None = None
57
+
58
+ def __post_init__(self) -> None:
59
+ """Refuse an unknown role and inconsistent bounds."""
60
+ if self.role not in ROLES:
61
+ raise ValueError(f"role must be one of {sorted(ROLES)}, got {self.role!r}")
62
+ for bound_name, bound in (
63
+ ("lower_bound", self.lower_bound),
64
+ ("upper_bound", self.upper_bound),
65
+ ):
66
+ if bound is not None and math.isnan(bound):
67
+ raise ValueError(f"column '{self.name}' {bound_name} must not be NaN")
68
+ if (
69
+ self.lower_bound is not None
70
+ and self.upper_bound is not None
71
+ and self.lower_bound > self.upper_bound
72
+ ):
73
+ raise ValueError(
74
+ f"column '{self.name}' lower_bound must not exceed upper_bound"
75
+ )
76
+
77
+
78
+ @dataclass(frozen=True)
79
+ class DataFrameSchema:
80
+ """How a history frame maps onto a canonical sample.
81
+
82
+ Attributes:
83
+ columns: The numeric columns, in canonical order.
84
+ time_index_mode: ``ordinal``, ``continuous_float``, or ``absolute_datetime``.
85
+ time_column: Column holding row times; optional only for ``ordinal``,
86
+ whose rows are then ``0 .. rows-1``. It must not be in ``columns``.
87
+ time_scale_seconds: Seconds per position unit for ``absolute_datetime``.
88
+ timezone: Timezone of naive ``absolute_datetime`` timestamps.
89
+ """
90
+
91
+ columns: Sequence[ColumnSpec]
92
+ time_index_mode: TimeIndexModeLiteral
93
+ time_column: str | None = None
94
+ time_scale_seconds: float | None = None
95
+ timezone: str | None = None
96
+
97
+ def __post_init__(self) -> None:
98
+ """Refuse an unknown mode, a missing time column, and duplicate names."""
99
+ if self.time_index_mode not in TIME_INDEX_MODES:
100
+ raise ValueError(
101
+ f"time_index_mode must be one of {sorted(TIME_INDEX_MODES)}, "
102
+ f"got {self.time_index_mode!r}"
103
+ )
104
+ if self.time_index_mode != "ordinal" and self.time_column is None:
105
+ raise ValueError(
106
+ f"time_column must be provided for time_index_mode '{self.time_index_mode}'"
107
+ )
108
+ names = [column.name for column in self.columns]
109
+ if not names:
110
+ raise ValueError("DataFrameSchema.columns must not be empty")
111
+ if len(set(names)) != len(names):
112
+ raise ValueError("column names must be unique")
113
+ if self.time_column is not None and self.time_column in names:
114
+ raise ValueError("time_column must not also appear in the columns")
115
+
116
+
117
+ def _time_positions(
118
+ df: pd.DataFrame, schema: DataFrameSchema
119
+ ) -> tuple[torch.Tensor, dict[str, object] | None]:
120
+ """Return the history positions and, for datetimes, their ``time_index`` block."""
121
+ if schema.time_column is None:
122
+ return torch.arange(len(df), dtype=torch.float64), None
123
+ raw_time = df[schema.time_column]
124
+ if schema.time_index_mode == "absolute_datetime":
125
+ return absolute_datetime_positions(
126
+ raw_time,
127
+ time_scale_seconds=schema.time_scale_seconds,
128
+ timezone=schema.timezone,
129
+ )
130
+ if pd.api.types.is_datetime64_any_dtype(raw_time):
131
+ raise TypeError(
132
+ f"time_column must be numeric when time_index_mode is '{schema.time_index_mode}'"
133
+ )
134
+ positions = torch.tensor(raw_time.to_numpy(dtype=np.float64), dtype=torch.float64)
135
+ if schema.time_index_mode == "ordinal":
136
+ rounded = torch.round(positions)
137
+ if not positions_within_relative_step_tolerance(
138
+ positions, rounded, step_scale=1.0
139
+ ):
140
+ raise TypeError(
141
+ "time_column must use integer-like numeric values when time_index_mode='ordinal'"
142
+ )
143
+ positions = rounded
144
+ return positions, None
145
+
146
+
147
+ def dataframe_to_canonical(
148
+ df: pd.DataFrame, schema: DataFrameSchema
149
+ ) -> CanonicalSample:
150
+ """Convert a history frame into a canonical sample of history rows only.
151
+
152
+ Raises:
153
+ ValueError: when the frame is empty, misses a column, holds a missing
154
+ or non-finite value, or its times are not strictly increasing.
155
+ TypeError: when a time column has the wrong kind of values.
156
+ """
157
+ if len(df) == 0:
158
+ raise ValueError("DataFrame must have at least one row")
159
+ names = [column.name for column in schema.columns]
160
+ expected = set(names) | (
161
+ {schema.time_column} if schema.time_column is not None else set()
162
+ )
163
+ missing = expected - set(df.columns)
164
+ if missing:
165
+ raise ValueError(f"DataFrame is missing columns: {sorted(missing)}")
166
+
167
+ values = torch.tensor(
168
+ df.loc[:, names].to_numpy(dtype=np.float64, na_value=np.nan),
169
+ dtype=torch.float32,
170
+ )
171
+ for index, name in enumerate(names):
172
+ if not bool(torch.isfinite(values[:, index]).all()):
173
+ raise ValueError(
174
+ f"history column '{name}' (column index {index}) holds a missing or "
175
+ "non-finite value; JointFM 1 reads complete numeric histories"
176
+ )
177
+ positions, time_index_metadata = _time_positions(df, schema)
178
+ metadata: dict[str, object] = {METADATA_COLUMN_NAMES_KEY: names}
179
+ if time_index_metadata is not None:
180
+ metadata[METADATA_TIME_INDEX_KEY] = time_index_metadata
181
+ return CanonicalSample(
182
+ values=values,
183
+ time_positions=positions,
184
+ time_index_mode=schema.time_index_mode,
185
+ query_row_mask=torch.zeros(values.shape[0], dtype=torch.bool),
186
+ metadata=metadata,
187
+ )
188
+
189
+
190
+ __all__ = ["ColumnSpec", "DataFrameSchema", "dataframe_to_canonical"]