pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/provider_keys.py

@@ -0,0 +1,278 @@
+"""Secure provider-key management for the Pulse CLI."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from pulse.providers.manager import PROVIDER_SPECS
+
+try:
+    import keyring
+except ImportError:  # pragma: no cover - the release dependency is mandatory
+    keyring = None  # type: ignore[assignment]
+
+
+KEYRING_SERVICE_NAME = "pulse-coding-agent.provider-keys"
+
+
+class ProviderKeyError(ValueError):
+    """Raised when a provider key cannot be safely updated."""
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderKeyStatus:
+    provider: str
+    environment_variable: str
+    configured: bool
+    source: str
+
+
+class ProviderKeyStore:
+    """Manage provider keys without accepting secrets as command arguments.
+
+    New keys are stored in the native OS credential vault and scoped to the
+    current workspace. Existing environment and ``.env`` credentials remain
+    readable for compatibility, but a set/rotation migrates that provider away
+    from plaintext workspace storage.
+    """
+
+    def __init__(self, workspace: Path) -> None:
+        self.workspace = workspace.resolve()
+        self.env_path = self.workspace / ".env"
+        workspace_digest = hashlib.sha256(
+            os.path.normcase(str(self.workspace)).encode("utf-8")
+        ).hexdigest()[:24]
+        self._account_prefix = f"workspace:{workspace_digest}"
+
+    @staticmethod
+    def _spec(provider: str):
+        normalized = provider.strip().lower()
+        try:
+            return PROVIDER_SPECS[normalized]
+        except KeyError as error:
+            supported = ", ".join(PROVIDER_SPECS)
+            raise ProviderKeyError(
+                f"Unsupported provider '{provider}'. Choose one of: {supported}."
+            ) from error
+
+    def statuses(self) -> tuple[ProviderKeyStatus, ...]:
+        workspace_values = self._workspace_values()
+        result: list[ProviderKeyStatus] = []
+        for spec in PROVIDER_SPECS.values():
+            workspace_value = workspace_values.get(spec.env_var, "").strip()
+            environment_value = os.environ.get(spec.env_var, "").strip()
+            vault_value = self._vault_get(spec.key)
+            if self._usable(vault_value):
+                configured, source = True, "OS credential vault"
+            elif self._usable(workspace_value):
+                configured, source = True, "legacy workspace .env"
+            elif self._usable(environment_value):
+                configured, source = True, "environment"
+            else:
+                configured, source = False, "not configured"
+            result.append(
+                ProviderKeyStatus(
+                    provider=spec.key,
+                    environment_variable=spec.env_var,
+                    configured=configured,
+                    source=source,
+                )
+            )
+        return tuple(result)
+
+    def get(self, provider: str) -> str | None:
+        """Resolve a provider secret without exposing it through status APIs."""
+        spec = self._spec(provider)
+        vault_value = self._vault_get(spec.key)
+        if self._usable(vault_value):
+            return vault_value
+        environment_value = os.environ.get(spec.env_var, "")
+        if self._usable(environment_value):
+            return environment_value.strip()
+        workspace_value = self._workspace_values().get(spec.env_var, "")
+        return workspace_value.strip() if self._usable(workspace_value) else None
+
+    def set(self, provider: str, value: str) -> str:
+        spec = self._spec(provider)
+        legacy_value = self._workspace_values().get(spec.env_var)
+        previous_vault_value = self._vault_get(spec.key)
+        normalized = value.strip()
+        if not self._usable(normalized) or "\n" in value or "\r" in value:
+            raise ProviderKeyError("API key must be a non-placeholder, single-line value.")
+        if keyring is None:
+            raise ProviderKeyError(
+                "The OS credential vault is unavailable; the API key was not stored."
+            )
+        try:
+            keyring.set_password(
+                KEYRING_SERVICE_NAME,
+                self._account(spec.key),
+                normalized,
+            )
+            persisted = keyring.get_password(
+                KEYRING_SERVICE_NAME,
+                self._account(spec.key),
+            )
+        except Exception as error:
+            raise ProviderKeyError(
+                "The OS credential vault rejected the API key; nothing was stored. "
+                "Check the native keyring configuration and try again."
+            ) from error
+        if not persisted or not hmac.compare_digest(persisted, normalized):
+            raise ProviderKeyError(
+                "The OS credential vault did not confirm persistence; the API key "
+                "was not accepted."
+            )
+
+        # Successful set/rotation is also an explicit migration away from the
+        # legacy plaintext workspace entry. Never remove it before persistence
+        # has been verified.
+        if legacy_value is not None:
+            try:
+                self._rewrite(spec.env_var, None)
+            except ProviderKeyError as migration_error:
+                try:
+                    if previous_vault_value is None:
+                        keyring.delete_password(
+                            KEYRING_SERVICE_NAME,
+                            self._account(spec.key),
+                        )
+                    else:
+                        keyring.set_password(
+                            KEYRING_SERVICE_NAME,
+                            self._account(spec.key),
+                            previous_vault_value,
+                        )
+                except Exception as rollback_error:
+                    raise ProviderKeyError(
+                        "The key reached the OS credential vault, but legacy .env "
+                        "cleanup and vault rollback both failed. The secret was not "
+                        "displayed; resolve storage permissions before retrying."
+                    ) from rollback_error
+                raise ProviderKeyError(
+                    "Legacy .env cleanup failed, so the credential-vault update was "
+                    "rolled back. Fix workspace permissions and retry."
+                ) from migration_error
+            if os.environ.get(spec.env_var) == legacy_value:
+                os.environ.pop(spec.env_var, None)
+        return spec.env_var
+
+    def rotate(self, provider: str, value: str) -> str:
+        """Atomically replace a managed provider secret in the credential vault."""
+        return self.set(provider, value)
+
+    def remove(self, provider: str) -> tuple[str, bool, bool]:
+        spec = self._spec(provider)
+        values = self._workspace_values()
+        removed_from_env = spec.env_var in values
+        if removed_from_env:
+            self._rewrite(spec.env_var, None)
+        removed_from_vault = self._vault_delete(spec.key)
+        environment_still_set = self._usable(os.environ.get(spec.env_var, ""))
+        return spec.env_var, removed_from_env or removed_from_vault, environment_still_set
+
+    def _account(self, provider: str) -> str:
+        return f"{self._account_prefix}:{provider}"
+
+    def _vault_get(self, provider: str) -> str | None:
+        if keyring is None:
+            return None
+        try:
+            value = keyring.get_password(
+                KEYRING_SERVICE_NAME,
+                self._account(provider),
+            )
+        except Exception:  # noqa: BLE001 - unavailable/locked vault means no key
+            return None
+        return value.strip() if self._usable(value or "") else None
+
+    def _vault_delete(self, provider: str) -> bool:
+        if keyring is None or self._vault_get(provider) is None:
+            return False
+        try:
+            keyring.delete_password(
+                KEYRING_SERVICE_NAME,
+                self._account(provider),
+            )
+        except Exception as error:
+            raise ProviderKeyError(
+                "The OS credential vault could not remove the provider key."
+            ) from error
+        return True
+
+    def _workspace_values(self) -> dict[str, str]:
+        values: dict[str, str] = {}
+        for line in self._read_lines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#") or "=" not in stripped:
+                continue
+            key, value = stripped.split("=", 1)
+            values[key.strip()] = value.strip().strip("\"'")
+        return values
+
+    def _read_lines(self) -> list[str]:
+        if not self.env_path.exists():
+            return []
+        if self.env_path.is_symlink():
+            raise ProviderKeyError("Refusing to manage a symbolic-link .env file.")
+        try:
+            self.env_path.resolve().relative_to(self.workspace)
+        except ValueError as error:
+            raise ProviderKeyError("The workspace .env file escapes the project root.") from error
+        return self.env_path.read_text(encoding="utf-8").splitlines()
+
+    def _rewrite(self, variable: str, value: str | None) -> None:
+        lines = self._read_lines()
+        updated: list[str] = []
+        replaced = False
+        for line in lines:
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#") and "=" in stripped:
+                key = stripped.split("=", 1)[0].strip()
+                if key == variable:
+                    if value is not None and not replaced:
+                        updated.append(f"{variable}={value}")
+                        replaced = True
+                    continue
+            updated.append(line)
+        if value is not None and not replaced:
+            if updated and updated[-1]:
+                updated.append("")
+            updated.append(f"{variable}={value}")
+
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        temporary_name: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                newline="\n",
+                prefix=".pulse-env-",
+                dir=self.workspace,
+                delete=False,
+            ) as temporary:
+                temporary_name = temporary.name
+                temporary.write("\n".join(updated) + ("\n" if updated else ""))
+            os.chmod(temporary_name, 0o600)
+            os.replace(temporary_name, self.env_path)
+            temporary_name = None
+        except OSError as error:
+            raise ProviderKeyError(f"Unable to update {self.env_path}: {error}") from error
+        finally:
+            if temporary_name:
+                try:
+                    Path(temporary_name).unlink()
+                except OSError:
+                    pass
+
+    @staticmethod
+    def _usable(value: str | None) -> bool:
+        if value is None:
+            return False
+        normalized = value.strip()
+        return bool(normalized and normalized.lower() not in {"replace_me", "placeholder"})

pulse/providers/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pulse.providers.anthropic import AnthropicProvider
+from pulse.providers.base import BaseProvider, ChatMessage
+from pulse.providers.deepseek import DeepSeekProvider
+from pulse.providers.failover import FailoverProvider
+from pulse.providers.gemini import GeminiProvider
+from pulse.providers.groq import GroqProvider
+from pulse.providers.manager import PROVIDER_SPECS, ProviderManager, ProviderSpec
+from pulse.providers.openai import OpenAIProvider
+from pulse.providers.openrouter import OpenRouterProvider
+
+__all__ = [
+    "PROVIDER_SPECS",
+    "AnthropicProvider",
+    "BaseProvider",
+    "ChatMessage",
+    "DeepSeekProvider",
+    "FailoverProvider",
+    "GeminiProvider",
+    "GroqProvider",
+    "OpenAIProvider",
+    "OpenRouterProvider",
+    "ProviderManager",
+    "ProviderSpec",
+]

pulse/providers/anthropic.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pulse.core.protocols import StreamChunk
+from pulse.providers.base import BaseProvider, ChatMessage
+
+
+class AnthropicProvider(BaseProvider):
+    """Anthropic Claude Messages API provider for Pulse."""
+
+    api_key_env_var = "ANTHROPIC_API_KEY"
+    endpoint = "https://api.anthropic.com/v1/messages"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "x-api-key": self.api_key or "",
+            "anthropic-version": "2023-06-01",
+            "Content-Type": "application/json",
+        }
+
+    def _build_payload(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        temperature: float = 0.2,
+    ) -> dict[str, Any]:
+        normalized = self._normalize_messages(messages)
+        system_prompts: list[str] = []
+        anthropic_messages: list[dict[str, Any]] = []
+
+        for msg in normalized:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                system_prompts.append(str(content))
+            else:
+                anthropic_role = "assistant" if role == "assistant" else "user"
+                anthropic_messages.append({"role": anthropic_role, "content": str(content)})
+
+        payload: dict[str, Any] = {
+            "model": self.config.name,
+            "max_tokens": self.config.max_tokens,
+            "messages": anthropic_messages,
+            "stream": True,
+        }
+        if system_prompts:
+            payload["system"] = "\n\n".join(system_prompts)
+        if temperature is not None:
+            payload["temperature"] = temperature
+        return payload
+
+    def _parse_stream_chunk(self, payload_line: str) -> StreamChunk:
+        try:
+            data = json.loads(payload_line)
+        except json.JSONDecodeError:
+            return StreamChunk(content="", metadata={"raw_line": payload_line})
+
+        event_type = data.get("type")
+        if event_type == "content_block_delta":
+            delta = data.get("delta", {})
+            if delta.get("type") == "text_delta":
+                return StreamChunk(content=delta.get("text", ""), metadata={"raw": data})
+
+        return StreamChunk(content="", metadata={"raw": data})

pulse/providers/base.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from pulse.config import ModelConfig, load_env_file
+from pulse.core.protocols import LLMProvider, StreamChunk
+
+ModelProvider = LLMProvider
+
+
+@dataclass(frozen=True)
+class ChatMessage:
+    role: str
+    content: str
+
+
+class BaseProvider(ABC, LLMProvider):
+    """Base class for async-first model providers independent from the CLI."""
+
+    def __init__(
+        self,
+        config: ModelConfig,
+        workspace_env_path: Path | str,
+        api_key: str | None = None,
+    ) -> None:
+        env_path = (
+            Path(workspace_env_path)
+            if isinstance(workspace_env_path, str)
+            else workspace_env_path
+        )
+        env = load_env_file(env_path) if env_path.exists() else {}
+        self.config = config
+        from pulse.provider_keys import ProviderKeyStore
+
+        self.api_key = (
+            api_key
+            or ProviderKeyStore(env_path.parent).get(config.provider)
+            or os.environ.get(self.api_key_env_var)
+            or env.get(self.api_key_env_var)
+        )
+
+    @property
+    def is_configured(self) -> bool:
+        return bool(self.api_key and self.api_key.strip() and self.api_key != "replace_me")
+
+    async def generate_stream(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        temperature: float = 0.2,
+    ) -> AsyncGenerator[StreamChunk, None]:
+        if not self.is_configured:
+            raise RuntimeError(
+                f"{self.api_key_env_var} is not configured. Run 'pulse keys' to add it securely."
+            )
+
+        payload = self._build_payload(messages, temperature=temperature)
+        endpoint = self.endpoint
+
+        async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+            try:
+                async with client.stream(
+                    "POST", endpoint, json=payload, headers=self._headers()
+                ) as response:
+                    if getattr(response, "is_error", False):
+                        await response.aread()
+                    if hasattr(response, "raise_for_status"):
+                        response.raise_for_status()
+
+                    async for line in response.aiter_lines():
+                        chunk = self._process_stream_line(line)
+                        if chunk is not None:
+                            yield chunk
+            except httpx.TimeoutException as error:
+                raise RuntimeError(
+                    f"The model request to {self.config.provider} timed out."
+                ) from error
+            except httpx.HTTPStatusError as error:
+                detail = self._safe_error_detail(error)
+                code = error.response.status_code if error.response else "unknown"
+                raise RuntimeError(
+                    f"Model request failed ({self.config.provider} HTTP {code}): {detail}"
+                ) from error
+            except httpx.HTTPError as error:
+                raise RuntimeError(
+                    f"Model request to {self.config.provider} failed due to a network error."
+                ) from error
+            except json.JSONDecodeError as error:
+                raise RuntimeError(
+                    f"Received an invalid streaming response from {self.config.provider}."
+                ) from error
+
+    def chat(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        temperature: float = 0.2,
+    ) -> str:
+        return asyncio.run(self._chat(messages, temperature=temperature))
+
+    def stream_chat(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        temperature: float = 0.2,
+    ) -> list[str]:
+        if not self.is_configured:
+            raise RuntimeError(
+                f"{self.api_key_env_var} is not configured. Run 'pulse keys' to add it securely."
+            )
+
+        payload = self._build_payload(messages, temperature=temperature)
+        try:
+            with httpx.stream(
+                "POST",
+                self.endpoint,
+                json=payload,
+                headers=self._headers(),
+                timeout=self.timeout_seconds,
+            ) as response:
+                if getattr(response, "is_error", False):
+                    response.read()
+                if hasattr(response, "raise_for_status"):
+                    response.raise_for_status()
+
+                results: list[str] = []
+                for line in response.iter_lines():
+                    chunk = self._process_stream_line(line)
+                    if chunk is not None and chunk.content:
+                        results.append(chunk.content)
+                return results
+        except httpx.TimeoutException as error:
+            raise RuntimeError(
+                f"The model request to {self.config.provider} timed out."
+            ) from error
+        except httpx.HTTPStatusError as error:
+            detail = self._safe_error_detail(error)
+            code = error.response.status_code if error.response else "unknown"
+            raise RuntimeError(
+                f"Model request failed ({self.config.provider} HTTP {code}): {detail}"
+            ) from error
+        except httpx.HTTPError as error:
+            raise RuntimeError(
+                f"Model request to {self.config.provider} failed due to a network error."
+            ) from error
+        except json.JSONDecodeError as error:
+            raise RuntimeError(
+                f"Received an invalid streaming response from {self.config.provider}."
+            ) from error
+
+    async def _chat(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        *,
+        temperature: float = 0.2,
+    ) -> str:
+        chunks = []
+        async for chunk in self.generate_stream(messages, temperature=temperature):
+            chunks.append(chunk.content)
+        return "".join(chunks)
+
+    async def _stream_chat(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        *,
+        temperature: float = 0.2,
+    ) -> list[str]:
+        return [
+            chunk.content
+            async for chunk in self.generate_stream(messages, temperature=temperature)
+        ]
+
+    def _build_payload(
+        self,
+        messages: list[dict[str, Any] | ChatMessage],
+        temperature: float = 0.2,
+    ) -> dict[str, Any]:
+        normalized = self._normalize_messages(messages)
+        return {
+            "model": self.config.name,
+            "temperature": temperature,
+            "max_tokens": self.config.max_tokens,
+            "messages": normalized,
+            "stream": True,
+        }
+
+    def _process_stream_line(self, line: str) -> StreamChunk | None:
+        if not line.startswith("data:"):
+            return None
+        payload_line = line[5:].strip()
+        if not payload_line or payload_line == "[DONE]":
+            return None
+        return self._parse_stream_chunk(payload_line)
+
+    def _safe_error_detail(self, error: httpx.HTTPError) -> str:
+        response = getattr(error, "response", None)
+        if response is None:
+            return "The provider request failed."
+        status = getattr(response, "status_code", 0)
+
+        if status == 401:
+            return f"Invalid or unauthenticated API key ({self.api_key_env_var})."
+        if status == 404:
+            return f"Model '{self.config.name}' was not found or is unavailable for {self.config.provider}."
+        if status == 429:
+            return f"Rate limit exceeded for {self.config.provider}. Please wait before retrying."
+
+        # Provider-controlled bodies may reflect prompts, request payloads, or
+        # credentials. They must never cross into CLI, RPC, telemetry, or logs.
+        return "The provider rejected the request. Check provider status and configuration."
+
+    def _normalize_messages(
+        self, messages: list[dict[str, Any] | ChatMessage]
+    ) -> list[dict[str, Any]]:
+        normalized: list[dict[str, Any]] = []
+        for msg in messages:
+            if isinstance(msg, ChatMessage):
+                normalized.append({"role": msg.role, "content": msg.content})
+            elif isinstance(msg, dict):
+                normalized.append(msg)
+            else:
+                raise TypeError(f"Unsupported message type: {type(msg)}")
+        return normalized
+
+    @abstractmethod
+    def _headers(self) -> dict[str, str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def _parse_stream_chunk(self, payload_line: str) -> StreamChunk:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def api_key_env_var(self) -> str:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def endpoint(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def timeout_seconds(self) -> int:
+        return 60

pulse/providers/deepseek.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from pulse.providers.openai import OpenAIProvider
+
+
+class DeepSeekProvider(OpenAIProvider):
+    """DeepSeek provider implementation for Pulse."""
+
+    api_key_env_var = "DEEPSEEK_API_KEY"
+    endpoint = "https://api.deepseek.com/chat/completions"

pulse/providers/failover.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from pulse.core.protocols import LLMProvider, StreamChunk
+
+
+class FailoverProvider(LLMProvider):
+    """Fallback mechanism to switch to a secondary configured provider if the primary API call fails or times out."""
+
+    def __init__(self, primary: LLMProvider, secondary: LLMProvider) -> None:
+        self.primary = primary
+        self.secondary = secondary
+
+    @property
+    def is_configured(self) -> bool:
+        return getattr(self.primary, "is_configured", True) or getattr(self.secondary, "is_configured", True)
+
+    async def generate_stream(
+        self,
+        messages: list[dict[str, Any]],
+        temperature: float = 0.2,
+    ) -> AsyncGenerator[StreamChunk, None]:
+        try:
+            async for chunk in self.primary.generate_stream(messages, temperature=temperature):
+                yield chunk
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception:  # noqa: BLE001
+            # Fallback to secondary provider if primary fails or times out
+            async for chunk in self.secondary.generate_stream(messages, temperature=temperature):
+                yield chunk