From 21c9fad92d5ed889d733d12f3f67eba76677570e Mon Sep 17 00:00:00 2001 From: Amirabbas Jalali <258926044+amirabbas-jalali-bentley@users.noreply.github.com> Date: Fri, 13 Nov 2026 21:19:23 -0600 Subject: [PATCH 1/2] Resolve compute references and hydrate task results generically Add ReferenceResolver to convert typed geoscience objects, attributes, files, and parameter models into wire references using each task's published schema annotations, with configurable supported_schemas checks. Add TaskResult and ResultNode dict subclasses so output references can be loaded back into typed objects or DataFrames, warn once per unrecognised catalogue annotation in DiscoveryClient, and add payload/behavior parity tests comparing the generic engine against the typed task runners. --- packages/evo-compute/pyproject.toml | 4 + .../evo-compute/src/evo/compute/__init__.py | 5 + .../evo-compute/src/evo/compute/discovery.py | 34 + .../evo-compute/src/evo/compute/engine.py | 70 +- .../evo-compute/src/evo/compute/outputs.py | 200 ++++++ .../evo-compute/src/evo/compute/resolution.py | 608 ++++++++++++++++ .../evo-compute/src/evo/compute/validation.py | 6 + .../tests/data/discovery-resolution.json | 258 +++++++ .../tests/data/discovery-tasks.json | 30 +- .../tests/data/discovery-validation.json | 2 +- .../evo-compute/tests/test_behavior_parity.py | 535 ++++++++++++++ packages/evo-compute/tests/test_discovery.py | 42 +- packages/evo-compute/tests/test_engine.py | 68 +- packages/evo-compute/tests/test_outputs.py | 314 +++++++++ .../evo-compute/tests/test_payload_parity.py | 657 ++++++++++++++++++ packages/evo-compute/tests/test_resolution.py | 630 +++++++++++++++++ .../tests/test_schema_conformance.py | 12 +- packages/evo-compute/tests/test_validation.py | 35 +- 18 files changed, 3442 insertions(+), 68 deletions(-) create mode 100644 packages/evo-compute/src/evo/compute/outputs.py create mode 100644 packages/evo-compute/src/evo/compute/resolution.py create mode 100644 packages/evo-compute/tests/data/discovery-resolution.json create mode 100644 packages/evo-compute/tests/test_behavior_parity.py create mode 100644 packages/evo-compute/tests/test_outputs.py create mode 100644 packages/evo-compute/tests/test_payload_parity.py create mode 100644 packages/evo-compute/tests/test_resolution.py diff --git a/packages/evo-compute/pyproject.toml b/packages/evo-compute/pyproject.toml index 12b6f6417..aea2a2383 100644 --- a/packages/evo-compute/pyproject.toml +++ b/packages/evo-compute/pyproject.toml @@ -42,6 +42,10 @@ dev = [ {include-group = "test"}, ] +[tool.pytest.ini_options] +# The parity suites share one harness module, so `tests` has to be importable under any import mode. +pythonpath = ["tests"] + [tool.ruff] src = ["src", "tests"] line-length = 120 diff --git a/packages/evo-compute/src/evo/compute/__init__.py b/packages/evo-compute/src/evo/compute/__init__.py index 3605ea56b..60726269f 100644 --- a/packages/evo-compute/src/evo/compute/__init__.py +++ b/packages/evo-compute/src/evo/compute/__init__.py @@ -16,6 +16,8 @@ from .endpoints.models import TaskResource from .engine import ComputeClient from .exceptions import ParameterValidationError +from .outputs import ResultNode, TaskResult +from .resolution import ReferenceResolver __all__ = [ "ComputeClient", @@ -24,6 +26,9 @@ "JobProgress", "JobStatusEnum", "ParameterValidationError", + "ReferenceResolver", + "ResultNode", "TaskResource", + "TaskResult", "tasks", ] diff --git a/packages/evo-compute/src/evo/compute/discovery.py b/packages/evo-compute/src/evo/compute/discovery.py index 5993280ee..4d867ad9b 100644 --- a/packages/evo-compute/src/evo/compute/discovery.py +++ b/packages/evo-compute/src/evo/compute/discovery.py @@ -15,11 +15,18 @@ and result schemas for each. The catalogue is paginated by the service; this client fetches every page and caches the combined result with a time-to-live. The convenience accessors (:meth:`get_topics`, :meth:`get_topic_tasks`, :meth:`get_task`) read from that cache. + +A fetched catalogue is also checked against the closed annotation vocabulary the engine +understands. An annotation this SDK has never heard of means the platform has moved on and +the schema can only be partly interpreted, so it is reported as a warning -- never a +failure. The unrecognised part may not even be one this call depends on, and refusing to +run would make the SDK the blocker the moment the platform ships a new annotation. """ from __future__ import annotations import asyncio +import logging import time from uuid import UUID @@ -27,11 +34,14 @@ from .endpoints.api import DiscoveryApi from .endpoints.models import TaskResource +from .validation import unknown_annotation_keys __all__ = [ "DiscoveryClient", ] +logger = logging.getLogger("compute.discovery") + DEFAULT_CACHE_TTL_SECONDS = 300.0 """Default time-to-live for the cached task catalogue, in seconds.""" @@ -64,6 +74,7 @@ def __init__( self._mutex = asyncio.Lock() self._cache: list[TaskResource] = [] self._cache_expiry: float | None = None + self._reported_annotations: set[str] = set() @classmethod def from_context( @@ -129,6 +140,29 @@ async def _fetch(self) -> None: break self._cache = tasks self._cache_expiry = time.monotonic() + self._cache_ttl_seconds + self._report_unknown_annotations(tasks) + + def _report_unknown_annotations(self, tasks: list[TaskResource]) -> None: + """Warn once about each annotation the platform publishes and this SDK cannot read. + + Reported per key rather than per task, and only the first time a key is seen, so a + catalogue that has moved ahead of the installed SDK costs one line rather than one + per task per cache expiry. + """ + carriers: dict[str, list[str]] = {} + for task in tasks: + for key in unknown_annotation_keys(task.parameters) | unknown_annotation_keys(task.results): + if key not in self._reported_annotations: + carriers.setdefault(key, []).append(f"{task.topic}.{task.name}") + if not carriers: + return + self._reported_annotations |= carriers.keys() + logger.warning( + "the compute catalogue uses schema annotations this SDK does not recognise: %s. " + "Those parts of the affected schemas cannot be interpreted, so a task may need " + "arguments in their wire form; upgrading evo-compute may add support for them.", + "; ".join(f"{key!r} on {', '.join(sorted(names))}" for key, names in sorted(carriers.items())), + ) async def _catalogue(self, force_refresh: bool) -> list[TaskResource]: """Return the cached catalogue, fetching it first if it is stale or forced.""" diff --git a/packages/evo-compute/src/evo/compute/engine.py b/packages/evo-compute/src/evo/compute/engine.py index 5531bee63..5cb13dc64 100644 --- a/packages/evo-compute/src/evo/compute/engine.py +++ b/packages/evo-compute/src/evo/compute/engine.py @@ -19,11 +19,15 @@ client = ComputeClient(context) result = await client.geostatistics.kriging.run(source=..., target=..., ...) +A call is checked, resolved, checked again and submitted: required parameters first +(before anything reaches the network), then :mod:`~evo.compute.resolution` turns the +caller's objects and attributes into the references the schema declares, then optional +deep validation runs on that resolved payload -- the form the platform actually receives. +What comes back is hydrated against the task's ``results`` schema by +:mod:`~evo.compute.outputs`, so the objects a task wrote can be loaded straight back. + Topic, task and parameter names are the platform's names with hyphens replaced by underscores, so ``normal-score`` is reached as ``client.geostatistics.normal_score``. -Parameters are sent in the form the task's schema declares, and only the ones the -caller passes: unset optional parameters are left to the platform's defaults. - The catalogue is fetched the first time a task is ``run(...)``. It is then held by the underlying :class:`~evo.compute.discovery.DiscoveryClient`, so repeated runs are served from there until its cache expires. @@ -42,6 +46,8 @@ from .discovery import DEFAULT_CACHE_TTL_SECONDS, DiscoveryClient from .endpoints.models import TaskResource from .exceptions import ParameterValidationError +from .outputs import TaskResult +from .resolution import ReferenceResolver from .validation import validate_parameters __all__ = [ @@ -129,7 +135,7 @@ def _signature_from_schema(spec: TaskResource) -> inspect.Signature: parameters.append(inspect.Parameter("preview", inspect.Parameter.KEYWORD_ONLY, default=False, annotation=bool)) if properties and not names: parameters.append(inspect.Parameter("parameters", inspect.Parameter.VAR_KEYWORD, annotation=Any)) - return inspect.Signature(parameters, return_annotation=dict) + return inspect.Signature(parameters, return_annotation=TaskResult) def _check_fallback_parameters(spec: TaskResource, parameters: dict[str, Any], label: str) -> None: @@ -154,11 +160,21 @@ class ComputeClient: :param context: An authenticated Evo context. :param cache_ttl_seconds: How long a discovered task catalogue is cached. - :param validate: Validate parameters against the task schema before submitting - (required-field presence). Defaults to ``True``. This is the master switch: - ``False`` turns off deep validation too, whatever ``deep_validation`` says. + :param validate: Check the parameters against the task's JSON Schema before submitting + (required-field presence, and, under ``deep_validation``, the whole payload). + Defaults to ``True``. ``False`` turns off deep validation too, whatever + ``deep_validation`` says. It does *not* make the call unchecked: the parameters are + still bound to the signature synthesised from the schema, so an unknown or missing + required argument is still rejected. That is how the payload is built, not a + validation pass, and there is no useful call to make without it. :param deep_validation: Additionally run full JSON Schema Draft 2020-12 validation. Defaults to ``False``. Only consulted when ``validate`` is ``True``. + :param check_schemas: Check that each referenced geoscience object is of a schema the + task declares support for. Defaults to following ``validate``. Independent of it + because the cost and the question differ: schema validation is local and free, + while this loads each referenced object's metadata. Pass ``False`` to keep + validation but skip the requests, or ``True`` alongside ``validate=False`` to keep + the guard that catches an object the task cannot read. """ def __init__( @@ -168,12 +184,16 @@ def __init__( cache_ttl_seconds: float = DEFAULT_CACHE_TTL_SECONDS, validate: bool = True, deep_validation: bool = False, + check_schemas: bool | None = None, ) -> None: + self._context = context self._org_id: UUID = context.get_org_id() self._connector: APIConnector = context.get_connector() self._discovery = DiscoveryClient(self._connector, self._org_id, cache_ttl_seconds=cache_ttl_seconds) + self._resolver = ReferenceResolver(context) self._validate = validate self._deep_validation = deep_validation + self._check_schemas = check_schemas # -- dynamic namespace ------------------------------------------------- # @@ -210,24 +230,25 @@ async def arun( *, validate: bool | None = None, deep_validation: bool | None = None, - ) -> dict: - """Run a task by name and wait for its results. - - The same as ``await client...run(**parameters)``, for names held as - strings. Names may be spelled as the platform publishes them or with underscores. + check_schemas: bool | None = None, + ) -> TaskResult: + """Discover the task (cached), resolve and validate the parameters, submit, and hydrate the results. :param topic: The task topic. :param task: The task name. :param parameters: The task parameters, plus ``preview=True`` to run a preview task. - :param validate: Override the client's shallow-validation setting for this call. - The master switch: ``False`` skips deep validation too. + :param validate: Override the client's schema-validation setting for this call. + ``False`` skips deep validation too, but never the signature binding that + builds the payload. :param deep_validation: Override the client's deep-validation setting for this call. Only consulted when validation is enabled. + :param check_schemas: Override the client's supported-schema setting for this call. + Falls back to ``validate`` when neither is set. - :return: The results of the finished job. + :return: The hydrated results of the finished job. :raises AttributeError: If the topic does not advertise the task. - :raises ParameterValidationError: If the parameters do not match the task's schema. + :raises ParameterValidationError: If the parameters or referenced objects fail validation. """ spec = await self._resolve_spec(topic, task) label = f"{topic}.{_normalise(task)}" @@ -253,9 +274,18 @@ async def arun( validate = self._validate if deep_validation is None: deep_validation = self._deep_validation - # ``validate`` is the master switch; deep validation only runs underneath it. + if check_schemas is None: + check_schemas = self._check_schemas if self._check_schemas is not None else validate + # ``validate`` masters the schema checks; ``check_schemas`` stands on its own. if validate: - validate_parameters(spec, wire_parameters, deep=deep_validation, task_label=label) + # Required fields first: a missing parameter is worth reporting before resolution + # spends a request loading the objects the other parameters name. + validate_parameters(spec, wire_parameters, task_label=label) + wire_parameters = await self._resolver.resolve( + spec, wire_parameters, check_schemas=check_schemas, task_label=label + ) + if validate and deep_validation: + validate_parameters(spec, wire_parameters, deep=True, task_label=label) job: JobClient[dict] = await JobClient.submit( connector=self._connector, @@ -266,7 +296,7 @@ async def arun( result_type=dict, preview=preview, ) - return await job.wait_for_results() + return TaskResult(await job.wait_for_results(), spec.results, self._context) async def _resolve_spec(self, topic: str, task: str) -> TaskResource: """Return the discovery spec for ``topic``/``task``, whether spelled with hyphens or underscores. @@ -338,7 +368,7 @@ def _make_run(client: ComputeClient, topic: str, task: str): discovery is never triggered by attribute access alone. """ - async def run(**parameters: Any) -> dict: + async def run(**parameters: Any) -> TaskResult: try: return await client.arun(topic, task, parameters) finally: diff --git a/packages/evo-compute/src/evo/compute/outputs.py b/packages/evo-compute/src/evo/compute/outputs.py new file mode 100644 index 000000000..55ccf9b9b --- /dev/null +++ b/packages/evo-compute/src/evo/compute/outputs.py @@ -0,0 +1,200 @@ +# Copyright © 2026 Bentley Systems, Incorporated +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Output hydration: the references a task returns, back as typed objects. + +A task's results are references too -- ``{"reference": "", "name": ..., "schema_id": +...}`` for an object it wrote, a JMESPath expression for the attribute it filled in. The +task's published ``results`` schema marks each of those with an ``output`` annotation, which +is all :class:`TaskResult` needs to hand the caller a loadable object instead of a URL:: + + result = await client.geostatistics.kriging.run(...) + grid = await result.target.load() + frame = await result.target.to_dataframe() + estimates = await result.target.attribute.to_dataframe() + +An ``output: attribute`` node names an attribute rather than an object, so it carries the +same two annotations the input side uses to place one: ``attribute_from``, a relative JSON +pointer to the object the attribute lives on, and ``attribute_path``, the container each +object family keeps attributes in. A task publishes one expression for every family it +supports, so the container it names can be the wrong one for the object actually written -- +:meth:`ResultNode.load` repairs it from ``attribute_path`` rather than reporting a miss. + +:class:`TaskResult` and :class:`ResultNode` subclass :class:`dict`, so the raw payload is +still available exactly as the platform sent it -- ``result["target"]["reference"]`` and +``result == {...}`` behave as they did before hydration existed. Attribute access and the +loaders are additions on top, driven entirely by the schema; nothing here is task-specific. +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from typing import TYPE_CHECKING, Any + +from evo.common import IContext +from evo.objects import ObjectSchema +from evo.objects.typed import BaseObject, object_from_reference + +# ``attribute_path`` means the same thing on the way in and on the way out, so both sides +# read it through the same helpers rather than agreeing by convention. +from .resolution import _container_for, _container_of, _pointer_value +from .tasks.common.source_target import AnyTypedAttribute + +if TYPE_CHECKING: + import pandas as pd + +__all__ = [ + "ResultNode", + "TaskResult", +] + + +class ResultNode(dict): + """One object in a task's result payload, viewed through its ``results`` schema. + + Nested objects and arrays of objects are hydrated into further nodes, so the whole + result is reachable by attribute access. Nodes annotated ``output: geoscience-object`` + or ``output: attribute`` additionally offer :meth:`load` and :meth:`to_dataframe`. + """ + + def __init__( + self, + payload: dict, + schema: dict[str, Any] | None, + context: IContext, + *, + root: dict | None = None, + path: tuple[str, ...] = (), + ) -> None: + """ + :param payload: The raw payload for this node. + :param schema: The ``results`` subschema describing it, if the task published one. + :param context: An authenticated Evo context, used to load referenced objects. + :param root: The whole result payload, which ``attribute_from`` pointers index into. + :param path: Where this node sits in that payload, which they are relative to. + """ + self._schema = schema if isinstance(schema, dict) else {} + self._context = context + self._root: dict = self if root is None else root + self._path = path + properties = self._schema.get("properties", {}) or {} + super().__init__( + { + name: _hydrate(value, properties.get(name), context, self._root, (*path, name)) + for name, value in payload.items() + } + ) + + def __getattr__(self, name: str) -> Any: + # Result fields are whatever the payload carried, so they cannot be declared up + # front. Only fires for names that are not real attributes of the dict itself. + if name.startswith("_") or name not in self: + raise AttributeError(name) + return self[name] + + def __dir__(self) -> list[str]: + return sorted(set(super().__dir__()) | {key for key in self if isinstance(key, str) and key.isidentifier()}) + + async def load(self) -> BaseObject | AnyTypedAttribute: + """Load whatever this node refers to, as its typed class. + + :return: The typed object for an ``output: geoscience-object`` node, or the typed + attribute for an ``output: attribute`` one. + + :raises TypeError: If this node is not annotated as either. + :raises ValueError: If an attribute's owning object cannot be identified, or the + attribute is not on it. + """ + match self._schema.get("output"): + case "geoscience-object": + return await object_from_reference(self._context, self["reference"]) + case "attribute": + return await self._load_attribute() + raise TypeError("this result is not a geoscience object or attribute reference") + + async def to_dataframe(self, *keys: str) -> pd.DataFrame: + """Load what this node refers to and read it into a DataFrame. + + :param keys: Attributes to include, if the object's type accepts a selection. An + ``output: attribute`` node is a single column and takes none. + + :raises TypeError: If this node is not a geoscience object or attribute reference. + """ + loaded = await self.load() + if isinstance(loaded, BaseObject): + return await loaded.to_dataframe(*keys) + if keys: + raise TypeError("an attribute result is a single column and takes no keys") + return await loaded.to_dataframe() + + async def _load_attribute(self) -> AnyTypedAttribute: + """The typed attribute this node names, on the object ``attribute_from`` points to.""" + leaf = (self._schema.get("properties") or {}).get("reference") or {} + pointer = leaf.get("attribute_from") + reference = _pointer_value(pointer, [*self._path, "reference"], self._root) if pointer else None + if not isinstance(reference, str): + raise ValueError(f"cannot tell which object this attribute belongs to (attribute_from={pointer!r})") + + owner = await object_from_reference(self._context, reference) + expression = self["reference"] + if (match := _search(owner, expression)) is None: + expression = _healed(expression, leaf.get("attribute_path"), owner.metadata.schema_id) + match = _search(owner, expression) + if match is None: + raise ValueError(f"{expression!r} matches no attribute on {reference}") + + # Every family that can carry a compute attribute exposes its ``attribute_path`` + # container as ``attributes`` -- ``locations.attributes`` on a pointset, + # ``cell_attributes`` on a grid -- so the typed lookup needs no per-family code. + container = getattr(owner, "attributes", None) + found = None if container is None else container[match.get("key") or match["name"]] + if found is None or not found.exists: + raise ValueError(f"{expression!r} is not an attribute {type(owner).__name__} exposes") + return found + + +class TaskResult(ResultNode): + """What a task returned, hydrated against the ``results`` schema it published. + + A :class:`dict` of the raw payload, plus attribute access and typed loaders for the + parts the schema marks as outputs. A task that publishes no ``results`` schema simply + yields the payload unhydrated. + """ + + +def _hydrate(value: Any, schema: Any, context: IContext, root: dict, path: tuple[str, ...]) -> Any: + """Wrap the objects inside ``value``, leaving scalars and nulls as they came.""" + if isinstance(value, dict): + return ResultNode(value, schema, context, root=root, path=path) + if isinstance(value, list): + items = schema.get("items") if isinstance(schema, dict) else None + return [_hydrate(item, items, context, root, (*path, str(index))) for index, item in enumerate(value)] + return value + + +def _search(owner: BaseObject, expression: str) -> Mapping[str, Any] | None: + """The first attribute a JMESPath expression selects on an object, if it selects any.""" + found = owner.search(expression) + if isinstance(found, Sequence) and not isinstance(found, (str, bytes)): + found = found[0] if len(found) else None + return found if isinstance(found, Mapping) else None + + +def _healed(expression: str, containers: Any, schema: ObjectSchema) -> str: + """Point an attribute expression at the container this object's family actually uses. + + A task supporting several object families publishes one expression for all of them, so a + result can name ``locations.attributes`` for an object that keeps its attributes under + ``cell_attributes``. ``attribute_path`` says which is right; the predicate is left alone. + """ + if (container := _container_for(containers, schema)) is None: + return expression + return container + expression[len(_container_of(expression)) :] diff --git a/packages/evo-compute/src/evo/compute/resolution.py b/packages/evo-compute/src/evo/compute/resolution.py new file mode 100644 index 000000000..9346e9199 --- /dev/null +++ b/packages/evo-compute/src/evo/compute/resolution.py @@ -0,0 +1,608 @@ +# Copyright © 2026 Bentley Systems, Incorporated +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Reference resolution: friendly Python inputs in, wire-shaped payload out. + +Compute tasks address data by reference -- an object URL, a JMESPath expression naming an +attribute, a File API URL. Asking callers to build those by hand is the ergonomic gap the +typed geostatistics tasks close with :class:`~evo.compute.tasks.Source` / +:class:`~evo.compute.tasks.Target`. :class:`ReferenceResolver` generalises that: it reads +the reference annotations off *any* task's published schema, so one walker serves every +task in the catalogue with no per-task code. + +The annotations it acts on (the closed vocabulary the platform publishes): + +.. code-block:: text + + reference_to: geoscience-object -> a validated object URL + reference_to: attribute -> a JMESPath expression + reference_to: file -> a File API URL + supported_schemas: [...] -> object families/versions the leaf accepts + attribute_from: -> which sibling object an attribute lives on + attribute_path: {pattern: [...]} -> per-object-family JMESPath container + target: attribute -> a create/update attribute slot + discriminator: -> tagged union; pick the branch by the tag + +Resolution reuses the very helpers the hand-written runners use +(:mod:`evo.compute.tasks.common.source_target`), so the two paths agree on the wire by +construction rather than by convention. It is also idempotent: a value that is already in +its wire form -- a URL string, a ready JMESPath expression, a ``{"operation": ...}`` dict +-- passes through untouched, so there is nothing to switch off. + +``supported_schemas`` is enforced as a hard error when the referenced object's schema can +be established, either from a typed object the caller already holds or from a metadata +download. When the object cannot be loaded (a cross-hub reference, a transient objects-API +failure) the check is downgraded to a logged warning: an availability problem must not +block a job the platform would happily accept, and the platform re-checks server side. +""" + +from __future__ import annotations + +import logging +import operator +import re +from dataclasses import dataclass, field +from typing import Any +from uuid import UUID + +from evo.common import IContext +from evo.objects import DownloadedObject, ObjectMetadata, ObjectReference, ObjectSchema, SchemaVersion +from evo.objects.typed import BaseObject + +from .endpoints.models import TaskResource +from .exceptions import ParameterValidationError + +# The engine deliberately shares the typed tasks' conversion helpers rather than +# reimplementing them, so a generic call and a hand-written runner cannot drift apart. +from .tasks.common.source_target import ( + AnyTypedAttribute, + _convert_object_reference, + _get_attribute_expression, + _source_from_attribute, + _validate_target_attribute, +) + +__all__ = [ + "ReferenceResolver", +] + +logger = logging.getLogger("compute.resolution") + +# A JMESPath filter projection, e.g. ``locations.attributes[?name=='grade']``. Its presence +# is what separates a ready-made expression from a bare attribute name. +_PROJECTION = "[?" + +# A File API v2 reference: an absolute URL, or the service-relative path form. Deliberately +# loose -- the aim is to catch a local filename, not to spell out a grammar this package has +# no File API client to check against. +_FILE_REFERENCE = re.compile(r"(?:https://|/file/)", re.IGNORECASE) + +# What a caller may hand over in place of an object: anything ``_convert_object_reference`` +# accepts, plus the bare object id ``_as_uuid`` expands. +_OBJECT_HANDLE = (str, UUID, BaseObject, DownloadedObject, ObjectMetadata) + +# One bound of a ``supported_schemas`` version range, e.g. ``>=1.2`` or ``<2``. +_BOUND = re.compile(r"(?P>=|<=|>|<|==|=)?\s*(?P\d+(?:\.\d+)*)") + +_COMPARISONS = { + ">=": operator.ge, + "<=": operator.le, + ">": operator.gt, + "<": operator.lt, + "=": operator.eq, + "==": operator.eq, +} + + +@dataclass +class _Walk: + """State shared by one :meth:`ReferenceResolver.resolve` pass. + + ``resolved`` is filled in as the walk proceeds so an ``attribute_from`` pointer can read + a sibling object that was resolved moments earlier; ``supplied`` is the caller's original + payload, consulted when a pointer names a parameter the walk has not reached yet. + """ + + schema: dict[str, Any] + label: str + supplied: dict[str, Any] + check_schemas: bool = True + resolved: dict[str, Any] = field(default_factory=dict) + + +class ReferenceResolver: + """Resolves a task's caller-supplied parameters into the payload the platform expects. + + One instance serves every task. Object schemas are cached for the lifetime of the + resolver, so an object referenced by several parameters is only fetched once. + + :param context: An authenticated Evo context, used to load referenced objects. + """ + + def __init__(self, context: IContext) -> None: + self._context = context + self._schemas: dict[str, ObjectSchema | None] = {} + + async def resolve( + self, + spec: TaskResource, + parameters: dict[str, Any], + *, + check_schemas: bool = True, + task_label: str | None = None, + ) -> dict[str, Any]: + """Resolve every reference in ``parameters`` against the task's parameter schema. + + :param spec: The discovered task, carrying its ``parameters`` JSON Schema. + :param parameters: The parameters the caller supplied, keyed by wire name. + :param check_schemas: Enforce ``supported_schemas`` on object references. + :param task_label: A ``topic.task`` label for error messages; derived from ``spec`` + when omitted. + + :return: A new payload with every reference in the form the schema declares. + + :raises ParameterValidationError: If a value cannot be resolved to a reference, or + names an object outside a leaf's ``supported_schemas``. + """ + schema = spec.parameters or {} + walk = _Walk( + schema=schema, + label=task_label or f"{spec.topic}.{spec.name.replace('-', '_')}", + supplied=parameters, + check_schemas=check_schemas, + ) + properties = schema.get("properties", {}) or {} + for name, value in parameters.items(): + node = _deref(properties.get(name, {}), schema) + walk.resolved[name] = await self._resolve_node(node, value, [name], walk) + return walk.resolved + + # -- the walk ---------------------------------------------------------- # + + async def _resolve_node(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> Any: + """Resolve one value against the schema node that describes it.""" + if value is None: + return None + node = _deref(node, walk.schema) + + # A tagged union describes several shapes; only the tagged branch's annotations apply. + if (discriminator := _discriminator_of(node)) is not None: + node = _select_branch(node, value, discriminator, walk.schema) or node + + match node.get("reference_to"): + case "geoscience-object": + return await self._resolve_object(node, value, path, walk) + case "attribute": + return await self._resolve_attribute(node, value, path, walk) + case "file": + return _resolve_file(value, path, walk) + + if node.get("target") == "attribute": + return await self._resolve_target_attribute(node, value, path, walk) + + # One of the SDK's typed parameter models (Source, Target, a filter, a sub-block frame, + # ...). Dumping it yields the shape the schema describes. This happens before the walk + # looks for ``properties`` because a union or optional slot has none of its own, and a + # model left alone there would reach the wire as a model. + if not isinstance(value, (dict, AnyTypedAttribute)) and hasattr(value, "model_dump"): + value = value.model_dump(mode="json", by_alias=True) + + if properties := node.get("properties"): + if (frame := self._frame_from_attribute(properties, value, path, walk)) is not None: + # Carry on into the walk below rather than returning: the frame's object leaf + # has to face ``supported_schemas`` like any other. + value = frame + elif (frame := await self._frame_from_object(properties, value, path, walk)) is not None: + _graft(walk.resolved, path, frame) + return frame + if isinstance(value, dict): + # Register the container before descending so a child's ``attribute_from`` + # can read a sibling object that this same pass has already resolved. + resolved: dict[str, Any] = {} + _graft(walk.resolved, path, resolved) + for key, child in value.items(): + child_node = _deref(properties.get(key, {}), walk.schema) + resolved[key] = await self._resolve_node(child_node, child, [*path, key], walk) + return resolved + + if node.get("type") == "array" and isinstance(value, list): + items = _deref(node.get("items", {}), walk.schema) + return [ + await self._resolve_node(items, item, [*path, str(index)], walk) for index, item in enumerate(value) + ] + + return value + + # -- leaves ------------------------------------------------------------ # + + async def _resolve_object(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> str: + """A ``reference_to: geoscience-object`` leaf: any object handle in, its URL out.""" + reference = self._object_reference(value, path, walk) + # Remember what the caller already knew. An ``attribute_from`` pointer reads the + # resolved URL back, and should not pay for a download to learn what the object in + # hand had already said. + if (metadata := _metadata_of(value)) is not None: + self._schemas[reference] = metadata.schema_id + + supported = node.get("supported_schemas") + if not walk.check_schemas or not supported: + return reference + + schema = await self._object_schema(value, reference) + if schema is None: + logger.warning( + "%s: could not load %s to check it against supported_schemas %s; " + "submitting unchecked -- the platform will validate it.", + _describe(path, walk), + reference, + supported, + ) + elif not any(_schema_matches(schema, pattern) for pattern in supported): + raise _invalid(path, walk, f"object schema {str(schema)!r} is not one of {supported}") + return reference + + async def _resolve_attribute(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> Any: + """A ``reference_to: attribute`` leaf: a typed attribute or a name in, JMESPath out.""" + if isinstance(value, AnyTypedAttribute): + try: + return _get_attribute_expression(value) + except ValueError as error: + raise _invalid(path, walk, str(error)) from None + if not isinstance(value, str): + # Nothing downstream would catch this: an attribute reference is a string on the + # wire, and deep validation relaxes reference leaves. + raise _invalid(path, walk, f"expected an attribute name or expression, got {type(value).__name__}") + if _PROJECTION in value: + return value # already an expression + container = await self._attribute_container(node, path, walk) + return f"{container}[?name=='{value}']" + + async def _resolve_target_attribute(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> Any: + """A ``target: attribute`` slot: which attribute to create, or which one to update.""" + if isinstance(value, AnyTypedAttribute): + # The slot names the attribute only; the object it belongs to is its sibling. + # Mirrors ``source_target._validate_target_attribute`` for that half alone. + if value.exists: + return {"operation": "update", "reference": _get_attribute_expression(value)} + return {"operation": "create", "name": value.name} + if isinstance(value, str): + return {"operation": "create", "name": value} + if hasattr(value, "model_dump"): # a Source/Target-style model built by the caller + value = value.model_dump(mode="json", by_alias=True) + if isinstance(value, dict) and (branch := _select_branch(node, value, "operation", walk.schema)) is not None: + return await self._resolve_node(branch, value, path, walk) + return value + + # -- object identity --------------------------------------------------- # + + def _object_reference(self, value: Any, path: list[str], walk: _Walk) -> str: + """The URL for an object handle: a UUID is expanded, everything else is delegated.""" + if (object_id := _as_uuid(value)) is not None: + return str(ObjectReference.new(self._context.get_environment(), object_id=object_id)) + try: + return _convert_object_reference(value) + except (TypeError, ValueError) as error: + raise _invalid(path, walk, str(error)) from None + + async def _object_schema(self, value: Any, reference: str | None = None) -> ObjectSchema | None: + """The schema of a referenced object, from metadata in hand or a metadata download. + + Returns ``None`` when the object cannot be loaded, which callers treat as "unknown" + rather than as a failure. Both the answer and a failure to get one are cached, so a + repeated reference costs at most one request. + """ + if (metadata := _metadata_of(value)) is not None: + return metadata.schema_id + if reference is None: + if (object_id := _as_uuid(value)) is not None: + reference = str(ObjectReference.new(self._context.get_environment(), object_id=object_id)) + elif isinstance(value, str): + reference = value + else: + return None + if reference in self._schemas: + return self._schemas[reference] + + try: + downloaded = await DownloadedObject.from_context(self._context, reference) + except Exception as error: + # Deliberately broad: any reason the object cannot be read -- a cross-hub + # reference, a permissions gap, an outage -- leaves its schema unknown, which + # the caller downgrades to a warning rather than a refusal to submit. + logger.debug("could not load %s: %s", reference, error) + schema = None + else: + schema = downloaded.metadata.schema_id + self._schemas[reference] = schema + return schema + + # -- attribute placement ----------------------------------------------- # + + async def _attribute_container(self, node: dict[str, Any], path: list[str], walk: _Walk) -> str: + """The JMESPath container an attribute name sits in, chosen by its object's family. + + A pointset keeps attributes under ``locations.attributes`` and a block model under + ``attributes``, so the container is only knowable once the owning object -- named by + ``attribute_from`` -- is known. ``attributes`` is the fallback when the schema says + nothing or the object cannot be identified. + """ + containers = node.get("attribute_path") + pointer = node.get("attribute_from") + if not containers or not pointer: + return "attributes" + owner = _pointer_value(pointer, path, walk.resolved, walk.supplied) + if owner is None or (schema := await self._object_schema(owner)) is None: + return "attributes" + if (container := _container_for(containers, schema)) is None: + return "attributes" + return container + + def _frame_from_attribute( + self, properties: dict[str, Any], value: Any, path: list[str], walk: _Walk + ) -> dict[str, Any] | None: + """Expand a bare typed attribute into the ``{object, attribute}`` frame it implies. + + ``run(source=pointset.attributes["grade"])`` is how the typed tasks are called; the + attribute already knows the object it belongs to, so an ``{object, attribute}`` + parameter can be filled from it alone. The frame is handed back unwalked so its object + leaf goes through the ordinary path. Returns ``None`` when this is not that case. + """ + if isinstance(value, dict) or not isinstance(value, AnyTypedAttribute): + return None + if not {"object", "attribute"} <= properties.keys(): + return None + target = _deref(properties["attribute"], walk.schema).get("target") == "attribute" + try: + model = _validate_target_attribute(value) if target else _source_from_attribute(value) + except ValueError as error: + raise _invalid(path, walk, str(error)) from None + + frame: dict[str, Any] = model.model_dump(mode="json", by_alias=True) + # The object came with the attribute, so its schema is already in hand; seed the cache + # so the leaf can be held to ``supported_schemas`` without paying for a download. + if (metadata := _metadata_of(value._obj)) is not None: + self._schemas[frame["object"]] = metadata.schema_id + return frame + + async def _frame_from_object( + self, properties: dict[str, Any], value: Any, path: list[str], walk: _Walk + ) -> dict[str, Any] | None: + """Expand a bare object into the one-key frame a parameter wraps it in. + + Some parameters are an object and nothing else -- declustering's ``grid``, for one -- + and the typed tasks let the object be passed straight in rather than spelled out as + ``{"object": ...}``. Returns ``None`` when this node is not such a frame. + """ + if isinstance(value, dict) or not isinstance(value, _OBJECT_HANDLE) or len(properties) != 1: + return None + ((name, leaf),) = properties.items() + if _deref(leaf, walk.schema).get("reference_to") != "geoscience-object": + return None + return {name: await self._resolve_node(leaf, value, [*path, name], walk)} + + +# --------------------------------------------------------------------------- # +# Schema helpers. +# --------------------------------------------------------------------------- # + + +def _sole_non_null_branch(node: dict[str, Any]) -> dict[str, Any] | None: + """The one real branch of an optional wrapper such as ``anyOf: [X, {"type": "null"}]``. + + The catalogue inlines an optional sub-object and adds ``null`` to its ``type``, but the + same schema is just as often written as a union with a null branch. Left uncollapsed, + the node carries no ``properties`` of its own and the walk returns everything below it + untouched -- a typed attribute inside an optional filter would reach the wire as an + object. A tagged union has more than one real branch and is left for the discriminator. + """ + branches = node.get("anyOf") or node.get("oneOf") + if not isinstance(branches, list): + return None + real = [branch for branch in branches if isinstance(branch, dict) and branch.get("type") != "null"] + return real[0] if len(real) == 1 and len(real) < len(branches) else None + + +def _deref(node: Any, root: dict[str, Any]) -> dict[str, Any]: + """Resolve a local ``$ref`` and collapse an optional wrapper, keeping annotations alongside.""" + if not isinstance(node, dict): + return {} + if (branch := _sole_non_null_branch(node)) is not None: + node = {**{key: value for key, value in node.items() if key not in ("anyOf", "oneOf")}, **branch} + reference = node.get("$ref") + if not isinstance(reference, str) or not reference.startswith("#/"): + return node + target: Any = root + for part in reference[2:].split("/"): + if not isinstance(target, dict) or part not in target: + return node + target = target[part] + if not isinstance(target, dict): + return node + return {**target, **{key: value for key, value in node.items() if key != "$ref"}} + + +def _discriminator_of(node: dict[str, Any]) -> str | None: + """The property a tagged union is keyed on, or ``None`` if this node is not one.""" + if not node.get("oneOf") and not node.get("anyOf"): + return None + discriminator = node.get("discriminator") + if isinstance(discriminator, dict): + discriminator = discriminator.get("propertyName") + return discriminator if isinstance(discriminator, str) else None + + +def _select_branch(node: dict[str, Any], value: Any, key: str, root: dict[str, Any]) -> dict[str, Any] | None: + """The ``oneOf``/``anyOf`` branch whose ``key`` constant matches ``value[key]``.""" + if not isinstance(value, dict) or key not in value: + return None + for branch in node.get("oneOf") or node.get("anyOf") or []: + resolved = _deref(branch, root) + if resolved.get("properties", {}).get(key, {}).get("const") == value[key]: + return resolved + return None + + +def _schema_matches(schema: ObjectSchema, pattern: str) -> bool: + """Whether an object schema satisfies a ``supported_schemas``/``attribute_path`` pattern. + + Patterns name an object family and an optional version range, ``pointset/[>=1.2,<2]``. + An unparseable bound is treated as satisfied: the family is the part that decides which + container an attribute lives in, and over-rejecting a legitimate object is the worse + failure. + """ + family, _, bounds = pattern.partition("/") + if schema.sub_classification != family: + return False + return all(_version_satisfies(schema.version, bound) for bound in bounds.strip("[]").split(",") if bound.strip()) + + +def _version_satisfies(version: SchemaVersion, bound: str) -> bool: + match = _BOUND.fullmatch(bound.strip()) + if match is None: + return True + expected = tuple(int(part) for part in match.group("version").split(".")) + # Compare only as precisely as the bound is written, so ``<2`` admits ``1.9.9``. + actual = (version.major, version.minor, version.patch)[: len(expected)] + return _COMPARISONS[match.group("op") or ">="](actual, expected) + + +def _container_of(template: str) -> str: + """The container an ``attribute_path`` template selects within. + + ``locations.attributes[?attribute_type=='scalar']`` -> ``locations.attributes``. The + predicate narrows by attribute type, which a lookup by name does not need. + """ + index = template.find("[") + return template[:index] if index != -1 else template + + +def _container_for(containers: Any, schema: ObjectSchema) -> str | None: + """The ``attribute_path`` container an object of this schema keeps its attributes in. + + ``None`` when the map says nothing about the object's family, which leaves the caller to + decide whether to guess or to leave a reference alone. + """ + if not isinstance(containers, dict): + return None + for pattern, templates in containers.items(): + if _schema_matches(schema, pattern): + return _container_of(templates[0] if isinstance(templates, list) else templates) + return None + + +# --------------------------------------------------------------------------- # +# Value helpers. +# --------------------------------------------------------------------------- # + + +def _as_uuid(value: Any) -> UUID | None: + """``value`` as a bare object id, or ``None`` if it is not one.""" + if isinstance(value, UUID): + return value + if isinstance(value, str) and not value.startswith("http"): + try: + return UUID(value) + except ValueError: + return None + return None + + +def _metadata_of(value: Any) -> ObjectMetadata | None: + """The metadata a caller-supplied object already carries, if it is one.""" + if isinstance(value, ObjectMetadata): + return value + if isinstance(value, (BaseObject, DownloadedObject)): + return value.metadata + return None + + +def _resolve_file(value: Any, path: list[str], walk: _Walk) -> str: + """A ``reference_to: file`` leaf: a File API URL, or a handle that carries one. + + The reference is held to a File API shape because nothing downstream would: deep + validation relaxes reference leaves, so a local filename would otherwise be submitted as + if it were a URL. Building a URL from a local path, and uploading local bytes, are + deferred until the import/converter tasks that need them are supported. + """ + if isinstance(value, str): + reference = value + else: + url = getattr(value, "url", None) + if url is None: + url = getattr(getattr(value, "metadata", None), "url", None) + if url is None: + raise _invalid(path, walk, f"cannot resolve a file reference from {type(value).__name__}") + reference = str(url) + if _FILE_REFERENCE.match(reference) is None: + raise _invalid(path, walk, f"expected a File API URL, got {reference!r}") + return reference + + +def _pointer_value(pointer: str, path: list[str], *roots: dict[str, Any]) -> Any: + """Follow an ``attribute_from`` pointer to the object the attribute belongs to. + + Absolute (``/target/object``) indexes from the payload root. Relative (``1/object``) + climbs at least that many levels from the attribute's own position -- at least, because + the platform writes the same pointer whether the attribute sits directly under a frame + or deeper inside that frame's filter, so the nearest enclosing frame that owns the named + object is the intended one. ``roots`` are consulted in order, so a resolution pass can + prefer the payload it has already resolved and fall back to the caller's original values + for pointers the walk has not reached yet. + """ + if pointer.startswith("/"): + return _index([segment for segment in pointer.split("/") if segment], roots) + + head, _, rest = pointer.partition("/") + try: + climb = max(int(head), 1) + except ValueError: + return None + tail = [segment for segment in rest.split("/") if segment] + for levels in range(climb, len(path) + 1): + if (value := _index(path[:-levels] + tail, roots)) is not None: + return value + return None + + +def _index(segments: list[str], roots: tuple[dict[str, Any], ...]) -> Any: + for root in roots: + current: Any = root + for segment in segments: + if not isinstance(current, dict) or segment not in current: + current = None + break + current = current[segment] + if current is not None: + return current + return None + + +def _graft(root: dict[str, Any], path: list[str], container: dict[str, Any]) -> None: + """Attach ``container`` at ``path``, so pointers can read it before it is filled in.""" + current = root + for segment in path[:-1]: + nested = current.get(segment) + if not isinstance(nested, dict): + nested = {} + current[segment] = nested + current = nested + if path: + current[path[-1]] = container + + +def _describe(path: list[str], walk: _Walk) -> str: + return f"{walk.label}.run(): {'.'.join(path)}" + + +def _invalid(path: list[str], walk: _Walk, message: str) -> ParameterValidationError: + location = ".".join(path) + detail = f"{location}: {message}" + return ParameterValidationError(f"{walk.label}.run(): {detail}", task=walk.label, errors=[detail]) diff --git a/packages/evo-compute/src/evo/compute/validation.py b/packages/evo-compute/src/evo/compute/validation.py index 84e115bb4..1a3a50368 100644 --- a/packages/evo-compute/src/evo/compute/validation.py +++ b/packages/evo-compute/src/evo/compute/validation.py @@ -207,6 +207,12 @@ def _iter_schema_nodes(node: Any) -> Iterator[dict[str, Any]]: def unknown_annotation_keys(schema: dict[str, Any] | None) -> set[str]: """Return schema keys that are neither standard JSON Schema nor a known annotation. + Two callers, for two audiences. :class:`~evo.compute.discovery.DiscoveryClient` calls it + on every fetched catalogue and *warns*, so a caller on an SDK that predates an annotation + the platform now publishes learns that the schema is only partly interpreted rather than + being blocked by it. The conformance test calls it on bundled schemas and *fails*, so the + same drift stops a release rather than reaching users as a warning. + :param schema: A task ``parameters`` or ``results`` JSON Schema (or ``None``). :return: The set of unrecognised annotation keys; empty when the schema only uses diff --git a/packages/evo-compute/tests/data/discovery-resolution.json b/packages/evo-compute/tests/data/discovery-resolution.json new file mode 100644 index 000000000..3b1f3f1a5 --- /dev/null +++ b/packages/evo-compute/tests/data/discovery-resolution.json @@ -0,0 +1,258 @@ +{ + "limit": 100, + "offset": 0, + "total": 2, + "count": 2, + "results": [ + { + "key": "demo/estimate", + "topic": "demo", + "name": "estimate", + "display_name": "Estimate", + "version": "1.0.0", + "description": "A task shaped like the catalogue's real estimation tasks: nested source/target frames, a recursive filter union behind $ref, and a create-or-update attribute slot.", + "parameters": { + "type": "object", + "additionalProperties": false, + "$defs": { + "FilterCondition": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": {"const": "condition"}, + "operator": {"type": "string", "enum": ["equal", "greater_than"]}, + "threshold": {"type": ["number", "null"], "default": null}, + "attribute": { + "type": "string", + "reference_to": "attribute", + "attribute_from": "/source/object", + "attribute_path": { + "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='category']"], + "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Utf8']"] + } + } + }, + "required": ["type", "operator", "attribute"] + }, + "AllOfFilter": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": {"const": "all_of"}, + "filters": {"type": "array", "items": {"$ref": "#/$defs/FilterExpression"}} + }, + "required": ["type", "filters"] + }, + "FilterExpression": { + "discriminator": "type", + "oneOf": [{"$ref": "#/$defs/FilterCondition"}, {"$ref": "#/$defs/AllOfFilter"}] + }, + "Filter": { + "type": "object", + "additionalProperties": false, + "properties": { + "where": {"$ref": "#/$defs/FilterExpression"} + }, + "required": ["where"] + } + }, + "properties": { + "source": { + "type": "object", + "additionalProperties": false, + "properties": { + "object": { + "type": "string", + "format": "uri", + "reference_to": "geoscience-object", + "supported_schemas": ["pointset/[>=1.2,<2]", "block-model/[>=1.0,<2]"] + }, + "attribute": { + "type": "string", + "reference_to": "attribute", + "attribute_from": "1/object", + "attribute_path": { + "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='scalar']"], + "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Float64']"] + } + }, + "filter": { + "type": "object", + "additionalProperties": false, + "composite": "filter", + "default": null, + "properties": { + "where": {"$ref": "#/$defs/FilterExpression"} + } + } + }, + "required": ["object", "attribute"] + }, + "target": { + "type": "object", + "additionalProperties": false, + "properties": { + "object": { + "type": "string", + "format": "uri", + "reference_to": "geoscience-object", + "supported_schemas": ["pointset/[>=1.2,<2]", "block-model/[>=1.0,<2]"] + }, + "attribute": { + "target": "attribute", + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "operation": {"const": "create"}, + "name": {"type": "string"} + }, + "required": ["operation", "name"] + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "operation": {"const": "update"}, + "reference": { + "type": "string", + "reference_to": "attribute", + "attribute_from": "2/object", + "attribute_path": { + "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='scalar']"], + "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Float64']"] + } + } + }, + "required": ["operation", "reference"] + } + ] + }, + "filter": { + "default": null, + "composite": "filter", + "anyOf": [{"$ref": "#/$defs/Filter"}, {"type": "null"}] + } + }, + "required": ["object", "attribute"] + }, + "report": { + "type": ["string", "null"], + "reference_to": "file", + "default": null + }, + "seeds": { + "type": "array", + "items": {"type": "integer"}, + "default": null + }, + "grid": { + "type": "object", + "additionalProperties": false, + "default": null, + "properties": { + "object": { + "type": "string", + "format": "uri", + "reference_to": "geoscience-object" + } + }, + "required": ["object"] + }, + "discretisation": { + "default": null, + "anyOf": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "nx": {"type": "integer"}, + "ny": {"type": "integer"}, + "nz": {"type": "integer"} + } + }, + {"type": "null"} + ] + }, + "options": { + "type": "object", + "additionalProperties": false, + "default": null, + "properties": { + "label": {"type": "string"}, + "retries": {"type": "integer"} + } + } + }, + "required": ["source", "target"] + }, + "results": { + "type": "object", + "properties": { + "message": {"type": "string"}, + "target": { + "type": "object", + "output": "geoscience-object", + "properties": { + "reference": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, + "name": {"type": "string"}, + "description": {"type": ["string", "null"]}, + "schema_id": {"type": "string"}, + "attribute": { + "type": "object", + "output": "attribute", + "properties": { + "reference": { + "type": "string", + "reference_to": "attribute", + "attribute_from": "2/reference", + "attribute_path": { + "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='scalar']"], + "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Float64']"] + } + }, + "name": {"type": "string"} + } + } + } + }, + "extras": { + "type": ["array", "null"], + "items": { + "type": "object", + "output": "geoscience-object", + "properties": { + "reference": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, + "name": {"type": "string"} + } + } + }, + "report": { + "type": ["object", "null"], + "output": "file", + "properties": { + "reference": {"type": "string", "reference_to": "file"}, + "name": {"type": "string"} + } + } + } + } + }, + { + "key": "demo/import", + "topic": "demo", + "name": "import", + "display_name": "Import", + "version": "1.0.0", + "description": "A task whose only input is a file reference.", + "parameters": { + "type": "object", + "properties": { + "file": {"type": "string", "reference_to": "file"} + }, + "required": ["file"] + } + } + ] +} diff --git a/packages/evo-compute/tests/data/discovery-tasks.json b/packages/evo-compute/tests/data/discovery-tasks.json index 5c7d0c720..09529dc23 100644 --- a/packages/evo-compute/tests/data/discovery-tasks.json +++ b/packages/evo-compute/tests/data/discovery-tasks.json @@ -14,9 +14,10 @@ "parameters": { "type": "object", "properties": { - "source": {"type": "object", "reference_to": "geoscience-object"}, + "source": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, "power": {"type": ["number", "null"], "default": null}, "method": {"type": "string", "enum": ["cell", "polygon"], "default": "cell"}, + "settings": {"type": "object"}, "options": {"default": null} }, "required": ["source"] @@ -24,7 +25,24 @@ "results": { "type": "object", "properties": { - "target": {"type": "object", "output": "geoscience-object"} + "message": {"type": "string"}, + "target": { + "type": "object", + "output": "geoscience-object", + "properties": { + "reference": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, + "name": {"type": "string"}, + "schema_id": {"type": "string"}, + "attribute": { + "type": "object", + "output": "attribute", + "properties": { + "reference": {"type": "string", "reference_to": "attribute"}, + "name": {"type": "string"} + } + } + } + } } } }, @@ -38,7 +56,7 @@ "parameters": { "type": "object", "properties": { - "distribution": {"type": "object", "reference_to": "geoscience-object"} + "distribution": {"type": "string", "format": "uri", "reference_to": "geoscience-object"} }, "required": ["distribution"] } @@ -54,9 +72,9 @@ "parameters": { "type": "object", "properties": { - "source": {"type": "object", "reference_to": "geoscience-object"}, - "target": {"type": "object", "reference_to": "geoscience-object"}, - "variogram": {"type": "object", "reference_to": "geoscience-object"} + "source": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, + "target": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, + "variogram": {"type": "string", "format": "uri", "reference_to": "geoscience-object"} }, "required": ["source", "target", "variogram"] } diff --git a/packages/evo-compute/tests/data/discovery-validation.json b/packages/evo-compute/tests/data/discovery-validation.json index 8143c156d..14c48e35b 100644 --- a/packages/evo-compute/tests/data/discovery-validation.json +++ b/packages/evo-compute/tests/data/discovery-validation.json @@ -14,7 +14,7 @@ "parameters": { "type": "object", "properties": { - "source": {"type": "object", "reference_to": "geoscience-object"}, + "source": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}, "mode": {"type": "string", "enum": ["fast", "accurate"]}, "iterations": {"type": "integer", "minimum": 1, "default": null} }, diff --git a/packages/evo-compute/tests/test_behavior_parity.py b/packages/evo-compute/tests/test_behavior_parity.py new file mode 100644 index 000000000..dcae4a5eb --- /dev/null +++ b/packages/evo-compute/tests/test_behavior_parity.py @@ -0,0 +1,535 @@ +# Copyright © 2026 Bentley Systems, Incorporated +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Behavior parity between the hand-written task runners and the generic engine. + +The companion suite in :mod:`test_payload_parity` shows the two paths agree on what they +send. This one shows they agree on what they refuse to send. Each case declares one set of +*invalid* inputs, hands that same set to a typed runner and to the discovery-driven engine, +and requires that neither reaches ``JobClient.submit`` and that both raise a comparable +error. + +This suite states the contract it holds the engine to: + +* Neither path submits a job. A job that the platform will reject is worse than a local + error, so this is the part that actually matters and it is asserted on every case. +* Both raise a :class:`ValueError` -- pydantic's ``ValidationError`` on the runner side, the + SDK's own :class:`~evo.compute.exceptions.ParameterValidationError` on the engine side. +* Both name the parameter at fault, so a caller can act on either message. + +What is deliberately *not* promised is identical text or identical precision. A parameter +model knows the branch a caller meant and can fault the field inside it; a JSON Schema +``anyOf`` with no discriminator does not, so the engine reports the parameter and leaves the +branch open. ``test_an_unknown_kriging_method`` pins both messages side by side rather than +asserting a likeness that does not exist. + +**Value checks are opt-in.** The engine only reproduces the runner's value-level refusals +under ``deep_validation=True``, which is what these tests use and what a caller who wants +this behavior has to ask for. Left off -- the default -- the engine still refuses a missing +parameter, an unknown one, and a reference it cannot resolve, but a value the schema +disallows is sent for the platform to reject. ``TestWhereTheTwoPathsDiffer`` pins that +boundary explicitly. + +Every task class opens with a case proving its *valid* inputs are accepted by both paths. +Without it a broken fixture would refuse everything and the whole suite would pass for the +wrong reason. + +The harness is shared with :mod:`test_payload_parity`: same mocked catalogue derived from +each runner's own parameter model, same fake context, so the two suites cannot drift into +testing different engines. As there, that makes this a test of the two code paths against +each other rather than of either against the live catalogue -- the constraints exercised here +are the ones the runners' own models publish. One of them publishes nothing: +``SearchNeighborhood`` hand-writes its own wire form, so the fixture can only advertise it as +an opaque object and the two paths go uncompared inside ``neighborhood``, the most-shared +nested parameter here. ``TestWhereTheTwoPathsDiffer`` asserts that gap rather than let the +silence read as agreement. +""" + +from __future__ import annotations + +import re +from collections.abc import Iterator +from contextlib import contextmanager +from typing import Any +from unittest import IsolatedAsyncioTestCase, mock + +from pydantic import ValidationError + +from evo.compute import ComputeClient, DiscoveryClient, ParameterValidationError +from evo.compute.tasks import CreateAttribute, Source, Target +from evo.compute.tasks.geostatistics.conditioned_simulator import ConSimRunner +from evo.compute.tasks.geostatistics.declustering import DeclusteringGrid, DeclusteringRunner, DeclusteringSource +from evo.compute.tasks.geostatistics.kriging import KrigingMethod, KrigingRunner +from evo.compute.tasks.geostatistics.location_wise import LocationWiseRunner, LocationWiseTarget +from test_payload_parity import ( + GRADE_ATTRIBUTE, + GRID_URL, + POINTSET_URL, + SIMULATIONS_ATTRIBUTE, + TARGET_URL, + VARIOGRAM_URL, + FakeContext, + _capture_submit, + _search, + _SubmitCaptured, + task_spec, +) + +#: Where ``JobClient`` is looked up on each path, so submission can be captured there. +RUNNER_MODULE = "evo.compute.tasks.common.runner" +ENGINE_MODULE = "evo.compute.engine" + + +# --------------------------------------------------------------------------- # +# Harness +# --------------------------------------------------------------------------- # + + +class BehaviorParityTestCase(IsolatedAsyncioTestCase): + """Runs one set of inputs through both paths and compares how each refuses it.""" + + def setUp(self) -> None: + super().setUp() + self.context = FakeContext() + # Deep validation is what makes the engine as strict about values as a parameter + # model is. See TestWhereTheTwoPathsDiffer for what the default does without it. + self.client = ComputeClient(self.context, deep_validation=True) + + # -- running one path -------------------------------------------------- # + + @contextmanager + def engine(self, **options: Any) -> Iterator[None]: + """Point the engine calls inside at a client configured differently from the fixture's.""" + previous, self.client = self.client, ComputeClient(self.context, **options) + try: + yield + finally: + self.client = previous + + async def _attempt(self, module: str, call) -> tuple[mock.AsyncMock, Exception | None]: + """Run ``call`` with submission captured: what ``submit`` saw, and what was raised. + + Only the two error types the contract admits are caught, so a bug in this harness -- + an ``AttributeError`` out of a malformed fixture, say -- fails the test rather than + passing for a refusal that never happened. + """ + raised: Exception | None = None + with _capture_submit(module) as submit: + try: + await call() + except _SubmitCaptured: + pass # the payload is recorded; this path accepted the inputs + except (ValueError, TypeError) as error: # which of the two it is, is the question under test + raised = error + return submit, raised + + def _runner_call(self, runner_cls, inputs: dict[str, Any]): + # Built inside the call so that a model the inputs cannot even construct is a refusal + # by the runner, which is where a caller would meet it, rather than a test error. + return lambda: runner_cls(self.context, runner_cls.params_type(**inputs)) + + def _engine_call(self, runner_cls, inputs: dict[str, Any]): + task = getattr(self.client.geostatistics, runner_cls.task.replace("-", "_")) + return lambda: task.run(**inputs) + + def _catalogue(self, runner_cls): + """Serve the engine the task's schema, derived from the runner's own parameter model.""" + return mock.patch.object(DiscoveryClient, "list_tasks", mock.AsyncMock(return_value=[task_spec(runner_cls)])) + + async def runner_refusal(self, runner_cls, **inputs: Any) -> Exception: + """The error the hand-written runner raises for ``inputs``, having submitted nothing.""" + submit, error = await self._attempt(RUNNER_MODULE, self._runner_call(runner_cls, inputs)) + return self._refused("runner", submit, error) + + async def engine_refusal(self, runner_cls, **inputs: Any) -> Exception: + """The error the generic engine raises for the same inputs, having submitted nothing.""" + with self._catalogue(runner_cls): + submit, error = await self._attempt(ENGINE_MODULE, self._engine_call(runner_cls, inputs)) + return self._refused("engine", submit, error) + + def _refused(self, path: str, submit: mock.AsyncMock, error: Exception | None) -> Exception: + self.assertEqual(0, submit.await_count, f"the {path} submitted a job for parameters it should have refused") + if error is None: + self.fail(f"the {path} accepted parameters it should have refused") + return error + + # -- comparing the two ------------------------------------------------- # + + async def assertBothRefuse(self, runner_cls, parameter: str, **inputs: Any) -> tuple[Exception, Exception]: + """Require both paths to refuse ``inputs`` locally, blaming ``parameter``. + + Returns both errors so a case that wants to say more about them can. + """ + runner_error = await self.runner_refusal(runner_cls, **inputs) + engine_error = await self.engine_refusal(runner_cls, **inputs) + self.assertIsInstance(runner_error, ValueError, f"the runner raised {type(runner_error).__name__}") + self.assertIsInstance(engine_error, ParameterValidationError) + for path, error in (("runner", runner_error), ("engine", engine_error)): + self.assertBlames(path, error, parameter) + return runner_error, engine_error + + def assertBlames(self, path: str, error: Exception, parameter: str) -> None: + """Require ``error`` to name ``parameter`` as a whole word, not as part of another name. + + A plain substring would let a case pass on an error about a different parameter: + ``source`` is inside ``source_filter``, ``variogram`` inside ``variogram_model``. + """ + self.assertRegex( + str(error), rf"\b{re.escape(parameter)}\b", f"the {path}'s message does not name {parameter!r}" + ) + + async def assertBothAccept(self, runner_cls, **inputs: Any) -> None: + """Require both paths to get as far as submitting, which is what makes a refusal mean something.""" + await self.assertRunnerAccepts(runner_cls, **inputs) + await self.assertEngineAccepts(runner_cls, **inputs) + + async def assertRunnerAccepts(self, runner_cls, **inputs: Any) -> dict[str, Any]: + """Require the runner to submit, and return the payload it submitted.""" + submit, error = await self._attempt(RUNNER_MODULE, self._runner_call(runner_cls, inputs)) + self.assertEqual(1, submit.await_count, f"the runner refused parameters it should have accepted: {error}") + return submit.await_args.kwargs["parameters"] + + async def assertEngineAccepts(self, runner_cls, **inputs: Any) -> dict[str, Any]: + """Require the engine to submit, and return the payload it submitted.""" + with self._catalogue(runner_cls): + submit, error = await self._attempt(ENGINE_MODULE, self._engine_call(runner_cls, inputs)) + self.assertEqual(1, submit.await_count, f"the engine refused parameters it should have accepted: {error}") + return submit.await_args.kwargs["parameters"] + + +# --------------------------------------------------------------------------- # +# Valid baselines, one per task +# --------------------------------------------------------------------------- # + + +def declustering_inputs(**overrides: Any) -> dict[str, Any]: + inputs: dict[str, Any] = dict( + source=DeclusteringSource(object=POINTSET_URL), + grid=DeclusteringGrid(object=GRID_URL), + target=Target(object=TARGET_URL, attribute=CreateAttribute(name="weights")), + neighborhood=_search(), + power=2.5, + ) + inputs.update(overrides) + return inputs + + +def kriging_inputs(**overrides: Any) -> dict[str, Any]: + # Keyed by wire name: ``KrigingParameters`` populates by alias, so one set of inputs + # serves both paths without restating anything. + inputs: dict[str, Any] = dict( + source=Source(object=POINTSET_URL, attribute=GRADE_ATTRIBUTE), + target=Target(object=TARGET_URL, attribute=CreateAttribute(name="kriged_grade")), + variogram=VARIOGRAM_URL, + neighborhood=_search(), + kriging_method=KrigingMethod.ORDINARY, + ) + inputs.update(overrides) + return inputs + + +def consim_inputs(**overrides: Any) -> dict[str, Any]: + inputs: dict[str, Any] = dict( + source_object=POINTSET_URL, + source_attribute=GRADE_ATTRIBUTE, + target_object=GRID_URL, + neighborhood=_search(), + variogram_model=VARIOGRAM_URL, + ) + inputs.update(overrides) + return inputs + + +def location_wise_inputs(**overrides: Any) -> dict[str, Any]: + inputs: dict[str, Any] = dict( + source=Source(object=POINTSET_URL, attribute=SIMULATIONS_ATTRIBUTE), + target=LocationWiseTarget(object=GRID_URL), + summary=True, + ) + inputs.update(overrides) + return inputs + + +# --------------------------------------------------------------------------- # +# Declustering +# --------------------------------------------------------------------------- # + + +class TestDeclusteringBehaviorParity(BehaviorParityTestCase): + async def test_valid_parameters_are_accepted_by_both(self) -> None: + """The guard for everything below: this baseline is a job both paths would run.""" + await self.assertBothAccept(DeclusteringRunner, **declustering_inputs()) + + async def test_a_missing_required_parameter(self) -> None: + """Caught as the call is bound to the schema's signature, so this refusal needs no validation.""" + inputs = declustering_inputs() + del inputs["grid"] + await self.assertBothRefuse(DeclusteringRunner, "grid", **inputs) + + async def test_a_power_below_the_allowed_range(self) -> None: + """``power`` must be positive, and the bound is published in the schema as well as the model.""" + await self.assertBothRefuse(DeclusteringRunner, "power", **declustering_inputs(power=-1.0)) + + async def test_a_power_that_is_not_a_number(self) -> None: + """Neither path lets a word through where a number belongs.""" + await self.assertBothRefuse(DeclusteringRunner, "power", **declustering_inputs(power="strong")) + + async def test_a_create_target_without_a_name(self) -> None: + """A nested field is as required as a top-level one, and both paths say which one it is.""" + target = {"object": TARGET_URL, "attribute": {"operation": "create"}} + await self.assertBothRefuse(DeclusteringRunner, "target", **declustering_inputs(target=target)) + + async def test_an_object_reference_that_is_not_a_url(self) -> None: + """The reference is checked as it is converted, so this one does not need deep validation.""" + runner_error, engine_error = await self.assertBothRefuse( + DeclusteringRunner, "source", **declustering_inputs(source="not-a-url") + ) + for error in (runner_error, engine_error): + self.assertIn("Reference must be a valid HTTPS URL", str(error)) + + +# --------------------------------------------------------------------------- # +# Kriging +# --------------------------------------------------------------------------- # + + +class TestKrigingBehaviorParity(BehaviorParityTestCase): + async def test_valid_parameters_are_accepted_by_both(self) -> None: + await self.assertBothAccept(KrigingRunner, **kriging_inputs()) + + async def test_a_missing_required_parameter(self) -> None: + inputs = kriging_inputs() + del inputs["variogram"] + await self.assertBothRefuse(KrigingRunner, "variogram", **inputs) + + async def test_a_required_parameter_explicitly_set_to_none(self) -> None: + """Supplying ``None`` is not the same as leaving a parameter out, and neither path accepts it.""" + await self.assertBothRefuse(KrigingRunner, "source", **kriging_inputs(source=None)) + + async def test_an_unknown_kriging_method(self) -> None: + """Both refuse an unknown method, but only the model can say which branch was meant. + + ``method`` is an untagged union in the model, so the schema derived from it is an + ``anyOf`` with no discriminator. Pydantic reports every branch it tried; the engine + has no way to pick one, so it reports the parameter and stops there. This is the + precision the engine does not promise, written out rather than glossed over. + """ + runner_error, engine_error = await self.assertBothRefuse( + KrigingRunner, "kriging_method", **kriging_inputs(kriging_method={"type": "magic"}) + ) + self.assertIn("kriging_method.SimpleKriging.type", str(runner_error)) + self.assertIn( + "kriging_method: {'type': 'magic'} is not valid under any of the given schemas", str(engine_error) + ) + + async def test_a_kriging_method_missing_its_own_field(self) -> None: + """Simple kriging needs a mean; a well-formed tag is not a well-formed method.""" + await self.assertBothRefuse( + KrigingRunner, "kriging_method", **kriging_inputs(kriging_method={"type": "simple"}) + ) + + async def test_a_block_discretization_outside_its_range(self) -> None: + """1 to 9 per axis, on both paths.""" + discretization = {"nx": 99, "ny": 3, "nz": 2} + await self.assertBothRefuse( + KrigingRunner, "block_discretization", **kriging_inputs(block_discretization=discretization) + ) + + async def test_an_attribute_that_is_not_a_name_or_expression(self) -> None: + """Reference leaves are relaxed for deep validation, so resolution is the only gate -- and it holds.""" + source = {"object": POINTSET_URL, "attribute": 12345} + _, engine_error = await self.assertBothRefuse(KrigingRunner, "source", **kriging_inputs(source=source)) + self.assertIn("source.attribute: expected an attribute name or expression, got int", str(engine_error)) + + async def test_a_variogram_that_is_not_an_object_url(self) -> None: + """A bare filename is not a geoscience object, however plausible it looks.""" + await self.assertBothRefuse(KrigingRunner, "variogram", **kriging_inputs(variogram="variogram.json")) + + +# --------------------------------------------------------------------------- # +# Conditional simulation (consim) +# --------------------------------------------------------------------------- # + + +class TestConSimBehaviorParity(BehaviorParityTestCase): + async def test_valid_parameters_are_accepted_by_both(self) -> None: + await self.assertBothAccept(ConSimRunner, **consim_inputs()) + + async def test_a_missing_required_parameter(self) -> None: + inputs = consim_inputs() + del inputs["variogram_model"] + await self.assertBothRefuse(ConSimRunner, "variogram_model", **inputs) + + async def test_more_simulations_than_the_task_allows(self) -> None: + runner_error, engine_error = await self.assertBothRefuse( + ConSimRunner, "number_of_simulations", **consim_inputs(number_of_simulations=500) + ) + self.assertIn("less than or equal to 100", str(runner_error)) + self.assertIn("500 is greater than the maximum of 100", str(engine_error)) + + async def test_fewer_lines_than_the_task_allows(self) -> None: + await self.assertBothRefuse(ConSimRunner, "number_of_lines", **consim_inputs(number_of_lines=0)) + + async def test_an_unknown_kriging_method(self) -> None: + """A closed set of strings is the one union shape the engine can be precise about.""" + _, engine_error = await self.assertBothRefuse( + ConSimRunner, "kriging_method", **consim_inputs(kriging_method="magic") + ) + self.assertIn("kriging_method: must be one of ['simple', 'ordinary'], got 'magic'", str(engine_error)) + + async def test_a_filter_with_an_unknown_operator(self) -> None: + """A filter is a parameter like any other, and its contents are checked like any other.""" + source_filter = { + "where": {"type": "condition", "attribute": GRADE_ATTRIBUTE, "operator": "roughly"}, + } + await self.assertBothRefuse(ConSimRunner, "source_filter", **consim_inputs(source_filter=source_filter)) + + async def test_a_discretization_outside_its_range(self) -> None: + """A sub-object that is not optional is descended into, so the engine names the axis too.""" + discretization = {"nx": 0, "ny": 1, "nz": 1} + _, engine_error = await self.assertBothRefuse( + ConSimRunner, "block_discretization", **consim_inputs(block_discretization=discretization) + ) + self.assertIn("block_discretization.nx: 0 is less than the minimum of 1", str(engine_error)) + + +# --------------------------------------------------------------------------- # +# Location-wise +# --------------------------------------------------------------------------- # + + +class TestLocationWiseBehaviorParity(BehaviorParityTestCase): + async def test_valid_parameters_are_accepted_by_both(self) -> None: + await self.assertBothAccept(LocationWiseRunner, **location_wise_inputs()) + + async def test_a_missing_required_parameter(self) -> None: + inputs = location_wise_inputs() + del inputs["target"] + await self.assertBothRefuse(LocationWiseRunner, "target", **inputs) + + async def test_an_empty_list_of_cutoffs(self) -> None: + """Asking for probabilities above no cutoffs at all is a mistake both paths catch.""" + await self.assertBothRefuse( + LocationWiseRunner, + "probability_above_cutoff", + **location_wise_inputs(probability_above_cutoff={"cutoffs": []}), + ) + + async def test_quantiles_that_are_not_a_list(self) -> None: + await self.assertBothRefuse(LocationWiseRunner, "quantiles", **location_wise_inputs(quantiles="all")) + + async def test_quantiles_that_are_not_numbers(self) -> None: + """A list of the right shape but the wrong contents is still refused.""" + await self.assertBothRefuse(LocationWiseRunner, "quantiles", **location_wise_inputs(quantiles=["low", "high"])) + + async def test_a_source_without_an_attribute(self) -> None: + await self.assertBothRefuse( + LocationWiseRunner, "source", **location_wise_inputs(source={"object": POINTSET_URL}) + ) + + +# --------------------------------------------------------------------------- # +# Where the two paths differ +# --------------------------------------------------------------------------- # + + +class TestWhereTheTwoPathsDiffer(BehaviorParityTestCase): + """The cases the contract above does not cover, asserted as they are rather than left implied.""" + + async def test_a_misspelled_parameter_reaches_the_platform_from_the_runner_only(self) -> None: + """DIVERGENCE, the engine is stricter: a parameter model ignores what it does not recognise. + + None of these models set ``extra="forbid"``, so a typo is dropped in silence and the + job runs with a default the caller did not intend. The engine binds the call to a + signature synthesised from the schema, so the same typo is a refusal -- and one that + does not depend on validation being switched on. + """ + misspelled = declustering_inputs(powr=2.5) + del misspelled["power"] + + payload = await self.assertRunnerAccepts(DeclusteringRunner, **misspelled) + self.assertNotIn("powr", payload) + self.assertEqual(2.0, payload["power"], "the runner should have fallen back to its own default") + + error = await self.engine_refusal(DeclusteringRunner, **misspelled) + self.assertIn("got an unexpected keyword argument 'powr'", str(error)) + + async def test_a_value_the_model_coerces_is_refused_by_the_engine(self) -> None: + """DIVERGENCE, the engine is stricter: pydantic reads ``"500"`` as ``500``; JSON Schema does not. + + The runner submits the number it parsed. The engine has no model to parse with, and + forwarding the string as it stands would fail at the platform, so it refuses instead. + """ + coerced = consim_inputs(number_of_lines="500") + await self.assertRunnerAccepts(ConSimRunner, **coerced) + error = await self.engine_refusal(ConSimRunner, **coerced) + self.assertIn("number_of_lines: expected type integer, got str", str(error)) + + async def test_an_unsupported_object_handle_is_refused_by_both_but_not_alike(self) -> None: + """DIVERGENCE, in the error type: the runner raises ``TypeError``, outside the contract. + + ``_convert_object_reference`` raises ``TypeError`` for a value that is no kind of + object handle, and pydantic re-wraps ``ValueError`` but not ``TypeError``, so it + surfaces raw rather than as a ``ValidationError``. The engine meets it later and + elsewhere: an int never looks like the object frame ``source`` declares, so it is + deep validation rather than resolution that stops it. Both refuse and neither + submits, so the part of the contract that matters holds; the ``except ValueError`` a + caller might write around either path does not. + """ + unsupported = declustering_inputs(source=12345) + runner_error = await self.runner_refusal(DeclusteringRunner, **unsupported) + engine_error = await self.engine_refusal(DeclusteringRunner, **unsupported) + self.assertIsInstance(runner_error, TypeError) + self.assertNotIsInstance(runner_error, ValidationError) + self.assertIn("Cannot convert object reference from type int", str(runner_error)) + self.assertIsInstance(engine_error, ParameterValidationError) + self.assertIn("source: expected type object, got int", str(engine_error)) + + async def test_value_checks_are_opt_in_on_the_engine(self) -> None: + """The clarified expectation: without ``deep_validation`` a bad value is the platform's to catch.""" + too_many = consim_inputs(number_of_simulations=500) + with self.engine(): # the default + await self.assertEngineAccepts(ConSimRunner, **too_many) + with self.engine(deep_validation=True): + await self.engine_refusal(ConSimRunner, **too_many) + + async def test_the_default_engine_still_refuses_the_mistakes_it_can_see(self) -> None: + """Deep validation buys value checks, not the whole of them: three refusals survive without it.""" + with self.engine(): # the default + missing = consim_inputs() + del missing["variogram_model"] + self.assertBlames("engine", await self.engine_refusal(ConSimRunner, **missing), "variogram_model") + + unknown = consim_inputs(number_of_liness=500) + self.assertBlames("engine", await self.engine_refusal(ConSimRunner, **unknown), "number_of_liness") + + unresolvable = consim_inputs(variogram_model="variogram.json") + self.assertBlames("engine", await self.engine_refusal(ConSimRunner, **unresolvable), "variogram_model") + + async def test_the_neighborhood_is_not_compared_field_by_field(self) -> None: + """NOT A DIVERGENCE but a gap in the fixture, asserted so that it is not mistaken for parity. + + ``SearchNeighborhood`` hand-writes its own wire form, so its fields stop describing + what it sends and ``_writes_its_own_wire_form`` has to advertise it as an opaque + object. Deep validation then has nothing to check inside it, and three of the four + tasks covered here take a neighborhood -- the most-shared nested parameter in the + suite is the one the two paths are not compared on. + + The live catalogue publishes the real schema, so this is the fixture falling short of + the engine rather than the engine falling short of the runner. + """ + nonsense = {"ellipsoid": {"ranges": {"major": "wide"}}, "max_samples": 20} + + runner_error = await self.runner_refusal(KrigingRunner, **kriging_inputs(neighborhood=nonsense)) + self.assertBlames("runner", runner_error, "neighborhood") + + payload = await self.assertEngineAccepts(KrigingRunner, **kriging_inputs(neighborhood=nonsense)) + self.assertEqual(nonsense, payload["neighborhood"], "the engine saw something the fixture cannot show it") diff --git a/packages/evo-compute/tests/test_discovery.py b/packages/evo-compute/tests/test_discovery.py index 5dea640be..22e3ef344 100644 --- a/packages/evo-compute/tests/test_discovery.py +++ b/packages/evo-compute/tests/test_discovery.py @@ -23,7 +23,7 @@ from evo.common.utils import get_header_metadata from data import load_test_data -from evo.compute import DiscoveryClient, TaskResource +from evo.compute import DiscoveryClient, TaskResource, discovery from evo.compute.discovery import DEFAULT_CACHE_TTL_SECONDS from evo.compute.endpoints.api import DiscoveryApi from evo.compute.endpoints.models import DiscoveryResponse @@ -275,3 +275,43 @@ async def test_from_context(self) -> None: with self.set_discovery_response(): tasks = await client.list_tasks() self.assertTrue(tasks) + + # -- annotations this SDK does not know -------------------------------- # + + def catalogue_with_annotation(self, key: str) -> dict: + """The bundled catalogue with ``key`` planted on the first task's source parameter.""" + catalogue = json.loads(json.dumps(self.catalogue)) + catalogue["results"][0]["parameters"]["properties"]["source"][key] = "something-new" + return catalogue + + async def test_an_unrecognised_annotation_is_warned_about_not_raised(self) -> None: + """The platform moving ahead of the SDK must not stop a caller from running a task.""" + with self.set_discovery_response(self.catalogue_with_annotation("invented_here")): + with self.assertLogs("compute.discovery", level="WARNING") as logged: + tasks = await self.client.list_tasks() + self.assertEqual(len(self.catalogue["results"]), len(tasks)) + self.assertIn("'invented_here'", logged.output[0]) + self.assertIn(f"{tasks[0].topic}.{tasks[0].name}", logged.output[0]) + + async def test_a_catalogue_the_sdk_fully_understands_says_nothing(self) -> None: + with self.set_discovery_response(): + with mock.patch.object(discovery.logger, "warning") as warning: + await self.client.list_tasks() + warning.assert_not_called() + + async def test_the_same_annotation_is_not_reported_again_on_a_refetch(self) -> None: + """One line per unknown key, not one per cache expiry.""" + with self.set_discovery_response(self.catalogue_with_annotation("invented_here")): + with mock.patch.object(discovery.logger, "warning") as warning: + await self.client.list_tasks() + self.clock.advance(DEFAULT_CACHE_TTL_SECONDS + 1) + await self.client.list_tasks() + warning.assert_called_once() + + async def test_a_result_schema_annotation_is_caught_too(self) -> None: + catalogue = json.loads(json.dumps(self.catalogue)) + catalogue["results"][0]["results"] = {"type": "object", "invented_here": True} + with self.set_discovery_response(catalogue): + with self.assertLogs("compute.discovery", level="WARNING") as logged: + await self.client.list_tasks() + self.assertIn("'invented_here'", logged.output[0]) diff --git a/packages/evo-compute/tests/test_engine.py b/packages/evo-compute/tests/test_engine.py index 2faac28af..337640aa4 100644 --- a/packages/evo-compute/tests/test_engine.py +++ b/packages/evo-compute/tests/test_engine.py @@ -25,6 +25,22 @@ from evo.compute import ComputeClient, ParameterValidationError +def _object_url(suffix: str) -> str: + """A structurally valid geoscience object URL, which reference resolution insists on.""" + return ( + "https://unittest.localhost/geoscience-object" + "/orgs/00000000-0000-0000-0000-000000000001" + "/workspaces/00000000-0000-0000-0000-000000000002" + f"/objects/00000000-0000-0000-0000-0000000000{suffix}" + ) + + +SOURCE_URL = _object_url("10") +TARGET_URL = _object_url("20") +VARIOGRAM_URL = _object_url("30") +FILE_URL = "https://unittest.localhost/file/v2/orgs/00000000-0000-0000-0000-000000000001/files/mesh" + + def _task(topic: str, name: str, properties: dict[str, Any], required: list[str] | None = None) -> dict[str, Any]: """A catalogue entry for a task the shared fixture does not describe.""" return { @@ -49,6 +65,9 @@ def get_connector(self): def get_org_id(self): return self._org_id + def get_cache(self): + return None + class TestComputeClient(TestWithConnector): def setUp(self) -> None: @@ -87,20 +106,20 @@ def test_attribute_access_does_not_trigger_discovery(self) -> None: async def test_run_discovers_then_submits(self) -> None: """run() fetches the catalogue, then submits the resolved task.""" with self.catalogue_response(), self.mock_job_client() as submit: - result = await self.client.geostatistics.declustering.run(source="obj-1") + result = await self.client.geostatistics.declustering.run(source=SOURCE_URL) submit.assert_awaited_once() kwargs = submit.await_args.kwargs self.assertEqual("geostatistics", kwargs["topic"]) self.assertEqual("declustering", kwargs["task"]) - self.assertEqual({"source": "obj-1"}, kwargs["parameters"]) + self.assertEqual({"source": SOURCE_URL}, kwargs["parameters"]) self.assertFalse(kwargs["preview"]) self.assertEqual({"ok": True}, result) async def test_hyphenated_task_names_are_reachable_with_underscores(self) -> None: """``normal_score`` resolves to the platform's ``normal-score``.""" with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.normal_score.run(distribution="dist-1") + await self.client.geostatistics.normal_score.run(distribution=SOURCE_URL) self.assertEqual("normal-score", submit.await_args.kwargs["task"]) async def test_hyphenated_topics_and_parameters_are_reachable_with_underscores(self) -> None: @@ -165,22 +184,22 @@ async def test_fallback_parameters_still_reject_missing_and_unexpected_names(sel async def test_arun_takes_the_names_the_platform_publishes(self) -> None: with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.arun("geostatistics", "normal-score", {"distribution": "dist-1"}) + await self.client.arun("geostatistics", "normal-score", {"distribution": SOURCE_URL}) self.assertEqual("normal-score", submit.await_args.kwargs["task"]) - self.assertEqual({"distribution": "dist-1"}, submit.await_args.kwargs["parameters"]) + self.assertEqual({"distribution": SOURCE_URL}, submit.await_args.kwargs["parameters"]) async def test_catalogue_is_cached_across_runs(self) -> None: """The catalogue is fetched once and reused for later runs (any task/topic).""" with self.catalogue_response(), self.mock_job_client(): - await self.client.geostatistics.declustering.run(source="obj-1") - await self.client.geostatistics.kriging.run(source="s", target="t", variogram="v") + await self.client.geostatistics.declustering.run(source=SOURCE_URL) + await self.client.geostatistics.kriging.run(source=SOURCE_URL, target=TARGET_URL, variogram=VARIOGRAM_URL) self.assertEqual(1, self.transport.request.call_count) async def test_catalogue_is_shared_across_topics(self) -> None: """One catalogue fetch serves every topic, not just the first one touched.""" with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.declustering.run(source="obj-1") - await self.client.converter.obj_import.run(file="mesh.obj") + await self.client.geostatistics.declustering.run(source=SOURCE_URL) + await self.client.converter.obj_import.run(file=FILE_URL) self.assertEqual(1, self.transport.request.call_count) self.assertEqual("converter", submit.await_args.kwargs["topic"]) @@ -194,7 +213,7 @@ async def test_a_run_reads_the_catalogue_once(self) -> None: self.client._discovery, "list_tasks", wraps=self.client._discovery.list_tasks ) as list_tasks, ): - await self.client.geostatistics.normal_score.run(distribution="dist-1") + await self.client.geostatistics.normal_score.run(distribution=SOURCE_URL) list_tasks.assert_awaited_once() # -- parameter forwarding ---------------------------------------------- # @@ -202,7 +221,7 @@ async def test_a_run_reads_the_catalogue_once(self) -> None: async def test_schema_defaults_are_not_forwarded(self) -> None: """Unset optionals are omitted so the platform applies its own defaults.""" with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.declustering.run(source="obj-1") + await self.client.geostatistics.declustering.run(source=SOURCE_URL) parameters = submit.await_args.kwargs["parameters"] self.assertNotIn("method", parameters) # schema default "cell" must not be sent @@ -211,28 +230,30 @@ async def test_schema_defaults_are_not_forwarded(self) -> None: async def test_explicit_falsy_values_are_forwarded(self) -> None: """A supplied ``0``/``False`` is a real value, not an omission.""" with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.declustering.run(source="obj-1", power=0.0) + await self.client.geostatistics.declustering.run(source=SOURCE_URL, power=0.0) - self.assertEqual({"source": "obj-1", "power": 0.0}, submit.await_args.kwargs["parameters"]) + self.assertEqual({"source": SOURCE_URL, "power": 0.0}, submit.await_args.kwargs["parameters"]) async def test_explicit_none_is_forwarded(self) -> None: """An explicit ``None`` reaches the wire for a nullable parameter.""" with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.declustering.run(source="obj-1", power=None) + await self.client.geostatistics.declustering.run(source=SOURCE_URL, power=None) - self.assertEqual({"source": "obj-1", "power": None}, submit.await_args.kwargs["parameters"]) + self.assertEqual({"source": SOURCE_URL, "power": None}, submit.await_args.kwargs["parameters"]) # -- preview flag ------------------------------------------------------ # async def test_preview_is_off_by_default_even_for_feature_flagged_tasks(self) -> None: with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.kriging.run(source="s", target="t", variogram="v") + await self.client.geostatistics.kriging.run(source=SOURCE_URL, target=TARGET_URL, variogram=VARIOGRAM_URL) self.assertFalse(submit.await_args.kwargs["preview"]) async def test_preview_can_be_enabled(self) -> None: """The preview flag is passed to the job, not sent as a task parameter.""" with self.catalogue_response(), self.mock_job_client() as submit: - await self.client.geostatistics.kriging.run(source="s", target="t", variogram="v", preview=True) + await self.client.geostatistics.kriging.run( + source=SOURCE_URL, target=TARGET_URL, variogram=VARIOGRAM_URL, preview=True + ) self.assertTrue(submit.await_args.kwargs["preview"]) self.assertNotIn("preview", submit.await_args.kwargs["parameters"]) @@ -257,7 +278,7 @@ async def test_unexpected_parameter_raises_validation_error(self) -> None: """An unknown keyword argument is rejected, and the error names the task.""" with self.catalogue_response(), self.mock_job_client() as submit: with self.assertRaises(ParameterValidationError) as ctx: - await self.client.geostatistics.declustering.run(source="obj-1", bogus=1) + await self.client.geostatistics.declustering.run(source=SOURCE_URL, bogus=1) self.assertIn("geostatistics.declustering.run():", str(ctx.exception)) self.assertIn("bogus", str(ctx.exception)) @@ -270,7 +291,7 @@ async def test_unexpected_parameter_raises_validation_error(self) -> None: async def test_signature_is_synthesised_after_caching(self) -> None: """Once a task is cached, run() advertises a schema-shaped signature.""" with self.catalogue_response(), self.mock_job_client(): - await self.client.geostatistics.declustering.run(source="obj-1") + await self.client.geostatistics.declustering.run(source=SOURCE_URL) run = self.client.geostatistics.declustering.run signature = inspect.signature(run) @@ -285,12 +306,13 @@ async def test_signature_is_synthesised_after_caching(self) -> None: async def test_signature_annotations_follow_the_schema(self) -> None: """Parameter annotations are derived from each property's JSON Schema type.""" with self.catalogue_response(), self.mock_job_client(): - await self.client.geostatistics.declustering.run(source="obj-1") + await self.client.geostatistics.declustering.run(source=SOURCE_URL) parameters = inspect.signature(self.client.geostatistics.declustering.run).parameters self.assertEqual(Literal["cell", "polygon"], parameters["method"].annotation) # enum self.assertEqual(Optional[float], parameters["power"].annotation) # ["number", "null"] - self.assertEqual(dict, parameters["source"].annotation) # object + self.assertEqual(str, parameters["source"].annotation) # reference leaf + self.assertEqual(dict, parameters["settings"].annotation) # object self.assertEqual(Any, parameters["options"].annotation) # no declared type self.assertEqual(bool, parameters["preview"].annotation) @@ -301,7 +323,7 @@ async def test_signature_is_refreshed_on_a_reused_proxy(self) -> None: self.assertNotIn("source", inspect.signature(run).parameters) with self.catalogue_response(), self.mock_job_client(): - await run(source="obj-1") + await run(source=SOURCE_URL) self.assertIn("source", inspect.signature(run).parameters) self.assertIn("source", inspect.signature(task_proxy.run).parameters) @@ -309,7 +331,7 @@ async def test_signature_is_refreshed_on_a_reused_proxy(self) -> None: async def test_dir_lists_cached_topics_and_tasks(self) -> None: """After a run, tab-completion surfaces the cached topics/tasks.""" with self.catalogue_response(), self.mock_job_client(): - await self.client.geostatistics.declustering.run(source="obj-1") + await self.client.geostatistics.declustering.run(source=SOURCE_URL) self.assertIn("geostatistics", dir(self.client)) self.assertIn("converter", dir(self.client)) diff --git a/packages/evo-compute/tests/test_outputs.py b/packages/evo-compute/tests/test_outputs.py new file mode 100644 index 000000000..9afab3839 --- /dev/null +++ b/packages/evo-compute/tests/test_outputs.py @@ -0,0 +1,314 @@ +# Copyright © 2026 Bentley Systems, Incorporated +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Hydration of a task's results against the ``results`` schema it publishes. + +The payload stays exactly what the platform sent -- these are ``dict`` subclasses, so a +caller who was indexing the raw JSON keeps working. What is added is attribute access and, +for the nodes the schema marks ``output: geoscience-object`` or ``output: attribute``, a +loader that turns the reference back into a typed object or attribute. +""" + +from __future__ import annotations + +import json +from collections.abc import Iterator, Mapping, Sequence +from contextlib import contextmanager +from typing import Any +from unittest import IsolatedAsyncioTestCase, mock + +from evo.common.test_tools import TestWithConnector +from evo.objects import ObjectSchema +from evo.objects.typed import BaseObject + +from data import load_test_data +from evo import jmespath +from evo.compute import ComputeClient, ResultNode, TaskResult +from test_resolution import ( + BLOCK_MODEL, + BLOCK_MODEL_URL, + POINTSET, + POINTSET_URL, + SCHEMAS_BY_URL, + TARGET_URL, + FakeContext, +) + +RESULTS = { + "message": "estimated 1000 blocks", + "target": { + "reference": TARGET_URL, + "name": "estimated grid", + "description": None, + "schema_id": "/objects/pointset/1.2.0/pointset.schema.json", + "attribute": {"reference": "locations.attributes[?name=='estimate']", "name": "estimate"}, + }, + "extras": [{"reference": POINTSET_URL, "name": "extra"}], + "report": None, +} + +# The two families the fixture's ``attribute_path`` knows about, each keeping its attributes +# somewhere else -- which is what makes an expression written for one wrong for the other. +POINTSET_DOCUMENT = {"locations": {"attributes": [{"name": "estimate", "key": "abc"}]}} +BLOCK_MODEL_DOCUMENT = {"attributes": [{"name": "estimate", "key": "abc"}]} + + +def loaded_object(document: dict, schema: ObjectSchema = POINTSET) -> mock.MagicMock: + """Stands in for the typed object a result reference downloads to.""" + obj = mock.MagicMock(spec=BaseObject) + obj.metadata.schema_id = schema + obj.to_dataframe = mock.AsyncMock(return_value="dataframe") + obj.search = lambda expression: jmespath.search(expression, document) + obj.attributes = _FakeAttributes(jmespath.search("attributes || locations.attributes", document)) + return obj + + +class _FakeAttributes: + """The name-or-key lookup every typed attribute collection offers.""" + + def __init__(self, attributes: Sequence[Mapping[str, Any]]) -> None: + self._attributes = attributes + + def __getitem__(self, name: str) -> mock.Mock: + for attribute in self._attributes: + if name in (attribute["name"], attribute["key"]): + found = mock.Mock(exists=True, to_dataframe=mock.AsyncMock(return_value="attribute dataframe")) + found.name = attribute["name"] + return found + return mock.Mock(exists=False) + + +class HydrationTestCase(IsolatedAsyncioTestCase): + def setUp(self) -> None: + catalogue = load_test_data("discovery-resolution.json") + self.schema = catalogue["results"][0]["results"] + self.context = FakeContext() + self.result = TaskResult(RESULTS, self.schema, self.context) + + @contextmanager + def loaded_object(self) -> Iterator[mock.AsyncMock]: + """Stub the typed-object download the object loaders delegate to.""" + obj = mock.Mock() + obj.to_dataframe = mock.AsyncMock(return_value="dataframe") + loader = mock.AsyncMock(return_value=obj) + with mock.patch("evo.compute.outputs.object_from_reference", loader): + yield loader + + @contextmanager + def objects_service(self, **by_url: mock.MagicMock) -> Iterator[mock.AsyncMock]: + """Serve a different typed object per reference, as the objects service would.""" + loader = mock.AsyncMock(side_effect=lambda _context, reference: by_url[reference]) + with mock.patch("evo.compute.outputs.object_from_reference", loader): + yield loader + + +class TestRawPayloadIsPreserved(HydrationTestCase): + """Hydration adds to the payload; it never rewrites it.""" + + def test_the_result_still_equals_the_payload_the_platform_sent(self) -> None: + self.assertEqual(RESULTS, self.result) + self.assertIsInstance(self.result, dict) + + def test_it_still_serialises_as_the_same_json(self) -> None: + self.assertEqual(json.loads(json.dumps(RESULTS)), json.loads(json.dumps(self.result))) + + def test_index_access_reaches_every_level(self) -> None: + self.assertEqual(TARGET_URL, self.result["target"]["reference"]) + self.assertEqual("estimate", self.result["target"]["attribute"]["name"]) + + +class TestAttributeAccess(HydrationTestCase): + """The schema shapes the payload, so it can be read as attributes.""" + + def test_nested_objects_become_nodes(self) -> None: + self.assertIsInstance(self.result.target, ResultNode) + self.assertEqual("estimated grid", self.result.target.name) + self.assertEqual("estimate", self.result.target.attribute.name) + + def test_arrays_of_outputs_become_lists_of_nodes(self) -> None: + self.assertEqual(1, len(self.result.extras)) + self.assertIsInstance(self.result.extras[0], ResultNode) + self.assertEqual(POINTSET_URL, self.result.extras[0].reference) + + def test_a_nullable_output_that_came_back_null_stays_none(self) -> None: + self.assertIsNone(self.result.report) + + def test_an_unknown_field_raises_attribute_error(self) -> None: + with self.assertRaises(AttributeError): + _ = self.result.nonexistent + + def test_tab_completion_lists_the_fields_that_came_back(self) -> None: + self.assertLessEqual({"message", "target", "extras"}, set(dir(self.result))) + + +class TestObjectOutputs(HydrationTestCase): + """``output: geoscience-object`` closes the DataFrame -> task -> DataFrame loop.""" + + async def test_load_downloads_the_object_the_task_wrote(self) -> None: + with self.loaded_object() as loader: + loaded = await self.result.target.load() + loader.assert_awaited_once_with(self.context, TARGET_URL) + self.assertIs(loader.return_value, loaded) + + async def test_to_dataframe_reads_the_loaded_object(self) -> None: + with self.loaded_object() as loader: + frame = await self.result.target.to_dataframe() + self.assertEqual("dataframe", frame) + loader.return_value.to_dataframe.assert_awaited_once_with() + + async def test_an_item_of_an_output_array_loads_too(self) -> None: + with self.loaded_object() as loader: + await self.result.extras[0].load() + loader.assert_awaited_once_with(self.context, POINTSET_URL) + + async def test_loading_something_that_is_no_kind_of_reference_is_refused(self) -> None: + """A file output is a reference the SDK has no loader for; it is not guessed at.""" + result = TaskResult({**RESULTS, "report": {"reference": "/file/v2/x", "name": "log"}}, self.schema, None) + with self.assertRaises(TypeError): + await result.report.load() + + def test_a_file_output_is_left_as_its_reference(self) -> None: + """File outputs are surfaced as references until the File API layer lands.""" + result = TaskResult({**RESULTS, "report": {"reference": "/file/v2/x", "name": "log"}}, self.schema, None) + self.assertEqual("/file/v2/x", result.report.reference) + + +class TestAttributeOutputs(HydrationTestCase): + """``output: attribute`` names an attribute on a sibling object, not an object.""" + + async def test_sdk_array_and_object_search_proxies_load(self) -> None: + owner = loaded_object(POINTSET_DOCUMENT) + for expression, proxy_type in ( + ("locations.attributes[?name=='estimate']", jmespath.JMESPathArrayProxy), + ("locations.attributes[0]", jmespath.JMESPathObjectProxy), + ): + with self.subTest(expression=expression): + self.assertIsInstance(owner.search(expression), proxy_type) + results = { + **RESULTS, + "target": {**RESULTS["target"], "attribute": {"reference": expression, "name": "estimate"}}, + } + result = TaskResult(results, self.schema, self.context) + with self.objects_service(**{TARGET_URL: owner}): + attribute = await result.target.attribute.load() + self.assertEqual("estimate", attribute.name) + + async def test_the_attribute_is_loaded_from_the_object_attribute_from_points_at(self) -> None: + with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}) as loader: + attribute = await self.result.target.attribute.load() + # ``2/reference`` climbs out of the attribute node to the target that owns it, so the + # other object in the payload is not what gets downloaded. + loader.assert_awaited_once_with(self.context, TARGET_URL) + self.assertEqual("estimate", attribute.name) + + async def test_an_expression_written_for_another_family_is_healed(self) -> None: + """One expression is published for every family a task supports; only one can be right.""" + results = {**RESULTS, "target": {**RESULTS["target"], "reference": BLOCK_MODEL_URL}} + result = TaskResult(results, self.schema, self.context) + block_model = loaded_object(BLOCK_MODEL_DOCUMENT, BLOCK_MODEL) + # Without healing there is nothing to find: the published expression names a + # container this family does not have. + self.assertIsNone(block_model.search(results["target"]["attribute"]["reference"])) + with self.objects_service(**{BLOCK_MODEL_URL: block_model}): + attribute = await result.target.attribute.load() + self.assertEqual("estimate", attribute.name) + + async def test_to_dataframe_reads_the_attribute_alone(self) -> None: + with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}): + frame = await self.result.target.attribute.to_dataframe() + self.assertEqual("attribute dataframe", frame) + + async def test_an_attribute_is_one_column_and_takes_no_keys(self) -> None: + with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}): + with self.assertRaises(TypeError): + await self.result.target.attribute.to_dataframe("estimate") + + async def test_an_attribute_the_object_does_not_have_is_reported(self) -> None: + results = {**RESULTS, "target": {**RESULTS["target"], "attribute": {"reference": "attributes[?name=='x']"}}} + result = TaskResult(results, self.schema, self.context) + with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}): + with self.assertRaises(ValueError) as context: + await result.target.attribute.load() + self.assertIn("matches no attribute", str(context.exception)) + + async def test_an_attribute_with_no_pointer_cannot_name_its_object(self) -> None: + node = ResultNode( + {"reference": "attributes[?name=='estimate']", "name": "estimate"}, + {"output": "attribute", "properties": {"reference": {"reference_to": "attribute"}}}, + self.context, + ) + with self.assertRaises(ValueError) as context: + await node.load() + self.assertIn("which object this attribute belongs to", str(context.exception)) + + +class TestTasksWithoutAResultSchema(HydrationTestCase): + """A task that advertises no ``results`` block still yields a usable payload.""" + + def test_the_payload_is_returned_as_it_came(self) -> None: + result = TaskResult({"message": "done"}, None, self.context) + self.assertEqual({"message": "done"}, result) + self.assertEqual("done", result.message) + + async def test_nothing_claims_to_be_an_object(self) -> None: + result = TaskResult({"target": {"reference": TARGET_URL}}, None, self.context) + with self.assertRaises(TypeError): + await result.target.load() + + +class TestEngineHydration(TestWithConnector): + """``run(...)`` returns the hydrated result, not the bare payload.""" + + def setUp(self) -> None: + super().setUp() + self.context = FakeContext(self.connector) + self.catalogue = load_test_data("discovery-resolution.json") + + @contextmanager + def catalogue_response(self) -> Iterator[None]: + with self.transport.set_http_response( + status_code=200, + content=json.dumps(self.catalogue), + headers={"Content-Type": "application/json"}, + ): + yield + + @contextmanager + def mock_job_client(self) -> Iterator[None]: + job = mock.Mock() + job.wait_for_results = mock.AsyncMock(return_value=RESULTS) + with mock.patch("evo.compute.engine.JobClient") as mock_job_client: + mock_job_client.submit = mock.AsyncMock(return_value=job) + yield + + @contextmanager + def objects_service(self) -> Iterator[None]: + async def load(_context: Any, reference: str) -> mock.Mock: + return mock.Mock(metadata=mock.Mock(schema_id=SCHEMAS_BY_URL[str(reference)])) + + with mock.patch("evo.compute.resolution.DownloadedObject.from_context", mock.AsyncMock(side_effect=load)): + yield + + async def run_task(self) -> Any: + client = ComputeClient(self.context) + with self.catalogue_response(), self.objects_service(), self.mock_job_client(): + return await client.demo.estimate.run( + source={"object": POINTSET_URL, "attribute": "locations.attributes[?name=='grade']"}, + target={"object": TARGET_URL, "attribute": "estimate"}, + ) + + async def test_the_result_is_hydrated_against_the_result_schema(self) -> None: + result = await self.run_task() + self.assertIsInstance(result, TaskResult) + self.assertEqual("estimated grid", result.target.name) + + async def test_the_result_is_still_the_payload_the_platform_sent(self) -> None: + self.assertEqual(RESULTS, await self.run_task()) diff --git a/packages/evo-compute/tests/test_payload_parity.py b/packages/evo-compute/tests/test_payload_parity.py new file mode 100644 index 000000000..8d7d95a78 --- /dev/null +++ b/packages/evo-compute/tests/test_payload_parity.py @@ -0,0 +1,657 @@ +# Copyright © 2026 Bentley Systems, Incorporated +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Payload parity between the hand-written task runners and the generic engine. + +Each case declares one set of inputs, hands that same set to a typed runner and to the +discovery-driven engine, and asserts that ``JobClient.submit`` was given the same +``parameters`` payload by both -- equal in value *and* in type, so a ``1`` never passes +for a ``1.0``. + +Feeding both paths the same inputs is the point. It is the difference between the engine +being a drop-in replacement for a runner and the engine merely being *capable* of the same +payload if the caller formats it by hand. The engine earns it through +:mod:`~evo.compute.resolution`, which turns objects and attributes into the references a +task's schema declares, reusing ``tasks/common/source_target.py`` so that both paths agree +by construction rather than by coincidence. + +Where the two genuinely disagree, a test says so outright instead of hiding it by reshaping +the input. Two do: a runner materialises its own client-side field defaults where the engine +sends only what it was given, and a runner passes a bare attribute name straight through +where the engine expands it into the JMESPath the platform expects. + +One case is deliberately not stated as a single input set. ``source_filter`` is a runner-only +argument -- ``exclude=True`` on the model, folded into ``source`` before anything is sent -- +so the catalogue does not advertise it and the engine will not take it. That case compares +wire shapes instead, and the test beside it pins the rejection so the asymmetry stays visible +rather than reading as parity. + +Discovery is mocked rather than recorded, so the suite needs no catalogue fixture and no +credentials. :func:`task_spec` derives each task's schema from the runner's own parameter +model: the wire names, which of them are required, and the reference annotations the +resolver reads. That makes this a test of the two code paths against each other, not of the +SDK against the live catalogue -- that is schema conformance, and is tested separately. +""" + +from __future__ import annotations + +from collections.abc import Iterator +from contextlib import contextmanager +from typing import Any, get_args +from unittest import IsolatedAsyncioTestCase, mock + +from evo.common.test_tools import ORG as TEST_ORG +from evo.objects import ObjectReference +from evo.objects.typed import Attribute, PendingAttribute +from evo.objects.typed.base import BaseObject +from pydantic import BaseModel + +from evo.compute import ComputeClient, DiscoveryClient, ParameterValidationError, TaskResource +from evo.compute.tasks import CreateAttribute, SearchNeighborhood, Source, Target, UpdateAttribute +from evo.compute.tasks.common import Ellipsoid, EllipsoidRanges, Filter, FilterCondition, Rotation +from evo.compute.tasks.common.source_target import _convert_object_reference, _get_attribute_expression +from evo.compute.tasks.geostatistics.conditioned_simulator import ConSimRunner +from evo.compute.tasks.geostatistics.declustering import DeclusteringGrid, DeclusteringRunner, DeclusteringSource +from evo.compute.tasks.geostatistics.kriging import BlockDiscretization, KrigingMethod, KrigingRunner +from evo.compute.tasks.geostatistics.location_wise import ( + LocationWiseRunner, + LocationWiseTarget, + MeanAboveCutoff, + ProbabilityAboveCutoff, +) + +# --------------------------------------------------------------------------- # +# Shared inputs +# --------------------------------------------------------------------------- # + + +def _obj_url(suffix: str) -> str: + """A structurally valid geoscience object URL, which the parameter models insist on.""" + return ( + "https://hub.test.evo.bentley.com/geoscience-object" + "/orgs/00000000-0000-0000-0000-000000000001" + "/workspaces/00000000-0000-0000-0000-000000000002" + f"/objects/00000000-0000-0000-0000-0000000000{suffix}" + ) + + +POINTSET_URL = _obj_url("10") +GRID_URL = _obj_url("20") +TARGET_URL = _obj_url("30") +VARIOGRAM_URL = _obj_url("40") + +GRADE_ATTRIBUTE = "locations.attributes[?name=='grade']" +SIMULATIONS_ATTRIBUTE = "locations.attributes[?name=='simulations']" + + +def _typed_object(url: str) -> mock.MagicMock: + """Stands in for a typed geoscience object, which the models resolve down to its URL.""" + obj = mock.MagicMock(spec=BaseObject) + obj.metadata.url = ObjectReference(url) + return obj + + +def _existing_attribute(key: str, url: str, schema_path: str = "") -> mock.MagicMock: + """Stands in for an attribute already on an object, which resolves to a key-based expression.""" + attribute = mock.MagicMock(spec=Attribute) + attribute.key = key + attribute.exists = True + attribute._context = mock.MagicMock(schema_path=schema_path) + attribute._obj = _typed_object(url) + return attribute + + +def _pending_attribute(name: str, url: str) -> PendingAttribute: + """An attribute that does not exist yet, which resolves to a create operation.""" + parent = mock.MagicMock() + parent._obj = _typed_object(url) + return PendingAttribute(parent, name) + + +def _search(min_samples: int | None = 4) -> SearchNeighborhood: + return SearchNeighborhood( + ellipsoid=Ellipsoid( + ranges=EllipsoidRanges(major=200.0, semi_major=150.0, minor=100.0), + rotation=Rotation(dip_azimuth=45.0, dip=10.0, pitch=5.0), + ), + max_samples=20, + min_samples=min_samples, + ) + + +# --------------------------------------------------------------------------- # +# Type-strict comparison +# --------------------------------------------------------------------------- # + + +def payload_differences(expected: Any, actual: Any, path: str = "parameters") -> list[str]: + """Compare two payloads by value *and* concrete type, reporting every divergence. + + ``==`` alone is too forgiving here: ``1 == 1.0`` and ``True == 1``, yet the platform + reads those as different JSON types. + """ + if type(expected) is not type(actual): + return [f"{path}: expected {type(expected).__name__} {expected!r}, got {type(actual).__name__} {actual!r}"] + + if isinstance(expected, dict): + differences = [] + for key in sorted(set(expected) - set(actual)): + differences.append(f"{path}.{key}: missing, expected {expected[key]!r}") + for key in sorted(set(actual) - set(expected)): + differences.append(f"{path}.{key}: unexpected, got {actual[key]!r}") + for key in expected.keys() & actual.keys(): + differences += payload_differences(expected[key], actual[key], f"{path}.{key}") + return differences + + if isinstance(expected, list): + if len(expected) != len(actual): + return [f"{path}: expected {len(expected)} item(s), got {len(actual)}"] + differences = [] + for index, (left, right) in enumerate(zip(expected, actual)): + differences += payload_differences(left, right, f"{path}[{index}]") + return differences + + return [] if expected == actual else [f"{path}: expected {expected!r}, got {actual!r}"] + + +# --------------------------------------------------------------------------- # +# Harness +# --------------------------------------------------------------------------- # + + +class FakeContext: + """Minimal duck-typed IContext exposing just what the runners and the engine use.""" + + def __init__(self) -> None: + self._connector = mock.Mock() + self._org_id = TEST_ORG.id + + def get_connector(self): + return self._connector + + def get_org_id(self): + return self._org_id + + def get_environment(self): + return mock.Mock() + + +class _SubmitCaptured(Exception): + """Raised in place of a real submission, once the payload has been recorded.""" + + +@contextmanager +def _capture_submit(module: str) -> Iterator[mock.AsyncMock]: + """Patch ``JobClient`` in ``module`` so submission stops as soon as the payload is known.""" + submit = mock.AsyncMock(side_effect=_SubmitCaptured) + with mock.patch(f"{module}.JobClient") as job_client: + job_client.submit = submit + yield submit + + +_REFERENCE_ANNOTATIONS = { + _convert_object_reference: {"reference_to": "geoscience-object"}, + _get_attribute_expression: {"reference_to": "attribute"}, +} + + +def _annotation_for(field) -> dict[str, str] | None: + """The catalogue annotation a model field corresponds to, if it carries a reference. + + The models already say this, in the validator each reference field is annotated with, so + reading it back keeps the mocked schema honest without hand-writing any annotations. + """ + for meta in field.metadata: + if (annotation := _REFERENCE_ANNOTATIONS.get(getattr(meta, "func", None))) is not None: + return annotation + if {CreateAttribute, UpdateAttribute} & set(get_args(field.annotation)): + return {"target": "attribute"} + return None + + +def _models_reachable_from(model: type[BaseModel], seen: dict[str, type[BaseModel]]) -> dict[str, type[BaseModel]]: + """Index every model in ``model``'s field graph by name, matching pydantic's ``$defs`` keys.""" + if model.__name__ in seen: + return seen + seen[model.__name__] = model + for field in model.model_fields.values(): + for annotation in (field.annotation, *get_args(field.annotation)): + for member in (annotation, *get_args(annotation)): + if isinstance(member, type) and issubclass(member, BaseModel): + _models_reachable_from(member, seen) + return seen + + +def _renest_folded_filters(schema: dict[str, Any], folded: dict[str, Any]) -> None: + """Advertise a folded filter where the payload carries it, tagged as the catalogue tags it. + + ``source_filter`` is an input to the model that never reaches the wire: the serializer + writes it to ``source.filter``. The catalogue describes the wire, so it advertises the + filter under ``source`` and marks it ``composite: "filter"`` -- the annotation for a + sub-object the platform composes from a group of fields. + """ + for name, prop in folded.items(): + owner, _, leaf = name.rpartition("_") + if leaf != "filter": + continue + reference = schema.get("properties", {}).get(owner, {}).get("$ref", "") + if (block := schema.get("$defs", {}).get(reference.rpartition("/")[2])) is not None: + block.setdefault("properties", {})[leaf] = dict(prop, composite="filter") + + +def _writes_its_own_wire_form(model: type[BaseModel]) -> bool: + """Whether ``model`` hand-writes what it sends, rather than serialising its own fields. + + A plain ``@model_serializer`` replaces the payload outright, so the model's fields stop + describing what reaches the wire -- ``SearchNeighborhood`` validates ``ellipsoid.ranges`` + and sends ``ellipsoid.ellipsoid_ranges``. A ``mode="wrap"`` serializer defers to the + handler and only adds to what it returns, so those models still describe themselves. + + Advertising such a model's fields anyway would fault every payload built from it. Nothing + in this module notices, because deep validation is off here; :mod:`test_behavior_parity` + turns it on and is where that would surface. The cost is that nothing inside such a model + is compared field by field in the derived-schema fixture. + """ + decorators = model.__pydantic_decorators__.model_serializers.values() + return any(decorator.info.mode == "plain" for decorator in decorators) + + +def task_spec(runner_cls) -> TaskResource: + """The discovery spec the engine would fetch for ``runner_cls``, built from its own model. + + Departures from a plain ``model_json_schema`` keep this a fair stand-in for the catalogue, + which describes the wire and nothing else. Fields the runner folds into another field are + ``exclude=True`` -- inputs to the model that never reach the wire -- so they are advertised + where the payload carries them rather than at the top level. Reference leaves carry the + annotations the resolver reads, without which it would leave a caller's objects and + attributes untouched. And a model that hand-writes its own wire form is advertised as the + opaque object it is, because its fields are no longer a description of what it sends. + """ + model = runner_cls.params_type + schema = model.model_json_schema(by_alias=True, mode="validation") + properties = schema.get("properties", {}) + folded = {field.alias or name for name, field in model.model_fields.items() if field.exclude} + schema["properties"] = {name: prop for name, prop in properties.items() if name not in folded} + schema["required"] = [name for name in schema.get("required", []) if name not in folded] + _renest_folded_filters(schema, {name: properties[name] for name in folded if name in properties}) + + models = _models_reachable_from(model, {}) + definitions = schema.get("$defs", {}) + for name, block in ((model.__name__, schema), *definitions.items()): + if (owner := models.get(name)) is None: + continue + if name in definitions and _writes_its_own_wire_form(owner): + definitions[name] = {"type": "object"} + continue + for field_name, field in owner.model_fields.items(): + key = field.alias or field_name + if key in block.get("properties", {}) and (annotation := _annotation_for(field)) is not None: + block["properties"][key].update(annotation) + return TaskResource(topic=runner_cls.topic, name=runner_cls.task, parameters=schema) + + +class PayloadParityTestCase(IsolatedAsyncioTestCase): + """Runs one job through both paths and compares what each hands to ``JobClient.submit``.""" + + def setUp(self) -> None: + super().setUp() + self.context = FakeContext() + self.client = ComputeClient(self.context) + + async def runner_payload(self, runner_cls, params) -> dict[str, Any]: + """The payload the hand-written runner submits for ``params``.""" + with _capture_submit("evo.compute.tasks.common.runner") as submit: + with self.assertRaises(_SubmitCaptured): + await runner_cls(self.context, params) + return submit.await_args.kwargs["parameters"] + + async def engine_payload(self, runner_cls, **parameters: Any) -> dict[str, Any]: + """The payload the generic engine submits for the same job, described as plain JSON.""" + catalogue = mock.patch.object( + DiscoveryClient, "list_tasks", mock.AsyncMock(return_value=[task_spec(runner_cls)]) + ) + with catalogue, _capture_submit("evo.compute.engine") as submit: + with self.assertRaises(_SubmitCaptured): + await getattr(self.client.geostatistics, runner_cls.task.replace("-", "_")).run(**parameters) + return submit.await_args.kwargs["parameters"] + + async def payload_difference(self, runner_cls, **inputs: Any) -> list[str]: + """How the two payloads differ when both paths are given ``inputs``.""" + runner_payload = await self.runner_payload(runner_cls, runner_cls.params_type(**inputs)) + engine_payload = await self.engine_payload(runner_cls, **inputs) + return payload_differences(runner_payload, engine_payload) + + async def assertSameInputsParity(self, runner_cls, **inputs: Any) -> None: + """Require both paths to submit the same payload when handed the same inputs.""" + differences = await self.payload_difference(runner_cls, **inputs) + if differences: + self.fail("engine payload diverges from the runner payload:\n " + "\n ".join(differences)) + + def assertPayloadParity(self, runner_payload: dict[str, Any], engine_payload: dict[str, Any]) -> None: + differences = payload_differences(runner_payload, engine_payload) + if differences: + self.fail("engine payload diverges from the runner payload:\n " + "\n ".join(differences)) + + +# --------------------------------------------------------------------------- # +# Declustering +# --------------------------------------------------------------------------- # + + +class TestDeclusteringPayloadParity(PayloadParityTestCase): + def _inputs(self, **overrides: Any) -> dict[str, Any]: + inputs: dict[str, Any] = dict( + source=DeclusteringSource(object=POINTSET_URL), + grid=DeclusteringGrid(object=GRID_URL), + target=Target(object=TARGET_URL, attribute=CreateAttribute(name="weights")), + neighborhood=_search(), + power=2.5, + ) + inputs.update(overrides) + return inputs + + async def test_inverse_distance_weighting(self) -> None: + """The everyday call: source, grid, target and a search, with an explicit power.""" + await self.assertSameInputsParity(DeclusteringRunner, **self._inputs()) + + async def test_knn_mode_sends_a_null_power(self) -> None: + """KNN mode is a literal ``null`` power, not an omitted one; both paths must forward it.""" + runner_payload = await self.runner_payload( + DeclusteringRunner, DeclusteringRunner.params_type(**self._inputs(power=None)) + ) + self.assertIn("power", runner_payload) + self.assertIsNone(runner_payload["power"]) + await self.assertSameInputsParity(DeclusteringRunner, **self._inputs(power=None)) + + async def test_a_typed_attribute_target_becomes_a_create_operation(self) -> None: + """The target is given as the attribute itself, and both paths expand it the same way.""" + await self.assertSameInputsParity( + DeclusteringRunner, **self._inputs(target=_pending_attribute("weights", TARGET_URL)) + ) + + async def test_search_without_min_samples_omits_the_key(self) -> None: + """An unset ``min_samples`` is dropped by the neighborhood serializer, not sent as null.""" + runner_payload = await self.runner_payload( + DeclusteringRunner, DeclusteringRunner.params_type(**self._inputs(neighborhood=_search(min_samples=None))) + ) + self.assertNotIn("min_samples", runner_payload["neighborhood"]) + await self.assertSameInputsParity(DeclusteringRunner, **self._inputs(neighborhood=_search(min_samples=None))) + + async def test_integer_power_is_not_accepted_as_the_float_the_runner_sends(self) -> None: + """Guards the comparison itself: the engine's ``2`` must not pass for the runner's ``2.0``.""" + runner_payload = await self.runner_payload( + DeclusteringRunner, DeclusteringRunner.params_type(**self._inputs(power=2.0)) + ) + engine_payload = await self.engine_payload(DeclusteringRunner, **self._inputs(power=2)) + self.assertEqual( + ["parameters.power: expected float 2.0, got int 2"], + payload_differences(runner_payload, engine_payload), + ) + + async def test_bare_objects_fill_in_their_frames(self) -> None: + """``source``/``grid`` are an object and nothing else, so the object goes straight in.""" + await self.assertSameInputsParity( + DeclusteringRunner, + **self._inputs(source=_typed_object(POINTSET_URL), grid=_typed_object(GRID_URL)), + ) + + +# --------------------------------------------------------------------------- # +# Kriging +# --------------------------------------------------------------------------- # + + +class TestKrigingPayloadParity(PayloadParityTestCase): + def _inputs(self, **overrides: Any) -> dict[str, Any]: + # Keyed by wire name throughout: ``KrigingParameters`` populates by alias, so one set + # of inputs serves the runner and the engine without any restating. + inputs: dict[str, Any] = dict( + source=Source(object=POINTSET_URL, attribute=GRADE_ATTRIBUTE), + target=Target(object=TARGET_URL, attribute=CreateAttribute(name="kriged_grade")), + variogram=VARIOGRAM_URL, + neighborhood=_search(), + kriging_method=KrigingMethod.ORDINARY, + ) + inputs.update(overrides) + return inputs + + async def test_ordinary_kriging(self) -> None: + """``neighborhood``/``kriging_method`` are the aliases of ``search``/``method``.""" + await self.assertSameInputsParity(KrigingRunner, **self._inputs()) + + async def test_simple_kriging_with_block_discretization(self) -> None: + """A tagged method object and an optional sub-block frame survive both paths intact.""" + await self.assertSameInputsParity( + KrigingRunner, + **self._inputs( + kriging_method=KrigingMethod.simple(mean=12.5), + block_discretization=BlockDiscretization(nx=3, ny=3, nz=2), + ), + ) + + async def test_typed_attributes_become_urls_and_jmespath_expressions(self) -> None: + """An attribute that already exists resolves to a key lookup, and to an *update* target.""" + runner_payload = await self.runner_payload( + KrigingRunner, + KrigingRunner.params_type( + **self._inputs( + source=_existing_attribute("src-key-1", POINTSET_URL, schema_path="locations.attributes"), + target=_existing_attribute("tgt-key-9", TARGET_URL), + ) + ), + ) + self.assertEqual("locations.attributes[?key=='src-key-1']", runner_payload["source"]["attribute"]) + self.assertEqual( + {"operation": "update", "reference": "attributes[?key=='tgt-key-9']"}, runner_payload["target"]["attribute"] + ) + await self.assertSameInputsParity( + KrigingRunner, + **self._inputs( + source=_existing_attribute("src-key-1", POINTSET_URL, schema_path="locations.attributes"), + target=_existing_attribute("tgt-key-9", TARGET_URL), + ), + ) + + async def test_a_folded_filter_reaches_the_wire_as_a_nested_one(self) -> None: + """WIRE SHAPE, NOT SAME INPUTS: ``source_filter`` is an argument only the runner has. + + It is ``exclude=True`` on the model and folded into ``source`` before anything is sent, + so the catalogue never advertises it and the engine rejects it -- the test below pins + that. What is worth asserting is that the shape the runner folds a filter into is the + shape an engine caller writes by hand, so this case compares payloads, not inputs. + """ + source_filter = Filter(where=FilterCondition(attribute=GRADE_ATTRIBUTE, operator="greater_than", threshold=0.5)) + runner_payload = await self.runner_payload( + KrigingRunner, KrigingRunner.params_type(**self._inputs(), source_filter=source_filter) + ) + self.assertNotIn("source_filter", runner_payload) + + nested = {"object": POINTSET_URL, "attribute": GRADE_ATTRIBUTE, "filter": source_filter.model_dump()} + engine_payload = await self.engine_payload(KrigingRunner, **self._inputs(source=nested)) + self.assertPayloadParity(runner_payload, engine_payload) + + async def test_the_folded_filter_fields_are_not_offered_as_engine_parameters(self) -> None: + """Folding a filter is runner-side work, so ``source_filter`` is not a task parameter.""" + self.assertNotIn("source_filter", task_spec(KrigingRunner).parameters["properties"]) + with self.assertRaises(ParameterValidationError) as caught: + await self.engine_payload( + KrigingRunner, + **self._inputs(), + source_filter={"where": {"type": "condition", "attribute": GRADE_ATTRIBUTE, "operator": "in"}}, + ) + self.assertIn("source_filter", str(caught.exception)) + + async def test_references_inside_a_composite_filter_are_resolved(self) -> None: + """WIRE SHAPE, NOT SAME INPUTS: a ``composite`` node is walked like any other. + + The catalogue tags ``source.filter`` ``composite: "filter"``. That annotation only + names the group of fields the platform composes, so it must not stop resolution at + the node: the attribute the condition filters on carries ``reference_to: attribute`` + and has to reach the wire as an expression from both paths. + + The engine caller spells out ``values: None`` because the runner does. Its serializer + dumps the filter model whole, and unlike the top-level payload that dump keeps the + unset keys, so an engine caller matching it has to send them too. + """ + attribute = _existing_attribute("filter-key-2", POINTSET_URL, schema_path="locations.attributes") + source_filter = Filter(where=FilterCondition(attribute=attribute, operator="greater_than", threshold=0.5)) + runner_payload = await self.runner_payload( + KrigingRunner, KrigingRunner.params_type(**self._inputs(), source_filter=source_filter) + ) + + nested = { + "object": POINTSET_URL, + "attribute": GRADE_ATTRIBUTE, + "filter": { + "where": { + "type": "condition", + "attribute": attribute, + "operator": "greater_than", + "threshold": 0.5, + "values": None, + } + }, + } + engine_payload = await self.engine_payload(KrigingRunner, **self._inputs(source=nested)) + + self.assertEqual( + "locations.attributes[?key=='filter-key-2']", engine_payload["source"]["filter"]["where"]["attribute"] + ) + self.assertPayloadParity(runner_payload, engine_payload) + + async def test_an_unset_method_is_defaulted_by_the_runner_only(self) -> None: + """DIVERGENCE: the runner materialises its ``method`` default; the engine sends nothing. + + The engine forwards only what the caller passed, leaving the platform to apply its own + default. Both reach the same job, but not by the same payload. This one is by design, + unlike the resolution gaps this suite found, which were fixed rather than recorded. + """ + inputs = self._inputs() + del inputs["kriging_method"] + self.assertEqual( + ["parameters.kriging_method: missing, expected {'type': 'ordinary'}"], + await self.payload_difference(KrigingRunner, **inputs), + ) + + async def test_a_bare_attribute_name_is_expanded_by_the_engine_only(self) -> None: + """DIVERGENCE: the runner passes a bare attribute name through; the engine expands it. + + ``_get_attribute_expression`` treats any string as an expression already written, so a + name reaches the platform as a name. The engine reads the leaf's ``reference_to: + attribute`` and projects the name into the container that attribute's family keeps its + attributes in -- ``attributes`` unless the schema names another through + ``attribute_path``, which is the container the typed paths above resolve to as well. + Only the engine's payload is one the platform can look the attribute up from. + """ + self.assertEqual( + ["parameters.source.attribute: expected 'grade', got \"attributes[?name=='grade']\""], + await self.payload_difference( + KrigingRunner, **self._inputs(source=Source(object=POINTSET_URL, attribute="grade")) + ), + ) + + +# --------------------------------------------------------------------------- # +# Conditional simulation (consim) +# --------------------------------------------------------------------------- # + + +class TestConSimPayloadParity(PayloadParityTestCase): + #: The runner materialises these from its own field defaults, so an engine caller has to + #: pass them for the two payloads to agree. Sending them on both paths is what makes this + #: one set of inputs rather than two. + RUNNER_DEFAULTS: dict[str, Any] = { + "block_discretization": {"nx": 1, "ny": 1, "nz": 1}, + "kriging_method": "simple", + "number_of_lines": 500, + "number_of_simulations": 1, + "random_seed": 38239342, + "number_of_simulations_to_save": 5, + "perform_validation": False, + } + + def _inputs(self, **overrides: Any) -> dict[str, Any]: + inputs: dict[str, Any] = dict( + source_object=POINTSET_URL, + source_attribute=GRADE_ATTRIBUTE, + target_object=GRID_URL, + neighborhood=_search(), + variogram_model=VARIOGRAM_URL, + **self.RUNNER_DEFAULTS, + ) + inputs.update(overrides) + return inputs + + async def test_minimal_conditional_simulation(self) -> None: + """The flat source shape: object and attribute as separate scalars, not a frame.""" + await self.assertSameInputsParity(ConSimRunner, **self._inputs()) + + async def test_multiple_simulations_with_quantiles(self) -> None: + """Counts stay ints and cutoffs stay floats across both paths.""" + await self.assertSameInputsParity( + ConSimRunner, + **self._inputs( + number_of_simulations=25, + number_of_simulations_to_save=3, + random_seed=7, + location_wise_quantiles=[0.1, 0.5, 0.9], + probability_above_cutoff=[1.0, 2.5], + ), + ) + + async def test_unset_defaults_are_supplied_by_the_runner_only(self) -> None: + """DIVERGENCE: seven client-side defaults the engine leaves to the platform.""" + inputs = self._inputs() + for name in self.RUNNER_DEFAULTS: + del inputs[name] + differences = await self.payload_difference(ConSimRunner, **inputs) + self.assertEqual( + sorted(f"parameters.{name}" for name in self.RUNNER_DEFAULTS), + sorted(difference.split(":")[0] for difference in differences), + ) + + +# --------------------------------------------------------------------------- # +# Location-wise +# --------------------------------------------------------------------------- # + + +class TestLocationWisePayloadParity(PayloadParityTestCase): + def _inputs(self, **overrides: Any) -> dict[str, Any]: + inputs: dict[str, Any] = dict( + source=Source(object=POINTSET_URL, attribute=SIMULATIONS_ATTRIBUTE), + target=LocationWiseTarget(object=GRID_URL), + summary=True, + ) + inputs.update(overrides) + return inputs + + async def test_summary_only(self) -> None: + """The plain-model control: no aliases, no defaults, no folded fields.""" + await self.assertSameInputsParity(LocationWiseRunner, **self._inputs()) + + async def test_all_statistics(self) -> None: + """Quantiles and cutoff lists keep their float element types.""" + await self.assertSameInputsParity( + LocationWiseRunner, + **self._inputs( + quantiles=[0.1, 0.5, 0.9], + probability_above_cutoff=ProbabilityAboveCutoff(cutoffs=[1.0, 2.0]), + mean_above_cutoff=MeanAboveCutoff(cutoffs=[1.5]), + ), + ) + + async def test_unset_optionals_stay_off_the_wire(self) -> None: + """Neither path invents a statistics block the caller never asked for.""" + runner_payload = await self.runner_payload(LocationWiseRunner, LocationWiseRunner.params_type(**self._inputs())) + for unset in ("quantiles", "probability_above_cutoff", "mean_above_cutoff"): + self.assertNotIn(unset, runner_payload) + await self.assertSameInputsParity(LocationWiseRunner, **self._inputs()) diff --git a/packages/evo-compute/tests/test_resolution.py b/packages/evo-compute/tests/test_resolution.py new file mode 100644 index 000000000..2913a715a --- /dev/null +++ b/packages/evo-compute/tests/test_resolution.py @@ -0,0 +1,630 @@ +# Copyright © 2026 Bentley Systems, Incorporated +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Reference resolution against a task schema shaped like the ones the platform publishes. + +``tests/data/discovery-resolution.json`` mirrors the real catalogue rather than a convenient +simplification: reference leaves are declared as URL *strings*, attribute leaves carry the +``attribute_from``/``attribute_path`` pair, the filter union sits behind ``$ref``, and the +target attribute is a create-or-update ``oneOf``. Resolution is only as good as the shapes it +is tested against, so the fixture has to be the awkward one. + +The objects service is stubbed at :meth:`DownloadedObject.from_context`, which is the single +point where resolution reaches the platform. +""" + +from __future__ import annotations + +import json +from collections.abc import Iterator +from contextlib import contextmanager +from typing import Any +from unittest import IsolatedAsyncioTestCase, mock +from uuid import UUID + +from evo.common import Environment +from evo.common.test_tools import TestWithConnector +from evo.objects import ObjectMetadata, ObjectReference, ObjectSchema, SchemaVersion +from evo.objects.typed import Attribute, PendingAttribute +from evo.objects.typed.base import BaseObject + +from data import load_test_data +from evo.compute import ComputeClient, ParameterValidationError, ReferenceResolver, TaskResource +from evo.compute.tasks import Source, Target +from evo.compute.tasks.geostatistics.kriging import BlockDiscretization + +HUB_URL = "https://unittest.localhost/" +ORG_ID = UUID(int=1) +WORKSPACE_ID = UUID(int=2) + + +def _object_url(suffix: str) -> str: + return ( + f"{HUB_URL.rstrip('/')}/geoscience-object" + f"/orgs/{ORG_ID}/workspaces/{WORKSPACE_ID}" + f"/objects/00000000-0000-0000-0000-0000000000{suffix}" + ) + + +POINTSET_URL = _object_url("10") +BLOCK_MODEL_URL = _object_url("20") +TARGET_URL = _object_url("30") + +POINTSET = ObjectSchema("objects", "pointset", SchemaVersion(1, 2, 0)) +BLOCK_MODEL = ObjectSchema("objects", "block-model", SchemaVersion(1, 0, 0)) + +SCHEMAS_BY_URL = {POINTSET_URL: POINTSET, BLOCK_MODEL_URL: BLOCK_MODEL, TARGET_URL: POINTSET} + + +class FakeContext: + """Minimal duck-typed IContext exposing just what reference resolution uses.""" + + def __init__(self, connector: Any = None) -> None: + self._connector = connector + + def get_environment(self) -> Environment: + return Environment(hub_url=HUB_URL, org_id=ORG_ID, workspace_id=WORKSPACE_ID) + + def get_connector(self) -> Any: + return self._connector + + def get_org_id(self) -> UUID: + return ORG_ID + + def get_cache(self) -> None: + return None + + +def typed_object(url: str, schema: ObjectSchema | None = POINTSET) -> mock.MagicMock: + """Stands in for a typed geoscience object the caller already holds.""" + obj = mock.MagicMock(spec=BaseObject) + obj.metadata.url = ObjectReference(url) + obj.metadata.schema_id = schema + return obj + + +def existing_attribute(key: str, url: str, schema_path: str = "", schema: ObjectSchema = POINTSET) -> mock.MagicMock: + """An attribute already on an object, which resolves to a key-based expression.""" + attribute = mock.MagicMock(spec=Attribute) + attribute.key = key + attribute.exists = True + attribute._context = mock.MagicMock(schema_path=schema_path) + attribute._obj = typed_object(url, schema) + return attribute + + +def pending_attribute(name: str, url: str, schema: ObjectSchema = POINTSET) -> PendingAttribute: + """An attribute that does not exist yet, which resolves to a create operation.""" + parent = mock.MagicMock() + parent._obj = typed_object(url, schema) + return PendingAttribute(parent, name) + + +class ResolutionTestCase(IsolatedAsyncioTestCase): + """A resolver over the ``demo/estimate`` spec, with the objects service stubbed out.""" + + def setUp(self) -> None: + catalogue = load_test_data("discovery-resolution.json") + self.spec = TaskResource.model_validate(catalogue["results"][0]) + self.import_spec = TaskResource.model_validate(catalogue["results"][1]) + self.resolver = ReferenceResolver(FakeContext()) + + @contextmanager + def objects_service(self, *, unavailable: bool = False) -> Iterator[mock.AsyncMock]: + """Stub the metadata download resolution falls back to for a bare reference.""" + + async def load(_context: Any, reference: str) -> mock.Mock: + if unavailable: + raise RuntimeError("objects service unavailable") + return mock.Mock(metadata=mock.Mock(schema_id=SCHEMAS_BY_URL[str(reference)])) + + loader = mock.AsyncMock(side_effect=load) + with mock.patch("evo.compute.resolution.DownloadedObject.from_context", loader): + yield loader + + async def resolve(self, **parameters: Any) -> dict[str, Any]: + return await self.resolver.resolve(self.spec, parameters) + + +class TestObjectReferences(ResolutionTestCase): + """``reference_to: geoscience-object`` -- any handle in, one validated URL out.""" + + async def frame(self, source_object: Any) -> Any: + with self.objects_service(): + resolved = await self.resolve(source={"object": source_object, "attribute": "grade"}) + return resolved["source"]["object"] + + async def test_a_url_string_is_passed_through_verbatim(self) -> None: + """The caller's own reference is submitted as written, version pin and all.""" + self.assertEqual(POINTSET_URL, await self.frame(POINTSET_URL)) + + async def test_an_object_reference_resolves_to_its_string(self) -> None: + self.assertEqual(POINTSET_URL, await self.frame(ObjectReference(POINTSET_URL))) + + async def test_a_typed_object_resolves_to_its_url(self) -> None: + self.assertEqual(POINTSET_URL, await self.frame(typed_object(POINTSET_URL))) + + async def test_object_metadata_resolves_to_its_url(self) -> None: + metadata = mock.MagicMock(spec=ObjectMetadata) + metadata.url = ObjectReference(POINTSET_URL) + metadata.schema_id = POINTSET + self.assertEqual(POINTSET_URL, await self.frame(metadata)) + + async def test_a_bare_uuid_is_expanded_in_the_client_workspace(self) -> None: + """A caller who only has an object id gets the URL built for them.""" + object_id = UUID("00000000-0000-0000-0000-000000000010") + self.assertEqual(POINTSET_URL, await self.frame(object_id)) + self.assertEqual(POINTSET_URL, await self.frame(str(object_id))) + + async def test_an_unusable_reference_is_reported_against_its_location(self) -> None: + with self.assertRaises(ParameterValidationError) as ctx: + await self.frame("not-a-reference") + self.assertIn("source.object", str(ctx.exception)) + self.assertEqual(1, len(ctx.exception.errors)) + + async def test_an_unsupported_handle_type_is_rejected(self) -> None: + with self.assertRaises(ParameterValidationError) as ctx: + await self.frame(12345) + self.assertIn("source.object", str(ctx.exception)) + + +class TestSupportedSchemas(ResolutionTestCase): + """``supported_schemas`` -- a hard error when it can be checked, a warning when it cannot.""" + + async def test_a_typed_object_is_checked_without_touching_the_network(self) -> None: + with self.objects_service() as loader: + await self.resolve( + source={"object": typed_object(POINTSET_URL), "attribute": "locations.attributes[?name=='grade']"}, + target={"object": typed_object(TARGET_URL), "attribute": "estimate"}, + ) + loader.assert_not_awaited() + + async def test_an_object_outside_the_supported_set_is_rejected(self) -> None: + unsupported = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0)) + with self.objects_service(): + with self.assertRaises(ParameterValidationError) as ctx: + await self.resolve(source={"object": typed_object(POINTSET_URL, unsupported), "attribute": "grade"}) + self.assertIn("source.object", str(ctx.exception)) + self.assertIn("triangle-mesh", str(ctx.exception)) + + async def test_a_bare_reference_is_checked_by_loading_the_object_once(self) -> None: + """The same object named twice costs one metadata request, not two.""" + with self.objects_service() as loader: + await self.resolve( + source={"object": POINTSET_URL, "attribute": "grade"}, + target={"object": POINTSET_URL, "attribute": "estimate"}, + ) + self.assertEqual(1, loader.await_count) + + async def test_an_unloadable_object_warns_instead_of_blocking(self) -> None: + """An objects-service outage must not stop a job the platform would accept.""" + with self.objects_service(unavailable=True): + with self.assertLogs("compute.resolution", level="WARNING") as logs: + resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"}) + self.assertEqual(POINTSET_URL, resolved["source"]["object"]) + self.assertIn("supported_schemas", logs.output[0]) + + async def test_the_check_is_skipped_when_validation_is_off(self) -> None: + unsupported = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0)) + with self.objects_service() as loader: + resolved = await self.resolver.resolve( + self.spec, + {"source": {"object": typed_object(POINTSET_URL, unsupported), "attribute": "grade"}}, + check_schemas=False, + ) + self.assertEqual(POINTSET_URL, resolved["source"]["object"]) + loader.assert_not_awaited() + + async def test_the_declared_version_range_is_honoured(self) -> None: + """``pointset/[>=1.2,<2]`` admits 1.9.9 but neither 1.1.0 nor 2.0.0.""" + accepted = [SchemaVersion(1, 2, 0), SchemaVersion(1, 9, 9)] + rejected = [SchemaVersion(1, 1, 0), SchemaVersion(2, 0, 0)] + for version in accepted: + with self.subTest(version=str(version)), self.objects_service(): + await self.resolve( + source={"object": typed_object(POINTSET_URL, ObjectSchema("objects", "pointset", version))} + ) + for version in rejected: + with self.subTest(version=str(version)), self.objects_service(): + with self.assertRaises(ParameterValidationError): + await self.resolve( + source={"object": typed_object(POINTSET_URL, ObjectSchema("objects", "pointset", version))} + ) + + +class TestAttributeReferences(ResolutionTestCase): + """``reference_to: attribute`` -- a name or a typed attribute in, JMESPath out.""" + + async def source_attribute(self, attribute: Any, object_: Any = POINTSET_URL) -> Any: + with self.objects_service(): + resolved = await self.resolve(source={"object": object_, "attribute": attribute}) + return resolved["source"]["attribute"] + + async def test_an_existing_typed_attribute_resolves_by_key(self) -> None: + attribute = existing_attribute("abc", POINTSET_URL, schema_path="locations.attributes") + self.assertEqual("locations.attributes[?key=='abc']", await self.source_attribute(attribute)) + + async def test_a_pending_typed_attribute_resolves_by_name(self) -> None: + self.assertEqual( + "attributes[?name=='grade']", await self.source_attribute(pending_attribute("grade", POINTSET_URL)) + ) + + async def test_a_ready_expression_is_left_alone(self) -> None: + """A caller who already speaks JMESPath is not second-guessed.""" + expression = "locations.attributes[?name=='grade']" + self.assertEqual(expression, await self.source_attribute(expression)) + + async def test_a_bare_name_is_placed_by_the_owning_objects_family(self) -> None: + """A pointset keeps attributes under ``locations``; a block model does not.""" + self.assertEqual("locations.attributes[?name=='grade']", await self.source_attribute("grade")) + self.assertEqual("attributes[?name=='grade']", await self.source_attribute("grade", object_=BLOCK_MODEL_URL)) + + async def test_a_bare_name_falls_back_when_the_object_is_unknown(self) -> None: + with self.objects_service(unavailable=True), self.assertLogs("compute.resolution", level="WARNING"): + resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"}) + self.assertEqual("attributes[?name=='grade']", resolved["source"]["attribute"]) + + async def test_a_value_that_is_not_an_attribute_at_all_is_rejected(self) -> None: + """Deep validation relaxes reference leaves, so this is the only place it can be caught.""" + with self.objects_service(): + with self.assertRaises(ParameterValidationError) as ctx: + await self.source_attribute(12345) + self.assertIn("source.attribute", str(ctx.exception)) + self.assertIn("int", str(ctx.exception)) + + async def test_a_filter_attribute_is_placed_by_an_absolute_pointer(self) -> None: + """``attribute_from: /source/object`` reaches across the payload, not just up it.""" + with self.objects_service(): + resolved = await self.resolve( + source={ + "object": POINTSET_URL, + "attribute": "grade", + "filter": {"where": {"type": "condition", "operator": "equal", "attribute": "domain"}}, + } + ) + condition = resolved["source"]["filter"]["where"] + self.assertEqual("locations.attributes[?name=='domain']", condition["attribute"]) + self.assertEqual("equal", condition["operator"]) + + async def test_a_nested_filter_union_resolves_every_branch(self) -> None: + """The union is recursive and behind ``$ref``; every leaf still gets resolved.""" + with self.objects_service(): + resolved = await self.resolve( + source={ + "object": BLOCK_MODEL_URL, + "attribute": "grade", + "filter": { + "where": { + "type": "all_of", + "filters": [ + {"type": "condition", "operator": "equal", "attribute": "domain"}, + {"type": "condition", "operator": "greater_than", "attribute": "zone"}, + ], + } + }, + } + ) + filters = resolved["source"]["filter"]["where"]["filters"] + self.assertEqual( + ["attributes[?name=='domain']", "attributes[?name=='zone']"], + [condition["attribute"] for condition in filters], + ) + + async def test_an_optional_filter_written_as_a_union_is_walked_too(self) -> None: + """``anyOf: [Filter, null]`` describes the same node as a nullable inline object. + + The catalogue inlines an optional sub-object and adds ``null`` to its ``type``, but a + schema generated from a model writes the union instead. Both have to be descended + into, or a reference inside an optional filter reaches the wire unresolved. + """ + with self.objects_service(): + resolved = await self.resolve( + source={"object": POINTSET_URL, "attribute": "grade"}, + target={ + "object": TARGET_URL, + "attribute": {"operation": "create", "name": "estimate"}, + "filter": {"where": {"type": "condition", "operator": "equal", "attribute": "domain"}}, + }, + ) + self.assertEqual("locations.attributes[?name=='domain']", resolved["target"]["filter"]["where"]["attribute"]) + + +class TestTargetAttributes(ResolutionTestCase): + """``target: attribute`` -- create a new attribute, or update an existing one.""" + + async def target_attribute(self, attribute: Any, object_: Any = TARGET_URL) -> Any: + with self.objects_service(): + resolved = await self.resolve(target={"object": object_, "attribute": attribute}) + return resolved["target"]["attribute"] + + async def test_a_bare_name_creates_the_attribute(self) -> None: + self.assertEqual({"operation": "create", "name": "estimate"}, await self.target_attribute("estimate")) + + async def test_a_pending_typed_attribute_creates_the_attribute(self) -> None: + self.assertEqual( + {"operation": "create", "name": "estimate"}, + await self.target_attribute(pending_attribute("estimate", TARGET_URL)), + ) + + async def test_an_existing_typed_attribute_updates_it(self) -> None: + attribute = existing_attribute("xyz", TARGET_URL, schema_path="locations.attributes") + self.assertEqual( + {"operation": "update", "reference": "locations.attributes[?key=='xyz']"}, + await self.target_attribute(attribute), + ) + + async def test_an_update_written_out_still_resolves_its_reference(self) -> None: + """Choosing the branch by hand does not opt out of resolving what is inside it.""" + self.assertEqual( + {"operation": "update", "reference": "locations.attributes[?name=='estimate']"}, + await self.target_attribute({"operation": "update", "reference": "estimate"}), + ) + + async def test_a_create_written_out_is_left_alone(self) -> None: + wire = {"operation": "create", "name": "estimate"} + self.assertEqual(wire, await self.target_attribute(wire)) + + +class TestTypedAttributeShorthand(ResolutionTestCase): + """A bare typed attribute names its object too, exactly as the typed tasks accept.""" + + async def test_a_source_attribute_fills_in_the_whole_frame(self) -> None: + attribute = existing_attribute("abc", POINTSET_URL, schema_path="locations.attributes") + with self.objects_service(): + resolved = await self.resolve(source=attribute) + self.assertEqual({"object": POINTSET_URL, "attribute": "locations.attributes[?key=='abc']"}, resolved["source"]) + + async def test_a_target_attribute_fills_in_the_whole_frame(self) -> None: + with self.objects_service(): + resolved = await self.resolve(target=pending_attribute("estimate", TARGET_URL)) + self.assertEqual( + {"object": TARGET_URL, "attribute": {"operation": "create", "name": "estimate"}}, resolved["target"] + ) + + async def test_a_missing_source_attribute_keeps_the_typed_tasks_error(self) -> None: + """The mistake and its wording are the same whichever path the caller took.""" + with self.objects_service(): + with self.assertRaises(ParameterValidationError) as ctx: + await self.resolve(source=pending_attribute("graed", POINTSET_URL)) + self.assertIn("does not exist on the source object", str(ctx.exception)) + + async def test_the_frame_object_still_faces_supported_schemas(self) -> None: + """The shorthand is a shorter way to say the same thing, not a way past the checks.""" + unsupported = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0)) + for parameter, attribute in ( + ("source", existing_attribute("abc", POINTSET_URL, schema=unsupported)), + ("target", pending_attribute("estimate", TARGET_URL, schema=unsupported)), + ): + with self.subTest(parameter=parameter), self.objects_service() as loader: + with self.assertRaises(ParameterValidationError) as ctx: + await self.resolve(**{parameter: attribute}) + self.assertIn(f"{parameter}.object", str(ctx.exception)) + # The attribute brought its object's schema along, so checking it is free. + loader.assert_not_awaited() + + +class TestFileReferences(ResolutionTestCase): + """``reference_to: file`` -- a File API URL, or a handle that carries one.""" + + async def test_a_url_string_is_passed_through(self) -> None: + resolved = await self.resolver.resolve(self.import_spec, {"file": "https://unittest.localhost/file/v2/x"}) + self.assertEqual("https://unittest.localhost/file/v2/x", resolved["file"]) + + async def test_a_service_relative_path_is_accepted(self) -> None: + resolved = await self.resolver.resolve(self.import_spec, {"file": "/file/v2/files/abc"}) + self.assertEqual("/file/v2/files/abc", resolved["file"]) + + async def test_a_handle_carrying_a_url_resolves_to_it(self) -> None: + handle = mock.Mock(url="https://unittest.localhost/file/v2/y") + resolved = await self.resolver.resolve(self.import_spec, {"file": handle}) + self.assertEqual("https://unittest.localhost/file/v2/y", resolved["file"]) + + async def test_a_local_filename_is_rejected(self) -> None: + """Deep validation relaxes reference leaves, so this is the only place it can be caught.""" + with self.assertRaises(ParameterValidationError) as ctx: + await self.resolver.resolve(self.import_spec, {"file": "mesh.obj"}) + self.assertIn("file", str(ctx.exception)) + self.assertIn("mesh.obj", str(ctx.exception)) + + async def test_a_handle_without_a_url_is_reported(self) -> None: + with self.assertRaises(ParameterValidationError) as ctx: + await self.resolver.resolve(self.import_spec, {"file": object()}) + self.assertIn("file", str(ctx.exception)) + + +class TestNonReferenceValues(ResolutionTestCase): + """Everything the annotations say nothing about survives the walk untouched.""" + + async def test_a_typed_parameter_model_is_accepted_and_resolved_through(self) -> None: + """The SDK's own ``Source``/``Target`` models are valid engine inputs too.""" + with self.objects_service(): + resolved = await self.resolve( + source=Source(object=POINTSET_URL, attribute="locations.attributes[?name=='grade']"), + target=Target.new_attribute(TARGET_URL, "estimate"), + ) + self.assertEqual( + {"object": POINTSET_URL, "attribute": "locations.attributes[?name=='grade']"}, resolved["source"] + ) + self.assertEqual( + {"object": TARGET_URL, "attribute": {"operation": "create", "name": "estimate"}}, resolved["target"] + ) + + async def test_scalars_arrays_and_plain_objects_are_unchanged(self) -> None: + with self.objects_service(): + resolved = await self.resolve( + source={"object": POINTSET_URL, "attribute": "grade"}, + seeds=[3, 1, 4], + options={"label": "run-1", "retries": 2}, + ) + self.assertEqual([3, 1, 4], resolved["seeds"]) + self.assertEqual({"label": "run-1", "retries": 2}, resolved["options"]) + + async def test_an_explicit_none_survives_resolution(self) -> None: + """A nullable reference set to ``None`` stays ``None`` rather than being resolved.""" + with self.objects_service(): + resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"}, report=None) + self.assertIsNone(resolved["report"]) + + async def test_an_undeclared_parameter_is_left_for_the_platform_to_judge(self) -> None: + resolved = await self.resolver.resolve(self.spec, {"mystery": {"a": 1}}) + self.assertEqual({"a": 1}, resolved["mystery"]) + + async def test_a_typed_model_in_an_optional_slot_is_dumped(self) -> None: + """An ``X | None`` slot has no ``properties`` of its own, but a model there is still ours.""" + with self.objects_service(): + resolved = await self.resolve( + source={"object": POINTSET_URL, "attribute": "grade"}, + discretisation=BlockDiscretization(nx=3, ny=3, nz=2), + ) + self.assertEqual({"nx": 3, "ny": 3, "nz": 2}, resolved["discretisation"]) + + +class TestBareObjectFrames(ResolutionTestCase): + """A parameter that is an object and nothing else accepts the object itself.""" + + async def resolve_grid(self, grid: Any) -> Any: + with self.objects_service(): + resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"}, grid=grid) + return resolved["grid"] + + async def test_a_typed_object_fills_in_the_frame(self) -> None: + """``run(grid=block_model)`` is how the typed tasks are called, so it works here too.""" + grid = typed_object(BLOCK_MODEL_URL, BLOCK_MODEL) + self.assertEqual({"object": BLOCK_MODEL_URL}, await self.resolve_grid(grid)) + + async def test_a_url_fills_in_the_frame(self) -> None: + self.assertEqual({"object": BLOCK_MODEL_URL}, await self.resolve_grid(BLOCK_MODEL_URL)) + + async def test_the_written_out_frame_is_left_alone(self) -> None: + self.assertEqual({"object": BLOCK_MODEL_URL}, await self.resolve_grid({"object": BLOCK_MODEL_URL})) + + +class EngineResolutionTestCase(TestWithConnector): + """A client over the ``demo`` catalogue, with the objects service and job client stubbed out.""" + + def setUp(self) -> None: + super().setUp() + self.context = FakeContext(self.connector) + self.catalogue = load_test_data("discovery-resolution.json") + + @contextmanager + def catalogue_response(self) -> Iterator[None]: + with self.transport.set_http_response( + status_code=200, + content=json.dumps(self.catalogue), + headers={"Content-Type": "application/json"}, + ): + yield + + @contextmanager + def mock_job_client(self, results: dict | None = None) -> Iterator[mock.AsyncMock]: + job = mock.Mock() + job.wait_for_results = mock.AsyncMock(return_value={} if results is None else results) + submit = mock.AsyncMock(return_value=job) + with mock.patch("evo.compute.engine.JobClient") as mock_job_client: + mock_job_client.submit = submit + yield submit + + @contextmanager + def objects_service(self) -> Iterator[mock.AsyncMock]: + async def load(_context: Any, reference: str) -> mock.Mock: + return mock.Mock(metadata=mock.Mock(schema_id=SCHEMAS_BY_URL[str(reference)])) + + with mock.patch("evo.compute.resolution.DownloadedObject.from_context", mock.AsyncMock(side_effect=load)): + yield + + +class TestEngineResolution(EngineResolutionTestCase): + """The engine resolves between its two validation passes, then submits the resolved payload.""" + + async def test_run_submits_the_resolved_payload(self) -> None: + client = ComputeClient(self.context) + with self.catalogue_response(), self.objects_service(), self.mock_job_client() as submit: + await client.demo.estimate.run( + source=existing_attribute("abc", POINTSET_URL, schema_path="locations.attributes"), + target=pending_attribute("estimate", TARGET_URL), + ) + + self.assertEqual( + { + "source": {"object": POINTSET_URL, "attribute": "locations.attributes[?key=='abc']"}, + "target": {"object": TARGET_URL, "attribute": {"operation": "create", "name": "estimate"}}, + }, + submit.await_args.kwargs["parameters"], + ) + + async def test_deep_validation_judges_the_resolved_payload(self) -> None: + """Typed objects would fail a schema that asks for URL strings; resolved ones pass.""" + client = ComputeClient(self.context, deep_validation=True) + with self.catalogue_response(), self.objects_service(), self.mock_job_client() as submit: + await client.demo.estimate.run( + source={"object": typed_object(POINTSET_URL), "attribute": "grade"}, + target={"object": typed_object(TARGET_URL), "attribute": "estimate"}, + ) + submit.assert_awaited_once() + + async def test_a_missing_required_parameter_is_caught_before_any_object_is_loaded(self) -> None: + """Nothing is worth a request until the call itself is known to be well formed.""" + client = ComputeClient(self.context) + with self.catalogue_response(), self.objects_service() as _, self.mock_job_client() as submit: + with mock.patch("evo.compute.resolution.DownloadedObject.from_context", mock.AsyncMock()) as loader: + with self.assertRaises(ParameterValidationError): + await client.demo.estimate.run(source={"object": POINTSET_URL, "attribute": "grade"}) + loader.assert_not_awaited() + submit.assert_not_awaited() + + +class TestSupportedSchemaSwitch(EngineResolutionTestCase): + """``check_schemas`` is independent of ``validate``, defaulting to follow it.""" + + UNSUPPORTED = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0)) + + async def run_with_an_unsupported_source(self, client: ComputeClient, **overrides: Any) -> mock.AsyncMock: + with self.catalogue_response(), self.objects_service(), self.mock_job_client() as submit: + await client.arun( + "demo", + "estimate", + { + "source": {"object": typed_object(POINTSET_URL, self.UNSUPPORTED), "attribute": "grade"}, + "target": {"object": typed_object(TARGET_URL), "attribute": "estimate"}, + }, + **overrides, + ) + return submit + + async def test_the_check_follows_validation_by_default(self) -> None: + for validate, expect_rejection in ((True, True), (False, False)): + with self.subTest(validate=validate): + client = ComputeClient(self.context, validate=validate) + if expect_rejection: + with self.assertRaises(ParameterValidationError): + await self.run_with_an_unsupported_source(client) + else: + submit = await self.run_with_an_unsupported_source(client) + submit.assert_awaited_once() + + async def test_the_check_survives_validation_being_turned_off(self) -> None: + """The guard that catches an object the task cannot read is worth keeping on its own.""" + client = ComputeClient(self.context, validate=False, check_schemas=True) + with self.assertRaises(ParameterValidationError) as ctx: + await self.run_with_an_unsupported_source(client) + self.assertIn("triangle-mesh", str(ctx.exception)) + + async def test_the_check_can_be_dropped_while_validation_stays_on(self) -> None: + """Skipping it costs the request each referenced object would otherwise need.""" + client = ComputeClient(self.context, check_schemas=False) + submit = await self.run_with_an_unsupported_source(client) + submit.assert_awaited_once() + + async def test_the_client_setting_is_overridden_per_call(self) -> None: + client = ComputeClient(self.context, check_schemas=False) + with self.assertRaises(ParameterValidationError): + await self.run_with_an_unsupported_source(client, check_schemas=True) diff --git a/packages/evo-compute/tests/test_schema_conformance.py b/packages/evo-compute/tests/test_schema_conformance.py index a8020537f..e01aace38 100644 --- a/packages/evo-compute/tests/test_schema_conformance.py +++ b/packages/evo-compute/tests/test_schema_conformance.py @@ -59,13 +59,13 @@ def test_vocabulary_matches_expected_set(self) -> None: self.assertEqual(_EXPECTED_VOCABULARY, KNOWN_SCHEMA_ANNOTATIONS) def test_bundled_catalogue_uses_only_known_annotations(self) -> None: - catalogue = load_test_data("discovery-tasks.json") offenders: dict[str, set[str]] = {} - for result in catalogue["results"]: - task = TaskResource.model_validate(result) - unknown = _unknown_keys_for_task(task) - if unknown: - offenders[task.name] = unknown + for fixture in ("discovery-tasks.json", "discovery-resolution.json"): + for result in load_test_data(fixture)["results"]: + task = TaskResource.model_validate(result) + unknown = _unknown_keys_for_task(task) + if unknown: + offenders[f"{fixture}:{task.name}"] = unknown self.assertEqual({}, offenders, f"unknown schema annotations found: {offenders}") def test_unknown_annotation_is_flagged(self) -> None: diff --git a/packages/evo-compute/tests/test_validation.py b/packages/evo-compute/tests/test_validation.py index 744a2c9aa..941360d61 100644 --- a/packages/evo-compute/tests/test_validation.py +++ b/packages/evo-compute/tests/test_validation.py @@ -407,6 +407,15 @@ def test_union_with_several_matching_branches_keeps_the_generic_message(self) -> class TestEngineValidation(TestWithConnector): """Engine-level tests for the validation toggles (shallow default, deep opt-in).""" + # Reference resolution runs between the two validation passes, so the engine-level + # tests have to name an object the way a caller really would. + SOURCE_URL = ( + "https://unittest.localhost/geoscience-object" + "/orgs/00000000-0000-0000-0000-000000000001" + "/workspaces/00000000-0000-0000-0000-000000000002" + "/objects/00000000-0000-0000-0000-000000000010" + ) + def setUp(self) -> None: super().setUp() self.context = FakeContext(self.connector, TEST_ORG.id) @@ -434,14 +443,14 @@ async def test_shallow_is_on_by_default_deep_is_off(self) -> None: """By default an enum violation slips through (deep off) and the job is submitted.""" client = ComputeClient(self.context) with self.catalogue_response(), self.mock_job_client() as submit: - await client.demo.widget.run(source="obj-1", mode="turbo") + await client.demo.widget.run(source=self.SOURCE_URL, mode="turbo") submit.assert_awaited_once() async def test_deep_validation_rejects_bad_enum(self) -> None: client = ComputeClient(self.context, deep_validation=True) with self.catalogue_response(), self.mock_job_client() as submit: with self.assertRaises(ParameterValidationError) as ctx: - await client.demo.widget.run(source="obj-1", mode="turbo") + await client.demo.widget.run(source=self.SOURCE_URL, mode="turbo") self.assertIn("mode", str(ctx.exception)) submit.assert_not_awaited() @@ -449,7 +458,7 @@ async def test_deep_validation_rejects_constraint_violation(self) -> None: client = ComputeClient(self.context, deep_validation=True) with self.catalogue_response(), self.mock_job_client() as submit: with self.assertRaises(ParameterValidationError): - await client.demo.widget.run(source="obj-1", mode="fast", iterations=0) + await client.demo.widget.run(source=self.SOURCE_URL, mode="fast", iterations=0) submit.assert_not_awaited() async def test_deep_validation_rejects_explicit_none_for_a_non_nullable_field(self) -> None: @@ -457,7 +466,7 @@ async def test_deep_validation_rejects_explicit_none_for_a_non_nullable_field(se client = ComputeClient(self.context, deep_validation=True) with self.catalogue_response(), self.mock_job_client() as submit: with self.assertRaises(ParameterValidationError) as ctx: - await client.demo.widget.run(source="obj-1", mode="fast", iterations=None) + await client.demo.widget.run(source=self.SOURCE_URL, mode="fast", iterations=None) self.assertIn("iterations", str(ctx.exception)) submit.assert_not_awaited() @@ -465,21 +474,21 @@ async def test_deep_validation_accepts_reference_string(self) -> None: """Deep validation passes when the required reference is supplied as a string.""" client = ComputeClient(self.context, deep_validation=True) with self.catalogue_response(), self.mock_job_client() as submit: - await client.demo.widget.run(source="obj-1", mode="fast") + await client.demo.widget.run(source=self.SOURCE_URL, mode="fast") submit.assert_awaited_once() async def test_deep_validation_can_be_forced_per_call(self) -> None: client = ComputeClient(self.context) # deep off at the client level with self.catalogue_response(), self.mock_job_client() as submit: with self.assertRaises(ParameterValidationError): - await client.arun("demo", "widget", {"source": "obj-1", "mode": "turbo"}, deep_validation=True) + await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": "turbo"}, deep_validation=True) submit.assert_not_awaited() async def test_validation_can_be_disabled_per_call(self) -> None: """With validation off, a required field set to ``None`` goes out for the platform to reject.""" client = ComputeClient(self.context) with self.catalogue_response(), self.mock_job_client() as submit: - await client.arun("demo", "widget", {"source": "obj-1", "mode": None}, validate=False) + await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": None}, validate=False) submit.assert_awaited_once() self.assertIsNone(submit.await_args.kwargs["parameters"]["mode"]) @@ -487,27 +496,31 @@ async def test_validation_on_catches_required_set_to_none(self) -> None: client = ComputeClient(self.context) with self.catalogue_response(), self.mock_job_client() as submit: with self.assertRaises(ParameterValidationError): - await client.arun("demo", "widget", {"source": "obj-1", "mode": None}) + await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": None}) submit.assert_not_awaited() async def test_validate_off_at_the_client_disables_deep_validation_too(self) -> None: """``validate`` is the master switch, so ``deep_validation=True`` under it does nothing.""" client = ComputeClient(self.context, validate=False, deep_validation=True) with self.catalogue_response(), self.mock_job_client() as submit: - await client.demo.widget.run(source="obj-1", mode="turbo") + await client.demo.widget.run(source=self.SOURCE_URL, mode="turbo") submit.assert_awaited_once() async def test_validate_off_per_call_disables_deep_validation_too(self) -> None: client = ComputeClient(self.context, deep_validation=True) with self.catalogue_response(), self.mock_job_client() as submit: - await client.arun("demo", "widget", {"source": "obj-1", "mode": "turbo"}, validate=False) + await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": "turbo"}, validate=False) submit.assert_awaited_once() async def test_validate_off_per_call_overrides_deep_validation_on_per_call(self) -> None: client = ComputeClient(self.context) with self.catalogue_response(), self.mock_job_client() as submit: await client.arun( - "demo", "widget", {"source": "obj-1", "mode": "turbo"}, validate=False, deep_validation=True + "demo", + "widget", + {"source": self.SOURCE_URL, "mode": "turbo"}, + validate=False, + deep_validation=True, ) submit.assert_awaited_once() From f191a4ded8c2072ce58631c26e95d4c7946db1e4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:19:50 +0000 Subject: [PATCH 2/2] Update to MkDocs documentation --- .../packages/evo-compute/ComputeClient.html | 66 +++++++++++++++---- 1 file changed, 54 insertions(+), 12 deletions(-) diff --git a/mkdocs/site/packages/evo-compute/ComputeClient.html b/mkdocs/site/packages/evo-compute/ComputeClient.html index a71b92e78..c3ec360dc 100644 --- a/mkdocs/site/packages/evo-compute/ComputeClient.html +++ b/mkdocs/site/packages/evo-compute/ComputeClient.html @@ -146,9 +146,13 @@

-

Validate parameters against the task schema before submitting -(required-field presence). Defaults to True. This is the master switch: -False turns off deep validation too, whatever deep_validation says.

+

Check the parameters against the task's JSON Schema before submitting +(required-field presence, and, under deep_validation, the whole payload). +Defaults to True. False turns off deep validation too, whatever +deep_validation says. It does not make the call unchecked: the parameters are +still bound to the signature synthesised from the schema, so an unknown or missing +required argument is still rejected. That is how the payload is built, not a +validation pass, and there is no useful call to make without it.

@@ -172,6 +176,27 @@

False + + + check_schemas + + + bool | None + + +
+

Check that each referenced geoscience object is of a schema the +task declares support for. Defaults to following validate. Independent of it +because the cost and the question differ: schema validation is local and free, +while this loads each referenced object's metadata. Pass False to keep +validation but skip the requests, or True alongside validate=False to keep +the guard that catches an object the task cannot read.

+
+ + + None + + @@ -215,14 +240,13 @@

*, validate: bool | None = None, deep_validation: bool | None = None, -) -> dict + check_schemas: bool | None = None, +) -> TaskResult
-

Run a task by name and wait for its results.

-

The same as await client.<topic>.<task>.run(**parameters), for names held as -strings. Names may be spelled as the platform publishes them or with underscores.

+

Discover the task (cached), resolve and validate the parameters, submit, and hydrate the results.

Parameters:

@@ -293,8 +317,9 @@

-

Override the client's shallow-validation setting for this call. -The master switch: False skips deep validation too.

+

Override the client's schema-validation setting for this call. +False skips deep validation too, but never the signature binding that +builds the payload.

@@ -318,6 +343,23 @@

None + + + check_schemas + + + bool | None + + +
+

Override the client's supported-schema setting for this call. +Falls back to validate when neither is set.

+
+ + + None + + @@ -333,11 +375,11 @@

- dict + TaskResult
-

The results of the finished job.

+

The hydrated results of the finished job.

@@ -370,7 +412,7 @@

-

If the parameters do not match the task's schema.

+

If the parameters or referenced objects fail validation.