Docs

Home All sections Swagger

The vilvik.run helper

One-shot context manager that submits, waits, and cleans up.

Last updated June 3, 2026

vilvik.run(...) is a shortcut for the most common pattern: submit a run, wait for it, then use the result. It is designed for scripts and notebooks where you do not want to manage a Client by hand.

Basic use

import vilvik

with vilvik.run(
    fitness_func="def fitness_func(ga, sol, idx): return -sum(s*s for s in sol)\n",
    num_genes=5,
    num_generations=50,
) as result:
    print(result.best_fitness, result.best_solution)

The helper:

  1. Builds a Client (reading VILVIK_API_KEY from the environment).
  2. Calls client.submissions.create(...) with the keyword arguments you pass.
  3. Calls client.results.wait_for(...) until the run finishes.
  4. Yields the resulting Result into the with block.
  5. On exit (including when you raise from inside the block) it best-effort cancels the submission if it has not yet finished. A Ctrl-C in a notebook will not leave a run burning credits in the background.

Arguments

Argument Default What it does
api_key None Optional override. Falls back to VILVIK_API_KEY from the environment.
base_url None Optional override for staging or self-hosted instances.
timeout 600.0 (seconds) How long to wait for the run before raising vilvik.TimeoutError.
poll_interval 3.0 (seconds) How often the helper polls the submission while waiting.
any other keyword - Forwarded to client.submissions.create(...), so fitness_func, num_genes, num_generations, sol_per_pop, submission_type, and any GA parameter all work directly.

Quick submission example

with vilvik.run(
    submission_type="quick_knapsack",
    num_generations=50,
    item_names=["gold", "silver"],
    item_values=[10, 6],
    item_weights=[[3], [2]],
    dimension_names=["weight"],
    dimension_capacities=[5],
) as result:
    print(result.best_solution)

When to use the helper vs the full client

vilvik.run(...) is ideal for a single run in a single script or notebook cell. For anything that does more than that (parallel submissions, custom retry logic, paginated history, mixing in webhooks), build a Client directly. See Submissions.

Thanks for the feedback!