### Setup NamespacedKvStore and HashEmbedder

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/text_search.md

Initializes a temporary directory, sets up Git configuration, creates a NamespacedKvStore, and initializes a HashEmbedder for deterministic, ML-free embeddings. This is a prerequisite for the text search examples.

```python
import os, subprocess, tempfile
from prollytree import NamespacedKvStore, HashEmbedder

tmp = tempfile.mkdtemp()
subprocess.run(["git", "init"], cwd=tmp, check=True, capture_output=True)
subprocess.run(["git", "config", "user.name",  "You"],       cwd=tmp, check=True)
subprocess.run(["git", "config", "user.email", "you@x.com"], cwd=tmp, check=True)
dataset = os.path.join(tmp, "dataset"); os.makedirs(dataset)

store = NamespacedKvStore(dataset)
emb = HashEmbedder(dim=64, seed=0)        # deterministic, ML-free; swap for MiniLmEmbedder for real semantic search
```

--------------------------------

### Run All Examples

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/examples.md

This script executes all available examples for the prollytree project when run directly. Ensure all example functions are defined before execution.

```python
if __name__ == "__main__":
    # Run examples
    print("=== Basic Key-Value Store ===")
    example_basic_kv_store()

    print("\n=== Data Types ===")
    example_data_types()

    print("\n=== Document Versioning ===")
    example_document_versioning()

    print("\n=== SQL Analytics ===")
    example_sql_analytics()

    print("\n=== Branch Merging ===")
    example_merge_operations()

    print("\n=== Performance ===")
    example_batch_operations()
```

--------------------------------

### Run Basic ProllyTree Examples

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/index.md

Execute fundamental ProllyTree examples using cargo run. These examples cover core functionalities like proofs and versioning.

```bash
cargo run --example proof
```

```bash
cargo run --example versioning
```

--------------------------------

### Install git-prolly CLI

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/cli.md

Installs the git-prolly binary using Cargo and displays the help message.

```bash
cargo install prollytree --features git
git-prolly --help
```

--------------------------------

### Run ProllyTree Storage Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/index.md

Execute the storage example for ProllyTree, which requires the 'rocksdb_storage' feature to be enabled.

```bash
cargo run --example storage --features rocksdb_storage
```

--------------------------------

### Interactive SQL Shell Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Demonstrates creating a table, inserting data, and selecting from it within the interactive SQL shell.

```sql
prolly-sql> CREATE TABLE test (id INTEGER, value TEXT);
prolly-sql> INSERT INTO test VALUES (1, 'Hello'), (2, 'World');
prolly-sql> SELECT * FROM test;
prolly-sql> exit
```

--------------------------------

### Run ProllyTree SQL Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/index.md

Execute the SQL example for ProllyTree, which requires the 'sql' feature to be enabled.

```bash
cargo run --example sql --features sql
```

--------------------------------

### Quick Start SQL Operations

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Demonstrates creating a table, inserting data, querying, and committing changes using the SQL interface.

```bash
git-prolly sql "CREATE TABLE users (id INTEGER, name TEXT, email TEXT)"
```

```bash
git-prolly sql "INSERT INTO users VALUES (1, 'Alice', 'alice@example.com')"
```

```bash
git-prolly sql "SELECT * FROM users"
```

```bash
git-prolly commit -m "Added users table with initial data"
```

--------------------------------

### Configuration Management with ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/examples.md

Shows how to manage application configurations with versioning. This example includes setting up production and development configurations and updating them.

```python
def example_config_management():
    """Example of managing application configuration with versions"""
    store = VersionedKvStore("./config_store")

    # Production config
    prod_config = {
        "database": {
            "host": "prod-db.example.com",
            "port": 5432,
            "ssl": True
        },
        "api": {
            "rate_limit": 1000,
            "timeout": 30
        }
    }

    store.insert(b"config:production", json.dumps(prod_config).encode('utf-8'))
    store.commit("Initial production configuration")

    # Development config
    dev_config = prod_config.copy()
    dev_config["database"]["host"] = "localhost"
    dev_config["database"]["ssl"] = False
    dev_config["api"]["rate_limit"] = 10000  # Higher for dev

    store.insert(b"config:development", json.dumps(dev_config).encode('utf-8'))
    store.commit("Add development configuration")

    # Update production config
    prod_config["api"]["rate_limit"] = 2000  # Increase rate limit
    store.update(b"config:production", json.dumps(prod_config).encode('utf-8'))
    store.commit("Increase production rate limit")

    # Retrieve current configs
    current_prod = json.loads(store.get(b"config:production").decode('utf-8'))
    print(f"Production rate limit: {current_prod['api']['rate_limit']}")

    return store

```

--------------------------------

### Run ProllyTree Worktree Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/index.md

Execute the worktree example for ProllyTree, which requires the 'git' and 'sql' features to be enabled.

```bash
cargo run --example worktree --features "git sql"
```

--------------------------------

### Verify git-prolly CLI Installation

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Run the --help flag on the git-prolly binary to confirm that the CLI has been installed successfully.

```bash
git-prolly --help
```

--------------------------------

### Install and Import ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/text_search_demo.html

Install the prollytree library and import necessary components for creating a text index.

```python
pip install prollytree
from prollytree import NamespacedKvStore, MiniLmEmbedder
store.text_index_open("docs", "by_body", MiniLmEmbedder())
```

--------------------------------

### Serve MkDocs Site Locally

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Start a local development server for the documentation site using mkdocs serve. This enables live-reloading for easier previewing.

