End-to-end examples · Vilvik docs

Copy-paste-ready snippets that combine several SDK calls. Each one assumes you have already installed the package and exported VILVIK_API_KEY (see Installation and authentication).

Custom fitness, wait for the result¶

import vilvik

client = vilvik.Client()

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

print("Submitted:", submission.id, "->", submission.status_url)

result = client.results.wait_for(submission.id, timeout=900)
print("Best fitness:", result.best_fitness)
print("Best solution:", result.best_solution)

Travelling salesman with demo data¶

import vilvik

with vilvik.run(
    submission_type="quick_travelling_salesman_demo_parameters",
    num_generations=300,
    name="tsp demo",
) as result:
    print("Tour length:", -result.best_fitness)
    print("City order:", result.best_solution)

Knapsack with your own items¶

import vilvik

with vilvik.run(
    submission_type="quick_knapsack",
    num_generations=100,
    name="weekend hike",
    item_names=["tent", "stove", "sleep bag", "rope", "water"],
    item_values=[8, 5, 7, 3, 6],
    item_weights=[[4], [2], [3], [1], [2]],
    dimension_names=["weight"],
    dimension_capacities=[7],
) as result:
    print("Items chosen:", result.best_solution)

Re-execute the same submission¶

When a run had random behaviour and you want another sample:

import vilvik

client = vilvik.Client()

second = client.submissions.reexecute("abcDEF123456")
result_2 = client.results.wait_for(second.id)
print("Second-run best fitness:", result_2.best_fitness)

Continue from a finished run¶

Branch a new submission from the final population of a finished one:

import vilvik

client = vilvik.Client()

child = client.results.continue_run(
    "res_abc123",
    num_generations=100,
    mutation_probability=0.05,
)
result = client.results.wait_for(child.id)
print("Continued run finished:", result.best_fitness)

See Continue a submission for the broader picture.

Paginate every submission¶

import vilvik

client = vilvik.Client()

for sub in client.submissions.iter_all(limit=100):
    print(sub.created_at, sub.id, sub.name, sub.status)

Webhook plus SDK pickup¶

Send a webhook so your service learns when a run completes, then read the full result:

import vilvik

client = vilvik.Client()

sub = client.submissions.create(
    fitness_func=src,
    num_genes=5,
    webhook_url="https://example.com/vilvik/done",
)

# Later, inside your webhook handler:
result = client.results.list(submission_id=sub.id, limit=1).items[0]
print(result.best_fitness)

See Webhooks for the payload shape.

Robust error handling¶

import time
import vilvik

client = vilvik.Client()

def submit_with_backoff(**kwargs):
    delay = 1.0
    while True:
        try:
            return client.submissions.create(**kwargs)
        except vilvik.RateLimitError as exc:
            wait = exc.retry_after or delay
            print(f"Rate-limited; sleeping {wait:.0f}s")
            time.sleep(wait)
            delay = min(delay * 2, 60)
        except vilvik.AuthenticationError:
            raise SystemExit("Check your API key.")
        except vilvik.ValidationError as exc:
            raise SystemExit(f"Bad parameters: {exc.message} ({exc.payload})")

Reusable code blob¶

Upload a fitness function once, then re-use it across many submissions:

import vilvik

client = vilvik.Client()

blob = client.code_uploads.create(
    content=(
        "def fitness_func(ga, sol, idx):\n"
        "    return -sum((s-3)**2 for s in sol)\n"
    ),
)

for trial in range(5):
    client.submissions.create(
        name=f"shared fitness, trial {trial}",
        fitness_func_id=blob.code_id,
        fitness_func_entry="fitness_func",
        num_genes=4,
        num_generations=50,
        sol_per_pop=30,
    )

Docs