mdb-engine 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

mdb_engine/utils/__init__.py

@@ -4,4 +4,6 @@ Utility functions and helpers for MDB Engine.
 This module provides utility functions used across the MDB Engine codebase.
 """
 
-__all__ = []
+from .mongo import clean_mongo_doc, clean_mongo_docs
+
+__all__ = ["clean_mongo_doc", "clean_mongo_docs"]

mdb_engine/utils/mongo.py

@@ -0,0 +1,117 @@
+"""
+MongoDB utility functions for MDB Engine.
+
+This module provides utility functions for working with MongoDB documents,
+including JSON serialization helpers.
+"""
+
+from typing import Any
+
+
+def clean_mongo_doc(doc: dict[str, Any] | None) -> dict[str, Any] | None:
+    """
+    Convert MongoDB document to JSON-serializable format.
+
+    Recursively converts MongoDB-specific types to JSON-compatible types:
+    - ObjectId -> str
+    - datetime -> ISO format string
+    - Nested dictionaries and lists are processed recursively
+
+    Args:
+        doc: MongoDB document (dict) or None
+
+    Returns:
+        Cleaned document with all MongoDB types converted, or None if input was None
+
+    Example:
+        ```python
+        from mdb_engine.utils import clean_mongo_doc
+
+        # MongoDB document with ObjectId and datetime
+        doc = {
+            "_id": ObjectId("507f1f77bcf86cd799439011"),
+            "name": "John",
+            "created_at": datetime(2024, 1, 1, 12, 0, 0),
+            "nested": {
+                "id": ObjectId("507f1f77bcf86cd799439012")
+            }
+        }
+
+        # Convert to JSON-serializable format
+        cleaned = clean_mongo_doc(doc)
+        # {
+        #     "_id": "507f1f77bcf86cd799439011",
+        #     "name": "John",
+        #     "created_at": "2024-01-01T12:00:00",
+        #     "nested": {
+        #         "id": "507f1f77bcf86cd799439012"
+        #     }
+        # }
+        ```
+    """
+    from datetime import datetime
+
+    from bson import ObjectId
+
+    if doc is None:
+        return None
+
+    if not isinstance(doc, dict):
+        # If it's not a dict, try to convert it
+        if isinstance(doc, ObjectId):
+            return str(doc)
+        elif isinstance(doc, datetime):
+            return doc.isoformat() if hasattr(doc, "isoformat") else str(doc)
+        else:
+            return doc
+
+    cleaned: dict[str, Any] = {}
+
+    for key, value in doc.items():
+        if isinstance(value, ObjectId):
+            cleaned[key] = str(value)
+        elif isinstance(value, datetime):
+            cleaned[key] = value.isoformat() if hasattr(value, "isoformat") else str(value)
+        elif isinstance(value, dict):
+            cleaned[key] = clean_mongo_doc(value)
+        elif isinstance(value, list):
+            cleaned[key] = [
+                clean_mongo_doc(item)
+                if isinstance(item, dict)
+                else (
+                    str(item)
+                    if isinstance(item, ObjectId)
+                    else (item.isoformat() if isinstance(item, datetime) else item)
+                )
+                for item in value
+            ]
+        else:
+            cleaned[key] = value
+
+    return cleaned
+
+
+def clean_mongo_docs(docs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Convert a list of MongoDB documents to JSON-serializable format.
+
+    Convenience function that applies clean_mongo_doc to each document in a list.
+
+    Args:
+        docs: List of MongoDB documents
+
+    Returns:
+        List of cleaned documents
+
+    Example:
+        ```python
+        from mdb_engine.utils import clean_mongo_docs
+
+        # List of MongoDB documents
+        docs = await db.collection.find({}).to_list(length=10)
+
+        # Convert all to JSON-serializable format
+        cleaned = clean_mongo_docs(docs)
+        ```
+    """
+    return [clean_mongo_doc(doc) for doc in docs]

