PyMkDB 0.1.0__tar.gz

pymkdb-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: PyMkDB
+Version: 0.1.0
+Summary: A log-structured, partitioned NoSQL database engine with full-text search, numeric indexes, and dual TCP/HTTP protocols.
+Author: MNG
+License: MIT
+Project-URL: Homepage, https://github.com/MNG/MkDB
+Project-URL: Repository, https://github.com/MNG/MkDB
+Keywords: database,nosql,document-store,full-text-search,log-structured
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: reedsolo>=1.7.0
+
+# MkDB
+
+MkDB is a Custom Log-Structured Merge & Partitioned Redundant Storage Engine built entirely in Python. It provides a robust, highly-available NoSQL/Document database experience with secondary indexing, full-text search, and dual-protocol network access.
+
+## Architecture Highlights
+
+- **Rolling Log Storage Engine**: Append-only storage format guaranteeing high write availability with safe background compaction.
+- **RAM Cache & Debounced Write Queue**: In-memory caching and debounced batching for extreme performance under high write load.
+- **Query Engine & Secondary Indexes**: Fully featured query evaluation including numeric range checks and tokenized full-text inverted indexes.
+- **Data Integrity**: Multi-disk mirroring and Reed-Solomon parity encoding for proactive self-healing and failover.
+- **Dual Protocols**: Accessible via high-speed, persistent TCP WebSockets or standard stateless REST HTTP endpoints.
+- **Web Administration UI**: Includes an embedded web control panel out-of-the-box (`/control` endpoint).
+
+## Project Structure
+
+- `src/db/`: The core database engine (storage primitives, RAM caching, query evaluator, auto-compaction and parity management).
+- `src/server/`: The networking boundary. Houses the TCP Socket and HTTP REST servers, as well as the web-based Control Panel.
+- `src/config/`: Configuration schemas for tailoring memory limits, storage thresholds, and cluster layout.
+- `sdk/`: The official `MkDBClient` for programmatic interaction from Python code.
+
+## Getting Started
+
+### Prerequisites
+- Python 3.10+
+- The database storage format is built into MkDB natively, but you'll need the following for advanced data integrity features (Reed-Solomon logic):
+  ```bash
+  pip install reedsolo
+  ```
+
+### Starting the Server
+MkDB operates as a CLI tool. Launch the engine by pointing it to your desired database directory (which must contain a `config.json` file configuring your stores and network bindings):
+```bash
+mkdb /path/to/your/db
+```
+Once running, the database will host both TCP socket and HTTP interfaces as specified in your `config.json`. The web control panel is accessible via your browser (check server output for the bound port, normally `http://localhost:<port>`).
+
+### Using the Python SDK
+The `MkDBClient` connects seamlessly to your database and abstracts the dual-protocol system:
+
+```python
+from sdk.mkdb_client import MkDBClient
+
+client = MkDBClient()
+client.connect(host="127.0.0.1", port=8080)
+
+# Writing a document (computes delta updates intelligently)
+client.set(
+    store="products",
+    record_id="prod_001",
+    data={"name": "Steel Bolt", "price": 9.99, "category": "fasteners"}
+)
+
+# Reading a document
+record = client.get("products", "prod_001")
+
+# Querying with filters
+results = client.query("products", filter={
+    "price": {"<=": 10.00},
+    "category": ["fasteners"]
+})
+```
+
+See the `docs/` folder for comprehensive guides on the Query Syntax and SDK Reference.