```bash
mkdocs serve
```

--------------------------------

### Build and Install ProllyTree from Source

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/index.md

Builds and installs ProllyTree from its source code, enabling all features. This method is an alternative to pip installation.

```bash
git clone https://github.com/zhangfengcdt/prollytree
cd prollytree
./python/build_python.sh --all-features --install
```

--------------------------------

### Build Python Bindings from Source with Maturin

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Build the Python bindings from source using maturin. This example shows how to build with the 'sql' feature enabled and install the package.

```bash
git clone https://github.com/zhangfengcdt/prollytree.git
cd prollytree
pip install maturin

# Build with the python + sql feature set
./python/build_python.sh --with-sql --install

# Or with every feature
./python/build_python.sh --all-features --install
```

--------------------------------

### Install Sphinx and Dependencies

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/README.md

Installs necessary packages for building Sphinx documentation, including the Read the Docs theme and Markdown parser.

```bash
pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints myst-parser maturin
```

--------------------------------

### Install Python Bindings with Pip

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Install the prollytree Python package from PyPI using pip. This is the simplest way to get the Python bindings.

```bash
pip install prollytree
```

--------------------------------

### Install git-prolly CLI with Cargo

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Install the git-prolly command-line interface directly from crates.io using cargo install. Ensure the 'git' feature is enabled.

```bash
cargo install prollytree --features git
```

--------------------------------

### Install MkDocs Dependencies

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Install the necessary Python packages for building the documentation site using pip, as listed in the docs/requirements.txt file.

```bash
pip install -r docs/requirements.txt
```

--------------------------------

### Branching and Merging Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/cli.md

Demonstrates creating a new branch, making changes, committing them, and then merging the branch back into main.

```bash
git checkout -b feature/darkmode
git-prolly set config:theme dark
git-prolly commit -m "Enable dark mode"

git checkout main
git-prolly merge feature/darkmode
```

--------------------------------

### Verify Python Bindings Installation

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Import the prollytree library in Python and print its version to verify that the Python bindings were installed correctly.

```python
import prollytree
print(prollytree.__version__)
```

--------------------------------

### Python TreeConfig Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/theory/rolling_hash.md

Shows how to instantiate ProllyTree with a custom TreeConfig in Python.

```python
from prollytree import ProllyTree, TreeConfig

config = TreeConfig(base=4, modulus=64)
tree = ProllyTree(config=config)
```

--------------------------------

### Serve MkDocs Site on Specific Port

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Start a local development server for the documentation site on a specific IP address and port using mkdocs serve -a.

```bash
mkdocs serve -a 0.0.0.0:8080
```

--------------------------------

### Building and Installing Python Bindings

Source: https://github.com/zhangfengcdt/prollytree/blob/main/CLAUDE.md

Use this script to build and install the Python bindings, especially when the 'python' feature is enabled. Raw 'cargo build --all-features' may fail to link PyO3.

```bash
./python/build_python.sh --all-features --install
python -m pytest python/tests/
```

--------------------------------

### Rust Merkle Tree Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/theory/merkle.md

Demonstrates creating, inserting into, and verifying a Merkle Tree using Rust. This snippet shows how to generate a proof for a specific key-value pair and verify it against the tree's root hash.

```rust
use prollytree::tree::{ProllyTree, Tree};
use prollytree::storage::InMemoryNodeStorage;

let mut tree = ProllyTree::new(InMemoryNodeStorage::<32>::new(), Default::default());
tree.insert(b"user:alice".to_vec(), b"Alice".to_vec());
tree.insert(b"user:bob".to_vec(),   b"Bob".to_vec());

let root = tree.root_hash();            // publish this
let proof = tree.generate_proof(b"user:alice");

// Verifier side: given only `root` and `proof`, check alice's value.
assert!(tree.verify(proof, b"user:alice", Some(b"Alice")));
```

--------------------------------

### Build ProllyTree Documentation

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/README.md

Executes a script to build both the Python bindings and the documentation. Alternatively, it can build only the documentation if the prollytree package is already installed.

```bash
# Build Python bindings and documentation
./build_docs.sh

# Or build documentation only (requires prollytree to be installed)
sphinx-build -b html . _build/html
```

--------------------------------

### In-Memory Node Storage Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/storage.md

Demonstrates how to initialize and use the InMemoryNodeStorage for ProllyTree. Data stored will be lost when the tree goes out of scope.

```rust
use prollytree::storage::InMemoryNodeStorage;
use prollytree::tree::{ProllyTree, Tree};
use prollytree::config::TreeConfig;

let storage = InMemoryNodeStorage::<32>::new();
let config = TreeConfig::<32>::default();
let mut tree = ProllyTree::new(storage, config);

// Data will be lost when `tree` goes out of scope
tree.insert(b"key".to_vec(), b"value".to_vec());

```

--------------------------------

### Python Example of Branch Merging and Conflict Resolution

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/examples.md

This comprehensive example demonstrates basic merge operations without conflicts, conflict detection, and various conflict resolution strategies using VersionedKvStore. It requires a Git repository to be initialized in the temporary directory.

