Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 54 additions & 12 deletions mkdocs/site/packages/evo-compute/ComputeClient.html
Original file line number Diff line number Diff line change
Expand Up @@ -146,9 +146,13 @@ <h2 id="evo.compute.engine.ComputeClient" class="doc doc-heading">
</td>
<td>
<div class="doc-md-description">
<p>Validate parameters against the task schema before submitting
(required-field presence). Defaults to <code>True</code>. This is the master switch:
<code>False</code> turns off deep validation too, whatever <code>deep_validation</code> says.</p>
<p>Check the parameters against the task's JSON Schema before submitting
(required-field presence, and, under <code>deep_validation</code>, the whole payload).
Defaults to <code>True</code>. <code>False</code> turns off deep validation too, whatever
<code>deep_validation</code> says. It does <em>not</em> 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.</p>
</div>
</td>
<td>
Expand All @@ -172,6 +176,27 @@ <h2 id="evo.compute.engine.ComputeClient" class="doc doc-heading">
<code>False</code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>check_schemas</code>
</td>
<td>
<code><span title="bool">bool</span> | None</code>
</td>
<td>
<div class="doc-md-description">
<p>Check that each referenced geoscience object is of a schema the
task declares support for. Defaults to following <code>validate</code>. 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 <code>False</code> to keep
validation but skip the requests, or <code>True</code> alongside <code>validate=False</code> to keep
the guard that catches an object the task cannot read.</p>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
</tbody>
</table>

Expand Down Expand Up @@ -215,14 +240,13 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
<span class="o">*</span><span class="p">,</span>
<span class="n">validate</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="n">deep_validation</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span>
<span class="n">check_schemas</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">TaskResult</span>
</code></pre></div>

<div class="doc doc-contents ">

<p>Run a task by name and wait for its results.</p>
<p>The same as <code>await client.&lt;topic&gt;.&lt;task&gt;.run(**parameters)</code>, for names held as
strings. Names may be spelled as the platform publishes them or with underscores.</p>
<p>Discover the task (cached), resolve and validate the parameters, submit, and hydrate the results.</p>


<p><span class="doc-section-title">Parameters:</span></p>
Expand Down Expand Up @@ -293,8 +317,9 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
</td>
<td>
<div class="doc-md-description">
<p>Override the client's shallow-validation setting for this call.
The master switch: <code>False</code> skips deep validation too.</p>
<p>Override the client's schema-validation setting for this call.
<code>False</code> skips deep validation too, but never the signature binding that
builds the payload.</p>
</div>
</td>
<td>
Expand All @@ -318,6 +343,23 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
<code>None</code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>check_schemas</code>
</td>
<td>
<code><span title="bool">bool</span> | None</code>
</td>
<td>
<div class="doc-md-description">
<p>Override the client's supported-schema setting for this call.
Falls back to <code>validate</code> when neither is set.</p>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
</tbody>
</table>

Expand All @@ -333,11 +375,11 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="dict">dict</span></code>
<code><span title="evo.compute.outputs.TaskResult">TaskResult</span></code>
</td>
<td>
<div class="doc-md-description">
<p>The results of the finished job.</p>
<p>The hydrated results of the finished job.</p>
</div>
</td>
</tr>
Expand Down Expand Up @@ -370,7 +412,7 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
</td>
<td>
<div class="doc-md-description">
<p>If the parameters do not match the task's schema.</p>
<p>If the parameters or referenced objects fail validation.</p>
</div>
</td>
</tr>
Expand Down
4 changes: 4 additions & 0 deletions packages/evo-compute/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions packages/evo-compute/src/evo/compute/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -24,6 +26,9 @@
"JobProgress",
"JobStatusEnum",
"ParameterValidationError",
"ReferenceResolver",
"ResultNode",
"TaskResource",
"TaskResult",
"tasks",
]
34 changes: 34 additions & 0 deletions packages/evo-compute/src/evo/compute/discovery.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,23 +15,33 @@
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

from evo.common import APIConnector, IContext

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."""

Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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."""
Expand Down
70 changes: 50 additions & 20 deletions packages/evo-compute/src/evo/compute/engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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__ = [
Expand Down Expand Up @@ -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:
Expand All @@ -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__(
Expand All @@ -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 ------------------------------------------------- #

Expand Down Expand Up @@ -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.<topic>.<task>.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)}"
Expand All @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -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:
Expand Down
Loading
Loading