Client python

ThemisDB Python SDK

Official Python client for ThemisDB - A high-performance multi-model database.

Features

• ✅ Type Hints - Full type annotations (PEP 484)
• ✅ Transaction Support - BEGIN/COMMIT/ROLLBACK with isolation levels
• ✅ LLM Integration - Native support for LLM interactions (v1.4.0+) 🆕
• ✅ Context Manager - Pythonic with statement support
• ✅ Multi-Model - Relational, Graph, Vector operations
• ✅ Query Support - AQL (Advanced Query Language)
• ✅ Topology-Aware - Automatic shard routing
• ✅ Batch Operations - Efficient bulk operations
• ✅ Vector Search - Similarity search
• ✅ Retry Logic - Automatic retries

Installation

pip install themisdb-client

Or for development:

pip install -e .[dev]

Quick Start

from themis import ThemisClient

client = ThemisClient(endpoints=["http://localhost:8080"])

# Basic CRUD
client.put("relational", "users", "user1", {"name": "Alice"})
user = client.get("relational", "users", "user1")
print(user)

# Transactions (NEW!)
tx = client.begin_transaction()
try:
    tx.put("relational", "accounts", "acc1", {"balance": 1000})
    tx.put("relational", "accounts", "acc2", {"balance": 500})
    tx.commit()
except Exception:
    tx.rollback()
    raise

Transaction Support (NEW!)

ThemisDB now supports ACID transactions with BEGIN/COMMIT/ROLLBACK semantics.

Basic Transaction Usage

from themis import ThemisClient

client = ThemisClient(endpoints=["http://localhost:8080"])

# Begin a transaction
tx = client.begin_transaction()

try:
    # Perform operations within the transaction
    tx.put("relational", "accounts", "acc1", {"balance": 1000})
    tx.put("relational", "accounts", "acc2", {"balance": 500})
    
    # Read within transaction
    acc1 = tx.get("relational", "accounts", "acc1")
    print(acc1)  # {"balance": 1000}
    
    # Commit the transaction
    tx.commit()
except Exception as error:
    # Rollback on error
    tx.rollback()
    raise

Context Manager (Pythonic Way)

The recommended way to use transactions in Python is with the with statement:

# Automatically commits on success, rolls back on exception
with client.begin_transaction() as tx:
    tx.put("relational", "accounts", "acc1", {"balance": 1000})
    tx.put("relational", "accounts", "acc2", {"balance": 500})
    
    acc1 = tx.get("relational", "accounts", "acc1")
    print(acc1)  # {"balance": 1000}
    
# Transaction is automatically committed here

If an exception occurs, the transaction is automatically rolled back:

try:
    with client.begin_transaction() as tx:
        tx.put("relational", "users", "user1", {"name": "Alice"})
        raise ValueError("Something went wrong")
except ValueError:
    pass
# Transaction was automatically rolled back

Isolation Levels

ThemisDB supports three isolation levels:

• READ_COMMITTED (default) – Prevents dirty reads. Non-repeatable reads and phantom reads are possible.

• SNAPSHOT – Provides a consistent snapshot of the database as of transaction start.

  ⚠️ Write-skew and phantom-read anomalies are possible at SNAPSHOT isolation. Two concurrent SNAPSHOT transactions that each read the same data and write disjoint keys can both commit even when their combined effect violates an application invariant (e.g. double-booking, over-withdrawal). Use SERIALIZABLE when strict correctness is required.

• SERIALIZABLE – Full serializability via SSI / predicate locking. Prevents write skew and phantom reads. May abort more transactions and has higher latency than SNAPSHOT.

# Use SNAPSHOT isolation for repeatable reads
# WARNING: write skew and phantom reads are possible at this level
tx = client.begin_transaction(isolation_level="SNAPSHOT")

# Use SERIALIZABLE to prevent write skew and phantom reads
tx = client.begin_transaction(isolation_level="SERIALIZABLE")

try:
    user1 = tx.get("relational", "users", "user1")
    user2 = tx.get("relational", "users", "user2")
    
    # These reads are from the same snapshot
    # even if other transactions modify the data
    
    tx.commit()
except Exception:
    tx.rollback()

Query Within Transactions

with client.begin_transaction() as tx:
    # Execute AQL query within transaction
    result = tx.query("FOR user IN users FILTER user.active == true RETURN user")
    
    # Update based on query results
    for user in result.items:
        user["last_seen"] = "2025-11-20T12:00:00Z"
        tx.put("relational", "users", user["id"], user)
    
# Automatically committed

Complex Example: Money Transfer