```python
from prollytree import VersionedKvStore, ConflictResolution, MergeConflict
import tempfile
import os
import subprocess

def example_merge_operations():
    """Comprehensive example of branch merging with conflict resolution"""

    # Create temporary directory for the example
    with tempfile.TemporaryDirectory() as tmpdir:
        # Initialize git repository
        subprocess.run(['git', 'init'], cwd=tmpdir, check=True, capture_output=True)
        subprocess.run(['git', 'config', 'user.name', 'Example'], cwd=tmpdir, check=True, capture_output=True)
        subprocess.run(['git', 'config', 'user.email', 'example@test.com'], cwd=tmpdir, check=True, capture_output=True)

        # Create data subdirectory
        data_dir = os.path.join(tmpdir, 'data')
        os.makedirs(data_dir)

        store = VersionedKvStore(data_dir)

        print("=== Basic Merge Without Conflicts ===")

        # Initial data
        store.insert(b"users:alice", b"Alice Smith")
        store.insert(b"users:bob", b"Bob Jones")
        store.insert(b"config:theme", b"light")
        store.commit("Initial data")

        # Create feature branch
        store.create_branch("add-user-feature")

        # Changes on feature branch
        store.insert(b"users:charlie", b"Charlie Brown")
        store.update(b"config:theme", b"dark")
        store.commit("Add Charlie and dark theme")

        # Switch back to main and make different changes
        store.checkout("main")
        store.insert(b"users:diana", b"Diana Prince")
        store.commit("Add Diana")

        # Merge feature branch
        merge_commit = store.merge("add-user-feature", ConflictResolution.TakeSource)
        print(f"Merge successful: {merge_commit[:8]}")

        # Show final state
        print("Final users:")
        for key in [b"users:alice", b"users:bob", b"users:charlie", b"users:diana"]:
            value = store.get(key)
            if value:
                print(f"  {key.decode()}: {value.decode()}")

        print(f"Theme: {store.get(b'config:theme').decode()}")

        print("\n=== Conflict Detection ===")

        # Create another scenario with conflicts
        store.create_branch("conflicting-feature")
        store.update(b"config:theme", b"blue")
        store.commit("Change theme to blue")

        store.checkout("main")
        store.update(b"config:theme", b"red")
        store.commit("Change theme to red")

        # Check for conflicts without applying
        success, conflicts = store.try_merge("conflicting-feature")
        if not success:
            print(f"Detected {len(conflicts)} conflicts:")
            for conflict in conflicts:
                print(f"  Key: {conflict.key.decode()}")
                print(f"    Source: {conflict.source_value.decode()}")
                print(f"    Destination: {conflict.destination_value.decode()}")

        print("\n=== Conflict Resolution Strategies ===")

        # Demonstrate different resolution strategies
        strategies = [
            ("IgnoreAll", ConflictResolution.IgnoreAll),
            ("TakeSource", ConflictResolution.TakeSource),
            ("TakeDestination", ConflictResolution.TakeDestination)
        ]

        for name, strategy in strategies:
            # Create test branch for each strategy
            branch_name = f"test-{name.lower()}"
            store.checkout("main")
            store.create_branch(branch_name)

            store.update(b"config:theme", b"feature-theme")
            store.commit(f"Feature theme on {branch_name}")

            store.checkout("main")

            # Apply merge with strategy
            merge_commit = store.merge(branch_name, strategy)
            final_theme = store.get(b"config:theme").decode()
            print(f"{name:15} -> Theme: {final_theme}")

            # Reset main for next test
            store.checkout("main")

```

--------------------------------

### Rust TreeConfig Example

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/theory/rolling_hash.md

Demonstrates how to create a custom TreeConfig in Rust, specifying base and modulus.

```rust
use prollytree::config::TreeConfig;

let config = TreeConfig::<32> {
    base: 4,
    modulus: 64,
    ..Default::default()
};
```

--------------------------------

### Install prollytree with pip

Source: https://github.com/zhangfengcdt/prollytree/blob/main/README.md

Install the prollytree Python package using pip. It includes default features like git, sql, proximity, and proximity_text.

```bash
pip install prollytree   # ships with git, sql, proximity, proximity_text by default

```

--------------------------------

### Start Interactive SQL Shell

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Launch an interactive SQL shell for executing multiple queries sequentially. Type 'exit' or 'quit' to leave.

```bash
git-prolly sql -i
```

--------------------------------

### Rust: Basic Prolly Tree Operations

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/basic.md

Use this snippet to create a Prolly Tree in memory, insert key-value pairs in batches, perform point lookups, generate inclusion proofs, and verify them. It also shows how to get the root hash of the tree.

```rust
use prollytree::tree::{ProllyTree, Tree};
use prollytree::storage::InMemoryNodeStorage;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tree = ProllyTree::new(
        InMemoryNodeStorage::<32>::new(),
        Default::default(),
    );

    // Batch insert — faster than one-at-a-time on big loads.
    tree.insert_batch(&[
        (b"user:alice".to_vec(),    b"Alice Johnson".to_vec()),
        (b"user:bob".to_vec(),      b"Bob Smith".to_vec()),
        (b"config:timeout".to_vec(), b"30".to_vec()),
    ]);

    // Point lookup.
    if let Some(node) = tree.find(b"user:alice") {
        for (i, k) in node.keys.iter().enumerate() {
            if k == b"user:alice" {
                println!("alice = {}", String::from_utf8(node.values[i].clone())?);
            }
        }
    }

    // Cryptographic inclusion proof.
    let proof = tree.generate_proof(b"user:alice");
    assert!(tree.verify(proof, b"user:alice", Some(b"Alice Johnson")));

    // Root hash — a stable fingerprint of the KV set.
    println!("root = {:?}", tree.root_hash());
    Ok(())
}

```

--------------------------------

### Create Simple SQL Table

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Defines a basic SQL table named 'users' with integer, text, and timestamp columns. Use for initial data structure setup.

