Sync text encoder 3.0 fix and smoke checks

kimodo/demo/app.py

@@ -54,14 +54,7 @@ from .state import ClientSession, ModelBundle
 
 class Demo:
     def __init__(self, default_model_name: str = DEFAULT_MODEL):
-        requested_device = (os.environ.get("KIMODO_DEVICE") or "").strip().lower()
-        if requested_device and requested_device != "auto":
-            self.device = requested_device
-        elif HF_MODE:
-            # ZeroGPU can report CUDA availability while blocking low-level CUDA init.
-            self.device = "cpu"
-        else:
-            self.device = "cuda:0" if torch.cuda.is_available() else "cpu"
+        self.device = "cuda:0" if torch.cuda.is_available() else "cpu"
         print(f"Using device: {self.device}")
         self.models: dict[str, ModelBundle] = {}
         resolved = resolve_model_name(default_model_name, "Kimodo")
@@ -110,7 +103,6 @@ class Demo:
         self.floor_len = 20.0  # meters
 
     def ensure_examples_layout(self) -> None:
-        print(f"[kimodo][examples_layout][entry] root={EXAMPLES_ROOT_DIR}")
         os.makedirs(EXAMPLES_ROOT_DIR, exist_ok=True)
         for model_dir in MODEL_EXAMPLES_DIRS.values():
             os.makedirs(model_dir, exist_ok=True)
@@ -128,18 +120,6 @@ class Demo:
             if not os.path.exists(dst):
                 shutil.move(src, dst)
 
-        for model_name, model_dir in MODEL_EXAMPLES_DIRS.items():
-            model_examples = []
-            if os.path.isdir(model_dir):
-                model_examples = sorted([d for d in os.listdir(model_dir) if os.path.isdir(os.path.join(model_dir, d))])
-            print(
-                "[kimodo][examples_layout][model]"
-                f" model={model_name} dir={model_dir} count={len(model_examples)}"
-                f" has_09={'09_qwen_agentic_actions' in model_examples}"
-                f" tail={model_examples[-3:] if len(model_examples) >= 3 else model_examples}"
-            )
-        print("[kimodo][examples_layout][exit]")
-
     def get_examples_base_dir(self, model_name: str, absolute: bool = True) -> str:
         return MODEL_EXAMPLES_DIRS[model_name]
 
@@ -151,7 +131,12 @@ class Demo:
         try:
             model = load_model(modelname=model_name, device=self.device)
         except Exception as e:
-            print(f"Error loading model: {e}\nMake sure text encoder server is running!")
+            print(
+                "Error loading model during Kimodo startup. "
+                "This often means the text encoder server is not running, the Hugging Face token is missing, "
+                "or the gated text encoder model cannot be accessed."
+            )
+            print(f"Original error: {type(e).__name__}: {e}")
             raise e
 
         if hasattr(model, "text_encoder"):
@@ -325,14 +310,6 @@ class Demo:
             model_name=self.default_model_name,
             model_fps=model_bundle.model_fps,
         )
