docs: Update all READMEs with new FFI/Python methods

Author: varshith-Git

README.md

@@ -84,8 +84,10 @@ pip install .
 from valori import Valori
 
 client = Valori()
-client.insert([0.1] * 16)                 # Insert vector
-results = client.search([0.1] * 16, k=5)  # Search (returns exact match)
+# Atomic Batch Insert
+client.insert_batch([[0.1]*16, [0.2]*16]) 
+# Search
+results = client.search([0.1] * 16, k=5)
 ```
 
 **That's it.** Simple embedded mode. No Docker. No Kubernetes.

ffi/README.md

@@ -61,3 +61,26 @@ Creates a relationship between two nodes.
 ### `save() -> str`
 Saves a snapshot of the current in-memory state to disk.
 *   **Returns**: Path to the saved snapshot file.
+
+### `insert_batch(vectors: list[list[float]]) -> list[int]`
+Atomically insert multiple vectors.
+*   **vectors**: List of float lists.
+*   **Returns**: List of assigned Record IDs.
+
+### `get_metadata(record_id: int) -> bytes | None`
+Get metadata for a record.
+
+### `set_metadata(record_id: int, metadata: bytes)`
+Set metadata for a record.
+
+### `get_state_hash() -> str`
+Get the cryptographic state hash (BLAKE3) of the kernel. Used for verifiable crash recovery.
+
+### `record_count() -> int`
+Get the total number of records.
+
+### `restore(data: bytes)`
+Restore kernel state from snapshot bytes.
+
+### `soft_delete(record_id: int)`
+Mark a record as deleted (tombstone). Excludes it from search results.

python/README.md

@@ -81,23 +81,56 @@ client = Valori(remote="https://your-node.koyeb.app")
 
 ### Methods
 
-#### `insert(vector)`
-Raw insert. Returns integer Record ID.
+#### `insert(vector)` / `insert_batch(vectors)`
+Insert single or multiple vectors atomically.
 ```python
-rid = client.insert([0.1, 0.2, ...])
+# Single
+rid = client.insert([0.1, ...])
+
+# Batch (Atomic)
+vectors = [[0.1]*16, [0.2]*16, [0.3]*16]
+ids = client.insert_batch(vectors) # [0, 1, 2]
 ```
 
 #### `search(query, k)`
 Raw search. Returns IDs and scores.
 ```python
-hits = client.search([0.1, 0.2, ...], k=5)
+hits = client.search([0.1, ...], k=5)
 # [{'id': 10, 'score': 12345}, ...]
 ```
 
+#### `get_metadata(id)` / `set_metadata(id, data)`
+Read/Write metadata (for both HTTP and Local modes).
+```python
+client.set_metadata(10, b"user:123")
+meta = client.get_metadata(10)
+```
+
+#### `get_state_hash()`
+**Verifiable AI**: Get cryptographic proof of current database state.
+```python
+hash1 = client.get_state_hash()
+# 1a2b3c... (BLAKE3 hash)
+```
+
+#### `record_count()`
+Get total number of records.
+```python
+count = client.record_count()
+```
+
+#### `soft_delete(id)`
+Mark record as deleted (excluded from search).
+```python
+client.soft_delete(10)
+```
+
 #### `snapshot()` / `restore(data)`
 Backup and recovery.
 ```python
+# Save to bytes
 data = client.snapshot()
-with open("backup.snap", "wb") as f:
-    f.write(data)
+
+# Restore (Local mode only)
+client.restore(data)
 ```