apical 0.2.0__tar.gz

apical-0.2.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: apical
+Version: 0.2.0
+Summary: Apical Labs — Zero-Retention Continual Memory & Embedding Router
+Author-email: Apical Labs Ltd <research@apical-labs.com>
+License: Apache-2.0
+Project-URL: Homepage, https://apical-labs.com
+Project-URL: Documentation, https://docs.apical-labs.com
+Project-URL: Repository, https://github.com/apical-labs/apical-sdk
+Project-URL: Changelog, https://github.com/apical-labs/apical-sdk/releases
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+
+# `apical` — Python Client SDK for Apical Labs
+
+[![PyPI version](https://img.shields.io/pypi/v/apical.svg)](https://pypi.org/project/apical/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Official Python client for the **Apical Labs** Zero-Retention Continual Memory & Embedding Router platform.
+
+- **Zero Data Retention:** Every update operates in constant $O(1)$ memory (`persisted_bytes_delta == 0`). No replay buffers, no logs, and no historical samples.
+- **Client-Side Privacy Blindness:** Transform features via a customer-held orthogonal secret ($Q \in O(d)$) before they leave your servers.
+- **Cryptographic Receipts:** Every API request returns a tamper-evident `Ed25519` cryptographic receipt provable offline.
+- **Instant Machine Unlearning:** Purge any class coordinate back to quiescent hold in under $1\text{ ms}$ (GDPR / UK GDPR Article 17).
+
+---
+
+## Installation
+
+```bash
+pip install apical
+```
+
+Dependencies: `numpy>=1.24.0`, `httpx>=0.25.0`, `cryptography>=41.0.0`.
+*Requires ZERO PyTorch and ZERO local training frameworks.*
+
+---
+
+## Quickstart
+
+### 1. Continual Classifier with Instant Machine Unlearning
+
+```python
+from apical import ApicalClient
+
+# Initialize client (optionally pass privacy_secret for client-side orthogonal encryption)
+client = ApicalClient(
+    api_key="apk_test_...",
+    privacy_secret="my-super-secret-salt-key",
+)
+
+# Bind to model
+classifier = client.classifier("customer-intent-v1")
+
+# Create model on Apical Cloud (128-D input embedding, 10 classes)
+classifier.create(in_features=128, num_classes=10)
+
+# Online update (learn a new sample with zero data retention)
+embedding = [0.05] * 128
+learn_result = classifier.learn(embedding, target_class=2)
+print(f"Updated: status={learn_result.status}, delta_bytes={learn_result.persisted_bytes_delta}")
+
+# Predict class
+pred = classifier.predict(embedding)
+print(f"Predicted class {pred.prediction} with confidence {pred.confidence:.4f}")
+
+# Instant GDPR Article 17 Machine Unlearning (< 1 ms)
+unlearn_result = classifier.unlearn(class_id=2)
+print(f"Erased class 2: status={unlearn_result.status}, delta_bytes={unlearn_result.persisted_bytes_delta}")
+```
+
+---
+
+### 2. Real-Time Dynamic Memory Router
+
+```python
+from apical import ApicalClient
+
+client = ApicalClient(api_key="apk_test_...")
+router = client.memory_router("agent-tool-router")
+
+# Create router: 512-D embeddings, 32 rule destinations
+router.create(embedding_dim=512, num_rules=32)
+
+# Route incoming query embedding to top 3 matching tools/rules
+query_embedding = [0.12] * 512
+route_result = router.route(query_embedding, top_k=3)
+for r in route_result.routes:
+    print(f"Rule ID: {r.rule_id}, Affinity: {r.affinity}")
+
+# Reinforce a target rule based on positive execution outcome
+router.reinforce(query_embedding, target_rule=5)
+```
+
+---
+
+### 3. Offline Ed25519 Zero-Retention Receipt Verification
+
+Every response returns an `Ed25519` cryptographic receipt certifying:
+1. `persisted_bytes_delta == 0` (mathematical proof that no raw sample was appended)
+2. `input_buffer_zeroed == True` (transient RAM scrubber timestamp)
+3. Cryptographic signature over canonical JSON
+
+```python
+from apical import verify_zero_retention_receipt
+
+# Verify receipt offline without making any network requests
+is_valid = verify_zero_retention_receipt(pred.receipt)
+assert is_valid is True
+print("Zero-retention receipt cryptographically verified!")
+```
+
+---
+
+## License
+
+Apache-2.0. Copyright &copy; 2026 Apical Labs Ltd. All rights reserved.

apical-0.2.0/README.md

@@ -0,0 +1,104 @@
+# `apical` — Python Client SDK for Apical Labs
+
+[![PyPI version](https://img.shields.io/pypi/v/apical.svg)](https://pypi.org/project/apical/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Official Python client for the **Apical Labs** Zero-Retention Continual Memory & Embedding Router platform.
+
+- **Zero Data Retention:** Every update operates in constant $O(1)$ memory (`persisted_bytes_delta == 0`). No replay buffers, no logs, and no historical samples.
+- **Client-Side Privacy Blindness:** Transform features via a customer-held orthogonal secret ($Q \in O(d)$) before they leave your servers.
+- **Cryptographic Receipts:** Every API request returns a tamper-evident `Ed25519` cryptographic receipt provable offline.
+- **Instant Machine Unlearning:** Purge any class coordinate back to quiescent hold in under $1\text{ ms}$ (GDPR / UK GDPR Article 17).
+
+---
+
+## Installation
+
+```bash
+pip install apical
+```
+
+Dependencies: `numpy>=1.24.0`, `httpx>=0.25.0`, `cryptography>=41.0.0`.
+*Requires ZERO PyTorch and ZERO local training frameworks.*
+
+---
+
+## Quickstart
+
+### 1. Continual Classifier with Instant Machine Unlearning
+
+```python
+from apical import ApicalClient
+
+# Initialize client (optionally pass privacy_secret for client-side orthogonal encryption)
+client = ApicalClient(
+    api_key="apk_test_...",
+    privacy_secret="my-super-secret-salt-key",
+)
+
+# Bind to model
+classifier = client.classifier("customer-intent-v1")
+
+# Create model on Apical Cloud (128-D input embedding, 10 classes)
+classifier.create(in_features=128, num_classes=10)
+
+# Online update (learn a new sample with zero data retention)
+embedding = [0.05] * 128
+learn_result = classifier.learn(embedding, target_class=2)
+print(f"Updated: status={learn_result.status}, delta_bytes={learn_result.persisted_bytes_delta}")
+
+# Predict class
+pred = classifier.predict(embedding)
+print(f"Predicted class {pred.prediction} with confidence {pred.confidence:.4f}")
+
+# Instant GDPR Article 17 Machine Unlearning (< 1 ms)
+unlearn_result = classifier.unlearn(class_id=2)
+print(f"Erased class 2: status={unlearn_result.status}, delta_bytes={unlearn_result.persisted_bytes_delta}")
+```
+
+---
+
+### 2. Real-Time Dynamic Memory Router
+
+```python
+from apical import ApicalClient
+
+client = ApicalClient(api_key="apk_test_...")
+router = client.memory_router("agent-tool-router")
+
+# Create router: 512-D embeddings, 32 rule destinations
+router.create(embedding_dim=512, num_rules=32)
+
+# Route incoming query embedding to top 3 matching tools/rules
+query_embedding = [0.12] * 512
+route_result = router.route(query_embedding, top_k=3)
+for r in route_result.routes:
+    print(f"Rule ID: {r.rule_id}, Affinity: {r.affinity}")
+
+# Reinforce a target rule based on positive execution outcome
+router.reinforce(query_embedding, target_rule=5)
+```
+
+---
+
+### 3. Offline Ed25519 Zero-Retention Receipt Verification
+
+Every response returns an `Ed25519` cryptographic receipt certifying:
+1. `persisted_bytes_delta == 0` (mathematical proof that no raw sample was appended)
+2. `input_buffer_zeroed == True` (transient RAM scrubber timestamp)
+3. Cryptographic signature over canonical JSON
+
+```python
+from apical import verify_zero_retention_receipt
+
+# Verify receipt offline without making any network requests
+is_valid = verify_zero_retention_receipt(pred.receipt)
+assert is_valid is True
+print("Zero-retention receipt cryptographically verified!")
+```
+
+---
+
+## License
+
+Apache-2.0. Copyright &copy; 2026 Apical Labs Ltd. All rights reserved.

apical-0.2.0/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-0.2.0/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)