mdb-engine 0.11.0

MongoDB Engine

mdb-engine

The MongoDB Engine for Python Apps — Auto-sandboxing, index management, and AI services in one package.

Get Running in 60 Seconds

Step 1: Start MongoDB

You need a running MongoDB instance. Pick one:

# Local (Docker) — full Atlas features including Vector Search
docker run -d --name mongodb -p 27017:27017 mongodb/mongodb-atlas-local:latest

Or use MongoDB Atlas (free tier):

export MONGODB_URI="mongodb+srv://user:[e-mail]/"

Step 2: Install and run

pip install mdb-engine fastapi uvicorn

Create web.py:

from mdb_engine import quickstart
from mdb_engine.dependencies import get_scoped_db
from fastapi import Depends

app = quickstart("my_app")

@app.get("/items")
async def list_items(db=Depends(get_scoped_db)):
    return await db.items.find({}).to_list(10)

uvicorn web:app --reload

Open http://localhost:8000/items -- you're live.

Using AI features? You'll also need an API key: export OPENAI_API_KEY=sk-... (or ANTHROPIC_API_KEY, GEMINI_API_KEY). See Environment Variables for the full list.

What you get automatically:

• Data isolation — every query is scoped by app_id; you cannot accidentally leak data across apps
• Collection prefixing — db.items transparently becomes my_app_items
• Lifecycle management — engine startup/shutdown handled for you
• Dependency injection — get_scoped_db, get_memory_service, etc. ready to use

---

Installation

pip install mdb-engine

---

Feature Layers

mdb-engine is designed for progressive adoption. Start with Layer 0 and add features as you need them.

Layer	What it gives you	How to enable
0: Scoped DB + Indexes	Auto-sandboxed collections, declarative indexes	quickstart("slug") or minimal manifest
1: Auth + GDPR	JWT, RBAC (Casbin/OSO), SSO, data export/deletion	Add auth section to manifest
2: LLM + Embeddings + Memory	Persistent AI memory, semantic search, fact extraction	Add llm_config + memory_config to manifest
3: GraphRAG + ChatEngine	Knowledge graphs, conversation orchestration with STM + LTM	Add graph_config, use ChatEngine

---

Three Ways to Create an App

1. Zero-config (quickstart)

No manifest file, no explicit connection string. Best for getting started.

from mdb_engine import quickstart

app = quickstart("my_app")

2. Inline manifest (dict)

Pass configuration directly in Python. Good for programmatic setups.

from mdb_engine import MongoDBEngine

engine = MongoDBEngine()
app = engine.create_app(
    slug="my_app",
    manifest={
        "schema_version": "2.0",
        "slug": "my_app",
        "name": "My App",
        "managed_indexes": {
            "tasks": [{"type": "regular", "keys": {"status": 1}, "name": "status_idx"}]
        },
    },
)

3. File-based manifest (recommended for production)

The full-featured approach. A single manifest.json defines your app's identity, indexes, auth, AI services, and more.

from pathlib import Path
from mdb_engine import MongoDBEngine

engine = MongoDBEngine(
    mongo_uri="mongodb+srv://...",  # or set MONGODB_URI env var
    db_name="production"
)
app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))

Minimal manifest.json (3 fields):

{
  "schema_version": "2.0",
  "slug": "my_app",
  "name": "My App"
}

Learn more: Manifest Reference | Quick Start Guide

4. Zero-Code Manifest (no Python at all)

A single manifest.json defines a production-grade REST API — auth, CRUD, hooks, relations, computed fields, unique constraints, TTL — without writing a line of Python.

mdb-engine serve manifest.json

Thirteen declarative collection primitives:

Primitive	What it does
schema	JSON Schema validation on every write
defaults	Auto-populate fields on create ({{user.*}}, $$NOW)
owner_field	Auto-inject creator ID, enforce ownership, admin bypass
immutable_fields	Silently strip protected fields from updates
hooks	Fire-and-forget side effects (after_create, after_update, after_delete)
relations	Declarative joins via ?populate=name
computed	Virtual fields via ?computed=name (aggregation at read time)
scopes	Named MQL filters via ?scope=name (with optional auth gates)
pipelines	Named aggregation endpoints at /_agg/{name}
policy	Document-level read/write/delete access policies
x-unique	Schema-driven unique indexes (409 on duplicates)
ttl	Auto-expiring documents ("expire_after": "90d")
auth	Role-based access for reads, creates, and mutations

Real-world example — a blog post collection with audit trail, computed comment counts, and ownership enforcement:

{
  "posts": {
    "auto_crud": true,
    "soft_delete": true,
    "owner_field": "author_id",
    "immutable_fields": ["author_id"],
    "auth": { "write_roles": ["admin"] },
    "defaults": { "status": "draft", "author": "{{user.email}}" },
    "scopes": { "published": { "status": "published" } },
    "hooks": {
      "after_create": [{ "action": "insert", "collection": "audit_log", "document": {
        "event": "post_created", "entity_id": "{{doc._id}}", "actor": "{{user.email}}", "timestamp": "$$NOW"
      }}]
    },
    "computed": {
      "comment_count": { "pipeline": [
        { "$lookup": { "from": "comments", "let": { "pid": { "$toString": "$_id" } },
          "pipeline": [{ "$match": { "$expr": { "$eq": ["$post_id", "$$pid"] }}}], "as": "_c" }},
        { "$addFields": { "comment_count": { "$size": "$_c" } } },
        { "$project": { "_c": 0 } }
      ]}
    }
  }
}

See it in action: zero_code_api — a complete blog with auth, comments, categories, and audit log.

---

Examples Ladder

Start simple, add complexity when you need it.

