vilvik 0.1.0__tar.gz

vilvik-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: vilvik
+Version: 0.1.0
+Summary: Official Python SDK for the Vilvik genetic-algorithm cloud API.
+Author-email: Vilvik <ahmed.f.gad@gmail.com>
+License: MIT
+Project-URL: Homepage, https://vilvik.com
+Project-URL: Documentation, https://vilvik.com/docs
+Project-URL: Repository, https://github.com/ahmedfgad/vilvik
+Project-URL: Issues, https://github.com/ahmedfgad/vilvik/issues
+Keywords: genetic-algorithm,optimization,pygad,vilvik
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# vilvik
+
+Official Python SDK for [Vilvik](https://vilvik.com) — a cloud platform that
+runs Genetic Algorithm (PyGAD) workloads with a REST API, scoped keys, and
+webhook delivery.
+
+```bash
+pip install vilvik
+```
+
+## Quick start
+
+```python
+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,
+    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)
+```
+
+## The `run()` one-liner
+
+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:
+
+```python
+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) as result:
+    print(result.best_fitness)
+```
+
+The API key is read from `VILVIK_API_KEY` if you do not pass it
+explicitly.
+
+## Listing and pagination
+
+The list endpoints return a `Page` whose items are typed dataclasses; for
+walking everything use `iter_all`:
+
+```python
+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():
+    ...
+```
+
+## Branching a finished run
+
+`B7 — branching run-graph` is exposed via `Results.continue_run`. Each
+call creates a child submission whose `parent_submission` is the result
+you forked from. Pass any GA parameter you want to override:
+
+```python
+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.
+
+## Errors
+
+Every SDK error inherits from `vilvik.VilvikError`. Subclasses let you
+catch specific failure modes:
+
+```python
+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")
+```
+
+## Configuration
+
+| 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. |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT.

vilvik-0.1.0/README.md

@@ -0,0 +1,122 @@
+# vilvik
+
+Official Python SDK for [Vilvik](https://vilvik.com) — a cloud platform that
+runs Genetic Algorithm (PyGAD) workloads with a REST API, scoped keys, and
+webhook delivery.
+
+```bash
+pip install vilvik
+```
+
+## Quick start
+
+```python
+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,
+    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)
+```
+
+## The `run()` one-liner
+
+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:
+
+```python
+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) as result:
+    print(result.best_fitness)
+```
+
+The API key is read from `VILVIK_API_KEY` if you do not pass it
+explicitly.
+
+## Listing and pagination
+
+The list endpoints return a `Page` whose items are typed dataclasses; for
+walking everything use `iter_all`:
+
+```python
+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():
+    ...
+```
+
+## Branching a finished run
+
+`B7 — branching run-graph` is exposed via `Results.continue_run`. Each
+call creates a child submission whose `parent_submission` is the result
+you forked from. Pass any GA parameter you want to override:
+
+```python
+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.
+
+## Errors
+
+Every SDK error inherits from `vilvik.VilvikError`. Subclasses let you
+catch specific failure modes:
+
+```python
+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")
+```
+
+## Configuration
+
+| 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. |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT.

vilvik-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vilvik"
+version = "0.1.0"
+description = "Official Python SDK for the Vilvik genetic-algorithm cloud API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Vilvik", email = "ahmed.f.gad@gmail.com" }]
+keywords = ["genetic-algorithm", "optimization", "pygad", "vilvik"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+async = ["httpx>=0.24"]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+    "responses>=0.23",
+]
+
+[project.urls]
+Homepage = "https://vilvik.com"
+Documentation = "https://vilvik.com/docs"
+Repository = "https://github.com/ahmedfgad/vilvik"
+Issues = "https://github.com/ahmedfgad/vilvik/issues"
+
+[tool.setuptools.packages.find]
+include = ["vilvik*"]
+exclude = ["tests*"]

vilvik-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vilvik-0.1.0/tests/test_client.py

