nedb-engine 2.7.2__tar.gz → 2.8.1__tar.gz

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nedb-engine
-Version: 2.7.2
+Version: 2.8.1
 Summary: NEDB — a versioned, self-compressing, time-traveling embedded database (replay-protected, idempotent, relational, searchable) with durable AOF persistence and a server daemon (nedbd).
 Project-URL: Homepage, https://github.com/aiassistsecure/nedb
 Project-URL: Repository, https://github.com/aiassistsecure/nedb
@@ -41,9 +41,29 @@ One Rust core → ships to **PyPI** and **npm** from a single source.
 
 ---
 
-## NEDB v2.5.34 — Production Stable
+## NEDB v2.8.0 — Production Stable
 
-**Current stable: 2.5.34** — NEDB ships as **three version-aligned distributions** on one tag — `nedb-engine` (flagship), `crypto-database` (verifiable v2/v3 DAG), and `aof-db` (fast append-only) — across npm / PyPI / crates.io with full mac + linux + windows native addons (see [**Releasing**](#releasing) below). On the engine side it remains a polish release on the complete cross-platform line. The `nedbd-v2` daemon now does **real CLI parsing** — `--dag-v3`, `--data`, `--fast-fsync`, `--help`, `--version` are recognized flags instead of being silently swallowed as the positional data dir — and `npm test` ships a **cinematic native smoke test** that tours v1→v2 migration, the v2 DAG, the v3 segment store, and a causal-provenance audit. All native wheels (Linux + Windows on GitHub Actions; macOS arm64 + x86_64 on Codemagic M2 Mac Minis) **plus** the universal pure-Python wheel ship from a single `v*` tag, with the `nedbd-v2` binary bundled inside `pip install nedb-engine`.
+**Current stable: 2.8.0** — NEDB ships as **three version-aligned distributions** on one tag — `nedb-engine` (flagship), `crypto-database` (verifiable v2/v3 DAG), and `aof-db` (fast append-only) — across npm / PyPI / crates.io with full mac + linux + windows native addons (see [**Releasing**](#releasing) below). All native wheels (Linux + Windows on GitHub Actions; macOS arm64 + x86_64 on Codemagic M2 Mac Minis) **plus** the universal pure-Python wheel ship from a single `v*` tag, with the `nedbd-v2` binary bundled inside `pip install nedb-engine`.
+
+### New in 2.8.0 — Cast: the database understands English
+
+`POST /v1/databases/<name>/cast` turns a short English prompt into NQL, using a **3.33M-parameter model that runs locally on CPU**. No API key, no network call, no per-token bill.
+
+```bash
+nedbd --dag --cast ./data     # requires: cargo install nedb-engine --features cast
+
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -d '{"prompt":"orders over 100"}'
+# → {"nql":"FROM orders WHERE total > 100","valid":true,"collection_known":true,"executed":false}
+```
+
+The model ([**nedb-cast-slm**](https://github.com/aiassistsecure/nedb-cast-slm)) was trained on NQL using NEDB's own parser as generator, grader, and gate — then shipped to PyPI, crates.io, and npm, all three loading the identical weights.
+
+**Why it lives in the engine and not in a client:** the hard part of natural-language querying is knowing the schema, and the engine already holds the live collection list. A plan naming a collection that doesn't exist returns **422 with the reason**, never a silently empty result set. See [**Cast**](#cast--natural-language-into-nql) below.
+
+Off by default — feature-gated at compile time, flag-gated at runtime, and `execute` defaults to `false` so you review the plan before it runs.
+
+**Also in 2.8.0 — an engine bug the feature exposed.** `IdIndex::collections()` did a bare `read_dir` while every other read path overlaid the WAL write buffer, so a brand-new collection was invisible until the 1s flush ticker fired. Unreachable by hand (the ticker fires between keystrokes) but reliable from a script, and latent in `Db::compact()` too, where a missed collection's live objects would be reclaimed as garbage. Fixed, with regression tests that seed *without* flushing.
 
 **New in 2.5.x:**
 
@@ -325,6 +345,8 @@ Alongside the daemon, `cargo install nedb-engine` ships **`nedb-cli`** — opera
 | `NEDBD_TOKEN` | unset | Optional bearer token; required on every `/v1/*` request when set. |
 | `NEDB_TMK` | unset | 32-byte hex AES-256-GCM at-rest encryption key. |
 | `NEDBD_DATA` | `./nedb-data` | Root directory. v2 creates `dag/`, IdIndex sharded across **256 subdirectories**, and a small `MANIFEST` file. |
+| `NEDBD_CAST` | `0` | Set `1` to enable the `/cast` natural-language planner. Same as `--cast`. Requires a build with `--features cast`. See [**Cast**](#cast--natural-language-into-nql). |
+| `NEDBD_CAST_MODEL` | unset | Explicit path to a `model.cast` container. Otherwise searched in the data dir, `$CAST_HOME`, and `~/.cache/nedb-cast-slm/`. |
 
 ```bash
 # Create a database with seed data and relations
@@ -381,6 +403,127 @@ db.query('FROM policy AS OF 200 VALID AS OF "2024-02-15"')
 
 ---
 
+## Cast — natural language into NQL
+
+*New in 2.8.0. Optional, feature-gated, off by default.*
+
+Ten clauses and six operators. That's the whole grammar above — small enough that a **3.33M-parameter** model can learn it completely, and small enough that shipping every query to a frontier model is an absurd amount of machinery.
+
+So we trained one. It runs on CPU, in-process, in milliseconds.
+
+```bash
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"orders over 100"}'
+```
+
+```json
+{
+  "prompt": "orders over 100",
+  "nql": "FROM orders WHERE total > 100",
+  "valid": true,
+  "collection": "orders",
+  "collection_known": true,
+  "collections": ["orders"],
+  "executed": false,
+  "seq": 3,
+  "head": "262fd9…"
+}
+```
+
+### NEDB is on both ends of this
+
+The model is [**nedb-cast-slm**](https://github.com/aiassistsecure/nedb-cast-slm), and NEDB built it as much as it consumes it.
+
+**NEDB's parser was the training pipeline.** It generated the corpus (sample a random plan → render NQL → render a human paraphrase; 200,000 pairs in 16.5 seconds, perfect labels, zero annotation cost). It was the grader — scoring *parsed plan* equality, not string equality, so `FROM orders WHERE total > 99` and `from orders where total>99` both earn full credit. And it was the gate: no example entered the corpus unless it round-tripped through the real parser to a canonically identical plan.
+
+> Most text-to-DSL projects hand-write a verifier and hope it's right. We didn't write one — it already shipped, and it's the same code the database runs in production.
+
+**Training lineage lives in NEDB too**, chained by `caused_by`:
+
+```
+datasets ──▶ training_runs ──▶ checkpoints ──▶ evals
+```
+
+```python
+db.query("FROM evals TRACE caused_by")   # the exact data behind any score
+```
+
+### Why the planner lives in the engine
+
+The hard part of natural-language querying is not the model. It's the **schema** — and a client has to fetch the collection list and pass it in, where it's stale on arrival. The engine already holds the live list.
+
+So the plan is checked against collections that actually exist, at the moment of the call:
+
+```json
+{ "prompt": "show me all stylists",
+  "nql": "FROM stylists",
+  "valid": true,
+  "collection_known": false,
+  "error": "collection \"stylists\" does not exist in \"shop\"" }
+```
+
+HTTP **422**. Not zero rows — zero rows reads as *"no matching data"*, which would be a lie. The query was perfectly well-formed; the collection was imagined. That's the model's known failure mode on an unfamiliar schema, and the engine is the one component positioned to catch it.
+
+Every `nedbd` client — Python, Node, Studio, `curl` — inherits this without writing a line.
+
+### Three safety properties
+
+| | |
+|---|---|
+| **The model never executes** | It emits text. The text goes to the same `nql::query` path a hand-typed query uses. No second executor exists to audit. |
+| **Validation is parsing** | `nql::parse` and `nql::execute` share one code path, so they cannot disagree about what is well-formed. Invalid output returns 422 *with the offending text*. |
+| **`execute` defaults to false** | You get a plan for review. Running a guess silently is worse than admitting uncertainty. |
+
+That last default earns its keep. A real miss, from a real run:
+
+```
+prompt   "paid orders over 100"
+nql      FROM orders WHERE status = "paid" LIMIT 100      ← wrong
+correct  FROM orders WHERE status = "paid" AND total > 100
+```
+
+It read *"over 100"* as `LIMIT 100` and dropped the predicate. The count still came back **2** — because both paid orders happened to exceed 100. A count-only assertion would have scored it a pass. A human reading `LIMIT 100` catches it in a heartbeat; an auto-executing client does not.
+
+Multi-predicate `WHERE` is the model's weakest clause: **85.1%** exact-plan match on eval, 61.2% on adversarial holdout. The [model card](https://github.com/aiassistsecure/nedb-cast-slm#what-it-gets-wrong) documents every failure mode with examples.
+
+To run it anyway, ask:
+
+```bash
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -d '{"prompt":"orders over 100","execute":true}'
+# → { …, "executed": true, "count": 2, "rows": [ … ] }
+```
+
+### Enabling it
+
+Two gates, because most deployments want neither the model dependency nor the weights:
+
+```bash
+# compile-time
+cargo install nedb-engine --features cast
+
+# weights (~13 MB) — GitHub release asset, checksum-verified on load
+curl -L -o ./data/model.cast \
+  https://github.com/aiassistsecure/nedb-cast-slm/releases/download/v10.30.90/model.cast
+
+# runtime
+nedbd --dag --cast ./data
+#   cast     enabled — 3.33M params, vocab 581, ./data/model.cast
+```
+
+Search order: `$NEDBD_CAST_MODEL` → `<data_dir>/model.cast` → `$CAST_HOME/model.cast` → `~/.cache/nedb-cast-slm/v10.30.90/model.cast` (the Python/npm cache location, so a machine that has run either package is already ready).
+
+Built without the feature, the route returns **501** rather than 404 — clients can detect the capability instead of guessing. Built with it but missing weights, the daemon logs loudly and serves everything else normally.
+
+**Verify the whole path:**
+
+```bash
+./scripts/test-cast.sh --boot     # boots a daemon, seeds, casts, executes, checks failure modes
+```
+
+---
+
 ## Performance
 
 **v2 DAG Rust server (v2.2.31, Intel iMac — 10k writes / 100k reads / 30k objects, AES-256-GCM on):**

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/README.md

@@ -20,9 +20,29 @@ One Rust core → ships to **PyPI** and **npm** from a single source.
 
 ---
 
-## NEDB v2.5.34 — Production Stable
+## NEDB v2.8.0 — Production Stable
 
-**Current stable: 2.5.34** — NEDB ships as **three version-aligned distributions** on one tag — `nedb-engine` (flagship), `crypto-database` (verifiable v2/v3 DAG), and `aof-db` (fast append-only) — across npm / PyPI / crates.io with full mac + linux + windows native addons (see [**Releasing**](#releasing) below). On the engine side it remains a polish release on the complete cross-platform line. The `nedbd-v2` daemon now does **real CLI parsing** — `--dag-v3`, `--data`, `--fast-fsync`, `--help`, `--version` are recognized flags instead of being silently swallowed as the positional data dir — and `npm test` ships a **cinematic native smoke test** that tours v1→v2 migration, the v2 DAG, the v3 segment store, and a causal-provenance audit. All native wheels (Linux + Windows on GitHub Actions; macOS arm64 + x86_64 on Codemagic M2 Mac Minis) **plus** the universal pure-Python wheel ship from a single `v*` tag, with the `nedbd-v2` binary bundled inside `pip install nedb-engine`.
+**Current stable: 2.8.0** — NEDB ships as **three version-aligned distributions** on one tag — `nedb-engine` (flagship), `crypto-database` (verifiable v2/v3 DAG), and `aof-db` (fast append-only) — across npm / PyPI / crates.io with full mac + linux + windows native addons (see [**Releasing**](#releasing) below). All native wheels (Linux + Windows on GitHub Actions; macOS arm64 + x86_64 on Codemagic M2 Mac Minis) **plus** the universal pure-Python wheel ship from a single `v*` tag, with the `nedbd-v2` binary bundled inside `pip install nedb-engine`.
+
+### New in 2.8.0 — Cast: the database understands English
+
+`POST /v1/databases/<name>/cast` turns a short English prompt into NQL, using a **3.33M-parameter model that runs locally on CPU**. No API key, no network call, no per-token bill.
+
+```bash
+nedbd --dag --cast ./data     # requires: cargo install nedb-engine --features cast
+
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -d '{"prompt":"orders over 100"}'
+# → {"nql":"FROM orders WHERE total > 100","valid":true,"collection_known":true,"executed":false}
+```
+
+The model ([**nedb-cast-slm**](https://github.com/aiassistsecure/nedb-cast-slm)) was trained on NQL using NEDB's own parser as generator, grader, and gate — then shipped to PyPI, crates.io, and npm, all three loading the identical weights.
+
+**Why it lives in the engine and not in a client:** the hard part of natural-language querying is knowing the schema, and the engine already holds the live collection list. A plan naming a collection that doesn't exist returns **422 with the reason**, never a silently empty result set. See [**Cast**](#cast--natural-language-into-nql) below.
+
+Off by default — feature-gated at compile time, flag-gated at runtime, and `execute` defaults to `false` so you review the plan before it runs.
+
+**Also in 2.8.0 — an engine bug the feature exposed.** `IdIndex::collections()` did a bare `read_dir` while every other read path overlaid the WAL write buffer, so a brand-new collection was invisible until the 1s flush ticker fired. Unreachable by hand (the ticker fires between keystrokes) but reliable from a script, and latent in `Db::compact()` too, where a missed collection's live objects would be reclaimed as garbage. Fixed, with regression tests that seed *without* flushing.
 
 **New in 2.5.x:**
 
@@ -304,6 +324,8 @@ Alongside the daemon, `cargo install nedb-engine` ships **`nedb-cli`** — opera
 | `NEDBD_TOKEN` | unset | Optional bearer token; required on every `/v1/*` request when set. |
 | `NEDB_TMK` | unset | 32-byte hex AES-256-GCM at-rest encryption key. |
 | `NEDBD_DATA` | `./nedb-data` | Root directory. v2 creates `dag/`, IdIndex sharded across **256 subdirectories**, and a small `MANIFEST` file. |
+| `NEDBD_CAST` | `0` | Set `1` to enable the `/cast` natural-language planner. Same as `--cast`. Requires a build with `--features cast`. See [**Cast**](#cast--natural-language-into-nql). |
+| `NEDBD_CAST_MODEL` | unset | Explicit path to a `model.cast` container. Otherwise searched in the data dir, `$CAST_HOME`, and `~/.cache/nedb-cast-slm/`. |
 
 ```bash
 # Create a database with seed data and relations
@@ -360,6 +382,127 @@ db.query('FROM policy AS OF 200 VALID AS OF "2024-02-15"')
 
 ---
 
+## Cast — natural language into NQL
+
+*New in 2.8.0. Optional, feature-gated, off by default.*
+
+Ten clauses and six operators. That's the whole grammar above — small enough that a **3.33M-parameter** model can learn it completely, and small enough that shipping every query to a frontier model is an absurd amount of machinery.
+
+So we trained one. It runs on CPU, in-process, in milliseconds.
+
+```bash
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"orders over 100"}'
+```
+
+```json
+{
+  "prompt": "orders over 100",
+  "nql": "FROM orders WHERE total > 100",
+  "valid": true,
+  "collection": "orders",
+  "collection_known": true,
+  "collections": ["orders"],
+  "executed": false,
+  "seq": 3,
+  "head": "262fd9…"
+}
+```
+
+### NEDB is on both ends of this
+
+The model is [**nedb-cast-slm**](https://github.com/aiassistsecure/nedb-cast-slm), and NEDB built it as much as it consumes it.
+
+**NEDB's parser was the training pipeline.** It generated the corpus (sample a random plan → render NQL → render a human paraphrase; 200,000 pairs in 16.5 seconds, perfect labels, zero annotation cost). It was the grader — scoring *parsed plan* equality, not string equality, so `FROM orders WHERE total > 99` and `from orders where total>99` both earn full credit. And it was the gate: no example entered the corpus unless it round-tripped through the real parser to a canonically identical plan.
+
+> Most text-to-DSL projects hand-write a verifier and hope it's right. We didn't write one — it already shipped, and it's the same code the database runs in production.
+
+**Training lineage lives in NEDB too**, chained by `caused_by`:
+
+```
+datasets ──▶ training_runs ──▶ checkpoints ──▶ evals
+```
+
+```python
+db.query("FROM evals TRACE caused_by")   # the exact data behind any score
+```
+
+### Why the planner lives in the engine
+
+The hard part of natural-language querying is not the model. It's the **schema** — and a client has to fetch the collection list and pass it in, where it's stale on arrival. The engine already holds the live list.
+
+So the plan is checked against collections that actually exist, at the moment of the call:
+
+```json
+{ "prompt": "show me all stylists",
+  "nql": "FROM stylists",
+  "valid": true,
+  "collection_known": false,
+  "error": "collection \"stylists\" does not exist in \"shop\"" }
+```
+
+HTTP **422**. Not zero rows — zero rows reads as *"no matching data"*, which would be a lie. The query was perfectly well-formed; the collection was imagined. That's the model's known failure mode on an unfamiliar schema, and the engine is the one component positioned to catch it.
+
+Every `nedbd` client — Python, Node, Studio, `curl` — inherits this without writing a line.
+
+### Three safety properties
+
+| | |
+|---|---|
+| **The model never executes** | It emits text. The text goes to the same `nql::query` path a hand-typed query uses. No second executor exists to audit. |
+| **Validation is parsing** | `nql::parse` and `nql::execute` share one code path, so they cannot disagree about what is well-formed. Invalid output returns 422 *with the offending text*. |
+| **`execute` defaults to false** | You get a plan for review. Running a guess silently is worse than admitting uncertainty. |
+
+That last default earns its keep. A real miss, from a real run:
+
+```
+prompt   "paid orders over 100"
+nql      FROM orders WHERE status = "paid" LIMIT 100      ← wrong
+correct  FROM orders WHERE status = "paid" AND total > 100
+```
+
+It read *"over 100"* as `LIMIT 100` and dropped the predicate. The count still came back **2** — because both paid orders happened to exceed 100. A count-only assertion would have scored it a pass. A human reading `LIMIT 100` catches it in a heartbeat; an auto-executing client does not.
+
+Multi-predicate `WHERE` is the model's weakest clause: **85.1%** exact-plan match on eval, 61.2% on adversarial holdout. The [model card](https://github.com/aiassistsecure/nedb-cast-slm#what-it-gets-wrong) documents every failure mode with examples.
+
+To run it anyway, ask:
+
+```bash
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -d '{"prompt":"orders over 100","execute":true}'
+# → { …, "executed": true, "count": 2, "rows": [ … ] }
+```
+
+### Enabling it
+
+Two gates, because most deployments want neither the model dependency nor the weights:
+
+```bash
+# compile-time
+cargo install nedb-engine --features cast
+
+# weights (~13 MB) — GitHub release asset, checksum-verified on load
+curl -L -o ./data/model.cast \
+  https://github.com/aiassistsecure/nedb-cast-slm/releases/download/v10.30.90/model.cast
+
+# runtime
+nedbd --dag --cast ./data
+#   cast     enabled — 3.33M params, vocab 581, ./data/model.cast
+```
+
+Search order: `$NEDBD_CAST_MODEL` → `<data_dir>/model.cast` → `$CAST_HOME/model.cast` → `~/.cache/nedb-cast-slm/v10.30.90/model.cast` (the Python/npm cache location, so a machine that has run either package is already ready).
+
+Built without the feature, the route returns **501** rather than 404 — clients can detect the capability instead of guessing. Built with it but missing weights, the daemon logs loudly and serves everything else normally.
+
+**Verify the whole path:**
+
+```bash
+./scripts/test-cast.sh --boot     # boots a daemon, seeds, casts, executes, checks failure modes
+```
+
+---
+
 ## Performance
 
 **v2 DAG Rust server (v2.2.31, Intel iMac — 10k writes / 100k reads / 30k objects, AES-256-GCM on):**

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/client/node/README.md

@@ -60,9 +60,13 @@ npm install nedb-engine   # or: pip install nedb-engine
 # v2 DAG engine (recommended — instant cold start, tamper-evident)
 NEDBD_DAG=1 nedbd --data ./data
 
+# With natural-language planning (see `cast` below)
+#   needs a build with --features cast, plus model.cast in the data dir
+NEDBD_DAG=1 NEDBD_CAST=1 nedbd --data ./data
+
 # Check health
 curl http://127.0.0.1:7070/health
-# {"ok":true,"version":"2.0.8","service":"nedbd","encrypted":true}
+# {"ok":true,"version":"2.8.0","service":"nedbd","encrypted":true}
 ```
 
 ---
@@ -126,6 +130,65 @@ FROM <collection>
   [SEARCH "text"]                full-text search
 ```
 
+### Cast — natural language into NQL
+
+| Method | Description |
+|--------|-------------|
+| `db.cast(prompt, opts?)` | English → `CastResult` (the plan). `opts.execute` defaults to `false` |
+| `db.castNql(prompt)` | English → just the NQL string |
+
+Requires a daemon built with `--features cast` and started with `--cast`. A **3.33M-parameter** model ([nedb-cast-slm](https://github.com/aiassistsecure/nedb-cast-slm)) runs server-side on CPU — no API key, no per-token bill.
+
+```typescript
+const plan = await db.cast("orders over 100");
+// {
+//   nql: 'FROM orders WHERE total > 100',
+//   valid: true,
+//   collection: 'orders',
+//   collection_known: true,
+//   collections: ['orders'],
+//   executed: false,
+//   seq: 3, head: '262fd9…'
+// }
+```
+
+**`execute` defaults to `false` on purpose.** You get a plan to look at, not a query that already ran:
+
+```typescript
+if (plan.valid && plan.collection_known) {
+  const rows = await db.query(plan.nql);        // review, then run
+}
+
+const run = await db.cast("orders over 100", { execute: true });
+run.count;  // 2
+run.rows;   // [...]
+```
+
+That default matters. A real miss from a real run:
+
+```
+prompt   "paid orders over 100"
+nql      FROM orders WHERE status = "paid" LIMIT 100      ← wrong
+correct  FROM orders WHERE status = "paid" AND total > 100
+```
+
+It read *"over 100"* as `LIMIT 100`. The count still came back correct **by coincidence** — both paid orders exceeded 100. Multi-predicate `WHERE` is the model's weakest clause (85.1% eval / 61.2% holdout). Show the plan to a human when you can.
+
+**Errors are explicit, never empty results.** The server checks the plan against the collections this database actually has:
+
+```typescript
+try {
+  await db.cast("show me all stylists");
+} catch (e) {
+  if (e instanceof NedbError) {
+    e.status;   // 422
+    e.message;  // collection "stylists" does not exist in "shop" (generated: "FROM stylists")
+  }
+}
+```
+
+Zero rows would read as *"no matching data"* — a lie, when the truth is the collection was imagined. Status **501** means the daemon was built without the feature, so you can detect the capability rather than guess at it.
+
 ### Integrity
 
 | Method | Description |
@@ -184,6 +247,7 @@ One HTTP request, multiple ops — best throughput for bulk ingestion.
 
 - **Engine:** [pip install nedb-engine](https://pypi.org/project/nedb-engine/) · [npm install nedb-engine](https://www.npmjs.com/package/nedb-engine)
 - **Python client:** [pip install nedb-engine-client](https://pypi.org/project/nedb-engine-client/)
+- **Cast model:** [nedb-cast-slm](https://github.com/aiassistsecure/nedb-cast-slm) — the 3.3M-param planner behind `db.cast()`
 - **Source:** [github.com/Eth-Interchained/nedb](https://github.com/Eth-Interchained/nedb)
 - **Studio:** [studio.interchained.org](https://studio.interchained.org)
 

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/client/python/README.md

@@ -75,9 +75,13 @@ NEDBD_DAG=1 nedbd --data ./data
 # With AES-256-GCM encryption
 NEDBD_DAG=1 NEDB_TMK=<32-byte-hex> nedbd --data ./data
 
+# With natural-language planning (see `cast` below)
+#   needs a build with --features cast, plus model.cast in the data dir
+NEDBD_DAG=1 NEDBD_CAST=1 nedbd --data ./data
+
 # Check health
 curl http://127.0.0.1:7070/health
-# {"ok":true,"version":"2.0.8","service":"nedbd","encrypted":true}
+# {"ok":true,"version":"2.8.0","service":"nedbd","encrypted":true}
 ```
 
 ---
@@ -141,6 +145,60 @@ FROM <collection>
   [SEARCH "text"]                full-text search
 ```
 
+### Cast — natural language into NQL
+
+| Method | Description |
+|--------|-------------|
+| `await db.cast(prompt, execute=False)` | English → dict (the plan) |
+| `await db.cast_nql(prompt)` | English → just the NQL string |
+
+Requires a daemon built with `--features cast` and started with `--cast`. A **3.33M-parameter** model ([nedb-cast-slm](https://github.com/aiassistsecure/nedb-cast-slm)) runs server-side on CPU — no API key, no per-token bill.
+
+```python
+plan = await db.cast("orders over 100")
+# {'prompt': 'orders over 100',
+#  'nql': 'FROM orders WHERE total > 100',
+#  'valid': True,
+#  'collection': 'orders',
+#  'collection_known': True,
+#  'collections': ['orders'],
+#  'executed': False,
+#  'seq': 3, 'head': '262fd9…'}
+```
+
+**`execute` defaults to `False` on purpose.** You get a plan to look at, not a query that already ran:
+
+```python
+if plan["valid"] and plan["collection_known"]:
+    rows = await db.query(plan["nql"])          # review, then run
+
+run = await db.cast("orders over 100", execute=True)
+run["count"]   # 2
+run["rows"]    # [...]
+```
+
+That default matters. A real miss from a real run:
+
+```
+prompt   "paid orders over 100"
+nql      FROM orders WHERE status = "paid" LIMIT 100      ← wrong
+correct  FROM orders WHERE status = "paid" AND total > 100
+```
+
+It read *"over 100"* as `LIMIT 100`. The count still came back correct **by coincidence** — both paid orders exceeded 100. Multi-predicate `WHERE` is the model's weakest clause (85.1% eval / 61.2% holdout). Show the plan to a human when you can.
+
+**Errors are explicit, never empty results.** The server checks the plan against the collections this database actually has:
+
+```python
+try:
+    await db.cast("show me all stylists")
+except NedbError as e:
+    e.status    # 422
+    e.message   # collection "stylists" does not exist in "shop" (generated: 'FROM stylists')
+```
+
+Zero rows would read as *"no matching data"* — a lie, when the truth is the collection was imagined. Status **501** means the daemon was built without the feature, so you can detect the capability rather than guess at it.
+
 ### Integrity
 
 | Method | Description |
@@ -183,6 +241,7 @@ Queries on missing collections return `[]` rather than raising — resilient by
 
 - **Engine:** [pip install nedb-engine](https://pypi.org/project/nedb-engine/) · [npm install nedb-engine](https://www.npmjs.com/package/nedb-engine)
 - **JS/TS client:** [npm install nedb-engine-client](https://www.npmjs.com/package/nedb-engine-client)
+- **Cast model:** [nedb-cast-slm](https://github.com/aiassistsecure/nedb-cast-slm) — the 3.3M-param planner behind `db.cast()`
 - **Source:** [github.com/Eth-Interchained/nedb](https://github.com/Eth-Interchained/nedb)
 - **Studio:** [studio.interchained.org](https://studio.interchained.org)
 

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nedb-engine"
-version = "2.7.2"
+version = "2.8.1"
 description = "NEDB — a versioned, self-compressing, time-traveling embedded database (replay-protected, idempotent, relational, searchable) with durable AOF persistence and a server daemon (nedbd)."
 readme = "README.md"
 requires-python = ">=3.8"

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/python/nedb/__init__.py

@@ -94,4 +94,4 @@ __all__ = [
     "verify_proof", "fold_head",
     "_native", "__has_native__",
 ]
-__version__ = "2.7.2"
+__version__ = "2.8.1"

{nedb_engine-2.7.2 → nedb_engine-2.8.1}/rust/nedb-v2/README.md

@@ -57,6 +57,7 @@ nedbd [OPTIONS] [data_dir]
 |---|---|---|
 | `data_dir` | `./nedb-data` | Directory for database files |
 | `--dag` | off | Use the v2 content-addressed DAG engine |
+| `--cast` | off | Enable natural-language query planning (requires `--features cast`) |
 | `--doctor` | — | Diagnose environment, print fix commands |
 
 ### Environment variables
@@ -69,6 +70,8 @@ nedbd [OPTIONS] [data_dir]
 | `NEDB_TMK` | — | 64-char hex master key for AES-256-GCM encryption at rest |
 | `NEDBD_MEMORY` | — | `1` = pure in-memory mode (no disk I/O) |
 | `NEDBD_DAG` | — | `1` = same as `--dag` flag |
+| `NEDBD_CAST` | — | `1` = same as `--cast` flag |
+| `NEDBD_CAST_MODEL` | — | Explicit path to a `model.cast` container |
 
 ---
 
@@ -86,12 +89,128 @@ POST   /v1/databases/<name>/put         {coll, id, doc, caused_by?}
 POST   /v1/databases/<name>/query       {nql}
 POST   /v1/databases/<name>/link        {frm, rel, to}
 POST   /v1/databases/<name>/neighbors   {node, rel}
+POST   /v1/databases/<name>/cast        {prompt, execute?}    # feature = "cast"
 GET    /v1/databases/<name>/verify
 POST   /v1/databases/<name>/checkpoint
 ```
 
 ---
 
+## Cast — natural language into NQL
+
+*Optional. Feature-gated, off by default.*
+
+```bash
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"orders over 100"}'
+```
+
+```json
+{
+  "prompt": "orders over 100",
+  "nql": "FROM orders WHERE total > 100",
+  "valid": true,
+  "collection": "orders",
+  "collection_known": true,
+  "collections": ["orders"],
+  "executed": false,
+  "seq": 3,
+  "head": "262fd9…"
+}
+```
+
+A **3.33M-parameter** model ([nedb-cast-slm](https://github.com/aiassistsecure/nedb-cast-slm)) turns a short English prompt into NQL. It runs locally on CPU in a few milliseconds. No API key, no network call, no tokens billed to anyone.
+
+### Why this lives in the engine
+
+The hard part of natural-language querying isn't the model — it's **knowing the schema**. A client has to fetch the collection list and pass it in, and it's stale the moment it arrives. The engine already holds the live list.
+
+So the planner is constrained against real collections at the instant of the call:
+
+```json
+{ "prompt": "show me all stylists",
+  "nql": "FROM stylists",
+  "valid": true,
+  "collection_known": false,
+  "error": "collection \"stylists\" does not exist in \"shop\"" }
+```
+
+HTTP **422**. Not an empty result set — an empty result set reads as *"no matching rows"*, which would be a lie. The query was fine; the collection was imaginary.
+
+Every `nedbd` client inherits this for free instead of reimplementing it.
+
+### Three safety properties
+
+**1 · The model never executes anything.** It emits text. That text goes to the same `nql::query` path a hand-typed query uses. There is no second executor to audit.
+
+**2 · Validation is parsing, not pattern-matching.** `nql::parse` and `nql::execute` share one code path, so they cannot disagree about what is well-formed. Unparseable output returns 422 *with the offending text attached*.
+
+**3 · `execute` defaults to `false`.** You get a plan for review. Opt in explicitly:
+
+```bash
+curl -X POST localhost:7070/v1/databases/shop/cast \
+  -d '{"prompt":"orders over 100","execute":true}'
+# → { …, "executed": true, "count": 2, "rows": [ … ] }
+```
+
+That default is not decoration. Here is a real miss, from a real run:
+
+```
+prompt   "paid orders over 100"
+nql      FROM orders WHERE status = "paid" LIMIT 100      ← wrong
+correct  FROM orders WHERE status = "paid" AND total > 100
+```
+
+It read *"over 100"* as `LIMIT 100` and dropped the second predicate. The row count still came back **2**, because both paid orders happened to exceed 100 — a count-only check would have called that a pass. A human reading `LIMIT 100` catches it instantly. An auto-executing client does not.
+
+Multi-predicate `WHERE` is the model's weakest clause (**85.1%** eval / 61.2% holdout). Ship accordingly.
+
+### Enabling it
+
+Off by default because it pulls a model dependency and expects weights at runtime — most deployments want neither.
+
+```bash
+# 1. build with the feature
+cargo install nedb-engine --features cast
+
+# 2. get the weights (~13 MB)
+curl -L -o model.cast \
+  https://github.com/aiassistsecure/nedb-cast-slm/releases/download/v10.30.90/model.cast
+
+# 3. run
+nedbd --dag --cast ./data
+#   cast     enabled — 3.33M params, vocab 581, ./data/model.cast
+```
+
+Model search order, first hit wins:
+
+1. `$NEDBD_CAST_MODEL`
+2. `<data_dir>/model.cast`
+3. `$CAST_HOME/model.cast`
+4. `~/.cache/nedb-cast-slm/v10.30.90/model.cast` — where the Python and npm packages cache it, so a machine that has run either one is already ready
+
+The container is checksum-verified on load. A silently corrupt model would emit plausible-but-wrong queries, which is the worst possible failure mode for a query planner.
+
+Without the feature the route still exists and returns **501** — so a client can detect the capability instead of guessing. Missing weights on a `--cast` build is loud but non-fatal: the daemon starts and serves everything else normally.
+
+### As a library
+
+```rust
+use nedb_engine::cast::Caster;
+
+let caster = Caster::load(&data_dir)?;
+let out = caster.cast_checked("orders over 100", &db.id_index.collections());
+
+if out.collection_known && nedb_engine::nql::parse(&out.nql).is_ok() {
+    let (rows, count) = nedb_engine::nql::query(&db, &out.nql)?;
+}
+```
+
+Decoding is greedy and deterministic — a DSL has exactly one right answer, so sampling could only hurt. The same prompt always produces the same plan, which makes the endpoint safe to cache.
+
+---
+
 ## NQL — NEDB Query Language
 
 ```sql