Valstorm Logo
VALSTORM
Back to All Free Tools
Developer CLI & SDK PolyForm Noncommercial License 1.0.0

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.

Write the exact same Python code whether running in-process inside a Valstorm serverless function or remotely from a microservice, CLI tool, or AI agent. Provides both synchronous (ValstormClient) and asynchronous (AsyncValstormClient) HTTP/2 clients backed by httpx and Pydantic.

View Source on GitHub (valstorm-client) Run Managed on Valstorm Cloud ($25/mo)
1:1 Interface Parity with Server-Side In-Process PlatformContext
Dual Sync (ValstormClient) & Async (AsyncValstormClient) HTTP/2 Transports
3 Auth Strategies: PAT, M2M Service Key, and Mutexed Auto-Refresh User JWT
Typed Exception Hierarchy (RateLimitError, ValidationError, NotFoundError)
Section 01 • Installation & Quickstart

1. Query SQL, Mutate Records & Browse VFS Vaults (Sync & Async) 

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()
Section 02 • Architecture & Data Flow

2. How valstorm-client Works Under the Hood 

  🐍 Your Python Application / Microservice / Agent
     • ValstormClient (Sync HTTP/2)  |  AsyncValstormClient (Async HTTP/2)
     • Auth: PatAuth (vst_pat_) | ServiceKeyAuth (vst_sk_) | UserJwtAuth (Auto-Refresh)
          │
          ├── client.records   (create, update, delete, get, list)
          ├── client.query     (sql, graphql)
          ├── client.vfs       (tree, snapshot, move, resolve_path)
          ├── client.files     (get, save_content, presigned_upload, rollback)
          ├── client.schemas   (get, list, create, add_field)
          └── client.sandboxes (create, delete)
          │
          ▼  (1:1 Protocol Parity with Server-Side PlatformContext)
  ☁️ Valstorm Open API (/v1)
Section 03 • Engineering Capabilities

3. Core Capabilities & Technical Specifications

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.

Section 04 • Dual-License Model

4. Open-Source & Commercial Licensing

Personal, Academic & Noncommercial Use

PolyForm Noncommercial License 1.0.0

Free to clone, inspect, modify, and run for personal projects, educational study, and noncommercial research under the PolyForm Noncommercial License 1.0.0.

Commercial & Enterprise Use

Valstorm Commercial License

Commercial use in business operations is included automatically with any active Valstorm BOS workspace ($25/mo in usage credits with $0/seat tax) or available via enterprise BYOC licensing.

5. Frequently Asked Questions

Does valstorm-client support both synchronous and asynchronous Python code?

Yes. Import ValstormClient for synchronous execution or AsyncValstormClient for asyncio applications. Both expose the exact same domain facades and method signatures.

Explore Other Valstorm Open-Source Packages

View All 7 Tools →
valstorm-agent

Enterprise-grade autonomous AI execution runtime, ReAct loop, and parallel subagent swarm engine for developer workstations, CI pipelines, and remote team automation.

valstorm-cli

Command-line interface for Valstorm developers to authenticate via OAuth2 PKCE, pull and push object schemas as code, and manage local workspaces.

valstorm-mcp

Stateless Streamable HTTP, SSE, and stdio Model Context Protocol (MCP) server exposing 16 granularly scoped Valstorm VFS, SQL, and CRM tools.

valstorm-web-scraper

High-performance web scraping, domain crawling, RSS monitoring, and visual diff microservice with Python 3.14 native Zstandard compression.

valstorm-video-worker

Dedicated asynchronous microservice for multi-preset FFmpeg video transcoding, Deepgram/Whisper speech-to-text captions, and AI chapter generation.

valstorm-sanitizer

Pure Python standard-library secret redaction engine that strips API keys, JWTs, database passwords, and environment secrets before logs or LLM prompts egress.