topos-node 0.1.0__py3-none-any.whl

topos/engine/engine.py

@@ -0,0 +1,165 @@
+"""Topos Engine: single entry point for processing tasks (PRD §5)."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, Optional
+
+from .intake import normalize_task
+
+logger = logging.getLogger("topos.engine")
+from .queue_manager import QueueManager, TaskHandle
+from .result_formatter import format_result
+from .router import get_adapter_for_task
+from .tasks import ExecutionMeta, ProcessingResult, ProcessingTask
+from .validator import validate_task
+
+
+class Engine:
+    """Core processing engine. run(task) sync; submit(task) async via queue."""
+
+    def __init__(
+        self,
+        registry: Optional[Any] = None,
+        queue_max_size: int = 0,
+        use_queue_analyzer: bool = False,
+    ) -> None:
+        """Optional registry for model resolution; queue_max_size 0 = unbounded.
+        use_queue_analyzer: when True, worker dequeues in model-batched order (same model together)."""
+        self._registry = registry
+        self._queue = QueueManager(max_size=queue_max_size)
+        self._use_queue_analyzer = use_queue_analyzer
+
+    def submit(self, task: ProcessingTask) -> Optional[TaskHandle]:
+        """Enqueue task; return TaskHandle or None if queue full. Worker must run to process."""
+        valid, err_msg = validate_task(task)
+        if not valid:
+            handle = TaskHandle(task.id)
+            handle._set_failed(format_result(task_id=task.id, status="failed", raw_output={}, error=err_msg))
+            return handle
+        task_id = self._queue.enqueue(task)
+        if task_id is None:
+            return None
+        return self._queue.get_handle(task_id)
+
+    def run_worker_once(self) -> bool:
+        """Dequeue one task (FIFO or model-sorted when use_queue_analyzer), run it, store result in handle. Returns True if a task was run."""
+        task = self._queue.get_next_for_worker(self._use_queue_analyzer, block=False)
+        if task is None:
+            return False
+        handle = self._queue.get_handle(task.id)
+        if handle:
+            handle._set_running()
+        result = self.run(task)
+        if handle:
+            if result.status == "completed":
+                handle._set_completed(result)
+            else:
+                handle._set_failed(result)
+        return True
+
+    def run(self, task: ProcessingTask) -> ProcessingResult:
+        """
+        Execute a task synchronously: intake → validate → route → inference → format.
+        Returns a ProcessingResult (never raises; errors are in result.status and result.error).
+        """
+        # Validate first (before intake fills defaults, so empty provider is rejected)
+        valid, err_msg = validate_task(task)
+        if not valid:
+            return format_result(
+                task_id=task.id,
+                status="failed",
+                raw_output={},
+                error=err_msg,
+            )
+        # Intake: normalize defaults
+        normalized = normalize_task(task)
+        # Build adapter config: subtype and model from task or registry
+        config = self._build_inference_config(normalized)
+        # Route to backend
+        adapter = get_adapter_for_task(normalized)
+        # Run inference
+        start = time.perf_counter()
+        raw_output = adapter.run_inference(normalized.input, config=config)
+        duration_ms = int((time.perf_counter() - start) * 1000)
+        # Adapter may return error in output
+        if raw_output.get("error"):
+            try:
+                from ..observability.metrics import record_metric
+                record_metric("engine.task_failed", 1.0)
+            except Exception:
+                pass
+            return format_result(
+                task_id=normalized.id,
+                status="failed",
+                raw_output=raw_output,
+                provenance_source_id=normalized.source_id,
+                provenance_record_ids=normalized.record_ids if normalized.record_ids else None,
+                execution_meta=ExecutionMeta(
+                    provider=normalized.model_request.provider,
+                    model=config.get("model"),
+                    duration_ms=duration_ms,
+                    cache_hit=False,
+                ),
+                error=str(raw_output.get("error")),
+            )
+        execution_meta = ExecutionMeta(
+            provider=normalized.model_request.provider,
+            model=raw_output.get("model") or normalized.model_request.model or config.get("model"),
+            duration_ms=duration_ms,
+            cache_hit=False,
+        )
+        try:
+            from ..observability.metrics import record_metric
+            record_metric("engine.task_completed", 1.0)
+            record_metric("engine.inference_duration_ms", float(duration_ms))
+        except Exception:
+            pass
+        return format_result(
+            task_id=normalized.id,
+            status="completed",
+            raw_output=raw_output,
+            provenance_source_id=normalized.source_id,
+            provenance_record_ids=normalized.record_ids if normalized.record_ids else None,
+            execution_meta=execution_meta,
+        )
+
+    def ensure_model(self, provider: str, model_name: str, **kwargs: Any) -> bool:
+        """
+        Ensure the model is available: download/pull if not present.
+        Returns True if we downloaded/pulled (caller may remove it later for cleanup), False if already present.
+        Logs when a download is started and when complete; adapters may log progress.
+        """
+        provider = (provider or "").strip().lower()
+        if provider == "ollama":
+            from .backends import get_ollama_adapter
+            adapter = get_ollama_adapter()
+            if adapter.ensure_model(model_name):
+                logger.info("Model %s (provider=ollama) download complete.", model_name)
+                return True
+            return False
+        if provider == "huggingface":
+            from .backends import get_huggingface_adapter
+            adapter = get_huggingface_adapter()
+            if adapter.ensure_model(model_name, subtype=kwargs.get("subtype")):
+                logger.info("Model %s (provider=huggingface) download complete.", model_name)
+                return True
+            return False
+        return False
+
+    def _build_inference_config(self, task: ProcessingTask) -> Dict[str, Any]:
+        """Build config dict for adapter.run_inference: subtype and model."""
+        model = task.model_request.model
+        if not model and self._registry is not None:
+            spec = self._registry.get_model_for_task(task.type, task.subtype)
+            if spec:
+                provider = (task.model_request.provider or "").strip().lower()
+                if provider == "ollama":
+                    model = spec.get("ollama_model") or spec.get("model")
+                else:
+                    model = spec.get("huggingface_path") or spec.get("model")
+        return {
+            "subtype": task.subtype or "",
+            "model": model,
+        }

topos/engine/intake.py

@@ -0,0 +1,32 @@
+"""Task intake: accept and normalize tasks."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .tasks import ExecutionSpec, ModelRequest, ProcessingTask
+
+
+def normalize_task(task: ProcessingTask) -> ProcessingTask:
+    """Apply defaults to missing optional fields. Returns a copy with defaults set."""
+    data = task.model_dump(mode="json")
+    # Ensure execution has defaults
+    if "execution" not in data or data["execution"] is None:
+        data["execution"] = ExecutionSpec().model_dump(mode="json")
+    else:
+        exec_spec = data["execution"]
+        if exec_spec.get("mode") is None:
+            exec_spec["mode"] = "sync"
+        if exec_spec.get("priority") is None:
+            exec_spec["priority"] = 100
+    # Ensure model_request has provider default
+    if "model_request" in data and data["model_request"]:
+        mr = data["model_request"]
+        if mr.get("provider") is None or mr.get("provider") == "":
+            mr["provider"] = "huggingface"
+    return ProcessingTask.model_validate(data)
+
+
+def task_from_dict(data: Dict[str, Any]) -> ProcessingTask:
+    """Build ProcessingTask from dict (e.g. JSON payload)."""
+    return ProcessingTask.model_validate(data)

