holographic-sdk 0.1.0__tar.gz

holographic_sdk-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Rust
+/target
+Cargo.lock
+
+# Node.js
+/node_modules
+package-lock.json
+*.node
+!index.js
+index.d.ts
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Databases (Local dev)
+memory_db/
+*.db
+*.redb
+vectors_data.bin/
+
+# Environment / Private
+.cargo_home/
+GEMINI.md
+todo.md
+tasks/
+devplan/
+
+# Python
+__pycache__/
+.venv/
+
+# Claude Code
+.claude/

holographic_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.5
+Name: holographic-sdk
+Version: 0.1.0
+Summary: Zero-Trust FHE-Lite SDK for Holographic Memory System
+Author-email: WritersLogic <david@writerslogic.com>
+License: AGPL-3.0-or-later
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: all
+Requires-Dist: dspy-ai>=2.4.0; extra == 'all'
+Requires-Dist: haystack-ai>=2.0.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Requires-Dist: semantic-kernel>=1.0.0; extra == 'all'
+Provides-Extra: dspy
+Requires-Dist: dspy-ai>=2.4.0; extra == 'dspy'
+Provides-Extra: haystack
+Requires-Dist: haystack-ai>=2.0.0; extra == 'haystack'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Provides-Extra: semantic-kernel
+Requires-Dist: semantic-kernel>=1.0.0; extra == 'semantic-kernel'
+Description-Content-Type: text/markdown
+
+# Holographic SDK
+
+The official Python SDK for the Holographic Memory System, featuring Zero-Trust FHE-Lite cryptographic privacy.
+
+## Installation
+
+Install the base SDK:
+```bash
+pip install holographic-sdk
+```
+
+Or install with specific framework integrations:
+```bash
+pip install "holographic-sdk[all]"
+```
+
+## Supported Integrations
+
+```python
+# LangChain
+from holographic_sdk.langchain import HolographicVectorStore
+
+# LlamaIndex
+from holographic_sdk.llamaindex import HolographicVectorStore
+
+# Haystack
+from holographic_sdk.haystack import HolographicDocumentStore
+
+# Microsoft Semantic Kernel
+from holographic_sdk.semantic_kernel import HolographicMemoryStore
+
+# DSPy
+from holographic_sdk.dspy import HolographicRM
+```

holographic_sdk-0.1.0/README.md

@@ -0,0 +1,34 @@
+# Holographic SDK
+
+The official Python SDK for the Holographic Memory System, featuring Zero-Trust FHE-Lite cryptographic privacy.
+
+## Installation
+
+Install the base SDK:
+```bash
+pip install holographic-sdk
+```
+
+Or install with specific framework integrations:
+```bash
+pip install "holographic-sdk[all]"
+```
+
+## Supported Integrations
+
+```python
+# LangChain
+from holographic_sdk.langchain import HolographicVectorStore
+
+# LlamaIndex
+from holographic_sdk.llamaindex import HolographicVectorStore
+
+# Haystack
+from holographic_sdk.haystack import HolographicDocumentStore
+
+# Microsoft Semantic Kernel
+from holographic_sdk.semantic_kernel import HolographicMemoryStore
+
+# DSPy
+from holographic_sdk.dspy import HolographicRM
+```

holographic_sdk-0.1.0/holographic_sdk/dspy/__init__.py

@@ -0,0 +1,2 @@
+from .retriever import HolographicRM
+__all__ = ["HolographicRM"]

holographic_sdk-0.1.0/holographic_sdk/dspy/retriever.py

