docs: add JVM API documentation and update references in existing docs

Co-authored-by: Copilot <copilot@github.com>

Author: tae898

bindings/python/docs/api/jvm.md

@@ -0,0 +1,99 @@
+# JVM API
+
+Helpers for locating the bundled runtime and configuring the JVM before the first
+database or server is created.
+
+!!! warning "Configure once per process"
+    JVM options are locked after the JVM starts. Call `start_jvm(...)` before the
+    first `create_database(...)`, `open_database(...)`, or `create_server(...)`.
+
+## Overview
+
+The `arcadedb_embedded.jvm` module provides three public entry points:
+
+- `start_jvm(...)` to configure and start the bundled JVM explicitly
+- `shutdown_jvm()` to shut down a JVM started in the current process
+- runtime location helpers for jars and the bundled JRE library
+
+## start_jvm
+
+```python
+from arcadedb_embedded.jvm import start_jvm
+
+start_jvm(
+    heap_size="8g",
+    jvm_args="-XX:MaxDirectMemorySize=8g",
+    common_pool_parallelism=8,
+)
+```
+
+**Parameters:**
+
+- `heap_size` (`Optional[str]`): Maximum JVM heap, for example `"4g"` or `"4096m"`
+- `disable_xml_limits` (`bool`): If `True`, relaxes JDK XML entity limits for large XML imports
+- `jvm_args` (`Optional[Iterable[str] | str]`): Additional JVM flags as a string or iterable
+- `common_pool_parallelism` (`Optional[int]`): Explicit cap for `ForkJoinPool.common.parallelism`
+
+**Raises:**
+
+- `ArcadeDBError`: If the JVM is already started with a different configuration, the bundled runtime is missing, or JPype cannot start the JVM
+
+**Notes:**
+
+- The bundled JRE is always used; no external Java installation is required
+- The module injects required defaults such as `jdk.incubator.vector`, UTF-8 file encoding, and required `--add-opens` flags if they are not already provided
+- `ARCADEDB_JVM_ARGS` remains supported as an environment fallback, but in-code configuration is preferred
+
+## shutdown_jvm
+
+```python
+from arcadedb_embedded.jvm import shutdown_jvm
+
+shutdown_jvm()
+```
+
+Shuts down the JVM if it is running in the current process.
+
+!!! note
+    Most application code does not need to call this directly. Normal database and
+    server usage should focus on proper object cleanup; use this helper mainly in
+    test harnesses or short-lived tooling.
+
+## get_jar_path
+
+```python
+from arcadedb_embedded.jvm import get_jar_path
+
+jar_dir = get_jar_path()
+```
+
+Returns the directory containing the bundled ArcadeDB JAR files.
+
+## get_bundled_jre_lib_path
+
+```python
+from arcadedb_embedded.jvm import get_bundled_jre_lib_path
+
+jvm_lib = get_bundled_jre_lib_path()
+```
+
+Returns the platform-specific JVM library path inside the bundled runtime:
+
+- Linux: `lib/server/libjvm.so`
+- macOS: `lib/server/libjvm.dylib`
+- Windows: `bin/server/jvm.dll`
+
+Raises `ArcadeDBError` if the bundled runtime is missing or incomplete.
+
+## Recommended Pattern
+
+```python
+from arcadedb_embedded.jvm import start_jvm
+import arcadedb_embedded as arcadedb
+
+start_jvm(heap_size="8g", jvm_args="-XX:MaxDirectMemorySize=8g")
+
+with arcadedb.create_database("./db") as db:
+    row = db.query("sql", "SELECT 1 AS ok").one()
+    assert row.get("ok") == 1
+```

bindings/python/docs/api/record-wrappers.md

@@ -28,7 +28,7 @@ when you explicitly need the wrapper object in hand.
 
 ```python
 import arcadedb_embedded as arcadedb
-from arcadedb_embedded.graph import Document, Vertex, Edge
+from arcadedb_embedded import Document, Vertex, Edge
 
 with arcadedb.create_database("./mydb") as db:
     db.command("sql", "CREATE DOCUMENT TYPE Note")
@@ -186,7 +186,7 @@ with db.transaction():
 Static method to wrap Java objects as Python wrappers. Automatically detects type.
 
 ```python