@@ -0,0 +1,379 @@
+"""Unit tests for `vilvik.Client` and its resource sub-clients."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import pytest
+
+import vilvik
+from vilvik.client import Client
+
+BASE = "https://example.test/api/v1"
+
+
+# --------------- Construction / config ---------------
+
+
+def test_client_requires_api_key(monkeypatch):
+    monkeypatch.delenv("VILVIK_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        Client()
+
+
+def test_client_reads_api_key_from_env(monkeypatch):
+    monkeypatch.setenv("VILVIK_API_KEY", "vlk_from_env")
+    c = Client(base_url=BASE)
+    # Smoke check: no exception means the env var was picked up.
+    assert c.base_url == BASE
+
+
+# --------------- Submissions ---------------
+
+
+def test_submissions_create_round_trip(mock_api, client):
+    mock_api.add(
+        "POST",
+        f"{BASE}/submissions",
+        json={
+            "id": "sub_abc",
+            "status": "queued",
+            "status_url": f"{BASE}/submissions/sub_abc",
+            "result_url": f"{BASE}/results?submission_id=sub_abc",
+            "created_at": "2026-05-18T10:00:00Z",
+            "request_id": "req_1",
+        },
+        status=202,
+    )
+
+    sub = client.submissions.create(
+        fitness_func="def fitness_func(g, s, i): return 0",
+        num_genes=3,
+        num_generations=10,
+        sol_per_pop=20,
+    )
+
+    assert sub.id == "sub_abc"
+    assert sub.status == "queued"
+    assert not sub.is_terminal
+    assert sub.created_at is not None
+
+    call = mock_api.calls[0]
+    assert call.request.headers["Authorization"] == f"Bearer {client._transport.api_key}"
+    assert call.request.headers["Idempotency-Key"]
+    body = json.loads(call.request.body)
+    assert body["num_genes"] == 3
+    assert body["num_generations"] == 10
+    assert body["fitness_func"].startswith("def fitness_func")
+
+
+def test_submissions_create_forwards_extra_ga_params(mock_api, client):
+    mock_api.add(
+        "POST",
+        f"{BASE}/submissions",
+        json={"id": "sub_x", "status": "queued"},
+        status=202,
+    )
+    client.submissions.create(
+        fitness_func="x",
+        num_genes=1,
+        mutation_probability=0.05,
+        parent_selection_type="tournament",
+    )
+    body = json.loads(mock_api.calls[0].request.body)
+    assert body["mutation_probability"] == 0.05
+    assert body["parent_selection_type"] == "tournament"
+
+
+def test_submissions_get(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_abc",
+        json={"id": "sub_abc", "status": "succeeded"},
+    )
+    sub = client.submissions.get("sub_abc")
+    assert sub.is_terminal
+    assert sub.status == "succeeded"
+
+
+def test_submissions_list_and_iter_all(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions",
+        json={
+            "data": [
+                {"id": "a", "status": "queued"},
+                {"id": "b", "status": "running"},
+            ],
+            "next_cursor": "cur_2",
+        },
+    )
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions",
+        json={
+            "data": [{"id": "c", "status": "succeeded"}],
+            "next_cursor": None,
+        },
+    )
+    ids = [s.id for s in client.submissions.iter_all()]
+    assert ids == ["a", "b", "c"]
+
+
+def test_submissions_reexecute_sends_overrides(mock_api, client):
+    mock_api.add(
+        "POST",
+        f"{BASE}/submissions/sub_abc/reexecute",
+        json={"id": "sub_def", "status": "queued"},
+        status=202,
+    )
+    client.submissions.reexecute("sub_abc", mutation_probability=0.2)
+    body = json.loads(mock_api.calls[0].request.body)
+    assert body == {"mutation_probability": 0.2}
+
+
+def test_submissions_delete(mock_api, client):
+    mock_api.add("DELETE", f"{BASE}/submissions/sub_abc", status=204)
+    # Must not raise.
+    assert client.submissions.delete("sub_abc") is None
+
+
+# --------------- Results ---------------
+
+
+def test_results_get(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/results/res_1",
+        json={
+            "id": "res_1",
+            "submission_id": "sub_abc",
+            "best_fitness": -0.0123,
+            "best_solution": [1, 2, 3],
+            "num_generations_ran": 100,
+        },
+    )
+    r = client.results.get("res_1")
+    assert r.best_fitness == pytest.approx(-0.0123)
+    assert r.best_solution == [1, 2, 3]
+    assert r.num_generations_ran == 100
+
+
+def test_results_continue_run(mock_api, client):
+    mock_api.add(
+        "POST",
+        f"{BASE}/results/res_1/continue",
+        json={"id": "sub_child", "status": "queued"},
+        status=202,
+    )
+    child = client.results.continue_run("res_1", sol_per_pop=200)
+    assert child.id == "sub_child"
+    body = json.loads(mock_api.calls[0].request.body)
+    assert body == {"sol_per_pop": 200}
+
+
+def test_wait_for_returns_result_when_submission_succeeds(mock_api, client, monkeypatch):
+    monkeypatch.setattr("vilvik.client.time.sleep", lambda *_a, **_k: None)
+    # First poll: still running. Second poll: succeeded. Then list returns one row.
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_abc",
+        json={"id": "sub_abc", "status": "running"},
+    )
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_abc",
+        json={"id": "sub_abc", "status": "succeeded"},
+    )
+    mock_api.add(
+        "GET",
+        f"{BASE}/results",
+        json={
+            "data": [
+                {"id": "res_1", "submission_id": "sub_abc", "best_fitness": 7.0},
+            ],
+            "next_cursor": None,
+        },
+    )
+    r = client.results.wait_for("sub_abc", timeout=5, poll_interval=0)
+    assert r.best_fitness == 7.0
+
+
+def test_wait_for_raises_on_failed_submission(mock_api, client, monkeypatch):
+    monkeypatch.setattr("vilvik.client.time.sleep", lambda *_a, **_k: None)
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_bad",
+        json={"id": "sub_bad", "status": "failed"},
+    )
+    with pytest.raises(vilvik.APIError) as info:
+        client.results.wait_for("sub_bad", timeout=5, poll_interval=0)
+    assert info.value.code == "submission_failed"
+
+
+def test_wait_for_times_out(mock_api, client, monkeypatch):
+    # Two stubbed responses, both "running" — the deadline will trigger first.
+    monkeypatch.setattr("vilvik.client.time.sleep", lambda *_a, **_k: None)
+    # responses replays the last match if exhausted; we set monotonic to
+    # walk past the deadline on the second call.
+    times = iter([0.0, 0.0, 999.0])
+    monkeypatch.setattr("vilvik.client.time.monotonic", lambda: next(times))
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_x",
+        json={"id": "sub_x", "status": "running"},
+    )
+    with pytest.raises(vilvik.TimeoutError):
+        client.results.wait_for("sub_x", timeout=1, poll_interval=0)
+
+
+# --------------- Code uploads & webhooks ---------------
+
+
+def test_code_upload_create(mock_api, client):
+    mock_api.add(
+        "POST",
+        f"{BASE}/code-uploads",
+        json={"id": "code_1", "field": "fitness_func", "size_bytes": 42},
+        status=201,
+    )
+    blob = client.code_uploads.create(
+        field="fitness_func",
+        code="def fitness_func(g, s, i): return 0",
+    )
+    assert blob.id == "code_1"
+    assert blob.field_name == "fitness_func"
+
+
+def test_webhooks_list(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/webhooks",
+        json={
+            "data": [
+                {"id": "wh_1", "url": "https://example.test/hook",
+                 "event_types": ["submission.completed"]},
+            ],
+        },
+    )
+    hooks = client.webhooks.list()
+    assert hooks[0].id == "wh_1"
+    assert "submission.completed" in hooks[0].event_types
+
+
+# --------------- Error translation ---------------
+
+
+def test_authentication_error_translation(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_abc",
+        json={"error": {"code": "invalid_key", "message": "bad key",
+                        "request_id": "req_z"}},
+        status=401,
+    )
+    with pytest.raises(vilvik.AuthenticationError) as info:
+        client.submissions.get("sub_abc")
+    assert info.value.code == "invalid_key"
+    assert info.value.request_id == "req_z"
+    assert info.value.status_code == 401
+
+
+def test_rate_limit_error_picks_up_retry_after(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions",
+        json={"error": {"code": "rate_limited", "message": "slow down"}},
+        status=429,
+        headers={"Retry-After": "7"},
+    )
+    with pytest.raises(vilvik.RateLimitError) as info:
+        client.submissions.list()
+    assert info.value.retry_after == 7
+
+
+def test_not_found_error(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/ghost",
+        json={"error": {"code": "not_found", "message": "missing"}},
+        status=404,
+    )
+    with pytest.raises(vilvik.NotFoundError):
+        client.submissions.get("ghost")
+
+
+def test_validation_error(mock_api, client):
+    mock_api.add(
+        "POST",
+        f"{BASE}/submissions",
+        json={"error": {"code": "validation_failed",
+                        "message": "num_genes is required"}},
+        status=400,
+    )
+    with pytest.raises(vilvik.ValidationError):
+        client.submissions.create(num_generations=10)
+
+
+def test_generic_api_error_for_5xx(mock_api, client):
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_abc",
+        json={"error": {"code": "upstream", "message": "boom"}},
+        status=502,
+    )
+    with pytest.raises(vilvik.APIError) as info:
+        client.submissions.get("sub_abc")
+    assert info.value.status_code == 502
+    # Not auth/notfound/validation/ratelimit.
+    assert not isinstance(info.value, vilvik.AuthenticationError)
+    assert not isinstance(info.value, vilvik.NotFoundError)
+    assert not isinstance(info.value, vilvik.ValidationError)
+    assert not isinstance(info.value, vilvik.RateLimitError)
+
+
+# --------------- run() context manager ---------------
+
+
+def test_run_context_manager_yields_result(mock_api, monkeypatch):
+    monkeypatch.setattr("vilvik.client.time.sleep", lambda *_a, **_k: None)
+    monkeypatch.setenv("VILVIK_API_KEY", "vlk_test_env")
+    mock_api.add(
+        "POST",
+        f"{BASE}/submissions",
+        json={"id": "sub_quick", "status": "queued"},
+        status=202,
+    )
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_quick",
+        json={"id": "sub_quick", "status": "succeeded"},
+    )
+    mock_api.add(
+        "GET",
+        f"{BASE}/results",
+        json={
+            "data": [{"id": "res_q", "submission_id": "sub_quick",
+                      "best_fitness": 1.5}],
+            "next_cursor": None,
+        },
+    )
+    # The submission lookup at __exit__ time finds a terminal run, so no
+    # DELETE is issued — `assert_all_requests_are_fired=False` keeps the
+    # mock from complaining about unused matchers.
+    mock_api.add(
+        "GET",
+        f"{BASE}/submissions/sub_quick",
+        json={"id": "sub_quick", "status": "succeeded"},
+    )
+
+    with vilvik.run(
+        base_url=BASE,
+        fitness_func="x",
+        num_genes=2,
+        poll_interval=0,
+        timeout=5,
+    ) as result:
+        assert result.id == "res_q"
+        assert result.best_fitness == 1.5