topos-node 1.0.2__tar.gz → 1.0.5__tar.gz

{topos_node-1.0.2 → topos_node-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.0.2
+Version: 1.0.5
 Summary: Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://topos.dialogues.ai
@@ -195,6 +195,16 @@ uv sync --extra engine
 just run
 ```
 
+### Engine memory (local dev)
+
+ML models are cached inside the Engine with LRU eviction. For lighter local runs (especially inside Cursor's integrated terminal), see [Engine memory management](topos/docs/ml-manager-v2/MEMORY_MANAGEMENT.md).
+
+```bash
+# Default: ENGINE_MAX_RESIDENT_MODELS=3; pipeline flush is automatic
+# Override only if needed, e.g. lower RAM: export ENGINE_MAX_RESIDENT_MODELS=2
+export PRIVACY_FILTER_DEVICE=cpu
+```
+
 Run tests:
 
 ```bash

{topos_node-1.0.2 → topos_node-1.0.5}/README.md

@@ -139,6 +139,16 @@ uv sync --extra engine
 just run
 ```
 
+### Engine memory (local dev)
+
+ML models are cached inside the Engine with LRU eviction. For lighter local runs (especially inside Cursor's integrated terminal), see [Engine memory management](topos/docs/ml-manager-v2/MEMORY_MANAGEMENT.md).
+
+```bash
+# Default: ENGINE_MAX_RESIDENT_MODELS=3; pipeline flush is automatic
+# Override only if needed, e.g. lower RAM: export ENGINE_MAX_RESIDENT_MODELS=2
+export PRIVACY_FILTER_DEVICE=cpu
+```
+
 Run tests:
 
 ```bash

{topos_node-1.0.2 → topos_node-1.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.0.2"
+version = "1.0.5"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"

{topos_node-1.0.2 → topos_node-1.0.5}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "1.0.2"
-__version_info__ = (1, 0, 2)
+__version__ = "1.0.5"
+__version_info__ = (1, 0, 5)
 
 __all__ = ["__version__", "__version_info__"]

topos_node-1.0.5/topos/api/engine_run.py

@@ -0,0 +1,43 @@
+"""Engine task execution HTTP endpoint."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ..auth import require_api_key
+from ..engine.engine import Engine
+from ..engine.tasks import ProcessingResult, ProcessingTask
+
+router = APIRouter(tags=["engine-run"])
+
+
+@router.post("/v1/engine/run", dependencies=[Depends(require_api_key)])
+async def engine_run(body: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute a ProcessingTask synchronously and return ProcessingResult JSON."""
+    try:
+        task = ProcessingTask.model_validate(body)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Invalid ProcessingTask: {exc}",
+        ) from exc
+    result: ProcessingResult = Engine().run(task)
+    return {"result": result.model_dump(mode="json")}
+
+
+@router.get("/v1/engine/memory", dependencies=[Depends(require_api_key)])
+async def engine_memory() -> Dict[str, Any]:
+    from ..engine.memory_utils import get_process_rss_mb, mps_available, torch_available
+    from ..engine.model_cache import get_model_cache
+
+    cache = get_model_cache()
+    return {
+        "rss_mb": get_process_rss_mb(),
+        "resident_slots": cache.resident_slots(),
+        "max_resident": cache.max_resident,
+        "evictions_total": cache.evictions_total,
+        "torch_available": torch_available(),
+        "mps_available": mps_available(),
+    }

{topos_node-1.0.2 → topos_node-1.0.5}/topos/app.py

@@ -15,6 +15,7 @@ from .api import (
     app_registry as app_registry_routes,
     backup as backup_routes,
     compute_remote as compute_remote_routes,
+    engine_run as engine_run_routes,
     data_commit as data_commit_routes,
     db as db_routes,
     device as device_routes,
@@ -119,6 +120,7 @@ app.include_router(filter_lab_routes.router)
 app.include_router(home_chat_routes.router)
 app.include_router(privacy_disclose_routes.router)
 app.include_router(compute_remote_routes.router)
+app.include_router(engine_run_routes.router)
 app.include_router(data_commit_routes.router)
 
 

{topos_node-1.0.2 → topos_node-1.0.5}/topos/config/settings.py

@@ -5,7 +5,7 @@ import os
 from pathlib import Path
 from typing import List, Optional
 
-from pydantic import Field, model_validator
+from pydantic import AliasChoices, Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # Set before any huggingface_hub import during app/route loading.
@@ -34,8 +34,14 @@ class Settings(BaseSettings):
 
     openai_base_url: str = Field("https://api.openai.com/v1", env="OPENAI_BASE_URL")
     openai_model: str = Field("gpt-4o-mini", env="OPENAI_MODEL")
-    red_pill_api_key: Optional[str] = Field(None, env="RED_PILL_API_KEY")
-    red_pill_api_base: str = Field("https://api.redpill.ai/v1", env="RED_PILL_API_BASE")
+    red_pill_api_key: Optional[str] = Field(
+        None,
+        validation_alias=AliasChoices("RED_PILL_API_KEY", "REDPILL_API_KEY"),
+    )
+    red_pill_api_base: str = Field(
+        "https://api.redpill.ai/v1",
+        validation_alias=AliasChoices("RED_PILL_API_BASE", "REDPILL_API_BASE"),
+    )
 
     gt_cloud_api_key: Optional[str] = Field(None, env="GT_CLOUD_API_KEY")
     griptape_nodes_api_base_url: str = Field(
@@ -95,6 +101,12 @@ class Settings(BaseSettings):
     ollama_query_model: str = Field("llama3.2:latest", env="TOPOS_OLLAMA_QUERY_MODEL")
     engine_default_provider: str = Field("huggingface", env="ENGINE_DEFAULT_PROVIDER")
 
+    engine_max_resident_models: int = Field(3, env="ENGINE_MAX_RESIDENT_MODELS")
+    engine_model_idle_ttl_sec: int = Field(0, env="ENGINE_MODEL_IDLE_TTL_SEC")
+    engine_memory_rss_soft_limit_mb: int = Field(0, env="ENGINE_MEMORY_RSS_SOFT_LIMIT_MB")
+    engine_flush_after_task: bool = Field(False, env="ENGINE_FLUSH_AFTER_TASK")
+    engine_ml_device: Optional[str] = Field(None, env="ENGINE_ML_DEVICE")
+
     # Sanitization field-transforms via Ollama (see topos.config.sanitization_ollama + engine_config overrides)
     sanitization_ollama_enabled: bool = Field(False, env="SANITIZATION_OLLAMA_ENABLED")
     sanitization_ollama_host: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_HOST")

{topos_node-1.0.2 → topos_node-1.0.5}/topos/disclosure/privacy_layer.py

@@ -69,13 +69,13 @@ class PrivacyLayerClient:
         *,
         transform_id: str,
     ) -> Dict[str, Any]:
-        from ..engine import Engine
+        from ..engine.client import get_engine_client_or_local
         from ..enrichment.jobs.canonical._engine_runner import run_engine_task
 
-        engine = self._engine or Engine()
+        client = get_engine_client_or_local(self._engine)
         record_ids = [str(i.get("id") or "") for i in items]
         result = await run_engine_task(
-            engine,
+            client,
             task_id=f"privacy_{record_ids[0] or 'batch'}",
             subtype="privacy_disclosure",
             source_id=None,
@@ -127,15 +127,15 @@ class PrivacyLayerClient:
         return await self._classify_nsfw_via_engine(items)
 
     async def _classify_nsfw_via_engine(self, items: List[Dict[str, Any]]) -> Dict[str, Any]:
-        from ..engine import Engine
-        from ..enrichment.jobs.canonical._engine_runner import run_engine_task
         from ..config.settings import settings
+        from ..engine.client import get_engine_client_or_local
+        from ..enrichment.jobs.canonical._engine_runner import run_engine_task
 
-        engine = self._engine or Engine()
+        client = get_engine_client_or_local(self._engine)
         model = getattr(settings, "nsfw_classifier_model", "michellejieli/NSFW_text_classifier")
         record_ids = [str(i.get("id") or "") for i in items]
         result = await run_engine_task(
-            engine,
+            client,
             task_id=f"nsfw_{record_ids[0] or 'batch'}",
             subtype="content_nsfw_classification",
             source_id=None,

{topos_node-1.0.2 → topos_node-1.0.5}/topos/engine/__init__.py

@@ -1,6 +1,8 @@
 """Topos Engine: unified runtime for ML/LLM processing (enrichments, transformations, queries)."""
 
 from .engine import Engine
+from .client import EngineClient, LocalEngineClient, RemoteEngineClient, get_engine_client, get_engine_client_or_local
+from .model_cache import ModelSlot, get_model_cache
 from .tasks import (
     ExecutionMeta,
     ExecutionSpec,
@@ -16,6 +18,13 @@ from .tasks import (
 
 __all__ = [
     "Engine",
+    "EngineClient",
+    "LocalEngineClient",
+    "RemoteEngineClient",
+    "get_engine_client",
+    "get_engine_client_or_local",
+    "ModelSlot",
+    "get_model_cache",
     "ProcessingTask",
     "ProcessingResult",
     "ModelRequest",

{topos_node-1.0.2 → topos_node-1.0.5}/topos/engine/backends/huggingface.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import logging
-import threading
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..model_cache import ModelSlot, get_model_cache
 
 logger = logging.getLogger("topos.engine.huggingface")
 
@@ -15,24 +16,38 @@ DEFAULT_NER_MODEL = "dslim/bert-base-NER"
 DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
 DEFAULT_SENTIMENT_MODEL = "cardiffnlp/twitter-roberta-base-sentiment-latest"
 
+_MODEL_NAME_TO_SLOT: Dict[str, ModelSlot] = {
+    DEFAULT_URL_CLASSIFICATION_MODEL: ModelSlot.URL_PIPELINE,
+    DEFAULT_EMOTION_MODEL: ModelSlot.EMOTION,
+    DEFAULT_NER_MODEL: ModelSlot.NER,
+    DEFAULT_EMBEDDING_MODEL: ModelSlot.EMBEDDING,
+    DEFAULT_SENTIMENT_MODEL: ModelSlot.SENTIMENT,
+}
+
+
+def _match_slot(model_name: str) -> Optional[ModelSlot]:
+    name = (model_name or "").strip().lower()
+    if not name:
+        return None
+    for key, slot in _MODEL_NAME_TO_SLOT.items():
+        if key.lower() == name or key.split("/")[-1].lower() in name:
+            return slot
+    if "website-classifier" in name:
+        return ModelSlot.URL_PIPELINE
+    if "go_emotions" in name or "emotion" in name:
+        return ModelSlot.EMOTION
+    if "ner" in name:
+        return ModelSlot.NER
+    if "minilm" in name or "embedding" in name or "sentence-transformers" in name:
+        return ModelSlot.EMBEDDING
+    if "sentiment" in name:
+        return ModelSlot.SENTIMENT
+    return None
+
 
 class HuggingFaceAdapter:
     """BackendAdapter for HuggingFace: text-classification pipeline and go_emotions model."""
 
-    def __init__(self) -> None:
-        self._url_pipeline: Any = None
-        self._url_lock = threading.Lock()
-        self._emotion_model: Any = None
-        self._emotion_tokenizer: Any = None
-        self._emotion_loaded = False
-        self._emotion_lock = threading.Lock()
-        self._ner_pipeline: Any = None
-        self._ner_lock = threading.Lock()
-        self._embedding_model: Any = None
-        self._embedding_lock = threading.Lock()
-        self._sentiment_pipeline: Any = None
-        self._sentiment_lock = threading.Lock()
-
     def load_model(self, model_name: str, config: Optional[Dict[str, Any]] = None) -> None:
         """Load model by name; we load on first run_inference per subtype instead."""
         pass
@@ -41,7 +56,6 @@ class HuggingFaceAdapter:
         """
         Ensure the model is downloaded (e.g. from HuggingFace Hub). Downloads if not present.
         Returns True if a download was triggered (caller may clean up cache later), False if already in cache.
-        Logs when download starts; Hub may show progress via tqdm if enabled.
         """
         try:
             from huggingface_hub import snapshot_download
@@ -49,8 +63,7 @@ class HuggingFaceAdapter:
             return False
         logger.info("Downloading model %s (huggingface)...", model_name)
         try:
-            # tqdm_enabled=True lets HuggingFace show a progress bar when available
-            snapshot_download(repo_id=model_name, tqdm_enabled=True)
+            snapshot_download(repo_id=model_name, tqdm_enabled=False)
         except Exception:
             logger.exception("Failed to download model %s", model_name)
             return False
@@ -58,27 +71,29 @@ class HuggingFaceAdapter:
         return True
 
     def _get_url_pipeline(self, model_name: str):
-        with self._url_lock:
-            if self._url_pipeline is not None:
-                return self._url_pipeline
+        model = model_name or DEFAULT_URL_CLASSIFICATION_MODEL
+
+        def _load():
             from transformers import pipeline
-            self._url_pipeline = pipeline(
-                task="text-classification",
-                model=model_name,
-            )
-            return self._url_pipeline
 
-    def _get_emotion_model(self, model_name: str):
-        with self._emotion_lock:
-            if self._emotion_loaded:
-                return self._emotion_model, self._emotion_tokenizer
+            return pipeline(task="text-classification", model=model)
+
+        handle, _ = get_model_cache().acquire(ModelSlot.URL_PIPELINE, model, _load)
+        return handle
+
+    def _get_emotion_model(self, model_name: str) -> Tuple[Any, Any]:
+        model = model_name or DEFAULT_EMOTION_MODEL
+
+        def _load():
             from transformers import AutoModelForSequenceClassification, AutoTokenizer
-            import torch
-            self._emotion_tokenizer = AutoTokenizer.from_pretrained(model_name)
-            self._emotion_model = AutoModelForSequenceClassification.from_pretrained(model_name)
-            self._emotion_model.eval()
-            self._emotion_loaded = True
-            return self._emotion_model, self._emotion_tokenizer
+
+            tokenizer = AutoTokenizer.from_pretrained(model)
+            emo_model = AutoModelForSequenceClassification.from_pretrained(model)
+            emo_model.eval()
+            return emo_model, tokenizer
+
+        handle, _ = get_model_cache().acquire(ModelSlot.EMOTION, model, _load)
+        return handle
 
     def run_inference(self, payload: Dict[str, Any], config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         """Dispatch by config.subtype to url_classification or emotion_classification."""
@@ -92,6 +107,8 @@ class HuggingFaceAdapter:
             return self._run_url_classification_batch(payload, model)
         if subtype in ("emotion_classification", "emo_27"):
             return self._run_emotion_classification(payload, model)
+        if subtype == "emotion_classification_batch":
+            return self._run_emotion_classification_batch(payload, model)
         if subtype == "entity_extraction":
             return self._run_entity_extraction(payload, model)
         if subtype == "embedding":
@@ -105,17 +122,21 @@ class HuggingFaceAdapter:
         return {"error": f"Unknown subtype: {subtype}", "status": "unsupported"}
 
     def _run_url_classification(self, payload: Dict[str, Any], model_name: str) -> Dict[str, Any]:
-        """Same behavior as WebsiteUrlClassifier."""
         url = payload.get("url") or ""
         title = payload.get("title") or ""
         if not isinstance(url, str) or not url.strip():
-            return {"error": "url must be a non-empty string", "category": "unknown", "confidence": 0.0, "model": model_name or DEFAULT_URL_CLASSIFICATION_MODEL}
+            return {
+                "error": "url must be a non-empty string",
+                "category": "unknown",
+                "confidence": 0.0,
+                "model": model_name or DEFAULT_URL_CLASSIFICATION_MODEL,
+            }
         model = model_name or DEFAULT_URL_CLASSIFICATION_MODEL
-        pipeline = self._get_url_pipeline(model)
+        pipe = self._get_url_pipeline(model)
         clean_url = url.strip()
         clean_title = (title or "").strip()
         text = f"{clean_url} [SEP] {clean_title}" if clean_title else clean_url
-        result = pipeline(text, truncation=True, top_k=1)
+        result = pipe(text, truncation=True, top_k=1)
         top_result = result[0] if isinstance(result, list) and result else {}
         return {
             "category": top_result.get("label", "unknown"),
@@ -128,7 +149,7 @@ class HuggingFaceAdapter:
         if not isinstance(items, list) or not items:
             return {"error": "items required", "items": [], "model": model_name or DEFAULT_URL_CLASSIFICATION_MODEL}
         model = model_name or DEFAULT_URL_CLASSIFICATION_MODEL
-        pipeline = self._get_url_pipeline(model)
+        pipe = self._get_url_pipeline(model)
         texts: List[str] = []
         for item in items:
             url = str(item.get("url") or "").strip()
@@ -142,7 +163,7 @@ class HuggingFaceAdapter:
         classified: List[Any] = []
         if non_empty_idx:
             batch_texts = [texts[i] for i in non_empty_idx]
-            classified = pipeline(batch_texts, truncation=True, top_k=1)
+            classified = pipe(batch_texts, truncation=True, top_k=1)
             if not isinstance(classified, list):
                 classified = [classified]
 
@@ -165,13 +186,10 @@ class HuggingFaceAdapter:
             )
         return {"items": out_items, "model": model}
 
-    def _run_emotion_classification(self, payload: Dict[str, Any], model_name: str) -> Dict[str, Any]:
-        """Same behavior as Emo27Job._classify_emotion."""
-        text = payload.get("text") or payload.get("content") or ""
-        if not text or not isinstance(text, str):
-            return {"error": "text or content required", "emotion_label": None, "confidence": None, "all_emotions": [], "model": model_name or DEFAULT_EMOTION_MODEL}
-        model = model_name or DEFAULT_EMOTION_MODEL
+    def _classify_emotion_text(self, text: str, model_name: str) -> Dict[str, Any]:
         import torch
+
+        model = model_name or DEFAULT_EMOTION_MODEL
         emo_model, tokenizer = self._get_emotion_model(model)
         inputs = tokenizer(
             text,
@@ -201,35 +219,74 @@ class HuggingFaceAdapter:
             "model": model,
         }
 
+    def _run_emotion_classification(self, payload: Dict[str, Any], model_name: str) -> Dict[str, Any]:
+        text = payload.get("text") or payload.get("content") or ""
+        if not text or not isinstance(text, str):
+            return {
+                "error": "text or content required",
+                "emotion_label": None,
+                "confidence": None,
+                "all_emotions": [],
+                "model": model_name or DEFAULT_EMOTION_MODEL,
+            }
+        return self._classify_emotion_text(text, model_name)
+
+    def _run_emotion_classification_batch(self, payload: Dict[str, Any], model_name: str) -> Dict[str, Any]:
+        items = payload.get("items") or []
+        if not isinstance(items, list) or not items:
+            return {"error": "items required", "items": [], "model": model_name or DEFAULT_EMOTION_MODEL}
+        model = model_name or DEFAULT_EMOTION_MODEL
+        out_items: List[Dict[str, Any]] = []
+        for item in items:
+            text = str(item.get("text") or item.get("content") or "")
+            item_id = item.get("id") or item.get("message_id")
+            if not text:
+                out_items.append(
+                    {
+                        "id": item_id,
+                        "emotion_label": None,
+                        "confidence": None,
+                        "all_emotions": [],
+                        "model": model,
+                    }
+                )
+                continue
+            result = self._classify_emotion_text(text, model)
+            out_items.append({"id": item_id, **result})
+        return {"items": out_items, "model": model}
+
     def _get_ner_pipeline(self, model_name: str):
-        with self._ner_lock:
-            if self._ner_pipeline is not None:
-                return self._ner_pipeline
+        model = model_name or DEFAULT_NER_MODEL
+
+        def _load():
             from transformers import pipeline
 
-            model = model_name or DEFAULT_NER_MODEL
-            self._ner_pipeline = pipeline("ner", model=model, aggregation_strategy="simple")
-            return self._ner_pipeline
+            return pipeline("ner", model=model, aggregation_strategy="simple")
+
+        handle, _ = get_model_cache().acquire(ModelSlot.NER, model, _load)
+        return handle
 
     def _get_embedding_model(self, model_name: str):
-        with self._embedding_lock:
-            if self._embedding_model is not None:
-                return self._embedding_model
+        model = model_name or DEFAULT_EMBEDDING_MODEL
+
+        def _load():
             from sentence_transformers import SentenceTransformer
 
-            model = model_name or DEFAULT_EMBEDDING_MODEL
-            self._embedding_model = SentenceTransformer(model)
-            return self._embedding_model
+            return SentenceTransformer(model)
+
+        handle, _ = get_model_cache().acquire(ModelSlot.EMBEDDING, model, _load)
+        return handle
 
     def _get_sentiment_pipeline(self, model_name: str):
-        with self._sentiment_lock:
-            if self._sentiment_pipeline is not None:
-                return self._sentiment_pipeline
+        model = model_name or DEFAULT_SENTIMENT_MODEL
+
+        def _load():
             from transformers import pipeline
 
-            model = model_name or DEFAULT_SENTIMENT_MODEL
-            self._sentiment_pipeline = pipeline("sentiment-analysis", model=model)
-            return self._sentiment_pipeline
+            return pipeline("sentiment-analysis", model=model)
+
+        handle, _ = get_model_cache().acquire(ModelSlot.SENTIMENT, model, _load)
+        return handle
 
     def _run_entity_extraction(self, payload: Dict[str, Any], model_name: str) -> Dict[str, Any]:
         text = payload.get("text") or payload.get("content") or ""
@@ -342,12 +399,12 @@ class HuggingFaceAdapter:
             return self._run_emotion_classification(payload, DEFAULT_EMOTION_MODEL)
 
     def unload_model(self, model_name: str) -> None:
-        """Clear cached pipeline/model (simplified: clear if name matches)."""
-        if model_name == DEFAULT_URL_CLASSIFICATION_MODEL or "website-classifier" in (model_name or ""):
-            with self._url_lock:
-                self._url_pipeline = None
-        if model_name == DEFAULT_EMOTION_MODEL or "go_emotions" in (model_name or ""):
-            with self._emotion_lock:
-                self._emotion_model = None
-                self._emotion_tokenizer = None
-                self._emotion_loaded = False
+        """Evict cached pipeline/model for the given model name."""
+        slot = _match_slot(model_name)
+        if slot is not None:
+            get_model_cache().evict_slot(slot)
+
+    def unload_all(self) -> None:
+        for slot in ModelSlot:
+            if slot not in (ModelSlot.NSFW, ModelSlot.PRIVACY_FILTER):
+                get_model_cache().evict_slot(slot)

topos_node-1.0.5/topos/engine/client.py

@@ -0,0 +1,85 @@
+"""Engine client: in-process or remote HTTP execution."""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import Optional, Protocol
+
+import httpx
+
+from .engine import Engine
+from .tasks import ProcessingResult, ProcessingTask
+
+
+class EngineClient(Protocol):
+    def run(self, task: ProcessingTask) -> ProcessingResult: ...
+
+
+class LocalEngineClient:
+    """Runs tasks in-process via Engine.run()."""
+
+    def __init__(self, engine: Optional[Engine] = None) -> None:
+        self._engine = engine or Engine()
+
+    @property
+    def engine(self) -> Engine:
+        return self._engine
+
+    def run(self, task: ProcessingTask) -> ProcessingResult:
+        return self._engine.run(task)
+
+
+class RemoteEngineClient:
+    """POST ProcessingTask JSON to a remote Topos Engine service."""
+
+    def __init__(self, base_url: str, *, api_key: Optional[str] = None, timeout_sec: float = 120.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = (api_key or "").strip() or None
+        self._timeout_sec = timeout_sec
+
+    def run(self, task: ProcessingTask) -> ProcessingResult:
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        body = task.model_dump(mode="json")
+        with httpx.Client(timeout=self._timeout_sec) as client:
+            resp = client.post(f"{self._base_url}/v1/engine/run", json=body, headers=headers)
+        resp.raise_for_status()
+        data = resp.json()
+        if isinstance(data, dict) and "result" in data:
+            data = data["result"]
+        return ProcessingResult.model_validate(data)
+
+
+def ml_deps_available() -> bool:
+    return importlib.util.find_spec("torch") is not None
+
+
+def get_engine_client(engine: Optional[Engine] = None) -> EngineClient:
+    """Return remote client when configured or ML deps missing; else local."""
+    from ..config.settings import settings
+
+    remote_url = (getattr(settings, "topos_engine_service_url", None) or "").strip()
+    if remote_url:
+        return RemoteEngineClient(
+            remote_url,
+            api_key=getattr(settings, "topos_key", None),
+        )
+    if not ml_deps_available():
+        raise RuntimeError(
+            "ML dependencies unavailable and TOPOS_ENGINE_SERVICE_URL is not configured"
+        )
+    return LocalEngineClient(engine)
+
+
+def get_engine_client_or_local(engine: Optional[Engine] = None) -> EngineClient:
+    """Like get_engine_client but always falls back to local when torch is present."""
+    from ..config.settings import settings
+
+    remote_url = (getattr(settings, "topos_engine_service_url", None) or "").strip()
+    if remote_url:
+        return RemoteEngineClient(
+            remote_url,
+            api_key=getattr(settings, "topos_key", None),
+        )
+    return LocalEngineClient(engine)