{mdb_engine-0.2.3.dist-info → mdb_engine-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.2.3
+Version: 0.2.4
 Summary: MongoDB Engine
 Home-page: https://github.com/ranfysvalle02/mdb-engine
 Author: Fabian Valle
@@ -73,6 +73,31 @@ Dynamic: requires-python
 
 ---
 
+## 🎯 manifest.json: The Key to Everything
+
+**`manifest.json` is the foundation of your application.** It's a single configuration file that defines your app's identity, data structure, authentication, indexes, and services. Everything flows from this file.
+
+### Your First manifest.json
+
+Create a `manifest.json` file with just 3 fields:
+
+```json
+{
+  "schema_version": "2.0",
+  "slug": "my_app",
+  "name": "My App"
+}
+```
+
+That's it! This minimal manifest gives you:
+- ✅ Automatic data scoping (all queries filtered by `app_id`)
+- ✅ Collection name prefixing (`db.tasks` → `my_app_tasks`)
+- ✅ App registration and lifecycle management
+
+**Learn more**: [Quick Start Guide](docs/QUICK_START.md) | [Manifest Deep Dive](docs/MANIFEST_DEEP_DIVE.md)
+
+---
+
 ## Installation
 
 ```bash
@@ -83,28 +108,55 @@ pip install mdb-engine
 
 ## 30-Second Quick Start
 
+**Step 1**: Create your `manifest.json`:
+
+```json
+{
+  "schema_version": "2.0",
+  "slug": "my_app",
+  "name": "My App",
+  "managed_indexes": {
+    "tasks": [
+      {
+        "type": "regular",
+        "keys": {"status": 1, "created_at": -1},
+        "name": "status_sort"
+      }
+    ]
+  }
+}
+```
+
+**Step 2**: Create your FastAPI app:
+
 ```python
 from pathlib import Path
 from fastapi import Depends
 from mdb_engine import MongoDBEngine
 from mdb_engine.dependencies import get_scoped_db
 
-# 1. Initialize the engine
+# Initialize the engine
 engine = MongoDBEngine(
     mongo_uri="mongodb://localhost:27017",
     db_name="my_database"
 )
 
-# 2. Create a FastAPI app with automatic lifecycle management
+# Create app - manifest.json is loaded automatically!
 app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
 
-# 3. Use request-scoped dependencies - all queries automatically isolated
+# Use request-scoped dependencies - all queries automatically isolated
 @app.post("/tasks")
 async def create_task(task: dict, db=Depends(get_scoped_db)):
     result = await db.tasks.insert_one(task)
     return {"id": str(result.inserted_id)}
 ```
 
+**What just happened?**
+- ✅ Engine loaded your `manifest.json`
+- ✅ Indexes created automatically from `managed_indexes`
+- ✅ Database queries automatically scoped to your app
+- ✅ Lifecycle management handled (startup/shutdown)
+
 That's it. Your data is automatically sandboxed, indexes are created, and cleanup is handled.
 
 ---
@@ -200,9 +252,11 @@ async def health():
 
 ## Why mdb-engine?
 
+- **manifest.json is everything** — Single source of truth for your entire app configuration
 - **Zero boilerplate** — No more connection setup, index creation scripts, or auth handlers
 - **Data isolation** — Multi-tenant ready with automatic app sandboxing
 - **Manifest-driven** — Define your app's "DNA" in JSON, not scattered code
+- **Incremental adoption** — Start minimal, add features as needed
 - **No lock-in** — Standard Motor/PyMongo underneath; export anytime with `mongodump --query='{"app_id":"my_app"}'`
 
 ---
@@ -300,13 +354,34 @@ async def get_items():
 
 ---
 
+## Understanding manifest.json
+
+Your `manifest.json` is the heart of your application. It defines:
+
+- **App Identity**: `slug`, `name`, `description`
+- **Data Access**: `data_access.read_scopes`, `data_access.write_scope`
+- **Indexes**: `managed_indexes` (regular, vector, text, TTL, compound)
+- **Authentication**: `auth.policy`, `auth.users` (Casbin/OSO, demo users)
+- **AI Services**: `embedding_config`, `memory_config`
+- **Real-time**: `websockets` endpoints
+- **CORS**: `cors` settings
+
+**Start minimal, grow as needed.** You can begin with just `slug`, `name`, and `schema_version`, then add features incrementally.
+
+**📖 Learn More:**
+- [Quick Start Guide](docs/QUICK_START.md) - Get started with manifest.json
+- [Manifest Deep Dive](docs/MANIFEST_DEEP_DIVE.md) - Comprehensive manifest.json guide
+- [Examples](examples/) - Real-world manifest.json files
+
+---
+
 ## Links
 
 - [GitHub Repository](https://github.com/ranfysvalle02/mdb-engine)
 - [Documentation](https://github.com/ranfysvalle02/mdb-engine/tree/main/docs)
 - [All Examples](https://github.com/ranfysvalle02/mdb-engine/tree/main/examples)
-- [Quick Start Guide](https://github.com/ranfysvalle02/mdb-engine/blob/main/docs/QUICK_START.md)
-- [Contributing](https://github.com/ranfysvalle02/mdb-engine/blob/main/CONTRIBUTING.md)
+- [Quick Start Guide](docs/QUICK_START.md) - **Start here!**
+- [Contributing](CONTRIBUTING.md)
 
 ---
 

{mdb_engine-0.2.3.dist-info → mdb_engine-0.2.4.dist-info}/RECORD

@@ -1,11 +1,11 @@
 mdb_engine/README.md,sha256=T3EFGcPopY9LslYW3lxgG3hohWkAOmBNbYG0FDMUJiY,3502
-mdb_engine/__init__.py,sha256=-W3Gdj2GAoptKsR_T4xluYnmnelZTdKrTxCthIytZ48,3008
+mdb_engine/__init__.py,sha256=ll3Xc4FaoNqqK_lnWOJTyFHY3uAyoB40g3NnBjwyx5U,3155
 mdb_engine/config.py,sha256=DTAyxfKB8ogyI0v5QR9Y-SJOgXQr_eDBCKxNBSqEyLc,7269
 mdb_engine/constants.py,sha256=eaotvW57TVOg7rRbLziGrVNoP7adgw_G9iVByHezc_A,7837
 mdb_engine/dependencies.py,sha256=MJuYQhZ9ZGzXlip1ha5zba9Rvn04HDPWahJFJH81Q2s,14107
 mdb_engine/exceptions.py,sha256=NkBSdTBNP9bVTtI6w6mAoEfeVZDq-Bg7vCF2L26ZDZo,8442
 mdb_engine/auth/ARCHITECTURE.md,sha256=JXZsjEIpNz4Szk18KaOiEabhEuz1pmYWXQRN-EJEHDM,4076
-mdb_engine/auth/README.md,sha256=STL4PHyMlYpSNEAqo4RBKTEm4kz1GbWpI9c_lS94nV4,36802
+mdb_engine/auth/README.md,sha256=IVlUOat96V3yM6wk4T-u4GxJ4-WF05eBSJBlvIexyBo,37285
 mdb_engine/auth/__init__.py,sha256=QemWqAVvqlxjF-UbzMTGP5AUOeuaAsUEtK4PMxmozmA,5852
 mdb_engine/auth/audit.py,sha256=UQ0Bj5Zxp5et9A21YZCVkUjaABFqO1CXaMrWxNcdxm8,17352
 mdb_engine/auth/base.py,sha256=4E3XkbruZLG9lc6aC56w0ypjnfiR5RbtjQKwn4am8to,7418
@@ -26,7 +26,7 @@ mdb_engine/auth/provider.py,sha256=FOSHn-jp4VYtxvmjnzho5kH6y-xDKWbcKUorYRRl1C4,2
 mdb_engine/auth/rate_limiter.py,sha256=l3EYZE1Kz9yVfZwNrKq_1AgdD7GXB1WOLSqqGQVSSgA,15808
 mdb_engine/auth/restrictions.py,sha256=tOyQBO_w0bK9zmTsOPZf9cbvh4oITvpNfSxIXt-XrcU,8824
 mdb_engine/auth/session_manager.py,sha256=ywWJjTarm-obgJ3zO3s-1cdqEYe0XrozlY00q_yMJ8I,15396
-mdb_engine/auth/shared_middleware.py,sha256=c1yQCbEWDyEH3Q0IieTO85Gin50GwTJnMEbwLBM5SHg,22312
+mdb_engine/auth/shared_middleware.py,sha256=3lvm6aC0W_7ECvno_Mj3eu_93DZ--JiXhZ9hte8tvhM,30480
 mdb_engine/auth/shared_users.py,sha256=25OBks4VRHaYZW7R61vnplV7wmr7RRpDctSgnej_nxc,26773
 mdb_engine/auth/token_lifecycle.py,sha256=Q9S1X2Y6W7Ckt5PvyYXswBRh2Tg9DGpyRv_3Xve7VYQ,6708
 mdb_engine/auth/token_store.py,sha256=-B8j5RH5YEoKsswF4rnMoI51BaxMe4icke3kuehXmcI,9121
@@ -48,7 +48,7 @@ mdb_engine/core/connection.py,sha256=XnwuPG34pJ7kJGJ84T0mhj1UZ6_CLz_9qZf6NRYGIS8
 mdb_engine/core/encryption.py,sha256=RZ5LPF5g28E3ZBn6v1IMw_oas7u9YGFtBcEj8lTi9LM,7515
 mdb_engine/core/engine.py,sha256=ciQHxHEcFh-DOQ0X9gV5kKk9WAxj3GKg5JDIPfFZjMg,69459
 mdb_engine/core/index_management.py,sha256=9-r7MIy3JnjQ35sGqsbj8K_I07vAUWtAVgSWC99lJcE,5555
-mdb_engine/core/manifest.py,sha256=Rezktd0Ulv28N6vO2Pg5Z6HNVy8hEdQqJ5pO08rRk6U,133570
+mdb_engine/core/manifest.py,sha256=ROaMKrlHY2gi77ScQCWu8U_QB7CVCoR8CQrP1gmtrtw,134756
 mdb_engine/core/ray_integration.py,sha256=vexYOzztscvRYje1xTNmXJbi99oJxCaVJAwKfTNTF_E,13610
 mdb_engine/core/seeding.py,sha256=c5IhdwlqUf_4Q5FFTAhPLaHPaUr_Txo3z_DUwZmWsFs,6421
 mdb_engine/core/service_initialization.py,sha256=rtb6BaPvFqomwT_s7bdbbvqi5m74llT0LkJFEhVG9Gg,12996
@@ -67,14 +67,14 @@ mdb_engine/di/scopes.py,sha256=pZgdkZ9ziW-vYCMvecC8Mv3Ud_Xk4ScsDYZ2eWHvar0,4165
 mdb_engine/embeddings/README.md,sha256=XjGWUXSdbSpXCAEEVfYmcJoFKBVmXDoM3eTjenrM5Z0,5926
 mdb_engine/embeddings/__init__.py,sha256=BM8tfcekVZv_iPQj3OuZBQ3hHr0eRQetNLEMysRTZkE,2129
 mdb_engine/embeddings/dependencies.py,sha256=0LIEU5L1jvZBKO4yhYxh4WxDhzJaZI9ohZGBNa6B7IY,2182
-mdb_engine/embeddings/service.py,sha256=yqVplODYLwWpEagv3mwS7n1-WXt2U-TluHwNi_BQ9Uc,25807
+mdb_engine/embeddings/service.py,sha256=3JUqAU-e5TVLOpry5MdP-O4q6tHoqkXA8PyvcxqFoik,26983
 mdb_engine/indexes/README.md,sha256=r7duq-1vtqHhBk1cwoBMYYh_dfTzxiaQaPE3mLB_3JQ,15341
 mdb_engine/indexes/__init__.py,sha256=9QFJ6qo_yD26dZcKyKjj-hhesFpaomBt-mWTtYTQvqc,613
 mdb_engine/indexes/helpers.py,sha256=tJHqDm18jKLrW-P2ofmnUnaf4_-V5xDLjqP_WU8W9MM,4190
 mdb_engine/indexes/manager.py,sha256=XSjvFNMOv67yey5Vi4mKBt6_w4b6Hqtv24fiAXnfLi0,32460
-mdb_engine/memory/README.md,sha256=vy2FSXADcqG18YrFBfrMph9a1vYKuLijhs8ziNFdvRk,10631
+mdb_engine/memory/README.md,sha256=uOE4SnPyq8TdoxGrttof5fSj2KSqnrgzUorMCV_1wg0,13624
 mdb_engine/memory/__init__.py,sha256=e4kAYgxd_-WAH8GovTwjEBO9hvASu_kXEupMgksAL-U,1008
-mdb_engine/memory/service.py,sha256=zX0oaHs8SHikH1fX4CtRF5pbOu1swEoiy3Segz_nLZI,47461
+mdb_engine/memory/service.py,sha256=l2bkKVN9AyUjO9K9ykb5BK9dZjs3ns78FJLOD5LajsY,18454
 mdb_engine/observability/README.md,sha256=CMgQaC1H8ESmCitfbhJifz6-XoXH_FPNE4MvuZ-oFas,13085
 mdb_engine/observability/__init__.py,sha256=jjLsrW6Gy2ayrbfLrgHsDB61NxWWkYLHwv0q-N3fxjA,1213
 mdb_engine/observability/health.py,sha256=eFd8a-Rv3NWML0EDdZ8thZWTiqP_FUZbub97hV2z57g,9190
@@ -87,10 +87,11 @@ mdb_engine/repositories/unit_of_work.py,sha256=XvmwGOspEDj4hsfOULPsQKjB1QZqh83TJ
 mdb_engine/routing/README.md,sha256=WVvTQXDq0amryrjkCu0wP_piOEwFjLukjmPz2mroWHY,13658
 mdb_engine/routing/__init__.py,sha256=reupjHi_RTc2ZBA4AH5XzobAmqy4EQIsfSUcTkFknUM,2438
 mdb_engine/routing/websockets.py,sha256=3X4OjQv_Nln4UmeifJky0gFhMG8A6alR77I8g1iIOLY,29311
-mdb_engine/utils/__init__.py,sha256=_xjHB5p6WLWBql1DyDqf5zdjj2xpfMlK25Y6BH9-oFk,145
-mdb_engine-0.2.3.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-mdb_engine-0.2.3.dist-info/METADATA,sha256=-GUB0bt3MSLlo3Ayigjb2NnA2rZBPtdXrgq7oI0gBEE,10490
-mdb_engine-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mdb_engine-0.2.3.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
-mdb_engine-0.2.3.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
-mdb_engine-0.2.3.dist-info/RECORD,,
+mdb_engine/utils/__init__.py,sha256=lDxQSGqkV4fVw5TWIk6FA6_eey_ZnEtMY0fir3cpAe8,236
+mdb_engine/utils/mongo.py,sha256=Oqtv4tQdpiiZzrilGLEYQPo8Vmh8WsTQypxQs8Of53s,3369
+mdb_engine-0.2.4.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+mdb_engine-0.2.4.dist-info/METADATA,sha256=DRYO0436-KCFjF-HHi1deGWWoO0Yq3vzKl53qow2ldE,12750
+mdb_engine-0.2.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mdb_engine-0.2.4.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
+mdb_engine-0.2.4.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
+mdb_engine-0.2.4.dist-info/RECORD,,

{mdb_engine-0.2.3.dist-info → mdb_engine-0.2.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any