enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@enigma/sdk",
+  "version": "0.1.22",
+  "description": "Unified Sovereign AI Agent SDK for Persistent Memory, GhostMesh P2P, and Solana ZKCP",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "src/",
+    "index.d.ts",
+    "python/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./mesh": "./src/mesh-client.js",
+    "./market": {
+      "types": "./index.d.ts",
+      "import": "./src/market-client.js",
+      "default": "./src/market-client.js"
+    },
+    "./rag": "./src/rag-client.js"
+  },
+  "dependencies": {
+    "@enigma/core": "workspace:*",
+    "@enigma/mesh": "workspace:*",
+    "@enigma/rag": "workspace:*",
+    "@enigma/vault": "workspace:*"
+  }
+}

package/packages/sdk/python/README.md

@@ -0,0 +1,24 @@
+# Enigma Sovereign AI Agent SDK (Python)
+
+Native Python SDK for sovereign AI memory custody, AES-256-GCM vault encryption, and local vector retrieval.
+
+## Quickstart
+
+```python
+from enigma_sdk import EnigmaPythonSDK
+
+# 1. Connect
+enigma = EnigmaPythonSDK.connect(scope="agent.solana", storage_path="./agent_vault.enc.json", passphrase="my-secret-passphrase")
+
+# 2. Remember
+enigma.remember("Always enforce 0.5% max slippage on Jupiter DEX swaps")
+
+# 3. Recall
+memories = enigma.recall("Jupiter swap slippage rules", top_k=1)
+print(memories[0]["text"])
+```
+
+## Security
+
+- **Encryption at Rest**: AES-256-GCM authenticated encryption with 600,000-round PBKDF2-HMAC-SHA256 key derivation.
+- **Fail-Closed**: Requires explicit passphrase or 32-byte vault key when persistent storage is configured.

package/packages/sdk/python/enigma_sdk.py

