Release 0.10.19: engine-free voice discovery

Provider and model discovery is answered from the model cache instead of by
loading engines, so listing no longer imports torch/transformers or loads
weights. With ABSTRACTVOICE_TTS_ENGINE=audiodit, list_tts_models() goes from
28.6s to 0.07s and list_cloning_models() from 49.5s to 0.2s, and local engines
report their own model ids instead of Piper's.

Remote providers are probed concurrently under one 5s discovery budget
(ABSTRACTVOICE_DISCOVERY_TIMEOUT_S), and a provider that does not answer is
marked unreachable rather than reported as having no models.

A local engine is now listed when its models are present on the machine;
selecting an uncached engine still downloads on demand.

Adds abstractvoice.local_models, docs/troubleshooting.md, CODE_OF_CONDUCT.md,
and refreshes the docs set plus llms.txt / llms-full.txt.

Author: lpalbou

CHANGELOG.md

@@ -10,9 +10,56 @@ Older changelog entries may reference historical CLI commands or model choices.
 
 ## [Unreleased]
 
+## [0.10.19] - 2026-08-03
+
+### Changed
+- **Provider and model discovery no longer loads engines.** Listing providers, models, or voices is
+  now answered from the model cache, so it does not import torch or transformers and does not load
+  weights. With `ABSTRACTVOICE_TTS_ENGINE=audiodit`, `list_tts_models()` goes from 28.6s to 0.07s and
+  `list_cloning_models()` from 49.5s to 0.2s, with the same content. Local engines also report their
+  own model ids — `meituan-longcat/LongCat-AudioDiT-1B`, `k2-fsa/OmniVoice` — where previously they
+  reported Piper's voices.
+
+  Engine-free surfaces: `available_providers()`, `list_models(...)` for every kind and filter,
+  `list_tts_voices(provider=...)`, `compatibility_catalog()`, `capability_support()`,
+  `find_compatible_models()`, `voice_catalog(providers_only=True)`, and
+  `voice_catalog(provider=<local>)`. The unfiltered `voice_catalog()`, `list_profiles()`, and
+  `list_cloned_voices()` report the active engine's live state and still build it; see the cost model
+  in `docs/api.md`.
+- **A local TTS engine is listed when its models are present on the machine.** `audiodit` and
+  `omnivoice` previously appeared whenever their runtime was importable, even with nothing
+  downloaded; `piper` and `supertonic` already required a populated cache. Selecting an engine that
+  has nothing downloaded still works and still downloads on demand with `allow_downloads=True` —
+  only the listing changed. Prefetch an engine (`python -m abstractvoice download --audiodit`) to
+  have it listed. A checkpoint configured through `ABSTRACTVOICE_TTS_MODEL` counts as present, so
+  your own finetune is selectable; it applies to the engine named by `ABSTRACTVOICE_TTS_ENGINE`.
+- **Remote providers are probed concurrently under one 5-second discovery budget**, instead of one
+  synthesis-length timeout each in sequence. An unreachable host now costs one pause for the whole
+  listing. Override the budget with `ABSTRACTVOICE_DISCOVERY_TIMEOUT_S`; the per-request socket
+  timeout is the smaller of the budget and `ABSTRACTVOICE_REMOTE_TIMEOUT_S`.
+
+### Added
+- `abstractvoice.local_models` for reading what is on the machine without loading an engine:
+  `cached_tts_model_ids(engine)` and `hf_repo_is_cached(model_id)`. `abstractvoice.adapters.tts_piper`
+  gains `cached_piper_model_ids()` and `cached_piper_voice_profiles()`.
+- `voice_catalog()` reports reachability: `unreachable_tts_providers`, plus an `unreachable` flag on
+  the affected `tts_catalog_by_provider` entry. A provider that did not answer within the budget is
+  marked rather than reported as a provider with no models, so an unavailable server is
+  distinguishable from an empty one. The key is absent on catalog paths that contact nobody.
+- `docs/troubleshooting.md`, a symptom-oriented page covering install, discovery, audio devices, and
+  performance; and `CODE_OF_CONDUCT.md`.
+
 ### Fixed
