tighten optional providers and expand ci triggers

Author: Luca Candela

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: CI
 on:
   push:
     branches:
-      - main
+      - '**'
   pull_request:
 
 jobs:

graphium_core/cross_encoder/rerankers/__init__.py

@@ -1,18 +1,33 @@
+from __future__ import annotations
+
 from .generic import GenericLiteLLMReranker
 from .openai import OpenAIReranker
 
 __all__ = ['GenericLiteLLMReranker', 'OpenAIReranker']
 
+
+def _missing_provider(name: str, dependency: str) -> type:
+    class _MissingProvider:  # pragma: no cover - simple error shim
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                f'{name} requires the optional dependency "{dependency}". '
+                f'Install it via `uv sync --extra {dependency}` or the matching extras group.'
+            )
+
+    _MissingProvider.__name__ = f'Missing{name}'
+    return _MissingProvider
+
+
 try:  # pragma: no cover - optional dependency
-    from .gemini import GeminiReranker
-except ImportError:  # pragma: no cover - optional dependency guard
-    GeminiReranker = None  # type: ignore[assignment]
-else:  # pragma: no cover - optional dependency available
+    from .gemini import GeminiReranker  # type: ignore[unused-import]
+except ImportError:  # pragma: no cover
+    GeminiReranker = _missing_provider('GeminiReranker', 'google-genai')  # type: ignore[assignment]
+else:  # pragma: no cover
     __all__.append('GeminiReranker')
 
 try:  # pragma: no cover - optional dependency
-    from .bge import BGEReranker
-except ImportError:  # pragma: no cover - optional dependency guard
-    BGEReranker = None  # type: ignore[assignment]
-else:  # pragma: no cover - optional dependency available
+    from .bge import BGEReranker  # type: ignore[unused-import]
+except ImportError:  # pragma: no cover
+    BGEReranker = _missing_provider('BGEReranker', 'sentence-transformers')  # type: ignore[assignment]
+else:  # pragma: no cover
     __all__.append('BGEReranker')

graphium_core/cross_encoder/rerankers/gemini.py

@@ -11,11 +11,15 @@
 from ..reranker_client import RerankerClient
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    genai = typing.Any  # type: ignore[assignment]
-    types = typing.Any  # type: ignore[assignment]
+    try:
+        from google import genai as genai  # type: ignore[import-not-found]
+        from google.genai import types as types  # type: ignore[import-not-found]
+    except ImportError:  # pragma: no cover - optional dependency missing at type time
+        genai = typing.cast(typing.Any, None)
+        types = typing.cast(typing.Any, None)
 else:  # pragma: no cover - runtime placeholders
-    genai = typing.Any
-    types = typing.Any
+    genai = typing.cast(typing.Any, None)
+    types = typing.cast(typing.Any, None)
 
 logger = logging.getLogger(__name__)
 

graphium_core/embedder/providers/__init__.py

@@ -4,26 +4,39 @@
 
 __all__ = ['OpenAIEmbedder', 'OpenAIEmbedderConfig']
 
+
+def _missing_provider(name: str, dependency: str) -> type:
+    class _MissingProvider:  # pragma: no cover - shim for optional extras
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                f'{name} requires the optional dependency "{dependency}". '
+                f'Install it via `uv sync --extra {dependency}` or the corresponding extras group.'
+            )
+
+    _MissingProvider.__name__ = f'Missing{name}'
+    return _MissingProvider
+
+
 try:  # pragma: no cover - optional dependency
-    from .gemini import GeminiEmbedder, GeminiEmbedderConfig
-except ImportError:  # pragma: no cover - optional dependency guard
-    GeminiEmbedder = None  # type: ignore[assignment]
-    GeminiEmbedderConfig = None  # type: ignore[assignment]
-else:  # pragma: no cover - optional dependency present
+    from .gemini import GeminiEmbedder, GeminiEmbedderConfig  # type: ignore[unused-import]
+except ImportError:  # pragma: no cover
+    GeminiEmbedder = _missing_provider('GeminiEmbedder', 'google-genai')  # type: ignore[assignment]
+    GeminiEmbedderConfig = _missing_provider('GeminiEmbedderConfig', 'google-genai')  # type: ignore[assignment]
+else:  # pragma: no cover
     __all__.extend(['GeminiEmbedder', 'GeminiEmbedderConfig'])
 
 try:  # pragma: no cover - optional dependency
