yera 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

yera/config2/keyring.py

@@ -0,0 +1,270 @@
+"""Secure credential management for Yera using system keyring.
+
+This module provides a wrapper around the system keyring for storing and
+retrieving credentials securely. It maintains a manifest of stored keys
+and validates key formats to ensure consistency across the application.
+
+"""
+
+import contextlib
+import json
+import re
+
+import keyring
+from keyring.backends.fail import Keyring as FailKeyring
+from keyring.errors import KeyringError, NoKeyringError, PasswordDeleteError
+
+
+class DevKeyring:
+    """Manages secure credential storage using the system keyring.
+
+    DevKeyring provides a high-level interface for storing, retrieving, and
+    managing credentials in the system keyring. It maintains a manifest of
+    all stored keys to enable listing and bulk operations, and enforces a
+    consistent key naming scheme.
+
+    All credentials are stored under the service name "yera" and use a
+    dot-separated hierarchical key format (e.g., 'providers.anthropic.api_key').
+
+    Attributes:
+        SERVICE_NAME: The service identifier used for all keyring operations.
+        MANIFEST_KEY: The special key used to store the list of credential keys.
+        KEY_PATTERN: Regex pattern for validating credential key formats.
+    """
+
+    SERVICE_NAME = "yera"
+    MANIFEST_KEY = "_yera_manifest"
+    KEY_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*$")
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """Check if a valid keyring backend is available.
+
+        Determines whether the system has a functional keyring backend
+        that can be used for credential storage. Returns False if only
+        the fail backend is available or if there are keyring errors.
+
+        Returns:
+            bool: True if a valid keyring backend is available, False otherwise.
+
+        """
+        try:
+            backend = keyring.get_keyring()
+            return not isinstance(backend, FailKeyring)
+        except (NoKeyringError, KeyringError):
+            return False
+
+    @classmethod
+    def _validate_key(cls, key: str) -> None:
+        if not key or not key.strip():
+            raise ValueError("Credential key cannot be empty")
+        if not cls.KEY_PATTERN.match(key):
+            raise ValueError(
+                f"Invalid key format: '{key}'. "
+                "Key must contain only letters, numbers, underscores, and hyphens, "
+                "with parts separated by dots (e.g., 'providers.anthropic.api_key')"
+            )
+
+    @classmethod
+    def _get_manifest(cls) -> set[str]:
+        with contextlib.suppress(KeyError, json.JSONDecodeError):
+            manifest_json = keyring.get_password(cls.SERVICE_NAME, cls.MANIFEST_KEY)
+            if manifest_json:
+                return set(json.loads(manifest_json))
+        return set()
+
+    @classmethod
+    def _save_manifest(cls, keys: set[str]) -> None:
+        with contextlib.suppress(KeyringError):
+            keyring.set_password(
+                cls.SERVICE_NAME, cls.MANIFEST_KEY, json.dumps(list(keys))
+            )
+
+    @classmethod
+    def _add_to_manifest(cls, key: str) -> None:
+        manifest = cls._get_manifest()
+        manifest.add(key)
+        cls._save_manifest(manifest)
+
+    @classmethod
+    def _remove_from_manifest(cls, key: str) -> None:
+        manifest = cls._get_manifest()
+        manifest.discard(key)
+        cls._save_manifest(manifest)
+
+    @classmethod
+    def get_backend_info(cls) -> str:
+        """Get information about the current keyring backend.
+
+        Returns a string describing the active keyring backend, including
+        its name and priority level. Useful for debugging credential storage
+        issues.
+
+        Returns:
+            str: Backend name and priority (e.g., "macOS Keychain (5)"),
+                or "No backend available" if no valid backend exists.
+
+        Example:
+            >>> print(DevKeyring.get_backend_info())
+            macOS Keychain (5)
+        """
+        if cls.is_available():
+            backend = keyring.get_keyring()
+            return f"{backend.name} ({backend.priority})"
+        return "No backend available"
+
+    @classmethod
+    def set(cls, key: str, value: str) -> None:
+        """Store a credential in the keyring.
+
+        Saves a credential value associated with the given key. The key is
+        automatically added to the manifest for tracking purposes.
+
+        Args:
+            key: Credential identifier following the format requirements
+                (alphanumeric, underscores, hyphens, dot-separated).
+            value: The credential value to store (e.g., API key, password).
+
+        Raises:
+            ValueError: If the key format is invalid or if key/value is empty.
+            KeyringError: If the keyring backend fails to store the credential.
+
+        Example:
+            >>> DevKeyring.set('providers.anthropic.api_key', 'sk-ant-...')
+            >>> DevKeyring.set('databases.my_db.password', 'secret123')
+        """
+        cls._validate_key(key)
+        if not value or not value.strip():
+            raise ValueError("Credential value cannot be empty")
+        keyring.set_password(cls.SERVICE_NAME, key.strip(), value.strip())
+        cls._add_to_manifest(key)
+
+    @classmethod
+    def get(cls, key: str) -> str:
+        """Retrieve a credential from the keyring.
+
+        Fetches the credential value associated with the given key.
+
+        Args:
+            key: Credential identifier to retrieve.
+
+        Returns:
+            str: The credential value associated with the key.
+
+        Raises:
+            ValueError: If the key format is invalid or if no credential
+                exists for the given key.
+
+        Example:
+            >>> api_key = DevKeyring.get('providers.anthropic.api_key')
+            >>> print(api_key)
+            sk-ant-...
+        """
+        cls._validate_key(key)
+        try:
+            cred = keyring.get_password(cls.SERVICE_NAME, key)
+        except KeyringError:
+            cred = None
+
+        if cred:
+            return cred
+        raise ValueError(f"No credentials found for {key}") from None
+
+    @classmethod
+    def delete(cls, key: str) -> None:
+        """Delete a credential from the keyring.
+
+        Removes the credential associated with the given key and updates
+        the manifest accordingly. Safe to call even if the key doesn't exist.
+
+        Args:
+            key: Credential identifier to delete.
+
+        Raises:
+            ValueError: If the key format is invalid.
+            RuntimeError: If the keyring backend fails to delete the credential.
+
+        Example:
+            >>> DevKeyring.delete('providers.anthropic.api_key')
+        """
+        cls._validate_key(key)
+        try:
+            keyring.delete_password(cls.SERVICE_NAME, key)
+            cls._remove_from_manifest(key)
+        except PasswordDeleteError:
+            # Key doesn't exist
+            cls._remove_from_manifest(key)  # Clean up manifest anyway
+        except KeyringError as e:
+            raise RuntimeError(f"Failed to delete secret: {e}") from None
+
+    @classmethod
+    def exists(cls, key: str) -> bool:
+        """Check if a credential exists in the keyring.
+
+        Verifies whether a credential is stored for the given key without
+        retrieving its value.
+
+        Args:
+            key: Credential identifier to check.
+
+        Returns:
+            bool: True if the credential exists, False otherwise.
+
+        Raises:
+            ValueError: If the key format is invalid.
+
+        Example:
+            >>> if DevKeyring.exists('api.key'):
+            ...     print("Credential found")
+            ... else:
+            ...     print("Credential not found")
+        """
+        cls._validate_key(key)
+        try:
+            cls.get(key)
+            return True
+        except ValueError:
+            return False
+
+    @classmethod
+    def list(cls) -> list[str]:
+        """List all stored credential keys.
+
+        Returns a sorted list of all credential keys currently stored in
+        the keyring, as tracked by the manifest.
+
+        Returns:
+            list[str]: Sorted list of credential keys. Returns an empty
+                list if no credentials are stored.
+
+        Example:
+            >>> keys = DevKeyring.list()
+            >>> print(keys)
+            ['database.password', 'providers.anthropic.api_key']
+        """
+        return sorted(cls._get_manifest())
+
+    @classmethod
+    def delete_all(cls) -> None:
+        """Delete all credentials managed by DevKeyring.
+
+        Removes all credentials tracked in the manifest and deletes the
+        manifest itself. This operation is irreversible and will clear
+        all Yera-related credentials from the system keyring.
+
+        Note:
+            This is a best-effort operation that continues even if individual
+            deletions fail.
+
+        Example:
+            >>> DevKeyring.delete_all()  # Removes all stored credentials
+        """
+        if not cls.exists(cls.MANIFEST_KEY):
+            # Nothing to delete
+            return
+
+        for key in cls.list():
+            with contextlib.suppress(PasswordDeleteError, KeyringError):
+                cls.delete(key)
+
+        keyring.delete_password(cls.SERVICE_NAME, cls.MANIFEST_KEY)