pymkdb-0.1.0/PyMkDB.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: PyMkDB
+Version: 0.1.0
+Summary: A log-structured, partitioned NoSQL database engine with full-text search, numeric indexes, and dual TCP/HTTP protocols.
+Author: MNG
+License: MIT
+Project-URL: Homepage, https://github.com/MNG/MkDB
+Project-URL: Repository, https://github.com/MNG/MkDB
+Keywords: database,nosql,document-store,full-text-search,log-structured
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: reedsolo>=1.7.0
+
+# MkDB
+
+MkDB is a Custom Log-Structured Merge & Partitioned Redundant Storage Engine built entirely in Python. It provides a robust, highly-available NoSQL/Document database experience with secondary indexing, full-text search, and dual-protocol network access.
+
+## Architecture Highlights
+
+- **Rolling Log Storage Engine**: Append-only storage format guaranteeing high write availability with safe background compaction.
+- **RAM Cache & Debounced Write Queue**: In-memory caching and debounced batching for extreme performance under high write load.
+- **Query Engine & Secondary Indexes**: Fully featured query evaluation including numeric range checks and tokenized full-text inverted indexes.
+- **Data Integrity**: Multi-disk mirroring and Reed-Solomon parity encoding for proactive self-healing and failover.
+- **Dual Protocols**: Accessible via high-speed, persistent TCP WebSockets or standard stateless REST HTTP endpoints.
+- **Web Administration UI**: Includes an embedded web control panel out-of-the-box (`/control` endpoint).
+
+## Project Structure
+
+- `src/db/`: The core database engine (storage primitives, RAM caching, query evaluator, auto-compaction and parity management).
+- `src/server/`: The networking boundary. Houses the TCP Socket and HTTP REST servers, as well as the web-based Control Panel.
+- `src/config/`: Configuration schemas for tailoring memory limits, storage thresholds, and cluster layout.
+- `sdk/`: The official `MkDBClient` for programmatic interaction from Python code.
+
+## Getting Started
+
+### Prerequisites
+- Python 3.10+
+- The database storage format is built into MkDB natively, but you'll need the following for advanced data integrity features (Reed-Solomon logic):
+  ```bash
+  pip install reedsolo
+  ```
+
+### Starting the Server
+MkDB operates as a CLI tool. Launch the engine by pointing it to your desired database directory (which must contain a `config.json` file configuring your stores and network bindings):
+```bash
+mkdb /path/to/your/db
+```
+Once running, the database will host both TCP socket and HTTP interfaces as specified in your `config.json`. The web control panel is accessible via your browser (check server output for the bound port, normally `http://localhost:<port>`).
+
+### Using the Python SDK
+The `MkDBClient` connects seamlessly to your database and abstracts the dual-protocol system:
+
+```python
+from sdk.mkdb_client import MkDBClient
+
+client = MkDBClient()
+client.connect(host="127.0.0.1", port=8080)
+
+# Writing a document (computes delta updates intelligently)
+client.set(
+    store="products",
+    record_id="prod_001",
+    data={"name": "Steel Bolt", "price": 9.99, "category": "fasteners"}
+)
+
+# Reading a document
+record = client.get("products", "prod_001")
+
+# Querying with filters
+results = client.query("products", filter={
+    "price": {"<=": 10.00},
+    "category": ["fasteners"]
+})
+```
+
+See the `docs/` folder for comprehensive guides on the Query Syntax and SDK Reference.

pymkdb-0.1.0/PyMkDB.egg-info/SOURCES.txt

