rushdb 2.6.0__tar.gz → 2.10.0__tar.gz

{rushdb-2.6.0 → rushdb-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rushdb
-Version: 2.6.0
+Version: 2.10.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'}})
@@ -205,6 +227,37 @@ if result:
 
 ---
 
+## Vector Search And Smart Search
+
+Use `db.records.vector_search()` for direct semantic/vector retrieval over an
+embedding index:
+
+```python
+results = db.records.vector_search({
+    'labels': ['MEMORY'],
+    'propertyName': 'content',
+    'query': 'how agents remember things',
+    'where': {'agent_id': 'agent-42'},
+    'limit': 5,
+})
+
+for record in results:
+    print(record.score, record.get('content'))
+```
+
+Use `db.ai.search()` when you want RushDB to turn a natural-language request
+into a SearchQuery and execute it:
+
+```python
+results = db.ai.search('Find active memories about Q4 results for agent-42')
+print(results.search_query)
+```
+
+`db.ai.search({...})` still works as a deprecated vector-search alias, but new
+code should use `db.records.vector_search({...})`.
+
+---
+
 ## Record API
 
 ```python

{rushdb-2.6.0 → rushdb-2.10.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'}})
@@ -180,6 +202,37 @@ if result:
 
 ---
 
+## Vector Search And Smart Search
+
+Use `db.records.vector_search()` for direct semantic/vector retrieval over an
+embedding index:
+
+```python
+results = db.records.vector_search({
+    'labels': ['MEMORY'],
+    'propertyName': 'content',
+    'query': 'how agents remember things',
+    'where': {'agent_id': 'agent-42'},
+    'limit': 5,
+})
+
+for record in results:
+    print(record.score, record.get('content'))
+```
+
+Use `db.ai.search()` when you want RushDB to turn a natural-language request
+into a SearchQuery and execute it:
+
+```python
+results = db.ai.search('Find active memories about Q4 results for agent-42')
+print(results.search_query)
+```
+
+`db.ai.search({...})` still works as a deprecated vector-search alias, but new
+code should use `db.records.vector_search({...})`.
+
+---
+
 ## Record API
 
 ```python

{rushdb-2.6.0 → rushdb-2.10.0}/pyproject.toml

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

{rushdb-2.6.0 → rushdb-2.10.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.6.0 → rushdb-2.10.0}/src/rushdb/api/ai.py

@@ -1,13 +1,16 @@
 """AI API for RushDB Python SDK.
 
-Provides methods for graph schema exploration, semantic vector search,
+Provides methods for AI-assisted graph exploration, smart search,
 and embedding index management.
 """
 
-from typing import TYPE_CHECKING, Any, Dict, Optional, Union
+import warnings
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union, cast
 
 from ..models.api_response import ApiResponse
 from ..models.record import Record
+from ..models.result import RecordSearchResult
+from ..models.search_query import SearchQuery
 from ..models.transaction import Transaction
 from .base import BaseAPI
 
@@ -124,7 +127,12 @@ class AIAPI(BaseAPI):
 
         >>> db = RushDB(api_key="...")
         >>> schema = db.ai.get_schema()
-        >>> results = db.ai.search({"query": "fast cars", "propertyName": "description"})
+        >>> results = db.ai.search("books about fast cars")
+        >>> vectors = db.records.vector_search({
+        ...     "query": "fast cars",
+        ...     "propertyName": "description",
+        ...     "labels": ["Book"],
+        ... })
         >>> db.ai.indexes.create({"propertyName": "description", "label": "Book"})
     """
 
@@ -145,7 +153,7 @@ class AIAPI(BaseAPI):
         indexes exist for that property — each entry exposes ``id``,
         ``sourceType``, ``similarityFunction``, ``dimensions``, ``status``, and
         ``modelKey``.  A non-empty ``vectorIndexes`` list means the property is
-        queryable with ``db.ai.search()``.
+        queryable with ``db.records.vector_search()``.
 
         Args:
             params: Optional filter. Pass ``{"labels": ["Label1"]}`` to scope
@@ -214,35 +222,60 @@ class AIAPI(BaseAPI):
             total=response.get("total"),
         )
 
-    def search(self, params: Dict[str, Any]) -> ApiResponse:
-        """Perform semantic (vector) search over indexed record properties.
+    def search(
+        self,
+        prompt: Union[str, Dict[str, Any]],
+        current_query: Optional[SearchQuery] = None,
+        transaction: Optional[Union[Transaction, str]] = None,
+    ) -> RecordSearchResult:
+        """Perform AI-assisted smart search from natural language.
 
-        **Direct vector-index mode** (default, fast): used when no ``where``
-        filter and at most one ``labels`` entry. Queries the shared global
-        vector index directly.
+        RushDB converts ``prompt`` into a SearchQuery using the project schema,
+        executes it, and returns matching records with the generated query
+        attached to ``result.search_query``.
 
-        **Prefilter mode** (exact, slower): activated when a ``where``
-        filter is supplied or ``labels`` contains more than one value.
-        Candidates are first narrowed by MATCH/WHERE, then ranked by exact
-        cosine similarity.
+        Use ``db.records.vector_search({...})`` for direct vector similarity
+        over embedding indexes.
 
         Args:
-            params: Search parameters. Expected keys:
-
-                - ``query`` (str): The natural-language query text.
-                - ``propertyName`` (str): Property that has been embedded.
-                - ``labels`` (list[str], optional): Scope to specific labels.
-                - ``where`` (dict, optional): Additional property filters.
-                - ``limit`` (int, optional): Maximum number of results.
+            prompt: Natural-language search request. Passing a dict is
+                deprecated and delegates to ``db.records.vector_search``.
+            current_query: Optional current SearchQuery context from a
+                dashboard/query-builder session.
+            transaction: Optional transaction context.
 
         Returns:
-            ApiResponse: Response whose ``data`` is a list of semantic search
-            result objects (each includes the matched record and a score).
+            RecordSearchResult: Matching records. The generated SearchQuery is
+            available as ``result.search_query`` and server warnings as
+            ``result.warnings``.
         """
-        response = self.client._make_request("POST", "/ai/search", params)
+        if isinstance(prompt, dict):
+            warnings.warn(
+                "db.ai.search({...}) is deprecated for vector search; "
+                "use db.records.vector_search({...}) instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return self.client.records.vector_search(prompt, transaction=transaction)
+
+        headers = Transaction._build_transaction_header(transaction)
+        generated = self.client._make_request(
+            "POST",
+            "/ai/search-query",
+            {"prompt": prompt, "currentQuery": current_query},
+            headers,
+        )
+        generated_data = generated.get("data") or {}
+        search_query = generated_data.get("searchQuery") or {}
+
+        response = self.client._make_request(
+            "POST", "/records/search", search_query, headers
+        )
         records = [Record(self.client, item) for item in response.get("data", [])]
-        return ApiResponse(
+        return RecordSearchResult(
             data=records,
-            success=response.get("success", True),
-            total=response.get("total"),
+            total=response.get("total", len(records)),
+            search_query=cast(SearchQuery, search_query),
+            client=self.client,
+            warnings=generated_data.get("warnings") or [],
         )

{rushdb-2.6.0 → rushdb-2.10.0}/src/rushdb/api/records.py

@@ -688,6 +688,46 @@ class RecordsAPI(BaseAPI):
         except Exception:
             return RecordSearchResult(data=[], total=0, client=self.client)
 
+    def vector_search(
+        self,
+        params: Dict[str, Any],
+        transaction: Optional[Union[Transaction, str]] = None,
+    ) -> RecordSearchResult:
+        """Perform vector similarity search over indexed record properties.
+
+        This is the Python SDK counterpart to the TypeScript
+        ``db.records.vectorSearch({...})`` method. RushDB narrows candidates by
+        ``labels`` and optional ``where`` filters first, then ranks them by
+        vector similarity. Pass ``query`` for managed indexes or ``queryVector``
+        for external/custom vectors.
+
+        Args:
+            params: Vector search parameters. Expected keys:
+
+                - ``propertyName`` (str): Property that has an embedding index.
+                - ``labels`` (list[str]): Labels to scope the search.
+                - ``query`` (str, optional): Text query for managed indexes.
+                - ``queryVector`` (list[float], optional): Pre-computed vector.
+                - ``where`` (dict, optional): Additional property filters.
+                - ``limit`` (int, optional): Maximum number of results.
+                - ``skip`` (int, optional): Number of results to skip.
+                - ``topK`` (int, optional): Candidate count in direct vector mode.
+            transaction: Optional transaction context.
+
+        Returns:
+            RecordSearchResult: Matching records ranked by similarity. Each
+            record may include ``__score``.
+        """
+        headers = Transaction._build_transaction_header(transaction)
+        response = self.client._make_request("POST", "/ai/search", params, headers)
+        records = [Record(self.client, item) for item in response.get("data", [])]
+        return RecordSearchResult(
+            data=records,
+            total=response.get("total", len(records)),
+            search_query=typing.cast(SearchQuery, params),
+            client=self.client,
+        )
+
     def find_one(
         self,
         search_query: Optional[SearchQuery] = None,

{rushdb-2.6.0 → rushdb-2.10.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.6.0 → rushdb-2.10.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.10.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.6.0 → rushdb-2.10.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.6.0 → rushdb-2.10.0}/src/rushdb/models/result.py

@@ -30,6 +30,7 @@ class SearchResult(Generic[T]):
         total: Optional[int] = None,
         search_query: Optional[SearchQuery] = None,
         client: Optional["RushDB"] = None,
+        warnings: Optional[List[str]] = None,
     ):
         """
         Initialize search result.
@@ -39,11 +40,13 @@ class SearchResult(Generic[T]):
             total: Total number of matching records (may be larger than len(data))
             search_query: The search query used to generate this result
             client: Optional RushDB client instance (required for delete_all, next, set_properties)
+            warnings: Optional warnings returned by AI-assisted query generation
         """
         self._data = data
         self._total = total or len(data)
         self._search_query = search_query or {}
         self._client = client
+        self._warnings = warnings or []
 
     @property
     def data(self) -> List[T]:
@@ -60,6 +63,11 @@ class SearchResult(Generic[T]):
         """Get the search query used to generate this result."""
         return self._search_query
 
+    @property
+    def warnings(self) -> List[str]:
+        """Get warnings returned by AI-assisted query generation."""
+        return self._warnings
+
     @property
     def has_more(self) -> bool:
         """Check if there are more records available beyond this result set."""
@@ -106,6 +114,7 @@ class SearchResult(Generic[T]):
             "total": self.total,
             "data": self.data,
             "search_query": self.search_query,
+            "warnings": self.warnings,
         }
 
     def get_page_info(self) -> dict:
@@ -246,5 +255,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.10.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]]