Documentation

from python.lakehouse.client import LakehouseClient

# Initialize client
client = LakehouseClient("/app/data/lakehouse")

# Get API keys with usage stats
keys = client.get_api_keys(user_id="user-123")

# Example output:
# {
#   "hfthot_api_key": "hft_abc123_...",
#   "provider_keys": {
#     "finnhub": {
#       "api_key": "c8q...",
#       "queries_done": 245,
#       "queries_remaining": 3355,
#       "queries_limit": 3600
#     },
#     "alpha_vantage": {
#       "api_key": "DEMO",
#       "queries_done": 12,
#       "queries_remaining": 488,
#       "queries_limit": 500
#     }
#   },
#   "data_sharing_consent": true
# }

# After making a Finnhub API call
success = client.update_query_count(
    user_id="user-123",
    provider="finnhub",
    increment=1
)

# Check updated stats
stats = client.get_query_stats("user-123", "finnhub")
print(f"Queries remaining: {stats['queries_remaining']}/{stats['queries_limit']}")

# Example output:
# Queries remaining: 3354/3600

# Save user's API keys (e.g., after subscribing to Data Sharing Program)
client.save_api_keys(
    user_id="user-123",
    provider_keys={
        "finnhub": {"api_key": "c8q2i...", "queries_limit": 3600},
        "alpha_vantage": {"api_key": "DEMO", "queries_limit": 500}
    },
    data_sharing_consent=True  # User opts into Data Sharing Program
)

# Generates a unique HFThoT API key automatically
hfthot_key = client.generate_hfthot_api_key("user-123")
print(f"Your HFThoT API key: {hfthot_key}")

# Example output:
# Your HFThoT API key: hft_abc123_xyz-456-789

# Read users table at version 5 (e.g., before a data migration)
users_v5 = client.read_version("users", version=5)
print(f"Total users at version 5: {len(users_v5)}")

# Read api_keys table at version 10 (e.g., before quota reset)
api_keys_v10 = client.read_version("api_keys", version=10)

from datetime import datetime

# Get state of users table on January 15, 2026 at 14:00 UTC
timestamp = datetime(2026, 1, 15, 14, 0, 0)
users_jan15 = client.read_at_timestamp("users", timestamp)

# Perfect for regulatory audits (MiFID II, FINMA compliance)

# Export all user data (users, sessions, api_keys, audit_log)
user_data = client.export_user_data(user_id="user-123")

# Returns JSON with:
# {
#   "user": {...},
#   "sessions": [{...}, {...}],
#   "api_keys": {...},
#   "audit_log": [{...}, ...]
# }

# Save to file for user download (CSV or JSON)
import json
with open(f"user_data_{user_id}.json", "w") as f:
    json.dump(user_data, f, indent=2)

# Soft delete: Mark user as deleted (tombstone)
client.delete_user_soft(user_id="user-123")
# → User marked as deleted, data still recoverable for 30 days

# Hard delete: Permanent removal with VACUUM
client.delete_user_permanent(user_id="user-123")
# → Deletes from users, sessions, api_keys, audit_log
# → Runs VACUUM to permanently erase Parquet files

# Export in standard formats (JSON, CSV)
export_data = client.export_user_data(user_id="user-123", format="csv")

# User can import into any service that accepts CSV/JSON
# Includes: API keys, subscription tier, billing history

# Get all actions for a user
logs = client.get_audit_log(
    user_id="user-123",
    start_date="2026-01-01",
    end_date="2026-02-01"
)

# Example output:
# [
#   {"timestamp": "2026-01-15T10:23:45Z", "action": "login", "ip": "203.0.113.42"},
#   {"timestamp": "2026-01-15T10:24:12Z", "action": "update_api_keys", "provider": "finnhub"},
#   {"timestamp": "2026-01-15T14:56:30Z", "action": "query_api", "provider": "finnhub", "queries_remaining": 3354}
# ]

# Get only login attempts (success + failures)
login_logs = client.get_audit_log(
    user_id="user-123",
    action_type="login"
)

# Detect suspicious activity (e.g., multiple failed logins)
failed_logins = [log for log in login_logs if log.get("success") == False]
if len(failed_logins) > 5:
    print("⚠️ Warning: Multiple failed login attempts detected")