nio-db-py 1.0.1__tar.gz

nio_db_py-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nio Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE 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
+AUTHORS OR COPYRIGHT HOLDERS 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nio_db_py-1.0.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: nio-db-py
+Version: 1.0.1
+Summary: Ultra-lightweight Python client for NioDB (The Agentic Database)
+Author: Nio Labs
+License: MIT
+Keywords: niodb,database,ai-agents,vector-search,sqlite,rag
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# nio-db-py
+
+Ultra-lightweight Python client SDK for **NioDB** — the Agentic Database.
+
+- **Zero dependencies** (uses Python standard library `urllib`)
+- **Fast and typed**
+- **Compatible with Python >= 3.8**
+
+---
+
+## Installation
+
+```bash
+pip install nio-db-py
+```
+
+---
+
+## Quickstart
+
+```python
+from niodb import NioDB
+
+db = NioDB(url="http://127.0.0.1:7432", token="client-token")
+
+# 1. Insert & Query Documents
+db.collection("tasks").insert({
+    "title": "Fix auth race condition",
+    "status": "pending",
+    "ttl": 3600  # 1 hour auto-expiry
+})
+
+records = db.collection("tasks").find(limit=10)
+
+# 2. Pure-Rust Vector Similarity Search
+results = db.collection("knowledge").search_vector(
+    vector=[0.012, -0.045, 0.089, ...],
+    top_k=5,
+    min_score=0.75
+)
+
+# 3. Multi-Agent Sessions
+session = db.session("session_104")
+session.append_turn(
+    agent="claude",
+    model="claude-3-7-sonnet",
+    summary="Refactored database pool",
+    cost_usd=0.012
+)
+
+manifest = session.get_manifest()
+print(manifest["manifest_text"])
+
+# 4. Safe SQL Queries
+sql_data = db.query("SELECT * FROM tasks WHERE status = 'pending'")
+```

nio_db_py-1.0.1/README.md

@@ -0,0 +1,56 @@
+# nio-db-py
+
+Ultra-lightweight Python client SDK for **NioDB** — the Agentic Database.
+
+- **Zero dependencies** (uses Python standard library `urllib`)
+- **Fast and typed**
+- **Compatible with Python >= 3.8**
+
+---
+
+## Installation
+
+```bash
+pip install nio-db-py
+```
+
+---
+
+## Quickstart
+
+```python
+from niodb import NioDB
+
+db = NioDB(url="http://127.0.0.1:7432", token="client-token")
+
+# 1. Insert & Query Documents
+db.collection("tasks").insert({
+    "title": "Fix auth race condition",
+    "status": "pending",
+    "ttl": 3600  # 1 hour auto-expiry
+})
+
+records = db.collection("tasks").find(limit=10)
+
+# 2. Pure-Rust Vector Similarity Search
+results = db.collection("knowledge").search_vector(
+    vector=[0.012, -0.045, 0.089, ...],
+    top_k=5,
+    min_score=0.75
+)
+
+# 3. Multi-Agent Sessions
+session = db.session("session_104")
+session.append_turn(
+    agent="claude",
+    model="claude-3-7-sonnet",
+    summary="Refactored database pool",
+    cost_usd=0.012
+)
+
+manifest = session.get_manifest()
+print(manifest["manifest_text"])
+
+# 4. Safe SQL Queries
+sql_data = db.query("SELECT * FROM tasks WHERE status = 'pending'")
+```

