lenapi 0.1.2__tar.gz → 0.1.3__tar.gz

{lenapi-0.1.2 → lenapi-0.1.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: lenapi
-Version: 0.1.2
+Version: 0.1.3
 Summary: A modern ASGI framework with Pydantic validation, sync and async database access, WebSockets, authentication, and integrated API documentation.
 Author: Maekandex Communication Limitation
 Author-email: "Ifeanyi M. Onovo" <ifeanyi@maekandex.com.ng>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/Mikandex/lenapi
 Project-URL: Repository, https://github.com/Mikandex/lenapi
-Project-URL: Documentation, https://github.com/Mikandex/lenapi_documentation
+Project-URL: Documentation, https://lenapi.site/
 Project-URL: Issues, https://github.com/Mikandex/lenapi/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -46,6 +46,8 @@ Provides-Extra: async-mysql
 Requires-Dist: asyncmy>=0.2; extra == "async-mysql"
 Provides-Extra: mongodb
 Requires-Dist: pymongo<5,>=4.13; extra == "mongodb"
+Provides-Extra: monitoring
+Requires-Dist: psutil<8,>=5.9; extra == "monitoring"
 Dynamic: license-file
 
 # lenApi
@@ -58,6 +60,18 @@ LenAPI aims to reduce repetitive code and simplify common integrations, helping
 
 **LenAPI — Compact by Design, Powerful by Capability.**
 
+## Feature overview
+
+- Typed HTTP routes with Pydantic request and response validation, Swagger UI, and ReDoc.
+- Synchronous and asynchronous ORM operations, migrations, transactions, search, aggregates, and pagination for SQLite, MySQL, and PostgreSQL. MongoDB document support is currently in beta.
+- Authentication building blocks for JWT, API keys, HTTP Basic, sessions, opaque bearer tokens, HMAC, OIDC, and social sign-in.
+- WebSockets for chat, video signaling, JSON, text, and binary messages; webhook handlers with optional HMAC verification; cache and durable background jobs with retries and delayed execution.
+- Validated public and private file uploads, middleware, throttling, and optional gzip compression.
+- An optional model admin console with explicit model/field allow-lists, per-model permissions, and CPU/RAM/process monitoring.
+- Independent generated projects that can run separately or be mounted under a path in a primary project.
+
+See the [LenAPI documentation](https://lenapi.site/) for setup guides and runnable examples.
+
 ## Python versions
 
 LenAPI is tested and supported on Python 3.11 through 3.14. Python 3.10 reached
@@ -523,6 +537,8 @@ Run `python lenora.py apikey` inside a project to set `AUTHENTICATION = "api_key
 
 `settings.py` centralizes the API title/version, docs and OpenAPI URLs, host, port, database selection, token settings, and shared security storage. `HOST = ""` uses `127.0.0.1`; set `HOST` directly to bind another address. `app = LENAPI()` loads project settings automatically. Each generated project gets a unique high-entropy `SECRET_KEY`; `TOKEN` uses it to sign tokens and configures token lifetime and issuer. Keep the key private. Changing it invalidates tokens signed with the old key. `DATABASE_TYPE` chooses one backend (`sqlite`, `mysql`, `postgresql`, or `mongodb`), and `DATABASE_URL` configures it. `ACTIVATE_ASYNC` enables asynchronous access using the same database URL. The default database is SQLite.
 
+Generated projects set `DEBUG = True` for local development. Unexpected route or dependency errors then print a traceback to the terminal. LenAPI returns a generic `500 Internal Server Error` response to the client in both debug modes; request validation errors and explicit `HTTPException` responses keep their normal status codes. Set `DEBUG = False` in production to stop LenAPI from printing exception tracebacks. If `DEBUG` is absent, LenAPI defaults to `False`.
+
 ## Automated tests
 
 Pytest is installed with lenApi, so you can run the framework test suite from the repository root:
@@ -849,6 +865,117 @@ The docs gate only handles `/`, `/logout`, the configured Swagger and ReDoc path
 
 To remove the gate, set `SAFE_GUARD_DOCS_URL = False` and restart the app. The admin tables may remain in the database; they are not queried while the feature is disabled.
 
+### Built-in model admin and resource monitor
+
+The optional admin console is separate from the Swagger/ReDoc login and is served at `/admin/`. It uses stateless HTTP Basic authentication for its API requests. Enable it in `settings.py`, then run a migration and create an administrator. The first CLI-created superadmin has full access and can create other admin accounts and grant per-model permissions. If the project already had docs-admin accounts before this feature, create an additional account with the CLI; it becomes superadmin if no superadmin exists yet.
+
+```python
+# settings.py
+ADMIN_ENABLED = True
+ADMIN_URL = "/admin/"
+ADMIN_SESSION_LIFETIME_SECONDS = 3600
+ADMIN_COOKIE_SECURE = None  # follows the ASGI HTTPS scheme
+
+# Monitoring is optional and requires the admin console to be enabled.
+ADMIN_MONITORING_ENABLED = True
+```
+
+```bash
+python lenora.py migration
+python lenora.py admin
+python lenora.py run
+```
+
+The first SQL migration includes the framework `AdminUser` fields and session storage along with the imported app models. MongoDB initializes the admin collections through `migration`. Mongo collections need a corresponding `MongoDocument` class so the admin can safely render typed edit forms.
+
+Create `app/admin.py` to explicitly allow-list models and choose which fields are visible. Once this file exists, only models registered there appear in the console. `fields` selects displayed/editable fields, `readonly` displays selected fields without allowing changes, and `exclude` hides fields. Credential-like fields such as `password`, `api_key`, and `key_digest` remain hidden even if listed; use application routes that hash or rotate credentials.
+
+```python
+# app/admin.py
+from lenapi.admin import admin
+from .models import Student, Course, Invoice, Staff
+
+admin.register(
+    Student,
+    fields=("person_name", "course", "email", "profile_image"),
+    readonly=("email",),
+    exclude=("password", "private_notes"),
+)
+
+admin.register(
+    Course,
+    fields=("title", "description", "duration_weeks", "is_active"),
+)
+
+admin.register(
+    Invoice,
+    fields=("invoice_number", "student_id", "amount", "status", "issued_at"),
+    readonly=("invoice_number", "issued_at"),
+    exclude=("payment_token", "provider_response"),
+)
+
+admin.register(
+    Staff,
+    fields=("name", "work_email", "department"),
+    readonly=("work_email",),
+    exclude=("password", "salary", "hr_notes"),
+)
+```
+
+When `app/admin.py` is absent, the console keeps its backward-compatible model discovery. Registered models show only the selected columns; readonly fields appear in record forms without editable controls, and excluded fields are omitted from both the UI and the API response. Update requests are checked against the same field allow-list. The console supports list/read, update, and delete; record creation is handled by application endpoints. Superadmins grant `view`, `read`, `write`, and `delete` independently. `view` controls whether a model appears in the sidebar, `read` allows listing records, `write` permits updates, and `delete` controls deletion.
+
+Admin accounts and model records use the selected SQL database or MongoDB. Disable the console with `ADMIN_ENABLED = False`; set `ADMIN_MONITORING_ENABLED = False` to hide its monitor. Resource metrics are available only to a superadmin when both settings are enabled:
+
+```bash
+python -m pip install 'lenapi[monitoring]'
+```
+
+The Resource Monitor page shows CPU and RAM metric cards with rolling graphs, plus the LenAPI process PID and thread count. RAM shows process resident memory and total system-memory use. Metrics refresh every two seconds while the page is open; history remains in that browser page only. The endpoint is restricted to superadmins. This is an operational status view, not a host monitoring or alerting system. Monitoring requires psutil and does not start background sampling.
+
+When a main LenAPI project mounts sibling projects, the main project's `/admin/` is the single admin entry point. It groups each mounted project's explicitly registered models under that project's name and reads or updates records through that project's own database. Enable `ADMIN_ENABLED` and create the admin account only in the main project. Keep `ADMIN_ENABLED = False` in mounted projects; they contribute their `app/admin.py` registrations but do not need their own admin login. The mount must be configured with `app.mount(...)` for the main admin to discover that project.
+
+In generated projects, prefer a relative model import in `app/admin.py` so project names and mounts remain unambiguous:
+
+```python
+from lenapi.admin import admin
+from .models import Student, Course
+
+admin.register(Student, fields=("person_name", "course"))
+admin.register(Course, fields=("title", "is_active"))
+```
+
+Per-model permissions for the main project keep their existing model-name keys. Mounted-project permissions use `<project_name>:<model_name>`, for example `games:student`, so same-named models in different projects stay separate.
+
+### Mount independent projects
+
+Every generated project keeps its own settings, models, migrations, and database configuration. Run projects independently on different ports, or mount a sibling project into a primary app at any URL prefix you choose. A mount prefix does not need to match the sibling project's name.
+
+```python
+# win/main.py — primary application
+from lenapi import LENAPI
+
+app = LENAPI()
+app.mount("/gamer", "games")
+```
+
+The sibling project must be in the same parent directory and have its own generated `settings.py` with a `PROJECT_NAME`:
+
+```text
+workspace/
+├── win/
+│   ├── main.py
+│   ├── settings.py
+│   └── app/
+└── games/
+    ├── main.py
+    ├── settings.py
+    └── app/
+```
+
+The mounted app keeps its own database URL and project namespace. Its routes are reachable under `/gamer/`, while its own docs paths are under `/gamer/docs/` and `/gamer/redoc/`. Project table names include the project's namespace so separate apps sharing one database do not collide. Mounting is optional; independent projects can instead run on separate ports or deployments.
+
+For the shared admin console, enable `ADMIN_ENABLED` and create the admin account only in the primary project. Register models explicitly in each project's `app/admin.py`; after mounting, the primary `/admin/` groups those models by project and performs their data operations against each project's configured database. Keep `ADMIN_ENABLED = False` in mounted projects. Each mounted app instance can belong to only one parent admin.
+
 The sample app exposes the model queries as HTTP routes: `POST /classrooms` creates a classroom, `GET /classrooms` lists them, and `POST /students` accepts an optional `classroom_id`. `POST /students/batch` creates multiple students, `PUT /students/batch` updates multiple students by ID, and `DELETE /students/batch` deletes multiple students by ID. Batch requests are all-or-nothing: unknown IDs, duplicate names, or a protected deletion reject the whole operation. `PUT /students/{student_id}` updates one student; it returns HTTP 404 if the ID does not exist. `GET /students/{student_id}/classroom` returns the related classroom. Other student routes list, search, and check existence. These routes appear in Swagger at `/docs/`.
 
 Batch request examples:
@@ -1625,7 +1752,7 @@ async def billing_webhook(
 
 ## Databases
 
-`DATABASE_TYPE` chooses one backend and `DATABASE_URL` connects to it. The generated project defaults to SQLite. SQLite, MySQL, and PostgreSQL use SQLAlchemy models and Alembic revisions; MongoDB uses the separate `MongoDocument` API and does not have SQL schema revisions. `ACTIVATE_ASYNC = True` enables async access to the same database URL. Keep production credentials out of committed settings and URL-encode reserved characters in credentials.
+`DATABASE_TYPE` chooses one backend and `DATABASE_URL` connects to it. The generated project defaults to SQLite. SQLite, MySQL, and PostgreSQL use SQLAlchemy models and Alembic revisions; MongoDB uses the separate `MongoDocument` API and does not have SQL schema revisions. `app.database_type` reports the selected backend at runtime. `ACTIVATE_ASYNC = True` enables async access to the same database URL. Keep production credentials out of committed settings and URL-encode reserved characters in credentials.
 
 ```python
 # settings.py — choose one backend and its URL
@@ -1643,6 +1770,8 @@ DATABASE_URL = f"sqlite:///{BASE_DIR / 'lenapi.db'}"
 # MongoDB: install `python -m pip install 'lenapi[mongodb]'`
 # DATABASE_TYPE = "mongodb"
 # DATABASE_URL = "mongodb://user:password@localhost:27017/app_db"
+# If the URI has no database path, set this explicitly instead:
+# MONGODB_DATABASE = "app_db"
 
 ACTIVATE_ASYNC = False
 ```
@@ -1686,7 +1815,44 @@ await student.asave()
 await student.adelete()
 ```
 
-`MongoDatabase.ping()` and `await MongoDatabase.aping()` check connectivity. To select MongoDB, set `DATABASE_TYPE = "mongodb"` and set `DATABASE_URL` to a Mongo URI whose path contains the database name, such as `mongodb://localhost:27017/my_database`. `ACTIVATE_ASYNC` controls whether LenApi also creates PyMongo's async client. `migration` and `migrate` ensure collections exist for imported `MongoDocument` models and framework security/admin state; document fields are schema-flexible and do not use Alembic revisions. `SECURITY_STORAGE = "database"` uses MongoDB for shared security state, while Redis and process memory remain optional choices. MongoDB uses the official synchronous and `AsyncMongoClient` APIs; see the [PyMongo driver guide](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/).
+`MongoDatabase.ping()` and `await MongoDatabase.aping()` check connectivity. To select MongoDB, set `DATABASE_TYPE = "mongodb"`. Put the database name in the URI path, such as `mongodb://localhost:27017/my_database`, or set `MONGODB_DATABASE = "my_database"` when the URI has no path. `ACTIVATE_ASYNC` controls whether LenApi also creates PyMongo's async client. `migration` and `migrate` ensure collections exist for imported `MongoDocument` models and framework security/admin state; document fields are schema-flexible and do not use Alembic revisions. `SECURITY_STORAGE = "database"` uses MongoDB for shared security state, while Redis and process memory remain optional choices. MongoDB uses the official synchronous and `AsyncMongoClient` APIs; see the [PyMongo driver guide](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/).
+
+#### Switching an existing project from SQL to MongoDB
+
+Changing `DATABASE_TYPE` and `DATABASE_URL` selects MongoDB for the app; it does not convert existing SQLAlchemy models, tables, or rows. Define the Mongo-backed version as a `MongoDocument`, bind it after creating the app, and update routes to use that document class. If a SQL `model.Model` query runs while MongoDB is selected, LenAPI raises a clear backend-mismatch error explaining that a Mongo document is required. Check the active backend with `app.database_type`.
+
+```python
+# settings.py
+DATABASE_TYPE = "mongodb"
+DATABASE_URL = "mongodb://127.0.0.1:27017/my_app"
+
+# app/models.py
+from lenapi import MongoDocument
+
+class MongoStudent(MongoDocument):
+    collection_name = "students"
+    username: str
+    course: str
+
+# main.py
+from lenapi import LENAPI
+from pydantic import BaseModel
+from app.models import MongoStudent
+
+class StudentCreate(BaseModel):
+    username: str
+    course: str
+
+app = LENAPI()
+MongoStudent.bind(app.mongodb)
+print(app.database_type)  # mongodb
+
+@app.post("/students")
+def create_student(data: StudentCreate):
+    return MongoStudent.create(**data.model_dump())
+```
+
+If you need to carry existing records over, treat that as an explicit data migration: back up both stores, copy in controlled batches, verify counts and important fields, and only then switch production traffic. LenAPI's `migration`/`migrate` commands initialize MongoDB collections and framework state; they do not copy SQL data. MongoDB document IDs are strings, so update route and response-schema ID types that previously expected integer SQL IDs.
 
 Put application models in `app/models.py` and import that module from `main.py`. The migration command loads `main:app`, so it discovers those model classes before creating a migration. The library's `Model` base supplies an integer `id`:
 
@@ -1801,6 +1967,8 @@ python lenora.py migration --message "add student phone"
 
 An existing unversioned SQLite database is adopted only when its schema matches the migration history; adoption preserves its data.
 
+`PositiveIntegerField` and `PositiveBigIntegerField` include a named database `CHECK` constraint. LenAPI prevents Alembic's metadata-copy step from adding that constraint twice, which MySQL rejects as a duplicate constraint name. If a local revision generated by an older LenAPI contains duplicate identical `sa.CheckConstraint(...)` entries, correct or regenerate that unapplied revision before using it. MySQL uses non-transactional DDL, so a failed migration may leave some project tables created even though no revision was recorded. Check `showmigrations` and inspect the project-namespaced tables before retrying. For a disposable database, `delete_migrations` can reset this project's tables and revisions after its confirmation prompt; if the data must be preserved, reconcile the partial schema instead of deleting it.
+
 `migrate` applies pending migration files already in `migrations/versions/`; it does not generate a revision. A common release workflow is to generate and inspect a revision during development, commit the revision with the code, then run `migrate` during deployment:
 
 ```bash
@@ -1823,9 +1991,9 @@ python lenora.py showmigrations
 python lenora.py repair-migrations
 ```
 
-`clear_migrations` removes local revision files and the Alembic version table only when there are no application tables. It is for resetting an empty SQL project, not for reconciling an existing schema.
+`clear_migrations` removes local revision files and this project's Alembic version table only when there are no application tables in this project's namespace. It is for resetting an empty SQL project, not for reconciling an existing schema.
 
-`delete_migrations` is a destructive full reset. After an interactive y/n confirmation, it drops every table and view in the selected SQL database (or every collection in MongoDB) and deletes local revision files. This also deletes application data. Back up first and use it only when a clean database is intended:
+`delete_migrations` is a destructive reset of the current project. After an interactive y/n confirmation, it drops tables and views in this project's SQL namespace (or collections in this project's MongoDB namespace) and deletes local revision files. Objects belonging to other project namespaces are left alone. This also deletes this project's application data. Back up first and use it only when a clean project database is intended:
 
 ```bash
 python lenora.py delete_migrations

{lenapi-0.1.2 → lenapi-0.1.3}/README.md

@@ -8,6 +8,18 @@ LenAPI aims to reduce repetitive code and simplify common integrations, helping
 
 **LenAPI — Compact by Design, Powerful by Capability.**
 
+## Feature overview
+
+- Typed HTTP routes with Pydantic request and response validation, Swagger UI, and ReDoc.
+- Synchronous and asynchronous ORM operations, migrations, transactions, search, aggregates, and pagination for SQLite, MySQL, and PostgreSQL. MongoDB document support is currently in beta.
+- Authentication building blocks for JWT, API keys, HTTP Basic, sessions, opaque bearer tokens, HMAC, OIDC, and social sign-in.
+- WebSockets for chat, video signaling, JSON, text, and binary messages; webhook handlers with optional HMAC verification; cache and durable background jobs with retries and delayed execution.
+- Validated public and private file uploads, middleware, throttling, and optional gzip compression.
+- An optional model admin console with explicit model/field allow-lists, per-model permissions, and CPU/RAM/process monitoring.
+- Independent generated projects that can run separately or be mounted under a path in a primary project.
+
+See the [LenAPI documentation](https://lenapi.site/) for setup guides and runnable examples.
+
 ## Python versions
 
 LenAPI is tested and supported on Python 3.11 through 3.14. Python 3.10 reached
@@ -473,6 +485,8 @@ Run `python lenora.py apikey` inside a project to set `AUTHENTICATION = "api_key
 
 `settings.py` centralizes the API title/version, docs and OpenAPI URLs, host, port, database selection, token settings, and shared security storage. `HOST = ""` uses `127.0.0.1`; set `HOST` directly to bind another address. `app = LENAPI()` loads project settings automatically. Each generated project gets a unique high-entropy `SECRET_KEY`; `TOKEN` uses it to sign tokens and configures token lifetime and issuer. Keep the key private. Changing it invalidates tokens signed with the old key. `DATABASE_TYPE` chooses one backend (`sqlite`, `mysql`, `postgresql`, or `mongodb`), and `DATABASE_URL` configures it. `ACTIVATE_ASYNC` enables asynchronous access using the same database URL. The default database is SQLite.
 
+Generated projects set `DEBUG = True` for local development. Unexpected route or dependency errors then print a traceback to the terminal. LenAPI returns a generic `500 Internal Server Error` response to the client in both debug modes; request validation errors and explicit `HTTPException` responses keep their normal status codes. Set `DEBUG = False` in production to stop LenAPI from printing exception tracebacks. If `DEBUG` is absent, LenAPI defaults to `False`.
+
 ## Automated tests
 
 Pytest is installed with lenApi, so you can run the framework test suite from the repository root:
@@ -799,6 +813,117 @@ The docs gate only handles `/`, `/logout`, the configured Swagger and ReDoc path
 
 To remove the gate, set `SAFE_GUARD_DOCS_URL = False` and restart the app. The admin tables may remain in the database; they are not queried while the feature is disabled.
 
+### Built-in model admin and resource monitor
+
+The optional admin console is separate from the Swagger/ReDoc login and is served at `/admin/`. It uses stateless HTTP Basic authentication for its API requests. Enable it in `settings.py`, then run a migration and create an administrator. The first CLI-created superadmin has full access and can create other admin accounts and grant per-model permissions. If the project already had docs-admin accounts before this feature, create an additional account with the CLI; it becomes superadmin if no superadmin exists yet.
+
+```python
+# settings.py
+ADMIN_ENABLED = True
+ADMIN_URL = "/admin/"
+ADMIN_SESSION_LIFETIME_SECONDS = 3600
+ADMIN_COOKIE_SECURE = None  # follows the ASGI HTTPS scheme
+
+# Monitoring is optional and requires the admin console to be enabled.
+ADMIN_MONITORING_ENABLED = True
+```
+
+```bash
+python lenora.py migration
+python lenora.py admin
+python lenora.py run
+```
+
+The first SQL migration includes the framework `AdminUser` fields and session storage along with the imported app models. MongoDB initializes the admin collections through `migration`. Mongo collections need a corresponding `MongoDocument` class so the admin can safely render typed edit forms.
+
+Create `app/admin.py` to explicitly allow-list models and choose which fields are visible. Once this file exists, only models registered there appear in the console. `fields` selects displayed/editable fields, `readonly` displays selected fields without allowing changes, and `exclude` hides fields. Credential-like fields such as `password`, `api_key`, and `key_digest` remain hidden even if listed; use application routes that hash or rotate credentials.
+
+```python
+# app/admin.py
+from lenapi.admin import admin
+from .models import Student, Course, Invoice, Staff
+
+admin.register(
+    Student,
+    fields=("person_name", "course", "email", "profile_image"),
+    readonly=("email",),
+    exclude=("password", "private_notes"),
+)
+
+admin.register(
+    Course,
+    fields=("title", "description", "duration_weeks", "is_active"),
+)
+
+admin.register(
+    Invoice,
+    fields=("invoice_number", "student_id", "amount", "status", "issued_at"),
+    readonly=("invoice_number", "issued_at"),
+    exclude=("payment_token", "provider_response"),
+)
+
+admin.register(
+    Staff,
+    fields=("name", "work_email", "department"),
+    readonly=("work_email",),
+    exclude=("password", "salary", "hr_notes"),
+)
+```
+
+When `app/admin.py` is absent, the console keeps its backward-compatible model discovery. Registered models show only the selected columns; readonly fields appear in record forms without editable controls, and excluded fields are omitted from both the UI and the API response. Update requests are checked against the same field allow-list. The console supports list/read, update, and delete; record creation is handled by application endpoints. Superadmins grant `view`, `read`, `write`, and `delete` independently. `view` controls whether a model appears in the sidebar, `read` allows listing records, `write` permits updates, and `delete` controls deletion.
+
+Admin accounts and model records use the selected SQL database or MongoDB. Disable the console with `ADMIN_ENABLED = False`; set `ADMIN_MONITORING_ENABLED = False` to hide its monitor. Resource metrics are available only to a superadmin when both settings are enabled:
+
+```bash
+python -m pip install 'lenapi[monitoring]'
+```
+
+The Resource Monitor page shows CPU and RAM metric cards with rolling graphs, plus the LenAPI process PID and thread count. RAM shows process resident memory and total system-memory use. Metrics refresh every two seconds while the page is open; history remains in that browser page only. The endpoint is restricted to superadmins. This is an operational status view, not a host monitoring or alerting system. Monitoring requires psutil and does not start background sampling.
+
+When a main LenAPI project mounts sibling projects, the main project's `/admin/` is the single admin entry point. It groups each mounted project's explicitly registered models under that project's name and reads or updates records through that project's own database. Enable `ADMIN_ENABLED` and create the admin account only in the main project. Keep `ADMIN_ENABLED = False` in mounted projects; they contribute their `app/admin.py` registrations but do not need their own admin login. The mount must be configured with `app.mount(...)` for the main admin to discover that project.
+
+In generated projects, prefer a relative model import in `app/admin.py` so project names and mounts remain unambiguous:
+
+```python
+from lenapi.admin import admin
+from .models import Student, Course
+
+admin.register(Student, fields=("person_name", "course"))
+admin.register(Course, fields=("title", "is_active"))
+```
+
+Per-model permissions for the main project keep their existing model-name keys. Mounted-project permissions use `<project_name>:<model_name>`, for example `games:student`, so same-named models in different projects stay separate.
+
+### Mount independent projects
+
+Every generated project keeps its own settings, models, migrations, and database configuration. Run projects independently on different ports, or mount a sibling project into a primary app at any URL prefix you choose. A mount prefix does not need to match the sibling project's name.
+
+```python
+# win/main.py — primary application
+from lenapi import LENAPI
+
+app = LENAPI()
+app.mount("/gamer", "games")
+```
+
+The sibling project must be in the same parent directory and have its own generated `settings.py` with a `PROJECT_NAME`:
+
+```text
+workspace/
+├── win/
+│   ├── main.py
+│   ├── settings.py
+│   └── app/
+└── games/
+    ├── main.py
+    ├── settings.py
+    └── app/
+```
+
+The mounted app keeps its own database URL and project namespace. Its routes are reachable under `/gamer/`, while its own docs paths are under `/gamer/docs/` and `/gamer/redoc/`. Project table names include the project's namespace so separate apps sharing one database do not collide. Mounting is optional; independent projects can instead run on separate ports or deployments.
+
+For the shared admin console, enable `ADMIN_ENABLED` and create the admin account only in the primary project. Register models explicitly in each project's `app/admin.py`; after mounting, the primary `/admin/` groups those models by project and performs their data operations against each project's configured database. Keep `ADMIN_ENABLED = False` in mounted projects. Each mounted app instance can belong to only one parent admin.
+
 The sample app exposes the model queries as HTTP routes: `POST /classrooms` creates a classroom, `GET /classrooms` lists them, and `POST /students` accepts an optional `classroom_id`. `POST /students/batch` creates multiple students, `PUT /students/batch` updates multiple students by ID, and `DELETE /students/batch` deletes multiple students by ID. Batch requests are all-or-nothing: unknown IDs, duplicate names, or a protected deletion reject the whole operation. `PUT /students/{student_id}` updates one student; it returns HTTP 404 if the ID does not exist. `GET /students/{student_id}/classroom` returns the related classroom. Other student routes list, search, and check existence. These routes appear in Swagger at `/docs/`.
 
 Batch request examples:
@@ -1575,7 +1700,7 @@ async def billing_webhook(
 
 ## Databases
 
-`DATABASE_TYPE` chooses one backend and `DATABASE_URL` connects to it. The generated project defaults to SQLite. SQLite, MySQL, and PostgreSQL use SQLAlchemy models and Alembic revisions; MongoDB uses the separate `MongoDocument` API and does not have SQL schema revisions. `ACTIVATE_ASYNC = True` enables async access to the same database URL. Keep production credentials out of committed settings and URL-encode reserved characters in credentials.
+`DATABASE_TYPE` chooses one backend and `DATABASE_URL` connects to it. The generated project defaults to SQLite. SQLite, MySQL, and PostgreSQL use SQLAlchemy models and Alembic revisions; MongoDB uses the separate `MongoDocument` API and does not have SQL schema revisions. `app.database_type` reports the selected backend at runtime. `ACTIVATE_ASYNC = True` enables async access to the same database URL. Keep production credentials out of committed settings and URL-encode reserved characters in credentials.
 
 ```python
 # settings.py — choose one backend and its URL
@@ -1593,6 +1718,8 @@ DATABASE_URL = f"sqlite:///{BASE_DIR / 'lenapi.db'}"
 # MongoDB: install `python -m pip install 'lenapi[mongodb]'`
 # DATABASE_TYPE = "mongodb"
 # DATABASE_URL = "mongodb://user:password@localhost:27017/app_db"
+# If the URI has no database path, set this explicitly instead:
+# MONGODB_DATABASE = "app_db"
 
 ACTIVATE_ASYNC = False
 ```
@@ -1636,7 +1763,44 @@ await student.asave()
 await student.adelete()
 ```
 
-`MongoDatabase.ping()` and `await MongoDatabase.aping()` check connectivity. To select MongoDB, set `DATABASE_TYPE = "mongodb"` and set `DATABASE_URL` to a Mongo URI whose path contains the database name, such as `mongodb://localhost:27017/my_database`. `ACTIVATE_ASYNC` controls whether LenApi also creates PyMongo's async client. `migration` and `migrate` ensure collections exist for imported `MongoDocument` models and framework security/admin state; document fields are schema-flexible and do not use Alembic revisions. `SECURITY_STORAGE = "database"` uses MongoDB for shared security state, while Redis and process memory remain optional choices. MongoDB uses the official synchronous and `AsyncMongoClient` APIs; see the [PyMongo driver guide](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/).
+`MongoDatabase.ping()` and `await MongoDatabase.aping()` check connectivity. To select MongoDB, set `DATABASE_TYPE = "mongodb"`. Put the database name in the URI path, such as `mongodb://localhost:27017/my_database`, or set `MONGODB_DATABASE = "my_database"` when the URI has no path. `ACTIVATE_ASYNC` controls whether LenApi also creates PyMongo's async client. `migration` and `migrate` ensure collections exist for imported `MongoDocument` models and framework security/admin state; document fields are schema-flexible and do not use Alembic revisions. `SECURITY_STORAGE = "database"` uses MongoDB for shared security state, while Redis and process memory remain optional choices. MongoDB uses the official synchronous and `AsyncMongoClient` APIs; see the [PyMongo driver guide](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/).
+
+#### Switching an existing project from SQL to MongoDB
+
+Changing `DATABASE_TYPE` and `DATABASE_URL` selects MongoDB for the app; it does not convert existing SQLAlchemy models, tables, or rows. Define the Mongo-backed version as a `MongoDocument`, bind it after creating the app, and update routes to use that document class. If a SQL `model.Model` query runs while MongoDB is selected, LenAPI raises a clear backend-mismatch error explaining that a Mongo document is required. Check the active backend with `app.database_type`.
+
+```python
+# settings.py
+DATABASE_TYPE = "mongodb"
+DATABASE_URL = "mongodb://127.0.0.1:27017/my_app"
+
+# app/models.py
+from lenapi import MongoDocument
+
+class MongoStudent(MongoDocument):
+    collection_name = "students"
+    username: str
+    course: str
+
+# main.py
+from lenapi import LENAPI
+from pydantic import BaseModel
+from app.models import MongoStudent
+
+class StudentCreate(BaseModel):
+    username: str
+    course: str
+
+app = LENAPI()
+MongoStudent.bind(app.mongodb)
+print(app.database_type)  # mongodb
+
+@app.post("/students")
+def create_student(data: StudentCreate):
+    return MongoStudent.create(**data.model_dump())
+```
+
+If you need to carry existing records over, treat that as an explicit data migration: back up both stores, copy in controlled batches, verify counts and important fields, and only then switch production traffic. LenAPI's `migration`/`migrate` commands initialize MongoDB collections and framework state; they do not copy SQL data. MongoDB document IDs are strings, so update route and response-schema ID types that previously expected integer SQL IDs.
 
 Put application models in `app/models.py` and import that module from `main.py`. The migration command loads `main:app`, so it discovers those model classes before creating a migration. The library's `Model` base supplies an integer `id`:
 
@@ -1751,6 +1915,8 @@ python lenora.py migration --message "add student phone"
 
 An existing unversioned SQLite database is adopted only when its schema matches the migration history; adoption preserves its data.
 
+`PositiveIntegerField` and `PositiveBigIntegerField` include a named database `CHECK` constraint. LenAPI prevents Alembic's metadata-copy step from adding that constraint twice, which MySQL rejects as a duplicate constraint name. If a local revision generated by an older LenAPI contains duplicate identical `sa.CheckConstraint(...)` entries, correct or regenerate that unapplied revision before using it. MySQL uses non-transactional DDL, so a failed migration may leave some project tables created even though no revision was recorded. Check `showmigrations` and inspect the project-namespaced tables before retrying. For a disposable database, `delete_migrations` can reset this project's tables and revisions after its confirmation prompt; if the data must be preserved, reconcile the partial schema instead of deleting it.
+
 `migrate` applies pending migration files already in `migrations/versions/`; it does not generate a revision. A common release workflow is to generate and inspect a revision during development, commit the revision with the code, then run `migrate` during deployment:
 
 ```bash
@@ -1773,9 +1939,9 @@ python lenora.py showmigrations
 python lenora.py repair-migrations
 ```
 
-`clear_migrations` removes local revision files and the Alembic version table only when there are no application tables. It is for resetting an empty SQL project, not for reconciling an existing schema.
+`clear_migrations` removes local revision files and this project's Alembic version table only when there are no application tables in this project's namespace. It is for resetting an empty SQL project, not for reconciling an existing schema.
 
-`delete_migrations` is a destructive full reset. After an interactive y/n confirmation, it drops every table and view in the selected SQL database (or every collection in MongoDB) and deletes local revision files. This also deletes application data. Back up first and use it only when a clean database is intended:
+`delete_migrations` is a destructive reset of the current project. After an interactive y/n confirmation, it drops tables and views in this project's SQL namespace (or collections in this project's MongoDB namespace) and deletes local revision files. Objects belonging to other project namespaces are left alone. This also deletes this project's application data. Back up first and use it only when a clean project database is intended:
 
 ```bash
 python lenora.py delete_migrations

{lenapi-0.1.2 → lenapi-0.1.3}/lenapi/__init__.py

@@ -8,7 +8,7 @@ if sys.version_info < (3, 11):
         "on 2026-10-01 and is no longer supported."
     )
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 from .application import Application, LENAPI, Router
 from .background import BackgroundQueue, BackgroundTasks
@@ -17,6 +17,7 @@ from .authentication import authentication
 from .auth import SocialAuth
 from .authorization import require_owner, require_permission, require_role
 from .database import AsyncDatabase, Database
+from .transaction import transaction
 from .mongodb import MongoDatabase, MongoDocument, MultipleDocumentsFound
 from .parameters import Body, File
 from .logging import get_logger, logger
@@ -95,7 +96,7 @@ from .security import (
 from . import model
 
 __all__ = [
-    "Application", "LENAPI", "Router", "Depends", "BackgroundTasks", "BackgroundQueue", "Cache", "Faker", "OpenAI", "Ollama", "CORSMiddleware", "DocsAuthMiddleware", "GZipMiddleware", "RequestIDMiddleware", "TimingMiddleware", "require_role", "require_permission", "require_owner", "Database", "AsyncDatabase", "MongoDatabase", "MongoDocument", "MultipleDocumentsFound", "Body", "File", "Model", "AdminUser", "AutoField", "logger", "get_logger", "WebSocket", "WebSocketConnection", "WebSocketDisconnect", "WebSocketService",
+    "Application", "LENAPI", "Router", "Depends", "BackgroundTasks", "BackgroundQueue", "Cache", "Faker", "OpenAI", "Ollama", "CORSMiddleware", "DocsAuthMiddleware", "GZipMiddleware", "RequestIDMiddleware", "TimingMiddleware", "require_role", "require_permission", "require_owner", "Database", "AsyncDatabase", "transaction", "MongoDatabase", "MongoDocument", "MultipleDocumentsFound", "Body", "File", "Model", "AdminUser", "AutoField", "logger", "get_logger", "WebSocket", "WebSocketConnection", "WebSocketDisconnect", "WebSocketService",
     "IntegerField", "PositiveIntegerField", "BigIntField", "BigIntegerField", "PositiveBigIntegerField", "DecimalField", "StringField", "EmailField", "IPField", "PhoneField", "TextField", "UUIDField", "ImageField", "FileField", "FileImageField", "URLField", "BooleanField", "FloatField", "User",
     "DateTimeField", "DateField", "TimeField", "DurationField", "JSONField", "ForeignKeyField", "OneToOneField", "ManyToManyField", "Count", "Sum", "Min", "Max", "Avg", "Request", "UploadFile", "Response", "JSONResponse",
     "HTTPException", "JWTAuth", "APIKeyAuth", "BasicAuth", "CSRFProtect", "SessionAuth", "OpaqueBearerAuth", "HMACAuth", "OIDCAuth", "WebhookAuth", "hmac_request_signature", "session_auth", "opaque_bearer_auth", "hmac_auth", "oidc_auth", "webhook_auth", "create_authenticator", "authentication", "SocialAuth", "hash_password", "verify_password", "make_password", "check_password", "make_api_key", "hash_api_key", "UNSET", "model", "CASCADE", "SET_NULL", "PROTECT", "cascade", "null", "protected",