-from arcadedb_embedded.graph import Document
+from arcadedb_embedded import Document
 
 # Wrap Java object and automatically detect type
 wrapped = Document.wrap(java_object)

bindings/python/docs/development/build-architecture.md

@@ -80,11 +80,11 @@ This simple class tells setuptools "this package has binary content" which:
 
 - Triggers platform-specific wheel naming
 - Makes uv pip download the correct wheel for each platform
-- Enables platform tags like `macosx_11_0_arm64`, `manylinux_2_17_x86_64`, etc.
+- Enables platform tags like `macosx_11_0_arm64`, `manylinux_2_34_x86_64`, etc.
 
 **Without setup.py**: All platforms → `arcadedb_embedded-X.Y.Z-py3-none-any.whl` (wrong!)
 
-**With setup.py**: Each platform → `arcadedb_embedded-X.Y.Z-py3-none-<platform>.whl` (correct!)
+**With setup.py**: Each platform → `arcadedb_embedded-X.Y.Z-cp<pyver>-cp<pyver>-<platform>.whl` (correct!)
 
 See `bindings/python/setup.py` for the complete implementation.
 

bindings/python/docs/development/troubleshooting.md

@@ -146,11 +146,12 @@ Configure JVM memory in Python **before the first database or server is created*
 
 ```python
 import arcadedb_embedded as arcadedb
+from arcadedb_embedded.jvm import start_jvm
 
 # Default: 4GB heap (no changes needed)
 
 # Production: 8GB heap with matching initial size
-arcadedb.start_jvm(heap_size="8g", jvm_args="-Xms8g")
+start_jvm(heap_size="8g", jvm_args="-Xms8g")
 ```
 
 **Common JVM Options:**
@@ -170,7 +171,9 @@ For applications using vector indexes, control memory usage:
 
 ```python
 # Conservative: bounded caches for large vector datasets
-arcadedb.start_jvm(
+from arcadedb_embedded.jvm import start_jvm
+
+start_jvm(
     heap_size="8g",
     jvm_args=(
         "-Xms8g -XX:MaxDirectMemorySize=8g "
@@ -214,13 +217,15 @@ Rule of thumb: Plan for 1.5-2× your heap size in actual RAM
 
 ```python
 # Small datasets (<1M records, <100K vectors)
-arcadedb.start_jvm(heap_size="2g", jvm_args="-Xms2g")
+from arcadedb_embedded.jvm import start_jvm
+
+start_jvm(heap_size="2g", jvm_args="-Xms2g")
 
 # Medium datasets (1M-10M records, 100K-1M vectors)
-arcadedb.start_jvm(heap_size="8g", jvm_args="-Xms8g -XX:MaxDirectMemorySize=8g")
+start_jvm(heap_size="8g", jvm_args="-Xms8g -XX:MaxDirectMemorySize=8g")
 
 # Large datasets (10M+ records, 1M+ vectors) with bounded caches