nio_db_py-1.0.1/nio_db_py.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: nio-db-py
+Version: 1.0.1
+Summary: Ultra-lightweight Python client for NioDB (The Agentic Database)
+Author: Nio Labs
+License: MIT
+Keywords: niodb,database,ai-agents,vector-search,sqlite,rag
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# nio-db-py
+
+Ultra-lightweight Python client SDK for **NioDB** — the Agentic Database.
+
+- **Zero dependencies** (uses Python standard library `urllib`)
+- **Fast and typed**
+- **Compatible with Python >= 3.8**
+
+---
+
+## Installation
+
+```bash
+pip install nio-db-py
+```
+
+---
+
+## Quickstart
+
+```python
+from niodb import NioDB
+
+db = NioDB(url="http://127.0.0.1:7432", token="client-token")
+
+# 1. Insert & Query Documents
+db.collection("tasks").insert({
+    "title": "Fix auth race condition",
+    "status": "pending",
+    "ttl": 3600  # 1 hour auto-expiry
+})
+
+records = db.collection("tasks").find(limit=10)
+
+# 2. Pure-Rust Vector Similarity Search
+results = db.collection("knowledge").search_vector(
+    vector=[0.012, -0.045, 0.089, ...],
+    top_k=5,
+    min_score=0.75
+)
+
+# 3. Multi-Agent Sessions
+session = db.session("session_104")
+session.append_turn(
+    agent="claude",
+    model="claude-3-7-sonnet",
+    summary="Refactored database pool",
+    cost_usd=0.012
+)
+
+manifest = session.get_manifest()
+print(manifest["manifest_text"])
+
+# 4. Safe SQL Queries
+sql_data = db.query("SELECT * FROM tasks WHERE status = 'pending'")
+```

nio_db_py-1.0.1/nio_db_py.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+nio_db_py.egg-info/PKG-INFO
+nio_db_py.egg-info/SOURCES.txt
+nio_db_py.egg-info/dependency_links.txt
+nio_db_py.egg-info/top_level.txt
+niodb/__init__.py
+niodb/client.py
+tests/test_client.py

nio_db_py-1.0.1/nio_db_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nio_db_py-1.0.1/nio_db_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+niodb

nio_db_py-1.0.1/niodb/__init__.py

@@ -0,0 +1,9 @@
+"""
+nio-db-py — Lightweight Python SDK for NioDB (The Agentic Database)
+"""
+
+from .client import NioDB, NioDBError, Collection, Session, Sessions, Tasks
+
+__all__ = ["NioDB", "NioDBError", "Collection", "Session", "Sessions", "Tasks"]
+__version__ = "0.1.1"
+

nio_db_py-1.0.1/niodb/client.py