def transfer_money(client, from_account: str, to_account: str, amount: float):
    """Transfer money between accounts using a transaction."""
    with client.begin_transaction(isolation_level="SNAPSHOT") as tx:
        # Read both accounts
        from_acc = tx.get("relational", "accounts", from_account)
        to_acc = tx.get("relational", "accounts", to_account)
        
        if not from_acc or not to_acc:
            raise ValueError("Account not found")
        
        if from_acc["balance"] < amount:
            raise ValueError("Insufficient funds")
        
        # Update balances
        from_acc["balance"] -= amount
        to_acc["balance"] += amount
        
        tx.put("relational", "accounts", from_account, from_acc)
        tx.put("relational", "accounts", to_account, to_acc)
        
    # Transaction automatically committed

# Usage
transfer_money(client, "alice", "bob", 100.0)

LLM Integration (v1.4.0+) 🆕

ThemisDB v1.8.0-rc1 introduces native LLM integration with support for various models and features like prefix caching, response caching, multi-GPU, and more.

Basic LLM Interaction

from themis import ThemisClient

client = ThemisClient(endpoints=["http://localhost:8080"])

# Create an LLM interaction
result = client.llm_interaction(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Explain MVCC in databases"}
    ]
)

print(f"Interaction ID: {result.id}")
print(f"Success: {result.success}")

LLM with Reasoning Steps

# Create interaction with chain-of-thought reasoning
result = client.llm_interaction(
    model="llama-3.1",
    messages=[
        {"role": "system", "content": "You are a database expert"},
        {"role": "user", "content": "How does ThemisDB handle transactions?"}
    ],
    reasoning_steps=[
        {
            "type": "chain_of_thought",
            "content": [
                "MVCC allows parallel reading/writing",
                "Each transaction gets a snapshot",
                "Commit checks for conflicts"
            ]
        }
    ],
    metadata={"use_case": "documentation", "version": "1.4.0"}
)

Retrieve LLM Interactions

# Get a specific interaction
interaction = client.get_llm_interaction("interaction_id_123")

if interaction:
    print(f"Model: {interaction.model}")
    print(f"Created: {interaction.created_at}")
    for msg in interaction.messages:
        print(f"{msg.role}: {msg.content}")
    
    if interaction.reasoning_steps:
        for step in interaction.reasoning_steps:
            print(f"Reasoning ({step.type}): {step.content}")

List LLM Interactions

# List all interactions
interactions = client.list_llm_interactions(limit=50, offset=0)

for interaction in interactions:
    print(f"{interaction.id}: {interaction.model} - {interaction.created_at}")

# Filter by model
gpt4_interactions = client.list_llm_interactions(model="gpt-4o", limit=10)

LLM with Vision Support

# Vision model interaction (requires v1.4.0+ with vision support)
result = client.llm_interaction(
    model="gpt-4-vision",
    messages=[
        {
            "role": "user",
            "content": "What's in this image?",
            "image_url": "https://example.com/image.jpg"  # Or base64 encoded
        }
    ]
)

API Reference

ThemisClient

Constructor

ThemisClient(
    endpoints: list[str],
    *,
    namespace: str = "default",
    timeout: float = 30.0,
    max_retries: int = 3,
    metadata_endpoint: str | None = None,
    metadata_path: str = "/_admin/cluster/topology",
    max_workers: int | None = None,
    transport: httpx.BaseTransport | None = None
)

Methods

• get(model, collection, uuid) - Retrieve an entity
• put(model, collection, uuid, data) - Create/update an entity
• delete(model, collection, uuid) - Delete an entity
• batch_get(model, collection, uuids) - Batch retrieve
• batch_put(model, collection, items) - Batch create/update
• batch_delete(model, collection, uuids) - Batch delete
• query(aql, *, params=None) - Execute AQL query
• vector_search(embedding, top_k=10) - Vector similarity search
• graph_traverse(start_node, max_depth=3) - Graph traversal
• health(endpoint=None) - Health check
• begin_transaction(*, isolation_level="READ_COMMITTED") - Start transaction
• llm_interaction(model, messages, *, reasoning_steps=None, metadata=None) - NEW: Create LLM interaction
• get_llm_interaction(interaction_id) - NEW: Retrieve LLM interaction
• list_llm_interactions(*, model=None, limit=100, offset=0) - NEW: List LLM interactions

Transaction

Properties

• transaction_id: str - Unique transaction identifier
• is_active: bool - Whether the transaction is active

Methods

• get(model, collection, uuid) - Retrieve within transaction
• put(model, collection, uuid, data) - Update within transaction
• delete(model, collection, uuid) - Delete within transaction
• query(aql, *, params=None) - Query within transaction
• commit() - Commit the transaction
• rollback() - Rollback the transaction

Context Manager

with client.begin_transaction() as tx:
    # Operations here
    pass
# Automatically commits on success, rolls back on exception

Development

# Install with dev dependencies
pip install -e .[dev]

# Run tests
pytest tests/

# Run tests with coverage
pytest --cov=themis tests/

License

Apache-2.0

---

ThemisDB 1.9.0-beta · Home · Module-Index · GitHub · Issues