tactus 0.31.0__py3-none-any.whl

tactus/backends/http_backend.py

@@ -0,0 +1,58 @@
+"""
+HTTP model backend for REST endpoint inference.
+"""
+
+import logging
+from typing import Any
+
+import httpx
+
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPModelBackend:
+    """Model backend that calls HTTP REST endpoints."""
+
+    def __init__(self, endpoint: str, timeout: float = 30.0, headers: dict | None = None):
+        """
+        Initialize HTTP model backend.
+
+        Args:
+            endpoint: URL of the inference endpoint
+            timeout: Request timeout in seconds
+            headers: Optional HTTP headers to include
+        """
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self.headers = headers or {}
+
+    async def predict(self, input_data: Any) -> Any:
+        """
+        Call HTTP endpoint with input data.
+
+        Args:
+            input_data: Data to send to endpoint (will be JSON serialized)
+
+        Returns:
+            Response JSON from endpoint
+        """
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(self.endpoint, json=input_data, headers=self.headers)
+            response.raise_for_status()
+            return response.json()
+
+    def predict_sync(self, input_data: Any) -> Any:
+        """
+        Synchronous version of predict.
+
+        Args:
+            input_data: Data to send to endpoint (will be JSON serialized)
+
+        Returns:
+            Response JSON from endpoint
+        """
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.post(self.endpoint, json=input_data, headers=self.headers)
+            response.raise_for_status()
+            return response.json()

tactus/backends/model_backend.py

@@ -0,0 +1,35 @@
+"""
+Model backend protocol for ML inference.
+
+Defines the interface that all model backends must implement.
+"""
+
+from typing import Any, Protocol
+
+
+class ModelBackend(Protocol):
+    """Protocol for model inference backends."""
+
+    async def predict(self, input_data: Any) -> Any:
+        """
+        Run inference on input data.
+
+        Args:
+            input_data: Input to the model (format depends on backend)
+
+        Returns:
+            Model prediction result
+        """
+        ...
+
+    def predict_sync(self, input_data: Any) -> Any:
+        """
+        Synchronous version of predict.
+
+        Args:
+            input_data: Input to the model (format depends on backend)
+
+        Returns:
+            Model prediction result
+        """
+        ...

tactus/backends/pytorch_backend.py

