rushdb 2.9.0__tar.gz → 3.0.0__tar.gz

{rushdb-2.9.0 → rushdb-3.0.0}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
@@ -43,7 +43,7 @@ jobs:
         run: |
           uv run pytest
 
-  publish:
+  build:
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     needs: test
@@ -61,13 +61,28 @@ jobs:
         with:
           version: "latest"
 
-      - name: Install dependencies
-        run: |
-          uv sync --dev
+      - name: Build distributions
+        run: uv build
 
-      - name: Build and publish
-        env:
-          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
-        run: |
-          uv build
-          uv publish
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{rushdb-2.9.0 → rushdb-3.0.0}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ When reporting an issue, include the following information:
 
 - Specify the version of RushDB you are using:
   - **Cloud**: Mention if you are using the latest cloud version.
-  - **Self-hosted**: Provide the tag from Docker Hub or the SDK version.
+  - **Self-hosted engine (direct mode)**: Provide the engine version (`rushdb --version`) and the SDK version.
 
 3. **Steps to Reproduce**
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rushdb
-Version: 2.9.0
+Version: 3.0.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
@@ -9,18 +9,7 @@ Author-email: RushDB Team <hi@rushdb.com>
 License: Apache-2.0
 License-File: LICENSE
 Keywords: agent memory,agent-memory,ai agents,ai memory,ai-agents,ai-memory,cloud,database,embedding,embeddings,graph,graph database,graph-database,json normalization,json-normalization,knowledge graph,knowledge-graph,llm memory,llm-memory,mcp,memory layer,memory-layer,no-schema,persistence,rag,relationships,rest api,rest-api,retrieval augmented generation,rush db,rush-db,rushdb,schema-less,schemaless,self-hosted,vector search,vector-search
-Requires-Python: >=3.8
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: requests>=2.31.0
-Provides-Extra: dev
-Requires-Dist: black>=23.7.0; extra == 'dev'
-Requires-Dist: isort>=5.12.0; extra == 'dev'
-Requires-Dist: mypy>=1.4.1; extra == 'dev'
-Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
-Requires-Dist: pytest>=7.4.0; extra == 'dev'
-Requires-Dist: ruff>=0.0.280; extra == 'dev'
-Requires-Dist: types-python-dateutil>=2.8.19.14; extra == 'dev'
-Requires-Dist: types-requests>=2.31.0.1; extra == 'dev'
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -62,6 +51,64 @@ pip install rushdb
 
 ---
 
