Skip to content

Personal AI, On Personal Devices

Python

fix: make engine fallback explicit (#893)

Elliot Slusky7c24e3e88ca8
diff --git a/src/openjarvis/engine/__init__.py b/src/openjarvis/engine/__init__.py
index 484bf511..ef88acab 100644
--- a/src/openjarvis/engine/__init__.py
+++ b/src/openjarvis/engine/__init__.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import importlib
+import logging
# Import engine modules to trigger @EngineRegistry.register() decorators
import openjarvis.engine.nim # noqa: F401
@@ -17,12 +18,21 @@ from openjarvis.engine._base import (
)
from openjarvis.engine._discovery import discover_engines, discover_models, get_engine
+logger = logging.getLogger(__name__)
+
+
+def _register_optional_engines() -> None:
+ """Register available optional engines and retain import diagnostics."""
+
+ for optional in ("cloud", "litellm", "gemma_cpp"):
+ try:
+ importlib.import_module(f".{optional}", __name__)
+ except ImportError as exc:
+ logger.debug("Optional engine %r unavailable: %s", optional, exc)
+
+
# Optional engines — only register if their SDK deps are present
-for _optional in ("cloud", "litellm", "gemma_cpp"):
- try:
- importlib.import_module(f".{_optional}", __name__)
- except ImportError:
- pass
+_register_optional_engines()
__all__ = [
"EngineConnectionError",
diff --git a/src/openjarvis/engine/_discovery.py b/src/openjarvis/engine/_discovery.py
index f448c647..d3a9acc9 100644
--- a/src/openjarvis/engine/_discovery.py
+++ b/src/openjarvis/engine/_discovery.py
@@ -166,7 +166,11 @@ def get_engine(
engine_key: str | None = None,
model: str | None = None,
) -> Tuple[str, InferenceEngine] | None:
- """Get a specific engine by key, or the default with fallback.
+ """Get a specific engine by key, or the default with a named fallback.
+
+ An explicit ``engine_key`` is authoritative and is never silently
+ substituted. Default-engine fallback prefers the same local/cloud class
+ and logs the selected replacement.
When *model* is given, an engine is selected only if it can actually
serve that model (``engine.can_serve(model)``). This stops the cloud
@@ -182,30 +186,68 @@ def get_engine(
def _usable(engine: InferenceEngine) -> bool:
return engine.health() and (model is None or engine.can_serve(model))
- # Build an ordered list of keys to try, then fall back to full discovery.
- keys_to_try: list[str] = []
if engine_key:
- keys_to_try.append(engine_key)
+ if not EngineRegistry.contains(engine_key):
+ logger.warning("Requested engine %r is not registered", engine_key)
+ return None
+ try:
+ engine = _make_engine(engine_key, config)
+ if _usable(engine):
+ return (engine_key, engine)
+ except Exception as exc:
+ logger.debug("Engine %r health check failed: %s", engine_key, exc)
+ logger.warning(
+ "Requested engine %r is unavailable%s; no substitute was selected",
+ engine_key,
+ f" for model {model!r}" if model else "",
+ )
+ return None
default_key = config.engine.default
- if default_key and default_key not in keys_to_try:
- keys_to_try.append(default_key)
-
- for key in keys_to_try:
- if not EngineRegistry.contains(key):
- continue
+ default_is_cloud: bool | None = None
+ if default_key and EngineRegistry.contains(default_key):
+ default_cls = EngineRegistry.get(default_key)
+ default_is_cloud = bool(getattr(default_cls, "is_cloud", False))
try:
- engine = _make_engine(key, config)
+ engine = _make_engine(default_key, config)
+ default_is_cloud = bool(getattr(engine, "is_cloud", default_is_cloud))
if _usable(engine):
- return (key, engine)
+ return (default_key, engine)
except Exception as exc:
- logger.debug("Engine %r health check failed: %s", key, exc)
+ logger.debug("Engine %r health check failed: %s", default_key, exc)
+
+ candidates = [
+ (key, engine)
+ for key, engine in discover_engines(config)
+ if key != default_key and (model is None or engine.can_serve(model))
+ ]
+ if not candidates:
+ return None
- # Fallback to the first healthy engine that can serve the model.
- for key, engine in discover_engines(config):
- if model is None or engine.can_serve(model):
- return (key, engine)
- return None
+ chosen: Tuple[str, InferenceEngine] | None = None
+ if default_is_cloud is not None:
+ chosen = next(
+ (
+ candidate
+ for candidate in candidates
+ if bool(getattr(candidate[1], "is_cloud", False)) == default_is_cloud
+ ),
+ None,
+ )
+ chosen = chosen or candidates[0]
+ chosen_is_cloud = bool(getattr(chosen[1], "is_cloud", False))
+ boundary = (
+ " across the local/cloud boundary"
+ if (default_is_cloud is not None and chosen_is_cloud != default_is_cloud)
+ else ""
+ )
+ logger.warning(
+ "Default engine %r is unavailable; using %r%s",
+ default_key,
+ chosen[0],
+ boundary,
+ )
+ return chosen
__all__ = ["discover_engines", "discover_models", "get_engine"]
diff --git a/tests/engine/test_discovery.py b/tests/engine/test_discovery.py
index 56740df8..8219a411 100644
--- a/tests/engine/test_discovery.py
+++ b/tests/engine/test_discovery.py
@@ -170,12 +170,7 @@ class TestGetEngine:
assert result is not None
assert result[0] == "good"
- def test_explicit_key_falls_back_to_any_healthy(self) -> None:
- """When an explicit engine_key fails, fallback to any healthy engine.
-
- Fixes #73: LM Studio running but not found because get_engine()
- returned None when the explicitly-requested key failed.
- """
+ def test_explicit_unavailable_key_does_not_substitute(self, caplog) -> None:
_reg("requested", "requested")
_reg("running", "running")
@@ -189,10 +184,70 @@ class TestGetEngine:
"openjarvis.engine._discovery._make_engine",
side_effect=_make,
):
- # Explicit key "requested" is unhealthy, but "running" is healthy
result = get_engine(cfg, engine_key="requested")
+
+ assert result is None
+ assert "Requested engine 'requested' is unavailable" in caplog.text
+
+ def test_unknown_explicit_key_does_not_substitute(self, caplog) -> None:
+ cfg = JarvisConfig()
+
+ result = get_engine(cfg, engine_key="not-registered")
+
+ assert result is None
+ assert "not registered" in caplog.text
+
+ def test_default_fallback_prefers_same_engine_class(self) -> None:
+ _reg("bad-local", "bad-local")
+ _reg("a-cloud", "a-cloud")
+ _reg("z-local", "z-local")
+
+ class _Cloud(_FakeEngine):
+ is_cloud = True
+
+ cfg = JarvisConfig()
+ cfg.engine.default = "bad-local"
+
+ def _make(k, c): # noqa: ANN001
+ if k == "bad-local":
+ return _FakeEngine(healthy=False)
+ if k == "a-cloud":
+ return _Cloud(healthy=True)
+ return _FakeEngine(healthy=(k == "z-local"))
+
+ with mock.patch(
+ "openjarvis.engine._discovery._make_engine",
+ side_effect=_make,
+ ):
+ result = get_engine(cfg)
+
+ assert result is not None
+ assert result[0] == "z-local"
+
+ def test_cross_boundary_default_fallback_is_named(self, caplog) -> None:
+ _reg("bad-local", "bad-local")
+ _reg("cloud-only", "cloud-only")
+
+ class _Cloud(_FakeEngine):
+ is_cloud = True
+
+ cfg = JarvisConfig()
+ cfg.engine.default = "bad-local"
+
+ def _make(k, c): # noqa: ANN001
+ if k == "bad-local":
+ return _FakeEngine(healthy=False)
+ return _Cloud(healthy=(k == "cloud-only"))
+
+ with mock.patch(
+ "openjarvis.engine._discovery._make_engine",
+ side_effect=_make,
+ ):
+ result = get_engine(cfg)
+
assert result is not None
- assert result[0] == "running"
+ assert result[0] == "cloud-only"
+ assert "across the local/cloud boundary" in caplog.text
def test_skips_engine_that_cannot_serve_model(self) -> None:
"""#532: a healthy engine that can't serve the requested model is
diff --git a/tests/engine/test_optional_imports.py b/tests/engine/test_optional_imports.py
new file mode 100644
index 00000000..90838653
--- /dev/null
+++ b/tests/engine/test_optional_imports.py
@@ -0,0 +1,22 @@
+"""Diagnostics for optional inference-engine imports."""
+
+from __future__ import annotations
+
+import logging
+from unittest import mock
+
+
+def test_optional_engine_import_errors_are_logged(caplog) -> None:
+ import openjarvis.engine as engine_module
+
+ caplog.set_level(logging.DEBUG, logger="openjarvis.engine")
+ with mock.patch.object(
+ engine_module.importlib,
+ "import_module",
+ side_effect=ImportError("renamed SDK symbol"),
+ ):
+ engine_module._register_optional_engines()
+
+ assert "Optional engine 'cloud' unavailable: renamed SDK symbol" in caplog.text
+ assert "Optional engine 'litellm' unavailable: renamed SDK symbol" in caplog.text
+ assert "Optional engine 'gemma_cpp' unavailable: renamed SDK symbol" in caplog.text