nexusflow-sdk 0.3.0__tar.gz

nexusflow_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: nexusflow-sdk
+Version: 0.3.0
+Summary: Python SDK for NexusFlow model editing and simulation workflows
+Author: NexusFlow Team
+License-Expression: LicenseRef-Proprietary
+Keywords: nexusflow,pipeline-simulation,oil-gas,sdk,digital-twin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.8.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+
+# nexusflow-sdk
+
+nexusflow-sdk is a Python SDK for NexusFlow model editing, simulation execution, streaming result retrieval, and runtime command control.
+
+## Features
+
+- Token-based authentication against the NexusFlow backend
+- Create models for supported workspace types and open existing models
+- Add, remove, connect, and configure components in the model graph
+- Save model snapshots and start simulation jobs
+- Poll or stream logs, plots, tables, inspect data, and container messages
+- Send runtime commands to components during online or transient execution
+
+## Requirements
+
+- Python 3.10 or later
+- A reachable NexusFlow service endpoint
+- A NexusFlow account that can obtain access tokens
+
+## Install
+
+Install from a built wheel or from PyPI after publication:
+
+```bash
+pip install nexusflow-sdk
+```
+
+For local development in this repository:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from nexusflow_sdk import NexusFlowClient
+
+client = NexusFlowClient(
+    base_url="http://localhost:8000",
+    username="admin",
+    password="your-password",
+)
+
+model = client.create_model(
+    name="sdk-demo-model",
+    workspace_type="lps_online",
+    description="Created by nexusflow-sdk",
+)
+
+source = model.add_component("Source", position=(0, 0))
+pipe = model.add_component("Pipe", position=(240, 0))
+load = model.add_component("Load", position=(480, 0))
+
+model.connect(source, "0", pipe, "0")
+model.connect(pipe, "1", load, "0")
+
+model.save()
+job = model.run(timeout=120, image="nexusflow")
+
+for message in job.stream_results(timeout=2):
+    print(message.get("type"), message.get("key"))
+```
+
+## Public API
+
+The package currently exports these main entry points:
+
+- `NexusFlowClient`
+- `Model`
+- `Component`
+- `Connection`
+- `Job`
+- `MetaService`
+- `ResultStream`
+- `LogMessage`
+- `PlotMessage`
+- `TableMessage`
+- `InspectMessage`
+- `ContainerMessage`
+- `NexusFlowError`
+- `AuthError`
+- `APIError`
+- `NotFoundError`
+- `ValidationError`
+
+## Examples
+
+- `examples/quickstart.py`: create, save, run, and fetch results
+- `examples/transient_streaming.py`: stream transient online results and send commands during execution
+- `examples/run_existing_model.py`: open an existing model by ID and run it
+
+## Release Validation
+
+Build and metadata check:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+Minimal install smoke test with the built wheel:
+
+```bash
+python -m venv .smoke-venv
+.smoke-venv\Scripts\python -m pip install dist\nexusflow_sdk-0.1.2-py3-none-any.whl
+.smoke-venv\Scripts\python -c "from nexusflow_sdk import NexusFlowClient, Model, Job, ResultStream; print('smoke ok')"
+```
+
+## Release Workflow
+
+If you want to publish a new version yourself, the repository now includes a reusable PowerShell script:
+
+```powershell
+.\scripts\release.ps1 -Repository pypi -Token "pypi-..."
+```
+
+Recommended process:
+
+1. Update `version` in `pyproject.toml`.
+2. Run the release script from the `nexusflow-sdk` directory.
+3. Wait for PyPI index propagation if the published install smoke test fails on the first try.
+
+The script performs these steps automatically:
+
+- clean `dist/`
+- `python -m build`
+- `python -m twine check dist/*`
+- `python -m unittest tests.test_public_api`
+- install the built wheel into a temporary virtual environment for a local smoke test
+- upload to PyPI or TestPyPI
+- create a fresh temporary virtual environment and install the published package for a post-publish smoke test
+
+Examples:
+
+```powershell
+# Full publish to PyPI
+.\scripts\release.ps1 -Repository pypi -Token "pypi-..."
+
+# Full publish to TestPyPI
+.\scripts\release.ps1 -Repository testpypi -Token "pypi-..."
+
+# Local validation only, without upload
+.\scripts\release.ps1 -SkipUpload -SkipSmokeTest
+```
+
+You can also avoid passing tokens on the command line by using environment variables:
+
+```powershell
+$env:PYPI_TOKEN = "pypi-..."
+.\scripts\release.ps1 -Repository pypi
+```
+
+## License
+
+This package is currently distributed as proprietary software.

nexusflow_sdk-0.3.0/README.md

@@ -0,0 +1,156 @@
+# nexusflow-sdk
+
+nexusflow-sdk is a Python SDK for NexusFlow model editing, simulation execution, streaming result retrieval, and runtime command control.
+
+## Features
+
+- Token-based authentication against the NexusFlow backend
+- Create models for supported workspace types and open existing models
+- Add, remove, connect, and configure components in the model graph
+- Save model snapshots and start simulation jobs
+- Poll or stream logs, plots, tables, inspect data, and container messages
+- Send runtime commands to components during online or transient execution
+
+## Requirements
+
+- Python 3.10 or later
+- A reachable NexusFlow service endpoint
+- A NexusFlow account that can obtain access tokens
+
+## Install
+
+Install from a built wheel or from PyPI after publication:
+
+```bash
+pip install nexusflow-sdk
+```
+
+For local development in this repository:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from nexusflow_sdk import NexusFlowClient
+
+client = NexusFlowClient(
+    base_url="http://localhost:8000",
+    username="admin",
+    password="your-password",
+)
+
+model = client.create_model(
+    name="sdk-demo-model",
+    workspace_type="lps_online",
+    description="Created by nexusflow-sdk",
+)
+
+source = model.add_component("Source", position=(0, 0))
+pipe = model.add_component("Pipe", position=(240, 0))
+load = model.add_component("Load", position=(480, 0))
+
+model.connect(source, "0", pipe, "0")
+model.connect(pipe, "1", load, "0")
+
+model.save()
+job = model.run(timeout=120, image="nexusflow")
+
+for message in job.stream_results(timeout=2):
+    print(message.get("type"), message.get("key"))
+```
+
+## Public API
+
+The package currently exports these main entry points:
+
+- `NexusFlowClient`
+- `Model`
+- `Component`
+- `Connection`
+- `Job`
+- `MetaService`
+- `ResultStream`
+- `LogMessage`
+- `PlotMessage`
+- `TableMessage`
+- `InspectMessage`
+- `ContainerMessage`
+- `NexusFlowError`
+- `AuthError`
+- `APIError`
+- `NotFoundError`
+- `ValidationError`
+
+## Examples
+
+- `examples/quickstart.py`: create, save, run, and fetch results
+- `examples/transient_streaming.py`: stream transient online results and send commands during execution
+- `examples/run_existing_model.py`: open an existing model by ID and run it
+
+## Release Validation
+
+Build and metadata check:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+Minimal install smoke test with the built wheel:
+
+```bash
+python -m venv .smoke-venv
+.smoke-venv\Scripts\python -m pip install dist\nexusflow_sdk-0.1.2-py3-none-any.whl
+.smoke-venv\Scripts\python -c "from nexusflow_sdk import NexusFlowClient, Model, Job, ResultStream; print('smoke ok')"
+```
+
+## Release Workflow
+
+If you want to publish a new version yourself, the repository now includes a reusable PowerShell script:
+
+```powershell
+.\scripts\release.ps1 -Repository pypi -Token "pypi-..."
+```
+
+Recommended process:
+
+1. Update `version` in `pyproject.toml`.
+2. Run the release script from the `nexusflow-sdk` directory.
+3. Wait for PyPI index propagation if the published install smoke test fails on the first try.
+
+The script performs these steps automatically:
+
+- clean `dist/`
+- `python -m build`
+- `python -m twine check dist/*`
+- `python -m unittest tests.test_public_api`
+- install the built wheel into a temporary virtual environment for a local smoke test
+- upload to PyPI or TestPyPI
+- create a fresh temporary virtual environment and install the published package for a post-publish smoke test
+
+Examples:
+
+```powershell
+# Full publish to PyPI
+.\scripts\release.ps1 -Repository pypi -Token "pypi-..."
+
+# Full publish to TestPyPI
+.\scripts\release.ps1 -Repository testpypi -Token "pypi-..."
+
+# Local validation only, without upload
+.\scripts\release.ps1 -SkipUpload -SkipSmokeTest
+```
+
+You can also avoid passing tokens on the command line by using environment variables:
+
+```powershell
+$env:PYPI_TOKEN = "pypi-..."
+.\scripts\release.ps1 -Repository pypi
+```
+
+## License
+
+This package is currently distributed as proprietary software.

nexusflow_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexusflow-sdk"
+version = "0.3.0"
+description = "Python SDK for NexusFlow model editing and simulation workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [
+    {name = "NexusFlow Team"},
+]
+keywords = ["nexusflow", "pipeline-simulation", "oil-gas", "sdk", "digital-twin"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "websocket-client>=1.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2.2",
+    "twine>=5.1.1",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

nexusflow_sdk-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nexusflow_sdk-0.3.0/src/nexusflow_sdk/__init__.py

@@ -0,0 +1,36 @@
+from .client import NexusFlowClient
+from .component import Component, PortRef
+from .connection import Connection
+from .exceptions import APIError, AuthError, NexusFlowError, NotFoundError, ValidationError
+from .job import Job
+from .meta import MetaService
+from .model import Model
+from .result import (
+    ContainerMessage,
+    InspectMessage,
+    LogMessage,
+    PlotMessage,
+    ResultStream,
+    TableMessage,
+)
+
+__all__ = [
+    "APIError",
+    "AuthError",
+    "Component",
+    "Connection",
+    "ContainerMessage",
+    "NexusFlowClient",
+    "NexusFlowError",
+    "InspectMessage",
+    "Job",
+    "LogMessage",
+    "MetaService",
+    "Model",
+    "NotFoundError",
+    "PlotMessage",
+    "PortRef",
+    "ResultStream",
+    "TableMessage",
+    "ValidationError",
+]

nexusflow_sdk-0.3.0/src/nexusflow_sdk/_constraints.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from ._expression import evaluate_condition, evaluate_expression
+
+
+def _constraint_scope(
+    *,
+    value: Any,
+    params: Mapping[str, Any] | None,
+    global_params: Mapping[str, Any] | None,
+    context: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    return {
+        "value": value,
+        "params": dict(params or {}),
+        "global": dict(global_params or params or {}),
+        "context": dict(context or {}),
+    }
+
+
+def validate_constraints(
+    arg_def: Mapping[str, Any],
+    value: Any,
+    *,
+    params: Mapping[str, Any] | None,
+    global_params: Mapping[str, Any] | None = None,
+    context: Mapping[str, Any] | None = None,
+) -> list[str]:
+    constraints = arg_def.get("constraints", [])
+    if not isinstance(constraints, list):
+        return []
+
+    issues: list[str] = []
+    scope = _constraint_scope(
+        value=value,
+        params=params,
+        global_params=global_params,
+        context={
+            **dict(context or {}),
+            "key": arg_def.get("key", ""),
+            "type": arg_def.get("type", ""),
+        },
+    )
+    for constraint in constraints:
+        if not isinstance(constraint, Mapping):
+            continue
+        expr = str(constraint.get("expr", "")).strip()
+        if not expr:
+            continue
+        message = str(constraint.get("message") or "constraint failed")
+        when = str(constraint.get("when", "")).strip()
+        try:
+            if when and not evaluate_condition(when, scope):
+                continue
+            if not bool(evaluate_expression(expr, scope)):
+                issues.append(message)
+        except Exception as exc:
+            issues.append(f"constraint rule failed: {message} ({exc})")
+    return issues

nexusflow_sdk-0.3.0/src/nexusflow_sdk/_expression.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import re
+from types import SimpleNamespace
+from typing import Any, Mapping
+
+
+_NOT_PATTERN = re.compile(r"(?<![=!<>])!(?!=)")
+
+
+def _to_namespace(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return SimpleNamespace(**{key: _to_namespace(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return [_to_namespace(item) for item in value]
+    return value
+
+
+def _equal_text(left: Any, right: Any) -> bool:
+    return str(left) == str(right)
+
+
+def _as_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return [value]
+
+
+def _stable_marker(value: Any) -> str:
+    if isinstance(value, Mapping):
+        return "dict:" + repr(sorted((str(key), _stable_marker(item)) for key, item in value.items()))
+    if isinstance(value, (list, tuple)):
+        return "list:" + repr([_stable_marker(item) for item in value])
+    return f"{type(value).__name__}:{value!r}"
+
+
+def _column(rows: Any, index: Any) -> list[Any]:
+    col_index = int(index)
+    result: list[Any] = []
+    for row in _as_list(rows):
+        if isinstance(row, Mapping):
+            result.append(row.get(col_index, row.get(str(col_index))))
+            continue
+        if isinstance(row, (list, tuple)) and -len(row) <= col_index < len(row):
+            result.append(row[col_index])
+        else:
+            result.append(None)
+    return result
+
+
+def _unique(items: Any) -> bool:
+    seen: set[str] = set()
+    for item in _as_list(items):
+        marker = _stable_marker(item)
+        if marker in seen:
+            return False
+        seen.add(marker)
+    return True
+
+
+def _empty(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, (str, list, tuple, dict, set)):
+        return len(value) == 0
+    return False
+
+
+def _not_empty(value: Any) -> bool:
+    return not _empty(value)
+
+
+def _matches(value: Any, pattern: Any) -> bool:
+    return re.search(str(pattern), "" if value is None else str(value)) is not None
+
+
+def _number(value: Any) -> float:
+    return float(value)
+
+
+def _string(value: Any) -> str:
+    return "" if value is None else str(value)
+
+
+def _transform(expr: str) -> str:
+    transformed = expr.strip()
+    transformed = transformed.replace("&&", " and ")
+    transformed = transformed.replace("||", " or ")
+    transformed = re.sub(r"\btrue\b", "True", transformed, flags=re.IGNORECASE)
+    transformed = re.sub(r"\bfalse\b", "False", transformed, flags=re.IGNORECASE)
+    transformed = re.sub(r"\bnull\b", "None", transformed, flags=re.IGNORECASE)
+    transformed = re.sub(r"\bglobal\b", "global_", transformed)
+    transformed = _NOT_PATTERN.sub(" not ", transformed)
+    return transformed
+
+
+def evaluate_expression(expr: str | None, scope: Mapping[str, Any] | None = None) -> Any:
+    if expr is None:
+        raise ValueError("expression is empty")
+    text = expr.strip()
+    if not text:
+        raise ValueError("expression is empty")
+    transformed = _transform(text)
+    locals_scope = {key: _to_namespace(value) for key, value in (scope or {}).items()}
+    if "global" in locals_scope and "global_" not in locals_scope:
+        locals_scope["global_"] = locals_scope["global"]
+    return eval(
+        transformed,
+        {
+            "__builtins__": {},
+            "equalText": _equal_text,
+            "min": min,
+            "max": max,
+            "abs": abs,
+            "len": len,
+            "empty": _empty,
+            "notEmpty": _not_empty,
+            "column": _column,
+            "unique": _unique,
+            "matches": _matches,
+            "number": _number,
+            "string": _string,
+        },
+        locals_scope,
+    )
+
+
+def evaluate_condition(expr: str | None, scope: Mapping[str, Any] | None = None) -> bool:
+    try:
+        result = evaluate_expression(expr, scope)
+    except Exception:
+        return False
+    return bool(result)