plexus-python 0.1.0__py3-none-any.whl

plexus/client.py

@@ -0,0 +1,465 @@
+"""
+Plexus client for sending sensor data.
+
+Usage:
+    from plexus import Plexus
+
+    px = Plexus()
+    px.send("temperature", 72.5)
+
+    # With tags
+    px.send("motor.rpm", 3450, tags={"motor_id": "A1"})
+
+    # Flexible value types (not just numbers!)
+    px.send("robot.state", "MOVING")                    # String states
+    px.send("error.code", "E_MOTOR_STALL")              # Error codes
+    px.send("position", {"x": 1.5, "y": 2.3, "z": 0.8}) # Complex objects
+    px.send("joint_angles", [0.5, 1.2, -0.3, 0.0])      # Arrays
+    px.send("motor.enabled", True)                      # Booleans
+
+    # Batch send
+    px.send_batch([
+        ("temperature", 72.5),
+        ("humidity", 45.2),
+        ("pressure", 1013.25),
+    ])
+
+    # Run recording
+    with px.run("motor-test-001"):
+        while True:
+            px.send("temperature", read_temp())
+            time.sleep(0.01)
+
+Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
+"""
+
+import gzip
+import json
+import logging
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import requests
+
+from plexus.buffer import BufferBackend, MemoryBuffer, SqliteBuffer
+from plexus.config import (
+    RetryConfig,
+    get_api_key,
+    get_endpoint,
+    get_gateway_url,
+    get_source_id,
+    require_login,
+)
+logger = logging.getLogger(__name__)
+
+# Flexible value type - supports any JSON-serializable value
+FlexValue = Union[int, float, str, bool, Dict[str, Any], List[Any]]
+
+
+class PlexusError(Exception):
+    """Base exception for Plexus errors."""
+
+    pass
+
+
+class AuthenticationError(PlexusError):
+    """Raised when API key is missing or invalid."""
+
+    pass
+
+
+class Plexus:
+    """
+    Client for sending sensor data to Plexus.
+
+    Args:
+        api_key: Your Plexus API key. If not provided, reads from
+                 PLEXUS_API_KEY env var or ~/.plexus/config.json
+        endpoint: API endpoint URL. Defaults to https://app.plexus.company
+        source_id: Unique identifier for this source. Auto-generated if not provided.
+        timeout: Request timeout in seconds. Default 10s.
+        retry_config: Configuration for retry behavior. If None, uses defaults.
+        max_buffer_size: Maximum number of points to buffer locally on failures. Default 10000.
+
+    Raises:
+        RuntimeError: If not logged in (no API key configured)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        source_id: Optional[str] = None,
+        timeout: float = 10.0,
+        retry_config: Optional[RetryConfig] = None,
+        max_buffer_size: int = 10000,
+        persistent_buffer: bool = False,
+        buffer_path: Optional[str] = None,
+    ):
+        self.api_key = api_key or get_api_key()
+
+        # Require login if no API key provided
+        if not self.api_key:
+            require_login()
+
+        self.endpoint = (endpoint or get_endpoint()).rstrip("/")
+        self.gateway_url = get_gateway_url()
+        self.source_id = source_id or get_source_id()
+        self.timeout = timeout
+        self.retry_config = retry_config or RetryConfig()
+        self._max_buffer_size = max_buffer_size
+
+        self._run_id: Optional[str] = None
+        self._session: Optional[requests.Session] = None
+        self._store_frames: bool = False
+
+        # Pluggable buffer backend for failed sends
+        if persistent_buffer:
+            self._buffer: BufferBackend = SqliteBuffer(
+                path=buffer_path, max_size=max_buffer_size
+            )
+        else:
+            self._buffer: BufferBackend = MemoryBuffer(max_size=max_buffer_size)
+
+    @property
+    def max_buffer_size(self):
+        return self._max_buffer_size
+
+    @max_buffer_size.setter
+    def max_buffer_size(self, value):
+        self._max_buffer_size = value
+        self._buffer._max_size = value
+
+    def _get_session(self) -> requests.Session:
+        """Get or create a requests session for connection pooling."""
+        if self._session is None:
+            self._session = requests.Session()
+            if self.api_key:
+                self._session.headers["x-api-key"] = self.api_key
+            self._session.headers["Content-Type"] = "application/json"
+            from plexus import __version__
+            self._session.headers["User-Agent"] = f"plexus-python/{__version__}"
+        return self._session
+
+    @staticmethod
+    def _normalize_ts_ms(timestamp: Optional[float] = None) -> int:
+        """Normalize a timestamp to milliseconds.
+
+        Accepts:
+            - None: returns current time in ms
+            - float seconds (e.g. time.time()): converts to ms
+            - int/float ms: returned as-is
+        """
+        if timestamp is None:
+            return int(time.time() * 1000)
+        # Heuristic: values < 1e12 are seconds
+        if timestamp > 0 and timestamp < 1e12:
+            return int(timestamp * 1000)
+        return int(timestamp)
+
+    def _make_point(
+        self,
+        metric: str,
+        value: FlexValue,
+        timestamp: Optional[float] = None,
+        tags: Optional[Dict[str, str]] = None,
+        data_class: str = "metric",
+    ) -> Dict[str, Any]:
+        """Create a data point dictionary.
+
+        Value can be:
+            - number (int/float): Traditional sensor readings
+            - string: State machines, error codes, status
+            - bool: Binary flags, enabled/disabled states
+            - dict: Complex objects, vectors, nested data
+            - list: Arrays, coordinates, multi-value readings
+        """
+        point = {
+            "class": data_class,
+            "metric": metric,
+            "value": value,
+            "timestamp": self._normalize_ts_ms(timestamp),
+        }
+        if tags:
+            point["tags"] = tags
+        if self._run_id:
+            point["run_id"] = self._run_id
+        return point
+
+    def send(
+        self,
+        metric: str,
+        value: FlexValue,
+        timestamp: Optional[float] = None,
+        tags: Optional[Dict[str, str]] = None,
+        data_class: str = "metric",
+    ) -> bool:
+        """
+        Send a single metric value to Plexus.
+
+        Args:
+            metric: Name of the metric (e.g., "temperature", "motor.rpm")
+            value: Value to send. Can be:
+                   - number (int/float): px.send("temp", 72.5)
+                   - string: px.send("state", "RUNNING")
+                   - bool: px.send("enabled", True)
+                   - dict: px.send("pos", {"x": 1, "y": 2})
+                   - list: px.send("angles", [0.5, 1.2, -0.3])
+            timestamp: Unix timestamp. If not provided, uses current time.
+            tags: Optional key-value tags for the metric
+            data_class: Pipeline data class - "metric" (default) or "event"
+
+        Returns:
+            True if successful
+
+        Raises:
+            AuthenticationError: If API key is missing or invalid (cloud mode only)
+            PlexusError: If the request fails
+
+        Example:
+            px.send("temperature", 72.5)
+            px.send("motor.rpm", 3450, tags={"motor_id": "A1"})
+            px.send("gps.status", {"fix": "lost"}, data_class="event")
+        """
+        point = self._make_point(metric, value, timestamp, tags, data_class)
+        return self._send_points([point])
+
+    def send_batch(
+        self,
+        points: List[Tuple[str, FlexValue]],
+        timestamp: Optional[float] = None,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> bool:
+        """
+        Send multiple metrics at once.
+
+        Args:
+            points: List of (metric, value) tuples. Values can be any FlexValue type.
+            timestamp: Shared timestamp for all points. If not provided, uses current time.
+            tags: Shared tags for all points
+
+        Returns:
+            True if successful
+
+        Example:
+            px.send_batch([
+                ("temperature", 72.5),
+                ("humidity", 45.2),
+                ("robot.state", "RUNNING"),
+                ("position", {"x": 1.0, "y": 2.0}),
+            ])
+        """
+        ts = timestamp or time.time()
+        data_points = [self._make_point(m, v, ts, tags) for m, v in points]
+        return self._send_points(data_points)
+
+    def _send_points(self, points: List[Dict[str, Any]]) -> bool:
+        """Send data points to the API with retry and buffering.
+
+        Retry behavior:
+        - Retries on: Timeout, ConnectionError, HTTP 429 (rate limit), HTTP 5xx
+        - No retry on: HTTP 401/403 (auth errors), HTTP 400/422 (bad request)
+        - After max retries: buffers points locally for next send attempt
+        """
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key configured. Run 'plexus start' or set PLEXUS_API_KEY"
+            )
+
+        # Include any previously buffered points
+        all_points = self._get_buffered_points() + points
+
+        url = f"{self.gateway_url}/ingest"
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.retry_config.max_retries + 1):
+            try:
+                payload = json.dumps({"source_id": self.source_id, "points": all_points})
+                payload_bytes = payload.encode("utf-8")
+
+                # Gzip compress payloads > 1KB for bandwidth efficiency
+                if len(payload_bytes) > 1024:
+                    body = gzip.compress(payload_bytes, compresslevel=6)
+                    headers = {"Content-Type": "application/json", "Content-Encoding": "gzip"}
+                else:
+                    body = payload_bytes
+                    headers = {"Content-Type": "application/json"}
+
+                response = self._get_session().post(
+                    url,
+                    data=body,
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+
+                # Auth errors - don't retry, raise immediately
+                if response.status_code == 401:
+                    raise AuthenticationError("Invalid API key")
+                elif response.status_code == 403:
+                    raise AuthenticationError("API key doesn't have write permissions")
+
+                # Bad request errors - don't retry (client error)
+                elif response.status_code in (400, 422):
+                    raise PlexusError(
+                        f"Bad request: {response.status_code} - {response.text}"
+                    )
+
+                # Rate limit - retry with backoff
+                elif response.status_code == 429:
+                    last_error = PlexusError("Rate limited (429)")
+                    if attempt < self.retry_config.max_retries:
+                        time.sleep(self.retry_config.get_delay(attempt))
+                        continue
+                    break
+
+                # Server errors - retry with backoff
+                elif response.status_code >= 500:
+                    last_error = PlexusError(
+                        f"Server error: {response.status_code} - {response.text}"
+                    )
+                    if attempt < self.retry_config.max_retries:
+                        time.sleep(self.retry_config.get_delay(attempt))
+                        continue
+                    break
+
+                # Success - clear the buffer and return
+                elif response.status_code < 400:
+                    self._clear_buffer()
+                    return True
+
+                # Other 4xx errors - don't retry
+                else:
+                    raise PlexusError(
+                        f"API error: {response.status_code} - {response.text}"
+                    )
+
+            except requests.exceptions.Timeout:
+                last_error = PlexusError(f"Request timed out after {self.timeout}s")
+                if attempt < self.retry_config.max_retries:
+                    time.sleep(self.retry_config.get_delay(attempt))
+                    continue
+                break
+
+            except requests.exceptions.ConnectionError as e:
+                last_error = PlexusError(f"Connection failed: {e}")
+                if attempt < self.retry_config.max_retries:
+                    time.sleep(self.retry_config.get_delay(attempt))
+                    continue
+                break
+
+        # All retries failed - buffer the points for later
+        self._add_to_buffer(points)
+
+        if last_error:
+            raise last_error
+        raise PlexusError("Send failed after all retries")
+
+    def _add_to_buffer(self, points: List[Dict[str, Any]]) -> None:
+        """Add points to the local buffer for later retry."""
+        self._buffer.add(points)
+
+    def _get_buffered_points(self) -> List[Dict[str, Any]]:
+        """Get a copy of buffered points without clearing."""
+        return self._buffer.get_all()
+
+    def _clear_buffer(self) -> None:
+        """Clear the failed points buffer."""
+        self._buffer.clear()
+
+    def buffer_size(self) -> int:
+        """Return the number of points currently buffered locally.
+
+        Points are buffered when sends fail after all retries.
+        They will be included in the next send attempt.
+        """
+        return self._buffer.size()
+
+    def flush_buffer(self) -> bool:
+        """Attempt to send all buffered points.
+
+        Returns:
+            True if buffer is empty (either was empty or successfully flushed)
+
+        Raises:
+            PlexusError: If flush fails (points remain in buffer)
+        """
+        if self.buffer_size() == 0:
+            return True
+
+        # Send with empty new points list - will include buffered points
+        return self._send_points([])
+
+    @contextmanager
+    def run(self, run_id: str, tags: Optional[Dict[str, str]] = None, store_frames: bool = False):
+        """
+        Context manager for recording a run.
+
+        All sends within this context will be tagged with the run ID,
+        making it easy to replay and analyze later.
+
+        Args:
+            run_id: Unique identifier for this run (e.g., "motor-test-001")
+            tags: Optional tags to apply to all points in this run
+            store_frames: If True, camera frames are uploaded to the Plexus API
+                         for persistent storage alongside the live WebSocket stream.
+
+        Example:
+            with px.run("motor-test-001", store_frames=True):
+                while True:
+                    px.send("temperature", read_temp())
+                    time.sleep(0.01)
+        """
+        self._run_id = run_id
+        self._store_frames = store_frames
+
+        # Notify API that run started
+        try:
+            self._get_session().post(
+                f"{self.endpoint}/api/runs",
+                json={
+                    "run_id": run_id,
+                    "source_id": self.source_id,
+                    "status": "started",
+                    "tags": tags,
+                    "timestamp": time.time(),
+                },
+                timeout=self.timeout,
+            )
+        except Exception as e:
+            logger.debug(f"Run start notification failed: {e}")
+
+        try:
+            yield
+        finally:
+            # Notify API that run ended
+            try:
+                self._get_session().post(
+                    f"{self.endpoint}/api/runs",
+                    json={
+                        "run_id": run_id,
+                        "source_id": self.source_id,
+                        "status": "ended",
+                        "timestamp": time.time(),
+                    },
+                    timeout=self.timeout,
+                )
+            except Exception as e:
+                logger.debug(f"Run end notification failed: {e}")
+            self._run_id = None
+            self._store_frames = False
+
+    def close(self):
+        """Close the client and release resources."""
+        if self._session:
+            self._session.close()
+            self._session = None
+        if hasattr(self._buffer, "close"):
+            self._buffer.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False

plexus/config.py

@@ -0,0 +1,169 @@
+"""
+Configuration management for Plexus Agent.
+
+Config is stored in ~/.plexus/config.json
+"""
+
+import json
+import os
+import random
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for retry behavior with exponential backoff.
+
+    Args:
+        max_retries: Maximum number of retry attempts. Default 3.
+        base_delay: Initial delay in seconds before first retry. Default 1.0.
+        max_delay: Maximum delay between retries in seconds. Default 30.0.
+        exponential_base: Base for exponential backoff calculation. Default 2.
+        jitter: Whether to add random jitter to delays. Default True.
+    """
+
+    max_retries: int = 3
+    base_delay: float = 1.0
+    max_delay: float = 30.0
+    exponential_base: float = 2.0
+    jitter: bool = True
+
+    def get_delay(self, attempt: int) -> float:
+        """Calculate delay for a given retry attempt (0-indexed).
+
+        Uses exponential backoff: delay = base_delay * (exponential_base ** attempt)
+        With optional jitter to prevent thundering herd.
+        """
+        delay = self.base_delay * (self.exponential_base ** attempt)
+        delay = min(delay, self.max_delay)
+
+        if self.jitter:
+            # Add jitter: random value between 0 and delay
+            delay = delay * (0.5 + random.random() * 0.5)
+
+        return delay
+
+CONFIG_DIR = Path.home() / ".plexus"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+PLEXUS_ENDPOINT = "https://app.plexus.company"
+PLEXUS_GATEWAY_URL = "https://plexus-gateway.fly.dev"
+
+DEFAULT_CONFIG = {
+    "api_key": None,
+    "source_id": None,
+    "org_id": None,
+    "source_name": None,
+    "endpoint": None,
+    "persistent_buffer": True,
+    "sensors": None,
+}
+
+def get_config_path() -> Path:
+    """Get the path to the config file."""
+    return CONFIG_FILE
+
+
+def load_config() -> dict:
+    """Load config from file, creating defaults if needed."""
+    if not CONFIG_FILE.exists():
+        return DEFAULT_CONFIG.copy()
+
+    try:
+        with open(CONFIG_FILE, "r") as f:
+            config = json.load(f)
+            # Merge with defaults to handle missing keys
+            return {**DEFAULT_CONFIG, **config}
+    except (json.JSONDecodeError, IOError):
+        return DEFAULT_CONFIG.copy()
+
+
+def save_config(config: dict) -> None:
+    """Save config to file."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(CONFIG_DIR, 0o700)
+    except OSError:
+        pass  # Windows or restricted filesystem
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(config, f, indent=2)
+    # Set restrictive permissions (API key is sensitive)
+    os.chmod(CONFIG_FILE, 0o600)
+
+
+def get_api_key() -> Optional[str]:
+    """Get API key from config or environment variable."""
+    # Environment variable takes precedence
+    env_key = os.environ.get("PLEXUS_API_KEY")
+    if env_key:
+        return env_key
+
+    config = load_config()
+    return config.get("api_key")
+
+
+def get_endpoint() -> str:
+    """Get the API endpoint URL."""
+    # Environment variable takes precedence
+    env_endpoint = os.environ.get("PLEXUS_ENDPOINT")
+    if env_endpoint:
+        return env_endpoint
+
+    # Check config file (use default if value is None/empty)
+    config = load_config()
+    return config.get("endpoint") or PLEXUS_ENDPOINT
+
+
+def get_gateway_url() -> str:
+    """Get the ingest gateway base URL (POST /ingest, GET /ws/device)."""
+    env_gateway = os.environ.get("PLEXUS_GATEWAY_URL")
+    if env_gateway:
+        return env_gateway.rstrip("/")
+    config = load_config()
+    return (config.get("gateway_url") or PLEXUS_GATEWAY_URL).rstrip("/")
+
+
+def get_source_id() -> Optional[str]:
+    """Get the source ID, generating one if not set."""
+    config = load_config()
+    source_id = config.get("source_id")
+
+    if not source_id:
+        import uuid
+        source_id = f"source-{uuid.uuid4().hex[:8]}"
+        config["source_id"] = source_id
+        save_config(config)
+
+    return source_id
+
+
+def get_org_id() -> Optional[str]:
+    """Get the organization ID from config or environment variable."""
+    # Environment variable takes precedence
+    env_org = os.environ.get("PLEXUS_ORG_ID")
+    if env_org:
+        return env_org
+
+    config = load_config()
+    return config.get("org_id")
+
+
+def is_logged_in() -> bool:
+    """Check if device is authenticated (has API key)."""
+    return get_api_key() is not None
+
+
+def require_login() -> None:
+    """Raise an error if not logged in."""
+    if not is_logged_in():
+        raise RuntimeError(
+            "Not logged in. Run 'plexus start' to connect your account."
+        )
+
+
+def get_persistent_buffer() -> bool:
+    """Get persistent buffer setting. Default True (store-and-forward enabled)."""
+    config = load_config()
+    return config.get("persistent_buffer", True)