@@ -0,0 +1,284 @@
+"""
+NioDB Python Client SDK — Zero-dependency Python wrapper for NioDB.
+"""
+
+import json
+import urllib.request
+import urllib.error
+from typing import Any, Dict, List, Optional, Union
+
+class NioDBError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None, data: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.data = data
+
+
+class Collection:
+    def __init__(self, client: "NioDB", name: str):
+        self._client = client
+        self.name = name
+
+    def insert(self, data: Dict[str, Any], ttl: Optional[int] = None, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        payload = {"collection": self.name, "data": dict(data)}
+        if ttl is not None:
+            payload["data"]["ttl"] = ttl
+        headers = {}
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        return self._client._request("/api/v1/records", method="POST", body=payload, extra_headers=headers)
+
+    def find(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        path = f"/api/v1/records?type={urllib.parse.quote(self.name)}"
+        if limit is not None:
+            path += f"&limit={limit}"
+        if cursor is not None:
+            path += f"&cursor={urllib.parse.quote(cursor)}"
+        return self._client._request(path, method="GET")
+
+    def get(self, record_id: str) -> Dict[str, Any]:
+        return self._client._request(f"/api/v1/records/{urllib.parse.quote(record_id)}", method="GET")
+
+    def update(self, record_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        payload = data if "data" in data else {"data": data}
+        return self._client._request(f"/api/v1/records/{urllib.parse.quote(record_id)}", method="PATCH", body=payload)
+
+    def delete(self, record_id: str) -> Dict[str, Any]:
+        return self._client._request(f"/api/v1/records/{urllib.parse.quote(record_id)}", method="DELETE")
+
+    def insert_many(self, records: List[Dict[str, Any]]) -> Dict[str, Any]:
+        formatted = []
+        for r in records:
+            if "data" in r:
+                formatted.append(r)
+            else:
+                formatted.append({"collection": self.name, "data": r})
+        payload = {
+            "collection": self.name,
+            "action": "insert",
+            "records": formatted
+        }
+        return self._client._request("/api/v1/records/bulk", method="POST", body=payload)
+
+    def bulk_insert(self, records: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return self.insert_many(records)
+
+    def update_many(self, records: List[Dict[str, Any]]) -> Dict[str, Any]:
+        formatted = []
+        for r in records:
+            rec_id = r.get("id") or r.get("record_id")
+            data = r.get("data") if "data" in r else r
+            formatted.append({"id": rec_id, "data": data})
+        payload = {
+            "action": "update",
+            "records": formatted
+        }
+        return self._client._request("/api/v1/records/bulk", method="POST", body=payload)
+
+    def bulk_update(self, records: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return self.update_many(records)
+
+    def delete_many(self, ids: List[Union[str, Dict[str, Any]]]) -> Dict[str, Any]:
+        formatted_ids = []
+        for item in ids:
+            if isinstance(item, dict):
+                rec_id = item.get("id") or item.get("record_id")
+                if rec_id:
+                    formatted_ids.append(rec_id)
+            else:
+                formatted_ids.append(str(item))
+        payload = {
+            "action": "delete",
+            "ids": formatted_ids
+        }
+        return self._client._request("/api/v1/records/bulk", method="POST", body=payload)
+
+    def bulk_delete(self, ids: List[Union[str, Dict[str, Any]]]) -> Dict[str, Any]:
+        return self.delete_many(ids)
+
+    def search_vector(self, vector: List[float], top_k: int = 5, min_score: float = 0.0) -> Dict[str, Any]:
+        payload = {
+            "collection": self.name,
+            "vector": vector,
+            "top_k": top_k,
+            "min_score": min_score
+        }
+        return self._client._request("/api/v1/records/search", method="POST", body=payload)
+
+
+class Session:
+    def __init__(self, client: "NioDB", session_id: str):
+        self._client = client
+        self.session_id = session_id
+
+    def create(self, title: str, goal: str = "", model_tier: str = "strong", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        payload = {
+            "title": title,
+            "goal": goal,
+            "model_tier": model_tier,
+            "metadata": metadata or {}
+        }
+        return self._client._request("/api/v1/sessions", method="POST", body=payload)
+
+    def get(self) -> Dict[str, Any]:
+        return self._client._request(f"/api/v1/sessions/{urllib.parse.quote(self.session_id)}", method="GET")
+
+    def append_turn(
+        self,
+        agent: str,
+        model: str,
+        summary: str = "",
+        files_touched: Optional[List[str]] = None,
+        tokens: Optional[Dict[str, Any]] = None,
+        cost_usd: float = 0.0
+    ) -> Dict[str, Any]:
+        payload = {
+            "agent": agent,
+            "model": model,
+            "summary": summary,
+            "files_touched": files_touched or [],
+            "tokens": tokens,
+            "cost_usd": cost_usd
+        }
+        return self._client._request(f"/api/v1/sessions/{urllib.parse.quote(self.session_id)}/turns", method="POST", body=payload)
+
+    def get_manifest(self) -> Dict[str, Any]:
+        return self._client._request(f"/api/v1/sessions/{urllib.parse.quote(self.session_id)}/manifest", method="GET")
+
+    def log_dead_end(self, hypothesis: str, reason: str, agent: str = "unknown") -> Dict[str, Any]:
+        payload = {
+            "hypothesis": hypothesis,
+            "reason": reason,
+            "agent": agent
+        }
+        return self._client._request(f"/api/v1/sessions/{urllib.parse.quote(self.session_id)}/dead-ends", method="POST", body=payload)
+
+    def get_dead_ends(self) -> Dict[str, Any]:
+        return self._client._request(f"/api/v1/sessions/{urllib.parse.quote(self.session_id)}/dead-ends", method="GET")
+
+
+class Sessions:
+    def __init__(self, client: "NioDB"):
+        self._client = client
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("/api/v1/sessions", method="GET")
+
+    def create(self, title: str, goal: str = "", model_tier: str = "strong", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        payload = {
+            "title": title,
+            "goal": goal,
+            "model_tier": model_tier,
+            "metadata": metadata or {}
+        }
+        return self._client._request("/api/v1/sessions", method="POST", body=payload)
+
+    def get(self, session_id: str) -> Session:
+        return Session(self._client, session_id)
+
+
+class Tasks:
+    def __init__(self, client: "NioDB"):
+        self._client = client
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("/api/v1/tasks", method="GET")
+
+    def create(self, title: str, prompt: str, priority: str = "normal", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        payload = {
+            "title": title,
+            "prompt": prompt,
+            "priority": priority,
+            "metadata": metadata or {}
+        }
+        return self._client._request("/api/v1/tasks", method="POST", body=payload)
+
+    def get(self, task_id: str) -> Dict[str, Any]:
+        return self._client._request(f"/api/v1/tasks/{urllib.parse.quote(task_id)}", method="GET")
+
+    def update(self, task_id: str, status: Optional[str] = None, progress: Optional[int] = None, log_line: Optional[str] = None, result: Any = None) -> Dict[str, Any]:
+        payload = {}
+        if status is not None: payload["status"] = status
+        if progress is not None: payload["progress"] = progress
+        if log_line is not None: payload["log_line"] = log_line
+        if result is not None: payload["result"] = result
+        return self._client._request(f"/api/v1/tasks/{urllib.parse.quote(task_id)}", method="PATCH", body=payload)
+
+
+class NioDB:
+    def __init__(self, url: str = "http://127.0.0.1:7432", token: Optional[str] = None, client_token: Optional[str] = None, secret_token: Optional[str] = None, workspace_id: Optional[str] = None):
+        self.url = url.rstrip("/")
+        if token:
+            self.token = token
+        elif client_token and secret_token:
+            self.token = f"{client_token}:{secret_token}"
+        elif client_token or secret_token:
+            self.token = client_token or secret_token
+        else:
+            self.token = None
+        self.workspace_id = workspace_id
+        self.sessions = Sessions(self)
+        self.tasks = Tasks(self)
+
+    def _request(self, path: str, method: str = "GET", body: Optional[Dict[str, Any]] = None, extra_headers: Optional[Dict[str, str]] = None) -> Any:
+        url = f"{self.url}{path}"
+        if self.workspace_id and "workspace_id=" not in url:
+            sep = "&" if "?" in url else "?"
+            url += f"{sep}workspace_id={urllib.parse.quote(self.workspace_id)}"
+
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": "nio-db-py/0.1.1"
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        data_bytes = None
+        if body is not None and method != "GET":
+            headers["Content-Type"] = "application/json"
+            data_bytes = json.dumps(body).encode("utf-8")
+
+        req = urllib.request.Request(url, data=data_bytes, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req) as resp:
+                if resp.status == 204:
+                    return None
+                resp_bytes = resp.read()
+                if not resp_bytes:
+                    return {}
+                return json.loads(resp_bytes.decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            try:
+                err_data = json.loads(e.read().decode("utf-8"))
+                msg = err_data.get("error", {}).get("message", str(e))
+            except Exception:
+                err_data = None
+                msg = str(e)
+            raise NioDBError(msg, status_code=e.code, data=err_data) from e
+        except urllib.error.URLError as e:
+            raise NioDBError(f"Connection failed: {e}") from e
+
+    def collection(self, name: str) -> Collection:
+        return Collection(self, name)
+
+    def session(self, session_id: str) -> Session:
+        return Session(self, session_id)
+
+    def bulk(self, operations: Union[List[Dict[str, Any]], Dict[str, Any]]) -> Dict[str, Any]:
+        if isinstance(operations, list):
+            payload = {"operations": operations}
+        else:
+            payload = operations
+        return self._request("/api/v1/records/bulk", method="POST", body=payload)
+
+    def query(self, sql: str) -> Dict[str, Any]:
+        return self._request("/api/v1/query", method="POST", body={"sql": sql})
+
+    def vacuum(self) -> Dict[str, Any]:
+        return self._request("/api/v1/admin/vacuum", method="POST", body={})
+
+    def get_tools(self) -> Dict[str, Any]:
+        return self._request("/api/v1/agent/tools", method="GET")

nio_db_py-1.0.1/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nio-db-py"
+version = "1.0.1"
+description = "Ultra-lightweight Python client for NioDB (The Agentic Database)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["niodb", "database", "ai-agents", "vector-search", "sqlite", "rag"]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["niodb*"]

nio_db_py-1.0.1/setup.cfg

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

nio_db_py-1.0.1/setup.py

@@ -0,0 +1,18 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="nio-db-py",
+    version="1.0.1",
+    description="Ultra-lightweight Python client for NioDB (The Agentic Database)",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="Nio Labs",
+    license="MIT",
+    packages=find_packages(exclude=["tests*"]),
+    python_requires=">=3.8",
+    keywords=["niodb", "database", "ai-agents", "vector-search", "sqlite", "rag"],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+)

nio_db_py-1.0.1/tests/test_client.py

@@ -0,0 +1,189 @@
+import unittest
+import json
+import threading
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import sys
+import os
+
+# Add package dir to sys.path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+from niodb import NioDB, NioDBError
+
+
+class MockNioDBHandler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+
+        if "/manifest" in self.path:
+            self.wfile.write(json.dumps({"session_id": "s1", "manifest_text": "Manifest ok"}).encode("utf-8"))
+        elif "/dead-ends" in self.path:
+            self.wfile.write(json.dumps({"session_id": "s1", "dead_ends": [{"hypothesis": "test"}], "count": 1}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/sessions"):
+            self.wfile.write(json.dumps({"items": [{"id": "s1"}], "count": 1}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/tasks/task_1"):
+            self.wfile.write(json.dumps({"id": "task_1", "status": "pending"}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/tasks"):
+            self.wfile.write(json.dumps({"items": [{"id": "task_1"}], "count": 1}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/agent/tools"):
+            self.wfile.write(json.dumps({"tools": [{"name": "query_database"}]}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/records/rec_1"):
+            self.wfile.write(json.dumps({"id": "rec_1", "data": {"key": "value"}}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/records"):
+            self.wfile.write(json.dumps({"items": [{"id": "rec_1"}], "count": 1}).encode("utf-8"))
+        else:
+            self.wfile.write(json.dumps({"status": "ok"}).encode("utf-8"))
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length).decode("utf-8")) if length > 0 else {}
+
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+
+        if self.path.startswith("/api/v1/records/search"):
+            self.wfile.write(json.dumps({"items": [{"id": "rec_1", "score": 0.99}], "count": 1}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/records/bulk"):
+            act = body.get("action", "insert")
+            recs = body.get("records", [])
+            ids = body.get("ids", [])
+            self.wfile.write(json.dumps({
+                "success": True,
+                "inserted": len(recs) if act == "insert" else 0,
+                "updated": len(recs) if act == "update" else 0,
+                "deleted": len(ids) if act == "delete" else 0,
+                "records": recs,
+                "deleted_ids": ids
+            }).encode("utf-8"))
+        elif self.path.startswith("/api/v1/records"):
+            self.wfile.write(json.dumps({"id": "rec_new", **body}).encode("utf-8"))
+        elif "/turns" in self.path:
+            self.wfile.write(json.dumps({"success": True, "session_id": "s1", "turn": body}).encode("utf-8"))
+        elif "/dead-ends" in self.path:
+            self.wfile.write(json.dumps({"success": True, "count": 1}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/sessions"):
+            self.wfile.write(json.dumps({"id": "s1", "title": body.get("title", "")}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/tasks"):
+            self.wfile.write(json.dumps({"id": "task_1", **body}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/admin/vacuum"):
+            self.wfile.write(json.dumps({"success": True, "stats": {"compacted_bytes": 500}}).encode("utf-8"))
+        elif self.path.startswith("/api/v1/query"):
+            self.wfile.write(json.dumps({"items": [{"cnt": 10}]}).encode("utf-8"))
+        else:
+            self.wfile.write(json.dumps({"status": "ok"}).encode("utf-8"))
+
+    def do_PATCH(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length).decode("utf-8")) if length > 0 else {}
+
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps({"id": "task_1", **body}).encode("utf-8"))
+
+    def do_DELETE(self):
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps({"success": True, "deleted": True, "id": "rec_1"}).encode("utf-8"))
+
+    def log_message(self, format, *args):
+        pass  # Quiet logger
+
+
+class TestNioDBPy(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), MockNioDBHandler)
+        cls.port = cls.server.server_port
+        cls.server_thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.server_thread.start()
+        cls.client = NioDB(f"http://127.0.0.1:{cls.port}", token="tok-123", workspace_id="ws-py")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def test_collection_crud_and_vector(self):
+        c_comb = NioDB("http://127.0.0.1:7432", client_token="cli-py", secret_token="sec-py")
+        self.assertEqual(c_comb.token, "cli-py:sec-py")
+
+        col = self.client.collection("memories")
+        inserted = col.insert({"text": "python test"}, ttl=300)
+        self.assertEqual(inserted["id"], "rec_new")
+        self.assertEqual(inserted["data"]["ttl"], 300)
+
+        found = col.find(limit=5)
+        self.assertEqual(found["count"], 1)
+
+        rec = col.get("rec_1")
+        self.assertEqual(rec["id"], "rec_1")
+
+        updated = col.update("rec_1", {"key": "val2"})
+        self.assertEqual(updated["id"], "task_1")
+
+        deleted = col.delete("rec_1")
+        self.assertTrue(deleted["success"])
+
+        bulk_ins = col.insert_many([{"text": "a"}, {"text": "b"}])
+        self.assertEqual(bulk_ins["inserted"], 2)
+
+        bulk_upd = col.update_many([{"id": "rec_1", "text": "a2"}])
+        self.assertEqual(bulk_upd["updated"], 1)
+
+        bulk_del = col.delete_many(["rec_1", "rec_2"])
+        self.assertEqual(bulk_del["deleted"], 2)
+
+        bulk_all = self.client.bulk([{"action": "insert", "collection": "test", "data": {}}])
+        self.assertTrue(bulk_all["success"])
+
+        search_res = col.search_vector([0.1, 0.2, 0.3], top_k=3)
+        self.assertEqual(search_res["count"], 1)
+        self.assertEqual(search_res["items"][0]["score"], 0.99)
+
+    def test_sessions_and_dead_ends(self):
+        sess = self.client.sessions.create("Py Task", goal="Test python client")
+        self.assertEqual(sess["id"], "s1")
+
+        sessions_list = self.client.sessions.list()
+        self.assertEqual(sessions_list["count"], 1)
+
+        s1 = self.client.session("s1")
+        turn_res = s1.append_turn(agent="worker", model="gpt-4o", summary="Completed step")
+        self.assertTrue(turn_res["success"])
+
+        manifest = s1.get_manifest()
+        self.assertEqual(manifest["manifest_text"], "Manifest ok")
+
+        dead_end_res = s1.log_dead_end(hypothesis="hypothesis 1", reason="failed validation")
+        self.assertTrue(dead_end_res["success"])
+
+        dead_ends = s1.get_dead_ends()
+        self.assertEqual(dead_ends["count"], 1)
+
+    def test_tasks_and_admin(self):
+        task = self.client.tasks.create("Run py workflow", prompt="Execute job")
+        self.assertEqual(task["id"], "task_1")
+
+        tasks_list = self.client.tasks.list()
+        self.assertEqual(tasks_list["count"], 1)
+
+        updated = self.client.tasks.update("task_1", status="running", progress=75)
+        self.assertEqual(updated["status"], "running")
+        self.assertEqual(updated["progress"], 75)
+
+        query_res = self.client.query("SELECT COUNT(*) FROM artifacts")
+        self.assertEqual(query_res["items"][0]["cnt"], 10)
+
+        vac_res = self.client.vacuum()
+        self.assertTrue(vac_res["success"])
+
+        tools = self.client.get_tools()
+        self.assertEqual(len(tools["tools"]), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()