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
212 changes: 34 additions & 178 deletions mkdocs/site/packages/evo-compute/ComputeClient.html
Original file line number Diff line number Diff line change
Expand Up @@ -147,12 +147,11 @@ <h2 id="evo.compute.engine.ComputeClient" class="doc doc-heading">
<td>
<div class="doc-md-description">
<p>Check the parameters against the task's JSON Schema before submitting
(required-field presence, and, under <code>deep_validation</code>, the whole payload).
(required-field presence, and, under <code>deep_validation</code>, known value constraints).
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>
still bound to the task's required arguments, and explicit extra-field rules
still apply. Custom runners also retain their own parameter checks.</p>
</div>
</td>
<td>
Expand All @@ -168,7 +167,7 @@ <h2 id="evo.compute.engine.ComputeClient" class="doc doc-heading">
</td>
<td>
<div class="doc-md-description">
<p>Additionally run full JSON Schema Draft 2020-12 validation.
<p>Additionally check the full JSON Schema Draft 2020-12 constraints.
Defaults to <code>False</code>. Only consulted when <code>validate</code> is <code>True</code>.</p>
</div>
</td>
Expand Down Expand Up @@ -218,6 +217,30 @@ <h2 id="evo.compute.engine.ComputeClient" class="doc doc-heading">



<div class="doc doc-object doc-attribute">



<h3 id="evo.compute.engine.ComputeClient.context" class="doc doc-heading">
<span class="doc doc-object-name doc-attribute-name">context</span>


<span class="doc doc-labels">
<small class="doc doc-label doc-label-property"><code>property</code></small>
</span>

</h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">context</span><span class="p">:</span> <span class="n">IContext</span>
</code></pre></div>

<div class="doc doc-contents ">

<p>The context used to submit tasks and load their results.</p>

</div>

</div>




Expand All @@ -241,183 +264,16 @@ <h3 id="evo.compute.engine.ComputeClient.arun" class="doc doc-heading">
<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="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>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Any</span>
</code></pre></div>

<div class="doc doc-contents ">

<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>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>topic</code>
</td>
<td>
<code><span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>The task topic.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>task</code>
</td>
<td>
<code><span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>The task name.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>parameters</code>
</td>
<td>
<code><span title="dict">dict</span>[<span title="str">str</span>, <span title="typing.Any">Any</span>]</code>
</td>
<td>
<div class="doc-md-description">
<p>The task parameters, plus <code>preview=True</code> to run a preview task.</p>
</div>
</td>
<td>
<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 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>
<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>
<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>


<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="evo.compute.outputs.TaskResult">TaskResult</span></code>
</td>
<td>
<div class="doc-md-description">
<p>The hydrated results of the finished job.</p>
</div>
</td>
</tr>
</tbody>
</table>


<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>AttributeError</code>
</td>
<td>
<div class="doc-md-description">
<p>If the topic does not advertise the task.</p>
</div>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>ParameterValidationError</code>
</td>
<td>
<div class="doc-md-description">
<p>If the parameters or referenced objects fail validation.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p>Run a task by name, using its custom runner when one is registered.</p>
<p>Parameters use the same names as <code>client.&lt;topic&gt;.&lt;task&gt;.run(...)</code>.
Custom tasks return their native result; other tasks return <code>TaskResult</code>.
Validation options override the client's settings for this call.
Preview is off unless <code>parameters</code> explicitly includes <code>preview=True</code>.</p>


</div>
Expand Down
34 changes: 34 additions & 0 deletions packages/evo-compute/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,33 @@ To get up and running quickly with the Evo Compute Task SDK, start by configurin

For some interactive Jupyter notebook examples, see the [examples folder](docs/examples).

### Running tasks through the generic engine

Authenticate and load inputs through the existing async SDK APIs, then use a client on
the same event loop:

```python
from evo.compute import ComputeClient

client = ComputeClient(manager)
result = await client.geostatistics.kriging.run(
source=samples.attributes["grade"],
target=target_model.attributes["kriged_grade"],
variogram=variogram,
neighborhood=search,
preview=True,
)
dataframe = await result.to_dataframe()
```

