Merge branch '45-bump-to-4.0.0' into dev

.github/workflows/test.yaml

@@ -11,7 +11,9 @@ jobs:
       matrix:
         os: ["ubuntu", "windows", "macos"]
         python: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"] # https://devguide.python.org/versions/#versions
-
+        exclude:
+        - os: "macos"
+          python: "3.7" # Prevent "The version '3.7' with architecture 'arm64' was not found for macOS 14.4.1"
     runs-on: ${{ matrix.os }}-latest
 
     steps:

CHANGELOG.md

@@ -0,0 +1,19 @@
+ObjectBox Python ChangeLog
+==========================
+
+4.0.0 (2024-05-16)
+------------------
+
+* ObjectBox now supports vector search ("vector database") to enable efficient similarity searches.
+  This is particularly useful for AI/ML/RAG applications, e.g. image, audio, or text similarity.
+  Other use cases include sematic search or recommendation engines.
+  See https://docs.objectbox.io/ann-vector-search for details.
+* Queries: support for Property-based conditions and logic combinations 
+* Convenient "Store" API deprecates ObjectBox and Builder API
+* New examples added, illustrating an VectorSearch and AI/RAG application
+* Dependency flatbuffers: Updated to 24.3.50
+* Adjusting the version number to match the core version (4.0); we will be aligning on major versions from now on.
+
+Older Versions
+--------------
+Please check https://github.com/objectbox/objectbox-python/releases for details.

README.md