@@ -0,0 +1,110 @@
+"""
+PyTorch model backend for .pt file inference.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class PyTorchModelBackend:
+    """Model backend that loads and runs PyTorch models."""
+
+    def __init__(self, path: str, device: str = "cpu", labels: list[str] | None = None):
+        """
+        Initialize PyTorch model backend.
+
+        Args:
+            path: Path to .pt model file
+            device: Device to run on ('cpu', 'cuda', 'mps')
+            labels: Optional list of class labels for classification
+        """
+        self.path = Path(path)
+        self.device = device
+        self.labels = labels
+        self.model = None
+
+    def _load_model(self):
+        """Lazy load the model on first use."""
+        if self.model is not None:
+            return
+
+        try:
+            import torch
+        except ImportError:
+            raise ImportError("PyTorch not installed. Install with: pip install torch")
+
+        if not self.path.exists():
+            raise FileNotFoundError(f"Model file not found: {self.path}")
+
+        self.model = torch.load(self.path, map_location=self.device)
+        self.model.eval()
+        logger.info(f"Loaded PyTorch model from {self.path}")
+
+    async def predict(self, input_data: Any) -> Any:
+        """
+        Run PyTorch model inference.
+
+        Args:
+            input_data: Input tensor or data convertible to tensor
+
+        Returns:
+            Model output (tensor or label if labels provided)
+        """
+        return self.predict_sync(input_data)
+
+    def predict_sync(self, input_data: Any) -> Any:
+        """
+        Synchronous PyTorch inference.
+
+        Args:
+            input_data: Input tensor or data convertible to tensor
+
+        Returns:
+            Model output (tensor or label if labels provided)
+        """
+        self._load_model()
+
+        try:
+            import torch
+        except ImportError:
+            raise ImportError("PyTorch not installed. Install with: pip install torch")
+
+        # Convert input to tensor if needed
+        if not isinstance(input_data, torch.Tensor):
+            if isinstance(input_data, (list, tuple)):
+                input_tensor = torch.tensor(input_data)
+            else:
+                input_tensor = torch.tensor([input_data])
+        else:
+            input_tensor = input_data
+
+        # Move to device
+        input_tensor = input_tensor.to(self.device)
+
+        # Run inference
+        with torch.no_grad():
+            output = self.model(input_tensor)
+
+        # If labels provided, return class label
+        if self.labels:
+            if output.dim() > 1:
+                # Classification - get argmax
+                predicted_idx = output.argmax(dim=-1).item()
+            else:
+                # Single value - round to nearest index
+                predicted_idx = int(round(output.item()))
+
+            if 0 <= predicted_idx < len(self.labels):
+                return self.labels[predicted_idx]
+            else:
+                logger.warning(f"Predicted index {predicted_idx} out of range for labels")
+                return predicted_idx
+
+        # Return raw output
+        if output.numel() == 1:
+            return output.item()
+        else:
+            return output.cpu().numpy().tolist()

tactus/broker/__init__.py

@@ -0,0 +1,12 @@
+"""
+Brokered capabilities for Tactus.
+
+The broker is a trusted host-side process that holds credentials and performs
+privileged operations (e.g., LLM API calls) on behalf of a secretless, networkless
+runtime container.
+"""
+
+from tactus.broker.client import BrokerClient
+from tactus.broker.server import BrokerServer, TcpBrokerServer
+
+__all__ = ["BrokerClient", "BrokerServer", "TcpBrokerServer"]

tactus/broker/client.py

@@ -0,0 +1,247 @@
+"""
+Broker client for use inside the runtime container.
+
+Uses a broker transport selected at runtime:
+- `stdio` (recommended for Docker Desktop): requests are written to stderr with a marker and
+  responses are read from stdin as NDJSON.
+- Unix domain sockets (UDS): retained for non-Docker/host testing.
+"""
+
+import asyncio
+import json
+import os
+import ssl
+import sys
+import threading
+import uuid
+from pathlib import Path
+from typing import Any, AsyncIterator, Optional
+
+from tactus.broker.protocol import read_message, write_message
+from tactus.broker.stdio import STDIO_REQUEST_PREFIX, STDIO_TRANSPORT_VALUE
+
+
+def _json_dumps(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
+
+
+class _StdioBrokerTransport:
+    def __init__(self):
+        self._write_lock = threading.Lock()
+        self._pending: dict[
+            str, tuple[asyncio.AbstractEventLoop, asyncio.Queue[dict[str, Any]]]
+        ] = {}
+        self._pending_lock = threading.Lock()
+        self._reader_thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+
+    def _ensure_reader_thread(self) -> None:
+        if self._reader_thread is not None and self._reader_thread.is_alive():
+            return
+
+        self._reader_thread = threading.Thread(
+            target=self._read_loop,
+            name="tactus-broker-stdio-reader",
+            daemon=True,
+        )
+        self._reader_thread.start()
+
+    def _read_loop(self) -> None:
+        while not self._stop.is_set():
+            line = sys.stdin.buffer.readline()
+            if not line:
+                return
+            try:
+                event = json.loads(line.decode("utf-8"))
+            except json.JSONDecodeError:
+                continue
+
+            req_id = event.get("id")
+            if not isinstance(req_id, str):
+                continue
+
+            with self._pending_lock:
+                pending = self._pending.get(req_id)
+            if pending is None:
+                continue
+
+            loop, queue = pending
+            try:
+                loop.call_soon_threadsafe(queue.put_nowait, event)
+            except RuntimeError:
+                # Loop is closed or unavailable; ignore.
+                continue
+
+    async def aclose(self) -> None:
+        self._stop.set()
+        thread = self._reader_thread
+        if thread is None or not thread.is_alive():
+            return
+        try:
+            await asyncio.to_thread(thread.join, 0.5)
+        except Exception:
+            return
+
+    async def request(
+        self, req_id: str, method: str, params: dict[str, Any]
+    ) -> AsyncIterator[dict[str, Any]]:
+        self._ensure_reader_thread()
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        with self._pending_lock:
+            self._pending[req_id] = (loop, queue)
+
+        try:
+            payload = _json_dumps({"id": req_id, "method": method, "params": params})
+            with self._write_lock:
+                sys.stderr.write(f"{STDIO_REQUEST_PREFIX}{payload}\n")
+                sys.stderr.flush()
+
+            while True:
+                event = await queue.get()
+                yield event
+                if event.get("event") in ("done", "error"):
+                    return
+        finally:
+            with self._pending_lock:
+                self._pending.pop(req_id, None)
+
+
+_STDIO_TRANSPORT = _StdioBrokerTransport()
+
+
+async def close_stdio_transport() -> None:
+    await _STDIO_TRANSPORT.aclose()
+
+
+class BrokerClient:
+    def __init__(self, socket_path: str | Path):
+        self.socket_path = str(socket_path)
+
+    @classmethod
+    def from_environment(cls) -> Optional["BrokerClient"]:
+        socket_path = os.environ.get("TACTUS_BROKER_SOCKET")
+        if not socket_path:
+            return None
+        return cls(socket_path)
+
+    async def _request(self, method: str, params: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        req_id = uuid.uuid4().hex
+
+        if self.socket_path == STDIO_TRANSPORT_VALUE:
+            async for event in _STDIO_TRANSPORT.request(req_id, method, params):
+                # Responses are already correlated by req_id; add a defensive filter anyway.
+                if event.get("id") == req_id:
+                    yield event
+            return
+
+        if self.socket_path.startswith(("tcp://", "tls://")):
+            use_tls = self.socket_path.startswith("tls://")
+            host_port = self.socket_path.split("://", 1)[1]
+            if "/" in host_port:
+                host_port = host_port.split("/", 1)[0]
+            if ":" not in host_port:
+                raise ValueError(
+                    f"Invalid broker endpoint: {self.socket_path}. Expected tcp://host:port or tls://host:port"
+                )
+            host, port_str = host_port.rsplit(":", 1)
+            try:
+                port = int(port_str)
+            except ValueError as e:
+                raise ValueError(f"Invalid broker port in endpoint: {self.socket_path}") from e
+
+            ssl_ctx: ssl.SSLContext | None = None
+            if use_tls:
+                ssl_ctx = ssl.create_default_context()
+                cafile = os.environ.get("TACTUS_BROKER_TLS_CA_FILE")
+                if cafile:
+                    ssl_ctx.load_verify_locations(cafile=cafile)
+
+                if os.environ.get("TACTUS_BROKER_TLS_INSECURE") in ("1", "true", "yes"):
+                    ssl_ctx.check_hostname = False
+                    ssl_ctx.verify_mode = ssl.CERT_NONE
+
+            reader, writer = await asyncio.open_connection(host, port, ssl=ssl_ctx)
+            await write_message(writer, {"id": req_id, "method": method, "params": params})
+
+            try:
+                while True:
+                    event = await read_message(reader)
+                    if event.get("id") != req_id:
+                        continue
+                    yield event
+                    if event.get("event") in ("done", "error"):
+                        return
+            finally:
+                try:
+                    writer.close()
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+
+        reader, writer = await asyncio.open_unix_connection(self.socket_path)
+        await write_message(writer, {"id": req_id, "method": method, "params": params})
+
+        try:
+            while True:
+                event = await read_message(reader)
+                # Ignore unrelated messages (defensive; current server is 1-req/conn).
+                if event.get("id") != req_id:
+                    continue
+                yield event
+                if event.get("event") in ("done", "error"):
+                    return
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    def llm_chat(
+        self,
+        *,
+        provider: str,
+        model: str,
+        messages: list[dict[str, Any]],
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stream: bool,
+    ) -> AsyncIterator[dict[str, Any]]:
+        params: dict[str, Any] = {
+            "provider": provider,
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+        }
+        if temperature is not None:
+            params["temperature"] = temperature
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+        return self._request("llm.chat", params)
+
+    async def call_tool(self, *, name: str, args: dict[str, Any]) -> Any:
+        """
+        Call an allowlisted host tool via the broker.
+
+        Returns the decoded `result` payload from the broker.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("tool name must be a non-empty string")
+        if not isinstance(args, dict):
+            raise ValueError("tool args must be an object")
+
+        async for event in self._request("tool.call", {"name": name, "args": args}):
+            event_type = event.get("event")
+            if event_type == "done":
+                data = event.get("data") or {}
+                return data.get("result")
+            if event_type == "error":
+                err = event.get("error") or {}
+                raise RuntimeError(err.get("message") or "Broker tool error")
+
+        raise RuntimeError("Broker tool call ended without a response")
+
+    async def emit_event(self, event: dict[str, Any]) -> None:
+        async for _ in self._request("events.emit", {"event": event}):
+            pass

