From 035cebdcf1f3cab73e4c001acdfbdecc6600a3cb Mon Sep 17 00:00:00 2001 From: caelum0x Date: Mon, 17 Aug 2026 22:30:54 +0300 Subject: [PATCH] =?UTF-8?q?feat(product):=20discovery-as-a-service=20?= =?UTF-8?q?=E2=80=94=20run=20workflow=20+=20Python=20service=20Client?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- python/lawsynth/examples/service_client.py | 135 +++++ python/lawsynth/src/lawsynth/__init__.py | 4 +- python/lawsynth/src/lawsynth/client.py | 640 +++++++++++++++++++++ python/lawsynth/src/lawsynth/errors.py | 40 ++ python/lawsynth/tests/test_client.py | 333 +++++++++++ services/api/src/lawsynth_api/app.py | 53 ++ services/api/src/lawsynth_api/discovery.py | 547 ++++++++++++++++++ services/api/src/lawsynth_api/runs.py | 2 + services/api/tests/_harness.py | 6 +- services/api/tests/discovery_test.py | 380 ++++++++++++ 10 files changed, 2136 insertions(+), 4 deletions(-) create mode 100644 python/lawsynth/examples/service_client.py create mode 100644 python/lawsynth/src/lawsynth/client.py create mode 100644 python/lawsynth/tests/test_client.py create mode 100644 services/api/src/lawsynth_api/discovery.py create mode 100644 services/api/tests/discovery_test.py 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