@@ -0,0 +1,57 @@
+README.md
+pyproject.toml
+PyMkDB.egg-info/PKG-INFO
+PyMkDB.egg-info/SOURCES.txt
+PyMkDB.egg-info/dependency_links.txt
+PyMkDB.egg-info/entry_points.txt
+PyMkDB.egg-info/requires.txt
+PyMkDB.egg-info/top_level.txt
+pymkdb/__init__.py
+pymkdb/cli.py
+sdk/__init__.py
+sdk/connection.py
+sdk/delta.py
+sdk/http_connection.py
+sdk/mkdb_client.py
+sdk/responses.py
+src/__init__.py
+src/config/db.py
+src/config/server.py
+src/db/__init__.py
+src/db/cache/__init__.py
+src/db/cache/ram_cache.py
+src/db/cache/write_queue.py
+src/db/maintenance/__init__.py
+src/db/maintenance/compactor.py
+src/db/maintenance/task_scheduler.py
+src/db/objects/store.py
+src/db/parity/__init__.py
+src/db/parity/parity_manager.py
+src/db/query/__init__.py
+src/db/query/full_text_index.py
+src/db/query/numeric_index.py
+src/db/query/query_engine.py
+src/db/query/tokenizer.py
+src/db/query_workers/__init__.py
+src/db/query_workers/dispatcher.py
+src/db/query_workers/task.py
+src/db/query_workers/worker.py
+src/db/requesting/main.py
+src/db/storage/__init__.py
+src/db/storage/blob_store.py
+src/db/storage/index_manager.py
+src/db/storage/log_manager.py
+src/db/storage/serializer.py
+src/filing/__init__.py
+src/objects/__init__.py
+src/runtime/__init__.py
+src/server/__init__.py
+src/server/event_log.py
+src/server/coms/actions.py
+src/server/coms/http.py
+src/server/coms/http_handlers.py
+src/server/coms/metrics.py
+src/server/coms/socket.py
+src/server/coms/socket_protocol.py
+src/server/control/server.py
+src/server/control/api/actions.py

pymkdb-0.1.0/PyMkDB.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pymkdb-0.1.0/PyMkDB.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mkdb = pymkdb.cli:main

pymkdb-0.1.0/PyMkDB.egg-info/requires.txt

@@ -0,0 +1,2 @@
+colorama>=0.4.6
+reedsolo>=1.7.0

pymkdb-0.1.0/PyMkDB.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+pymkdb
+sdk
+src

pymkdb-0.1.0/README.md

@@ -0,0 +1,63 @@
+# MkDB
+
+MkDB is a Custom Log-Structured Merge & Partitioned Redundant Storage Engine built entirely in Python. It provides a robust, highly-available NoSQL/Document database experience with secondary indexing, full-text search, and dual-protocol network access.
+
+## Architecture Highlights
+
+- **Rolling Log Storage Engine**: Append-only storage format guaranteeing high write availability with safe background compaction.
+- **RAM Cache & Debounced Write Queue**: In-memory caching and debounced batching for extreme performance under high write load.
+- **Query Engine & Secondary Indexes**: Fully featured query evaluation including numeric range checks and tokenized full-text inverted indexes.
+- **Data Integrity**: Multi-disk mirroring and Reed-Solomon parity encoding for proactive self-healing and failover.
+- **Dual Protocols**: Accessible via high-speed, persistent TCP WebSockets or standard stateless REST HTTP endpoints.
+- **Web Administration UI**: Includes an embedded web control panel out-of-the-box (`/control` endpoint).
+
+## Project Structure
+
+- `src/db/`: The core database engine (storage primitives, RAM caching, query evaluator, auto-compaction and parity management).
+- `src/server/`: The networking boundary. Houses the TCP Socket and HTTP REST servers, as well as the web-based Control Panel.
+- `src/config/`: Configuration schemas for tailoring memory limits, storage thresholds, and cluster layout.
+- `sdk/`: The official `MkDBClient` for programmatic interaction from Python code.
+
+## Getting Started
+
+### Prerequisites
+- Python 3.10+
+- The database storage format is built into MkDB natively, but you'll need the following for advanced data integrity features (Reed-Solomon logic):
+  ```bash
+  pip install reedsolo
+  ```
+
+### Starting the Server
+MkDB operates as a CLI tool. Launch the engine by pointing it to your desired database directory (which must contain a `config.json` file configuring your stores and network bindings):
+```bash
+mkdb /path/to/your/db
+```
+Once running, the database will host both TCP socket and HTTP interfaces as specified in your `config.json`. The web control panel is accessible via your browser (check server output for the bound port, normally `http://localhost:<port>`).
+
+### Using the Python SDK
+The `MkDBClient` connects seamlessly to your database and abstracts the dual-protocol system:
+
+```python
+from sdk.mkdb_client import MkDBClient
+
+client = MkDBClient()
+client.connect(host="127.0.0.1", port=8080)
+
+# Writing a document (computes delta updates intelligently)
+client.set(
+    store="products",
+    record_id="prod_001",
+    data={"name": "Steel Bolt", "price": 9.99, "category": "fasteners"}
+)
+
+# Reading a document
+record = client.get("products", "prod_001")
+
+# Querying with filters
+results = client.query("products", filter={
+    "price": {"<=": 10.00},
+    "category": ["fasteners"]
+})
+```
+
+See the `docs/` folder for comprehensive guides on the Query Syntax and SDK Reference.

