openadapt-desktop 0.2.0__py3-none-any.whl

engine/__init__.py

@@ -0,0 +1,24 @@
+"""OpenAdapt Desktop Engine -- Python sidecar for the Tauri shell.
+
+This package implements the recording engine, PII scrubbing, storage management,
+upload backends, and health monitoring. It runs as a standalone process that
+communicates with the Tauri shell via JSON-over-stdin/stdout IPC.
+
+Architecture:
+    Tauri Shell (Rust + WebView)
+        |  IPC (JSON over stdin/stdout)
+        v
+    Python Engine (this package)
+        +-- controller.py      Recording start/stop/pause
+        +-- ipc.py             JSON line protocol handler
+        +-- storage_manager.py Storage tiers, cleanup, index
+        +-- upload_manager.py  Multi-backend upload with queue
+        +-- scrubber.py        PII scrubbing orchestration
+        +-- review.py          Upload review state machine
+        +-- config.py          Settings (pydantic-settings)
+        +-- monitor.py         Health monitoring (memory, disk, watchdog)
+        +-- audit.py           Network audit logging
+        +-- backends/          Storage backend plugins
+"""
+
+__version__ = "0.2.0"

engine/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m engine`."""
+
+from engine.main import main
+
+main()

engine/audit.py

@@ -0,0 +1,125 @@
+"""Network audit logging -- append-only JSONL log of all outbound network activity.
+
+Every outbound network request is logged to an append-only JSONL file at
+~/.openadapt/audit.jsonl. This enables enterprise IT to:
+    - grep the audit log for unexpected destinations
+    - set firewall rules allowing only their S3 endpoint
+    - use a network proxy to independently verify traffic
+    - run OPENADAPT_STORAGE_MODE=air-gapped and confirm zero outbound traffic
+
+Log format (from design doc Section 7.9):
+    {"ts":"2026-03-02T10:00:01Z","event":"startup","storage_mode":"enterprise","backends":["s3"],"excluded":["hf","r2","ipfs"]}
+    {"ts":"2026-03-02T10:05:00Z","event":"upload_start","backend":"s3","dest":"s3://bucket/rec.tar.zst","size_mb":142}
+    {"ts":"2026-03-02T10:05:32Z","event":"upload_complete","backend":"s3","dest":"s3://bucket/rec.tar.zst","bytes_sent":148897280}
+
+All significant actions are logged:
+    - Recording started/stopped
+    - Upload initiated/completed/failed (with destination URL)
+    - Settings changed
+    - Data deleted (local or cloud)
+    - Update installed
+    - Permissions granted/denied
+    - Every outbound network request (destination, size, response code)
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+class AuditLogger:
+    """Append-only audit logger for network and significant events.
+
+    Args:
+        log_path: Path to the audit.jsonl file.
+        enabled: Whether audit logging is active.
+    """
+
+    def __init__(self, log_path: Path, enabled: bool = True) -> None:
+        self.log_path = log_path
+        self.enabled = enabled
+
+    def log(self, event: str, **data: Any) -> None:
+        """Write an audit log entry.
+
+        Args:
+            event: Event type (e.g., "startup", "upload_start", "settings_changed").
+            **data: Additional event data as keyword arguments.
+        """
+        if not self.enabled:
+            return
+
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "event": event,
+            **data,
+        }
+
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(entry)
+        with open(self.log_path, "a") as f:
+            f.write(line + "\n")
+
+    def log_startup(self, storage_mode: str, active_backends: list[str]) -> None:
+        """Log engine startup with active configuration.
+
+        Args:
+            storage_mode: Current storage mode (air-gapped, enterprise, community, full).
+            active_backends: List of active backend names.
+        """
+        all_backends = {"s3", "r2", "hf", "wormhole", "federated"}
+        excluded = sorted(all_backends - set(active_backends))
+        self.log(
+            "startup",
+            storage_mode=storage_mode,
+            backends=active_backends,
+            excluded=excluded,
+        )
+
+    def log_upload_start(self, backend: str, dest: str, size_bytes: int) -> None:
+        """Log the start of an upload operation.
+
+        Args:
+            backend: Storage backend name.
+            dest: Destination URI (e.g., "s3://bucket/key").
+            size_bytes: Size of the data being uploaded.
+        """
+        self.log(
+            "upload_start",
+            backend=backend,
+            dest=dest,
+            size_mb=round(size_bytes / (1024 * 1024), 1),
+        )
+
+    def log_upload_complete(self, backend: str, dest: str, bytes_sent: int) -> None:
+        """Log the completion of an upload operation.
+
+        Args:
+            backend: Storage backend name.
+            dest: Destination URI.
+            bytes_sent: Total bytes sent.
+        """
+        self.log(
+            "upload_complete",
+            backend=backend,
+            dest=dest,
+            bytes_sent=bytes_sent,
+        )
+
+    def log_upload_failed(self, backend: str, dest: str, error: str) -> None:
+        """Log a failed upload operation.
+
+        Args:
+            backend: Storage backend name.
+            dest: Destination URI.
+            error: Error message.
+        """
+        self.log(
+            "upload_failed",
+            backend=backend,
+            dest=dest,
+            error=error,
+        )

engine/backends/__init__.py

@@ -0,0 +1,12 @@
+"""Storage backend plugins for OpenAdapt Desktop.
+
+Each backend implements the StorageBackend protocol defined in protocol.py.
+Backends are loaded conditionally based on build-time feature flags and
+runtime configuration.
+
+Available backends:
+    s3          S3-compatible (AWS S3, Cloudflare R2, MinIO)
+    huggingface HuggingFace Hub (public/private datasets)
+    wormhole    Magic Wormhole (P2P ephemeral transfer)
+    federated   Federated learning gradient upload (Flower)
+"""

engine/backends/federated.py

@@ -0,0 +1,117 @@
+"""Federated learning gradient upload backend -- Flower-based federated learning.
+
+Federated learning solves the tension between privacy and model improvement:
+    - Enterprise users get model improvements WITHOUT sharing any data
+    - Community users get model improvements WITHOUT seeing enterprise screens
+    - OpenAdapt trains better models without centralized data collection
+
+What gets shared:
+    - Model weight deltas (compressed, ~1-10 MB per round)
+    - Participation metadata (sample count, training loss)
+    - Differentially private gradients (optionally)
+
+What does NOT get shared:
+    - Raw screenshots
+    - Keyboard/mouse events
+    - Any recording content
+
+Phasing (from design doc Section 9.8):
+    v0.1-v0.5: No federated (data collection focus)
+    v1.0:      Custom gradient API (manual model update sharing)
+    v2.0:      Flower integration (automated federated rounds)
+    v3.0:      Secure aggregation + DP (enterprise-grade privacy)
+
+Requires: flwr, torch (installed via federated or full extras)
+
+See design doc Section 9 for the full federated learning design.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from engine.backends.protocol import UploadRecord, UploadResult
+
+
+class FederatedBackend:
+    """Federated learning gradient upload backend.
+
+    Uploads model gradients (NOT raw data) to a Flower aggregation server.
+    The server averages gradients from all participants to produce an
+    improved global model.
+
+    Args:
+        server_url: Flower aggregation server URL.
+        rounds_per_day: How many federated rounds to participate in per day.
+        min_local_samples: Minimum number of local recordings before participating.
+        differential_privacy: Whether to add DP noise to gradients.
+        epsilon: Privacy budget (lower = more private, noisier gradients).
+    """
+
+    name: str = "federated"
+    supports_delete: bool = False
+    supports_list: bool = False
+
+    def __init__(
+        self,
+        server_url: str = "https://fl.openadapt.ai",
+        rounds_per_day: int = 1,
+        min_local_samples: int = 100,
+        differential_privacy: bool = True,
+        epsilon: float = 1.0,
+    ) -> None:
+        self.server_url = server_url
+        self.rounds_per_day = rounds_per_day
+        self.min_local_samples = min_local_samples
+        self.differential_privacy = differential_privacy
+        self.epsilon = epsilon
+
+    def upload(self, archive_path: Path, metadata: dict) -> UploadResult:
+        """Upload model gradients (not raw data) to the FL server.
+
+        This method performs local training on the capture data and
+        uploads only the resulting model weight deltas.
+
+        Args:
+            archive_path: Path to the capture (used for local training, not uploaded).
+            metadata: Capture metadata.
+
+        Returns:
+            UploadResult with gradient upload confirmation.
+        """
+        # TODO: Load base model
+        # TODO: Fine-tune on local capture data
+        # TODO: Compute gradient deltas
+        # TODO: Apply differential privacy noise if enabled
+        # TODO: Upload gradients to Flower server
+        raise NotImplementedError
+
+    def delete(self, recording_id: str) -> bool:
+        """Not supported -- gradients cannot be individually deleted from the aggregate."""
+        raise NotImplementedError(
+            "Federated gradients are aggregated and cannot be individually deleted"
+        )
+
+    def list_uploads(self) -> list[UploadRecord]:
+        """Not supported for federated learning."""
+        raise NotImplementedError("Federated gradient uploads cannot be listed")
+
+    def verify_credentials(self) -> bool:
+        """Verify connection to the Flower aggregation server.
+
+        Returns:
+            True if the server is reachable.
+        """
+        # TODO: HTTP health check to server_url
+        raise NotImplementedError
+
+    def estimate_cost(self, size_bytes: int) -> float | None:
+        """Federated learning has no per-upload cost for participants.
+
+        Args:
+            size_bytes: Ignored (gradients are ~1-10 MB regardless of data size).
+
+        Returns:
+            Always 0.0 for participants.
+        """
+        return 0.0

engine/backends/huggingface.py

@@ -0,0 +1,160 @@
+"""HuggingFace Hub storage backend -- uploads recordings as dataset shards.
+
+Uploads capture archives to a HuggingFace dataset repository using the
+huggingface_hub Python library. Recordings are stored as dataset shards
+in a community dataset repo (e.g., OpenAdaptAI/desktop-recordings).
+
+Features:
+    - Versioned via Git LFS
+    - Built-in dataset viewer lets community browse without downloading
+    - Supports both public and private (paid HF tier) datasets
+
+Requires: huggingface_hub (installed via community or full extras)
+
+See design doc Section 7.7 for implementation details.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from engine.backends.protocol import UploadRecord, UploadResult
+
+
+class HuggingFaceBackend:
+    """HuggingFace Hub storage backend.
+
+    Args:
+        repo: HuggingFace dataset repository (e.g., "OpenAdaptAI/desktop-recordings").
+        token: HuggingFace API token.
+        private: Whether to create a private dataset (requires paid HF tier).
+    """
+
+    name: str = "huggingface"
+    supports_delete: bool = True
+    supports_list: bool = True
+
+    def __init__(
+        self,
+        repo: str = "OpenAdaptAI/desktop-recordings",
+        token: str = "",
+        private: bool = False,
+    ) -> None:
+        self.repo = repo
+        self.token = token
+        self.private = private
+
+    def upload(self, archive_path: Path, metadata: dict) -> UploadResult:
+        """Upload a capture archive to HuggingFace Hub.
+
+        Args:
+            archive_path: Path to the archive file.
+            metadata: Capture metadata.
+
+        Returns:
+            UploadResult with the HF Hub URL.
+        """
+        try:
+            from huggingface_hub import HfApi
+
+            api = HfApi(token=self.token)
+            capture_id = metadata.get("capture_id", "unknown")
+            path_in_repo = f"captures/{capture_id}/{archive_path.name}"
+
+            api.upload_file(
+                path_or_fileobj=str(archive_path),
+                path_in_repo=path_in_repo,
+                repo_id=self.repo,
+                repo_type="dataset",
+            )
+
+            url = f"https://huggingface.co/datasets/{self.repo}/blob/main/{path_in_repo}"
+            return UploadResult(
+                success=True,
+                remote_url=url,
+                bytes_sent=archive_path.stat().st_size,
+            )
+        except ImportError:
+            return UploadResult(success=False, error="huggingface_hub not installed")
+        except Exception as e:
+            return UploadResult(success=False, error=str(e))
+
+    def delete(self, recording_id: str) -> bool:
+        """Delete a recording from HuggingFace Hub.
+
+        Args:
+            recording_id: The capture session ID.
+
+        Returns:
+            True if deletion succeeded.
+        """
+        try:
+            from huggingface_hub import HfApi
+
+            api = HfApi(token=self.token)
+            api.delete_folder(
+                path_in_repo=f"captures/{recording_id}",
+                repo_id=self.repo,
+                repo_type="dataset",
+            )
+            return True
+        except Exception:
+            return False
+
+    def list_uploads(self) -> list[UploadRecord]:
+        """List all uploads in the HuggingFace dataset repo.
+
+        Returns:
+            List of UploadRecord objects.
+        """
+        try:
+            from huggingface_hub import HfApi
+
+            api = HfApi(token=self.token)
+            files = api.list_repo_files(repo_id=self.repo, repo_type="dataset")
+            records = []
+            for f in files:
+                if f.startswith("captures/"):
+                    parts = f.split("/")
+                    recording_id = parts[1] if len(parts) > 1 else "unknown"
+                    records.append(UploadRecord(
+                        recording_id=recording_id,
+                        backend="huggingface",
+                        remote_url=f"https://huggingface.co/datasets/{self.repo}/blob/main/{f}",
+                        uploaded_at="",
+                        size_bytes=0,
+                    ))
+            return records
+        except Exception:
+            return []
+
+    def verify_credentials(self) -> bool:
+        """Verify HuggingFace token by calling the whoami endpoint.
+
+        Returns:
+            True if the token is valid.
+        """
+        try:
+            from huggingface_hub import HfApi
+
+            api = HfApi(token=self.token)
+            api.whoami()
+            return True
+        except Exception:
+            return False
+
+    def estimate_cost(self, size_bytes: int) -> float | None:
+        """Estimate cost for HuggingFace Hub storage.
+
+        Public datasets on HF Hub are free (unlimited storage).
+        Private datasets require a paid HF tier.
+
+        Args:
+            size_bytes: Size of the data in bytes.
+
+        Returns:
+            0.0 for public datasets, None for private (varies by tier).
+        """
+        if not self.private:
+            return 0.0
+        return None

engine/backends/protocol.py

@@ -0,0 +1,134 @@
+"""StorageBackend protocol -- interface that all storage backends implement.
+
+Every storage destination implements this protocol. The upload manager
+dispatches uploads to backends through this uniform interface.
+
+All backends share the same upload pipeline:
+    [User approves in review UI] -> Compress (tar.zst) -> Queue -> Upload Worker
+                                                          |
+                                                    Backend-specific:
+                                                    - S3: multipart upload
+                                                    - HF Hub: git lfs push
+                                                    - R2: S3-compatible multipart
+                                                    - Wormhole: P2P direct
+
+See design doc Section 7.3 for the full protocol specification.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class UploadResult:
+    """Result of an upload operation.
+
+    Attributes:
+        success: Whether the upload succeeded.
+        remote_url: URL or URI of the uploaded resource (if applicable).
+        bytes_sent: Total bytes sent.
+        error: Error message if the upload failed.
+        metadata: Additional backend-specific metadata.
+    """
+
+    success: bool
+    remote_url: str = ""
+    bytes_sent: int = 0
+    error: str = ""
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class UploadRecord:
+    """Record of a past upload, for listing/auditing.
+
+    Attributes:
+        recording_id: The capture session ID that was uploaded.
+        backend: Name of the storage backend used.
+        remote_url: URL or URI of the uploaded resource.
+        uploaded_at: ISO 8601 timestamp of the upload.
+        size_bytes: Size of the uploaded archive.
+    """
+
+    recording_id: str
+    backend: str
+    remote_url: str
+    uploaded_at: str
+    size_bytes: int
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    """Protocol that every storage backend must implement.
+
+    Backends provide upload, optional delete, optional list, credential
+    verification, and cost estimation.
+
+    Attributes:
+        name: Human-readable backend name (e.g., "s3", "huggingface").
+        supports_delete: Whether uploaded resources can be deleted.
+        supports_list: Whether uploaded resources can be listed.
+    """
+
+    name: str
+    supports_delete: bool
+    supports_list: bool
+
+    def upload(self, archive_path: Path, metadata: dict) -> UploadResult:
+        """Upload a capture archive to the backend.
+
+        Args:
+            archive_path: Path to the tar.zst archive to upload.
+            metadata: Capture metadata (id, duration, event count, etc.).
+
+        Returns:
+            UploadResult with success status and remote URL.
+        """
+        ...
+
+    def delete(self, recording_id: str) -> bool:
+        """Delete a previously uploaded recording.
+
+        Args:
+            recording_id: The capture session ID to delete.
+
+        Returns:
+            True if deletion succeeded.
+
+        Raises:
+            NotImplementedError: If the backend does not support deletion.
+        """
+        ...
+
+    def list_uploads(self) -> list[UploadRecord]:
+        """List all uploads made through this backend.
+
+        Returns:
+            List of UploadRecord objects.
+
+        Raises:
+            NotImplementedError: If the backend does not support listing.
+        """
+        ...
+
+    def verify_credentials(self) -> bool:
+        """Verify that the backend credentials are valid.
+
+        Returns:
+            True if credentials are valid and the backend is reachable.
+        """
+        ...
+
+    def estimate_cost(self, size_bytes: int) -> float | None:
+        """Estimate the cost of uploading/storing the given amount of data.
+
+        Args:
+            size_bytes: Size of the data in bytes.
+
+        Returns:
+            Estimated cost in USD, or None if cost estimation is not available.
+        """
+        ...