apical 0.2.0__py3-none-any.whl

apical/__init__.py

@@ -0,0 +1,88 @@
+"""Apical Labs — Zero-Retention Continual Memory & Embedding Router.
+
+Client SDK providing:
+- ApicalClient: Main client connection pool
+- Classifier: Continual classification with instant GDPR Art. 17 unlearning
+- MemoryRouter: Real-time dynamic embedding routing and reinforcement
+- OrthogonalPrivacyProjector: Client-side mathematical input de-identification
+- verify_zero_retention_receipt: Offline Ed25519 receipt verification
+"""
+
+from __future__ import annotations
+
+from apical.classifier import (
+    Classifier,
+    LearnResult,
+    PredictionResult,
+    UnlearnResult,
+)
+from apical.client import ApicalClient, ArborNamespace, BridgeResult
+
+# Backward-compatible convenience alias
+Client = ApicalClient
+from apical.exceptions import (
+    APIError,
+    ApicalError,
+    AuthenticationError,
+    FixedByteInvariantError,
+    ModelNotFoundError,
+    ProductNotEntitledError,
+    RateLimitError,
+    SparseProbeError,
+    SweepDetectedError,
+    VerificationError,
+)
+from apical.orthogonal import OrthogonalPrivacyProjector
+from apical.plexus import (
+    PlexusClassifier,
+    PlexusLearnResult,
+    PlexusNetwork,
+    PlexusPredictionResult,
+    PlexusRouteResult,
+    PlexusRouter,
+    PlexusUnlearnResult,
+)
+from apical.router import (
+    MemoryRouter,
+    ReinforceResult,
+    RouteItem,
+    RouteResult,
+)
+from apical.verifier import verify_zero_retention_receipt
+
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "APIError",
+    "ApicalClient",
+    "ApicalError",
+    "ArborNamespace",
+    "AuthenticationError",
+    "BridgeResult",
+    "Classifier",
+    "Client",
+    "FixedByteInvariantError",
+    "LearnResult",
+    "MemoryRouter",
+    "ModelNotFoundError",
+    "OrthogonalPrivacyProjector",
+    "PlexusClassifier",
+    "PlexusLearnResult",
+    "PlexusNetwork",
+    "PlexusPredictionResult",
+    "PlexusRouteResult",
+    "PlexusRouter",
+    "PlexusUnlearnResult",
+    "PredictionResult",
+    "ProductNotEntitledError",
+    "RateLimitError",
+    "ReinforceResult",
+    "RouteItem",
+    "RouteResult",
+    "SparseProbeError",
+    "SweepDetectedError",
+    "UnlearnResult",
+    "VerificationError",
+    "verify_zero_retention_receipt",
+]

apical/classifier.py