-        dropdown_options = list(gui_examples_dropdown.options)
-        print(
-            "[kimodo][session_setup]"
-            f" client={client.client_id} model={self.default_model_name}"
-            f" example_dict_count={len(example_dict)} dropdown_count={len(dropdown_options)}"
-            f" has_09={'09_qwen_agentic_actions' in dropdown_options}"
-            f" tail={dropdown_options[-3:] if len(dropdown_options) >= 3 else dropdown_options}"
-        )
         timeline_data = {
             "tracks": timeline_tracks,
             "tracks_ids": {val["name"]: key for key, val in timeline_tracks.items()},

kimodo/model/llm2vec/llm2vec.py

@@ -123,7 +123,7 @@ class LLM2Vec(nn.Module):
         # pop out encoder args
         keys = ["pooling_mode", "max_length", "doc_max_length", "skip_instruction"]
         encoder_args = {key: kwargs.pop(key, None) for key in keys if kwargs.get(key) is not None}
-        hf_token = kwargs.get("token")
+        hf_token = kwargs.pop("token", None)
 
         tokenizer = AutoTokenizer.from_pretrained(base_model_name_or_path, token=hf_token)
         tokenizer.pad_token = tokenizer.eos_token
@@ -134,7 +134,7 @@ class LLM2Vec(nn.Module):
 
         model_class = cls._get_model_class(config_class_name, enable_bidirectional=enable_bidirectional)
 
-        model = model_class.from_pretrained(base_model_name_or_path, **kwargs)
+        model = model_class.from_pretrained(base_model_name_or_path, token=hf_token, **kwargs)
 
         if os.path.isdir(base_model_name_or_path) and os.path.exists(f"{base_model_name_or_path}/config.json"):
             with open(f"{base_model_name_or_path}/config.json", "r") as fIn:

kimodo/model/llm2vec/llm2vec_wrapper.py

@@ -24,7 +24,12 @@ class LLM2VecEncoder:
         self.llm_dim = llm_dim
 
         cache_dir = os.environ.get("HUGGINGFACE_CACHE_DIR")
-        hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        hf_token = (
+            os.environ.get("HF_TOKEN")
+            or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+            or os.environ.get("HF_HUB_TOKEN")
+            or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+        )
 
         if "TEXT_ENCODERS_DIR" in os.environ:
             base_model_name_or_path = os.path.join(os.environ["TEXT_ENCODERS_DIR"], base_model_name_or_path)

kimodo/model/load_model.py

@@ -2,8 +2,14 @@
 # SPDX-License-Identifier: Apache-2.0
 """Load Kimodo diffusion models from local checkpoints or Hugging Face."""
 
+import os
+import socket
+import subprocess
+import sys
+import time
 from pathlib import Path
 from typing import Optional
+from urllib.parse import urlparse
 
 from huggingface_hub import snapshot_download
 from omegaconf import OmegaConf
@@ -20,20 +26,98 @@ from .loading import (
 from .registry import get_model_info, resolve_model_name
 
 DEFAULT_TEXT_ENCODER = "llm2vec"
-DEFAULT_LLM2VEC_BASE = "meta-llama/Meta-Llama-3.1-8B-Instruct"
-DEFAULT_LLM2VEC_PEFT = "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised"
 TEXT_ENCODER_PRESETS = {
     "llm2vec": {
         "target": "kimodo.model.LLM2VecEncoder",
         "kwargs": {
-            "base_model_name_or_path": get_env_var("LLM2VEC_BASE_MODEL", DEFAULT_LLM2VEC_BASE),
-            "peft_model_name_or_path": get_env_var("LLM2VEC_PEFT_MODEL", DEFAULT_LLM2VEC_PEFT),
+            "base_model_name_or_path": "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp",
+            "peft_model_name_or_path": "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised",
             "dtype": "bfloat16",
             "llm_dim": 4096,
         },
     }
 }
 
+_TEXT_ENCODER_SERVER_PROCESS: subprocess.Popen | None = None
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = get_env_var(name, str(default)).strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+def _is_local_text_encoder_url(text_encoder_url: str) -> bool:
+    parsed = urlparse(text_encoder_url)
+    host = (parsed.hostname or "").strip().lower()
+    return host in {"127.0.0.1", "localhost", "0.0.0.0"}
+
+
+def _is_port_open(text_encoder_url: str, timeout_sec: float = 1.0) -> bool:
+    parsed = urlparse(text_encoder_url)
+    host = parsed.hostname or "127.0.0.1"
+    if host == "0.0.0.0":
+        host = "127.0.0.1"
+    port = parsed.port or 9550
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(timeout_sec)
+        try:
+            sock.connect((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def _build_text_encoder_env() -> dict[str, str]:
+    env = os.environ.copy()
+    token = (
+        env.get("HF_TOKEN")
+        or env.get("HUGGING_FACE_HUB_TOKEN")
+        or env.get("HF_HUB_TOKEN")
+        or env.get("HUGGINGFACEHUB_API_TOKEN")
+    )
+    if token:
+        env.setdefault("HF_TOKEN", token)
+        env.setdefault("HUGGING_FACE_HUB_TOKEN", token)
+        env.setdefault("HF_HUB_TOKEN", token)
+        env.setdefault("HUGGINGFACEHUB_API_TOKEN", token)
+    return env
+
+
+def _ensure_text_encoder_server(text_encoder_url: str) -> None:
+    global _TEXT_ENCODER_SERVER_PROCESS
+
+    if not _is_local_text_encoder_url(text_encoder_url):
+        return
+    if _is_port_open(text_encoder_url):
+        return
+
+    if _TEXT_ENCODER_SERVER_PROCESS is not None and _TEXT_ENCODER_SERVER_PROCESS.poll() is None:
+        return
+
+    startup_timeout_sec = int(get_env_var("TEXT_ENCODER_STARTUP_TIMEOUT_SEC", "90"))
+    print(f"Starting local text encoder server for URL {text_encoder_url}...")
+    _TEXT_ENCODER_SERVER_PROCESS = subprocess.Popen(
+        [sys.executable, "-m", "kimodo.scripts.run_text_encoder_server"],
+        env=_build_text_encoder_env(),
+    )
+
+    deadline = time.time() + startup_timeout_sec
+    while time.time() < deadline:
+        if _is_port_open(text_encoder_url):
+            print("Text encoder server is reachable.")
+            return
+        if _TEXT_ENCODER_SERVER_PROCESS.poll() is not None:
+            raise RuntimeError(
+                "Text encoder server process exited during startup. "
+                "Check server logs for details from kimodo.scripts.run_text_encoder_server."
+            )
+        time.sleep(1.0)
+
+    raise RuntimeError(
+        "Timed out waiting for local text encoder server to open its port. "
+        "Adjust TEXT_ENCODER_STARTUP_TIMEOUT_SEC if cold starts are slow."
+    )
+
 
 def _resolve_hf_model_path(modelname: str) -> Path:
     """Resolve model name to a local path, using Hugging Face cache or CHECKPOINT_DIR."""
@@ -85,13 +169,21 @@ def _select_text_encoder_conf(text_encoder_url: str) -> dict:
     # - "local": force local LLM2VecEncoder
     # - "auto": try API first, fallback to local if unreachable
     mode = get_env_var("TEXT_ENCODER_MODE", "auto").lower()
+    autostart_enabled = _env_bool("TEXT_ENCODER_AUTOSTART", True)
     if mode == "local":
         return _build_local_text_encoder_conf()
     if mode == "api":
-        return _build_api_text_encoder_conf(text_encoder_url)
+        if autostart_enabled:
+            _ensure_text_encoder_server(text_encoder_url)
+        api_conf = _build_api_text_encoder_conf(text_encoder_url)
+        text_encoder = instantiate_from_dict(api_conf)
+        text_encoder(["healthcheck"])
+        return api_conf
 
     api_conf = _build_api_text_encoder_conf(text_encoder_url)
     try:
+        if autostart_enabled:
+            _ensure_text_encoder_server(text_encoder_url)
         text_encoder = instantiate_from_dict(api_conf)
         # Probe availability early so inference doesn't fail later.
         text_encoder(["healthcheck"])
@@ -179,16 +271,33 @@ def load_model(
         pass
 
     text_encoder_url = get_env_var("TEXT_ENCODER_URL", DEFAULT_TEXT_ENCODER_URL)
+    try:
+        text_encoder_conf = _select_text_encoder_conf(text_encoder_url)
+    except Exception as error:
+        raise RuntimeError(
+            "Failed to prepare the text encoder while loading the model. "
+            "Check TEXT_ENCODER_MODE, TEXT_ENCODER_URL, HF_TOKEN/HUGGING_FACE_HUB_TOKEN, "
+            "and whether the text encoder server is running or the local model cache is complete. "
+            f"Original error: {type(error).__name__}: {error}"
+        ) from error
+
     runtime_conf = OmegaConf.create(
         {
             "checkpoint_dir": str(model_path),
-            "text_encoder": _select_text_encoder_conf(text_encoder_url),
+            "text_encoder": text_encoder_conf,
         }
     )
     model_cfg = OmegaConf.to_container(OmegaConf.merge(model_conf, runtime_conf), resolve=True)
     model_cfg.pop("checkpoint_dir", None)
 
-    model = instantiate_from_dict(model_cfg, overrides={"device": device})
+    try:
+        model = instantiate_from_dict(model_cfg, overrides={"device": device})
+    except Exception as error:
+        raise RuntimeError(
+            "Kimodo model initialization failed after text encoder setup. "
+            "This usually means the base checkpoint, text encoder, or adapter could not be loaded. "
+            f"Original error: {type(error).__name__}: {error}"
+        ) from error
     if eval_mode:
         model = model.eval()
     if return_resolved_name:

kimodo/scripts/run_text_encoder_server.py

@@ -4,10 +4,9 @@
 import argparse
 import os
 
-os.environ.pop("GRADIO_HOT_RELOAD", None)
-
 import gradio as gr
 import numpy as np
+from huggingface_hub import HfApi
 
 from kimodo.model import resolve_target
 
@@ -19,14 +18,12 @@ DEFAULT_SERVER_NAME = "0.0.0.0"
 DEFAULT_SERVER_PORT = 9550
 DEFAULT_TMP_FOLDER = "/tmp/text_encoder/"
 DEFAULT_TEXT_ENCODER = "llm2vec"
-DEFAULT_LLM2VEC_BASE = "meta-llama/Meta-Llama-3.1-8B-Instruct"
-DEFAULT_LLM2VEC_PEFT = "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised"
 TEXT_ENCODER_PRESETS = {
     "llm2vec": {
         "target": "kimodo.model.LLM2VecEncoder",
         "kwargs": {
-            "base_model_name_or_path": os.getenv("LLM2VEC_BASE_MODEL", DEFAULT_LLM2VEC_BASE),
-            "peft_model_name_or_path": os.getenv("LLM2VEC_PEFT_MODEL", DEFAULT_LLM2VEC_PEFT),
+            "base_model_name_or_path": "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp",
+            "peft_model_name_or_path": "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised",
             "dtype": "bfloat16",
             "llm_dim": 4096,
         },
@@ -35,6 +32,53 @@ TEXT_ENCODER_PRESETS = {
 }
 
 
+def _get_hf_token() -> str | None:
+    return (
+        os.environ.get("HF_TOKEN")
+        or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        or os.environ.get("HF_HUB_TOKEN")
+        or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+    )
+
+
+def _validate_text_encoder_startup(text_encoder_name: str) -> None:
+    """Fail fast before launching Gradio if the text encoder cannot be resolved."""
+    if text_encoder_name not in TEXT_ENCODER_PRESETS:
+        available = ", ".join(sorted(TEXT_ENCODER_PRESETS))
+        raise ValueError(f"Unknown TEXT_ENCODER='{text_encoder_name}'. Available: {available}")
+
+    preset = TEXT_ENCODER_PRESETS[text_encoder_name]
+    token = _get_hf_token()
+    text_encoders_dir = os.environ.get("TEXT_ENCODERS_DIR")
+
+    if text_encoders_dir:
+        base_model_path = os.path.join(text_encoders_dir, preset["kwargs"]["base_model_name_or_path"])
+        peft_model_path = os.path.join(text_encoders_dir, preset["kwargs"]["peft_model_name_or_path"])
+        missing = [path for path in (base_model_path, peft_model_path) if not os.path.exists(path)]
+        if missing:
+            raise RuntimeError(
+                "TEXT_ENCODERS_DIR is set, but the following local model paths are missing: "
+                + ", ".join(missing)
+            )
+        return
+
+    if not token:
+        raise RuntimeError(
+            "HF token is missing. Set one of HF_TOKEN, HUGGING_FACE_HUB_TOKEN, HF_HUB_TOKEN, or "
+            "HUGGINGFACEHUB_API_TOKEN before starting the text encoder server."
+        )
+
+    api = HfApi()
+    for repo_id, label in (
+        (preset["kwargs"]["base_model_name_or_path"], "base model"),
+        (preset["kwargs"]["peft_model_name_or_path"], "PEFT adapter"),
+    ):
+        try:
+            api.model_info(repo_id=repo_id, token=token)
+        except Exception as error:
+            raise RuntimeError(f"Failed to access {label} '{repo_id}' with the configured HF token: {error}") from error
+
+
 class DemoWrapper:
     def __init__(self, text_encoder_name, tmp_folder):
         self.text_encoder_name = text_encoder_name
@@ -52,8 +96,6 @@ class DemoWrapper:
             return self.text_encoder
         except Exception as error:
             self.init_error = error
-            import traceback
-            traceback.print_exc()
             raise
 
     def __call__(self, text, filename, progress=gr.Progress()):
@@ -122,12 +164,15 @@ def main():
     theme, css = get_gradio_theme()
     os.makedirs(args.tmp_folder, exist_ok=True)
     display_name = TEXT_ENCODER_PRESETS[args.text_encoder]["display_name"]
+
+    if _get_env("TEXT_ENCODER_VALIDATE_STARTUP", "1") != "0":
+        _validate_text_encoder_startup(args.text_encoder)
     
     # Suppress model loading during DemoWrapper initialization to allow graceful degradation
     # Model will be loaded lazily on first request
     demo_wrapper_fn = DemoWrapper(args.text_encoder, args.tmp_folder)
 
-    with gr.Blocks(title="Text encoder") as demo:
+    with gr.Blocks(title="Text encoder", css=css, theme=theme) as demo:
         gr.Markdown(f"# Text encoder: {display_name}")
         gr.Markdown("## Description")
         gr.Markdown("Get a embeddings from a text.")
@@ -192,7 +237,7 @@ def main():
         )
         clear.click(fn=clear_fn, inputs=None, outputs=outputs)
 
-    demo.launch(server_name=server_name, server_port=server_port, theme=theme, css=css)
+    demo.launch(server_name=server_name, server_port=server_port)
 
 
 if __name__ == "__main__":

kimodo/scripts/text_encoder_health.py

@@ -0,0 +1,131 @@
+"""Text encoder preflight health check for gated Hugging Face access and local cache paths."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+from huggingface_hub import HfApi, hf_hub_download
+from transformers import AutoConfig
+
+
+TEXT_ENCODER_PRESETS = {
+    "llm2vec": {
+        "base_model_name_or_path": "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp",
+        "peft_model_name_or_path": "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised",
+    }
+}
+
+
+def _get_hf_token() -> str | None:
+    return (
+        os.environ.get("HF_TOKEN")
+        or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        or os.environ.get("HF_HUB_TOKEN")
+        or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+    )
+
+
+def _check_repo_access(repo_id: str, token: str) -> tuple[bool, str]:
+    api = HfApi()
+    try:
+        api.model_info(repo_id=repo_id, token=token)
+        return True, "ok"
+    except Exception as error:  # pragma: no cover - depends on runtime/network/auth
+        return False, f"{type(error).__name__}: {error}"
+
+
+def _check_gated_base_access(repo_id: str, token: str) -> tuple[bool, str, str | None]:
+    """Resolve adapter base model and verify config download entitlement."""
+    try:
+        adapter_cfg_path = hf_hub_download(repo_id, "adapter_config.json", token=token)
+        with open(adapter_cfg_path, "r", encoding="utf-8") as f:
+            adapter_cfg = json.load(f)
+        base_model = adapter_cfg.get("base_model_name_or_path")
+        if not isinstance(base_model, str) or not base_model:
+            return False, "adapter_config missing base_model_name_or_path", None
+        AutoConfig.from_pretrained(base_model, token=token)
+        return True, "ok", base_model
+    except Exception as error:  # pragma: no cover - depends on runtime/network/auth
+        return False, f"{type(error).__name__}: {error}", None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Kimodo text encoder health check")
+    parser.add_argument(
+        "--text-encoder",
+        default="llm2vec",
+        choices=sorted(TEXT_ENCODER_PRESETS.keys()),
+        help="Text encoder preset to validate.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Return non-zero if any check fails.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    preset = TEXT_ENCODER_PRESETS[args.text_encoder]
+    base_repo = preset["base_model_name_or_path"]
+    peft_repo = preset["peft_model_name_or_path"]
+
+    token = _get_hf_token()
+    text_encoders_dir = os.environ.get("TEXT_ENCODERS_DIR")
+
+    report = {
+        "text_encoder": args.text_encoder,
+        "token_present": bool(token),
+        "token_length": len(token) if token else 0,
+        "text_encoders_dir": text_encoders_dir,
+        "checks": {},
+    }
+
+    failed = False
+
+    if text_encoders_dir:
+        base_path = os.path.join(text_encoders_dir, base_repo)
+        peft_path = os.path.join(text_encoders_dir, peft_repo)
+        base_ok = os.path.exists(base_path)
+        peft_ok = os.path.exists(peft_path)
+        report["checks"]["base_local_path"] = {"ok": base_ok, "path": base_path}
+        report["checks"]["peft_local_path"] = {"ok": peft_ok, "path": peft_path}
+        if not base_ok or not peft_ok:
+            failed = True
+    else:
+        if not token:
+            report["checks"]["token"] = {
+                "ok": False,
+                "error": "No HF token found in HF_TOKEN/HUGGING_FACE_HUB_TOKEN/HF_HUB_TOKEN/HUGGINGFACEHUB_API_TOKEN",
+            }
+            failed = True
+        else:
+            base_ok, base_error = _check_repo_access(base_repo, token)
+            peft_ok, peft_error = _check_repo_access(peft_repo, token)
+            report["checks"]["base_repo_access"] = {"ok": base_ok, "repo": base_repo, "detail": base_error}
+            report["checks"]["peft_repo_access"] = {"ok": peft_ok, "repo": peft_repo, "detail": peft_error}
+
+            gated_ok, gated_detail, gated_base = _check_gated_base_access(base_repo, token)
+            report["checks"]["gated_base_config_access"] = {
+                "ok": gated_ok,
+                "adapter_repo": base_repo,
+                "base_model": gated_base,
+                "detail": gated_detail,
+            }
+
+            if not base_ok or not peft_ok:
+                failed = True
+            if not gated_ok:
+                failed = True
+
+    print(json.dumps(report, indent=2, sort_keys=True))
+    if args.strict and failed:
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kimodo/scripts/text_encoder_smoke.py

@@ -0,0 +1,90 @@
+"""End-to-end text encoder smoke test for API/local/auto modes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+
+from kimodo.model.load_model import DEFAULT_TEXT_ENCODER_URL, _select_text_encoder_conf
+from kimodo.model.loading import get_env_var, instantiate_from_dict
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Kimodo text encoder smoke test")
+    parser.add_argument(
+        "--prompt",
+        default="A person walks forward.",
+        help="Prompt used for the end-to-end encoding call.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Return non-zero if any step fails.",
+    )
+    parser.add_argument(
+        "--retry-delay-sec",
+        type=float,
+        default=10.0,
+        help="Delay before a single retry when the first cold-start attempt fails.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    text_encoder_url = get_env_var("TEXT_ENCODER_URL", DEFAULT_TEXT_ENCODER_URL)
+    mode = get_env_var("TEXT_ENCODER_MODE", "auto").lower()
+
+    report = {
+        "mode": mode,
+        "text_encoder_url": text_encoder_url,
+        "encoder_target": None,
+        "ready": False,
+        "encode_ok": False,
+        "elapsed_ms": None,
+        "output_shape": None,
+        "lengths": None,
+        "error": None,
+    }
+
+    started = time.time()
+    conf = None
+    encoder = None
+    for attempt in range(2):
+        try:
+            if conf is None:
+                conf = _select_text_encoder_conf(text_encoder_url)
+                report["encoder_target"] = conf.get("_target_")
+            if encoder is None:
+                encoder = instantiate_from_dict(conf)
+
+            # Probe readiness path first.
+            encoder(["healthcheck"])
+            report["ready"] = True
+
+            encoded, lengths = encoder([args.prompt])
+            report["encode_ok"] = True
+            report["output_shape"] = tuple(encoded.shape)
+            report["lengths"] = lengths
+            report["attempts"] = attempt + 1
+            break
+        except Exception as error:  # pragma: no cover - runtime/network dependent
+            report["error"] = f"{type(error).__name__}: {error}"
+            report["attempts"] = attempt + 1
+            if attempt == 0:
+                time.sleep(max(0.0, args.retry_delay_sec))
+                encoder = None
+                continue
+
+    report["elapsed_ms"] = int((time.time() - started) * 1000)
+
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+    if args.strict and (not report["ready"] or not report["encode_ok"]):
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kimodo"
+version = "1.0.0"
+description = "Kimodo motion generation model"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "Apache-2.0"}
+dependencies = [
+  "hydra-core>=1.3",
+  "omegaconf>=2.3",
+  "numpy>=1.23",
+  "scipy>=1.10",
+  "transformers==5.1.0",
+  "urllib3>=2.6.3",
+  "boto3",
+  "peft>=0.18",
+  "einops>=0.7",
+  "tqdm>=4.0",
+  "packaging>=21.0",
+  "pydantic>=2.0",
+  "filelock>=3.20.3",
+  "gradio>=6.8.0",
+  "gradio_client>=1.0",
+  "trimesh>=3.21.7",
+  "scenepic>=1.1.0",
+  "pillow>=9.0",
+  "av>=16.1.0",
+  "bvhio",
+]
+
+[project.optional-dependencies]
+demo = [
+  "viser @ git+https://github.com/nv-tlabs/kimodo-viser.git",
+]
+soma = [
+  "py-soma-x @ git+https://github.com/NVlabs/SOMA-X.git"
+]
+all = [
+  "viser @ git+https://github.com/nv-tlabs/kimodo-viser.git",
+  "py-soma-x @ git+https://github.com/NVlabs/SOMA-X.git"
+]
+
+[project.scripts]
+kimodo_gen = "kimodo.scripts.generate:main"
+kimodo_demo = "kimodo.demo:main"
+kimodo_textencoder = "kimodo.scripts.run_text_encoder_server:main"
+kimodo_convert = "kimodo.scripts.motion_convert:main"
+kimodo_bones_seed = "kimodo.scripts.bones_seed:main"
+kimodo_planner = "kimodo.scripts.qwen_planner:main"
+kimodo_planner_contract_check = "kimodo.scripts.planner_contract_check:main"
+kimodo_planner_baseline_eval = "kimodo.scripts.planner_baseline_eval:main"
+kimodo_runtime_health = "kimodo.scripts.runtime_health:main"
+kimodo_textencoder_health = "kimodo.scripts.text_encoder_health:main"
+kimodo_textencoder_smoke = "kimodo.scripts.text_encoder_smoke:main"
+kimodo_space = "kimodo.scripts.space_frontend:main"
+
+[tool.setuptools]
+include-package-data = true
+zip-safe = false
+
+[tool.setuptools.package-data]
+kimodo = ["assets/**/*"]
+
+[tool.flake8]
+max-line-length = 120
+
+[tool.ruff]
+extend-select = ["I001"]  # Enable import sorting
+line-length = 120
+
+[tool.ruff.lint.isort]
+known-first-party = ["kimodo"]
+known-third-party = ["torch", "numpy", "pytorch_lightning", "wandb", "tqdm"]
+force-sort-within-sections = false