Enhance Python bindings documentation and tests

- Updated mkdocs.yml to improve navigation structure and added examples section.
- Revised README.md in tests to reflect updated test counts and results.
- Introduced comprehensive tests for rich data types and SQL features in test_core.py.
- Enhanced test_server_patterns.py with realistic CRUD operations benchmark and performance comparison between HTTP and Java APIs.

Author: tae898

bindings/python/README.md

@@ -2,7 +2,7 @@
 
 Native Python bindings for ArcadeDB - the multi-model database that supports Graph, Document, Key/Value, Search Engine, Time Series, and Vector models.
 
-**Status**: ✅ Production Ready | **Tests**: 42/42 Passing (100%)
+**Status**: ✅ Production Ready | **Tests**: 44/44 Passing (100%)
 
 ---
 
@@ -37,7 +37,7 @@ pip install arcadedb-embedded-minimal
 pip install arcadedb-embedded
 ```
 
-**Requirements**: Java 11+ must be installed ([details](https://humemai.github.io/arcadedb/latest/getting-started/installation/#java-runtime-environment-jre))
+**Requirements**: Java 21+ must be installed ([details](https://humemai.github.io/arcadedb/latest/getting-started/installation/#java-runtime-environment-jre))
 
 ### 5-Minute Example
 
@@ -95,7 +95,7 @@ All use the same import: `import arcadedb_embedded as arcadedb`
 
 ## 🧪 Testing
 
-**Status**: 42/42 tests passing (100%)
+**Status**: 44/44 tests passing (100%)
 
 ```bash
 # Run all tests

bindings/python/docs/development/contributing.md

@@ -29,7 +29,7 @@ pytest tests/
 **Required:**
 
 - Python 3.8+
-- Java 11+ (JDK or JRE)
+- Java 21+ (JDK or JRE)
 - Docker (for building distributions)
 - Git
 
@@ -78,7 +78,7 @@ pip install pytest pytest-cov black isort mypy numpy
 python --version  # Should be 3.8+
 
 # Check Java
-java -version     # Should be 11+
+java -version     # Should be 21+
 
 # Run quick test
 python -c "import arcadedb_embedded; print('✅ Setup successful!')"