tactus/broker/protocol.py

@@ -0,0 +1,183 @@
+"""
+Length-prefixed JSON protocol for broker communication.
+
+This module provides utilities for sending and receiving JSON messages
+with a length prefix, avoiding the buffer size limitations of newline-delimited JSON.
+
+Wire format:
+    <10-digit-decimal-length>\n<json-payload>
+
+Example:
+    0000000123
+    {"id":"abc","method":"llm.chat","params":{...}}
+"""
+
+import json
+import asyncio
+import logging
+from typing import Any, Dict, AsyncIterator
+
+import anyio
+from anyio.streams.buffered import BufferedByteReceiveStream
+
+logger = logging.getLogger(__name__)
+
+# Length prefix is exactly 10 decimal digits + newline
+LENGTH_PREFIX_SIZE = 11  # "0000000123\n"
+MAX_MESSAGE_SIZE = 100 * 1024 * 1024  # 100MB safety limit
+
+
+async def write_message(writer: asyncio.StreamWriter, message: Dict[str, Any]) -> None:
+    """
+    Write a JSON message with length prefix.
+
+    Args:
+        writer: asyncio StreamWriter
+        message: Dictionary to encode as JSON
+
+    Raises:
+        ValueError: If message is too large
+    """
+    json_bytes = json.dumps(message).encode("utf-8")
+    length = len(json_bytes)
+
+    if length > MAX_MESSAGE_SIZE:
+        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
+
+    # Write 10-digit length prefix + newline
+    length_prefix = f"{length:010d}\n".encode("ascii")
+    writer.write(length_prefix)
+    writer.write(json_bytes)
+    await writer.drain()
+
+
+async def read_message(reader: asyncio.StreamReader) -> Dict[str, Any]:
+    """
+    Read a JSON message with length prefix.
+
+    Args:
+        reader: asyncio StreamReader
+
+    Returns:
+        Parsed JSON message as dictionary
+
+    Raises:
+        EOFError: If connection closed
+        ValueError: If message is invalid or too large
+    """
+    # Read exactly 11 bytes for length prefix
+    length_bytes = await reader.readexactly(LENGTH_PREFIX_SIZE)
+
+    if not length_bytes:
+        raise EOFError("Connection closed")
+
+    try:
+        length_str = length_bytes[:10].decode("ascii")
+        length = int(length_str)
+    except (ValueError, UnicodeDecodeError) as e:
+        raise ValueError(f"Invalid length prefix: {length_bytes!r}") from e
+
+    if length > MAX_MESSAGE_SIZE:
+        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
+
+    if length == 0:
+        raise ValueError("Zero-length message not allowed")
+
+    # Read exactly that many bytes for the JSON payload
+    json_bytes = await reader.readexactly(length)
+
+    try:
+        message = json.loads(json_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as e:
+        raise ValueError("Invalid JSON payload") from e
+
+    return message
+
+
+async def read_messages(reader: asyncio.StreamReader) -> AsyncIterator[Dict[str, Any]]:
+    """
+    Read a stream of length-prefixed JSON messages.
+
+    Args:
+        reader: asyncio StreamReader
+
+    Yields:
+        Parsed JSON messages as dictionaries
+
+    Stops when connection is closed or error occurs.
+    """
+    try:
+        while True:
+            message = await read_message(reader)
+            yield message
+    except EOFError:
+        return
+    except asyncio.IncompleteReadError:
+        return
+
+
+# AnyIO-compatible versions for broker server
+async def write_message_anyio(stream: anyio.abc.ByteStream, message: Dict[str, Any]) -> None:
+    """
+    Write a JSON message with length prefix using AnyIO streams.
+
+    Args:
+        stream: anyio ByteStream
+        message: Dictionary to encode as JSON
+
+    Raises:
+        ValueError: If message is too large
+    """
+    json_bytes = json.dumps(message).encode("utf-8")
+    length = len(json_bytes)
+
+    if length > MAX_MESSAGE_SIZE:
+        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
+
+    # Write 10-digit length prefix + newline
+    length_prefix = f"{length:010d}\n".encode("ascii")
+    await stream.send(length_prefix)
+    await stream.send(json_bytes)
+
+
+async def read_message_anyio(stream: BufferedByteReceiveStream) -> Dict[str, Any]:
+    """
+    Read a JSON message with length prefix using AnyIO streams.
+
+    Args:
+        stream: anyio BufferedByteReceiveStream
+
+    Returns:
+        Parsed JSON message as dictionary
+
+    Raises:
+        EOFError: If connection closed
+        ValueError: If message is invalid or too large
+    """
+    # Read exactly 11 bytes for length prefix
+    length_bytes = await stream.receive_exactly(LENGTH_PREFIX_SIZE)
+
+    if not length_bytes:
+        raise EOFError("Connection closed")
+
+    try:
+        length_str = length_bytes[:10].decode("ascii")
+        length = int(length_str)
+    except (ValueError, UnicodeDecodeError) as e:
+        raise ValueError(f"Invalid length prefix: {length_bytes!r}") from e
+
+    if length > MAX_MESSAGE_SIZE:
+        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
+
+    if length == 0:
+        raise ValueError("Zero-length message not allowed")
+
+    # Read exactly that many bytes for the JSON payload
+    json_bytes = await stream.receive_exactly(length)
+
+    try:
+        message = json.loads(json_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as e:
+        raise ValueError("Invalid JSON payload") from e
+
+    return message