@@ -0,0 +1,205 @@
+"""Classifier Surface for the Apical Labs Platform."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, NamedTuple, Optional, Sequence, Union
+import numpy as np
+
+from apical.orthogonal import OrthogonalPrivacyProjector
+from apical.verifier import verify_zero_retention_receipt
+
+
+class PredictionResult(NamedTuple):
+    """Result of a classifier inference pass."""
+    prediction: int
+    confidence: float
+    receipt: Dict[str, Any]
+    crystallization_pct: Optional[float] = None
+    mean_plasticity: Optional[float] = None
+
+    @property
+    def signature(self) -> str:
+        """Return the Ed25519 signature from the cryptographic attestation receipt."""
+        return str(self.receipt.get("ed25519_signature", ""))
+
+
+class LearnResult(NamedTuple):
+    """Result of a single continual update."""
+    status: str
+    target_class: int
+    winner_class: int
+    confidence: float
+    update_count: int
+    persisted_bytes_delta: int
+    receipt: Dict[str, Any]
+
+    @property
+    def signature(self) -> str:
+        """Return the Ed25519 signature from the cryptographic attestation receipt."""
+        return str(self.receipt.get("ed25519_signature", ""))
+
+
+class UnlearnResult(NamedTuple):
+    """Result of an instant GDPR Article 17 class erasure."""
+    status: str
+    erased_class_id: int
+    persisted_bytes_delta: int
+    receipt: Dict[str, Any]
+
+    @property
+    def signature(self) -> str:
+        """Return the Ed25519 signature from the cryptographic attestation receipt."""
+        return str(self.receipt.get("ed25519_signature", ""))
+
+
+class Classifier:
+    """Client interface for continuous classification models."""
+
+    def __init__(
+        self,
+        client: Any,
+        model_id: str,
+        in_features: Optional[int] = None,
+        num_classes: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> None:
+        self.client = client
+        self.model_id = model_id
+        self.in_features = in_features
+        self.num_classes = num_classes
+        self.privacy_secret = privacy_secret
+
+        self._projector: Optional[OrthogonalPrivacyProjector] = None
+        if self.privacy_secret and self.in_features:
+            self._projector = OrthogonalPrivacyProjector(self.privacy_secret, self.in_features)
+
+    def _prepare_vector(self, vector: Union[Sequence[float], np.ndarray]) -> list[float]:
+        """Optionally apply orthogonal privacy projection, returning a JSON-serializable list."""
+        arr = np.asarray(vector, dtype=np.float32).ravel()
+
+        if self._projector is not None:
+            arr = self._projector.project(arr)
+        elif self.privacy_secret and not self._projector:
+            # Lazy initialize projector once vector dimension is known
+            self.in_features = arr.size
+            self._projector = OrthogonalPrivacyProjector(self.privacy_secret, self.in_features)
+            arr = self._projector.project(arr)
+
+        return arr.tolist()
+
+    def create(self, in_features: int, num_classes: int) -> Dict[str, Any]:
+        """Create and initialize a new fixed-byte model container on Apical Cloud."""
+        self.in_features = in_features
+        self.num_classes = num_classes
+
+        if self.privacy_secret and not self._projector:
+            self._projector = OrthogonalPrivacyProjector(self.privacy_secret, self.in_features)
+
+        payload = {
+            "model_id": self.model_id,
+            "in_features": in_features,
+            "out_features": num_classes,
+        }
+        resp = self.client.request("POST", f"/api/v1/models", payload)
+        data = resp.get("data", resp)
+
+        if "receipt" in data:
+            verify_zero_retention_receipt(data["receipt"])
+
+        return data
+
+    def predict(
+        self,
+        vector: Union[Sequence[float], np.ndarray],
+        tier: int = 0,
+        verify_receipt: bool = True,
+    ) -> PredictionResult:
+        """Execute directional classification, returning class prediction and signed receipt."""
+        prep_vec = self._prepare_vector(vector)
+        payload = {
+            "model_id": self.model_id,
+            "vector": prep_vec,
+            "tier": tier,
+        }
+        resp = self.client.request("POST", f"/api/v1/predict", payload)
+        data = resp.get("data", resp)
+
+        receipt = data.get("receipt", {})
+        if verify_receipt and receipt:
+            verify_zero_retention_receipt(receipt)
+
+        return PredictionResult(
+            prediction=int(data["prediction"]),
+            confidence=float(data["confidence"]),
+            receipt=receipt,
+            crystallization_pct=data.get("crystallization_pct"),
+            mean_plasticity=data.get("mean_plasticity"),
+        )
+
+    def learn(
+        self,
+        vector: Union[Sequence[float], np.ndarray],
+        target_class: int,
+        tier: int = 0,
+        verify_receipt: bool = True,
+    ) -> LearnResult:
+        """Stream a single continual update, updating model state under zero retention."""
+        prep_vec = self._prepare_vector(vector)
+        payload = {
+            "model_id": self.model_id,
+            "vector": prep_vec,
+            "target_class": target_class,
+            "tier": tier,
+        }
+        resp = self.client.request("POST", f"/api/v1/learn", payload)
+        data = resp.get("data", resp)
+
+        receipt = data.get("receipt", {})
+        if verify_receipt and receipt:
+            verify_zero_retention_receipt(receipt)
+
+        return LearnResult(
+            status=str(data.get("status", "updated")),
+            target_class=int(data["target_class"]),
+            winner_class=int(data["winner_class"]),
+            confidence=float(data["confidence"]),
+            update_count=int(data.get("update_count", 0)),
+            persisted_bytes_delta=int(data.get("persisted_bytes_delta", 0)),
+            receipt=receipt,
+        )
+
+    def unlearn(
+        self,
+        class_id: int,
+        verify_receipt: bool = True,
+    ) -> UnlearnResult:
+        """Execute instant GDPR Article 17 Machine Unlearning for a specific class coordinate."""
+        payload = {
+            "model_id": self.model_id,
+            "class_id": class_id,
+        }
+        resp = self.client.request("POST", f"/api/v1/unlearn", payload)
+        data = resp.get("data", resp)
+
+        receipt = data.get("receipt", {})
+        if verify_receipt and receipt:
+            verify_zero_retention_receipt(receipt)
+
+        return UnlearnResult(
+            status=str(data.get("status", "erased")),
+            erased_class_id=int(data.get("erased_class_id", class_id)),
+            persisted_bytes_delta=int(data.get("persisted_bytes_delta", 0)),
+            receipt=receipt,
+        )
+
+    def erase_class(
+        self,
+        target_class: Optional[int] = None,
+        class_id: Optional[int] = None,
+        verify_receipt: bool = True,
+    ) -> UnlearnResult:
+        """Execute instant GDPR Article 17 Machine Unlearning for a specific class coordinate (alias for unlearn)."""
+        target = target_class if target_class is not None else class_id
+        if target is None:
+            raise ValueError("Either target_class or class_id must be provided")
+        return self.unlearn(class_id=target, verify_receipt=verify_receipt)

apical/client.py

@@ -0,0 +1,371 @@
+"""Base HTTP Client for the Apical Labs Platform."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, NamedTuple, Optional, Sequence, Union
+import httpx
+
+from apical.exceptions import (
+    APIError,
+    ApicalError,
+    AuthenticationError,
+    ModelNotFoundError,
+    ProductNotEntitledError,
+    RateLimitError,
+    SparseProbeError,
+    SweepDetectedError,
+)
+
+
+DEFAULT_BASE_URL = "https://api.apical-labs.com"
+DEFAULT_TIMEOUT_SECONDS = 10.0
+DEFAULT_MAX_RETRIES = 3
+SDK_VERSION = "0.2.0"
+
+
+class BridgeResult(NamedTuple):
+    """Result of an arbor.Bridge cross-backbone migration."""
+    status: str
+    model_id: str
+    alignment_score: float
+    persisted_bytes_delta: int
+    update_count: int
+    receipt: Dict[str, Any]
+    latency_ms: float = 0.0
+
+    @property
+    def signature(self) -> str:
+        """Return the Ed25519 signature from the cryptographic attestation receipt."""
+        return str(self.receipt.get("ed25519_signature", ""))
+
+
+class ArborNamespace:
+    """Namespace for Arbor (SCPP v1) components matching the landing page and developer ergonomics."""
+
+    def __init__(self, client: "ApicalClient") -> None:
+        self._client = client
+
+    def create_model(
+        self,
+        model_id: str,
+        in_features: Optional[int] = None,
+        out_features: Optional[int] = None,
+        input_dim: Optional[int] = None,
+        num_classes: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> Any:
+        return self._client.create_model(
+            model_id=model_id,
+            in_features=in_features,
+            out_features=out_features,
+            input_dim=input_dim,
+            num_classes=num_classes,
+            privacy_secret=privacy_secret,
+        )
+
+    def classifier(
+        self,
+        model_id: str,
+        in_features: Optional[int] = None,
+        num_classes: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> Any:
+        return self._client.classifier(
+            model_id=model_id,
+            in_features=in_features,
+            num_classes=num_classes,
+            privacy_secret=privacy_secret,
+        )
+
+    def memory_router(
+        self,
+        router_id: str,
+        embedding_dim: Optional[int] = None,
+        num_rules: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> Any:
+        return self._client.memory_router(
+            router_id=router_id,
+            embedding_dim=embedding_dim,
+            num_rules=num_rules,
+            privacy_secret=privacy_secret,
+        )
+
+    def bridge(
+        self,
+        model_id: str,
+        source_anchors: Optional[Any] = None,
+        target_anchors: Optional[Any] = None,
+        public_anchors: Optional[Any] = None,
+        tier: int = 0,
+        verify_receipt: bool = True,
+    ) -> BridgeResult:
+        return self._client.bridge(
+            model_id=model_id,
+            source_anchors=source_anchors,
+            target_anchors=target_anchors,
+            public_anchors=public_anchors,
+            tier=tier,
+            verify_receipt=verify_receipt,
+        )
+
+
+class ApicalClient:
+    """Primary client for interacting with the Apical Labs API Gateway.
+
+    Manages HTTP/2 connection pooling, API key authentication, and retry policies.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        privacy_secret: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key cannot be empty")
+
+        self.api_key = api_key
+        self.privacy_secret = privacy_secret
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Client-Version": SDK_VERSION,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=self.timeout,
+            transport=transport,
+        )
+
+    @property
+    def arbor(self) -> ArborNamespace:
+        """Access the Arbor (SCPP v1) namespace (classifier, memory_router, bridge)."""
+        return ArborNamespace(self)
+
+    def create_model(
+        self,
+        model_id: str,
+        in_features: Optional[int] = None,
+        out_features: Optional[int] = None,
+        input_dim: Optional[int] = None,
+        num_classes: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> Any:
+        """Create and initialize a fixed-byte model container on the Enclave, returning a Classifier."""
+        in_dim = in_features or input_dim
+        out_dim = out_features or num_classes
+        if in_dim is None or out_dim is None:
+            raise ValueError("Both input dimensions and output classes must be specified to create a model container.")
+
+        payload = {
+            "model_id": model_id,
+            "in_features": in_dim,
+            "out_features": out_dim,
+        }
+        self.request("POST", "/api/v1/models", payload)
+
+        return self.classifier(
+            model_id=model_id,
+            in_features=in_dim,
+            num_classes=out_dim,
+            privacy_secret=privacy_secret,
+        )
+
+    def classifier(
+        self,
+        model_id: str,
+        in_features: Optional[int] = None,
+        num_classes: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> "Classifier":
+        """Return a Classifier wrapper for classification and continuous learning."""
+        from apical.classifier import Classifier
+
+        secret = privacy_secret or self.privacy_secret
+        return Classifier(
+            client=self,
+            model_id=model_id,
+            in_features=in_features,
+            num_classes=num_classes,
+            privacy_secret=secret,
+        )
+
+    def memory_router(
+        self,
+        router_id: str,
+        embedding_dim: Optional[int] = None,
+        num_rules: Optional[int] = None,
+        privacy_secret: Optional[str] = None,
+    ) -> "MemoryRouter":
+        """Return a MemoryRouter wrapper for embedding routing and reinforcement."""
+        from apical.router import MemoryRouter
+
+        secret = privacy_secret or self.privacy_secret
+        return MemoryRouter(
+            client=self,
+            router_id=router_id,
+            embedding_dim=embedding_dim,
+            num_rules=num_rules,
+            privacy_secret=secret,
+        )
+
+    def plexus(
+        self,
+        model_id: str,
+        in_features: Optional[int] = None,
+        hidden_dim: int = 2048,
+        out_features: Optional[int] = None,
+        assembly_k: int = 64,
+        privacy_secret: Optional[str] = None,
+    ) -> "PlexusNetwork":
+        """Return a PlexusNetwork wrapper for SCPP v2 multi-layer continual learning and routing."""
+        from apical.plexus import PlexusNetwork
+
+        secret = privacy_secret or self.privacy_secret
+        return PlexusNetwork(
+            client=self,
+            model_id=model_id,
+            in_features=in_features,
+            hidden_dim=hidden_dim,
+            out_features=out_features,
+            assembly_k=assembly_k,
+            privacy_secret=secret,
+        )
+
+    def bridge(
+        self,
+        model_id: str,
+        source_anchors: Optional[Any] = None,
+        target_anchors: Optional[Any] = None,
+        public_anchors: Optional[Any] = None,
+        tier: int = 0,
+        verify_receipt: bool = True,
+    ) -> BridgeResult:
+        """Execute cross-backbone model migration via Orthogonal Procrustes alignment."""
+        from apical.verifier import verify_zero_retention_receipt
+
+        # Unpack public_anchors if provided as dict or tuple
+        if public_anchors is not None:
+            if isinstance(public_anchors, dict):
+                source_anchors = public_anchors.get("source") or public_anchors.get("source_anchors")
+                target_anchors = public_anchors.get("target") or public_anchors.get("target_anchors")
+            elif isinstance(public_anchors, (list, tuple)) and len(public_anchors) == 2:
+                source_anchors, target_anchors = public_anchors[0], public_anchors[1]
+
+        if source_anchors is None or target_anchors is None:
+            raise ValueError("Both source_anchors and target_anchors must be provided (or public_anchors)")
+
+        def _to_list_matrix(m: Any) -> list[list[float]]:
+            if hasattr(m, "tolist"):
+                return m.tolist()
+            if isinstance(m, (list, tuple)):
+                return [list(row) if hasattr(row, "__iter__") else [float(row)] for row in m]
+            return list(m)
+
+        src_list = _to_list_matrix(source_anchors)
+        tgt_list = _to_list_matrix(target_anchors)
+
+        payload = {
+            "model_id": model_id,
+            "source_anchors": src_list,
+            "target_anchors": tgt_list,
+            "tier": tier,
+        }
+
+        resp = self.request("POST", "/api/v1/bridge", payload)
+        data = resp.get("data", resp)
+
+        receipt = data.get("receipt", {})
+        if verify_receipt and receipt:
+            verify_zero_retention_receipt(receipt)
+
+        return BridgeResult(
+            status=str(data.get("status", "bridged")),
+            model_id=str(data.get("model_id", model_id)),
+            alignment_score=float(data.get("alignment_score", 1.0)),
+            persisted_bytes_delta=int(data.get("persisted_bytes_delta", 0)),
+            update_count=int(data.get("update_count", 0)),
+            receipt=receipt,
+            latency_ms=float(data.get("latency_ms", 0.0)),
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Execute an HTTP request with automatic retry on transient network failures."""
+        clean_path = "/" + path.lstrip("/")
+        retries = 0
+
+        while True:
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=clean_path,
+                    json=json_body,
+                )
+
+                if response.status_code == 200 or response.status_code == 201:
+                    return response.json()
+
+                self._handle_error_response(response)
+
+            except (httpx.ConnectError, httpx.TimeoutException) as e:
+                retries += 1
+                if retries >= self.max_retries:
+                    raise APIError(
+                        f"Network connection failed after {retries} retries: {e}",
+                        status_code=None,
+                        error_code="ERR_NETWORK_FAILURE",
+                    ) from e
+                time.sleep(0.1 * (2 ** retries))
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Parse structured API gateway errors and raise appropriate typed exceptions."""
+        try:
+            body = response.json()
+        except Exception:
+            body = {"error": response.text}
+
+        code = body.get("code", "")
+        message = body.get("error", response.text)
+        status = response.status_code
+
+        if status == 401:
+            raise AuthenticationError(message, status_code=status, error_code=code, details=body)
+        elif code == "ERR_PRODUCT_NOT_ENTITLED":
+            raise ProductNotEntitledError(message, status_code=status, error_code=code, details=body)
+        elif status == 404:
+            raise ModelNotFoundError(message, status_code=status, error_code=code, details=body)
+        elif status == 429:
+            raise RateLimitError(message, status_code=status, error_code=code, details=body)
+        elif code == "ERR_ORACLE_SPARSE_PROBE":
+            raise SparseProbeError(message, status_code=status, error_code=code, details=body)
+        elif code == "ERR_ORACLE_SWEEP_DETECTED":
+            raise SweepDetectedError(message, status_code=status, error_code=code, details=body)
+        else:
+            raise APIError(message, status_code=status, error_code=code, details=body)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> "ApicalClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()