vski-sdk (0.7.0)

Published 2026-10-24 13:44:50 +00:00 by x

To install the package using pip, run the following command:

pip install --index-url  vski-sdk

For more information on the PyPI registry, see the documentation.

Python client (SDK) for the VSKI backend - databases, collections, graphs, SQL, realtime, and durable workflows.

vski-sdk

A fully-featured Python client for the VSKI backend - multi-tenant SQLite with collections, SQL, auth, realtime, and durable workflows. Async-first with a sync wrapper.

Install

pip install vski-sdk

Quickstart (async)

import asyncio
from vski import VskiClient

async def main():
    async with VskiClient("http://127.0.0.1:3000") as client:
        # Auth as admin (bootstrap the first superuser if needed)
        res = await client.admins.auth_with_password("admin@example.com", "password")
        client.set_token(res["token"])

        # Manage databases & collections
        await client.settings.databases.create({"name": "mydb"})
        await client.settings.collections.create({
            "name": "posts",
            "type": "base",
            "fields": [
                {"name": "title", "type": "text", "required": True},
                {"name": "views", "type": "number"},
            ],
        })

        # Records
        post = await client.collection("posts").create({"title": "Hello", "views": 0})
        page = await client.collection("posts").getList(1, 30, filter='title ~ "Hello"')

        # Raw SQL
        print(await client.sql.execute("SELECT count(*) FROM posts"))

        # Light graphs: nodes + labelled edges, traversed from an in-memory index
        await client.settings.graphs.create({"name": "knowledge"})
        g = client.graph("knowledge")
        await g.create_nodes([{"id": "go", "label": "lang"}, {"id": "rust", "label": "lang"}])
        await g.create_edges([{"id": "e1", "source": "go", "target": "rust", "label": "compiles-to"}])
        path = await g.path("go", "rust")            # fewest hops
        weighted = await g.path("go", "rust", cost="weight")  # Dijkstra over edge weights
        print(path["hops"], weighted["cost"], (await g.stats())["edgeCount"])

asyncio.run(main())

Sync usage

from vski.sync import SyncVskiClient

with SyncVskiClient("http://127.0.0.1:3000") as client:
    res = client.admins.auth_with_password("admin@example.com", "password")
    client.set_token(res["token"])
    print(client.settings.databases.list())

Durable workflows

Author a workflow with the functional workflow() / step() API, then run a WorkflowWorker against it. Steps are idempotent and event-sourced, so runs survive worker restarts; sleep, wait_for_signal, parallel, retries, and rollback are all supported.

import asyncio
from vski import VskiClient, workflow, step, WorkflowWorker

@step("greet")
async def greet(name: str) -> list[str]:
    return [f"Hello, {name}"]

@workflow("hello").run
async def hello(ctx, name: str):
    return await greet(name)

async def main():
    async with VskiClient("http://127.0.0.1:3000") as client:
        res = await client.admins.auth_with_password("admin@example.com", "password")
        client.set_token(res["token"])

        worker = WorkflowWorker(client)
        task = asyncio.create_task(worker.start("hello"))
        await client.wait_for_workflow_ready()

        run = await client.workflow.trigger("hello", ["VSKI"])
        while True:
            run = await client.workflow.get_run(run["runId"])
            if run["status"] in ("completed", "failed"):
                break
            await asyncio.sleep(0.5)
        print(run["output"])  # ['Hello, VSKI']

        await worker.stop()
        await task

asyncio.run(main())

Features

Databases & collections - create/list/delete databases, schema (fields, indexes, views, FTS, triggers), rules.
Records - CRUD, search (FTS), views, bulk ops, file uploads, relation expand, auth-with-password.
Light graphs - client.graph(name) / client.settings.graphs: db-scoped property graphs (nodes + labelled, directed edges) persisted in SQLite and traversed server-side from an in-memory index. Neighbors, BFS traversal, shortest path (hops or weighted), subgraph extraction, topology stats; collection-style access rules and per-graph edge/node caps (vski server v0.10.0+).
Vector embeddings - client.embeddings.upsert/search/info/get/fetch (sqlite-vec; euclidean L2 over float32 vectors). Upsert accepts a model tag that pins the collection's embedding model on first tagged write - later mismatches are rejected with 409, and info()/search echo the tag so consumers can refuse foreign embedding spaces. get/fetch read the exact stored vectors back (vski server v0.9.0+).
SQL & named queries - client.sql.execute(...), client.query.execute(...).
Auth - admin/user password auth, registration, refresh, OAuth2, API keys, RBAC.
Automation - cron jobs, webhooks + logs, gates (API proxy).
Realtime - WebSocket collection subscriptions with consumer groups.
Durable workflows - workflow() / step() authoring, WorkflowWorker, signals, sleeps, parallel, rollback, event-sourced recovery.
Replication - list known replicas; sticky replica routing via X-Replica-Id.