yera/config2/paths.py

@@ -0,0 +1,28 @@
+"""Helper functions for paths."""
+
+from pathlib import Path
+
+
+def has_local_yera_toml() -> bool:
+    """Check whether there is a local yera toml file.
+
+    Local tomls are under current working directory
+
+    Returns:
+        true if present otherwise false
+    """
+    toml_path = Path.cwd() / "yera.toml"
+    return toml_path.exists()
+
+
+def has_global_yera_toml() -> bool:
+    """Check whether there is a global yera toml file.
+
+    global tomls are under the user home/.config/yera directory
+
+    Returns:
+        true if present otherwise false
+
+    """
+    toml_path = Path.home() / ".config" / "yera" / "yera.toml"
+    return toml_path.exists()

yera/config2/read.py

@@ -0,0 +1,113 @@
+"""Module for reading yera config toml."""
+
+from pathlib import Path
+
+import tomllib
+
+from yera.config2.dataclasses import YeraConfig
+
+
+def _read_toml(use_global: bool = False) -> dict:
+    """Read yera.toml configuration file.
+
+    First this function tries in CWD, then HOME/.config/yera and then errors if neither
+    are present.
+
+    Args:
+        use_global: whether to use the global config, if local is present (default:
+        False).
+
+    Returns:
+        dict: yera.toml content loaded into a dictionary
+
+    """
+    toml_path = Path.cwd() / "yera.toml"
+    if not toml_path.exists() or use_global:
+        toml_path = Path.home() / ".config" / "yera" / "yera.toml"
+
+    if not toml_path.exists():
+        raise FileNotFoundError(
+            "No yera.toml found in current working directory or home/.config/yera"
+        )
+
+    with toml_path.open("rb") as f:
+        return tomllib.load(f)
+
+
+def _fill_config_object(config_dict: dict) -> YeraConfig:
+    """Create YeraConfig from parsed TOML dictionary.
+
+    This method flattens the nested TOML structure (models.llm.provider.model_name)
+    into the flat dictionary structure (models.llm["provider.model_name"]) and
+    adds the `id` field to each model.
+
+    Args:
+        config_dict: Dictionary from tomllib.load()
+
+    Returns:
+        Validated YeraConfig instance
+
+    """
+
+    def _flatten_nested_models(
+        nested_dict: dict, path: list[str] | None = None
+    ) -> dict:
+        if path is None:
+            path = []
+
+        flattened = {}
+
+        for k, v in nested_dict.items():
+            current_path = [*path, k]
+
+            is_leaf = isinstance(v, dict) and any(
+                not isinstance(sv, dict) for sv in v.values()
+            )
+
+            if is_leaf:
+                full_id = ".".join(current_path)
+                model_cfg = {**v, "id": full_id}
+                flattened[full_id] = model_cfg
+            elif isinstance(v, dict):
+                flattened.update(_flatten_nested_models(v, current_path))
+            else:
+                raise TypeError(
+                    f"Expected nested dicts only in models section. Encountered {type(v)}"
+                )
+        return flattened
+
+    kws = {**config_dict, "models": {}}
+
+    for model_type in config_dict["models"]:
+        kws["models"][model_type] = _flatten_nested_models(
+            config_dict["models"][model_type]
+        )
+
+    return YeraConfig(**kws)
+
+
+def read_config(use_global: bool = False) -> YeraConfig:
+    """Read and parse yera.toml configuration into a YeraConfig object.
+
+    Searches for yera.toml in the current working directory first, then falls
+    back to ~/.config/yera/yera.toml. The TOML structure is parsed and validated
+    into a YeraConfig dataclass instance.
+
+    Args:
+        use_global: If True, skip the local directory and use the global config
+            at ~/.config/yera/yera.toml even if a local config exists (default: False).
+
+    Returns:
+        Validated YeraConfig instance with flattened model configurations.
+
+    Raises:
+        FileNotFoundError: If no yera.toml is found in either location.
+        ValidationError: If the TOML structure doesn't match YeraConfig schema.
+
+    Example:
+        >>> config = read_config()  # Uses local config if available
+        >>> config = read_config(use_global=True)  # Forces global config
+
+    """
+    toml_dict = _read_toml(use_global=use_global)
+    return _fill_config_object(toml_dict)