```sql
-- Simple table
CREATE TABLE users (
    id INTEGER,
    name TEXT,
    email TEXT,
    created_at TEXT
);
```

--------------------------------

### CLI Time Travel Queries

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/versioning.md

Shows how to query historical data using the git-prolly CLI. Examples include retrieving values at a specific version, running SQL queries on historical data, and diffing versions.

```bash
git-prolly keys-at v1.0 --values
git-prolly sql -b v1.0 "SELECT COUNT(*) FROM users"
git-prolly diff v1.0 v2.0
```

--------------------------------

### Using ProllySQLStore for Relational Data

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/api/python.md

Demonstrates how to initialize ProllySQLStore, create a table, insert data, and query it using SQL commands.

```python
from prollytree import ProllySQLStore

sql = ProllySQLStore("/path/to/store")
sql.execute("CREATE TABLE users (id INTEGER, name TEXT)")
sql.execute("INSERT INTO users VALUES (1, 'Alice')")
rows = sql.execute("SELECT * FROM users WHERE id = 1")
```

--------------------------------

### Initialize and Use NamespacedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/api/python.md

Demonstrates initializing a NamespacedKvStore, inserting data into different namespaces, committing changes, creating a branch, modifying data in a new branch, and checking out an existing branch.

```python
from prollytree import NamespacedKvStore

store = NamespacedKvStore("/path/to/store")     # init or open

store.ns_insert("users",    b"u:alice", b"Alice")
store.ns_insert("settings", b"theme",   b"dark")
store.commit("seed users + settings")

store.branch("experiment")                      # create + switch
store.ns_insert("settings", b"theme", b"light")
store.commit("flip theme")
store.checkout("main")                          # both namespaces snap back
```

--------------------------------

### Initialize and Use NamespacedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/README.md

Demonstrates initializing NamespacedKvStore and performing per-namespace KV writes. Shows how commits affect all namespaces simultaneously.

```python
from prollytree import NamespacedKvStore

store = NamespacedKvStore("./data")

# Per-namespace primary KV writes. Each namespace owns its own key space —
# the same key in two namespaces resolves independently.
store.ns_insert("users",    b"u:alice", b"Alice")
store.ns_insert("settings", b"theme",   b"dark")
store.commit("seed users + settings")        # one commit, both namespaces
```

--------------------------------

### Initialize and Use VersionedKvStore with Different Backends

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/README.md

Demonstrates how to initialize VersionedKvStore with default Git backend or explicitly choose File, InMemory, or RocksDB. Shows basic insert and commit operations.

```python
from prollytree import VersionedKvStore, StorageBackend

# Default Git backend (recommended for full version control)
store = VersionedKvStore("./data")

# Or explicitly choose a storage backend
store = VersionedKvStore("./data", StorageBackend.Git)      # Full git versioning
store = VersionedKvStore("./data", StorageBackend.File)     # File-based storage
store = VersionedKvStore("./data", StorageBackend.InMemory) # In-memory (volatile)
store = VersionedKvStore("./data", StorageBackend.RocksDB)  # RocksDB (requires rocksdb_storage feature)

# Basic operations
store.insert(b"config", b"production_settings")
commit_id = store.commit("Add production config")
```

--------------------------------

### Initialize and Use VersionedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/api/python.md

Demonstrates initializing a VersionedKvStore, inserting data, committing changes, creating branches, updating values, and merging branches with conflict resolution.

```python
from prollytree import VersionedKvStore, ConflictResolution

store = VersionedKvStore("/path/to/store")

store.insert(b"user:alice", b"Alice")
store.commit("seed")

store.create_branch("feature")
store.update(b"user:alice", b"Alice Smith")
store.commit("rename")

store.checkout("main")
store.merge("feature", ConflictResolution.TakeSource)
```

--------------------------------

### Clone and Build ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/CONTRIBUTING.md

Clone the repository, navigate into the directory, and build the project with default or all features. Also includes the command to run tests.

```bash
git clone https://github.com/zhangfengcdt/prollytree.git
cd prollytree

cargo build

cargo build --all-features

cargo test
```

--------------------------------

### Install Prollytree CLI with Git Feature

Source: https://github.com/zhangfengcdt/prollytree/blob/main/README.md

Install the prollytree command-line interface using cargo, enabling the 'git' feature. This command is used to interact with prollytree functionalities from the terminal.

```bash
cargo install prollytree --features git

```

```bash
git-prolly --help

```

--------------------------------

### Initialize Git-Prolly Repository

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Before using SQL features, ensure your repository is initialized.

```bash
git-prolly init
```

--------------------------------

### Verify SQL Feature

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Check if the SQL feature is enabled in your git-prolly installation.

```bash
git-prolly sql --help
```

--------------------------------

### Running Benchmarks

Source: https://github.com/zhangfengcdt/prollytree/blob/main/CLAUDE.md

Initiate benchmarks for different components of the project, such as the tree, SQL interface, Git storage, or general storage.

```bash
cargo bench --bench tree   # also: sql, git, storage
```

--------------------------------

### Configuration Management with ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/python.md

Demonstrates storing and managing different configurations (e.g., production and development) using ProllyTree.

```python
prod = {
    "database": {"host": "prod-db", "port": 5432, "ssl": True},
    "api":      {"rate_limit": 1000, "timeout": 30},
}

dev = json.loads(json.dumps(prod))   # copy
dev["database"]["host"] = "localhost"
dev["database"]["ssl"]  = False
dev["api"]["rate_limit"] = 10_000

store.insert(b"config:production",  json.dumps(prod).encode())
store.insert(b"config:development", json.dumps(dev).encode())
store.commit("seed configs")
```