-    from .voyage import VoyageAIEmbedder, VoyageAIEmbedderConfig
-except ImportError:  # pragma: no cover - optional dependency guard
-    VoyageAIEmbedder = None  # type: ignore[assignment]
-    VoyageAIEmbedderConfig = None  # type: ignore[assignment]
+    from .voyage import VoyageAIEmbedder, VoyageAIEmbedderConfig  # type: ignore[unused-import]
+except ImportError:  # pragma: no cover
+    VoyageAIEmbedder = _missing_provider('VoyageAIEmbedder', 'voyageai')  # type: ignore[assignment]
+    VoyageAIEmbedderConfig = _missing_provider('VoyageAIEmbedderConfig', 'voyageai')  # type: ignore[assignment]
 else:  # pragma: no cover
     __all__.extend(['VoyageAIEmbedder', 'VoyageAIEmbedderConfig'])
 
 try:  # pragma: no cover - optional dependency
-    from .embeddinggemma import EmbeddingGemmaConfig, EmbeddingGemmaEmbedder
-except ImportError:  # pragma: no cover - optional dependency guard
-    EmbeddingGemmaEmbedder = None  # type: ignore[assignment]
-    EmbeddingGemmaConfig = None  # type: ignore[assignment]
+    from .embeddinggemma import EmbeddingGemmaConfig, EmbeddingGemmaEmbedder  # type: ignore[unused-import]
+except ImportError:  # pragma: no cover
+    EmbeddingGemmaEmbedder = _missing_provider('EmbeddingGemmaEmbedder', 'sentence-transformers')  # type: ignore[assignment]
+    EmbeddingGemmaConfig = _missing_provider('EmbeddingGemmaConfig', 'sentence-transformers')  # type: ignore[assignment]
 else:  # pragma: no cover
     __all__.extend(['EmbeddingGemmaEmbedder', 'EmbeddingGemmaConfig'])

graphium_core/llm_client/pydantic_ai_adapter.py

@@ -117,6 +117,14 @@ async def maybe_run_with_pydantic_ai(
     if conversation is None:
         return None
 
+    api_key = settings.resolved_api_key()
+    if not api_key:
+        logger.debug(
+            'Skipping Pydantic AI path for provider %s: API key unavailable.',
+            getattr(settings.provider, 'value', settings.provider),
+        )
+        return None
+
     try:
         model = create_pydantic_ai_model(settings, model_name)
     except PydanticAIUserError:

graphium_core/providers/factory.py

@@ -140,7 +140,13 @@ def create_embedder(
         return OpenAIEmbedder(config=config)
 
     if provider == EmbedderProvider.gemini:
-        from graphium_core.embedder import GeminiEmbedder, GeminiEmbedderConfig
+        try:
+            from graphium_core.embedder import GeminiEmbedder, GeminiEmbedderConfig
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                'Gemini embedder requires the optional google-genai dependency. '
+                'Install it via `uv sync --extra google-genai` to enable Gemini embeddings.'
+            ) from exc
 
         _ensure_embedder_api_key(provider, resolved_settings, resolved_llm_settings)
         config_kwargs = {
@@ -153,7 +159,13 @@ def create_embedder(
         return GeminiEmbedder(config=config)
 
     if provider == EmbedderProvider.embeddinggemma:
-        from graphium_core.embedder import EmbeddingGemmaConfig, EmbeddingGemmaEmbedder
+        try:
+            from graphium_core.embedder import EmbeddingGemmaConfig, EmbeddingGemmaEmbedder
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                'EmbeddingGemma embedder requires the optional sentence-transformers dependency. '
+                'Install it via `uv sync --extra sentence-transformers` to enable EmbeddingGemma.'
+            ) from exc
 
         config_kwargs = {
             'embedding_dim': embedding_dim,
@@ -196,14 +208,26 @@ def create_reranker(
         return OpenAIReranker(config=config)
 
     if provider == LLMProvider.gemini:
-        from graphium_core.cross_encoder import GeminiReranker
+        try:
+            from graphium_core.cross_encoder import GeminiReranker
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                'Gemini reranker requires the optional google-genai dependency. '
+                'Install it via `uv sync --extra google-genai` to enable Gemini reranking.'
+            ) from exc
 
         _ensure_llm_api_key(settings)
         config = LLMConfig(api_key=settings.resolved_api_key(), model=settings.model)
         return GeminiReranker(config=config)
 
     if provider.value == 'bge':
-        from graphium_core.cross_encoder import BGEReranker
+        try:
+            from graphium_core.cross_encoder import BGEReranker
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                'BGE reranker requires the optional sentence-transformers dependency. '
+                'Install it via `uv sync --extra sentence-transformers` to enable BGE reranking.'
+            ) from exc
 
         return BGEReranker()
 

graphium_core/settings.py

@@ -35,7 +35,11 @@
 
 
 class GraphiumBaseSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_file='.env', extra='ignore')
+    model_config = SettingsConfigDict(
+        env_file='.env',
+        extra='ignore',
+        populate_by_name=True,
+    )
 
 
 class LLMProvider(str, Enum):

mcp_server/graphium_mcp/state.py

@@ -3,15 +3,21 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING
+from collections.abc import Awaitable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 from .config import GraphiumConfig
 
 if TYPE_CHECKING:
     from graphium_core import Graphium
 
-EpisodeProcessor = Callable[[], Awaitable[None]]
+
+@runtime_checkable
+class EpisodeProcessor(Protocol):
+    queue_metadata: dict[str, Any] | None  # attribute populated by queue management
+
+    def __call__(self) -> Awaitable[None]:
+        ...
 
 graphium_config: GraphiumConfig = GraphiumConfig()
 graphium_client: Graphium | None = None

mcp_server/graphium_mcp/tools.py

@@ -106,13 +106,14 @@ async def process_episode() -> None:
                     group_id_str,
                 )
 