yera/config2/setup.py

@@ -0,0 +1,109 @@
+# ruff: noqa: T201
+"""Module for setting up Yera provider configuration and credentials."""
+
+from typing import Literal
+
+from yera.config2.dataclasses import YeraConfig
+from yera.config2.read import read_config
+from yera.config2.setup_handlers.anthropic import AnthropicSetup
+from yera.config2.setup_handlers.azure import AzureSetup
+from yera.config2.setup_handlers.llama_cpp import LlamaCppSetup
+from yera.config2.setup_handlers.ollama import OllamaSetup
+from yera.config2.setup_handlers.openai import OpenAISetup
+from yera.config2.write import write_config
+
+handlers = {
+    "anthropic": AnthropicSetup(),
+    "openai": OpenAISetup(),
+    "ollama": OllamaSetup(),
+    "azure": AzureSetup(),
+    "llama-cpp": LlamaCppSetup(),
+}
+
+
+def setup(
+    location: Literal["global", "local"],
+    auto_import: bool,
+) -> None:
+    """Set up Yera provider configuration and credentials.
+
+    Configures model provider credentials by either automatically importing from
+    environment variables or prompting the user interactively. The configuration is
+    saved to the specified location and credentials are saved to the secure developer
+    keyring.
+
+    Args:
+        location: Where to save the configuration - "global" for user-wide
+            settings (~/.config/yera/config.toml) or "local" for project-specific
+            settings (./yera.toml)
+        auto_import: If True, automatically import credentials from environment
+            variables and only prompt for providers that fail auto-import. If False,
+            prompt interactively for all providers.
+
+    The function will:
+        1. Load existing config from the specified location (or create new)
+        2. Attempt auto-import if enabled, falling back to interactive prompt
+        3. Allow user to configure additional providers from a menu
+        4. Save the merged configuration to the specified location
+    """
+    try:
+        config = read_config(use_global=location == "global")
+    except FileNotFoundError:
+        config = YeraConfig()
+
+    to_ask = []
+
+    if auto_import:
+        for k, handler in handlers.items():
+            new_config = handler.automatic_setup()
+            if new_config:
+                config = config.merge(new_config)
+            else:
+                print(f"Could not find credentials for {k}")
+                to_ask.append(k)
+    else:
+        to_ask = list(handlers.keys())
+
+    user_has_quit = False
+    while not user_has_quit:
+        if len(to_ask) == 0:
+            break
+
+        print(f"There are {len(to_ask)} other providers you can set up")
+        sep = "\n * "
+        print(sep + sep.join(f"{i + 1}: {name}" for i, name in enumerate(to_ask)))
+
+        print("\nOr you can enter 0 to finish.")
+        ix = input(" > ")
+        if ix == "0":
+            break
+        handler = handlers[to_ask[int(ix) - 1]]
+        new_config = handler.interactive_setup()
+        config = config.merge(new_config)
+
+        del to_ask[int(ix) - 1]
+
+    write_config(config, location, True)
+
+
+def set_default_llm(location: Literal["global", "local"]) -> None:
+    """Interactive user flow to choose a default LLM for your configuration.
+
+    Args:
+        location: which config to read and update: global or local.
+
+    """
+    config = read_config(use_global=location == "global")
+
+    labels = [v.id for v in config.models.llm.values()]
+    print(f"You have {len(labels)} models to choose from:\n * ")
+    print("\n * ".join(labels))
+    print("Please enter your choice of default llm:")
+    choice = input(" > ")
+    while choice not in labels:
+        print(f"{choice} not in list. Please try again")
+        choice = input(" > ")
+
+    config.defaults.models.llm = choice
+    write_config(config, location, True)
+    print("Config updated.")