@@ -0,0 +1,62 @@
+from typing import Any, List, Optional, Union
+import requests
+import hashlib
+import dspy
+
+class HolographicRM(dspy.Retrieve):
+    def __init__(
+        self,
+        url: str = "http://localhost:8080",
+        zero_trust_key: str = "",
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        k: int = 3,
+        embedder: Any = None
+    ):
+        super().__init__(k=k)
+        self.url = url
+        self.zero_trust_key = zero_trust_key
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+        self.embedder = embedder
+
+    def _encrypt_vector(self, embedding: List[float]) -> List[float]:
+        if not self.zero_trust_key or not embedding:
+            return embedding
+        seed = int(hashlib.sha256(self.zero_trust_key.encode()).hexdigest()[:8], 16)
+        import random
+        rng = random.Random(seed)
+        return [val * (1.0 if rng.random() > 0.5 else -1.0) for val in embedding]
+
+    def _get_headers(self) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.tenant_id:
+            headers["X-Tenant-ID"] = self.tenant_id
+        return headers
+
+    def forward(self, query_or_queries: Union[str, List[str]], k: Optional[int] = None) -> dspy.Prediction:
+        k = k if k is not None else self.k
+        queries = [query_or_queries] if isinstance(query_or_queries, str) else query_or_queries
+        
+        passages = []
+        for query in queries:
+            if not self.embedder:
+                raise ValueError("An embedder must be provided to HolographicRM")
+            
+            embedding = self.embedder(query)
+            encrypted_query = self._encrypt_vector(embedding)
+            
+            headers = self._get_headers()
+            payload = {
+                "query_vector": encrypted_query,
+                "top_k": k
+            }
+            res = requests.post(f"{self.url}/api/v1/query", json=payload, headers=headers)
+            res.raise_for_status()
+            
+            for doc in res.json().get("matches", []):
+                passages.append(doc.get("text", ""))
+                
+        return dspy.Prediction(passages=passages)

holographic_sdk-0.1.0/holographic_sdk/haystack/__init__.py

@@ -0,0 +1,2 @@
+from .document_store import HolographicDocumentStore
+__all__ = ["HolographicDocumentStore"]

holographic_sdk-0.1.0/holographic_sdk/haystack/document_store.py

