termux-tts 0.1.1

package/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "termux-tts"
+version = "1.1.3"
+description = "On-device Text-to-Speech framework utilizing device resources (DSP Formant Vocoder, ONNX Neural Runtime & Android Native Voice Bridge)"
+readme = "README.pypi.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "AOSF / uno-km", email = "zhfldk014745@naver.com" }
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "numpy>=1.20.0",
+]
+
+[project.optional-dependencies]
+onnx = ["onnxruntime>=1.15.0"]
+neural = ["onnxruntime>=1.15.0"]
+dev = ["pytest>=7.0", "paramiko>=3.0"]
+
+[project.scripts]
+termux-tts = "termux_tts.cli:main"
+
+[project.entry-points."ameva.components"]
+termux-tts = "termux_tts.adapter:create_adapter"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["termux_tts*"]

package/setup.py

@@ -0,0 +1,38 @@
+import os
+from setuptools import setup, find_packages
+
+setup(
+    name="termux-tts",
+    version="1.1.3",
+    description="Ultra-Fast On-Device Dual-Engine Text-to-Speech Framework (Parametric Formant Acoustic Synthesizer & Android Native Voice Bridge)",
+    long_description=open("README.pypi.md", encoding="utf-8").read() if os.path.exists("README.pypi.md") else open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="AMEVA Foundation",
+    license="Apache-2.0",
+    url="https://github.com/uno-km/termux-tts",
+    packages=find_packages(include=["termux_tts", "termux_tts.*"]),
+    python_requires=">=3.8",
+    install_requires=[
+        "numpy>=1.20.0",
+        "ameva-vulkan-runtime>=1.0.0",
+    ],
+    extras_require={
+        "onnx": ["onnxruntime>=1.15.0"],
+        "neural": ["onnxruntime>=1.15.0"],
+        "dev": ["pytest>=7.0.0", "pytest-asyncio"],
+    },
+    entry_points={
+        "console_scripts": [
+            "termux-tts=termux_tts.cli:main",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: Android",
+        "Operating System :: POSIX :: Linux",
+        "Programming Language :: Python :: 3",
+        "Topic :: Multimedia :: Sound/Audio :: Speech",
+    ],
+)

package/termux_tts/__init__.py

@@ -0,0 +1,47 @@
+"""
+termux-tts: Production-Grade Dual-Engine TTS Framework for Android Termux.
+- Option A: Deep Learning VITS ONNX Neural Vocoder (Vulkan GPU Accelerated)
+- Option B: Android System Native Voice Engine Bridge (Samsung / Google Voice)
+"""
+
+from .engine import TTSEngine, load, doctor
+from .engine_native import NativeAndroidEngine, NativeResult
+from .engine_dsp import ParametricDSPEngine, DSPResult, QUALITY_PRESETS, DSPSynthesizer
+from .engine_onnx import ONNXNeuralEngine, ONNXResult
+from .tokenizer import PhoneticTokenizer, EXPRESSIVE_TAGS
+from .g2p_korean import KoreanG2PEngine, korean_text_to_phonemes
+from .audio import AudioBuffer
+from .exceptions import (
+    TTSError,
+    TTSModelLoadError,
+    TTSInferenceError,
+    VulkanInitializationError,
+    TTSAudioEncodingError,
+    TTSLanguageNotSupportedError
+)
+
+__version__ = "1.1.2"
+__all__ = [
+    "TTSEngine",
+    "load",
+    "doctor",
+    "ParametricDSPEngine",
+    "DSPSynthesizer",
+    "DSPResult",
+    "NativeAndroidEngine",
+    "NativeResult",
+    "ONNXNeuralEngine",
+    "ONNXResult",
+    "QUALITY_PRESETS",
+    "PhoneticTokenizer",
+    "KoreanG2PEngine",
+    "korean_text_to_phonemes",
+    "EXPRESSIVE_TAGS",
+    "AudioBuffer",
+    "TTSError",
+    "TTSModelLoadError",
+    "TTSInferenceError",
+    "VulkanInitializationError",
+    "TTSAudioEncodingError",
+    "TTSLanguageNotSupportedError"
+]

package/termux_tts/adapter.py

@@ -0,0 +1,99 @@
+"""
+termux_tts.adapter
+===================
+AMEVA Component Protocol v1 — Orchestrator Adapter (v0.8.1 호환)
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from ameva_component.adapter_base import BaseOrchestratorAdapter
+from termux_tts.control.component import TTSControl
+
+
+class TTSOrchestratorAdapter(BaseOrchestratorAdapter):
+    """TTS (Text-to-Speech) Orchestrator Adapter.
+
+    합성은 파일 기반으로 수행됩니다.
+    infer()는 text를 받아 audio 파일 경로를 반환합니다.
+    요청 모델과 실행 모델이 다르면 fallback_used=True를 명시합니다.
+    """
+
+    COMPONENT_ID = "termux-tts"
+
+    def __init__(self, control: TTSControl | None = None) -> None:
+        self._control = control or TTSControl()
+
+    async def infer(self, request: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        """TTS synthesis: text → audio file path.
+
+        request 키:
+            text (str): 합성할 텍스트 (필수)
+            voice_id (str): 목소리 ID (선택)
+            model_id (str): 모델 ID (선택)
+            output_path (str): 출력 파일 경로 (선택, 없으면 임시 파일)
+
+        반환 프레임:
+            {"type": "audio", "audio_path": str, "final": bool, "fallback_used": bool}
+            {"type": "error", "code": str, "message": str}
+        """
+        text = request.get("text", "").strip()
+        if not text:
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    "code": "TEXT_EMPTY",
+                    "message": "text is required and must not be empty",
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": False,
+                },
+            }
+            return
+
+        if hasattr(self._control, "synthesize"):
+            try:
+                result = await self._control.synthesize(request)
+                audio_path = result.get("audio_path", "")
+                if not audio_path:
+                    yield {
+                        "type": "error",
+                        "ok": False,
+                        "error": {
+                            "code": "SYNTHESIS_FAILED",
+                            "message": "synthesize() returned no audio_path",
+                            "operation": "infer",
+                            "component_id": self.COMPONENT_ID,
+                            "retryable": True,
+                        },
+                    }
+                    return
+                yield {
+                    "type": "audio",
+                    "audio_path": audio_path,
+                    "final": True,
+                    "fallback_used": result.get("fallback_used", False),
+                    "requested_voice": result.get("requested_voice"),
+                    "executed_voice": result.get("executed_voice"),
+                    "ok": True,
+                }
+            except Exception as exc:
+                yield {
+                    "type": "error",
+                    "ok": False,
+                    "error": {
+                        "code": "SYNTHESIS_FAILED",
+                        "message": str(exc),
+                        "operation": "infer",
+                        "component_id": self.COMPONENT_ID,
+                        "retryable": True,
+                    },
+                }
+        else:
+            yield self._not_supported("infer.synthesize")
+
+
+def create_adapter() -> TTSOrchestratorAdapter:
+    """Entry Point Factory."""
+    return TTSOrchestratorAdapter()

package/termux_tts/audio.py

@@ -0,0 +1,75 @@
+"""
+Zero-Dependency Audio Buffer and RIFF WAV Stream Encoder.
+Handles 16-bit Linear PCM formatting with soft-clipping protection.
+"""
+
+import io
+import wave
+import numpy as np
+from typing import Union
+from .exceptions import TTSAudioEncodingError
+
+class AudioBuffer:
+    """Manages raw floating-point audio samples and converts to 16-bit PCM WAV."""
+
+    def __init__(self, samples: Union[np.ndarray, list], sample_rate: int = 22050):
+        if isinstance(samples, list):
+            self.samples = np.array(samples, dtype=np.float32)
+        elif isinstance(samples, np.ndarray):
+            self.samples = samples.astype(np.float32).flatten()
+        else:
+            raise TTSAudioEncodingError("Samples must be a list or numpy ndarray.")
+
+        self.sample_rate = sample_rate
+        self._normalize_and_clip()
+
+    def _normalize_and_clip(self) -> None:
+        """Apply peak normalization and soft clipping to prevent distortion."""
+        if len(self.samples) == 0:
+            return
+
+        peak = np.max(np.abs(self.samples))
+        if peak > 1.0:
+            self.samples = self.samples / peak
+        elif peak < 0.0001:
+            pass # Keep quiet signals as is
+        else:
+            # Gentle scale to target -1dB
+            self.samples = self.samples * 0.95
+
+    @property
+    def duration_seconds(self) -> float:
+        """Duration of the audio in seconds."""
+        if self.sample_rate <= 0:
+            return 0.0
+        return len(self.samples) / float(self.sample_rate)
+
+    def to_pcm16_bytes(self) -> bytes:
+        """Convert float32 [-1.0, 1.0] samples into 16-bit signed integer bytes."""
+        clipped = np.clip(self.samples, -1.0, 1.0)
+        pcm16 = (clipped * 32767.0).astype(np.int16)
+        return pcm16.tobytes()
+
+    def to_wav_bytes(self) -> bytes:
+        """Encode raw samples into standard RIFF WAV format."""
+        try:
+            pcm_bytes = self.to_pcm16_bytes()
+            buf = io.BytesIO()
+            with wave.open(buf, "wb") as wav_file:
+                wav_file.setnchannels(1)      # Mono
+                wav_file.setsampwidth(2)      # 16-bit (2 bytes)
+                wav_file.setframerate(self.sample_rate)
+                wav_file.writeframes(pcm_bytes)
+            return buf.getvalue()
+        except Exception as e:
+            raise TTSAudioEncodingError(f"Failed to encode WAV buffer: {e}") from e
+
+    def save(self, filepath: str) -> str:
+        """Save the audio buffer to a WAV file on disk."""
+        wav_data = self.to_wav_bytes()
+        try:
+            with open(filepath, "wb") as f:
+                f.write(wav_data)
+            return filepath
+        except Exception as e:
+            raise TTSAudioEncodingError(f"Failed to save WAV to '{filepath}': {e}") from e

package/termux_tts/cli.py

@@ -0,0 +1,82 @@
+"""
+Command-Line Interface for termux-tts:
+- termux-tts synth : Option A Deep Learning Neural Synthesis to File
+- termux-tts speak : Option B Android System Native Immediate Voice Output
+- termux-tts doctor: 12-Stage Vulkan GPU Hardware Diagnostics
+"""
+
+import argparse
+from .engine import load, doctor
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="termux-tts",
+        description="Termux Neural & Native Text-to-Speech Engine"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Sub-commands")
+
+    # 1. Synth (Option A: DSP Formant or ONNX Neural Vocoder to File)
+    synth_parser = subparsers.add_parser("synth", help="Synthesize text to audio WAV file (DSP / ONNX)")
+    synth_parser.add_argument("-t", "--text", required=True, help="Input text to synthesize")
+    synth_parser.add_argument("-o", "--output", default="output.wav", help="Output WAV filepath")
+    synth_parser.add_argument("-l", "--lang", default="ko", help="Language code (ko, en)")
+    synth_parser.add_argument("-e", "--engine", default="auto", choices=["auto", "dsp", "onnx"], help="Synthesis engine (dsp=zero-dependency, onnx=deep learning)")
+    synth_parser.add_argument("-m", "--model", default=None, help="Path to .onnx model file (required for onnx engine)")
+    synth_parser.add_argument("-p", "--preset", default="balanced", choices=["fast", "balanced", "expressive", "ultra"])
+    synth_parser.add_argument("-d", "--device", default="auto", choices=["auto", "gpu", "vulkan", "cpu"])
+    synth_parser.add_argument("-s", "--speed", type=float, default=1.0, help="Speech speed multiplier (0.5 to 2.0)")
+
+    # 2. Speak (Option B: Native Samsung/Google System Voice)
+    speak_parser = subparsers.add_parser("speak", help="Speak text directly through device speaker (Option B: Native)")
+    speak_parser.add_argument("-t", "--text", required=True, help="Input text to speak")
+    speak_parser.add_argument("-l", "--lang", default="ko", help="Language code (ko, en)")
+    speak_parser.add_argument("-s", "--stream", default="MUSIC", help="Audio stream (MUSIC, NOTIFICATION, ALARM)")
+
+    # 3. Doctor (Diagnostics)
+    subparsers.add_parser("doctor", help="Run 12-stage Vulkan GPU hardware diagnostics")
+
+    # ── AMEVA Component Protocol v1 ─────────────────────────────────────────
+    _protocol_available = False
+    try:
+        from ameva_component.cli_support import build_protocol_subcommands
+        build_protocol_subcommands(subparsers)
+        _protocol_available = True
+    except ImportError:
+        pass
+    # ────────────────────────────────────────────────────────────────────────
+
+    args = parser.parse_args()
+
+    if args.command == "synth":
+        with load(model=args.model, language=args.lang, preset=args.preset, device=args.device, engine=args.engine) as engine:
+            res = engine.synthesize(args.text, output=args.output, speed=args.speed)
+            print(f"[SUCCESS] Synthesized via {res.backend} ({res.model_name}) -> {args.output}")
+            print(f"  Duration: {res.duration_sec:.2f}s | Elapsed: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x")
+
+    elif args.command == "speak":
+        with load(language=args.lang) as engine:
+            res = engine.speak(args.text, stream=args.stream)
+            print(f"[SUCCESS] Spoken via {res.engine_name} on stream {args.stream} ({res.elapsed_ms:.1f}ms)")
+
+    elif args.command == "doctor":
+        diag = doctor()
+        print("=" * 60)
+        print("   TERMUX-TTS 12-STAGE VULKAN HARDWARE DIAGNOSTICS")
+        print("=" * 60)
+        for k, v in diag.items():
+            print(f"  - {k:30s}: {v}")
+        print("=" * 60)
+
+    elif args.command in ("component", "model", "instance") and _protocol_available:
+        from ameva_component.cli_support import dispatch_protocol
+        from termux_tts.control import TTSControl
+        dispatch_protocol(args, TTSControl())
+    elif args.command in ("component", "model", "instance"):
+        print("[ERROR] ameva-component-sdk not installed.", file=sys.stderr)
+        sys.exit(1)
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()
+

package/termux_tts/control/__init__.py

@@ -0,0 +1,4 @@
+"""termux_tts.control — AMEVA Component Protocol v1."""
+from .component import TTSControl
+from .status import TTSStatusWriter
+__all__ = ["TTSControl", "TTSStatusWriter"]

package/termux_tts/control/component.py

@@ -0,0 +1,242 @@
+"""
+termux_tts.control.component
+AMEVA Component Protocol v1 — TTSControl
+
+기존 TTSEngine.doctor() Adapter 연결.
+Model/Voice 분리 추적 (신규 — 기존 코드에 없음).
+doctor_lite: 상태파일 + PID만 (12단계 Vulkan Doctor는 doctor_full에만).
+"""
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from ameva_component import (
+    ActivationLock, ComponentInfo, ComponentStateFile,
+    ControlMode, InstanceRegistry, InstanceState, InstanceStatus,
+    ModelRegistry, ModelState, ModelNotFound, ModelLoadFailed,
+    OperationNotSupported, now_timestamps, log_stderr, PROTOCOL_COMPONENT,
+)
+from ameva_component.control import ComponentControl
+
+
+class TTSControl(ComponentControl):
+    """
+    termux-tts ComponentControl.
+    Model/Voice 분리: model_id=piper-ko / voice_id=ko-speaker-01
+    기존 engine.py TTSEngine은 Adapter로 연결합니다.
+    """
+
+    COMPONENT_ID   = "termux-tts"
+    COMPONENT_TYPE = "tts"
+    CAPABILITIES   = ("audio.synthesize", "voice.list")
+
+    DEFAULT_MODELS_DIR = Path.home() / ".cache" / "termux-tts" / "models"
+    DEFAULT_PID_FILE   = Path.home() / ".local" / "run" / "termux-tts.pid"
+
+    def __init__(self, models_dir: Path | None = None) -> None:
+        self._models_dir = models_dir or self.DEFAULT_MODELS_DIR
+        self._state_file = ComponentStateFile(self.COMPONENT_ID)
+        self._model_reg  = ModelRegistry(self.COMPONENT_ID)
+        self._inst_reg   = InstanceRegistry(self.COMPONENT_ID)
+        self._act_lock   = ActivationLock()
+        # Phase 4: Heartbeat Writer
+        from termux_tts.control.status import TTSStatusWriter
+        self._heartbeat = TTSStatusWriter(self)
+
+    def _get_version(self) -> str:
+        try:
+            from termux_tts import __version__; return __version__
+        except Exception: return "1.1.2"
+
+    def component_info(self) -> dict:
+        info = ComponentInfo(
+            protocol=PROTOCOL_COMPONENT, component_id=self.COMPONENT_ID,
+            component_type=self.COMPONENT_TYPE, version=self._get_version(),
+            capabilities=self.CAPABILITIES,
+        )
+        info.validate()
+        return info.to_dict()
+
+    def doctor_lite(self) -> dict:
+        """
+        경량 진단.
+        12단계 Vulkan Doctor 금지 — doctor_full()에서만 호출.
+        """
+        ts = now_timestamps()
+        state_data = self._state_file.read()
+        stale = self._state_file.is_stale(threshold_ms=30_000)
+        pid, pid_alive = self._check_pid()
+        instances = self._inst_reg.list_all()
+        hot = [i for i in instances if i.state == InstanceState.HOT]
+
+        # DSP 백엔드는 항상 가용 (Zero Dependency)
+        dsp_available = True
+        onnx_available = False
+        try:
+            from termux_tts.engine_onnx import ONNXNeuralEngine
+            onnx_available = True
+        except ImportError:
+            pass
+
+        ready = dsp_available  # DSP는 Zero Dependency이므로 항상 최소 가용
+        degraded = stale or not pid_alive
+
+        return {
+            "protocol":       "ameva-component-status/1",
+            "component_id":   self.COMPONENT_ID,
+            "component_type": self.COMPONENT_TYPE,
+            "version":        self._get_version(),
+            "ready":          ready,
+            "degraded":       degraded,
+            **ts,
+            "process":        {"running": pid_alive, "pid": pid},
+            "capabilities":   list(self.CAPABILITIES),
+            "active_models":  [i.model_id for i in hot],
+            "backends": {
+                "dsp":    dsp_available,
+                "onnx":   onnx_available,
+                "native": None,  # Android 런타임에서만 확인 가능
+            },
+            "errors":   [state_data.get("last_error")] if state_data and state_data.get("last_error") else [],
+            "state_file": {
+                "path":       str(self._state_file.path),
+                "stale":      stale,
+                "updated_at": state_data.get("updated_at") if state_data else None,
+            },
+        }
+
+    def _check_pid(self) -> tuple[int | None, bool]:
+        if self.DEFAULT_PID_FILE.exists():
+            try:
+                pid = int(self.DEFAULT_PID_FILE.read_text().strip())
+                os.kill(pid, 0)
+                return pid, True
+            except Exception:
+                pass
+        return None, False
+
+    def doctor_full(self) -> dict:
+        """기존 TTSEngine doctor() 호출 — 12단계 Vulkan Doctor 포함."""
+        lite = self.doctor_lite()
+        try:
+            from termux_tts.vulkan_probe import VulkanDoctor
+            vd = VulkanDoctor()
+            lite["vulkan"] = vd.probe() if hasattr(vd, "probe") else {"note": "probe() not available"}
+        except Exception as e:
+            lite["vulkan_error"] = str(e)
+        lite["doctor_level"] = "full"
+        return lite
+
+    def list_models(self) -> dict:
+        """ModelRegistry 기반 + 설치된 파일 스캔."""
+        reg_models = self._model_reg.list_all()
+        reg_map = {m["model_id"]: m for m in reg_models}
+
+        # models_dir 스캔 (파일만 존재 = unverified)
+        if self._models_dir.exists():
+            for p in self._models_dir.glob("*"):
+                if p.is_file():
+                    mid = p.stem
+                    if mid not in reg_map:
+                        reg_map[mid] = {
+                            "model_id":    mid,
+                            "state":       "unverified",
+                            "format":      p.suffix.lstrip("."),
+                            "note":        "File found on disk but not verified by AMEVA registry",
+                            "verified_at": None,
+                        }
+
+        return {"models": list(reg_map.values()), "total": len(reg_map),
+                "models_dir": str(self._models_dir)}
+
+    def model_status(self, model_id: str | None = None) -> dict:
+        if model_id:
+            rec = self._model_reg.get(model_id)
+            if rec is None: raise ModelNotFound(model_id)
+            return {"model": rec}
+        return self.list_models()
+
+    def install_model(self, request: dict) -> dict:
+        from ameva_component import ModelInstaller
+        url = request.get("url", ""); filename = request.get("filename", "")
+        sha256 = request.get("sha256", "")
+        expected_bytes = int(request.get("expected_bytes", 0))
+        model_id = request.get("model_id") or Path(filename).stem
+        self._models_dir.mkdir(parents=True, exist_ok=True)
+        installer = ModelInstaller(self.COMPONENT_ID, self._models_dir, self._model_reg)
+        return installer.install(url=url, filename=filename, sha256=sha256,
+                                 expected_bytes=expected_bytes, model_id=model_id)
+
+    async def activate_model(self, request: dict) -> dict:
+        model_id = request.get("model_id", "")
+        voice_id = request.get("voice_id")  # Model/Voice 분리
+        rec = self._model_reg.get(model_id)
+        if rec is None: raise ModelNotFound(model_id)
+        if ModelState.from_str(rec.get("state", "missing")) not in (ModelState.INSTALLED, ModelState.INACTIVE):
+            raise ModelLoadFailed(model_id, f"State is '{rec.get('state')}'")
+        with self._act_lock.acquire(timeout=60.0):
+            self._model_reg.set_state(model_id, ModelState.ACTIVE)
+            self._write_state()
+        return {"activated": True, "model_id": model_id, "voice_id": voice_id,
+                "rollback": {"attempted": False, "succeeded": False}}
+
+    async def deactivate_model(self, request: dict) -> dict:
+        model_id = request.get("model_id", "")
+        self._model_reg.set_state(model_id, ModelState.INACTIVE)
+        self._write_state()
+        return {"deactivated": True, "model_id": model_id}
+
+    def list_instances(self) -> dict:
+        instances = self._inst_reg.list_all()
+        return {"instances": [i.to_dict() for i in instances], "total": len(instances)}
+
+    async def start_instance(self, request: dict) -> dict:
+        backend = request.get("backend", "dsp")
+        model_id = request.get("model_id", "dsp-default")
+        instance_id = request.get("instance_id") or f"tts-{backend}-{int(time.time())}"
+        inst = InstanceStatus(
+            instance_id=instance_id, component_id=self.COMPONENT_ID,
+            model_id=model_id, state=InstanceState.HOT,
+            active_jobs=0, queue_depth=0, max_concurrency=4,
+            backend=backend, started_at=time.time(), last_heartbeat=time.time(),
+            last_error=None, control_mode=ControlMode.IN_PROCESS,
+        )
+        self._inst_reg.register(inst)
+        self._write_state()
+        # Phase 4: Heartbeat 시작 (Worker 시작 트리거)
+        self._heartbeat.start()
+        return {"instance_id": instance_id, "state": InstanceState.HOT.value, "backend": backend}
+
+    async def drain_instance(self, instance_id: str) -> dict:
+        from ameva_component import InstanceNotFound
+        if not self._inst_reg.get(instance_id): raise InstanceNotFound(instance_id)
+        self._inst_reg.update_state(instance_id, InstanceState.DRAINING)
+        return {"instance_id": instance_id, "state": InstanceState.DRAINING.value}
+
+    async def stop_instance(self, instance_id: str) -> dict:
+        from ameva_component import InstanceNotFound
+        if not self._inst_reg.get(instance_id): raise InstanceNotFound(instance_id)
+        self._inst_reg.update_state(instance_id, InstanceState.STOPPED)
+        self._inst_reg.remove(instance_id)
+        # Phase 4: Heartbeat 중단 (정상 종료 트리거)
+        remaining = self._inst_reg.list_all()
+        if not remaining:
+            self._heartbeat.stop()
+        else:
+            self._write_state()
+        return {"instance_id": instance_id, "state": InstanceState.STOPPED.value}
+
+    def _write_state(self, *, ready: bool | None = None, last_error: str | None = None) -> None:
+        ts = now_timestamps()
+        hot = [i for i in self._inst_reg.list_all() if i.state == InstanceState.HOT]
+        _, pid_alive = self._check_pid()
+        _ready = True if ready is None else ready  # DSP는 항상 최소 가용
+        self._state_file.write({
+            "protocol": "ameva-component-status/1", "component_id": self.COMPONENT_ID,
+            "component_type": self.COMPONENT_TYPE, "version": self._get_version(),
+            "ready": _ready, "degraded": not _ready, **ts,
+            "active_models": [i.model_id for i in hot], "last_error": last_error,
+        })