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.
- jointfm_inference/__init__.py +19 -0
- jointfm_inference/cli.py +123 -0
- jointfm_inference/core/__init__.py +15 -0
- jointfm_inference/core/timing.py +170 -0
- jointfm_inference/core/version.py +45 -0
- jointfm_inference/data/__init__.py +15 -0
- jointfm_inference/data/adapters.py +190 -0
- jointfm_inference/data/time_index.py +256 -0
- jointfm_inference/data/types.py +110 -0
- jointfm_inference/model/__init__.py +15 -0
- jointfm_inference/model/checkpoint.py +250 -0
- jointfm_inference/model/inference/__init__.py +92 -0
- jointfm_inference/model/inference/_bounds.py +83 -0
- jointfm_inference/model/inference/adapter.py +225 -0
- jointfm_inference/model/inference/backend_registry.py +95 -0
- jointfm_inference/model/inference/capacity_envelope.py +126 -0
- jointfm_inference/model/inference/checkpoint.py +55 -0
- jointfm_inference/model/inference/conditional_query.py +740 -0
- jointfm_inference/model/inference/conditioning.py +572 -0
- jointfm_inference/model/inference/contract.py +436 -0
- jointfm_inference/model/inference/interval_conditioning.py +391 -0
- jointfm_inference/model/inference/jointfm_1_backend.py +250 -0
- jointfm_inference/model/inference/jointfm_1_grid.py +166 -0
- jointfm_inference/model/inference/session.py +159 -0
- jointfm_inference/model/inference/time_index.py +102 -0
- jointfm_inference/model/jointfm_1/__init__.py +15 -0
- jointfm_inference/model/jointfm_1/config.py +258 -0
- jointfm_inference/model/jointfm_1/encoder.py +267 -0
- jointfm_inference/model/jointfm_1/head.py +434 -0
- jointfm_inference/model/jointfm_1/input_scale.py +119 -0
- jointfm_inference/model/jointfm_1/loader.py +69 -0
- jointfm_inference/model/jointfm_1/marginals.py +548 -0
- jointfm_inference/model/jointfm_1/model.py +275 -0
- jointfm_inference/model/jointfm_1/pooling.py +83 -0
- jointfm_inference/model/jointfm_1/readouts.py +255 -0
- jointfm_inference/model/jointfm_1/sign_symmetry.py +109 -0
- jointfm_inference/model/jointfm_1/tail_map.py +444 -0
- jointfm_inference/model/linalg.py +230 -0
- jointfm_inference/model/precision.py +117 -0
- jointfm_inference/model/probe.py +545 -0
- jointfm_inference/model/profile.py +530 -0
- jointfm_inference/model/service/__init__.py +56 -0
- jointfm_inference/model/service/checkpoint_source.py +141 -0
- jointfm_inference/model/service/column_specs.py +160 -0
- jointfm_inference/model/service/conditions.py +247 -0
- jointfm_inference/model/service/config.py +307 -0
- jointfm_inference/model/service/constants.py +64 -0
- jointfm_inference/model/service/data_frames.py +224 -0
- jointfm_inference/model/service/errors.py +88 -0
- jointfm_inference/model/service/http_handler.py +226 -0
- jointfm_inference/model/service/http_service.py +818 -0
- jointfm_inference/model/service/scoring.py +119 -0
- jointfm_inference/model/service/serialization.py +111 -0
- jointfm_inference/model/service/server.py +92 -0
- jointfm_inference/model/service/time_conversion.py +35 -0
- jointfm_inference/model/service/validation.py +207 -0
- jointfm_inference/model/service/wire_schema/__init__.py +97 -0
- jointfm_inference/model/service/wire_schema/document.py +163 -0
- jointfm_inference/model/service/wire_schema/examples.py +145 -0
- jointfm_inference/model/service/wire_schema/fields.py +134 -0
- jointfm_inference/model/service/wire_schema/openapi.json +2621 -0
- jointfm_inference/model/service/wire_schema/request.py +422 -0
- jointfm_inference/model/service/wire_schema/response.py +551 -0
- jointfm_inference/model/service/wire_schema/vocabulary.py +188 -0
- jointfm_inference/py.typed +0 -0
- jointfm_inference-0.9.0.dist-info/METADATA +217 -0
- jointfm_inference-0.9.0.dist-info/RECORD +70 -0
- jointfm_inference-0.9.0.dist-info/WHEEL +4 -0
- jointfm_inference-0.9.0.dist-info/entry_points.txt +5 -0
- 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")
|
jointfm_inference/cli.py
ADDED
|
@@ -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"]
|