graphdatascience 1.7a1__tar.gz → 1.9__tar.gz

{graphdatascience-1.7a1 → graphdatascience-1.9}/MANIFEST.in

@@ -5,3 +5,4 @@ include LICENSE
 prune graphdatascience/tests
 prune graphdatascience/resources/cora/serialize_cora.py
 prune graphdatascience/resources/imdb/serialize_imdb.py
+prune graphdatascience/resources/lastfm/serialize_lastfm.py

{graphdatascience-1.7a1/graphdatascience.egg-info → graphdatascience-1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: graphdatascience
-Version: 1.7a1
+Version: 1.9
 Summary: A Python client for the Neo4j Graph Data Science (GDS) library
 Home-page: https://neo4j.com/product/graph-data-science/
 Author: Neo4j
@@ -16,7 +16,6 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -25,11 +24,21 @@ Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
-Requires-Python: >=3.7
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: multimethod<2.0,>=1.0
+Requires-Dist: neo4j<6.0,>=4.4.2
+Requires-Dist: pandas<3.0,>=1.0
+Requires-Dist: pyarrow<15.0,>=10.0
+Requires-Dist: textdistance<5.0,>=4.0
+Requires-Dist: tqdm<5.0,>=4.0
+Requires-Dist: typing-extensions<5.0,>=4.0
+Requires-Dist: requests
 Provides-Extra: ogb
+Requires-Dist: ogb<2.0,>=1.0; extra == "ogb"
 Provides-Extra: networkx
-License-File: LICENSE
+Requires-Dist: networkx<4.0,>=2.0; extra == "networkx"
 
 # Neo4j Graph Data Science Client
 
@@ -117,6 +126,7 @@ Full end-to-end examples in Jupyter ready-to-run notebooks can be found in the [
 * [Sampling, Export and Integration with PyG example](examples/import-sample-export-gnn.ipynb)
 * [Load data to a projected graph via graph construction](examples/load-data-via-graph-construction.ipynb)
 * [Heterogeneous Node Classification with HashGNN and Autotuning](https://github.com/neo4j/graph-data-science-client/tree/main/examples/heterogeneous-node-classification-with-hashgnn.ipynb)
+* [Perform inference using pre-trained KGE models](examples/kge-predict-transe-pyg-train.ipynb)
 
 
 ## Documentation

{graphdatascience-1.7a1 → graphdatascience-1.9}/README.md

@@ -84,6 +84,7 @@ Full end-to-end examples in Jupyter ready-to-run notebooks can be found in the [
 * [Sampling, Export and Integration with PyG example](examples/import-sample-export-gnn.ipynb)
 * [Load data to a projected graph via graph construction](examples/load-data-via-graph-construction.ipynb)
 * [Heterogeneous Node Classification with HashGNN and Autotuning](https://github.com/neo4j/graph-data-science-client/tree/main/examples/heterogeneous-node-classification-with-hashgnn.ipynb)
+* [Perform inference using pre-trained KGE models](examples/kge-predict-transe-pyg-train.ipynb)
 
 
 ## Documentation

graphdatascience-1.9/graphdatascience/__init__.py

@@ -0,0 +1,36 @@
+from .gds_session.gds_sessions import GdsSessions
+from .graph.graph_create_result import GraphCreateResult
+from .graph.graph_object import Graph
+from .graph_data_science import GraphDataScience
+from .model.graphsage_model import GraphSageModel
+from .model.link_prediction_model import LinkFeature, LPModel
+from .model.node_classification_model import NCModel
+from .model.node_regression_model import NRModel
+from .model.pipeline_model import NodePropertyStep
+from .model.simple_rel_embedding_model import SimpleRelEmbeddingModel
+from .pipeline.lp_training_pipeline import LPTrainingPipeline
+from .pipeline.nc_training_pipeline import NCTrainingPipeline
+from .pipeline.nr_training_pipeline import NRTrainingPipeline
+from .query_runner.query_runner import QueryRunner
+from .server_version.server_version import ServerVersion
+from .version import __version__
+
+__all__ = [
+    "GraphDataScience",
+    "GdsSessions",
+    "QueryRunner",
+    "__version__",
+    "ServerVersion",
+    "Graph",
+    "GraphCreateResult",
+    "LPTrainingPipeline",
+    "NCTrainingPipeline",
+    "NRTrainingPipeline",
+    "NodePropertyStep",
+    "LinkFeature",
+    "LPModel",
+    "NCModel",
+    "NRModel",
+    "GraphSageModel",
+    "SimpleRelEmbeddingModel",
+]

{graphdatascience-1.7a1 → graphdatascience-1.9}/graphdatascience/algo/algo_proc_runner.py

@@ -7,21 +7,15 @@ from ..error.illegal_attr_checker import IllegalAttrChecker
 from ..graph.graph_object import Graph
 from ..graph.graph_type_check import graph_type_check
 from ..model.graphsage_model import GraphSageModel
+from graphdatascience.call_parameters import CallParameters
 
 
 class AlgoProcRunner(IllegalAttrChecker, ABC):
     @graph_type_check
     def _run_procedure(self, G: Graph, config: Dict[str, Any], with_logging: bool = True) -> DataFrame:
-        query = f"CALL {self._namespace}($graph_name, $config)"
+        params = CallParameters(graph_name=G.name(), config=config)
 
-        params: Dict[str, Any] = {}
-        params["graph_name"] = G.name()
-        params["config"] = config
-
-        if with_logging:
-            return self._query_runner.run_query_with_logging(query, params)
-        else:
-            return self._query_runner.run_query(query, params)
+        return self._query_runner.call_procedure(endpoint=self._namespace, params=params, logging=with_logging)
 
     @graph_type_check
     def estimate(self, G: Graph, **config: Any) -> "Series[Any]":

graphdatascience-1.9/graphdatascience/algo/single_mode_algo_endpoints.py

@@ -0,0 +1,18 @@
+from ..caller_base import CallerBase
+from ..server_version.compatible_with import compatible_with
+from ..server_version.server_version import ServerVersion
+from .algo_proc_runner import StreamModeRunner
+
+
+# these algorithms have only one mode
+class SingleModeAlgoEndpoints(CallerBase):
+    @property
+    @compatible_with("triangles", min_inclusive=ServerVersion(2, 5, 0))
+    def triangles(self) -> StreamModeRunner:
+        return StreamModeRunner(self._query_runner, f"{self._namespace}.triangles", self._server_version)
+
+
+class SingleModeAlphaAlgoEndpoints(CallerBase):
+    @property
+    def triangles(self) -> StreamModeRunner:
+        return StreamModeRunner(self._query_runner, f"{self._namespace}.triangles", self._server_version)

graphdatascience-1.9/graphdatascience/call_parameters.py

@@ -0,0 +1,8 @@
+from typing import Any, OrderedDict
+
+
+class CallParameters(OrderedDict[str, Any]):
+    # since Python 3.6 also initializing through CallParameters(**kwargs) is order preserving
+
+    def placeholder_str(self) -> str:
+        return ", ".join([f"${k}" for k in self.keys()])

{graphdatascience-1.7a1 → graphdatascience-1.9}/graphdatascience/caller_base.py

@@ -13,7 +13,11 @@ class CallerBase(ABC):
         self._server_version = server_version
 
     def _raise_suggestive_error_message(self, requested_endpoint: str) -> NoReturn:
-        list_result = self._query_runner.run_query("CALL gds.list() YIELD name", custom_error=False)
+        list_result = self._query_runner.call_procedure(
+            endpoint="gds.list",
+            yields=["name"],
+            custom_error=False,
+        )
         all_endpoints = list_result["name"].tolist()
 
         raise SyntaxError(generate_suggestive_error_message(requested_endpoint, all_endpoints))

{graphdatascience-1.7a1 → graphdatascience-1.9}/graphdatascience/endpoints.py

@@ -1,10 +1,9 @@
-from .algo.single_mode_algo_endpoints import SingleModeAlgoEndpoints
-from .call_builder import IndirectAlphaCallBuilder, IndirectBetaCallBuilder
-from .graph.graph_endpoints import (
-    GraphAlphaEndpoints,
-    GraphBetaEndpoints,
-    GraphEndpoints,
+from .algo.single_mode_algo_endpoints import (
+    SingleModeAlgoEndpoints,
+    SingleModeAlphaAlgoEndpoints,
 )
+from .call_builder import IndirectAlphaCallBuilder, IndirectBetaCallBuilder
+from .graph.graph_endpoints import GraphAlphaEndpoints, GraphBetaEndpoints
 from .model.model_endpoints import (
     ModelAlphaEndpoints,
     ModelBetaEndpoints,
@@ -17,7 +16,7 @@ from .pipeline.pipeline_endpoints import (
 )
 from .query_runner.query_runner import QueryRunner
 from .server_version.server_version import ServerVersion
-from .system.config_endpoints import ConfigEndpoints
+from .system.config_endpoints import AlphaConfigEndpoints, ConfigEndpoints
 from .system.system_endpoints import (
     DirectSystemEndpoints,
     SystemAlphaEndpoints,
@@ -32,14 +31,21 @@ the `gds` namespace. Example of such endpoints are: "graph" and "list".
 """
 
 
-class DirectEndpoints(DirectSystemEndpoints, DirectUtilEndpoints, GraphEndpoints, PipelineEndpoints, ModelEndpoints):
+class DirectEndpoints(
+    SingleModeAlgoEndpoints,
+    DirectSystemEndpoints,
+    DirectUtilEndpoints,
+    PipelineEndpoints,
+    ModelEndpoints,
+    ConfigEndpoints,
+):
     def __init__(self, query_runner: QueryRunner, namespace: str, server_version: ServerVersion):
         super().__init__(query_runner, namespace, server_version)
 
 
 """
 This class should inherit endpoint classes that only expose calls of the `gds.beta` namespace.
-Example of such endpoints are: "gds.alpha.model.store" and "gds.alpha.listProgress".
+Example of such endpoints: "gds.alpha.listProgress".
 """
 
 
@@ -48,9 +54,9 @@ class AlphaEndpoints(
     PipelineAlphaEndpoints,
     TopologicalLPAlphaEndpoints,
     ModelAlphaEndpoints,
-    SingleModeAlgoEndpoints,
+    SingleModeAlphaAlgoEndpoints,
     SystemAlphaEndpoints,
-    ConfigEndpoints,
+    AlphaConfigEndpoints,
 ):
     def __init__(self, query_runner: QueryRunner, namespace: str, server_version: ServerVersion):
         super().__init__(query_runner, namespace, server_version)
@@ -61,7 +67,7 @@ class AlphaEndpoints(
 
 """
 This class should inherit endpoint classes that only expose calls of the `gds.beta` namespace.
-Example of such endpoints are: "gds.beta.model.list" and "gds.beta.listProgress".
+Example of such endpoints:  "gds.beta.listProgress".
 """
 
 

{graphdatascience-1.7a1 → graphdatascience-1.9}/graphdatascience/error/client_only_endpoint.py

@@ -1,3 +1,4 @@
+import warnings
 from functools import wraps
 from typing import Any, Callable, TypeVar, cast
 
@@ -23,3 +24,20 @@ def client_only_endpoint(expected_namespace_prefix: str) -> Callable[[F], F]:
         return cast(F, wrapper)
 
     return decorator
+
+
+def client_deprecated(
+    old_endpoint: str,
+    new_endpoint: str,
+) -> Callable[[F], F]:
+    def decorator(func: F) -> F:
+        wraps(func)
+
+        @wraps(func)
+        def wrapper(self: CallerBase, *args: Any, **kwargs: Any) -> Any:
+            warnings.warn(f"Deprecated `{old_endpoint}` in favor of `{new_endpoint}`", DeprecationWarning)
+            return func(self, *args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator

graphdatascience-1.9/graphdatascience/error/cypher_warning_handler.py

@@ -0,0 +1,31 @@
+import warnings
+from functools import wraps
+from typing import Any, Callable, TypeVar, cast
+
+from ..caller_base import CallerBase
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def filter_id_func_deprecation_warning() -> Callable[[F], F]:
+    def decorator(func: F) -> F:
+        wraps(func)
+
+        @wraps(func)
+        def wrapper(self: CallerBase, *args: Any, **kwargs: Any) -> Any:
+            # GDS uses the numeric id to resolve the node
+            warnings.filterwarnings(
+                "ignore",
+                message=r"^The query used a deprecated function: `id`\.",
+            )
+
+            warnings.filterwarnings(
+                "ignore",
+                message=r"^The query used a deprecated function. \('id' is no longer supported\)",
+            )
+
+            return func(self, *args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator

graphdatascience-1.9/graphdatascience/error/gds_not_installed.py

@@ -0,0 +1,2 @@
+class GdsNotFound(Exception):
+    pass

graphdatascience-1.9/graphdatascience/gds_session/aura_api.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import dataclasses
+import logging
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, List, Optional
+from urllib.parse import urlparse
+
+import requests as req
+from requests import HTTPError
+
+from graphdatascience.version import __version__
+
+
+@dataclass(repr=True)
+class InstanceDetails:
+    id: str
+    name: str
+    tenant_id: str
+    cloud_provider: str
+
+    @classmethod
+    def fromJson(cls, json: dict[str, Any]) -> InstanceDetails:
+        return cls(
+            id=json["id"],
+            name=json["name"],
+            tenant_id=json["tenant_id"],
+            cloud_provider=json["cloud_provider"],
+        )
+
+
+@dataclass(repr=True)
+class InstanceSpecificDetails(InstanceDetails):
+    status: str
+    connection_url: str
+    memory: str
+    type: str
+    region: str
+
+    @classmethod
+    def fromJson(cls, json: dict[str, Any]) -> InstanceSpecificDetails:
+        return cls(
+            id=json["id"],
+            name=json["name"],
+            tenant_id=json["tenant_id"],
+            cloud_provider=json["cloud_provider"],
+            status=json["status"],
+            connection_url=json.get("connection_url", ""),
+            memory=json.get("memory", ""),
+            type=json["type"],
+            region=json["region"],
+        )
+
+
+@dataclass(repr=True)
+class InstanceCreateDetails:
+    id: str
+    username: str
+    password: str
+    connection_url: str
+
+    @classmethod
+    def from_json(cls, json: dict[str, Any]) -> InstanceCreateDetails:
+        fields = dataclasses.fields(cls)
+        if any(f.name not in json for f in fields):
+            raise RuntimeError(f"Missing required field. Expected `{[f.name for f in fields]}` but got `{json}`")
+
+        return cls(**{f.name: json[f.name] for f in fields})
+
+
+class AuraApi:
+    class AuraAuthToken:
+        access_token: str
+        expires_in: int
+        token_type: str
+
+        def __init__(self, json: dict[str, Any]) -> None:
+            self.access_token = json["access_token"]
+            expires_in: int = json["expires_in"]
+            self.expires_at = int(time.time()) + expires_in
+            self.token_type = json["token_type"]
+
+        def is_expired(self) -> bool:
+            return self.expires_at >= int(time.time())
+
+    def __init__(self, client_id: str, client_secret: str, tenant_id: Optional[str] = None) -> None:
+        self._dev_env = os.environ.get("AURA_ENV")
+        self._base_uri = "https://api.neo4j.io" if not self._dev_env else f"https://api-{self._dev_env}.neo4j-dev.io"
+        self._credentials = (client_id, client_secret)
+        self._token: Optional[AuraApi.AuraAuthToken] = None
+        self._logger = logging.getLogger()
+        self._tenant_id = tenant_id if tenant_id else self._get_tenant_id()
+
+    @staticmethod
+    def extract_id(uri: str) -> str:
+        host = urlparse(uri).hostname
+
+        if not host:
+            raise RuntimeError(f"Could not parse the uri `{uri}`.")
+
+        return host.split(".")[0].split("-")[0]
+
+    def create_instance(self, name: str, memory: str, cloud_provider: str, region: str) -> InstanceCreateDetails:
+        # TODO should give more control here
+        data = {
+            "name": name,
+            "memory": memory,
+            "version": "5",
+            "region": region,
+            # TODO should be figured out from the tenant details in the future
+            "type": self._instance_type(),
+            "tenant_id": self._tenant_id,
+            "cloud_provider": cloud_provider,
+        }
+
+        response = req.post(
+            f"{self._base_uri}/v1/instances",
+            json=data,
+            headers=self._build_header(),
+        )
+
+        try:
+            response.raise_for_status()
+        except HTTPError as e:
+            print(response.json())
+            raise e
+
+        return InstanceCreateDetails.from_json(response.json()["data"])
+
+    def delete_instance(self, instance_id: str) -> Optional[InstanceSpecificDetails]:
+        response = req.delete(
+            f"{self._base_uri}/v1/instances/{instance_id}",
+            headers=self._build_header(),
+        )
+
+        if response.status_code == 404:
+            return None
+
+        response.raise_for_status()
+
+        return InstanceSpecificDetails.fromJson(response.json()["data"])
+
+    def list_instances(self) -> List[InstanceDetails]:
+        response = req.get(
+            f"{self._base_uri}/v1/instances",
+            headers=self._build_header(),
+            params={"tenantId": self._tenant_id},
+        )
+
+        response.raise_for_status()
+
+        raw_data = response.json()["data"]
+
+        return [InstanceDetails.fromJson(i) for i in raw_data]
+
+    def list_instance(self, instance_id: str) -> Optional[InstanceSpecificDetails]:
+        response = req.get(
+            f"{self._base_uri}/v1/instances/{instance_id}",
+            headers=self._build_header(),
+        )
+
+        if response.status_code == 404:
+            return None
+
+        response.raise_for_status()
+
+        raw_data = response.json()["data"]
+
+        return InstanceSpecificDetails.fromJson(raw_data)
+
+    def wait_for_instance_running(
+        self, instance_id: str, sleep_time: float = 0.2, max_sleep_time: float = 300
+    ) -> Optional[str]:
+        waited_time = 0.0
+        while waited_time <= max_sleep_time:
+            instance = self.list_instance(instance_id)
+            if instance is None:
+                return "Instance is not found -- please retry"
+            elif instance.status in ["deleting", "destroying"]:
+                return "Instance is being deleted"
+            elif instance.status == "running":
+                return None
+            else:
+                self._logger.debug(
+                    f"Instance `{instance_id}` is not yet running. "
+                    f"Current status: {instance.status}. "
+                    f"Retrying in {sleep_time} seconds..."
+                )
+            waited_time += sleep_time
+            time.sleep(sleep_time)
+
+        return f"Instance is not running after waiting for {waited_time} seconds"
+
+    def _get_tenant_id(self) -> str:
+        response = req.get(
+            f"{self._base_uri}/v1/tenants",
+            headers=self._build_header(),
+        )
+        response.raise_for_status()
+
+        raw_data = response.json()["data"]
+
+        if len(raw_data) != 1:
+            raise RuntimeError(
+                f"This account has access to multiple tenants `{raw_data}`. Please specify which one to use."
+            )
+
+        return raw_data[0]["id"]  # type: ignore
+
+    def _build_header(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._auth_token()}", "User-agent": f"neo4j-graphdatascience-v{__version__}"}
+
+    def _auth_token(self) -> str:
+        if self._token is None or self._token.is_expired():
+            self._token = self._update_token()
+        return self._token.access_token
+
+    def _update_token(self) -> AuraAuthToken:
+        data = {
+            "grant_type": "client_credentials",
+        }
+
+        self._logger.debug("Updating oauth token")
+
+        response = req.post(
+            f"{self._base_uri}/oauth/token", data=data, auth=(self._credentials[0], self._credentials[1])
+        )
+
+        response.raise_for_status()
+
+        return AuraApi.AuraAuthToken(response.json())
+
+    def _instance_type(self) -> str:
+        return "enterprise-ds" if not self._dev_env else "professional-ds"