Add sync-upstream script to manage upstream changes while preserving fork-specific customizations

Author: tae898

.gitattributes

@@ -1,2 +1,8 @@
 package/src/main/scripts/console.bat eol=crlf
 package/src/main/scripts/server.bat eol=crlf
+
+# Fork-specific paths - automatically prefer our version during upstream sync
+# See ./sync-upstream.sh for sync workflow
+/README.md merge=ours
+.github/workflows/** merge=ours
+bindings/python/** merge=ours

README.md

@@ -1,193 +1,173 @@
-# ![ArcadeDB](https://arcadedb.com/assets/images/arcadedb-logo.png)
-
-<h2 align="center">Multi Model DBMS Built for Extreme Performance</h2>
-
-<p align="center">
-  <a href="https://github.com/ArcadeData/arcadedb/releases"><img src="https://img.shields.io/github/v/release/arcadedata/arcadedb?color=%23ff00a0&include_prereleases&label=version&sort=semver"></a>
-  &nbsp;
-  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg"></a>
-  &nbsp;
-  <a href="https://docs.oracle.org/en/java/21/"><img src="https://img.shields.io/badge/Java-%3D21-green.svg"></a>
-  &nbsp;
-  <a href="https://docs.oracle.org/en/java/17/"><img src="https://img.shields.io/badge/Java-%3D17-green.svg"></a>
-  &nbsp;
-  <a href="https://api.reuse.software/info/github.com/ArcadeData/arcadedb"><img src="https://api.reuse.software/badge/github.com/ArcadeData/arcadedb"></a>
-  &nbsp;
-  <a href="https://maven-badges.herokuapp.com/maven-central/com.arcadedb/arcadedb-parent"><img src="https://maven-badges.herokuapp.com/maven-central/com.arcadedb/arcadedb-parent/badge.svg"></a>
-  &nbsp;
-  <a href="https://hub.docker.com/repository/docker/arcadedata/arcadedb/general"><img src="https://img.shields.io/docker/pulls/arcadedata/arcadedb"></a>
-  <a href="https://deepwiki.com/ArcadeData/arcadedb"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/ArcadeData/arcadedb/actions/workflows/mvn-deploy.yml"><img src="https://github.com/ArcadeData/arcadedb/actions/workflows/mvn-deploy.yml/badge.svg"></a>
-  &nbsp;
-  <a href="https://www.codacy.com/gh/ArcadeData/arcadedb/dashboard?utm_source=github.com&utm_medium=referral&utm_content=ArcadeData/arcadedb&utm_campaign=Badge_Coverage"><img src="https://app.codacy.com/project/badge/Coverage/1f971260db1e46638bd3fd91e3ebf668"></a>
-  &nbsp;
-  <a href="https://app.codacy.com/gh/ArcadeData/arcadedb?utm_source=github.com&utm_medium=referral&utm_content=ArcadeData/arcadedb&utm_campaign=Badge_Grade_Settings"><img src="https://api.codacy.com/project/badge/Grade/d40cc721f39b49eb81408307960f145b"></a>
-  &nbsp;
-  <a href="https://www.meterian.io/report/gh/ArcadeData/arcadedb"><img src="https://www.meterian.io/badge/gh/ArcadeData/arcadedb/security?branch=main"></a>
-  &nbsp;
-  <a href="https://www.meterian.io/report/gh/ArcadeData/arcadedb"><img src="https://www.meterian.io/badge/gh/ArcadeData/arcadedb/stability?branch=main"></a>
-</p>
-
-<p align="center">
-  <a href="https://discord.gg/w2Npx2B7hZ"><img width="208" height="97" src="https://arcadedb.com/assets/images/discord_button.png" alt="Join Discord"></a>
-</p>
-
-<p align="center">
-	<a href="https://github.com/arcadedata/arcadedb"><img height="25" src="studio/src/main/resources/static/images/social/github.svg" alt="Github"></a>
-	&nbsp;
-  <a href="https://www.linkedin.com/company/arcadedb/"><img height="25" src="studio/src/main/resources/static/images/social/linkedin.svg" alt="LinkedIn"></a>
-  &nbsp;
-  <a href="https://bsky.app/profile/arcadedb.bsky.social"><img height="25" src="studio/src/main/resources/static/images/social/bluesky.svg" alt="Bluesky"></a>
-  &nbsp;
-  <a href="https://twitter.com/arcade_db"><img height="25" src="studio/src/main/resources/static/images/social/twitter.svg" alt="Twitter"></a>
-  &nbsp;
-  <a href="https://www.youtube.com/@ArcadeDB"><img height="25" src="studio/src/main/resources/static/images/social/youtube.svg" alt="Youtube"></a>
-  &nbsp;
-  <a href="https://discord.gg/w2Npx2B7hZ"><img height="25" src="studio/src/main/resources/static/images/social/discord.svg" alt="Discord"></a>
-  &nbsp;
-  <a href="https://stackoverflow.com/questions/tagged/arcadedb"><img height="25" src="studio/src/main/resources/static/images/social/stack-overflow.svg" alt="StackOverflow"></a>
-	&nbsp;
-	<a href="https://blog.arcadedb.com/"><img height="25" src="studio/src/main/resources/static/images/social/blog.svg" alt="Blog"></a>
-</p>
-
-ArcadeDB is a Multi-Model DBMS (created originally as a fork
-from [OrientDB Open Source project](https://github.com/orientechnologies/orientdb) after the acquisition by SAP) with a brand-new
-engine made of Alien Technology, able to crunch millions of records per second on common hardware with the usage of
-minimal resources. ArcadeDB is written in LLJ: Low Level Java. It's still Java21+ but only using low level API to use advanced
-mechanical sympathy techniques and a reduced pressure of the Garbage Collector. It's highly optimized for extreme performance. Runs
-from a Raspberry Pi to multiple servers on the cloud.
-
-ArcadeDB is fully transactional DBMS with support for ACID transactions, structured and unstructured data, native graph engine (no
-joins but links between records), full-text indexing, geospatial querying, and advanced security.
-
-ArcadeDB supports the following models:
-
-- [Graph Database](https://docs.arcadedb.com#Graph-Model) (compatible with Neo4j Cypher, Apache Tinkerpop Gremlin and OrientDB SQL)
-- [Document Database](https://docs.arcadedb.com#Document-Model) (compatible with the MongoDB driver + MongoDB queries and OrientDB
-  SQL)
-- [Key/Value](https://docs.arcadedb.com#KeyValue-Model) (compatible with the Redis driver)
-- [Search Engine](https://docs.arcadedb.com/#SearchEngine-Model)
-- [Time Series](https://docs.arcadedb.com#TimeSeries-Model)
-- [Vector Embedding](https://docs.arcadedb.com/#VectorEmbedding-Model)
-
-ArcadeDB understands multiple languages:
-
-- [SQL](https://docs.arcadedb.com#SQL) (from OrientDB SQL)
-- Neo4j [Cypher (Open Cypher)](https://docs.arcadedb.com#Cypher)
-- [Apache Gremlin (Apache Tinkerpop v3.7.x)](https://docs.arcadedb.com#Gremlin-API)
-- [GraphQL Language](https://docs.arcadedb.com#GraphQL)
-- [MongoDB Query Language](https://docs.arcadedb.com#MongoDB-API)
-
-ArcadeDB can be used as:
-
-- Embedded from any language on top of the Java Virtual Machine
-- Remotely by using [HTTP/JSON](https://docs.arcadedb.com#HTTP-API)
-- Remotely by using a [Postgres driver](https://docs.arcadedb.com#Postgres-Driver) (ArcadeDB implements Postgres Wire protocol)
-- Remotely by using a [Redis driver](https://docs.arcadedb.com#Redis-API) (only a subset of the operations are implemented)
-- Remotely by using a [MongoDB driver](https://docs.arcadedb.com#MongoDB-API) (only a subset of the operations are implemented)
-
-For more information, see the [documentation](https://docs.arcadedb.com).
-
-### Getting started in 5 minutes
-
-Start ArcadeDB Server with Docker:
+# ArcadeDB Python Bindings
 
-```
-docker run --rm -p 2480:2480 -p 2424:2424 \
-           -e JAVA_OPTS="-Darcadedb.server.rootPassword=playwithdata -Darcadedb.server.defaultDatabases=Imported[root]{import:https://github.com/ArcadeData/arcadedb-datasets/raw/main/orientdb/OpenBeer.gz}" \
-           arcadedata/arcadedb:latest
-```
+> **Python bindings for [ArcadeDB](https://github.com/ArcadeData/arcadedb)** - A multi-model database supporting Graph, Document, Key/Value, Vector, and Time Series models with extreme performance.
 
-Now open your browser on http://localhost:2480 and play with [ArcadeDB Studio](https://docs.arcadedb.com/#_studio) and the
-imported `OpenBeer` database to find your favorite beer.
+[![PyPI - Headless](https://img.shields.io/badge/PyPI-headless-blue)](https://pypi.org/project/arcadedb-embedded-headless/)
+[![PyPI - Minimal](https://img.shields.io/badge/PyPI-minimal-blue)](https://pypi.org/project/arcadedb-embedded-minimal/)
+[![PyPI - Full](https://img.shields.io/badge/PyPI-full-blue)](https://pypi.org/project/arcadedb-embedded/)
+[![Tests](https://img.shields.io/badge/tests-44%2F44%20passing-brightgreen)](https://github.com/humemai/arcadedb-embedded-python/actions)
+[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
 
-![ArcadeDB Studio](https://arcadedb.com/assets/images/openbeer-demo-graph.png)
+**📖 [Documentation](https://humemai.github.io/arcadedb-embedded-python/) | 🐛 [Issues](https://github.com/humemai/arcadedb-embedded-python/issues)**
 
-ArcadeDB is cloud-ready with [Docker](https://docs.arcadedb.com/#Docker) and [Kubernetes](https://docs.arcadedb.com/#Kubernetes) support.
+---
 
-You can also [download the latest release](https://github.com/ArcadeData/arcadedb/releases), unpack it on your local hard drive and start the server with `bin/server.sh` or `bin/server.bat` for Windows.
+## Quick Start
 
-### Releases
+### Installation
+
+```bash
+pip install arcadedb-embedded-headless  # Recommended for production
+pip install arcadedb-embedded-minimal   # With Studio UI for development
+pip install arcadedb-embedded           # With Gremlin + GraphQL
+```
 
-There are three variants of (about monthly) releases:
+**Requirements:** Python 3.8+ and [Java 21+](https://adoptium.net/) (JRE)
 
-- `full` - this is the complete package of including all modules
-- `minimal` - this package excludes the `gremlin`, `redisw`, `mongodbw`, `graphql` modules
-- `headless` - this package excludes the `gremlin`, `redisw`, `mongodbw`, `graphql`, `studio` modules
+**Technology:** Uses [JPype](https://jpype.readthedocs.io/) to bridge Python and Java, providing direct access to ArcadeDB's embedded engine with minimal overhead.
 
-The nightly builds of the repository head can be found [here](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/com/arcadedb/arcadedb-package/).
+### Basic Usage (CRUD)
 
-### Java Versions
+```python
+import arcadedb_embedded as arcadedb
 
-Starting from ArcadeDB 24.4.1 code is compatible with Java 21.
+# Create database
+with arcadedb.create_database("/tmp/mydb") as db:
 
-Java 21 packages are available on [Maven central](https://repo.maven.apache.org/maven2/com/arcadedb/) and docker images on [Docker Hub](https://hub.docker.com/r/arcadedata/arcadedb).
+    # CREATE: Define schema
+    db.command("sql", "CREATE DOCUMENT TYPE Person")
 
-We also support Java 17 on a separate branch `java17` for those who cannot upgrade to Java 21 yet through GitHub packages.
+    # CREATE: Insert data (requires transaction)
+    with db.transaction():
+        db.command("sql", """
+            INSERT INTO Person SET name = 'Alice', age = 30, city = 'NYC'
+        """)
+        db.command("sql", """
+            INSERT INTO Person SET name = 'Bob', age = 25, city = 'LA'
+        """)
 
-To use Java 17 inside your project, add the repository to your `pom.xml` and reference dependencies as follows:
+    # READ: Query data
+    result = db.query("sql", "SELECT FROM Person WHERE age > 20")
+    for record in result:
+        print(f"{record.get_property('name')} - {record.get_property('age')}")
 
-```xml
-    <repositories>
-        <repository>
-            <name>github</name>
-            <id>github</id>
-            <url>https://maven.pkg.github.com/ArcadeData/arcadedb</url>
-        </repository>
-    </repositories>
-    <dependencies>
-      <dependency>
-          <groupId>com.arcadedb</groupId>
-          <artifactId>arcadedb-engine</artifactId>
-          <version>25.5.1-java17</version>
-      </dependency>
-    </dependencies>
+    # UPDATE: Modify records
+    with db.transaction():
+        db.command("sql", "UPDATE Person SET age = 31 WHERE name = 'Alice'")
+
+    # DELETE: Remove records
+    with db.transaction():
+        db.command("sql", "DELETE FROM Person WHERE name = 'Bob'")
 ```
 
-Docker images are available on ghcr.io too:
+### Graph Example
+
+```python
+# Create graph schema
+db.command("sql", "CREATE VERTEX TYPE User")
+db.command("sql", "CREATE EDGE TYPE Follows")
+
+# Insert vertices and edges
+with db.transaction():
+    db.command("sql", "CREATE VERTEX User SET name = 'Alice'")
+    db.command("sql", "CREATE VERTEX User SET name = 'Bob'")
+    db.command("sql", """
+        CREATE EDGE Follows
+        FROM (SELECT FROM User WHERE name = 'Alice')
+        TO (SELECT FROM User WHERE name = 'Bob')
+    """)
+
+# Query graph
+result = db.query("sql", """
+    SELECT expand(out('Follows')) FROM User WHERE name = 'Alice'
+""")
+```
 
-```shell
-docker pull ghcr.io/arcadedata/arcadedb:25.5.1-java17
+### Vector Search Example
+
+```python
+# Create vector index
+db.command("sql", "CREATE VERTEX TYPE Document")
+db.command("sql", """
+    CREATE PROPERTY Document.embedding ARRAY OF DOUBLE
+""")
+db.command("sql", """
+    CREATE VECTOR INDEX Document_embedding
+    ON Document(embedding)
+    HNSW M 16, EF_CONSTRUCTION 128
+""")
+
+# Insert vectors
+with db.transaction():
+    db.command("sql", """
+        CREATE VERTEX Document
+        SET text = 'Hello world', embedding = [0.1, 0.2, 0.3]
+    """)
+
+# Search by vector similarity
+result = db.query("sql", """
+    SELECT FROM Document
+    ORDER BY embedding <-> [0.1, 0.2, 0.4]
+    LIMIT 5
+""")
 ```
 
-### Community
+**📚 [More Examples](https://humemai.github.io/arcadedb-embedded-python/latest/examples/) | [Full Tutorial](https://humemai.github.io/arcadedb-embedded-python/latest/getting-started/quickstart/)**
 
-Join our growing community around the world, for ideas, discussions and help regarding ArcadeDB.
+---
 
-- Chat live with us on [Discord](https://discord.gg/w2Npx2B7hZ)
-- Follow us on [Twitter](https://twitter.com/arcade_db)
-- or on [Bluesky](https://bsky.app/profile/arcadedb.bsky.social)
-- Connect with us on [LinkedIn](https://www.linkedin.com/products/arcadedb)
-- or on [Facebook](https://www.facebook.com/arcadedb)
-- Questions tagged `#arcadedb` on [Stack Overflow](https://stackoverflow.com/questions/tagged/arcadedb)
-- View our official [Blog](https://blog.arcadedb.com/)
+## Features
 
-### Security
+✅ **Embedded Mode** - Runs in your Python process (no server needed)
+✅ **Multi-Model** - Graph, Document, Key/Value, Vector, Time Series
+✅ **Query Languages** - SQL, Cypher, Gremlin (full distribution), MongoDB
+✅ **ACID Transactions** - Full transactional support
+✅ **Vector Search** - HNSW indexing for embeddings
+✅ **Self-Contained** - All JARs bundled, no external dependencies
+✅ **Production Ready** - 44/44 tests passing, actively maintained
 
-For security issues kindly email us at support@arcadedb.com instead of posting a public issue on GitHub.
+---
 
-### License
+## Distribution Comparison
 
-ArcadeDB is Free for any usage and licensed under the liberal [Open Source Apache 2 license](LICENSE). If you need commercial
-support, or you need to have an issue fixed ASAP, check our [GitHub Sponsor page](https://github.com/sponsors/ArcadeData) on both
-Recurrent and One-Time tiers. All the sponsorship received will be distributed to the active contributors of this project.
+| Distribution | Size | Studio UI | Gremlin | Use Case |
+|-------------|------|-----------|---------|----------|
+| **Headless** | ~94MB | ❌ | ❌ | Production, CI/CD |
+| **Minimal** | ~97MB | ✅ | ❌ | Development with UI |
+| **Full** | ~158MB | ✅ | ✅ | All features |
 
-### Thanks To
+All distributions use the same import: `import arcadedb_embedded as arcadedb`
 
-<a href="https://www.yourkit.com"><img src="https://www.yourkit.com/images/yklogo.png"></a> for providing YourKit Profiler to our committers.
+---
+
+## About ArcadeDB
+
+**[ArcadeDB](https://github.com/ArcadeData/arcadedb)** is a high-performance multi-model database that supports:
+
+- **Data Models:** Graph, Document, Key/Value, Vector, Time Series
+- **Query Languages:** SQL, Cypher, Gremlin, MongoDB, GraphQL
+- **Architecture:** ACID transactions, native graph engine, full-text search
+- **Performance:** Millions of records/second with minimal resources
 
-### Contributing
+This fork provides **embedded Python bindings** using JPype to bridge Python and the Java-based ArcadeDB engine.
 
-We would love for you to get involved with ArcadeDB project.
-If you wish to help, you can learn more about how you can contribute to this project in the [contribution guide](CONTRIBUTING.md).
+**Main ArcadeDB Resources:**
+- 📖 [Official Documentation](https://docs.arcadedb.com)
+- 🐳 [Docker Images](https://hub.docker.com/r/arcadedata/arcadedb)
+- 💬 [Community Discord](https://discord.gg/w2Npx2B7hZ)
+- 🔧 [Upstream Repository](https://github.com/ArcadeData/arcadedb)
 
-Have fun with data!
+---
+
+## Contributing
 
-The ArcadeDB Team
+**Python Bindings:** Issues and PRs welcome at [this repository](https://github.com/humemai/arcadedb-embedded-python/issues)
+**Main ArcadeDB:** Contribute to the [upstream project](https://github.com/ArcadeData/arcadedb)
 
 ---
 
-#### TL;DR: [ArcadeDB](https://arcadedb.com) is an open-source multi-model NoSQL database systems.
+## License
+
+Apache License 2.0 - See [LICENSE](LICENSE)
+
+Built on [ArcadeDB](https://arcadedb.com) | Python bindings by [HumemAI](https://github.com/humemai)