-        process_episode.queue_metadata = {
+        queue_task = cast(state.EpisodeProcessor, process_episode)
+        queue_task.queue_metadata = {
             'name': name,
             'group_id': group_id_str,
             'source': source_type.value,
         }
 
-        position = await enqueue_episode(group_id_str, process_episode)
+        position = await enqueue_episode(group_id_str, queue_task)
 
         pending_failures = state.queue_failures.get(group_id_str, [])
         message = f"Episode '{name}' queued for processing (position: {position})"

pyproject.toml

@@ -35,16 +35,16 @@ groq = ["groq>=0.2.0"]
 google-genai = ["google-genai>=1.8.0"]
 kuzu = ["kuzu>=0.11.2"]
 falkordb = ["falkordb>=1.1.2,<2.0.0"]
-voyageai = ["voyageai>=0.2.3"]
+voyageai = ["voyageai>=0.3.3"]
 neo4j-opensearch = ["boto3>=1.39.16", "opensearch-py>=3.0.0"]
-sentence-transformers = ["sentence-transformers>=3.2.1"]
+sentence-transformers = ["sentence-transformers>=5.0.0"]
 neptune = ["langchain-aws>=0.2.29", "opensearch-py>=3.0.0", "boto3>=1.39.16"]
 tracing = ["opentelemetry-api>=1.20.0", "opentelemetry-sdk>=1.20.0"]
 dev = [
     "pyright>=1.1.404",
     "fastapi>=0.115.0",
     "uvicorn>=0.30.0",
-    "fastmcp>=2.12.0",
+    "fastmcp>=2.12.4",
     "mcp>=1.5.0",
     "groq>=0.2.0",
     "anthropic>=0.49.0",
@@ -61,12 +61,12 @@ dev = [
     "langchain-anthropic>=0.2.4",
     "langsmith>=0.1.108",
     "langchain-openai>=0.2.6",
-    "sentence-transformers>=3.2.1",
+    "sentence-transformers>=5.0.0",
     "transformers>=4.45.2",
-    "voyageai>=0.2.3",
+    "voyageai>=0.3.3",
     "pytest>=8.3.3",
     "pytest-cov>=7.0.0",
-    "pytest-asyncio>=0.24.0",
+    "pytest-asyncio>=1.0.0",
     "pytest-xdist>=3.6.1",
     "ruff>=0.7.1",
     "opentelemetry-sdk>=1.20.0",