From e28f3fbd6ea70172b2edd78ddf58d2b45bd0c444 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Tue, 8 Sep 2026 18:27:57 +0600
Subject: [PATCH 01/12] Refactor object label handling and search functionality

- Introduced `get_display_label` and `get_default_search_fields` functions to centralize label retrieval and search field defaults via the introspection backend.
- Updated `model_display_name` to utilize the new label retrieval method, ensuring consistent label rendering across the application.
- Refactored `ModelAdmin` and related views to use introspection for displaying object labels in dropdowns and search results.
- Enhanced JavaScript utility functions for normalizing option objects and handling label/value extraction.
- Updated templates to reflect changes in label handling, ensuring that displayed labels are derived from the introspection backend.
- Improved multi-relation and permission selection widgets to use the new label structure, maintaining backward compatibility with existing IDs.
---
 fastapi_admin_kit/backends/memory.py          |  40 +++++++
 fastapi_admin_kit/backends/protocols.py       |  24 ++++
 fastapi_admin_kit/backends/sqlalchemy.py      |  86 ++++++++++++++
 fastapi_admin_kit/export_import/csv.py        |   9 +-
 fastapi_admin_kit/inspection.py               |  16 ++-
 fastapi_admin_kit/inspection/__init__.py      |  44 +++++--
 fastapi_admin_kit/modeladmin.py               |  15 ++-
 fastapi_admin_kit/router.py                   |  27 +++--
 fastapi_admin_kit/static/js/admin.js          | 107 ++++++++++++++----
 .../templates/macros/form_fields.html         |  18 +--
 fastapi_admin_kit/templates/pages/search.html |   8 +-
 .../templates/pages/users/form.html           |  17 +--
 .../templates/partials/detail_field.html      |  17 +++
 .../templates/partials/inline_stacked.html    |   5 +-
 .../templates/partials/inline_tabular.html    |   5 +-
 .../partials/perm_select_widget.html          |   8 +-
 .../templates/partials/permission_widget.html |   8 +-
 fastapi_admin_kit/views.py                    |   4 +-
 fastapi_admin_kit/views/class_views.py        |  92 +++++++++++----
 fastapi_admin_kit/views/context.py            |  10 +-
 fastapi_admin_kit/views/factory.py            |  52 +++++++--
 fastapi_admin_kit/views/list_context.py       |  10 +-
 fastapi_admin_kit/views/roles.py              |  20 ++--
 fastapi_admin_kit/views/users.py              |   2 +-
 24 files changed, 505 insertions(+), 139 deletions(-)

diff --git a/fastapi_admin_kit/backends/memory.py b/fastapi_admin_kit/backends/memory.py
index 7028ac1..21edd93 100644
--- a/fastapi_admin_kit/backends/memory.py
+++ b/fastapi_admin_kit/backends/memory.py
@@ -442,6 +442,46 @@ def get_pk_columns(self, model: type) -> list[Any]:
         pk = _pk_field_name(model)
         return [pk] if pk else []
 
+    _DISPLAY_CANDIDATES: tuple[str, ...] = ("name", "title", "email", "username", "label")
+
+    def get_display_label(self, obj: Any) -> str | None:
+        """Short label for *obj* (custom ``__str__`` or display field)."""
+        if type(obj).__str__ is not object.__str__:
+            try:
+                text = str(obj)
+            except Exception:
+                text = ""
+            if text and "=" not in text:
+                return text
+        schema: Schema = getattr(type(obj), "__schema__", None)
+        available = {f.name for f in schema.fields} if schema is not None else None
+        for attr in self._DISPLAY_CANDIDATES:
+            if available is not None and attr not in available:
+                continue
+            try:
+                label = getattr(obj, attr, None)
+            except Exception:
+                label = None
+            if label is not None and str(label).strip():
+                return str(label)
+        return None
+
+    def get_default_search_fields(self, model: type) -> list[str]:
+        """Default ``search_fields`` for *model* (existing candidates first)."""
+        schema: Schema = getattr(model, "__schema__", None)
+        if schema is None:
+            return []
+        by_name = {f.name: f for f in schema.fields}
+        found = [a for a in self._DISPLAY_CANDIDATES if a in by_name]
+        if found:
+            return found
+        for f in schema.fields:
+            if any(
+                hint in str(f.type).lower() for hint in ("string", "str", "text", "char", "email")
+            ):
+                return [f.name]
+        return []
+
 
 # ---------------------------------------------------------------------------
 # Audit backend
diff --git a/fastapi_admin_kit/backends/protocols.py b/fastapi_admin_kit/backends/protocols.py
index 573ec45..a17db24 100644
--- a/fastapi_admin_kit/backends/protocols.py
+++ b/fastapi_admin_kit/backends/protocols.py
@@ -75,6 +75,30 @@ def get_pk_columns(self, model: type) -> list[Any]:
         """Return the primary key column(s) for a model."""
         ...
 
+    def get_display_label(self, obj: Any) -> str | None:
+        """Return a short human-readable label for *obj*, or None.
+
+        Used for relation-picker options, list/detail relation values, and
+        anywhere a related object must render as ``label`` instead of full
+        row data. Backends must ignore framework-default ``__str__``
+        implementations that dump every field (e.g. SQLModel/Pydantic
+        ``BaseModel.__str__``) and prefer a custom ``__str__``, falling
+        back to ``name`` / ``title`` / ``email`` / ``username`` attributes.
+        Callers apply their own final fallback (``#id``, ``ClassName:pk``).
+        """
+        ...
+
+    def get_default_search_fields(self, model: type) -> list[str]:
+        """Return default searchable field names for *model*.
+
+        Used when ``ModelAdmin.search_fields`` is unset. Backends return
+        the ``name`` / ``title`` / ``email`` / ``username`` columns that
+        actually exist on the model, falling back to the first text-like
+        column so models without those fields (e.g. feedback/comment
+        tables) are still searchable instead of silently unfiltered.
+        """
+        ...
+
 
 @runtime_checkable
 class SessionBackend(Protocol):
diff --git a/fastapi_admin_kit/backends/sqlalchemy.py b/fastapi_admin_kit/backends/sqlalchemy.py
index f5a0d79..5445fc7 100644
--- a/fastapi_admin_kit/backends/sqlalchemy.py
+++ b/fastapi_admin_kit/backends/sqlalchemy.py
@@ -347,6 +347,92 @@ def get_pk_columns(self, model: type) -> list[Any]:
         mapper = sa_inspect(model)
         return list(mapper.primary_key)
 
+    # Display candidates in priority order. Only attributes that exist as
+    # real columns are considered, so proxies/deferred loaders on missing
+    # attributes are never triggered.
+    _DISPLAY_CANDIDATES: tuple[str, ...] = ("name", "title", "email", "username", "label")
+
+    def get_display_label(self, obj: Any) -> str | None:
+        """Short label for *obj* (custom ``__str__`` or display column)."""
+        if self._has_custom_str(obj):
+            try:
+                text = str(obj)
+            except Exception:
+                text = ""
+            # Guard against __str__ implementations that still dump fields
+            # (e.g. "id=1 name='x'"): prefer a clean column value instead.
+            if text and "=" not in text:
+                return text
+        try:
+            columns, _ = self.inspect_model(type(obj))
+            available = {c.name for c in columns}
+        except Exception:
+            # Not a mapped model (plain object, memory record, ...):
+            # fall back to a plain attribute probe.
+            available = None
+        for attr in self._DISPLAY_CANDIDATES:
+            if available is not None and attr not in available:
+                continue
+            try:
+                label = getattr(obj, attr, None)
+            except Exception:
+                label = None
+            if label is not None and str(label).strip():
+                return str(label)
+        if self._has_custom_str(obj):
+            try:
+                return str(obj)
+            except Exception:
+                return None
+        return None
+
+    def get_default_search_fields(self, model: type) -> list[str]:
+        """Default ``search_fields`` for *model* (existing candidates first)."""
+        try:
+            columns, _ = self.inspect_model(model)
+        except Exception:
+            return []
+        by_name = {c.name: c for c in columns}
+        found = [a for a in self._DISPLAY_CANDIDATES if a in by_name]
+        if found:
+            return found
+        for col in columns:
+            # ColumnMeta.type may be a type *class* (SQLModel-resolved) or
+            # an instance (plain SQLAlchemy) — handle both.
+            col_type = col.type
+            if col_type is None:
+                continue
+            type_name = (
+                col_type.__name__ if isinstance(col_type, type) else type(col_type).__name__
+            ).lower()
+            if any(hint in type_name for hint in ("string", "text", "char", "unicode")):
+                return [col.name]
+        return []
+
+    @staticmethod
+    def _has_custom_str(obj: Any) -> bool:
+        """True if the model defines a real custom ``__str__``.
+
+        Framework-default ``__str__`` implementations that dump every
+        field (SQLModel/Pydantic ``BaseModel.__str__``) are explicitly
+        ignored so they never leak full row data into labels.
+        """
+        str_fn = type(obj).__str__
+        if str_fn is object.__str__:
+            return False
+        owner = getattr(str_fn, "__objclass__", None)
+        if owner is None:
+            # Plain function defined on a class in the MRO — find it.
+            for klass in type(obj).__mro__:
+                if "__str__" in klass.__dict__:
+                    owner = klass
+                    break
+        if owner is not None:
+            module = getattr(owner, "__module__", "") or ""
+            if module.split(".")[0] in ("sqlmodel", "pydantic"):
+                return False
+        return True
+
     # -- internal helpers ---------------------------------------------------
 
     def _is_sqlmodel(self, model: type) -> bool:
diff --git a/fastapi_admin_kit/export_import/csv.py b/fastapi_admin_kit/export_import/csv.py
index 2624a9e..53704a9 100644
--- a/fastapi_admin_kit/export_import/csv.py
+++ b/fastapi_admin_kit/export_import/csv.py
@@ -98,12 +98,13 @@ def export_filtered(
 
         # Apply search filter
         if q:
+            from fastapi_admin_kit.inspection import get_default_search_fields
             from fastapi_admin_kit.search_utils import apply_search_filter
 
-            search_fields = getattr(self.admin, "search_fields", None) or [
-                "name",
-                "title",
-            ]
+            search_fields = getattr(self.admin, "search_fields", None) or get_default_search_fields(
+                self.registered.model,
+                getattr(request.app.state, "admin_introspection_adapter", None),
+            )
             from sqlalchemy import select
 
             queryset = apply_search_filter(
diff --git a/fastapi_admin_kit/inspection.py b/fastapi_admin_kit/inspection.py
index 3a7cde3..77d80cb 100644
--- a/fastapi_admin_kit/inspection.py
+++ b/fastapi_admin_kit/inspection.py
@@ -104,12 +104,18 @@ def is_required(col: ColumnMeta) -> bool:
 def model_display_name(obj: Any) -> str:
     """Return a human-readable label for an ORM object.
 
-    Uses the model's ``__str__`` if it has a custom implementation.
-    Falls back to ``ClassName:pk`` when ``__str__`` is the default
-    ``object.__str__``.
+    Delegates to the introspection backend
+    (``IntrospectionBackend.get_display_label``) so display logic lives
+    behind the multi-ORM seam; falls back to ``ClassName:pk``.
     """
-    if type(obj).__str__ is not object.__str__:
-        return str(obj)
+    from fastapi_admin_kit.backends.sqlalchemy import SqlAlchemyIntrospectionAdapter
+
+    try:
+        label = SqlAlchemyIntrospectionAdapter().get_display_label(obj)
+    except Exception:
+        label = None
+    if label:
+        return label
     pk = getattr(obj, "id", None)
     return f"{type(obj).__name__}:{pk}" if pk is not None else type(obj).__name__
 
diff --git a/fastapi_admin_kit/inspection/__init__.py b/fastapi_admin_kit/inspection/__init__.py
index 3041d6e..b98da28 100644
--- a/fastapi_admin_kit/inspection/__init__.py
+++ b/fastapi_admin_kit/inspection/__init__.py
@@ -109,17 +109,47 @@ def is_required(col: ColumnMeta) -> bool:
     )
 
 
+def get_display_label(obj: Any, introspection: Any | None = None) -> str | None:
+    """Best-effort short label for *obj* via the introspection backend.
+
+    Delegates to ``IntrospectionBackend.get_display_label`` (SQLAlchemy by
+    default) so display logic lives behind the multi-ORM seam instead of
+    inline ``getattr`` chains. Returns None when no clean label exists —
+    callers apply their own final fallback (``#id``, ``ClassName:pk``).
+    """
+    adapter = introspection if introspection is not None else _inspector
+    try:
+        return adapter.get_display_label(obj)
+    except Exception:
+        return None
+
+
+def get_default_search_fields(model: type, introspection: Any | None = None) -> list[str]:
+    """Default ``search_fields`` for *model* via the introspection backend.
+
+    Falls back to ``["name", "title", "email"]`` when the backend cannot
+    determine fields (e.g. third-party backends predating this method),
+    preserving historical behaviour.
+    """
+    adapter = introspection if introspection is not None else _inspector
+    try:
+        fields = adapter.get_default_search_fields(model)
+    except Exception:
+        fields = []
+    return list(fields) if fields else ["name", "title", "email"]
+
+
 def model_display_name(obj: Any) -> str:
     """Return a human-readable label for an ORM object.
 
-    Uses the model's ``__str__`` if it has a custom implementation.
-    Falls back to ``name``, ``title``, or ``ClassName:pk``.
+    Resolved through the introspection backend (custom ``__str__``, else
+    ``name`` / ``title`` / ``email`` / ``username``), falling back to
+    ``ClassName:pk`` — so related objects always render as a short label,
+    never full row data.
     """
-    if type(obj).__str__ is not object.__str__:
-        return str(obj)
-    label = getattr(obj, "name", None) or getattr(obj, "title", None)
-    if label is not None:
-        return str(label)
+    label = get_display_label(obj)
+    if label:
+        return label
     pk = getattr(obj, "id", None)
     return f"{type(obj).__name__}:{pk}" if pk is not None else type(obj).__name__
 
diff --git a/fastapi_admin_kit/modeladmin.py b/fastapi_admin_kit/modeladmin.py
index af81565..7cdc4cb 100644
--- a/fastapi_admin_kit/modeladmin.py
+++ b/fastapi_admin_kit/modeladmin.py
@@ -224,12 +224,15 @@ def get_nav_badge(self, request: Any = None) -> str | None:
 
     # Object display
     def __str__(self, obj: Any) -> str:
-        """How to display an object in dropdowns/links."""
-        return str(
-            getattr(obj, "name", None)
-            or getattr(obj, "title", None)
-            or f"#{getattr(obj, 'id', '?')}"
-        )
+        """How to display an object in dropdowns/links.
+
+        Label resolution goes through the introspection backend
+        (custom ``__str__``, else ``name`` / ``title`` / ``email`` /
+        ``username``); falls back to ``#id``.
+        """
+        from fastapi_admin_kit.inspection import get_display_label
+
+        return str(get_display_label(obj) or f"#{getattr(obj, 'id', '?')}")
 
     def get_model(self) -> Any:
         return self.model
diff --git a/fastapi_admin_kit/router.py b/fastapi_admin_kit/router.py
index 98db39c..510c1a5 100644
--- a/fastapi_admin_kit/router.py
+++ b/fastapi_admin_kit/router.py
@@ -228,9 +228,13 @@ async def export_data(
         # Apply search/filter from query params
         q = request.query_params.get("q", "")
         if q:
+            from fastapi_admin_kit.inspection import get_default_search_fields
             from fastapi_admin_kit.search_utils import apply_search_filter
 
-            search_fields = getattr(admin, "search_fields", None) or ["name", "title"]
+            search_fields = getattr(admin, "search_fields", None) or get_default_search_fields(
+                registered.model,
+                getattr(request.app.state, "admin_introspection_adapter", None),
+            )
             base = apply_search_filter(base, registered.model, search_fields, q)
 
         # Execute query
@@ -857,11 +861,20 @@ async def autocomplete(
         """Search-as-you-type endpoint for relation pickers."""
         from fastapi.responses import JSONResponse
 
+        from fastapi_admin_kit.inspection import (
+            get_default_search_fields,
+            model_display_name,
+        )
+
         session = get_db_session(request)
         model = registered.model
         results = []
 
-        search_fields = getattr(registered.admin, "search_fields", None) or ["name", "title"]
+        search_fields = getattr(
+            registered.admin, "search_fields", None
+        ) or get_default_search_fields(
+            model, getattr(request.app.state, "admin_introspection_adapter", None)
+        )
 
         from sqlalchemy import select
 
@@ -869,12 +882,10 @@ async def autocomplete(
 
         query = apply_search_filter(request, select(model), model, search_fields, q).limit(20)
         for obj in await session.all(query):
-            label = str(
-                getattr(obj, "name", None)
-                or getattr(obj, "title", None)
-                or f"#{getattr(obj, 'id', '?')}"
-            )
-            results.append({"id": str(obj.id), "label": label})
+            # Label via the introspection backend — never full row data.
+            label = model_display_name(obj)
+            # Standard option shape: label/value (+ id for back-compat).
+            results.append({"id": str(obj.id), "value": str(obj.id), "label": label})
 
         return JSONResponse(content=results)
 
diff --git a/fastapi_admin_kit/static/js/admin.js b/fastapi_admin_kit/static/js/admin.js
index f22362d..3599373 100644
--- a/fastapi_admin_kit/static/js/admin.js
+++ b/fastapi_admin_kit/static/js/admin.js
@@ -69,6 +69,32 @@ document.addEventListener('alpine:init', () => {
     },
   });
 
+  /* ── Relation option helpers (label/value only, never full JSON) ─── */
+  function _normOption(raw) {
+    if (raw == null) return { id: '', value: '', label: '' };
+    if (typeof raw === 'string') return { id: raw, value: raw, label: raw };
+    const value = raw.value ?? raw.id ?? '';
+    const label = raw.label ?? raw.name ?? raw.title ?? String(value ?? '');
+    return { ...raw, id: value, value: value, label: label };
+  }
+
+  function _normList(data) {
+    if (!Array.isArray(data)) return [];
+    return data.map(_normOption);
+  }
+
+  function _optLabel(opt) {
+    if (opt == null) return '';
+    if (typeof opt === 'string') return opt;
+    return opt.label ?? opt.name ?? opt.title ?? String(opt.value ?? opt.id ?? '');
+  }
+
+  function _optValue(opt) {
+    if (opt == null) return '';
+    if (typeof opt === 'string') return opt;
+    return String(opt.value ?? opt.id ?? '');
+  }
+
   /* ── Relation Picker ─────────────────────────────────────────────── */
 
   Alpine.data('relationPicker', (initialId, initialLabel, searchUrl, fixed = false) => ({
@@ -132,7 +158,7 @@ document.addEventListener('alpine:init', () => {
         try {
           const resp = await fetch(`${searchUrl}?q=${encodeURIComponent(this.searchQuery)}`);
           if (resp.ok) {
-            this.results = await resp.json();
+            this.results = _normList(await resp.json());
             if (this.fixed) this._setPosition();
           }
         } catch (e) {
@@ -142,8 +168,9 @@ document.addEventListener('alpine:init', () => {
     },
 
     select(result) {
-      this.selectedId = result.id;
-      this.searchQuery = result.label;
+      const opt = _normOption(result);
+      this.selectedId = _optValue(opt);
+      this.searchQuery = _optLabel(opt);
       this.results = [];
       this.open = false;
     },
@@ -180,9 +207,9 @@ document.addEventListener('alpine:init', () => {
         try { this.selectedIds = JSON.parse(initialIds); } catch (e) { this.selectedIds = []; }
       }
       if (Array.isArray(initialItems)) {
-        this.selectedItems = initialItems;
+        this.selectedItems = _normList(initialItems);
       } else if (typeof initialItems === 'string' && initialItems) {
-        try { this.selectedItems = JSON.parse(initialItems); } catch (e) { this.selectedItems = []; }
+        try { this.selectedItems = _normList(JSON.parse(initialItems)); } catch (e) { this.selectedItems = []; }
       }
       if (this.selectedIds.length > 0 && this.selectedItems.length === 0) {
         this._loadSelected();
@@ -207,6 +234,9 @@ document.addEventListener('alpine:init', () => {
       return [];
     },
 
+    optLabel(opt) { return _optLabel(opt); },
+    optValue(opt) { return _optValue(opt); },
+
     async _loadSelected() {
       try {
         const ids = this._ensureArray(this.selectedIds);
@@ -216,7 +246,7 @@ document.addEventListener('alpine:init', () => {
         }
         const resp = await fetch(`${searchUrl}?ids=${ids.join(',')}`);
         if (resp.ok) {
-          this.selectedItems = await resp.json();
+          this.selectedItems = _normList(await resp.json());
         }
       } catch (e) {
         console.error('Multi-relation load error:', e);
@@ -231,10 +261,10 @@ document.addEventListener('alpine:init', () => {
           const url = q ? `${searchUrl}?q=${encodeURIComponent(q)}` : `${searchUrl}`;
           const resp = await fetch(url);
           if (resp.ok) {
-            const all = await resp.json();
+            const all = _normList(await resp.json());
             const ids = this._ensureArray(this.selectedIds);
             const idStrs = ids.map(String);
-            this.results = all.filter(r => !idStrs.includes(String(r.id)));
+            this.results = all.filter(r => !idStrs.includes(String(_optValue(r))));
           }
         } catch (e) {
           console.error('Multi-relation search error:', e);
@@ -243,11 +273,13 @@ document.addEventListener('alpine:init', () => {
     },
 
     add(result) {
+      const opt = _normOption(result);
+      const val = _optValue(opt);
       const ids = this._ensureArray(this.selectedIds);
       const idStrs = ids.map(String);
-      if (!idStrs.includes(String(result.id))) {
-        this.selectedIds.push(result.id);
-        this.selectedItems.push(result);
+      if (!idStrs.includes(String(val))) {
+        this.selectedIds.push(val);
+        this.selectedItems.push(opt);
       }
       this.searchQuery = '';
       this.results = [];
@@ -268,11 +300,19 @@ document.addEventListener('alpine:init', () => {
     open: false,
     _debounce: null,
 
+    optLabel(opt) { return opt.label ?? opt.name ?? _optLabel(opt); },
+
     init() {
       if (initialPermData && Array.isArray(initialPermData)) {
-        this.selectedPerms = initialPermData.map(p => ({
-          id: p.id, name: p.name, table_name: p.table_name
-        }));
+        this.selectedPerms = initialPermData.map(p => {
+          const o = _normOption(p);
+          return {
+            id: _optValue(o), value: _optValue(o),
+            label: p.label ?? p.name ?? _optLabel(o),
+            name: p.label ?? p.name ?? _optLabel(o),
+            table_name: p.table_name,
+          };
+        });
       }
     },
 
@@ -284,17 +324,23 @@ document.addEventListener('alpine:init', () => {
           const url = q ? `${searchUrl}?q=${encodeURIComponent(q)}` : searchUrl;
           const resp = await fetch(url);
           if (resp.ok) {
-            const all = await resp.json();
-            const selected = new Set(this.selectedPerms.map(p => p.id));
-            this.results = all.filter(r => !selected.has(r.id));
+            const all = _normList(await resp.json()).map(o => ({
+              ...o,
+              name: o.label ?? o.name,
+            }));
+            const selected = new Set(this.selectedPerms.map(p => String(p.id)));
+            this.results = all.filter(r => !selected.has(String(_optValue(r))));
           }
         } catch (e) { console.error('Permission search error:', e); }
       }, 250);
     },
 
     addPerm(perm) {
-      if (!this.selectedPerms.find(p => p.id === perm.id)) {
-        this.selectedPerms.push({ id: perm.id, name: perm.name, table_name: perm.table_name });
+      const o = _normOption(perm);
+      const val = _optValue(o);
+      const label = perm.label ?? perm.name ?? _optLabel(o);
+      if (!this.selectedPerms.find(p => String(p.id) === String(val))) {
+        this.selectedPerms.push({ id: val, value: val, label: label, name: label, table_name: perm.table_name });
       }
       this.searchQuery = '';
       this.results = [];
@@ -330,12 +376,18 @@ document.addEventListener('alpine:init', () => {
       }
     },
 
+    optLabel(opt) { return opt.label ?? opt.name ?? _optLabel(opt); },
+    optValue(opt) { return _optValue(opt); },
+
     async _loadSelected() {
       try {
         const ids = this.selectedIds.join(',');
         const resp = await fetch(`${searchUrl}?ids=${ids}`);
         if (resp.ok) {
-          this.selectedItems = await resp.json();
+          this.selectedItems = _normList(await resp.json()).map(o => ({
+            ...o,
+            label: o.label ?? o.name ?? _optLabel(o),
+          }));
         }
       } catch (e) {
         console.error('Permission load error:', e);
@@ -350,9 +402,12 @@ document.addEventListener('alpine:init', () => {
           const url = q ? `${searchUrl}?q=${encodeURIComponent(q)}` : searchUrl;
           const resp = await fetch(url);
           if (resp.ok) {
-            const all = await resp.json();
+            const all = _normList(await resp.json()).map(o => ({
+              ...o,
+              label: o.label ?? o.name ?? _optLabel(o),
+            }));
             const idSet = new Set(this.selectedIds.map(String));
-            this.results = all.filter(r => !idSet.has(String(r.id)));
+            this.results = all.filter(r => !idSet.has(String(_optValue(r))));
           }
         } catch (e) {
           console.error('Permission search error:', e);
@@ -361,9 +416,11 @@ document.addEventListener('alpine:init', () => {
     },
 
     add(result) {
-      if (!this.selectedIds.includes(result.id)) {
-        this.selectedIds.push(result.id);
-        this.selectedItems.push(result);
+      const opt = _normOption(result);
+      const val = _optValue(opt);
+      if (!this.selectedIds.map(String).includes(String(val))) {
+        this.selectedIds.push(val);
+        this.selectedItems.push({ ...opt, label: opt.label ?? opt.name ?? _optLabel(opt) });
       }
       this.searchQuery = '';
       this.results = [];
diff --git a/fastapi_admin_kit/templates/macros/form_fields.html b/fastapi_admin_kit/templates/macros/form_fields.html
index e0d4175..006e6f8 100644
--- a/fastapi_admin_kit/templates/macros/form_fields.html
+++ b/fastapi_admin_kit/templates/macros/form_fields.html
@@ -584,9 +584,10 @@
              placeholder="Search {{ field_ctx.meta.label | lower }}..."
              class="form-input">
       <div x-show="open && results.length > 0" class="relation-picker-dropdown">
-        <template x-for="result in results" :key="result.id">
+        <template x-for="result in results" :key="result.value ?? result.id">
           <div @click="select(result)" class="relation-option">
-            <span x-text="result.label"></span>
+            <span x-text="result.label ?? result.name ?? result.value ?? result.id"></span>
+            <span style="font-size: var(--text-xs); color: var(--text-secondary); margin-left: 8px;" x-text="result.value ?? result.id"></span>
           </div>
         </template>
       </div>
@@ -614,9 +615,9 @@
   <div x-data='multiRelation({{ val | tojson }}, {{ url | tojson }}, [])'>
     <input type="hidden" name="{{ name }}" x-effect="$el.value = JSON.stringify(selectedIds)">
     <div class="flex flex-wrap gap-2" style="margin-bottom: 8px;">
-      <template x-for="(item, index) in selectedItems" :key="item.id">
+      <template x-for="(item, index) in selectedItems" :key="item.value ?? item.id">
         <span class="tag-chip">
-          <span x-text="item.label"></span>
+          <span x-text="item.label ?? item.name ?? item.value ?? item.id"></span>
           <button type="button" @click="remove(index)" class="tag-chip__remove">
             {{ icon("x-mark", size="12px") }}
           </button>
@@ -625,12 +626,13 @@
     </div>
     <div class="relation-picker">
       <input type="text" x-model="searchQuery" @input="search()" @focus="open = true" @click.outside="open = false"
-             placeholder="Add {{ field_ctx.meta.label | lower }}..."
-             class="form-input">
+              placeholder="Add {{ field_ctx.meta.label | lower }}..."
+              class="form-input">
       <div x-show="open && results.length > 0" class="relation-picker-dropdown">
-        <template x-for="result in results" :key="result.id">
+        <template x-for="result in results" :key="result.value ?? result.id">
           <div @click="add(result)" class="relation-option">
-            <span x-text="result.label"></span>
+            <span x-text="result.label ?? result.name ?? result.value ?? result.id"></span>
+            <span style="font-size: var(--text-xs); color: var(--text-secondary); margin-left: 8px;" x-text="result.value ?? result.id"></span>
           </div>
         </template>
       </div>
diff --git a/fastapi_admin_kit/templates/pages/search.html b/fastapi_admin_kit/templates/pages/search.html
index 8cd53bc..5da542e 100644
--- a/fastapi_admin_kit/templates/pages/search.html
+++ b/fastapi_admin_kit/templates/pages/search.html
@@ -54,13 +54,13 @@ <h1 class="page-header-title">Search {{ registered.verbose_name_plural }}</h1>
         </thead>
         <tbody>
           <template x-if="results.length > 0">
-            <template x-for="item in results" :key="item.id">
+            <template x-for="item in results" :key="item.value ?? item.id">
               <tr class="data-row">
-                <td class="col-cell" x-text="item.id"></td>
+                <td class="col-cell" x-text="item.value ?? item.id"></td>
                 <td class="col-cell">
-                  <a :href="adminPath + '/{{ registered.table_name }}/' + item.id"
+                  <a :href="adminPath + '/{{ registered.table_name }}/' + (item.value ?? item.id)"
                      class="text-[var(--color-primary-600)] hover:text-[var(--color-primary-700)] transition-colors"
-                     x-text="item.label"></a>
+                     x-text="item.label ?? item.name ?? item.value ?? item.id"></a>
                 </td>
               </tr>
             </template>
diff --git a/fastapi_admin_kit/templates/pages/users/form.html b/fastapi_admin_kit/templates/pages/users/form.html
index 54d5d5e..231d663 100644
--- a/fastapi_admin_kit/templates/pages/users/form.html
+++ b/fastapi_admin_kit/templates/pages/users/form.html
@@ -73,9 +73,9 @@ <h3 class="fieldset__title">User Details</h3>
           <div x-data='multiRelation({{ selected_role_ids | tojson }}, {{ (admin_path | default("/admin") ~ "/users/roles/search") | tojson }}, {{ selected_role_items | tojson }})'>
             <input type="hidden" name="role_ids" :value="JSON.stringify(selectedIds)">
             <div class="flex flex-wrap gap-2" style="margin-bottom: 8px;">
-              <template x-for="(item, index) in selectedItems" :key="item.id">
+              <template x-for="(item, index) in selectedItems" :key="item.value ?? item.id">
                 <span class="tag-chip">
-                  <span x-text="item.label"></span>
+                  <span x-text="item.label ?? item.name ?? item.value ?? item.id"></span>
                   <button type="button" @click="remove(index)" class="tag-chip__remove">&times;</button>
                 </span>
               </template>
@@ -86,11 +86,12 @@ <h3 class="fieldset__title">User Details</h3>
                      class="form-input">
               <div x-show="open && results.length > 0"
                    style="position: absolute; z-index: 50; width: 100%; margin-top: 4px; background: var(--surface-base); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-md); max-height: 200px; overflow-y: auto;">
-                <template x-for="result in results" :key="result.id">
+                <template x-for="result in results" :key="result.value ?? result.id">
                   <div @click="add(result)"
                        style="padding: 8px 12px; cursor: pointer; font-size: 0.875rem;"
                        onmouseover="this.style.background='var(--surface-hover)'" onmouseout="this.style.background=''">
-                    <span x-text="result.label"></span>
+                    <span x-text="result.label ?? result.name ?? result.value ?? result.id"></span>
+                    <span style="font-size: var(--text-xs); color: var(--text-secondary); margin-left: 8px;" x-text="result.value ?? result.id"></span>
                   </div>
                 </template>
               </div>
@@ -116,10 +117,10 @@ <h3 class="fieldset__title">User Details</h3>
                     </tr>
                   </thead>
                   <tbody>
-                    <template x-for="(perm, index) in selectedPerms" :key="perm.id">
+                    <template x-for="(perm, index) in selectedPerms" :key="perm.value ?? perm.id">
                       <tr style="border-bottom: 1px solid var(--surface-border);" onmouseover="this.style.background='var(--surface-inset)'" onmouseout="this.style.background=''">
                         <td style="padding: 12px 16px;">
-                          <span style="font-size: 0.875rem; font-weight: 500; color: var(--text-primary);" x-text="perm.name"></span>
+                          <span style="font-size: 0.875rem; font-weight: 500; color: var(--text-primary);" x-text="perm.label ?? perm.name"></span>
                         </td>
                         <td style="padding: 12px 16px;">
                           <span style="font-size: 0.875rem; color: var(--text-secondary);" x-text="perm.table_name"></span>
@@ -152,11 +153,11 @@ <h3 class="fieldset__title">User Details</h3>
                      class="form-input" style="width: 100%;">
               <div x-show="open && results.length > 0" x-cloak
                    style="position: absolute; z-index: 50; width: 100%; margin-top: 4px; background: var(--surface-raised); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-md); max-height: 200px; overflow-y: auto;">
-                <template x-for="result in results" :key="result.id">
+                <template x-for="result in results" :key="result.value ?? result.id">
                   <div @click="addPerm(result)"
                        style="padding: 8px 12px; cursor: pointer; font-size: 0.875rem; color: var(--text-primary);"
                        onmouseover="this.style.background='var(--surface-inset)'" onmouseout="this.style.background=''">
-                    <span x-text="result.name"></span>
+                    <span x-text="result.label ?? result.name"></span>
                     <span style="font-size: 0.75rem; color: var(--text-secondary); margin-left: 8px;" x-text="result.table_name"></span>
                   </div>
                 </template>
diff --git a/fastapi_admin_kit/templates/partials/detail_field.html b/fastapi_admin_kit/templates/partials/detail_field.html
index 9b58531..ecc42b7 100644
--- a/fastapi_admin_kit/templates/partials/detail_field.html
+++ b/fastapi_admin_kit/templates/partials/detail_field.html
@@ -42,6 +42,23 @@
       </div>
     {% elif field.widget_macro == 'relation_picker' %}
       {{ field.widget_context.label_text | default(val) }}
+    {% elif field.widget_macro == 'multi_relation' %}
+      {% set _labels = field.widget_context.labels | default(none) %}
+      {% if _labels %}
+        {{ _labels | join(', ') }}
+      {% elif val is iterable and val is not string %}
+        <div class="flex flex-wrap gap-1">
+          {% for _v in val %}
+            {% if _v is mapping %}
+              <span class="tag-chip">{{ _v.label | default(_v.name | default(_v.value | default(_v.id))) }}</span>
+            {% else %}
+              <span class="tag-chip">{{ _v }}</span>
+            {% endif %}
+          {% endfor %}
+        </div>
+      {% else %}
+        {{ val }}
+      {% endif %}
     {% elif field.widget_macro == 'tag_input' %}
       {% set tags = val | default('[]') %}
       {% if tags is string %}
diff --git a/fastapi_admin_kit/templates/partials/inline_stacked.html b/fastapi_admin_kit/templates/partials/inline_stacked.html
index e7ff93a..6bed5d5 100644
--- a/fastapi_admin_kit/templates/partials/inline_stacked.html
+++ b/fastapi_admin_kit/templates/partials/inline_stacked.html
@@ -146,12 +146,13 @@ <h3 style="margin: 0; font-size: var(--text-sm); font-weight: var(--font-medium)
                  :style="fixed ? dropdownStyle : ''"
                  :class="fixed ? '' : 'relation-picker-dropdown'"
                  style="background: var(--surface-overlay); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-lg); max-height: 200px; overflow-y: auto; min-width: 200px;">
-              <template x-for="result in results" :key="result.id">
+              <template x-for="result in results" :key="result.value ?? result.id">
                 <div @click="select(result)"
                      style="padding: 10px 14px; cursor: pointer; font-size: var(--text-sm); border-bottom: 1px solid var(--surface-border);"
                      @mouseenter="$el.style.background = 'var(--surface-hover)'"
                      @mouseleave="$el.style.background = 'transparent'">
-                  <span x-text="result.label"></span>
+                  <span x-text="result.label ?? result.name ?? result.value ?? result.id"></span>
+                  <span style="font-size: var(--text-xs); color: var(--text-secondary); margin-left: 8px;" x-text="result.value ?? result.id"></span>
                 </div>
               </template>
             </div>
diff --git a/fastapi_admin_kit/templates/partials/inline_tabular.html b/fastapi_admin_kit/templates/partials/inline_tabular.html
index 69e46aa..ca7d00a 100644
--- a/fastapi_admin_kit/templates/partials/inline_tabular.html
+++ b/fastapi_admin_kit/templates/partials/inline_tabular.html
@@ -133,12 +133,13 @@ <h3 style="margin: 0; font-size: var(--text-sm); font-weight: var(--font-medium)
                      :style="fixed ? dropdownStyle : ''"
                      :class="fixed ? '' : 'relation-picker-dropdown'"
                      style="background: var(--surface-overlay); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-lg); max-height: 200px; overflow-y: auto; min-width: 200px;">
-                  <template x-for="result in results" :key="result.id">
+                  <template x-for="result in results" :key="result.value ?? result.id">
                     <div @click="select(result)"
                          style="padding: 8px 12px; cursor: pointer; font-size: var(--text-sm); border-bottom: 1px solid var(--surface-border);"
                          @mouseenter="$el.style.background = 'var(--surface-hover)'"
                          @mouseleave="$el.style.background = 'transparent'">
-                      <span x-text="result.label"></span>
+                      <span x-text="result.label ?? result.name ?? result.value ?? result.id"></span>
+                      <span style="font-size: var(--text-xs); color: var(--text-secondary); margin-left: 8px;" x-text="result.value ?? result.id"></span>
                     </div>
                   </template>
                 </div>
diff --git a/fastapi_admin_kit/templates/partials/perm_select_widget.html b/fastapi_admin_kit/templates/partials/perm_select_widget.html
index f04fd5b..27c5804 100644
--- a/fastapi_admin_kit/templates/partials/perm_select_widget.html
+++ b/fastapi_admin_kit/templates/partials/perm_select_widget.html
@@ -7,9 +7,9 @@
 
   {# Selected permissions #}
   <div x-show="selectedItems.length > 0" style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px;">
-    <template x-for="(item, index) in selectedItems" :key="item.id">
+    <template x-for="(item, index) in selectedItems" :key="item.value ?? item.id">
       <span style="display: inline-flex; align-items: center; gap: 6px; padding: 4px 10px; background: var(--primary-500); color: white; border-radius: 9999px; font-size: 0.8125rem; font-weight: 500;">
-        <span x-text="item.label"></span>
+        <span x-text="item.label ?? item.name ?? item.value ?? item.id"></span>
         <button type="button" @click="remove(index)"
                 style="background: none; border: none; color: white; cursor: pointer; padding: 0; line-height: 1; opacity: 0.8;"
                 onmouseover="this.style.opacity='1'" onmouseout="this.style.opacity='0.8'">
@@ -33,11 +33,11 @@
            class="form-input" style="width: 100%;">
     <div x-show="open && results.length > 0" x-cloak
          style="position: absolute; z-index: 50; width: 100%; margin-top: 4px; background: var(--surface-raised); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-md); max-height: 200px; overflow-y: auto;">
-      <template x-for="result in results" :key="result.id">
+      <template x-for="result in results" :key="result.value ?? result.id">
         <div @click="add(result)"
              style="padding: 8px 12px; cursor: pointer; font-size: 0.875rem; color: var(--text-primary);"
              onmouseover="this.style.background='var(--surface-inset)'" onmouseout="this.style.background=''">
-          <span x-text="result.label"></span>
+          <span x-text="result.label ?? result.name ?? result.value ?? result.id"></span>
           <span style="font-size: 0.75rem; color: var(--text-secondary); margin-left: 8px;" x-text="result.table_name"></span>
         </div>
       </template>
diff --git a/fastapi_admin_kit/templates/partials/permission_widget.html b/fastapi_admin_kit/templates/partials/permission_widget.html
index dcb2a57..4e5e982 100644
--- a/fastapi_admin_kit/templates/partials/permission_widget.html
+++ b/fastapi_admin_kit/templates/partials/permission_widget.html
@@ -16,10 +16,10 @@
           </tr>
         </thead>
         <tbody>
-          <template x-for="(perm, index) in selectedPerms" :key="perm.id">
+          <template x-for="(perm, index) in selectedPerms" :key="perm.value ?? perm.id">
             <tr style="border-bottom: 1px solid var(--surface-border);" onmouseover="this.style.background='var(--surface-inset)'" onmouseout="this.style.background=''">
               <td style="padding: 12px 16px;">
-                <span style="font-size: 0.875rem; font-weight: 500; color: var(--text-primary);" x-text="perm.name"></span>
+                <span style="font-size: 0.875rem; font-weight: 500; color: var(--text-primary);" x-text="perm.label ?? perm.name"></span>
               </td>
               <td style="padding: 12px 16px;">
                 <span style="font-size: 0.875rem; color: var(--text-secondary);" x-text="perm.table_name"></span>
@@ -52,11 +52,11 @@
            class="form-input" style="width: 100%;">
     <div x-show="open && results.length > 0" x-cloak
          style="position: absolute; z-index: 50; width: 100%; margin-top: 4px; background: var(--surface-raised); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-md); max-height: 200px; overflow-y: auto;">
-      <template x-for="result in results" :key="result.id">
+      <template x-for="result in results" :key="result.value ?? result.id">
         <div @click="addPerm(result)"
              style="padding: 8px 12px; cursor: pointer; font-size: 0.875rem; color: var(--text-primary);"
              onmouseover="this.style.background='var(--surface-inset)'" onmouseout="this.style.background=''">
-          <span x-text="result.name"></span>
+          <span x-text="result.label ?? result.name"></span>
           <span style="font-size: 0.75rem; color: var(--text-secondary); margin-left: 8px;" x-text="result.table_name"></span>
         </div>
       </template>
diff --git a/fastapi_admin_kit/views.py b/fastapi_admin_kit/views.py
index fe15c3a..6b188bb 100644
--- a/fastapi_admin_kit/views.py
+++ b/fastapi_admin_kit/views.py
@@ -44,7 +44,9 @@ class ModelAdmin:
 
     def __str__(self, obj: Any) -> str:
         """How to display an object in dropdowns/links."""
-        return str(getattr(obj, "name", None) or getattr(obj, "title", None) or f"#{obj.id}")
+        from fastapi_admin_kit.inspection import get_display_label
+
+        return str(get_display_label(obj) or f"#{getattr(obj, 'id', '?')}")
 
 
 def create_list_view(registered: RegisteredModel) -> Any:
diff --git a/fastapi_admin_kit/views/class_views.py b/fastapi_admin_kit/views/class_views.py
index ace3954..1d66387 100644
--- a/fastapi_admin_kit/views/class_views.py
+++ b/fastapi_admin_kit/views/class_views.py
@@ -710,35 +710,62 @@ class EditView(BaseView):
     api_renderer_class = ItemAPIRenderer
 
     async def _resolve_rel_labels(self, obj: Any, request: Request) -> dict[str, str]:
-        """Resolve display labels for relationship fields from FK values."""
-        from sqlalchemy import inspect as sa_inspect
+        """Resolve display labels for relationship fields from FK values.
 
+        Relationship metadata comes from the introspection backend
+        (``registered.relationships`` + ``get_relationship_local_columns``)
+        and targets are loaded through the session backend — no direct
+        ORM inspection here.
+        """
         from fastapi_admin_kit.inspection import model_display_name
 
         labels: dict[str, str] = {}
         if obj is None:
             return labels
         try:
-            mapper = sa_inspect(type(obj))
+            introspection = request.app.state.admin_introspection_adapter
         except Exception:
-            return labels
+            introspection = None
         session = get_db_session(request)
-        for rel_key, rel_prop in mapper.relationships.items():
-            local_cols = [c.key for c in rel_prop.local_columns]
+        for rel in self.registered.relationships:
+            if rel.direction == "MANYTOMANY":
+                continue
+            if rel.target_model is None:
+                continue
+            local_cols = self._rel_local_columns(introspection, rel.name)
             if not local_cols:
                 continue
             fk_val = getattr(obj, local_cols[0], None)
             if fk_val is None:
                 continue
-            target_cls = rel_prop.mapper.class_
             try:
-                target = await session.get(target_cls, fk_val)
+                target = await session.get(rel.target_model, fk_val)
                 if target is not None:
-                    labels[rel_key] = model_display_name(target)
+                    labels[rel.name] = model_display_name(target)
             except Exception:
-                labels[rel_key] = str(fk_val)
+                labels[rel.name] = str(fk_val)
         return labels
 
+    def _rel_local_columns(self, introspection: Any, rel_name: str) -> list[str]:
+        """Local FK column key(s) for *rel_name* via the backend (with fallback)."""
+        if introspection is not None:
+            try:
+                cols = introspection.get_relationship_local_columns(self.registered.model, rel_name)
+                if cols:
+                    return list(cols)
+            except Exception:
+                pass
+        try:
+            from sqlalchemy import inspect as sa_inspect
+
+            mapper = sa_inspect(self.registered.model)
+            rel_prop = mapper.relationships.get(rel_name)
+            if rel_prop is not None:
+                return [c.key for c in rel_prop.local_columns]
+        except Exception:
+            pass
+        return []
+
     async def _build_form_context(
         self,
         request: Request,
@@ -1042,6 +1069,26 @@ async def _build_detail_context(
             is_create=False,
             rel_labels=rel_labels,
         )
+        # Resolve M2M labels so the read-only detail view shows
+        # "label" chips instead of raw id JSON (e.g. ["1", "2"]).
+        # Relationship names come from the backend-derived registry
+        # metadata — no direct ORM inspection.
+        try:
+            from fastapi_admin_kit.inspection import model_display_name
+
+            m2m_rels = {
+                r.name for r in self.registered.relationships if r.direction == "MANYTOMANY"
+            }
+            if ctx.fieldsets:
+                for f in ctx.fieldsets[0].fields:
+                    if f.widget_macro == "multi_relation" and f.meta.name in m2m_rels:
+                        collection = getattr(obj, f.meta.name, None)
+                        if collection:
+                            f.widget_context["labels"] = [
+                                model_display_name(item) for item in collection
+                            ]
+        except Exception:
+            pass
         template_context = {
             "form_context": ctx,
             "registered": self.registered,
@@ -1477,12 +1524,14 @@ def _render_search_page(
         error: str | None = None,
         results: list | None = None,
     ) -> Any:
+        from fastapi_admin_kit.inspection import get_default_search_fields
+
         templates = request.app.state.admin_jinja_env
         admin_path = request.app.state.admin_config["admin_path"]
-        search_fields = getattr(self.admin, "search_fields", None) or [
-            "name",
-            "title",
-        ]
+        search_fields = getattr(self.admin, "search_fields", None) or get_default_search_fields(
+            self.registered.model,
+            getattr(request.app.state, "admin_introspection_adapter", None),
+        )
         return templates.TemplateResponse(
             request,
             "pages/search.html",
@@ -1539,12 +1588,15 @@ async def _search(
                     return self._render_search_page(request, q, results=[])
                 return JSONResponse([])
             else:
+                from fastapi_admin_kit.inspection import get_default_search_fields
                 from fastapi_admin_kit.search_utils import apply_search_filter
 
-                search_fields = getattr(self.admin, "search_fields", None) or [
-                    "name",
-                    "title",
-                ]
+                search_fields = getattr(
+                    self.admin, "search_fields", None
+                ) or get_default_search_fields(
+                    self.registered.model,
+                    getattr(request.app.state, "admin_introspection_adapter", None),
+                )
                 base = apply_search_filter(
                     request,
                     self.admin.get_queryset(session, request),
@@ -1572,7 +1624,9 @@ async def _search(
                 from fastapi_admin_kit.inspection import model_display_name
 
                 label = model_display_name(row)
-                results.append({"id": str(pk), "label": label})
+                # Standard option shape: label for display, value for
+                # submission. ``id`` is kept for backward compatibility.
+                results.append({"id": str(pk), "value": str(pk), "label": label})
 
             if is_browser:
                 return self._render_search_page(request, q, results=results)
diff --git a/fastapi_admin_kit/views/context.py b/fastapi_admin_kit/views/context.py
index 89fc692..9573bac 100644
--- a/fastapi_admin_kit/views/context.py
+++ b/fastapi_admin_kit/views/context.py
@@ -166,13 +166,11 @@ async def _get_filter_choices(
                     else:
                         pk = sa_inspect(target_model).primary_key[0]
                         q = sa_select(target_model).order_by(pk).limit(100)
+                    from fastapi_admin_kit.inspection import model_display_name
+
                     for obj in await session.all(q):
-                        label = str(
-                            getattr(obj, "name", None)
-                            or getattr(obj, "title", None)
-                            or f"#{getattr(obj, 'id', '?')}"
-                        )
-                        choices.append((str(obj.id), label))
+                        # Label via the introspection backend.
+                        choices.append((str(obj.id), model_display_name(obj)))
                 except Exception:
                     pass
             return {"field_type": field_type, "choices": choices}
diff --git a/fastapi_admin_kit/views/factory.py b/fastapi_admin_kit/views/factory.py
index 323cfd5..2067db1 100644
--- a/fastapi_admin_kit/views/factory.py
+++ b/fastapi_admin_kit/views/factory.py
@@ -146,36 +146,64 @@ def _resolve_rel_keys(parsed: dict[str, Any], registered: RegisteredModel) -> di
     return resolved
 
 
+def _rel_local_columns(registered: RegisteredModel, request: Any, rel_name: str) -> list[str]:
+    """Local FK column key(s) for *rel_name* via the introspection backend."""
+    try:
+        introspection = request.app.state.admin_introspection_adapter
+    except Exception:
+        introspection = None
+    if introspection is not None:
+        try:
+            cols = introspection.get_relationship_local_columns(registered.model, rel_name)
+            if cols:
+                return list(cols)
+        except Exception:
+            pass
+    try:
+        from sqlalchemy import inspect as sa_inspect
+
+        mapper = sa_inspect(registered.model)
+        rel_prop = mapper.relationships.get(rel_name)
+        if rel_prop is not None:
+            return [c.key for c in rel_prop.local_columns]
+    except Exception:
+        pass
+    return []
+
+
 async def _resolve_rel_labels(
     obj: Any, registered: RegisteredModel, request: Any
 ) -> dict[str, str]:
-    """Resolve display labels for relationship fields from FK values."""
-    from sqlalchemy import inspect as sa_inspect
+    """Resolve display labels for relationship fields from FK values.
 
+    Relationship metadata comes from the introspection backend
+    (``registered.relationships`` + ``get_relationship_local_columns``)
+    and targets are loaded through the session backend — no direct
+    ORM inspection in the main path.
+    """
     from fastapi_admin_kit.inspection import model_display_name
 
     labels: dict[str, str] = {}
     if obj is None:
         return labels
-    try:
-        mapper = sa_inspect(registered.model)
-    except Exception:
-        return labels
     session = get_db_session(request)
-    for rel_key, rel_prop in mapper.relationships.items():
-        local_cols = [c.key for c in rel_prop.local_columns]
+    for rel in registered.relationships:
+        if rel.direction == "MANYTOMANY":
+            continue
+        if rel.target_model is None:
+            continue
+        local_cols = _rel_local_columns(registered, request, rel.name)
         if not local_cols:
             continue
         fk_val = getattr(obj, local_cols[0], None)
         if fk_val is None:
             continue
-        target_cls = rel_prop.mapper.class_
         try:
-            target = await session.get(target_cls, fk_val)
+            target = await session.get(rel.target_model, fk_val)
             if target is not None:
-                labels[rel_key] = model_display_name(target)
+                labels[rel.name] = model_display_name(target)
         except Exception:
-            labels[rel_key] = str(fk_val)
+            labels[rel.name] = str(fk_val)
     return labels
 
 
diff --git a/fastapi_admin_kit/views/list_context.py b/fastapi_admin_kit/views/list_context.py
index 7e2a9ab..6733096 100644
--- a/fastapi_admin_kit/views/list_context.py
+++ b/fastapi_admin_kit/views/list_context.py
@@ -170,13 +170,11 @@ async def _build_relation_choices(
                     else sa_inspect(target).primary_key[0]
                 )
                 q = select(target).order_by(order_col or pk).limit(100)
+            from fastapi_admin_kit.inspection import model_display_name
+
             for obj in await session.all(q):
-                label = str(
-                    getattr(obj, "name", None)
-                    or getattr(obj, "title", None)
-                    or f"#{getattr(obj, 'id', '?')}"
-                )
-                choices.append((str(obj.id), label))
+                # Label via the introspection backend.
+                choices.append((str(obj.id), model_display_name(obj)))
         except Exception:
             pass
         return choices
diff --git a/fastapi_admin_kit/views/roles.py b/fastapi_admin_kit/views/roles.py
index 39114c5..901eab9 100644
--- a/fastapi_admin_kit/views/roles.py
+++ b/fastapi_admin_kit/views/roles.py
@@ -34,7 +34,7 @@ async def tables_search(
     registry = request.app.state.admin_registry
     models = registry.all()
 
-    results = [{"id": m.table_name, "label": m.verbose_name} for m in models]
+    results = [{"id": m.table_name, "value": m.table_name, "label": m.verbose_name} for m in models]
 
     if q:
         q_lower = q.lower()
@@ -55,13 +55,21 @@ async def permissions_search(
     """Search existing permissions for the multi-select picker."""
     session = get_db_session(request)
 
+    def _perm_option(p: Permission) -> dict:
+        # Standard option shape: label/value (+ id/name/table_name for back-compat).
+        return {
+            "id": p.id,
+            "value": p.id,
+            "label": p.name,
+            "name": p.name,
+            "table_name": p.table_name,
+        }
+
     if ids:
         id_list = [int(i.strip()) for i in ids.split(",") if i.strip().isdigit()]
         if id_list:
             perms = await session.all(select(Permission).where(Permission.id.in_(id_list)))
-            return JSONResponse(
-                content=[{"id": p.id, "name": p.name, "table_name": p.table_name} for p in perms]
-            )
+            return JSONResponse(content=[_perm_option(p) for p in perms])
 
     query = select(Permission)
     if q:
@@ -70,9 +78,7 @@ async def permissions_search(
 
     perms = await session.all(query)
 
-    return JSONResponse(
-        content=[{"id": p.id, "name": p.name, "table_name": p.table_name} for p in perms]
-    )
+    return JSONResponse(content=[_perm_option(p) for p in perms])
 
 
 @router.get("/roles", response_class=HTMLResponse, include_in_schema=False)
diff --git a/fastapi_admin_kit/views/users.py b/fastapi_admin_kit/views/users.py
index b015bbe..6d8b7f7 100644
--- a/fastapi_admin_kit/views/users.py
+++ b/fastapi_admin_kit/views/users.py
@@ -42,7 +42,7 @@ async def roles_search(
         result = select(Role).order_by(Role.name).limit(20)
 
     roles = await session.all(result)
-    return JSONResponse(content=[{"id": r.id, "label": r.name} for r in roles])
+    return JSONResponse(content=[{"id": r.id, "value": r.id, "label": r.name} for r in roles])
 
 
 # @router.get("/users", response_class=HTMLResponse)

From feb3cfe9903f6fc4c504be83cada6fabccb85cef Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Wed, 9 Sep 2026 19:57:18 +0600
Subject: [PATCH 02/12] fix: enhance DisplayColumn value method to handle
 non-string iterable types

---
 fastapi_admin_kit/views/context.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/fastapi_admin_kit/views/context.py b/fastapi_admin_kit/views/context.py
index 9573bac..5b83f9a 100644
--- a/fastapi_admin_kit/views/context.py
+++ b/fastapi_admin_kit/views/context.py
@@ -52,7 +52,11 @@ def value(self, obj: Any) -> Any:
             from fastapi_admin_kit.inspection import model_display_name
 
             # M2M relations return a list/InstrumentedList — join each item's name
-            if isinstance(val, list) or (hasattr(val, "__iter__") and not isinstance(val, str)):
+            if isinstance(val, list) or (
+                hasattr(val, "__iter__")
+                and not isinstance(val, str)
+                and not hasattr(val, "__table__")
+            ):
                 parts = [model_display_name(item) for item in val]
                 return ", ".join(parts) if parts else "-"
             return model_display_name(val)

From 1ba2fc1d725fa73fe356d853f9390ae63ed2aa64 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Thu, 10 Sep 2026 07:04:57 +0600
Subject: [PATCH 03/12] fix related model filtering issue

---
 fastapi_admin_kit/backends/memory.py     |  15 +++
 fastapi_admin_kit/backends/protocols.py  |   4 +
 fastapi_admin_kit/backends/sqlalchemy.py |  17 +++
 fastapi_admin_kit/filters/base.py        |  36 ++++++
 fastapi_admin_kit/filters/registry.py    |  93 ++++++++++++++-
 tests/test_filters.py                    | 146 ++++++++++++++++++++++-
 tests/test_registry.py                   |  19 ++-
 7 files changed, 324 insertions(+), 6 deletions(-)

diff --git a/fastapi_admin_kit/backends/memory.py b/fastapi_admin_kit/backends/memory.py
index 21edd93..4f5a0ac 100644
--- a/fastapi_admin_kit/backends/memory.py
+++ b/fastapi_admin_kit/backends/memory.py
@@ -428,6 +428,21 @@ def get_relationship(self, model: type, name: str) -> Any:
     def get_relationship_local_columns(self, model: type, name: str) -> list[str]:
         return []
 
+    def get_relationship_meta(self, model: type, name: str) -> RelationMeta | None:
+        schema: Schema = getattr(model, "__schema__", None)
+        if schema is None:
+            return None
+        r = schema.get_relation(name)
+        if r is None:
+            return None
+        return RelationMeta(
+            name=r.name,
+            direction=r.type.upper(),
+            target_model=None,
+            back_populates=r.back_populates,
+            secondary=r.through,
+        )
+
     def get_column_type_name(self, model: type, field_name: str) -> str | None:
         schema: Schema = getattr(model, "__schema__", None)
         if schema is None:
diff --git a/fastapi_admin_kit/backends/protocols.py b/fastapi_admin_kit/backends/protocols.py
index a17db24..e09d7c7 100644
--- a/fastapi_admin_kit/backends/protocols.py
+++ b/fastapi_admin_kit/backends/protocols.py
@@ -54,6 +54,10 @@ def get_relationship(self, model: type, name: str) -> Any:
         """Return a single relationship descriptor by name, or None."""
         ...
 
+    def get_relationship_meta(self, model: type, name: str) -> RelationMeta | None:
+        """Return ORM-agnostic metadata for a single relationship, or None."""
+        ...
+
     def get_relationship_local_columns(self, model: type, name: str) -> list[str]:
         """Return the local column key(s) for a relationship.
 
diff --git a/fastapi_admin_kit/backends/sqlalchemy.py b/fastapi_admin_kit/backends/sqlalchemy.py
index 5445fc7..809a656 100644
--- a/fastapi_admin_kit/backends/sqlalchemy.py
+++ b/fastapi_admin_kit/backends/sqlalchemy.py
@@ -323,6 +323,23 @@ def get_relationship_local_columns(self, model: type, name: str) -> list[str]:
             return []
         return [c.key for c in rel.local_columns]
 
+    def get_relationship_meta(self, model: type, name: str) -> RelationMeta | None:
+        """Return ORM-agnostic metadata for a single relationship, or None."""
+        mapper = sa_inspect(model)
+        rel = mapper.relationships.get(name)
+        if rel is None:
+            return None
+        from fastapi_admin_kit.inspection.types import RelationMeta
+
+        return RelationMeta(
+            name=rel.key,
+            direction=rel.direction.name,
+            target_model=rel.mapper.class_,
+            uselist=rel.uselist,
+            back_populates=rel.back_populates,
+            secondary=rel.secondary,
+        )
+
     def get_column_type_name(self, model: type, field_name: str) -> str | None:
         """Return the SQLAlchemy type class name for a column, or None."""
         mapper = sa_inspect(model)
diff --git a/fastapi_admin_kit/filters/base.py b/fastapi_admin_kit/filters/base.py
index 485fb1b..c1bcd43 100644
--- a/fastapi_admin_kit/filters/base.py
+++ b/fastapi_admin_kit/filters/base.py
@@ -194,12 +194,21 @@ def __init__(
         label: str = "",
         resolved_column: str | None = None,
         choices: list[str] | None = None,
+        relationship_name: str | None = None,
+        target_model: Any = None,
+        target_pk: str | None = None,
     ) -> None:
         super().__init__(field_name, label)
         self.resolved_column = resolved_column
         self._choices = list(choices or [])
+        self.relationship_name = relationship_name
+        self.target_model = target_model
+        self.target_pk = target_pk
 
     def apply(self, query_adapter: Any, query: Any, model: Any, value: Any) -> Any:
+        if self.relationship_name:
+            return self._apply_membership(query_adapter, model, value)
+
         col_name = self.resolved_column or self.field_name
         col = self._column(model, col_name)
         if col is None:
@@ -221,6 +230,33 @@ def apply(self, query_adapter: Any, query: Any, model: Any, value: Any) -> Any:
             return col == value
         return None
 
+    def _apply_membership(self, query_adapter: Any, model: Any, value: Any) -> Any:
+        """Filter by related-object membership (M2M / reverse ONETOMANY).
+
+        Builds ``model.rel.any(target.pk == value)``. Unsupported backends
+        (no ``.any()`` on the relationship) return None and skip the filter.
+        """
+        rel = self._column(model, self.relationship_name or self.field_name)
+        target_col = getattr(self.target_model, self.target_pk, None) if self.target_model else None
+        if rel is None or target_col is None:
+            return None
+        try:
+            conditions: list = []
+            if isinstance(value, dict):
+                exact = value.get("exact", "")
+                if exact:
+                    conditions.append(rel.any(target_col == exact))
+                raw_in = value.get("in")
+                if raw_in:
+                    items = _split_csv(raw_in)
+                    if items:
+                        conditions.append(rel.any(target_col.in_(items)))
+            elif value:
+                return rel.any(target_col == value)
+            return self._combine(conditions, query_adapter)
+        except Exception:
+            return None
+
     def get_choices(self, session: Any = None) -> list[tuple[str, str]]:
         if not self._choices:
             return [("", "All")]
diff --git a/fastapi_admin_kit/filters/registry.py b/fastapi_admin_kit/filters/registry.py
index 5721483..085aa41 100644
--- a/fastapi_admin_kit/filters/registry.py
+++ b/fastapi_admin_kit/filters/registry.py
@@ -98,8 +98,7 @@ def auto_generate(
                 continue
 
             if field_name in rel_names:
-                resolved_col = self._resolve_fk_column(model, field_name, introspection)
-                filters[field_name] = ChoiceFilter(field_name, resolved_column=resolved_col)
+                filters[field_name] = self._relationship_filter(model, field_name, introspection)
                 continue
 
             type_name = self._get_type_name(model, field_name, introspection)
@@ -133,8 +132,7 @@ def auto_generate(
 
         for rel_name in rel_names:
             if rel_name not in filters:
-                resolved_col = self._resolve_fk_column(model, rel_name, introspection)
-                filters[rel_name] = ChoiceFilter(rel_name, resolved_column=resolved_col)
+                filters[rel_name] = self._relationship_filter(model, rel_name, introspection)
 
         return filters
 
@@ -142,6 +140,93 @@ def auto_generate(
     # Internal helpers — all go through IntrospectionBackend when available
     # ------------------------------------------------------------------
 
+    @classmethod
+    def _relationship_filter(
+        cls,
+        model: Any,
+        rel_name: str,
+        introspection: Any | None,
+    ) -> ChoiceFilter:
+        """Build a filter for a relationship, discovered via the backend.
+
+        MANYTOONE relationships filter the local FK column. M2M / ONETOMANY
+        relationships have no local FK — filtering uses related-object
+        membership (``rel.any(target.pk == value)``). Falls back to a plain
+        ``ChoiceFilter`` when the target cannot be resolved (e.g. memory
+        backend, where relation filters aren't supported).
+        """
+        meta = cls._get_relationship_meta(model, rel_name, introspection)
+        direction = meta.direction if meta is not None else None
+        resolved_col = cls._resolve_fk_column(model, rel_name, introspection)
+
+        if direction != "MANYTOONE":
+            target = meta.target_model if meta is not None else None
+            target_pk = (
+                cls._resolve_pk_column(target, introspection)
+                if target is not None
+                else None
+            )
+            if target is not None and target_pk is not None:
+                return ChoiceFilter(
+                    rel_name,
+                    relationship_name=rel_name,
+                    target_model=target,
+                    target_pk=target_pk,
+                )
+        return ChoiceFilter(rel_name, resolved_column=resolved_col)
+
+    @staticmethod
+    def _get_relationship_meta(
+        model: Any,
+        rel_name: str,
+        introspection: Any | None,
+    ) -> Any | None:
+        """Return ORM-agnostic relationship metadata, or None."""
+        if introspection is not None:
+            try:
+                return introspection.get_relationship_meta(model, rel_name)
+            except Exception:
+                return None
+        try:
+            from sqlalchemy import inspect as sa_inspect
+
+            from fastapi_admin_kit.inspection.types import RelationMeta
+
+            rel = sa_inspect(model).relationships.get(rel_name)
+            if rel is None:
+                return None
+            return RelationMeta(
+                name=rel.key,
+                direction=rel.direction.name,
+                target_model=rel.mapper.class_,
+                uselist=rel.uselist,
+                back_populates=rel.back_populates,
+                secondary=rel.secondary,
+            )
+        except Exception:
+            return None
+
+    @staticmethod
+    def _resolve_pk_column(model: Any, introspection: Any | None) -> str | None:
+        """Return the single primary-key column name for *model*, or None."""
+        if introspection is not None:
+            try:
+                cols = introspection.get_pk_columns(model)
+                if cols:
+                    col = cols[0]
+                    return getattr(col, "key", col)
+            except Exception:
+                pass
+        try:
+            from sqlalchemy import inspect as sa_inspect
+
+            mapper = sa_inspect(model)
+            if mapper.primary_key:
+                return mapper.primary_key[0].key
+        except Exception:
+            pass
+        return None
+
     @staticmethod
     def _get_type_name(model: Any, field_name: str, introspection: Any | None) -> str | None:
         """Return the ORM type class name for a column, or None."""
diff --git a/tests/test_filters.py b/tests/test_filters.py
index f2afd9e..b2b4662 100644
--- a/tests/test_filters.py
+++ b/tests/test_filters.py
@@ -22,7 +22,7 @@
 from fastapi_admin_kit.migrations.models import Role, User
 from fastapi_admin_kit.models.base import Base as AdminBase
 from tests.conftest import SECRET_KEY, create_session_cookie, run_async
-from tests.test_registry import Category, Product
+from tests.test_registry import Article, Category, Product, Tag
 
 
 @pytest.fixture(autouse=True)
@@ -158,6 +158,24 @@ def test_choice_filter_resolved_column(self):
         clause = f.apply(self.adapter, None, Product, {"in": "1,2"})
         assert "products.category_id IN" in str(clause)
 
+    def test_m2m_membership_exact(self):
+        from fastapi_admin_kit.filters import ChoiceFilter
+
+        f = ChoiceFilter("tags", relationship_name="tags", target_model=Tag, target_pk="id")
+        clause = f.apply(self.adapter, None, Article, "1")
+        assert clause is not None
+        sql = str(clause)
+        assert "article_tags" in sql
+        assert "tags.id" in sql
+
+    def test_m2m_membership_in(self):
+        from fastapi_admin_kit.filters import ChoiceFilter
+
+        f = ChoiceFilter("tags", relationship_name="tags", target_model=Tag, target_pk="id")
+        clause = f.apply(self.adapter, None, Article, {"in": "1,2"})
+        assert clause is not None
+        assert "tags.id IN" in str(clause)
+
     def test_invalid_value_skipped(self):
         from fastapi_admin_kit.filters import NumericFilter
 
@@ -193,6 +211,32 @@ def test_auto_generate_types(self):
         assert isinstance(filters["category_id"], ChoiceFilter)
         assert isinstance(filters["category"], ChoiceFilter)
 
+    def test_auto_generate_many_to_one_resolves_fk_column(self):
+        from fastapi_admin_kit.filters import FilterRegistry
+        from fastapi_admin_kit.registry import AdminRegistry
+
+        reg = AdminRegistry()
+        reg.clear()
+        registered = reg.register(Product)
+        filters = FilterRegistry().auto_generate(Product, registered.columns)
+        assert filters["category"].resolved_column == "category_id"
+        assert filters["category"].relationship_name is None
+
+    def test_auto_generate_many_to_many_uses_membership(self):
+        from fastapi_admin_kit.filters import ChoiceFilter, FilterRegistry
+        from fastapi_admin_kit.registry import AdminRegistry
+
+        reg = AdminRegistry()
+        reg.clear()
+        registered = reg.register(Article)
+        filters = FilterRegistry().auto_generate(Article, registered.columns)
+        f = filters["tags"]
+        assert isinstance(f, ChoiceFilter)
+        assert f.relationship_name == "tags"
+        assert f.target_model is Tag
+        assert f.target_pk == "id"
+        assert f.resolved_column is None
+
     def test_auto_generate_memory_backend(self):
         from fastapi_admin_kit.backends import InMemoryBackend
         from fastapi_admin_kit.filters import (
@@ -330,6 +374,86 @@ def api():
     cleanup()
 
 
+def _make_m2m_client():
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    sync_engine = create_engine(f"sqlite:///{path}", connect_args={"check_same_thread": False})
+    AdminBase.metadata.create_all(sync_engine)
+    Article.metadata.create_all(sync_engine)
+    sync_engine.dispose()
+    async_engine = create_async_engine(
+        f"sqlite+aiosqlite:///{path}",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+
+    async def _seed():
+        async with AsyncSession(async_engine) as session:
+            role = Role(name="SuperAdmin")
+            session.add(role)
+            await session.flush()
+            user = User(
+                email="test@example.com",
+                password="$2b$12$DOXzSwSZYp0Y1pTzEvWjO.KOLQg3wA/Ez1RkN4RHMiLqngoLM2lMG",
+                full_name="Test User",
+                is_superuser=True,
+                is_active=True,
+            )
+            user.roles.append(role)
+            session.add(user)
+
+            python = Tag(name="python")
+            web = Tag(name="web")
+            session.add_all([python, web])
+            await session.flush()
+
+            session.add_all(
+                [
+                    Article(title="Flask guide", tags=[python]),
+                    Article(title="Reflex blog", tags=[python, web]),
+                    Article(title="Figma tricks", tags=[web]),
+                ]
+            )
+            await session.commit()
+
+    run_async(_seed())
+
+    from fastapi_admin_kit.modeladmin import ModelAdmin
+
+    admin_cls = type("ArticleAdmin", (ModelAdmin,), {"list_filter": ["tags"]})
+
+    admin = Admin(
+        engine=async_engine,
+        auth_model=User,
+        auth_backend=BuiltinAuthBackend(),
+        secret_key=SECRET_KEY,
+        auto_discover=False,
+        session_secure=False,
+    )
+    admin.register(Article, admin_cls)
+    app = FastAPI()
+    run_async(admin.setup(app))
+    client = TestClient(app)
+    creds = base64.b64encode(b"test@example.com:secret").decode()
+    token = client.post("/api/auth/token", headers={"Authorization": f"Basic {creds}"}).json()[
+        "access_token"
+    ]
+    headers = {"Authorization": f"Bearer {token}"}
+
+    def cleanup():
+        run_async(async_engine.dispose())
+        os.unlink(path)
+
+    return client, headers, cleanup
+
+
+@pytest.fixture
+def api_m2m():
+    client, headers, cleanup = _make_m2m_client()
+    yield client, headers
+    cleanup()
+
+
 def _names(body):
     return {item["name"] for item in body["items"]}
 
@@ -404,6 +528,26 @@ def test_combined_filters(self, api):
         assert _names(body) == {"Widget", "Widglet"}
 
 
+class TestApiM2MFilters:
+    def _titles(self, body):
+        return {item["title"] for item in body["items"]}
+
+    def test_m2m_exact(self, api_m2m):
+        client, headers = api_m2m
+        body = client.get("/api/articles/?filter_tags=1", headers=headers).json()
+        assert self._titles(body) == {"Flask guide", "Reflex blog"}
+
+    def test_m2m_other_tag(self, api_m2m):
+        client, headers = api_m2m
+        body = client.get("/api/articles/?filter_tags=2", headers=headers).json()
+        assert self._titles(body) == {"Reflex blog", "Figma tricks"}
+
+    def test_m2m_in(self, api_m2m):
+        client, headers = api_m2m
+        body = client.get("/api/articles/?filter_tags__in=1", headers=headers).json()
+        assert self._titles(body) == {"Flask guide", "Reflex blog"}
+
+
 class TestAdminUiListFilters:
     def test_icontains_in_list_view(self, api):
         client, _headers = api
diff --git a/tests/test_registry.py b/tests/test_registry.py
index f28d0ad..56d05b4 100644
--- a/tests/test_registry.py
+++ b/tests/test_registry.py
@@ -1,7 +1,7 @@
 """Tests for ModelAdmin base class, AdminRegistry, and @admin.register."""
 
 import pytest
-from sqlalchemy import Boolean, Column, ForeignKey, Integer, String
+from sqlalchemy import Boolean, Column, ForeignKey, Integer, String, Table
 from sqlalchemy.orm import DeclarativeBase, relationship
 
 
@@ -28,6 +28,14 @@ class Product(Base):
     category = relationship("Category")
 
 
+article_tags = Table(
+    "article_tags",
+    Base.metadata,
+    Column("article_id", Integer, ForeignKey("articles.id"), primary_key=True),
+    Column("tag_id", Integer, ForeignKey("tags.id"), primary_key=True),
+)
+
+
 class Article(Base):
     __tablename__ = "articles"
 
@@ -35,6 +43,15 @@ class Article(Base):
     title = Column(String(200), nullable=False)
     body = Column(String(5000))
 
+    tags = relationship("Tag", secondary=article_tags)
+
+
+class Tag(Base):
+    __tablename__ = "tags"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(100), nullable=False)
+
 
 # ===========================================================================
 # 5.1-5.3 ModelAdmin base class

From a50c331807d455c89cf20490f4d92bc46ef7c942 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Thu, 10 Sep 2026 15:48:41 +0600
Subject: [PATCH 04/12] fix: add value coercion for ChoiceFilter to handle
 non-string types

---
 fastapi_admin_kit/filters/base.py | 45 ++++++++++++++++++++++++++-----
 tests/test_filters.py             | 15 +++++++++++
 2 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/fastapi_admin_kit/filters/base.py b/fastapi_admin_kit/filters/base.py
index c1bcd43..326ccf5 100644
--- a/fastapi_admin_kit/filters/base.py
+++ b/fastapi_admin_kit/filters/base.py
@@ -81,6 +81,21 @@ def _coerce(value: str, converter: Callable[[str], Any]) -> Any | None:
         except (ValueError, TypeError):
             return None
 
+    @staticmethod
+    def _coerce_column_value(value: Any, col: Any) -> Any | None:
+        if not isinstance(value, str):
+            return value
+        try:
+            python_type = col.type.python_type
+        except (AttributeError, NotImplementedError):
+            return value
+        if python_type is str:
+            return value
+        try:
+            return python_type(value)
+        except (ValueError, TypeError, OverflowError):
+            return None
+
     @staticmethod
     def _combine(conditions: list, query_adapter: Any = None) -> Any | None:
         """Combine zero or more conditions into a single AND clause."""
@@ -218,16 +233,25 @@ def apply(self, query_adapter: Any, query: Any, model: Any, value: Any) -> Any:
             conditions: list = []
             exact = value.get("exact", "")
             if exact:
-                conditions.append(col == exact)
+                converted = self._coerce_column_value(exact, col)
+                if converted is not None:
+                    conditions.append(col == converted)
             raw_in = value.get("in")
             if raw_in:
-                items = _split_csv(raw_in)
+                items = []
+                for item in _split_csv(raw_in):
+                    converted = self._coerce_column_value(item, col)
+                    if converted is not None:
+                        items.append(converted)
                 if items:
                     conditions.append(col.in_(items))
             return self._combine(conditions, query_adapter)
 
         if value:
-            return col == value
+            converted = self._coerce_column_value(value, col)
+            if converted is None:
+                return None
+            return col == converted
         return None
 
     def _apply_membership(self, query_adapter: Any, model: Any, value: Any) -> Any:
@@ -245,14 +269,23 @@ def _apply_membership(self, query_adapter: Any, model: Any, value: Any) -> Any:
             if isinstance(value, dict):
                 exact = value.get("exact", "")
                 if exact:
-                    conditions.append(rel.any(target_col == exact))
+                    converted = self._coerce_column_value(exact, target_col)
+                    if converted is not None:
+                        conditions.append(rel.any(target_col == converted))
                 raw_in = value.get("in")
                 if raw_in:
-                    items = _split_csv(raw_in)
+                    items = []
+                    for item in _split_csv(raw_in):
+                        converted = self._coerce_column_value(item, target_col)
+                        if converted is not None:
+                            items.append(converted)
                     if items:
                         conditions.append(rel.any(target_col.in_(items)))
             elif value:
-                return rel.any(target_col == value)
+                converted = self._coerce_column_value(value, target_col)
+                if converted is None:
+                    return None
+                return rel.any(target_col == converted)
             return self._combine(conditions, query_adapter)
         except Exception:
             return None
diff --git a/tests/test_filters.py b/tests/test_filters.py
index b2b4662..13d0a3a 100644
--- a/tests/test_filters.py
+++ b/tests/test_filters.py
@@ -158,6 +158,21 @@ def test_choice_filter_resolved_column(self):
         clause = f.apply(self.adapter, None, Product, {"in": "1,2"})
         assert "products.category_id IN" in str(clause)
 
+    def test_choice_filter_coerces_integer_exact_value(self):
+        from sqlalchemy.dialects import postgresql
+
+        from fastapi_admin_kit.filters import ChoiceFilter
+
+        f = ChoiceFilter("category", resolved_column="category_id")
+        clause = f.apply(self.adapter, None, Product, "2")
+        compiled = clause.compile(
+            dialect=postgresql.dialect(), compile_kwargs={"literal_binds": True}
+        )
+
+        assert clause.right.value == 2
+        assert "products.category_id = 2" in str(compiled)
+        assert "products.category_id = '2'" not in str(compiled)
+
     def test_m2m_membership_exact(self):
         from fastapi_admin_kit.filters import ChoiceFilter
 

From b6ce9ca8a0cbe31786b7b61d79b749c196bdbeaa Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Fri, 11 Sep 2026 17:17:27 +0600
Subject: [PATCH 05/12] feat: add required fields to AuthModelMixin and related
 models for enhanced user authentication

---
 docs/guide/custom-auth-model.md      | 35 ++++++++++++--------
 example/example.py                   |  5 +++
 fastapi_admin_kit/auth/mixins.py     | 48 ++++++++++++++++++----------
 fastapi_admin_kit/auth/protocol.py   | 12 +++++--
 fastapi_admin_kit/config/auth.py     | 24 ++++++++++----
 tests/test_admin_config.py           |  1 +
 tests/test_schema_materialization.py |  5 ++-
 7 files changed, 90 insertions(+), 40 deletions(-)

diff --git a/docs/guide/custom-auth-model.md b/docs/guide/custom-auth-model.md
index aec6b6c..3ab1ee3 100644
--- a/docs/guide/custom-auth-model.md
+++ b/docs/guide/custom-auth-model.md
@@ -20,7 +20,7 @@ import uuid
 from typing import Optional
 
 from fastapi import FastAPI
-from sqlalchemy import Column, ForeignKey, Integer, String
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Integer, String
 from sqlalchemy.orm import DeclarativeBase, relationship
 from sqlalchemy.types import Uuid
 
@@ -37,11 +37,15 @@ class User(AuthModelMixin, Base):
 
     id = Column(Uuid, primary_key=True, default=uuid.uuid4)
     email = Column(String(255), unique=True, nullable=False, index=True)
-    hashed_password = Column(String(255), nullable=False)
     name = Column(String(255), nullable=True)
 
-    # AuthModelMixin provides the rest of the protocol surface
-    # (is_active, is_superuser, role_ids, verify_password, etc.).
+    # Required: AuthModelMixin is behavior-only — add these 4 fields
+    # with your ORM (SQLAlchemy shown; SQLModel/Tortoise declare the
+    # same 4 names with their own Field types).
+    password = Column(String(255), nullable=False)
+    is_active = Column(Boolean, default=True)
+    is_superuser = Column(Boolean, default=False)
+    last_login = Column(DateTime(timezone=True), nullable=True)
 
 
 app = FastAPI()
@@ -124,16 +128,19 @@ Your `auth_model` must satisfy `AdminUserProtocol` (validated at
 |-----------|------|-------|
 | `id` | any | The PK type — `int`, `UUID`, etc. |
 | `email` | `str` | Used as the login identifier |
-| `is_active` | `bool` | Inactive users cannot log in |
-| `is_superuser` | `bool` | Bypasses all RBAC checks |
-| `hashed_password` | `str` | bcrypt / argon2 hash |
-| `role_ids` | `list[int]` | Property that returns role IDs |
-| `roles` | relationship | M2M to `Role` model |
-| `verify_password(plain)` | method | Returns `bool` |
-
-`fastapi_admin_kit.auth.mixins.AuthModelMixin` provides all of the
-above for SQLAlchemy declarative models — inherit from it to get
-`is_active`, `is_superuser`, `role_ids`, and password helpers for free.
+| `password` | `str` | Hashed password (bcrypt / argon2), `String(255)`, `nullable=False` recommended |
+| `is_active` | `bool` | Inactive users cannot log in (`default=True` recommended) |
+| `is_superuser` | `bool` | Bypasses all RBAC checks (`default=False` recommended) |
+| `last_login` | `datetime \| None` | Tz-aware, nullable |
+| `role_ids` | `list[int]` | Property that returns role IDs (provided by mixin) |
+| `roles` | relationship | M2M to `Role` model (optional if you only need `role_ids`) |
+| `verify_password(plain)` | method | Returns `bool` (provided by mixin) |
+
+`fastapi_admin_kit.auth.mixins.AuthModelMixin` is behavior-only — it
+provides `role_ids`, `verify_password`, `hash_password`, `has_perm`, etc.
+You must add the 4 fields (`password`, `is_active`, `is_superuser`,
+`last_login`) with your ORM on your model. The same 4 names apply to
+SQLAlchemy, SQLModel, Tortoise, and other Python ORMs.
 
 ## Troubleshooting
 
diff --git a/example/example.py b/example/example.py
index fa4d468..0c9cc67 100644
--- a/example/example.py
+++ b/example/example.py
@@ -105,7 +105,12 @@ class User(AuthModelMixin, Base):
     id = Column(Integer, primary_key=True)
     email = Column(String(255), nullable=False, unique=True)
     full_name = Column(String(255), nullable=True)
+    # Required auth fields — AuthModelMixin is behavior-only, declare
+    # these 4 with your ORM.
+    password = Column(String(255), nullable=False)
     is_active = Column(Boolean, default=True)
+    is_superuser = Column(Boolean, default=False)
+    last_login = Column(DateTime(timezone=True), nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
 
     # Relationships
diff --git a/fastapi_admin_kit/auth/mixins.py b/fastapi_admin_kit/auth/mixins.py
index f44e28e..6ee5c2c 100644
--- a/fastapi_admin_kit/auth/mixins.py
+++ b/fastapi_admin_kit/auth/mixins.py
@@ -4,25 +4,44 @@
 
 from typing import TYPE_CHECKING, ClassVar
 
-from sqlalchemy import Boolean, Column, DateTime, String
-
 from fastapi_admin_kit.backends import as_session_backend
 
 if TYPE_CHECKING:
+    from datetime import datetime
+
     from sqlalchemy.ext.asyncio import AsyncSession
 
+    # Editor-only hints for the 4 ORM-mapped fields the host model must
+    # declare with its own ORM (SQLAlchemy Column, SQLModel Field,
+    # Tortoise field, ...). Declared here only for type checkers —
+    # there are NO runtime attributes for these names on the mixin,
+    # so subclasses never trigger field-shadowing warnings.
+    password: str | None
+    is_active: bool
+    is_superuser: bool
+    last_login: datetime | None
+
 
 class AuthModelMixin:
-    """Mixin for custom user models to work with admin's built-in RBAC.
+    """ORM-agnostic behavior mixin for custom user models.
+
+    The mixin provides **behavior only** — no ORM columns/fields.
+    You must add these 4 fields with your ORM on your auth model::
 
-    Provides: password, is_active, is_superuser, last_login columns,
-    role_ids property, verify_password() and hash_password() methods.
+        password      — hashed password (str, e.g. String(255), NOT NULL)
+        is_active     — bool, recommended default True
+        is_superuser  — bool, recommended default False
+        last_login    — datetime with timezone, nullable (recommended)
+
+    Defaults/nullability beyond presence are per-app; the admin validator
+    only checks that the attributes exist (plus ``verify_password``).
+    Works with SQLAlchemy, SQLModel, and other Python ORMs — each model
+    declares the 4 fields with its own ``Column``/``Field`` type.
 
     Usage::
 
         from fastapi_admin_kit.auth.mixins import AuthModelMixin
-        from fastapi_admin_kit.auth.models import admin_user_roles, Role
-        from sqlalchemy.orm import relationship
+        from sqlalchemy import Boolean, Column, DateTime, String
 
         class MyUser(AuthModelMixin, Base):
             __tablename__ = "my_users"
@@ -31,16 +50,18 @@ class MyUser(AuthModelMixin, Base):
             username = Column(String(255), unique=True)
             email = Column(String(255), unique=True)
 
+            # Required: declare these 4 with your ORM
+            password = Column(String(255), nullable=False)
+            is_active = Column(Boolean, default=True)
+            is_superuser = Column(Boolean, default=False)
+            last_login = Column(DateTime(timezone=True), nullable=True)
+
             # Define roles relationship yourself (FK must match your table)
             roles = relationship(
                 "Role", secondary=admin_user_roles, back_populates="users"
             )
 
     The mixin provides:
-    - ``password`` column (String 255) — stores the hashed password
-    - ``is_active`` column (Boolean, default True)
-    - ``is_superuser`` column (Boolean, default False)
-    - ``last_login`` column (DateTime with timezone, nullable)
     - ``role_ids`` property → ``list[int]`` (reads from ``self.roles``)
     - ``verify_password(password)`` → bool
     - ``hash_password(password)`` → str (classmethod)
@@ -50,11 +71,6 @@ class MyUser(AuthModelMixin, Base):
 
     _hasher: ClassVar[type | None] = None
 
-    password = Column(String(255))
-    is_active = Column(Boolean, default=True)
-    is_superuser = Column(Boolean, default=False)
-    last_login = Column(DateTime(timezone=True), nullable=True)
-
     @property
     def role_ids(self) -> list[int]:
         """Return list of role IDs from the ``roles`` relationship."""
diff --git a/fastapi_admin_kit/auth/protocol.py b/fastapi_admin_kit/auth/protocol.py
index 79efdec..70ea444 100644
--- a/fastapi_admin_kit/auth/protocol.py
+++ b/fastapi_admin_kit/auth/protocol.py
@@ -52,12 +52,20 @@ class AdminUserProtocol(Protocol):
 
     Any user model passed as ``auth_model=`` must satisfy this interface.
     The admin framework only reads these attributes from the user object.
+
+    ``AuthModelMixin`` is behavior-only — the host model must declare the
+    4 data fields (``password``, ``is_active``, ``is_superuser``,
+    ``last_login``) with its own ORM (SQLAlchemy ``Column``, SQLModel
+    ``Field``, Tortoise field, ...). Either a ``roles`` relationship or
+    the ``role_ids`` property satisfies role lookups.
     """
 
     id: Any  # primary key (int, str, UUID, etc.)
     email: str  # used for audit log denormalization
-    is_active: bool  # inactive users are refused login
-    is_superuser: bool  # bypasses all permission checks if True
+    password: str | None  # hashed password; declare with your ORM
+    is_active: bool  # inactive users are refused login; declare with your ORM
+    is_superuser: bool  # bypasses all permission checks if True; declare with your ORM
+    last_login: Any | None  # tz-aware datetime or None; declare with your ORM
 
     # Many-to-many roles — the admin reads this to look up permissions.
     # Must be an iterable of role objects, each with an `id` attribute
diff --git a/fastapi_admin_kit/config/auth.py b/fastapi_admin_kit/config/auth.py
index f651e73..69cd256 100644
--- a/fastapi_admin_kit/config/auth.py
+++ b/fastapi_admin_kit/config/auth.py
@@ -83,27 +83,36 @@ def validate_auth_model(self) -> None:
                 f"{', '.join(missing)}. Every auth model must have id and email."
             )
 
-        # Required: is_active, is_superuser (can be provided by AuthModelMixin)
+        # Required: is_active, is_superuser, last_login.
+        # AuthModelMixin is behavior-only — add these 4 fields with your ORM.
         missing_flags = []
         if not hasattr(model, "is_active"):
             missing_flags.append("is_active")
         if not hasattr(model, "is_superuser"):
             missing_flags.append("is_superuser")
+        if not hasattr(model, "last_login"):
+            missing_flags.append("last_login")
         if missing_flags:
             raise ConfigError(
                 f"auth_model {model.__name__!r} is missing: {', '.join(missing_flags)}. "
-                f"Use AuthModelMixin or add these columns to your model."
+                f"Add these 4 fields with your ORM (see docs): "
+                f"password, is_active, is_superuser, last_login."
             )
 
-        # Required: roles or role_ids (for RBAC)
+        # Required: roles or role_ids (for RBAC).
+        # AuthModelMixin provides a defensive role_ids property that returns
+        # [] when the model has no roles relationship (e.g. single-role
+        # enum models). Full RBAC requires a roles relationship.
         if not hasattr(model, "roles") and not hasattr(model, "role_ids"):
             raise ConfigError(
                 f"auth_model {model.__name__!r} has no 'roles' relationship or "
                 f"'role_ids' property. RBAC requires role lookups. "
-                f"Use AuthModelMixin or define a roles relationship on your model."
+                f"Add a roles relationship with your ORM on your model."
             )
 
-        # Check password-related attributes for authentication
+        # Check password-related attributes for authentication.
+        # AuthModelMixin provides verify_password/hash_password behavior —
+        # add the password field itself with your ORM.
         missing_auth = []
         if not hasattr(model, "password"):
             missing_auth.append("password")
@@ -113,6 +122,7 @@ def validate_auth_model(self) -> None:
             raise ConfigError(
                 f"auth_model {model.__name__!r} is missing password-related "
                 f"attributes: {', '.join(missing_auth)}. "
-                f"Use AuthModelMixin or implement password (str) and "
-                f"verify_password(password) -> bool."
+                f"Add the password field with your ORM and inherit "
+                f"AuthModelMixin (or implement password (str) and "
+                f"verify_password(password) -> bool)."
             )
diff --git a/tests/test_admin_config.py b/tests/test_admin_config.py
index 762215e..d17ad3b 100644
--- a/tests/test_admin_config.py
+++ b/tests/test_admin_config.py
@@ -65,6 +65,7 @@ class ValidAuthModel:
             email = None
             is_active = None
             is_superuser = None
+            last_login = None
             roles = None
             password = ""
 
diff --git a/tests/test_schema_materialization.py b/tests/test_schema_materialization.py
index 148859b..47ba954 100644
--- a/tests/test_schema_materialization.py
+++ b/tests/test_schema_materialization.py
@@ -533,6 +533,7 @@ class UserNoRoles:
             email = "test@test.com"
             is_active = True
             is_superuser = False
+            last_login = None
             password = "hash"
             role_ids = None  # has role_ids but it's not a list property
 
@@ -559,6 +560,7 @@ class CustomUser:
             email = "u@x.com"
             is_active = True
             is_superuser = False
+            last_login = None
             password = "h"
             role_ids = []
 
@@ -597,7 +599,7 @@ async def test_create_tables_skips_builtin_user_when_custom_auth_model(self, mon
         ``admin_user_roles`` IS created with its ``user_id`` FK
         retargeted to the custom auth_model's table.
         """
-        from sqlalchemy import Column, Integer, String
+        from sqlalchemy import Column, DateTime, Integer, String
         from sqlalchemy.orm import DeclarativeBase
 
         from fastapi_admin_kit.admin.core import Admin
@@ -612,6 +614,7 @@ class CustomUser(_TestBase):
             password = Column(String, nullable=False)
             is_active = Column(Integer, default=True)
             is_superuser = Column(Integer, default=False)
+            last_login = Column(DateTime, nullable=True)
 
             @property
             def role_ids(self) -> list[int]:

From 9376453ad806d5d3270ae76773bd23942fa1474f Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Sat, 12 Sep 2026 11:29:00 +0600
Subject: [PATCH 06/12] add simple filter base class for django style admin
 class

---
 docs/guide/filters.md                   | 30 ++++++++++
 fastapi_admin_kit/filters/__init__.py   |  2 +
 fastapi_admin_kit/filters/base.py       | 18 ++++++
 fastapi_admin_kit/views/list_context.py |  5 +-
 fastapi_admin_kit/views/renderers.py    |  5 +-
 tests/test_filters.py                   | 75 +++++++++++++++++++++++++
 6 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/docs/guide/filters.md b/docs/guide/filters.md
index d0370de..ab373a2 100644
--- a/docs/guide/filters.md
+++ b/docs/guide/filters.md
@@ -123,6 +123,36 @@ class ProductAdmin(ModelAdmin):
     list_filter = ["name", IntegerFilter("price", label="Price")]
 ```
 
+### SimpleFilter
+
+Django `SimpleListFilter` style: declare `parameter_name` + `title` as class
+attributes and pass the *class itself* in `list_filter` — no constructor args,
+no instance:
+
+```python
+from fastapi_admin_kit.filters import SimpleFilter
+
+class InStockFilter(SimpleFilter):
+    parameter_name = "in_stock"
+    title = "Stock Status"
+    field_type = "boolean"
+
+    def apply(self, query_adapter, query, model, value):
+        raw = value.get("exact") if isinstance(value, dict) else value
+        if raw and raw.lower() in ("1", "true"):
+            return model.stock > 0
+        if raw:
+            return model.stock <= 0
+        return None
+
+    def get_choices(self, session=None):
+        return [("", "All"), ("1", "In stock"), ("0", "Out of stock")]
+
+@admin.register(Product)
+class ProductAdmin(ModelAdmin):
+    list_filter = [InStockFilter]   # class itself, no instantiation
+```
+
 ## Query Parameter Lookups
 
 Filters are applied as query parameters in both the admin UI list view and the
diff --git a/fastapi_admin_kit/filters/__init__.py b/fastapi_admin_kit/filters/__init__.py
index 8f578bc..a1f4d38 100644
--- a/fastapi_admin_kit/filters/__init__.py
+++ b/fastapi_admin_kit/filters/__init__.py
@@ -13,6 +13,7 @@
     IntegerFilter,
     NumericFilter,
     RelationFilter,
+    SimpleFilter,
     TextFilter,
     TimeFilter,
 )
@@ -28,6 +29,7 @@
     "EnumFilter",
     "IntegerFilter",
     "NumericFilter",
+    "SimpleFilter",
     "DateRangeFilter",
     "DatetimeRangeFilter",
     "TimeFilter",
diff --git a/fastapi_admin_kit/filters/base.py b/fastapi_admin_kit/filters/base.py
index c1bcd43..6d54ec4 100644
--- a/fastapi_admin_kit/filters/base.py
+++ b/fastapi_admin_kit/filters/base.py
@@ -141,6 +141,24 @@ def _comparison_lookups(
         return conditions
 
 
+class SimpleFilter(Filter):
+    """Class-configured filter (Django ``SimpleListFilter`` style).
+
+    The author declares ``parameter_name`` and ``title`` as class attributes
+    and passes the *class itself* (not an instance) in ``list_filter``.
+    """
+
+    parameter_name: str = ""
+    title: str = ""
+
+    def __init__(self, label: str = "") -> None:
+        if not self.parameter_name:
+            raise TypeError(
+                f"{type(self).__name__} requires a non-empty 'parameter_name' class attribute"
+            )
+        super().__init__(self.parameter_name, label or self.title)
+
+
 class TextFilter(Filter):
     """Text filter — exact match plus icontains/startswith/endswith lookups."""
 
diff --git a/fastapi_admin_kit/views/list_context.py b/fastapi_admin_kit/views/list_context.py
index 6733096..e1d2b27 100644
--- a/fastapi_admin_kit/views/list_context.py
+++ b/fastapi_admin_kit/views/list_context.py
@@ -37,7 +37,7 @@ def _get_or_build_filters(
         If ``list_filter`` contains Filter instances they are used directly;
         strings are auto-resolved via FilterRegistry.
         """
-        from fastapi_admin_kit.filters import Filter, FilterRegistry
+        from fastapi_admin_kit.filters import Filter, FilterRegistry, SimpleFilter
 
         introspection = self._get_introspection(request)
         registry = FilterRegistry()
@@ -54,6 +54,9 @@ def _get_or_build_filters(
                     result[item] = auto[item]
             elif isinstance(item, Filter):
                 result[item.field_name] = item
+            elif isinstance(item, type) and issubclass(item, SimpleFilter):
+                item = item()
+                result[item.field_name] = item
         return result
 
     def _collect_filter_value(
diff --git a/fastapi_admin_kit/views/renderers.py b/fastapi_admin_kit/views/renderers.py
index 9afcca3..5e206b4 100644
--- a/fastapi_admin_kit/views/renderers.py
+++ b/fastapi_admin_kit/views/renderers.py
@@ -367,7 +367,7 @@ def _build_filter_clauses(
         registered: RegisteredModel,
     ) -> list:
         """Build filter clauses via Filter.apply()."""
-        from fastapi_admin_kit.filters import Filter, FilterRegistry
+        from fastapi_admin_kit.filters import Filter, FilterRegistry, SimpleFilter
         from fastapi_admin_kit.filters.lookups import parse_filter_params
 
         query_adapter = self._get_query_adapter(request)
@@ -381,6 +381,9 @@ def _build_filter_clauses(
                 filters[item] = auto[item]
             elif isinstance(item, Filter):
                 filters[item.field_name] = item
+            elif isinstance(item, type) and issubclass(item, SimpleFilter):
+                item = item()
+                filters[item.field_name] = item
 
         clauses: list = []
         for field_name, filter_obj in filters.items():
diff --git a/tests/test_filters.py b/tests/test_filters.py
index b2b4662..60a4674 100644
--- a/tests/test_filters.py
+++ b/tests/test_filters.py
@@ -19,6 +19,7 @@
 
 from fastapi_admin_kit import Admin
 from fastapi_admin_kit.auth.backend import BuiltinAuthBackend
+from fastapi_admin_kit.filters import SimpleFilter
 from fastapi_admin_kit.migrations.models import Role, User
 from fastapi_admin_kit.models.base import Base as AdminBase
 from tests.conftest import SECRET_KEY, create_session_cookie, run_async
@@ -97,6 +98,50 @@ def test_no_params(self):
         assert active == {}
 
 
+# ===========================================================================
+# Unit: SimpleFilter class-configuration (Django SimpleListFilter style)
+# ===========================================================================
+
+
+class TestSimpleFilter:
+    def test_class_attrs_derive_field_name_and_label(self):
+        from fastapi_admin_kit.filters import SimpleFilter
+
+        class InStockFilter(SimpleFilter):
+            parameter_name = "in_stock"
+            title = "Stock Status"
+            field_type = "boolean"
+
+            def apply(self, query_adapter, query, model, value):
+                return None
+
+        f = InStockFilter()
+        assert f.field_name == "in_stock"
+        assert f.label == "Stock Status"
+
+    def test_empty_label_falls_back_to_title(self):
+        from fastapi_admin_kit.filters import SimpleFilter
+
+        class ActiveFilter(SimpleFilter):
+            parameter_name = "is_active"
+            title = "Active Status"
+
+            def apply(self, query_adapter, query, model, value):
+                return None
+
+        assert ActiveFilter().label == "Active Status"
+
+    def test_missing_parameter_name_raises_type_error(self):
+        from fastapi_admin_kit.filters import SimpleFilter
+
+        class BrokenFilter(SimpleFilter):
+            def apply(self, query_adapter, query, model, value):
+                return None
+
+        with pytest.raises(TypeError, match="parameter_name"):
+            BrokenFilter()
+
+
 # ===========================================================================
 # Unit: Filter.apply() clause building
 # ===========================================================================
@@ -458,6 +503,36 @@ def _names(body):
     return {item["name"] for item in body["items"]}
 
 
+class InStockFilter(SimpleFilter):
+    """Bare-class filter keyed off the Product.is_active boolean column."""
+
+    parameter_name = "is_active"
+    title = "Stock Status"
+    field_type = "boolean"
+
+    def apply(self, query_adapter, query, model, value):
+        raw = value.get("exact") if isinstance(value, dict) else value
+        if not raw:
+            return None
+        in_stock = raw.lower() in ("1", "true")
+        return model.is_active == in_stock
+
+    def get_choices(self, session=None):
+        return [("", "All"), ("1", "In stock"), ("0", "Out of stock")]
+
+
+class TestApiSimpleFilter:
+    def test_bare_class_filters_via_api(self):
+        client, headers, cleanup = _make_client([InStockFilter])
+        try:
+            body = client.get("/api/products/?filter_is_active=1", headers=headers).json()
+            assert _names(body) == {"Widget", "Widglet", "Textbook"}
+            body = client.get("/api/products/?filter_is_active=0", headers=headers).json()
+            assert _names(body) == {"Novel"}
+        finally:
+            cleanup()
+
+
 class TestApiFilters:
     def test_exact_match(self, api):
         client, headers = api

From 6243553faa620ea10963d7d47832150dccc2f3f1 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Sat, 12 Sep 2026 14:46:55 +0600
Subject: [PATCH 07/12] fix filter and multipart parser for swagger

---
 CHANGELOG.md                                  |   8 +
 docs/guide/filters.md                         |  35 ++--
 docs/guide/json-api.md                        |  14 ++
 example/example.py                            |  21 +-
 fastapi_admin_kit/api/crud.py                 | 179 +++++++++++++++++-
 fastapi_admin_kit/api/schema_generator.py     |  64 ++++++-
 fastapi_admin_kit/filters/lookups.py          |  26 +--
 .../templates/admin/base_list.html            |  24 ++-
 .../templates/partials/inline_edit_form.html  |   2 +-
 fastapi_admin_kit/views/renderers.py          |  30 +++
 fastapi_admin_kit/widgets/inputs.py           |   8 +-
 tests/test_filters.py                         |  82 +++++---
 12 files changed, 403 insertions(+), 90 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 295c981..abdaa20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+- feat: add Django-style `SimpleFilter` base class — class-configured filters, pass the class itself in `list_filter`
+- feat: list filters configured in `list_filter` are documented as query params on the JSON API list endpoint in the OpenAPI/Swagger schema (lookups limited to the field type's supported lookups)
+- change: filter query params dropped the `filter_` prefix — they now use the bare field name and lookup (e.g. `name__icontains=wid`) in both the admin UI and the JSON API
+- feat: enum columns map to real enum types in the API create/update schemas so Swagger shows them as dropdowns; models with file/image fields expose create/update as multipart forms with file pickers, saved through the same storage backend as the HTML form
+- fix: `SelectWidget` validation accepted only member names, rejecting the stored values of str-enum members
+
 ## [0.6.0] - 2026-09-03
 
 - feat: improve form rendering — WYSIWYG and array input widgets ([#59](https://github.com/borhanst/fastapi-admin-kit/pull/59))
diff --git a/docs/guide/filters.md b/docs/guide/filters.md
index ab373a2..54e0b95 100644
--- a/docs/guide/filters.md
+++ b/docs/guide/filters.md
@@ -156,33 +156,38 @@ class ProductAdmin(ModelAdmin):
 ## Query Parameter Lookups
 
 Filters are applied as query parameters in both the admin UI list view and the
-JSON API. Lookups follow the `django-filter` convention (`filter_<field>__<lookup>`):
+JSON API. Lookups follow the field-name convention (`<field>__<lookup>`):
 
 ```
-filter_name=value              exact match
-filter_name__icontains=term    case-insensitive contains
-filter_name__startswith=Jo     starts with
-filter_name__endswith=hn       ends with
-filter_price__gt=100           greater than
-filter_price__gte=100          greater than or equal
-filter_price__lt=50            less than
-filter_price__lte=200          less than or equal
-filter_price__range=10,200     range (inclusive)
-filter_id__in=1,2,3            in list
-filter_is_active=1             boolean (1/true/yes, 0/false/no)
-filter_category=1              relation exact match
+name=value                     exact match
+name__icontains=term           case-insensitive contains
+name__startswith=Jo            starts with
+name__endswith=hn              ends with
+price__gt=100                  greater than
+price__gte=100                 greater than or equal
+price__lt=50                   less than
+price__lte=200                 less than or equal
+price__range=10,200            range (inclusive)
+id__in=1,2,3                   in list
+is_active=1                    boolean (1/true/yes, 0/false/no)
+category=1                     relation exact match
 ```
 
 Examples:
 
 ```
-/admin/products/?filter_name__icontains=phone&filter_price__gte=100
-/api/products/?filter_category=2&filter_price__range=10,200
+/admin/products/?name__icontains=phone&price__gte=100
+/api/products/?category=2&price__range=10,200
 ```
 
 Multiple filters are AND'd together. Range values are comma-separated pairs;
 `in` values are comma-separated lists.
 
+On the JSON API, the list endpoint documents every configured filter as
+optional query parameters in the OpenAPI/Swagger schema — add a filter to
+`list_filter` and it (plus the lookups its field type supports) shows up in
+`/openapi.json` automatically.
+
 ## Per-Filter UI Options
 
 Customize individual filter UI:
diff --git a/docs/guide/json-api.md b/docs/guide/json-api.md
index 7ac44d0..bf87d1a 100644
--- a/docs/guide/json-api.md
+++ b/docs/guide/json-api.md
@@ -168,6 +168,20 @@ Auto-generated JSON schemas are available for each model:
 curl http://localhost:8000/admin/api/schema/products/
 ```
 
+### Enum fields render as dropdowns
+
+`Enum` columns map to real enum types in the create/update schemas, so
+Swagger shows them as dropdowns (both Python-enum classes and plain
+`Enum("a", "b")` columns).
+
+### File/image fields use multipart forms
+
+When a model has file/image upload fields (`LargeBinary` columns or
+`formfield_overrides` with `FileUploadWidget`/`ImageUploadWidget`), the
+create/update endpoints accept `multipart/form-data` instead of JSON so files
+can be picked directly in Swagger. Uploads go through the same storage
+backend as the admin HTML form.
+
 ## Next Steps
 
 - [Authentication & RBAC](auth-rbac.md) — Set up permissions
diff --git a/example/example.py b/example/example.py
index fa4d468..8404122 100644
--- a/example/example.py
+++ b/example/example.py
@@ -42,8 +42,9 @@
 from fastapi_admin_kit.inline import StackedInline, TabularInline
 from fastapi_admin_kit.models import Base as AdminBase
 from fastapi_admin_kit.pagination.cursor import CursorPagination
+from fastapi_admin_kit.storage.local import LocalStorageBackend
 from fastapi_admin_kit.types import TabConfig, TableSection
-from fastapi_admin_kit.widgets.inputs import ArrayWidget, WysiwygWidget
+from fastapi_admin_kit.widgets.inputs import ArrayWidget, ImageUploadWidget, WysiwygWidget
 
 # ============================================================================
 # SQLAlchemy Models
@@ -83,6 +84,7 @@ class Product(Base):
     description = Column(Text, nullable=True)
     price = Column(Float, nullable=False)
     stock = Column(Integer, default=0)
+    image = Column(String(500), nullable=True)  # uploaded product photo (path)
     category_id = Column(Integer, ForeignKey("categories.id"), nullable=True)
     is_active = Column(Boolean, default=True)
     sort_order = Column(Integer, default=0)
@@ -290,7 +292,7 @@ class CategoryAdmin(ModelAdmin):
         TabConfig(title="All", url="/admin/categories/"),
         TabConfig(
             title="Active",
-            url="/admin/categories/?filter_created_at__gte=2025-01-01",
+            url="/admin/categories/?created_at__gte=2025-01-01",
         ),
     ]
 
@@ -327,6 +329,7 @@ class ProductAdmin(ModelAdmin):
         "category",
         "price",
         "stock",
+        "image",
         "is_active",
     ]
     readonly_fields = ["created_at", "updated_at"]
@@ -349,8 +352,8 @@ class ProductAdmin(ModelAdmin):
     # Tabs
     list_tabs = [
         TabConfig(title="All Products", url="/admin/products/"),
-        TabConfig(title="Active", url="/admin/products/?filter_is_active=1"),
-        TabConfig(title="Out of Stock", url="/admin/products/?filter_stock__lte=0"),
+        TabConfig(title="Active", url="/admin/products/?is_active=1"),
+        TabConfig(title="Out of Stock", url="/admin/products/?stock__lte=0"),
     ]
 
     # Sortable
@@ -380,6 +383,7 @@ def status(self, obj):
     formfield_overrides = {
         "description": WysiwygWidget(),
         # "tags": ArrayWidget(),
+        "image": ImageUploadWidget(max_size_mb=5),  # product photo upload
     }
 
     @action(
@@ -440,7 +444,7 @@ class UserAdmin(ModelAdmin):
     # Tabs
     list_tabs = [
         TabConfig(title="All Users", url="/admin/users/"),
-        TabConfig(title="Active", url="/admin/users/?filter_is_active=1"),
+        TabConfig(title="Active", url="/admin/users/?is_active=1"),
     ]
 
     # Form UX
@@ -496,8 +500,8 @@ class OrderAdmin(ModelAdmin):
     # Tabs
     list_tabs = [
         TabConfig(title="All Orders", url="/admin/orders/"),
-        TabConfig(title="Pending", url="/admin/orders/?filter_status=pending"),
-        TabConfig(title="Completed", url="/admin/orders/?filter_status=completed"),
+        TabConfig(title="Pending", url="/admin/orders/?status=pending"),
+        TabConfig(title="Completed", url="/admin/orders/?status=completed"),
     ]
 
     # Expandable sections
@@ -814,6 +818,9 @@ async def lifespan(app: FastAPI):
     per_page_default=25,
     secret_key=SECRET_KEY,
     auth_backend=BuiltinAuthBackend(),
+    # File/image uploads (used by the Product image field + the JSON API
+    # multipart endpoints); served from /uploads by admin.setup().
+    storage=LocalStorageBackend(upload_dir=str(EXAMPLE_DIR / "uploads")),
     sidebar_bottom_links=[
         {"label": "Settings", "url": "/admin/users/", "icon": "cog-6-tooth"},
         {"label": "Help", "url": "https://docs.example.com"},
diff --git a/fastapi_admin_kit/api/crud.py b/fastapi_admin_kit/api/crud.py
index 9722778..79c8916 100644
--- a/fastapi_admin_kit/api/crud.py
+++ b/fastapi_admin_kit/api/crud.py
@@ -7,12 +7,26 @@
 
 from typing import Annotated, Any
 
-from fastapi import APIRouter, Body, Depends, HTTPException, Request
+from fastapi import (
+    APIRouter,
+    Body,
+    Depends,
+    File,
+    Form,
+    HTTPException,
+    Query,
+    Request,
+    UploadFile,
+)
 from fastapi.responses import Response
 from pydantic import BaseModel
 
 from fastapi_admin_kit.api.deps import require_api_permission
-from fastapi_admin_kit.api.schema_generator import get_or_build_schemas
+from fastapi_admin_kit.api.schema_generator import (
+    _file_field_names,
+    get_or_build_schemas,
+    has_file_fields,
+)
 from fastapi_admin_kit.views.class_views import (
     CreateView,
     DeleteView,
@@ -149,6 +163,144 @@ async def wrapped(request: Request, item_id: Any) -> Any:
     return wrapped
 
 
+def _wrap_multipart_handler(
+    handler: Any,
+    payload_schema: type[BaseModel],
+    registered: Any,
+    *,
+    include_item_id: bool = False,
+) -> Any:
+    """Multipart variant of :func:`_wrap_body_handler` for file/image models.
+
+    Declares one ``File()`` param per file column and a ``Form()`` param for
+    every other write-schema field, so Swagger switches to a multipart form
+    with file pickers. Non-file values arrive as raw strings (exactly like the
+    HTML form) and are coerced by ``JSONBodyParser``'s widget pipeline;
+    ``None`` values are dropped to keep partial-update semantics.
+    """
+    from inspect import Parameter, Signature
+
+    file_names = _file_field_names(registered)
+
+    params = [
+        Parameter("request", Parameter.POSITIONAL_OR_KEYWORD, annotation=Request),
+    ]
+    if include_item_id:
+        params.append(Parameter("item_id", Parameter.POSITIONAL_OR_KEYWORD, annotation=Any))
+    for name in payload_schema.model_fields:
+        if name in file_names:
+            param_type = Annotated[UploadFile | None, File()]
+        else:
+            param_type = Annotated[str | None, Form()]
+        # All params optional here — required fields are enforced by the
+        # shared widget/validator pipeline, exactly like the HTML form.
+        params.append(
+            Parameter(name, Parameter.KEYWORD_ONLY, default=None, annotation=param_type)
+        )
+
+    if include_item_id:
+
+        async def wrapped(request: Request, **kwargs: Any) -> Any:
+            item_id = kwargs.pop("item_id", None)
+            request.state._api_payload = {
+                k: v for k, v in kwargs.items() if v is not None
+            }
+            return await handler(request, item_id=item_id)
+
+    else:
+
+        async def wrapped(request: Request, **kwargs: Any) -> Any:
+            request.state._api_payload = {
+                k: v for k, v in kwargs.items() if v is not None
+            }
+            return await handler(request)
+
+    wrapped.__signature__ = Signature(params)
+    wrapped.__name__ = getattr(handler, "__name__", "api_response")
+    wrapped.__doc__ = getattr(handler, "__doc__", None)
+    return wrapped
+
+
+# Lookups each filter field_type supports — mirrors the apply() methods in
+# filters/base.py. Exact uses the bare ``filter_<field>`` param.
+LOOKUPS_BY_TYPE: dict[str, tuple[str, ...]] = {
+    "text": ("exact", "icontains", "startswith", "endswith"),
+    "boolean": ("exact",),
+    "enum": ("exact", "in"),
+    "relation": ("exact",),
+    "integer": ("exact", "gt", "gte", "lt", "lte", "range", "in"),
+    "numeric": ("exact", "gt", "gte", "lt", "lte", "range", "in"),
+    "date": ("exact", "gt", "gte", "lt", "lte", "range", "in", "from", "to"),
+    "datetime": ("exact", "gt", "gte", "lt", "lte", "range", "in", "from", "to"),
+    "time": ("exact", "gt", "gte", "lt", "lte", "range", "in"),
+}
+
+
+def _lookups_for_field_type(field_type: str) -> tuple[str, ...]:
+    """Return the lookup names a filter field_type supports (from base.apply())."""
+    return LOOKUPS_BY_TYPE.get(field_type, ("exact",))
+
+
+def _wrap_list_handler(handler: Any, registered: Any) -> Any:
+    """Document configured list filters as query params in the OpenAPI schema.
+
+    Filtering already works — the query provider reads ``filter_*`` from
+    ``request.query_params``. This wrapper only declares those params so
+    Swagger lists them: it mirrors the handler's own signature (pagination
+    stays documented) and appends one optional string param per filter field
+    for each lookup its type supports. Only the handler's original params are
+    forwarded; the ``filter_*`` values reach the provider through the raw
+    query string.
+    """
+    import inspect
+    from inspect import Parameter, Signature
+
+    from fastapi_admin_kit.filters import Filter, FilterRegistry, SimpleFilter
+    from fastapi_admin_kit.filters.lookups import LOOKUP_SUFFIXES
+
+    suffix = dict(LOOKUP_SUFFIXES)
+    try:
+        auto = FilterRegistry().auto_generate(registered.model, registered.columns)
+    except Exception:
+        auto = {}
+
+    filter_fields: list[tuple[str, str]] = []  # (field_name, field_type)
+    for item in registered.admin.list_filter or []:
+        if isinstance(item, str):
+            f = auto.get(item)
+            filter_fields.append((item, getattr(f, "field_type", "text") if f else "text"))
+        elif isinstance(item, Filter):
+            filter_fields.append((item.field_name, item.field_type))
+        elif isinstance(item, type) and issubclass(item, SimpleFilter):
+            f = item()
+            filter_fields.append((f.field_name, f.field_type))
+        else:
+            continue
+
+    sig = inspect.signature(handler)
+    params = list(sig.parameters.values())
+    for name, field_type in filter_fields:
+        for lookup in _lookups_for_field_type(field_type):
+            qname = f"{name}{suffix[lookup]}"
+            params.append(
+                Parameter(
+                    qname,
+                    Parameter.KEYWORD_ONLY,
+                    default=Query(None, description=f"Filter on '{name}' ({lookup})"),
+                )
+            )
+
+    handler_params = {p.name for p in sig.parameters.values() if p.name != "request"}
+
+    async def wrapped(request: Request, **kwargs: Any) -> Any:
+        return await handler(request, **{k: v for k, v in kwargs.items() if k in handler_params})
+
+    wrapped.__signature__ = Signature(params)
+    wrapped.__name__ = getattr(handler, "__name__", "api_response")
+    wrapped.__doc__ = getattr(handler, "__doc__", None)
+    return wrapped
+
+
 def _register_model_routes(router: APIRouter, registered: Any) -> None:
     """Register CRUD routes for a single model using view classes."""
     table_name = registered.table_name
@@ -167,10 +319,25 @@ def _register_model_routes(router: APIRouter, registered: Any) -> None:
     create_schema = schemas["create"]
     update_schema = schemas["update"]
 
+    list_handler = list_v.api_response if hasattr(list_v, "api_response") else list_v
+
+    # Models with file/image columns use multipart form bodies (file pickers
+    # in Swagger); everything else keeps the JSON body.
+    use_multipart = has_file_fields(registered)
+
+    def _body_wrapper(
+        handler: Any, payload_schema: type[BaseModel], *, include_item_id: bool = False
+    ) -> Any:
+        if use_multipart:
+            return _wrap_multipart_handler(
+                handler, payload_schema, registered, include_item_id=include_item_id
+            )
+        return _wrap_body_handler(handler, payload_schema, include_item_id=include_item_id)
+
     # Add routes with both "api-crud" and model verbose_name tags
     router.add_api_route(
         "",
-        list_v.api_response if hasattr(list_v, "api_response") else list_v,
+        _wrap_list_handler(list_handler, registered),
         methods=["GET"],
         response_model=list_response_schema,
         tags=["api-crud", registered.verbose_name],
@@ -178,7 +345,7 @@ def _register_model_routes(router: APIRouter, registered: Any) -> None:
     )
     router.add_api_route(
         "",
-        _wrap_body_handler(create_v.api_response, create_schema),
+        _body_wrapper(create_v.api_response, create_schema),
         methods=["POST"],
         response_model=response_schema,
         status_code=201,
@@ -195,7 +362,7 @@ def _register_model_routes(router: APIRouter, registered: Any) -> None:
     )
     router.add_api_route(
         "/{item_id}",
-        _wrap_body_handler(edit_v.api_response, update_schema, include_item_id=True),
+        _body_wrapper(edit_v.api_response, update_schema, include_item_id=True),
         methods=["PUT"],
         response_model=response_schema,
         tags=["api-crud", registered.verbose_name],
@@ -203,7 +370,7 @@ def _register_model_routes(router: APIRouter, registered: Any) -> None:
     )
     router.add_api_route(
         "/{item_id}",
-        _wrap_body_handler(edit_v.api_response, update_schema, include_item_id=True),
+        _body_wrapper(edit_v.api_response, update_schema, include_item_id=True),
         methods=["PATCH"],
         response_model=response_schema,
         tags=["api-crud", registered.verbose_name],
diff --git a/fastapi_admin_kit/api/schema_generator.py b/fastapi_admin_kit/api/schema_generator.py
index 19c7e45..63aecd2 100644
--- a/fastapi_admin_kit/api/schema_generator.py
+++ b/fastapi_admin_kit/api/schema_generator.py
@@ -14,7 +14,6 @@ def _sa_type_to_python(sa_type: Any) -> type:
         Boolean,
         Date,
         DateTime,
-        Enum,
         Float,
         Integer,
         LargeBinary,
@@ -42,15 +41,40 @@ def _sa_type_to_python(sa_type: Any) -> type:
         return datetime.time
     if type_cls in (LargeBinary,):
         return bytes
-    if type_cls is Enum:
-        return str
     return Any
 
 
+def _enum_python_type(sa_type: Any, field_name: str) -> type:
+    """Return the Python type for a SQLAlchemy ``Enum`` column.
+
+    Uses the underlying Python enum class when the column declares one;
+    otherwise builds a dynamic ``Enum`` with one member per stored value so
+    Swagger renders the field as a dropdown either way. Falls back to ``str``
+    when no value list is known.
+    """
+    import enum
+
+    enum_class = getattr(sa_type, "enum_class", None)
+    if isinstance(enum_class, type) and issubclass(enum_class, enum.Enum):
+        return enum_class
+    values = list(getattr(sa_type, "enums", None) or [])
+    if values:
+        # ponytail: member names are generated (values may not be valid
+        # identifiers); two models sharing a field_name with different values
+        # would share one OpenAPI component — scope by model if it ever bites.
+        members = {f"MEMBER_{i}": v for i, v in enumerate(values)}
+        return enum.Enum(f"{field_name}Enum", members)
+    return str
+
+
 def _get_column_python_type(col: Any) -> type:
-    """Get the Python type for a column, handling ForeignKey."""
+    """Get the Python type for a column, handling ForeignKey and Enum."""
     if col.foreign_keys:
         return int
+    from sqlalchemy import Enum
+
+    if isinstance(col.type, Enum):
+        return _enum_python_type(col.type, col.name)
     return _sa_type_to_python(col.type)
 
 
@@ -216,6 +240,38 @@ def build_list_response_schema(registered: Any) -> type[BaseModel]:
     )
 
 
+def _file_field_names(registered: Any) -> set[str]:
+    """Names of file/image upload fields, honoring fields/exclude config.
+
+    Detection is widget-based (same rule as the HTML form's ``has_file_field``):
+    a field is a file field when its widget is a file-upload widget, whether
+    by column type (``LargeBinary``) or a ``formfield_overrides`` entry on a
+    string column (the usual path-storage pattern).
+    """
+    from fastapi_admin_kit.views.file_handler import FILE_WIDGET_TYPES
+
+    names: set[str] = set()
+    admin = registered.admin
+    for col in registered.columns:
+        if col.name == "id":
+            continue
+        if admin.fields is not None and col.name not in admin.fields:
+            continue
+        if admin.exclude and col.name in admin.exclude:
+            continue
+        try:
+            if isinstance(registered.get_widget(col.name), FILE_WIDGET_TYPES):
+                names.add(col.name)
+        except Exception:
+            continue
+    return names
+
+
+def has_file_fields(registered: Any) -> bool:
+    """True when the model's write schemas include file/image upload columns."""
+    return bool(_file_field_names(registered))
+
+
 def get_or_build_schemas(registered: Any) -> dict[str, type[BaseModel]]:
     """Get or generate and cache schemas for a registered model."""
     if hasattr(registered, "_schemas") and registered._schemas is not None:
diff --git a/fastapi_admin_kit/filters/lookups.py b/fastapi_admin_kit/filters/lookups.py
index b418555..d04699a 100644
--- a/fastapi_admin_kit/filters/lookups.py
+++ b/fastapi_admin_kit/filters/lookups.py
@@ -1,18 +1,18 @@
 """Django-style lookup parsing for filter query parameters.
 
-The admin accepts filters as ``filter_<field>`` query parameters with the
-same conventions as ``django-filter``::
+The admin accepts filters as ``<field>`` query parameters with the same
+conventions as ``django-filter``::
 
-    ?filter_name=value                     exact match
-    ?filter_name__icontains=term           case-insensitive contains
-    ?filter_name__startswith=Jo            starts with
-    ?filter_name__endswith=hn              ends with
-    ?filter_price__gt=100                  greater than
-    ?filter_price__gte=100                 greater than or equal
-    ?filter_price__lt=50                   less than
-    ?filter_price__lte=200                 less than or equal
-    ?filter_price__range=10,200            range (inclusive)
-    ?filter_id__in=1,2,3                   in list
+    ?name=value                     exact match
+    ?name__icontains=term           case-insensitive contains
+    ?name__startswith=Jo            starts with
+    ?name__endswith=hn              ends with
+    ?price__gt=100                  greater than
+    ?price__gte=100                 greater than or equal
+    ?price__lt=50                   less than
+    ?price__lte=200                 less than or equal
+    ?price__range=10,200            range (inclusive)
+    ?id__in=1,2,3                   in list
 
 This module owns the (query params -> value) mapping so the HTML list views
 and the JSON API share one source of truth.
@@ -65,7 +65,7 @@ def parse_filter_params(
     parts: dict[str, str] = {}
     active: dict[str, str] = {}
     for lookup, suffix in LOOKUP_SUFFIXES:
-        raw = query_params.get(f"filter_{field_name}{suffix}", "")
+        raw = query_params.get(f"{field_name}{suffix}", "")
         if raw:
             parts[lookup] = raw
             active[f"{field_name}{suffix}"] = raw
diff --git a/fastapi_admin_kit/templates/admin/base_list.html b/fastapi_admin_kit/templates/admin/base_list.html
index 90f71fb..3be798b 100644
--- a/fastapi_admin_kit/templates/admin/base_list.html
+++ b/fastapi_admin_kit/templates/admin/base_list.html
@@ -177,7 +177,7 @@ <h3 class="text-sm font-semibold text-slate-900 dark:text-white">Import Data</h3
          @click="closeDrawer()" aria-hidden="true"></div>
 
     {# Filter drawer panel #}
-    <aside x-show="drawerOpen" x-cloak
+    <aside id="filter-drawer" x-show="drawerOpen" x-cloak
            role="dialog" aria-modal="true" aria-label="Filters"
            class="fixed top-0 right-0 z-[51] flex h-full w-full flex-col bg-white shadow-xl sm:max-w-md dark:bg-slate-900 dark:ring-1 dark:ring-slate-700"
            x-transition:enter="transform transition ease-out duration-300"
@@ -213,7 +213,7 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
                       x-show='draftFilters[{{ field_name | tojson }}]' x-cloak
                       @click='draftFilters[{{ field_name | tojson }}] = ""'>Clear</button>
             </div>
-            <input id="drawer-filter-{{ field_name }}" type="date" name="filter_{{ field_name }}"
+            <input id="drawer-filter-{{ field_name }}" type="date" name="{{ field_name }}"
                    class="input w-full"
                    x-model='draftFilters[{{ field_name | tojson }}]'>
           </div>
@@ -226,7 +226,7 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
                       x-show='draftFilters[{{ field_name | tojson }}]' x-cloak
                       @click='draftFilters[{{ field_name | tojson }}] = ""'>Clear</button>
             </div>
-            <input id="drawer-filter-{{ field_name }}" type="datetime-local" name="filter_{{ field_name }}"
+            <input id="drawer-filter-{{ field_name }}" type="datetime-local" name="{{ field_name }}"
                    class="input w-full"
                    x-model='draftFilters[{{ field_name | tojson }}]'>
           </div>
@@ -239,7 +239,7 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
                       x-show='draftFilters[{{ field_name | tojson }}]' x-cloak
                       @click='draftFilters[{{ field_name | tojson }}] = ""'>Clear</button>
             </div>
-            <input id="drawer-filter-{{ field_name }}" type="time" name="filter_{{ field_name }}"
+            <input id="drawer-filter-{{ field_name }}" type="time" name="{{ field_name }}"
                    class="input w-full"
                    x-model='draftFilters[{{ field_name | tojson }}]'>
           </div>
@@ -253,7 +253,7 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
                       x-show='draftFilters[{{ _tkey | tojson }}]' x-cloak
                       @click='draftFilters[{{ _tkey | tojson }}] = ""'>Clear</button>
             </div>
-            <input id="drawer-filter-{{ field_name }}" type="text" name="filter_{{ field_name }}__icontains"
+            <input id="drawer-filter-{{ field_name }}" type="text" name="{{ field_name }}__icontains"
                    placeholder="Contains..."
                    class="input w-full"
                    x-model='draftFilters[{{ _tkey | tojson }}]'>
@@ -270,11 +270,11 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
                       @click='draftFilters[{{ _gtek | tojson }}] = ""; draftFilters[{{ _ltek | tojson }}] = ""'>Clear</button>
             </div>
             <div class="grid grid-cols-2 gap-2">
-              <input type="number" name="filter_{{ field_name }}__gte" placeholder="Min"
+              <input type="number" name="{{ field_name }}__gte" placeholder="Min"
                      aria-label="{{ field_name | replace('_', ' ') | title }} minimum"
                      class="input w-full"
                      x-model='draftFilters[{{ _gtek | tojson }}]'>
-              <input type="number" name="filter_{{ field_name }}__lte" placeholder="Max"
+              <input type="number" name="{{ field_name }}__lte" placeholder="Max"
                      aria-label="{{ field_name | replace('_', ' ') | title }} maximum"
                      class="input w-full"
                      x-model='draftFilters[{{ _ltek | tojson }}]'>
@@ -290,7 +290,7 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
                       x-show='draftFilters[{{ field_name | tojson }}]' x-cloak
                       @click='draftFilters[{{ field_name | tojson }}] = ""'>Clear</button>
             </div>
-            <select id="drawer-filter-{{ field_name }}" name="filter_{{ field_name }}"
+            <select id="drawer-filter-{{ field_name }}" name="{{ field_name }}"
                     class="input w-full"
                     x-model='draftFilters[{{ field_name | tojson }}]'>
               {% for value, label in field_info.choices %}
@@ -418,12 +418,10 @@ <h2 class="text-base font-semibold text-slate-900 dark:text-white">Filters</h2>
     },
     applyFilters() {
       const params = new URLSearchParams(window.location.search);
-      Array.from(params.keys()).forEach((k) => {
-        if (k.startsWith('filter_')) params.delete(k);
-      });
+      document.querySelectorAll('#filter-drawer [name]').forEach((el) => params.delete(el.name));
       Object.entries(this.activeFilters).forEach(([key, val]) => {
-        if (val !== '' && val !== null && val !== undefined) params.set('filter_' + key, val);
-        else params.delete('filter_' + key);
+        if (val !== '' && val !== null && val !== undefined) params.set(key, val);
+        else params.delete(key);
       });
       const search = this.$refs.searchInput?.value;
       if (search) params.set('q', search);
diff --git a/fastapi_admin_kit/templates/partials/inline_edit_form.html b/fastapi_admin_kit/templates/partials/inline_edit_form.html
index 87d1966..4f4912b 100644
--- a/fastapi_admin_kit/templates/partials/inline_edit_form.html
+++ b/fastapi_admin_kit/templates/partials/inline_edit_form.html
@@ -23,7 +23,7 @@
                   hx-get="{{ admin_path }}/{{ table_name }}/"
                   hx-target="#table-wrapper"
                   hx-swap="outerHTML"
-                  hx-include="[name='q'], [name^='filter_']">
+                  hx-include="[name='q'], #filter-drawer [name]">
             Cancel
           </button>
         </div>
diff --git a/fastapi_admin_kit/views/renderers.py b/fastapi_admin_kit/views/renderers.py
index 5e206b4..474242a 100644
--- a/fastapi_admin_kit/views/renderers.py
+++ b/fastapi_admin_kit/views/renderers.py
@@ -289,6 +289,36 @@ async def parse(
         allowed |= extra_names
         filtered = {k: v for k, v in body.items() if k in allowed}
 
+        # File/image fields: run raw UploadFile values through the same
+        # storage-backed save used by HTMLFormParser so the multipart API path
+        # replaces them with the saved path before validation. Missing file
+        # values on create default to None, mirroring the HTML submit path.
+        errors: dict[str, list[str]] = {}
+        for field_meta in self.registered.form_fields:
+            if field_meta.name not in allowed:
+                continue
+            widget = self.registered.get_widget(field_meta.name)
+            if not isinstance(widget, _FILE_WIDGET_TYPES):
+                continue
+            if field_meta.name not in filtered:
+                if obj is None:
+                    filtered[field_meta.name] = None
+                continue
+            await _handle_file_field(
+                request,
+                widget,
+                field_meta,
+                filtered,
+                obj=obj,
+                action="replace" if obj is not None else None,
+                parsed=filtered,
+                errors=errors,
+            )
+            if obj is None and field_meta.name not in errors and field_meta.name not in filtered:
+                filtered[field_meta.name] = None
+        if errors:
+            return filtered, errors
+
         # Coerce raw JSON values (ISO date strings etc.) through the same
         # widgets the HTML path uses, so widget validators see typed values.
         for name, value in list(filtered.items()):
diff --git a/fastapi_admin_kit/widgets/inputs.py b/fastapi_admin_kit/widgets/inputs.py
index 0012802..460eb8d 100644
--- a/fastapi_admin_kit/widgets/inputs.py
+++ b/fastapi_admin_kit/widgets/inputs.py
@@ -148,8 +148,12 @@ def validate(self, value: Any, field: FieldMeta) -> list[str]:
         errors = super().validate(value, field)
         if value and self.choices:
             valid = {c[0] for c in self.choices}
-            check = self._coerce_enum(value)
-            if check not in valid:
+            candidates = {self._coerce_enum(value)}
+            if isinstance(value, enum.Enum):
+                # Choices carry member names while str-enums store values —
+                # accept either so both spellings validate.
+                candidates.add(value.name)
+            if candidates.isdisjoint(valid):
                 errors.append(f"'{value}' is not a valid choice for {field.label}.")
         return errors
 
diff --git a/tests/test_filters.py b/tests/test_filters.py
index 60a4674..16aa8f2 100644
--- a/tests/test_filters.py
+++ b/tests/test_filters.py
@@ -44,14 +44,14 @@ class TestParseFilterParams:
     def test_exact_match(self):
         from fastapi_admin_kit.filters.lookups import parse_filter_params
 
-        value, active = parse_filter_params({"filter_name": "widget"}, "name")
+        value, active = parse_filter_params({"name": "widget"}, "name")
         assert value == "widget"
         assert active == {"name": "widget"}
 
     def test_icontains(self):
         from fastapi_admin_kit.filters.lookups import parse_filter_params
 
-        value, active = parse_filter_params({"filter_name__icontains": "wid"}, "name")
+        value, active = parse_filter_params({"name__icontains": "wid"}, "name")
         assert value == {"icontains": "wid"}
         assert active == {"name__icontains": "wid"}
 
@@ -59,7 +59,7 @@ def test_startswith_and_endswith(self):
         from fastapi_admin_kit.filters.lookups import parse_filter_params
 
         value, _ = parse_filter_params(
-            {"filter_name__startswith": "Jo", "filter_name__endswith": "hn"}, "name"
+            {"name__startswith": "Jo", "name__endswith": "hn"}, "name"
         )
         assert value == {"startswith": "Jo", "endswith": "hn"}
 
@@ -68,10 +68,10 @@ def test_numeric_lookups(self):
 
         value, active = parse_filter_params(
             {
-                "filter_price__gt": "100",
-                "filter_price__gte": "10",
-                "filter_price__lt": "50",
-                "filter_price__lte": "200",
+                "price__gt": "100",
+                "price__gte": "10",
+                "price__lt": "50",
+                "price__lte": "200",
             },
             "price",
         )
@@ -83,11 +83,11 @@ def test_range_and_in(self):
         from fastapi_admin_kit.filters.lookups import parse_filter_params
 
         value, _ = parse_filter_params(
-            {"filter_price__range": "10,200", "filter_id__in": "1,2,3"}, "price"
+            {"price__range": "10,200", "id__in": "1,2,3"}, "price"
         )
         assert value == {"range": "10,200"}
 
-        value, _ = parse_filter_params({"filter_id__in": "1,2,3"}, "id")
+        value, _ = parse_filter_params({"id__in": "1,2,3"}, "id")
         assert value == {"in": "1,2,3"}
 
     def test_no_params(self):
@@ -525,9 +525,9 @@ class TestApiSimpleFilter:
     def test_bare_class_filters_via_api(self):
         client, headers, cleanup = _make_client([InStockFilter])
         try:
-            body = client.get("/api/products/?filter_is_active=1", headers=headers).json()
+            body = client.get("/api/products/?is_active=1", headers=headers).json()
             assert _names(body) == {"Widget", "Widglet", "Textbook"}
-            body = client.get("/api/products/?filter_is_active=0", headers=headers).json()
+            body = client.get("/api/products/?is_active=0", headers=headers).json()
             assert _names(body) == {"Novel"}
         finally:
             cleanup()
@@ -536,69 +536,69 @@ def test_bare_class_filters_via_api(self):
 class TestApiFilters:
     def test_exact_match(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_name=Widget", headers=headers).json()
+        body = client.get("/api/products/?name=Widget", headers=headers).json()
         assert _names(body) == {"Widget"}
 
     def test_icontains(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_name__icontains=wid", headers=headers).json()
+        body = client.get("/api/products/?name__icontains=wid", headers=headers).json()
         assert _names(body) == {"Widget", "Widglet"}
 
     def test_startswith(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_name__startswith=Text", headers=headers).json()
+        body = client.get("/api/products/?name__startswith=Text", headers=headers).json()
         assert _names(body) == {"Textbook"}
 
     def test_endswith(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_name__endswith=glet", headers=headers).json()
+        body = client.get("/api/products/?name__endswith=glet", headers=headers).json()
         assert _names(body) == {"Widglet"}
 
     def test_numeric_gt(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_price__gt=10", headers=headers).json()
+        body = client.get("/api/products/?price__gt=10", headers=headers).json()
         assert _names(body) == {"Widglet", "Textbook"}
 
     def test_numeric_gte(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_price__gte=10", headers=headers).json()
+        body = client.get("/api/products/?price__gte=10", headers=headers).json()
         assert _names(body) == {"Widget", "Widglet", "Textbook"}
 
     def test_numeric_lt(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_price__lt=10", headers=headers).json()
+        body = client.get("/api/products/?price__lt=10", headers=headers).json()
         assert _names(body) == {"Novel"}
 
     def test_numeric_lte(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_price__lte=10", headers=headers).json()
+        body = client.get("/api/products/?price__lte=10", headers=headers).json()
         assert _names(body) == {"Widget", "Novel"}
 
     def test_numeric_range(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_price__range=5,25", headers=headers).json()
+        body = client.get("/api/products/?price__range=5,25", headers=headers).json()
         assert _names(body) == {"Widget", "Widglet", "Novel"}
 
     def test_in_list(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_price__in=5,40", headers=headers).json()
+        body = client.get("/api/products/?price__in=5,40", headers=headers).json()
         assert _names(body) == {"Novel", "Textbook"}
 
     def test_boolean_filter(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_is_active=1", headers=headers).json()
+        body = client.get("/api/products/?is_active=1", headers=headers).json()
         assert _names(body) == {"Widget", "Widglet", "Textbook"}
 
     def test_relation_choice_filter(self, api):
         client, headers = api
-        body = client.get("/api/products/?filter_category=1", headers=headers).json()
+        body = client.get("/api/products/?category=1", headers=headers).json()
         # Category id 1 == Gadgets
         assert _names(body) == {"Widget", "Widglet"}
 
     def test_combined_filters(self, api):
         client, headers = api
         body = client.get(
-            "/api/products/?filter_name__icontains=wid&filter_price__gte=10", headers=headers
+            "/api/products/?name__icontains=wid&price__gte=10", headers=headers
         ).json()
         assert _names(body) == {"Widget", "Widglet"}
 
@@ -609,26 +609,50 @@ def _titles(self, body):
 
     def test_m2m_exact(self, api_m2m):
         client, headers = api_m2m
-        body = client.get("/api/articles/?filter_tags=1", headers=headers).json()
+        body = client.get("/api/articles/?tags=1", headers=headers).json()
         assert self._titles(body) == {"Flask guide", "Reflex blog"}
 
     def test_m2m_other_tag(self, api_m2m):
         client, headers = api_m2m
-        body = client.get("/api/articles/?filter_tags=2", headers=headers).json()
+        body = client.get("/api/articles/?tags=2", headers=headers).json()
         assert self._titles(body) == {"Reflex blog", "Figma tricks"}
 
     def test_m2m_in(self, api_m2m):
         client, headers = api_m2m
-        body = client.get("/api/articles/?filter_tags__in=1", headers=headers).json()
+        body = client.get("/api/articles/?tags__in=1", headers=headers).json()
         assert self._titles(body) == {"Flask guide", "Reflex blog"}
 
 
+class TestOpenApiFilterParams:
+    def test_lookups_follow_field_type(self, api):
+        client, _headers = api
+        op = client.get("/openapi.json").json()["paths"]["/api/products"]["get"]
+        names = {p["name"] for p in op.get("parameters", [])}
+        assert "name" in names
+        assert "name__icontains" in names
+        assert "name__startswith" in names
+        assert "name__gt" not in names
+        assert "price__gt" in names
+        assert "price__gte" in names
+        assert "price__icontains" not in names
+        assert "is_active" in names
+        assert "is_active__gte" not in names
+        assert "category" in names
+        assert "category__in" not in names
+
+    def test_pagination_params_still_documented(self, api):
+        client, _headers = api
+        op = client.get("/openapi.json").json()["paths"]["/api/products"]["get"]
+        names = {p["name"] for p in op.get("parameters", [])}
+        assert {"page", "per_page", "q", "order"} <= names
+
+
 class TestAdminUiListFilters:
     def test_icontains_in_list_view(self, api):
         client, _headers = api
         cookie = create_session_cookie(1)
         resp = client.get(
-            "/admin/products/?filter_name__icontains=wid",
+            "/admin/products/?name__icontains=wid",
             cookies={"admin_session": cookie},
         )
         assert resp.status_code == 200
@@ -640,7 +664,7 @@ def test_numeric_range_in_list_view(self, api):
         client, _headers = api
         cookie = create_session_cookie(1)
         resp = client.get(
-            "/admin/products/?filter_price__range=5,10",
+            "/admin/products/?price__range=5,10",
             cookies={"admin_session": cookie},
         )
         assert resp.status_code == 200

From dcc44d5b4bb44fc39370ce8275c795fb683e7ff4 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Sat, 12 Sep 2026 15:28:39 +0600
Subject: [PATCH 08/12] test file

---
 tests/test_api_enum_file.py | 277 ++++++++++++++++++++++++++++++++++++
 1 file changed, 277 insertions(+)
 create mode 100644 tests/test_api_enum_file.py

diff --git a/tests/test_api_enum_file.py b/tests/test_api_enum_file.py
new file mode 100644
index 0000000..4bed0a3
--- /dev/null
+++ b/tests/test_api_enum_file.py
@@ -0,0 +1,277 @@
+"""API schema forms: enum dropdowns and multipart file upload in Swagger.
+
+- Enum columns map to real ``Enum`` types in the create/update schemas, so
+  Swagger renders them as dropdowns (both Python-enum and plain string enums).
+- Models with file/image fields expose POST/PUT/PATCH as multipart forms so
+  files can be picked in Swagger; uploads run through the same storage-backed
+  save used by the HTML form.
+"""
+
+from __future__ import annotations
+
+import base64
+import enum
+import os
+import tempfile
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy import Column, Enum, Integer, LargeBinary, String, create_engine
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.pool import StaticPool
+
+from fastapi_admin_kit import Admin
+from fastapi_admin_kit.auth.backend import BuiltinAuthBackend
+from fastapi_admin_kit.migrations.models import Role, User
+from fastapi_admin_kit.modeladmin import ModelAdmin
+from fastapi_admin_kit.models.base import Base as AdminBase
+from fastapi_admin_kit.widgets.inputs import ImageUploadWidget
+from tests.conftest import SECRET_KEY, run_async
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class TicketStatus(enum.StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+class Ticket(Base):
+    __tablename__ = "tickets"
+    id = Column(Integer, primary_key=True)
+    title = Column(String(200), nullable=False)
+    status = Column(Enum(TicketStatus), nullable=True)
+
+
+class Survey(Base):
+    __tablename__ = "surveys"
+    id = Column(Integer, primary_key=True)
+    title = Column(String(200), nullable=False)
+    mood = Column(Enum("happy", "sad", name="survey_mood"), nullable=True)
+
+
+class Photo(Base):
+    __tablename__ = "photos"
+    id = Column(Integer, primary_key=True)
+    title = Column(String(200), nullable=False)
+    image_url = Column(String(500), nullable=True)
+    raw = Column(LargeBinary, nullable=True)
+
+
+@pytest.fixture(autouse=True)
+def _clear_registry():
+    from fastapi_admin_kit.registry import AdminRegistry
+
+    AdminRegistry().clear()
+    yield
+    AdminRegistry().clear()
+
+
+def _make_client(tmp_path):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    sync_engine = create_engine(f"sqlite:///{path}", connect_args={"check_same_thread": False})
+    AdminBase.metadata.create_all(sync_engine)
+    Base.metadata.create_all(sync_engine)
+    sync_engine.dispose()
+    async_engine = create_async_engine(
+        f"sqlite+aiosqlite:///{path}",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+
+    async def _seed():
+        async with AsyncSession(async_engine) as session:
+            role = Role(name="SuperAdmin")
+            session.add(role)
+            await session.flush()
+            user = User(
+                email="test@example.com",
+                password="$2b$12$DOXzSwSZYp0Y1pTzEvWjO.KOLQg3wA/Ez1RkN4RHMiLqngoLM2lMG",
+                full_name="Test User",
+                is_superuser=True,
+                is_active=True,
+            )
+            user.roles.append(role)
+            session.add(user)
+            await session.commit()
+
+    run_async(_seed())
+
+    from fastapi_admin_kit.storage.local import LocalStorageBackend
+
+    class PhotoAdmin(ModelAdmin):
+        formfield_overrides = {"image_url": ImageUploadWidget()}
+
+    admin = Admin(
+        engine=async_engine,
+        auth_model=User,
+        auth_backend=BuiltinAuthBackend(),
+        secret_key=SECRET_KEY,
+        auto_discover=False,
+        session_secure=False,
+        storage=LocalStorageBackend(upload_dir=str(tmp_path / "uploads")),
+    )
+    admin.register(Ticket, ModelAdmin)
+    admin.register(Survey, ModelAdmin)
+    admin.register(Photo, PhotoAdmin)
+    app = FastAPI()
+    run_async(admin.setup(app))
+    client = TestClient(app)
+    creds = base64.b64encode(b"test@example.com:secret").decode()
+    token = client.post("/api/auth/token", headers={"Authorization": f"Basic {creds}"}).json()[
+        "access_token"
+    ]
+    headers = {"Authorization": f"Bearer {token}"}
+
+    def cleanup():
+        run_async(async_engine.dispose())
+        os.unlink(path)
+
+    return client, headers, cleanup
+
+
+@pytest.fixture
+def client_env(tmp_path):
+    client, headers, cleanup = _make_client(tmp_path)
+    yield client, headers
+    cleanup()
+
+
+def _resolve_ref(openapi, ref):
+    node = openapi
+    for part in ref.lstrip("#/").split("/"):
+        node = node[part]
+    return node
+
+
+def _deref(openapi, schema):
+    """Follow $ref (incl. nullable anyOf wrappers) to the concrete schema."""
+    while True:
+        if "$ref" in schema:
+            schema = _resolve_ref(openapi, schema["$ref"])
+        elif "anyOf" in schema:
+            non_null = [s for s in schema["anyOf"] if s.get("type") != "null"]
+            if len(non_null) != 1:
+                return schema
+            schema = non_null[0]
+        else:
+            return schema
+
+
+def _is_file_picker(prop):
+    """True when the OpenAPI property renders as a Swagger file picker."""
+    variants = prop.get("anyOf", [prop])
+    return any(
+        v.get("format") == "binary" or v.get("contentMediaType") == "application/octet-stream"
+        for v in variants
+    )
+
+
+def _post_body_props(openapi, path):
+    op = openapi["paths"][path]["post"]
+    ctype, media = next(iter(op["requestBody"]["content"].items()))
+    schema = media["schema"]
+    if "$ref" in schema:
+        schema = _resolve_ref(openapi, schema["$ref"])
+    return ctype, schema.get("properties", {})
+
+
+# ===========================================================================
+# Enum dropdowns
+# ===========================================================================
+
+
+class TestApiEnumDropdown:
+    def test_python_enum_schema_is_real_enum(self, client_env):
+        client, _ = client_env
+        openapi = client.get("/openapi.json").json()
+        ctype, props = _post_body_props(openapi, "/api/tickets")
+        assert ctype == "application/json"
+        status_schema = _deref(openapi, props["status"])
+        assert set(status_schema["enum"]) == {"open", "closed"}
+
+    def test_plain_string_enum_gets_dropdown(self, client_env):
+        client, _ = client_env
+        openapi = client.get("/openapi.json").json()
+        ctype, props = _post_body_props(openapi, "/api/surveys")
+        assert ctype == "application/json"
+        mood_schema = _deref(openapi, props["mood"])
+        assert set(mood_schema["enum"]) == {"happy", "sad"}
+
+    def test_create_with_enum_value(self, client_env):
+        client, headers = client_env
+        resp = client.post(
+            "/api/tickets", headers=headers, json={"title": "T1", "status": "open"}
+        )
+        assert resp.status_code == 201
+        assert resp.json()["status"] == "open"
+
+    def test_create_rejects_unknown_enum_value(self, client_env):
+        client, headers = client_env
+        resp = client.post(
+            "/api/tickets", headers=headers, json={"title": "T1", "status": "bogus"}
+        )
+        assert resp.status_code == 422
+
+
+# ===========================================================================
+# Multipart file/image upload
+# ===========================================================================
+
+
+class TestApiMultipartUpload:
+    def test_file_model_uses_multipart_with_file_picker(self, client_env):
+        client, _ = client_env
+        openapi = client.get("/openapi.json").json()
+        ctype, props = _post_body_props(openapi, "/api/photos")
+        assert ctype == "multipart/form-data"
+        assert _is_file_picker(props["image_url"])
+        assert _is_file_picker(props["raw"])
+        assert "string" in str(props["title"])
+
+    def test_non_file_model_keeps_json_body(self, client_env):
+        client, _ = client_env
+        openapi = client.get("/openapi.json").json()
+        ctype, _ = _post_body_props(openapi, "/api/tickets")
+        assert ctype == "application/json"
+
+    def test_multipart_create_uploads_file(self, client_env):
+        client, headers = client_env
+        resp = client.post(
+            "/api/photos",
+            headers=headers,
+            data={"title": "Sunset"},
+            files={"image_url": ("sunset.png", b"PNGDATA", "image/png")},
+        )
+        assert resp.status_code == 201, resp.text
+        photo_id = resp.json()["id"]
+        body = client.get(f"/api/photos/{photo_id}", headers=headers).json()
+        assert body["title"] == "Sunset"
+        assert body["image_url"]  # saved path, not empty
+
+    def test_multipart_patch_without_file_keeps_existing(self, client_env):
+        client, headers = client_env
+        created = client.post(
+            "/api/photos",
+            headers=headers,
+            data={"title": "Before"},
+            files={"image_url": ("a.png", b"PNGDATA", "image/png")},
+        )
+        assert created.status_code == 201, created.text
+        photo_id = created.json()["id"]
+        before = client.get(f"/api/photos/{photo_id}", headers=headers).json()["image_url"]
+
+        patched = client.patch(
+            f"/api/photos/{photo_id}",
+            headers=headers,
+            data={"title": "After"},
+        )
+        assert patched.status_code == 200, patched.text
+        after = client.get(f"/api/photos/{photo_id}", headers=headers).json()
+        assert after["title"] == "After"
+        assert after["image_url"] == before

From b8ce30a70f6750a611a1062fe7d635f63b4f0ce1 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Sat, 12 Sep 2026 16:38:11 +0600
Subject: [PATCH 09/12] seperate endpoint by tag name in swagger

---
 fastapi_admin_kit/api/crud.py | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/fastapi_admin_kit/api/crud.py b/fastapi_admin_kit/api/crud.py
index 79c8916..96f0cd5 100644
--- a/fastapi_admin_kit/api/crud.py
+++ b/fastapi_admin_kit/api/crud.py
@@ -66,7 +66,7 @@ def _export_endpoint(registered: Any) -> str | None:
 
 def build_api_router(registry: Any) -> APIRouter:
     """Build the CRUD API router for all registered models."""
-    router = APIRouter(tags=["api-crud"])
+    router = APIRouter()
 
     for registered in registry.all():
         # Respect skip_auto_routes (set for internal/built-in tables and any
@@ -83,6 +83,14 @@ def build_api_router(registry: Any) -> APIRouter:
     return router
 
 
+def _api_tags(registered: Any) -> list[str]:
+    """Return OpenAPI tags: admin.tag if set, else verbose_name."""
+    tag = getattr(registered.admin, "tag", None)
+    if tag:
+        return [tag]
+    return [registered.verbose_name]
+
+
 def build_api_router_for_model(registered: Any) -> APIRouter:
     """Build a standalone CRUD router for a single model.
 
@@ -92,7 +100,7 @@ def build_api_router_for_model(registered: Any) -> APIRouter:
     """
     router = APIRouter(
         prefix=f"/{registered.table_name}",
-        tags=["api-crud", registered.verbose_name],
+        tags=_api_tags(registered),
     )
     _register_model_routes(router, registered)
     return router
@@ -334,13 +342,14 @@ def _body_wrapper(
             )
         return _wrap_body_handler(handler, payload_schema, include_item_id=include_item_id)
 
-    # Add routes with both "api-crud" and model verbose_name tags
+    # Add routes with admin tag(s) or verbose_name fallback
+    api_tags = _api_tags(registered)
     router.add_api_route(
         "",
         _wrap_list_handler(list_handler, registered),
         methods=["GET"],
         response_model=list_response_schema,
-        tags=["api-crud", registered.verbose_name],
+        tags=api_tags,
         dependencies=[Depends(require_api_permission(table_name, "view"))],
     )
     router.add_api_route(
@@ -349,7 +358,7 @@ def _body_wrapper(
         methods=["POST"],
         response_model=response_schema,
         status_code=201,
-        tags=["api-crud", registered.verbose_name],
+        tags=api_tags,
         dependencies=[Depends(require_api_permission(table_name, "create"))],
     )
     router.add_api_route(
@@ -357,7 +366,7 @@ def _body_wrapper(
         _wrap_item_handler(edit_v.api_response),
         methods=["GET"],
         response_model=response_schema,
-        tags=["api-crud", registered.verbose_name],
+        tags=api_tags,
         dependencies=[Depends(require_api_permission(table_name, "view"))],
     )
     router.add_api_route(
@@ -365,7 +374,7 @@ def _body_wrapper(
         _body_wrapper(edit_v.api_response, update_schema, include_item_id=True),
         methods=["PUT"],
         response_model=response_schema,
-        tags=["api-crud", registered.verbose_name],
+        tags=api_tags,
         dependencies=[Depends(require_api_permission(table_name, "edit"))],
     )
     router.add_api_route(
@@ -373,7 +382,7 @@ def _body_wrapper(
         _body_wrapper(edit_v.api_response, update_schema, include_item_id=True),
         methods=["PATCH"],
         response_model=response_schema,
-        tags=["api-crud", registered.verbose_name],
+        tags=api_tags,
         dependencies=[Depends(require_api_permission(table_name, "edit"))],
     )
     router.add_api_route(
@@ -381,6 +390,6 @@ def _body_wrapper(
         _wrap_item_handler(delete_v.api_response, returns_response=True),
         methods=["DELETE"],
         status_code=204,
-        tags=["api-crud", registered.verbose_name],
+        tags=api_tags,
         dependencies=[Depends(require_api_permission(table_name, "delete"))],
     )

From 482775b63e6a58deaafa09b28e82d1b1a51f0e71 Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Mon, 14 Sep 2026 19:22:10 +0600
Subject: [PATCH 10/12] refactor: improve JWT handling and user resolution in
 auth system

---
 fastapi_admin_kit/api/auth.py       | 70 +++++++++++++++++++---
 fastapi_admin_kit/api/deps.py       | 18 +++---
 fastapi_admin_kit/api/middleware.py | 16 ++---
 fastapi_admin_kit/auth/backend.py   | 93 ++++++++++++++++++++++++-----
 fastapi_admin_kit/auth/identity.py  | 24 ++++----
 5 files changed, 168 insertions(+), 53 deletions(-)

diff --git a/fastapi_admin_kit/api/auth.py b/fastapi_admin_kit/api/auth.py
index 35f6dc7..59d909b 100644
--- a/fastapi_admin_kit/api/auth.py
+++ b/fastapi_admin_kit/api/auth.py
@@ -225,6 +225,64 @@ def decode_access_token(token: str, secret_key: str) -> dict[str, Any] | None:
         return None
 
 
+def parse_jwt_subject(sub: Any) -> int | str | None:
+    """Normalize a JWT ``sub`` claim to a DB-usable user id.
+
+    The ``AdminUserProtocol`` allows any PK type (``int``, ``str``, ``UUID``),
+    and :func:`create_access_token` stores ``str(user.id)``. Earlier code did
+    ``int(sub)`` and dropped every non-integer subject, so a valid token
+    minted for a UUID/str-PK user could be issued but never validated
+    (``Account not found or inactive`` on every subsequent call).
+
+    Returns ``int`` for digit strings (keeps integer-PK queries exact),
+    the stripped string otherwise, and ``None`` for missing/empty subjects.
+    """
+    if sub is None:
+        return None
+    if isinstance(sub, bool):
+        return None
+    if isinstance(sub, int):
+        return sub
+    # UUID objects (or any non-str scalar) — stringify; get_user() coerces back.
+    try:
+        text = str(sub).strip()
+    except Exception:
+        return None
+    if not text:
+        return None
+    try:
+        return int(text)
+    except (TypeError, ValueError):
+        return text
+
+
+def extract_bearer_token(auth_header: str | None) -> str | None:
+    """Extract the raw JWT from an ``Authorization`` header value.
+
+    Tolerates the two most common Swagger copy-paste mistakes:
+
+    - pasting ``Bearer <token>`` into the ``BearerAuth`` value field, which
+      Swagger then sends as ``Bearer Bearer <token>``;
+    - surrounding whitespace/quotes from copying a JSON response body.
+    """
+    if not auth_header or not auth_header.startswith("Bearer "):
+        return None
+    token = auth_header[7:].strip()
+    if not token:
+        return None
+    # Tolerate a duplicated scheme prefix (case-insensitive).
+    if len(token) > 7 and token[:7].lower() == "bearer ":
+        token = token[7:].strip()
+        if not token:
+            return None
+    # Tolerate surrounding quotes from JSON copy-paste.
+    if len(token) >= 2 and (
+        (token[0] == '"' and token[-1] == '"') or (token[0] == "'" and token[-1] == "'")
+    ):
+        token = token[1:-1].strip()
+    return token or None
+
+
 def _hash_token(token: str) -> str:
     """SHA256 hash of a token for storage."""
     return hashlib.sha256(token.encode()).hexdigest()
@@ -455,22 +513,18 @@ async def get_current_user_info(
     immediately.
     """
     auth_header = request.headers.get("Authorization", "")
-    if not auth_header.startswith("Bearer "):
+    token = extract_bearer_token(auth_header)
+    if token is None:
         raise HTTPException(status_code=401, detail="Missing or invalid Authorization header.")
 
-    token = auth_header[7:]
     secret_key = _get_secret_key(request)
     payload = decode_access_token(token, secret_key)
     if payload is None:
         raise HTTPException(status_code=401, detail="Invalid or expired token.")
 
-    sub = payload.get("sub")
-    if sub is None:
+    user_id = parse_jwt_subject(payload.get("sub"))
+    if user_id is None:
         raise HTTPException(status_code=401, detail="Invalid or expired token.")
-    try:
-        user_id: int | str = int(sub)
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=401, detail="Invalid or expired token.") from None
 
     # Resolve through the AuthBackend seam: honours BYO user models and
     # returns None for deleted/deactivated accounts.
diff --git a/fastapi_admin_kit/api/deps.py b/fastapi_admin_kit/api/deps.py
index c60ab06..90d91b8 100644
--- a/fastapi_admin_kit/api/deps.py
+++ b/fastapi_admin_kit/api/deps.py
@@ -20,6 +20,8 @@
 from fastapi_admin_kit.api.auth import (
     _get_secret_key,
     decode_access_token,
+    extract_bearer_token,
+    parse_jwt_subject,
     token_predates_password_change,
 )
 
@@ -34,11 +36,10 @@ async def get_api_current_user(request: Request) -> dict[str, Any]:
     if cached is not None:
         return cached
 
-    auth_header = request.headers.get("Authorization", "")
-    if not auth_header.startswith("Bearer "):
+    token = extract_bearer_token(request.headers.get("Authorization", ""))
+    if token is None:
         raise HTTPException(status_code=401, detail="Missing or invalid Authorization header.")
 
-    token = auth_header[7:]
     secret_key = _get_secret_key(request)
     payload = decode_access_token(token, secret_key)
     if payload is None:
@@ -51,13 +52,12 @@ async def _resolve_live_user(request: Request, user: dict[str, Any]) -> Any | No
 
     Returns ``None`` when the account was deleted or deactivated, so stale
     tokens cannot keep working after the account is removed.
+
+    The subject may be an ``int`` (built-in User) or a ``str``/``UUID``
+    (custom ``auth_model``) — it is passed through unchanged so BYO PKs work.
     """
-    sub = user.get("sub")
-    if sub is None:
-        return None
-    try:
-        user_id: int | str = int(sub)
-    except (TypeError, ValueError):
+    user_id = parse_jwt_subject(user.get("sub"))
+    if user_id is None:
         return None
 
     from fastapi_admin_kit.auth.identity import resolve_user
diff --git a/fastapi_admin_kit/api/middleware.py b/fastapi_admin_kit/api/middleware.py
index b3d2376..2bf66aa 100644
--- a/fastapi_admin_kit/api/middleware.py
+++ b/fastapi_admin_kit/api/middleware.py
@@ -97,6 +97,8 @@ async def dispatch(
         from fastapi_admin_kit.api.auth import (
             _get_secret_key,
             decode_access_token,
+            extract_bearer_token,
+            parse_jwt_subject,
             token_predates_password_change,
         )
         from fastapi_admin_kit.auth.identity import resolve_user
@@ -106,17 +108,15 @@ async def dispatch(
         except Exception:  # noqa: BLE001 — app misconfiguration surfaces below
             return await call_next(request)
 
-        payload = decode_access_token(auth_header[7:], secret_key)
+        token = extract_bearer_token(auth_header)
+        if token is None:
+            return _unauthorized("Missing or invalid Authorization header.")
+
+        payload = decode_access_token(token, secret_key)
         if payload is None:
             return _unauthorized("Invalid or expired token.")
 
-        sub = payload.get("sub")
-        user_id: int | str | None = None
-        if sub is not None:
-            try:
-                user_id = int(sub)
-            except (TypeError, ValueError):
-                user_id = None
+        user_id = parse_jwt_subject(payload.get("sub"))
 
         user = await resolve_user(request, user_id) if user_id is not None else None
         if user is None:
diff --git a/fastapi_admin_kit/auth/backend.py b/fastapi_admin_kit/auth/backend.py
index 707c77f..d1b7afd 100644
--- a/fastapi_admin_kit/auth/backend.py
+++ b/fastapi_admin_kit/auth/backend.py
@@ -29,7 +29,7 @@ async def authenticate(
         ...
 
     @abstractmethod
-    async def get_user(self, user_id: int | str, session: Any) -> AdminUserProtocol | None:
+    async def get_user(self, user_id: Any, session: Any) -> AdminUserProtocol | None:
         """Load user by PK. Return ``None`` if not found or inactive."""
         ...
 
@@ -173,20 +173,60 @@ async def authenticate(
             return None
         return user
 
-    async def get_user(
+    def _candidate_user_ids(self, user_id: Any) -> list[Any]:
+        """Return DB lookup candidates for *user_id* covering int/str/UUID PKs.
+
+        JWT ``sub`` arrives as ``str`` (``create_access_token`` stores
+        ``str(user.id)``), while the DB PK may be an ``int``, a ``str``, or a
+        ``UUID`` object. Strict ``==`` comparison (SQLAlchemy or the in-memory
+        backend) fails on type mismatch, so we try the original value plus
+        its int/UUID reinterpretations in order.
+        """
+        if user_id is None or isinstance(user_id, bool):
+            return []
+        candidates: list[Any] = [user_id]
+        seen = {(type(user_id).__name__, str(user_id))}
+
+        def _add(value: Any) -> None:
+            key = (type(value).__name__, str(value))
+            if key not in seen:
+                seen.add(key)
+                candidates.append(value)
+
+        if isinstance(user_id, int):
+            _add(str(user_id))
+            return candidates
+        if isinstance(user_id, str):
+            text = user_id.strip()
+            if text != user_id:
+                _add(text)
+                user_id = text
+            try:
+                _add(int(text))
+            except (TypeError, ValueError):
+                pass
+            try:
+                import uuid as _uuid
+
+                _add(_uuid.UUID(text))
+            except Exception:
+                pass
+            return candidates
+        # UUID objects (or any other scalar PK): also try their string form.
+        try:
+            _add(str(user_id))
+        except Exception:
+            pass
+        return candidates
+
+    async def _lookup_user_by_id(
         self,
-        user_id: int | str,
+        query_backend_resolved: Any,
         session: Any,
-        query_adapter: Any | None = None,
-        query_backend: Any | None = None,
-        **kwargs: Any,
-    ) -> AdminUserProtocol | None:
-        qb = query_adapter if query_adapter is not None else query_backend
-        if qb is None:
-            qb = kwargs.get("query_adapter") or kwargs.get("query_backend")
-        query_backend_resolved = self._resolve_query_backend(qb)
-        session = self._resolve_session(session)
-        model = self._get_model()
+        model: type,
+        candidate: Any,
+    ) -> Any | None:
+        """Run a single PK + is_active lookup for *candidate*."""
         query = query_backend_resolved.select(model)
         is_active_col = getattr(model, "is_active", None)
         id_col = getattr(model, "id", None)
@@ -195,13 +235,12 @@ async def get_user(
         if is_active_col is not None:
             query = query_backend_resolved.where(
                 query,
-                id_col == user_id,
+                id_col == candidate,
                 is_active_col == True,  # noqa: E712
             )
         else:
-            query = query_backend_resolved.where(query, id_col == user_id)
+            query = query_backend_resolved.where(query, id_col == candidate)
 
-        # Eagerly load roles if the model has a roles relationship
         if hasattr(model, "roles"):
             try:
                 if query_backend_resolved.__class__.__name__ == "SqlAlchemyQueryAdapter":
@@ -214,6 +253,28 @@ async def get_user(
         result = session.scalar_one_or_none(query)
         return await result if hasattr(result, "__await__") else result
 
+    async def get_user(
+        self,
+        user_id: Any,
+        session: Any,
+        query_adapter: Any | None = None,
+        query_backend: Any | None = None,
+        **kwargs: Any,
+    ) -> AdminUserProtocol | None:
+        qb = query_adapter if query_adapter is not None else query_backend
+        if qb is None:
+            qb = kwargs.get("query_adapter") or kwargs.get("query_backend")
+        query_backend_resolved = self._resolve_query_backend(qb)
+        session = self._resolve_session(session)
+        model = self._get_model()
+        if getattr(model, "id", None) is None:
+            return None
+        for candidate in self._candidate_user_ids(user_id):
+            user = await self._lookup_user_by_id(query_backend_resolved, session, model, candidate)
+            if user is not None:
+                return user
+        return None
+
     async def on_logout(self, user_id: int | str | None = None) -> None:
         """No-op for built-in backend."""
         return None
diff --git a/fastapi_admin_kit/auth/identity.py b/fastapi_admin_kit/auth/identity.py
index aae562b..9e2be7c 100644
--- a/fastapi_admin_kit/auth/identity.py
+++ b/fastapi_admin_kit/auth/identity.py
@@ -52,7 +52,7 @@ def _get_db_session(request: Request) -> AsyncSession | None:
         return None
 
 
-async def resolve_user(request: Request, user_id: int | str | None) -> AdminUserProtocol | None:
+async def resolve_user(request: Request, user_id: Any | None) -> AdminUserProtocol | None:
     """Resolve *user_id* to an active user and cache it on the request.
 
     Idempotent for a given request: if ``request.state.admin_user`` is already
@@ -62,7 +62,7 @@ async def resolve_user(request: Request, user_id: int | str | None) -> AdminUser
 
     Always honours the configured ``AuthBackend.get_user`` seam, so BYO user
     models are supported on every transport (cookie *and* JWT), not just the
-    built-in one.
+    built-in one. ``user_id`` may be an ``int``, ``str``, or ``UUID``.
     """
     cached = getattr(request.state, "admin_user", None)
     if cached is not None:
@@ -174,24 +174,24 @@ async def get_current_user_from_bearer(
     honours the ``AuthBackend.get_user`` seam just like the cookie path.
     """
     # Imported lazily to avoid a circular import at module load time.
-    from fastapi_admin_kit.api.auth import _get_secret_key, decode_access_token
+    from fastapi_admin_kit.api.auth import (
+        _get_secret_key,
+        decode_access_token,
+        extract_bearer_token,
+        parse_jwt_subject,
+    )
 
-    auth_header = request.headers.get("Authorization", "")
-    if not auth_header.startswith("Bearer "):
+    token = extract_bearer_token(request.headers.get("Authorization", ""))
+    if token is None:
         return None
 
-    token = auth_header[len("Bearer ") :]
     secret_key = _get_secret_key(request)
     payload = decode_access_token(token, secret_key)
     if payload is None:
         return None
 
-    sub = payload.get("sub")
-    if sub is None:
-        return None
-    try:
-        user_id: int | str = int(sub)  # type: ignore[assignment]
-    except (TypeError, ValueError):
+    user_id = parse_jwt_subject(payload.get("sub"))
+    if user_id is None:
         return None
 
     user = await resolve_user(request, user_id)

From a2f5498619bd50dcb138a30ceb090008b2bda79a Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Mon, 14 Sep 2026 19:22:53 +0600
Subject: [PATCH 11/12] bump version to 0.6.2

---
 fastapi_admin_kit/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/fastapi_admin_kit/__init__.py b/fastapi_admin_kit/__init__.py
index 8c92c32..e96e43b 100644
--- a/fastapi_admin_kit/__init__.py
+++ b/fastapi_admin_kit/__init__.py
@@ -134,4 +134,4 @@
     "configure_notifications",
     "notifications_router",
 ]
-__version__ = "0.6.1"
+__version__ = "0.6.2"

From 7c16e4c54590ae1a8df5ffe31b58ccce06a60d6d Mon Sep 17 00:00:00 2001
From: borhanst <mdborhan.st@gmail.com>
Date: Mon, 14 Sep 2026 19:31:24 +0600
Subject: [PATCH 12/12] refactor: streamline parameter handling and payload
 assignment in CRUD operations

---
 fastapi_admin_kit/api/crud.py         | 12 +++---------
 fastapi_admin_kit/filters/registry.py |  4 +---
 2 files changed, 4 insertions(+), 12 deletions(-)

diff --git a/fastapi_admin_kit/api/crud.py b/fastapi_admin_kit/api/crud.py
index 96f0cd5..40ad44f 100644
--- a/fastapi_admin_kit/api/crud.py
+++ b/fastapi_admin_kit/api/crud.py
@@ -202,25 +202,19 @@ def _wrap_multipart_handler(
             param_type = Annotated[str | None, Form()]
         # All params optional here — required fields are enforced by the
         # shared widget/validator pipeline, exactly like the HTML form.
-        params.append(
-            Parameter(name, Parameter.KEYWORD_ONLY, default=None, annotation=param_type)
-        )
+        params.append(Parameter(name, Parameter.KEYWORD_ONLY, default=None, annotation=param_type))
 
     if include_item_id:
 
         async def wrapped(request: Request, **kwargs: Any) -> Any:
             item_id = kwargs.pop("item_id", None)
-            request.state._api_payload = {
-                k: v for k, v in kwargs.items() if v is not None
-            }
+            request.state._api_payload = {k: v for k, v in kwargs.items() if v is not None}
             return await handler(request, item_id=item_id)
 
     else:
 
         async def wrapped(request: Request, **kwargs: Any) -> Any:
-            request.state._api_payload = {
-                k: v for k, v in kwargs.items() if v is not None
-            }
+            request.state._api_payload = {k: v for k, v in kwargs.items() if v is not None}
             return await handler(request)
 
     wrapped.__signature__ = Signature(params)
diff --git a/fastapi_admin_kit/filters/registry.py b/fastapi_admin_kit/filters/registry.py
index 085aa41..d047f10 100644
--- a/fastapi_admin_kit/filters/registry.py
+++ b/fastapi_admin_kit/filters/registry.py
@@ -162,9 +162,7 @@ def _relationship_filter(
         if direction != "MANYTOONE":
             target = meta.target_model if meta is not None else None
             target_pk = (
-                cls._resolve_pk_column(target, introspection)
-                if target is not None
-                else None
+                cls._resolve_pk_column(target, introspection) if target is not None else None
             )
             if target is not None and target_pk is not None:
                 return ChoiceFilter(