vilvik 0.1.0__py3-none-any.whl

vilvik/__init__.py

@@ -0,0 +1,56 @@
+"""Vilvik — Python SDK for the Vilvik genetic-algorithm cloud API.
+
+Quick start:
+
+    import vilvik
+
+    client = vilvik.Client(api_key="vlk_live_…")
+    sub = client.submissions.create(
+        fitness_func="def fitness_func(ga_instance, solution, idx):\\n    return -sum(s*s for s in solution)",
+        num_genes=5,
+        num_generations=50,
+        sol_per_pop=30,
+    )
+    print(sub.id, sub.status_url)
+
+    # Block until the run finishes and inspect the best fitness:
+    result = client.results.wait_for(sub.id, timeout=600)
+    print(result.best_fitness, result.best_solution)
+
+For one-shot scripts, the context-managed `vilvik.run(...)` helper
+combines submit + wait:
+
+    with vilvik.run(api_key="vlk_live_…", fitness_func=fn, num_genes=5) as r:
+        print(r.best_fitness)
+"""
+
+from vilvik.client import Client
+from vilvik.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+    VilvikError,
+)
+from vilvik.models import CodeUpload, Result, Submission, Webhook
+from vilvik.run import run
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "Client",
+    "CodeUpload",
+    "NotFoundError",
+    "RateLimitError",
+    "Result",
+    "Submission",
+    "TimeoutError",
+    "ValidationError",
+    "VilvikError",
+    "Webhook",
+    "run",
+]
+
+__version__ = "0.1.0"

vilvik/_http.py

@@ -0,0 +1,151 @@
+"""Shared HTTP plumbing for `vilvik.Client`.
+
+Kept separate from `client.py` so the resource sub-clients (Submissions,
+Results, CodeUploads, Webhooks) can each consume a thin transport object
+without circular imports.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+import requests
+
+from vilvik.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://vilvik.com/api/v1"
+DEFAULT_TIMEOUT_SECONDS = 60.0
+DEFAULT_USER_AGENT = "vilvik-python/0.1.0"
+
+logger = logging.getLogger("vilvik")
+
+
+class Transport:
+    """Wraps `requests.Session` with auth, retry, and error translation."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        session: Optional[requests.Session] = None,
+        user_agent: str = DEFAULT_USER_AGENT,
+        max_retries: int = 2,
+    ):
+        if not api_key:
+            raise ValueError(
+                "api_key is required. Pass it explicitly or set VILVIK_API_KEY.",
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self.max_retries = max(0, int(max_retries))
+        self.session = session or requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        attempt = 0
+        while True:
+            try:
+                resp = self.session.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    data=json.dumps(json_body) if json_body is not None else None,
+                    headers=headers,
+                    timeout=timeout or self.timeout,
+                )
+            except requests.RequestException as exc:
+                if attempt < self.max_retries and method.upper() in {"GET", "HEAD"}:
+                    attempt += 1
+                    sleep_for = 0.5 * (2 ** (attempt - 1))
+                    logger.warning(
+                        "vilvik: network error on %s %s, retrying in %.1fs (%s)",
+                        method,
+                        path,
+                        sleep_for,
+                        exc,
+                    )
+                    time.sleep(sleep_for)
+                    continue
+                raise APIError(
+                    status_code=0,
+                    code="network_error",
+                    message=str(exc),
+                ) from exc
+
+            # The server may return non-JSON on infrastructure errors (e.g.
+            # 502 from a load balancer). Treat those as APIError without
+            # trying to decode the body.
+            try:
+                payload = resp.json() if resp.content else {}
+            except ValueError:
+                payload = {"raw_body": resp.text[:1000]}
+
+            if 200 <= resp.status_code < 300:
+                return payload
+
+            self._raise_for_status(resp, payload)
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response, payload: Dict[str, Any]) -> None:
+        status = resp.status_code
+        # Vilvik's API errors come back as {"error": {"code": "...", "message": "...", "request_id": "..."}}.
+        # Fall back to top-level keys if a proxy returned a different envelope.
+        err = payload.get("error") if isinstance(payload, dict) else None
+        if not isinstance(err, dict):
+            err = payload if isinstance(payload, dict) else {}
+        code = str(err.get("code") or "")
+        message = str(err.get("message") or err.get("detail") or "")
+        request_id = str(err.get("request_id") or resp.headers.get("X-Request-Id") or "")
+
+        if status in (401, 403):
+            raise AuthenticationError(status, code, message, request_id, payload)
+        if status == 404:
+            raise NotFoundError(status, code, message, request_id, payload)
+        if status in (400, 422):
+            raise ValidationError(status, code, message, request_id, payload)
+        if status == 429:
+            retry_after_raw = resp.headers.get("Retry-After")
+            try:
+                retry_after = int(retry_after_raw) if retry_after_raw else None
+            except (TypeError, ValueError):
+                retry_after = None
+            raise RateLimitError(
+                status, code, message, request_id, payload, retry_after=retry_after,
+            )
+        raise APIError(status, code, message, request_id, payload)
+
+    @staticmethod
+    def make_idempotency_key() -> str:
+        return str(uuid.uuid4())

