veep 0.4.2__py3-none-any.whl

veep/__init__.py

@@ -0,0 +1,112 @@
+"""veep -- Python SDK for Vector Panda vector search.
+
+Module structure and method signatures:
+
+    from veep import VP
+
+    vp = VP(api_key="...", verbose=True)
+
+    # Collections (resource-based)
+    vp.collections.create("my_collection", tier="hot")    -> Collection
+    vp.collections.get("my_collection")                   -> Collection
+    vp.collections.list()                                 -> list[Collection]
+    vp.collections.delete("my_collection")                -> None
+    vp.collections.status("my_collection")                -> str
+
+    # Vectors / files
+    vp.vectors.upsert("col", "data.parquet")              -> UploadResult  (file)
+    vp.vectors.upsert("col", vectors=[{...}])             -> UploadResult  (inline)
+    vp.vectors.upsert("col", dataframe=df)                -> UploadResult  (DataFrame)
+    vp.vectors.replace("col", "data.parquet")             -> UploadResult
+    vp.vectors.query("col", [0.1, ...])                   -> QueryResults
+    vp.vectors.query("col", [0.1, ...], filter={...})     -> QueryResults  (filtered)
+    vp.vectors.query_batch([...])                         -> list[QueryResults]
+    vp.vectors.delete("col", "data.parquet")              -> None  (file delete)
+    vp.vectors.delete("col", ids=["k1", "k2"])            -> dict  (id delete)
+    vp.vectors.list_files("col")                          -> list[FileInfo]
+
+    # Schema
+    vp.schema.get("my_collection")                        -> SchemaInfo
+    vp.schema.confirm("my_collection", id_field, vec_field) -> dict
+
+    # Health
+    vp.ping()                                             -> bool
+
+    # Authentication (device flow + credential persistence)
+    vp = VP.login()                                       # interactive OAuth via browser
+    vp = VP.from_creds()                                  # load ~/.veep/credentials.json
+    vp.save()                                             # persist api_key for later
+
+API endpoints (all through consumer-site .120):
+    POST   /api/v1/collections                              create collection
+    GET    /api/v1/collections                              list collections
+    GET    /api/v1/collections/:name                        get collection detail
+    GET    /api/v1/collections/:name/status                 lightweight status
+    DELETE /api/v1/collections/:name                        delete collection
+    POST   /api/v1/collections/:name/files/:filename        upload file (multipart)
+    PUT    /api/v1/collections/:name/files/:filename        replace file (multipart)
+    DELETE /api/v1/collections/:name/files/:filename        delete file
+    GET    /api/v1/collections/:name/files                  list files
+    GET    /api/v1/collections/:name/schema                 get schema
+    POST   /api/v1/collections/:name/schema/confirm         confirm schema
+    POST   /api/v1/query                                    single query
+    POST   /api/v1/query/batch                              batch query
+    GET    /api/v1/health                                   health check
+"""
+
+from __future__ import annotations
+
+from .client import VP
+from .collections import Collections
+from .exceptions import (
+    AuthError,
+    CollectionAlreadyExistsError,
+    CollectionNotFoundError,
+    CollectionNotReadyError,
+    FileAlreadyExistsError,
+    NotFoundError,
+    QueryError,
+    ServerError,
+    TimeoutError,
+    UploadError,
+    ValidationError,
+    VeepError,
+)
+from .models import (
+    Collection,
+    FetchResult,
+    FileInfo,
+    QueryResults,
+    Result,
+    SchemaInfo,
+    UploadResult,
+)
+from .vectors import Vectors
+
+__version__ = "0.4.2"
+
+__all__ = [
+    "VP",
+    "Collections",
+    "Vectors",
+    "AuthError",
+    "Collection",
+    "CollectionAlreadyExistsError",
+    "CollectionNotFoundError",
+    "CollectionNotReadyError",
+    "FetchResult",
+    "FileAlreadyExistsError",
+    "FileInfo",
+    "NotFoundError",
+    "QueryError",
+    "QueryResults",
+    "Result",
+    "SchemaInfo",
+    "ServerError",
+    "TimeoutError",
+    "UploadError",
+    "UploadResult",
+    "ValidationError",
+    "VeepError",
+    "__version__",
+]

veep/auth.py

