rushdb 2.10.0__tar.gz → 3.0.1__tar.gz

{rushdb-2.10.0 → rushdb-3.0.1}/.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.1}/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/README.md → rushdb-3.0.1/PKG-INFO

@@ -1,19 +1,32 @@
+Metadata-Version: 2.5
+Name: rushdb
+Version: 3.0.1
+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
+Project-URL: Documentation, https://docs.rushdb.com
+Author-email: RushDB Team <hi@rushdb.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent-memory,ai-agents,cypher,database,database-for-ai,full-text-search,graph-database,hybrid-search,mcp,rag,rushdb,self-hosted,sql,vector-search
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 ![RushDB Logo](https://raw.githubusercontent.com/rush-db/rushdb/main/rushdb-logo.svg)
 
 # RushDB — Python SDK
 
-### The memory layer for AI agents and apps.
+### RushDB — the database for AI
 
-Push any JSON. Get graph relationships and vector search — automatically.
-No schema. No pipeline. No glue code.
+One database for your records, their relationships, and search over them.
 
 ![PyPI - Version](https://img.shields.io/pypi/v/rushdb)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rushdb)
 ![PyPI - License](https://img.shields.io/pypi/l/rushdb)
 
-[📖 Documentation](https://docs.rushdb.com/python-sdk/introduction) • [🌐 Website](https://rushdb.com) • [☁️ Cloud](https://app.rushdb.com)
+[📖 Documentation](https://docs.rushdb.com/3.x/connect/sdks/) • [🌐 Website](https://rushdb.com) • [☁️ Cloud](https://app.rushdb.com)
 
 </div>
 
@@ -37,6 +50,74 @@ pip install rushdb
 
 ---
 
+## Compatibility
+
+| Package | RushDB 3.x and RushDB Cloud | RushDB 2.x (legacy) |
+|---|---|---|
+| `@rushdb/javascript-sdk` | 3.x | 2.11.0: `npm i @rushdb/javascript-sdk@2` |
+| `rushdb` (PyPI) | 3.x | 2.10.0: `pip install "rushdb<3"` |
+| `@rushdb/mcp-server` | 3.x | 2.13.0: `npx @rushdb/mcp-server@2` |
+
+---
+
+## 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 +312,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 +390,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,
 )
 ```
@@ -288,7 +399,7 @@ db = RushDB(
 
 ## Documentation
 
-[docs.rushdb.com/python-sdk](https://docs.rushdb.com/python-sdk/introduction) — full API reference, vector search, aggregations, and more.
+[docs.rushdb.com/3.x/connect/sdks](https://docs.rushdb.com/3.x/connect/sdks/) and the [Python reference](https://docs.rushdb.com/3.x/learn/reference/python/) — full API reference, vector search, aggregations, and more.
 
 ---
 

rushdb-2.10.0/PKG-INFO → rushdb-3.0.1/README.md

@@ -1,44 +1,18 @@
-Metadata-Version: 2.4
-Name: rushdb
-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
-Project-URL: Documentation, https://docs.rushdb.com
-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'
-Description-Content-Type: text/markdown
-
 <div align="center">
 
 ![RushDB Logo](https://raw.githubusercontent.com/rush-db/rushdb/main/rushdb-logo.svg)
 
 # RushDB — Python SDK
 
-### The memory layer for AI agents and apps.
+### RushDB — the database for AI
 
-Push any JSON. Get graph relationships and vector search — automatically.
-No schema. No pipeline. No glue code.
+One database for your records, their relationships, and search over them.
 
 ![PyPI - Version](https://img.shields.io/pypi/v/rushdb)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rushdb)
 ![PyPI - License](https://img.shields.io/pypi/l/rushdb)
 
-[📖 Documentation](https://docs.rushdb.com/python-sdk/introduction) • [🌐 Website](https://rushdb.com) • [☁️ Cloud](https://app.rushdb.com)
+[📖 Documentation](https://docs.rushdb.com/3.x/connect/sdks/) • [🌐 Website](https://rushdb.com) • [☁️ Cloud](https://app.rushdb.com)
 
 </div>
 
@@ -62,6 +36,74 @@ pip install rushdb
 
 ---
 
+## Compatibility
+
+| Package | RushDB 3.x and RushDB Cloud | RushDB 2.x (legacy) |
+|---|---|---|
+| `@rushdb/javascript-sdk` | 3.x | 2.11.0: `npm i @rushdb/javascript-sdk@2` |
+| `rushdb` (PyPI) | 3.x | 2.10.0: `pip install "rushdb<3"` |
+| `@rushdb/mcp-server` | 3.x | 2.13.0: `npx @rushdb/mcp-server@2` |
+
+---
+
+## 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 +298,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 +376,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,
 )
 ```
@@ -313,7 +385,7 @@ db = RushDB(
 
 ## Documentation
 
-[docs.rushdb.com/python-sdk](https://docs.rushdb.com/python-sdk/introduction) — full API reference, vector search, aggregations, and more.
+[docs.rushdb.com/3.x/connect/sdks](https://docs.rushdb.com/3.x/connect/sdks/) and the [Python reference](https://docs.rushdb.com/3.x/learn/reference/python/) — full API reference, vector search, aggregations, and more.
 
 ---
 

rushdb-3.0.1/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "rushdb"
+version = "3.0.1"
+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"}
+]
+license = {text = "Apache-2.0"}
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = [
+    "rushdb",
+    "database",
+    "database-for-ai",
+    "ai-agents",
+    "graph-database",
+    "sql",
+    "cypher",
+    "vector-search",
+    "full-text-search",
+    "hybrid-search",
+    "mcp",
+    "self-hosted",
+    "rag",
+    "agent-memory"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/rush-db/rushdb-python"
+Repository = "https://github.com/rush-db/rushdb-python"
+Documentation = "https://docs.rushdb.com"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rushdb"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.isort]
+profile = "black"
+
+[dependency-groups]
+dev = [
+    "black>=26.3.1",
+    "isort>=5.13.2",
+    "mypy>=1.14.1",
+    "pygments>=2.20.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=5.0.0",
+    "python-dotenv>=1.2.2",
+    "ruff>=0.12.1,<0.13",
+    "types-python-dateutil>=2.9.0.20241206",
+]

{rushdb-2.10.0 → rushdb-3.0.1}/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.1}/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.1}/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