AbstractRuntime 0.18.2__tar.gz → 0.18.3__tar.gz

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/CHANGELOG.md

@@ -10,6 +10,17 @@ Unreleased changes live in [`changelog.d/`](changelog.d/README.md), one file per
 
 ## [Unreleased]
 
+## [0.18.3] - 2026-11-07
+
+### Fixed
+
+- **A voice engine that cannot run says why in plain words** (`integrations/abstractcore/discovery_queries.py`,
+  framework backlog 0968). When the engine raised while `local_list_tts_models` was building the listing, the
+  listing's `error` was the bare exception text (for example "No module named 'kokoro'"). It is now AbstractVoice's
+  own `unavailable_reason`: from the catalog already returned, or else from the engine-free providers-only catalog.
+  Only when neither gives one is the exception kept, worded for a person: "the text-to-speech engine could not list
+  its models: ...".
+
 ## [0.18.2] - 2026-11-07
 
 ### Fixed

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.18.2
+Version: 0.18.3
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime
@@ -51,16 +51,21 @@ Description-Content-Type: text/markdown
 
 # AbstractRuntime
 
-**Release 0.18.2:** Embedding imports use the public AbstractCore module and preserve actionable import errors. See [release notes](CHANGELOG.md).
+**Release 0.18.3:** A voice engine that cannot run says why in plain words when its models are listed. See [release notes](CHANGELOG.md).
 
 **AbstractRuntime** is a durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.18.2 • **Python:** 3.10+
+**Version:** 0.18.3 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.18.3
+
+Listing text-to-speech models when the voice engine cannot run now gives AbstractVoice's own reason in
+plain words (for example that the engine is not installed or no API key is set) instead of a bare Python error.
+
 ## What's new in 0.18.2
 
 An embedding import failure now reports its real cause (for example a missing dependency) instead of a

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/README.md

@@ -1,15 +1,20 @@
 # AbstractRuntime
 
-**Release 0.18.2:** Embedding imports use the public AbstractCore module and preserve actionable import errors. See [release notes](CHANGELOG.md).
+**Release 0.18.3:** A voice engine that cannot run says why in plain words when its models are listed. See [release notes](CHANGELOG.md).
 
 **AbstractRuntime** is a durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.18.2 • **Python:** 3.10+
+**Version:** 0.18.3 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.18.3
+
+Listing text-to-speech models when the voice engine cannot run now gives AbstractVoice's own reason in
+plain words (for example that the engine is not installed or no API key is set) instead of a bare Python error.
+
 ## What's new in 0.18.2
 
 An embedding import failure now reports its real cause (for example a missing dependency) instead of a

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/llms-full.txt

@@ -53,16 +53,21 @@ See llms.txt for the linked index.
 
 # AbstractRuntime
 
-**Release 0.18.2:** Embedding imports use the public AbstractCore module and preserve actionable import errors. See [release notes](CHANGELOG.md).
+**Release 0.18.3:** A voice engine that cannot run says why in plain words when its models are listed. See [release notes](CHANGELOG.md).
 
 **AbstractRuntime** is a durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.18.2 • **Python:** 3.10+
+**Version:** 0.18.3 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.18.3
+
+Listing text-to-speech models when the voice engine cannot run now gives AbstractVoice's own reason in
+plain words (for example that the engine is not installed or no API key is set) instead of a bare Python error.
+
 ## What's new in 0.18.2
 
 An embedding import failure now reports its real cause (for example a missing dependency) instead of a

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/llms.txt

@@ -3,7 +3,7 @@
 > Durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
 
 - Python: 3.10+ (see `pyproject.toml`)