vilvik/client.py

@@ -0,0 +1,294 @@
+"""High-level entrypoint: `vilvik.Client`.
+
+Modelled after `stripe.StripeClient` — one top-level object that
+namespaces resources (`client.submissions`, `client.results`, …). Each
+resource class is a thin wrapper over `Transport` that converts JSON
+into the dataclasses in `vilvik.models`.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, Iterable, Iterator, List, Optional
+
+from vilvik._http import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, Transport
+from vilvik.exceptions import TimeoutError as VilvikTimeout
+from vilvik.models import CodeUpload, Page, Result, Submission, Webhook
+
+
+class _Resource:
+    """Base for resource sub-clients — holds a reference to the transport."""
+
+    def __init__(self, transport: Transport):
+        self._t = transport
+
+
+class Submissions(_Resource):
+    """Endpoints under `/api/v1/submissions`."""
+
+    def create(
+        self,
+        *,
+        fitness_func: Optional[str] = None,
+        num_genes: Optional[int] = None,
+        num_generations: int = 100,
+        sol_per_pop: int = 50,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        submission_type: str = "new",
+        webhook_url: Optional[str] = None,
+        notification_email: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        **ga_params: Any,
+    ) -> Submission:
+        """POST /submissions — enqueue a new GA run.
+
+        Extra `ga_params` are forwarded as-is so callers can pass any of
+        the PyGAD knobs (`mutation_probability`, `parent_selection_type`,
+        `gene_space`, …) without the SDK having to enumerate them.
+        """
+        body: Dict[str, Any] = {
+            "num_generations": num_generations,
+            "sol_per_pop": sol_per_pop,
+            "submission_type": submission_type,
+        }
+        if fitness_func is not None:
+            body["fitness_func"] = fitness_func
+        if num_genes is not None:
+            body["num_genes"] = num_genes
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        if notification_email is not None:
+            body["notification_email"] = notification_email
+        body.update({k: v for k, v in ga_params.items() if v is not None})
+
+        payload = self._t.request(
+            "POST",
+            "/submissions",
+            json_body=body,
+            idempotency_key=idempotency_key or Transport.make_idempotency_key(),
+        )
+        return Submission.from_api(payload)
+
+    def get(self, submission_id: str) -> Submission:
+        payload = self._t.request("GET", f"/submissions/{submission_id}")
+        return Submission.from_api(payload)
+
+    def list(self, *, cursor: Optional[str] = None, limit: int = 25) -> Page:
+        params: Dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        payload = self._t.request("GET", "/submissions", params=params)
+        items = [Submission.from_api(row) for row in payload.get("data", [])]
+        return Page(items=items, next_cursor=payload.get("next_cursor"), raw=payload)
+
+    def iter_all(self, *, limit: int = 25) -> Iterator[Submission]:
+        """Generator that follows `next_cursor` until exhausted."""
+        cursor: Optional[str] = None
+        while True:
+            page = self.list(cursor=cursor, limit=limit)
+            for item in page:
+                yield item
+            if not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    def delete(self, submission_id: str) -> None:
+        self._t.request("DELETE", f"/submissions/{submission_id}")
+
+    def reexecute(
+        self,
+        submission_id: str,
+        *,
+        idempotency_key: Optional[str] = None,
+        **overrides: Any,
+    ) -> Submission:
+        """POST /submissions/{id}/reexecute — re-run with optional overrides."""
+        payload = self._t.request(
+            "POST",
+            f"/submissions/{submission_id}/reexecute",
+            json_body=overrides or None,
+            idempotency_key=idempotency_key or Transport.make_idempotency_key(),
+        )
+        return Submission.from_api(payload)
+
+
+class Results(_Resource):
+    """Endpoints under `/api/v1/results`."""
+
+    def get(self, result_id: str) -> Result:
+        payload = self._t.request("GET", f"/results/{result_id}")
+        return Result.from_api(payload)
+
+    def list(
+        self,
+        *,
+        submission_id: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: int = 25,
+    ) -> Page:
+        params: Dict[str, Any] = {"limit": limit}
+        if submission_id:
+            params["submission_id"] = submission_id
+        if cursor:
+            params["cursor"] = cursor
+        payload = self._t.request("GET", "/results", params=params)
+        items = [Result.from_api(row) for row in payload.get("data", [])]
+        return Page(items=items, next_cursor=payload.get("next_cursor"), raw=payload)
+
+    def continue_run(
+        self,
+        result_id: str,
+        *,
+        idempotency_key: Optional[str] = None,
+        **overrides: Any,
+    ) -> Submission:
+        """POST /results/{id}/continue — branch a fresh run from a finished result."""
+        payload = self._t.request(
+            "POST",
+            f"/results/{result_id}/continue",
+            json_body=overrides or None,
+            idempotency_key=idempotency_key or Transport.make_idempotency_key(),
+        )
+        return Submission.from_api(payload)
+
+    def wait_for(
+        self,
+        submission_id: str,
+        *,
+        timeout: float = 600.0,
+        poll_interval: float = 3.0,
+    ) -> Result:
+        """Block until the submission terminates, then return its first result.
+
+        Polls `GET /submissions/{id}` every `poll_interval` seconds.
+        Raises `vilvik.TimeoutError` if `timeout` is exceeded; raises
+        `vilvik.APIError` (subclass `vilvik.exceptions.APIError`) wrapping
+        the API failure if the submission ended in `failed`.
+        """
+        from vilvik.exceptions import APIError as _APIError
+
+        deadline = time.monotonic() + timeout
+        while True:
+            sub = Submissions(self._t).get(submission_id)
+            if sub.is_terminal:
+                if sub.status == "failed":
+                    raise _APIError(
+                        status_code=0,
+                        code="submission_failed",
+                        message=f"Submission {submission_id} ended with status 'failed'.",
+                    )
+                if sub.status == "cancelled":
+                    raise _APIError(
+                        status_code=0,
+                        code="submission_cancelled",
+                        message=f"Submission {submission_id} was cancelled.",
+                    )
+                page = self.list(submission_id=submission_id, limit=1)
+                if not page.items:
+                    raise _APIError(
+                        status_code=0,
+                        code="result_not_found",
+                        message=(
+                            f"Submission {submission_id} reported '{sub.status}' "
+                            "but no result row was returned."
+                        ),
+                    )
+                return page.items[0]
+
+            if time.monotonic() >= deadline:
+                raise VilvikTimeout(
+                    f"Timed out after {timeout:.0f}s waiting for submission "
+                    f"{submission_id} (last status: {sub.status!r}).",
+                )
+            time.sleep(poll_interval)
+
+
+class CodeUploads(_Resource):
+    """Endpoints under `/api/v1/code-uploads`."""
+
+    def create(self, *, field: str, code: str) -> CodeUpload:
+        payload = self._t.request(
+            "POST",
+            "/code-uploads",
+            json_body={"field": field, "code": code},
+        )
+        return CodeUpload.from_api(payload)
+
+    def get(self, code_id: str) -> CodeUpload:
+        return CodeUpload.from_api(self._t.request("GET", f"/code-uploads/{code_id}"))
+
+    def list(self, *, cursor: Optional[str] = None, limit: int = 25) -> Page:
+        params: Dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        payload = self._t.request("GET", "/code-uploads", params=params)
+        items = [CodeUpload.from_api(row) for row in payload.get("data", [])]
+        return Page(items=items, next_cursor=payload.get("next_cursor"), raw=payload)
+
+
+class Webhooks(_Resource):
+    """Read-only listing of webhook subscriptions for this account.
+
+    Mutations (create / update / delete / test / replay) currently live
+    behind the dashboard's CSRF-protected endpoints rather than the
+    public REST surface. They will land here once exposed under
+    `/api/v1/webhooks`.
+    """
+
+    def list(self) -> List[Webhook]:
+        payload = self._t.request("GET", "/webhooks")
+        items = payload.get("data") if isinstance(payload, dict) else payload
+        return [Webhook.from_api(row) for row in (items or [])]
+
+
+class Client:
+    """Top-level Vilvik client.
+
+    Parameters
+    ----------
+    api_key:
+        Required. Pass explicitly or set the `VILVIK_API_KEY` env var.
+    base_url:
+        Override for self-hosted or staging deployments.
+    timeout:
+        Per-request timeout in seconds.
+    session:
+        Pre-built `requests.Session` (useful for connection pooling or
+        custom adapters / mounts during testing).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        session: Any = None,
+        max_retries: int = 2,
+    ):
+        resolved_key = api_key or os.environ.get("VILVIK_API_KEY", "")
+        self._transport = Transport(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            session=session,
+            max_retries=max_retries,
+        )
+        self.submissions = Submissions(self._transport)
+        self.results = Results(self._transport)
+        self.code_uploads = CodeUploads(self._transport)
+        self.webhooks = Webhooks(self._transport)
+
+    @property
+    def base_url(self) -> str:
+        return self._transport.base_url
+
+    def health(self) -> Dict[str, Any]:
+        """GET /health — liveness probe; returns the raw envelope."""
+        return self._transport.request("GET", "/health")

