vecmindb 1.0.0b0__tar.gz

vecmindb-1.0.0b0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: vecmindb
+Version: 1.0.0b0
+Summary: Python SDK for VecminDB - High-performance vector database HTTP client
+Author-email: VecminDB Team <sulingqi@hotmail.com>
+License: MIT OR Apache-2.0
+Project-URL: Homepage, https://lingxinmind.com
+Project-URL: Repository, https://github.com/lingxinmind/vecminDB
+Project-URL: Documentation, https://lingxinmind.com/docs/index.html
+Project-URL: Changelog, https://github.com/lingxinmind/vecminDB/blob/main/CHANGELOG.md
+Keywords: vector-database,similarity-search,embedding,sdk,rag
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# VecminDB SDK
+
+The official SDK for [VecminDB](https://lingxinmind.com) — The Sovereign Memory OS for AI Agents.
+
+> Stop letting your AI Agents hallucinate from memory rot. VecminDB naturally decays outdated memories, distills knowledge via PCA, and provides 100% Air-Gapped cryptographic data sovereignty.
+
+⚠️ **License Note**: VecminDB is a commercial Cognitive Vector Database. The Free Tier supports up to 5 agents and 100K vectors/agent forever. For enterprise scale-out or clusters, please visit our official website to register and obtain a license key: [https://lingxinmind.com](https://lingxinmind.com).
+
+## Deployment & Installation
+
+VecminDB can be run via Docker or as optimized, standalone pre-compiled native binary packages. No local compilers, dependencies, or Python runtimes are needed.
+
+### Method A: Docker Deployment (All Platforms - Windows, macOS, Linux)
+The fastest way to spin up VecminDB with automatic in-database bilingual embedding support.
+
+```bash
+# For Global / Overseas users:
+docker run -d --name vecmindb-trial -p 5520:5520 ghcr.io/lingxinmind/vecmindb:latest
+
+# For Domestic users (China Aliyun Mirror):
+# docker run -d --name vecmindb-trial -p 5520:5520 crpi-ngtfnt7d3tsnwk7l.cn-shanghai.personal.cr.aliyuncs.com/vecmindb/vecmindb:latest
+```
+
+---
+
+### Method B: Pre-Compiled Native Binary Bundles (Zero-Docker / Zero-Python)
+Ideal for high-performance, air-gapped on-premise or private cloud servers. Download the appropriate package from our official website [Downloads](https://lingxinmind.com) portal:
+
+*   **Windows (AMD64)**:
+    Download `vecmindb-1.0.0-beta-x86_64-pc-windows-msvc.zip`. Extract the ZIP archive, open Command Prompt or PowerShell in the directory, and run:
+    ```cmd
+    .\vecmindb-server.exe
+    ```
+*   **macOS (Apple Silicon M1/M2/M3)**:
+    Download `vecmindb-1.0.0-beta-aarch64-apple-darwin.tar.gz`. Open Terminal, extract and run:
+    ```bash
+    tar -xzf vecmindb-1.0.0-beta-aarch64-apple-darwin.tar.gz
+    cd vecmindb-1.0.0-beta-aarch64-apple-darwin
+    ./vecmindb-server
+    ```
+*   **Linux (AMD64)**:
+    Download `vecmindb-offline-linux-amd64.tar.gz`. Extract and run:
+    ```bash
+    tar -xzf vecmindb-offline-linux-amd64.tar.gz
+    cd vecmindb-offline-linux-amd64
+    ./vecmindb-server
+    ```
+
+---
+
+## SDK Quickstart
+
+First, install the target client SDK:
+
+```bash
+# Install core client
+pip install vecmindb
+
+# Install with LangChain integration
+pip install vecmindb[langchain]
+
+# Install with CrewAI integration
+pip install vecmindb[crewai]
+```
+
+### Using with LangChain
+
+```python
+from vecmindb.memory_plugin import VecminDBMemoryPlugin
+from langchain_openai import ChatOpenAI
+from langchain.chains import ConversationChain
+
+# Initialize Sovereign Agent Memory
+memory = VecminDBMemoryPlugin.for_langchain(agent_id="support_agent_01", base_url="http://localhost:5520")
+
+llm = ChatOpenAI(temperature=0)
+conversation = ConversationChain(llm=llm, memory=memory)
+
+conversation.predict(input="Hi, I need help with my billing.")
+```
+
+### Using with CrewAI
+
+```python
+from vecmindb.memory_plugin import VecminDBMemoryPlugin
+from crewai import Agent, Crew
+
+# Initialize Sovereign Agent Memory
+memory_storage = VecminDBMemoryPlugin.for_crewai(agent_id="finance_agent_01", base_url="http://localhost:5520")
+
+agent = Agent(
+    role='Financial Analyst',
+    goal='Analyze billing data',
+    backstory='An expert in financial data.',
+    memory=True,
+    memory_config={"storage": memory_storage} # Inject VecminDB memory
+)
+```
+
+## Why VecminDB?
+
+Unlike generic vector databases that act as static drives, VecminDB acts as a cognitive memory operating system with native lifecycle management and cryptographic isolation:
+
+*   **Biological Forgetting (LTSM)**: Episodic memories decay dynamically following $W(t) = \exp(-\lambda \times \Delta t)$ with automatic 90-day semantic pruning (`let semantic_prune_threshold_secs = 90 * 86400;` on disk). Frequently accessed memories persist; transient noise is permanently retired.
+*   **Welford & PCA Memory Distillation**: Fuses decaying memory clusters into stable Abstract Centroids using real-time Welford online variance and DP-Federated PCA. Storage converges and scales logarithmically, locking in long-term TCO budgets.
+*   **3-Sigma Sentinel Guard**: Performs real-time anomaly detection and adversarial injection pruning. Evaluates cosine outlier distance with dynamic cutoffs: $\text{Threshold} = \max(\text{Mean}_s - 3 \times \text{Std}_s, 0.7)$.
+*   **Sovereign Federation**: Shares collective intelligence across multiple agent domains or VPCs without raw data leak. Fuses PCA Candidate Centroids with differential privacy and a 10% principal bias: $\vec{v}_{\text{centroid}} = \text{Mean}_{\text{global}} + P_0 \times 0.1$.
+*   **Raft Consensus & 1024-Bucket Anti-Entropy**: Combines strong consensus replication with self-healing topology. Employs monotonic lock validation (`pub fencing_token: u64`) and an adaptive sync cap: `(resolution * 2).min(1024)`.
+*   **100% Air-Gapped Single-Binary**: Built-in BGE-M3 ONNX runtime. No Python, PyTorch, or external embedding API keys needed. Bounded tightly to machine-level HAI hardware fingerprints.
+
+---
+**Enterprise Licensing**: For multi-node SOC-2 compliant deployments, please purchase subscriptions or contact us at `sulingqi@hotmail.com`.

vecmindb-1.0.0b0/README.md

@@ -0,0 +1,112 @@
+# VecminDB SDK
+
+The official SDK for [VecminDB](https://lingxinmind.com) — The Sovereign Memory OS for AI Agents.
+
+> Stop letting your AI Agents hallucinate from memory rot. VecminDB naturally decays outdated memories, distills knowledge via PCA, and provides 100% Air-Gapped cryptographic data sovereignty.
+
+⚠️ **License Note**: VecminDB is a commercial Cognitive Vector Database. The Free Tier supports up to 5 agents and 100K vectors/agent forever. For enterprise scale-out or clusters, please visit our official website to register and obtain a license key: [https://lingxinmind.com](https://lingxinmind.com).
+
+## Deployment & Installation
+
+VecminDB can be run via Docker or as optimized, standalone pre-compiled native binary packages. No local compilers, dependencies, or Python runtimes are needed.
+
+### Method A: Docker Deployment (All Platforms - Windows, macOS, Linux)
+The fastest way to spin up VecminDB with automatic in-database bilingual embedding support.
+
+```bash
+# For Global / Overseas users:
+docker run -d --name vecmindb-trial -p 5520:5520 ghcr.io/lingxinmind/vecmindb:latest
+
+# For Domestic users (China Aliyun Mirror):
+# docker run -d --name vecmindb-trial -p 5520:5520 crpi-ngtfnt7d3tsnwk7l.cn-shanghai.personal.cr.aliyuncs.com/vecmindb/vecmindb:latest
+```
+
+---
+
+### Method B: Pre-Compiled Native Binary Bundles (Zero-Docker / Zero-Python)
+Ideal for high-performance, air-gapped on-premise or private cloud servers. Download the appropriate package from our official website [Downloads](https://lingxinmind.com) portal:
+
+*   **Windows (AMD64)**:
+    Download `vecmindb-1.0.0-beta-x86_64-pc-windows-msvc.zip`. Extract the ZIP archive, open Command Prompt or PowerShell in the directory, and run:
+    ```cmd
+    .\vecmindb-server.exe
+    ```
+*   **macOS (Apple Silicon M1/M2/M3)**:
+    Download `vecmindb-1.0.0-beta-aarch64-apple-darwin.tar.gz`. Open Terminal, extract and run:
+    ```bash
+    tar -xzf vecmindb-1.0.0-beta-aarch64-apple-darwin.tar.gz
+    cd vecmindb-1.0.0-beta-aarch64-apple-darwin
+    ./vecmindb-server
+    ```
+*   **Linux (AMD64)**:
+    Download `vecmindb-offline-linux-amd64.tar.gz`. Extract and run:
+    ```bash
+    tar -xzf vecmindb-offline-linux-amd64.tar.gz
+    cd vecmindb-offline-linux-amd64
+    ./vecmindb-server
+    ```
+
+---
+
+## SDK Quickstart
+
+First, install the target client SDK:
+
+```bash
+# Install core client
+pip install vecmindb
+
+# Install with LangChain integration
+pip install vecmindb[langchain]
+
+# Install with CrewAI integration
+pip install vecmindb[crewai]
+```
+
+### Using with LangChain
+
+```python
+from vecmindb.memory_plugin import VecminDBMemoryPlugin
+from langchain_openai import ChatOpenAI
+from langchain.chains import ConversationChain
+
+# Initialize Sovereign Agent Memory
+memory = VecminDBMemoryPlugin.for_langchain(agent_id="support_agent_01", base_url="http://localhost:5520")
+
+llm = ChatOpenAI(temperature=0)
+conversation = ConversationChain(llm=llm, memory=memory)
+
+conversation.predict(input="Hi, I need help with my billing.")
+```
+
+### Using with CrewAI
+
+```python
+from vecmindb.memory_plugin import VecminDBMemoryPlugin
+from crewai import Agent, Crew
+
+# Initialize Sovereign Agent Memory
+memory_storage = VecminDBMemoryPlugin.for_crewai(agent_id="finance_agent_01", base_url="http://localhost:5520")
+
+agent = Agent(
+    role='Financial Analyst',
+    goal='Analyze billing data',
+    backstory='An expert in financial data.',
+    memory=True,
+    memory_config={"storage": memory_storage} # Inject VecminDB memory
+)
+```
+
+## Why VecminDB?
+
+Unlike generic vector databases that act as static drives, VecminDB acts as a cognitive memory operating system with native lifecycle management and cryptographic isolation:
+
+*   **Biological Forgetting (LTSM)**: Episodic memories decay dynamically following $W(t) = \exp(-\lambda \times \Delta t)$ with automatic 90-day semantic pruning (`let semantic_prune_threshold_secs = 90 * 86400;` on disk). Frequently accessed memories persist; transient noise is permanently retired.
+*   **Welford & PCA Memory Distillation**: Fuses decaying memory clusters into stable Abstract Centroids using real-time Welford online variance and DP-Federated PCA. Storage converges and scales logarithmically, locking in long-term TCO budgets.
+*   **3-Sigma Sentinel Guard**: Performs real-time anomaly detection and adversarial injection pruning. Evaluates cosine outlier distance with dynamic cutoffs: $\text{Threshold} = \max(\text{Mean}_s - 3 \times \text{Std}_s, 0.7)$.
+*   **Sovereign Federation**: Shares collective intelligence across multiple agent domains or VPCs without raw data leak. Fuses PCA Candidate Centroids with differential privacy and a 10% principal bias: $\vec{v}_{\text{centroid}} = \text{Mean}_{\text{global}} + P_0 \times 0.1$.
+*   **Raft Consensus & 1024-Bucket Anti-Entropy**: Combines strong consensus replication with self-healing topology. Employs monotonic lock validation (`pub fencing_token: u64`) and an adaptive sync cap: `(resolution * 2).min(1024)`.
+*   **100% Air-Gapped Single-Binary**: Built-in BGE-M3 ONNX runtime. No Python, PyTorch, or external embedding API keys needed. Bounded tightly to machine-level HAI hardware fingerprints.
+
+---
+**Enterprise Licensing**: For multi-node SOC-2 compliant deployments, please purchase subscriptions or contact us at `sulingqi@hotmail.com`.

vecmindb-1.0.0b0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vecmindb"
+version = "1.0.0-beta"
+description = "Python SDK for VecminDB - High-performance vector database HTTP client"
+authors = [{email = "sulingqi@hotmail.com", name = "VecminDB Team"}]
+license = {text = "MIT OR Apache-2.0"}
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["vector-database", "similarity-search", "embedding", "sdk", "rag"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://lingxinmind.com"
+Repository = "https://github.com/lingxinmind/vecminDB"
+Documentation = "https://lingxinmind.com/docs/index.html"
+Changelog = "https://github.com/lingxinmind/vecminDB/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["vecmindb*"]

vecmindb-1.0.0b0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vecmindb-1.0.0b0/tests/test_agent_memory.py

@@ -0,0 +1,224 @@
+"""Unit tests for the VecminDB Agent OS Memory abstraction."""
+
+import unittest
+from unittest.mock import MagicMock, AsyncMock, patch
+from vecmindb import (
+    VecminClient,
+    AsyncVecminClient,
+    connect,
+    AgentMemoryManager,
+    AsyncAgentMemoryManager,
+    VecminMemorySpace,
+    AsyncVecminMemorySpace,
+)
+
+
+class TestAgentMemory(unittest.IsolatedAsyncioTestCase):
+    """Verify sovereignty agent isolation and cognitive memory space lifecycle."""
+
+    def test_client_init(self) -> None:
+        """Verify constructor handles agent_id and sovereignty_token correctly."""
+        client = VecminClient(
+            "http://localhost:5520",
+            agent_id="my_agent",
+            sovereignty_token="my_token",
+        )
+        self.assertEqual(client.agent_id, "my_agent")
+        self.assertEqual(client.sovereignty_token, "my_token")
+
+        # default values
+        client_default = VecminClient("http://localhost:5520")
+        self.assertEqual(client_default.agent_id, "default_agent")
+        self.assertEqual(client_default.sovereignty_token, "system")
+
+    def test_connect_shortcut(self) -> None:
+        """Verify package-level connect() sets agent parameters correctly."""
+        client = connect(
+            "http://localhost:5520",
+            agent_id="agent_123",
+            sovereignty_token="sovereign_abc",
+        )
+        self.assertIsInstance(client, VecminClient)
+        self.assertEqual(client.agent_id, "agent_123")
+        self.assertEqual(client.sovereignty_token, "sovereign_abc")
+
+    @patch("vecmindb.client.VecminClient._api_post")
+    def test_mcp_store_search_sync(self, mock_post: MagicMock) -> None:
+        """Verify MCP parameters propagate sovereignty values correctly."""
+        mock_post.return_value = {"data": {"content": "Stored successfully"}}
+        client = VecminClient(
+            "http://localhost:5520",
+            agent_id="a1",
+            sovereignty_token="t1",
+        )
+
+        res = client.mcp_store_memory("my memory content")
+        self.assertEqual(res, "Stored successfully")
+
+        # Verify extra headers and arguments propagation
+        mock_post.assert_called_once()
+        args = mock_post.call_args[0]
+        kwargs = mock_post.call_args[1]
+        self.assertEqual(args[0], "/mcp/message")
+        self.assertEqual(args[1]["params"]["arguments"]["agent_id"], "a1")
+        self.assertEqual(args[1]["params"]["arguments"]["sovereignty_token"], "t1")
+        self.assertEqual(args[1]["params"]["arguments"]["model_id"], "t1")
+        self.assertEqual(kwargs.get("agent_id"), "a1")
+        self.assertEqual(kwargs.get("model_id"), "t1")
+
+    @patch("vecmindb.client.VecminClient._api_post")
+    @patch("vecmindb.client.VecminClient.ensure_collection")
+    @patch("vecmindb.client.VecminClient._api_get")
+    def test_memory_space_lifecycle_sync(
+        self,
+        mock_get: MagicMock,
+        mock_ensure: MagicMock,
+        mock_post: MagicMock,
+    ) -> None:
+        """Verify full memory space mounting, storage, search, evolve, and centroids lifecycle."""
+        client = VecminClient(
+            "http://localhost:5520",
+            agent_id="agent_alice",
+            sovereignty_token="sovereign_wonderland",
+        )
+
+        # Mount memory space
+        space = client.mount_memory(domain="my_domain")
+        self.assertIsInstance(space, VecminMemorySpace)
+        mock_ensure.assert_called_once_with(
+            "my_domain",
+            dimension=1536,
+            metric_type="Cosine",
+            index_type="HNSW",
+        )
+
+        # Store memory
+        mock_post.return_value = {"data": {"content": "anchored"}}
+        store_res = space.store_memory("test memory")
+        self.assertEqual(store_res, "anchored")
+
+        # Search memory
+        mock_post.return_value = {
+            "data": {
+                "content": '[{"text": "test memory", "score": 0.9}]',
+            },
+        }
+        search_res = space.search_memory("test query")
+        self.assertEqual(len(search_res), 1)
+        self.assertEqual(search_res[0]["text"], "test memory")
+
+        # Evolve memory
+        mock_get.return_value = {"data": {"candidates": [{"id": "cand_1"}]}}
+        # Mock decide & optimize
+        mock_post.side_effect = [
+            {"data": {"decision": "approved"}},  # decide
+            {"data": {"status": "optimized"}},  # optimize
+        ]
+        evolve_res = space.evolve()
+        self.assertEqual(evolve_res["status"], "success")
+        self.assertEqual(evolve_res["candidates_evaluated"], 1)
+        self.assertEqual(evolve_res["decisions"][0]["decision"], "approved")
+
+        # Get centroids
+        mock_get.return_value = {
+            "data": {
+                "centroids": [
+                    {
+                        "id": "c_1",
+                        "vector": [0.1],
+                        "weight": 1.0,
+                        "source_count": 5,
+                        "created_at": "now",
+                    },
+                ],
+            },
+        }
+        centroids = space.get_centroids()
+        self.assertEqual(len(centroids), 1)
+        self.assertEqual(centroids[0]["id"], "c_1")
+
+    async def test_async_lifecycle(self) -> None:
+        """Verify full asynchronous memory space lifecycle."""
+        client = AsyncVecminClient(
+            "http://localhost:5520",
+            agent_id="agent_bob",
+            sovereignty_token="sovereign_builder",
+        )
+
+        # Mocking async client internal calls
+        client.ensure_collection = AsyncMock()  # type: ignore[method-assign]
+        client._api_post = AsyncMock(return_value={"data": {"content": "anchored"}})  # type: ignore[method-assign]
+        client._api_get = AsyncMock()  # type: ignore[method-assign]
+
+        space = await client.mount_memory(domain="async_domain")
+        self.assertIsInstance(space, AsyncVecminMemorySpace)
+        client.ensure_collection.assert_called_once()
+
+        # Store memory
+        store_res = await space.store_memory("async test memory")
+        self.assertEqual(store_res, "anchored")
+
+        # Search memory
+        client._api_post.return_value = {
+            "data": {
+                "content": '[{"text": "async search result"}]',
+            },
+        }
+        search_res = await space.search_memory("async query")
+        self.assertEqual(search_res[0]["text"], "async search result")
+
+        # Evolve memory
+        client._api_get.return_value = {
+            "data": {"candidates": [{"id": "cand_async_1"}]},
+        }
+        client._api_post.side_effect = [
+            {"data": {"decision": "deferred"}},
+            {"data": {"status": "optimized"}},
+        ]
+        evolve_res = await space.evolve()
+        self.assertEqual(evolve_res["status"], "success")
+        self.assertEqual(evolve_res["decisions"][0]["decision"], "deferred")
+
+        # Get centroids
+        client._api_get.return_value = {
+            "data": {"centroids": [{"id": "c_async_1"}]},
+        }
+        centroids = await space.get_centroids()
+        self.assertEqual(centroids[0]["id"], "c_async_1")
+
+    @patch("vecmindb.client.VecminClient._api_post")
+    def test_sovereignty_violation_sync(self, mock_post: MagicMock) -> None:
+        """Verify sovereignty violation raises AuthenticationError or PermissionError."""
+        from vecmindb.exceptions import AuthenticationError, PermissionError
+
+        # Simulate sovereignty_token rejection with 401 Unauthorized
+        mock_post.side_effect = AuthenticationError("Sovereignty token validation failed", code=401)
+        client = VecminClient("http://localhost:5520", agent_id="hacker", sovereignty_token="invalid_token")
+        
+        with self.assertRaises(AuthenticationError):
+            client.mcp_store_memory("unauthorized write")
+
+        # Simulate sovereignty_token access restriction with 403 Forbidden
+        mock_post.side_effect = PermissionError("Access to sovereign domain denied", code=403)
+        with self.assertRaises(PermissionError):
+            client.mcp_store_memory("forbidden write")
+
+    async def test_sovereignty_violation_async(self) -> None:
+        """Verify sovereignty violation in async client raises AuthenticationError or PermissionError."""
+        from vecmindb.exceptions import AuthenticationError, PermissionError
+
+        client = AsyncVecminClient("http://localhost:5520", agent_id="hacker_async", sovereignty_token="invalid_token")
+        
+        # Simulate 401 Unauthorized
+        client._api_post = AsyncMock(side_effect=AuthenticationError("Sovereignty token validation failed", code=401))  # type: ignore[method-assign]
+        with self.assertRaises(AuthenticationError):
+            await client.mcp_store_memory("unauthorized write")
+
+        # Simulate 403 Forbidden
+        client._api_post = AsyncMock(side_effect=PermissionError("Access to sovereign domain denied", code=403))  # type: ignore[method-assign]
+        with self.assertRaises(PermissionError):
+            await client.mcp_store_memory("forbidden write")
+
+
+if __name__ == "__main__":
+    unittest.main()