+## RushDB Cloud or a self-hosted engine
+
+The SDK works with RushDB in one of two ways:
+
+| | RushDB Cloud | Self-hosted RushDB engine (direct mode) |
+| --- | --- | --- |
+| What you run | nothing: the managed service at [app.rushdb.com](https://app.rushdb.com) | one `rushdb` binary, on your own infrastructure |
+| Connect with | an API key | the engine URL and the engine token |
+
+The engine is what you can self-host. RushDB Cloud runs that engine for you and adds the dashboard,
+managed embeddings and the AI features (natural-language search, relationship-pattern suggestions),
+which exist only in RushDB Cloud.
+
+```python
+from rushdb import RushDB
+
+# RushDB Cloud
+db = RushDB("RUSHDB_API_KEY")
+
+# A self-hosted engine
+db = RushDB(
+    "ENGINE_TOKEN",
+    direct=True,
+    engine_url="http://127.0.0.1:3000",
+    scope="tenant-1",  # only for an engine started with --multitenant
+)
+```
+
+What each offers:
+
+| Feature | Cloud | Self-hosted engine |
+| --- | :---: | :---: |
+| Records: create, read, update, set, upsert, delete, `find` with `where`, `orderBy`, `select`, `groupBy` | ✓ | ✓ |
+| Relationships: `attach`/`detach`, `relationships.create_many`/`delete_many`/`find` | ✓ | ✓ |
+| Labels, properties, property values | ✓ | ✓ |
+| Import JSON and CSV, export CSV | ✓ | ✓ |
+| External vector indexes; vector search with a `queryVector` you supply | ✓ | ✓ |
+| Raw openCypher (`query.raw`; the engine needs `--languages cypher`) | ✓ | ✓ |
+| Schema (`ai.get_schema`, `ai.get_schema_markdown`) | ✓ | ✓ |
+| 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`) | ✓ | — |
+| Relationship-pattern suggestions (`relationships.patterns.*`) | ✓ | — |
+| Project settings (`settings.get`), dashboard, team access | ✓ | — |
+
+In direct mode a Cloud-only method raises `CloudOnlyError` (with `method` and `reason`) before
+sending anything, and no request ever goes to RushDB Cloud. A write the engine cannot stage into a
+transaction raises `DirectModeError`, also before sending anything. The list is available in code:
+
+```python
+from rushdb import CLOUD_ONLY_METHODS, CloudOnlyError, is_cloud_only_method
+```
+
+`db.engine.execute()` runs any Protocol v1 operation directly.
+
+---
+
 ## Agent memory in 3 lines
 
 Get an API key at [app.rushdb.com](https://app.rushdb.com).
@@ -227,6 +274,67 @@ 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({...})`.
+
+## Keyword And Hybrid Search
+
+Declare a BM25 text index, then search it by keywords:
+
+```python
+db.text_indexes.create({'label': 'MEMORY', 'property': 'content'})
+
+results = db.records.text_search({
+    'query': 'quarterly results',
+    'labels': ['MEMORY'],
+    'where': {'agent_id': 'agent-42'},
+    'limit': 5,
+})
+print(results.total, results.meta['textSearch'])
+```
+
+Add a `text` leg to a vector search to fuse keyword and vector ranking. `fusion`
+is `rrf` (default) or `dbsf`; `weight` and `prefetchLimit` tune each leg:
+
+```python
+results = db.records.vector_search({
+    'labels': ['MEMORY'],
+    'propertyName': 'content',
+    'queryVector': embedding,
+    'text': {'query': 'quarterly results', 'weight': 0.5},
+    'fusion': 'dbsf',
+    'limit': 5,
+})
+```
+
+---
+
 ## Record API
 
 ```python
@@ -273,7 +381,7 @@ from rushdb import RushDB
 
 db = RushDB(
     'RUSHDB_API_KEY',
-    url='http://your-rushdb-server.com/api/v1',  # default: https://api.rushdb.com/api/v1
+    url='https://api.rushdb.com/api/v1',  # a different RushDB Cloud API endpoint; this is the default
     timeout=30,
 )
 ```

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

@@ -37,6 +37,64 @@ pip install rushdb
 
 ---
 
+## RushDB Cloud or a self-hosted engine
+
+The SDK works with RushDB in one of two ways:
+
+| | RushDB Cloud | Self-hosted RushDB engine (direct mode) |
+| --- | --- | --- |
+| What you run | nothing: the managed service at [app.rushdb.com](https://app.rushdb.com) | one `rushdb` binary, on your own infrastructure |
+| Connect with | an API key | the engine URL and the engine token |
+
+The engine is what you can self-host. RushDB Cloud runs that engine for you and adds the dashboard,
+managed embeddings and the AI features (natural-language search, relationship-pattern suggestions),
+which exist only in RushDB Cloud.
+
+```python
+from rushdb import RushDB
+
+# RushDB Cloud
+db = RushDB("RUSHDB_API_KEY")
+
+# A self-hosted engine
+db = RushDB(
+    "ENGINE_TOKEN",
+    direct=True,
+    engine_url="http://127.0.0.1:3000",
+    scope="tenant-1",  # only for an engine started with --multitenant
+)
+```
+
+What each offers:
+
+| Feature | Cloud | Self-hosted engine |
+| --- | :---: | :---: |
+| Records: create, read, update, set, upsert, delete, `find` with `where`, `orderBy`, `select`, `groupBy` | ✓ | ✓ |
+| Relationships: `attach`/`detach`, `relationships.create_many`/`delete_many`/`find` | ✓ | ✓ |
+| Labels, properties, property values | ✓ | ✓ |
+| Import JSON and CSV, export CSV | ✓ | ✓ |
+| External vector indexes; vector search with a `queryVector` you supply | ✓ | ✓ |
+| Raw openCypher (`query.raw`; the engine needs `--languages cypher`) | ✓ | ✓ |
+| Schema (`ai.get_schema`, `ai.get_schema_markdown`) | ✓ | ✓ |
+| 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`) | ✓ | — |
+| Relationship-pattern suggestions (`relationships.patterns.*`) | ✓ | — |
+| Project settings (`settings.get`), dashboard, team access | ✓ | — |
+
+In direct mode a Cloud-only method raises `CloudOnlyError` (with `method` and `reason`) before
+sending anything, and no request ever goes to RushDB Cloud. A write the engine cannot stage into a
+transaction raises `DirectModeError`, also before sending anything. The list is available in code:
+
+```python
+from rushdb import CLOUD_ONLY_METHODS, CloudOnlyError, is_cloud_only_method
+```
+
+`db.engine.execute()` runs any Protocol v1 operation directly.
+
+---
+
 ## Agent memory in 3 lines
 
 Get an API key at [app.rushdb.com](https://app.rushdb.com).
@@ -202,6 +260,67 @@ 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({...})`.
+
+## Keyword And Hybrid Search
+
+Declare a BM25 text index, then search it by keywords:
+
+```python
+db.text_indexes.create({'label': 'MEMORY', 'property': 'content'})
+
+results = db.records.text_search({
+    'query': 'quarterly results',
+    'labels': ['MEMORY'],
+    'where': {'agent_id': 'agent-42'},
+    'limit': 5,
+})
+print(results.total, results.meta['textSearch'])
+```
+
+Add a `text` leg to a vector search to fuse keyword and vector ranking. `fusion`
+is `rrf` (default) or `dbsf`; `weight` and `prefetchLimit` tune each leg:
+
+```python
+results = db.records.vector_search({
+    'labels': ['MEMORY'],
+    'propertyName': 'content',
+    'queryVector': embedding,
+    'text': {'query': 'quarterly results', 'weight': 0.5},
+    'fusion': 'dbsf',
+    'limit': 5,
+})
+```
+
+---
+
 ## Record API
 
 ```python
@@ -248,7 +367,7 @@ from rushdb import RushDB
 
 db = RushDB(
     'RUSHDB_API_KEY',
-    url='http://your-rushdb-server.com/api/v1',  # default: https://api.rushdb.com/api/v1
+    url='https://api.rushdb.com/api/v1',  # a different RushDB Cloud API endpoint; this is the default
     timeout=30,
 )
 ```

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

@@ -1,13 +1,13 @@
 [project]
 name = "rushdb"
-version = "2.9.0"
+version = "3.0.0"
 description = "RushDB Python SDK — memory layer for AI agents and modern apps"
 authors = [
     {name = "RushDB Team", email = "hi@rushdb.com"}
 ]
 license = {text = "Apache-2.0"}
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 keywords = [
     "rushdb",
     "database",
@@ -47,28 +47,13 @@ keywords = [
     "rush-db",
     "rush db"
 ]
-dependencies = [
-    "python-dotenv>=1.0.0",
-    "requests>=2.31.0"
-]
+dependencies = []
 
 [project.urls]
 Homepage = "https://github.com/rush-db/rushdb-python"
 Repository = "https://github.com/rush-db/rushdb-python"
 Documentation = "https://docs.rushdb.com"
 
-[project.optional-dependencies]
-dev = [
-    "black>=23.7.0",
-    "isort>=5.12.0",
-    "ruff>=0.0.280",
-    "mypy>=1.4.1",
-    "pytest>=7.4.0",
-    "pytest-cov>=4.1.0",
-    "types-requests>=2.31.0.1",
-    "types-python-dateutil>=2.8.19.14"
-]
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -84,12 +69,13 @@ profile = "black"
 
 [dependency-groups]
 dev = [
-    "black>=24.8.0",
+    "black>=26.3.1",
     "isort>=5.13.2",
     "mypy>=1.14.1",
-    "pytest>=8.3.5",
+    "pygments>=2.20.0",
+    "pytest>=9.0.3",
     "pytest-cov>=5.0.0",
-    "ruff>=0.12.1",
+    "python-dotenv>=1.2.2",
+    "ruff>=0.12.1,<0.13",
     "types-python-dateutil>=2.9.0.20241206",
-    "types-requests>=2.32.0.20241016",
 ]

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

@@ -8,8 +8,14 @@ from .api.query import QueryAPI
 from .api.records import pick_record_id
 from .api.relationship_patterns import RelationshipPatternsAPI
 from .api.relationships import RelationsAPI
+from .api.text_indexes import TextIndexesAPI
 from .client import RushDB
-from .common import NonUniqueResultError, RushDBError
+from .common import CloudOnlyError, DirectModeError, NonUniqueResultError, RushDBError
+from .direct.capabilities import (
+    CLOUD_ONLY_FORMS,
+    CLOUD_ONLY_METHODS,
+    is_cloud_only_method,
+)
 from .models.api_response import ApiResponse
 from .models.property import Property
 from .models.record import Record, RecordTarget, RelationTarget
@@ -31,6 +37,11 @@ from .models.search_query import (
 from .models.transaction import Transaction
 
 __all__ = [
+    "CLOUD_ONLY_FORMS",
+    "CLOUD_ONLY_METHODS",
+    "CloudOnlyError",
+    "DirectModeError",
+    "is_cloud_only_method",
     "RushDB",
     "RushDBError",
     "NonUniqueResultError",
@@ -57,4 +68,5 @@ __all__ = [
     "RelationshipPatternsAPI",
     "ApiResponse",
     "AIAPI",
+    "TextIndexesAPI",
 ]

{rushdb-2.9.0 → rushdb-3.0.0}/src/rushdb/api/__init__.py

@@ -1,12 +1,15 @@
+from .ai import AIAPI
 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 .text_indexes import TextIndexesAPI
 from .transactions import TransactionsAPI
 
 __all__ = [
+    "AIAPI",
     "RecordsAPI",
     "PropertiesAPI",
     "LabelsAPI",
@@ -14,4 +17,5 @@ __all__ = [
     "QueryAPI",
     "RelationsAPI",
     "RelationshipPatternsAPI",
+    "TextIndexesAPI",
 ]

{rushdb-2.9.0 → rushdb-3.0.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.9.0 → rushdb-3.0.0}/src/rushdb/api/query.py

@@ -5,11 +5,10 @@ from .base import BaseAPI
 
 
 class QueryAPI(BaseAPI):
-    """API client for executing raw Cypher queries (cloud-only).
+    """API client for executing raw openCypher queries.
 
-    This endpoint is only available when using the RushDB managed cloud
-    service or when your project is connected to a custom database through
-    RushDB Cloud. It will not function for self-hosted or local-only deployments.
+    Works on RushDB Cloud and on a self-hosted RushDB engine in direct mode
+    (the engine must be started with ``--languages cypher``).
 
     Example:
         >>> from rushdb import RushDB