menteedb 0.1.0__tar.gz

menteedb-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: menteedb
+Version: 0.1.0
+Summary: A lightweight local vector-aware database for Python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+
+# menteedb
+
+menteedb is a lightweight local Python library that combines table-like records with optional vector similarity search.
+
+## Features
+
+- Define tables with a schema.
+- Insert structured records.
+- Enable vector search on one text field per table.
+- Add fast text contains search per table.
+- Query by field filters and/or semantic similarity.
+- Persist data locally with append-only files for speed.
+
+## Quick Start
+
+```python
+from menteedb import MenteeDB
+
+db = MenteeDB(base_path="./data")
+
+db.create_table(
+    table_name="notes",
+    fields={"title": "str", "body": "str", "tag": "str"},
+    vector_field="body",
+)
+
+db.insert("notes", {"title": "First", "body": "Vector databases are useful.", "tag": "ml"})
+db.insert("notes", {"title": "Second", "body": "I enjoy local-first tools.", "tag": "dev"})
+
+results = db.query("notes", vector_query="local vector tools", top_k=2)
+for item in results:
+    print(item["score"], item["record"])
+
+text_hits = db.query("notes", text_query="local", text_fields=["body"])
+print(text_hits)
+```
+
+## Query Modes
+
+- Filter-only:
+  - `db.query("notes", conditions={"tag": "ml"})`
+- Text contains search:
+  - `db.query("notes", text_query="vector", text_fields=["title", "body"])`
+- Vector-only:
+  - `db.query("notes", vector_query="your text")`
+- Hybrid (filter + vector):
+  - `db.query("notes", conditions={"tag": "dev"}, vector_query="local tools")`
+
+## Storage Layout
+
+For `base_path="./data"` and table `notes`, menteedb stores:
+
+- `./data/notes/schema.json`
+- `./data/notes/records.jsonl`
+- `./data/notes/vector_ids.jsonl`
+- `./data/notes/vectors.f32`
+
+This is local file-based storage. It is not publicly exposed over the network, but anyone with local filesystem access to this folder can read it.
+
+## Privacy and Permissions
+
+- By default, `MenteeDB(..., secure_permissions=True)` applies best-effort private permissions (`700` for table folders, `600` for files).
+- On Windows, real privacy is controlled by NTFS ACLs; chmod behavior is limited.
+
+## Testing
+
+Run locally:
+
+```bash
+pip install .[dev]
+pytest -q
+```
+
+## CI/CD to PyPI
+
+Workflow file: `.github/workflows/pypi-publish.yml`
+
+- Runs tests on pushes to `main`, tags (`v*`), and releases.
+- Publishes to PyPI on tag push (`v*`) or GitHub Release publish.
+- Uses trusted publishing via GitHub OIDC.
+
+## Notes
+
+- This initial version supports one vector field per table.
+- Default embeddings use a deterministic local hashing embedder with no external model download.

menteedb-0.1.0/README.md