-- Version: 0.18.2
+- Version: 0.18.3
 - Ecosystem: [AbstractFramework](https://github.com/lpalbou/AbstractFramework) umbrella, integrates with [AbstractCore](https://github.com/lpalbou/abstractcore)
 - Hard invariant: `RunState.vars` must be JSON-serializable (`src/abstractruntime/core/models.py`)
 - Current AbstractCore baseline: base `abstractruntime` requires AbstractCore 2.34.0 or newer with its light install (remote providers, tools and the MCP worker, media routing, the `decision` output modality); `abstractruntime[apple]` and `abstractruntime[gpu]` require AbstractCore's `apple` and `gpu` settings (`pyproject.toml`)

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "AbstractRuntime"
-version = "0.18.2"
+version = "0.18.3"
 description = "AbstractRuntime: a durable graph runner designed to pair with AbstractCore."
 readme = "README.md"
 requires-python = ">=3.10"

abstractruntime-0.18.3/release-notes.md

@@ -0,0 +1,8 @@
+### Fixed
+
+- **A voice engine that cannot run says why in plain words** (`integrations/abstractcore/discovery_queries.py`,
+  framework backlog 0968). When the engine raised while `local_list_tts_models` was building the listing, the
+  listing's `error` was the bare exception text (for example "No module named 'kokoro'"). It is now AbstractVoice's
+  own `unavailable_reason`: from the catalog already returned, or else from the engine-free providers-only catalog.
+  Only when neither gives one is the exception kept, worded for a person: "the text-to-speech engine could not list
+  its models: ...".

{abstractruntime-0.18.2 → abstractruntime-0.18.3}/src/abstractruntime/integrations/abstractcore/discovery_queries.py

@@ -1156,6 +1156,32 @@ def local_get_voice_catalog(
     return _filter_voice_catalog_response(payload, provider=provider, model=model, providers_only=providers_only)
 
 
+def _catalog_unavailable_reason(catalog: Any) -> Optional[str]:
+    reason = catalog.get("unavailable_reason") if isinstance(catalog, dict) else None
+    return reason.strip() if isinstance(reason, str) and reason.strip() else None
+
+
+def _tts_listing_failure_reason(voice: Any, catalog: Any, *, provider: Optional[str], exc: Exception) -> str:
+    """The `error` of a TTS listing whose engine raised: AbstractVoice's own reason first (0968).
+
+    A voice engine that cannot run often raises while it is being built, before any
+    catalog comes back, so the bare exception text ("No module named ...") used to be
+    the whole answer. The catalog it already returned, or else the engine-free
+    providers-only catalog, says why in plain words (`unavailable_reason`); the
+    exception is kept, worded for a person, only when neither does.
+    """
+    reason = _catalog_unavailable_reason(catalog)
+    if reason is None and voice is not None and hasattr(voice, "voice_catalog"):
+        try:
+            reason = _catalog_unavailable_reason(voice.voice_catalog(provider=provider, providers_only=True))
+        except Exception:
+            reason = None
+    if reason is not None:
+        return reason
+    detail = str(exc).strip() or type(exc).__name__
+    return f"the text-to-speech engine could not list its models: {detail}"
+
+
 def local_list_tts_models(
     *,
     base_url: Optional[str] = None,
@@ -1163,6 +1189,8 @@ def local_list_tts_models(
     voice_openai_api_key: Optional[str] = None,
     provider: Optional[str] = None,
 ) -> Dict[str, Any]:
+    voice: Any = None
+    catalog: Any = {}
     try:
         voice = _runtime_capability_registry(
             voice_base_url=base_url,
@@ -1186,7 +1214,7 @@ def local_list_tts_models(
                 },
                 source="abstractvoice.local",
                 available=False,
-                error=str(exc),
+                error=_tts_listing_failure_reason(voice, catalog, provider=provider, exc=exc),
             ),
             provider=provider,
             model_keys=("models_by_provider", "tts_models_by_provider"),

abstractruntime-0.18.3/tests/test_discovery_tts_unavailable_reason.py

@@ -0,0 +1,108 @@
+"""An unavailable TTS listing says WHY (voice tag gate follow-up).
+
+`local_list_tts_models` answered `available: false, error: null` for a provider
+that cannot run (OpenAI without a key, an unknown provider id): the reason
+AbstractVoice (>= 0.13) puts in the catalog's `unavailable_reason` was dropped.
+It is now the listing's `error`.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from abstractruntime.integrations.abstractcore import discovery_queries as dq
+
+# AbstractVoice is a declared dependency (through AbstractCore's light install):
+# the first two tests run the real catalog, engine-free, with no key configured.
+
+
+@pytest.fixture()
+def no_voice_keys(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    for name in ("OPENAI_API_KEY", "ABSTRACTVOICE_OPENAI_API_KEY", "OPENAI_BASE_URL"):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+
+
+def test_openai_without_a_key_names_the_missing_key(no_voice_keys) -> None:
+    out = dq.local_list_tts_models(provider="openai")
+    assert out["available"] is False and out["models"] == []
+    assert out["error"] and "OpenAI API key" in out["error"]
+
+
+def test_unknown_provider_says_it_is_unknown(no_voice_keys) -> None:
+    out = dq.local_list_tts_models(provider="no-such-engine")
+    assert out["available"] is False
+    assert out["error"] and "not a known text-to-speech provider" in out["error"]
+
+
+def test_the_error_is_the_catalogs_unavailable_reason(monkeypatch: pytest.MonkeyPatch) -> None:
+    voice = SimpleNamespace(
+        voice_catalog=lambda provider=None: {"tts_providers": [], "unavailable_reason": "engine X is not installed"},
+        list_tts_models=lambda provider=None: [],
+    )
+    monkeypatch.setattr(dq, "_runtime_capability_registry", lambda **_: SimpleNamespace(voice=voice))
+    assert dq.local_list_tts_models(provider="x")["error"] == "engine X is not installed"
+    # An available listing never carries it.
+    voice.voice_catalog = lambda provider=None: {"tts_providers": ["x"], "tts_models_by_provider": {"x": ["m"]},
+                                                 "unavailable_reason": None}
+    voice.list_tts_models = lambda provider=None: ["m"]
+    ok = dq.local_list_tts_models(provider="x")
+    assert ok["available"] is True and ok["error"] is None
+
+
+# 0968: an engine that RAISES while the listing is built (it cannot run, so building it
+# fails) used to answer with the bare exception text. The reason AbstractVoice gives
+# in plain words wins; the exception is kept, worded for a person, only as a fallback.
+
+
+def _raising_voice(full_catalog_error: Exception, light_catalog: object) -> SimpleNamespace:
+    def voice_catalog(provider=None, providers_only=False):
+        if providers_only:
+            if isinstance(light_catalog, Exception):
+                raise light_catalog
+            return light_catalog
+        raise full_catalog_error
+
+    return SimpleNamespace(voice_catalog=voice_catalog, list_tts_models=lambda provider=None: [])
+
+
+def test_a_raising_engine_answers_with_the_engine_free_catalogs_reason(monkeypatch: pytest.MonkeyPatch) -> None:
+    voice = _raising_voice(
+        ModuleNotFoundError("No module named 'kokoro'"),
+        {"tts_providers": [], "unavailable_reason": "Kokoro is not installed; install abstractvoice[kokoro]"},
+    )
+    monkeypatch.setattr(dq, "_runtime_capability_registry", lambda **_: SimpleNamespace(voice=voice))
+    out = dq.local_list_tts_models(provider="kokoro")
+    assert out["available"] is False and out["models"] == []
+    assert out["error"] == "Kokoro is not installed; install abstractvoice[kokoro]"
+
+
+def test_a_listing_that_raises_after_the_catalog_keeps_the_catalogs_reason(monkeypatch: pytest.MonkeyPatch) -> None:
+    def list_tts_models(provider=None):
+        raise RuntimeError("engine build failed")
+
+    voice = SimpleNamespace(
+        voice_catalog=lambda provider=None, providers_only=False: {"unavailable_reason": "no OpenAI API key is configured"},
+        list_tts_models=list_tts_models,
+    )
+    monkeypatch.setattr(dq, "_runtime_capability_registry", lambda **_: SimpleNamespace(voice=voice))
+    assert dq.local_list_tts_models(provider="openai")["error"] == "no OpenAI API key is configured"
+
+
+def test_with_no_reason_the_exception_is_worded_for_a_person(monkeypatch: pytest.MonkeyPatch) -> None:
+    for light in ({"tts_providers": ["piper"], "unavailable_reason": None}, RuntimeError("light failed too")):
+        voice = _raising_voice(RuntimeError("weights are corrupt"), light)
+        monkeypatch.setattr(dq, "_runtime_capability_registry", lambda **_: SimpleNamespace(voice=voice))
+        out = dq.local_list_tts_models(provider="piper")
+        assert out["available"] is False
+        assert out["error"] == "the text-to-speech engine could not list its models: weights are corrupt"
+
+
+def test_an_empty_exception_still_names_what_went_wrong(monkeypatch: pytest.MonkeyPatch) -> None:
+    def broken_registry(**_):
+        raise ImportError()
+
+    monkeypatch.setattr(dq, "_runtime_capability_registry", broken_registry)
+    assert dq.local_list_tts_models()["error"] == "the text-to-speech engine could not list its models: ImportError"

abstractruntime-0.18.2/release-notes.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Embedding imports preserve their original error and use the public AbstractCore module path.

abstractruntime-0.18.2/tests/test_discovery_tts_unavailable_reason.py

@@ -1,52 +0,0 @@
-"""An unavailable TTS listing says WHY (voice tag gate follow-up).
-
-`local_list_tts_models` answered `available: false, error: null` for a provider
-that cannot run (OpenAI without a key, an unknown provider id): the reason
-AbstractVoice (>= 0.13) puts in the catalog's `unavailable_reason` was dropped.
-It is now the listing's `error`.
-"""
-
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-from abstractruntime.integrations.abstractcore import discovery_queries as dq
-
-# AbstractVoice is a declared dependency (through AbstractCore's light install):
-# the first two tests run the real catalog, engine-free, with no key configured.
-
-
-@pytest.fixture()
-def no_voice_keys(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
-    for name in ("OPENAI_API_KEY", "ABSTRACTVOICE_OPENAI_API_KEY", "OPENAI_BASE_URL"):
-        monkeypatch.delenv(name, raising=False)
-    monkeypatch.setenv("HOME", str(tmp_path))
-
-
-def test_openai_without_a_key_names_the_missing_key(no_voice_keys) -> None:
-    out = dq.local_list_tts_models(provider="openai")
-    assert out["available"] is False and out["models"] == []
-    assert out["error"] and "OpenAI API key" in out["error"]
-
-
-def test_unknown_provider_says_it_is_unknown(no_voice_keys) -> None:
-    out = dq.local_list_tts_models(provider="no-such-engine")
-    assert out["available"] is False
-    assert out["error"] and "not a known text-to-speech provider" in out["error"]
-
-
-def test_the_error_is_the_catalogs_unavailable_reason(monkeypatch: pytest.MonkeyPatch) -> None:
-    voice = SimpleNamespace(
-        voice_catalog=lambda provider=None: {"tts_providers": [], "unavailable_reason": "engine X is not installed"},
-        list_tts_models=lambda provider=None: [],
-    )
-    monkeypatch.setattr(dq, "_runtime_capability_registry", lambda **_: SimpleNamespace(voice=voice))
-    assert dq.local_list_tts_models(provider="x")["error"] == "engine X is not installed"
-    # An available listing never carries it.
-    voice.voice_catalog = lambda provider=None: {"tts_providers": ["x"], "tts_models_by_provider": {"x": ["m"]},
-                                                 "unavailable_reason": None}
-    voice.list_tts_models = lambda provider=None: ["m"]
-    ok = dq.local_list_tts_models(provider="x")
-    assert ok["available"] is True and ok["error"] is None