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:pass@cluster.mongodb.net/"

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.

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:

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.

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

MongoDB Connection Reference

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

# Option A: environment variable
export MONGODB_URI="mongodb+srv://user:password@cluster.mongodb.net/"

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

Environment Variables

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.