Metadata-Version: 2.4
Name: apical
Version: 0.5.3
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://apical-labs.com/docs
Project-URL: Repository, https://github.com/apicallabs/apical-sdk
Project-URL: Changelog, https://github.com/apicallabs/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
License-File: LICENSE
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"
Dynamic: license-file

# `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** platform, featuring **Apical Arbor** — the zero-retention continual memory and embedding router.

- **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).
- **Cross-Backbone Model Migration:** Rotate models across embedding revisions via `arbor.bridge` in zero downtime.

---

## 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",
)

# Create model on Apical Cloud (128-D input embedding, 10 classes)
classifier = client.arbor.create_model("customer-intent-v1", 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_...")

# Bind or instantiate router: 512-D embeddings, 32 rule destinations
router = client.arbor.memory_router("agent-tool-router", 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. Cross-Backbone Model Migration (`arbor.bridge`)

```python
# Rotate model across embedding backbones via Orthogonal Procrustes alignment
migration = client.arbor.bridge(
    "customer-intent-v1",
    public_anchors={
        "source": [[0.05] * 128 for _ in range(5)],
        "target": [[0.08] * 128 for _ in range(5)],
    },
)
print(f"Bridged: status={migration.status}, alignment={migration.alignment_score:.4f}")
```

---

### 4. 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!")
```

---

### 5. Universal MCP Server for Claude, Cursor & Google Antigravity

Run the built-in Model Context Protocol (MCP) server to equip your AI pair programming agents with sub-millisecond dynamic tool routing and online developer preference adaptation:

```bash
# Launch MCP Server (stdio)
apical-mcp

# Or view real-time zero-retention telemetry dashboard
apical-mcp --dashboard
```

#### Configuration for Claude Desktop & Cursor IDE
Add to `claude_desktop_config.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "plexus": {
      "command": "apical-mcp"
    }
  }
}
```

---

## License

Apache-2.0. Copyright &copy; 2026 Apical Labs Ltd. All rights reserved.