Example	What it shows	Lines of Python
zero_code_api	Blog with auth, hooks, relations, computed fields, unique, TTL — all manifest	0
hello_world	Zero-config CRUD, no manifest	~15
memory_quickstart	AI memory with semantic search	~25
chit_chat	Full AI chat with ChatEngine, auth, WebSockets	~2400
interactive_rag	RAG with vector search	—
simple_app	Task management with create_app() pattern	—
sso-multi-app	SSO with shared user pool across apps	—

---

CRUD Operations (Auto-Scoped)

All database operations are automatically scoped to your app:

from mdb_engine.dependencies import get_scoped_db

@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)}

@app.get("/tasks")
async def list_tasks(db=Depends(get_scoped_db)):
    return await db.tasks.find({"status": "pending"}).to_list(length=10)

Under the hood:

# You write:
await db.tasks.find({}).to_list(length=10)

# Engine executes:
# Collection: my_app_tasks
# Query: {"app_id": "my_app"}

---

AI Memory (MemoryService)

Add persistent, searchable AI memory to any app.

from mdb_engine.dependencies import get_memory_service

@app.post("/remember")
async def remember(text: str, memory=Depends(get_memory_service)):
    result = await memory.add(messages=text, user_id="user1")
    return {"stored": result}

@app.get("/recall")
async def recall(q: str, memory=Depends(get_memory_service)):
    results = await memory.search(query=q, user_id="user1")
    return {"results": results}

Note: All memory operations are async. Use await directly in your routes.

Enable in your manifest:

{
  "llm_config": {"enabled": true, "default_model": "openai/gpt-4o-mini"},
  "embedding_config": {"enabled": true, "default_embedding_model": "text-embedding-3-small"},
  "memory_config": {"enabled": true, "provider": "cognitive", "infer": true}
}

Optional cognitive features (add to memory_config):

• Importance scoring: AI evaluates memory significance
• Memory reinforcement: Similar memories strengthen each other
• Memory decay: Less relevant memories fade over time
• Memory merging: Related memories combined intelligently

---

ChatEngine (Conversation Orchestration)

ChatEngine (formerly CognitiveEngine) orchestrates full conversations with short-term memory (chat history) + long-term memory (semantic search):

from mdb_engine.memory import ChatEngine

cognitive = ChatEngine(
    app_slug="my_app",
    memory_service=memory_service,
    chat_history_collection=db.chat_history,
    llm_provider=llm_provider,
)

result = await cognitive.chat(
    user_id="user123",
    session_id="session456",
    user_query="What did we discuss about the project?",
    system_prompt="You are a helpful assistant.",
    extract_facts=True,
)

---

RequestContext (All Services in One Place)

from mdb_engine import RequestContext, get_request_context

@app.post("/ai-chat")
async def chat(query: str, ctx: RequestContext = Depends(get_request_context)):
    user = ctx.require_user()       # 401 if not logged in
    ctx.require_role("user")        # 403 if missing role

    # ctx.db, ctx.memory, ctx.llm, ctx.embedding_service — all available
    if ctx.llm:
        response = ctx.llm.chat.completions.create(
            model=ctx.llm_model,
            messages=[{"role": "user", "content": query}]
        )
        return {"response": response.choices[0].message.content}

---

Index Management

Define indexes in manifest.json — they're auto-created on startup:

{
  "managed_indexes": {
    "tasks": [
      {"type": "regular", "keys": {"status": 1, "created_at": -1}, "name": "status_sort"},
      {"type": "regular", "keys": {"email": 1}, "name": "email_unique", "unique": true}
    ]
  }
}

Supported index types: regular, text, vector, ttl, compound.

---

Advanced Features

Feature	Description	Learn More
Authentication	JWT + Casbin/OSO RBAC	Bible: Auth
Vector Search	Atlas Vector Search + embeddings	RAG Example
MemoryService	Persistent AI memory with cognitive features	Memory Docs
GraphService	Knowledge graph with $graphLookup traversal	Graph Docs
ChatEngine	Full RAG pipeline with STM + LTM	Chat Example
WebSockets	Real-time updates from manifest config	Bible: WebSockets
Multi-App	Secure cross-app data access	SSO Example
SSO	Shared auth across apps	SSO Example
GDPR	Data discovery, export, deletion, rectification	Bible: GDPR

---

MongoDB Connection Reference

mdb-engine connects to mongodb://localhost:27017 by default. Override via env var or constructor:

Setup	Connection String
Local / Docker	mongodb://localhost:27017 (default, no config needed)
Atlas (free tier)	mongodb+srv://user:[e-mail]/dbname

# Option A: environment variable
export MONGODB_URI="mongodb+srv://user:[e-mail]/"

# Option B: in code
engine = MongoDBEngine(mongo_uri="mongodb+srv://...")

---

Environment Variables

Variable	Required	Purpose
MONGODB_URI	No	MongoDB connection string (default: localhost:27017)
MDB_DB_NAME	No	Database name (default: mdb_engine)
OPENAI_API_KEY	For AI features	OpenAI API key for LLM/embeddings
ANTHROPIC_API_KEY	For AI features	Anthropic API key (alternative to OpenAI)
GEMINI_API_KEY	For AI features	Google Gemini API key (alternative to OpenAI)
MDB_JWT_SECRET	For auth	JWT signing secret for shared auth mode

---

Why mdb-engine?

• Zero to running in 3 lines — quickstart("my_app") and go
• Data isolation built in — multi-tenant ready with automatic app sandboxing
• manifest.json is everything — single source of truth for your app config
• Incremental adoption — start minimal, add features as needed
• No lock-in — standard Motor/PyMongo underneath; export with mongodump --query='{"app_id":"my_app"}'

---

Links

• GitHub Repository
• Documentation
• All Examples
• Quick Start Guide — Start here!
• Manifest Reference
• Contributing

---

Stop building scaffolding. Start building features.