pulsedb 1.0.0__tar.gz

pulsedb-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+Licensor: G Kavinrajan
+Licensed Work: PulseDB
+Additional Use Grant: You may make use of the Licensed Work for non-production purposes, including testing, development, and academic research. You may not use the Licensed Work for any production purpose without a commercial agreement with the Licensor.
+Change Date: 2030-06-28
+Change License: Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensed Work is provided "AS IS", without warranties or conditions of any kind.
+
+You may also make production use of the Licensed Work, provided such use does not exceed the Additional Use Grant (if any). If your use exceeds the Additional Use Grant, you must acquire a commercial license from the Licensor.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and such rights shall replace all rights and restrictions granted under this License.
+
+Disclaimer of Warranty
+THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE LICENSED WORK.

pulsedb-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: pulsedb
+Version: 1.0.0
+Summary: High-performance Python Vector Database & Memory Engine with RESP2 support.
+Author-email: G Kavinrajan <gkavinrajan@example.com>
+Project-URL: Homepage, https://github.com/gkavinrajanCodes/pulseDB
+Project-URL: Bug Tracker, https://github.com/gkavinrajanCodes/pulseDB/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: redis>=5.0.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: hnswlib>=0.8.0
+Dynamic: license-file
+
+<div align="center">
+
+# ⚡ PulseDB
+
+**An enterprise-grade, in-memory database with a native AI Vector Engine.**
+
+Built for developers who need Redis-compatible storage *and* lightning-fast semantic search — without running two separate systems.
+
+[![CI](https://github.com/gkavinrajanCodes/pulseDB/actions/workflows/python-app.yml/badge.svg)](https://github.com/gkavinrajanCodes/pulseDB/actions)
+[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue)](https://pypi.org/project/pulsedb/)
+[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)
+
+</div>
+
+---
+
+## What is PulseDB?
+
+PulseDB is a high-performance, open-source database that combines:
+
+- **A Redis-compatible KV store** — Strings, Lists, Hashes with TTL, LRU eviction, and RESP2 wire protocol
+- **An AI Memory Engine** — HNSW-based vector search with native C++ pre-filtering callbacks
+- **A Python SDK** — Ergonomic `db.vectors.upsert()` / `db.vectors.search()` API
+- **A LangChain Integration** — Drop-in `PulseDBVectorStore` for RAG pipelines with metadata filtering
+
+> One server, one protocol, one SDK. No Pinecone. No Weaviate. No Redis Stack.
+
+---
+
+## Features
+
+| Category | Capability |
+|---|---|
+| **KV Store** | `SET`, `GET`, `DEL`, `EXPIRE`, `TTL`, `MSET`, `MGET`, `INCR`, `APPEND` |
+| **Data Types** | Strings · Lists (`LPUSH/RPOP/LRANGE`) · Hashes (`HSET/HGET/HGETALL`) |
+| **Vector Engine** | HNSW cosine similarity, O(log N) search, dynamic resizing |
+| **Hybrid Search** | Native C++ pre-filter callbacks — filter by metadata *during* graph traversal |
+| **Persistence** | Write-Ahead Log (WAL) + JSON snapshots + HNSW binary graph snapshots |
+| **Protocol** | RESP2 TCP (port 6379) — works with `redis-cli`, `redis-py`, `ioredis` |
+| **Cluster** | Consistent hashing, multi-node routing |
+| **Auth** | API Key (HTTP) + `REQUIREPASS` (TCP) + optional TLS/SSL |
+| **Observability** | Prometheus `/metrics` endpoint, structured `/health` and `/ready` |
+| **LangChain** | `PulseDBVectorStore` with `similarity_search(filter={...})` |
+
+---
+
+## Quickstart
+
+### 1. Run the Server (Docker)
+
+```bash
+docker run -d \
+  -p 6379:6379 \
+  -p 8000:8000 \
+  -v pulsedb_data:/app/data \
+  --name pulsedb \
+  ghcr.io/gkavinrajancodes/pulsedb:latest
+```
+
+Or use Docker Compose for a 3-node cluster:
+
+```bash
+git clone https://github.com/gkavinrajanCodes/pulseDB.git
+cd pulseDB && docker-compose up --build
+```
+
+### 2. Install the SDK
+
+```bash
+pip install pulsedb
+```
+
+### 3. Use It
+
+```python
+from pulsedb import PulseDB
+
+db = PulseDB(host="localhost", port=6379)
+
+# Standard KV Store
+db.set("session:abc", "user_data", ttl=3600)
+print(db.get("session:abc"))  # "user_data"
+
+# AI Memory Engine — insert vectors with metadata
+db.vectors.upsert("article:1", [0.12, 0.98, 0.34], metadata={"category": "sports", "year": 2024})
+db.vectors.upsert("article:2", [0.91, 0.11, 0.67], metadata={"category": "tech", "year": 2023})
+
+# Semantic similarity search — optionally filter by metadata
+results = db.vectors.search([0.10, 0.95, 0.40], top_k=5, filter={"category": "sports"})
+# → [{"id": "article:1", "score": 0.997}]
+```
+
+---
+
+## LangChain Integration
+
+PulseDB works natively as a LangChain VectorStore, giving your RAG pipeline blazing fast retrieval with hybrid metadata filtering.
+
+```python
+from langchain_openai import OpenAIEmbeddings
+from sdk.langchain_pulsedb.vectorstore import PulseDBVectorStore
+
+store = PulseDBVectorStore(
+    embedding=OpenAIEmbeddings(),
+    host="localhost",
+    port=6379,
+)
+
+# Ingest documents — metadata is automatically stored for hybrid filtering
+store.add_texts(
+    texts=["PulseDB is fast", "Redis is popular", "Pinecone is expensive"],
+    metadatas=[{"source": "blog"}, {"source": "wiki"}, {"source": "review"}]
+)
+
+# Hybrid search — find similar docs but only from the blog source
+docs = store.similarity_search("fast database", k=2, filter={"source": "blog"})
+```
+
+---
+
+## How the AI Memory Engine Works
+
+Standard vector databases do **post-filtering**: search all vectors, get K results, then throw away the ones that don't match the filter. This degrades accuracy.
+
+PulseDB does **true pre-filtering** using native `hnswlib` C++ filter callbacks. The filter function is evaluated *inside* the graph traversal — so the C++ engine skips disqualified nodes entirely before scoring them.
+
+```
+Query Vector → HNSW Graph Traversal → [Filter Callback runs on every node visited]
+                                        ↓ Pass → included in result set
+                                        ↓ Fail → skipped immediately
+                                       Top-K results returned
+```
+
+This means your effective `top_k` is always accurate, even with highly restrictive filters.
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    Client["Client (SDK / redis-cli)"] -->|RESP2 Binary Protocol| TCP["asyncio TCP Server :6379"]
+    Client -->|HTTP REST| HTTP["FastAPI Gateway :8000"]
+    TCP --> Router["Command Router"]
+    HTTP --> Router
+    Router --> KV["16-Shard KV Store (LRU + TTL)"]
+    Router --> VE["AI Vector Engine (hnswlib HNSW)"]
+    Router --> DT["Data Types (Lists, Hashes)"]
+    Router --> PS["Pub/Sub Engine"]
+    KV --> WAL["Write-Ahead Log"]
+    VE --> Snap["HNSW Binary Snapshot"]
+    WAL --> Snap
+```
+
+---
+
+## Run Locally (From Source)
+
+```bash
+# 1. Clone and install
+git clone https://github.com/gkavinrajanCodes/pulseDB.git
+cd pulseDB
+python3.10 -m venv workenv && source workenv/bin/activate
+pip install -r requirements.txt
+
+# 2. Start the server
+NODE_ID=node1 CLUSTER_NODES=node1 uvicorn server.main:app --host 0.0.0.0 --port 8000
+
+# 3. Install the SDK (in another terminal)
+pip install -e sdk/
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/sorted-sets`
+3. Commit your changes: `git commit -m "feat: add ZADD/ZRANGE sorted set commands"`
+4. Push: `git push origin feature/sorted-sets`
+5. Open a Pull Request
+
+All PRs are validated against our CI matrix (Python 3.10, 3.11, 3.12 with flake8, mypy, and pytest).
+
+---
+
+## License
+
+Distributed under the Business Source License (BSL 1.1). See [LICENSE](LICENSE) for details.

pulsedb-1.0.0/README.md

@@ -0,0 +1,189 @@
+<div align="center">
+
+# ⚡ PulseDB
+
+**An enterprise-grade, in-memory database with a native AI Vector Engine.**
+
+Built for developers who need Redis-compatible storage *and* lightning-fast semantic search — without running two separate systems.
+
+[![CI](https://github.com/gkavinrajanCodes/pulseDB/actions/workflows/python-app.yml/badge.svg)](https://github.com/gkavinrajanCodes/pulseDB/actions)
+[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue)](https://pypi.org/project/pulsedb/)
+[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)
+
+</div>
+
+---
+
+## What is PulseDB?
+
+PulseDB is a high-performance, open-source database that combines:
+
+- **A Redis-compatible KV store** — Strings, Lists, Hashes with TTL, LRU eviction, and RESP2 wire protocol
+- **An AI Memory Engine** — HNSW-based vector search with native C++ pre-filtering callbacks
+- **A Python SDK** — Ergonomic `db.vectors.upsert()` / `db.vectors.search()` API
+- **A LangChain Integration** — Drop-in `PulseDBVectorStore` for RAG pipelines with metadata filtering
+
+> One server, one protocol, one SDK. No Pinecone. No Weaviate. No Redis Stack.
+
+---
+
+## Features
+
+| Category | Capability |
+|---|---|
+| **KV Store** | `SET`, `GET`, `DEL`, `EXPIRE`, `TTL`, `MSET`, `MGET`, `INCR`, `APPEND` |
+| **Data Types** | Strings · Lists (`LPUSH/RPOP/LRANGE`) · Hashes (`HSET/HGET/HGETALL`) |
+| **Vector Engine** | HNSW cosine similarity, O(log N) search, dynamic resizing |
+| **Hybrid Search** | Native C++ pre-filter callbacks — filter by metadata *during* graph traversal |
+| **Persistence** | Write-Ahead Log (WAL) + JSON snapshots + HNSW binary graph snapshots |
+| **Protocol** | RESP2 TCP (port 6379) — works with `redis-cli`, `redis-py`, `ioredis` |
+| **Cluster** | Consistent hashing, multi-node routing |
+| **Auth** | API Key (HTTP) + `REQUIREPASS` (TCP) + optional TLS/SSL |
+| **Observability** | Prometheus `/metrics` endpoint, structured `/health` and `/ready` |
+| **LangChain** | `PulseDBVectorStore` with `similarity_search(filter={...})` |
+
+---
+
+## Quickstart
+
+### 1. Run the Server (Docker)
+
+```bash
+docker run -d \
+  -p 6379:6379 \
+  -p 8000:8000 \
+  -v pulsedb_data:/app/data \
+  --name pulsedb \
+  ghcr.io/gkavinrajancodes/pulsedb:latest
+```
+
+Or use Docker Compose for a 3-node cluster:
+
+```bash
+git clone https://github.com/gkavinrajanCodes/pulseDB.git
+cd pulseDB && docker-compose up --build
+```
+
+### 2. Install the SDK
+
+```bash
+pip install pulsedb
+```
+
+### 3. Use It
+
+```python
+from pulsedb import PulseDB
+
+db = PulseDB(host="localhost", port=6379)
+
+# Standard KV Store
+db.set("session:abc", "user_data", ttl=3600)
+print(db.get("session:abc"))  # "user_data"
+
+# AI Memory Engine — insert vectors with metadata
+db.vectors.upsert("article:1", [0.12, 0.98, 0.34], metadata={"category": "sports", "year": 2024})
+db.vectors.upsert("article:2", [0.91, 0.11, 0.67], metadata={"category": "tech", "year": 2023})
+
+# Semantic similarity search — optionally filter by metadata
+results = db.vectors.search([0.10, 0.95, 0.40], top_k=5, filter={"category": "sports"})
+# → [{"id": "article:1", "score": 0.997}]
+```
+
+---
+
+## LangChain Integration
+
+PulseDB works natively as a LangChain VectorStore, giving your RAG pipeline blazing fast retrieval with hybrid metadata filtering.
+
+```python
+from langchain_openai import OpenAIEmbeddings
+from sdk.langchain_pulsedb.vectorstore import PulseDBVectorStore
+
+store = PulseDBVectorStore(
+    embedding=OpenAIEmbeddings(),
+    host="localhost",
+    port=6379,
+)
+
+# Ingest documents — metadata is automatically stored for hybrid filtering
+store.add_texts(
+    texts=["PulseDB is fast", "Redis is popular", "Pinecone is expensive"],
+    metadatas=[{"source": "blog"}, {"source": "wiki"}, {"source": "review"}]
+)
+
+# Hybrid search — find similar docs but only from the blog source
+docs = store.similarity_search("fast database", k=2, filter={"source": "blog"})
+```
+
+---
+
+## How the AI Memory Engine Works
+
+Standard vector databases do **post-filtering**: search all vectors, get K results, then throw away the ones that don't match the filter. This degrades accuracy.
+
+PulseDB does **true pre-filtering** using native `hnswlib` C++ filter callbacks. The filter function is evaluated *inside* the graph traversal — so the C++ engine skips disqualified nodes entirely before scoring them.
+
+```
+Query Vector → HNSW Graph Traversal → [Filter Callback runs on every node visited]
+                                        ↓ Pass → included in result set
+                                        ↓ Fail → skipped immediately
+                                       Top-K results returned
+```
+
+This means your effective `top_k` is always accurate, even with highly restrictive filters.
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    Client["Client (SDK / redis-cli)"] -->|RESP2 Binary Protocol| TCP["asyncio TCP Server :6379"]
+    Client -->|HTTP REST| HTTP["FastAPI Gateway :8000"]
+    TCP --> Router["Command Router"]
+    HTTP --> Router
+    Router --> KV["16-Shard KV Store (LRU + TTL)"]
+    Router --> VE["AI Vector Engine (hnswlib HNSW)"]
+    Router --> DT["Data Types (Lists, Hashes)"]
+    Router --> PS["Pub/Sub Engine"]
+    KV --> WAL["Write-Ahead Log"]
+    VE --> Snap["HNSW Binary Snapshot"]
+    WAL --> Snap
+```
+
+---
+
+## Run Locally (From Source)
+
+```bash
+# 1. Clone and install
+git clone https://github.com/gkavinrajanCodes/pulseDB.git
+cd pulseDB
+python3.10 -m venv workenv && source workenv/bin/activate
+pip install -r requirements.txt
+
+# 2. Start the server
+NODE_ID=node1 CLUSTER_NODES=node1 uvicorn server.main:app --host 0.0.0.0 --port 8000
+
+# 3. Install the SDK (in another terminal)
+pip install -e sdk/
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/sorted-sets`
+3. Commit your changes: `git commit -m "feat: add ZADD/ZRANGE sorted set commands"`
+4. Push: `git push origin feature/sorted-sets`
+5. Open a Pull Request
+
+All PRs are validated against our CI matrix (Python 3.10, 3.11, 3.12 with flake8, mypy, and pytest).
+
+---
+
+## License
+
+Distributed under the Business Source License (BSL 1.1). See [LICENSE](LICENSE) for details.

pulsedb-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pulsedb"
+version = "1.0.0"
+authors = [
+  { name="G Kavinrajan", email="gkavinrajan@example.com" },
+]
+description = "High-performance Python Vector Database & Memory Engine with RESP2 support."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Database",
+]
+dependencies = [
+    "redis>=5.0.0",
+    "numpy>=1.20.0",
+    "hnswlib>=0.8.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/gkavinrajanCodes/pulseDB"
+"Bug Tracker" = "https://github.com/gkavinrajanCodes/pulseDB/issues"
+
+[tool.setuptools.packages.find]
+where = ["sdk"]
+include = ["pulsedb", "pulsedb.*", "langchain_pulsedb", "langchain_pulsedb.*"]

pulsedb-1.0.0/sdk/langchain_pulsedb/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 G Kavinrajan. All rights reserved.
+# Licensed under the Business Source License 1.1
+
+from .vectorstore import PulseDBVectorStore
+
+__all__ = ["PulseDBVectorStore"]

pulsedb-1.0.0/sdk/langchain_pulsedb/vectorstore.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2026 G Kavinrajan. All rights reserved.
+# Licensed under the Business Source License 1.1
+
+import uuid
+from typing import Any, Iterable, List, Optional, Tuple, Dict
+
+from langchain_core.documents import Document
+from langchain_core.embeddings import Embeddings
+from langchain_core.vectorstores import VectorStore
+
+from pulsedb import PulseDB
+
+
+class PulseDBVectorStore(VectorStore):
+    """PulseDB VectorStore wrapper for LangChain."""
+
+    def __init__(
+        self,
+        embedding: Embeddings,
+        client: Optional[PulseDB] = None,
+        host: str = "localhost",
+        port: int = 6379,
+        collection_name: str = "langchain",
+    ):
+        self._embedding = embedding
+        self._client = client or PulseDB(host=host, port=port)
+        self._collection = collection_name
+
+    def _get_key(self, doc_id: str) -> str:
+        return f"{self._collection}:{doc_id}"
+
+    def add_texts(
+        self,
+        texts: Iterable[str],
+        metadatas: Optional[List[dict]] = None,
+        ids: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> List[str]:
+        """Run more texts through the embeddings and add to the vectorstore."""
+        texts = list(texts)
+        if not texts:
+            return []
+
+        embeddings = self._embedding.embed_documents(texts)
+        if ids is None:
+            ids = [str(uuid.uuid4()) for _ in texts]
+        if metadatas is None:
+            metadatas = [{} for _ in texts]
+
+        batch = []
+        for text, metadata, doc_id, embedding in zip(texts, metadatas, ids, embeddings):
+            key = self._get_key(doc_id)
+            doc_metadata = metadata.copy()
+            doc_metadata["_text"] = text
+            batch.append({"id": key, "vector": embedding, "metadata": doc_metadata})
+
+        self._client.vectors.upsert_batch(batch)
+
+        return ids
+
+    def similarity_search(
+        self, query: str, k: int = 4, filter: Optional[Dict[str, Any]] = None, **kwargs: Any
+    ) -> List[Document]:
+        """Return docs most similar to query."""
+        results = self.similarity_search_with_score(query, k=k, filter=filter, **kwargs)
+        return [doc for doc, _ in results]
+
+    def similarity_search_with_score(
+        self, query: str, k: int = 4, filter: Optional[Dict[str, Any]] = None, **kwargs: Any
+    ) -> List[Tuple[Document, float]]:
+        """Return docs most similar to query, along with scores."""
+        embedding = self._embedding.embed_query(query)
+        
+        # Search the vector index using the native TCP Binary Protocol
+        raw_results = self._client.vectors.search(embedding, top_k=k, filter=filter)
+        
+        docs_with_scores = []
+        for res in raw_results:
+            key = res["id"]
+            score = res["score"]
+            
+            # Only process keys in our collection
+            if not key.startswith(f"{self._collection}:"):
+                continue
+
+            # Fetch the metadata dictionary
+            doc_data = self._client.vectors.get(key)
+            if not doc_data:
+                continue
+
+            metadata = doc_data.get("metadata", {})
+            text = metadata.pop("_text", "")
+            
+            doc = Document(page_content=text, metadata=metadata)
+            docs_with_scores.append((doc, score))
+
+        return docs_with_scores
+
+    @classmethod
+    def from_texts(
+        cls,
+        texts: List[str],
+        embedding: Embeddings,
+        metadatas: Optional[List[dict]] = None,
+        **kwargs: Any,
+    ) -> "PulseDBVectorStore":
+        """Return VectorStore initialized from texts and embeddings."""
+        store = cls(embedding, **kwargs)
+        store.add_texts(texts, metadatas)
+        return store

pulsedb-1.0.0/sdk/pulsedb/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 G Kavinrajan. All rights reserved.
+# Licensed under the Business Source License 1.1
+
+# sdk/pulsedb/__init__.py
+"""
+PulseDB Python SDK
+
+Connects to PulseDB over the high-performance TCP Binary Protocol (port 6379).
+
+Usage (sync):
+    from pulsedb import PulseDB
+
+    db = PulseDB(host="localhost", port=6379)
+    db.set("user:123", "alice", ttl=3600)
+    print(db.get("user:123"))  # "alice"
+
+    # AI Memory Engine (Vector Search)
+    db.vectors.upsert("doc1", [0.1, 0.2, 0.3], metadata={"category": "news"})
+    results = db.vectors.search([0.1, 0.2, 0.3], top_k=5, filter={"category": "news"})
+
+Usage (async):
+    from pulsedb import AsyncPulseDB
+
+    async def main():
+        async with AsyncPulseDB(host="localhost", port=6379) as db:
+            await db.set("counter", 0)
+            await db.incr("counter")
+            await db.vectors.upsert("doc1", [0.1, 0.2, 0.3])
+"""
+
+from .client import PulseDB
+from .async_client import AsyncPulseDB
+from .exceptions import (
+    PulseDBError,
+    ConnectionError,
+    AuthenticationError,
+    CommandError,
+    TimeoutError,
+)
+
+__version__ = "1.1.0"
+__all__ = [
+    "PulseDB",
+    "AsyncPulseDB",
+    "PulseDBError",
+    "ConnectionError",
+    "AuthenticationError",
+    "CommandError",
+    "TimeoutError",
+]