# Valstorm Python Client SDK (valstorm-client)

> Official typed Python 3.13+ SDK with 1:1 PlatformContext parity across records, SQL/GraphQL queries, VFS Knowledge Vaults, schemas, and sandboxes.

- **GitHub Repository:** https://github.com/Valstorm-Corp/valstorm-client-python
- **License:** PolyForm Noncommercial License 1.0.0 (https://polyformproject.org/licenses/noncommercial/1.0.0)
- **Installation:** `uv add valstorm-client`
- **Language/Stack:** Python 3.13+ (HTTPX HTTP/2, Pydantic, Typing Protocols)
- **Web Documentation:** https://www.valstorm.com/free-tools/valstorm-client-python

## Key Capabilities
- **1:1 PlatformContext Structural Parity:** Enforced via Python typing.Protocol (PlatformProtocol) so code written for in-process platform functions runs unchanged over remote HTTP/2.
- **Dual Sync & Async HTTP/2 Multiplexing:** Use ValstormClient for linear ETL scripts or AsyncValstormClient for high-concurrency AI agent loops and FastAPI services.
- **Proactive & Reactive JWT Auto-Refresh:** UserJwtAuth detects token expiry windows automatically and executes mutex-locked refreshes with custom persistence callbacks.
- **Complete Domain Facades:** Covers records, query (SQL & GraphQL), schemas, vfs, files (presigned S3 & rollback), apps, and isolated database sandboxes.

## Quickstart
```bash
from valstorm import ValstormClient, AsyncValstormClient, PatAuth

# Synchronous HTTP/2 Client (Ideal for scripts, CLI, and Celery workers)
client = ValstormClient(
    base_url="https://api.valstorm.com/v1",
    auth=PatAuth("vst_pat_your_token_here"),
)

# 1. Execute Valstorm SQL
leads = client.query.sql("SELECT id, name, status FROM lead WHERE status = 'Active' LIMIT 10")

# 2. Bulk-safe Record CUD (Create, Update, Delete)
created = client.records.create("lead", [{"name": "Acme Dental Group", "status": "Active"}])

# 3. Inspect VFS Knowledge Vault hierarchy
tree = client.vfs.tree()
```