rushdb 3.0.1__tar.gz → 3.1.0__tar.gz

{rushdb-3.0.1 → rushdb-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rushdb
-Version: 3.0.1
+Version: 3.1.0
 Summary: RushDB SDK for Python: the client for RushDB, the database for AI (RushDB Cloud or self-hosted)
 Project-URL: Homepage, https://github.com/rush-db/rushdb-python
 Project-URL: Repository, https://github.com/rush-db/rushdb-python
@@ -102,7 +102,7 @@ What each offers:
 | Keyword (BM25) search (`records.text_search`), text indexes (`text_indexes.*`), hybrid search | ✓ | ✓ |
 | Transactions | ✓ | record creates, updates, sets, deletes by id, attaches and imports are staged; other writes refuse a transaction |
 | Managed embeddings: managed indexes, `records.vector_search` by text `query` | ✓ | — |
-| Natural-language search (`ai.search`) | ✓ | — |
+| Natural-language search on SQL (`ai.search`, `ai.run_sql`) | ✓ | — |
 | Relationship-pattern suggestions (`relationships.patterns.*`) | ✓ | — |
 | Project settings (`settings.get`), dashboard, team access | ✓ | — |
 
@@ -280,6 +280,7 @@ if result:
 | `total`        | `int`          | Total matching records in the database      |
 | `has_more`     | `bool`         | Whether more records exist beyond this page |
 | `search_query` | `dict`         | The query that produced this result         |
+| `sql`          | `str`          | For Smart search, the SQL statement it ran  |
 
 ---
 
@@ -302,13 +303,21 @@ for record in results:
 ```
 
 Use `db.ai.search()` when you want RushDB to turn a natural-language request
-into a SearchQuery and execute it:
+into one read-only SQL statement over your schema and run it (RushDB Cloud):
 
 ```python
 results = db.ai.search('Find active memories about Q4 results for agent-42')
-print(results.search_query)
+print(results.name)  # a short title, e.g. to save the query under
+print(results.sql)   # the statement it ran
+more = results.next()  # the next page of the statement's rows
+
+# Run a statement directly, e.g. a saved one:
+rows = db.ai.run_sql('SELECT agent_id, count(*) AS memories FROM "MEMORY" GROUP BY agent_id')
 ```
 
+Rows that select a record's `__id` come back as full records; aggregates come
+back as plain rows.
+
 `db.ai.search({...})` still works as a deprecated vector-search alias, but new
 code should use `db.records.vector_search({...})`.
 

{rushdb-3.0.1 → rushdb-3.1.0}/README.md

@@ -88,7 +88,7 @@ What each offers:
 | Keyword (BM25) search (`records.text_search`), text indexes (`text_indexes.*`), hybrid search | ✓ | ✓ |
 | Transactions | ✓ | record creates, updates, sets, deletes by id, attaches and imports are staged; other writes refuse a transaction |
 | Managed embeddings: managed indexes, `records.vector_search` by text `query` | ✓ | — |
-| Natural-language search (`ai.search`) | ✓ | — |
+| Natural-language search on SQL (`ai.search`, `ai.run_sql`) | ✓ | — |
 | Relationship-pattern suggestions (`relationships.patterns.*`) | ✓ | — |
 | Project settings (`settings.get`), dashboard, team access | ✓ | — |
 
@@ -266,6 +266,7 @@ if result:
 | `total`        | `int`          | Total matching records in the database      |
 | `has_more`     | `bool`         | Whether more records exist beyond this page |
 | `search_query` | `dict`         | The query that produced this result         |
+| `sql`          | `str`          | For Smart search, the SQL statement it ran  |
 
 ---
 
@@ -288,13 +289,21 @@ for record in results:
 ```
 
 Use `db.ai.search()` when you want RushDB to turn a natural-language request
-into a SearchQuery and execute it:
+into one read-only SQL statement over your schema and run it (RushDB Cloud):
 
 ```python
 results = db.ai.search('Find active memories about Q4 results for agent-42')
-print(results.search_query)
+print(results.name)  # a short title, e.g. to save the query under
+print(results.sql)   # the statement it ran
+more = results.next()  # the next page of the statement's rows
+
+# Run a statement directly, e.g. a saved one:
+rows = db.ai.run_sql('SELECT agent_id, count(*) AS memories FROM "MEMORY" GROUP BY agent_id')
 ```
 
+Rows that select a record's `__id` come back as full records; aggregates come
+back as plain rows.
+
 `db.ai.search({...})` still works as a deprecated vector-search alias, but new
 code should use `db.records.vector_search({...})`.
 

{rushdb-3.0.1 → rushdb-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rushdb"
-version = "3.0.1"
+version = "3.1.0"
 description = "RushDB SDK for Python: the client for RushDB, the database for AI (RushDB Cloud or self-hosted)"
 authors = [
     {name = "RushDB Team", email = "hi@rushdb.com"}

{rushdb-3.0.1 → rushdb-3.1.0}/src/rushdb/api/ai.py

@@ -5,12 +5,11 @@ and embedding index management.
 """
 
 import warnings
-from typing import TYPE_CHECKING, Any, Dict, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union
 
 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
 
@@ -225,14 +224,18 @@ class AIAPI(BaseAPI):
     def search(
         self,
         prompt: Union[str, Dict[str, Any]],
-        current_query: Optional[SearchQuery] = None,
+        skip: Optional[int] = None,
+        limit: Optional[int] = None,
         transaction: Optional[Union[Transaction, str]] = None,
     ) -> RecordSearchResult:
         """Perform AI-assisted smart search from natural language.
 
-        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``.
+        RushDB turns ``prompt`` into one read-only SQL statement over the
+        project's schema, runs it, and returns the result with the statement
+        as ``result.sql``, a short title as ``result.name`` and any generation
+        warnings as ``result.warnings``. Rows that select a record's ``__id``
+        come back as full records; aggregates come back as plain rows.
+        ``result.next()`` pages through the statement.
 
         Use ``db.records.vector_search({...})`` for direct vector similarity
         over embedding indexes.
@@ -240,14 +243,12 @@ class AIAPI(BaseAPI):
         Args:
             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.
+            skip: Rows to skip (default 0).
+            limit: Rows to return, at most 1000 (default 100).
+            transaction: Only used by the deprecated dict form.
 
         Returns:
-            RecordSearchResult: Matching records. The generated SearchQuery is
-            available as ``result.search_query`` and server warnings as
-            ``result.warnings``.
+            RecordSearchResult: The statement's first page of rows.
         """
         if isinstance(prompt, dict):
             warnings.warn(
@@ -258,24 +259,45 @@ class AIAPI(BaseAPI):
             )
             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,
+            "POST", "/ai/sql-search", {"prompt": prompt}
         )
         generated_data = generated.get("data") or {}
-        search_query = generated_data.get("searchQuery") or {}
+        result = self.run_sql(generated_data.get("sql", ""), skip=skip, limit=limit)
+        result._name = generated_data.get("name")
+        result._warnings = generated_data.get("warnings") or []
+        return result
+
+    def run_sql(
+        self,
+        sql: str,
+        skip: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> RecordSearchResult:
+        """Run one read-only SQL statement over the project's schema, as Smart
+        search does: a statement from ``ai.search`` (its ``sql``), or one
+        written by hand. Labels are tables; relationship types are
+        ``rushdb_edges.<type>`` tables.
 
+        Args:
+            sql: One read-only SELECT statement.
+            skip: Rows to skip (default 0).
+            limit: Rows to return, at most 1000 (default 100).
+
+        Returns:
+            RecordSearchResult: Full records for rows that select a record's
+            ``__id``, otherwise the rows themselves; ``result.sql`` holds the
+            statement and ``result.next()`` fetches the following page.
+        """
+        page = {"skip": skip or 0, "limit": limit or 100}
         response = self.client._make_request(
-            "POST", "/records/search", search_query, headers
+            "POST", "/records/sql-search", {"sql": sql, **page}
         )
         records = [Record(self.client, item) for item in response.get("data", [])]
         return RecordSearchResult(
             data=records,
             total=response.get("total", len(records)),
-            search_query=cast(SearchQuery, search_query),
             client=self.client,
-            warnings=generated_data.get("warnings") or [],
+            sql=sql,
+            sql_page=page,
         )

{rushdb-3.0.1 → rushdb-3.1.0}/src/rushdb/api/query.py

@@ -8,7 +8,7 @@ class QueryAPI(BaseAPI):
     """API client for executing raw openCypher queries.
 
     Works on RushDB Cloud and on a self-hosted RushDB engine in direct mode
-    (the engine must be started with ``--languages cypher``).
+    (the engine must be started with ``--languages cypher,sql``).
 
     Example:
         >>> from rushdb import RushDB

{rushdb-3.0.1 → rushdb-3.1.0}/src/rushdb/direct/capabilities.py

@@ -10,7 +10,8 @@ from typing import Dict
 _PATTERNS = "relationship-pattern suggestions are produced and stored by the platform"
 
 CLOUD_ONLY_METHODS: Dict[str, str] = {
-    "ai.search": "natural-language search turns the prompt into a query with an LLM",
+    "ai.search": "natural-language search turns the prompt into a SQL statement with an LLM",
+    "ai.run_sql": "Smart search SQL runs on the platform, which loads the full records the statement selects",
     "relationships.patterns.list": _PATTERNS,
     "relationships.patterns.analyze": _PATTERNS,
     "relationships.patterns.approve": _PATTERNS,

{rushdb-3.0.1 → rushdb-3.1.0}/src/rushdb/direct/router.py

@@ -1372,7 +1372,8 @@ _ROUTES: List[Tuple[str, "re.Pattern[str]", Callable[[_Request], Body]]] = [
     ),
     ("DELETE", re.compile(rf"^/text-indexes/{_ID}$"), _drop_text_index),
     ("POST", re.compile(r"^/search/text$"), _text_search),
-    ("POST", re.compile(r"^/ai/search-query$"), _cloud_only("ai.search")),
+    ("POST", re.compile(r"^/ai/sql-search$"), _cloud_only("ai.search")),
+    ("POST", re.compile(r"^/records/sql-search$"), _cloud_only("ai.run_sql")),
     ("POST", re.compile(r"^/ai/search$"), _vector_search),
     (
         "GET",

{rushdb-3.0.1 → rushdb-3.1.0}/src/rushdb/models/result.py

@@ -32,6 +32,9 @@ class SearchResult(Generic[T]):
         client: Optional["RushDB"] = None,
         warnings: Optional[List[str]] = None,
         meta: Optional[Dict[str, Any]] = None,
+        sql: Optional[str] = None,
+        name: Optional[str] = None,
+        sql_page: Optional[Dict[str, int]] = None,
     ):
         """
         Initialize search result.
@@ -44,6 +47,10 @@ class SearchResult(Generic[T]):
             warnings: Optional warnings returned by AI-assisted query generation
             meta: How a vector, keyword or hybrid search ran (``vectorSearch``,
                 ``textSearch``, ``fusion``)
+            sql: For Smart search, the SQL statement that produced this result
+            name: For Smart search, a short title of the query
+            sql_page: For Smart search, the page (``skip``, ``limit``) of the
+                statement's rows this result holds
         """
         self._data = data
         self._total = total or len(data)
@@ -51,6 +58,9 @@ class SearchResult(Generic[T]):
         self._client = client
         self._warnings = warnings or []
         self._meta = meta or {}
+        self._sql = sql
+        self._name = name
+        self._sql_page = sql_page or {"skip": 0, "limit": 100}
 
     @property
     def data(self) -> List[T]:
@@ -67,6 +77,16 @@ class SearchResult(Generic[T]):
         """Get the search query used to generate this result."""
         return self._search_query
 
+    @property
+    def sql(self) -> Optional[str]:
+        """For Smart search: the SQL statement that produced this result."""
+        return self._sql
+
+    @property
+    def name(self) -> Optional[str]:
+        """For Smart search: a short title of the query."""
+        return self._name
+
     @property
     def warnings(self) -> List[str]:
         """Get warnings returned by AI-assisted query generation."""
@@ -87,11 +107,15 @@ class SearchResult(Generic[T]):
     @property
     def skip(self) -> int:
         """Get the number of records that were skipped."""
+        if self._sql:
+            return self._sql_page["skip"]
         return self._search_query.get("skip") or 0
 
     @property
     def limit(self) -> Optional[int]:
         """Get the limit that was applied to the search."""
+        if self._sql:
+            return self._sql_page["limit"]
         return self._search_query.get("limit")
 
     def __len__(self) -> int:
@@ -119,12 +143,14 @@ class SearchResult(Generic[T]):
         Return the result in a standardized dictionary format.
 
         Returns:
-            Dict with keys: total, data, search_query
+            Dict with keys: total, data, search_query, sql, name, warnings
         """
         return {
             "total": self.total,
             "data": self.data,
             "search_query": self.search_query,
+            "sql": self.sql,
+            "name": self.name,
             "warnings": self.warnings,
         }
 
@@ -164,7 +190,8 @@ class SearchResult(Generic[T]):
         return self._get_client().records.delete_by_id(ids, transaction)
 
     def next(self, preserve_data: bool = False) -> "SearchResult":
-        """Fetch the next page of results.
+        """Fetch the next page of results: of the original search query, or of
+        the SQL statement for a Smart search result.
 
         Args:
             preserve_data: If True, appends new records to this instance's data
@@ -174,8 +201,21 @@ class SearchResult(Generic[T]):
             SearchResult with the next page (or self when preserve_data=True)
 
         Raises:
-            RuntimeError: If no search_query was provided at construction
+            RuntimeError: If neither a search_query nor a sql statement was provided
         """
+        if self._sql:
+            next_page = {
+                "skip": self._sql_page["skip"] + self._sql_page["limit"],
+                "limit": self._sql_page["limit"],
+            }
+            result = self._get_client().ai.run_sql(self._sql, **next_page)
+            if preserve_data:
+                self._data = self._data + result._data  # type: ignore[operator]
+                self._total = result._total
+                self._sql_page = next_page
+                return self
+            result._name = self._name
+            return result
         if not self._search_query:
             raise RuntimeError(
                 "SearchResult: cannot paginate — no search_query was provided."

{rushdb-3.0.1 → rushdb-3.1.0}/tests/test_ai_vector_search.py

@@ -43,13 +43,14 @@ class TestVectorAndSmartSearch(unittest.TestCase):
         self.assertEqual(result[0].get("title"), "Alpha")
         self.assertEqual(result[0].score, 0.91)
 
-    def test_ai_search_prompt_generates_and_executes_search_query(self):
+    def test_ai_search_prompt_generates_and_runs_sql(self):
         client = Mock()
         client._make_request.side_effect = [
             {
                 "success": True,
                 "data": {
-                    "searchQuery": {"labels": ["Pilot"], "where": {"ship": "Falcon"}},
+                    "sql": 'SELECT __id FROM "Pilot" WHERE "ship" = \'Falcon\'',
+                    "name": "Falcon pilots",
                     "warnings": ["ambiguous ship name"],
                 },
             },
@@ -60,38 +61,41 @@ class TestVectorAndSmartSearch(unittest.TestCase):
             },
         ]
 
-        result = AIAPI(client).search(
-            "Who are piloting Falcon?",
-            current_query={"labels": ["Pilot"]},
-            transaction="tx_123",
-        )
+        result = AIAPI(client).search("Who are piloting Falcon?", limit=10)
 
         self.assertEqual(
             client._make_request.call_args_list[0].args,
-            (
-                "POST",
-                "/ai/search-query",
-                {
-                    "prompt": "Who are piloting Falcon?",
-                    "currentQuery": {"labels": ["Pilot"]},
-                },
-                {"X-Transaction-Id": "tx_123"},
-            ),
+            ("POST", "/ai/sql-search", {"prompt": "Who are piloting Falcon?"}),
         )
+        sql = 'SELECT __id FROM "Pilot" WHERE "ship" = \'Falcon\''
+        self.assertEqual(
+            client._make_request.call_args_list[1].args,
+            ("POST", "/records/sql-search", {"sql": sql, "skip": 0, "limit": 10}),
+        )
+        self.assertEqual(result.sql, sql)
+        self.assertEqual(result.name, "Falcon pilots")
+        self.assertEqual(result.warnings, ["ambiguous ship name"])
+        self.assertEqual(result.search_query, {})
+        self.assertEqual(result[0].get("name"), "Han")
+
+    def test_smart_search_result_pages_through_its_sql(self):
+        client = Mock()
+        client._make_request.return_value = {"success": True, "total": 3, "data": []}
+        client.ai = AIAPI(client)
+
+        first = client.ai.run_sql('SELECT __id FROM "Pilot"', limit=2)
+        self.assertEqual((first.skip, first.limit), (0, 2))
+        second = first.next()
+
         self.assertEqual(
             client._make_request.call_args_list[1].args,
             (
                 "POST",
-                "/records/search",
-                {"labels": ["Pilot"], "where": {"ship": "Falcon"}},
-                {"X-Transaction-Id": "tx_123"},
+                "/records/sql-search",
+                {"sql": 'SELECT __id FROM "Pilot"', "skip": 2, "limit": 2},
             ),
         )
-        self.assertEqual(
-            result.search_query, {"labels": ["Pilot"], "where": {"ship": "Falcon"}}
-        )
-        self.assertEqual(result.warnings, ["ambiguous ship name"])
-        self.assertEqual(result[0].get("name"), "Han")
+        self.assertEqual((second.skip, second.limit, second.sql), (2, 2, first.sql))
 
     def test_ai_search_dict_is_deprecated_vector_search_alias(self):
         client = Mock()

{rushdb-3.0.1 → rushdb-3.1.0}/tests/test_direct_mode.py

@@ -271,6 +271,7 @@ EVERY_METHOD = {
         "book-vec", {"items": [{"recordId": RECORD["id"], "vector": [1, 0, 0]}]}
     ),
     "ai.search": lambda db: db.ai.search("books about deserts"),
+    "ai.run_sql": lambda db: db.ai.run_sql('SELECT __id FROM "Book"'),
     "settings.get": lambda db: db.settings.get(),
 }
 

{rushdb-3.0.1 → rushdb-3.1.0}/uv.lock

@@ -710,7 +710,7 @@ wheels = [
 
 [[package]]
 name = "rushdb"
-version = "3.0.1"
+version = "3.1.0"
 source = { editable = "." }
 
 [package.dev-dependencies]