import without individual providers

Author: ikamensh

.github/workflows/test.yml

@@ -23,10 +23,18 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y tesseract-ocr
       
-      - name: Install dependencies
+      - name: Install core package only (no providers)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          pip install -e .
+      
+      - name: Verify import without provider SDKs
+        run: |
+          python -c "from covenance import ask_llm, Covenance, print_usage; print('Import OK')"
+      
+      - name: Install all dependencies
+        run: |
+          pip install -e ".[all,dev]"
       
       - name: Run pytest
         run: pytest --cov --cov-branch --cov-report=xml
@@ -36,4 +44,4 @@ jobs:
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          token: ${{ secrets.CODECOV_TOKEN }}

covenance/client.py

@@ -12,16 +12,10 @@
 from pathlib import Path
 from typing import Any
 
-from anthropic import Anthropic
-from google import genai
-from mistralai import Mistral
-from openai import OpenAI
 from pydantic import TypeAdapter, ValidationError
 
 from ._caller_context import capture_caller_context
 from ._lazy_client import LazyClient
-from .clients.grok_client import GROK_BASE_URL
-from .clients.openrouter_client import OPENROUTER_BASE_URL
 from .exceptions import StructuredOutputParsingError
 from .keys import (
     get_anthropic_api_key,
@@ -105,33 +99,49 @@ def _require_key(
     ) -> str:
         return require_api_key(override or getter(), provider)
 
-    def _create_openai_client(self) -> OpenAI:
+    def _create_openai_client(self):
+        from openai import OpenAI
+
         api_key = self._require_key(self._openai_api_key, "openai", get_openai_api_key)
         return OpenAI(api_key=api_key)
 
-    def _create_openrouter_client(self) -> OpenAI:
+    def _create_openrouter_client(self):
+        from openai import OpenAI
+
+        from .clients.openrouter_client import OPENROUTER_BASE_URL
+
         api_key = self._require_key(
             self._openrouter_api_key, "openrouter", get_openrouter_api_key
         )
         return OpenAI(api_key=api_key, base_url=OPENROUTER_BASE_URL)
 
-    def _create_gemini_client(self) -> genai.Client:
+    def _create_gemini_client(self):
+        from google import genai
+
         api_key = self._require_key(self._gemini_api_key, "gemini", get_gemini_api_key)
         return genai.Client(api_key=api_key)
 
-    def _create_mistral_client(self) -> Mistral:
+    def _create_mistral_client(self):
+        from mistralai import Mistral
+
         api_key = self._require_key(
             self._mistral_api_key, "mistral", get_mistral_api_key
         )
         return Mistral(api_key=api_key)
 
-    def _create_anthropic_client(self) -> Anthropic:
+    def _create_anthropic_client(self):
+        from anthropic import Anthropic
+
         api_key = self._require_key(
             self._anthropic_api_key, "anthropic", get_anthropic_api_key
         )
         return Anthropic(api_key=api_key)
 
-    def _create_grok_client(self) -> OpenAI:
+    def _create_grok_client(self):
+        from openai import OpenAI
+
+        from .clients.grok_client import GROK_BASE_URL
+
         api_key = self._require_key(self._grok_api_key, "grok", get_grok_api_key)
         return OpenAI(api_key=api_key, base_url=GROK_BASE_URL)
 

covenance/clients/anthropic_client.py

@@ -4,23 +4,27 @@
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING, TypeVar
 
-from anthropic import Anthropic, APIError, RateLimitError
 from pydantic import BaseModel
 
 from covenance._lazy_client import LazyClient
-from covenance.exceptions import StructuredOutputParsingError
+from covenance.exceptions import StructuredOutputParsingError, require_provider
 from covenance.keys import get_anthropic_api_key, require_api_key
 from covenance.models import ClaudeModels
 from covenance.record import TokenUsage
 from covenance.retry import exponential_backoff
 
 if TYPE_CHECKING:
+    from anthropic import Anthropic
+
     from covenance.record import RecordStore
 
 T = TypeVar("T")
 
 
-def _create_anthropic_client() -> Anthropic:
+def _create_anthropic_client() -> "Anthropic":
+    require_provider("anthropic")
+    from anthropic import Anthropic
+
     api_key = require_api_key(get_anthropic_api_key(), "anthropic")
     return Anthropic(api_key=api_key)
 
@@ -95,7 +99,7 @@ def ask_anthropic[T](
     sys_msg: str | None = None,
     model: str = ClaudeModels.haiku45,
     *,
-    client_override: Anthropic | None = None,
+    client_override: "Anthropic | None" = None,
     record_store: "RecordStore | None" = None,
     temperature: float | None = None,
 ) -> T:
@@ -105,22 +109,11 @@ def ask_anthropic[T](
     to get structured output. Retries up to 100 times when encountering rate limit errors.
 
     If response_type is str, performs a standard chat completion and returns the text.
-
-    Args:
-        user_msg: User message/prompt
-        response_type: Pydantic model class for structured output, or str/None for plain text
-        sys_msg: Optional system message/instructions
-        model: Claude model identifier (defaults to claude-3-5-haiku)
-
-    Returns:
-        Parsed Pydantic object of type T, or str if response_type is str
-
-    Raises:
-        StructuredOutputParsingError: If parsing fails
-        Exception: After max_attempts retries on rate limit errors
     """
+    from anthropic import APIError, RateLimitError
+
     max_attempts = 100
-    api_client = client_override or client
+    api_client = client_override or client  # type: ignore[assignment]
 
     # Handle plain text output
     is_plain_text = response_type is str or response_type is None

covenance/clients/google_client.py

@@ -4,16 +4,15 @@
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING, TypeVar
 
-from google import genai  # pip install --upgrade google-genai
-from google.genai.errors import ClientError
-
 from covenance._lazy_client import LazyClient
-from covenance.exceptions import StructuredOutputParsingError
+from covenance.exceptions import StructuredOutputParsingError, require_provider
 from covenance.keys import get_gemini_api_key, require_api_key
 from covenance.models import GeminiModels
 from covenance.record import TokenUsage
 
 if TYPE_CHECKING:
+    from google import genai
+
     from covenance.record import RecordStore
 
 # Suppress warning about non-text parts (thought_signature) in Gemini responses.
@@ -27,7 +26,10 @@
 T = TypeVar("T")
 
 
-def _create_gemini_client() -> genai.Client:
+def _create_gemini_client() -> "genai.Client":
+    require_provider("google")
+    from google import genai
+
     api_key = require_api_key(get_gemini_api_key(), "gemini")
     return genai.Client(api_key=api_key)
 
@@ -38,7 +40,7 @@ def _create_gemini_client() -> genai.Client:
 VERBOSE = False
 
 
-def _parse_wait_time_from_error(error: ClientError) -> float:
+def _parse_wait_time_from_error(error: Exception) -> float:
     """Parse wait time from Gemini ClientError message.
 
     The error message typically contains: "Please retry in X.XXXs."
@@ -99,7 +101,7 @@ def ask_gemini[T](
     sys_msg: str | None = None,
     model: str = GeminiModels.flash_25.value,
     *,
-    client_override: genai.Client | None = None,
+    client_override: "genai.Client | None" = None,
     record_store: "RecordStore | None" = None,
     temperature: float | None = None,
 ) -> T:
@@ -109,15 +111,11 @@ def ask_gemini[T](
     parsing the wait time from the error message and waiting accordingly.
 
     If response_type is str or None, performs a standard chat completion and returns the text.
-
-    `response_type` can be:
-        - a Pydantic model                -> returns a model instance
-        - list[MyModel]                   -> returns the annotated container
-        - a builtin typing annotation     -> returns that type
-        - str                             -> returns plain text
     """
+    from google.genai.errors import ClientError
+
     max_attempts = 100
-    api_client = client_override or client
+    api_client = client_override or client  # type: ignore[assignment]
     total_tpm_wait = 0.0  # Accumulate TPM retry wait time
     started_at = datetime.now(UTC)  # Record absolute start time
 

covenance/clients/grok_client.py

@@ -2,20 +2,24 @@
 
 from typing import TYPE_CHECKING
 
-from openai import OpenAI
-
 from covenance._lazy_client import LazyClient
 from covenance.clients.openai_client import ask_openai_compatible_structured
+from covenance.exceptions import require_provider
 from covenance.keys import get_grok_api_key, require_api_key
 from covenance.models import GrokModels
 
 if TYPE_CHECKING:
+    from openai import OpenAI
+
     from covenance.record import RecordStore
 
 GROK_BASE_URL = "https://api.x.ai/v1"
 
 
-def _create_grok_client() -> OpenAI:
+def _create_grok_client() -> "OpenAI":
+    require_provider("openai")
+    from openai import OpenAI
+
     api_key = require_api_key(get_grok_api_key(), "grok")
     return OpenAI(api_key=api_key, base_url=GROK_BASE_URL)
 
@@ -29,12 +33,12 @@ def ask_grok[T](
     sys_msg: str | None = None,
     model: str = GrokModels.grok4_fast.value,
     *,
-    client_override: OpenAI | None = None,
+    client_override: "OpenAI | None" = None,
     record_store: "RecordStore | None" = None,
     temperature: float | None = None,
 ) -> T:
     """Call xAI Grok API with automatic retry."""
-    api_client = client_override or client
+    api_client = client_override or client  # type: ignore[assignment]
     return ask_openai_compatible_structured(
         client=api_client,
         user_msg=user_msg,

covenance/clients/mistral_client.py

@@ -4,23 +4,25 @@
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING, TypeVar
 
-from mistralai import Mistral
-from mistralai.models import HTTPValidationError, SDKError
-
 from covenance._lazy_client import LazyClient
-from covenance.exceptions import StructuredOutputParsingError
+from covenance.exceptions import StructuredOutputParsingError, require_provider
 from covenance.keys import get_mistral_api_key, require_api_key
 from covenance.models import MistralModels
 from covenance.record import TokenUsage
 from covenance.retry import exponential_backoff
 
 if TYPE_CHECKING:
+    from mistralai import Mistral
+
     from covenance.record import RecordStore
 
 T = TypeVar("T")
 
 
-def _create_mistral_client() -> Mistral:
+def _create_mistral_client() -> "Mistral":
+    require_provider("mistral")
+    from mistralai import Mistral
+
     api_key = require_api_key(get_mistral_api_key(), "mistral")
     return Mistral(api_key=api_key)
 
@@ -76,7 +78,7 @@ def ask_mistral[T](
     sys_msg: str | None = None,
     model: str = MistralModels.small.value,
     *,
-    client_override: Mistral | None = None,
+    client_override: "Mistral | None" = None,
     record_store: "RecordStore | None" = None,
     temperature: float | None = None,
 ) -> T:
@@ -86,21 +88,11 @@ def ask_mistral[T](
     output directly. Retries up to 100 times when encountering rate limit errors.
 
     If response_type is str or None, performs a standard chat completion and returns the text.
-
-    Args:
-        user_msg: User message/prompt
-        response_type: Pydantic model class for structured output, or str/None for plain text
-        sys_msg: Optional system message/instructions
-        model: Mistral model identifier (defaults to mistral-small-latest)
-
-    Returns:
-        Parsed Pydantic object of type T, or str if response_type is str
-
-    Raises:
-        Exception: After max_attempts retries on rate limit errors
     """
+    from mistralai.models import HTTPValidationError, SDKError
+
     max_attempts = 100
-    api_client = client_override or client
+    api_client = client_override or client  # type: ignore[assignment]
 
     # Build messages array
     messages = []