--------------------------------

### Branching and Checking Out in NamespacedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/README.md

Illustrates how to create a new branch, make changes to a specific namespace, commit the changes, and then check out a different branch.

```python
store.branch("experiment")                   # create + switch
store.ns_insert("settings", b"theme", b"light")
store.commit("flip theme on experiment")

store.checkout("main")
store.ns_get("settings", b"theme")           # b"dark" again
store.list_namespaces()                      # ['users', 'settings', ...]
```

--------------------------------

### Basic Key-Value Store with ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/examples.md

Demonstrates how to use ProllyTree as a simple key-value store. It shows inserting user data and retrieving it using byte keys.

```python
from prollytree import ProllyTree

def example_basic_kv_store():
    """Basic key-value store example"""
    tree = ProllyTree()

    # Store user data
    users = {
        "alice": {"name": "Alice Smith", "age": 30},
        "bob": {"name": "Bob Jones", "age": 25},
        "charlie": {"name": "Charlie Brown", "age": 35}
    }

    # Insert users
    import json
    for user_id, user_data in users.items():
        key = f"user:{user_id}".encode('utf-8')
        value = json.dumps(user_data).encode('utf-8')
        tree.insert(key, value)

    # Retrieve a user
    alice_data = tree.find(b"user:alice")
    if alice_data:
        alice = json.loads(alice_data.decode('utf-8'))
        print(f"Alice: {alice['name']}, age {alice['age']}")

    return tree
```

--------------------------------

### Versioned Key-Value Store with Branching and Merging

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/python.md

Demonstrates creating a versioned key-value store, managing branches, committing changes, and merging branches with conflict resolution.

```python
from prollytree import VersionedKvStore, ConflictResolution

store = VersionedKvStore("./my_store")
store.insert(b"config:theme", b"light")
store.insert(b"config:lang",  b"en")
store.commit("initial config")

store.create_branch("darkmode")
store.update(b"config:theme", b"dark")
store.insert(b"config:animations", b"enabled")
store.commit("dark + animations")

store.checkout("main")
store.update(b"config:lang", b"fr")
store.commit("french")

ok, conflicts = store.try_merge("darkmode")
assert ok  # no overlapping keys

merge = store.merge("darkmode", ConflictResolution.TakeSource)
print("merge:", merge[:8])
```

--------------------------------

### Enable Prollytree Features in Cargo.toml

Source: https://github.com/zhangfengcdt/prollytree/blob/main/README.md

Specify the desired features for prollytree in your Cargo.toml file. This example enables git, sql, proximity, and proximity_text features.

```toml
[dependencies.prollytree]
version = "0.4.1-beta"
features = ["git", "sql", "proximity", "proximity_text"]

```

--------------------------------

### Choosing Storage Backends

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/advanced.md

Select the appropriate storage backend based on persistence and versioning needs. Options include in-memory, file-based, and versioned key-value stores.

```python
from prollytree import ProllyTree, VersionedKvStore

# In-memory (fastest, not persistent)
tree = ProllyTree()

# File-based storage (persistent)
tree = ProllyTree(storage_type="file", path="/path/to/data")

# Versioned storage with Git-like history
store = VersionedKvStore("/path/to/versioned_data")
```

--------------------------------

### Initialize and Commit with VersionedKvStore (Rust)

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/basic_usage.md

Initialize a Git-like versioned key-value store in Rust and perform an initial commit. Ensure the specified path is within a Git repository.

```rust
use prollytree::git::versioned_store::StoreFactory;

let mut store = StoreFactory::git::<32, _>("data")?;

store.insert(b"config/theme".to_vec(), b"light".to_vec())?;
let c1 = store.commit("initial config")?;
```

--------------------------------

### Initialize and Use FileNodeStorage

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/storage.md

Demonstrates how to create a FileNodeStorage instance, configure a ProllyTree, and insert data. The data will be persisted in the specified directory.

```rust
use prollytree::storage::FileNodeStorage;
use prollytree::tree::{ProllyTree, Tree};
use prollytree::config::TreeConfig;
use std::path::PathBuf;

let storage_dir = PathBuf::from("./prolly_data");
let storage = FileNodeStorage::<32>::new(storage_dir);
let config = TreeConfig::<32>::default();
let mut tree = ProllyTree::new(storage, config);

tree.insert(b"key".to_vec(), b"value".to_vec());
// Data persists in ./prolly_data/ directory

```

--------------------------------

### Interactive Shell Querying Historical Data

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Examples of querying historical data using SELECT statements in the interactive shell. Demonstrates attempting a disallowed INSERT operation and the resulting error.

```sql
prolly-sql> SELECT COUNT(*) FROM new_analytics_table;
prolly-sql> SELECT * FROM products WHERE price > 1000;
prolly-sql> INSERT INTO products VALUES (3, 'iPad', 800);
prolly-sql> exit
```

--------------------------------

### Build MkDocs Site

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/installation.md

Build the static documentation site using mkdocs build. The output will be placed in the ./site directory.

```bash
mkdocs build
```

--------------------------------

### Start Interactive Shell on Historical Data

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Initiate the interactive SQL shell against a specific branch or commit to query historical data. Note that only SELECT statements are permitted in this read-only mode.

```bash
git-prolly sql -b feature/analytics -i
```

