docs(python): embedded bindings page and quickstart connection options

scripts/generate-nav.py

@@ -95,6 +95,7 @@
                 # The group labels carry no URL because there is no per-language
                 # landing page to point them at (Java has one; Python, JS and Go do not).
                 ("Python", [
+                    ("how-to/connectivity/python-embedded.adoc", "Embedded bindings"),
                     ("how-to/connectivity/drivers/python-http.adoc", "Native driver — HTTP"),
                     ("how-to/connectivity/drivers/python-grpc.adoc", "Native driver — gRPC"),
                     ("tutorials/python-quickstart.adoc", "PostgreSQL protocol"),

src/main/asciidoc/how-to/connectivity/python-embedded.adoc

@@ -0,0 +1,104 @@
+[[python-embedded]]
+==== Python -- Embedded Bindings
+
+`arcadedb-embedded` runs the ArcadeDB engine inside your Python process. Calls cross into the engine through https://jpype.readthedocs.io/[JPype], so there is no network hop and no server to start. The wheel bundles its own Java runtime: you do not install Java.
+
+The bindings live in the https://github.com/ArcadeData/arcadedb-python[ArcadeData/arcadedb-python] repository. This page covers the first steps; the repository holds the full guides and the API reference.
+
+===== Install
+
+[source,shell]
+----
+pip install arcadedb-embedded
+----
+
+Or with https://docs.astral.sh/uv/[uv]:
+
+[source,shell]
+----
+uv add arcadedb-embedded
+----
+
+Python 3.11 to 3.14 is what the wheels' CI runs. Wheels exist for Linux (x86_64 and ARM64), macOS on Apple Silicon, and Windows (x86_64).
+
+There is a second package, `arcadedb-embedded-native`, which is a *preview*. It is the same engine built as a GraalVM native-image library: no JVM and no JPype. It installs beside `arcadedb-embedded`. Both builds are published for now, with the JVM build as the default. The plan is to converge on the native build once it matches the JVM build on the workloads that matter; then one package, `arcadedb`, will ship the native build only. Check the preview's PyPI page for its current status before you rely on it.
+
+===== Open a database and query it
+
+[source,python]
+----
+import arcadedb_embedded as arcadedb
+
+with arcadedb.create_database("./mydb") as db:
+    db.command("sql", "CREATE VERTEX TYPE Person")
+    db.command("sql", "CREATE PROPERTY Person.name STRING")
+    db.command("sql", "CREATE PROPERTY Person.age INTEGER")
+
+    with db.transaction():
+        db.command("sql", "INSERT INTO Person SET name = ?, age = ?", "Alice", 30)
+        db.command("sql", "INSERT INTO Person SET name = ?, age = ?", "Bob", 25)
+
+    for row in db.query("sql", "SELECT name, age FROM Person WHERE age > ?", 26):
+        print(row.get("name"), row.get("age"))
+----
+
+[source,text]
+----
+Alice 30
+----
+
+Reopen the same directory later with `arcadedb.open_database("./mydb")`. `create_database` raises if the path already holds a database. Pass `read_only=True` to `open_database` to refuse writes.
+
+Queries in other languages use the same two calls, for example openCypher:
+
+[source,python]
+----
+with arcadedb.open_database("./mydb") as db:
+    for row in db.query("opencypher", "MATCH (p:Person) RETURN p.name AS name ORDER BY name"):
+        print(row.get("name"))
+----
+
+[source,text]
+----
+Alice
+Bob
+----
+
+TIP: Schema, inserts and graph work are best written as SQL or openCypher through `db.command(...)` and `db.query(...)`. The bindings also expose wrapper objects for the rest of the Java API; the repository documents them.
+
+NOTE: *Writes need a transaction.* `INSERT`, `UPDATE` and `DELETE` go inside `with db.transaction():`. Schema statements apply immediately.
+
+===== Pick the embedded bindings or the HTTP driver
+
+[cols="1,2,2"]
+|===
+| | Embedded bindings | HTTP driver (`arcadedb-driver`)
+
+| Where the engine runs
+| In your Python process
+| In a separate ArcadeDB server
+
+| Who can reach the data
+| One process at a time: the database directory is locked while it is open
+| Any number of clients, local or remote
+
+| Network round trip
+| None
+| One per call
+
+| Setup
+| `pip install arcadedb-embedded`
+| A running server, plus `pip install arcadedb-driver`
+|===
+
+Choose the embedded bindings for a single script, a notebook, or an application with one Python process that owns its data. Several threads of one process can share a database.
+
+Choose the xref:how-to/connectivity/drivers/python-http.adoc[HTTP driver] when more than one process, another language, or a remote machine must reach the same database, or when the server must outlive your Python process.
+
+The two meet in one case. The bindings can start an in-process HTTP server (`arcadedb.create_server(...)`), so the process that owns the database keeps direct access while other clients connect over HTTP. That server lives and dies with your Python process. For a long-running service, run the regular ArcadeDB server instead.
+
+===== Where to go next
+
+* https://github.com/ArcadeData/arcadedb-python[Bindings repository] -- guides for vectors, graphs, time series, import and server mode, plus the API reference and examples.
+* xref:how-to/connectivity/drivers/native-drivers.adoc[Native drivers] -- the HTTP and gRPC clients, if you would rather talk to a server.
+* xref:tutorials/python-quickstart.adoc[Python quickstart] -- the PostgreSQL wire protocol route.

src/main/asciidoc/languages-drivers.adoc

@@ -22,7 +22,7 @@
   <a class="logo-card" href="how-to/connectivity/drivers/native-drivers.html">
     <img src="https://cdn.simpleicons.org/python/3776AB" alt="Python" loading="lazy">
     <h3>Python</h3>
-    <p>arcadedb-driver (HTTP &amp; gRPC), psycopg, neo4j, httpx.</p>
+    <p>arcadedb-driver (HTTP &amp; gRPC), embedded bindings, psycopg, neo4j, httpx.</p>
   </a>
   <a class="logo-card" href="how-to/connectivity/drivers/native-drivers.html">
     <img src="https://cdn.simpleicons.org/javascript/F7DF1E" alt="JavaScript" loading="lazy">
@@ -76,3 +76,5 @@
   </a>
 </div>
 ++++
+
+Running Python in the same process as the database? See xref:how-to/connectivity/python-embedded.adoc[Python -- Embedded Bindings].

src/main/asciidoc/tutorials/python-quickstart.adoc

@@ -12,6 +12,7 @@ ArcadeDB exposes multiple wire protocols, so you can pick the one your stack alr
 * xref:how-to/connectivity/drivers/python-grpc.adoc[*Native gRPC driver*] -- `pip install arcadedb-driver-grpc`, for streaming and bulk inserts.
 * xref:how-to/connectivity/bolt.adoc#python-example[*Neo4j BOLT*] -- `pip install neo4j`, run Cypher queries.
 * xref:reference/http-api/http.adoc[*HTTP/JSON API*] -- use `requests` or `httpx`, no driver required.
+* xref:how-to/connectivity/python-embedded.adoc[*Embedded bindings*] -- `pip install arcadedb-embedded`, runs the engine inside your Python process with no server. A native-image build, `arcadedb-embedded-native`, is in preview.
 
 This tutorial uses the PostgreSQL wire protocol, which is the right choice when you already run a PostgreSQL stack.
 ====
@@ -207,7 +208,7 @@ See the xref:reference/http-api/http.adoc[HTTP/JSON API reference] for every end
 
 ==== Embedded Python Bindings
 
-For high-performance use cases that need in-process access (no network overhead), see the https://github.com/humemai/arcadedb-embedded-python[arcadedb-embedded-python] project, which provides direct JVM bindings via JPype.
+For use cases that need in-process access (no network overhead), see xref:how-to/connectivity/python-embedded.adoc[Python -- Embedded Bindings]. They run the engine inside your Python process through JPype.
 
 ==== Next Steps