yera/config2/setup_handlers/__init__.py

@@ -0,0 +1 @@
+"""Module containing handler classes for finding and importing model providers."""

yera/config2/setup_handlers/anthropic.py

@@ -0,0 +1,126 @@
+# ruff: noqa: T201
+"""Configuration and credentials import handler for Anthropic."""
+
+import os
+import re
+
+from anthropic import Anthropic
+from anthropic.types import ModelInfo
+
+from yera.config2.dataclasses import CredentialsMap, LLMConfig, ModelRegistry
+from yera.config2.keyring import DevKeyring
+from yera.config2.setup_handlers.base import BaseProviderSetup
+
+
+class AnthropicSetup(BaseProviderSetup):
+    """Setup handler for Anthropic provider credentials and models.
+
+    Manages credential detection, validation, and model fetching for the
+    Anthropic API. Supports both automatic import from environment variables
+    and interactive credential entry.
+    """
+
+    def __init__(self):
+        """Initialise the Anthropic setup handler."""
+        super().__init__("anthropic")
+
+    def detect_creds(self) -> dict[str, str] | None:
+        """Detect Anthropic credentials from environment variables.
+
+        Returns:
+            Dictionary with "api_key" if ANTHROPIC_API_KEY environment variable
+            is set, otherwise None.
+        """
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if api_key:
+            return {"api_key": api_key}
+        return None
+
+    def ask_for_creds(self) -> dict[str, str] | None:
+        """Prompt user to enter Anthropic API credentials interactively.
+
+        Returns:
+            Dictionary with "api_key" if user provides credentials, otherwise
+            None if user declines to enter credentials.
+        """
+        ask = self._confirm_ask_for_creds()
+        if ask:
+            print("  Please enter your Anthropic API Key:")
+            api_key = input(" > ")
+            return {"api_key": api_key}
+        return None
+
+    def validate_creds(self, creds: dict[str, str]) -> None:
+        """Validate Anthropic API key format.
+
+        Args:
+            creds: Dictionary containing "api_key" to validate.
+
+        Raises:
+            ValueError: If the API key format is invalid (wrong prefix, invalid
+                characters, or appears incomplete).
+        """
+        api_key = creds["api_key"]
+
+        pattern = r"^sk-ant-[A-Za-z0-9_-]+$"
+
+        if not api_key.startswith("sk-ant-"):
+            raise ValueError(
+                "Invalid API key format. Anthropic API keys should start with 'sk-ant-'\n"
+                "Please ensure you've copied the complete API key from the Anthropic Console."
+            )
+
+        if not re.match(pattern, api_key):
+            raise ValueError(
+                "Invalid API key format. Key contains invalid characters.\n"
+                "Please ensure you've copied the complete API key from the Anthropic Console."
+            )
+
+        # Basic length check - Anthropic keys are typically quite long
+        if len(api_key) < 40:
+            raise ValueError(
+                "API key appears too short. Please ensure you've copied the complete key."
+            )
+
+    def fetch_models(self, creds_map: CredentialsMap) -> ModelRegistry:
+        """Fetch available models from Anthropic API.
+
+        Retrieves the list of available Claude models and creates LLMConfig
+        entries for each. Model IDs are normalised to lowercase with hyphens.
+
+        Args:
+            creds_map: Credentials map containing Anthropic provider credential labels.
+
+        Returns:
+            ModelRegistry containing LLMConfig entries for all available
+            Anthropic models.
+        """
+        creds = {
+            k: DevKeyring.get(f"providers.{v}")
+            for k, v in creds_map.providers["anthropic"].items()
+        }
+
+        client = Anthropic(**creds)
+
+        def _make_model_cfg(model_info: ModelInfo) -> LLMConfig:
+            model_id = (
+                model_info.display_name.lower().replace(" ", "-").replace(".", "-")
+            )
+            return LLMConfig(
+                id=f"anthropic.{model_id}".lower(),
+                display_name=model_info.display_name,
+                credentials="anthropic",
+                provider="anthropic",
+                interface="anthropic-sdk",
+                model_id=model_info.id,
+            )
+
+        model_list_result = client.models.list()
+        model_configs = [_make_model_cfg(info) for info in model_list_result.data]
+
+        names = "  \n   * ".join(m.display_name for m in model_configs)
+        print(f"  Adding {len(model_configs)} LLMs from Anthropic:\n   * {names}")
+
+        return ModelRegistry(
+            llm={m.id: m for m in model_configs},
+        )