@@ -0,0 +1,211 @@
+"""Device authorization flow and credential persistence for veep.
+
+Enables fully programmatic login from Python/Jupyter without
+manually copying API keys:
+
+    from veep import VP
+    vp = VP.login()  # opens browser, completes OAuth, returns client
+
+Credentials are saved to ~/.veep/credentials.json and reused
+on subsequent sessions via VP.from_creds().
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+import requests
+
+logger = logging.getLogger("veep")
+
+CREDENTIALS_DIR = Path.home() / ".veep"
+CREDENTIALS_FILE = CREDENTIALS_DIR / "credentials.json"
+
+DEFAULT_HOST = "https://api.vectorpanda.com"
+
+
+def save_credentials(api_key: str, host: str | None = None, **extra: Any) -> Path:
+    """Save API key and host to ~/.veep/credentials.json.
+
+    Args:
+        api_key: The API key to save.
+        host: The API host URL. Defaults to the Vector Panda cloud.
+        **extra: Additional fields to store (e.g., client_id).
+
+    Returns:
+        Path to the credentials file.
+    """
+    CREDENTIALS_DIR.mkdir(parents=True, exist_ok=True)
+    data = {"api_key": api_key, "host": host or DEFAULT_HOST, **extra}
+    CREDENTIALS_FILE.write_text(json.dumps(data, indent=2) + "\n")
+    CREDENTIALS_FILE.chmod(0o600)
+    logger.info("Credentials saved to %s", CREDENTIALS_FILE)
+    return CREDENTIALS_FILE
+
+
+def load_credentials() -> dict | None:
+    """Load saved credentials from ~/.veep/credentials.json.
+
+    Returns:
+        Dict with at least 'api_key' and 'host', or None if not found.
+    """
+    if not CREDENTIALS_FILE.exists():
+        return None
+    try:
+        data = json.loads(CREDENTIALS_FILE.read_text())
+        if "api_key" in data:
+            return data
+    except (json.JSONDecodeError, OSError):
+        pass
+    return None
+
+
+def clear_credentials() -> None:
+    """Remove saved credentials."""
+    if CREDENTIALS_FILE.exists():
+        CREDENTIALS_FILE.unlink()
+        logger.info("Credentials cleared")
+
+
+def _is_notebook() -> bool:
+    """Detect if running in a Jupyter/IPython notebook."""
+    try:
+        from IPython import get_ipython
+        shell = get_ipython()
+        if shell is None:
+            return False
+        return shell.__class__.__name__ == "ZMQInteractiveShell"
+    except ImportError:
+        return False
+
+
+def _display_link(url: str, user_code: str) -> None:
+    """Display the verification URL — clickable in notebooks, printed in terminals."""
+    if _is_notebook():
+        try:
+            from IPython.display import HTML, display
+            display(HTML(
+                f'<p>Open this link to sign in: <a href="{url}" target="_blank">{url}</a></p>'
+                f'<p>Your confirmation code: <b>{user_code}</b></p>'
+            ))
+            return
+        except ImportError:
+            pass
+    print(f"\nOpen this URL to sign in:\n  {url}\n")
+    print(f"Your confirmation code: {user_code}\n")
+
+
+def device_login(
+    host: str | None = None,
+    open_browser: bool = True,
+    timeout_s: int = 300,
+) -> dict:
+    """Run the device authorization flow.
+
+    1. Requests a device code from the server
+    2. Opens the verification URL in a browser (or prints it)
+    3. Polls until the user completes OAuth in the browser
+    4. Returns {"api_key": ..., "client_id": ..., "host": ...}
+
+    Args:
+        host: API base URL. Defaults to VEEP_HOST env var or Vector Panda cloud.
+        open_browser: Whether to automatically open the browser. Default True.
+        timeout_s: How long to wait for the user to complete login. Default 300s.
+
+    Returns:
+        Dict with api_key, client_id, and host.
+
+    Raises:
+        TimeoutError: If the user doesn't complete login in time.
+        ServerError: If the device flow is not supported or fails.
+    """
+    from .exceptions import ServerError, TimeoutError
+
+    host = (host or os.environ.get("VEEP_HOST", DEFAULT_HOST)).rstrip("/")
+
+    # Step 1: Request device code
+    try:
+        resp = requests.post(
+            f"{host}/api/v1/auth/device",
+            json={},
+            timeout=10,
+        )
+    except requests.exceptions.ConnectionError:
+        raise ServerError(
+            f"Could not connect to {host}. "
+            f"Check that the host is correct and the service is running."
+        ) from None
+
+    if resp.status_code != 200:
+        raise ServerError(
+            f"Device login not available at {host}. "
+            f"You may need to update your server or use VP(api_key=...) instead.",
+            status_code=resp.status_code,
+        )
+
+    data = resp.json()
+    device_code = data["device_code"]
+    user_code = data["user_code"]
+    verification_url = data["verification_url"]
+    interval = data.get("interval", 5)
+    expires_in = data.get("expires_in", timeout_s)
+
+    # Step 2: Show the URL to the user
+    _display_link(verification_url, user_code)
+
+    if open_browser:
+        try:
+            webbrowser.open(verification_url)
+            print("Browser opened. Complete sign-in there, then return here.")
+        except Exception:
+            print("Could not open browser automatically. Please open the URL above.")
+
+    print("Waiting for sign-in...", end="", flush=True)
+
+    # Step 3: Poll for completion
+    deadline = time.time() + min(expires_in, timeout_s)
+    while time.time() < deadline:
+        time.sleep(interval)
+        print(".", end="", flush=True)
+
+        try:
+            poll_resp = requests.post(
+                f"{host}/api/v1/auth/device/token",
+                json={"device_code": device_code},
+                timeout=10,
+            )
+        except requests.exceptions.RequestException:
+            continue
+
+        if poll_resp.status_code == 200:
+            result = poll_resp.json()
+            print(" done!\n")
+            logger.info("Login successful. Client ID: %s", result.get("client_id"))
+            return {
+                "api_key": result["api_key"],
+                "client_id": result.get("client_id", ""),
+                "host": host,
+            }
+
+        if poll_resp.status_code == 400:
+            body = poll_resp.json()
+            error = body.get("error", "")
+            if error == "authorization_pending":
+                continue
+            if error == "expired_token":
+                break
+            if error == "access_denied":
+                print(" denied.\n")
+                raise ServerError("Login was denied by the user.")
+
+    print(" timed out.\n")
+    raise TimeoutError(
+        f"Login was not completed within {timeout_s} seconds. "
+        f"Run VP.login() again to retry."
+    )