--------------------------------

### Enable Verbose Mode for Debugging SQL Queries

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Use the --verbose flag when executing SQL queries to get detailed error messages, query execution times, and additional troubleshooting context.

```bash
git-prolly sql --verbose "SELECT * FROM users"
```

--------------------------------

### Initialize and Use VersionedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/quickstart.md

Create and interact with a VersionedKvStore for Git-like versioned storage. This includes inserting data, committing changes, and updating existing entries.

```python
from prollytree import VersionedKvStore

# Create a versioned store
store = VersionedKvStore("/path/to/store")

# Insert data
store.insert(b"user:123", b"Alice")
store.insert(b"user:456", b"Bob")

# Commit changes
commit_id = store.commit("Add initial users")

# Update data
store.update(b"user:123", b"Alice Smith")
commit_id2 = store.commit("Update Alice's name")

# View history
commits = store.log()
for commit in commits:
    print(f"{commit['id'][:8]} - {commit['message']}")
```

--------------------------------

### Initialize and Commit with VersionedKvStore (Python)

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/basic_usage.md

Initialize a versioned key-value store in Python and perform an initial commit. This sets up the basic structure for version control.

```python
from prollytree import VersionedKvStore, ConflictResolution

store = VersionedKvStore("./store")
store.insert(b"config:theme", b"light")
store.commit("init")
```

--------------------------------

### Create and verify a key-value store in Rust

Source: https://github.com/zhangfengcdt/prollytree/blob/main/README.md

Demonstrates creating a ProllyTree with an in-memory storage, inserting a key-value pair, generating a Merkle inclusion proof, and verifying it.

```rust
use prollytree::tree::{ProllyTree, Tree};
use prollytree::storage::InMemoryNodeStorage;

let mut tree = ProllyTree::new(InMemoryNodeStorage::<32>::new(), Default::default());
tree.insert(b"user:alice".to_vec(), b"Alice".to_vec());

let proof = tree.generate_proof(b"user:alice");
assert!(tree.verify(proof, b"user:alice", Some(b"Alice")));

```

--------------------------------

### Select Data with WHERE Clause

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Filters rows based on specified conditions. Use 'id > 1' to get users with IDs greater than 1, or 'price < 100 AND in_stock = true' for products meeting multiple criteria.

```sql
-- With WHERE clause
SELECT * FROM users WHERE id > 1;
SELECT * FROM products WHERE price < 100 AND in_stock = true;
```

--------------------------------

### View Built Documentation

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/README.md

Opens the generated HTML documentation in the default browser or serves it locally using Python's built-in HTTP server.

```bash
# Open in browser
open _build/html/index.html

# Or serve locally
cd _build/html && python -m http.server 8000
# Then visit: http://localhost:8000
```

--------------------------------

### Complex SQL Queries for Data Analysis

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/sql.md

Perform complex data analysis using SQL, including creating tables, joining tables, grouping data, and filtering results based on aggregated values. These examples are useful for generating insights from your data.

```sql
-- Create sales data
CREATE TABLE sales (
    id INTEGER,
    product_id INTEGER,
    customer_id INTEGER,
    quantity INTEGER,
    price INTEGER,
    sale_date TEXT
);
```

```sql
-- Top selling products
SELECT p.name, SUM(s.quantity) as total_sold, SUM(s.quantity * s.price) as revenue
FROM sales s
JOIN products p ON s.product_id = p.id
GROUP BY p.id, p.name
ORDER BY revenue DESC
LIMIT 10;
```

```sql
-- Customer purchase history
SELECT c.name, COUNT(DISTINCT s.id) as purchase_count,
       SUM(s.quantity * s.price) as total_spent
FROM customers c
JOIN sales s ON c.id = s.customer_id
GROUP BY c.id, c.name
HAVING total_spent > 1000;
```

--------------------------------

### Document Version Control with ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/examples.md

Demonstrates how to version control documents using VersionedKvStore. It covers creating, updating, and retrieving commit history for documents.

```python
from prollytree import VersionedKvStore
import json
from datetime import datetime

def example_document_versioning():
    """Example of version controlling documents"""
    store = VersionedKvStore("./document_store")

    # Create initial document
    doc = {
        "title": "My Document",
        "content": "Initial content",
        "author": "Alice",
        "created": datetime.now().isoformat()
    }

    store.insert(b"doc:readme", json.dumps(doc).encode('utf-8'))
    commit1 = store.commit("Initial document creation")
    print(f"Initial commit: {commit1[:8]}")

    # Update document
    doc["content"] = "Updated content with more details"
    doc["modified"] = datetime.now().isoformat()
    store.update(b"doc:readme", json.dumps(doc).encode('utf-8'))
    commit2 = store.commit("Add more content details")
    print(f"Update commit: {commit2[:8]}")

    # View commit history
    print("\nCommit History:")
    commits = store.log()
    for commit in commits:
        timestamp = datetime.fromtimestamp(commit['timestamp'])
        print(f"  {commit['id'][:8]} - {commit['message']} ({timestamp})")

    return store

```

--------------------------------

### Create, Insert, and Select Data via CLI

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/sql.md

Use the `git-prolly sql` command to execute SQL statements for table creation, data insertion, and retrieval. Ensure changes are committed using `git-prolly commit`.

```bash
git-prolly sql "CREATE TABLE users (id INTEGER, name TEXT, email TEXT)"
git-prolly sql "INSERT INTO users VALUES (1, 'Alice', 'alice@example.com'),
                                          (2, 'Bob',   'bob@example.com')"
git-prolly sql "SELECT * FROM users ORDER BY id"

# Commit the changes.
git-prolly commit -m "seed users"
```

