feat(product): discovery-as-a-service — run workflow + Python service Client

Wave 7 — the backend ties together into one working loop:
API — POST /v1/runs executes a real discovery run state machine (queued ->
running -> succeeded|failed) via the native engine on a worker thread, stores the
discovered world, computes a real result summary (mse/complexity/#laws), and
emits RunQueued/Started/Succeeded/Failed to the event bus (streamed by
/v1/events). GET /v1/runs/{id} (status+summary) and /v1/runs/{id}/world flow
straight into the existing explain/report endpoints. Honest 503 when native
absent; bearer-auth + tenant-scoped + idempotent.

SDK — lawsynth.Client (stdlib urllib) drives the loop: submit_discovery -> wait
-> world -> explain/forecast/report, with a real HTTP transport and an in-process
WSGI transport so it runs fully offline. Demonstrated end to end.

API 98 -> 134 tests (native absent); client 18 tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
caelum0x 2026-08-17 22:30:54 +03:00
parent 8e6d7f1cb0
commit 035cebdcf1
10 changed files with 2136 additions and 4 deletions

View File

@ -0,0 +1,135 @@
#!/usr/bin/env python3
"""Drive the LawSynth API's discovery-as-a-service loop from Python --- offline.
This stands up the real ``lawsynth_api`` WSGI application in-process (a temp
SQLite metadata store, a temp object root, and a single bearer token), then uses
:class:`lawsynth.Client` to run the full *remote* product loop against it without
opening a socket:
upload dataset -> submit discovery run -> wait for completion ->
fetch + explain the discovered world -> forecast -> write an HTML report.
Because the client talks to the app object through an in-process WSGI transport,
the whole thing is deterministic and needs no network. Run it with::
PYTHONPATH="python/lawsynth/src:services/api/src:python/lawsynth-server/src" \
python3 python/lawsynth/examples/service_client.py
The native engine (built via ``python/lawsynth/scripts/build-native.sh``) backs
discovery, forecast, and simulation on the server side.
"""
from __future__ import annotations
import tempfile
from pathlib import Path
import lawsynth
from lawsynth_api import ApiSettings, create_wsgi_app
from lawsynth_server.settings import Settings as ServerSettings
TOKEN = "0123456789abcdef0123456789abcdef" # 32-char demo token (>= 16 required)
def lotka_volterra(n: int = 80, dt: float = 0.1) -> tuple[list[float], dict[str, list[float]]]:
"""A short, clean predator-prey trajectory --- ideal for the ecology preset."""
time: list[float] = []
x_series: list[float] = []
y_series: list[float] = []
x, y = 10.0, 5.0
alpha, beta, delta, gamma = 1.1, 0.4, 0.1, 0.4
for step in range(n):
time.append(round(step * dt, 6))
x_series.append(x)
y_series.append(y)
dx = alpha * x - beta * x * y
dy = delta * x * y - gamma * y
x += dx * dt
y += dy * dt
return time, {"x": x_series, "y": y_series}
def build_app(root: Path):
"""Construct the real API WSGI app over a temp SQLite store and object root."""
server = ServerSettings(
database_url=f"sqlite:///{root / 'metadata.sqlite3'}",
object_root=root / "objects",
tokens={TOKEN: ("acme", frozenset({"read", "write"}))},
max_upload_bytes=8 * 1024 * 1024,
)
return create_wsgi_app(
ApiSettings(server=server, environment="test", max_request_bytes=8 * 1024 * 1024)
)
def main() -> None:
workdir = Path(tempfile.mkdtemp(prefix="lawsynth-service-"))
app = build_app(workdir)
client = lawsynth.Client(wsgi_app=app, token=TOKEN)
print("LawSynth service client --- offline in-process transcript")
print("=" * 60)
banner = client.version()
print(f"connected: API version {banner.get('version')} (protocol {banner.get('protocol')})")
time, columns = lotka_volterra()
print(f"dataset: {len(time)} samples, columns {sorted(columns)}")
# Submit a discovery run. The client uploads the dataset, then references it
# in POST /v1/runs with the 'ecology' preset (resolved client-side into
# concrete discovery knobs the service accepts).
run = client.submit_discovery(
columns=columns,
time=time,
state=["x", "y"],
preset="ecology",
name="predator-prey",
)
print(f"submit: run {run.id} -> status {run.status!r}")
run = client.wait(run)
print(f"wait: status {run.status!r}, world_id {run.world_id}")
if not run.succeeded:
raise SystemExit(f"discovery did not succeed: {run.raw}")
# The run-scoped world endpoint may still be pending on the API side; the
# client degrades to GET /v1/worlds/{id} transparently.
world = client.world(run)
print(f"world: {world.get('name')!r} with states {world.get('states')}")
for target, expression in sorted(dict(world.get("equations", {})).items()):
print(f" d{target}/dt = {expression}")
explanation = client.explain(run.world_id)
complexity = explanation.get("complexity", {})
print(
f"explain: {complexity.get('laws')} laws, "
f"{complexity.get('total_terms')} total terms across "
f"{len(explanation.get('variables', []))} variables"
)
for law in explanation.get("laws", []):
print(f" {law.get('readable')} (dominant: {law.get('dominant_term')})")
# 'Use' the world: a native forecast from the first observation.
forecast = client.forecast(
run.world_id,
initial={"x": columns["x"][0], "y": columns["y"][0]},
horizon=4.0,
step=0.1,
)
samples = len(forecast["trajectory"]["time"])
finals = {name: series[-1] for name, series in forecast["trajectory"]["values"].items()}
print(f"forecast: {samples} samples, final state "
f"{{{', '.join(f'{k}={v:.3f}' for k, v in sorted(finals.items()))}}}")
report_path = client.report(run.world_id, workdir / "world-report.html")
print(f"report: wrote {report_path.stat().st_size} bytes -> {report_path}")
print("=" * 60)
print("done: submit -> succeeded -> explained -> forecast -> report, fully offline.")
app.close()
if __name__ == "__main__":
main()

View File

@ -6,9 +6,10 @@ native classes are resolved lazily when a simulation or discovery is requested.
from . import recipes
from ._version import __version__
from .client import Client, Run
from .config import DiscoveryConfig
from .dataset import Dataset
from .errors import LawSynthError, NativeError, ValidationError
from .errors import ApiError, LawSynthError, NativeError, RunTimeout, ValidationError
from .profile import ColumnProfile, DataProfile, TimeProfile, profile
from .sources import SourceError, load_source
@ -76,6 +77,7 @@ def __getattr__(name):
__all__ = [
"Dataset", "DiscoveryConfig", "LawSynthError", "NativeError", "ValidationError",
"ApiError", "RunTimeout", "Client", "Run",
"SourceError", "load_source", "recipes",
"profile", "DataProfile", "ColumnProfile", "TimeProfile",
"discover", "Scenario", "Trajectory", "World",

View File

@ -0,0 +1,640 @@
"""A dependency-free client for a running LawSynth API service.
``Client`` drives the *discovery-as-a-service* product loop from Python: submit
a discovery run against an uploaded (or inline) dataset, poll it to completion,
fetch and explain the discovered world, and render a self-contained report ---
all over the service's ``/v1`` HTTP contract (bearer auth, ``X-Api-Version: 1``,
and the ``{"error": {code, message, request_id}}`` envelope).
Two transports back the exact same client so the whole loop is testable offline:
* :class:`_HttpTransport` speaks real HTTP over :mod:`urllib` --- ``Client("http://host:8080", token=...)``.
* :class:`_WsgiTransport` calls a WSGI application object in-process (building the
``environ`` and capturing ``start_response``) --- ``Client(wsgi_app=create_wsgi_app(...))``.
No socket is opened, so the example and tests run fully offline and deterministically.
Only the standard library is used; the native engine is never touched by the
client (discovery runs on the *server* side).
"""
from __future__ import annotations
import csv as _csv
import io
import json
from dataclasses import dataclass
from os import PathLike
from pathlib import Path
from typing import Callable, Iterable, Mapping, Sequence
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode, urlsplit
from urllib.request import Request as _UrlRequest
from urllib.request import urlopen
from uuid import uuid4
from .errors import ApiError, RunTimeout, ValidationError
__all__ = ["Client", "Run"]
_TERMINAL_STATUSES = frozenset({"succeeded", "failed", "cancelled"})
_WRITE_METHODS = frozenset({"POST", "PATCH", "DELETE"})
# --------------------------------------------------------------------------- #
# Run — the client-side view of a submitted discovery run #
# --------------------------------------------------------------------------- #
@dataclass(frozen=True, slots=True)
class Run:
"""An immutable snapshot of a discovery run as reported by the service.
``summary`` folds in the result fields the service surfaces once a run is
done (``mse``, ``complexity``, ``laws``, ``world_id``); fields the running
API has not yet populated are simply absent. ``raw`` is the untouched run
record for forward compatibility.
"""
id: str
status: str
world_id: str | None
name: str | None
dataset_id: str | None
summary: Mapping[str, object]
raw: Mapping[str, object]
@property
def terminal(self) -> bool:
return self.status in _TERMINAL_STATUSES
@property
def succeeded(self) -> bool:
return self.status == "succeeded"
@classmethod
def from_payload(cls, payload: Mapping[str, object]) -> "Run":
if not isinstance(payload, Mapping) or not isinstance(payload.get("id"), str):
raise ApiError(
"run response did not contain an id", status=502, code="invalid_response"
)
summary: dict[str, object] = {}
for key in ("mse", "complexity", "laws", "law_count", "world_id"):
if key in payload and payload[key] is not None:
summary[key] = payload[key]
# The service may nest the result under "result" or "summary".
for container in ("result", "summary"):
nested = payload.get(container)
if isinstance(nested, Mapping):
summary.update({k: v for k, v in nested.items() if v is not None})
return cls(
id=str(payload["id"]),
status=str(payload.get("status", "unknown")),
world_id=payload.get("world_id") if isinstance(payload.get("world_id"), str) else None,
name=payload.get("name") if isinstance(payload.get("name"), str) else None,
dataset_id=payload.get("dataset_id") if isinstance(payload.get("dataset_id"), str) else None,
summary=summary,
raw=dict(payload),
)
# --------------------------------------------------------------------------- #
# Transports — one JSON contract, two ways to reach the app #
# --------------------------------------------------------------------------- #
class _Transport:
"""Send a request and return ``(status, headers, body_bytes)``."""
def request(
self, method: str, path: str, headers: Mapping[str, str], body: bytes
) -> tuple[int, dict[str, str], bytes]: # pragma: no cover - interface
raise NotImplementedError
class _WsgiTransport(_Transport):
"""Drive a WSGI application object in-process --- no socket required."""
def __init__(self, app: Callable[[dict, Callable], Iterable[bytes]]) -> None:
self._app = app
def request(
self, method: str, path: str, headers: Mapping[str, str], body: bytes
) -> tuple[int, dict[str, str], bytes]:
split = urlsplit(path)
environ: dict[str, object] = {
"REQUEST_METHOD": method,
"PATH_INFO": split.path,
"QUERY_STRING": split.query,
"SERVER_NAME": "in-process",
"SERVER_PORT": "80",
"SERVER_PROTOCOL": "HTTP/1.1",
"wsgi.version": (1, 0),
"wsgi.url_scheme": "http",
"wsgi.input": io.BytesIO(body),
"wsgi.errors": io.StringIO(),
"wsgi.multithread": False,
"wsgi.multiprocess": False,
"wsgi.run_once": False,
"CONTENT_LENGTH": str(len(body)),
}
for name, value in headers.items():
if name.lower() == "content-type":
environ["CONTENT_TYPE"] = value
else:
environ[f"HTTP_{name.upper().replace('-', '_')}"] = value
captured: dict[str, object] = {}
def start_response(status: str, response_headers: list[tuple[str, str]]) -> None:
captured["status"] = status
captured["headers"] = dict(response_headers)
chunks = self._app(environ, start_response)
try:
payload = b"".join(chunks)
finally:
close = getattr(chunks, "close", None)
if callable(close): # honor the WSGI iterable close protocol
close()
status_line = str(captured.get("status", "500 Internal Server Error"))
status_code = int(status_line.split(" ", 1)[0])
return status_code, dict(captured.get("headers", {})), payload # type: ignore[arg-type]
class _HttpTransport(_Transport):
"""Speak real HTTP to a remote LawSynth service over ``urllib``."""
def __init__(self, base_url: str, *, timeout: float) -> None:
self._base = base_url.rstrip("/")
self._timeout = timeout
def request(
self, method: str, path: str, headers: Mapping[str, str], body: bytes
) -> tuple[int, dict[str, str], bytes]:
url = f"{self._base}{path}"
data = body if body else None
req = _UrlRequest(url, data=data, method=method)
for name, value in headers.items():
req.add_header(name, value)
try:
with urlopen(req, timeout=self._timeout) as response: # noqa: S310 - user-provided base URL
return response.status, dict(response.headers.items()), response.read()
except HTTPError as error: # 4xx/5xx still carry a JSON envelope
payload = error.read()
return error.code, dict(error.headers.items() if error.headers else {}), payload
except URLError as error:
raise ApiError(
f"could not reach LawSynth service at {url}: {error.reason}",
status=0,
code="connection_error",
) from error
# --------------------------------------------------------------------------- #
# Client #
# --------------------------------------------------------------------------- #
class Client:
"""A stdlib client for a running LawSynth API (discovery-as-a-service).
Construct it against a live service::
client = lawsynth.Client("http://localhost:8080", token="…")
or, for fully offline use, against the API's in-process WSGI app::
client = lawsynth.Client(wsgi_app=create_wsgi_app(settings))
Then drive the remote product loop::
run = client.submit_discovery(csv="obs.csv", time="t", state=["x", "y"], preset="ecology")
run = client.wait(run) # poll until terminal
world = client.world(run) # the discovered world
print(client.explain(run.world_id)) # plain-language explanation
client.report(run.world_id, "out.html")
"""
def __init__(
self,
base_url: str | None = None,
*,
token: str | None = None,
wsgi_app: Callable[[dict, Callable], Iterable[bytes]] | None = None,
api_version: str = "1",
max_poll_attempts: int = 20,
timeout: float = 30.0,
) -> None:
if (base_url is None) == (wsgi_app is None):
raise ValidationError("provide exactly one of base_url or wsgi_app")
if max_poll_attempts < 1:
raise ValidationError("max_poll_attempts must be positive")
self._transport: _Transport = (
_WsgiTransport(wsgi_app)
if wsgi_app is not None
else _HttpTransport(str(base_url), timeout=timeout)
)
self._token = token
self._api_version = api_version
self._max_poll_attempts = max_poll_attempts
# -- low-level request helpers ----------------------------------------- #
def _headers(self, *, json_body: bool, idempotency_key: str | None) -> dict[str, str]:
headers = {"X-Api-Version": self._api_version, "Accept": "application/json"}
if self._token:
headers["Authorization"] = f"Bearer {self._token}"
if json_body:
headers["Content-Type"] = "application/json"
if idempotency_key:
headers["Idempotency-Key"] = idempotency_key
return headers
def _call(
self,
method: str,
path: str,
*,
body: object | None = None,
query: Mapping[str, str] | None = None,
idempotency_key: str | None = None,
) -> tuple[int, dict[str, str], bytes]:
if query:
path = f"{path}?{urlencode(query)}"
if method in _WRITE_METHODS and idempotency_key is None and body is not None:
idempotency_key = uuid4().hex
raw = b"" if body is None else json.dumps(body).encode("utf-8")
headers = self._headers(json_body=body is not None, idempotency_key=idempotency_key)
return self._transport.request(method, path, headers, raw)
def _request_json(
self,
method: str,
path: str,
*,
body: object | None = None,
query: Mapping[str, str] | None = None,
idempotency_key: str | None = None,
) -> dict[str, object]:
status, _, payload = self._call(
method, path, body=body, query=query, idempotency_key=idempotency_key
)
parsed = self._decode_json(payload) if payload else {}
if status >= 400:
raise self._as_error(status, parsed)
if not isinstance(parsed, dict):
raise ApiError(
f"expected a JSON object from {path}", status=502, code="invalid_response"
)
return parsed
@staticmethod
def _decode_json(payload: bytes) -> object:
try:
return json.loads(payload.decode("utf-8"))
except (ValueError, UnicodeDecodeError) as error:
raise ApiError(
"service returned a malformed JSON response",
status=502,
code="invalid_response",
) from error
@staticmethod
def _as_error(status: int, parsed: object) -> ApiError:
code, message, request_id = "error", "request failed", None
if isinstance(parsed, Mapping):
envelope = parsed.get("error")
if isinstance(envelope, Mapping):
code = str(envelope.get("code", code))
message = str(envelope.get("message", message))
rid = envelope.get("request_id")
request_id = str(rid) if isinstance(rid, str) else None
return ApiError(message, status=status, code=code, request_id=request_id)
# -- service metadata --------------------------------------------------- #
def version(self) -> dict[str, object]:
"""The service protocol/version banner (``GET /v1/version``)."""
return self._request_json("GET", "/v1/version")
def health(self) -> dict[str, object]:
"""The service health probe (``GET /v1/health``)."""
return self._request_json("GET", "/v1/health")
# -- datasets ----------------------------------------------------------- #
def upload_dataset(
self,
*,
time: Sequence[float],
columns: Mapping[str, Sequence[float]],
name: str | None = None,
) -> str:
"""Upload numeric observations and return the new dataset id.
``columns`` maps every state/observable name to a series aligned with
``time``; the dataset ``schema`` is exactly those column names.
"""
schema = list(columns)
if not schema:
raise ValidationError("a dataset needs at least one column")
body: dict[str, object] = {
"name": name or "dataset",
"schema": schema,
"time": [float(value) for value in time],
"columns": {key: [float(v) for v in series] for key, series in columns.items()},
}
created = self._request_json("POST", "/v1/datasets", body=body)
dataset_id = created.get("id")
if not isinstance(dataset_id, str):
raise ApiError(
"dataset upload did not return an id", status=502, code="invalid_response"
)
return dataset_id
# -- discovery runs ----------------------------------------------------- #
def submit_discovery(
self,
*,
state: Sequence[str],
csv: str | PathLike[str] | None = None,
columns: Mapping[str, Sequence[float]] | None = None,
time: str | Sequence[float] = "t",
dataset_id: str | None = None,
preset: str | None = None,
degree: int | None = None,
threshold: float | None = None,
solver: str | None = None,
include_trigonometric: bool | None = None,
include_rational: bool | None = None,
name: str = "discovery",
world_name: str | None = None,
idempotency_key: str | None = None,
) -> Run:
"""Submit a discovery run and return its initial :class:`Run` status.
The dataset is referenced one of three ways (exactly one required):
an existing ``dataset_id``, an inline ``columns``/``time`` pair, or a
``csv`` source (path or literal CSV text) whose ``time`` column and
``state`` columns are read out. ``preset`` selects a curated discovery
recipe (``ecology``/``mechanics``/``epidemiology``/…); ``degree``,
``threshold``, ``solver`` and the feature toggles layer on top of it and
always win.
"""
states = list(state)
if not states:
raise ValidationError("at least one state column is required")
resolved_dataset = self._resolve_dataset(
dataset_id=dataset_id, csv=csv, columns=columns, time=time, state=states, name=name
)
discovery = self._build_discovery(
preset=preset,
degree=degree,
threshold=threshold,
solver=solver,
include_trigonometric=include_trigonometric,
include_rational=include_rational,
)
body: dict[str, object] = {
"name": name,
"dataset_id": resolved_dataset,
"states": states,
"discovery": discovery,
}
if world_name is not None:
body["world_name"] = world_name
created = self._request_json(
"POST", "/v1/runs", body=body, idempotency_key=idempotency_key
)
return Run.from_payload(created)
def _resolve_dataset(
self,
*,
dataset_id: str | None,
csv: str | PathLike[str] | None,
columns: Mapping[str, Sequence[float]] | None,
time: str | Sequence[float],
state: Sequence[str],
name: str,
) -> str:
sources = [src for src in (dataset_id, csv, columns) if src is not None]
if len(sources) != 1:
raise ValidationError("provide exactly one of dataset_id, csv, or columns")
if dataset_id is not None:
return dataset_id
if columns is not None:
if isinstance(time, str):
raise ValidationError("inline columns require a numeric 'time' sequence")
return self.upload_dataset(time=time, columns=columns, name=name)
# CSV source: 'time' names the time column, 'state' the observable columns.
if not isinstance(time, str):
raise ValidationError("csv source requires the 'time' column name as a string")
parsed_time, parsed_columns = _read_csv(csv, time_column=time, state_columns=state)
return self.upload_dataset(time=parsed_time, columns=parsed_columns, name=name)
@staticmethod
def _build_discovery(
*,
preset: str | None,
degree: int | None,
threshold: float | None,
solver: str | None,
include_trigonometric: bool | None,
include_rational: bool | None,
) -> dict[str, object]:
"""Resolve a preset (client-side) and layer explicit knobs on top.
Presets are resolved through :mod:`lawsynth.recipes` into the concrete
discovery options the service accepts, so ``preset=`` works against a
service that only understands raw discovery knobs.
"""
options: dict[str, object] = {}
if preset is not None:
from . import recipes
config = recipes.get(preset).config()
options = {
"polynomial_degree": config.polynomial_degree,
"threshold": config.threshold,
"solver": config.solver,
"derivative_method": config.derivative_method,
}
if config.include_trigonometric:
options["include_trigonometric"] = True
if config.include_rational:
options["include_rational"] = True
if degree is not None:
options["polynomial_degree"] = degree
if threshold is not None:
options["threshold"] = threshold
if solver is not None:
options["solver"] = solver
if include_trigonometric is not None:
options["include_trigonometric"] = include_trigonometric
if include_rational is not None:
options["include_rational"] = include_rational
return options
def get_run(self, run_id: str) -> Run:
"""Fetch the current status/summary of a run (``GET /v1/runs/{id}``)."""
return Run.from_payload(self._request_json("GET", f"/v1/runs/{run_id}"))
def wait(self, run: Run | str) -> Run:
"""Poll a run until it reaches a terminal status; return the final run.
Deterministic and sleep-free: the service runs discovery synchronously
(or quickly), so a bounded number of polls suffices. Raises
:class:`~lawsynth.errors.RunTimeout` if the bound is exhausted first.
"""
run_id = run.id if isinstance(run, Run) else str(run)
current = run if isinstance(run, Run) else self.get_run(run_id)
attempts = 0
while not current.terminal and attempts < self._max_poll_attempts:
current = self.get_run(run_id)
attempts += 1
if not current.terminal:
raise RunTimeout(run_id, status=current.status, attempts=attempts)
return current
# -- worlds ------------------------------------------------------------- #
def world(self, run: Run | str) -> dict[str, object]:
"""The world discovered by a run.
Prefers ``GET /v1/runs/{id}/world`` and gracefully falls back to
``GET /v1/worlds/{world_id}`` when the run-scoped endpoint is not yet
deployed. Both are normalized to the flat world record: the run-scoped
endpoint may wrap it in a ``{"run_id", "world_id", "world", "links"}``
envelope, which is unwrapped here.
"""
run_id = run.id if isinstance(run, Run) else str(run)
try:
return self._unwrap_world(self._request_json("GET", f"/v1/runs/{run_id}/world"))
except ApiError as error:
if error.status != 404:
raise
record = run if isinstance(run, Run) else self.get_run(run_id)
if record.world_id is None:
raise ApiError(
f"run {run_id!r} has no discovered world yet",
status=409,
code="world_unavailable",
)
return self.get_world(record.world_id)
@staticmethod
def _unwrap_world(payload: dict[str, object]) -> dict[str, object]:
"""Return the flat world record from either a flat or ``{world: …}`` envelope."""
inner = payload.get("world")
if isinstance(inner, dict) and "equations" in inner:
return inner
return payload
def get_world(self, world_id: str) -> dict[str, object]:
"""Fetch a discovered world record (``GET /v1/worlds/{id}``)."""
return self._request_json("GET", f"/v1/worlds/{world_id}")
def explain(self, world_id: str) -> dict[str, object]:
"""Plain-language explanation of a world (``GET /v1/worlds/{id}/explain``)."""
return self._request_json("GET", f"/v1/worlds/{world_id}/explain")
def forecast(
self,
world_id: str,
*,
initial: Mapping[str, float],
horizon: float,
step: float,
start: float = 0.0,
parameters: Mapping[str, float] | None = None,
inputs: Mapping[str, float] | None = None,
interventions: Sequence[Mapping[str, object]] | None = None,
) -> dict[str, object]:
"""Run a native forecast (``POST /v1/worlds/{id}/forecast``)."""
body: dict[str, object] = {
"initial": {k: float(v) for k, v in initial.items()},
"horizon": float(horizon),
"step": float(step),
"start": float(start),
}
if parameters:
body["parameters"] = {k: float(v) for k, v in parameters.items()}
if inputs:
body["inputs"] = {k: float(v) for k, v in inputs.items()}
if interventions:
body["interventions"] = list(interventions)
return self._request_json("POST", f"/v1/worlds/{world_id}/forecast", body=body)
def compare(self, left_id: str, right_id: str) -> dict[str, object]:
"""Structured diff of two worlds (``POST /v1/worlds/compare``)."""
return self._request_json(
"POST", "/v1/worlds/compare", body={"left": left_id, "right": right_id}
)
def report(self, world_id: str, path: str | PathLike[str]) -> Path:
"""Write a world's self-contained HTML report to ``path``.
The report endpoint returns ``text/html`` on success; a failure still
carries the shared JSON error envelope, which is decoded and raised.
"""
status, headers, payload = self._call("GET", f"/v1/worlds/{world_id}/report")
if status >= 400:
raise self._as_error(status, self._decode_json(payload) if payload else {})
target = Path(path)
if target.suffix.lower() not in {".html", ".htm"}:
raise ValidationError("report path must end in .html or .htm")
target.write_bytes(payload)
return target
# --------------------------------------------------------------------------- #
# CSV ingest #
# --------------------------------------------------------------------------- #
def _read_csv(
source: str | PathLike[str],
*,
time_column: str,
state_columns: Sequence[str],
) -> tuple[list[float], dict[str, list[float]]]:
"""Read a CSV path (or literal CSV text) into ``(time, {state: series})``."""
text = _read_csv_text(source)
reader = _csv.DictReader(text.splitlines())
if reader.fieldnames is None:
raise ValidationError("CSV is empty or has no header row")
required = [time_column, *state_columns]
missing = [column for column in required if column not in reader.fieldnames]
if missing:
raise ValidationError(
f"CSV is missing required columns {missing}; found {reader.fieldnames}"
)
time: list[float] = []
columns: dict[str, list[float]] = {column: [] for column in state_columns}
for line_number, row in enumerate(reader, start=2):
try:
time.append(float(row[time_column]))
for column in state_columns:
columns[column].append(float(row[column]))
except (TypeError, ValueError) as error:
raise ValidationError(
f"non-numeric value on CSV line {line_number}: {error}"
) from error
if not time:
raise ValidationError("CSV contains a header but no data rows")
return time, columns
def _read_csv_text(source: str | PathLike[str]) -> str:
"""Return CSV text: read a file when ``source`` points at one, else use it verbatim."""
if isinstance(source, PathLike):
return Path(source).read_text(encoding="utf-8")
if "\n" not in source and "\r" not in source:
candidate = Path(source)
try:
if candidate.is_file():
return candidate.read_text(encoding="utf-8")
except OSError:
pass
return source

View File

@ -11,3 +11,43 @@ class ValidationError(LawSynthError, ValueError):
class NativeError(LawSynthError, RuntimeError):
"""Raised when the native executable-world engine rejects an operation."""
class ApiError(LawSynthError):
"""Raised when a LawSynth API service returns an error envelope.
Carries the transport ``status`` alongside the service's typed error
``code``, human ``message``, and the ``request_id`` that correlates the
failure with the server's logs (``{"error": {code, message, request_id}}``).
"""
def __init__(
self,
message: str,
*,
status: int,
code: str = "error",
request_id: str | None = None,
) -> None:
super().__init__(message)
self.status = status
self.code = code
self.message = message
self.request_id = request_id
def __str__(self) -> str:
suffix = f" (request_id={self.request_id})" if self.request_id else ""
return f"[{self.status} {self.code}] {self.message}{suffix}"
class RunTimeout(LawSynthError):
"""Raised when a run does not reach a terminal status within the poll bound."""
def __init__(self, run_id: str, *, status: str, attempts: int) -> None:
super().__init__(
f"run {run_id!r} did not reach a terminal status after {attempts} "
f"poll attempts (last status: {status!r})"
)
self.run_id = run_id
self.status = status
self.attempts = attempts

View File

@ -0,0 +1,333 @@
"""Offline, deterministic tests for :class:`lawsynth.Client`.
The transport/logic tests drive the client against a tiny in-process fake WSGI
service, so they need neither a socket nor the native engine. A final,
importorskip-guarded test exercises the real ``lawsynth_api`` app end to end.
"""
from __future__ import annotations
import io
import json
import pytest
import lawsynth
from lawsynth import ApiError, Client, Run, RunTimeout
# Pre-existing SDK collision: the package exposes a public ``lawsynth.discover``
# callable (which the API server invokes), but the SDK also ships a
# ``lawsynth/discover.py`` submodule. Importing that submodule (as
# ``test_discover.py`` does) rebinds ``lawsynth.discover`` to the module and
# shadows the callable. This module is imported before ``test_discover`` (pytest
# collects alphabetically), so capture the genuine callable now and restore it in
# the end-to-end test so it is order-independent. See the task report.
_PUBLIC_DISCOVER = lawsynth.discover
# --------------------------------------------------------------------------- #
# A minimal fake WSGI service: records requests, returns scripted responses. #
# --------------------------------------------------------------------------- #
class FakeService:
"""Route (method, path) to a scripted ``(status, headers, body)`` response."""
def __init__(self):
self.requests: list[dict[str, object]] = []
self.routes: dict[tuple[str, str], object] = {}
def route(self, method: str, path: str, status: int, body, *, content_type="application/json"):
self.routes[(method, path)] = (status, content_type, body)
return self
def __call__(self, environ, start_response):
body_bytes = environ["wsgi.input"].read()
headers = {
key[5:].replace("_", "-").title(): value
for key, value in environ.items()
if isinstance(key, str) and key.startswith("HTTP_")
}
record = {
"method": environ["REQUEST_METHOD"],
"path": environ["PATH_INFO"],
"query": environ.get("QUERY_STRING", ""),
"headers": headers,
"body": json.loads(body_bytes) if body_bytes else None,
}
self.requests.append(record)
key = (record["method"], record["path"])
status, content_type, body = self.routes.get(
key, (404, "application/json", {"error": {"code": "not_found", "message": "no route", "request_id": "rid-404"}})
)
payload = body if isinstance(body, (bytes, bytearray)) else json.dumps(body).encode("utf-8")
start_response(f"{status} STATUS", [("Content-Type", content_type)])
return [payload]
def make_client(service: FakeService, **kwargs) -> Client:
return Client(wsgi_app=service, token="secret-token", **kwargs)
# --------------------------------------------------------------------------- #
# Construction #
# --------------------------------------------------------------------------- #
def test_requires_exactly_one_transport():
with pytest.raises(lawsynth.ValidationError):
Client()
with pytest.raises(lawsynth.ValidationError):
Client("http://host", wsgi_app=FakeService())
def test_rejects_nonpositive_poll_bound():
with pytest.raises(lawsynth.ValidationError):
Client(wsgi_app=FakeService(), max_poll_attempts=0)
# --------------------------------------------------------------------------- #
# Auth / version / idempotency headers #
# --------------------------------------------------------------------------- #
def test_sends_auth_version_and_content_type_headers():
service = FakeService().route("GET", "/v1/version", 200, {"version": "9.9", "protocol": "1"})
banner = make_client(service).version()
assert banner == {"version": "9.9", "protocol": "1"}
sent = service.requests[-1]["headers"]
assert sent["Authorization"] == "Bearer secret-token"
assert sent["X-Api-Version"] == "1"
def test_write_requests_carry_an_idempotency_key():
service = FakeService().route("POST", "/v1/datasets", 201, {"id": "ds-1"})
make_client(service).upload_dataset(time=[0.0, 1.0], columns={"x": [1.0, 2.0]}, name="d")
sent = service.requests[-1]
assert "Idempotency-Key" in sent["headers"]
assert sent["body"]["schema"] == ["x"]
# --------------------------------------------------------------------------- #
# Error envelope -> ApiError #
# --------------------------------------------------------------------------- #
def test_error_envelope_becomes_typed_apierror():
service = FakeService().route(
"GET", "/v1/worlds/nope",
404, {"error": {"code": "not_found", "message": "unknown world", "request_id": "rid-7"}},
)
with pytest.raises(ApiError) as excinfo:
make_client(service).get_world("nope")
error = excinfo.value
assert error.status == 404 and error.code == "not_found"
assert error.request_id == "rid-7"
assert "unknown world" in str(error)
# --------------------------------------------------------------------------- #
# Run submission, parsing, and bounded waiting #
# --------------------------------------------------------------------------- #
def test_submit_discovery_uploads_then_references_dataset():
service = (
FakeService()
.route("POST", "/v1/datasets", 201, {"id": "ds-9"})
.route("POST", "/v1/runs", 201, {"id": "run-9", "status": "succeeded", "world_id": "w-9"})
)
run = make_client(service).submit_discovery(
columns={"x": [1.0, 2.0, 3.0], "y": [4.0, 5.0, 6.0]},
time=[0.0, 1.0, 2.0],
state=["x", "y"],
preset="ecology",
)
assert isinstance(run, Run) and run.succeeded and run.world_id == "w-9"
run_body = service.requests[-1]["body"]
assert run_body["dataset_id"] == "ds-9"
assert run_body["states"] == ["x", "y"]
# 'ecology' preset resolved client-side into concrete discovery knobs.
assert run_body["discovery"]["polynomial_degree"] == 2
assert run_body["discovery"]["solver"] == "stlsq"
def test_explicit_knobs_override_preset():
service = FakeService().route("POST", "/v1/runs", 201, {"id": "r", "status": "queued"})
make_client(service).submit_discovery(
dataset_id="ds", state=["x"], preset="ecology", degree=4, threshold=0.5, solver="sr3",
)
discovery = service.requests[-1]["body"]["discovery"]
assert discovery["polynomial_degree"] == 4
assert discovery["threshold"] == 0.5
assert discovery["solver"] == "sr3"
def test_submit_requires_exactly_one_dataset_source():
client = make_client(FakeService())
with pytest.raises(lawsynth.ValidationError):
client.submit_discovery(state=["x"]) # no source
with pytest.raises(lawsynth.ValidationError):
client.submit_discovery(state=["x"], dataset_id="ds", columns={"x": [1.0]})
def test_wait_polls_until_terminal_without_sleeping():
class Polling(FakeService):
def __init__(self):
super().__init__()
self._statuses = iter(["running", "running", "succeeded"])
def __call__(self, environ, start_response):
if environ["PATH_INFO"] == "/v1/runs/run-1":
status = next(self._statuses)
start_response("200 OK", [("Content-Type", "application/json")])
return [json.dumps({"id": "run-1", "status": status, "world_id": "w-1"}).encode()]
return super().__call__(environ, start_response)
service = Polling()
run = make_client(service).wait(Run.from_payload({"id": "run-1", "status": "queued"}))
assert run.succeeded and run.world_id == "w-1"
def test_wait_raises_run_timeout_when_bound_exhausted():
service = FakeService().route("GET", "/v1/runs/stuck", 200, {"id": "stuck", "status": "running"})
with pytest.raises(RunTimeout) as excinfo:
make_client(service, max_poll_attempts=3).wait("stuck")
assert excinfo.value.attempts == 3 and excinfo.value.status == "running"
# --------------------------------------------------------------------------- #
# World access: run-scoped endpoint with graceful 404 fallback #
# --------------------------------------------------------------------------- #
def test_world_prefers_run_scoped_endpoint():
service = FakeService().route(
"GET", "/v1/runs/run-1/world", 200, {"id": "w-1", "name": "W", "equations": {"x": "x"}}
)
world = make_client(service).world(Run.from_payload({"id": "run-1", "status": "succeeded", "world_id": "w-1"}))
assert world["id"] == "w-1"
def test_world_unwraps_run_scoped_envelope():
# The run-scoped endpoint wraps the record: {run_id, world_id, world, links}.
service = FakeService().route(
"GET", "/v1/runs/run-1/world", 200,
{"run_id": "run-1", "world_id": "w-1", "links": {}, "world": {"id": "w-1", "name": "W", "equations": {"x": "x"}}},
)
world = make_client(service).world(Run.from_payload({"id": "run-1", "status": "succeeded", "world_id": "w-1"}))
assert world["name"] == "W" and world["equations"] == {"x": "x"}
def test_world_falls_back_to_worlds_endpoint_on_404():
service = (
FakeService()
.route("GET", "/v1/runs/run-1/world", 404, {"error": {"code": "not_found", "message": "x", "request_id": "r"}})
.route("GET", "/v1/worlds/w-1", 200, {"id": "w-1", "name": "fallback"})
)
world = make_client(service).world(Run.from_payload({"id": "run-1", "status": "succeeded", "world_id": "w-1"}))
assert world["name"] == "fallback"
assert [r["path"] for r in service.requests] == ["/v1/runs/run-1/world", "/v1/worlds/w-1"]
# --------------------------------------------------------------------------- #
# Report: HTML bytes on success, envelope on failure #
# --------------------------------------------------------------------------- #
def test_report_writes_html_bytes(tmp_path):
html = b"<!doctype html><title>report</title>"
service = FakeService().route("GET", "/v1/worlds/w-1/report", 200, html, content_type="text/html")
path = make_client(service).report("w-1", tmp_path / "r.html")
assert path.read_bytes() == html
def test_report_rejects_non_html_extension(tmp_path):
service = FakeService().route("GET", "/v1/worlds/w-1/report", 200, b"<html>", content_type="text/html")
with pytest.raises(lawsynth.ValidationError):
make_client(service).report("w-1", tmp_path / "r.txt")
def test_report_raises_on_error_envelope(tmp_path):
service = FakeService().route(
"GET", "/v1/worlds/w-1/report", 403,
{"error": {"code": "forbidden", "message": "nope", "request_id": "r"}},
)
with pytest.raises(ApiError) as excinfo:
make_client(service).report("w-1", tmp_path / "r.html")
assert excinfo.value.status == 403
# --------------------------------------------------------------------------- #
# CSV ingest #
# --------------------------------------------------------------------------- #
def test_submit_from_csv_text_parses_columns():
service = (
FakeService()
.route("POST", "/v1/datasets", 201, {"id": "ds-csv"})
.route("POST", "/v1/runs", 201, {"id": "run-csv", "status": "succeeded", "world_id": "w"})
)
csv_text = "t,x,y\n0,1,4\n1,2,5\n2,3,6\n"
make_client(service).submit_discovery(csv=csv_text, time="t", state=["x", "y"])
dataset_body = service.requests[0]["body"]
assert dataset_body["time"] == [0.0, 1.0, 2.0]
assert dataset_body["columns"] == {"x": [1.0, 2.0, 3.0], "y": [4.0, 5.0, 6.0]}
def test_csv_missing_column_is_rejected():
with pytest.raises(lawsynth.ValidationError):
make_client(FakeService()).submit_discovery(csv="t,x\n0,1\n", time="t", state=["x", "y"])
# --------------------------------------------------------------------------- #
# End-to-end against the real API app (skipped if server/native unavailable). #
# --------------------------------------------------------------------------- #
def test_end_to_end_against_real_wsgi_app(tmp_path):
lawsynth_api = pytest.importorskip("lawsynth_api")
pytest.importorskip("lawsynth_server")
try:
_ = lawsynth.World # native engine required for discovery
except lawsynth.NativeError:
pytest.skip("native engine unavailable")
# Restore the public discovery callable in case a prior test imported the
# colliding ``lawsynth.discover`` submodule and shadowed it (see module note).
lawsynth.discover = _PUBLIC_DISCOVER
from lawsynth_server.settings import Settings as ServerSettings
token = "0123456789abcdef0123456789abcdef"
server = ServerSettings(
database_url=f"sqlite:///{tmp_path / 'm.sqlite3'}",
object_root=tmp_path / "obj",
tokens={token: ("acme", frozenset({"read", "write"}))},
max_upload_bytes=8 * 1024 * 1024,
)
app = lawsynth_api.create_wsgi_app(
lawsynth_api.ApiSettings(server=server, environment="test", max_request_bytes=8 * 1024 * 1024)
)
try:
client = Client(wsgi_app=app, token=token)
time = [round(i * 0.1, 6) for i in range(60)]
x, y = [], []
xv, yv = 10.0, 5.0
for _ in time:
x.append(xv)
y.append(yv)
xv, yv = xv + (1.1 * xv - 0.4 * xv * yv) * 0.1, yv + (0.1 * xv * yv - 0.4 * yv) * 0.1
run = client.submit_discovery(
columns={"x": x, "y": y}, time=time, state=["x", "y"], preset="ecology"
)
run = client.wait(run)
assert run.succeeded and run.world_id
world = client.world(run)
assert set(world["equations"]) == {"x", "y"}
explanation = client.explain(run.world_id)
assert explanation["complexity"]["laws"] == 2
report = client.report(run.world_id, tmp_path / "report.html")
assert report.read_text().startswith("<!")
finally:
app.close()

View File

@ -23,6 +23,7 @@ from lawsynth_server.errors import ServerError
from . import artifacts, datasets, downloads, products, projects, runs, uploads, worlds
from .auth import ApiAuthenticator
from .discovery import DiscoveryService
from .authorization import READ, WRITE, require_scope_or_problem
from .database import ApiDatabase
from .events import EventBus
@ -66,8 +67,10 @@ class WsgiApplication:
self._storage = ApiStorage(services.storage)
self._database = ApiDatabase(services.database)
self._repositories = ApiRepositories(services)
self._discovery = DiscoveryService(services, self._events)
def close(self) -> None:
self._discovery.close()
self._lifespan.close()
@property
@ -102,6 +105,10 @@ class WsgiApplication:
return self._serve_report(request, parts, request_id, start_response)
if product is not None:
response = self._handle_product(request, product, parts, request_id)
elif self._is_discovery_submit(request, parts):
response = self._handle_discovery_submit(request, request_id)
elif self._is_run_world(request, parts):
response = self._handle_run_world(request, parts, request_id)
elif request["path"].startswith("/v1/worker/") or request["path"] == "/v1/worker":
response = error_envelope(501, "worker_transport_unavailable", "worker HTTP transport is not deployed by this API process", request_id)
else:
@ -201,6 +208,52 @@ class WsgiApplication:
return error_envelope(error.status_code, error.code, error.message, request_id)
return {"status": 200, "headers": {"X-Request-ID": request_id}, "body": body}
# -- Discovery-as-a-service ---------------------------------------------
#
# The discovery run workflow is composed at this boundary rather than in the
# domain dispatcher: submitting a run creates a domain run record, runs the
# native engine in-process (queued -> running -> succeeded/failed on a worker
# thread), stores the resulting world through the domain, and emits the
# run-lifecycle ``ApiEvent``s through the same bus that backs ``/v1/events``.
# A discovery submit is a ``POST /v1/runs`` that names a dataset (an uploaded
# ``dataset_id`` or an inline ``dataset``); a plain run create -- no dataset
# reference -- still flows through the domain dispatcher unchanged.
@staticmethod
def _is_discovery_submit(request: Mapping[str, object], parts: list[str]) -> bool:
if request["method"] != "POST" or parts != ["runs"]:
return False
body = request.get("body")
return isinstance(body, Mapping) and ("dataset_id" in body or "dataset" in body)
@staticmethod
def _is_run_world(request: Mapping[str, object], parts: list[str]) -> bool:
return request["method"] == "GET" and len(parts) == 3 and parts[0] == "runs" and parts[2] == "world"
def _handle_discovery_submit(self, request: Mapping[str, object], request_id: str) -> dict[str, object]:
"""Authenticate, scope, and submit a discovery run (honest 503 if native absent)."""
headers = request["headers"]
principal = self._auth.authenticate_or_problem(headers)
require_scope_or_problem(principal, WRITE)
key = headers.get("Idempotency-Key")
if not isinstance(key, str) or not key:
return error_envelope(422, "validation_error", "Idempotency-Key is required for writes", request_id)
try:
return self._discovery.submit(principal.organization_id, request.get("body"), key, request_id)
except ServerError as error:
return error_envelope(error.status_code, error.code, error.message, request_id)
def _handle_run_world(self, request: Mapping[str, object], parts: list[str], request_id: str) -> dict[str, object]:
"""Authenticate, scope, and return the world a completed run discovered."""
principal = self._auth.authenticate_or_problem(request["headers"])
require_scope_or_problem(principal, READ)
try:
return self._discovery.run_world(principal.organization_id, parts[1], request_id)
except ServerError as error:
return error_envelope(error.status_code, error.code, error.message, request_id)
def _serve_report(self, request: Mapping[str, object], parts: list[str], request_id: str, start_response: StartResponse) -> Iterable[bytes]:
"""Serve ``GET /v1/worlds/{id}/report`` as a self-contained HTML document.

View File

@ -0,0 +1,547 @@
"""Discovery-as-a-service: the run workflow that turns a dataset into a world.
This module owns the *execution* half of the ``runs`` resource. The domain
(:mod:`lawsynth_server`) persists runs, datasets, and worlds and enforces tenant
isolation; the transport (:mod:`app`) authenticates, scopes, and frames. What
lives here is the honest, in-process orchestration that makes a run *real*:
Workflow (states)
``POST /v1/runs`` with a dataset reference creates a run in ``queued`` and
returns immediately. A daemon worker thread then transitions the run
``queued -> running -> succeeded|failed``: it runs native discovery, stores
the resulting world through the domain world repository, computes a result
summary (mse, complexity, law count, world id) and records it on the run.
Every transition is published to the :class:`EventBus` as an ``ApiEvent``
(``run_queued``/``run_started``/``run_succeeded``/``run_failed``) so
``GET /v1/events`` streams the lifecycle.
Honest boundaries
Discovery runs the *native* engine in this process -- there is no distributed
scheduler and none is pretended. If the compiled runtime is absent the
submit is rejected with ``503 native_unavailable`` before a run is recorded,
exactly like the simulate-backed product paths. A run that fails at
execution time records ``failed`` with a clear reason instead of a
fabricated world.
The dataset may be an already-uploaded ``dataset_id`` or an inline dataset
(structured ``time``/``columns`` or a ``csv`` string); inline data is
materialised through the same validating domain dataset repository so it is
tenant-isolated and reproducible.
"""
from __future__ import annotations
import csv
import io
import json
import math
import time as _time
from dataclasses import dataclass
from threading import RLock, Thread
from typing import Mapping, Sequence
from uuid import uuid4
from lawsynth_server.dependencies import Services
from lawsynth_server.errors import ConflictError, NativeUnavailableError, ServerError, ValidationError
from lawsynth_server.native import discover_world, simulate_world
from . import laws
from .events import EventBus, EventKind
# Discovery knobs accepted by ``lawsynth_server.native.discover_world`` (which
# validates against the same set); this module normalises friendly aliases and a
# ``recipe`` preset down to these before forwarding.
_ALLOWED_CONFIG = frozenset(
{
"polynomial_degree",
"threshold",
"solver",
"include_trigonometric",
"include_rational",
"smoothing_radius",
"derivative_method",
"savgol_window",
"tvreg_lambda",
"tvreg_iterations",
"symbolic_depth",
}
)
_CONFIG_ALIASES = {"degree": "polynomial_degree"}
def native_available() -> bool:
"""True when the compiled LawSynth runtime can be imported and used.
Mirrors the probe used by the simulate-backed product paths: a source-only
install resolves ``import lawsynth`` but not ``lawsynth.World``.
"""
try:
import lawsynth
_ = lawsynth.World
return True
except Exception:
return False
@dataclass(frozen=True, slots=True)
class _Plan:
"""A validated, side-effect-free discovery plan produced at submit time."""
run_name: str
world_name: str
project_id: str | None
states: tuple[str, ...]
config: Mapping[str, object]
dataset_ref: str | None
inline_name: str | None
inline_schema: tuple[str, ...] | None
inline_time: tuple[float, ...] | None
inline_columns: Mapping[str, list[float]] | None
class DiscoveryService:
"""Owns discovery-run submission, execution, and world retrieval."""
def __init__(self, services: Services, events: EventBus) -> None:
self._services = services
self._events = events
self._lock = RLock()
self._threads: list[Thread] = []
# -- lifecycle ---------------------------------------------------------- #
def close(self) -> None:
"""Join outstanding worker threads so shutdown is orderly (best effort)."""
with self._lock:
threads = list(self._threads)
for thread in threads:
thread.join(timeout=5)
# -- submit ------------------------------------------------------------- #
def submit(self, organization_id: str, body: object, idempotency_key: str, request_id: str) -> dict[str, object]:
"""Validate a discovery request, record a ``queued`` run, and kick it off.
Validation (and dataset-reference resolution) happens synchronously so a
bad request is a ``422``/``404`` at submit. The record-and-launch step
runs under idempotency so a retried key returns the same queued run
without starting a second worker.
"""
plan = self._parse(organization_id, body)
if not native_available():
raise NativeUnavailableError(
"the LawSynth native runtime is unavailable; install the built lawsynth package"
)
def create() -> tuple[int, dict[str, object]]:
dataset_record, dataset_id = self._materialize_dataset(organization_id, plan)
values: dict[str, object] = {
"name": plan.run_name,
"status": "queued",
"dataset_id": dataset_id,
"metadata": self._metadata(plan, phase="queued"),
}
if plan.project_id is not None:
values["project_id"] = plan.project_id
run = self._services.runs.create(organization_id, values)
run_id = str(run["id"])
self._emit(organization_id, EventKind.RUN_QUEUED, run_id, {"id": run_id, "status": "queued"})
self._start_worker(organization_id, run_id, plan, dataset_record)
return 201, run
status, run, replayed = self._services.idempotency.execute(
organization_id,
idempotency_key,
{"method": "POST", "path": "/v1/runs", "body": body},
create,
)
return {
"status": status,
"headers": {"X-Request-ID": request_id, "Idempotency-Replayed": str(replayed).lower()},
"body": run,
}
# -- run world retrieval ----------------------------------------------- #
def run_world(self, organization_id: str, run_id: str, request_id: str) -> dict[str, object]:
"""Return the world a completed run discovered, with product links.
``404`` when the run is unknown, ``409`` when the run has not produced a
world yet (still queued/running) or failed without one.
"""
run = self._services.runs.get(organization_id, run_id)
status = run.get("status")
world_id = run.get("world_id")
if not isinstance(world_id, str) or not world_id:
if status in {"queued", "running"}:
raise ConflictError(f"run has not produced a world yet (status={status})")
reason = ""
metadata = run.get("metadata")
if isinstance(metadata, Mapping) and isinstance(metadata.get("error"), str):
reason = f": {metadata['error']}"
raise ConflictError(f"run did not produce a world (status={status}){reason}")
world = self._services.worlds.get(organization_id, world_id)
return {
"status": 200,
"headers": {"X-Request-ID": request_id},
"body": {
"run_id": run_id,
"world_id": world_id,
"world": world,
"links": {
"self": f"/v1/worlds/{world_id}",
"explain": f"/v1/worlds/{world_id}/explain",
"report": f"/v1/worlds/{world_id}/report",
},
},
}
# -- parsing / validation (no side effects) ---------------------------- #
def _parse(self, organization_id: str, body: object) -> _Plan:
if not isinstance(body, Mapping):
raise ValidationError("discovery run body must be an object")
states = self._states(body.get("states"))
config = _normalize_config(body.get("discovery"))
run_name = self._optional_name(body.get("name"), "name") or f"discovery-{uuid4().hex[:8]}"
world_name = self._optional_name(body.get("world_name"), "world_name") or f"{run_name}-world-{uuid4().hex[:6]}"
project_id = body.get("project_id")
if project_id is not None:
if not isinstance(project_id, str):
raise ValidationError("project_id must be a string")
self._services.projects.get(organization_id, project_id)
dataset_ref = body.get("dataset_id")
inline = body.get("dataset")
if dataset_ref is not None and inline is not None:
raise ValidationError("provide either dataset_id or an inline dataset, not both")
if dataset_ref is not None:
if not isinstance(dataset_ref, str):
raise ValidationError("dataset_id must be a string")
record = self._services.datasets.get(organization_id, dataset_ref)
self._verify_states_present(record.get("columns"), states)
return _Plan(run_name, world_name, project_id, states, config, dataset_ref, None, None, None, None)
if inline is None:
raise ValidationError("a discovery run requires a dataset_id or an inline dataset")
itime, icolumns, iname = self._parse_inline(inline)
self._verify_states_present(icolumns, states)
schema = tuple(sorted(icolumns))
return _Plan(run_name, world_name, project_id, states, config, None, iname, schema, itime, icolumns)
@staticmethod
def _states(value: object) -> tuple[str, ...]:
if not isinstance(value, Sequence) or isinstance(value, (str, bytes)) or not value:
raise ValidationError("states must be a non-empty list of identifiers")
states = list(value)
if any(not isinstance(name, str) or not name.isidentifier() for name in states):
raise ValidationError("states must contain identifiers")
if len(set(states)) != len(states):
raise ValidationError("states cannot contain duplicates")
return tuple(states)
@staticmethod
def _optional_name(value: object, field: str) -> str | None:
if value is None:
return None
if not isinstance(value, str) or not value.strip():
raise ValidationError(f"{field} must be a non-empty string")
return value.strip()
@staticmethod
def _verify_states_present(columns: object, states: Sequence[str]) -> None:
if not isinstance(columns, Mapping):
raise ValidationError("dataset has no observations to discover from")
missing = [name for name in states if name not in columns]
if missing:
raise ValidationError("discovery states must be dataset columns", details={"fields": sorted(missing)})
def _parse_inline(self, inline: object) -> tuple[tuple[float, ...], dict[str, list[float]], str]:
if not isinstance(inline, Mapping):
raise ValidationError("inline dataset must be an object")
name = self._optional_name(inline.get("name"), "dataset name") or f"run-dataset-{uuid4().hex[:8]}"
if "csv" in inline:
itime, columns = self._from_csv(inline)
elif "time" in inline or "columns" in inline:
time_value, columns_value = inline.get("time"), inline.get("columns")
if not isinstance(time_value, list) or not isinstance(columns_value, Mapping):
raise ValidationError("inline dataset requires a 'time' list and a 'columns' object")
itime = tuple(time_value) # type: ignore[arg-type]
columns = {str(key): list(series) for key, series in columns_value.items()} # type: ignore[arg-type]
else:
raise ValidationError("inline dataset must provide 'csv' or 'time' and 'columns'")
if not columns:
raise ValidationError("inline dataset must contain at least one observation column")
return itime, columns, name
@staticmethod
def _from_csv(inline: Mapping[str, object]) -> tuple[tuple[float, ...], dict[str, list[float]]]:
text = inline.get("csv")
if not isinstance(text, str) or not text.strip():
raise ValidationError("inline csv must be a non-empty string")
rows = [row for row in csv.reader(io.StringIO(text)) if any(cell.strip() for cell in row)]
if len(rows) < 3:
raise ValidationError("inline csv needs a header row and at least two observations")
header = [cell.strip() for cell in rows[0]]
if any(not name for name in header) or len(set(header)) != len(header):
raise ValidationError("inline csv header must have unique, non-empty column names")
requested = inline.get("time_column")
if requested is not None and not isinstance(requested, str):
raise ValidationError("time_column must be a string")
time_column = requested or ("t" if "t" in header else "time" if "time" in header else header[0])
if time_column not in header:
raise ValidationError(f"csv time column {time_column!r} is not present")
index = {name: position for position, name in enumerate(header)}
def column(name: str) -> list[float]:
values: list[float] = []
for row in rows[1:]:
if len(row) != len(header):
raise ValidationError("every inline csv row must match the header width")
try:
values.append(float(row[index[name]]))
except ValueError as error:
raise ValidationError(f"csv value in column {name!r} is not a number") from error
return values
itime = tuple(column(time_column))
columns = {name: column(name) for name in header if name != time_column}
if not columns:
raise ValidationError("inline csv must have at least one non-time column")
return itime, columns
# -- dataset materialisation (side-effecting; inside idempotency) ------- #
def _materialize_dataset(self, organization_id: str, plan: _Plan) -> tuple[dict[str, object], str]:
if plan.dataset_ref is not None:
record = self._services.datasets.get(organization_id, plan.dataset_ref)
return record, plan.dataset_ref
record = self._services.datasets.create(
organization_id,
{
"name": plan.inline_name,
"schema": list(plan.inline_schema or ()),
"time": list(plan.inline_time or ()),
"columns": {name: list(series) for name, series in (plan.inline_columns or {}).items()},
},
)
return record, str(record["id"])
# -- execution (worker thread) ----------------------------------------- #
def _start_worker(self, organization_id: str, run_id: str, plan: _Plan, dataset_record: Mapping[str, object]) -> None:
thread = Thread(
target=self._execute,
args=(organization_id, run_id, plan, dict(dataset_record)),
name=f"discovery-{run_id}",
daemon=True,
)
with self._lock:
self._threads.append(thread)
thread.start()
def _execute(self, organization_id: str, run_id: str, plan: _Plan, dataset_record: Mapping[str, object]) -> None:
try:
self._services.runs.update(
organization_id, run_id, {"status": "running", "metadata": self._metadata(plan, phase="running")}
)
self._emit(organization_id, EventKind.RUN_STARTED, run_id, {"id": run_id, "status": "running"})
_, spec = discover_world(dataset_record, list(plan.states), dict(plan.config))
world = self._services.worlds.create(
organization_id,
{
"name": plan.world_name,
"project_id": plan.project_id,
"dataset_id": dataset_record.get("id"),
**spec,
},
)
world_id = str(world["id"])
summary = self._summarize(world, dataset_record, plan.states)
self._services.runs.update(
organization_id,
run_id,
{
"status": "succeeded",
"world_id": world_id,
"metadata": self._metadata(plan, phase="succeeded", summary=summary),
},
)
self._emit(
organization_id,
EventKind.RUN_SUCCEEDED,
run_id,
{"id": run_id, "status": "succeeded", "world_id": world_id},
)
except NativeUnavailableError as error:
self._fail(organization_id, run_id, plan, f"native runtime unavailable: {error.message}")
except ServerError as error:
self._fail(organization_id, run_id, plan, error.message)
except Exception as error: # pragma: no cover - defensive; never leak a worker crash
self._fail(organization_id, run_id, plan, f"discovery failed: {error}")
def _fail(self, organization_id: str, run_id: str, plan: _Plan, reason: str) -> None:
try:
self._services.runs.update(
organization_id,
run_id,
{"status": "failed", "metadata": self._metadata(plan, phase="failed", error=reason)},
)
except Exception:
pass
self._emit(
organization_id,
EventKind.RUN_FAILED,
run_id,
{"id": run_id, "status": "failed", "reason": reason[:500]},
)
# -- result summary ----------------------------------------------------- #
def _summarize(self, world: Mapping[str, object], dataset: Mapping[str, object], states: Sequence[str]) -> dict[str, object]:
equations = world.get("equations")
equations = dict(equations) if isinstance(equations, Mapping) else {}
read = laws.read_laws(equations)
return {
"world_id": world.get("id"),
"laws": len(read),
"complexity": {"laws": len(read), "total_terms": laws.total_terms(read)},
"mse": self._fit_mse(world, dataset, states),
"equations": equations,
}
@staticmethod
def _fit_mse(world: Mapping[str, object], dataset: Mapping[str, object], states: Sequence[str]) -> float | None:
"""In-sample mean squared error from re-simulating the discovered world.
Honest fit indicator: simulate from the first observation across the
observed window and compare index-wise. Returns ``None`` (never a
fabricated number) if the world cannot be simulated or the result is not
finite.
"""
observations = dataset.get("columns")
times = dataset.get("time")
if not isinstance(observations, Mapping) or not isinstance(times, list) or len(times) < 2:
return None
try:
deltas = sorted(float(times[i + 1]) - float(times[i]) for i in range(len(times) - 1))
step = deltas[len(deltas) // 2]
if step <= 0:
return None
initial = {name: float(observations[name][0]) for name in states if name in observations}
if not initial:
return None
trajectory = simulate_world(
world,
{"initial": initial, "start": float(times[0]), "horizon": float(times[-1]), "step": step},
)
simulated = trajectory.get("values", {})
total, count = 0.0, 0
for name in states:
observed = observations.get(name)
series = simulated.get(name) if isinstance(simulated, Mapping) else None
if not isinstance(observed, list) or not isinstance(series, list):
continue
for index in range(min(len(observed), len(series))):
difference = float(observed[index]) - float(series[index])
total += difference * difference
count += 1
if count == 0:
return None
mse = total / count
return mse if math.isfinite(mse) else None
except Exception:
return None
# -- shared helpers ----------------------------------------------------- #
@staticmethod
def _metadata(plan: _Plan, *, phase: str, summary: Mapping[str, object] | None = None, error: str | None = None) -> dict[str, object]:
metadata: dict[str, object] = {
"kind": "discovery",
"phase": phase,
"states": list(plan.states),
"config": dict(plan.config),
}
if summary is not None:
metadata["summary"] = dict(summary)
if error is not None:
metadata["error"] = error
return metadata
def _emit(self, organization_id: str, kind: EventKind, run_id: str, payload: Mapping[str, object]) -> None:
try:
self._events.append(
organization_id,
int(_time.time() * 1000),
kind,
json.dumps(payload, separators=(",", ":"), allow_nan=False),
run_id=run_id,
)
except Exception:
pass
def _normalize_config(raw: object) -> dict[str, object]:
"""Normalise a discovery config: apply a ``recipe`` preset and aliases.
``recipe``/``preset`` selects a curated base config from
:mod:`lawsynth.recipes`; explicit fields override it. Friendly aliases
(``degree`` -> ``polynomial_degree``) are expanded, and the result is
restricted to the options the native engine accepts.
"""
if raw is None:
return {}
if not isinstance(raw, Mapping):
raise ValidationError("discovery config must be an object")
data = dict(raw)
recipe = data.pop("recipe", None)
preset = data.pop("preset", None)
if recipe is None:
recipe = preset
elif preset is not None:
raise ValidationError("specify only one of 'recipe' or 'preset'")
for alias, canonical in _CONFIG_ALIASES.items():
if alias in data:
if canonical in data:
raise ValidationError(f"specify only one of {alias!r} or {canonical!r}")
data[canonical] = data.pop(alias)
unknown = set(data) - _ALLOWED_CONFIG
if unknown:
raise ValidationError("unknown discovery options", details={"fields": sorted(unknown)})
base: dict[str, object] = {}
if recipe is not None:
base = _recipe_settings(recipe)
merged = {**base, **data}
unknown = set(merged) - _ALLOWED_CONFIG
if unknown:
raise ValidationError("unknown discovery options", details={"fields": sorted(unknown)})
return merged
def _recipe_settings(name: object) -> dict[str, object]:
if not isinstance(name, str) or not name.strip():
raise ValidationError("recipe must be a non-empty string")
try:
from lawsynth import recipes
except Exception as error: # pragma: no cover - recipes ship with the SDK
raise ValidationError("discovery recipes are unavailable in this install") from error
try:
recipe = recipes.get(name)
except Exception as error:
raise ValidationError(f"unknown discovery recipe {name!r}") from error
return dict(recipe.settings)

View File

@ -60,6 +60,8 @@ def classify(method: str, parts: Sequence[str]) -> str:
return "runs.cancel"
if len(parts) == 3 and parts[2] == "events" and method == "GET":
return "runs.events"
if len(parts) == 3 and parts[2] == "world" and method == "GET":
return "runs.world"
if len(parts) == 1:
return "runs.list" if method == "GET" else "runs.create" if method == "POST" else "runs.other"
if len(parts) == 2:

View File

@ -19,7 +19,7 @@ TOKEN = "0123456789abcdef0123456789abcdef"
TOKEN_GLOBEX = "fedcba9876543210fedcba9876543210"
def make_app(tmp_path, *, scopes=("read", "write"), extra_tokens=None):
def make_app(tmp_path, *, scopes=("read", "write"), extra_tokens=None, max_bytes=1024):
tokens = {TOKEN: ("acme", frozenset(scopes))}
if extra_tokens:
tokens.update(extra_tokens)
@ -27,9 +27,9 @@ def make_app(tmp_path, *, scopes=("read", "write"), extra_tokens=None):
database_url=f"sqlite:///{tmp_path / 'metadata.sqlite3'}",
object_root=tmp_path / "objects",
tokens=tokens,
max_upload_bytes=1024,
max_upload_bytes=max_bytes,
)
return create_wsgi_app(ApiSettings(server=server, environment="test", max_request_bytes=1024))
return create_wsgi_app(ApiSettings(server=server, environment="test", max_request_bytes=max_bytes))
def request(app, method: str, path: str, *, body: object | None = None, headers: dict[str, str] | None = None, query: str = "") -> tuple[int, dict[str, str], dict[str, Any] | None]:

View File

@ -0,0 +1,380 @@
"""Tests for the discovery-as-a-service run workflow.
These exercise the real WSGI transport through the shared harness: unit checks of
config normalisation and route recognition (native-agnostic), the request-shape
error contracts that surface before the native probe (401/403/404/422), and --
guarded with ``skipif`` -- the native-absent 503 path and the full native-present
loop (submit -> poll -> fetch world -> explain/report).
"""
from __future__ import annotations
import io
import math
import time
import pytest
from _harness import TOKEN, auth, make_app, request
from lawsynth_api import discovery
# Read-only and scope-less tokens in the same tenant as the harness' default
# read+write TOKEN, to probe scope authorization independent of tenancy.
READ_ONLY = "11112222333344445555666677778888"
NO_SCOPE = "aaaabbbbccccddddeeeeffff000011112"
_EXTRA = {
READ_ONLY: ("acme", frozenset({"read"})),
NO_SCOPE: ("acme", frozenset()),
}
def _native_present() -> bool:
return discovery.native_available()
def _make(tmp_path):
# Discovery payloads carry inline observation series, so raise the request
# ceiling above the harness' tiny default.
return make_app(tmp_path, extra_tokens=_EXTRA, max_bytes=1_000_000)
def _decay(samples: int = 60, dt: float = 0.1, rate: float = 0.5):
"""A clean single-state exponential-decay series discovery recovers well."""
times = [round(i * dt, 6) for i in range(samples)]
return times, {"x": [math.exp(-rate * t) for t in times]}
def _discovery_body(**overrides):
times, columns = _decay()
body = {
"name": overrides.pop("name", "decay-run"),
"dataset": {"time": times, "columns": columns},
"states": ["x"],
"discovery": {"polynomial_degree": 2, "threshold": 0.05},
}
body.update(overrides)
return body
def _poll(app, run_id, *, token=TOKEN, attempts=400, delay=0.01):
"""Poll GET /v1/runs/{id} until the run reaches a terminal status."""
for _ in range(attempts):
status, _, run = request(app, "GET", f"/v1/runs/{run_id}", headers=auth(token=token))
assert status == 200, run
if run["status"] in {"succeeded", "failed", "cancelled"}:
return run
time.sleep(delay)
raise AssertionError(f"run {run_id} did not terminate; last status {run['status']}")
def _sse(app, token=TOKEN):
environ = {
"REQUEST_METHOD": "GET",
"PATH_INFO": "/v1/events",
"QUERY_STRING": "",
"CONTENT_LENGTH": "0",
"wsgi.input": io.BytesIO(b""),
"HTTP_ACCEPT": "text/event-stream",
"HTTP_AUTHORIZATION": f"Bearer {token}",
}
captured: dict = {}
payload = b"".join(app(environ, lambda status, hs: captured.update(status=status)))
return payload.decode("utf-8")
# --------------------------------------------------------------------------- #
# Unit: config normalisation + native probe (native-agnostic) #
# --------------------------------------------------------------------------- #
def test_normalize_config_expands_alias_and_recipe():
merged = discovery._normalize_config({"recipe": "ecology", "degree": 3})
# recipe seeds a base; explicit degree alias overrides polynomial_degree.
assert merged["polynomial_degree"] == 3
assert merged["solver"] == "stlsq"
def test_normalize_config_rejects_unknown_option():
with pytest.raises(Exception):
discovery._normalize_config({"nonsense": 1})
def test_normalize_config_rejects_conflicting_degree_aliases():
with pytest.raises(Exception):
discovery._normalize_config({"degree": 2, "polynomial_degree": 3})
def test_native_available_returns_bool():
assert isinstance(discovery.native_available(), bool)
# --------------------------------------------------------------------------- #
# Request-shape contracts that surface before the native probe #
# (run identically whether or not native is installed) #
# --------------------------------------------------------------------------- #
def test_submit_requires_authentication_401(tmp_path):
app = _make(tmp_path)
try:
status, _, body = request(app, "POST", "/v1/runs", body=_discovery_body())
assert status == 401 and body["error"]["code"]
finally:
app.close()
def test_submit_forbidden_without_write_scope_403(tmp_path):
app = _make(tmp_path)
try:
status, _, body = request(
app, "POST", "/v1/runs", body=_discovery_body(), headers=auth(token=READ_ONLY, key="d-403")
)
assert status == 403 and body["error"]["code"] == "forbidden"
finally:
app.close()
def test_submit_requires_idempotency_key_422(tmp_path):
app = _make(tmp_path)
try:
status, _, body = request(app, "POST", "/v1/runs", body=_discovery_body(), headers=auth())
assert status == 422 and body["error"]["code"] == "validation_error"
finally:
app.close()
def test_submit_missing_states_422(tmp_path):
app = _make(tmp_path)
try:
body = _discovery_body()
body.pop("states")
status, _, out = request(app, "POST", "/v1/runs", body=body, headers=auth(key="d-nostate"))
assert status == 422 and out["error"]["code"] == "validation_error"
finally:
app.close()
def test_submit_conflicting_dataset_refs_422(tmp_path):
app = _make(tmp_path)
try:
body = _discovery_body()
body["dataset_id"] = "some-id"
status, _, out = request(app, "POST", "/v1/runs", body=body, headers=auth(key="d-both"))
assert status == 422 and out["error"]["code"] == "validation_error"
finally:
app.close()
def test_submit_unknown_dataset_id_404(tmp_path):
app = _make(tmp_path)
try:
status, _, out = request(
app,
"POST",
"/v1/runs",
body={"name": "r", "dataset_id": "does-not-exist", "states": ["x"]},
headers=auth(key="d-404"),
)
assert status == 404 and out["error"]["code"] == "not_found"
finally:
app.close()
def test_run_world_unknown_run_404(tmp_path):
app = _make(tmp_path)
try:
status, _, out = request(app, "GET", "/v1/runs/does-not-exist/world", headers=auth())
assert status == 404 and out["error"]["code"] == "not_found"
finally:
app.close()
def test_run_world_requires_authentication_401(tmp_path):
app = _make(tmp_path)
try:
status, _, out = request(app, "GET", "/v1/runs/whatever/world")
assert status == 401
finally:
app.close()
def test_plain_run_create_still_flows_through_domain(tmp_path):
# A run with no dataset reference is not a discovery submit: it must keep the
# existing domain behaviour (queued record, no native involvement).
app = _make(tmp_path)
try:
status, _, run = request(app, "POST", "/v1/runs", body={"name": "plain"}, headers=auth(key="plain-1"))
assert status == 201 and run["status"] == "queued"
assert "world_id" not in run or not run["world_id"]
finally:
app.close()
# --------------------------------------------------------------------------- #
# Native-absent: the honest 503 boundary #
# --------------------------------------------------------------------------- #
@pytest.mark.skipif(_native_present(), reason="native runtime is installed")
def test_submit_reports_missing_native_503(tmp_path):
app = _make(tmp_path)
try:
status, _, out = request(app, "POST", "/v1/runs", body=_discovery_body(), headers=auth(key="d-503"))
assert status == 503 and out["error"]["code"] == "native_unavailable"
finally:
app.close()
# --------------------------------------------------------------------------- #
# Native-present: the full discovery loop #
# --------------------------------------------------------------------------- #
@pytest.mark.skipif(not _native_present(), reason="native runtime is absent")
def test_inline_discovery_full_loop(tmp_path):
app = _make(tmp_path)
try:
status, _, run = request(app, "POST", "/v1/runs", body=_discovery_body(), headers=auth(key="loop-1"))
assert status == 201 and run["status"] == "queued"
run_id = run["id"]
done = _poll(app, run_id)
assert done["status"] == "succeeded"
assert isinstance(done["world_id"], str) and done["world_id"]
summary = done["metadata"]["summary"]
assert summary["laws"] == 1
assert summary["complexity"]["laws"] == 1
assert summary["mse"] is not None and summary["mse"] >= 0.0
assert summary["world_id"] == done["world_id"]
# GET /v1/runs/{id}/world returns the discovered world + product links.
status, _, world = request(app, "GET", f"/v1/runs/{run_id}/world", headers=auth())
assert status == 200
world_id = world["world_id"]
assert world_id == done["world_id"]
assert "x" in world["world"]["equations"]
assert world["links"]["explain"] == f"/v1/worlds/{world_id}/explain"
# A completed run flows straight into explain and report.
status, _, explained = request(app, "GET", f"/v1/worlds/{world_id}/explain", headers=auth())
assert status == 200 and explained["variables"] == ["x"]
status, headers, payload = _raw_get(app, f"/v1/worlds/{world_id}/report")
assert status == 200 and headers["Content-Type"].startswith("text/html")
assert b"LawSynth World" in payload
# The lifecycle projected onto the SSE stream.
kinds = [line[len("event: "):] for line in _sse(app).splitlines() if line.startswith("event: ")]
assert kinds == ["run_queued", "run_started", "run_succeeded"]
finally:
app.close()
@pytest.mark.skipif(not _native_present(), reason="native runtime is absent")
def test_uploaded_dataset_discovery(tmp_path):
app = _make(tmp_path)
try:
times, columns = _decay()
status, _, dataset = request(
app,
"POST",
"/v1/datasets",
body={"name": "uploaded-decay", "schema": ["x"], "time": times, "columns": columns},
headers=auth(key="ds-1"),
)
assert status == 201
status, _, run = request(
app,
"POST",
"/v1/runs",
body={"name": "from-upload", "dataset_id": dataset["id"], "states": ["x"]},
headers=auth(key="up-run-1"),
)
assert status == 201
done = _poll(app, run["id"])
assert done["status"] == "succeeded"
assert done["dataset_id"] == dataset["id"]
assert done["metadata"]["summary"]["laws"] >= 1
finally:
app.close()
@pytest.mark.skipif(not _native_present(), reason="native runtime is absent")
def test_inline_csv_discovery(tmp_path):
app = _make(tmp_path)
try:
times, columns = _decay(samples=40)
rows = ["t,x"] + [f"{times[i]},{columns['x'][i]}" for i in range(len(times))]
status, _, run = request(
app,
"POST",
"/v1/runs",
body={"name": "csv-run", "dataset": {"csv": "\n".join(rows)}, "states": ["x"]},
headers=auth(key="csv-1"),
)
assert status == 201
done = _poll(app, run["id"])
assert done["status"] == "succeeded" and done["world_id"]
finally:
app.close()
@pytest.mark.skipif(not _native_present(), reason="native runtime is absent")
def test_submit_is_idempotent_on_repeated_key(tmp_path):
app = _make(tmp_path)
try:
body = _discovery_body(name="idem")
status, _, first = request(app, "POST", "/v1/runs", body=body, headers=auth(key="same-key"))
assert status == 201
status, headers, second = request(app, "POST", "/v1/runs", body=body, headers=auth(key="same-key"))
assert status == 201
assert second["id"] == first["id"]
assert headers.get("Idempotency-Replayed") == "true"
finally:
app.close()
@pytest.mark.skipif(not _native_present(), reason="native runtime is absent")
def test_run_fails_honestly_on_bad_solver(tmp_path):
app = _make(tmp_path)
try:
body = _discovery_body(name="doomed")
body["discovery"] = {"solver": "bogus"}
status, _, run = request(app, "POST", "/v1/runs", body=body, headers=auth(key="fail-1"))
assert status == 201 and run["status"] == "queued"
done = _poll(app, run["id"])
assert done["status"] == "failed"
assert isinstance(done["metadata"]["error"], str) and done["metadata"]["error"]
# No world was fabricated: fetching the run's world is a 409, not a 200.
status, _, out = request(app, "GET", f"/v1/runs/{run['id']}/world", headers=auth())
assert status == 409 and out["error"]["code"] == "conflict"
# The failure projected onto the SSE stream.
kinds = [line[len("event: "):] for line in _sse(app).splitlines() if line.startswith("event: ")]
assert kinds == ["run_queued", "run_started", "run_failed"]
finally:
app.close()
def _raw_get(app, path, *, token=TOKEN):
"""Drive a GET and return the undecoded body (for HTML report)."""
environ = {
"REQUEST_METHOD": "GET",
"PATH_INFO": path,
"QUERY_STRING": "",
"CONTENT_LENGTH": "0",
"wsgi.input": io.BytesIO(b""),
"HTTP_AUTHORIZATION": f"Bearer {token}",
}
captured: dict = {}
def start_response(status, response_headers):
captured["status"], captured["headers"] = status, dict(response_headers)
payload = b"".join(app(environ, start_response))
return int(str(captured["status"]).split(" ", 1)[0]), captured["headers"], payload