pymkdb-0.1.0/pymkdb/__init__.py

@@ -0,0 +1,6 @@
+"""
+PyMkDB — Python client SDK and server package for MkDB.
+"""
+
+__version__ = "0.1.0"
+__author__ = "MNG"

pymkdb-0.1.0/pymkdb/cli.py

@@ -0,0 +1,57 @@
+"""
+pymkdb.cli — console entry point for the `mkdb` command.
+
+Usage:
+    mkdb [PATH_TO_DB]          Start the server pointing at a database directory
+    mkdb [PATH_TO_DB] -c       Generate a default config.json in that directory
+"""
+
+import os
+import sys
+
+
+def main():
+    from colorama import Fore
+    from src.db import mkdb
+    from src.config.db import mkdb_config
+    from src.filing import read_json, write_json
+    from src.runtime import runtime_settings
+
+    print(f"""{Fore.CYAN}
+    ╔═══════════════════════════════════════╗
+    ║                                       ║
+    ║             Initializing              ║
+    ║                 MkDB                  ║
+    ║                                       ║
+    ╚═══════════════════════════════════════╝
+    {Fore.RESET}""")
+
+    try:
+        print("Initialized CWD:", os.getcwd())
+        pointer = sys.argv[1] if len(sys.argv) > 1 else runtime_settings.args.config
+        print("Pointing to:", pointer)
+        print(f"{Fore.CYAN}Reading Config...{Fore.RESET}")
+        if not pointer.endswith(".json"):
+            os.chdir(pointer)
+        CONFIG = read_json(runtime_settings.args.config)
+    except FileNotFoundError:
+        CONFIG = {}
+        if "-c" in sys.argv or "--generate-config" in sys.argv:
+            print(f"{Fore.GREEN}Generating default config file at "
+                  f"{runtime_settings.args.config}{Fore.RESET}")
+            write_json(runtime_settings.args.config, mkdb_config().json)
+            sys.exit(0)
+        print(f"{Fore.YELLOW}Config file not found at {runtime_settings.args.config}")
+        print(f"{Fore.BLUE}Use a path to a db directory or -c to generate a "
+              f"new config.{Fore.RESET}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"{Fore.RED}Error loading config: {e}{Fore.RESET}")
+        sys.exit(1)
+
+    DATA_BASE = mkdb(CONFIG)
+    DATA_BASE.run()
+
+
+if __name__ == "__main__":
+    main()

pymkdb-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "PyMkDB"
+version = "0.1.0"
+description = "A log-structured, partitioned NoSQL database engine with full-text search, numeric indexes, and dual TCP/HTTP protocols."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "MNG" }
+]
+keywords = ["database", "nosql", "document-store", "full-text-search", "log-structured"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+]
+dependencies = [
+    "colorama>=0.4.6",
+    "reedsolo>=1.7.0",
+]
+
+[project.scripts]
+mkdb = "pymkdb.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MNG/MkDB"
+Repository = "https://github.com/MNG/MkDB"
+
+[tool.setuptools.packages.find]
+include = ["pymkdb*", "src*", "sdk*"]

pymkdb-0.1.0/sdk/__init__.py

