From 9861959d9e58fe0fa9608542a15f478c02e63072 Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Wed, 23 Sep 2026 15:52:48 +0800 Subject: [PATCH] feat: carry Function initialization in the canonical model A Function instance is created with one initialization row whose schema the Function declares. Bindings, not Function versions, own the values: FunctionSignature.initialization lists the fields, a FunctionApplication carries the values as transport JSON, and a FunctionBinding persists the validated one-row Arrow IPC stream every instance of that binding uses. --- python/python/lancedb/functions.py | 21 +++ .../tests/test_first_class_function_slice1.py | 38 ++++ python/uv.lock | 177 +++++++++--------- rust/lancedb/src/function.rs | 87 +++++++++ .../tests/first_class_function_slice1.rs | 23 +++ ...alized_function_application.canonical.json | 1 + ...mote_initialized_function_application.json | 37 ++++ ...nitialized_function_binding.canonical.json | 1 + .../remote_initialized_function_binding.json | 30 +++ 9 files changed, 328 insertions(+), 87 deletions(-) create mode 100644 rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.canonical.json create mode 100644 rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.json create mode 100644 rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.canonical.json create mode 100644 rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.json diff --git a/python/python/lancedb/functions.py b/python/python/lancedb/functions.py index 8c6864cc3..21c8a31e0 100644 --- a/python/python/lancedb/functions.py +++ b/python/python/lancedb/functions.py @@ -256,8 +256,16 @@ class SecretBinding(_RemoteValue): class FunctionSignature(_RemoteValue): + """Ordered inputs, output, and initialization fields of a Function. + + ``initialization`` lists the fields of the single row each Function + instance is created with. Values come from each binding, not from the + Function version; the tuple is empty when the Function takes none. + """ + inputs: tuple[FunctionParameter, ...] output: FunctionOutput + initialization: tuple[FunctionParameter, ...] = () class PythonEnvironmentSpec(_RemoteValue): @@ -478,6 +486,10 @@ class FunctionApplication(_OpenRemoteValue): inputs: tuple[ApplicationInput, ...] output: FunctionOutput columns: Mapping[str, str] = Field(default_factory=dict) + # Transport JSON: the service validates it against the Function's + # initialization schema and persists the Arrow row in the binding, so it is + # never hashed and floating-point values are allowed. + initialization: Mapping[str, Any] = Field(default_factory=dict) def _known_dict(self) -> dict[str, Any]: value = super()._known_dict() @@ -560,6 +572,15 @@ class FunctionBinding(_RemoteValue): assignment: Optional[AssignmentMapping] = None input_schema: Optional[Mapping[str, Any]] = None output_schema: Optional[Mapping[str, Any]] = None + initialization: Optional[str] = None + """Standard base64 of the validated one-row Arrow IPC initialization stream.""" + + def initialization_row(self) -> Optional[dict[str, Any]]: + """The initialization values this binding creates instances with.""" + if self.initialization is None: + return None + reader = pa.ipc.open_stream(base64.b64decode(self.initialization)) + return reader.read_all().to_pylist()[0] class RefreshColumnResult(_RemoteValue): diff --git a/python/python/tests/test_first_class_function_slice1.py b/python/python/tests/test_first_class_function_slice1.py index fbcfa03b1..85118055e 100644 --- a/python/python/tests/test_first_class_function_slice1.py +++ b/python/python/tests/test_first_class_function_slice1.py @@ -83,6 +83,18 @@ def test_public_function_values_are_in_api_reference(): FunctionBinding, False, ), + ( + "remote_initialized_function_application.json", + "remote_initialized_function_application.canonical.json", + FunctionApplication, + False, + ), + ( + "remote_initialized_function_binding.json", + "remote_initialized_function_binding.canonical.json", + FunctionBinding, + False, + ), ( "remote_refresh_job.json", "remote_refresh_result.canonical.json", @@ -269,6 +281,32 @@ def test_binding_and_refresh_result_keep_stable_remote_fields(): assert RefreshColumnResult.from_json(result.to_canonical_json()) == result +def test_initialization_travels_on_the_application_and_binding(): + application = FunctionApplication.from_json( + fixture("remote_initialized_function_application.json") + ) + assert application.initialization["temperature"] == 0.25 + assert application.initialization["retry"]["backoff"] == (1, 2, 4) + application._ensure_declarable() + + binding = FunctionBinding.from_json( + fixture("remote_initialized_function_binding.json") + ) + assert binding.initialization_row() == { + "model": "text-embedding-3-small", + "dimensions": 512, + } + assert FunctionBinding.from_json( + fixture("remote_function_binding.json") + ).initialization_row() is None + + signature = FunctionVersion.from_json( + json.dumps(job_result("remote_function_job.json")) + ).signature + assert signature.initialization == () + assert "initialization" not in json.loads(signature.to_canonical_json()) + + def test_function_literal_numeric_domain_matches_rust(): with pytest.raises(ValueError, match="floating-point Function literals"): FunctionApplication.from_json(fixture("remote_function_application_float.json")) diff --git a/python/uv.lock b/python/uv.lock index 8366dd397..9d0b6832c 100644 --- a/python/uv.lock +++ b/python/uv.lock @@ -10,6 +10,9 @@ resolution-markers = [ "python_full_version < '3.11'", ] +[options] +prerelease-mode = "allow" + [[package]] name = "accelerate" version = "1.14.0" @@ -799,7 +802,7 @@ name = "cuda-bindings" version = "13.3.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cuda-pathfinder", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "cuda-pathfinder" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/a9/21/8464d133752951c154feafb3b65c297e7d80f301183d220bec4c830f1441/cuda_bindings-13.3.1-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:120fcc53d57903df529c3486962c56528cba5b7d6c57c99537320ed9922c8b86", size = 6073403, upload-time = "2026-05-29T23:11:36.22Z" }, @@ -834,37 +837,37 @@ wheels = [ [package.optional-dependencies] cublas = [ - { name = "nvidia-cublas", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cublas" }, ] cudart = [ - { name = "nvidia-cuda-runtime", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cuda-runtime" }, ] cufft = [ - { name = "nvidia-cufft", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cufft" }, ] cufile = [ - { name = "nvidia-cufile", marker = "sys_platform == 'linux'" }, + { name = "nvidia-cufile" }, ] cupti = [ - { name = "nvidia-cuda-cupti", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cuda-cupti" }, ] curand = [ - { name = "nvidia-curand", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-curand" }, ] cusolver = [ - { name = "nvidia-cusolver", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cusolver" }, ] cusparse = [ - { name = "nvidia-cusparse", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cusparse" }, ] nvjitlink = [ - { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-nvjitlink" }, ] nvrtc = [ - { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-cuda-nvrtc" }, ] nvtx = [ - { name = "nvidia-nvtx", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" }, + { name = "nvidia-nvtx" }, ] [[package]] @@ -1023,7 +1026,7 @@ name = "exceptiongroup" version = "1.3.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "typing-extensions", marker = "python_full_version < '3.11'" }, + { name = "typing-extensions" }, ] sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" } wheels = [ @@ -1440,16 +1443,16 @@ resolution-markers = [ "python_full_version < '3.11'", ] dependencies = [ - { name = "cachetools", marker = "python_full_version < '3.11'" }, - { name = "certifi", marker = "python_full_version < '3.11'" }, - { name = "httpx", marker = "python_full_version < '3.11'" }, - { name = "ibm-cos-sdk", marker = "python_full_version < '3.11'" }, - { name = "lomond", marker = "python_full_version < '3.11'" }, - { name = "packaging", marker = "python_full_version < '3.11'" }, - { name = "pandas", version = "2.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "requests", marker = "python_full_version < '3.11'" }, - { name = "tabulate", marker = "python_full_version < '3.11'" }, - { name = "urllib3", marker = "python_full_version < '3.11'" }, + { name = "cachetools" }, + { name = "certifi" }, + { name = "httpx" }, + { name = "ibm-cos-sdk" }, + { name = "lomond" }, + { name = "packaging" }, + { name = "pandas", version = "2.2.3", source = { registry = "https://pypi.org/simple" } }, + { name = "requests" }, + { name = "tabulate" }, + { name = "urllib3" }, ] sdist = { url = "https://files.pythonhosted.org/packages/c7/56/2e3df38a1f13062095d7bde23c87a92f3898982993a15186b1bfecbd206f/ibm_watsonx_ai-1.3.42.tar.gz", hash = "sha256:ee5be59009004245d957ce97d1227355516df95a2640189749487614fef674ff", size = 688651, upload-time = "2025-10-01T13:35:41.527Z" } wheels = [ @@ -1468,17 +1471,17 @@ resolution-markers = [ "python_full_version == '3.11.*'", ] dependencies = [ - { name = "cachetools", marker = "python_full_version >= '3.11'" }, - { name = "certifi", marker = "python_full_version >= '3.11'" }, - { name = "httpx", marker = "python_full_version >= '3.11'" }, - { name = "ibm-cos-sdk", marker = "python_full_version >= '3.11'" }, - { name = "lomond", marker = "python_full_version >= '3.11'" }, - { name = "packaging", marker = "python_full_version >= '3.11'" }, - { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.14'" }, + { name = "cachetools" }, + { name = "certifi" }, + { name = "httpx" }, + { name = "ibm-cos-sdk" }, + { name = "lomond" }, + { name = "packaging" }, + { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.14'" }, { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.14'" }, - { name = "requests", marker = "python_full_version >= '3.11'" }, - { name = "tabulate", marker = "python_full_version >= '3.11'" }, - { name = "urllib3", marker = "python_full_version >= '3.11'" }, + { name = "requests" }, + { name = "tabulate" }, + { name = "urllib3" }, ] sdist = { url = "https://files.pythonhosted.org/packages/29/a3/c756b534696ab2f3f29882fdb7ca7198b7a5c94e10c0a3a327853d6d6b79/ibm_watsonx_ai-1.5.14.tar.gz", hash = "sha256:a756488bd57e87c0fc51be42dcba871143cfe0ac1e805c497c5047e1e4f13e9d", size = 735804, upload-time = "2026-06-22T12:32:43.85Z" } wheels = [ @@ -1554,17 +1557,17 @@ resolution-markers = [ "python_full_version < '3.11'", ] dependencies = [ - { name = "colorama", marker = "python_full_version < '3.11' and sys_platform == 'win32'" }, - { name = "decorator", marker = "python_full_version < '3.11'" }, - { name = "exceptiongroup", marker = "python_full_version < '3.11'" }, - { name = "jedi", marker = "python_full_version < '3.11'" }, - { name = "matplotlib-inline", marker = "python_full_version < '3.11'" }, - { name = "pexpect", marker = "python_full_version < '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "prompt-toolkit", marker = "python_full_version < '3.11'" }, - { name = "pygments", marker = "python_full_version < '3.11'" }, - { name = "stack-data", marker = "python_full_version < '3.11'" }, - { name = "traitlets", marker = "python_full_version < '3.11'" }, - { name = "typing-extensions", marker = "python_full_version < '3.11'" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "decorator" }, + { name = "exceptiongroup" }, + { name = "jedi" }, + { name = "matplotlib-inline" }, + { name = "pexpect", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "prompt-toolkit" }, + { name = "pygments" }, + { name = "stack-data" }, + { name = "traitlets" }, + { name = "typing-extensions" }, ] sdist = { url = "https://files.pythonhosted.org/packages/40/18/f8598d287006885e7136451fdea0755af4ebcbfe342836f24deefaed1164/ipython-8.39.0.tar.gz", hash = "sha256:4110ae96012c379b8b6db898a07e186c40a2a1ef5d57a7fa83166047d9da7624", size = 5513971, upload-time = "2026-03-27T10:02:13.94Z" } wheels = [ @@ -1583,18 +1586,18 @@ resolution-markers = [ "python_full_version == '3.11.*'", ] dependencies = [ - { name = "colorama", marker = "python_full_version >= '3.11' and sys_platform == 'win32'" }, - { name = "decorator", marker = "python_full_version >= '3.11'" }, - { name = "ipython-pygments-lexers", marker = "python_full_version >= '3.11'" }, - { name = "jedi", marker = "python_full_version >= '3.11'" }, - { name = "matplotlib-inline", marker = "python_full_version >= '3.11'" }, - { name = "pexpect", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "prompt-toolkit", marker = "python_full_version >= '3.11'" }, - { name = "psutil", marker = "python_full_version >= '3.11' and sys_platform != 'cygwin' and sys_platform != 'emscripten'" }, - { name = "pygments", marker = "python_full_version >= '3.11'" }, - { name = "stack-data", marker = "python_full_version >= '3.11'" }, - { name = "traitlets", marker = "python_full_version >= '3.11'" }, - { name = "typing-extensions", marker = "python_full_version == '3.11.*'" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "decorator" }, + { name = "ipython-pygments-lexers" }, + { name = "jedi" }, + { name = "matplotlib-inline" }, + { name = "pexpect", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "prompt-toolkit" }, + { name = "psutil", marker = "sys_platform != 'cygwin' and sys_platform != 'emscripten'" }, + { name = "pygments" }, + { name = "stack-data" }, + { name = "traitlets" }, + { name = "typing-extensions", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/53/59/165d3b4d75cc34add3122c4417ecb229085140ac573103c223cd01dde96f/ipython-9.15.0.tar.gz", hash = "sha256:da2819ce2aa83135257df830660b1176d986c3d2876db24df01974fa955b2756", size = 4442580, upload-time = "2026-06-26T11:03:35.913Z" } wheels = [ @@ -1606,7 +1609,7 @@ name = "ipython-pygments-lexers" version = "1.1.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "pygments", marker = "python_full_version >= '3.11'" }, + { name = "pygments" }, ] sdist = { url = "https://files.pythonhosted.org/packages/ef/4c/5dd1d8af08107f88c7f741ead7a40854b8ac24ddf9ae850afbcf698aa552/ipython_pygments_lexers-1.1.1.tar.gz", hash = "sha256:09c0138009e56b6854f9535736f4171d855c8c08a563a0dcd8022f78355c7e81", size = 8393, upload-time = "2025-01-17T11:24:34.505Z" } wheels = [ @@ -2858,7 +2861,7 @@ name = "nvidia-cudnn-cu13" version = "9.19.0.56" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cublas", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-cublas" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/f1/84/26025437c1e6b61a707442184fa0c03d083b661adf3a3eecfd6d21677740/nvidia_cudnn_cu13-9.19.0.56-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:6ed29ffaee1176c612daf442e4dd6cfeb6a0caa43ddcbeb59da94953030b1be4", size = 433781201, upload-time = "2026-02-03T20:40:53.805Z" }, @@ -2870,7 +2873,7 @@ name = "nvidia-cufft" version = "12.0.0.61" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-nvjitlink" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/8b/ae/f417a75c0259e85c1d2f83ca4e960289a5f814ed0cea74d18c353d3e989d/nvidia_cufft-12.0.0.61-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2708c852ef8cd89d1d2068bdbece0aa188813a0c934db3779b9b1faa8442e5f5", size = 214053554, upload-time = "2025-09-04T08:31:38.196Z" }, @@ -2900,9 +2903,9 @@ name = "nvidia-cusolver" version = "12.0.4.66" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cublas", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, - { name = "nvidia-cusparse", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-cublas" }, + { name = "nvidia-cusparse" }, + { name = "nvidia-nvjitlink" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/c8/c3/b30c9e935fc01e3da443ec0116ed1b2a009bb867f5324d3f2d7e533e776b/nvidia_cusolver-12.0.4.66-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:02c2457eaa9e39de20f880f4bd8820e6a1cfb9f9a34f820eb12a155aa5bc92d2", size = 223467760, upload-time = "2025-09-04T08:33:04.222Z" }, @@ -2914,7 +2917,7 @@ name = "nvidia-cusparse" version = "12.6.3.3" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-nvjitlink" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/f8/94/5c26f33738ae35276672f12615a64bd008ed5be6d1ebcb23579285d960a9/nvidia_cusparse-12.6.3.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:80bcc4662f23f1054ee334a15c72b8940402975e0eab63178fc7e670aa59472c", size = 162155568, upload-time = "2025-09-04T08:33:42.864Z" }, @@ -3091,10 +3094,10 @@ resolution-markers = [ "python_full_version < '3.11'", ] dependencies = [ - { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "python-dateutil", marker = "python_full_version < '3.11'" }, - { name = "pytz", marker = "python_full_version < '3.11'" }, - { name = "tzdata", marker = "python_full_version < '3.11'" }, + { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } }, + { name = "python-dateutil" }, + { name = "pytz" }, + { name = "tzdata" }, ] sdist = { url = "https://files.pythonhosted.org/packages/9c/d6/9f8431bacc2e19dca897724cd097b1bb224a6ad5433784a44b587c7c13af/pandas-2.2.3.tar.gz", hash = "sha256:4f18ba62b61d7e192368b84517265a99b4d7ee8912f8708660fb4a366cc82667", size = 4399213, upload-time = "2024-09-20T13:10:04.827Z" } wheels = [ @@ -3143,11 +3146,11 @@ resolution-markers = [ "python_full_version == '3.11.*'", ] dependencies = [ - { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" }, + { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12' or python_full_version >= '3.14'" }, { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12' and python_full_version < '3.14'" }, - { name = "python-dateutil", marker = "python_full_version >= '3.11' and python_full_version < '3.14'" }, - { name = "pytz", marker = "python_full_version >= '3.11' and python_full_version < '3.14'" }, - { name = "tzdata", marker = "python_full_version >= '3.11' and python_full_version < '3.14'" }, + { name = "python-dateutil" }, + { name = "pytz" }, + { name = "tzdata" }, ] sdist = { url = "https://files.pythonhosted.org/packages/33/01/d40b85317f86cf08d853a4f495195c73815fdf205eef3993821720274518/pandas-2.3.3.tar.gz", hash = "sha256:e05e1af93b977f7eafa636d043f9f94c7ee3ac81af99c13508215942e64c993b", size = 4495223, upload-time = "2025-09-29T23:34:51.853Z" } wheels = [ @@ -3210,9 +3213,9 @@ resolution-markers = [ "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'", ] dependencies = [ - { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.14'" }, - { name = "python-dateutil", marker = "python_full_version >= '3.14'" }, - { name = "tzdata", marker = "(python_full_version >= '3.14' and sys_platform == 'emscripten') or (python_full_version >= '3.14' and sys_platform == 'win32')" }, + { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" } }, + { name = "python-dateutil" }, + { name = "tzdata", marker = "sys_platform == 'emscripten' or sys_platform == 'win32'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/f8/87/4341c6252d1c47b08768c3d25ac487362bf403f0313ddae4a2a26c9b1b4c/pandas-3.0.3.tar.gz", hash = "sha256:696a4a00a2a2a35d4e5deb3fc946641b96c944f02230e4f76137fe35d806c4fc", size = 4651414, upload-time = "2026-05-11T18:54:29.21Z" } wheels = [ @@ -3320,7 +3323,7 @@ name = "pexpect" version = "4.9.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "ptyprocess", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "ptyprocess" }, ] sdist = { url = "https://files.pythonhosted.org/packages/42/92/cc564bf6381ff43ce1f4d06852fc19a2f11d180f23dc32d9588bee2f149d/pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f", size = 166450, upload-time = "2023-11-25T09:07:26.339Z" } wheels = [ @@ -4683,10 +4686,10 @@ resolution-markers = [ "python_full_version < '3.11'", ] dependencies = [ - { name = "joblib", marker = "python_full_version < '3.11'" }, - { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "threadpoolctl", marker = "python_full_version < '3.11'" }, + { name = "joblib" }, + { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } }, + { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" } }, + { name = "threadpoolctl" }, ] sdist = { url = "https://files.pythonhosted.org/packages/98/c2/a7855e41c9d285dfe86dc50b250978105dce513d6e459ea66a6aeb0e1e0c/scikit_learn-1.7.2.tar.gz", hash = "sha256:20e9e49ecd130598f1ca38a1d85090e1a600147b9c02fa6f15d69cb53d968fda", size = 7193136, upload-time = "2025-09-09T08:21:29.075Z" } wheels = [ @@ -4734,13 +4737,13 @@ resolution-markers = [ "python_full_version == '3.11.*'", ] dependencies = [ - { name = "joblib", marker = "python_full_version >= '3.11'" }, - { name = "narwhals", marker = "python_full_version >= '3.11'" }, - { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" }, + { name = "joblib" }, + { name = "narwhals" }, + { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, - { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" }, + { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, { name = "scipy", version = "1.18.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, - { name = "threadpoolctl", marker = "python_full_version >= '3.11'" }, + { name = "threadpoolctl" }, ] sdist = { url = "https://files.pythonhosted.org/packages/fa/6f/37092bdb25f712817231799fc5674d8e704066a8a70c1d2d40517e18b4ab/scikit_learn-1.9.0.tar.gz", hash = "sha256:8833266989d3a5110178a9fae30783675460724d0e1efb13b14901d2c660c557", size = 7750767, upload-time = "2026-06-02T11:54:32.706Z" } wheels = [ @@ -4784,7 +4787,7 @@ resolution-markers = [ "python_full_version < '3.11'", ] dependencies = [ - { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } }, ] sdist = { url = "https://files.pythonhosted.org/packages/0f/37/6964b830433e654ec7485e45a00fc9a27cf868d622838f6b6d9c5ec0d532/scipy-1.15.3.tar.gz", hash = "sha256:eae3cf522bc7df64b42cad3925c876e1b0b6c35c1337c93e12c0f366f55b0eaf", size = 59419214, upload-time = "2025-05-08T16:13:05.955Z" } wheels = [ @@ -4843,7 +4846,7 @@ resolution-markers = [ "python_full_version == '3.11.*'", ] dependencies = [ - { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" }, + { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" } }, ] sdist = { url = "https://files.pythonhosted.org/packages/7a/97/5a3609c4f8d58b039179648e62dd220f89864f56f7357f5d4f45c29eb2cc/scipy-1.17.1.tar.gz", hash = "sha256:95d8e012d8cb8816c226aef832200b1d45109ed4464303e997c5b13122b297c0", size = 30573822, upload-time = "2026-02-23T00:26:24.851Z" } wheels = [ @@ -4920,7 +4923,7 @@ resolution-markers = [ "python_full_version >= '3.12' and python_full_version < '3.14'", ] dependencies = [ - { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, + { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" } }, ] sdist = { url = "https://files.pythonhosted.org/packages/a7/25/c2700dfaf6442b4effaa91af24ebce5dc9d31bb4a69706313aae70d72cd0/scipy-1.18.0.tar.gz", hash = "sha256:67b2ad2ad54c72ca6d04975a9b2df8c3638c34ddd5b28738e94fc2b57929d378", size = 30774447, upload-time = "2026-06-19T15:01:43.456Z" } wheels = [ diff --git a/rust/lancedb/src/function.rs b/rust/lancedb/src/function.rs index 3f790b6ab..3b7209bd5 100644 --- a/rust/lancedb/src/function.rs +++ b/rust/lancedb/src/function.rs @@ -187,6 +187,11 @@ pub struct FunctionOutput { pub struct FunctionSignature { pub inputs: Vec, pub output: FunctionOutput, + /// Ordered fields of the single initialization row a Function instance is + /// created with. Each binding supplies its own values; they are not part + /// of the Function version. Empty when the Function takes none. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub initialization: Vec, } /// One Python environment source. @@ -579,6 +584,13 @@ pub struct FunctionApplication { output: FunctionOutput, #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] columns: BTreeMap, + /// Initialization values for this binding, by initialization field name. + /// The service validates them against the Function's initialization + /// schema and persists the resulting Arrow row in the binding; this JSON + /// is transport only and never hashed into an identity, so floating-point + /// values are accepted here. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + initialization: BTreeMap, #[serde(default, flatten, skip_serializing)] unknown_fields: BTreeMap, #[serde(default, skip)] @@ -601,6 +613,11 @@ impl FunctionApplication { pub fn columns(&self) -> &BTreeMap { &self.columns } + + /// Initialization values supplied by this application, by field name. + pub fn initialization(&self) -> &BTreeMap { + &self.initialization + } /// Whether a newer writer attached application fields this client cannot /// validate. Such applications remain readable but must not be declared. pub fn has_unknown_fields(&self) -> bool { @@ -677,6 +694,11 @@ pub struct FunctionBinding { /// Exact physical Arrow schema of the binding's table outputs. #[serde(default, skip_serializing_if = "Option::is_none")] output_schema: Option, + /// Standard base64 of the one-row Arrow IPC stream every instance of this + /// binding is created with, already validated against the Function's + /// initialization schema. Absent when the Function takes none. + #[serde(default, skip_serializing_if = "Option::is_none")] + initialization: Option, } impl FunctionBinding { @@ -707,6 +729,11 @@ impl FunctionBinding { pub fn output_schema(&self) -> Option<&Value> { self.output_schema.as_ref() } + + /// Base64 one-row Arrow IPC initialization stream, if the Function takes one. + pub fn initialization(&self) -> Option<&str> { + self.initialization.as_deref() + } } impl_json!(FunctionBinding); @@ -964,6 +991,66 @@ mod tests { } } + /// A Function without initialization keeps its pre-initialization wire + /// form, so existing signatures and applications encode byte-identically. + #[test] + fn empty_initialization_is_omitted_from_the_wire() { + let signature: FunctionSignature = serde_json::from_str( + r#"{"inputs":[{"name":"x","arrow_type":"int64","nullable":true}],"output":{"kind":"scalar","arrow_type":"int64","nullable":false}}"#, + ) + .unwrap(); + assert!(signature.initialization.is_empty()); + assert!( + !canonical_json(&signature) + .unwrap() + .contains("initialization") + ); + + let signature: FunctionSignature = serde_json::from_str( + r#"{"inputs":[],"output":{"kind":"scalar","arrow_type":"int64","nullable":false},"initialization":[{"name":"factor","arrow_type":"float64","nullable":false}]}"#, + ) + .unwrap(); + assert_eq!(signature.initialization[0].name, "factor"); + assert!( + canonical_json(&signature) + .unwrap() + .contains(r#""initialization":[{"#) + ); + } + + /// Initialization values are transport JSON, validated and re-encoded as + /// Arrow by the service, so floats are accepted there while column-input + /// literals keep the Slice 1 domain. + #[test] + fn application_initialization_accepts_floats() { + let application = FunctionApplication::from_json( + r#"{"function":{"name":"scale","object_id":"o","location":"l","version":"1","manifest_digest":"sha256:x"},"inputs":[{"parameter":"x","kind":"column","value":{"path":"x"}}],"output":{"kind":"scalar","arrow_type":"float64","nullable":false},"initialization":{"factor":2.5,"label":"fast"}}"#, + ) + .unwrap(); + assert!(!application.has_unknown_fields()); + assert_eq!( + application.initialization()["factor"], + serde_json::json!(2.5) + ); + let encoded = application.to_canonical_json().unwrap(); + assert!(encoded.contains(r#""initialization":{"factor":2.5,"label":"fast"}"#)); + } + + #[test] + fn binding_initialization_round_trips() { + let binding = FunctionBinding::from_json( + r#"{"binding_id":"fb_1","function":{"name":"scale","object_id":"o","location":"l","version":"1","manifest_digest":"sha256:x"},"inputs":[],"outputs":[],"initialization":"QUJD"}"#, + ) + .unwrap(); + assert_eq!(binding.initialization(), Some("QUJD")); + assert!( + binding + .to_canonical_json() + .unwrap() + .ends_with(r#""initialization":"QUJD","inputs":[],"outputs":[]}"#) + ); + } + /// Unknown keys are how a newer server's payload reaches an older client, /// so the check has to be exact about which level it is looking at. #[test] diff --git a/rust/lancedb/tests/first_class_function_slice1.rs b/rust/lancedb/tests/first_class_function_slice1.rs index 3971a2471..86ccea1cc 100644 --- a/rust/lancedb/tests/first_class_function_slice1.rs +++ b/rust/lancedb/tests/first_class_function_slice1.rs @@ -115,6 +115,29 @@ fn application_and_binding_match_shared_remote_goldens() { ); } +/// Initialization values travel as JSON on the application, including +/// floats, and as the validated Arrow row on the binding. +#[test] +fn initialized_application_and_binding_match_shared_remote_goldens() { + let application = + FunctionApplication::from_json(&fixture("remote_initialized_function_application.json")) + .expect("application fixture"); + assert!(!application.has_unknown_fields()); + assert_eq!(application.initialization()["temperature"], 0.25); + assert_eq!( + application.to_canonical_json().expect("canonical JSON"), + fixture("remote_initialized_function_application.canonical.json").trim() + ); + + let binding = FunctionBinding::from_json(&fixture("remote_initialized_function_binding.json")) + .expect("binding fixture"); + assert!(binding.initialization().is_some()); + assert_eq!( + binding.to_canonical_json().expect("canonical JSON"), + fixture("remote_initialized_function_binding.canonical.json").trim() + ); +} + #[test] fn refresh_job_result_matches_shared_canonical_golden() { let result = job_result("remote_refresh_job.json"); diff --git a/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.canonical.json b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.canonical.json new file mode 100644 index 000000000..7efcecdba --- /dev/null +++ b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.canonical.json @@ -0,0 +1 @@ +{"function":{"location":"memory:///fixture","manifest_digest":"sha256:7e22f815b6648e14f093a3979a8e5a2082fa773ebe1ec84b135cae7e84d6f8e6","name":"openai_embed","object_id":"fixture","version":"1"},"initialization":{"dimensions":512,"model":"text-embedding-3-small","prompt":null,"retry":{"backoff":[1,2,4],"max_attempts":6},"temperature":0.25},"inputs":[{"kind":"column","parameter":"text","value":{"path":"body"}}],"output":{"arrow_type":"list","kind":"scalar","nullable":false}} diff --git a/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.json b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.json new file mode 100644 index 000000000..84d7c48c1 --- /dev/null +++ b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_application.json @@ -0,0 +1,37 @@ +{ + "function": { + "name": "openai_embed", + "version": "1", + "object_id": "fixture", + "location": "memory:///fixture", + "manifest_digest": "sha256:7e22f815b6648e14f093a3979a8e5a2082fa773ebe1ec84b135cae7e84d6f8e6" + }, + "inputs": [ + { + "parameter": "text", + "kind": "column", + "value": { + "path": "body" + } + } + ], + "output": { + "kind": "scalar", + "arrow_type": "list", + "nullable": false + }, + "initialization": { + "model": "text-embedding-3-small", + "dimensions": 512, + "temperature": 0.25, + "retry": { + "max_attempts": 6, + "backoff": [ + 1, + 2, + 4 + ] + }, + "prompt": null + } +} diff --git a/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.canonical.json b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.canonical.json new file mode 100644 index 000000000..42ee442fe --- /dev/null +++ b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.canonical.json @@ -0,0 +1 @@ +{"binding_id":"fb_01K3EMBED","function":{"location":"memory:///fixture","manifest_digest":"sha256:7e22f815b6648e14f093a3979a8e5a2082fa773ebe1ec84b135cae7e84d6f8e6","name":"openai_embed","object_id":"fixture","version":"1"},"initialization":"/////7AAAAAQAAAAAAAKAAwABgAFAAgACgAAAAABBAAMAAAACAAIAAAABAAIAAAABAAAAAIAAABUAAAABAAAAMT///8AAAACEAAAACQAAAAEAAAAAAAAAAoAAABkaW1lbnNpb25zAAAIAAwACAAHAAgAAAAAAAABIAAAABAAFAAIAAAABwAMAAAAEAAQAAAAAAAABRAAAAAcAAAABAAAAAAAAAAFAAAAbW9kZWwAAAAEAAQABAAAAP/////IAAAAFAAAAAAAAAAMABYABgAFAAgADAAMAAAAAAMEABgAAAAoAAAAAAAAAAAACgAYAAwABAAIAAoAAABsAAAAEAAAAAEAAAAAAAAAAAAAAAUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAgAAAAAAAAAFgAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAEAAAAAAAAAAAAAAACAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAFgAAAHRleHQtZW1iZWRkaW5nLTMtc21hbGwAAAACAAAAAAAA/////wAAAAA=","inputs":[{"arrow_type":"utf8","field_id":12,"field_path":"body","nullable":true,"parameter":"text"}],"outputs":[{"arrow_type":"list","nullable":false,"output_field_id":21,"output_name":"embedding","output_ordinal":0,"result_field":"result"}]} diff --git a/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.json b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.json new file mode 100644 index 000000000..c0f41641e --- /dev/null +++ b/rust/lancedb/tests/fixtures/first_class_functions/v1/remote_initialized_function_binding.json @@ -0,0 +1,30 @@ +{ + "binding_id": "fb_01K3EMBED", + "function": { + "name": "openai_embed", + "version": "1", + "object_id": "fixture", + "location": "memory:///fixture", + "manifest_digest": "sha256:7e22f815b6648e14f093a3979a8e5a2082fa773ebe1ec84b135cae7e84d6f8e6" + }, + "inputs": [ + { + "parameter": "text", + "field_id": 12, + "field_path": "body", + "arrow_type": "utf8", + "nullable": true + } + ], + "outputs": [ + { + "result_field": "result", + "output_name": "embedding", + "output_field_id": 21, + "output_ordinal": 0, + "arrow_type": "list", + "nullable": false + } + ], + "initialization": "/////7AAAAAQAAAAAAAKAAwABgAFAAgACgAAAAABBAAMAAAACAAIAAAABAAIAAAABAAAAAIAAABUAAAABAAAAMT///8AAAACEAAAACQAAAAEAAAAAAAAAAoAAABkaW1lbnNpb25zAAAIAAwACAAHAAgAAAAAAAABIAAAABAAFAAIAAAABwAMAAAAEAAQAAAAAAAABRAAAAAcAAAABAAAAAAAAAAFAAAAbW9kZWwAAAAEAAQABAAAAP/////IAAAAFAAAAAAAAAAMABYABgAFAAgADAAMAAAAAAMEABgAAAAoAAAAAAAAAAAACgAYAAwABAAIAAoAAABsAAAAEAAAAAEAAAAAAAAAAAAAAAUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAgAAAAAAAAAFgAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAEAAAAAAAAAAAAAAACAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAFgAAAHRleHQtZW1iZWRkaW5nLTMtc21hbGwAAAACAAAAAAAA/////wAAAAA=" +}