rushdb 2.10.0__tar.gz → 3.0.0__tar.gz

{rushdb-2.10.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.10.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.10.0 → rushdb-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rushdb
-Version: 2.10.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).
@@ -256,6 +303,36 @@ 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
@@ -304,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.10.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).
@@ -231,6 +289,36 @@ 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
@@ -279,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.10.0 → rushdb-3.0.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "rushdb"
-version = "2.10.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.10.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.10.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.10.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