feat(function): expose resolved environments and fresh lock requests (#5034)

Function registration clients cannot request fresh dependency resolution
or inspect the measured environment returned by the server. Add
`refresh_lock=True` to Python registration and preserve the requested
runtime and measured environments in Rust/Python Function version
readback. Registration forwards both `exist_ok` and `refresh_lock`;
defaults remain unchanged.

Single-platform versions retain `resolved_environment`.
Multiarchitecture versions expose `resolved_environments`, keyed by OCI
`os/architecture`, and the Python `environment_report` alias. Platforms
are never flattened: absent entries mean unknown measurements, while
measured empty package lists remain present. Registration waits emit
scalar and per-platform server warnings once per Job; catalog reads do
not repeat them.

Requires matching server support, including Sophon #10344 for
per-platform publication. Nine focused Python source-overlay tests and
29 documentation tests passed for the additive map change; one
documentation test requiring a newer native `exist_ok` binding was
excluded. These checks reuse a prebuilt extension and do not establish
current native integration. PR CI exercises the Rust transport/readback
and Python bindings. Live multiarchitecture registration and GPU
acceptance remain separate.
This commit is contained in:
Xuanwo
2026-11-14 22:30:28 +08:00
committed by GitHub
parent ea59f8acb6
commit 2499342fa1
9 changed files with 1087 additions and 8 deletions
+8
View File
@@ -564,6 +564,14 @@ with BlobReader(read_range, len(payload)) as reader:
::: lancedb.functions.FunctionVersion
::: lancedb.functions.FunctionEnvironment
::: lancedb.functions.ResolvedEnvironment
::: lancedb.functions.ResolvedPackage
::: lancedb.functions.ResolvedEnvironmentProvenance
::: lancedb.functions.HuggingFaceModel
::: lancedb.functions.PythonRuntimeSpec
+118
View File
@@ -178,6 +178,13 @@ with `db.get_function(name, version=...)`. The version may be an integer or
its string form. Omit `version` to resolve and return the latest currently
visible revision.
Re-registering unchanged code reuses the published version and its resolved
environment lock. Pass `refresh_lock=True` to `create_function` or
`create_function_async` to request a fresh lock for this registration. It is a
registration action, not part of the Function's source or runtime identity.
A deployment must support the field; an older server rejects the unknown
field rather than silently reusing the old lock.
{/* Draft for the function exist_ok release.
Use `exist_ok=True` on `create_function` or `create_function_async` to return
@@ -246,6 +253,117 @@ are not included; list each namespace separately. A version's
`created_at_millis`, `metadata`, `disabled` flag, and `secret_bindings` are
all readable this way without applying or calling the function.
### Inspect the resolved environment {#resolved-environment}
The version keeps the requested runtime separate from what the server actually
installed. The typed catalog API is available in Python and Rust; TypeScript
does not yet expose this readback API. `version.runtime` is the specification
sent at registration. `version.resolved_environment` is measured data from the
built image:
<CodeGroup>
```python
version = db.get_function("double")
print(version.runtime) # requested runtime, or None for legacy
print(version.environment.resolved) # measured environment, or None for legacy
print(version.environment_report) # platform -> measured environment map
if version.environment.resolved is not None:
for package in version.environment.resolved.packages:
print(package.name, package.version) # versions keep labels such as +cu130
```
{/* Draft for the typed Rust environment inspection release.
```rust
# async fn inspect_environment(connection: &lancedb::Connection) -> Result<(), Box<dyn std::error::Error>> {
let version = connection.get_function_latest("double", &[]).await?;
println!("Requested runtime: {:?}", version.runtime());
if let Some(environment) = version.resolved_environment() {
for package in &environment.packages {
println!("{} {}", package.name, package.version);
}
}
for (platform, environment) in version.resolved_environments() {
println!("{platform}: {} measured packages", environment.packages.len());
for package in &environment.packages {
println!("{} {}", package.name, package.version);
}
}
# Ok(())
# }
```
*/}
</CodeGroup>
`version.environment.requested` and `version.environment.resolved` are
convenience members over the same canonical fields; they do not add another
wire shape. The canonical JSON exposes top-level `runtime` and
`resolved_environment`. A missing `resolved_environment` means the version or
environment cache predates measurement; it is unknown, not an empty installed
package list. A package's `source` is present only when the submitted lock
retained it, and provenance fields are reported without client-side guessing.
For a multiarchitecture image, the scalar field is absent and
`version.resolved_environments` (also available as
`version.environment_report`) maps OCI `os/architecture` keys to the measured
environment for that platform. A missing platform key means its measurement is
unknown; an empty `packages` list inside a key is a measured empty environment
and is retained. The SDK never merges platforms or fabricates an aggregate
package list.
The corresponding canonical payload has this shape:
```json
{
"runtime": {
"kind": "python",
"python_version": "3.12",
"environment": {"kind": "pip", "packages": ["vllm==0.11.0"]}
},
"resolved_environment": {
"packages": [
{
"name": "torch",
"version": "2.9.0+cu130",
"source": "https://packages.example/simple"
}
],
"provenance": {
"configured_index_urls": ["https://packages.example/simple"],
"resolved_indexes": ["https://packages.example/simple"],
"cuda_toolkit": "12.8",
"torch_version": "torch==2.9.0+cu130"
},
"warnings": [
"torch resolved to torch==2.9.0+cu130 but is not pinned exactly; add torch==2.9.0+cu130 to pin it."
]
}
}
```
The multiarchitecture form has the same package shape per platform:
```json
{
"resolved_environments": {
"linux/amd64": {
"packages": [{"name": "torch", "version": "2.9.0+cu130"}]
},
"linux/arm64": {
"packages": []
}
}
}
```
Environment warnings are part of the registration result. Waiting on
`create_function_async(...)` (or calling `create_function`) emits each server
warning from the scalar or per-platform measurements as a Python `UserWarning`;
`get_function` and `list_functions` read the same version but do not
replay those registration warnings.
## Try it in SQL {#try-sql}
A registered function is callable in SQL by its name, the same as any other
+4
View File
@@ -51,11 +51,15 @@ from .functions import (
FunctionApplication as FunctionApplication,
FunctionBinding as FunctionBinding,
FunctionDefinition as FunctionDefinition,
FunctionEnvironment as FunctionEnvironment,
FunctionRegistrationRequest as FunctionRegistrationRequest,
FunctionRetryPolicy as FunctionRetryPolicy,
FunctionVersion as FunctionVersion,
HuggingFaceModel as HuggingFaceModel,
PythonRuntimeSpec as PythonRuntimeSpec,
ResolvedEnvironment as ResolvedEnvironment,
ResolvedEnvironmentProvenance as ResolvedEnvironmentProvenance,
ResolvedPackage as ResolvedPackage,
RefreshColumnResult as RefreshColumnResult,
function as function,
udf as udf,
+54 -2
View File
@@ -154,6 +154,38 @@ def _normalize_function_version(version: Optional[Union[int, str]]) -> Optional[
raise TypeError("version must be an int, str, or None")
def _function_registration_decoder():
"""Parse a registration result and emit its server warnings once.
The warnings come from the scalar environment or, for a multiarchitecture
image, each measured platform entry. They are part of the registration job
result, not a new client-side package policy. Catalog get/list readbacks
use ``FunctionVersion.from_json`` directly and therefore do not replay
them.
"""
warned = False
def decode(payload: str) -> FunctionVersion:
nonlocal warned
version = FunctionVersion.from_json(payload)
if not warned:
environments = [
environment
for environment in (
version.resolved_environment,
*version.resolved_environments.values(),
)
if environment is not None
]
for environment in environments:
for message in environment.warnings:
warnings.warn(message, UserWarning, stacklevel=3)
warned = True
return version
return decode
class DBConnection(EnforceOverrides):
"""An active LanceDB connection interface.
@@ -1018,6 +1050,7 @@ class DBConnection(EnforceOverrides):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
refresh_lock: bool = False,
) -> FunctionVersion:
"""Build and register a scalar Python function, then return its version.
@@ -1040,6 +1073,13 @@ class DBConnection(EnforceOverrides):
namespace_path : list of str, optional
The namespace holding the Function. None or an empty list is the
root namespace.
refresh_lock : bool, default False
Ask the server to resolve a fresh environment lock instead of
reusing the published version's lock.
When the registration job resolves, each resolved-environment warning
reported by the server is emitted as a Python ``UserWarning``. Catalog
reads do not replay those registration warnings.
Examples
--------
@@ -1060,6 +1100,7 @@ class DBConnection(EnforceOverrides):
secrets=secrets,
exist_ok=exist_ok,
namespace_path=namespace_path,
refresh_lock=refresh_lock,
).wait()
def create_function_async(
@@ -1069,6 +1110,7 @@ class DBConnection(EnforceOverrides):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
refresh_lock: bool = False,
) -> Job[FunctionVersion]:
"""Submit a scalar Python function for building and registration.
@@ -1079,6 +1121,11 @@ class DBConnection(EnforceOverrides):
artifact. The returned job has type ``query`` and the SQL query UUID as
its ID. Waiting on it returns the immutable Function version.
LanceDB Embedded connections raise ``NotImplementedError``.
``refresh_lock`` asks the server to resolve a fresh environment lock
instead of reusing the published version's lock. Waiting on the job
emits the server's resolved-environment warnings as Python warnings;
reading the same version later does not repeat them.
"""
raise NotImplementedError(
_append_doc_url(
@@ -2432,6 +2479,7 @@ class LanceDBConnection(DBConnection):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
refresh_lock: bool = False,
) -> Job[FunctionVersion]:
job = LOOP.run(
self._conn.create_function_async(
@@ -2439,6 +2487,7 @@ class LanceDBConnection(DBConnection):
secrets=secrets,
exist_ok=exist_ok,
namespace_path=namespace_path,
refresh_lock=refresh_lock,
)
)
return Job(job)
@@ -3788,6 +3837,7 @@ class AsyncConnection(object):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
refresh_lock: bool = False,
) -> AsyncJob[FunctionVersion]:
"""Submit a scalar Python function for building and registration.
@@ -3802,14 +3852,16 @@ class AsyncConnection(object):
the environment variable its value arrives in. ``namespace_path`` is
the namespace the Function is registered in; None or an empty list is
the root. LanceDB Embedded connections raise ``NotImplementedError``.
``refresh_lock`` asks the server to resolve a fresh environment lock
instead of reusing the published version's lock.
"""
if not isinstance(definition, FunctionDefinition):
raise TypeError("create_function_async requires a @function definition")
request = definition.bind_secrets(secrets)
request = definition.bind_secrets(secrets).with_refresh_lock(refresh_lock)
inner = await self._inner.create_function_async(
request.to_canonical_json(), namespace_path, exist_ok=exist_ok
)
return _typed_job(inner, FunctionVersion.from_json)
return _typed_job(inner, _function_registration_decoder())
async def get_function(
self,
+122
View File
@@ -36,6 +36,7 @@ from typing import (
Any,
Callable,
Literal,
NamedTuple,
Optional,
TYPE_CHECKING,
Union,
@@ -101,6 +102,12 @@ def _validate_batch_size(value: Any) -> Optional[int]:
return value
def _validate_refresh_lock(value: Any) -> bool:
if not isinstance(value, bool):
raise ValueError("refresh_lock must be a boolean")
return value
def _validate_max_concurrency(value: Any) -> Optional[int]:
if value is None:
return None
@@ -544,6 +551,67 @@ class FunctionImage(_RemoteValue):
models: tuple[HuggingFaceModel, ...] = ()
class ResolvedPackage(_RemoteValue):
"""One installed Python distribution measured from a baked environment.
``version`` is the complete version reported by package metadata,
including local labels such as ``+cu130``. ``source`` is present only when
the submitted lock retained a per-package source; absent means unknown, not
an inferred index.
"""
name: str
version: str
source: Optional[str] = None
class ResolvedEnvironmentProvenance(_RemoteValue):
"""Sanitized source and accelerator provenance for a resolved environment.
``configured_index_urls`` and ``configured_find_links`` record build
inputs. ``resolved_indexes`` records indexes visible in the submitted lock,
so a configured source is not by itself evidence that a package came from
it. Empty lists and absent fields remain absent; the client does not
synthesize them.
"""
configured_index_urls: tuple[str, ...] = ()
configured_find_links: tuple[str, ...] = ()
resolved_indexes: tuple[str, ...] = ()
cuda_toolkit: Optional[str] = None
torch_version: Optional[str] = None
class ResolvedEnvironment(_RemoteValue):
"""Actual installed distributions and registration warnings for one platform.
A missing value means its measurement is unknown, not an empty
installed-package list. Versions are retained verbatim, including local
labels; package ``source`` is retained only when the producer recorded it.
"""
packages: tuple[ResolvedPackage, ...]
provenance: Optional[ResolvedEnvironmentProvenance] = None
warnings: tuple[str, ...] = ()
class FunctionEnvironment(NamedTuple):
"""Requested and measured environment view for a Function version.
This is a view over
[FunctionVersion.runtime][lancedb.functions.FunctionVersion.runtime]
and
[FunctionVersion.resolved_environment][lancedb.functions.FunctionVersion.resolved_environment].
It adds no wire field and performs no second parse. ``requested`` is the
runtime specification supplied at registration; ``resolved`` is measured
data and is ``None`` when unknown. For per-platform multiarchitecture
measurements, use ``FunctionVersion.environment_report``.
"""
requested: Optional[PythonRuntimeSpec]
resolved: Optional[ResolvedEnvironment]
def _validate_object_version(value: str) -> str:
if int(value) > 2**64 - 1:
raise ValueError("Function version exceeds uint64")
@@ -593,6 +661,17 @@ class FunctionVersion(_RemoteValue):
``result_stability`` retain the execution controls reported by the
catalog. They are ``None`` for versions registered before the
corresponding declaration.
``runtime`` is the runtime specification requested at registration. It is
not evidence of what was installed. ``resolved_environment`` is measured
data for a single-platform image: actual package names and complete
versions, optional per-package source, provenance, and registration
warnings. ``resolved_environments`` is the corresponding map for a
multiarchitecture image, keyed by OCI ``os/architecture``. It is never
flattened into an aggregate package list. ``None`` or an empty map means
unknown data, not an empty installed environment. ``environment`` is a
convenience view with ``requested`` and ``resolved`` members over the same
fields.
"""
name: str
@@ -613,6 +692,11 @@ class FunctionVersion(_RemoteValue):
max_concurrency: Optional[int] = None
row_timeout_seconds: Optional[float] = None
result_stability: Optional[str] = None
runtime: Optional[PythonRuntimeSpec] = None
resolved_environment: Optional[ResolvedEnvironment] = None
resolved_environments: Mapping[str, ResolvedEnvironment] = Field(
default_factory=dict
)
@field_validator("batch_size", mode="before")
@classmethod
@@ -629,6 +713,24 @@ class FunctionVersion(_RemoteValue):
def _validate_row_timeout(cls, value):
return _validate_row_timeout(value)
@property
def environment(self) -> FunctionEnvironment:
"""Requested and measured environment without adding a second parser."""
return FunctionEnvironment(
requested=self.runtime,
resolved=self.resolved_environment,
)
@property
def environment_report(self) -> Mapping[str, ResolvedEnvironment]:
"""Per-platform measured reports, keyed by OCI ``os/architecture``.
This is the same map as ``resolved_environments`` and is never
flattened. Single-platform images use ``resolved_environment`` instead;
an absent platform means its measurement is unknown.
"""
return self.resolved_environments
def __call__(self, **arguments: Any) -> FunctionApplication:
"""Bind this exact version to named table columns and constant inputs.
@@ -769,6 +871,9 @@ class FunctionRegistrationRequest(_RemoteValue):
Credential values deliberately have no field here. The only secret-shaped
thing a client sends is ``secret_bindings``: the name of a Secret the
database already holds, which the remote service resolves at execution.
``refresh_lock`` is a per-registration action, not part of the Function's
source or runtime identity; its false default is omitted from canonical
JSON.
"""
name: str
@@ -781,6 +886,7 @@ class FunctionRegistrationRequest(_RemoteValue):
retry_policy: Optional[FunctionRetryPolicy] = None
secret_bindings: tuple[SecretBinding, ...] = ()
models: tuple[HuggingFaceModel, ...] = ()
refresh_lock: bool = False
@field_validator("batch_size", mode="before")
@classmethod
@@ -797,6 +903,18 @@ class FunctionRegistrationRequest(_RemoteValue):
def _validate_row_timeout(cls, value):
return _validate_row_timeout(value)
@field_validator("refresh_lock", mode="before")
@classmethod
def _validate_refresh_lock(cls, value):
return _validate_refresh_lock(value)
def with_refresh_lock(self, refresh_lock: bool) -> FunctionRegistrationRequest:
"""Return this request with the registration-time refresh action set."""
refresh_lock = _validate_refresh_lock(refresh_lock)
if self.refresh_lock == refresh_lock:
return self
return self._copy(update={"refresh_lock": refresh_lock})
class FunctionVersionRef(_OpenRemoteValue):
name: str
@@ -3043,6 +3161,7 @@ __all__ = [
"FunctionArtifactContent",
"FunctionArtifactRequest",
"FunctionBinding",
"FunctionEnvironment",
"FunctionOutput",
"FunctionParameter",
"FunctionRegistrationRequest",
@@ -3059,6 +3178,9 @@ __all__ = [
"PythonEnvironmentSpec",
"PythonAdapterSpec",
"PythonRuntimeSpec",
"ResolvedEnvironment",
"ResolvedEnvironmentProvenance",
"ResolvedPackage",
"RefreshColumnResult",
"FunctionDefinition",
]
+2
View File
@@ -1002,6 +1002,7 @@ class RemoteDBConnection(DBConnection):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
refresh_lock: bool = False,
) -> Job[FunctionVersion]:
job = LOOP.run(
self._conn.create_function_async(
@@ -1009,6 +1010,7 @@ class RemoteDBConnection(DBConnection):
secrets=secrets,
exist_ok=exist_ok,
namespace_path=namespace_path,
refresh_lock=refresh_lock,
)
)
return Job(job)
@@ -26,8 +26,9 @@ import pytest
import lancedb
from lancedb import BlobReader
from lancedb.db import AsyncConnection
from lancedb.db import AsyncConnection, DBConnection, LanceDBConnection
from lancedb.functions import (
FunctionRegistrationRequest,
FunctionSignature,
FunctionVersion,
HuggingFaceModel,
@@ -82,6 +83,63 @@ def analyze_caption(caption: str) -> str:
return caption.strip()
def _function_version_with_resolved_environment():
version = json.loads(
(FIXTURES / "remote_function_version.canonical.json").read_text()
)
version["runtime"] = json.loads(
normalize_score.registration_request.runtime.to_canonical_json()
)
version["resolved_environment"] = {
"packages": [
{
"name": "torch",
"version": "2.9.0+cu130",
"source": "https://packages.example/simple",
},
{"name": "transformers", "version": "4.57.1"},
],
"provenance": {
"configured_index_urls": ["https://packages.example/simple"],
"configured_find_links": ["https://downloads.example/wheels"],
"resolved_indexes": ["https://packages.example/simple"],
"cuda_toolkit": "12.8",
"torch_version": "torch==2.9.0+cu130",
},
"warnings": [
"transformers resolved to transformers==4.57.1 but is not pinned "
"exactly; add transformers==4.57.1 to pin it."
],
}
return version
def _function_version_with_resolved_environments():
version = json.loads(
(FIXTURES / "remote_function_version.canonical.json").read_text()
)
version["runtime"] = json.loads(
normalize_score.registration_request.runtime.to_canonical_json()
)
version["resolved_environments"] = {
"linux/amd64": {
"packages": [
{
"name": "torch",
"version": "2.9.0+cu130",
"source": "https://packages.example/simple",
}
],
"warnings": ["amd64 environment warning"],
},
"linux/arm64": {
"packages": [],
"warnings": ["arm64 environment warning"],
},
}
return version
def test_scalar_function_matches_shared_registration_golden_and_remains_callable():
assert isinstance(normalize_score, FunctionDefinition)
assert normalize_score(25.0) == 0.25
@@ -98,6 +156,118 @@ def test_scalar_function_matches_shared_registration_golden_and_remains_callable
}
def test_refresh_lock_is_a_registration_option_not_part_of_identity():
default = normalize_score.registration_request
old_json = default.to_canonical_json()
assert "refresh_lock" not in json.loads(old_json)
refreshed = default.with_refresh_lock(True)
payload = json.loads(refreshed.to_canonical_json())
assert payload["refresh_lock"] is True
assert (
FunctionRegistrationRequest.from_json(
refreshed.to_canonical_json()
).refresh_lock
is True
)
assert refreshed.artifact.digest == default.artifact.digest
assert refreshed.runtime.digest == default.runtime.digest
assert default.with_refresh_lock(False).to_canonical_json() == old_json
with pytest.raises(ValueError, match="refresh_lock must be a boolean"):
default.with_refresh_lock(1)
@pytest.mark.asyncio
@pytest.mark.parametrize("exist_ok", [False, True])
async def test_async_create_function_forwards_refresh_lock(exist_ok):
calls = []
class Inner:
async def create_function_async(
self, request_json, namespace_path=None, *, exist_ok=False
):
calls.append((json.loads(request_json), namespace_path, exist_ok))
return object()
connection = object.__new__(AsyncConnection)
connection._inner = Inner()
await connection.create_function_async(normalize_score)
await connection.create_function_async(
normalize_score, refresh_lock=True, exist_ok=exist_ok, namespace_path=["team"]
)
with pytest.raises(ValueError, match="refresh_lock must be a boolean"):
await connection.create_function_async(normalize_score, refresh_lock=1)
assert len(calls) == 2
assert "refresh_lock" not in calls[0][0]
assert calls[0][1:] == (None, False)
assert calls[1][0]["refresh_lock"] is True
assert calls[1][1:] == (["team"], exist_ok)
@pytest.mark.parametrize("exist_ok", [False, True])
def test_sync_create_function_paths_forward_refresh_lock(exist_ok):
calls = []
class AsyncInner:
async def create_function_async(
self,
definition,
*,
secrets=None,
exist_ok=False,
namespace_path=None,
refresh_lock=False,
):
calls.append(("wrapped", refresh_lock, namespace_path, exist_ok))
return object()
for connection_type in (LanceDBConnection, RemoteDBConnection):
connection = object.__new__(connection_type)
connection._conn = AsyncInner()
connection.create_function_async(
normalize_score,
refresh_lock=True,
exist_ok=exist_ok,
namespace_path=["team"],
)
class BlockingConnection:
def create_function_async(
self,
definition,
*,
secrets=None,
exist_ok=False,
namespace_path=None,
refresh_lock=False,
):
calls.append(("blocking", refresh_lock, namespace_path, exist_ok))
class ImmediateJob:
def wait(self):
return "version"
return ImmediateJob()
blocking = BlockingConnection()
assert (
DBConnection.create_function(
blocking,
normalize_score,
refresh_lock=True,
exist_ok=exist_ok,
namespace_path=["team"],
)
== "version"
)
assert calls == [
("wrapped", True, ["team"], exist_ok),
("wrapped", True, ["team"], exist_ok),
("blocking", True, ["team"], exist_ok),
]
def test_function_declares_pinned_hugging_face_models():
model = HuggingFaceModel(
repo="sentence-transformers/all-MiniLM-L6-v2",
@@ -2205,6 +2375,205 @@ class _RawFunctionCatalog:
return None
def test_function_version_reads_requested_and_resolved_environments():
legacy = json.loads(
(FIXTURES / "remote_function_version.canonical.json").read_text()
)
legacy_version = FunctionVersion.from_json(json.dumps(legacy))
assert legacy_version.runtime is None
assert legacy_version.resolved_environment is None
assert legacy_version.environment.requested is None
assert legacy_version.environment.resolved is None
payload = _function_version_with_resolved_environment()
version = FunctionVersion.from_json(json.dumps(payload))
assert version.environment.requested is version.runtime
assert version.environment.resolved is version.resolved_environment
assert version.runtime.kind == "python"
resolved = version.resolved_environment
assert resolved.packages[0].version == "2.9.0+cu130"
assert resolved.packages[0].source == "https://packages.example/simple"
assert resolved.packages[1].source is None
assert resolved.provenance.torch_version == "torch==2.9.0+cu130"
assert resolved.warnings == tuple(payload["resolved_environment"]["warnings"])
encoded = json.loads(version.to_canonical_json())
assert encoded["runtime"]["kind"] == "python"
assert encoded["resolved_environment"]["packages"][0]["version"] == "2.9.0+cu130"
assert "source" not in encoded["resolved_environment"]["packages"][1]
assert (
encoded["resolved_environment"]["provenance"]["torch_version"]
== "torch==2.9.0+cu130"
)
assert FunctionVersion.from_json(version.to_canonical_json()) == version
invalid = json.loads(json.dumps(payload))
del invalid["resolved_environment"]["packages"]
with pytest.raises(ValueError):
FunctionVersion.from_json(json.dumps(invalid))
def test_function_version_reads_resolved_environments_by_platform():
legacy = json.loads(
(FIXTURES / "remote_function_version.canonical.json").read_text()
)
legacy_version = FunctionVersion.from_json(json.dumps(legacy))
assert legacy_version.resolved_environment is None
assert legacy_version.resolved_environments == {}
assert legacy_version.environment_report == {}
payload = _function_version_with_resolved_environments()
version = FunctionVersion.from_json(json.dumps(payload))
assert version.resolved_environment is None
assert version.resolved_environments == version.environment_report
assert set(version.environment_report) == {"linux/amd64", "linux/arm64"}
assert (
version.environment_report["linux/amd64"].packages[0].version == "2.9.0+cu130"
)
assert version.environment_report["linux/arm64"].packages == ()
assert version.environment_report["linux/arm64"].warnings == (
"arm64 environment warning",
)
encoded = json.loads(version.to_canonical_json())
assert "resolved_environment" not in encoded
assert (
encoded["resolved_environments"]["linux/amd64"]["packages"][0]["version"]
== "2.9.0+cu130"
)
assert encoded["resolved_environments"]["linux/arm64"]["packages"] == []
assert FunctionVersion.from_json(version.to_canonical_json()) == version
missing_platform = json.loads(json.dumps(payload))
del missing_platform["resolved_environments"]["linux/arm64"]
missing_version = FunctionVersion.from_json(json.dumps(missing_platform))
assert "linux/arm64" not in missing_version.environment_report
assert "linux/amd64" in missing_version.environment_report
empty_map = json.loads(json.dumps(payload))
empty_map["resolved_environments"] = {}
empty_version = FunctionVersion.from_json(json.dumps(empty_map))
assert empty_version.resolved_environments == {}
assert "resolved_environments" not in json.loads(empty_version.to_canonical_json())
invalid = json.loads(json.dumps(payload))
del invalid["resolved_environments"]["linux/amd64"]["packages"]
with pytest.raises(ValueError):
FunctionVersion.from_json(json.dumps(invalid))
@pytest.mark.asyncio
async def test_registration_job_emits_server_environment_warnings_once():
payload = _function_version_with_resolved_environment()
class InnerJob:
async def wait(self):
return json.dumps(payload)
class Inner:
async def create_function_async(
self, request_json, namespace_path=None, *, exist_ok=False
):
assert "refresh_lock" not in json.loads(request_json)
return InnerJob()
connection = object.__new__(AsyncConnection)
connection._inner = Inner()
job = await connection.create_function_async(normalize_score)
with pytest.warns(UserWarning) as recorded:
version = await job.wait()
assert [str(w.message) for w in recorded] == list(
payload["resolved_environment"]["warnings"]
)
assert version.environment.resolved.warnings == tuple(
payload["resolved_environment"]["warnings"]
)
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
assert await job.wait() is not None
assert caught == []
@pytest.mark.asyncio
async def test_registration_job_emits_per_platform_environment_warnings():
payload = _function_version_with_resolved_environments()
class InnerJob:
async def wait(self):
return json.dumps(payload)
class Inner:
async def create_function_async(
self, request_json, namespace_path=None, *, exist_ok=False
):
return InnerJob()
connection = object.__new__(AsyncConnection)
connection._inner = Inner()
job = await connection.create_function_async(normalize_score)
with pytest.warns(UserWarning) as recorded:
version = await job.wait()
assert [str(w.message) for w in recorded] == [
"amd64 environment warning",
"arm64 environment warning",
]
assert version.environment_report["linux/arm64"].warnings == (
"arm64 environment warning",
)
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
assert await job.wait() is not None
assert caught == []
def test_blocking_create_function_emits_server_environment_warnings():
payload = _function_version_with_resolved_environment()
class InnerJob:
async def wait(self):
return json.dumps(payload)
class Inner:
async def create_function_async(
self, request_json, namespace_path=None, *, exist_ok=False
):
return InnerJob()
connection = object.__new__(RemoteDBConnection)
connection._conn = AsyncConnection(Inner())
with pytest.warns(UserWarning) as recorded:
version = DBConnection.create_function(connection, normalize_score)
assert [str(w.message) for w in recorded] == list(
payload["resolved_environment"]["warnings"]
)
assert version.environment.resolved.packages[0].version == "2.9.0+cu130"
@pytest.mark.asyncio
async def test_catalog_readback_does_not_replay_registration_warnings():
payload = _function_version_with_resolved_environment()
connection = AsyncConnection(_RawFunctionCatalog(payload, encode=True))
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
version = await connection.get_function("embed")
listed = [item async for item in connection.list_functions()]
assert caught == []
assert version.environment.resolved.packages[0].version == "2.9.0+cu130"
assert listed[0].environment.resolved == version.resolved_environment
@pytest.mark.asyncio
async def test_catalog_readback_does_not_replay_per_platform_warnings():
payload = _function_version_with_resolved_environments()
connection = AsyncConnection(_RawFunctionCatalog(payload, encode=True))
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
version = await connection.get_function("embed")
listed = [item async for item in connection.list_functions()]
assert caught == []
assert version.environment_report == listed[0].environment_report
def _assert_execution_control_encoding(version):
encoded = json.loads(version.to_canonical_json())
assert type(encoded["batch_size"]) is int
+274 -5
View File
@@ -521,6 +521,59 @@ pub struct HuggingFaceModel {
pub revision: String,
}
/// One installed Python distribution as measured from a Function's baked
/// environment.
///
/// `version` is the complete version string reported by the package metadata,
/// including local labels such as `+cu130`. `source` is present only when the
/// submitted lock retained a per-package source; a missing value is unknown and
/// must not be inferred from other package indexes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResolvedPackage {
pub name: String,
pub version: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
}
/// Sanitized source and accelerator provenance retained with a resolved
/// environment.
///
/// `configured_*` records what the build was asked to use. `resolved_indexes`
/// records indexes visible in the submitted lock, so a configured source is
/// not mistaken for evidence that a package came from it. Empty lists and
/// absent fields remain absent rather than being synthesized by the client.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResolvedEnvironmentProvenance {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub configured_index_urls: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub configured_find_links: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub resolved_indexes: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cuda_toolkit: Option<String>,
/// The fully resolved `torch==<version>` when torch was installed.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub torch_version: Option<String>,
}
/// Actual installed distributions and registration warnings for one native
/// Function environment.
///
/// A missing environment means its measurement is unknown, not an empty
/// installed-package list. The field keeps the complete versions and only the
/// provenance the producer recorded; SDK readers do not recompute package
/// policy.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResolvedEnvironment {
pub packages: Vec<ResolvedPackage>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub provenance: Option<ResolvedEnvironmentProvenance>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub warnings: Vec<String>,
}
/// A complete OCI Function image. Its digest is independent of catalog names.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FunctionImage {
@@ -578,7 +631,9 @@ impl<'de> Deserialize<'de> for RowTimeoutSeconds {
/// decoding, but they are not part of this value and are omitted from
/// canonical JSON. Known fields retain their complete values, while unknown
/// fields inside the open [`FunctionImage::descriptor`] JSON object remain
/// available.
/// available. Single-platform measurements use `resolved_environment`;
/// multiarchitecture measurements use `resolved_environments`, keyed by OCI
/// `os/architecture`, without flattening the platforms.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FunctionVersion {
name: String,
@@ -626,6 +681,28 @@ pub struct FunctionVersion {
/// Result-stability value declared at registration.
#[serde(default, skip_serializing_if = "Option::is_none")]
result_stability: Option<String>,
/// The runtime requested at registration, with submitted lock bytes omitted.
///
/// This is a specification, not the measured installation. Compare it with
/// [`Self::resolved_environment`] when the caller needs actual package
/// versions.
#[serde(default, skip_serializing_if = "Option::is_none")]
runtime: Option<PythonRuntimeSpec>,
/// Actual installed distributions, provenance, and registration warnings.
///
/// This is the single-platform compatibility field. `None` on a
/// multiarchitecture version is expected; use
/// [`Self::resolved_environments`] for its per-platform measurements.
#[serde(default, skip_serializing_if = "Option::is_none")]
resolved_environment: Option<ResolvedEnvironment>,
/// Measurements for a multiarchitecture image, keyed by OCI
/// `os/architecture`.
///
/// Unmeasured platforms are absent. An empty map is unknown, not an
/// aggregate of packages from the available platforms. Single-platform
/// images use [`Self::resolved_environment`] instead.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
resolved_environments: BTreeMap<String, ResolvedEnvironment>,
}
impl FunctionVersion {
@@ -716,6 +793,35 @@ impl FunctionVersion {
self.result_stability.as_deref()
}
/// The runtime specification requested at registration, when exposed by the
/// server.
///
/// This is the requested configuration, not evidence of what was installed.
pub fn runtime(&self) -> Option<&PythonRuntimeSpec> {
self.runtime.as_ref()
}
/// Actual installed distributions and registration warnings for a
/// single-platform image, when measured by the server.
///
/// `None` is unknown, not an empty environment. Package versions are
/// retained verbatim, including local labels such as `+cu130`; `source`
/// remains absent when the producer did not retain it.
pub fn resolved_environment(&self) -> Option<&ResolvedEnvironment> {
self.resolved_environment.as_ref()
}
/// Per-platform measurements for a multiarchitecture image, keyed by OCI
/// `os/architecture`.
///
/// The map is returned without flattening or synthesis. A missing platform
/// means its measurement is unknown; an empty environment value is a
/// measured empty environment and is retained. Single-platform images use
/// [`Self::resolved_environment`] instead.
pub fn resolved_environments(&self) -> &BTreeMap<String, ResolvedEnvironment> {
&self.resolved_environments
}
pub fn signature(&self) -> &FunctionSignature {
&self.signature
}
@@ -827,6 +933,10 @@ fn validate_row_timeout_value(value: Option<f64>) -> std::result::Result<(), &'s
Ok(())
}
fn is_false(value: &bool) -> bool {
!*value
}
/// Stable request envelope for remote immutable Function registration.
///
/// Credential values deliberately have no field here. The only secret-shaped
@@ -877,10 +987,10 @@ pub struct FunctionRegistrationRequest {
/// Model snapshots prepared by the service before user code runs.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub models: Vec<HuggingFaceModel>,
}
fn is_false(value: &bool) -> bool {
!*value
/// Ask the service to resolve a fresh environment lock for this request
/// instead of reusing the published version's lock. Omitted when false.
#[serde(default, skip_serializing_if = "is_false")]
pub refresh_lock: bool,
}
impl FunctionRegistrationRequest {
@@ -1465,6 +1575,165 @@ mod tests {
assert!(FunctionVersion::from_json(&document.to_string()).is_err());
}
#[test]
fn function_version_preserves_requested_and_resolved_environments() {
const VERSION: &str = include_str!(
"../tests/fixtures/first_class_functions/v1/remote_function_version.canonical.json"
);
let mut document: Value = serde_json::from_str(VERSION).unwrap();
let legacy = FunctionVersion::from_json(VERSION).unwrap();
assert!(legacy.runtime().is_none());
assert!(legacy.resolved_environment().is_none());
assert!(legacy.resolved_environments().is_empty());
document["runtime"] = serde_json::json!({
"kind": "python",
"python_version": "3.12",
"environment": {
"kind": "pip",
"packages": ["vllm==0.11.0"]
}
});
document["resolved_environment"] = serde_json::json!({
"packages": [
{
"name": "torch",
"version": "2.9.0+cu130",
"source": "https://packages.example/simple"
},
{
"name": "transformers",
"version": "4.57.1"
}
],
"provenance": {
"configured_index_urls": ["https://packages.example/simple"],
"configured_find_links": ["https://downloads.example/wheels"],
"resolved_indexes": ["https://packages.example/simple"],
"cuda_toolkit": "12.8",
"torch_version": "torch==2.9.0+cu130"
},
"warnings": [
"transformers resolved to transformers==4.57.1 but is not pinned exactly; add transformers==4.57.1 to pin it."
]
});
let version = FunctionVersion::from_json(&document.to_string()).unwrap();
assert_eq!(version.runtime().unwrap().kind(), "python");
assert!(version.resolved_environments().is_empty());
let resolved = version.resolved_environment().unwrap();
assert_eq!(resolved.packages[0].version, "2.9.0+cu130");
assert_eq!(
resolved.packages[0].source.as_deref(),
Some("https://packages.example/simple")
);
assert_eq!(resolved.packages[1].source, None);
assert_eq!(
resolved
.provenance
.as_ref()
.unwrap()
.torch_version
.as_deref(),
Some("torch==2.9.0+cu130")
);
assert_eq!(resolved.warnings.len(), 1);
let encoded = version.to_canonical_json().unwrap();
let encoded_value: Value = serde_json::from_str(&encoded).unwrap();
assert_eq!(
encoded_value["resolved_environment"]["packages"][0]["version"],
"2.9.0+cu130"
);
assert!(
encoded_value["resolved_environment"]["packages"][1]
.get("source")
.is_none()
);
assert_eq!(FunctionVersion::from_json(&encoded).unwrap(), version);
document["resolved_environment"] = serde_json::json!({"warnings": []});
assert!(FunctionVersion::from_json(&document.to_string()).is_err());
}
#[test]
fn function_version_preserves_resolved_environments_by_platform() {
const VERSION: &str = include_str!(
"../tests/fixtures/first_class_functions/v1/remote_function_version.canonical.json"
);
let mut document: Value = serde_json::from_str(VERSION).unwrap();
document["runtime"] = serde_json::json!({
"kind": "python",
"python_version": "3.12",
"environment": {
"kind": "pip",
"packages": ["vllm==0.11.0"]
}
});
document["resolved_environments"] = serde_json::json!({
"linux/amd64": {
"packages": [
{"name": "torch", "version": "2.9.0+cu130"}
],
"warnings": ["amd64 measurement"]
},
"linux/arm64": {
"packages": [],
"warnings": ["arm64 measurement"]
}
});
let version = FunctionVersion::from_json(&document.to_string()).unwrap();
assert!(version.resolved_environment().is_none());
let environments = version.resolved_environments();
assert_eq!(environments.len(), 2);
assert_eq!(
environments["linux/amd64"].packages[0].version,
"2.9.0+cu130"
);
assert!(environments["linux/arm64"].packages.is_empty());
assert_eq!(environments["linux/arm64"].warnings, ["arm64 measurement"]);
let encoded = version.to_canonical_json().unwrap();
let encoded_value: Value = serde_json::from_str(&encoded).unwrap();
assert!(encoded_value.get("resolved_environment").is_none());
assert_eq!(
encoded_value["resolved_environments"]["linux/amd64"]["packages"][0]["version"],
"2.9.0+cu130"
);
assert_eq!(
encoded_value["resolved_environments"]["linux/arm64"]["packages"],
serde_json::json!([])
);
assert_eq!(FunctionVersion::from_json(&encoded).unwrap(), version);
document["resolved_environments"]
.as_object_mut()
.unwrap()
.remove("linux/arm64");
let missing_platform = FunctionVersion::from_json(&document.to_string()).unwrap();
assert!(
!missing_platform
.resolved_environments()
.contains_key("linux/arm64")
);
document["resolved_environments"] = serde_json::json!({});
let empty_map = FunctionVersion::from_json(&document.to_string()).unwrap();
assert!(empty_map.resolved_environments().is_empty());
assert!(
!empty_map
.to_canonical_json()
.unwrap()
.contains("resolved_environments")
);
document["resolved_environments"] = serde_json::json!({
"linux/amd64": {"warnings": []}
});
assert!(FunctionVersion::from_json(&document.to_string()).is_err());
}
#[test]
fn blob_reader_access_survives_signature_round_trip() {
let parameter: FunctionParameter = serde_json::from_value(serde_json::json!({
+135
View File
@@ -3171,6 +3171,38 @@ async fn function_creation_and_description_use_sql_query_handles() {
version_json["max_concurrency"] = serde_json::json!(4);
version_json["row_timeout_seconds"] = serde_json::json!(8.0);
version_json["result_stability"] = serde_json::json!("input_and_context");
version_json["runtime"] = request_json["runtime"].clone();
version_json["resolved_environment"] = serde_json::json!({
"packages": [
{
"name": "torch",
"version": "2.9.0+cu130",
"source": "https://packages.example/simple"
},
{
"name": "transformers",
"version": "4.57.1"
}
],
"provenance": {
"configured_index_urls": ["https://packages.example/simple"],
"configured_find_links": [],
"resolved_indexes": ["https://packages.example/simple"],
"cuda_toolkit": "12.8",
"torch_version": "torch==2.9.0+cu130"
},
"warnings": [
"transformers resolved to transformers==4.57.1 but is not pinned exactly; add transformers==4.57.1 to pin it."
]
});
version_json["resolved_environments"] = serde_json::json!({
"linux/amd64": {
"packages": [{"name": "torch", "version": "2.9.0+cu130"}]
},
"linux/arm64": {
"packages": []
}
});
if with_models {
let models = serde_json::json!([{
"repo": "sentence-transformers/all-MiniLM-L6-v2",
@@ -3217,6 +3249,17 @@ async fn function_creation_and_description_use_sql_query_handles() {
assert_eq!(created.max_concurrency(), Some(4));
assert_eq!(created.row_timeout_seconds(), Some(8.0));
assert_eq!(created.result_stability(), Some("input_and_context"));
assert_eq!(created.runtime().unwrap().kind(), "python");
assert_eq!(
created.resolved_environment().unwrap().packages[0].version,
"2.9.0+cu130"
);
assert_eq!(created.resolved_environments().len(), 2);
assert!(
created.resolved_environments()["linux/arm64"]
.packages
.is_empty()
);
// Assert the actual SQL body, after the same native JSON decode used
// by the Python binding, rather than only the Python declaration.
{
@@ -3240,6 +3283,23 @@ async fn function_creation_and_description_use_sql_query_handles() {
assert_eq!(created_json["max_concurrency"], 4);
assert_eq!(created_json["row_timeout_seconds"], 8.0);
assert_eq!(created_json["result_stability"], "input_and_context");
assert_eq!(
created_json["resolved_environment"]["packages"][0]["version"],
"2.9.0+cu130"
);
assert!(
created_json["resolved_environment"]["packages"][1]
.get("source")
.is_none()
);
assert_eq!(
created_json["resolved_environments"]["linux/amd64"]["packages"][0]["version"],
"2.9.0+cu130"
);
assert_eq!(
created_json["resolved_environments"]["linux/arm64"]["packages"],
serde_json::json!([])
);
assert_eq!(
client.describe(id).await.unwrap().status,
QueryStatus::Finished
@@ -3253,6 +3313,19 @@ async fn function_creation_and_description_use_sql_query_handles() {
assert_eq!(described.max_concurrency(), Some(4));
assert_eq!(described.row_timeout_seconds(), Some(8.0));
assert_eq!(described.result_stability(), Some("input_and_context"));
assert_eq!(described.runtime().unwrap().kind(), "python");
assert_eq!(
described
.resolved_environment()
.unwrap()
.provenance
.as_ref()
.unwrap()
.torch_version
.as_deref(),
Some("torch==2.9.0+cu130")
);
assert_eq!(described.resolved_environments().len(), 2);
let described_json: serde_json::Value =
serde_json::from_str(&described.to_canonical_json().unwrap()).unwrap();
assert_eq!(described_json["image"].get("models"), expected_models);
@@ -3279,6 +3352,16 @@ async fn function_creation_and_description_use_sql_query_handles() {
listed.items[0].result_stability(),
Some("input_and_context")
);
assert_eq!(listed.items[0].runtime().unwrap().kind(), "python");
assert_eq!(
listed.items[0]
.resolved_environment()
.unwrap()
.warnings
.len(),
1
);
assert_eq!(listed.items[0].resolved_environments().len(), 2);
let listed_json: serde_json::Value =
serde_json::from_str(&listed.items[0].to_canonical_json().unwrap()).unwrap();
assert_eq!(listed_json["image"].get("models"), expected_models);
@@ -3293,6 +3376,58 @@ async fn function_creation_and_description_use_sql_query_handles() {
}
}
#[tokio::test]
async fn function_creation_refresh_lock_is_forwarded_only_when_true() {
const VERSION: &str = include_str!(
"../../tests/fixtures/first_class_functions/v1/remote_function_version.canonical.json"
);
const REQUEST: &str = include_str!(
"../../tests/fixtures/first_class_functions/v1/remote_function_registration_request.json"
);
for (refresh_lock, expect_field) in [(false, false), (true, true)] {
let mut request_json: serde_json::Value = serde_json::from_str(REQUEST).unwrap();
if refresh_lock {
request_json["refresh_lock"] = serde_json::json!(true);
}
let request =
crate::function::FunctionRegistrationRequest::from_json(&request_json.to_string())
.unwrap();
assert_eq!(request.refresh_lock, refresh_lock);
let result = RecordBatch::try_from_iter(vec![(
"definition",
Arc::new(StringArray::from(vec![VERSION.to_string()])) as ArrayRef,
)])
.unwrap();
let service = TestSqlService {
adaptive: true,
defer: false,
result,
..Default::default()
};
let statements = service.statements.clone();
let (client, shutdown) = start_sql_service(service, ClientConfig::default()).await;
let db = RemoteDatabase::new_mock(|request| -> http::Response<String> {
panic!("unexpected REST request: {}", request.url().path());
})
.with_sql_client(client.clone());
let job = db.create_function_async(request, &[]).await.unwrap();
job.wait().await.unwrap();
let seen = statements.lock().unwrap();
let encoded = seen[0]
.strip_prefix(r#"CREATE FUNCTION "normalize_score" FROM '"#)
.unwrap()
.strip_suffix('\'')
.unwrap();
let sent: serde_json::Value = serde_json::from_str(&encoded.replace("''", "'")).unwrap();
assert_eq!(sent.get("refresh_lock").is_some(), expect_field);
if expect_field {
assert_eq!(sent["refresh_lock"], serde_json::json!(true));
}
drop(seen);
shutdown.send(()).unwrap();
}
}
#[tokio::test]
async fn function_creation_rejects_invalid_execution_controls_before_sql() {
const REQUEST: &str = include_str!(