topos/engine/queue_manager.py

@@ -0,0 +1,112 @@
+"""In-memory task queue for async execution (Sprint 05)."""
+
+from __future__ import annotations
+
+import queue
+import threading
+from typing import Any, Dict, Optional
+
+from .tasks import ProcessingTask, ProcessingResult
+
+
+class TaskHandle:
+    """Handle for a submitted task: poll status and get result."""
+
+    def __init__(self, task_id: str) -> None:
+        self.task_id = task_id
+        self._status = "pending"  # pending | running | completed | failed
+        self._result: Optional[ProcessingResult] = None
+        self._lock = threading.Lock()
+
+    def get_status(self) -> str:
+        with self._lock:
+            return self._status
+
+    def get_result(self, timeout: Optional[float] = None) -> Optional[ProcessingResult]:
+        with self._lock:
+            return self._result
+
+    def _set_running(self) -> None:
+        with self._lock:
+            self._status = "running"
+
+    def _set_completed(self, result: ProcessingResult) -> None:
+        with self._lock:
+            self._status = "completed"
+            self._result = result
+
+    def _set_failed(self, result: Optional[ProcessingResult] = None) -> None:
+        with self._lock:
+            self._status = "failed"
+            self._result = result
+
+
+class QueueManager:
+    """In-memory queue with optional max size."""
+
+    def __init__(self, max_size: int = 0) -> None:
+        self._max_size = max_size  # 0 = unbounded
+        self._queue: queue.Queue = queue.Queue(maxsize=max_size if max_size > 0 else 0)
+        self._handles: Dict[str, TaskHandle] = {}
+        self._handles_lock = threading.Lock()
+
+    def enqueue(self, task: ProcessingTask) -> Optional[str]:
+        """Enqueue task; return task_id or None if queue full."""
+        task_id = task.id
+        if self._max_size > 0 and self._queue.qsize() >= self._max_size:
+            return None
+        try:
+            self._queue.put_nowait(task)
+        except queue.Full:
+            return None
+        with self._handles_lock:
+            self._handles[task_id] = TaskHandle(task_id)
+        return task_id
+
+    def dequeue(self, block: bool = True, timeout: Optional[float] = None) -> Optional[ProcessingTask]:
+        try:
+            return self._queue.get(block=block, timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def get_next_for_worker(self, sort_by_model: bool, block: bool = False, timeout: Optional[float] = None) -> Optional[ProcessingTask]:
+        """
+        Get the next task for the worker. If sort_by_model is True, drain the queue,
+        sort tasks by (provider, model) to batch same-model runs, then return the first
+        and put the rest back in order.
+        """
+        if not sort_by_model:
+            return self.dequeue(block=block, timeout=timeout)
+        # Drain into list
+        tasks: list = []
+        while True:
+            t = self.dequeue(block=False)
+            if t is None:
+                break
+            tasks.append(t)
+        if not tasks:
+            return None
+        if len(tasks) == 1:
+            return tasks[0]
+        # Sort by (provider, model) so same model is processed together
+        def model_key(task: ProcessingTask) -> str:
+            p = (task.model_request.provider or "").strip().lower()
+            m = (task.model_request.model or "").strip()
+            return f"{p}|{m}"
+
+        tasks.sort(key=model_key)
+        # Put back all but the first
+        for t in tasks[1:]:
+            try:
+                self._queue.put_nowait(t)
+            except queue.Full:
+                # Should not happen with unbounded queue; put the rest back and return first
+                break
+        return tasks[0]
+
+    def get_handle(self, task_id: str) -> Optional[TaskHandle]:
+        with self._handles_lock:
+            return self._handles.get(task_id)
+
+    def qsize(self) -> int:
+        return self._queue.qsize()

topos/engine/registration.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict
+from uuid import uuid4
+
+from ..config.settings import settings
+
+
+CAPABILITIES_SCHEMA_VERSION = "v1"
+
+RUNTIME_PROFILE_OPERATIONS: dict[str, list[str]] = {
+    "basic_hosted": ["healthcheck", "sanitization.run", "filter_lab.list_job_groups"],
+    "upgraded_hosted": [
+        "healthcheck",
+        "sanitization.run",
+        "filter_lab.list_job_groups",
+        "filter_lab.run",
+        "filter_lab.create_job_group",
+    ],
+    "local_engine": [
+        "healthcheck",
+        "sanitization.run",
+        "filter_lab.list_job_groups",
+        "filter_lab.run",
+        "filter_lab.create_job_group",
+        "llm_generation",
+        "ollama_list_models",
+    ],
+}
+
+
+def resolve_runtime_profile() -> str:
+    raw = str(getattr(settings, "topos_compute_profile", "basic_hosted") or "basic_hosted").strip().lower()
+    aliases = {
+        "basic": "basic_hosted",
+        "hosted_basic": "basic_hosted",
+        "pro": "upgraded_hosted",
+        "hosted_pro": "upgraded_hosted",
+        "upgraded": "upgraded_hosted",
+        "local": "local_engine",
+    }
+    normalized = aliases.get(raw, raw)
+    if normalized not in RUNTIME_PROFILE_OPERATIONS:
+        return "basic_hosted"
+    return normalized
+
+
+def build_engine_capabilities() -> Dict[str, Any]:
+    runtime_profile = resolve_runtime_profile()
+    providers: list[str] = []
+    models: list[str] = []
+
+    if settings.enable_llm:
+        providers.append("openai")
+        if settings.openai_model:
+            models.append(settings.openai_model)
+
+    if settings.engine_ollama_base_url:
+        providers.append("ollama")
+
+    return {
+        "schema_version": CAPABILITIES_SCHEMA_VERSION,
+        "providers": sorted(set(providers)),
+        "models": sorted(set(models)),
+        "supports_filtering": True,
+        "supports_sanitization": True,
+        "supports_enrichment": True,
+        "operations": list(RUNTIME_PROFILE_OPERATIONS.get(runtime_profile, [])),
+        "runtime_profile": {
+            "id": runtime_profile,
+            "allowed_operations": list(RUNTIME_PROFILE_OPERATIONS.get(runtime_profile, [])),
+            "deployment_mode": "local" if runtime_profile == "local_engine" else "hosted",
+            "pricing_tier": "pro" if runtime_profile == "upgraded_hosted" else ("local" if runtime_profile == "local_engine" else "basic"),
+        },
+        "limits": {
+            "sanitization_ollama_max_input_chars": settings.sanitization_ollama_max_input_chars,
+            "request_timeout_seconds": settings.request_timeout_seconds,
+        },
+        "transport": {
+            "mode": resolve_transport_mode(),
+            "control_plane_url_configured": bool(settings.topos_control_plane_url),
+        },
+    }
+
+
+def resolve_transport_mode() -> str:
+    mode = str(getattr(settings, "engine_transport_mode", "ws") or "ws").strip().lower()
+    if mode not in {"ws", "endpoint"}:
+        return "ws"
+    return mode
+
+
+def build_engine_register_message() -> Dict[str, Any]:
+    now = datetime.now(timezone.utc).isoformat()
+    return {
+        "id": str(uuid4()),
+        "type": "engine_register",
+        "payload": {
+            "occurred_at": now,
+            "status": "connected",
+            "transport_mode": resolve_transport_mode(),
+            "capabilities": build_engine_capabilities(),
+            "metadata": {
+                "engine_mode": settings.engine_mode,
+                "enable_llm": settings.enable_llm,
+            },
+        },
+    }
+
+
+def build_engine_heartbeat_message() -> Dict[str, Any]:
+    now = datetime.now(timezone.utc).isoformat()
+    return {
+        "id": str(uuid4()),
+        "type": "engine_heartbeat",
+        "payload": {
+            "occurred_at": now,
+            "status": "connected",
+            "transport_mode": resolve_transport_mode(),
+            "metadata": {
+                "engine_mode": settings.engine_mode,
+                "enable_llm": settings.enable_llm,
+            },
+        },
+    }

topos/engine/result_formatter.py

@@ -0,0 +1,38 @@
+"""Result formatter: raw adapter output + meta → ProcessingResult."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .tasks import ExecutionMeta, ProcessingResult, Provenance
+
+
+def format_result(
+    task_id: str,
+    status: str,
+    raw_output: Dict[str, Any],
+    *,
+    provenance_source_id: Optional[str] = None,
+    provenance_record_ids: Optional[list] = None,
+    execution_meta: Optional[ExecutionMeta] = None,
+    error: Optional[str] = None,
+    confidence: Optional[float] = None,
+    output_type: str = "json",
+) -> ProcessingResult:
+    """Build a ProcessingResult from adapter output and metadata."""
+    provenance = None
+    if provenance_source_id is not None or (provenance_record_ids is not None and len(provenance_record_ids or []) > 0):
+        provenance = Provenance(
+            source_id=provenance_source_id,
+            record_ids=provenance_record_ids or [],
+        )
+    return ProcessingResult(
+        task_id=task_id,
+        status=status,
+        output=raw_output,
+        output_type=output_type,
+        confidence=confidence,
+        provenance=provenance,
+        execution_meta=execution_meta,
+        error=error,
+    )

topos/engine/router.py

@@ -0,0 +1,19 @@
+"""Task router: select backend adapter by provider."""
+
+from __future__ import annotations
+
+from .backends import BackendAdapter, get_huggingface_adapter, get_ollama_adapter, get_stub_adapter
+from .tasks import ProcessingTask
+
+
+def get_adapter_for_task(task: ProcessingTask) -> BackendAdapter:
+    """
+    Return the backend adapter for this task's model_request.provider.
+    huggingface -> HuggingFaceAdapter; ollama -> OllamaAdapter; else StubBackendAdapter.
+    """
+    provider = (task.model_request.provider or "").strip().lower()
+    if provider == "huggingface":
+        return get_huggingface_adapter()
+    if provider == "ollama":
+        return get_ollama_adapter()
+    return get_stub_adapter()

topos/engine/scoped_token.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Optional
+
+
+def _b64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(raw: str) -> bytes:
+    padding = "=" * ((4 - len(raw) % 4) % 4)
+    return base64.urlsafe_b64decode((raw + padding).encode("ascii"))
+
+
+def _sign(data: str, secret: str) -> str:
+    digest = hmac.new(secret.encode("utf-8"), data.encode("utf-8"), hashlib.sha256).digest()
+    return _b64url_encode(digest)
+
+
+def create_scoped_invocation_token(claims: Dict[str, Any], *, secret: str) -> str:
+    payload = json.dumps(claims, separators=(",", ":"), sort_keys=True)
+    encoded_payload = _b64url_encode(payload.encode("utf-8"))
+    signature = _sign(encoded_payload, secret)
+    return f"{encoded_payload}.{signature}"
+
+
+class ScopedTokenValidationError(ValueError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def validate_scoped_invocation_token(
+    *,
+    token: str,
+    secret: str,
+    resource_id: str,
+    operation: str,
+    request_id: Optional[str] = None,
+    now_epoch_s: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not token or "." not in token:
+        raise ScopedTokenValidationError("TOKEN_INVALID", "missing or malformed invocation token")
+    encoded_payload, signature = token.split(".", 1)
+    expected = _sign(encoded_payload, secret)
+    if not hmac.compare_digest(signature, expected):
+        raise ScopedTokenValidationError("TOKEN_INVALID", "invalid token signature")
+    try:
+        claims = json.loads(_b64url_decode(encoded_payload).decode("utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        raise ScopedTokenValidationError("TOKEN_INVALID", "token payload is not valid JSON") from exc
+    if not isinstance(claims, dict):
+        raise ScopedTokenValidationError("TOKEN_INVALID", "token payload must be an object")
+
+    now_s = int(now_epoch_s if now_epoch_s is not None else time.time())
+    exp = claims.get("exp")
+    if not isinstance(exp, int):
+        raise ScopedTokenValidationError("TOKEN_INVALID", "token exp claim is required")
+    if now_s >= exp:
+        raise ScopedTokenValidationError("TOKEN_EXPIRED", "invocation token has expired")
+
+    token_resource_id = str(claims.get("resource_id") or "")
+    if token_resource_id != resource_id:
+        raise ScopedTokenValidationError("SCOPE_MISMATCH", "resource_id does not match token scope")
+
+    allowed_ops = claims.get("allowed_operations")
+    if not isinstance(allowed_ops, list) or not allowed_ops:
+        raise ScopedTokenValidationError("TOKEN_INVALID", "allowed_operations claim is required")
+    normalized_allowed = {str(v) for v in allowed_ops if str(v)}
+    if "*" not in normalized_allowed and operation not in normalized_allowed:
+        raise ScopedTokenValidationError("OPERATION_NOT_ALLOWED", "operation not allowed by token scope")
+
+    token_request_id = str(claims.get("request_id") or "")
+    if request_id and token_request_id and token_request_id != request_id:
+        raise ScopedTokenValidationError("SCOPE_MISMATCH", "request_id does not match token scope")
+    return claims