--------------------------------

### Initialize ProllyTree KV Store

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/cli.md

Initializes a ProllyTree KV store in the current directory or a specified path.

```bash
git-prolly init [path]
```

--------------------------------

### Python: Basic Prolly Tree Operations

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/basic.md

This Python snippet demonstrates creating a Prolly Tree, inserting data in batches, finding values, generating and verifying inclusion proofs, and retrieving the root hash. It's a concise way to interact with the data structure.

```python
from prollytree import ProllyTree

tree = ProllyTree()
tree.insert_batch([
    (b"user:alice",    b"Alice Johnson"),
    (b"user:bob",      b"Bob Smith"),
    (b"config:timeout", b"30"),
])

print("alice =", tree.find(b"user:alice"))

proof = tree.generate_proof(b"user:alice")
assert tree.verify(proof, b"user:alice", b"Alice Johnson")

print("root =", tree.root_hash().hex())

```

--------------------------------

### Create, Insert, and Find Data in ProllyTree

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/index.md

Demonstrates the basic usage of ProllyTree by creating a new tree, inserting key-value pairs, and retrieving a value.

```python
from prollytree import ProllyTree

# Create a new tree
tree = ProllyTree()

# Insert some data
tree.insert(b"key1", b"value1")
tree.insert(b"key2", b"value2")

# Find data
value = tree.find(b"key1")
print(value)  # b"value1"
```

--------------------------------

### CLI: `git-prolly` as a Git-like KV Store

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/quickstart.md

Illustrates using the `git-prolly` CLI to initialize a KV dataset within a Git repository, perform basic operations like setting values, committing, branching, merging, and inspecting history.

```bash
# 1. Create a repo and initialize a KV dataset inside it.
git init demo && cd demo
mkdir data && git-prolly init data
cd data

# 2. Put data, commit.
git-prolly set "user:alice" "Alice Johnson"
git-prolly set "user:bob" "Bob Smith"
git-prolly commit -m "seed users"

# 3. Branch, edit, merge.
git checkout -b feature/rename
git-prolly set "user:alice" "Alice J."
git-prolly commit -m "rename alice"
git checkout main
git-prolly merge feature/rename

# 4. Inspect.
git-prolly list --values
git-prolly log
git-prolly history "user:alice"

```

--------------------------------

### Manage multiple namespaces in a single store with Python

Source: https://github.com/zhangfengcdt/prollytree/blob/main/README.md

Demonstrates using `NamespacedKvStore` to manage independent prolly trees within a single Git repository. Each namespace has its own key space and search indexes.

```python
from prollytree import NamespacedKvStore

store = NamespacedKvStore("./data")
store.ns_insert("users",    b"u:alice", b"Alice")
store.ns_insert("settings", b"theme",   b"dark")
store.commit("seed users + settings")

store.branch("experiment")
store.ns_insert("settings", b"theme", b"light")
store.commit("flip theme on experiment")

store.checkout("main")
store.ns_get("settings", b"theme")   # b"dark" — main is unchanged

```

--------------------------------

### Create TreeConfig Instance

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/api/python.md

Shows how to instantiate a TreeConfig object with custom base and modulus parameters for tuning the ProllyTree's structure.

```python
from prollytree import TreeConfig

cfg = TreeConfig(base=4, modulus=64)
```

--------------------------------

### ProllySQLStore for SQL Operations

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/python.md

Illustrates using ProllySQLStore to execute SQL commands, including table creation, data insertion, and querying.

```python
from prollytree import ProllySQLStore

sql = ProllySQLStore("./sql_store")
sql.execute("CREATE TABLE users (id INTEGER, name TEXT, email TEXT)")
sql.execute("INSERT INTO users VALUES (1, 'Alice', 'alice@example.com'),"
            "                          (2, 'Bob',   'bob@example.com')")

for row in sql.execute("SELECT id, name FROM users ORDER BY id"):
    print(row)
```

--------------------------------

### SQL Analytics with ProllySQLStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/docs/examples.md

Demonstrates creating tables, inserting data, and performing analytics queries using ProllySQLStore. This is useful for data analysis tasks directly within the ProllyTree environment.

```python
from prollytree import ProllySQLStore

def example_sql_analytics():
    """Example using SQL for data analytics"""
    sql_store = ProllySQLStore("./analytics_store")

    # Create tables
    sql_store.execute("""
        CREATE TABLE users (
            id INTEGER,
            name TEXT,
            email TEXT,
            signup_date TEXT,
            plan TEXT
        )
    """)

    sql_store.execute("""
        CREATE TABLE events (
            id INTEGER,
            user_id INTEGER,
            event_type TEXT,
            timestamp TEXT,
            metadata TEXT
        )
    """)

    # Insert sample data
    users_data = [
        (1, 'Alice Smith', 'alice@example.com', '2023-01-15', 'premium'),
        (2, 'Bob Jones', 'bob@example.com', '2023-02-01', 'basic'),
        (3, 'Charlie Brown', 'charlie@example.com', '2023-02-15', 'premium'),
    ]

    for user in users_data:
        sql_store.execute(
            "INSERT INTO users (id, name, email, signup_date, plan) VALUES (?, ?, ?, ?, ?)",
            user
        )

    # Analytics queries
    print("=== User Analytics ===")

    # Premium users
    premium_users = sql_store.execute(
        "SELECT name, email FROM users WHERE plan = 'premium'"
    )
    print(f"Premium users: {len(premium_users)}")
    for user in premium_users:
        print(f"  - {user[0]} ({user[1]})")

    return sql_store

```