-- **Capability asset loading survives package-name shadowing (laurent's offline voice outage, 2026-07-17)**: a serving process launched with cwd = the monorepo root resolves `abstractvoice` as a loaderless NAMESPACE package (the repo checkout directory shadows the installed package on `sys.path[0]`), so `pkgutil.get_data("abstractvoice", ...)` returned `None` and every voice call died with `Capability asset not found: abstractvoice/assets/voice_model_capabilities.json` — retried as if transient, burning the effect retry budget on a deterministic import-layout error. `compatibility._load_capability_asset` now resolves the asset relative to the module's own `__file__` first (immune to the shadow: this module was imported from the real install even when the package NAME resolves to the shadow), keeps `pkgutil` as the fallback for non-filesystem installs, and when both fail raises a diagnostic error that names the attempted path and the namespace-shadow condition (`abstractvoice resolved as a NAMESPACE package from [...] — a directory named 'abstractvoice' on sys.path ... is shadowing the installed package`) instead of the honest-but-mute one-liner. Regression pins in `tests/test_compatibility_catalog.py`.
-- **Builtin voice profiles survive the same shadow (silent-degradation shape, found hunting the class)**: `voice_profiles.get_builtin_voice_profiles` resolved its JSON assets via `importlib.resources.files("abstractvoice")` — also keyed on the package NAME — and under the cwd shadow returned `[]` silently: the supertonic builtin profiles (incl. the operator's configured `M1`/`M2` voices) vanished with no error (live-verified: 10 profiles from a neutral cwd, 0 under the shadow, 10 after the fix). Now resolves module-`__file__`-relative first with `importlib.resources` as the fallback; genuinely absent engine files still return `[]` (piper has no builtin profiles file — legitimate absence, unchanged). Suite 218 green.
+- `voice_catalog(provider="piper")` now includes Piper's voice profiles. Piper ships no packaged
+  profile asset because its voices are its downloaded files, so both catalog paths read them from the
+  same cache probe that reports its model ids.
+- Capability assets and built-in voice profiles load correctly when a directory named
+  `abstractvoice` on `sys.path` shadows the installed package — for example a server started with the
+  working directory set to a monorepo root. Previously voice calls could fail with
+  `Capability asset not found: abstractvoice/assets/voice_model_capabilities.json`, or built-in
+  Supertonic profiles (`M1`–`M5`, `F1`–`F5`) could come back empty with no error. Both now resolve
+  their assets relative to the module file, and an unresolvable asset raises an error that names the
+  shadowing condition.
 
 ## [0.10.18] - 2026-06-14
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,50 @@
+# Code of Conduct
+
+## Our Pledge
+
+We want AbstractVoice to be a project that anyone can use, learn from, and contribute to. We pledge
+to make participation a harassment-free experience for everyone, regardless of age, body size,
+visible or invisible disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Behavior that helps this community:
+
+- Being kind and respectful to other people
+- Assuming good faith, and asking before assuming a mistake was careless
+- Giving and accepting constructive feedback about the work rather than the person
+- Being clear about what you verified and what you are guessing
+- Taking responsibility for mistakes, correcting them, and moving on
+
+Behavior that is not acceptable:
+
+- Harassment, insults, or derogatory comments, public or private
+- Sexualized language or imagery, and unwelcome sexual attention
+- Publishing others' private information without explicit permission
+- Sustained disruption of discussions, issues, or reviews
+- Other conduct that would reasonably be considered inappropriate in a professional setting
+
+## Scope
+
+This Code of Conduct applies in all project spaces — issues, pull requests, discussions, commit
+messages, and documentation — and when an individual is representing the project in public spaces.
+
+## Reporting
+
+Report unacceptable behavior by opening a confidential report through the process in `SECURITY.md`,
+or by contacting the maintainer directly through the address listed on the repository's GitHub
+profile. Reports are reviewed as promptly as the maintainer's availability allows, and the reporter's
+identity is kept confidential.
+
+## Enforcement
+
+Maintainers are responsible for clarifying and enforcing these standards. They may edit, remove, or
+reject comments, commits, code, issues, and other contributions that do not align with this Code of
+Conduct, and may temporarily or permanently ban any contributor for behavior they judge
+inappropriate, threatening, offensive, or harmful.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

abstractvoice/_version.py

@@ -3,4 +3,4 @@
 This file is the single source of truth for AbstractVoice releases.
 """
 
-__version__ = "0.10.18"
+__version__ = "0.10.19"

abstractvoice/adapters/tts_piper.py

@@ -26,6 +26,16 @@
 logger = logging.getLogger(__name__)
 
 
+def default_piper_model_dir() -> Path:
+    """Directory Piper voice files are downloaded into."""
+    return Path.home() / '.piper' / 'models'
+
+
+def _piper_model_files(model_dir: Path, model_filename: str) -> tuple[Path, Path]:
+    """(weights, config) paths for a Piper voice inside `model_dir`."""
+    return model_dir / f"{model_filename}.onnx", model_dir / f"{model_filename}.onnx.json"
+
+
 class PiperTTSAdapter(TTSAdapter):
     """Piper TTS adapter using piper-tts package.
     
@@ -81,8 +91,7 @@ def __init__(
 
         # Set model directory
         if model_dir is None:
-            home = Path.home()
-            self._model_dir = home / '.piper' / 'models'
+            self._model_dir = default_piper_model_dir()
         else:
             self._model_dir = Path(model_dir)
 
@@ -160,41 +169,7 @@ def _voice_id_from_hf_path(hf_path: str) -> str:
         return parts[2] if len(parts) >= 3 else str(hf_path or "")
 
     def _profile_for_language(self, language: str) -> Optional[VoiceProfile]:
-        model_info = self.PIPER_MODELS.get(str(language or ""))
-        if not model_info:
-            return None
-
-        hf_path, model_filename = model_info
-        voice_id = self._voice_id_from_hf_path(hf_path)
-        if not voice_id:
-            return None
-
-        cached = False
-        try:
-            model_path, config_path = self._get_model_path(str(language))
-            cached = model_path.exists() and config_path.exists()
-        except Exception:
-            cached = False
-
-        return VoiceProfile(
-            engine_id="piper",
-            profile_id=voice_id,
-            label=f"Piper {voice_id}",
-            description=f"Default Piper voice for {language}",
-            params={
-                "provider": "piper",
-                "language": str(language),
-                "voice": voice_id,
-                "model": model_filename,
-                "model_filename": model_filename,
-            },
-            tags={
-                "provider": "piper",
-                "engine_id": "piper",
-                "kind": "profile",
-                "cached": "true" if cached else "false",
-            },
-        )
+        return _piper_voice_profile(self._model_dir, language)
 
     def _profile_candidates_for_language(self, language: str) -> set[str]:
         model_info = self.PIPER_MODELS.get(str(language or ""))
@@ -230,10 +205,7 @@ def _get_model_path(self, language: str) -> tuple[Path, Path]:
             raise ValueError(f"Unsupported language: {language}")
 
         _, model_filename = model_info
-        model_path = self._model_dir / f"{model_filename}.onnx"
-        config_path = self._model_dir / f"{model_filename}.onnx.json"
-        
-        return model_path, config_path
+        return _piper_model_files(self._model_dir, model_filename)
 
     def ensure_model_downloaded(self, language: str) -> bool:
         """Explicitly download Piper model files for a language (no implicit calls).
@@ -784,3 +756,72 @@ def _parse_size_mb(size: str) -> int:
             }
 
         return models
+
+
+def _piper_voice_profile(model_dir: Path, language: str) -> Optional[VoiceProfile]:
+    """The voice profile for a Piper language, tagged with whether it is cached."""
+    model_info = PiperTTSAdapter.PIPER_MODELS.get(str(language or ""))
+    if not model_info:
+        return None
+
+    hf_path, model_filename = model_info
+    voice_id = PiperTTSAdapter._voice_id_from_hf_path(hf_path)
+    if not voice_id:
+        return None
+
+    weights, config = _piper_model_files(Path(model_dir), model_filename)
+    cached = weights.is_file() and config.is_file()
+
+    return VoiceProfile(
+        engine_id="piper",
+        profile_id=voice_id,
+        label=f"Piper {voice_id}",
+        description=f"Default Piper voice for {language}",
+        params={
+            "provider": "piper",
+            "language": str(language),
+            "voice": voice_id,
+            "model": model_filename,
+            "model_filename": model_filename,
+        },
+        tags={
+            "provider": "piper",
+            "engine_id": "piper",
+            "kind": "profile",
+            "cached": "true" if cached else "false",
+        },
+    )
+
+
+def _cached_piper_languages(model_dir: Optional[str]) -> tuple[Path, list[str]]:
+    """(voice directory, languages whose weights AND config are both present).
+
+    The single presence predicate behind both public probes, so the model ids and
+    the voice profiles can never disagree about what is downloaded. Filesystem
+    only: constructing the adapter imports `piper` and through it ONNX Runtime,
+    which is a synthesis cost, not a discovery cost.
+    """
+    root = Path(model_dir).expanduser() if model_dir else default_piper_model_dir()
+    languages = [
+        language
+        for language, (_hf_path, model_filename) in PiperTTSAdapter.PIPER_MODELS.items()
+        if all(path.is_file() for path in _piper_model_files(root, model_filename))
+    ]
+    return root, languages
+
+
+def cached_piper_model_ids(model_dir: Optional[str] = None) -> list[str]:
+    """Piper voice ids whose model files are on this machine."""
+    _root, languages = _cached_piper_languages(model_dir)
+    return [PiperTTSAdapter.PIPER_MODELS[language][1] for language in languages]
+
+
+def cached_piper_voice_profiles(model_dir: Optional[str] = None) -> list[VoiceProfile]:
+    """Voice profiles for the Piper voices on this machine.
+
+    Piper has no packaged profile asset because its voices *are* its downloaded
+    files, so the filesystem is the only honest source.
+    """
+    root, languages = _cached_piper_languages(model_dir)
+    profiles = (_piper_voice_profile(root, language) for language in languages)
+    return [profile for profile in profiles if profile is not None]