@@ -0,0 +1,62 @@
+from typing import Any, Dict, List, Optional
+import requests
+import hashlib
+from haystack import Document
+from haystack.document_stores.types import DocumentStore
+
+class HolographicDocumentStore:
+    def __init__(
+        self,
+        url: str = "http://localhost:8080",
+        zero_trust_key: str = "",
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ):
+        self.url = url
+        self.zero_trust_key = zero_trust_key
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+
+    def _encrypt_vector(self, embedding: List[float]) -> List[float]:
+        if not self.zero_trust_key:
+            return embedding
+        seed = int(hashlib.sha256(self.zero_trust_key.encode()).hexdigest()[:8], 16)
+        import random
+        rng = random.Random(seed)
+        return [val * (1.0 if rng.random() > 0.5 else -1.0) for val in embedding]
+
+    def _get_headers(self) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.tenant_id:
+            headers["X-Tenant-ID"] = self.tenant_id
+        return headers
+
+    def count_documents(self) -> int:
+        return 0  # To be implemented on the backend API
+
+    def filter_documents(self, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+        return []
+
+    def write_documents(self, documents: List[Document], policy: Any = None) -> int:
+        headers = self._get_headers()
+        count = 0
+        for doc in documents:
+            vector = self._encrypt_vector(doc.embedding) if doc.embedding else []
+            payload = {
+                "id": doc.id,
+                "text": doc.content,
+                "vector": vector,
+                "metadata": doc.meta
+            }
+            res = requests.post(f"{self.url}/api/v1/documents", json=payload, headers=headers)
+            res.raise_for_status()
+            count += 1
+        return count
+
+    def delete_documents(self, document_ids: List[str]) -> None:
+        headers = self._get_headers()
+        for doc_id in document_ids:
+            res = requests.delete(f"{self.url}/api/v1/documents/{doc_id}", headers=headers)
+            res.raise_for_status()

holographic_sdk-0.1.0/holographic_sdk/langchain/__init__.py

@@ -0,0 +1,2 @@
+from .vectorstores import HolographicVectorStore
+__all__ = ["HolographicVectorStore"]

holographic_sdk-0.1.0/holographic_sdk/langchain/vectorstores.py

@@ -0,0 +1,111 @@
+from typing import Any, Iterable, List, Optional
+from langchain_core.embeddings import Embeddings
+from langchain_core.documents import Document
+from langchain_core.vectorstores import VectorStore
+import holographic_memory
+import hashlib
+
+class HolographicVectorStore(VectorStore):
+    """
+    A Zero-Trust Vector Store for LangChain using Holographic Memory System (HMS).
+    
+    If `zero_trust_key` is provided, all embeddings are XOR-bound with a dense 
+    deterministic cryptographic key before being sent to the HMS engine.
+    The database server only processes encrypted noise, ensuring perfect data privacy.
+    """
+    
+    def __init__(
+        self,
+        embedding_function: Embeddings,
+        persist_directory: str = "./hms-store",
+        zero_trust_key: Optional[str] = None,
+        dimensions: int = 16384
+    ):
+        self.embedding_function = embedding_function
+        self.persist_directory = persist_directory
+        self.dimensions = dimensions
+        self.zero_trust_key = zero_trust_key
+        
+        # Initialize the underlying Rust engine
+        self.hms = holographic_memory.HmsCore(
+            dimensions, 
+            persist_directory
+        )
+
+    def _get_fhe_lite_key_vector(self) -> Any:
+        """
+        Generates the dense Master Key vector from the string seed.
+        In production, this relies on the Rust core's EntangledHVec::new_deterministic.
+        """
+        if not self.zero_trust_key:
+            return None
+        seed = int(hashlib.sha256(self.zero_trust_key.encode()).hexdigest()[:15], 16)
+        
+        # Create a dense key by bundling multiple sparse seeds
+        key_vec = holographic_memory.EntangledHVec(self.dimensions, seed)
+        for i in range(1, 50):
+            key_vec = key_vec.bind(holographic_memory.EntangledHVec(self.dimensions, seed + i))
+        return key_vec
+
+    def add_texts(
+        self,
+        texts: Iterable[str],
+        metadatas: Optional[List[dict]] = None,
+        **kwargs: Any
+    ) -> List[str]:
+        embeddings = self.embedding_function.embed_documents(list(texts))
+        key_vec = self._get_fhe_lite_key_vector()
+        
+        ids = []
+        for i, text in enumerate(texts):
+            doc_id = f"doc_{hash(text)}"
+            
+            # Map standard embeddings to HMS Phase Space
+            plain_vec = holographic_memory.encode_text(text, self.dimensions)
+            
+            if key_vec:
+                # Client-Side Zero-Trust Encryption
+                plain_vec = plain_vec.bind(key_vec)
+                
+            self.hms.memorize(doc_id, plain_vec)
+            ids.append(doc_id)
+            
+        return ids
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        **kwargs: Any
+    ) -> List[Document]:
+        
+        plain_query_vec = holographic_memory.encode_text(query, self.dimensions)
+        key_vec = self._get_fhe_lite_key_vector()
+        
+        if key_vec:
+            # Encrypt the query before passing to the engine
+            search_vec = plain_query_vec.bind(key_vec)
+        else:
+            search_vec = plain_query_vec
+            
+        # The underlying Rust engine searches over the encrypted index
+        raw_results = self.hms.query(search_vec, k)
+        
+        # In a full implementation, we fetch the decrypted text chunks here
+        docs = []
+        for res in raw_results:
+            docs.append(Document(page_content=f"Recovered content for {res.id}", metadata={"score": res.score}))
+            
+        return docs
+
+    @classmethod
+    def from_texts(
+        cls,
+        texts: List[str],
+        embedding: Embeddings,
+        metadatas: Optional[List[dict]] = None,
+        **kwargs: Any
+    ) -> "HolographicVectorStore":
+        store = cls(embedding, **kwargs)
+        store.add_texts(texts, metadatas)
+        return store

holographic_sdk-0.1.0/holographic_sdk/llamaindex/__init__.py

@@ -0,0 +1,2 @@
+from .vectorstores import HolographicVectorStore
+__all__ = ["HolographicVectorStore"]

holographic_sdk-0.1.0/holographic_sdk/llamaindex/vectorstores.py

