rushdb 2.0.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rushdb
-Version: 2.0.0
+Version: 2.3.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
@@ -138,7 +138,17 @@ authored_posts = db.records.find({
 # Manage relationships explicitly
 user = db.records.find_uniq({'labels': ['USER'], 'where': {'name': 'Alice'}})
 company = db.records.find_uniq({'labels': ['COMPANY'], 'where': {'name': 'Acme Corp'}})
-user.attach(target=company, options={'type': 'WORKS_AT', 'direction': 'out'})
+user.attach(
+    target=company,
+    options={'type': 'WORKS_AT', 'direction': 'out', 'properties': {'source': 'profile'}},
+)
+
+# Relationship search: where filters edge type/properties, source/target filter endpoint records
+relationships = db.relationships.find({
+    'source': {'labels': ['USER'], 'where': {'name': 'Alice'}},
+    'target': {'labels': ['COMPANY']},
+    'where': {'type': 'WORKS_AT', 'source': 'profile'},
+})
 ```
 
 ---

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

@@ -113,7 +113,17 @@ authored_posts = db.records.find({
 # Manage relationships explicitly
 user = db.records.find_uniq({'labels': ['USER'], 'where': {'name': 'Alice'}})
 company = db.records.find_uniq({'labels': ['COMPANY'], 'where': {'name': 'Acme Corp'}})
-user.attach(target=company, options={'type': 'WORKS_AT', 'direction': 'out'})
+user.attach(
+    target=company,
+    options={'type': 'WORKS_AT', 'direction': 'out', 'properties': {'source': 'profile'}},
+)
+
+# Relationship search: where filters edge type/properties, source/target filter endpoint records
+relationships = db.relationships.find({
+    'source': {'labels': ['USER'], 'where': {'name': 'Alice'}},
+    'target': {'labels': ['COMPANY']},
+    'where': {'type': 'WORKS_AT', 'source': 'profile'},
+})
 ```
 
 ---

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

@@ -1,6 +1,6 @@
 [project]
 name = "rushdb"
-version = "2.0.0"
+version = "2.3.0"
 description = "RushDB Python SDK — memory layer for AI agents and modern apps"
 authors = [
     {name = "RushDB Team", email = "hi@rushdb.com"}
@@ -81,8 +81,6 @@ line-length = 120
 
 [tool.isort]
 profile = "black"
-multi_line_output = 3
-line_length = 120
 
 [dependency-groups]
 dev = [

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

@@ -5,14 +5,26 @@ Exposes the RushDB class.
 
 from .api.ai import AIAPI
 from .api.query import QueryAPI
+from .api.records import pick_record_id
+from .api.relationship_patterns import RelationshipPatternsAPI
 from .api.relationships import RelationsAPI
 from .client import RushDB
 from .common import NonUniqueResultError, RushDBError
 from .models.api_response import ApiResponse
 from .models.property import Property
-from .models.record import Record
-from .models.relationship import RelationshipDetachOptions, RelationshipOptions
+from .models.record import Record, RecordTarget, RelationTarget
+from .models.relationship import (
+    Relationship,
+    RelationshipDetachOptions,
+    RelationshipDirection,
+    RelationshipOptions,
+)
 from .models.result import RecordSearchResult, SearchResult
+from .models.search_query import (
+    RelationshipEndpointQuery,
+    RelationshipSearchQuery,
+    SearchQuery,
+)
 from .models.transaction import Transaction
 
 __all__ = [
@@ -20,14 +32,23 @@ __all__ = [
     "RushDBError",
     "NonUniqueResultError",
     "Record",
+    "RecordTarget",
+    "RelationTarget",
+    "pick_record_id",
     "RecordSearchResult",
     "SearchResult",
     "Transaction",
     "Property",
+    "Relationship",
+    "RelationshipDirection",
     "RelationshipOptions",
     "RelationshipDetachOptions",
+    "SearchQuery",
+    "RelationshipEndpointQuery",
+    "RelationshipSearchQuery",
     "QueryAPI",
     "RelationsAPI",
+    "RelationshipPatternsAPI",
     "ApiResponse",
     "AIAPI",
 ]

{rushdb-2.0.0 → rushdb-2.3.0}/src/rushdb/api/__init__.py

@@ -2,6 +2,7 @@ from .labels import LabelsAPI
 from .properties import PropertiesAPI
 from .query import QueryAPI
 from .records import RecordsAPI
+from .relationship_patterns import RelationshipPatternsAPI
 from .relationships import RelationsAPI
 from .transactions import TransactionsAPI
 
@@ -12,4 +13,5 @@ __all__ = [
     "TransactionsAPI",
     "QueryAPI",
     "RelationsAPI",
+    "RelationshipPatternsAPI",
 ]

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

@@ -1,7 +1,7 @@
 import typing
 from typing import Any, Dict, List, Optional, Union
 
-from ..models.record import Record
+from ..models.record import Record, RecordTarget, RelationTarget
 from ..models.relationship import RelationshipDetachOptions, RelationshipOptions
 from ..models.result import RecordSearchResult
 from ..models.search_query import SearchQuery
@@ -9,6 +9,29 @@ from ..models.transaction import Transaction
 from .base import BaseAPI
 
 
+def pick_record_id(target: RecordTarget) -> Optional[str]:
+    """Extract a record ID string from any RecordTarget representation.
+
+    Mirrors the JavaScript SDK's ``pickRecordId`` utility in ``src/api/utils.ts``.
+    Accepts a UUID string, a ``Record`` instance, or a plain dict containing
+    an ``__id`` field — in all cases the resolved UUID string is returned.
+
+    Args:
+        target: A record reference as a string ID, ``Record`` object, or dict
+            with an ``"__id"`` key.
+
+    Returns:
+        The UUID string, or ``None`` if it cannot be resolved.
+    """
+    if isinstance(target, str):
+        return target
+    elif isinstance(target, Record):
+        return target.data.get("__id")
+    elif isinstance(target, dict):
+        return target.get("__id")
+    return None
+
+
 def _is_flat(obj: Any) -> bool:
     """Return True if obj is a dict with no nested dict/list values."""
     return isinstance(obj, dict) and not any(
@@ -55,7 +78,7 @@ class RecordsAPI(BaseAPI):
 
     def set(
         self,
-        record_id: str,
+        target: RecordTarget,
         data: Dict[str, Any],
         label: Optional[str] = None,
         vectors: Optional[List[Dict[str, Any]]] = None,
@@ -67,7 +90,8 @@ class RecordsAPI(BaseAPI):
         removing any existing fields that are not present in the new data.
 
         Args:
-            record_id (str): The unique identifier of the record to update.
+            target (RecordTarget): The record to update. Accepts a UUID string,
+                a ``Record`` instance, or a dict containing an ``"__id"`` field.
             data (Dict[str, Any]): The new data to replace the existing record data.
             label (Optional[str]): Optional label to re-assign to the record.
             vectors (Optional[List[Dict[str, Any]]]): Optional pre-computed embedding vectors
@@ -81,9 +105,10 @@ class RecordsAPI(BaseAPI):
             Dict[str, str]: Response from the server containing operation status.
 
         Raises:
-            ValueError: If the record_id is invalid or empty.
+            ValueError: If the target cannot be resolved to a valid record ID.
             RequestError: If the server request fails.
         """
+        record_id = pick_record_id(target)
         headers = Transaction._build_transaction_header(transaction)
         payload: Dict[str, Any] = {"data": data}
         if label is not None:
@@ -96,7 +121,7 @@ class RecordsAPI(BaseAPI):
 
     def update(
         self,
-        record_id: str,
+        target: RecordTarget,
         data: Dict[str, Any],
         transaction: Optional[Transaction] = None,
     ) -> Dict[str, str]:
@@ -106,7 +131,8 @@ class RecordsAPI(BaseAPI):
         with existing record data without removing existing fields.
 
         Args:
-            record_id (str): The unique identifier of the record to update.
+            target (RecordTarget): The record to update. Accepts a UUID string,
+                a ``Record`` instance, or a dict containing an ``"__id"`` field.
             data (Dict[str, Any]): The data to merge with the existing record data.
             transaction (Optional[Transaction], optional): Transaction context for the operation.
                 If provided, the operation will be part of the transaction. Defaults to None.
@@ -115,9 +141,10 @@ class RecordsAPI(BaseAPI):
             Dict[str, str]: Response from the server containing operation status.
 
         Raises:
-            ValueError: If the record_id is invalid or empty.
+            ValueError: If the target cannot be resolved to a valid record ID.
             RequestError: If the server request fails.
         """
+        record_id = pick_record_id(target)
         headers = Transaction._build_transaction_header(transaction)
 
         return self.client._make_request(
@@ -383,15 +410,8 @@ class RecordsAPI(BaseAPI):
 
     def attach(
         self,
-        source: Union[str, Dict[str, Any]],
-        target: Union[
-            str,
-            List[str],
-            Dict[str, Any],
-            List[Dict[str, Any]],
-            "Record",
-            List["Record"],
-        ],
+        source: RecordTarget,
+        target: RelationTarget,
         options: Optional[RelationshipOptions] = None,
         transaction: Optional[Transaction] = None,
     ) -> Dict[str, str]:
@@ -402,16 +422,11 @@ class RecordsAPI(BaseAPI):
         record dictionaries, or Record objects.
 
         Args:
-            source (Union[str, Dict[str, Any]]): The source record to attach targets to.
-                Can be a record ID string or a record dictionary containing '__id'.
-            target (Union[str, List[str], Dict[str, Any], List[Dict[str, Any]], Record, List[Record]]):
-                The target record(s) to attach to the source. Accepts multiple formats:
-                - Single record ID (str)
-                - List of record IDs (List[str])
-                - Record dictionary with '__id' field
-                - List of record dictionaries
-                - Record object
-                - List of Record objects
+            source (RecordTarget): The source record to attach targets to.
+                Accepts a UUID string, a ``Record`` instance, or a dict with ``"__id"``.
+            target (RelationTarget): The target record(s) to attach to the source.
+                Accepts a single or list of: UUID string, ``Record`` instance, or
+                dict with ``"__id"``.
             options (Optional[RelationshipOptions], optional): Additional options for the relationship.
                 Defaults to None.
             transaction (Optional[Transaction], optional): Transaction context for the operation.
@@ -431,6 +446,17 @@ class RecordsAPI(BaseAPI):
             >>>
             >>> # Attach using Record objects
             >>> response = records_api.attach(source_record, target_records)
+            >>>
+            >>> # Attach with a typed relationship carrying edge properties
+            >>> response = records_api.attach(
+            ...     movie,
+            ...     actor,
+            ...     options={
+            ...         "type": "STARS_IN",
+            ...         "direction": "out",
+            ...         "properties": {"role": "lead", "billing": 1},
+            ...     },
+            ... )
         """
         headers = Transaction._build_transaction_header(transaction)
 
@@ -445,15 +471,8 @@ class RecordsAPI(BaseAPI):
 
     def detach(
         self,
-        source: Union[str, Dict[str, Any]],
-        target: Union[
-            str,
-            List[str],
-            Dict[str, Any],
-            List[Dict[str, Any]],
-            "Record",
-            List["Record"],
-        ],
+        source: RecordTarget,
+        target: RelationTarget,
         options: Optional[RelationshipDetachOptions] = None,
         transaction: Optional[Transaction] = None,
     ) -> Dict[str, str]:
@@ -464,16 +483,11 @@ class RecordsAPI(BaseAPI):
         record dictionaries, or Record objects.
 
         Args:
-            source (Union[str, Dict[str, Any]]): The source record to detach targets from.
-                Can be a record ID string or a record dictionary containing '__id'.
-            target (Union[str, List[str], Dict[str, Any], List[Dict[str, Any]], Record, List[Record]]):
-                The target record(s) to detach from the source. Accepts multiple formats:
-                - Single record ID (str)
-                - List of record IDs (List[str])
-                - Record dictionary with '__id' field
-                - List of record dictionaries
-                - Record object
-                - List of Record objects
+            source (RecordTarget): The source record to detach targets from.
+                Accepts a UUID string, a ``Record`` instance, or a dict with ``"__id"``.
+            target (RelationTarget): The target record(s) to detach from the source.
+                Accepts a single or list of: UUID string, ``Record`` instance, or
+                dict with ``"__id"``.
             options (Optional[RelationshipDetachOptions], optional): Additional options for the detach operation.
                 Defaults to None.
             transaction (Optional[Transaction], optional): Transaction context for the operation.
@@ -550,7 +564,7 @@ class RecordsAPI(BaseAPI):
 
     def delete_by_id(
         self,
-        id_or_ids: Union[str, List[str]],
+        target: Union[RecordTarget, List[RecordTarget]],
         transaction: Optional[Transaction] = None,
     ) -> Dict[str, str]:
         """Delete one or more records by their unique identifiers.
@@ -559,8 +573,9 @@ class RecordsAPI(BaseAPI):
         deletion and bulk deletion of multiple records.
 
         Args:
-            id_or_ids (Union[str, List[str]]): The record identifier(s) to delete.
-                Can be a single record ID string or a list of record ID strings.
+            target (Union[RecordTarget, List[RecordTarget]]): The record(s) to delete.
+                Accepts a UUID string, a ``Record`` instance, a dict containing
+                ``"__id"``, or a list of any of those forms.
             transaction (Optional[Transaction], optional): Transaction context for the operation.
                 If provided, the operation will be part of the transaction. Defaults to None.
 
@@ -569,39 +584,42 @@ class RecordsAPI(BaseAPI):
                 information about the deletion operation.
 
         Raises:
-            ValueError: If any of the provided IDs are invalid or empty.
+            ValueError: If any target cannot be resolved to a valid record ID.
             RequestError: If the server request fails.
 
         Note:
-            When deleting multiple records (list of IDs), the operation uses a
+            When deleting multiple records (list), the operation uses a
             batch delete with a limit of 1000 records. For single record deletion,
             it uses a direct DELETE request.
 
         Example:
             >>> records_api = RecordsAPI(client)
-            >>> # Delete a single record
+            >>> # Delete a single record — string, Record object, or dict all work
             >>> response = records_api.delete_by_id("record_123")
+            >>> response = records_api.delete_by_id(my_record)
             >>>
             >>> # Delete multiple records
-            >>> record_ids = ["record_123", "record_456", "record_789"]
-            >>> response = records_api.delete_by_id(record_ids)
+            >>> response = records_api.delete_by_id(["record_123", "record_456"])
+            >>> response = records_api.delete_by_id([record_a, record_b])
         """
         headers = Transaction._build_transaction_header(transaction)
 
-        if isinstance(id_or_ids, list):
+        if isinstance(target, list):
+            ids = self._extract_target_ids(target)
             return self.client._make_request(
                 "POST",
                 "/records/delete",
-                {"limit": 1000, "where": {"$id": {"$in": id_or_ids}}},
+                {"limit": 1000, "where": {"$id": {"$in": ids}}},
                 headers,
             )
+        record_id = pick_record_id(target)
         return self.client._make_request(
-            "DELETE", f"/records/{id_or_ids}", None, headers
+            "DELETE", f"/records/{record_id}", None, headers
         )
 
     def find_by_id(
         self,
-        id_or_ids: Union[str, List[str]],
+        target: Union[RecordTarget, List[RecordTarget]],
         transaction: Optional[Transaction] = None,
     ) -> Union["Record", RecordSearchResult]:
         """Retrieve one or more records by their unique identifiers.
@@ -609,17 +627,19 @@ class RecordsAPI(BaseAPI):
         Mirrors the TypeScript SDK ``records.findById`` method.
 
         Args:
-            id_or_ids: A single record ID string or a list of ID strings.
+            target: A single record reference (UUID string, ``Record`` instance, or
+                dict with ``"__id"``), or a list of any of those forms.
             transaction: Optional transaction context for the operation.
 
         Returns:
-            A single :class:`Record` when ``id_or_ids`` is a string, or a
-            :class:`RecordSearchResult` when ``id_or_ids`` is a list.
+            A single :class:`Record` when ``target`` is a single reference, or a
+            :class:`RecordSearchResult` when ``target`` is a list.
         """
         headers = Transaction._build_transaction_header(transaction)
-        if isinstance(id_or_ids, list):
+        if isinstance(target, list):
+            ids = self._extract_target_ids(target)
             response = self.client._make_request(
-                "POST", "/records", {"ids": id_or_ids}, headers
+                "POST", "/records", {"ids": ids}, headers
             )
             records = [Record(self.client, r) for r in (response.get("data") or [])]
             return RecordSearchResult(
@@ -627,21 +647,25 @@ class RecordsAPI(BaseAPI):
                 total=response.get("total", len(records)),
                 client=self.client,
             )
+        record_id = pick_record_id(target)
         response = self.client._make_request(
-            "GET", f"/records/{id_or_ids}", None, headers
+            "GET", f"/records/{record_id}", None, headers
         )
         return Record(self.client, response.get("data", response))
 
     def find(
         self,
         search_query: Optional[SearchQuery] = None,
-        record_id: Optional[str] = None,
+        record_id: Optional[RecordTarget] = None,
         transaction: Optional[Transaction] = None,
     ) -> RecordSearchResult:
         try:
             headers = Transaction._build_transaction_header(transaction)
 
-            path = f"/records/{record_id}/search" if record_id else "/records/search"
+            resolved_id = pick_record_id(record_id) if record_id is not None else None
+            path = (
+                f"/records/{resolved_id}/search" if resolved_id else "/records/search"
+            )
             response = self.client._make_request(
                 "POST",
                 path,
@@ -825,14 +849,7 @@ class RecordsAPI(BaseAPI):
 
     @staticmethod
     def _extract_target_ids(
-        target: Union[
-            str,
-            List[str],
-            Dict[str, Any],
-            List[Dict[str, Any]],
-            "Record",
-            List["Record"],
-        ],
+        target: Union[RecordTarget, List[RecordTarget]],
     ) -> List[str]:
         """Extract record IDs from various input types and formats.
 
@@ -841,14 +858,9 @@ class RecordsAPI(BaseAPI):
         types commonly used throughout the API for specifying target records.
 
         Args:
-            target (Union[str, List[str], Dict[str, Any], List[Dict[str, Any]], Record, List[Record]]):
-                The target input to extract IDs from. Supported formats:
-                - str: Single record ID
-                - List[str]: List of record IDs
-                - Dict[str, Any]: Record dictionary containing '__id' field
-                - List[Dict[str, Any]]: List of record dictionaries with '__id' fields
-                - Record: Record object with data containing '__id'
-                - List[Record]: List of Record objects
+            target (Union[RecordTarget, List[RecordTarget]]): The target input to
+                extract IDs from. Accepts a UUID string, a ``Record`` instance, a
+                dict with ``"__id"``, or a list of any of those forms.
 
         Returns:
             List[str]: List of extracted record ID strings.

rushdb-2.3.0/src/rushdb/api/relationship_patterns.py

@@ -0,0 +1,61 @@
+"""Relationship pattern suggestions API for the RushDB Python SDK."""
+
+from typing import TYPE_CHECKING, Any, Dict
+
+from ..models.api_response import ApiResponse
+from .base import BaseAPI
+
+if TYPE_CHECKING:
+    from ..client import RushDB
+
+
+class RelationshipPatternsAPI(BaseAPI):
+    """Review and manage relationship patterns inferred from project ontology.
+
+    Accessed via ``db.relationships.patterns``.
+    """
+
+    def __init__(self, client: "RushDB"):
+        super().__init__(client)
+
+    @staticmethod
+    def _wrap(response: Dict[str, Any]) -> ApiResponse:
+        return ApiResponse(
+            data=response.get("data"),
+            success=response.get("success", True),
+            total=response.get("total"),
+        )
+
+    def list(self) -> ApiResponse:
+        """List inferred patterns, ontology 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."""
+        response = self.client._make_request(
+            "POST", "/relationships/patterns/analyze", {}
+        )
+        return self._wrap(response)
+
+    def approve(self, pattern_id: str) -> ApiResponse:
+        """Approve and apply a suggested relationship pattern."""
+        response = self.client._make_request(
+            "POST", f"/relationships/patterns/{pattern_id}/approve", {}
+        )
+        return self._wrap(response)
+
+    def ignore(self, pattern_id: str) -> ApiResponse:
+        """Ignore a suggested relationship pattern without applying it."""
+        response = self.client._make_request(
+            "POST", f"/relationships/patterns/{pattern_id}/ignore", {}
+        )
+        return self._wrap(response)
+
+    def delete(self, pattern_id: str, *, delete_existing: bool = False) -> ApiResponse:
+        """Delete a saved pattern and optionally its materialized relationships."""
+        params = {"deleteExisting": "true"} if delete_existing else None
+        response = self.client._make_request(
+            "DELETE", f"/relationships/patterns/{pattern_id}", params=params
+        )
+        return self._wrap(response)

{rushdb-2.0.0 → rushdb-2.3.0}/src/rushdb/api/relationships.py

@@ -1,11 +1,15 @@
 import typing
-from typing import List, Optional, TypedDict, Union
-from urllib.parse import urlencode
+from typing import TYPE_CHECKING, Optional, TypedDict, Union
 
 from ..models.relationship import Relationship
-from ..models.search_query import SearchQuery
+from ..models.result import SearchResult
+from ..models.search_query import RelationshipSearchQuery
 from ..models.transaction import Transaction
 from .base import BaseAPI
+from .relationship_patterns import RelationshipPatternsAPI
+
+if TYPE_CHECKING:
+    from ..client import RushDB
 
 
 class PaginationParams(TypedDict, total=False):
@@ -43,59 +47,78 @@ class RelationsAPI(BaseAPI):
     Attributes:
         client: The underlying RushDB client instance for making HTTP requests.
 
-    Note:
-        This API currently contains async methods. Ensure you're using it in an
-        async context or consider updating to sync methods if needed.
-
     Example:
         >>> from rushdb import RushDB
         >>> client = RushDB(api_key="your_api_key")
         >>> relations_api = client.relationships
         >>>
         >>> # Find all relationships
-        >>> relationships = await relations_api.find()
+        >>> relationships = relations_api.find()
+        >>>
+        >>> # Filter by edge type and properties
+        >>> leads = relations_api.find({"where": {"type": "STARS_IN", "role": "lead"}})
         >>>
         >>> # Find relationships with pagination
-        >>> pagination = {"limit": 50, "skip": 0}
-        >>> page_1 = await relations_api.find(pagination=pagination)
+        >>> page_1 = relations_api.find(pagination={"limit": 50, "skip": 0})
     """
 
+    def __init__(self, client: "RushDB"):
+        super().__init__(client)
+        self.patterns = RelationshipPatternsAPI(client)
+
     def find(
         self,
-        search_query: Optional[SearchQuery] = None,
+        search_query: Optional[RelationshipSearchQuery] = None,
         pagination: Optional[PaginationParams] = None,
         transaction: Optional[Union[Transaction, str]] = None,
-    ) -> List[Relationship]:
+    ) -> SearchResult[Relationship]:
         """Search for and retrieve relationships matching the specified criteria.
 
         Args:
-            search_query: The search criteria to filter relationships.
+            search_query: Relationship-edge criteria. ``where`` filters the edge —
+                ``type`` maps to the relationship type, ``direction`` constrains
+                direction, and every other key matches a user-defined edge property
+                (full operator set: ``$gte``, ``$contains``, ``$in``, ``$exists``,
+                logical grouping, ...). Use top-level ``source`` and ``target``
+                (``{"labels": [...], "where": {...}}``) to filter endpoint records.
+                ``limit``/``skip`` inside the query control pagination.
                 If None, returns all relationships (subject to pagination limits).
-            pagination: Pagination options (``limit`` and ``skip``).
+            pagination: Pagination options (``limit`` and ``skip``). Merged into the
+                search query body, overriding any ``limit``/``skip`` already inside
+                ``search_query`` — useful for paginating a stored query object
+                without mutating it.
             transaction: Optional transaction context.
 
         Returns:
-            List[Relationship]: Relationships matching the search criteria.
+            SearchResult[Relationship]: Matching relationships with ``total`` count.
+                Iterable and indexable like a list; each item includes ``sourceId``,
+                ``sourceLabel``, ``targetId``, ``targetLabel``, ``type``,
+                ``direction``, and user-defined edge ``properties``.
 
         Raises:
             RushDBError: If the server request fails.
 
         Example:
             >>> relations_api = RelationsAPI(client)
-            >>> all_rels = relations_api.find()
-            >>> page = relations_api.find(pagination={"limit": 50, "skip": 0})
+            >>> result = relations_api.find({
+            ...     "source": {"labels": ["MOVIE"], "where": {"title": "Inception"}},
+            ...     "target": {"labels": ["ACTOR"]},
+            ...     "where": {"type": "STARS_IN", "role": "lead"},
+            ...     "limit": 50,
+            ... })
+            >>> result.total
+            1
+            >>> result[0]["properties"]["role"]
+            'lead'
         """
-        # Build query string for pagination
-        query_params = {}
+        # Pagination lives in the body, same as records search. The `pagination`
+        # argument overrides limit/skip inside `search_query` without mutating it.
+        payload: typing.Dict[str, typing.Any] = dict(search_query or {})
         if pagination:
             if pagination.get("limit") is not None:
-                query_params["limit"] = str(pagination["limit"])
+                payload["limit"] = pagination["limit"]
             if pagination.get("skip") is not None:
-                query_params["skip"] = str(pagination["skip"])
-
-        # Construct path with query string
-        query_string = f"?{urlencode(query_params)}" if query_params else ""
-        path = f"/relationships/search{query_string}"
+                payload["skip"] = pagination["skip"]
 
         # Build headers with transaction if present
         headers = Transaction._build_transaction_header(transaction)
@@ -103,12 +126,17 @@ class RelationsAPI(BaseAPI):
         # Make request
         response = self.client._make_request(
             method="POST",
-            path=path,
-            data=typing.cast(typing.Dict[str, typing.Any], search_query or {}),
+            path="/relationships/search",
+            data=payload,
             headers=headers,
         )
 
-        return response.get("data", [])
+        data = response.get("data", [])
+        return SearchResult(
+            data=data,
+            total=response.get("total"),
+            search_query=typing.cast(typing.Any, payload),
+        )
 
     def create_many(
         self,
@@ -117,6 +145,7 @@ class RelationsAPI(BaseAPI):
         target: dict,
         type: Optional[str] = None,
         direction: Optional[str] = None,
+        properties: Optional[dict] = None,
         many_to_many: Optional[bool] = None,
         transaction: Optional[Union[Transaction, str]] = None,
     ) -> dict:
@@ -131,6 +160,7 @@ class RelationsAPI(BaseAPI):
             target (dict): { label: str, key?: str, where?: dict }
             type (str, optional): Relationship type override.
             direction (str, optional): 'in' | 'out'. Defaults to 'out' server-side when omitted.
+            properties (dict, optional): Shared user-defined properties to store on created edges.
             many_to_many (bool, optional): Enable cartesian mode (requires filters, disallows keys).
             transaction (Transaction|str, optional): Transaction context.
 
@@ -143,6 +173,8 @@ class RelationsAPI(BaseAPI):
             payload["type"] = type
         if direction:
             payload["direction"] = direction
+        if properties is not None:
+            payload["properties"] = properties
         if many_to_many is not None:
             payload["manyToMany"] = many_to_many
         return self.client._make_request(

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

@@ -34,7 +34,7 @@ class _SettingsNamespace:
         Returns:
             Dict[str, Any]: Current project settings object.
         """
-        response = self._client._make_request("GET", "/settings")
+        response = self._client._make_request("GET", "/sdk/settings")
         return response.get("data", response)
 
 
@@ -288,7 +288,7 @@ class RushDB:
             ...     return client
         """
         try:
-            self._make_request("GET", "/settings")
+            self._make_request("GET", "/sdk/settings")
             return True
         except RushDBError:
             return False

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

@@ -0,0 +1,30 @@
+from .property import Property
+from .record import Record
+from .relationship import (
+    Relationship,
+    RelationshipDetachOptions,
+    RelationshipDirection,
+    RelationshipOptions,
+)
+from .result import RecordSearchResult, SearchResult
+from .search_query import (
+    RelationshipEndpointQuery,
+    RelationshipSearchQuery,
+    SearchQuery,
+)
+from .transaction import Transaction
+
+__all__ = [
+    "Property",
+    "Record",
+    "Relationship",
+    "RelationshipDetachOptions",
+    "RelationshipDirection",
+    "RelationshipOptions",
+    "RecordSearchResult",
+    "SearchResult",
+    "SearchQuery",
+    "RelationshipEndpointQuery",
+    "RelationshipSearchQuery",
+    "Transaction",
+]

{rushdb-2.0.0 → rushdb-2.3.0}/src/rushdb/models/record.py

@@ -7,6 +7,17 @@ from .transaction import Transaction
 if TYPE_CHECKING:
     from ..client import RushDB
 
+# RecordTarget mirrors the JS SDK's DBRecordTarget type:
+# a record can be identified by a UUID string, a dict containing "__id", or a Record instance.
+RecordTarget = Union[str, Dict[str, Any], "Record"]
+
+# RelationTarget mirrors the JS SDK's RelationTarget type:
+# one or more records used as the target in attach/detach operations.
+RelationTarget = Union[
+    "RecordTarget",
+    List["RecordTarget"],
+]
+
 
 class Record:
     """Represents a record in RushDB with methods for manipulation."""
@@ -74,14 +85,7 @@ class Record:
 
     def attach(
         self,
-        target: Union[
-            str,
-            List[str],
-            Dict[str, Any],
-            List[Dict[str, Any]],
-            "Record",
-            List["Record"],
-        ],
+        target: "RelationTarget",
         options: Optional[RelationshipOptions] = None,
         transaction: Optional[Transaction] = None,
     ) -> Dict[str, str]:
@@ -90,14 +94,7 @@ class Record:
 
     def detach(
         self,
-        target: Union[
-            str,
-            List[str],
-            Dict[str, Any],
-            List[Dict[str, Any]],
-            "Record",
-            List["Record"],
-        ],
+        target: "RelationTarget",
         options: Optional[RelationshipDetachOptions] = None,
         transaction: Optional[Transaction] = None,
     ) -> Dict[str, str]:

{rushdb-2.0.0 → rushdb-2.3.0}/src/rushdb/models/relationship.py

@@ -1,4 +1,4 @@
-from typing import List, Literal, Optional, TypedDict, Union
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
 
 RelationshipDirection = Literal["in", "out"]
 
@@ -7,8 +7,10 @@ class Relationship(TypedDict, total=False):
     targetLabel: str
     targetId: str
     type: str
+    direction: RelationshipDirection
     sourceId: str
     sourceLabel: str
+    properties: Dict[str, Any]
 
 
 class RelationshipOptions(TypedDict, total=False):
@@ -16,6 +18,7 @@ class RelationshipOptions(TypedDict, total=False):
 
     direction: Optional[RelationshipDirection]
     type: Optional[str]
+    properties: Optional[Dict[str, Any]]
 
 
 class RelationshipDetachOptions(TypedDict, total=False):

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

@@ -0,0 +1,37 @@
+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]]

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

@@ -153,6 +153,53 @@ class TestCreateImport(TestBase):
             source=project, target=employee, options=detach_options
         )
 
+    def test_attach_with_edge_properties_and_find(self):
+        """Test attaching with edge properties and searching edges by them"""
+        movie = self.client.records.create("MOVIE", {"title": "Inception"})
+        actor = self.client.records.create("ACTOR", {"name": "Leonardo DiCaprio"})
+
+        self.client.records.attach(
+            source=movie,
+            target=actor,
+            options=RelationshipOptions(
+                type="STARS_IN",
+                direction="out",
+                properties={"role": "lead", "billing": 1},
+            ),
+        )
+
+        # where filters the edge (type + edge properties);
+        # source/target filter the endpoint records
+        result = self.client.relationships.find(
+            {
+                "source": {"labels": ["MOVIE"], "where": {"title": "Inception"}},
+                "target": {"labels": ["ACTOR"]},
+                "where": {"type": "STARS_IN", "role": "lead", "billing": {"$lte": 3}},
+            }
+        )
+
+        self.assertGreaterEqual(result.total, 1)
+        edge = next(
+            rel
+            for rel in result
+            if rel["sourceId"] == movie.id and rel["targetId"] == actor.id
+        )
+        self.assertEqual(edge["type"], "STARS_IN")
+        self.assertEqual(edge["properties"]["role"], "lead")
+        self.assertEqual(edge["properties"]["billing"], 1)
+
+        # Edge-property mismatch excludes the relationship
+        no_match = self.client.relationships.find(
+            {
+                "source": {"labels": ["MOVIE"], "where": {"title": "Inception"}},
+                "where": {"type": "STARS_IN", "role": "extra"},
+            }
+        )
+        self.assertNotIn(
+            (movie.id, actor.id),
+            [(rel["sourceId"], rel["targetId"]) for rel in no_match],
+        )
+
     def test_create_with_nested_data(self):
         """Test creating records with nested data structure"""
         data = {

rushdb-2.3.0/tests/test_relationship_patterns.py

@@ -0,0 +1,160 @@
+from unittest.mock import Mock
+
+from src.rushdb.api.records import RecordsAPI
+from src.rushdb.api.relationship_patterns import RelationshipPatternsAPI
+from src.rushdb.api.relationships import RelationsAPI
+
+
+def test_relationships_exposes_patterns_namespace():
+    client = Mock()
+
+    relationships = RelationsAPI(client)
+
+    assert isinstance(relationships.patterns, RelationshipPatternsAPI)
+
+
+def test_list_relationship_patterns():
+    client = Mock()
+    client._make_request.return_value = {
+        "data": {"patterns": [], "relationships": [], "analysis": {"status": "idle"}},
+        "success": True,
+    }
+
+    response = RelationsAPI(client).patterns.list()
+
+    client._make_request.assert_called_once_with("GET", "/relationships/patterns")
+    assert response.data["patterns"] == []
+    assert response.data["analysis"]["status"] == "idle"
+
+
+def test_mutate_relationship_patterns():
+    client = Mock()
+    client._make_request.return_value = {"data": {"deleted": True}, "success": True}
+    patterns = RelationsAPI(client).patterns
+
+    patterns.analyze()
+    client._make_request.assert_called_with(
+        "POST", "/relationships/patterns/analyze", {}
+    )
+
+    patterns.approve("pattern-id")
+    client._make_request.assert_called_with(
+        "POST", "/relationships/patterns/pattern-id/approve", {}
+    )
+
+    patterns.ignore("pattern-id")
+    client._make_request.assert_called_with(
+        "POST", "/relationships/patterns/pattern-id/ignore", {}
+    )
+
+    patterns.delete("pattern-id", delete_existing=True)
+    client._make_request.assert_called_with(
+        "DELETE",
+        "/relationships/patterns/pattern-id",
+        params={"deleteExisting": "true"},
+    )
+
+
+def test_relationships_find_uses_edge_where_and_endpoint_filters():
+    client = Mock()
+    edge = {
+        "sourceId": "user-1",
+        "sourceLabel": "USER",
+        "targetId": "order-1",
+        "targetLabel": "ORDER",
+        "type": "ORDERED",
+        "direction": "out",
+        "properties": {"confidence": 0.9},
+    }
+    client._make_request.return_value = {"data": [edge], "total": 1}
+
+    search_query = {
+        "source": {"labels": ["USER"], "where": {"status": "active"}},
+        "target": {"labels": ["ORDER"]},
+        "where": {"type": "ORDERED", "confidence": {"$gte": 0.8}},
+        "limit": 25,
+    }
+
+    response = RelationsAPI(client).find(search_query)
+
+    # Pagination travels in the body, same as records search.
+    client._make_request.assert_called_once_with(
+        method="POST",
+        path="/relationships/search",
+        data=search_query,
+        headers=None,
+    )
+    assert response.total == 1
+    assert list(response) == [edge]
+    assert response[0]["properties"]["confidence"] == 0.9
+
+
+def test_relationships_find_explicit_pagination_wins_over_query_limit():
+    client = Mock()
+    client._make_request.return_value = {"data": [], "total": 0}
+
+    search_query = {"where": {"type": "ORDERED"}, "limit": 25}
+    RelationsAPI(client).find(search_query, pagination={"limit": 10, "skip": 5})
+
+    # The pagination argument overrides limit/skip in the body, leaving the
+    # caller's search_query object untouched.
+    client._make_request.assert_called_once_with(
+        method="POST",
+        path="/relationships/search",
+        data={"where": {"type": "ORDERED"}, "limit": 10, "skip": 5},
+        headers=None,
+    )
+    assert search_query == {"where": {"type": "ORDERED"}, "limit": 25}
+
+
+def test_relationships_create_many_forwards_edge_properties():
+    client = Mock()
+    client._make_request.return_value = {"success": True}
+
+    RelationsAPI(client).create_many(
+        source={"label": "USER", "key": "id"},
+        target={"label": "ORDER", "key": "userId"},
+        type="ORDERED",
+        direction="out",
+        properties={"source": "import", "confidence": 0.9},
+    )
+
+    client._make_request.assert_called_once_with(
+        "POST",
+        "/relationships/create-many",
+        {
+            "source": {"label": "USER", "key": "id"},
+            "target": {"label": "ORDER", "key": "userId"},
+            "type": "ORDERED",
+            "direction": "out",
+            "properties": {"source": "import", "confidence": 0.9},
+        },
+        None,
+    )
+
+
+def test_records_attach_forwards_edge_properties():
+    client = Mock()
+    client._make_request.return_value = {"success": True}
+
+    RecordsAPI(client).attach(
+        source="source-id",
+        target="target-id",
+        options={
+            "type": "RELATED_TO",
+            "direction": "out",
+            "properties": {"source": "test"},
+        },
+    )
+
+    client._make_request.assert_called_once_with(
+        "POST",
+        "/relationships/source-id",
+        {
+            "targetIds": ["target-id"],
+            "type": "RELATED_TO",
+            "direction": "out",
+            "properties": {"source": "test"},
+        },
+        None,
+    )

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

@@ -785,7 +785,7 @@ wheels = [
 
 [[package]]
 name = "rushdb"
-version = "2.0.0"
+version = "2.3.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.0.0/src/rushdb/models/__init__.py

@@ -1,17 +0,0 @@
-from .property import Property
-from .record import Record
-from .relationship import RelationshipDetachOptions, RelationshipOptions
-from .result import RecordSearchResult, SearchResult
-from .search_query import SearchQuery
-from .transaction import Transaction
-
-__all__ = [
-    "Property",
-    "Record",
-    "RelationshipDetachOptions",
-    "RelationshipOptions",
-    "RecordSearchResult",
-    "SearchResult",
-    "SearchQuery",
-    "Transaction",
-]

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

@@ -1,19 +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]]