@@ -0,0 +1,250 @@
+"""
+Enigma Sovereign AI Agent SDK for Python.
+Provides persistent memory custody, local vector search, and sovereign agent context.
+Uses AES-256-GCM encryption at rest with 600,000-round PBKDF2-HMAC-SHA256 key derivation
+or direct 32-byte master vault keys. Zero plaintext is stored on disk.
+"""
+import time
+import math
+import json
+import os
+import secrets
+import base64
+import hashlib
+from typing import List, Dict, Any, Optional
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+VAULT_AAD = b"enigma.python_vault.v1"
+PBKDF2_ROUNDS = 600000
+
+class EnigmaPythonSDK:
+    def __init__(
+        self,
+        scope: str = "enigma.global",
+        agent_id: Optional[str] = None,
+        storage_path: Optional[str] = None,
+        passphrase: Optional[str] = None,
+        vault_key: Optional[bytes] = None,
+        in_memory: bool = False,
+        api_base: str = "http://127.0.0.1:8787",
+        auth_token: Optional[str] = None
+    ):
+        self.scope = scope
+        self.agent_id = agent_id or f"py_agent_{int(time.time())}"
+        self.storage_path = os.path.abspath(storage_path) if storage_path and not in_memory else None
+        self.passphrase = passphrase
+        self.api_base = api_base.rstrip('/')
+        self.auth_token = auth_token
+        self._local_memories: Dict[str, Dict[str, Any]] = {}
+
+        if self.storage_path and not self.passphrase and not vault_key:
+            raise ValueError(
+                "Explicit passphrase or vault_key is required when persistent storage_path is configured."
+            )
+
+        if vault_key:
+            if not isinstance(vault_key, (bytes, bytearray)) or len(vault_key) != 32:
+                raise ValueError("vault_key must be exactly 32 bytes")
+            self.vault_key = bytes(vault_key)
+        elif self.passphrase:
+            self.vault_key = self._derive_key(self.passphrase, secrets.token_bytes(16))
+        else:
+            self.vault_key = secrets.token_bytes(32)
+
+        if self.storage_path and os.path.exists(self.storage_path):
+            self.load()
+
+    @staticmethod
+    def _derive_key(passphrase: str, salt: bytes) -> bytes:
+        return hashlib.pbkdf2_hmac("sha256", passphrase.encode("utf-8"), salt, PBKDF2_ROUNDS, dklen=32)
+
+    @classmethod
+    def connect(
+        cls,
+        scope: str = "enigma.global",
+        agent_id: Optional[str] = None,
+        storage_path: Optional[str] = None,
+        passphrase: Optional[str] = None,
+        vault_key: Optional[bytes] = None,
+        api_base: str = "http://127.0.0.1:8787",
+        auth_token: Optional[str] = None
+    ) -> 'EnigmaPythonSDK':
+        """3-Line Quickstart Factory for Python Agents."""
+        return cls(
+            scope=scope,
+            agent_id=agent_id,
+            storage_path=storage_path,
+            passphrase=passphrase,
+            vault_key=vault_key,
+            api_base=api_base,
+            auth_token=auth_token
+        )
+
+    def remember(
+        self,
+        text: str,
+        scope: Optional[str] = None,
+        importance: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Stores a persistent memory atom in the sovereign vault."""
+        if not text or not isinstance(text, str):
+            raise ValueError("Memory text must be a non-empty string")
+        
+        target_scope = scope or self.scope
+        atom_id = f"atom_{int(time.time() * 1000)}"
+        record = {
+            "id": atom_id,
+            "text": text,
+            "scope": target_scope,
+            "importance": importance,
+            "created_at": int(time.time() * 1000),
+            "metadata": metadata or {}
+        }
+        self._local_memories[atom_id] = record
+
+        if self.storage_path:
+            self.save()
+
+        return record
+
+    def recall(
+        self,
+        query: str,
+        top_k: int = 5,
+        scope: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """Retrieves top-k relevant memory atoms using lexical similarity."""
+        if not query or not isinstance(query, str):
+            return []
+        
+        target_scope = scope or self.scope
+        query_words = set(query.lower().split())
+        scored = []
+
+        for atom_id, doc in self._local_memories.items():
+            if target_scope and doc["scope"] != target_scope and doc["scope"] != "enigma.global":
+                continue
+            doc_words = set(doc["text"].lower().split())
+            intersection = query_words.intersection(doc_words)
+            sim = len(intersection) / max(1, math.sqrt(len(query_words) * len(doc_words)))
+            score = sim * doc.get("importance", 1.0)
+            if score > 0:
+                scored.append({
+                    "id": atom_id,
+                    "text": doc["text"],
+                    "score": round(score, 4),
+                    "scope": doc["scope"],
+                    "created_at": doc["created_at"]
+                })
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        return scored[:top_k]
+
+    def save(self, target_path: Optional[str] = None) -> None:
+        """Persists memory store to disk encrypted with AES-256-GCM."""
+        dest = os.path.abspath(target_path) if target_path else self.storage_path
+        if not dest:
+            raise ValueError("No storage_path configured for persistence")
+
+        kdf_meta = None
+        if self.passphrase:
+            salt = secrets.token_bytes(16)
+            active_key = self._derive_key(self.passphrase, salt)
+            self.vault_key = active_key
+            kdf_meta = {
+                "algorithm": "pbkdf2",
+                "iterations": PBKDF2_ROUNDS,
+                "hash": "sha256",
+                "salt": base64.b64encode(salt).decode("ascii")
+            }
+        else:
+            active_key = self.vault_key
+            kdf_meta = {
+                "algorithm": "direct_vault_key",
+            }
+
+        payload_raw = json.dumps({
+            "version": 1,
+            "format": "enigma.python_vault.v1",
+            "scope": self.scope,
+            "agent_id": self.agent_id,
+            "updated_at": int(time.time() * 1000),
+            "memories": list(self._local_memories.values())
+        }).encode("utf-8")
+
+        iv = secrets.token_bytes(12)
+        aesgcm = AESGCM(active_key)
+        ciphertext_with_tag = aesgcm.encrypt(iv, payload_raw, VAULT_AAD)
+        ciphertext = ciphertext_with_tag[:-16]
+        auth_tag = ciphertext_with_tag[-16:]
+
+        bundle = {
+            "version": 1,
+            "format": "enigma.python_vault.v1",
+            "kdf": kdf_meta,
+            "ciphertext": base64.b64encode(ciphertext).decode("ascii"),
+            "iv": iv.hex(),
+            "auth_tag": auth_tag.hex(),
+            "count": len(self._local_memories)
+        }
+
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        tmp_file = f"{dest}.tmp.{int(time.time() * 1000)}"
+        with open(tmp_file, "w", encoding="utf-8") as f:
+            json.dump(bundle, f, indent=2)
+        os.replace(tmp_file, dest)
+
+    def load(self, source_path: Optional[str] = None) -> None:
+        """Loads and decrypts memory store from disk. Fails closed on corruption/tampering."""
+        src = os.path.abspath(source_path) if source_path else self.storage_path
+        if not src or not os.path.exists(src):
+            raise FileNotFoundError(f"Storage path not found: {src}")
+        
+        with open(src, "r", encoding="utf-8") as f:
+            bundle = json.load(f)
+        
+        if bundle.get("format") != "enigma.python_vault.v1":
+            raise ValueError("Invalid Python vault bundle format")
+
+        kdf_meta = bundle.get("kdf", {})
+        if kdf_meta.get("algorithm") == "pbkdf2":
+            if not self.passphrase:
+                raise ValueError("Vault bundle requires passphrase to decrypt")
+            salt = base64.b64decode(kdf_meta.get("salt", ""))
+            if len(salt) < 16:
+                raise ValueError("Invalid or missing KDF salt in vault bundle")
+            active_key = self._derive_key(self.passphrase, salt)
+            self.vault_key = active_key
+        else:
+            active_key = self.vault_key
+
+        iv = bytes.fromhex(bundle["iv"])
+        auth_tag = bytes.fromhex(bundle["auth_tag"])
+        ciphertext = base64.b64decode(bundle["ciphertext"])
+        ciphertext_with_tag = ciphertext + auth_tag
+
+        aesgcm = AESGCM(active_key)
+        try:
+            decrypted_bytes = aesgcm.decrypt(iv, ciphertext_with_tag, VAULT_AAD)
+        except Exception as e:
+            raise ValueError(f"Decryption failed: invalid passphrase/key or corrupted vault bundle ({e})")
+
+        data = json.loads(decrypted_bytes.decode("utf-8"))
+        self._local_memories.clear()
+        for mem in data.get("memories", []):
+            self._local_memories[mem["id"]] = mem
+
+    def status(self) -> Dict[str, Any]:
+        """Returns local agent status."""
+        return {
+            "ok": True,
+            "agent_id": self.agent_id,
+            "scope": self.scope,
+            "memory_count": len(self._local_memories),
+            "storage_path": self.storage_path,
+            "api_base": self.api_base
+        }
+
+# Top-level canonical class alias
+Enigma = EnigmaPythonSDK

package/packages/sdk/python/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "enigma-memory"
+version = "0.1.22"
+description = "Enigma Sovereign AI Agent SDK for persistent memory custody, local vector search, and sovereign agent context"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Enigma Memory", email = "team@enigmamemory.com" }
+]
+keywords = ["ai-memory", "sovereign-ai", "rag", "vector-search", "solana", "zk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security :: Cryptography"
+]
+dependencies = [
+    "cryptography>=41.0.0"
+]
+
+[project.urls]
+Homepage = "https://enigmamemory.com"
+Repository = "https://github.com/Enigma-Memory/enigma-cortex-enterprise"

package/packages/sdk/python/requirements.txt

@@ -0,0 +1 @@
+cryptography>=41.0.0

package/packages/sdk/python/setup.py

@@ -0,0 +1,20 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="enigma-memory",
+    version="0.1.22",
+    py_modules=["enigma_sdk"],
+    install_requires=[
+        "cryptography>=41.0.0",
+    ],
+    author="Enigma Memory",
+    author_email="team@enigmamemory.com",
+    description="Enigma Sovereign AI Agent SDK for persistent memory custody, local vector search, and sovereign agent context",
+    license="Apache-2.0",
+    keywords="ai-memory sovereign-ai rag vector-search solana zk",
+    url="https://enigmamemory.com",
+    classifiers=[
+        "License :: OSI Approved :: Apache Software License",
+        "Programming Language :: Python :: 3",
+    ],
+)