Python SDK overview · Vilvik docs

The official Python SDK wraps the API overview so your code can submit runs, read results, and react to webhooks without writing HTTP calls by hand. If you already work in Python, this is the easiest way to drive Vilvik.

The package is open source: install it from PyPI, and browse or contribute to the code on GitHub.

What you get¶

A typed Client that handles authentication, retries, and JSON parsing.
Friendly resources: client.submissions, client.results, client.code_uploads, client.webhooks.
Typed return values (Submission, Result, CodeUpload, Webhook, Page) so editors and type checkers help you.
A vilvik.run(...) context manager that submits and waits in a single block of code.
A clean exception hierarchy that lets you catch authentication, validation, and rate-limit failures separately.

Quick start¶

Install the package and set your API key. Full setup is in Installation and authentication.

pip install vilvik
export VILVIK_API_KEY=vlk_live_...

Then submit a job:

import vilvik

client = vilvik.Client()  # reads VILVIK_API_KEY from the environment

submission = client.submissions.create(
    name="sphere min, 5 genes",
    fitness_func=(
        "def fitness_func(ga, sol, idx):\n"
        "    return -sum(s*s for s in sol)\n"
    ),
    num_genes=5,
    num_generations=50,
    sol_per_pop=30,
)

print(submission.id, submission.status_url)

result = client.results.wait_for(submission.id, timeout=600)
print(result.best_fitness, result.best_solution)

One-shot variant for notebooks:

with vilvik.run(fitness_func=fn, num_genes=5) as result:
    print(result.best_fitness)

When to use the SDK vs the raw REST API¶

Pick the SDK when	Pick the REST API when
You write in Python.	You write in another language (JavaScript, Go, Rust, etc.).
You want typed responses and clean exceptions.	You want full control over the HTTP layer.
You want a built-in waiter, paginator, and retry policy.	You already use your own HTTP client and want to keep it.

Both surfaces share the same API keys, the same scopes, and the same rate limits. You can mix them: a script can list submissions through the SDK and post a webhook reply with whatever HTTP client your framework already loads.

Where to go next¶

Installation and authentication for install, configuration, and authentication.
Submissions to create and manage submissions.
Results to fetch and wait for results.
The vilvik.run helper for the one-shot context manager.
End-to-end examples for end-to-end recipes.
Errors and exceptions for the exception hierarchy.

Docs

What you get¶

Quick start¶

When to use the SDK vs the raw REST API¶

Where to go next¶

Related pages¶