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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.2.3
+Version: 0.3.0
 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
@@ -81,31 +106,162 @@ pip install mdb-engine
 
 ---
 
-## 30-Second Quick Start
+## 30-Second Quick Start: Build a Todo List API
+
+Let's build a complete CRUD todo list app in 3 steps!
+
+### Step 1: Create `manifest.json`
+
+```json
+{
+  "schema_version": "2.0",
+  "slug": "todo_app",
+  "name": "Todo List App",
+  "managed_indexes": {
+    "todos": [
+      {
+        "type": "regular",
+        "keys": {"completed": 1, "created_at": -1},
+        "name": "completed_sort"
+      }
+    ]
+  }
+}
+```
+
+### Step 2: Create `app.py` with Full CRUD
 
 ```python
+from datetime import datetime
 from pathlib import Path
-from fastapi import Depends
+from typing import Optional
+
+from bson import ObjectId
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+
 from mdb_engine import MongoDBEngine
 from mdb_engine.dependencies import get_scoped_db
 
-# 1. Initialize the engine
+# Initialize engine
 engine = MongoDBEngine(
     mongo_uri="mongodb://localhost:27017",
     db_name="my_database"
 )
 
-# 2. Create a FastAPI app with automatic lifecycle management
-app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+# Create app - manifest.json loaded automatically!
+app = engine.create_app(
+    slug="todo_app",
+    manifest=Path("manifest.json")
+)
 
-# 3. 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)}
+# Pydantic models
+class TodoCreate(BaseModel):
+    title: str
+    description: Optional[str] = None
+
+class TodoUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    completed: Optional[bool] = None
+
+# CREATE - Add a new todo
+@app.post("/todos")
+async def create_todo(todo: TodoCreate, db=Depends(get_scoped_db)):
+    doc = {
+        **todo.dict(),
+        "completed": False,
+        "created_at": datetime.utcnow()
+    }
+    result = await db.todos.insert_one(doc)
+    return {"id": str(result.inserted_id), "message": "Todo created"}
+
+# READ - List all todos
+@app.get("/todos")
+async def list_todos(completed: Optional[bool] = None, db=Depends(get_scoped_db)):
+    query = {}
+    if completed is not None:
+        query["completed"] = completed
+    
+    todos = await db.todos.find(query).sort("created_at", -1).to_list(length=100)
+    for todo in todos:
+        todo["_id"] = str(todo["_id"])
+    return {"todos": todos, "count": len(todos)}
+
+# READ - Get single todo
+@app.get("/todos/{todo_id}")
+async def get_todo(todo_id: str, db=Depends(get_scoped_db)):
+    todo = await db.todos.find_one({"_id": ObjectId(todo_id)})
+    if not todo:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    todo["_id"] = str(todo["_id"])
+    return todo
+
+# UPDATE - Update a todo
+@app.put("/todos/{todo_id}")
+async def update_todo(todo_id: str, todo: TodoUpdate, db=Depends(get_scoped_db)):
+    updates = {k: v for k, v in todo.dict(exclude_unset=True).items() if v is not None}
+    if not updates:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    
+    updates["updated_at"] = datetime.utcnow()
+    result = await db.todos.update_one(
+        {"_id": ObjectId(todo_id)},
+        {"$set": updates}
+    )
+    
+    if result.matched_count == 0:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return {"message": "Todo updated"}
+
+# DELETE - Delete a todo
+@app.delete("/todos/{todo_id}")
+async def delete_todo(todo_id: str, db=Depends(get_scoped_db)):
+    result = await db.todos.delete_one({"_id": ObjectId(todo_id)})
+    if result.deleted_count == 0:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return {"message": "Todo deleted"}
+```
+
+### Step 3: Run It!
+
+```bash
+# Start MongoDB (if not running)
+mongod
+
+# Install dependencies
+pip install mdb-engine fastapi uvicorn
+
+# Run the app
+uvicorn app:app --reload
+```
+
+**Test your API:**
+```bash
+# Create a todo
+curl -X POST http://localhost:8000/todos \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Buy groceries", "description": "Milk and eggs"}'
+
+# List todos
+curl http://localhost:8000/todos
+
+# Update a todo (replace {id} with actual ID)
+curl -X PUT http://localhost:8000/todos/{id} \
+  -H "Content-Type: application/json" \
+  -d '{"completed": true}'
+
+# Delete a todo
+curl -X DELETE http://localhost:8000/todos/{id}
 ```
 
-That's it. Your data is automatically sandboxed, indexes are created, and cleanup is handled.
+**What just happened?**
+- ✅ **Automatic scoping**: All queries filtered by `app_id` — your data is isolated
+- ✅ **Indexes created**: The `completed_sort` index was created automatically
+- ✅ **Lifecycle managed**: Startup/shutdown handled automatically
+- ✅ **Zero boilerplate**: No connection setup, no index scripts, no auth handlers
+
+**That's it!** You now have a fully functional, production-ready todo API with automatic data sandboxing, index management, and lifecycle handling.
 
 ---
 
@@ -200,9 +356,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 +458,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.3.0}/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
@@ -16,31 +41,162 @@ pip install mdb-engine
 
 ---
 
