Official Python SDK for Vilvik, a cloud platform for running and tracking optimization jobs through a REST API, with scoped keys and webhook delivery. Vilvik currently runs Genetic Algorithm (PyGAD) workloads, and this SDK gives your Python code a typed client, a submit-and-wait helper, and a clean error hierarchy to drive them.
Documentation: SDK guide · REST API reference · all docs
pip install vilvik
import vilvik client = vilvik.Client(api_key="vlk_live_…") submission = client.submissions.create( fitness_func=""" def fitness_func(ga_instance, solution, idx): return -sum(s * s for s in solution) """, num_genes=5, num_generations=100, sol_per_pop=50, num_parents_mating=4, name="quadratic-minimisation", ) print(submission.id, submission.status) # "abc123…", "queued" result = client.results.wait_for(submission.id, timeout=300) print(result.best_fitness, result.best_solution)
For scripts and notebook cells, vilvik.run(...) packages create-and-wait
into a context manager that also cancels the run if you exit the block
early:
import vilvik fn = """ def fitness_func(ga_instance, solution, idx): return -sum(s * s for s in solution) """ with vilvik.run(fitness_func=fn, num_genes=5, num_generations=50, sol_per_pop=10, num_parents_mating=4) as result: print(result.best_fitness)
The API key is read from VILVIK_API_KEY if you do not pass it
explicitly.
Quick submission types let you run a built-in problem without writing a
fitness function. Set submission_type and pass that problem's inputs.
You can leave num_generations and sol_per_pop unset, and the quick
type applies its own defaults:
import vilvik client = vilvik.Client(api_key="vlk_live_…") # Find a subset of the integers that sums to the target. submission = client.submissions.create( submission_type="quick_binary_subset_sum", integers=[3, 7, 1, 9, 4, 2, 8, 5], target=20, ) # A 0/1 knapsack with explicit items and a single capacity dimension. submission = client.submissions.create( submission_type="quick_knapsack", item_names=["map", "compass", "water", "rope"], item_values=[5, 8, 3, 4], item_weights=[[2], [1], [3], [2]], dimension_names=["weight"], dimension_capacities=[5], )
When you ask the service to generate the inputs for you (for example
passing num_integers instead of an explicit integers list), the
response echoes what it picked under submission.generated:
submission = client.submissions.create( submission_type="quick_binary_subset_sum", num_integers=8, target=20, ) print(submission.generated) # {"integers": [...]}
The machine learning types tune model hyperparameters with a genetic
algorithm. Over the API they run on a built-in dataset only (dataset_name
is iris, breast_cancer, or random); training on your own uploaded
data is available on the website but not yet over the API or SDK:
submission = client.submissions.create( submission_type="quick_sklearn_rfc_hyperparameters", dataset_name="iris", hyperparameters={ "n_estimators": {"tune": True, "min": 50, "max": 150}, "max_depth": {"fixed": 10}, }, )
The list endpoints return a Page whose items are typed dataclasses; for
walking everything use iter_all:
page = client.submissions.list(limit=25) for sub in page: print(sub.id, sub.status, sub.name) # All submissions, transparently following the cursor: for sub in client.submissions.iter_all(): ...
Results.continue_run branches a fresh run from a finished result. Each
call creates a child submission whose parent_submission is the result
you forked from. Pass any GA parameter you want to override:
parent = client.results.get(result_id) variant_a = client.results.continue_run(parent.id, mutation_probability=0.10) variant_b = client.results.continue_run(parent.id, sol_per_pop=100)
The Vilvik dashboard renders the resulting lineage as an interactive tree on the result page.
Every SDK error inherits from vilvik.VilvikError. Subclasses let you
catch specific failure modes:
try: client.submissions.get("does-not-exist") except vilvik.NotFoundError as e: print("Not found:", e.request_id) except vilvik.RateLimitError as e: print("Slow down, retry after", e.retry_after, "seconds") except vilvik.AuthenticationError: print("Check your API key and scopes") except vilvik.VilvikError: print("Something else went wrong")
| Argument | Default | Notes |
|---|---|---|
api_key |
os.environ["VILVIK_API_KEY"] |
Required. Bearer token created in the dashboard. |
base_url |
https://vilvik.com/api/v1 |
Override for staging or self-hosted instances. |
timeout |
60.0 seconds |
Per-HTTP-request timeout. |
max_retries |
2 |
Idempotent (GET / HEAD) retries on network errors. |
The full SDK guide lives at https://vilvik.com/docs/sdk/, with a page per feature:
- Installation and configuration
- Submissions,
results, and the
run()helper - Importing a local PyGAD run, code uploads, and webhooks
- Error handling and worked examples
Every SDK page links to the matching REST API reference, so you can drop down to the raw HTTP calls whenever you need to.
pip install -e ".[dev]"
pytestMIT.