@@ -0,0 +1,85 @@
+# menteedb
+
+menteedb is a lightweight local Python library that combines table-like records with optional vector similarity search.
+
+## Features
+
+- Define tables with a schema.
+- Insert structured records.
+- Enable vector search on one text field per table.
+- Add fast text contains search per table.
+- Query by field filters and/or semantic similarity.
+- Persist data locally with append-only files for speed.
+
+## Quick Start
+
+```python
+from menteedb import MenteeDB
+
+db = MenteeDB(base_path="./data")
+
+db.create_table(
+    table_name="notes",
+    fields={"title": "str", "body": "str", "tag": "str"},
+    vector_field="body",
+)
+
+db.insert("notes", {"title": "First", "body": "Vector databases are useful.", "tag": "ml"})
+db.insert("notes", {"title": "Second", "body": "I enjoy local-first tools.", "tag": "dev"})
+
+results = db.query("notes", vector_query="local vector tools", top_k=2)
+for item in results:
+    print(item["score"], item["record"])
+
+text_hits = db.query("notes", text_query="local", text_fields=["body"])
+print(text_hits)
+```
+
+## Query Modes
+
+- Filter-only:
+  - `db.query("notes", conditions={"tag": "ml"})`
+- Text contains search:
+  - `db.query("notes", text_query="vector", text_fields=["title", "body"])`
+- Vector-only:
+  - `db.query("notes", vector_query="your text")`
+- Hybrid (filter + vector):
+  - `db.query("notes", conditions={"tag": "dev"}, vector_query="local tools")`
+
+## Storage Layout
+
+For `base_path="./data"` and table `notes`, menteedb stores:
+
+- `./data/notes/schema.json`
+- `./data/notes/records.jsonl`
+- `./data/notes/vector_ids.jsonl`
+- `./data/notes/vectors.f32`
+
+This is local file-based storage. It is not publicly exposed over the network, but anyone with local filesystem access to this folder can read it.
+
+## Privacy and Permissions
+
+- By default, `MenteeDB(..., secure_permissions=True)` applies best-effort private permissions (`700` for table folders, `600` for files).
+- On Windows, real privacy is controlled by NTFS ACLs; chmod behavior is limited.
+
+## Testing
+
+Run locally:
+
+```bash
+pip install .[dev]
+pytest -q
+```
+
+## CI/CD to PyPI
+
+Workflow file: `.github/workflows/pypi-publish.yml`
+
+- Runs tests on pushes to `main`, tags (`v*`), and releases.
+- Publishes to PyPI on tag push (`v*`) or GitHub Release publish.
+- Uses trusted publishing via GitHub OIDC.
+
+## Notes
+
+- This initial version supports one vector field per table.
+- Default embeddings use a deterministic local hashing embedder with no external model download.

menteedb-0.1.0/menteedb/__init__.py

@@ -0,0 +1,3 @@
+from .core import MenteeDB
+
+__all__ = ["MenteeDB"]

