@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/mcp_split_proxy_http.py

@@ -0,0 +1,165 @@
+"""HTTP adapter for Codex's split MCP transport."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+import time
+from typing import Any, Callable
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+@dataclass(frozen=True, slots=True)
+class McpSplitProxyHttpPorts:
+    resolve_server: Callable[[str], tuple[str, dict[str, Any]] | None]
+    upstream_url: Callable[[dict[str, Any], str], str]
+    runtime_headers: Callable[[dict[str, Any]], dict[str, str]]
+    copy_response_headers: Callable[[Any, Any], None]
+    is_client_disconnect: Callable[[BaseException], bool]
+    write_json: Callable[..., Any]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class McpSplitProxyHttpAdapter:
+    ports: McpSplitProxyHttpPorts
+    channel_notification_method: str
+
+    @staticmethod
+    def local_sse_hold_seconds() -> float:
+        raw = os.environ.get("CIEL_RUNTIME_CODEX_MCP_LOCAL_SSE_SECONDS", "3600")
+        try:
+            value = float(str(raw).strip())
+        except (TypeError, ValueError):
+            value = 3600.0
+        return max(0.0, min(24 * 3600.0, value))
+
+    def handle_get(self, handler: Any, path: str) -> bool:
+        resolved = self.ports.resolve_server(path)
+        if resolved is None:
+            return False
+        name, _server = resolved
+        handler.send_response(200)
+        handler.send_header("content-type", "text/event-stream")
+        handler.send_header("cache-control", "no-cache")
+        handler.send_header("connection", "close")
+        handler.end_headers()
+        self.ports.log("INFO", f"codex_mcp_split_proxy_local_sse name={name} upstream_get=false")
+        deadline = time.time() + self.local_sse_hold_seconds()
+        try:
+            while time.time() < deadline:
+                handler.wfile.write(b": ciel-runtime owns upstream SSE for this MCP server\n\n")
+                handler.wfile.flush()
+                time.sleep(min(15.0, max(0.05, deadline - time.time())))
+        except (BrokenPipeError, ConnectionError, ConnectionResetError):
+            pass
+        return True
+
+    def handle_request(self, handler: Any, path: str, raw_body: bytes, method: str) -> bool:
+        resolved = self.ports.resolve_server(path)
+        if resolved is None:
+            return False
+        name, server = resolved
+        verb = method.upper()
+        query = urllib.parse.urlparse(handler.path).query
+        upstream_url = self.ports.upstream_url(server, query)
+        data = raw_body if verb in {"POST", "PUT", "PATCH"} else None
+        try:
+            request = urllib.request.Request(
+                upstream_url,
+                data=data,
+                headers=self._request_headers(handler, server),
+                method=verb,
+            )
+            with urllib.request.urlopen(request, timeout=120.0) as response:
+                handler.send_response(getattr(response, "status", 200))
+                self.ports.copy_response_headers(handler, response.headers)
+                handler.end_headers()
+                content_type = str(response.headers.get("Content-Type") or "").split(";", 1)[0].strip().lower()
+                if content_type == "text/event-stream":
+                    self._forward_sse(handler, response, name)
+                else:
+                    self._forward_body(handler, response)
+            self.ports.log(
+                "INFO",
+                f"codex_mcp_split_proxy_forwarded name={name} method={verb} upstream={upstream_url}",
+            )
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            handler.send_response(exc.code)
+            self.ports.copy_response_headers(handler, exc.headers)
+            handler.end_headers()
+            if raw:
+                handler.wfile.write(raw)
+            self.ports.log("WARN", f"codex_mcp_split_proxy_http_error name={name} method={verb} status={exc.code}")
+        except Exception as exc:
+            if self.ports.is_client_disconnect(exc):
+                return True
+            self.ports.write_json(handler, {"error": {"message": f"{type(exc).__name__}: {exc}"}}, status=502)
+            self.ports.log(
+                "WARN",
+                f"codex_mcp_split_proxy_failed name={name} method={verb} error={type(exc).__name__}: {exc}",
+            )
+        return True
+
+    def _request_headers(self, handler: Any, server: dict[str, Any]) -> dict[str, str]:
+        headers = self.ports.runtime_headers(server)
+        skipped = {"host", "content-length", "connection", "transfer-encoding", "content-encoding"}
+        for key, value in handler.headers.items():
+            if str(key).lower() not in skipped:
+                headers[str(key)] = str(value)
+        return headers
+
+    @staticmethod
+    def _forward_body(handler: Any, response: Any) -> None:
+        while True:
+            chunk = response.read(65536)
+            if not chunk:
+                break
+            handler.wfile.write(chunk)
+            handler.wfile.flush()
+
+    def _forward_sse(self, handler: Any, response: Any, server_name: str) -> None:
+        event = bytearray()
+        while True:
+            line = response.readline()
+            if line:
+                event.extend(line)
+            if not line or line in {b"\n", b"\r\n"}:
+                if event:
+                    raw_event = bytes(event)
+                    if self._is_channel_event(raw_event):
+                        self.ports.log(
+                            "INFO",
+                            f"codex_mcp_split_proxy_channel_notification_suppressed "
+                            f"name={server_name} source=post_sse",
+                        )
+                    else:
+                        handler.wfile.write(raw_event)
+                        handler.wfile.flush()
+                    event.clear()
+                if not line:
+                    break
+
+    def _is_channel_event(self, event: bytes) -> bool:
+        data_lines: list[str] = []
+        for raw_line in event.splitlines():
+            field, separator, value = raw_line.decode("utf-8", errors="replace").partition(":")
+            if separator and field == "data":
+                data_lines.append(value[1:] if value.startswith(" ") else value)
+        if not data_lines:
+            return False
+        try:
+            payload = json.loads("\n".join(data_lines))
+        except (json.JSONDecodeError, TypeError):
+            return False
+        return bool(
+            isinstance(payload, dict)
+            and str(payload.get("method") or "").strip() == self.channel_notification_method
+        )
+
+
+__all__ = ["McpSplitProxyHttpAdapter", "McpSplitProxyHttpPorts"]

package/ciel_runtime_support/mcp_stdio_probe.py

@@ -0,0 +1,240 @@
+"""Stdio MCP capability probe process adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+import queue
+import subprocess
+import threading
+import time
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class StdioProbeCodec:
+    initialize_payload: Callable[[], bytes]
+    strategy_for: Callable[..., str]
+    find_initialize_response: Callable[..., dict[str, Any] | None]
+    capability_present: Callable[..., bool]
+    decode_preview: Callable[..., str]
+
+
+@dataclass(frozen=True, slots=True)
+class StdioProbeProcess:
+    is_stdio: Callable[..., bool]
+    resolve_server_process: Callable[..., tuple[str, list[str]]]
+    popen: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class StdioProbePolicy:
+    default_timeout: Callable[[], float]
+    stderr_cap_bytes: int
+    stderr_preview_chars: int
+    stdout_preview_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class StdioProbeServices:
+    codec: StdioProbeCodec
+    process: StdioProbeProcess
+    policy: StdioProbePolicy
+    log: Callable[[str, str], Any]
+
+
+def _empty_result(reason: str) -> dict[str, Any]:
+    return {
+        "capable": False,
+        "reason": reason,
+        "response_bytes": 0,
+        "response_received": False,
+        "exit_code": None,
+        "stderr_bytes": 0,
+        "stderr_preview": "",
+        "stdout_preview": "",
+        "elapsed_ms": 0,
+    }
+
+
+def probe_stdio_mcp_for_channel_capability_detailed(
+    server_name: str,
+    server: dict[str, Any],
+    timeout: float | None = None,
+    *,
+    services: StdioProbeServices,
+) -> dict[str, Any]:
+    started = time.time()
+    codec = services.codec
+    process = services.process
+    policy = services.policy
+    if not process.is_stdio(server):
+        return _empty_result("not_stdio")
+    command = str(server.get("command") or "").strip()
+    args_raw = server.get("args", [])
+    args = [str(item) for item in args_raw] if isinstance(args_raw, list) else []
+    if not command:
+        return _empty_result("no_command")
+    command, args = process.resolve_server_process(command, args)
+    environment = os.environ.copy()
+    raw_environment = server.get("env")
+    if isinstance(raw_environment, dict):
+        environment.update({str(key): str(value) for key, value in raw_environment.items() if str(key)})
+    cwd_value = server.get("cwd") or server.get("workingDirectory")
+    cwd = str(cwd_value) if cwd_value else None
+    framed = codec.strategy_for(server) == "framed"
+    effective_timeout = timeout if timeout is not None else policy.default_timeout()
+    try:
+        child = process.popen(
+            [command, *args],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=cwd,
+            env=environment,
+            bufsize=0,
+            close_fds=True,
+        )
+    except Exception as exc:
+        services.log("DEBUG", f"channel_probe_spawn_failed server={server_name} error={type(exc).__name__}: {exc}")
+        result = _empty_result(f"spawn_failed:{type(exc).__name__}")
+        result["stderr_preview"] = str(exc)[:policy.stderr_preview_chars]
+        result["elapsed_ms"] = int((time.time() - started) * 1000)
+        return result
+
+    stdout_chunks: queue.Queue[bytes | None] = queue.Queue()
+    stderr_buffer = bytearray()
+    stderr_lock = threading.Lock()
+
+    def read_stdout() -> None:
+        try:
+            if child.stdout is None:
+                return
+            while True:
+                chunk = child.stdout.read(4096)
+                if not chunk:
+                    break
+                stdout_chunks.put(chunk)
+        except Exception as exc:
+            services.log("DEBUG", f"channel_probe_stdout_reader_failed server={server_name} error={type(exc).__name__}: {exc}")
+        finally:
+            stdout_chunks.put(None)
+
+    def read_stderr() -> None:
+        try:
+            if child.stderr is None:
+                return
+            while True:
+                chunk = child.stderr.read(1024)
+                if not chunk:
+                    break
+                with stderr_lock:
+                    remaining = policy.stderr_cap_bytes - len(stderr_buffer)
+                    if remaining > 0:
+                        stderr_buffer.extend(chunk[:remaining])
+        except Exception as exc:
+            services.log("DEBUG", f"channel_probe_stderr_reader_failed server={server_name} error={type(exc).__name__}: {exc}")
+
+    stdout_thread = threading.Thread(target=read_stdout, daemon=True, name=f"channel-probe-stdout-{server_name}")
+    stderr_thread = threading.Thread(target=read_stderr, daemon=True, name=f"channel-probe-stderr-{server_name}")
+    stdout_thread.start()
+    stderr_thread.start()
+    body = codec.initialize_payload()
+    frame = b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n" + body if framed else body + b"\n"
+    try:
+        if child.stdin:
+            child.stdin.write(frame)
+            child.stdin.flush()
+    except Exception as exc:
+        services.log("WARN", f"channel_probe_initialize_write_failed server={server_name} error={type(exc).__name__}: {exc}")
+
+    deadline = time.time() + effective_timeout
+    stdout_buffer = bytearray()
+    capable = False
+    response_received = False
+    eof_seen = False
+    try:
+        while time.time() < deadline:
+            wait = min(0.2, max(0.001, deadline - time.time()))
+            try:
+                chunk = stdout_chunks.get(timeout=wait)
+            except queue.Empty:
+                continue
+            if chunk is None:
+                eof_seen = True
+                break
+            stdout_buffer.extend(chunk)
+            response = codec.find_initialize_response(bytes(stdout_buffer), framed)
+            if response is not None:
+                response_received = True
+                capable = codec.capability_present(response)
+                break
+    finally:
+        try:
+            if child.stdin:
+                child.stdin.close()
+        except Exception as exc:
+            services.log("DEBUG", f"channel_probe_stdin_close_failed server={server_name} error={type(exc).__name__}: {exc}")
+        try:
+            child.terminate()
+            child.wait(timeout=1.0)
+        except Exception as terminate_exc:
+            services.log("DEBUG", f"channel_probe_terminate_failed server={server_name} error={type(terminate_exc).__name__}: {terminate_exc}")
+            try:
+                child.kill()
+                child.wait(timeout=1.0)
+            except Exception as kill_exc:
+                services.log("WARN", f"channel_probe_kill_failed server={server_name} error={type(kill_exc).__name__}: {kill_exc}")
+        stdout_thread.join(timeout=1.0)
+        stderr_thread.join(timeout=1.0)
+        for stream in (child.stdout, child.stderr):
+            try:
+                if stream:
+                    stream.close()
+            except Exception as exc:
+                services.log("DEBUG", f"channel_probe_stream_close_failed server={server_name} error={type(exc).__name__}: {exc}")
+
+    exit_code = child.returncode
+    reason = "capable" if capable else (
+        "no_experimental_claude_channel" if response_received else ("exited_without_response" if eof_seen else "timeout")
+    )
+    with stderr_lock:
+        stderr_bytes = len(stderr_buffer)
+        stderr_preview = codec.decode_preview(stderr_buffer, policy.stderr_preview_chars) if not capable else ""
+    stdout_preview = ""
+    if not capable and not response_received and stdout_buffer:
+        stdout_preview = codec.decode_preview(
+            bytes(stdout_buffer)[:policy.stdout_preview_bytes],
+            policy.stdout_preview_bytes,
+        )
+    elapsed_ms = int((time.time() - started) * 1000)
+    services.log(
+        "INFO",
+        "channel_probe_result server=%s channel_capable=%s reason=%s framed=%s bytes=%d stderr_bytes=%d exit_code=%s elapsed_ms=%d timeout_s=%.1f"
+        % (
+            server_name,
+            capable,
+            reason,
+            framed,
+            len(stdout_buffer),
+            stderr_bytes,
+            "None" if exit_code is None else str(exit_code),
+            elapsed_ms,
+            effective_timeout,
+        ),
+    )
+    if stderr_preview:
+        services.log("INFO", f"channel_probe_stderr server={server_name} preview={stderr_preview!r}")
+    if stdout_preview:
+        services.log("INFO", f"channel_probe_stdout server={server_name} preview={stdout_preview!r}")
+    return {
+        "capable": capable,
+        "reason": reason,
+        "response_bytes": len(stdout_buffer),
+        "response_received": response_received,
+        "exit_code": exit_code,
+        "stderr_bytes": stderr_bytes,
+        "stderr_preview": stderr_preview,
+        "stdout_preview": stdout_preview,
+        "elapsed_ms": elapsed_ms,
+    }

