mdb-engine 0.2.3__tar.gz → 0.2.4__tar.gz

{mdb_engine-0.2.3/mdb_engine.egg-info → mdb_engine-0.2.4}/PKG-INFO

@@ -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 → mdb_engine-0.2.4}/README.md

@@ -8,6 +8,31 @@
 
 ---
 
+## 🎯 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
@@ -18,28 +43,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.
 
 ---
@@ -135,9 +187,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"}'`
 
 ---
@@ -235,13 +289,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 → mdb_engine-0.2.4}/mdb_engine/__init__.py

@@ -78,7 +78,10 @@ from .indexes import (
 # Repository pattern
 from .repositories import Entity, MongoRepository, Repository, UnitOfWork
 
-__version__ = "0.2.1"  # Major version bump for new DI system
+# Utilities
+from .utils import clean_mongo_doc, clean_mongo_docs
+
+__version__ = "0.2.4"  # Patch version bump for exception handling improvements
 
 __all__ = [
     # Core Engine
@@ -127,4 +130,7 @@ __all__ = [
     "AsyncAtlasIndexManager",
     "AutoIndexManager",
     "run_index_creation_for_collection",
+    # Utilities
+    "clean_mongo_doc",
+    "clean_mongo_docs",
 ]

{mdb_engine-0.2.3 → mdb_engine-0.2.4}/mdb_engine/auth/README.md

@@ -42,6 +42,10 @@ All apps share a central user pool. Users authenticate once and can access any a
 {
   "auth": {
     "mode": "shared",
+    "auth_hub_url": "http://localhost:8000",
+    "related_apps": {
+      "dashboard": "http://localhost:8001"
+    },
     "roles": ["viewer", "editor", "admin"],
     "default_role": "viewer",
     "require_role": "viewer",
@@ -60,6 +64,8 @@ All apps share a central user pool. Users authenticate once and can access any a
 | Field | Description |
 |-------|-------------|
 | `roles` | Available roles for this app |
+| `auth_hub_url` | URL of the authentication hub for SSO apps. Used for redirecting unauthenticated users to login. Can be overridden via `AUTH_HUB_URL` environment variable |
+| `related_apps` | Map of related app slugs to their URLs for cross-app navigation. Keys are app slugs, values are URLs. Can be overridden via `{APP_SLUG_UPPER}_URL` environment variables |
 | `default_role` | Role assigned to new users |
 | `require_role` | Minimum role required to access app |
 | `public_routes` | Routes that don't require authentication |