menteedb-0.1.0/menteedb/core.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import re
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+import numpy as np
+
+from .embeddings import HashingEmbedder
+from .file_handler import (
+    append_record,
+    append_vector,
+    create_table_files,
+    ensure_path,
+    load_schema,
+    load_vectors,
+    read_all_records,
+    table_exists,
+)
+
+
+class MenteeDB:
+    def __init__(
+        self,
+        base_path: str = "./menteedb_data",
+        embedder: Optional[Any] = None,
+        secure_permissions: bool = True,
+    ) -> None:
+        self.base_path = Path(base_path)
+        ensure_path(self.base_path)
+        self.embedder = embedder or HashingEmbedder()
+        self.secure_permissions = secure_permissions
+
+    def create_table(self, table_name: str, fields: Dict[str, str], vector_field: Optional[str] = None) -> Dict[str, Any]:
+        if not table_name or not isinstance(table_name, str):
+            raise ValueError("table_name must be a non-empty string.")
+        if not re.fullmatch(r"[A-Za-z0-9_\-]+", table_name):
+            raise ValueError("table_name may only contain letters, numbers, underscore, and dash.")
+        if not isinstance(fields, dict) or not fields:
+            raise ValueError("fields must be a non-empty dictionary.")
+        if table_exists(self.base_path, table_name):
+            raise ValueError(f"Table '{table_name}' already exists.")
+        if vector_field is not None and vector_field not in fields:
+            raise ValueError("vector_field must be one of the schema field names.")
+
+        embedding_dim = getattr(self.embedder, "dimension", None) if vector_field else None
+        if vector_field and (not isinstance(embedding_dim, int) or embedding_dim <= 0):
+            raise ValueError("Embedder must expose a positive integer 'dimension' attribute when vector_field is enabled.")
+
+        schema = {
+            "table_name": table_name,
+            "fields": fields,
+            "vector_field": vector_field,
+            "embedding_dim": embedding_dim,
+            "version": 1,
+        }
+        create_table_files(self.base_path, table_name, schema, secure_permissions=self.secure_permissions)
+        return {"ok": True, "table": table_name, "vector_field": vector_field}
+
+    def insert(self, table_name: str, record: Dict[str, Any], record_id: Optional[str] = None) -> Dict[str, Any]:
+        schema = load_schema(self.base_path, table_name)
+        fields = schema["fields"]
+
+        if not isinstance(record, dict):
+            raise ValueError("record must be a dictionary.")
+
+        for field_name in fields:
+            if field_name not in record:
+                raise ValueError(f"Missing field '{field_name}' in record.")
+
+        rid = record_id or str(uuid.uuid4())
+        stored = {"_id": rid, **record}
+        append_record(self.base_path, table_name, stored, secure_permissions=self.secure_permissions)
+
+        vector_field = schema.get("vector_field")
+        if vector_field:
+            value = record.get(vector_field)
+            if not isinstance(value, str):
+                raise ValueError(f"vector_field '{vector_field}' must contain string data for embedding.")
+            embedding = self.embedder.encode(value).astype(np.float32)
+            embedding_dim = schema.get("embedding_dim")
+            if embedding_dim is None:
+                embedding_dim = embedding.shape[0]
+            if embedding.shape[0] != embedding_dim:
+                raise ValueError("Embedding dimension does not match table configuration.")
+
+            append_vector(
+                self.base_path,
+                table_name,
+                rid,
+                embedding,
+                secure_permissions=self.secure_permissions,
+            )
+
+        return {"ok": True, "id": rid}
+
+    def query(
+        self,
+        table_name: str,
+        conditions: Optional[Dict[str, Any]] = None,
+        text_query: Optional[str] = None,
+        text_fields: Optional[Sequence[str]] = None,
+        case_sensitive: bool = False,
+        vector_query: Optional[str] = None,
+        top_k: int = 5,
+        min_score: Optional[float] = None,
+    ) -> List[Dict[str, Any]]:
+        schema = load_schema(self.base_path, table_name)
+        rows = read_all_records(self.base_path, table_name)
+
+        if conditions:
+            rows = [r for r in rows if self._record_matches(r, conditions)]
+
+        if text_query is not None:
+            rows = self._text_filter_rows(rows, text_query, text_fields=text_fields, case_sensitive=case_sensitive)
+
+        if vector_query is None:
+            return [{"id": row["_id"], "score": None, "record": row} for row in rows]
+
+        vector_field = schema.get("vector_field")
+        if not vector_field:
+            raise ValueError(f"Table '{table_name}' is not configured for vector search.")
+        if not isinstance(vector_query, str) or not vector_query.strip():
+            raise ValueError("vector_query must be a non-empty string.")
+
+        embedding_dim = schema.get("embedding_dim")
+        ids, vectors = load_vectors(self.base_path, table_name, dimension=embedding_dim)
+        if vectors is None or len(ids) == 0:
+            return []
+
+        query_vec = self.embedder.encode(vector_query).astype(np.float32)
+        if query_vec.shape[0] != vectors.shape[1]:
+            raise ValueError("Query embedding dimension does not match stored vectors.")
+
+        scores = self._cosine_scores(vectors, query_vec)
+        by_id = {row["_id"]: row for row in rows}
+
+        ranked = []
+        for idx, rid in enumerate(ids):
+            row = by_id.get(rid)
+            if row is None:
+                continue
+            score = float(scores[idx])
+            if min_score is not None and score < min_score:
+                continue
+            ranked.append({"id": rid, "score": score, "record": row})
+
+        ranked.sort(key=lambda x: x["score"], reverse=True)
+        return ranked[:top_k]
+
+    @staticmethod
+    def _record_matches(record: Dict[str, Any], conditions: Dict[str, Any]) -> bool:
+        for key, expected in conditions.items():
+            if record.get(key) != expected:
+                return False
+        return True
+
+    @staticmethod
+    def _text_filter_rows(
+        rows: List[Dict[str, Any]],
+        text_query: str,
+        text_fields: Optional[Sequence[str]] = None,
+        case_sensitive: bool = False,
+    ) -> List[Dict[str, Any]]:
+        if not isinstance(text_query, str) or not text_query.strip():
+            raise ValueError("text_query must be a non-empty string when provided.")
+
+        query = text_query if case_sensitive else text_query.lower()
+        selected_fields = list(text_fields) if text_fields is not None else None
+
+        out: List[Dict[str, Any]] = []
+        for row in rows:
+            field_names = selected_fields or [k for k in row.keys() if k != "_id"]
+            haystack_parts: List[str] = []
+            for field_name in field_names:
+                value = row.get(field_name)
+                if isinstance(value, str):
+                    haystack_parts.append(value)
+            haystack = " ".join(haystack_parts)
+            haystack = haystack if case_sensitive else haystack.lower()
+            if query in haystack:
+                out.append(row)
+        return out
+
+    @staticmethod
+    def _cosine_scores(matrix: np.ndarray, query_vector: np.ndarray) -> np.ndarray:
+        matrix_norm = np.linalg.norm(matrix, axis=1)
+        query_norm = np.linalg.norm(query_vector)
+        if query_norm == 0:
+            return np.zeros(matrix.shape[0], dtype=np.float32)
+
+        denom = matrix_norm * query_norm
+        denom = np.where(denom == 0, 1e-12, denom)
+        return (matrix @ query_vector) / denom

