diff --git a/mkdocs/site/packages/evo-compute/ComputeClient.html b/mkdocs/site/packages/evo-compute/ComputeClient.html index a71b92e7..c3ec360d 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.

diff --git a/packages/evo-compute/pyproject.toml b/packages/evo-compute/pyproject.toml index 12b6f641..aea2a238 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 3605ea56..60726269 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 5993280e..4d867ad9 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 5531bee6..5cb13dc6 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 00000000..55ccf9b9 --- /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 00000000..9346e919 --- /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 84e115bb..1a3a5036 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 00000000..3b1f3f1a --- /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 5c7d0c72..09529dc2 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 8143c156..14c48e35 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 00000000..dcae4a5e --- /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 5dea640b..22e3ef34 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 2faac28a..337640aa 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 00000000..9afab383 --- /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 00000000..8d7d95a7 --- /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 00000000..2913a715 --- /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 a8020537..e01aace3 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 744a2c9a..941360d6 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()