--------------------------------

### Rust: Insert and Verify Proof

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/index.md

Demonstrates inserting key-value pairs into a ProllyTree and generating/verifying a cryptographic proof for a specific key. Requires `prollytree` and `InMemoryNodeStorage`.

```rust
use prollytree::tree::{ProllyTree, Tree};
use prollytree::storage::InMemoryNodeStorage;

let storage = InMemoryNodeStorage::<32>::new();
let mut tree = ProllyTree::new(storage, Default::default());

tree.insert(b"user:alice".to_vec(), b"Alice Johnson".to_vec());
tree.insert(b"config:timeout".to_vec(), b"30".to_vec());

// Generate a cryptographic proof and verify it.
let proof = tree.generate_proof(b"user:alice");
assert!(tree.verify(proof, b"user:alice", Some(b"Alice Johnson")));
```

--------------------------------

### Build and Quality Gate Commands

Source: https://github.com/zhangfengcdt/prollytree/blob/main/CLAUDE.md

Run these commands to ensure the project builds correctly and meets quality standards before completing work.

```bash
cargo build --all
cargo fmt --all
cargo clippy --all
```

--------------------------------

### Document Versioning with VersionedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/examples/python.md

Shows how to manage document versions using VersionedKvStore, including initial insertion, updates, and logging commit history.

```python
from prollytree import VersionedKvStore
import json, datetime

store = VersionedKvStore("./docs_store")

doc = {"title": "My Document",
       "content": "Initial content",
       "author": "Alice",
       "created": datetime.datetime.utcnow().isoformat()}

store.insert(b"doc:readme", json.dumps(doc).encode())
store.commit("initial")

# Update.
doc["content"] = "Updated with more details"
doc["modified"] = datetime.datetime.utcnow().isoformat()
store.update(b"doc:readme", json.dumps(doc).encode())
store.commit("expand")

for c in store.log():
    print(c["id"][:8], c["message"])
```

--------------------------------

### Basic RocksDBNodeStorage Usage

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/storage.md

Demonstrates the basic initialization of RocksDBNodeStorage with a default configuration. Ensure the path exists and is accessible.

```rust
use prollytree::storage::RocksDBNodeStorage;
use prollytree::tree::{ProllyTree, Tree};
use prollytree::config::TreeConfig;
use std::path::PathBuf;

// Basic usage
let db_path = PathBuf::from("./rocksdb_data");
let storage = RocksDBNodeStorage::<32>::new(db_path)?;
let config = TreeConfig::<32>::default();
let mut tree = ProllyTree::new(storage, config);
```

--------------------------------

### Branching, Merging, and Diffing in VersionedKvStore

Source: https://github.com/zhangfengcdt/prollytree/blob/main/python/README.md

Illustrates how to create branches, add data, commit changes, merge branches, and view differences between branches using the Git backend.

```python
# Branch and experiment
store.create_branch("experiment")
store.insert(b"feature", b"experimental_data")
store.commit("Add experimental feature")

# Merge branches (Git backend only)
store.checkout("main")
store.merge("experiment")

# Diff between branches (Git backend only)
diffs = store.diff("main", "experiment")
for diff in diffs:
    print(f"Key: {diff.key}, Operation: {diff.operation}")
```

--------------------------------

### Generate Rust Documentation Locally

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/api/rust.md

Use this command to generate local documentation for the Rust API, including private items and without dependencies. The --open flag will automatically open the generated documentation in your browser.

```bash
cargo doc --document-private-items --no-deps --open
```

--------------------------------

### VersionedKvStore Data Model

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/theory/versioning.md

Illustrates the Git-like versioning model with commits, branches, and merges using a Prolly Tree. This diagram helps visualize the relationships between different states of the data.

```mermaid
flowchart LR
    A[main: seed users] --> B[main: add config]
    B --> C[main: update theme]
    B --> D[feature: add darkmode]
    C --> M[merge commit]
    D --> M
```

--------------------------------

### Branch, Update, and Merge in VersionedKvStore (Python)

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/basic_usage.md

Demonstrates creating a branch, updating a value, committing, and then merging branches with a specified conflict resolution strategy in Python's VersionedKvStore.

```python
store.create_branch("dark-mode")
store.update(b"config:theme", b"dark")
store.commit("try dark")

store.checkout("main")
merge = store.merge("dark-mode", ConflictResolution.TakeSource)
```

--------------------------------

### Initialize and Use GitNodeStorage

Source: https://github.com/zhangfengcdt/prollytree/blob/main/docs/storage.md

This snippet demonstrates how to initialize GitNodeStorage with a Git repository and a dataset directory, and then insert data into a ProllyTree. Ensure the 'git' feature is enabled. Note that data stored this way is temporary and can be lost during `git gc`.

```rust
#[cfg(feature = "git")]
use prollytree::git::GitNodeStorage;

let repo = gix::open(".")?;
let dataset_dir = std::path::PathBuf::from("./git_data");
let storage = GitNodeStorage::<32>::new(repo, dataset_dir)?;

// ⚠️ WARNING: Data may be lost during git gc!
let config = TreeConfig::<32>::default();
let mut tree = ProllyTree::new(storage, config);
tree.insert(b"key".to_vec(), b"value".to_vec());
```