Celune 4.2.0

.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Sync dependencies
-        run: uv sync --dev
+        run: uv sync --dev --all-extras
 
       - name: Verify formatting
         run: uv run ruff format --check .

AGENTS.md

@@ -73,15 +73,15 @@ Do not modify the execution environment to work around failures.
 
 Before CI, format the repository with `uv run ruff format .`.
 
-Expected CI runtime is 3-5 minutes.
+Expected CI runtime is around 5 minutes.
 
 If CI runtime exceeds 5 minutes:
 - Assume it may have stalled.
 - Stop it from running any further.
 - Report that the CI has taken too long.
 - Do not try to extend any timeouts.
-- Do not try to work around the problem.
-- Wait for any further guidance.
+- Attempt to run again only the relevant CI steps in isolation.
+- If the isolated CI attempts also fail or time out, report it back.
 
 After each task, run `scripts/update_docstrings.py` and then replace placeholders in docstrings like:
 
@@ -100,15 +100,25 @@ Returns:
 
 with proper documentation, while preserving the docstring format.
 
+If this process updates typing or dataclass related docstrings, remove the placeholders instead of completing them.
+
 This process may leave some formatting inaccuracies, run `uv run ruff format .` again after completing docstrings.
 
-If CI fails or times out, report the actual failure clearly. Do not claim success.
+## Localization
+
+Celune does not use hardcoded strings in English. Define each new string you add into Celune's localization string database.
+
+Do not use raw string literals in the code. Always use `string("key_name", **kwargs)` in string literals to populate them from the global localization string database.
+
+If you find any raw strings in the code, add them to the localization string database, and remove the hardcoded string.
+
+Make sure to only modify user-facing strings (both normal and dev mode strings), don't change anything internal.
 
 ## Python and Environment
 
 * Supported Python versions are 3.12 and 3.13.
 * Use `uv` for environment management.
-* Do not use `pip` directly unless explicitly required.
+* Do not use `pip` directly unless explicitly required. If you need to run `pip` alone, do it so with `uv pip` instead.
 * Do not assume CPU-only mode supports all features. CPU-only execution is only supported with Celune Mini.
 * Be aware that many features require an RTX 30 series GPU or newer.
 

README.md

@@ -331,6 +331,33 @@ Without this, Celune may require elevated permissions or fall back to slower beh
 See [API.md](./API.md) for REST API configuration, authentication, endpoints, and cURL examples.
 The API allows programmatic usage of all Celune features. It can be used both as a public and local interface.
 
+## Extensions
+
+Celune comes with extension support, allowing custom code to run with the engine.
+
+Extensions may subscribe at will to certain core events with `@celune.subscribe(...)`.
+
+Celune exposes the following core events to extensions:
+
+- `ready`
+- `shutdown`
+- `fatal`
+- `error`
+- `voice_changed`
+- `state_changed`
+- `generation_start`
+- `generation_end`
+- `generation_error`
+- `audio_start`
+- `audio_end`
+- `character_changed`
+- `character_loaded`
+- `character_unloaded`
+
+For example extension usage, check the [example extension](./extensions/test.py).
+
+The aforementioned extension defines a basic usage case for Celune extensions.
+
 ## Web UI
 
 Celune exposes a web interface for remote access to Celune. It reuses the Celune API commands to provide an interface for control.

celune/__init__.py

@@ -17,13 +17,21 @@
 import sys as _sys
 import inspect as _inspect
 import subprocess as _subprocess
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Callable, Union
 
 from .constants import APP_NAME
+from .paths import (
+    configure_huggingface_cache_environment,
+    configure_huggingface_runtime,
+)
+
+configure_huggingface_cache_environment()
+configure_huggingface_runtime()
 
 if TYPE_CHECKING:
     from .celune import Celune
     from .extensions.base import CeluneContext, CeluneExtension
+    from .extensions.events import subscribe
 
 
 def _get_revision() -> str:
@@ -60,7 +68,7 @@ def _caller_is_repl() -> bool:
 
 
 REVISION = _get_revision()
-VERSION = "4.1.2"
+VERSION = "4.2.0"
 
 if REVISION:
     _local = REVISION.rstrip("*")
@@ -84,7 +92,12 @@ def _caller_is_repl() -> bool:
 
 def __getattr__(
     name: str,
-) -> Union[type["Celune"], type["CeluneContext"], type["CeluneExtension"]]:
+) -> Union[
+    type["Celune"],
+    type["CeluneContext"],
+    type["CeluneExtension"],
+    Callable[..., Callable[..., None]],
+]:
     if name == "Celune":
         from .celune import Celune
 
@@ -100,6 +113,11 @@ def __getattr__(
 
         return CeluneExtension
 
+    if name == "subscribe":
+        from .extensions.events import subscribe
+
+        return subscribe
+
     raise AttributeError(f"module '{__name__!r}' has no attribute '{name!r}'")
 
 
@@ -108,6 +126,7 @@ def __getattr__(
     "CeluneContext",
     "CeluneExtension",
     "REVISION",
+    "subscribe",
     "__version__",
     "__tagline__",
     "__codename__",

celune/analysis.py

@@ -17,7 +17,11 @@
 from transformers import AutoModel, AutoProcessor
 
 from .cevoice import ManifestValue, default_loader
-from .constants import VOICE_EMBEDDING_MODEL, N_A_NUMERIC
+from .constants import (
+    VOICE_EMBEDDING_MODEL,
+    N_A_NUMERIC,
+    remote_code_model_revision,
+)
 from .typing.analysis import (
     EmbeddingPayload,
     EmbeddingModel,
@@ -318,18 +322,21 @@ def _load_embedding_model() -> tuple[EmbeddingProcessor, EmbeddingModel]:
     global _EMBEDDING_MODEL, _EMBEDDING_PROCESSOR
 
     if _EMBEDDING_MODEL is None or _EMBEDDING_PROCESSOR is None:
+        revision = remote_code_model_revision(VOICE_EMBEDDING_MODEL)
         _EMBEDDING_PROCESSOR = cast(
             EmbeddingProcessor,
             AutoProcessor.from_pretrained(
                 VOICE_EMBEDDING_MODEL,
                 trust_remote_code=True,
+                revision=revision,
             ),
         )
         _EMBEDDING_MODEL = cast(
             EmbeddingModel,
             AutoModel.from_pretrained(
                 VOICE_EMBEDDING_MODEL,
                 trust_remote_code=True,
+                revision=revision,
             ),
         )
         _EMBEDDING_MODEL.eval()