vilvik/exceptions.py

@@ -0,0 +1,81 @@
+"""Typed exception hierarchy for the Vilvik SDK.
+
+All SDK errors derive from `VilvikError` so applications can `except
+VilvikError` to catch every SDK failure in one place. Specific subclasses
+let callers branch on the kind of failure (auth, validation, rate limit,
+etc.) without inspecting status codes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class VilvikError(Exception):
+    """Base class for every SDK-raised error."""
+
+
+class TimeoutError(VilvikError):
+    """A polling helper (e.g. `Results.wait_for`) exceeded its deadline."""
+
+
+class APIError(VilvikError):
+    """A non-2xx HTTP response from the Vilvik API.
+
+    Attributes
+    ----------
+    status_code:
+        HTTP status returned by the server.
+    code:
+        Stable machine-readable error code (e.g. "validation_failed").
+        Empty string if the server did not return one.
+    message:
+        Human-readable summary.
+    request_id:
+        The `X-Request-Id` echoed back by the API (or empty when missing).
+        Useful to quote in support requests.
+    payload:
+        The full decoded JSON body, when available, for debugging.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str = "",
+        message: str = "",
+        request_id: str = "",
+        payload: Optional[Dict[str, Any]] = None,
+    ):
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.payload = payload or {}
+        detail = message or code or f"HTTP {status_code}"
+        if request_id:
+            detail = f"{detail} (request_id={request_id})"
+        super().__init__(detail)
+
+
+class AuthenticationError(APIError):
+    """401 / 403 — invalid, revoked, expired, or under-scoped API key."""
+
+
+class NotFoundError(APIError):
+    """404 — the resource does not exist or is not visible to this key."""
+
+
+class ValidationError(APIError):
+    """400 / 422 — the request body failed server-side validation."""
+
+
+class RateLimitError(APIError):
+    """429 — too many requests for this key's rate limit window.
+
+    `retry_after` is seconds reported by the server's Retry-After header,
+    or `None` when the server didn't advise one.
+    """
+
+    def __init__(self, *args, retry_after: Optional[int] = None, **kwargs):
+        self.retry_after = retry_after
+        super().__init__(*args, **kwargs)