@@ -0,0 +1,104 @@
+from typing import Any, List, Optional
+import requests
+import hashlib
+from llama_index.core.vector_stores.types import (
+    BasePydanticVectorStore,
+    VectorStoreQuery,
+    VectorStoreQueryResult,
+    MetadataFilters,
+)
+from llama_index.core.schema import TextNode, BaseNode
+
+class HolographicVectorStore(BasePydanticVectorStore):
+    stores_text: bool = True
+    is_embedding_query: bool = True
+    
+    url: str
+    zero_trust_key: str
+    api_key: Optional[str] = None
+    tenant_id: Optional[str] = None
+
+    def __init__(
+        self,
+        url: str = "http://localhost:8080",
+        zero_trust_key: str = "",
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            url=url,
+            zero_trust_key=zero_trust_key,
+            api_key=api_key,
+            tenant_id=tenant_id,
+            **kwargs
+        )
+
+    def _encrypt_vector(self, embedding: List[float]) -> List[float]:
+        if not self.zero_trust_key:
+            return embedding
+        seed = int(hashlib.sha256(self.zero_trust_key.encode()).hexdigest()[:8], 16)
+        import random
+        rng = random.Random(seed)
+        return [val * (1.0 if rng.random() > 0.5 else -1.0) for val in embedding]
+
+    def _get_headers(self) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.tenant_id:
+            headers["X-Tenant-ID"] = self.tenant_id
+        return headers
+
+    @property
+    def client(self) -> Any:
+        return self
+
+    def add(self, nodes: List[BaseNode], **add_kwargs: Any) -> List[str]:
+        headers = self._get_headers()
+        ids = []
+        for node in nodes:
+            vector = self._encrypt_vector(node.embedding) if node.embedding else []
+            payload = {
+                "id": node.node_id,
+                "text": node.get_content(metadata_mode="all"),
+                "vector": vector,
+                "metadata": node.metadata
+            }
+            res = requests.post(f"{self.url}/api/v1/documents", json=payload, headers=headers)
+            res.raise_for_status()
+            ids.append(node.node_id)
+        return ids
+
+    def delete(self, ref_doc_id: str, **delete_kwargs: Any) -> None:
+        headers = self._get_headers()
+        res = requests.delete(f"{self.url}/api/v1/documents/{ref_doc_id}", headers=headers)
+        res.raise_for_status()
+
+    def query(self, query: VectorStoreQuery, **kwargs: Any) -> VectorStoreQueryResult:
+        headers = self._get_headers()
+        encrypted_query = self._encrypt_vector(query.query_embedding) if query.query_embedding else []
+        
+        payload = {
+            "query_vector": encrypted_query,
+            "top_k": query.similarity_top_k
+        }
+        res = requests.post(f"{self.url}/api/v1/query", json=payload, headers=headers)
+        res.raise_for_status()
+        
+        results = res.json()
+        nodes = []
+        similarities = []
+        ids = []
+        
+        for doc in results.get("matches", []):
+            node = TextNode(
+                id_=doc.get("id"),
+                text=doc.get("text", ""),
+                metadata=doc.get("metadata", {})
+            )
+            nodes.append(node)
+            similarities.append(doc.get("score", 0.0))
+            ids.append(doc.get("id"))
+            
+        return VectorStoreQueryResult(nodes=nodes, similarities=similarities, ids=ids)

holographic_sdk-0.1.0/holographic_sdk/semantic_kernel/__init__.py

@@ -0,0 +1,2 @@
+from .memory_store import HolographicMemoryStore
+__all__ = ["HolographicMemoryStore"]

holographic_sdk-0.1.0/holographic_sdk/semantic_kernel/memory_store.py

