mllm-annotator 0.1.0__py3-none-any.whl

mllm_annotator/__init__.py

@@ -0,0 +1,33 @@
+"""mllm-annotator: resumable multimodal-LLM media annotation and embedding.
+
+Gemini is the first (and currently only) backend; the public surface is kept
+backend-agnostic so additional providers can be added later.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .config import (
+    BACKENDS,
+    Backend,
+    ConfigError,
+    clear_api_key,
+    get_api_key,
+    has_api_key,
+    store_api_key,
+)
+from .core import MediaItem, RateLimitReached
+
+__all__ = [
+    "__version__",
+    "BACKENDS",
+    "Backend",
+    "ConfigError",
+    "MediaItem",
+    "RateLimitReached",
+    "get_api_key",
+    "has_api_key",
+    "store_api_key",
+    "clear_api_key",
+]

mllm_annotator/config.py

@@ -0,0 +1,151 @@
+"""API key resolution and secure storage, per backend.
+
+For each backend, a key is resolved in order from:
+
+1. an environment variable (e.g. ``GEMINI_API_KEY`` / ``GOOGLE_API_KEY``);
+2. a ``.env`` file in the current working directory;
+3. the OS keyring (Windows Credential Manager / macOS Keychain / Secret
+   Service), where the GUI stores keys the user enters.
+
+The keyring is optional at runtime: if the ``keyring`` package or its backend
+is unavailable, resolution silently falls back to the environment/``.env``.
+
+Backends are registered in ``BACKENDS``. Gemini is the only one today; adding
+another is just a new ``Backend`` entry plus its client wiring — key storage,
+resolution, and the GUI dialog all pick it up automatically.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+KEYRING_SERVICE = "mllm-annotator"
+
+
+class ConfigError(Exception):
+    """Raised when user-provided inputs are inconsistent or incomplete."""
+
+
+@dataclass(frozen=True)
+class Backend:
+    """A model provider that needs an API key."""
+
+    id: str
+    label: str
+    env_vars: tuple[str, ...]
+
+
+GEMINI = Backend(
+    id="gemini",
+    label="Google Gemini",
+    env_vars=("GEMINI_API_KEY", "GOOGLE_API_KEY"),
+)
+
+BACKENDS: dict[str, Backend] = {GEMINI.id: GEMINI}
+DEFAULT_BACKEND = GEMINI.id
+
+
+def _backend(backend_id: str) -> Backend:
+    try:
+        return BACKENDS[backend_id]
+    except KeyError:
+        raise ConfigError(f"Unknown backend: {backend_id}") from None
+
+
+def load_env_file(path: Path) -> None:
+    """Load ``KEY=VALUE`` lines from *path* into os.environ (real env wins)."""
+    if not path.exists() or not path.is_file():
+        return
+    for raw_line in path.read_text(encoding="utf-8-sig").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key:
+            os.environ.setdefault(key, value)
+
+
+def _keyring() -> Any | None:
+    """Return the keyring module, or None if it (or its backend) is unusable."""
+    try:
+        import keyring
+    except Exception:
+        return None
+    return keyring
+
+
+def _keyring_get(backend_id: str) -> str | None:
+    kr = _keyring()
+    if kr is None:
+        return None
+    try:
+        return kr.get_password(KEYRING_SERVICE, backend_id)
+    except Exception:
+        return None
+
+
+def _env_key(backend: Backend) -> str | None:
+    load_env_file(Path.cwd() / ".env")
+    for var in backend.env_vars:
+        value = os.environ.get(var)
+        if value:
+            return value
+    return None
+
+
+def get_api_key(backend_id: str = DEFAULT_BACKEND) -> str:
+    """Return the API key for *backend_id*, or raise ConfigError with guidance."""
+    backend = _backend(backend_id)
+    key = _env_key(backend) or _keyring_get(backend.id)
+    if key:
+        return key
+    raise ConfigError(
+        f"No API key set for {backend.label}. Set {' or '.join(backend.env_vars)}, "
+        "add it to a .env file, or save it in the app (the 'Set API Key' button, "
+        "top-left)."
+    )
+
+
+def key_source(backend_id: str = DEFAULT_BACKEND) -> str | None:
+    """Where *backend_id*'s key comes from: 'environment', 'keyring', or None."""
+    backend = _backend(backend_id)
+    if _env_key(backend):
+        return "environment"
+    if _keyring_get(backend.id):
+        return "keyring"
+    return None
+
+
+def has_api_key(backend_id: str = DEFAULT_BACKEND) -> bool:
+    return key_source(backend_id) is not None
+
+
+def store_api_key(key: str, backend_id: str = DEFAULT_BACKEND) -> None:
+    """Persist *key* for *backend_id* in the OS keyring."""
+    _backend(backend_id)  # validate
+    kr = _keyring()
+    if kr is None:
+        raise ConfigError(
+            "Cannot save the API key: the 'keyring' package or its OS backend is "
+            "unavailable. Set an environment variable or use a .env file instead."
+        )
+    try:
+        kr.set_password(KEYRING_SERVICE, backend_id, key)
+    except Exception as exc:  # noqa: BLE001 - surface backend failures clearly.
+        raise ConfigError(f"Could not save the API key to the keyring: {exc}") from exc
+
+
+def clear_api_key(backend_id: str = DEFAULT_BACKEND) -> None:
+    """Remove *backend_id*'s key from the OS keyring (best effort)."""
+    kr = _keyring()
+    if kr is None:
+        return
+    try:
+        kr.delete_password(KEYRING_SERVICE, backend_id)
+    except Exception:
+        pass