menteedb-0.1.0/menteedb/embeddings.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class HashingEmbedder:
+    """Deterministic local embedder based on hashing.
+
+    This keeps the library dependency-light and fully offline.
+    """
+
+    dimension: int = 384
+
+    def encode(self, text: str) -> np.ndarray:
+        if not isinstance(text, str):
+            raise TypeError("Embedding input must be a string.")
+
+        digest = hashlib.sha256(text.encode("utf-8")).digest()
+        seed = int.from_bytes(digest[:8], byteorder="big", signed=False)
+        rng = np.random.default_rng(seed)
+        vec = rng.standard_normal(self.dimension, dtype=np.float32)
+        norm = np.linalg.norm(vec)
+        if norm == 0:
+            return vec
+        return vec / norm

menteedb-0.1.0/menteedb/file_handler.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+
+def ensure_path(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def table_dir(base_path: Path, table_name: str) -> Path:
+    return base_path / table_name
+
+
+def schema_path(base_path: Path, table_name: str) -> Path:
+    return table_dir(base_path, table_name) / "schema.json"
+
+
+def records_path(base_path: Path, table_name: str) -> Path:
+    return table_dir(base_path, table_name) / "records.jsonl"
+
+
+def vectors_path(base_path: Path, table_name: str) -> Path:
+    return table_dir(base_path, table_name) / "vectors.npz"
+
+
+def vectors_bin_path(base_path: Path, table_name: str) -> Path:
+    return table_dir(base_path, table_name) / "vectors.f32"
+
+
+def vector_ids_path(base_path: Path, table_name: str) -> Path:
+    return table_dir(base_path, table_name) / "vector_ids.jsonl"
+
+
+def _apply_private_permissions(path: Path, is_dir: bool) -> None:
+    # Best effort only. On Windows, chmod is limited and ACLs are the real control.
+    try:
+        os.chmod(path, 0o700 if is_dir else 0o600)
+    except OSError:
+        pass
+
+
+def table_exists(base_path: Path, table_name: str) -> bool:
+    return schema_path(base_path, table_name).exists()
+
+
+def create_table_files(base_path: Path, table_name: str, schema: Dict[str, Any], secure_permissions: bool = True) -> None:
+    tdir = table_dir(base_path, table_name)
+    ensure_path(tdir)
+
+    spath = schema_path(base_path, table_name)
+    rpath = records_path(base_path, table_name)
+
+    with spath.open("w", encoding="utf-8") as f:
+        json.dump(schema, f, ensure_ascii=True, indent=2)
+
+    if not rpath.exists():
+        rpath.touch()
+
+    if secure_permissions:
+        _apply_private_permissions(tdir, is_dir=True)
+        _apply_private_permissions(spath, is_dir=False)
+        _apply_private_permissions(rpath, is_dir=False)
+
+
+def load_schema(base_path: Path, table_name: str) -> Dict[str, Any]:
+    spath = schema_path(base_path, table_name)
+    if not spath.exists():
+        raise ValueError(f"Table '{table_name}' does not exist.")
+
+    with spath.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def append_record(base_path: Path, table_name: str, record: Dict[str, Any], secure_permissions: bool = True) -> None:
+    rpath = records_path(base_path, table_name)
+    with rpath.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=True) + "\n")
+    if secure_permissions:
+        _apply_private_permissions(rpath, is_dir=False)
+
+
+def read_all_records(base_path: Path, table_name: str) -> List[Dict[str, Any]]:
+    rpath = records_path(base_path, table_name)
+    if not rpath.exists():
+        return []
+
+    items: List[Dict[str, Any]] = []
+    with rpath.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                items.append(json.loads(line))
+    return items
+
+
+def append_vector(
+    base_path: Path,
+    table_name: str,
+    record_id: str,
+    vector: np.ndarray,
+    secure_permissions: bool = True,
+) -> None:
+    id_path = vector_ids_path(base_path, table_name)
+    bin_path = vectors_bin_path(base_path, table_name)
+
+    with id_path.open("a", encoding="utf-8") as idf:
+        idf.write(json.dumps(record_id, ensure_ascii=True) + "\n")
+
+    vec = vector.astype(np.float32, copy=False)
+    with bin_path.open("ab") as vf:
+        vec.tofile(vf)
+
+    if secure_permissions:
+        _apply_private_permissions(id_path, is_dir=False)
+        _apply_private_permissions(bin_path, is_dir=False)
+
+
+def load_vectors(base_path: Path, table_name: str, dimension: Optional[int] = None) -> Tuple[List[str], Optional[np.ndarray]]:
+    # Backward compatibility with the initial compressed storage format.
+    legacy_vpath = vectors_path(base_path, table_name)
+    if legacy_vpath.exists():
+        data = np.load(legacy_vpath, allow_pickle=True)
+        ids = data["ids"].tolist()
+        vectors = data["vectors"]
+        return ids, vectors
+
+    id_path = vector_ids_path(base_path, table_name)
+    bin_path = vectors_bin_path(base_path, table_name)
+    if not id_path.exists() or not bin_path.exists():
+        return [], None
+
+    ids: List[str] = []
+    with id_path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                ids.append(json.loads(line))
+
+    raw = np.fromfile(bin_path, dtype=np.float32)
+    if not ids:
+        return [], None
+    if dimension is None:
+        raise ValueError("dimension is required for binary vector loading.")
+
+    expected = len(ids) * dimension
+    if raw.size != expected:
+        raise ValueError(
+            f"Corrupt vector storage for table '{table_name}': expected {expected} float32 values, found {raw.size}."
+        )
+
+    return ids, raw.reshape(len(ids), dimension)

