openspeechapi 0.1.0__py3-none-any.whl

openspeech/server/routes/management.py

@@ -0,0 +1,848 @@
+"""Management endpoints."""
+from __future__ import annotations
+import asyncio
+import json
+import queue
+import subprocess
+import sys
+from pathlib import Path
+from pydantic import BaseModel, Field
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+
+import yaml
+
+from openspeech.engine_catalog import get_catalog, get_catalog_entry, get_installed_engines
+
+router = APIRouter()
+
+
+@router.get("/engines")
+async def list_engines(request: Request):
+    dispatcher = request.app.state.dispatcher
+    engines = dispatcher.list_engines_info()
+    # Augment with async health check (not available in sync list_engines_info)
+    health = await dispatcher.health()
+    for eng in engines:
+        eng["healthy"] = health.get(eng["name"], False)
+    return {"engines": engines}
+
+
+# Backward compatibility: old endpoint
+@router.get("/providers")
+async def list_providers(request: Request):
+    """Deprecated: use /engines instead."""
+    result = await list_engines(request)
+    return {"providers": result["engines"]}
+
+
+@router.get("/health")
+async def health_check(request: Request):
+    dispatcher = request.app.state.dispatcher
+    health = await dispatcher.health()
+    all_healthy = all(health.values()) if health else True
+    return {"status": "ok" if all_healthy else "degraded", "engines": health}
+
+
+@router.get("/metrics")
+async def metrics(request: Request):
+    dispatcher = request.app.state.dispatcher
+    from openspeech.observe.metrics import MetricsObserver
+
+    for obs in dispatcher._observer_mgr.list():
+        if isinstance(obs, MetricsObserver):
+            result = {}
+            for name in dispatcher.list_engines():
+                provider_metrics = {}
+                for method in ("transcribe", "synthesize"):
+                    m = obs.get(name, method)
+                    if m is not None:
+                        provider_metrics[method] = {
+                            "total_calls": m.total_calls,
+                            "error_count": m.error_count,
+                            "durations_ms": m.durations_ms,
+                            "ttfb_ms": m.ttfb_ms,
+                        }
+                result[name] = provider_metrics
+            return {"metrics": result}
+
+    return {"metrics": {}, "message": "No MetricsObserver registered"}
+
+
+@router.post("/admin/reload")
+async def reload_config(request: Request):
+    """Hot-reload: re-read providers.yaml and apply config changes without restart."""
+    dispatcher = request.app.state.dispatcher
+    config_path = request.app.state.config_path
+    registry = request.app.state.registry
+    result = await dispatcher.reload_config(config_path, registry)
+    return result
+
+
+@router.get("/admin/states")
+async def engine_states(request: Request):
+    """Return current lifecycle state for each registered engine."""
+    dispatcher = request.app.state.dispatcher
+    return {"states": dispatcher.provider_states()}
+
+
+def _mask_secret(value: str) -> str:
+    """Mask sensitive values, showing first 4 chars + ****."""
+    if not value or len(value) <= 4:
+        return "****" if value else ""
+    return value[:4] + "****"
+
+
+_SECRET_KEYS = {"api_key", "secret_key", "api_secret", "access_token", "subscription_key", "secret_id"}
+
+
+def _sanitize_settings(settings: dict) -> dict:
+    """Mask secret fields in provider settings for safe API responses."""
+    out = {}
+    for k, v in settings.items():
+        if k in _SECRET_KEYS and isinstance(v, str) and v:
+            out[k] = _mask_secret(v)
+        else:
+            out[k] = v
+    return out
+
+
+def _is_masked_secret_value(value: object) -> bool:
+    """Detect masked placeholder values like ``sk_xxxx****`` or ``****``."""
+    if not isinstance(value, str):
+        return False
+    if "****" not in value:
+        return False
+    # Treat any placeholder containing mask stars as masked, not real secret.
+    return True
+
+
+def _restore_masked_provider_secrets(new_providers: dict, old_providers: dict) -> dict:
+    """Replace masked incoming provider secrets with existing raw values."""
+    if not isinstance(new_providers, dict):
+        return new_providers
+    restored = {}
+    for pname, spec in new_providers.items():
+        if not isinstance(spec, dict):
+            restored[pname] = spec
+            continue
+        prev = old_providers.get(pname, {}) if isinstance(old_providers, dict) else {}
+        merged = dict(spec)
+        for k, v in list(merged.items()):
+            if k in _SECRET_KEYS and _is_masked_secret_value(v):
+                if isinstance(prev, dict) and prev.get(k):
+                    merged[k] = prev[k]
+        restored[pname] = merged
+    return restored
+
+
+@router.get("/admin/config")
+async def get_config(request: Request):
+    """Return current config as JSON with secrets masked."""
+    config_path: Path = request.app.state.config_path
+    if not config_path.exists():
+        raise HTTPException(status_code=404, detail="Config file not found")
+    with open(config_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f)
+
+    # Parse providers (shared credentials)
+    providers_out = {}
+    for name, spec in (raw.get("providers") or {}).items():
+        # In new format, providers are flat credential dicts
+        if isinstance(spec, dict) and "provider" not in spec and "exec_mode" not in spec:
+            providers_out[name] = _sanitize_settings(spec)
+
+    # Parse engines (or old-format providers)
+    engines_raw = raw.get("engines") or {}
+    if not engines_raw and "providers" in raw:
+        # Old format: providers contains engine configs
+        engines_raw = raw.get("providers") or {}
+        providers_out = {}  # No credential providers in old format
+
+    engines_out = {}
+    for name, spec in engines_raw.items():
+        if not isinstance(spec, dict):
+            continue
+        # Skip if this is a credential provider (no exec_mode/provider field)
+        if "exec_mode" not in spec and "provider" not in spec:
+            continue
+        entry = {
+            "provider": spec.get("provider", ""),
+            "exec_mode": spec.get("exec_mode", "remote"),
+            "settings": _sanitize_settings(spec.get("settings", {})),
+            "preload": spec.get("preload", False),
+        }
+        # Resolve type/category/display_name/provider_key from engine catalog
+        cat_entry = get_catalog_entry(name)
+        if cat_entry:
+            entry["type"] = cat_entry.type
+            entry["category"] = cat_entry.category
+            entry["display_name"] = cat_entry.display_name
+            entry["provider_key"] = cat_entry.provider
+        engines_out[name] = entry
+
+    return {"providers": providers_out, "engines": engines_out}
+
+
+@router.get("/admin/config/raw")
+async def get_config_raw(request: Request):
+    """Return raw config content with secrets unmasked (for save round-trip)."""
+    config_path: Path = request.app.state.config_path
+    if not config_path.exists():
+        raise HTTPException(status_code=404, detail="Config file not found")
+    with open(config_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f)
+    return raw
+
+
+class EngineConfigUpdate(BaseModel):
+    engines: dict
+    providers: dict = Field(default_factory=dict)
+
+
+# Backward compatibility alias
+ProviderConfigUpdate = EngineConfigUpdate
+
+
+@router.put("/admin/config")
+async def update_config(request: Request, body: EngineConfigUpdate):
+    """Write new config to providers.yaml and hot-reload."""
+    config_path: Path = request.app.state.config_path
+
+    # Read existing config to preserve non-engine sections (server, etc.)
+    existing = {}
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            existing = yaml.safe_load(f) or {}
+
+    # Update engines and providers sections
+    if body.providers:
+        existing["providers"] = _restore_masked_provider_secrets(
+            body.providers,
+            existing.get("providers", {}),
+        )
+    existing["engines"] = body.engines
+
+    # Remove old-format 'providers' if it contained engine configs (migration)
+    if "providers" in existing and "engines" in existing:
+        prov = existing.get("providers", {})
+        # Check if providers section has engine-style entries
+        has_engine_entries = any(
+            isinstance(v, dict) and ("exec_mode" in v or "provider" in v)
+            for v in prov.values()
+        )
+        if has_engine_entries and not body.providers:
+            # Old format detected, remove engine entries from providers
+            existing.pop("providers", None)
+
+    # Write YAML
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(existing, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+    # Hot-reload
+    dispatcher = request.app.state.dispatcher
+    registry = request.app.state.registry
+    result = await dispatcher.reload_config(config_path, registry)
+    return {"status": "ok", "reload": result}
+
+
+@router.get("/admin/provider-templates")
+async def provider_templates(request: Request):
+    """Return all registered provider names and their default settings schema."""
+    from openspeech.factory import _PROVIDER_MAP, _resolve
+
+    templates = []
+    for name in sorted(_PROVIDER_MAP):
+        try:
+            provider_cls, settings_cls = _resolve(name)
+            # Get default settings by instantiating with no args
+            defaults = {}
+            if settings_cls:
+                s = settings_cls()
+                for k, v in s.__dict__.items():
+                    if not k.startswith("_"):
+                        defaults[k] = v
+            ptype = getattr(provider_cls, "provider_type", None)
+            # Look up field_options from catalog
+            cat_entry = get_catalog_entry(name)
+            if not cat_entry:
+                # Fallback: find by factory key (provider field in registry)
+                for _e in get_catalog():
+                    if _e.provider == name:
+                        cat_entry = _e
+                        break
+            fopts = cat_entry.field_options if cat_entry else {}
+            display = cat_entry.display_name if cat_entry and cat_entry.display_name else name
+            templates.append({
+                "provider": name,
+                "display_name": display,
+                "type": ptype.value if ptype else "unknown",
+                "defaults": defaults,
+                "field_options": fopts,
+            })
+        except Exception:
+            templates.append({"provider": name, "display_name": name, "type": "unknown", "defaults": {}, "field_options": {}})
+    return {"templates": templates}
+
+
+# ---- Vendor/Provider Templates ----
+
+@router.get("/admin/vendor-templates")
+async def vendor_templates(request: Request):
+    """Return vendor registry templates (shared credential field definitions)."""
+    from openspeech.engine_catalog import get_vendor_registry
+    return {"vendors": get_vendor_registry()}
+
+
+@router.get("/admin/providers")
+async def get_providers(request: Request):
+    """Return configured providers (shared credentials) with secrets masked."""
+    config_path: Path = request.app.state.config_path
+    if not config_path.exists():
+        return {"providers": {}}
+    with open(config_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+
+    # Only return providers in new format (flat credential dicts)
+    providers_out = {}
+    for name, spec in (raw.get("providers") or {}).items():
+        if isinstance(spec, dict) and "exec_mode" not in spec and "provider" not in spec:
+            providers_out[name] = _sanitize_settings(spec)
+    return {"providers": providers_out}
+
+
+class ProvidersUpdate(BaseModel):
+    providers: dict
+
+
+@router.put("/admin/providers")
+async def update_providers(request: Request, body: ProvidersUpdate):
+    """Update providers (shared credentials) section and hot-reload."""
+    config_path: Path = request.app.state.config_path
+
+    existing = {}
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            existing = yaml.safe_load(f) or {}
+
+    existing["providers"] = _restore_masked_provider_secrets(
+        body.providers,
+        existing.get("providers", {}),
+    )
+
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(existing, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+    # Hot-reload
+    dispatcher = request.app.state.dispatcher
+    registry = request.app.state.registry
+    result = await dispatcher.reload_config(config_path, registry)
+    return {"status": "ok", "reload": result}
+
+
+# ---- Engine Catalog ----
+
+@router.get("/engine-catalog")
+async def engine_catalog(request: Request):
+    """Return full engine catalog with installation status.
+
+    Native meta-aliases (native-stt / native-tts) are excluded — only
+    platform-specific entries (windows-stt, macos-stt, etc.) are shown.
+    """
+    config_path: Path = request.app.state.config_path
+    installed = get_installed_engines(config_path)
+    catalog = get_catalog()
+
+    # Filter out native meta-alias entries
+    _NATIVE_META = {"native-stt", "native-tts"}
+
+    return {
+        "engines": [
+            {
+                "name": e.name,
+                "vendor": e.vendor,
+                "provider": e.provider,
+                "type": e.type,
+                "category": e.category,
+                "description": e.description,
+                "display_name": e.display_name or e.name,
+                "installed": e.name in installed,
+                "compatible": e.compatible,
+                "platforms": e.platforms,
+                "default_alias": e.default_alias,
+                "pip_deps": e.pip_deps,
+                "pip_extras": e.pip_extras,
+                "field_options": e.field_options,
+            }
+            for e in catalog
+            if e.name not in _NATIVE_META
+        ]
+    }
+
+
+@router.post("/engine-catalog/{name}/install")
+async def install_engine(request: Request, name: str):
+    """Install an engine: write config + install pip deps + hot-reload."""
+    entry = get_catalog_entry(name)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Engine '{name}' not found in catalog")
+
+    if not entry.compatible:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Engine '{name}' is not compatible with this platform ({sys.platform})"
+        )
+
+    config_path: Path = request.app.state.config_path
+
+    # Read existing config
+    existing = {}
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            existing = yaml.safe_load(f) or {}
+    if "engines" not in existing:
+        existing["engines"] = {}
+
+    # Check if already installed
+    installed = get_installed_engines(config_path)
+    if name in installed:
+        return {"status": "already_installed", "alias": entry.default_alias}
+
+    # Build engine entry
+    engine_entry = {
+        "exec_mode": entry.default_exec_mode,
+        "settings": dict(entry.default_settings),
+    }
+
+    # If engine has a vendor, reference it as provider
+    if entry.vendor:
+        engine_entry["provider"] = entry.vendor
+        # Remove settings keys that duplicate vendor shared fields (e.g. api_key)
+        # — these are inherited from vendor credentials at merge time
+        from openspeech.engine_catalog import get_vendor_registry
+        vendors = get_vendor_registry()
+        vendor_tpl = vendors.get(entry.vendor, {})
+        shared_keys = set(vendor_tpl.get("shared_fields", {}).keys())
+        engine_entry["settings"] = {
+            k: v for k, v in engine_entry["settings"].items()
+            if k not in shared_keys
+        }
+        # Auto-create provider entry if not exists
+        if "providers" not in existing:
+            existing["providers"] = {}
+        if entry.vendor not in existing.get("providers", {}):
+            # Create empty provider with required fields from vendor registry
+            from openspeech.engine_catalog import get_vendor_registry
+            vendors = get_vendor_registry()
+            vendor_tpl = vendors.get(entry.vendor, {})
+            provider_defaults = {}
+            for field_name, field_def in vendor_tpl.get("shared_fields", {}).items():
+                if isinstance(field_def, dict) and "default" in field_def:
+                    provider_defaults[field_name] = field_def["default"]
+                else:
+                    provider_defaults[field_name] = ""
+            existing["providers"][entry.vendor] = provider_defaults
+
+    existing["engines"][entry.default_alias] = engine_entry
+
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(existing, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+    # Run install script for cloud engines (pip deps + verification)
+    install_log = ""
+    if entry.category == "cloud" and entry.pip_deps:
+        script = Path(__file__).resolve().parents[3] / "scripts" / "engines" / "cloud" / "install.sh"
+        if script.exists():
+            env = {
+                **dict(__import__("os").environ),
+                "OPENSPEECH_ENGINE": entry.name,
+                "OPENSPEECH_PIP_DEPS": " ".join(entry.pip_deps),
+                "OPENSPEECH_PYTHON_BIN": sys.executable,
+            }
+            try:
+                proc = subprocess.run(
+                    ["bash", str(script)],
+                    capture_output=True, text=True, timeout=180, env=env,
+                )
+                install_log = proc.stdout
+            except Exception as e:
+                install_log = f"Install script error: {e}"
+
+    # Fallback: direct pip install for any remaining deps
+    pip_results = []
+    for dep in entry.pip_deps:
+        try:
+            # Check if already importable
+            subprocess.run(
+                [sys.executable, "-c", f"import {dep}"],
+                capture_output=True, check=True, timeout=10,
+            )
+            pip_results.append({"dep": dep, "status": "ok"})
+        except subprocess.CalledProcessError:
+            try:
+                subprocess.run(
+                    [sys.executable, "-m", "pip", "install", dep, "--quiet"],
+                    capture_output=True, text=True, check=True, timeout=120,
+                )
+                pip_results.append({"dep": dep, "status": "installed"})
+            except Exception as e:
+                pip_results.append({"dep": dep, "status": "failed", "error": str(e)})
+
+    # Hot-reload
+    dispatcher = request.app.state.dispatcher
+    registry = request.app.state.registry
+    reload_result = await dispatcher.reload_config(config_path, registry)
+
+    return {
+        "status": "installed",
+        "alias": entry.default_alias,
+        "pip": pip_results,
+        "install_log": install_log,
+        "reload": reload_result,
+    }
+
+
+@router.post("/engine-catalog/{name}/uninstall")
+async def uninstall_engine(request: Request, name: str):
+    """Uninstall an engine: remove from config + hot-reload."""
+    entry = get_catalog_entry(name)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Engine '{name}' not found in catalog")
+
+    config_path: Path = request.app.state.config_path
+
+    existing = {}
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            existing = yaml.safe_load(f) or {}
+
+    engines = existing.get("engines", {})
+
+    # Find and remove aliases using this provider
+    removed = []
+    for alias in list(engines.keys()):
+        # Check if this engine matches by provider factory key
+        eng_spec = engines[alias]
+        provider_val = eng_spec.get("provider", "")
+        # Look up factory key from catalog
+        from openspeech.config import _resolve_factory_key
+        factory_key = _resolve_factory_key(alias, provider_val)
+        if factory_key == entry.provider:
+            del engines[alias]
+            removed.append(alias)
+
+    if not removed:
+        return {"status": "not_installed"}
+
+    existing["engines"] = engines
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(existing, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+    # Hot-reload
+    dispatcher = request.app.state.dispatcher
+    registry = request.app.state.registry
+    reload_result = await dispatcher.reload_config(config_path, registry)
+
+    return {"status": "uninstalled", "removed": removed, "reload": reload_result}
+
+
+class BatchInstallRequest(BaseModel):
+    engines: list[str] = Field(..., description='Engine names to install, or ["all"] for all compatible')
+
+
+@router.post("/engine-catalog/batch-install")
+async def batch_install_engines(request: Request, body: BatchInstallRequest):
+    """Install multiple engines at once. Use ["all"] to install all compatible engines."""
+    config_path: Path = request.app.state.config_path
+    catalog = get_catalog()
+    installed = get_installed_engines(config_path)
+
+    # Resolve engine list
+    if body.engines == ["all"]:
+        to_install = [e for e in catalog if e.compatible and e.name not in installed]
+    else:
+        to_install = []
+        for name in body.engines:
+            entry = get_catalog_entry(name)
+            if entry is None:
+                continue
+            if not entry.compatible:
+                continue
+            if entry.name in installed:
+                continue
+            to_install.append(entry)
+
+    if not to_install:
+        return {"status": "nothing_to_install", "results": []}
+
+    # Read existing config
+    existing = {}
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            existing = yaml.safe_load(f) or {}
+    if "engines" not in existing:
+        existing["engines"] = {}
+    if "providers" not in existing:
+        existing["providers"] = {}
+
+    # Load vendor registry for auto-creating provider entries
+    from openspeech.engine_catalog import get_vendor_registry
+    vendors = get_vendor_registry()
+
+    results = []
+    for entry in to_install:
+        # Build engine entry
+        engine_entry = {
+            "exec_mode": entry.default_exec_mode,
+            "settings": dict(entry.default_settings),
+        }
+
+        # If engine has a vendor, reference it as provider
+        if entry.vendor:
+            engine_entry["provider"] = entry.vendor
+            if entry.vendor not in existing["providers"]:
+                vendor_tpl = vendors.get(entry.vendor, {})
+                provider_defaults = {}
+                for field_name, field_def in vendor_tpl.get("shared_fields", {}).items():
+                    if isinstance(field_def, dict) and "default" in field_def:
+                        provider_defaults[field_name] = field_def["default"]
+                    else:
+                        provider_defaults[field_name] = ""
+                existing["providers"][entry.vendor] = provider_defaults
+
+        existing["engines"][entry.default_alias] = engine_entry
+
+        # Install pip deps
+        pip_status = "ok"
+        for dep in entry.pip_deps:
+            try:
+                subprocess.run(
+                    [sys.executable, "-c", f"import {dep}"],
+                    capture_output=True, check=True, timeout=10,
+                )
+            except subprocess.CalledProcessError:
+                try:
+                    subprocess.run(
+                        [sys.executable, "-m", "pip", "install", dep, "--quiet"],
+                        capture_output=True, text=True, check=True, timeout=120,
+                    )
+                except Exception:
+                    pip_status = "pip_failed"
+
+        results.append({"name": entry.name, "alias": entry.default_alias, "pip": pip_status})
+
+    # Write config
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(existing, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+    # Hot-reload
+    dispatcher = request.app.state.dispatcher
+    registry = request.app.state.registry
+    reload_result = await dispatcher.reload_config(config_path, registry)
+
+    return {"status": "installed", "results": results, "reload": reload_result}
+
+
+class EngineActionRequest(BaseModel):
+    engine: str = "fish-speech"
+    action: str
+    runtime: str = "docker"
+    api_url: str = "http://127.0.0.1:8080"
+    install_dir: str = "~/AI/services"
+    work_dir: str = ".openspeech/engines"
+    timeout_s: float = 120.0
+    retries: int = 0
+    options: dict = Field(default_factory=dict)
+
+
+from openspeech.local_engines import EngineAction, RuntimeConfig
+
+
+def _runtime_cfg_from_query(
+    runtime: str,
+    api_url: str,
+    install_dir: str,
+    work_dir: str,
+    timeout_s: float,
+    retries: int,
+) -> RuntimeConfig:
+    return RuntimeConfig(
+        runtime=runtime,
+        api_url=api_url,
+        install_dir=install_dir,
+        work_dir=work_dir,
+        timeout_s=timeout_s,
+        retries=retries,
+        options={},
+    )
+
+
+def _task_snapshot(task) -> dict:
+    if hasattr(task, "snapshot"):
+        return task.snapshot()
+    raise TypeError("Task object must expose snapshot()")
+
+
+@router.post("/engines/actions")
+async def start_engine_action(request: Request, body: EngineActionRequest):
+    manager = request.app.state.engine_manager
+    try:
+        action = EngineAction(body.action)
+        cfg = RuntimeConfig(
+            runtime=body.runtime,
+            api_url=body.api_url,
+            install_dir=body.install_dir,
+            work_dir=body.work_dir,
+            timeout_s=body.timeout_s,
+            retries=body.retries,
+            options=body.options,
+        )
+        task = manager.run_action_async(body.engine, action, cfg)
+        return {"task": _task_snapshot(task)}
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("/engines/status")
+async def engine_status(
+    request: Request,
+    engine: str = Query(default="fish-speech"),
+    runtime: str = Query(default="docker"),
+    api_url: str = Query(default="http://127.0.0.1:8080"),
+    install_dir: str = Query(default="~/AI/services"),
+    work_dir: str = Query(default=".openspeech/engines"),
+    timeout_s: float = Query(default=120.0, ge=1.0, le=3600.0),
+    retries: int = Query(default=0, ge=0, le=10),
+):
+    manager = request.app.state.engine_manager
+    try:
+        cfg = _runtime_cfg_from_query(runtime, api_url, install_dir, work_dir, timeout_s, retries)
+        status = manager.status(engine, cfg)
+        return {
+            "engine": status.engine,
+            "runtime": status.runtime,
+            "running": status.running,
+            "healthy": status.healthy,
+            "detail": status.detail,
+            "metadata": status.metadata,
+        }
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("/engines/logs")
+async def engine_logs(
+    request: Request,
+    engine: str = Query(default="fish-speech"),
+    runtime: str = Query(default="docker"),
+    api_url: str = Query(default="http://127.0.0.1:8080"),
+    install_dir: str = Query(default="~/AI/services"),
+    work_dir: str = Query(default=".openspeech/engines"),
+    timeout_s: float = Query(default=120.0, ge=1.0, le=3600.0),
+    retries: int = Query(default=0, ge=0, le=10),
+    lines: int = Query(default=100, ge=1, le=2000),
+):
+    manager = request.app.state.engine_manager
+    try:
+        cfg = _runtime_cfg_from_query(runtime, api_url, install_dir, work_dir, timeout_s, retries)
+        logs = manager.logs(engine, cfg, lines=lines)
+        return {"logs": logs}
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("/engines/tasks/{task_id}")
+async def get_engine_task(request: Request, task_id: str):
+    manager = request.app.state.engine_manager
+    task = manager.get_task(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task not found: {task_id}")
+    return {"task": _task_snapshot(task)}
+
+
+@router.get("/engines/tasks")
+async def list_engine_tasks(
+    request: Request,
+    engine: str | None = Query(default=None),
+    limit: int = Query(default=20, ge=1, le=200),
+):
+    manager = request.app.state.engine_manager
+    tasks = manager.list_tasks(engine=engine, limit=limit)
+    return {"tasks": [_task_snapshot(t) for t in tasks]}
+
+
+@router.get("/engines/tasks/{task_id}/events")
+async def stream_engine_task_events(
+    request: Request,
+    task_id: str,
+    poll_interval: float = Query(default=1.0, ge=0.2, le=10.0),
+):
+    manager = request.app.state.engine_manager
+    task = manager.get_task(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task not found: {task_id}")
+
+    q = manager.emitter.subscribe(task_id)
+
+    async def _iter_events():
+        last_updated = ""
+        try:
+            initial = _task_snapshot(task)
+            yield f"event: snapshot\ndata: {json.dumps(initial, ensure_ascii=True)}\n\n"
+            if initial.get("status") in {"succeeded", "failed", "cancelled"}:
+                yield f"event: done\ndata: {json.dumps(initial, ensure_ascii=True)}\n\n"
+                return
+
+            while True:
+                if await request.is_disconnected():
+                    return
+                try:
+                    evt = await asyncio.to_thread(q.get, True, poll_interval)
+                    payload = {
+                        "task_id": evt.task_id,
+                        "engine": evt.engine,
+                        "action": evt.action,
+                        "runtime": evt.runtime,
+                        "phase": evt.phase,
+                        "message": evt.message,
+                        "progress": evt.progress,
+                        "eta_seconds": evt.eta_seconds,
+                        "status": evt.status.value,
+                        "timestamp": evt.timestamp.isoformat(),
+                    }
+                    yield f"event: progress\ndata: {json.dumps(payload, ensure_ascii=True)}\n\n"
+                except queue.Empty:
+                    pass
+
+                latest_task = manager.get_task(task_id)
+                if latest_task is None:
+                    return
+                latest = _task_snapshot(latest_task)
+                stamp = str(latest.get("updated_at", ""))
+                if stamp != last_updated:
+                    yield f"event: snapshot\ndata: {json.dumps(latest, ensure_ascii=True)}\n\n"
+                    last_updated = stamp
+                if latest.get("status") in {"succeeded", "failed", "cancelled"}:
+                    yield f"event: done\ndata: {json.dumps(latest, ensure_ascii=True)}\n\n"
+                    return
+        finally:
+            manager.emitter.unsubscribe(task_id, q)
+
+    return StreamingResponse(
+        _iter_events(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.post("/engines/tasks/{task_id}/cancel")
+async def cancel_engine_task(request: Request, task_id: str):
+    manager = request.app.state.engine_manager
+    task = manager.cancel_task(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task not found: {task_id}")
+    return {"task": _task_snapshot(task)}