vilvik/models.py

@@ -0,0 +1,155 @@
+"""Typed dataclasses for the public surface of the Vilvik API.
+
+Each `from_api()` classmethod is lenient on missing keys so a server-side
+addition does not break older SDK builds. New keys not yet modelled here
+are preserved on `raw` for forward compatibility.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+def _parse_dt(value: Any) -> Optional[datetime]:
+    """Parse an ISO-8601 timestamp; return None when missing or malformed."""
+    if not value:
+        return None
+    if isinstance(value, datetime):
+        return value
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass
+class Submission:
+    """A queued, running, or completed GA run."""
+
+    id: str
+    status: str
+    status_url: str = ""
+    result_url: str = ""
+    name: Optional[str] = None
+    description: Optional[str] = None
+    submission_type: Optional[str] = None
+    created_at: Optional[datetime] = None
+    request_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_terminal(self) -> bool:
+        """True once the server-side run has reached a final state.
+
+        Mirrors the public status mapping in `apiapp.v1.status_mapping`:
+        `succeeded`, `failed`, and `cancelled` are terminal; `queued` and
+        `running` are not.
+        """
+        return self.status in {"succeeded", "failed", "cancelled"}
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "Submission":
+        return cls(
+            id=str(data.get("id", "")),
+            status=str(data.get("status", "")),
+            status_url=str(data.get("status_url", "") or ""),
+            result_url=str(data.get("result_url", "") or ""),
+            name=data.get("name"),
+            description=data.get("description"),
+            submission_type=data.get("submission_type"),
+            created_at=_parse_dt(data.get("created_at")),
+            request_id=data.get("request_id"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class Result:
+    """The outcome row associated with a finished submission."""
+
+    id: str
+    submission_id: str
+    best_fitness: Optional[float] = None
+    best_solution: Optional[List[Any]] = None
+    num_generations_ran: Optional[int] = None
+    stopped_reason: Optional[str] = None
+    created_at: Optional[datetime] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "Result":
+        return cls(
+            id=str(data.get("id", "")),
+            submission_id=str(data.get("submission_id", "")),
+            best_fitness=data.get("best_fitness"),
+            best_solution=data.get("best_solution"),
+            num_generations_ran=data.get("num_generations_ran"),
+            stopped_reason=data.get("stopped_reason"),
+            created_at=_parse_dt(data.get("created_at")),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class CodeUpload:
+    """A reusable code blob that submissions can reference by id.
+
+    The model attribute is named `field_name` rather than `field` to
+    avoid shadowing `dataclasses.field` inside the class body.
+    """
+
+    id: str
+    field_name: str = ""
+    size_bytes: Optional[int] = None
+    created_at: Optional[datetime] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "CodeUpload":
+        return cls(
+            id=str(data.get("id", "")),
+            field_name=str(data.get("field", "") or ""),
+            size_bytes=data.get("size_bytes"),
+            created_at=_parse_dt(data.get("created_at")),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class Webhook:
+    """A user-configured webhook endpoint."""
+
+    id: str
+    url: str = ""
+    event_types: List[str] = field(default_factory=list)
+    is_active: bool = True
+    created_at: Optional[datetime] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "Webhook":
+        return cls(
+            id=str(data.get("id", "")),
+            url=str(data.get("url", "") or ""),
+            event_types=list(data.get("event_types") or []),
+            is_active=bool(data.get("is_active", True)),
+            created_at=_parse_dt(data.get("created_at")),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class Page:
+    """One page of a cursor-paginated list response."""
+
+    items: List[Any]
+    next_cursor: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __len__(self):
+        return len(self.items)

vilvik/run.py

@@ -0,0 +1,66 @@
+"""Context-managed one-shot helper: `vilvik.run(...)`.
+
+Lets a script submit a run and block until it finishes in a single
+expression — the workflow most users actually want in a Jupyter cell:
+
+    with vilvik.run(fitness_func=fn, num_genes=5) as result:
+        print(result.best_fitness)
+
+The context manager handles client construction, submission, and the
+polling loop. On exit (success or exception) it tries to cancel the run
+if it has not yet reached a terminal state, so a Ctrl-C in a notebook
+does not leave a hot run on the server.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+from vilvik.client import Client
+from vilvik.exceptions import APIError
+
+
+@contextmanager
+def run(
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    timeout: float = 600.0,
+    poll_interval: float = 3.0,
+    **submission_kwargs: Any,
+) -> Iterator[Any]:
+    """Submit a run, block on completion, and yield the resulting `Result`.
+
+    Any keyword not consumed by the context manager itself is forwarded
+    to `Client.submissions.create(...)` — so `fitness_func`, `num_genes`,
+    `num_generations`, `sol_per_pop`, plus any extra PyGAD params all
+    work here directly.
+    """
+    client_kwargs: dict = {}
+    if api_key is not None:
+        client_kwargs["api_key"] = api_key
+    if base_url is not None:
+        client_kwargs["base_url"] = base_url
+    client = Client(**client_kwargs)
+
+    submission = client.submissions.create(**submission_kwargs)
+    try:
+        result = client.results.wait_for(
+            submission.id,
+            timeout=timeout,
+            poll_interval=poll_interval,
+        )
+        yield result
+    finally:
+        # Best-effort cancel if the user exited the block early (Ctrl-C,
+        # exception, etc.) before the run had a chance to finish. The
+        # API does not currently expose a public cancel endpoint, so we
+        # try DELETE — failures are silently swallowed because the
+        # submission may already be terminal.
+        try:
+            latest = client.submissions.get(submission.id)
+            if not latest.is_terminal:
+                client.submissions.delete(submission.id)
+        except APIError:
+            pass