menteedb-0.1.0/menteedb.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: menteedb
+Version: 0.1.0
+Summary: A lightweight local vector-aware database for Python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+
+# menteedb
+
+menteedb is a lightweight local Python library that combines table-like records with optional vector similarity search.
+
+## Features
+
+- Define tables with a schema.
+- Insert structured records.
+- Enable vector search on one text field per table.
+- Add fast text contains search per table.
+- Query by field filters and/or semantic similarity.
+- Persist data locally with append-only files for speed.
+
+## Quick Start
+
+```python
+from menteedb import MenteeDB
+
+db = MenteeDB(base_path="./data")
+
+db.create_table(
+    table_name="notes",
+    fields={"title": "str", "body": "str", "tag": "str"},
+    vector_field="body",
+)
+
+db.insert("notes", {"title": "First", "body": "Vector databases are useful.", "tag": "ml"})
+db.insert("notes", {"title": "Second", "body": "I enjoy local-first tools.", "tag": "dev"})
+
+results = db.query("notes", vector_query="local vector tools", top_k=2)
+for item in results:
+    print(item["score"], item["record"])
+
+text_hits = db.query("notes", text_query="local", text_fields=["body"])
+print(text_hits)
+```
+
+## Query Modes
+
+- Filter-only:
+  - `db.query("notes", conditions={"tag": "ml"})`
+- Text contains search:
+  - `db.query("notes", text_query="vector", text_fields=["title", "body"])`
+- Vector-only:
+  - `db.query("notes", vector_query="your text")`
+- Hybrid (filter + vector):
+  - `db.query("notes", conditions={"tag": "dev"}, vector_query="local tools")`
+
+## Storage Layout
+
+For `base_path="./data"` and table `notes`, menteedb stores:
+
+- `./data/notes/schema.json`
+- `./data/notes/records.jsonl`
+- `./data/notes/vector_ids.jsonl`
+- `./data/notes/vectors.f32`
+
+This is local file-based storage. It is not publicly exposed over the network, but anyone with local filesystem access to this folder can read it.
+
+## Privacy and Permissions
+
+- By default, `MenteeDB(..., secure_permissions=True)` applies best-effort private permissions (`700` for table folders, `600` for files).
+- On Windows, real privacy is controlled by NTFS ACLs; chmod behavior is limited.
+
+## Testing
+
+Run locally:
+
+```bash
+pip install .[dev]
+pytest -q
+```
+
+## CI/CD to PyPI
+
+Workflow file: `.github/workflows/pypi-publish.yml`
+
+- Runs tests on pushes to `main`, tags (`v*`), and releases.
+- Publishes to PyPI on tag push (`v*`) or GitHub Release publish.
+- Uses trusted publishing via GitHub OIDC.
+
+## Notes
+
+- This initial version supports one vector field per table.
+- Default embeddings use a deterministic local hashing embedder with no external model download.

