matprops-sdk 0.1.1__py3-none-any.whl

matprops_sdk/__init__.py

@@ -0,0 +1,14 @@
+from matprops_sdk.context import RunContext
+from matprops_sdk.models import Field, InputModel, OutputModel
+from matprops_sdk.simulation import SimulationDefinition, simulation
+
+__all__ = [
+    "Field",
+    "InputModel",
+    "OutputModel",
+    "RunContext",
+    "SimulationDefinition",
+    "simulation",
+]
+
+__version__ = "0.1.1"

matprops_sdk/auth.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from typing import Any
+
+from matprops_sdk.credentials import (
+    Credentials,
+    default_api_url,
+    default_app_url,
+    delete_credentials,
+    load_credentials,
+    save_credentials,
+)
+from matprops_sdk.runtime import MatpropsError
+
+_TOKEN_ERRORS = {
+    "authorization_pending": "Waiting for approval in the browser.",
+    "slow_down": "Polling too quickly.",
+    "access_denied": "The CLI login was denied.",
+    "expired_token": "The CLI login expired. Run matprops login again.",
+    "invalid_grant": "This CLI login is no longer valid.",
+}
+
+
+def login(
+    app_url: str | None = None,
+    api_url: str | None = None,
+    *,
+    open_browser: bool = True,
+    sleep: Any = time.sleep,
+) -> Credentials:
+    base = (app_url or default_app_url()).rstrip("/")
+    api = (api_url or default_api_url()).rstrip("/")
+    started = _post_json(f"{base}/api/cli/device/authorize", {})
+    device_code = started.get("device_code")
+    verification = started.get("verification_uri_complete") or started.get(
+        "verification_uri"
+    )
+    interval = int(started.get("interval") or 5)
+    expires_in = int(started.get("expires_in") or 600)
+    if not isinstance(device_code, str) or not device_code:
+        raise MatpropsError("The login server did not return a device code.")
+    if not isinstance(verification, str) or not verification:
+        raise MatpropsError("The login server did not return a verification URL.")
+
+    print(f"Open {verification} to authorize the CLI.")
+    if started.get("user_code"):
+        print(f"Confirm the code {started['user_code']} if asked.")
+    if open_browser:
+        opened = webbrowser.open(verification)
+        if not opened:
+            print("Could not open a browser automatically.")
+
+    deadline = time.monotonic() + expires_in
+    wait = max(interval, 1)
+    while time.monotonic() < deadline:
+        status, body = _post_json_with_status(
+            f"{base}/api/cli/device/token",
+            {"device_code": device_code},
+        )
+        if status == 200 and "api_key" in body:
+            credentials = Credentials(
+                api_key=str(body["api_key"]),
+                api_key_id=str(body.get("api_key_id") or ""),
+                expires_at=(
+                    str(body["expires_at"])
+                    if isinstance(body.get("expires_at"), str)
+                    else None
+                ),
+                user=body.get("user") if isinstance(body.get("user"), dict) else {},
+                organization=(
+                    body.get("organization")
+                    if isinstance(body.get("organization"), dict)
+                    else {}
+                ),
+                app_url=base,
+                api_url=api,
+            )
+            path = save_credentials(credentials)
+            print(f"Logged in. Credentials saved to {path}")
+            return credentials
+
+        error = body.get("error")
+        if error == "authorization_pending":
+            wait = max(interval, 1)
+            sleep(wait)
+            continue
+        if error == "slow_down":
+            wait = max(interval, 1) + 5
+            sleep(wait)
+            continue
+        message = _TOKEN_ERRORS.get(
+            str(error),
+            str(body.get("error") or body.get("message") or "CLI login failed."),
+        )
+        raise MatpropsError(message)
+
+    raise MatpropsError("The CLI login expired. Run matprops login again.")
+
+
+def logout(app_url: str | None = None) -> None:
+    stored = load_credentials()
+    base = (app_url or (stored.app_url if stored else default_app_url())).rstrip("/")
+    if stored:
+        with contextlib.suppress(MatpropsError):
+            _post_json(
+                f"{base}/api/cli/logout",
+                {},
+                headers={"x-api-key": stored.api_key},
+            )
+    delete_credentials()
+    print("Logged out.")
+
+
+_WHOAMI_QUERY = """
+query {
+  me {
+    actor {
+      ... on UserActor { kind userId }
+      ... on OrgActor { kind userId organizationId role }
+      ... on ApiKeyActor { kind organizationId keyId userId }
+      ... on SystemAdminActor { kind userId }
+    }
+    user { id name email image }
+    session { id expiresAt activeOrganizationId systemAdminMode }
+  }
+}
+"""
+
+
+def whoami(api_url: str | None = None) -> dict[str, Any]:
+    stored = load_credentials()
+    if stored is None:
+        raise MatpropsError("Not logged in. Run matprops login first.")
+    api = (api_url or stored.api_url or default_api_url()).rstrip("/")
+    status, body = _request_json(
+        "POST",
+        f"{api}/graphql",
+        {"query": _WHOAMI_QUERY},
+        headers={"x-api-key": stored.api_key},
+    )
+    if status >= 400:
+        raise MatpropsError(_graphql_error_message(body, status))
+    errors = body.get("errors")
+    if errors:
+        raise MatpropsError(_graphql_error_message(body, status))
+    me = (body.get("data") or {}).get("me")
+    if not isinstance(me, dict):
+        raise MatpropsError("The API did not return an identity.")
+    return me
+
+
+def _post_json(
+    url: str,
+    payload: dict[str, Any],
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    status, body = _post_json_with_status(url, payload, headers)
+    if status >= 400:
+        raise MatpropsError(
+            str(
+                body.get("error")
+                or body.get("message")
+                or f"Request failed ({status})."
+            )
+        )
+    return body
+
+
+def _post_json_with_status(
+    url: str,
+    payload: dict[str, Any],
+    headers: dict[str, str] | None = None,
+) -> tuple[int, dict[str, Any]]:
+    return _request_json("POST", url, payload, headers)
+
+
+def _request_json(
+    method: str,
+    url: str,
+    payload: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+) -> tuple[int, dict[str, Any]]:
+    request_headers = {"Accept": "application/json", **(headers or {})}
+    data = None
+    if payload is not None:
+        request_headers["Content-Type"] = "application/json"
+        data = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=data,
+        headers=request_headers,
+        method=method,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return response.status, _decode_json(response.read())
+    except urllib.error.HTTPError as error:
+        return error.code, _decode_json(error.read())
+    except urllib.error.URLError as error:
+        raise MatpropsError(f"Could not reach {url}: {error.reason}") from error
+
+
+def _graphql_error_message(body: dict[str, Any], status: int) -> str:
+    errors = body.get("errors")
+    if isinstance(errors, list) and errors:
+        first = errors[0]
+        if isinstance(first, dict) and first.get("message"):
+            return str(first["message"])
+    return str(
+        body.get("error") or body.get("message") or f"Request failed ({status})."
+    )
+
+
+def _decode_json(raw: bytes) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except json.JSONDecodeError:
+        return {"error": raw.decode("utf-8", errors="replace")}
+    return parsed if isinstance(parsed, dict) else {"error": parsed}

matprops_sdk/bundle.py

@@ -0,0 +1,64 @@
+"""Helpers for unpacking uploaded simulation bundles (.zip).
+
+Used by sim-builder to turn a published zip back into a project directory,
+applying a path-traversal guard and the same wrapper-directory flattening
+rule sim-server uses when it locates ``manifest.json`` at upload time.
+"""
+
+from __future__ import annotations
+
+import shutil
+import zipfile
+from pathlib import Path
+
+JUNK_ENTRIES = frozenset({"__MACOSX"})
+MAX_WRAPPER_DEPTH = 10
+#: Either of these at a directory's top level marks it as the project root.
+ROOT_MARKERS = ("manifest.json", "pyproject.toml")
+
+
+def safe_extract(archive: zipfile.ZipFile, dest_dir: Path) -> None:
+    """Extract ``archive`` into ``dest_dir``, refusing entries that escape it."""
+    dest_dir = dest_dir.resolve()
+    for member in archive.namelist():
+        target = (dest_dir / member).resolve()
+        if target != dest_dir and dest_dir not in target.parents:
+            raise ValueError(
+                f"Refusing to extract entry outside destination: {member!r}"
+            )
+    archive.extractall(dest_dir)
+
+
+def flatten_wrapper_dirs(dest_dir: Path) -> None:
+    """Hoist contents up when the archive was zipped with a wrapper folder.
+
+    Some tools (e.g. macOS Finder's "Compress") zip a project as
+    ``<name>/manifest.json`` instead of ``manifest.json``, plus a stray
+    ``__MACOSX/`` directory. matprops only looks for the project's marker
+    files in the current directory and its parents, never its children, so
+    drill down through single-directory wrappers until the project root is
+    found. sim-server's manifest check applies the same rule.
+    """
+    for _ in range(MAX_WRAPPER_DEPTH):
+        if any((dest_dir / marker).is_file() for marker in ROOT_MARKERS):
+            return
+
+        for junk in list(dest_dir.iterdir()):
+            if junk.name in JUNK_ENTRIES:
+                shutil.rmtree(junk) if junk.is_dir() else junk.unlink()
+
+        entries = list(dest_dir.iterdir())
+        if len(entries) != 1 or not entries[0].is_dir():
+            return
+
+        wrapper = entries[0]
+        for item in wrapper.iterdir():
+            shutil.move(str(item), str(dest_dir / item.name))
+        wrapper.rmdir()
+
+
+def extract_bundle(zip_path: Path, dest_dir: Path) -> None:
+    """Extract a simulation zip into ``dest_dir`` and normalise its layout."""
+    with zipfile.ZipFile(zip_path) as archive:
+        safe_extract(archive, dest_dir)
+    flatten_wrapper_dirs(dest_dir)

matprops_sdk/cli.py

@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import re
+import sys
+import zipfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from matprops_sdk.manifest import build_manifest
+from matprops_sdk.publish import (
+    post_simulation_zip,
+    resolve_api_key,
+    resolve_api_url,
+    zip_project_directory,
+)
+from matprops_sdk.runtime import (
+    Entrypoint,
+    MatpropsError,
+    load_simulation,
+    resolve_entrypoint,
+    run_local,
+    schema_document,
+    utc_run_timestamp,
+)
+from matprops_sdk.simulation import SimulationDefinition
+
+_PACKAGE_OUTPUT_DIR = "dist"
+
+_SIMULATION_TEMPLATE = """from matprops_sdk import (
+    Field,
+    InputModel,
+    OutputModel,
+    RunContext,
+    simulation,
+)
+
+
+class Inputs(InputModel):
+    var1: float = Field(description="First addend")
+    var2: float = Field(description="Second addend")
+
+
+class Outputs(OutputModel):
+    sum: float
+
+
+@simulation(name="add-numbers", inputs=Inputs, outputs=Outputs)
+def run(inputs: Inputs, context: RunContext) -> Outputs:
+    trace = context.artifact("trace.txt", "Calculation trace")
+    trace.write_text(f"{inputs.var1} + {inputs.var2}\\n", encoding="utf-8")
+    return Outputs(sum=inputs.var1 + inputs.var2)
+"""
+
+_PYPROJECT_TEMPLATE = """[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{project_name}"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["matprops-sdk"]
+
+[tool.matprops]
+entrypoint = "simulation:run"
+"""
+
+_INPUT_TEMPLATE = """{
+  "var1": 1.0,
+  "var2": 2.0
+}
+"""
+
+
+def _add_entrypoint_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--entrypoint",
+        help='Override [tool.matprops].entrypoint, for example "simulation:run".',
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="matprops",
+        description="Define, run, and authenticate Matprops simulations.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Scaffold a simulation project.")
+    init_parser.add_argument("directory", nargs="?", default=".")
+
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate a simulation entrypoint and its schemas.",
+    )
+    _add_entrypoint_argument(validate_parser)
+
+    schema_parser = subparsers.add_parser(
+        "schema",
+        help="Generate input and output JSON Schema.",
+    )
+    _add_entrypoint_argument(schema_parser)
+    schema_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        help="Write input.schema.json and output.schema.json instead of stdout.",
+    )
+
+    run_parser = subparsers.add_parser("run", help="Run a simulation locally.")
+    _add_entrypoint_argument(run_parser)
+    run_parser.add_argument(
+        "--input",
+        required=True,
+        help="Input JSON file path, or an inline JSON object/array string.",
+    )
+    run_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path(".run-results"),
+        help="Parent directory for timestamped run folders.",
+    )
+
+    run_remote_parser = subparsers.add_parser(
+        "run-remote",
+        help="Execute a platform-scheduled run and report results to sim-server "
+        "(the container entrypoint; reads MATPROPS_RUN_ID, MATPROPS_RUN_TOKEN, "
+        "MATPROPS_API_URL). You probably don't need to use this.",
+    )
+    _add_entrypoint_argument(run_remote_parser)
+    run_remote_parser.add_argument("--run-id", help="Overrides MATPROPS_RUN_ID.")
+    run_remote_parser.add_argument("--token", help="Overrides MATPROPS_RUN_TOKEN.")
+    run_remote_parser.add_argument(
+        "--url",
+        help="sim-server base URL. Overrides MATPROPS_API_URL "
+        "(default https://api.matprops.com).",
+    )
+
+    login_parser = subparsers.add_parser(
+        "login",
+        help="Sign in through the Matprops web app and store credentials.",
+    )
+    login_parser.add_argument(
+        "--app-url",
+        help="Matprops web app URL. Defaults to MATPROPS_APP_URL or "
+        "https://matprops.com.",
+    )
+    login_parser.add_argument(
+        "--api-url",
+        help="Matprops API URL. Defaults to MATPROPS_API_URL or "
+        "https://api.matprops.com.",
+    )
+    login_parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Print the login URL without opening a browser.",
+    )
+    subparsers.add_parser("logout", help="Revoke and delete stored CLI credentials.")
+    subparsers.add_parser("whoami", help="Show the signed-in user and organization.")
+
+    package_parser = subparsers.add_parser(
+        "package",
+        help="Validate the simulation and write an uploadable zip (with "
+        "manifest.json) to dist/<name>.zip. No login required.",
+    )
+    _add_entrypoint_argument(package_parser)
+    package_parser.add_argument(
+        "--output",
+        type=Path,
+        help=f"Zip path to write. Defaults to {_PACKAGE_OUTPUT_DIR}/<name>.zip.",
+    )
+
+    publish_parser = subparsers.add_parser(
+        "publish",
+        help="Package the current simulation and upload it to sim-server.",
+    )
+    _add_entrypoint_argument(publish_parser)
+    publish_parser.add_argument(
+        "--api-key",
+        help="API key. Overrides MATPROPS_API_KEY.",
+    )
+    publish_parser.add_argument(
+        "--url",
+        help="sim-server base URL. Overrides MATPROPS_API_URL "
+        "(default https://api.matprops.com).",
+    )
+    return parser
+
+
+def project_name_for(directory: Path) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", directory.resolve().name.lower()).strip("-")
+    if not slug:
+        slug = "simulation"
+    return f"matprops-sim-{slug}"
+
+
+def init_project(directory: Path) -> None:
+    files = {
+        "simulation.py": _SIMULATION_TEMPLATE,
+        "pyproject.toml": _PYPROJECT_TEMPLATE.format(
+            project_name=project_name_for(directory)
+        ),
+        "example.input.json": _INPUT_TEMPLATE,
+    }
+    existing = [name for name in files if (directory / name).exists()]
+    if existing:
+        raise MatpropsError(
+            "Refusing to overwrite existing files: " + ", ".join(existing)
+        )
+    directory.mkdir(parents=True, exist_ok=True)
+    for name, contents in files.items():
+        (directory / name).write_text(contents, encoding="utf-8")
+
+
+def package_simulation(
+    definition: SimulationDefinition, entrypoint: Entrypoint
+) -> bytes:
+    """Build the upload bundle: project files plus a freshly computed manifest.
+
+    Shared by ``package`` and ``publish`` so both produce byte-identical zips.
+    """
+    definition.input_schema()
+    definition.output_schema()
+    manifest = build_manifest(definition, entrypoint)
+    return zip_project_directory(entrypoint.project_dir, manifest)
+
+
+def load_run_input(value: str) -> object:
+    stripped = value.strip()
+    if stripped.startswith("{") or stripped.startswith("["):
+        try:
+            return json.loads(stripped)
+        except json.JSONDecodeError as error:
+            raise MatpropsError(f"Invalid JSON input: {error}") from error
+    return json.loads(Path(value).read_text(encoding="utf-8"))
+
+
+def _write_schema_files(output_dir: Path, document: dict[str, object]) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for key, filename in (
+        ("input_schema", "input.schema.json"),
+        ("output_schema", "output.schema.json"),
+    ):
+        (output_dir / filename).write_text(
+            json.dumps(document[key], indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            target = Path(args.directory).resolve()
+            init_project(target)
+            print(f"Created Matprops simulation in {target}")
+            return 0
+
+        if args.command == "login":
+            from matprops_sdk.auth import login
+
+            login(
+                app_url=args.app_url,
+                api_url=args.api_url,
+                open_browser=not args.no_browser,
+            )
+            return 0
+
+        if args.command == "logout":
+            from matprops_sdk.auth import logout
+
+            logout()
+            return 0
+
+        if args.command == "whoami":
+            from matprops_sdk.auth import whoami
+
+            print(json.dumps(whoami(), indent=2))
+            return 0
+
+        if args.command == "run-remote":
+            from matprops_sdk.remote import reporter_from_env, run_remote
+
+            reporter = reporter_from_env(
+                api_url=args.url,
+                run_id=args.run_id,
+                token=args.token,
+            )
+            return run_remote(reporter, entrypoint=args.entrypoint)
+
+        entrypoint = resolve_entrypoint(args.entrypoint)
+        definition = load_simulation(entrypoint)
+        if args.command == "validate":
+            definition.input_schema()
+            definition.output_schema()
+            print(f"Simulation {definition.name!r} is valid.")
+            return 0
+
+        if args.command == "schema":
+            document = {**schema_document(definition), "entrypoint": entrypoint.value}
+            if args.output_dir is not None:
+                _write_schema_files(args.output_dir, document)
+                print(f"Wrote schemas to {args.output_dir.resolve()}")
+            else:
+                print(json.dumps(document, indent=2))
+            return 0
+
+        if args.command == "run":
+            input_data = load_run_input(args.input)
+            folder, started_at = utc_run_timestamp()
+            run_dir = args.output_dir / folder
+            output_data = run_local(
+                definition,
+                input_data,
+                run_dir,
+                started_at=started_at,
+            )
+            print(json.dumps(output_data, indent=2))
+            print(f"Run files written to {run_dir.resolve()}")
+            return 0
+
+        if args.command == "package":
+            zip_bytes = package_simulation(definition, entrypoint)
+            output = args.output or (
+                entrypoint.project_dir / _PACKAGE_OUTPUT_DIR / f"{definition.name}.zip"
+            )
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_bytes(zip_bytes)
+            with zipfile.ZipFile(io.BytesIO(zip_bytes)) as archive:
+                entry_count = len(archive.namelist())
+            print(
+                f"Packaged {definition.name!r} ({entry_count} files, "
+                f"{len(zip_bytes)} bytes) to {output.resolve()}"
+            )
+            return 0
+
+        if args.command == "publish":
+            zip_bytes = package_simulation(definition, entrypoint)
+            upload = post_simulation_zip(
+                resolve_api_url(args.url),
+                resolve_api_key(args.api_key),
+                zip_bytes,
+            )
+            print(json.dumps(upload, indent=2))
+            return 0
+    except (MatpropsError, ValidationError, OSError, ValueError, TypeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+
+    raise AssertionError(f"Unhandled command: {args.command}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())