@@ -776,10 +776,10 @@ dependencies = [
 
 ```bash
 # Check Java version
-java -version  # Must be 11+
+java -version  # Must be 21+
 
 # Set JAVA_HOME
-export JAVA_HOME=/path/to/jdk-11
+export JAVA_HOME=/path/to/jdk-21
 ```
 
 ### Build Errors

bindings/python/docs/development/release.md

@@ -30,13 +30,13 @@ cd bindings/python
 
 # Test each distribution
 pip install dist/arcadedb_embedded_headless-*.whl
-pytest  # 35 passed, 7 skipped
+pytest  # 37 passed, 7 skipped
 
 pip install --force-reinstall dist/arcadedb_embedded_minimal-*.whl
-pytest  # 39 passed, 3 skipped
+pytest  # 41 passed, 3 skipped
 
 pip install --force-reinstall dist/arcadedb_embedded_full-*.whl
-pytest  # 42 passed, 0 skipped
+pytest  # 44 passed, 0 skipped
 ```
 
 **Note**: Version is automatically extracted from `pom.xml` by `extract_version.py` during build. The `-SNAPSHOT` suffix is converted to `.dev0` for PEP 440 compliance.
@@ -73,9 +73,9 @@ Instead of pushing tags manually, create a GitHub Release which automatically cr
 
    ## Test Results
 
-   - Headless: 35/42 passed (7 skipped)
-   - Minimal: 39/42 passed (3 skipped)
-   - Full: 42/42 passed
+   - Headless: 37/44 passed (7 skipped)
+   - Minimal: 41/44 passed (3 skipped)
+   - Full: 44/44 passed
    ```
 
 6. Click **Publish release** (or **Save as draft** to test first)
@@ -114,9 +114,9 @@ https://humemai.github.io/arcadedb/
 
 ## Test Results
 
-- Headless: 35/42 passed
-- Minimal: 39/42 passed
-- Full: 42/42 passed"
+- Headless: 37/44 passed
+- Minimal: 41/44 passed
+- Full: 44/44 passed
 
 **What happens automatically:**
 
@@ -347,7 +347,7 @@ mike set-default 25.9.0 --push
 
 - Run specific test: `pytest tests/test_core.py::test_name -v`
 - Check logs in `bindings/python/log/`
-- Verify Java JDK 11+ is available
+- Verify Java JDK 21+ is available
 
 ## Automation Improvements
 

bindings/python/docs/development/testing.md

@@ -3,11 +3,11 @@
 Comprehensive testing documentation for ArcadeDB Python bindings.
 
 !!! success "Test Coverage"
-    **42 tests** across 6 test files, 100% passing
+    **44 tests** across 6 test files, 100% passing
 
-    - **Headless**: 35 passed, 7 skipped
-    - **Minimal**: 39 passed, 3 skipped
-    - **Full**: 42 passed, 0 skipped
+    - **Headless**: 37 passed, 7 skipped
+    - **Minimal**: 41 passed, 3 skipped
+    - **Full**: 44 passed, 0 skipped
 
 ## Quick Navigation
 

bindings/python/docs/development/testing/overview.md

@@ -5,11 +5,11 @@ The ArcadeDB Python bindings have a comprehensive test suite covering all major
 ## Quick Statistics
 
 !!! success "Test Results by Distribution"
-    - **Headless**: ✅ 35 passed, 7 skipped (Cypher, Gremlin, Server tests)
-    - **Minimal**: ✅ 39 passed, 3 skipped (Cypher, Gremlin tests)
-    - **Full**: ✅ 42 passed, 0 skipped (all features available)
+    - **Headless**: ✅ 37 passed, 7 skipped (Cypher, Gremlin, Server tests)
+    - **Minimal**: ✅ 41 passed, 3 skipped (Cypher, Gremlin tests)
+    - **Full**: ✅ 44 passed, 0 skipped (all features available)
 
-    **Total: 42 tests** across 6 test files, 100% passing
+    **Total: 44 tests** across 6 test files, 100% passing
 
 ## What's Tested
 
@@ -144,13 +144,13 @@ pytest -m "not slow"
 When all tests pass, you should see:
 
 ```
-======================== 42 passed in 9.67s =========================
+======================== 44 passed in 9.67s =========================
 ```
 
 With some distributions, you may see skipped tests:
 
 ```
-================== 39 passed, 3 skipped in 8.50s ===================
+================== 41 passed, 3 skipped in 8.50s ===================
 ```
 
 This is normal! Tests are skipped when features aren't available in your distribution.

bindings/python/docs/development/testing/test-core.md

@@ -315,11 +315,74 @@ import arcadedb_embedded as arcadedb
 
 with arcadedb.create_database("./test_db") as db:
     # Create document type with vector property
-    db.command("sql", "CREATE DOCUMENT TYPE Document")
-    db.command("sql", "CREATE PROPERTY Document.embedding EMBEDDING DOUBLE[3]")
+    db.command("sql", "CREATE VERTEX TYPE Document")
+    db.command("sql", "CREATE PROPERTY Document.name STRING")
+    db.command("sql", "CREATE PROPERTY Document.embedding ARRAY_OF_FLOATS")
 
     # Create HNSW index
-    db.command("sql", """
+    index = db.create_vector_index(
+        vertex_type="Document",
+        vector_property="embedding",
+        dimensions=3,
+        id_property="name",
+        distance_function="cosine",
+        m=16,
+        ef=128,
+        ef_construction=128,
+        max_items=100
+    )
+
+    # Insert documents with vectors
+    with db.transaction():
+        for i, vec in enumerate([[1.0, 0.0, 0.0], [0.9, 0.1, 0.0],
+                                  [0.0, 1.0, 0.0]]):
+            vertex = db.new_vertex("Document")
+            vertex.set("name", f"doc{i+1}")
+            vertex.set("embedding", arcadedb.to_java_float_array(vec))
+            vertex.save()
+            index.add_vertex(vertex)
+
+    # Search for nearest neighbors
+    query_vec = [1.0, 0.0, 0.0]
+    results = list(index.find_nearest(query_vec, k=2))
+
+    assert len(results) == 2
+    # Verify results ordered by distance
+    assert results[0][0].get_property("name") == "doc1"  # Exact match
+    assert results[1][0].get_property("name") == "doc2"  # Second closest
+```
+
+!!! note "Implementation Status"
+    Vector search is **experimental**. Current implementation uses jelmerk/hnswlib.
+    Future migration to datastax/jvector planned for better performance.
+
+**What it tests:**
+
+- EMBEDDING property type creation
+- HNSW index creation with parameters
+- Vector insertion (NumPy arrays or Python lists)
+- Cosine similarity search
+- Result ranking by similarity
+
+**Key findings:**
+
+- ✅ Index creation fast (~0.16s) - creates metadata only
+- ⚠️ Index population expensive (~13ms/doc) - builds HNSW graph + disk writes
+- ✅ Search efficient (logarithmic) - visits ~1,500-2,000 vertices, not all
+- ✅ Works with NumPy arrays and plain Python lists
+- ✅ Distance values correct (cosine distance = 1 - similarity, range [0,2])
+- ⚠️ No native filtered search - requires oversampling or multiple indexes
+
+**Performance characteristics** (10K documents, 384D):
+
+- Total storage: ~115 MB (24MB vertices + 91MB edges)
+- Index file: 4 KB (metadata only, graph stored as edges)
+- Per-document cost: ~13ms (HNSW algorithm + edge writes)
+- Search working set: ~4 MB (visited vertices, not entire dataset)
+
+See [Vector Search Example](../../examples/03_vector_search.md) for detailed documentation.
+
+---
         CREATE HNSW INDEX Document.embedding
         ON Document(embedding)
         WITH m=16, ef=128, efConstruction=128