rushdb 2.3.0__tar.gz → 2.9.0__tar.gz

{rushdb-2.3.0 → rushdb-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rushdb
-Version: 2.3.0
+Version: 2.9.0
 Summary: RushDB Python SDK — memory layer for AI agents and modern apps
 Project-URL: Homepage, https://github.com/rush-db/rushdb-python
 Project-URL: Repository, https://github.com/rush-db/rushdb-python
@@ -135,6 +135,28 @@ authored_posts = db.records.find({
     'limit': 10,
 })
 
+# Multi-hop: add hops to $relation — everyone in Alice's reporting chain, up to 4 levels
+chain = db.records.find({
+    'labels': ['EMPLOYEE'],
+    'where': {
+        'EMPLOYEE': {
+            '$relation': {'type': 'REPORTS_TO', 'direction': 'out', 'hops': {'min': 1, 'max': 4}},
+            'name': {'$contains': 'Alice'},
+        }
+    },
+})
+
+# Cycle detection: accounts on a circular transfer ring (fraud rings, circular ownership)
+ring_members = db.records.find({
+    'labels': ['ACCOUNT'],
+    'where': {
+        'RING': {  # key is a display name — the $cycle block holds only $relation
+            '$cycle': True,
+            '$relation': {'type': 'TRANSFERRED_TO', 'direction': 'out', 'hops': {'min': 2, 'max': 6}},
+        }
+    },
+})
+
 # Manage relationships explicitly
 user = db.records.find_uniq({'labels': ['USER'], 'where': {'name': 'Alice'}})
 company = db.records.find_uniq({'labels': ['COMPANY'], 'where': {'name': 'Acme Corp'}})
@@ -161,7 +183,8 @@ csv_data = "name,email,age\nJohn,john@example.com,30\nJane,jane@example.com,25"
 db.records.import_csv(
     label='USER',
     data=csv_data,
-    options={'returnResult': True, 'suggestTypes': True},
+    # skipEmptyValues: treat empty cells ("" / []) as unset instead of storing them (0/False are kept)
+    options={'returnResult': True, 'suggestTypes': True, 'skipEmptyValues': True},
     parse_config={'header': True, 'skipEmptyLines': True, 'dynamicTyping': True},
 )
 ```

{rushdb-2.3.0 → rushdb-2.9.0}/README.md

@@ -110,6 +110,28 @@ authored_posts = db.records.find({
     'limit': 10,
 })
 
+# Multi-hop: add hops to $relation — everyone in Alice's reporting chain, up to 4 levels
+chain = db.records.find({
+    'labels': ['EMPLOYEE'],
+    'where': {
+        'EMPLOYEE': {
+            '$relation': {'type': 'REPORTS_TO', 'direction': 'out', 'hops': {'min': 1, 'max': 4}},
+            'name': {'$contains': 'Alice'},
+        }
+    },
+})
+
+# Cycle detection: accounts on a circular transfer ring (fraud rings, circular ownership)
+ring_members = db.records.find({
+    'labels': ['ACCOUNT'],
+    'where': {
+        'RING': {  # key is a display name — the $cycle block holds only $relation
+            '$cycle': True,
+            '$relation': {'type': 'TRANSFERRED_TO', 'direction': 'out', 'hops': {'min': 2, 'max': 6}},
+        }
+    },
+})
+
 # Manage relationships explicitly
 user = db.records.find_uniq({'labels': ['USER'], 'where': {'name': 'Alice'}})
 company = db.records.find_uniq({'labels': ['COMPANY'], 'where': {'name': 'Acme Corp'}})
@@ -136,7 +158,8 @@ csv_data = "name,email,age\nJohn,john@example.com,30\nJane,jane@example.com,25"
 db.records.import_csv(
     label='USER',
     data=csv_data,
-    options={'returnResult': True, 'suggestTypes': True},
+    # skipEmptyValues: treat empty cells ("" / []) as unset instead of storing them (0/False are kept)
+    options={'returnResult': True, 'suggestTypes': True, 'skipEmptyValues': True},
     parse_config={'header': True, 'skipEmptyLines': True, 'dynamicTyping': True},
 )
 ```

{rushdb-2.3.0 → rushdb-2.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rushdb"
-version = "2.3.0"
+version = "2.9.0"
 description = "RushDB Python SDK — memory layer for AI agents and modern apps"
 authors = [
     {name = "RushDB Team", email = "hi@rushdb.com"}

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/__init__.py

@@ -24,6 +24,9 @@ from .models.search_query import (
     RelationshipEndpointQuery,
     RelationshipSearchQuery,
     SearchQuery,
+    TraversalHops,
+    TraversalHopsRange,
+    TraversalRelationOptions,
 )
 from .models.transaction import Transaction
 
@@ -46,6 +49,9 @@ __all__ = [
     "SearchQuery",
     "RelationshipEndpointQuery",
     "RelationshipSearchQuery",
+    "TraversalHops",
+    "TraversalHopsRange",
+    "TraversalRelationOptions",
     "QueryAPI",
     "RelationsAPI",
     "RelationshipPatternsAPI",

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/api/ai.py

@@ -1,6 +1,6 @@
 """AI API for RushDB Python SDK.
 
-Provides methods for graph ontology exploration, semantic vector search,
+Provides methods for graph schema exploration, semantic vector search,
 and embedding index management.
 """
 
@@ -123,7 +123,7 @@ class AIAPI(BaseAPI):
     Example::
 
         >>> db = RushDB(api_key="...")
-        >>> ontology = db.ai.get_ontology()
+        >>> schema = db.ai.get_schema()
         >>> results = db.ai.search({"query": "fast cars", "propertyName": "description"})
         >>> db.ai.indexes.create({"propertyName": "description", "label": "Book"})
     """
@@ -132,12 +132,12 @@ class AIAPI(BaseAPI):
         super().__init__(client)
         self.indexes = _AIIndexesNamespace(client)
 
-    def get_ontology(
+    def get_schema(
         self,
         params: Optional[Dict[str, Any]] = None,
         transaction: Optional[Union[Transaction, str]] = None,
     ) -> ApiResponse:
-        """Return the full graph ontology as structured JSON.
+        """Return the full graph schema as structured JSON.
 
         Each item contains the label name, record count, properties with value
         ranges/samples, and cross-label relationships with direction.
@@ -149,13 +149,13 @@ class AIAPI(BaseAPI):
 
         Args:
             params: Optional filter. Pass ``{"labels": ["Label1"]}`` to scope
-                the ontology to specific labels only. Pass ``{"force": True}``
-                to bypass the 1-hour ontology cache and trigger a full
+                the schema to specific labels only. Pass ``{"force": True}``
+                to bypass the 1-hour schema cache and trigger a full
                 recalculation.
             transaction: Optional transaction context.
 
         Returns:
-            ApiResponse: Response whose ``data`` is a list of ontology items.
+            ApiResponse: Response whose ``data`` is a list of schema items.
         """
         headers: Dict[str, str] = {}
         if transaction is not None:
@@ -165,7 +165,7 @@ class AIAPI(BaseAPI):
             headers["x-transaction-id"] = tx_id
 
         response = self.client._make_request(
-            "POST", "/ai/ontology", params or {}, headers=headers or None
+            "POST", "/ai/schema", params or {}, headers=headers or None
         )
         return ApiResponse(
             data=response.get("data"),
@@ -173,12 +173,12 @@ class AIAPI(BaseAPI):
             total=response.get("total"),
         )
 
-    def get_ontology_markdown(
+    def get_schema_markdown(
         self,
         params: Optional[Dict[str, Any]] = None,
         transaction: Optional[Union[Transaction, str]] = None,
     ) -> ApiResponse:
-        """Return the full graph ontology as compact Markdown tables.
+        """Return the full graph schema as compact Markdown tables.
 
         Token-efficient representation intended for direct LLM consumption.
         Includes labels with counts, properties with types and value
@@ -191,7 +191,7 @@ class AIAPI(BaseAPI):
         Args:
             params: Optional filter. Pass ``{"labels": ["Label1"]}`` to scope
                 the output to specific labels only. Pass ``{"force": True}``
-                to bypass the 1-hour ontology cache and trigger a full
+                to bypass the 1-hour schema cache and trigger a full
                 recalculation.
             transaction: Optional transaction context.
 
@@ -206,7 +206,7 @@ class AIAPI(BaseAPI):
             headers["x-transaction-id"] = tx_id
 
         response = self.client._make_request(
-            "POST", "/ai/ontology/md", params or {}, headers=headers or None
+            "POST", "/ai/schema/md", params or {}, headers=headers or None
         )
         return ApiResponse(
             data=response.get("data"),

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/api/records.py

@@ -172,6 +172,8 @@ class RecordsAPI(BaseAPI):
                 Available options:
                 - returnResult (bool): Whether to return the created record data. Defaults to True.
                 - suggestTypes (bool): Whether to automatically suggest data types. Defaults to True.
+                - skipEmptyValues (bool): Treat empty strings ("") and empty arrays ([]) as unset —
+                  no property is created. 0 and False are kept. Defaults to False.
             vectors (Optional[List[Dict[str, Any]]]): Optional pre-computed embedding vectors
                 to write alongside the record. Each entry must contain at least
                 ``propertyName`` and ``vector``; ``similarityFunction`` is required when
@@ -231,7 +233,9 @@ class RecordsAPI(BaseAPI):
                 record. Nested objects/arrays are not supported here — raises
                 ``ValueError`` if any item contains a nested object or list.
             options: Optional write options forwarded as-is to the server
-                (e.g. ``suggestTypes``, ``mergeBy``, ``mergeStrategy``, etc.).
+                (e.g. ``suggestTypes``, ``skipEmptyValues``, ``mergeBy``,
+                ``mergeStrategy``, etc.). ``skipEmptyValues`` treats empty strings
+                and empty arrays as unset (``0``/``False`` are kept); defaults to False.
             vectors: Optional per-row inline vectors for external embedding indexes.
                 ``vectors[i]`` is applied to ``data[i]``. Each element is a list of
                 vector entry dicts: ``[{"propertyName": str, "vector": List[float],

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/api/relationship_patterns.py

@@ -10,7 +10,7 @@ if TYPE_CHECKING:
 
 
 class RelationshipPatternsAPI(BaseAPI):
-    """Review and manage relationship patterns inferred from project ontology.
+    """Review and manage relationship patterns inferred from project schema.
 
     Accessed via ``db.relationships.patterns``.
     """
@@ -27,12 +27,12 @@ class RelationshipPatternsAPI(BaseAPI):
         )
 
     def list(self) -> ApiResponse:
-        """List inferred patterns, ontology relationships, and analysis status."""
+        """List inferred patterns, schema relationships, and analysis status."""
         response = self.client._make_request("GET", "/relationships/patterns")
         return self._wrap(response)
 
     def analyze(self) -> ApiResponse:
-        """Queue ontology analysis to generate relationship pattern suggestions."""
+        """Queue schema analysis to generate relationship pattern suggestions."""
         response = self.client._make_request(
             "POST", "/relationships/patterns/analyze", {}
         )

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/api/transactions.py

@@ -51,7 +51,8 @@ class TransactionsAPI(BaseAPI):
         Args:
             ttl (Optional[int], optional): Time-to-live in milliseconds for the transaction.
                 After this time, the transaction will automatically expire and be rolled back.
-                If None, defaults to 5000ms (5 seconds). Defaults to None.
+                If None, defaults to 5000ms (5 seconds). Values above the server-side cap
+                (60 seconds) are clamped to it. Defaults to None.
 
         Returns:
             Transaction: A Transaction object that can be used with other API operations.

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/client.py

@@ -144,7 +144,9 @@ class RushDB:
             else None
         )
         effective_url = url or base_url or self.DEFAULT_BASE_URL
-        if url and "/api/" not in effective_url:
+        # Both `url` and its deprecated alias `base_url` are documented to get
+        # `/api/v1` appended when the path is absent.
+        if (url or base_url) and "/api/" not in effective_url:
             effective_url = effective_url.rstrip("/") + "/api/v1"
         self.base_url = effective_url.rstrip("/")
         self.api_key = api_key
@@ -245,8 +247,17 @@ class RushDB:
             with urllib.request.urlopen(request) as response:
                 return json.loads(response.read().decode("utf-8"))
         except urllib.error.HTTPError as e:
-            error_body = json.loads(e.read().decode("utf-8"))
-            raise RushDBError(error_body.get("message", str(e)), error_body)
+            # Error bodies are usually JSON, but a gateway/proxy may return HTML or an
+            # empty body — without this guard the JSONDecodeError raised here would
+            # escape as-is instead of surfacing as a RushDBError.
+            try:
+                error_body = json.loads(e.read().decode("utf-8"))
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                error_body = {}
+            message = error_body.get("message")
+            if isinstance(message, list):
+                message = "; ".join(str(item) for item in message)
+            raise RushDBError(message or f"HTTP {e.code}", error_body, status=e.code)
         except urllib.error.URLError as e:
             raise RushDBError(f"Connection error: {str(e)}")
         except json.JSONDecodeError as e:

rushdb-2.9.0/src/rushdb/common.py

@@ -0,0 +1,33 @@
+from typing import Dict, Optional
+
+
+class RushDBError(Exception):
+    """Custom exception for RushDB client errors.
+
+    Attributes:
+        details: Parsed error response body from the server, if any.
+        status: HTTP status code for server errors (e.g. 403 for a write attempt
+            with a read-only API key, 408 for a server-side transaction timeout).
+            ``None`` for client-side errors such as connection failures.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict] = None,
+        status: Optional[int] = None,
+    ):
+        super().__init__(message)
+        self.details = details or {}
+        self.status = status
+
+
+class NonUniqueResultError(Exception):
+    """Raised by ``records.find_uniq()`` when more than one record matches the query."""
+
+    def __init__(self, count: int):
+        super().__init__(
+            f"Expected at most one record but found {count}. "
+            "Refine your search query or use records.find() instead."
+        )
+        self.count = count

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/models/__init__.py

@@ -11,6 +11,9 @@ from .search_query import (
     RelationshipEndpointQuery,
     RelationshipSearchQuery,
     SearchQuery,
+    TraversalHops,
+    TraversalHopsRange,
+    TraversalRelationOptions,
 )
 from .transaction import Transaction
 
@@ -26,5 +29,8 @@ __all__ = [
     "SearchQuery",
     "RelationshipEndpointQuery",
     "RelationshipSearchQuery",
+    "TraversalHops",
+    "TraversalHopsRange",
+    "TraversalRelationOptions",
     "Transaction",
 ]

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/models/api_response.py

@@ -19,7 +19,7 @@ class ApiResponse(Generic[T]):
         total: Optional total count (e.g. for list endpoints).
 
     Example:
-        >>> response = db.ai.get_ontology_markdown()
+        >>> response = db.ai.get_schema_markdown()
         >>> schema_md = response.data          # str
         >>> response = db.ai.indexes.find()
         >>> indexes = response.data            # list[dict]

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/models/property.py

@@ -21,8 +21,9 @@ BooleanValue = bool
 NumberValue = Union[float, int]
 StringValue = str
 
-# Property types
-PropertyType = Literal["boolean", "datetime", "null", "number", "string"]
+# Property types. A None/null value means the field is unset; `None` is still accepted as an
+# input value in `PropertyWithValue.value` below.
+PropertyType = Literal["boolean", "datetime", "number", "string"]
 
 
 class Property(TypedDict):

{rushdb-2.3.0 → rushdb-2.9.0}/src/rushdb/models/result.py

@@ -246,5 +246,10 @@ class SearchResult(Generic[T]):
         return pd.DataFrame(rows)
 
 
-# Type alias for record search results
-RecordSearchResult = SearchResult[Record]
+class RecordSearchResult(SearchResult[Record]):
+    """Search result specialized for ``Record`` items.
+
+    A real subclass (not a ``SearchResult[Record]`` alias) so that
+    ``isinstance(result, RecordSearchResult)`` works — isinstance checks against
+    subscripted generics raise ``TypeError`` at runtime.
+    """

rushdb-2.9.0/src/rushdb/models/search_query.py

@@ -0,0 +1,93 @@
+from enum import Enum
+from typing import Any, Dict, List, Optional, TypedDict, Union
+
+
+class OrderDirection(str, Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+
+class TraversalHopsRange(TypedDict, total=False):
+    """Hop range for variable-length traversal.
+
+    ``min`` defaults to 1 (2 inside a ``$cycle`` block). Omitting ``max``
+    requests unbounded traversal, which is only allowed on self-hosted
+    deployments and projects with a custom Neo4j instance; the shared cloud
+    connection caps ``max`` per deployment (default 25).
+    """
+
+    min: int
+    max: int
+
+
+TraversalHops = Union[int, TraversalHopsRange]
+"""Depth of a variable-length traversal: an exact hop count or a range."""
+
+
+class TraversalRelationOptions(TypedDict, total=False):
+    """Value for the ``$relation`` key of a traversal block in ``where``.
+
+    ``type`` and ``direction`` constrain every hop; ``hops`` makes the
+    traversal variable-length. The nested label constrains only the final
+    record — intermediate records are anonymous.
+
+    Example::
+
+        {
+            "labels": ["EMPLOYEE"],
+            "where": {
+                "EMPLOYEE": {
+                    "$alias": "$manager",
+                    "$relation": {
+                        "type": "REPORTS_TO",
+                        "direction": "out",
+                        "hops": {"min": 1, "max": 4},
+                    },
+                    "name": {"$contains": "Alice"},
+                }
+            },
+        }
+    """
+
+    type: str
+    direction: str  # 'in' | 'out'
+    hops: TraversalHops
+
+
+class SearchQuery(TypedDict, total=False):
+    """TypedDict representing the query structure for finding records.
+
+    Inside ``where``, a nested key that is a label name traverses to related
+    records. Traversal blocks accept ``$alias`` (name the endpoint for
+    ``select``/``groupBy``), ``$relation`` (a type string or
+    :class:`TraversalRelationOptions`, including variable-length ``hops``),
+    and ``$cycle`` (``True`` binds the traversal back to the parent record to
+    detect rings; requires ``$relation`` with ``hops`` where ``min`` >= 2 and
+    accepts no other keys).
+    """
+
+    where: Optional[Dict[str, Any]]
+    labels: Optional[List[str]]
+    skip: Optional[int]
+    limit: Optional[int]
+    orderBy: Optional[Union[Dict[str, OrderDirection], OrderDirection]]
+    select: Optional[Dict[str, Any]]
+    groupBy: Optional[List[str]]
+
+
+class RelationshipEndpointQuery(TypedDict, total=False):
+    """Endpoint record predicates for relationship search."""
+
+    where: Optional[Dict[str, Any]]
+    labels: Optional[List[str]]
+
+
+class RelationshipSearchQuery(TypedDict, total=False):
+    """TypedDict representing the query structure for finding relationship edges."""
+
+    where: Optional[Dict[str, Any]]
+    source: Optional[RelationshipEndpointQuery]
+    target: Optional[RelationshipEndpointQuery]
+    skip: Optional[int]
+    limit: Optional[int]
+    orderBy: Optional[Union[Dict[str, OrderDirection], OrderDirection]]

{rushdb-2.3.0 → rushdb-2.9.0}/tests/test_create_import.py

@@ -40,7 +40,7 @@ class TestCreateImport(TestBase):
         # Test new functionality
         self.assertEqual(record.get("name"), "Google LLC")
         self.assertEqual(record.get("nonexistent", "default"), "default")
-        self.assertTrue(record.exists())
+        self.assertTrue(record.exists)
 
     def test_record_methods(self):
         """Test Record class methods"""
@@ -201,7 +201,11 @@ class TestCreateImport(TestBase):
         )
 
     def test_create_with_nested_data(self):
-        """Test creating records with nested data structure"""
+        """Test importing records with nested data structure.
+
+        ``create_many`` accepts flat rows only (it raises ``ValueError`` for
+        nested payloads); nested JSON goes through ``import_json``.
+        """
         data = {
             "name": "Meta Platforms Inc",
             "rating": 4.6,
@@ -220,7 +224,9 @@ class TestCreateImport(TestBase):
                 }
             ],
         }
-        self.client.records.create_many("COMPANY", data)
+        with self.assertRaises(ValueError):
+            self.client.records.create_many("COMPANY", data)
+        self.client.records.import_json(data=data, label="COMPANY")
 
     def test_transaction_rollback(self):
         """Test transaction rollback"""

{rushdb-2.3.0 → rushdb-2.9.0}/tests/test_search_query.py

@@ -1,6 +1,10 @@
 """Test cases for RushDB search query functionality."""
 
+import time
 import unittest
+import uuid
+
+from src.rushdb import RushDB, RushDBError
 
 from .test_base_setup import TestBase
 
@@ -389,5 +393,225 @@ class TestSearchQuery(TestBase):
         self.client.records.find(query)
 
 
+class TestMultihopAndCycles(TestBase):
+    """Variable-length traversal ($relation.hops) and cycle detection ($cycle).
+
+    Seeds its own graph, isolated by a unique tenantId:
+
+        Reporting chain (MHEmployee, REPORTS_TO, directed "up"):
+            E1 -> E2 -> E3 -> E4
+
+        Transfer ring + linear chain (MHAccount, TRANSFERRED_TO):
+            A -> B -> C -> A        (3-hop directed ring)
+            X -> Y -> Z             (no cycle)
+    """
+
+    tenant: str
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls.tenant = f"multihop-{uuid.uuid4().hex[:8]}"
+        # TestBase only creates a client per-test (setUp); seeding needs one here.
+        cls.client = RushDB(cls.token, base_url=cls.base_url)
+
+        # TestBase skips per-test in setUp when the server is unreachable; this
+        # class seeds data in setUpClass, so it must skip here for the same
+        # reason (e.g. CI without a running RushDB) instead of erroring.
+        try:
+            if not cls.client.ping():
+                raise unittest.SkipTest(
+                    f"Could not connect to RushDB at {cls.base_url}"
+                )
+        except RushDBError as e:
+            raise unittest.SkipTest(f"RushDB connection error: {str(e)}")
+
+        cls.client.records.create_many(
+            "MHEmployee",
+            [
+                {"name": "E1", "managerName": "E2", "tenantId": cls.tenant},
+                {"name": "E2", "managerName": "E3", "tenantId": cls.tenant},
+                {"name": "E3", "managerName": "E4", "tenantId": cls.tenant},
+                {"name": "E4", "tenantId": cls.tenant},
+            ],
+        )
+        cls.client.relationships.create_many(
+            source={
+                "label": "MHEmployee",
+                "key": "managerName",
+                "where": {"tenantId": cls.tenant},
+            },
+            target={
+                "label": "MHEmployee",
+                "key": "name",
+                "where": {"tenantId": cls.tenant},
+            },
+            type="REPORTS_TO",
+            direction="out",
+        )
+
+        cls.client.records.create_many(
+            "MHAccount",
+            [
+                {"name": "A", "sendsTo": "B", "tenantId": cls.tenant},
+                {"name": "B", "sendsTo": "C", "tenantId": cls.tenant},
+                {"name": "C", "sendsTo": "A", "tenantId": cls.tenant},
+                {"name": "X", "sendsTo": "Y", "tenantId": cls.tenant},
+                {"name": "Y", "sendsTo": "Z", "tenantId": cls.tenant},
+                {"name": "Z", "tenantId": cls.tenant},
+            ],
+        )
+        cls.client.relationships.create_many(
+            source={
+                "label": "MHAccount",
+                "key": "sendsTo",
+                "where": {"tenantId": cls.tenant},
+            },
+            target={
+                "label": "MHAccount",
+                "key": "name",
+                "where": {"tenantId": cls.tenant},
+            },
+            type="TRANSFERRED_TO",
+            direction="out",  # sender -> receiver
+        )
+
+        # relationships.create_many is applied via apoc.periodic.iterate — poll
+        # until both relationship sets are visible.
+        for _ in range(10):
+            employee_rels = cls.client.relationships.find(
+                {
+                    "source": {
+                        "labels": ["MHEmployee"],
+                        "where": {"tenantId": cls.tenant},
+                    },
+                    "limit": 100,
+                }
+            )
+            account_rels = cls.client.relationships.find(
+                {
+                    "source": {
+                        "labels": ["MHAccount"],
+                        "where": {"tenantId": cls.tenant},
+                    },
+                    "limit": 100,
+                }
+            )
+            if len(employee_rels.data) >= 3 and len(account_rels.data) >= 5:
+                break
+            time.sleep(1)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.client.records.delete({"where": {"tenantId": cls.tenant}})
+        super().tearDownClass()
+
+    def _names(self, result):
+        return sorted(record.get("name") for record in result)
+
+    def test_hops_range_reaches_chain_top(self):
+        """hops {max: 3} reaches E4 from every subordinate"""
+        result = self.client.records.find(
+            {
+                "labels": ["MHEmployee"],
+                "where": {
+                    "tenantId": self.tenant,
+                    "MHEmployee": {
+                        "$relation": {
+                            "type": "REPORTS_TO",
+                            "direction": "out",
+                            "hops": {"max": 3},
+                        },
+                        "name": "E4",
+                    },
+                },
+            }
+        )
+        self.assertEqual(self._names(result), ["E1", "E2", "E3"])
+
+    def test_hops_range_is_bounded(self):
+        """hops {max: 2} does not reach 3 hops away"""
+        result = self.client.records.find(
+            {
+                "labels": ["MHEmployee"],
+                "where": {
+                    "tenantId": self.tenant,
+                    "MHEmployee": {
+                        "$relation": {
+                            "type": "REPORTS_TO",
+                            "direction": "out",
+                            "hops": {"max": 2},
+                        },
+                        "name": "E4",
+                    },
+                },
+            }
+        )
+        self.assertEqual(self._names(result), ["E2", "E3"])
+
+    def test_hops_exact_count(self):
+        """hops: 3 matches exactly 3 hops"""
+        result = self.client.records.find(
+            {
+                "labels": ["MHEmployee"],
+                "where": {
+                    "tenantId": self.tenant,
+                    "MHEmployee": {
+                        "$relation": {
+                            "type": "REPORTS_TO",
+                            "direction": "out",
+                            "hops": 3,
+                        },
+                        "name": "E4",
+                    },
+                },
+            }
+        )
+        self.assertEqual(self._names(result), ["E1"])
+
+    def test_cycle_flags_ring_members(self):
+        """$cycle returns exactly the ring participants with a deduplicated total"""
+        result = self.client.records.find(
+            {
+                "labels": ["MHAccount"],
+                "where": {
+                    "tenantId": self.tenant,
+                    "RING": {
+                        "$cycle": True,
+                        "$relation": {
+                            "type": "TRANSFERRED_TO",
+                            "direction": "out",
+                            "hops": {"min": 2, "max": 6},
+                        },
+                    },
+                },
+            }
+        )
+        self.assertEqual(self._names(result), ["A", "B", "C"])
+        self.assertEqual(result.total, 3)
+
+    def test_not_cycle_excludes_ring_members(self):
+        """$not around a $cycle block finds acyclic accounts"""
+        result = self.client.records.find(
+            {
+                "labels": ["MHAccount"],
+                "where": {
+                    "tenantId": self.tenant,
+                    "$not": {
+                        "RING": {
+                            "$cycle": True,
+                            "$relation": {
+                                "type": "TRANSFERRED_TO",
+                                "direction": "out",
+                                "hops": {"min": 2, "max": 6},
+                            },
+                        }
+                    },
+                },
+            }
+        )
+        self.assertEqual(self._names(result), ["X", "Y", "Z"])
+
+
 if __name__ == "__main__":
     unittest.main()

{rushdb-2.3.0 → rushdb-2.9.0}/uv.lock

@@ -785,7 +785,7 @@ wheels = [
 
 [[package]]
 name = "rushdb"
-version = "2.3.0"
+version = "2.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "python-dotenv", version = "1.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },

rushdb-2.3.0/src/rushdb/common.py

@@ -1,20 +0,0 @@
-from typing import Dict, Optional
-
-
-class RushDBError(Exception):
-    """Custom exception for RushDB client errors."""
-
-    def __init__(self, message: str, details: Optional[Dict] = None):
-        super().__init__(message)
-        self.details = details or {}
-
-
-class NonUniqueResultError(Exception):
-    """Raised by ``records.find_uniq()`` when more than one record matches the query."""
-
-    def __init__(self, count: int):
-        super().__init__(
-            f"Expected at most one record but found {count}. "
-            "Refine your search query or use records.find() instead."
-        )
-        self.count = count

rushdb-2.3.0/src/rushdb/models/search_query.py

@@ -1,37 +0,0 @@
-from enum import Enum
-from typing import Any, Dict, List, Optional, TypedDict, Union
-
-
-class OrderDirection(str, Enum):
-    ASC = "asc"
-    DESC = "desc"
-
-
-class SearchQuery(TypedDict, total=False):
-    """TypedDict representing the query structure for finding records."""
-
-    where: Optional[Dict[str, Any]]
-    labels: Optional[List[str]]
-    skip: Optional[int]
-    limit: Optional[int]
-    orderBy: Optional[Union[Dict[str, OrderDirection], OrderDirection]]
-    select: Optional[Dict[str, Any]]
-    groupBy: Optional[List[str]]
-
-
-class RelationshipEndpointQuery(TypedDict, total=False):
-    """Endpoint record predicates for relationship search."""
-
-    where: Optional[Dict[str, Any]]
-    labels: Optional[List[str]]
-
-
-class RelationshipSearchQuery(TypedDict, total=False):
-    """TypedDict representing the query structure for finding relationship edges."""
-
-    where: Optional[Dict[str, Any]]
-    source: Optional[RelationshipEndpointQuery]
-    target: Optional[RelationshipEndpointQuery]
-    skip: Optional[int]
-    limit: Optional[int]
-    orderBy: Optional[Union[Dict[str, OrderDirection], OrderDirection]]