@@ -0,0 +1 @@
+# MkDB SDK

pymkdb-0.1.0/sdk/connection.py

@@ -0,0 +1,225 @@
+"""
+Low-level persistent TCP connection to a MkDB socket server.
+
+Wire format: 4-byte big-endian uint32 length + UTF-8 JSON payload.
+Mirrors src/server/coms/socket_protocol.py (client-side copy).
+"""
+
+import json
+import socket
+import struct
+import threading
+import uuid
+from typing import Callable, Optional
+
+
+MAX_FRAME = 10 * 1024 * 1024   # 10 MB
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = b""
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            raise ConnectionError("Connection closed")
+        buf += chunk
+    return buf
+
+
+def _encode(payload: dict) -> bytes:
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    return struct.pack(">I", len(body)) + body
+
+
+def _decode(data: bytes) -> dict:
+    return json.loads(data.decode("utf-8"))
+
+
+class Connection:
+    """
+    Thread-safe persistent connection to MkDB.
+
+    Outbound: _send() serialises and writes to socket.
+    Inbound:  background _reader_loop() dispatches to registered handlers.
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 9001,
+                 recv_timeout: float = 30.0,
+                 access: str = "R",
+                 username: str = "",
+                 password: str = ""):
+        self.host         = host
+        self.port         = port
+        self.recv_timeout = recv_timeout
+        self._access      = access.upper() if access.upper() in ("R", "W", "RW") else "R"
+        self._username    = username
+        self._password    = password
+        self._sock: Optional[socket.socket] = None
+        self._lock        = threading.Lock()
+        self._pending: dict[str, threading.Event] = {}     # correlation_id -> Event
+        self._results: dict[str, dict] = {}                # correlation_id -> response dict
+        self._push_handlers: list[Callable[[dict], None]] = []   # for server-push events
+        self._running  = False
+        self.can_read  = False
+        self.can_write = False
+
+    # ------------------------------------------------------------------
+    # Connect / disconnect
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(self.recv_timeout)
+        sock.connect((self.host, self.port))
+
+        # ── Handshake ────────────────────────────────────────────────
+        perm = self._handshake_recv(sock)
+        if perm.get("type") != "permissions":
+            sock.close()
+            raise ConnectionError(f"Expected 'permissions', got: {perm}")
+
+        read_protected  = perm.get("read_protected", False)
+        write_protected = perm.get("write_protected", False)
+
+        # Declare desired access level
+        self._handshake_send(sock, {"access": self._access})
+
+        need_auth = (
+            (self._access in ("W", "RW") and write_protected)
+            or (self._access == "R" and read_protected)
+        )
+
+        if need_auth:
+            challenge = self._handshake_recv(sock)
+            if challenge.get("type") != "auth_required":
+                sock.close()
+                raise ConnectionError(f"Expected 'auth_required', got: {challenge}")
+            if not self._password:
+                sock.close()
+                raise PermissionError("Server requires authentication but no password provided")
+            self._handshake_send(sock, {
+                "type":     "auth",
+                "username": self._username,
+                "password": self._password,
+            })
+            result = self._handshake_recv(sock)
+            if result.get("type") == "error":
+                sock.close()
+                raise PermissionError(result.get("error", "Authentication failed"))
+            if result.get("type") != "auth_ok":
+                sock.close()
+                raise ConnectionError(f"Unexpected handshake response: {result}")
+            self.can_read  = result.get("can_read",  False)
+            self.can_write = result.get("can_write", False)
+        else:
+            ready = self._handshake_recv(sock)
+            if ready.get("type") == "error":
+                sock.close()
+                raise ConnectionError(ready.get("error", "Connection refused"))
+            self.can_read  = ready.get("can_read",  True)
+            self.can_write = ready.get("can_write", False)
+
+        self._sock    = sock
+        self._running = True
+        reader = threading.Thread(
+            target=self._reader_loop, daemon=True, name="MkDB-SDK-reader"
+        )
+        reader.start()
+
+    @staticmethod
+    def _handshake_send(sock: socket.socket, msg: dict) -> None:
+        body = json.dumps(msg).encode("utf-8")
+        sock.sendall(struct.pack(">I", len(body)) + body)
+
+    @staticmethod
+    def _handshake_recv(sock: socket.socket) -> dict:
+        hdr    = _recv_exact(sock, 4)
+        length = struct.unpack(">I", hdr)[0]
+        return json.loads(_recv_exact(sock, length).decode("utf-8"))
+
+    def close(self) -> None:
+        self._running = False
+        if self._sock:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+        self._sock = None
+
+    # ------------------------------------------------------------------
+    # Send / receive
+    # ------------------------------------------------------------------
+
+    def send(self, payload: dict) -> dict:
+        """
+        Send a request and block until the matching response arrives.
+        Returns the response dict.
+        """
+        correlation_id = str(uuid.uuid4())
+        payload["id"] = correlation_id
+        payload.setdefault("type", "request")
+
+        event = threading.Event()
+        with self._lock:
+            self._pending[correlation_id] = event
+
+        frame = _encode(payload)
+        with self._lock:
+            self._sock.sendall(frame)
+
+        event.wait(timeout=self.recv_timeout)
+        with self._lock:
+            result = self._results.pop(correlation_id, None)
+            self._pending.pop(correlation_id, None)
+        if result is None:
+            raise TimeoutError("No response received within timeout")
+        return result
+
+    def send_raw(self, payload: dict) -> None:
+        """Fire-and-forget (used for subscribe)."""
+        frame = _encode(payload)
+        with self._lock:
+            self._sock.sendall(frame)
+
+    def register_push_handler(self, handler: Callable[[dict], None]) -> None:
+        """Register a callback for server-push (ping, update, subscribed, disconnect)."""
+        self._push_handlers.append(handler)
+
+    # ------------------------------------------------------------------
+    # Reader loop (background thread)
+    # ------------------------------------------------------------------
+
+    def _reader_loop(self) -> None:
+        while self._running and self._sock:
+            try:
+                length_bytes = _recv_exact(self._sock, 4)
+                length = struct.unpack(">I", length_bytes)[0]
+                if length > MAX_FRAME:
+                    break   # protocol violation — disconnect
+                payload_bytes = _recv_exact(self._sock, length)
+                msg = _decode(payload_bytes)
+            except Exception:
+                break
+
+            msg_type = msg.get("type")
+            correlation_id = msg.get("id")
+
+            if msg_type == "response" and correlation_id:
+                with self._lock:
+                    event = self._pending.get(correlation_id)
+                    if event:
+                        self._results[correlation_id] = msg
+                        event.set()
+            elif msg_type == "ping":
+                # Respond with pong
+                try:
+                    self._sock.sendall(_encode({"type": "pong"}))
+                except Exception:
+                    break
+            else:
+                # Server-push: dispatch to registered handlers
+                for handler in self._push_handlers:
+                    try:
+                        handler(msg)
+                    except Exception:
+                        pass

pymkdb-0.1.0/sdk/delta.py

@@ -0,0 +1,19 @@
+"""
+Delta helpers — flatten nested dicts into dot-notation keys for MkDB writes.
+
+Example:
+    flatten({"product": {"name": "Widget", "price": 9.99}})
+    # → {"product.name": "Widget", "product.price": 9.99}
+"""
+
+
+def flatten(d: dict, prefix: str = "", sep: str = ".") -> dict:
+    """Recursively flatten a nested dict into dot-notation keys."""
+    result = {}
+    for key, value in d.items():
+        full_key = f"{prefix}{sep}{key}" if prefix else key
+        if isinstance(value, dict):
+            result.update(flatten(value, full_key, sep))
+        else:
+            result[full_key] = value
+    return result