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
80 changes: 78 additions & 2 deletions mkdocs/site/packages/evo-compute/ComputeClient.html
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,41 @@ <h2 id="evo.compute.engine.ComputeClient" class="doc doc-heading">
<code><span title="evo.compute.discovery.DEFAULT_CACHE_TTL_SECONDS">DEFAULT_CACHE_TTL_SECONDS</span></code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>validate</code>
</td>
<td>
<code><span title="bool">bool</span></code>
</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>
</div>
</td>
<td>
<code>True</code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>deep_validation</code>
</td>
<td>
<code><span title="bool">bool</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Additionally run full JSON Schema Draft 2020-12 validation.
Defaults to <code>False</code>. Only consulted when <code>validate</code> is <code>True</code>.</p>
</div>
</td>
<td>
<code>False</code>
</td>
</tr>
</tbody>
</table>

Expand Down Expand Up @@ -173,7 +208,14 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
</span>

</h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">arun</span><span class="p">(</span><span class="n">topic</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">task</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">parameters</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">dict</span>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">arun</span><span class="p">(</span>
<span class="n">topic</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="n">task</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="n">parameters</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
<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>
</code></pre></div>

<div class="doc doc-contents ">
Expand Down Expand Up @@ -242,6 +284,40 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
<em>required</em>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>validate</code>
</td>
<td>
<code><span title="bool">bool</span> | None</code>
</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>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>deep_validation</code>
</td>
<td>
<code><span title="bool">bool</span> | None</code>
</td>
<td>
<div class="doc-md-description">
<p>Override the client's deep-validation setting for this call.
Only consulted when validation is enabled.</p>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
</tbody>
</table>

Expand Down Expand Up @@ -290,7 +366,7 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
</tr>
<tr class="doc-section-item">
<td>
<code>TypeError</code>
<code>ParameterValidationError</code>
</td>
<td>
<div class="doc-md-description">
Expand Down
1 change: 1 addition & 0 deletions packages/evo-compute/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ dependencies = [
"evo-blockmodels[utils]",
"evo-objects[utils,blockmodels]",
"evo-sdk-common",
"jsonschema>=4.18",
"pydantic>=2",
"typing_extensions>=4.0",
]
Expand Down
2 changes: 2 additions & 0 deletions packages/evo-compute/src/evo/compute/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,15 @@
from .discovery import DiscoveryClient
from .endpoints.models import TaskResource
from .engine import ComputeClient
from .exceptions import ParameterValidationError

__all__ = [
"ComputeClient",
"DiscoveryClient",
"JobClient",
"JobProgress",
"JobStatusEnum",
"ParameterValidationError",
"TaskResource",
"tasks",
]
50 changes: 44 additions & 6 deletions packages/evo-compute/src/evo/compute/engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@
from .client import JobClient
from .discovery import DEFAULT_CACHE_TTL_SECONDS, DiscoveryClient
from .endpoints.models import TaskResource
from .exceptions import ParameterValidationError
from .validation import validate_parameters

__all__ = [
"ComputeClient",
Expand Down Expand Up @@ -136,10 +138,12 @@ def _check_fallback_parameters(spec: TaskResource, parameters: dict[str, Any], l
properties: dict[str, Any] = schema.get("properties", {})
for name in schema.get("required", []):
if name not in parameters:
raise TypeError(f"{label}.run(): missing a required keyword-only argument: {name!r}")
detail = f"missing a required keyword-only argument: {name!r}"
raise ParameterValidationError(f"{label}.run(): {detail}", task=label, errors=[detail])
for name in parameters:
if name not in properties:
raise TypeError(f"{label}.run(): got an unexpected keyword argument {name!r}")
detail = f"got an unexpected keyword argument {name!r}"
raise ParameterValidationError(f"{label}.run(): {detail}", task=label, errors=[detail])


class ComputeClient:
Expand All @@ -150,12 +154,26 @@ 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 deep_validation: Additionally run full JSON Schema Draft 2020-12 validation.
Defaults to ``False``. Only consulted when ``validate`` is ``True``.
"""

def __init__(self, context: IContext, *, cache_ttl_seconds: float = DEFAULT_CACHE_TTL_SECONDS) -> None:
def __init__(
self,
context: IContext,
*,
cache_ttl_seconds: float = DEFAULT_CACHE_TTL_SECONDS,
validate: bool = True,
deep_validation: bool = False,
) -> None:
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._validate = validate
self._deep_validation = deep_validation

# -- dynamic namespace ------------------------------------------------- #

Expand Down Expand Up @@ -184,7 +202,15 @@ def _peek_spec(self, topic: str, task: str) -> TaskResource | None:

# -- execution --------------------------------------------------------- #

async def arun(self, topic: str, task: str, parameters: dict[str, Any]) -> dict:
async def arun(
self,
topic: str,
task: str,
parameters: dict[str, Any],
*,
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
Expand All @@ -193,19 +219,23 @@ async def arun(self, topic: str, task: str, parameters: dict[str, Any]) -> dict:
: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 deep_validation: Override the client's deep-validation setting for this call.
Only consulted when validation is enabled.

:return: The results of the finished job.

:raises AttributeError: If the topic does not advertise the task.
:raises TypeError: If the parameters do not match the task's schema.
:raises ParameterValidationError: If the parameters do not match the task's schema.
"""
spec = await self._resolve_spec(topic, task)
label = f"{topic}.{_normalise(task)}"
signature = _signature_from_schema(spec)
try:
bound = signature.bind(**parameters)
except TypeError as error:
raise TypeError(f"{label}.run(): {error}") from None
raise ParameterValidationError(f"{label}.run(): {error}", task=label, errors=[str(error)]) from None

# Forward only what the caller actually passed, so unset optionals fall back to the
# platform's own defaults while an explicit ``None`` still reaches the wire.
Expand All @@ -219,6 +249,14 @@ async def arun(self, topic: str, task: str, parameters: dict[str, Any]) -> dict:
if (spec.parameters or {}).get("properties"):
_check_fallback_parameters(spec, wire_parameters, label)

if validate is None:
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 validate:
validate_parameters(spec, wire_parameters, deep=deep_validation, task_label=label)

job: JobClient[dict] = await JobClient.submit(
connector=self._connector,
org_id=self._org_id,
Expand Down
13 changes: 13 additions & 0 deletions packages/evo-compute/src/evo/compute/exceptions.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,3 +67,16 @@ class JobPendingError(EvoClientException):

def __init__(self, url: str, status: str) -> None:
super().__init__(f"Job at {url} is still pending with status: {status}")


class ParameterValidationError(ValueError):
"""Raised when task parameters fail validation against the task's schema.

Subclasses :class:`ValueError`. :attr:`errors` holds one actionable message per
individual validation failure; :attr:`task` is the ``topic.task`` label when known.
"""

def __init__(self, message: str, *, task: str | None = None, errors: list[str] | None = None) -> None:
super().__init__(message)
self.task = task
self.errors = errors or []
Loading
Loading