@@ -1,82 +1,56 @@
-ObjectBox Python API
-====================
-[ObjectBox](https://objectbox.io) is a superfast database for objects, now also available for Python (3.4+) with a simple CRUD API.
+ObjectBox Python
+================
+[ObjectBox](https://objectbox.io) Python is a lightweight yet powerful on-device database & vector database.
+Store Python objects and vectors directly with an easy-to-use CRUD API while enjoying exceptional speed and efficiency.
 And because it's an embedded database, there's no setup required.
-
-## Table of Contents:
-- [Getting Started](#getting-started)
-   - [Model IDs and UIDs](#model-ids-and-uids)
-   - [model.py](#modelpy)
-- [Using ObjectBox](#using-objectbox)
-- [Some features](#some-features)
-- [Coming in the future](#coming-in-the-future)
-- [Help wanted](#help-wanted)
-- [Feedback](#feedback)
-- [License](#license)
 
----
+Its advanced vector search empowers AI for a variety of applications, including RAG AI, generative AI,
+and similarity searches.
 
-Getting started
----------------
-First of all, install the latest version:
+Designed for high performance, the ObjectBox database runs locally on-device.
+As an offline-first solution, ObjectBox makes sure your app reliably works offline as well as online
+(via [Sync](https://objectbox.io/sync/)).
 
-```bash
-pip install --upgrade objectbox
-```
-
-To start using ObjectBox as a storage for your data, you need to define your model first.
-The model consists of Python classes annotated with `@Entity` decorator.
-
-### Model IDs and UIDs
+_Table of Contents_
 
-Each Entity has to have an ID (unique among entities).
-Properties need an ID as well (unique inside one Entity).
-Both Entities and Properties must also have an UID, which is a globally unique identifier.
-
-For other ObjectBox supported languages, the binding takes care of assigning these IDs/UIDs but this feature is not yet implemented for Python.
-To learn more, see [ObjectBox Java documentation](https://docs.objectbox.io/advanced/meta-model-ids-and-uids)
-
-#### model.py
+- [Feature Highlights](#feature-highlights)
+- [Code Example (CRUD - Create, Read, Update, Delete)](#code-example-crud---create-read-update-delete)
+- [Getting Started](#getting-started)
+- [Alpha Notes](#alpha-notes)
+- [Help wanted](#help-wanted)
+- [Feedback](#feedback)
+- [License](#license)
 
-```python
-from objectbox.model import *
-
-@Entity(id=1, uid=1)
-class Person:
-    id = Id(id=1, uid=1001)
-    name = Property(str, id=2, uid=1002)
-    is_enabled = Property(bool, id=3, uid=1003)
-    # int can be stored with 64 (default), 32, 16 or 8 bit precision.
-    int64 = Property(int, id=4, uid=1004)
-    int32 = Property(int, type=PropertyType.int, id=5, uid=1005)
-    int16 = Property(int, type=PropertyType.short, id=6, uid=1006)
-    int8 = Property(int, type=PropertyType.byte, id=7, uid=1007)
-    # float can be stored with 64 or 32 (default) bit precision.
-    float64 = Property(float, id=8, uid=1008)
-    float32 = Property(float, type=PropertyType.float, id=9, uid=1009)
-    byte_array = Property(bytes, id=10, uid=1010)
-    # Regular properties are not stored.
-    transient = ""
-```
+Feature Highlights
+------------------
 
-### Using ObjectBox
+🏁 **On-device vector database** - for AI apps that work any place.\
+🏁 **High performance** - superfast response rates enabling real-time applications.\
+🪂 **ACID compliant** - Atomic, Consistent, Isolated, Durable.\
+🌱 **Scalable** - grows with your app, handling millions of objects with ease.\
+💚 **Sustainable** - frugal on CPU, Memory and battery / power use, reducing CO2 emissions.\
+💐 **[Queries](https://docs.objectbox.io/queries)** - filter data as needed, even across relations.\
+💻 **Multiplatform** - Get native speed on your favorite platforms.\
+* Linux x86-64 (64-bit)
+* Linux ARMv6hf (e.g. Raspberry PI Zero)
+* Linux ARMv7hf (e.g. Raspberry PI 3)
+* Linux ARMv8   (e.g. Raspberry PI 4, 5, etc.)
+* MacOS x86-64 and arm64 (Intel 64-bit and Apple Silicon)
+* Windows x86-64 (64-bit)
 
-To actually use the database, you create a Store with the model you've just defined.
-Afterwards, you can reuse the instance (`store` in the example below) and use it to access "Entity Boxes" which hold your objects.
+#### Code Example (CRUD - Create, Read, Update, Delete)
 
-#### program.py
+What does using ObjectBox in Python look like?
 
 ```python
 import objectbox
+
 # from mypackage.model import Person
 
-# Configure ObjectBox: should be done only once in the whole program and the "store" variable should be kept around
-model = objectbox.Model()
-model.entity(Person, last_property_id=objectbox.model.IdUid(10, 1010))
-model.last_entity_id = objectbox.model.IdUid(1, 1)
+# The ObjectBox Store represents a database; keep it around...
 store = objectbox.Store(model=model)
 
-# Open the box of "Person" entity. This can be called many times but you can also pass the variable around
+# Get a box for the "Person" entity; a Box is the main interaction point with objects and the database.
 box = store.box(Person)
 
 person = Person()
@@ -88,65 +62,46 @@ box.put(person)       # Update
 box.remove(person)    # Delete
 ```
 
-Additionally, see the [TaskList example app](https://github.com/objectbox/objectbox-python/tree/main/example). After checking out this repository to run the example:
+Getting started
+---------------
+Latest version: 4.0.0a0 (2024-05-15)
+
+To install or update the latest version of ObjectBox, run this:
+
+```bash
+pip install --upgrade --pre objectbox  # "--pre" because you want to get the 4.0.0 alpha version
 ```
-// Set up virtual environment, download ObjectBox libraries
-make depend
+Now you are ready to use ObjectBox in your Python project.
 
-// Activate virtual environment...
-// ...on Linux
-source .venv/bin/activate
-// ...on Windows
-.venv\Scripts\activate
+Head over to the **[ObjectBox documentation](https://docs.objectbox.io)**
+and learn how to setup your first entity classes.
 
-// Run the example
-python3 -m example
+### Examples
 
-// Once done, leave the virtual environment
-deactivate
-```
+Do you prefer to dive right into working examples?
+We have you covered in the [example](example/) folder.
+It comes with a task list application and a vector search example using cities.
+Additionally, for AI enthusiasts, we provide an "ollama" example,
+which integrates a local LLM (via [ollama](https://ollama.com))
+with ObjectBox to manage and search embeddings effectively.
 
-For more information and code examples, see the tests folder. The docs for other languages may also help you understand the basics.
-
-* ObjectBox Java/Dart/Flutter - https://docs.objectbox.io
-* ObjectBox Go - https://golang.objectbox.io
-* ObjectBox Swift - https://swift.objectbox.io
-
-Some features
--------------
-* Automatic transactions (ACID compliant)
-* Bulk operations
-* Vector types, e.g. for AI vector embeddings
-* Platforms supported with native speed:
-  * Linux x86-64 (64-bit)
-  * Linux ARMv6hf (e.g. Raspberry PI Zero)
-  * Linux ARMv7hf (e.g. Raspberry PI 3; available only on request)
-  * Linux ARMv8   (e.g. Raspberry PI 4)
-  * MacOS x86-64 and arm64 (Intel 64-bit and Apple Silicon)
-  * Windows x86-64 (64-bit)
-
-Coming in the future
---------------------
-The goodness you know from the other ObjectBox language-bindings, e.g.,
-
-* model management (no need to manually set id/uid)
-* automatic model migration (no schema upgrade scripts etc.)
-* powerful queries
-* relations (to-one, to-many)
-* asynchronous operations
-* secondary indexes
+Alpha Notes
+-----------
+While ObjectBox Python is powered by a rock stable core written in C/C++, we label our Python binding still "alpha."
+We do this to manage expectations as some quality of life improvements are yet to come to our Python binding.
+This is mostly about "model management," which still requires you to do some manual coding setup, e.g. for model IDs.
+The final release will take care of this for you automatically.
 
 Help wanted
 -----------
-ObjectBox for Python is still in an early stage with limited feature set (compared to our other supported languages).
-To bring all these features to Python, we're asking the community to help out. PRs are more than welcome!
+ObjectBox for Python is open to contributions.
 The ObjectBox team will try its best to guide you and answer questions.
 See [CONTRIBUTING.md](https://github.com/objectbox/objectbox-python/blob/main/CONTRIBUTING.md) to get started.
 
 Feedback
 --------
-Also, please let us know your feedback by opening an issue: for example, if you experience errors or if you have ideas
-for how to improve the API. Thanks!
+We are looking for your feedback!
+Please let us know what you think about ObjectBox for Python and how we can improve it.
 
 License
 -------

download-c-lib.py

@@ -6,7 +6,7 @@
 # Script used to download objectbox-c shared libraries for all supported platforms. Execute by running `make get-lib`
 # on first checkout of this repo and any time after changing the objectbox-c lib version.
 
-version = "v0.21.1-alpha5"  # see objectbox/c.py required_version
+version = "v4.0.0"  # see objectbox/c.py required_version
 variant = 'objectbox'  # or 'objectbox-sync'
 
 base_url = "https://github.com/objectbox/objectbox-c/releases/download/"

example/README.md

@@ -1,14 +1,29 @@
 # ObjectBox-Python Examples
 
-The following examples are available from this repository.
+This directory contains a couple of examples that demonstrate capabilities of ObjectBox using the Python API.
+
+As we are currently short before releasing 4.0 version, please install the pre-release version of `objectbox` from PyPI via `pip`; for example, on UN*X-flavour platforms:
+
+```shell
+cd example # assuming you are in project root dir 
+python3 -m venv venv
+source venv/bin/activate
+pip install --pre objectbox
+```
+
+The following examples are available from this directory:
+
+- `tasks`: CRUD Application Example (see below for details)
+- `vectorsearch-cities`: VectorSearch Application Example (see below for details)
+- `ollama`: LLM + VectorSearch Embeddings Script Example (See [ollama/README.md](./ollama/README.md) for details)
+
 
 ## Application Example: Tasks
 
 This is our classic Tasks application using a CLI.
 
 ```
-cd example
-python -m tasks
+$ python -m tasks
 
 Welcome to the ObjectBox tasks-list app example. Type help or ? for a list of commands.
 > new buy oat
@@ -36,7 +51,8 @@ This example application starts with a pre-defined set of capital cities and the
 It allows to search for nearest neighbors of a city (`city_neighbors`) or by coordinates (`neighbors`) as well as adding more locations (`add`).
 
 ```
-python -m vectorsearch-cities
+$ python -m vectorsearch-cities
+
 Welcome to the ObjectBox vectorsearch-cities example. Type help or ? for a list of commands.
 > ls
 ID   Name                        Latitude  Longitude

example/vectorsearch-cities/__main__.py

@@ -24,7 +24,7 @@ def __init__(self, *args):
         dbdir = "cities-db"
         new_db = not os.path.exists(dbdir)
         self._store = objectbox.Store(model=get_objectbox_model(),directory=dbdir)
-        self._box = _store.box(City)
+        self._box = self._store.box(City)
         self._name_prop: Property = City.get_property("name")
         self._location_prop: Property = City.get_property("location")
         if new_db: 

objectbox/__init__.py

@@ -34,7 +34,7 @@
 ]
 
 # Python binding version
-version = Version(0, 7, 0, alpha=14)
+version = Version(4, 0, 0, alpha=0)
 
 
 def version_info():

objectbox/c.py

@@ -27,7 +27,7 @@
 
 # Version of the library used by the binding. This version is checked at runtime to ensure binary compatibility.
 # Don't forget to update download-c-lib.py when upgrading to a newer version.
-required_version = "0.21.0"
+required_version = "4.0.0"
 
 
 def shlib_name(library: str) -> str:

tests/test_basics.py

@@ -16,11 +16,11 @@
 
 
 def test_version():
-    assert objectbox.version.major == 0  # update for major version changes
-    assert objectbox.version.minor >= 6
+    assert objectbox.version.major == 4  # update for major version changes
+    assert objectbox.version.minor >= 0
 
-    assert objectbox.version_core.major == 0  # update for major version changes
-    assert objectbox.version_core.minor >= 21
+    assert objectbox.version_core.major == 4  # update for major version changes
+    assert objectbox.version_core.minor >= 0
 
     info = objectbox.version_info()
     print("\nVersion found:", info)