vilvik-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+vilvik/__init__.py,sha256=RgCJZ9zGzpPNeHuTzl2FC33QUSYh4z-8LkWvJ5PmJYA,1370
+vilvik/_http.py,sha256=ljLx2PcHQYZfqQndXoUnlov9zuaygFiysomnMDrGaoc,5340
+vilvik/client.py,sha256=N8LypnqZAG4subfA4SeXE21tpdgCX92HkYZHnPAC5b8,10608
+vilvik/exceptions.py,sha256=MEC8vtD_0Dgwn6jDMiUi5pOCWuPT8X9UiUyuqzFc7gE,2419
+vilvik/models.py,sha256=yZ4k2ohVIKfiaClhZuVTaAqB2OdmOioDOvWtbvqXWIU,4804
+vilvik/run.py,sha256=diWXW6SuWhqi6m3QVMsmysEnZRiQwIKL6t9Le8BNpOQ,2289
+vilvik-0.1.0.dist-info/METADATA,sha256=sVPRVyc6ot4uyTxgFJxD3twbEx15wuF9LhTBdci6Bis,4708
+vilvik-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vilvik-0.1.0.dist-info/top_level.txt,sha256=W9FSlc5ZA_rc_jGCl6R4dV8S4-lyFs_VNCdWTJMzSdw,7
+vilvik-0.1.0.dist-info/RECORD,,

vilvik-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vilvik-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vilvik