Compatibility

Wire-compatible with the VSKI server (vski) and equivalent to the TypeScript @vski/sdk. License: VSKI License v1.0 - see LICENSE.

Testing

The tests/ directory is a full port of the TypeScript e2e suites (test/e2e/ and test/e2e-replica/) - 98 scenarios covering every feature, including the complete durable-workflow matrix (signals, sleeps, retries, parallel, saga rollback, circuit breakers, child workflows, recovery) and replication. The pytest harness builds/locates vski-prod, starts a fresh server per session, and tears it down (process-group managed).

# Run the core e2e suite (master on :3001)
pytest tests/e2e/

# Run the replication suite (master on :3001 + replica on :3002)
pytest tests/e2e_replica/

Set VSKI_BINARY, API_URL, or VSKI_REUSE_SERVER=1 to target a specific or already-running server.

Improvements over the TypeScript SDK

Unified VskiError (status + parsed message) instead of per-namespace throw new Error(text()).
Configurable request timeout + retries on transient errors (the TS SDK had none).
Lazily-cached namespace singletons (TS rebuilt every namespace on each access).
Realtime supports multiple subscriptions per collection (TS overwrote prior callbacks).
Concurrency-safe workflow context via contextvars (TS fell back to a global in browsers).
Fixed 500ms duration parsing (TS checked s before ms, misparsing it as 500s).
Enforced worker concurrency cap (TS accepted but ignored it).

Requires Python: >=3.11

Details

PyPI

2026-10-24 13:44:50 +00:00

Project website

VSKI License v1.0 Copyright (c) 2025 Anton A Nesterov <an+vski@vski.sh> This VSKI License (the "License") governs your use of the software provided hereunder (the "Software"). By using, copying, modifying, or distributing the Software, you accept and agree to be bound by the terms of this License. 1. Definitions "Entity" shall mean any individual, corporation, partnership, or other legal entity, and includes all other entities that control, are controlled by, or are under common control with that entity. "Annual Gross Revenue" shall mean all revenue received by an Entity from all sources worldwide during its most recently completed fiscal year, measured in United States Dollars ($USD). "Total Capital Raised" shall mean the cumulative total of all funds received by an Entity in exchange for equity, debt instruments convertible to equity, grants, or any other form of investment, measured in United States Dollars ($USD). "Derivative Work" shall mean: (i) any work based on the Software, including any modification, translation, or adaptation that incorporates a substantial portion of the Software's source code; or (ii) any work, in whole or in part, generated by an artificial intelligence system where the Software (or any portion thereof) was used as input, training data, or reference. "Excluded Work" shall mean a separate and independent software work, such as a third-party plugin or extension, which interoperates with the Software through its designated Application Programming Interfaces (APIs) but is not otherwise a Derivative Work. "Integration" means the act of connecting, linking, merging, or interfacing the Software or a Derivative Work with any other software, application, or system. This includes, but is not limited to, the use of Application Programming Interfaces (APIs) or any other method that enables interoperation. 2. Free License Grant Subject to the terms and conditions of this License, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license is hereby granted to any Entity that meets neither of the conditions set forth in Section 3, to use, copy, modify, merge, publish, and/or distribute copies of the Software. 3. Commercial License Required Use, modification, or distribution of the Software by or for any Entity is prohibited without a separate, paid commercial license issued by this License copyright holders if the Entity meets either of the following conditions: a. Its Annual Gross Revenue is one million US dollars ($1,000,000 USD) or more; OR b. Its Total Capital Raised is one million US dollars ($1,000,000 USD) or more. The commercial licenses may only be issued by this VSKI License copyright holders. Creators of any Derivative Work are expressly prohibited from granting commercial licenses for such works. Terms, costs, and additional agreements for commercial licenses may be negotiated individually. 4. Copyleft and Distribution Conditions Any distribution of the Software, or any Derivative Work, is subject to the following conditions: a. It must be licensed under the terms of this VSKI License. b. The above copyright notice and the full text of this License must be included in all copies or substantial portions of the Software or Derivative Work. c. For the avoidance of doubt, creating and distributing an Excluded Work that interoperates with the Software does not, by itself, subject the Excluded Work to the terms of this License. d. For the avoidance of doubt, the Integration of the Software is not considered Excluded Work. Any such Integration remains subject to all terms and conditions set in Section 3. e. Providing the functionality of the Software or a Derivative Work as part of a commercial Software-as-a-Service (SaaS) product constitutes distribution and is subject to the conditions defined in Section 3. 6. Disclaimer of Warranty THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

182 KiB

Assets (2)

vski_sdk-0.7.0-py3-none-any.whl 66 KiB

vski_sdk-0.7.0.tar.gz 116 KiB

Versions (7) View all

0.7.0

2026-10-24

0.6.0

2026-10-22

0.5.0

2026-10-22

0.4.1

2026-10-21

0.4.0