menteedb-0.1.0/menteedb.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+./menteedb/__init__.py
+./menteedb/core.py
+./menteedb/embeddings.py
+./menteedb/file_handler.py
+menteedb/__init__.py
+menteedb/core.py
+menteedb/embeddings.py
+menteedb/file_handler.py
+menteedb.egg-info/PKG-INFO
+menteedb.egg-info/SOURCES.txt
+menteedb.egg-info/dependency_links.txt
+menteedb.egg-info/requires.txt
+menteedb.egg-info/top_level.txt
+tests/test_core.py

menteedb-0.1.0/menteedb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

menteedb-0.1.0/menteedb.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=1.24
+
+[dev]
+pytest>=8.0
+build>=1.2

menteedb-0.1.0/menteedb.egg-info/top_level.txt

@@ -0,0 +1 @@
+menteedb

menteedb-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "menteedb"
+version = "0.1.0"
+description = "A lightweight local vector-aware database for Python"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.2",
+]
+
+[tool.setuptools]
+package-dir = {"" = "."}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["menteedb*"]

menteedb-0.1.0/setup.cfg

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

menteedb-0.1.0/tests/test_core.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+from menteedb import MenteeDB
+
+
+def test_create_insert_filter_and_text_query(tmp_path: Path) -> None:
+    db = MenteeDB(base_path=str(tmp_path))
+    db.create_table(
+        table_name="notes",
+        fields={"title": "str", "body": "str", "tag": "str"},
+        vector_field="body",
+    )
+
+    db.insert("notes", {"title": "A", "body": "Vector search is local", "tag": "ml"}, record_id="1")
+    db.insert("notes", {"title": "B", "body": "Fast tiny library", "tag": "dev"}, record_id="2")
+
+    filtered = db.query("notes", conditions={"tag": "dev"})
+    assert len(filtered) == 1
+    assert filtered[0]["id"] == "2"
+
+    text_hits = db.query("notes", text_query="tiny", text_fields=["body"])
+    assert len(text_hits) == 1
+    assert text_hits[0]["id"] == "2"
+
+
+def test_vector_query_returns_ranked_results(tmp_path: Path) -> None:
+    db = MenteeDB(base_path=str(tmp_path))
+    db.create_table(
+        table_name="docs",
+        fields={"title": "str", "body": "str", "tag": "str"},
+        vector_field="body",
+    )
+
+    db.insert("docs", {"title": "One", "body": "cats and pets", "tag": "a"}, record_id="r1")
+    db.insert("docs", {"title": "Two", "body": "dogs and parks", "tag": "b"}, record_id="r2")
+
+    results = db.query("docs", vector_query="pets", top_k=2)
+    assert len(results) == 2
+    assert results[0]["score"] >= results[1]["score"]
+
+
+def test_rejects_invalid_table_name(tmp_path: Path) -> None:
+    db = MenteeDB(base_path=str(tmp_path))
+
+    try:
+        db.create_table("../../bad", fields={"x": "str"})
+        assert False, "Expected ValueError"
+    except ValueError:
+        pass