package/ciel_runtime_support/mcp_transport.py

@@ -0,0 +1,146 @@
+"""MCP HTTP transport primitives with no channel or router state."""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+MCP_STREAMABLE_HTTP_PROTOCOL_VERSION = "2025-03-26"
+MCP_LEGACY_SSE_PROTOCOL_VERSION = "2024-11-05"
+CODEX_MCP_SPLIT_PROXY_PREFIX = "/ca/codex-mcp/"
+
+
+def read_sse_json_response(response: Any, request_id: Any | None = None) -> Any:
+    """Read the first matching JSON object from an SSE response."""
+
+    data_lines: list[str] = []
+    while True:
+        raw = response.readline()
+        if raw == b"":
+            break
+        line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+        if not line:
+            message = _matching_json_message(data_lines, request_id)
+            if message is not None:
+                return message
+            data_lines = []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if field == "data":
+            data_lines.append(value[1:] if value.startswith(" ") else value)
+    return _matching_json_message(data_lines, request_id)
+
+
+def _matching_json_message(data_lines: list[str], request_id: Any | None) -> dict[str, Any] | None:
+    if not data_lines:
+        return None
+    try:
+        message = json.loads("\n".join(data_lines).strip())
+    except (TypeError, ValueError, json.JSONDecodeError):
+        return None
+    if not isinstance(message, dict):
+        return None
+    if request_id is not None and "id" in message and message.get("id") != request_id:
+        return None
+    return message
+
+
+def post_json_with_response_headers(
+    endpoint: str,
+    headers: dict[str, str],
+    payload: dict[str, Any],
+    timeout: float,
+) -> tuple[Any, Any]:
+    request_headers = {**headers, "Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
+    request = urllib.request.Request(
+        endpoint,
+        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers=request_headers,
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        content_type = str(response.headers.get("Content-Type") or "").lower()
+        if "text/event-stream" in content_type:
+            return read_sse_json_response(response, payload.get("id")), response.headers
+        data = response.read()
+        if not data:
+            return None, response.headers
+        try:
+            return json.loads(data.decode("utf-8")), response.headers
+        except (UnicodeDecodeError, ValueError, json.JSONDecodeError):
+            return data.decode("utf-8", errors="replace"), response.headers
+
+
+def sse_post_json(endpoint: str, headers: dict[str, str], payload: dict[str, Any], timeout: float) -> Any:
+    result, _headers = post_json_with_response_headers(endpoint, headers, payload, timeout)
+    return result
+
+
+def streamable_headers(
+    headers: dict[str, str],
+    protocol_version: str,
+    session_id: str | None = None,
+    *,
+    accept: str = "application/json, text/event-stream",
+) -> dict[str, str]:
+    out = {**headers, "Accept": accept, "MCP-Protocol-Version": protocol_version}
+    if session_id:
+        out["Mcp-Session-Id"] = session_id
+    return out
+
+
+def streamable_post_json(
+    endpoint: str,
+    headers: dict[str, str],
+    payload: dict[str, Any],
+    timeout: float,
+    protocol_version: str,
+    session_id: str | None = None,
+) -> tuple[Any, str | None]:
+    result, response_headers = post_json_with_response_headers(
+        endpoint,
+        streamable_headers(headers, protocol_version, session_id),
+        payload,
+        timeout,
+    )
+    returned_session = None
+    if response_headers is not None:
+        returned_session = response_headers.get("Mcp-Session-Id") or response_headers.get("MCP-Session-Id")
+    return result, str(returned_session).strip() if returned_session else None
+
+
+def split_proxy_server_name(path: str, prefix: str = CODEX_MCP_SPLIT_PROXY_PREFIX) -> str | None:
+    if not path.startswith(prefix):
+        return None
+    suffix = path[len(prefix):]
+    if not suffix or "/" in suffix:
+        return None
+    name = urllib.parse.unquote(suffix).strip()
+    return name or None
+
+
+def upstream_url(server: dict[str, Any], query: str = "") -> str:
+    url = str(server.get("url") or server.get("endpoint") or "").strip()
+    if query:
+        separator = "&" if urllib.parse.urlparse(url).query else "?"
+        url = f"{url}{separator}{query}"
+    return url
+
+
+__all__ = [
+    "CODEX_MCP_SPLIT_PROXY_PREFIX",
+    "MCP_LEGACY_SSE_PROTOCOL_VERSION",
+    "MCP_STREAMABLE_HTTP_PROTOCOL_VERSION",
+    "post_json_with_response_headers",
+    "read_sse_json_response",
+    "split_proxy_server_name",
+    "sse_post_json",
+    "streamable_headers",
+    "streamable_post_json",
+    "upstream_url",
+]

package/ciel_runtime_support/model_cache_lifecycle.py

@@ -0,0 +1,78 @@
+"""Model cache invalidation and launch-time hydration orchestration."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCacheLifecyclePorts:
+    invalidate_config: Callable[[], None]
+    artifact_paths: Callable[[], tuple[Path, ...]]
+    read_list_cache: Callable[[str, dict[str, Any]], list[str] | None]
+    read_registry_models: Callable[[str, dict[str, Any], float], list[str] | None]
+    upstream_model_ids: Callable[[str, dict[str, Any]], list[str]]
+    catalog_model_ids: Callable[[str], list[str]]
+    normalize_model_id: Callable[[str, str], str]
+    unique_model_ids: Callable[[str, list[str]], list[str]]
+    sorted_model_ids: Callable[[list[str]], list[str]]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCacheLifecycleService:
+    ports: ModelCacheLifecyclePorts
+
+    def clear(self) -> None:
+        self.ports.invalidate_config()
+        for path in self.ports.artifact_paths():
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                pass
+
+    def cached_or_configured_ids(
+        self,
+        provider: str,
+        config: dict[str, Any],
+    ) -> list[str]:
+        model_ids = self.ports.read_list_cache(provider, config) or []
+        if provider == "ollama-cloud":
+            model_ids.extend(self.ports.catalog_model_ids(provider))
+        for raw_model_id in config.get("custom_models", []) or []:
+            model_id = self.ports.normalize_model_id(provider, raw_model_id)
+            if model_id and model_id not in model_ids:
+                model_ids.append(model_id)
+        current = self.ports.normalize_model_id(provider, config.get("current_model") or "")
+        if current and current not in model_ids and not current.startswith(
+            f"ciel-runtime-{provider}-"
+        ):
+            model_ids.insert(0, current)
+        model_ids = self.ports.unique_model_ids(provider, model_ids)
+        return model_ids if provider == "anthropic" else self.ports.sorted_model_ids(model_ids)
+
+    def ensure_for_launch(self, provider: str, config: dict[str, Any]) -> None:
+        if self.ports.read_list_cache(provider, config):
+            return
+        if self.ports.read_registry_models(provider, config, 0):
+            return
+        try:
+            model_ids = self.ports.upstream_model_ids(provider, config)
+        except Exception as exc:
+            self.ports.log(
+                "WARN",
+                "launch_model_cache_refresh_failed "
+                f"provider={provider} error={type(exc).__name__}: {exc}",
+            )
+            return
+        if model_ids:
+            self.ports.log(
+                "INFO",
+                f"launch_model_cache_ready provider={provider} count={len(model_ids)}",
+            )
+
+
+__all__ = ["ModelCacheLifecyclePorts", "ModelCacheLifecycleService"]

package/ciel_runtime_support/model_catalog_projection.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+
+@dataclass(frozen=True)
+class ModelCatalogProjectionServices:
+    normalize_model_id: Callable[[str, str], str]
+    model_context: Callable[[Mapping[str, Any]], int | None]
+    positive_int: Callable[[Any], int | None]
+    project_metadata: Callable[[Mapping[str, Any]], Mapping[str, Any]]
+
+
+def project_model_info(
+    provider: str,
+    data: Any,
+    services: ModelCatalogProjectionServices,
+) -> dict[str, dict[str, Any]]:
+    candidates = _model_candidates(data)
+    if candidates is None:
+        return {}
+    output: dict[str, dict[str, Any]] = {}
+    for item in candidates:
+        if isinstance(item, str):
+            model_id = item
+            raw: Mapping[str, Any] = {}
+        elif isinstance(item, Mapping):
+            model_id = str(
+                item.get("id")
+                or item.get("key")
+                or item.get("name")
+                or item.get("model")
+                or ""
+            )
+            raw = item
+        else:
+            continue
+        normalized_id = services.normalize_model_id(provider, model_id.strip())
+        if not normalized_id:
+            continue
+        info = dict(services.project_metadata(raw))
+        max_context = services.positive_int(raw.get("max_context_length")) or services.model_context(raw)
+        if max_context:
+            info["max_model_len"] = max_context
+        if info:
+            output[normalized_id] = info
+    return output
+
+
+def _model_candidates(data: Any) -> list[Any] | None:
+    candidates = data
+    if isinstance(data, Mapping):
+        candidates = data.get("data")
+        if candidates is None:
+            candidates = data.get("models")
+        if candidates is None:
+            candidates = data.get("model")
+    if isinstance(candidates, Mapping) or isinstance(candidates, str):
+        candidates = [candidates]
+    return candidates if isinstance(candidates, list) else None