-## 30-Second Quick Start
+## 30-Second Quick Start: Build a Todo List API
+
+Let's build a complete CRUD todo list app in 3 steps!
+
+### Step 1: Create `manifest.json`
+
+```json
+{
+  "schema_version": "2.0",
+  "slug": "todo_app",
+  "name": "Todo List App",
+  "managed_indexes": {
+    "todos": [
+      {
+        "type": "regular",
+        "keys": {"completed": 1, "created_at": -1},
+        "name": "completed_sort"
+      }
+    ]
+  }
+}
+```
+
+### Step 2: Create `app.py` with Full CRUD
 
 ```python
+from datetime import datetime
 from pathlib import Path
-from fastapi import Depends
+from typing import Optional
+
+from bson import ObjectId
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+
 from mdb_engine import MongoDBEngine
 from mdb_engine.dependencies import get_scoped_db
 
-# 1. Initialize the engine
+# Initialize engine
 engine = MongoDBEngine(
     mongo_uri="mongodb://localhost:27017",
     db_name="my_database"
 )
 
-# 2. Create a FastAPI app with automatic lifecycle management
-app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+# Create app - manifest.json loaded automatically!
+app = engine.create_app(
+    slug="todo_app",
+    manifest=Path("manifest.json")
+)
 
-# 3. 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)}
+# Pydantic models
+class TodoCreate(BaseModel):
+    title: str
+    description: Optional[str] = None
+
+class TodoUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    completed: Optional[bool] = None
+
+# CREATE - Add a new todo
+@app.post("/todos")
+async def create_todo(todo: TodoCreate, db=Depends(get_scoped_db)):
+    doc = {
+        **todo.dict(),
+        "completed": False,
+        "created_at": datetime.utcnow()
+    }
+    result = await db.todos.insert_one(doc)
+    return {"id": str(result.inserted_id), "message": "Todo created"}
+
+# READ - List all todos
+@app.get("/todos")
+async def list_todos(completed: Optional[bool] = None, db=Depends(get_scoped_db)):
+    query = {}
+    if completed is not None:
+        query["completed"] = completed
+    
+    todos = await db.todos.find(query).sort("created_at", -1).to_list(length=100)
+    for todo in todos:
+        todo["_id"] = str(todo["_id"])
+    return {"todos": todos, "count": len(todos)}
+
+# READ - Get single todo
+@app.get("/todos/{todo_id}")
+async def get_todo(todo_id: str, db=Depends(get_scoped_db)):
+    todo = await db.todos.find_one({"_id": ObjectId(todo_id)})
+    if not todo:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    todo["_id"] = str(todo["_id"])
+    return todo
+
+# UPDATE - Update a todo
+@app.put("/todos/{todo_id}")
+async def update_todo(todo_id: str, todo: TodoUpdate, db=Depends(get_scoped_db)):
+    updates = {k: v for k, v in todo.dict(exclude_unset=True).items() if v is not None}
+    if not updates:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    
+    updates["updated_at"] = datetime.utcnow()
+    result = await db.todos.update_one(
+        {"_id": ObjectId(todo_id)},
+        {"$set": updates}
+    )
+    
+    if result.matched_count == 0:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return {"message": "Todo updated"}
+
+# DELETE - Delete a todo
+@app.delete("/todos/{todo_id}")
+async def delete_todo(todo_id: str, db=Depends(get_scoped_db)):
+    result = await db.todos.delete_one({"_id": ObjectId(todo_id)})
+    if result.deleted_count == 0:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return {"message": "Todo deleted"}
+```
+
+### Step 3: Run It!
+
+```bash
+# Start MongoDB (if not running)
+mongod
+
+# Install dependencies
+pip install mdb-engine fastapi uvicorn
+
+# Run the app
+uvicorn app:app --reload
+```
+
+**Test your API:**
+```bash
+# Create a todo
+curl -X POST http://localhost:8000/todos \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Buy groceries", "description": "Milk and eggs"}'
+
+# List todos
+curl http://localhost:8000/todos
+
+# Update a todo (replace {id} with actual ID)
+curl -X PUT http://localhost:8000/todos/{id} \
+  -H "Content-Type: application/json" \
+  -d '{"completed": true}'
+
+# Delete a todo
+curl -X DELETE http://localhost:8000/todos/{id}
 ```
 
-That's it. Your data is automatically sandboxed, indexes are created, and cleanup is handled.
+**What just happened?**
+- ✅ **Automatic scoping**: All queries filtered by `app_id` — your data is isolated
+- ✅ **Indexes created**: The `completed_sort` index was created automatically
+- ✅ **Lifecycle managed**: Startup/shutdown handled automatically
+- ✅ **Zero boilerplate**: No connection setup, no index scripts, no auth handlers
+
+**That's it!** You now have a fully functional, production-ready todo API with automatic data sandboxing, index management, and lifecycle handling.
 
 ---
 
@@ -135,9 +291,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 +393,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.3.0}/mdb_engine/__init__.py

@@ -78,7 +78,11 @@ 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.3.0"  # Minor version bump: Multi-app mounting, SSO improvements,
+# and exception handling fixes
 
 __all__ = [
     # Core Engine
@@ -127,4 +131,7 @@ __all__ = [
     "AsyncAtlasIndexManager",
     "AutoIndexManager",
     "run_index_creation_for_collection",
+    # Utilities
+    "clean_mongo_doc",
+    "clean_mongo_docs",
 ]

{mdb_engine-0.2.3 → mdb_engine-0.3.0}/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 |