-arcadedb.start_jvm(
+start_jvm(
     heap_size="16g",
     jvm_args=(
         "-Xms16g -XX:MaxDirectMemorySize=16g "
@@ -231,7 +236,7 @@ arcadedb.start_jvm(
 )
 
 # High-dimensional vectors (e.g., 1536-dim embeddings)
-arcadedb.start_jvm(
+start_jvm(
     heap_size="8g",
     jvm_args=(
         "-Xms8g -XX:MaxDirectMemorySize=8g "
@@ -262,13 +267,16 @@ arcadedb.start_jvm(
 
 1. **Increase Heap (preferred)**:
     ```python
-    import arcadedb_embedded as arcadedb
-    arcadedb.start_jvm(heap_size="8g", jvm_args="-Xms8g")
+    from arcadedb_embedded.jvm import start_jvm
+
+    start_jvm(heap_size="8g", jvm_args="-Xms8g")
     ```
 
 2. **Bound Vector Caches** (for vector workloads):
     ```python
-    arcadedb.start_jvm(
+    from arcadedb_embedded.jvm import start_jvm
+
+    start_jvm(
         heap_size="8g",
         jvm_args=(
             "-Xms8g "

bindings/python/docs/examples/05_csv_import_graph.md

@@ -457,8 +457,9 @@ Prefer configuring heap inside the script before it creates the first database:
 
 ```python
 import arcadedb_embedded as arcadedb
+from arcadedb_embedded.jvm import start_jvm
 
-arcadedb.start_jvm(heap_size="8g", jvm_args="-Xms8g")
+start_jvm(heap_size="8g", jvm_args="-Xms8g")
 ```
 
 **Memory Planning:**

bindings/python/docs/getting-started/distributions.md

@@ -145,9 +145,9 @@ with arcadedb.create_database("./test") as db:
 uv pip automatically selects the correct platform-specific wheel:
 
 ```bash
-# On Linux x64, installs: arcadedb_embedded-X.Y.Z-py3-none-manylinux_2_17_x86_64.whl
-# On macOS ARM64, installs: arcadedb_embedded-X.Y.Z-py3-none-macosx_11_0_arm64.whl
-# On Windows x86_64, installs: arcadedb_embedded-X.Y.Z-py3-none-win_amd64.whl
+# On Linux x64 for Python 3.12, installs: arcadedb_embedded-X.Y.Z-cp312-cp312-manylinux_2_34_x86_64.whl
+# On macOS ARM64 for Python 3.12, installs: arcadedb_embedded-X.Y.Z-cp312-cp312-macosx_11_0_arm64.whl
+# On Windows x86_64 for Python 3.12, installs: arcadedb_embedded-X.Y.Z-cp312-cp312-win_amd64.whl
 # etc.
 ```
 

bindings/python/docs/getting-started/installation.md

@@ -87,7 +87,13 @@ Built wheels will be in `dist/`:
 
 ```text
 dist/
-└── arcadedb_embedded-X.Y.Z-py3-none-<platform>.whl
+└── arcadedb_embedded-X.Y.Z-cp<pyver>-cp<pyver>-<platform>.whl
+```
+
+For example, a Linux x86_64 build on Python 3.12 now looks like:
+
+```text
+arcadedb_embedded-X.Y.Z-cp312-cp312-manylinux_2_34_x86_64.whl
 ```
 
 Install locally:

bindings/python/docs/guide/core/database.md

@@ -485,9 +485,10 @@ with open_with_retry("./mydb") as db:
 ```python
 # JVM starts on first database creation
 import arcadedb_embedded as arcadedb
+from arcadedb_embedded.jvm import start_jvm
 
 # Optional: configure JVM before first database or server
-arcadedb.start_jvm(heap_size="8g")
+start_jvm(heap_size="8g")
 
 # JVM runs for entire Python process
 with arcadedb.create_database("./db1") as db1:

bindings/python/docs/guide/operations.md

@@ -108,10 +108,10 @@ ArcadeDB has **three distinct types of logs** stored in **two different location
 **Verbosity**: Controlled by Java system properties:
 
 ```python
-import arcadedb_embedded as arcadedb
+from arcadedb_embedded.jvm import start_jvm
 
 # Set before the first database or server is created
-arcadedb.start_jvm(jvm_args="-Djava.util.logging.level=DEBUG -Darcadedb.log.level=FINE")
+start_jvm(jvm_args="-Djava.util.logging.level=DEBUG -Darcadedb.log.level=FINE")
 ```
 
 ## Database Files (Embedded Mode)

bindings/python/mkdocs.yml

@@ -179,6 +179,7 @@ nav:
 - API Reference:
   - Database: api/database.md
   - GraphBatch: api/graph_batch.md
+  - JVM: api/jvm.md
   - Record Wrappers: api/record-wrappers.md
   - Results: api/results.md
   - Server: api/server.md