Kriging opts into a handwritten runner with additional checks and native `KrigingResult`.
Its arguments use the same names as other estimation tasks: `neighborhood` and
`kriging_method`. Other tasks use the schema-driven generic surface.
`client.arun(topic, task, parameters)` uses the same runner, argument names and result type
as the task's `run(...)` method, including for tasks absent from the snapshot.
Preview is off by default on every path; pass `preview=True` to opt in.
The existing lowercase task modules and `await tasks.run(manager, parameters)` API are unchanged.

### Static typing for the generic engine

`ComputeClient` resolves `client.<topic>.<task>.run(...)` from the live task catalogue, so
Expand All @@ -46,6 +73,13 @@ editors completion, signature help and parameter checking for every task in a ch
catalogue snapshot, while execution stays fully generic. See
[stubs/README.md](stubs/README.md) for how to regenerate it and refresh the snapshot.

For compatible neighborhood schemas, generated client signatures accept the
existing `SearchNeighborhood` model alongside schema-shaped dictionaries. Its native
`Ellipsoid`, ranges and rotation objects keep their existing serialization; the type hints
describe behavior the resolver already supports. Matching is based on serialized field
structure, not a task or schema name. Unrelated models and malformed dictionaries are still
rejected by the type checkers.

## Contributing

For instructions on contributing to the development of this library, please refer to the [evo-python-sdk documentation](https://github.com/seequentevo/evo-python-sdk).
Expand Down
24 changes: 22 additions & 2 deletions packages/evo-compute/src/evo/compute/_stubgen.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@

import argparse
import ast
import inspect
import json
import keyword
import re
Expand All @@ -47,6 +48,7 @@

from .endpoints.models import TaskResource
from .engine import _normalise, _wire_names
from .overrides import load_override, overridden_tasks

__all__ = [
"capture_snapshot",
Expand Down Expand Up @@ -480,7 +482,7 @@ def _run_parameters(self) -> list[str]:
annotation = self._annotation(properties.get(name, {}), schema, (name,))
default = "" if name in required else " = ..."
lines.append(f"{published[name]}: {annotation}{default}")
lines.append(f"preview: bool = {bool(self.spec.feature_flag)!r}")
lines.append("preview: bool = False")
return lines

def _return_type(self) -> str:
Expand Down Expand Up @@ -640,7 +642,7 @@ def _render_client(topics: list[str]) -> list[str]:
" validate: bool | None = ...,",
" deep_validation: bool | None = ...,",
" check_schemas: bool | None = ...,",
" ) -> TaskResult:",
" ) -> Any:",
_docstring(
"Run any task by name, including one this stub does not know about.",
" ",
Expand All @@ -654,19 +656,36 @@ def _render_client(topics: list[str]) -> list[str]:
return lines


def _override_runner(topic: str, task: str) -> tuple[str, str]:
module = load_override(topic, task)
assert module is not None, "only called for a task an override claims"
annotation = inspect.signature(module.bind).return_annotation
return module.__name__.removeprefix("evo.compute"), getattr(annotation, "__name__", annotation)


def _render(tasks: list[TaskResource], snapshot_dir: Path) -> str:
overridden = overridden_tasks()
stubs: list[_TaskStub] = []
override_imports: list[str] = []
members: dict[str, list[tuple[str, str]]] = {}

def remember(topic: str, attribute: str, class_name: str) -> None:
members.setdefault(topic, []).append((attribute, class_name))

for task in sorted(tasks, key=lambda task: (task.topic, task.name)):
attribute = _normalise(task.name)
if (_normalise(task.topic), attribute) in overridden:
continue
awaited = _TaskRenderer(task).render()
stubs.append(awaited)
remember(task.topic, attribute, awaited.class_name)

for topic, task_name in overridden:
class_name = f"_{_camel(topic)}{_camel(task_name)}"
module_path, runner_name = _override_runner(topic, task_name)
override_imports.append(f"from {module_path} import {runner_name} as {class_name}")
remember(topic, task_name, class_name)

blocks: list[str] = []
for stub in stubs:
blocks.extend(generated.body for generated in stub.types)
Expand Down Expand Up @@ -744,6 +763,7 @@ def remember(topic: str, attribute: str, class_name: str) -> None:
if "AnyTypedAttribute" in declared
else []
),
*override_imports,
]
),
]
Expand Down
Loading
Loading