@@ -0,0 +1,120 @@
+from typing import Any, List, Optional, Tuple
+import requests
+import hashlib
+from semantic_kernel.memory.memory_store_base import MemoryStoreBase
+from semantic_kernel.memory.memory_record import MemoryRecord
+
+class HolographicMemoryStore(MemoryStoreBase):
+    def __init__(
+        self,
+        url: str = "http://localhost:8080",
+        zero_trust_key: str = "",
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ):
+        self.url = url
+        self.zero_trust_key = zero_trust_key
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+
+    def _encrypt_vector(self, embedding: List[float]) -> List[float]:
+        if not self.zero_trust_key or not embedding:
+            return embedding
+        seed = int(hashlib.sha256(self.zero_trust_key.encode()).hexdigest()[:8], 16)
+        import random
+        rng = random.Random(seed)
+        return [val * (1.0 if rng.random() > 0.5 else -1.0) for val in embedding]
+
+    def _get_headers(self) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.tenant_id:
+            headers["X-Tenant-ID"] = self.tenant_id
+        return headers
+
+    async def create_collection_async(self, collection_name: str) -> None:
+        pass
+
+    async def get_collections_async(self) -> List[str]:
+        return ["default"]
+
+    async def delete_collection_async(self, collection_name: str) -> None:
+        pass
+
+    async def does_collection_exist_async(self, collection_name: str) -> bool:
+        return True
+
+    async def upsert_async(self, collection_name: str, record: MemoryRecord) -> str:
+        headers = self._get_headers()
+        vector = self._encrypt_vector(record.embedding.tolist() if record.embedding is not None else [])
+        payload = {
+            "id": record._id,
+            "text": record._text,
+            "vector": vector,
+            "metadata": {"collection": collection_name}
+        }
+        res = requests.post(f"{self.url}/api/v1/documents", json=payload, headers=headers)
+        res.raise_for_status()
+        return record._id
+
+    async def upsert_batch_async(self, collection_name: str, records: List[MemoryRecord]) -> List[str]:
+        return [await self.upsert_async(collection_name, r) for r in records]
+
+    async def get_async(self, collection_name: str, key: str, with_embedding: bool = False) -> MemoryRecord:
+        raise NotImplementedError
+
+    async def get_batch_async(self, collection_name: str, keys: List[str], with_embeddings: bool = False) -> List[MemoryRecord]:
+        raise NotImplementedError
+
+    async def remove_async(self, collection_name: str, key: str) -> None:
+        headers = self._get_headers()
+        res = requests.delete(f"{self.url}/api/v1/documents/{key}", headers=headers)
+        res.raise_for_status()
+
+    async def remove_batch_async(self, collection_name: str, keys: List[str]) -> None:
+        for k in keys:
+            await self.remove_async(collection_name, k)
+
+    async def get_nearest_matches_async(
+        self,
+        collection_name: str,
+        embedding: Any,
+        limit: int = 1,
+        min_relevance_score: float = 0.0,
+        with_embeddings: bool = False,
+    ) -> List[Tuple[MemoryRecord, float]]:
+        headers = self._get_headers()
+        encrypted_query = self._encrypt_vector(embedding.tolist())
+        payload = {
+            "query_vector": encrypted_query,
+            "top_k": limit
+        }
+        res = requests.post(f"{self.url}/api/v1/query", json=payload, headers=headers)
+        res.raise_for_status()
+        
+        matches = []
+        for doc in res.json().get("matches", []):
+            if doc.get("score", 0.0) >= min_relevance_score:
+                record = MemoryRecord(
+                    id=doc.get("id"),
+                    text=doc.get("text", ""),
+                    is_reference=False,
+                    embedding=None,
+                    description=None,
+                    additional_metadata=None
+                )
+                matches.append((record, doc.get("score", 0.0)))
+        return matches
+
+    async def get_nearest_match_async(
+        self,
+        collection_name: str,
+        embedding: Any,
+        min_relevance_score: float = 0.0,
+        with_embedding: bool = False,
+    ) -> Tuple[MemoryRecord, float]:
+        matches = await self.get_nearest_matches_async(
+            collection_name, embedding, limit=1, min_relevance_score=min_relevance_score
+        )
+        return matches[0] if matches else (None, 0.0)

holographic_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "holographic-sdk"
+version = "0.1.0"
+description = "Zero-Trust FHE-Lite SDK for Holographic Memory System"
+authors = [
+    {name = "WritersLogic", email = "david@writerslogic.com"},
+]
+dependencies = [
+    "numpy>=1.24.0",
+    "requests>=2.31.0"
+]
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "AGPL-3.0-or-later"}
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+llamaindex = ["llama-index-core>=0.10.0"]
+haystack = ["haystack-ai>=2.0.0"]
+semantic-kernel = ["semantic-kernel>=1.0.0"]
+dspy = ["dspy-ai>=2.4.0"]
+all = [
+    "langchain-core>=0.1.0",
+    "llama-index-core>=0.10.0",
+    "haystack-ai>=2.0.0",
+    "semantic-kernel>=1.0.0",
+    "dspy-ai>=2.4.0"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"