morphdb 0.1.3__tar.gz → 0.1.4__tar.gz

{morphdb-0.1.3 → morphdb-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.3
+Version: 0.1.4
 Summary: A coding-agent-friendly, multi-tenant backend for vibe-coded websites. One process hosts many isolated apps; reshape each app's schema as fast as your agent iterates while the frontend keeps calling the same generic endpoints.
 Author: morphdb contributors
 License: MIT
@@ -34,6 +34,8 @@ keeps calling the same small set of generic, deterministic endpoints. One
 process hosts many isolated apps (one per site), zero dependencies, backed by
 SQLite.
 
+📖 **[Visual explainer → morphdb.pages.dev](https://morphdb.pages.dev)** — the whole idea (schema-fluid, API-stable), the agent/frontend split, relations, and how Claude plugs in over MCP, on one page.
+
 ## Install
 
 ```bash
@@ -79,7 +81,9 @@ H="X-App-Key: my-site"
 # 1. define types + a relation
 curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
 curl -X PUT $BASE/schema/task -H "$H" -d '{
-  "fields": {"title":"string","done":"boolean","priority":"number"},
+  "fields": {"title":"string",
+             "done":{"type":"boolean","index":true},
+             "priority":{"type":"number","index":true}},
   "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
 
 # 2. create + read + query
@@ -321,15 +325,58 @@ Every schema and object request must send the app key as the `X-App-Key` header
 
 ### Query operators
 
-Append `__op` to a field name: `eq` (default), `ne`, `gt`, `gte`, `lt`, `lte`,
-`contains` (substring), `in` (comma-separated), `exists` (`true`/`false`).
-Filtering is on **fields**, not relations.
+A field is filterable/sortable only if its schema marks it **`"index": true`**
+(opt-in, default off). Filtering or sorting an un-indexed field returns a 400
+telling you to index it; turning the flag on backfills existing objects
+automatically, turning it off is instant. `json` fields can't be indexed.
+
+Append `__op` to an **indexed field** name: `eq` (default), `ne`, `gt`, `gte`,
+`lt`, `lte`, `contains` (substring), `in` (comma-separated), `exists`
+(`true`/`false`).
 
 ```
+# priority, title, done, status all declared with "index": true
 GET /objects/task?priority__gte=3&title__contains=buy&done=false
-GET /objects/task?status__in=open,blocked&sort=_created_at&order=desc&limit=50
+GET /objects/task?status__in=open,blocked&sort=priority&order=desc&limit=50
+```
+
+You can also filter by a **relation** — treat it like an ORM foreign key, not a
+manual join. Filtering by a relation matches objects linked to a given neighbor,
+and resolves through the indexed edge table (so it is index-backed):
+
+| Query | Meaning |
+| --- | --- |
+| `?assignee=<guid>` | objects whose `assignee` is / includes that neighbor |
+| `?assignee__in=<g1>,<g2>` | linked to any of those neighbors |
+| `?assignee__ne=<guid>` | not linked to that neighbor (includes unlinked) |
+| `?assignee__exists=true` | has any `assignee` (`false` → has none) |
+
+```
+# "stages of business X that are still in build" — relation + field, one query
+GET /objects/stage?business=<bizguid>&status=build&sort=_created_at
 ```
 
+Relation filters compose with field filters, `sort`, and pagination. Scalar
+comparisons (`gt`/`lt`/`contains`) are field-only; relations support
+`eq`/`ne`/`in`/`exists`. So **model a foreign key as a relation, not a string
+field** — you keep one-read traversal *and* get filtering, indexed, for free.
+
+### Including related objects
+
+By default a relation reads back as a guid (to-one) or list of guids (to-many).
+Add `?include=` with comma-separated relation paths (dots nest) to hydrate them
+into the full neighbor objects, nested Prisma-style:
+
+```
+GET /objects/post?include=author,comments,comments.author
+# each post.author becomes a full user; post.comments a list of full comments,
+# and each comment.author a full user too.
+```
+
+Works on the list endpoint and both single-object reads. Read-only, depth ≤ 4,
+and batched (one query per relation per level — no N+1). Writes stay flat: create
+and update with guids, never nested objects.
+
 ## Errors
 
 JSON shape: `{"error": {"code": "...", "message": "...", ...extra}}`.
@@ -364,8 +411,10 @@ allowed, `413` body too large, `500` internal.
   old type simply reads as unset (the field's default, or null) until it's
   written again; reads and queries apply this rule identically, so they always
   agree. Re-adding a dropped field at the same type recovers its values.
-- **Filtering is field-only.** Query operators apply to raw fields; relations
-  are read/written on the object body but not filtered server-side (yet).
+- **Filtering/sorting is opt-in per field.** Only a field marked `"index": true`
+  can be filtered or sorted (it gets a row in the indexed `field_index` table);
+  an un-indexed field is storage-only and a filter/sort on it is a 400. Relations
+  are always filterable via the indexed edge table — no flag needed.
 - **Integer magnitude.** Numbers are stored and read back exactly at any size.
   Filtering/sorting on integers beyond ±2⁶³ uses floating-point comparison (a
   SQLite limitation), so equality/range queries on such huge integers may be

{morphdb-0.1.3 → morphdb-0.1.4}/README.md

@@ -7,6 +7,8 @@ keeps calling the same small set of generic, deterministic endpoints. One
 process hosts many isolated apps (one per site), zero dependencies, backed by
 SQLite.
 
+📖 **[Visual explainer → morphdb.pages.dev](https://morphdb.pages.dev)** — the whole idea (schema-fluid, API-stable), the agent/frontend split, relations, and how Claude plugs in over MCP, on one page.
+
 ## Install
 
 ```bash
@@ -52,7 +54,9 @@ H="X-App-Key: my-site"
 # 1. define types + a relation
 curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
 curl -X PUT $BASE/schema/task -H "$H" -d '{
-  "fields": {"title":"string","done":"boolean","priority":"number"},
+  "fields": {"title":"string",
+             "done":{"type":"boolean","index":true},
+             "priority":{"type":"number","index":true}},
   "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
 
 # 2. create + read + query
@@ -294,15 +298,58 @@ Every schema and object request must send the app key as the `X-App-Key` header
 
 ### Query operators
 
-Append `__op` to a field name: `eq` (default), `ne`, `gt`, `gte`, `lt`, `lte`,
-`contains` (substring), `in` (comma-separated), `exists` (`true`/`false`).
-Filtering is on **fields**, not relations.
+A field is filterable/sortable only if its schema marks it **`"index": true`**
+(opt-in, default off). Filtering or sorting an un-indexed field returns a 400
+telling you to index it; turning the flag on backfills existing objects
+automatically, turning it off is instant. `json` fields can't be indexed.
+
+Append `__op` to an **indexed field** name: `eq` (default), `ne`, `gt`, `gte`,
+`lt`, `lte`, `contains` (substring), `in` (comma-separated), `exists`
+(`true`/`false`).
 
 ```
+# priority, title, done, status all declared with "index": true
 GET /objects/task?priority__gte=3&title__contains=buy&done=false
-GET /objects/task?status__in=open,blocked&sort=_created_at&order=desc&limit=50
+GET /objects/task?status__in=open,blocked&sort=priority&order=desc&limit=50
+```
+
+You can also filter by a **relation** — treat it like an ORM foreign key, not a
+manual join. Filtering by a relation matches objects linked to a given neighbor,
+and resolves through the indexed edge table (so it is index-backed):
+
+| Query | Meaning |
+| --- | --- |
+| `?assignee=<guid>` | objects whose `assignee` is / includes that neighbor |
+| `?assignee__in=<g1>,<g2>` | linked to any of those neighbors |
+| `?assignee__ne=<guid>` | not linked to that neighbor (includes unlinked) |
+| `?assignee__exists=true` | has any `assignee` (`false` → has none) |
+
+```
+# "stages of business X that are still in build" — relation + field, one query
+GET /objects/stage?business=<bizguid>&status=build&sort=_created_at
 ```
 
+Relation filters compose with field filters, `sort`, and pagination. Scalar
+comparisons (`gt`/`lt`/`contains`) are field-only; relations support
+`eq`/`ne`/`in`/`exists`. So **model a foreign key as a relation, not a string
+field** — you keep one-read traversal *and* get filtering, indexed, for free.
+
+### Including related objects
+
+By default a relation reads back as a guid (to-one) or list of guids (to-many).
+Add `?include=` with comma-separated relation paths (dots nest) to hydrate them
+into the full neighbor objects, nested Prisma-style:
+
+```
+GET /objects/post?include=author,comments,comments.author
+# each post.author becomes a full user; post.comments a list of full comments,
+# and each comment.author a full user too.
+```
+
+Works on the list endpoint and both single-object reads. Read-only, depth ≤ 4,
+and batched (one query per relation per level — no N+1). Writes stay flat: create
+and update with guids, never nested objects.
+
 ## Errors
 
 JSON shape: `{"error": {"code": "...", "message": "...", ...extra}}`.
@@ -337,8 +384,10 @@ allowed, `413` body too large, `500` internal.
   old type simply reads as unset (the field's default, or null) until it's
   written again; reads and queries apply this rule identically, so they always
   agree. Re-adding a dropped field at the same type recovers its values.
-- **Filtering is field-only.** Query operators apply to raw fields; relations
-  are read/written on the object body but not filtered server-side (yet).
+- **Filtering/sorting is opt-in per field.** Only a field marked `"index": true`
+  can be filtered or sorted (it gets a row in the indexed `field_index` table);
+  an un-indexed field is storage-only and a filter/sort on it is a 400. Relations
+  are always filterable via the indexed edge table — no flag needed.
 - **Integer magnitude.** Numbers are stored and read back exactly at any size.
   Filtering/sorting on integers beyond ±2⁶³ uses floating-point comparison (a
   SQLite limitation), so equality/range queries on such huge integers may be

{morphdb-0.1.3 → morphdb-0.1.4}/morphdb/__init__.py

@@ -5,4 +5,4 @@ coding agent iterates, while the frontend keeps calling the same small set of
 generic, deterministic endpoints.
 """
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{morphdb-0.1.3 → morphdb-0.1.4}/morphdb/cli/__init__.py

@@ -13,8 +13,15 @@ Commands (see :mod:`morphdb.cli.main`):
     morphdb logs          show the server log (-f to follow)
     morphdb run           run in the foreground (blocking; for dev)
     morphdb dashboard     open a read-only web view of every app + its tables
+    morphdb mcp           run the MCP server (stdio; spawned by Claude Code, not you)
     morphdb install-skill install/update the bundled Claude Code skill
 
+The ``mcp`` command is a thin HTTP *client* of the running backend daemon (it
+auto-starts the daemon if needed). It exposes schema + app operations to a coding
+agent as MCP tools, so the agent calls real tools instead of shelling out to the
+bundled schema script. It is pure stdlib — no MCP SDK — so the package stays
+dependency-free.
+
 Storage: the local server keeps data in a per-user SQLite file at
 ``~/.morphdb/data.sqlite3`` (override the file with ``--db``, or move the state
 dir with ``$MORPHDB_HOME``). To talk to a MorphDB hosted somewhere else instead