diff --git a/python/lawsynth/examples/service_client.py b/python/lawsynth/examples/service_client.py
new file mode 100644
index 0000000..ad0a8db
--- /dev/null
+++ b/python/lawsynth/examples/service_client.py
@@ -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()
diff --git a/python/lawsynth/src/lawsynth/__init__.py b/python/lawsynth/src/lawsynth/__init__.py
index af53993..4e99c99 100644
--- a/python/lawsynth/src/lawsynth/__init__.py
+++ b/python/lawsynth/src/lawsynth/__init__.py
@@ -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",
diff --git a/python/lawsynth/src/lawsynth/client.py b/python/lawsynth/src/lawsynth/client.py
new file mode 100644
index 0000000..72dac4f
--- /dev/null
+++ b/python/lawsynth/src/lawsynth/client.py
@@ -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
diff --git a/python/lawsynth/src/lawsynth/errors.py b/python/lawsynth/src/lawsynth/errors.py
index 4d95b72..c0f6dc6 100644
--- a/python/lawsynth/src/lawsynth/errors.py
+++ b/python/lawsynth/src/lawsynth/errors.py
@@ -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
diff --git a/python/lawsynth/tests/test_client.py b/python/lawsynth/tests/test_client.py
new file mode 100644
index 0000000..6515cb0
--- /dev/null
+++ b/python/lawsynth/tests/test_client.py
@@ -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"
report"
+ 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"", 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(" 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.
diff --git a/services/api/src/lawsynth_api/discovery.py b/services/api/src/lawsynth_api/discovery.py
new file mode 100644
index 0000000..e78807d
--- /dev/null
+++ b/services/api/src/lawsynth_api/discovery.py
@@ -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)
diff --git a/services/api/src/lawsynth_api/runs.py b/services/api/src/lawsynth_api/runs.py
index 6154e04..185ed3a 100644
--- a/services/api/src/lawsynth_api/runs.py
+++ b/services/api/src/lawsynth_api/runs.py
@@ -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:
diff --git a/services/api/tests/_harness.py b/services/api/tests/_harness.py
index 6da4fa4..9f55e78 100644
--- a/services/api/tests/_harness.py
+++ b/services/api/tests/_harness.py
@@ -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]:
diff --git a/services/api/tests/discovery_test.py b/services/api/tests/discovery_test.py
new file mode 100644
index 0000000..ce4566b
--- /dev/null
+++ b/services/api/tests/discovery_test.py
@@ -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