graphdatascience 1.20a1__tar.gz → 1.21__tar.gz

{graphdatascience-1.20a1/src/graphdatascience.egg-info → graphdatascience-1.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphdatascience
-Version: 1.20a1
+Version: 1.21
 Summary: A Python client for the Neo4j Graph Data Science (GDS) library
 Author-email: Neo4j <team-gds@neo4j.org>
 License-Expression: Apache-2.0

{graphdatascience-1.20a1 → graphdatascience-1.21}/pyproject.toml

@@ -54,13 +54,12 @@ rust-ext = ["neo4j-rust-ext >= 4.4.12, < 7.0"]
 
 
 [dependency-groups]
-# To install all development dependencies,
-# run `pip install --group dev -e .` inside repository root folder.#
 dev = [
     "tox>4.24",
     { include-group = "dev-base" },
     { include-group = "test" },
     { include-group = "docs-ci" },
+    { include-group = "notebook-base"}
 ]
 
 dev-base = [
@@ -79,6 +78,7 @@ dev-base = [
 ]
 test = [
     "pytest == 9.0.2",
+    "pytest-timeout",
     "requests_mock == 1.12.1",
     "pytest_mock == 3.15.1",
     "testcontainers == 4.14.0",
@@ -89,6 +89,7 @@ docs-ci = [
     "sphinx == 7.3.7",
     "enum-tools[sphinx]==0.13.0",
     "autodoc_pydantic",
+    "networkx >= 2.0, < 4.0"
 ]
 notebook-base = [
     "nbconvert==7.16.6",
@@ -111,6 +112,10 @@ notebook-ci = [
 
 publish = ["build", "twine"]
 
+[tool.uv.extra-build-dependencies]
+torch-sparse = ["torch"]
+torch-scatter = ["torch"]
+
 [tool.setuptools]
 include-package-data = true
 zip-safe = false

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/arrow_client/arrow_info.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from ..query_runner.query_runner import QueryRunner
-from ..server_version.server_version import ServerVersion
+from graphdatascience.query_runner.query_runner import QueryRunner
+from graphdatascience.query_runner.query_type import QueryType
+from graphdatascience.server_version.server_version import ServerVersion
 
 
 @dataclass(frozen=True)
@@ -20,7 +21,7 @@ class ArrowInfo:
             debugYields.append("versions")
 
         procResult = query_runner.call_procedure(
-            endpoint="gds.debug.arrow", custom_error=False, yields=debugYields
+            endpoint="gds.debug.arrow", query_type=QueryType.SYSTEM, custom_error=False, yields=debugYields
         ).iloc[0]
 
         return ArrowInfo(

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/arrow_client/v2/mutation_client.py

@@ -10,11 +10,17 @@ class MutationClient:
     MUTATE_ENDPOINT = "v2/results.mutate"
 
     @staticmethod
-    def mutate_node_property(client: AuthenticatedArrowClient, job_id: str, mutate_property: str) -> MutateResult:
+    def mutate_node_property(
+        client: AuthenticatedArrowClient,
+        result_store_job_id: str,
+        mutate_property: str,
+        process_job_id: str | None = None,
+    ) -> MutateResult:
         return MutationClient._mutate(
             client=client,
-            job_id=job_id,
+            result_store_job_id=result_store_job_id,
             mutate_property=mutate_property,
+            process_job_id=process_job_id,
         )
 
     @staticmethod
@@ -26,7 +32,7 @@ class MutationClient:
     ) -> MutateResult:
         return MutationClient._mutate(
             client=client,
-            job_id=job_id,
+            result_store_job_id=job_id,
             mutate_property=mutate_property,
             mutate_relationship_type=mutate_relationship_type,
         )
@@ -34,13 +40,16 @@ class MutationClient:
     @staticmethod
     def _mutate(
         client: AuthenticatedArrowClient,
-        job_id: str,
+        result_store_job_id: str,
+        process_job_id: str | None = None,
         mutate_property: str | None = None,
         mutate_relationship_type: str | None = None,
     ) -> MutateResult:
         mutate_config = {
-            "jobId": job_id,
+            "jobId": result_store_job_id,
         }
+        if process_job_id:
+            mutate_config["processJobId"] = process_job_id
         if mutate_relationship_type:
             mutate_config["mutateRelationshipType"] = mutate_relationship_type
         if mutate_property:

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/endpoints.py

@@ -43,6 +43,17 @@ class DirectEndpoints(
         super().__init__(query_runner, namespace, server_version)
 
 
+class DirectSessionEndpoints(
+    SingleModeAlgoEndpoints,
+    DirectSystemEndpoints,
+    DirectUtilEndpoints,
+    PipelineEndpoints,
+    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.alpha` namespace.
 Example of such endpoints: "gds.alpha.listProgress".

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/graph/graph_cypher_runner.py

@@ -6,13 +6,13 @@ from typing import Any
 
 from pandas import Series
 
+from graphdatascience.caller_base import CallerBase
+from graphdatascience.graph.graph_create_result import GraphCreateResult
+from graphdatascience.graph.graph_object import Graph
 from graphdatascience.query_runner.query_mode import QueryMode
-
-from ..caller_base import CallerBase
-from ..query_runner.query_runner import QueryRunner
-from ..server_version.server_version import ServerVersion
-from .graph_create_result import GraphCreateResult
-from .graph_object import Graph
+from graphdatascience.query_runner.query_runner import QueryRunner
+from graphdatascience.query_runner.query_type import QueryType
+from graphdatascience.server_version.server_version import ServerVersion
 
 
 class GraphCypherRunner(CallerBase):
@@ -48,7 +48,7 @@ class GraphCypherRunner(CallerBase):
         GraphCypherRunner._verify_query_ends_with_return_clause(self._namespace, query)
 
         result: dict[str, Any] | None = self._query_runner.run_retryable_cypher(
-            query, params, database, custom_error=False, mode=QueryMode.READ
+            query, QueryType.USER_DIRECTED, params, database, custom_error=False, mode=QueryMode.READ
         ).squeeze()
 
         if not result:

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/graph/graph_entity_ops_runner.py

@@ -8,6 +8,7 @@ import pandas as pd
 from pandas import DataFrame, Series
 
 from graphdatascience.query_runner.query_mode import QueryMode
+from graphdatascience.query_runner.query_type import QueryType
 
 from ..call_parameters import CallParameters
 from ..error.cypher_warning_handler import (
@@ -169,6 +170,7 @@ class GraphNodePropertiesRunner(GraphEntityOpsBaseRunner):
 
             db_properties_df = query_runner.run_retryable_cypher(
                 GraphNodePropertiesRunner._build_query(db_node_properties),
+                QueryType.USER_TRANSPILED,
                 params={"ids": unique_node_ids},
                 mode=QueryMode.READ,
             )

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/graph/v2/graph_api.py

@@ -106,7 +106,7 @@ class GraphV2:
         """
         return self._backend.graph_info().density
 
-    def memory_usage(self) -> str:
+    def memory_usage(self) -> str | None:
         """
         Returns:
             the memory usage of the graph

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/graph_data_science.py

@@ -22,6 +22,7 @@ from .query_runner.arrow_info import ArrowInfo
 from .query_runner.arrow_query_runner import ArrowQueryRunner
 from .query_runner.neo4j_query_runner import Neo4jQueryRunner
 from .query_runner.query_runner import QueryRunner
+from .query_runner.query_type import QueryType
 from .server_version.server_version import ServerVersion
 from .utils.util_proc_runner import UtilProcRunner
 from .version import __min_server_version__
@@ -93,7 +94,7 @@ class GraphDataScience(DirectEndpoints, UncallableNamespace):
         if isinstance(endpoint, QueryRunner):
             self._query_runner = endpoint
         else:
-            db_auth = None
+            db_auth: neo4j.Auth | None = None
             if auth:
                 db_auth = neo4j.basic_auth(*auth)
             neo4j_query_runner = Neo4jQueryRunner.create_for_db(
@@ -118,21 +119,29 @@ class GraphDataScience(DirectEndpoints, UncallableNamespace):
             if auth is not None:
                 username, password = auth
                 arrow_auth = UsernamePasswordAuthentication(username, password)
+            if isinstance(endpoint, Neo4jQueryRunner):
+                if neo4j_auth := endpoint.get_auth():
+                    arrow_auth = UsernamePasswordAuthentication(neo4j_auth[0], neo4j_auth[1])
 
-            if arrow_client_options is None:
-                arrow_client_options = {}
-            if arrow_disable_server_verification:
-                disable_server_verification(arrow_client_options)
-            if arrow_tls_root_certs is not None:
-                set_tls_root_certs(arrow_client_options, arrow_tls_root_certs)
-            self._query_runner = ArrowQueryRunner.create(
-                self._query_runner,
-                arrow_info=arrow_info,
-                arrow_authentication=arrow_auth,
-                encrypted=self._query_runner.encrypted(),
-                arrow_client_options=arrow_client_options,
-                connection_string_override=None if arrow is True else arrow,
-            )
+            if isinstance(endpoint, Driver) and not auth:
+                warnings.warn(
+                    "Falling back to use Cypher for GDS. To use Arrow, you must explicitly provide the `auth` parameter."
+                )
+            else:
+                if arrow_client_options is None:
+                    arrow_client_options = {}
+                if arrow_disable_server_verification:
+                    disable_server_verification(arrow_client_options)
+                if arrow_tls_root_certs is not None:
+                    set_tls_root_certs(arrow_client_options, arrow_tls_root_certs)
+                self._query_runner = ArrowQueryRunner.create(
+                    self._query_runner,
+                    arrow_info=arrow_info,
+                    arrow_authentication=arrow_auth,
+                    encrypted=self._query_runner.encrypted(),
+                    arrow_client_options=arrow_client_options,
+                    connection_string_override=None if arrow is True else arrow,
+                )
 
         arrow_client = (
             None if not isinstance(self._query_runner, ArrowQueryRunner) else self._query_runner._gds_arrow_client
@@ -258,15 +267,16 @@ class GraphDataScience(DirectEndpoints, UncallableNamespace):
             The query result as a DataFrame
         """
         qr = self._query_runner
+        query_type = QueryType.USER_DIRECTED
 
         # The Arrow query runner should not be used to execute arbitrary Cypher
         if isinstance(self._query_runner, ArrowQueryRunner):
             qr = self._query_runner.fallback_query_runner()
 
         if retryable:
-            return qr.run_retryable_cypher(query, params, database, custom_error=False, mode=mode)
+            return qr.run_retryable_cypher(query, query_type, params, database, custom_error=False, mode=mode)
         else:
-            return qr.run_cypher(query, params, database, custom_error=False, mode=mode)
+            return qr.run_cypher(query, query_type, params, database, custom_error=False, mode=mode)
 
     def driver_config(self) -> dict[str, Any]:
         """
@@ -310,6 +320,7 @@ class GraphDataScience(DirectEndpoints, UncallableNamespace):
             The Neo4j Driver instance to use.
         auth : tuple[str, str] | None, default None
             A username, password pair for authentication.
+            Is required for enabling Arrow.
         database: str | None, default None
             The Neo4j database to query against.
         arrow : str | bool, default True

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/procedure_surface/api/catalog/catalog_endpoints.py

@@ -2,9 +2,10 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from types import TracebackType
-from typing import NamedTuple, Type
+from typing import Any, NamedTuple, Type
 
 from pandas import DataFrame
+from pydantic import field_validator
 
 from graphdatascience.graph.v2.graph_api import GraphV2
 from graphdatascience.procedure_surface.api.base_result import BaseResult
@@ -245,7 +246,12 @@ class GraphGenerationStats(BaseResult):
     relationship_seed: int | None
     average_degree: float
     relationship_distribution: str
-    relationship_property: RelationshipPropertySpec
+    relationship_property: RelationshipPropertySpec | None
+
+    @field_validator("relationship_property", mode="before")
+    @classmethod
+    def check_empty_property(cls, value: Any) -> Any:
+        return value or None
 
 
 class RelationshipPropertySpec(BaseResult):

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/procedure_surface/api/catalog/graph_info.py

@@ -15,7 +15,7 @@ class GraphInfo(BaseResult):
     database: str
     database_location: str
     configuration: dict[str, Any]
-    memory_usage: str
+    memory_usage: str | None  # can be none if there was an error computing the usage
     size_in_bytes: int
     node_count: int
     relationship_count: int

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/procedure_surface/api/catalog/graph_sampling_endpoints.py

@@ -7,6 +7,7 @@ from typing import NamedTuple, Type
 from graphdatascience.graph.v2.graph_api import GraphV2
 from graphdatascience.procedure_surface.api.base_result import BaseResult
 from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
+from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
 
 
 class GraphSamplingEndpoints(ABC):
@@ -146,6 +147,54 @@ class GraphSamplingEndpoints(ABC):
         """
         pass
 
+    @abstractmethod
+    def estimate(
+        self,
+        G: GraphV2,
+        start_nodes: list[int] | None = None,
+        restart_probability: float = 0.1,
+        sampling_ratio: float = 0.15,
+        node_label_stratification: bool = False,
+        relationship_weight_property: str | None = None,
+        relationship_types: list[str] = ALL_TYPES,
+        node_labels: list[str] = ALL_LABELS,
+        concurrency: int | None = None,
+    ) -> EstimationResult:
+        """
+        Estimate the memory consumption of a CNARW algorithm run.
+
+        Parameters
+        ----------
+        G
+            Graph object to use
+        start_nodes : list of int, optional
+            IDs of the initial set of nodes in the original graph from which the sampling random walks will start.
+            By default, a single node is chosen uniformly at random.
+        restart_probability : float, optional
+            The probability that a sampling random walk restarts from one of the start nodes.
+            Default is 0.1.
+        sampling_ratio : float, optional
+            The fraction of nodes in the original graph to be sampled.
+            Default is 0.15.
+        node_label_stratification : bool, optional
+            If true, preserves the node label distribution of the original graph.
+            Default is False.
+        relationship_weight_property
+            Name of the property to be used as weights.
+        relationship_types
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
+        node_labels
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
+        concurrency
+            Number of concurrent threads to use.
+
+        Returns
+        -------
+        EstimationResult
+            Memory estimation details
+        """
+        pass
+
 
 class GraphSamplingResult(BaseResult):
     graph_name: str

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/procedure_surface/api/model/model_catalog_endpoints.py

@@ -69,7 +69,7 @@ class ModelCatalogEndpoints(ABC):
         """
 
     @abstractmethod
-    def drop(self, model_name: str, *, fail_if_missing: bool = False) -> ModelDetails:
+    def drop(self, model_name: str, *, fail_if_missing: bool = False) -> ModelDetails | None:
         """Drop a model from the in-memory catalog.
 
         Parameters
@@ -86,13 +86,15 @@ class ModelCatalogEndpoints(ABC):
         """
 
     @abstractmethod
-    def delete(self, model_name: str) -> ModelDeleteResult:
+    def delete(self, model_name: str, fail_if_missing: bool = False) -> ModelDeleteResult | None:
         """Delete a persisted model from storage.
 
         Parameters
         ----------
         model_name: str
             The model to delete.
+        fail_if_missing: bool
+            If True, a missing model will cause an error. If False, returns None when missing.
 
         Returns
         -------

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/procedure_surface/api/pathfinding/__init__.py

@@ -27,6 +27,12 @@ from graphdatascience.procedure_surface.api.pathfinding.max_flow_endpoints impor
     MaxFlowStatsResult,
     MaxFlowWriteResult,
 )
+from graphdatascience.procedure_surface.api.pathfinding.max_flow_min_cost_endpoints import (
+    MaxFlowMinCostEndpoints,
+    MaxFlowMinCostMutateResult,
+    MaxFlowMinCostStatsResult,
+    MaxFlowMinCostWriteResult,
+)
 from graphdatascience.procedure_surface.api.pathfinding.prize_steiner_tree_endpoints import (
     PrizeSteinerTreeEndpoints,
     PrizeSteinerTreeMutateResult,
@@ -105,6 +111,10 @@ __all__ = [
     "MaxFlowWriteResult",
     "MaxFlowStatsResult",
     "MaxFlowMutateResult",
+    "MaxFlowMinCostEndpoints",
+    "MaxFlowMinCostWriteResult",
+    "MaxFlowMinCostStatsResult",
+    "MaxFlowMinCostMutateResult",
     "PrizeSteinerTreeEndpoints",
     "PrizeSteinerTreeMutateResult",
     "PrizeSteinerTreeStatsResult",

{graphdatascience-1.20a1 → graphdatascience-1.21}/src/graphdatascience/procedure_surface/api/pathfinding/max_flow_endpoints.py

@@ -9,9 +9,18 @@ from graphdatascience.graph.v2.graph_api import GraphV2
 from graphdatascience.procedure_surface.api.base_result import BaseResult
 from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
 from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
+from graphdatascience.procedure_surface.api.pathfinding.max_flow_min_cost_endpoints import MaxFlowMinCostEndpoints
 
 
 class MaxFlowEndpoints(ABC):
+    @property
+    @abstractmethod
+    def min_cost(self) -> MaxFlowMinCostEndpoints:
+        """
+        Container for Min-Cost Max Flow algorithm endpoints.
+        """
+        ...
+
     @abstractmethod
     def mutate(
         self,