Skip to content

API Reference

Protocols

`AdminContributorProtocol`

Contract for packages that contribute admin dashboard surfaces.

Any lexigram extension package can implement this protocol and register it via the lexigram.admin.contributors entry point. The admin dashboard discovers contributors at boot and assembles their widgets, pages, navigation, and actions into the unified admin UI.

name

property name() -> str

Unique contributor identifier (e.g. ‘cache’, ‘events’, ‘ai’).

display_name

property display_name() -> str

Human-readable contributor name for the admin UI.

group

property group() -> str

Navigation group this contributor belongs to.

icon

property icon() -> str

Lucide icon name for the contributor.

depends_on

property depends_on() -> tuple[str, Ellipsis]

Contributor names that must boot before this contributor.

priority

property priority() -> int

Ordering priority within its group (lower = first).

version

property version() -> str

Semantic version of this contributor (e.g. ‘1.2.3’).

package_source

property package_source() -> str

Python package name that provides this contributor (e.g. ‘lexigram-cache’).

contributor_id

property contributor_id() -> str

Stable unique identifier used for lookup and RBAC keying (equals name).

required_permissions

property required_permissions() -> frozenset[str]

Permissions a user must hold to execute any action on this contributor.

get_resources

def get_resources() -> Sequence[type]

Return resource classes managed by this contributor.

get_dashboard_widgets

def get_dashboard_widgets() -> Sequence[DashboardWidgetDefinition]

Return widget definitions for the main dashboard.

get_navigation_items

def get_navigation_items() -> Sequence[NavigationContribution]

Return navigation entries for the admin sidebar.

get_management_pages

def get_management_pages() -> Sequence[ManagementPageDefinition]

Return full management page definitions.

get_settings_panels

def get_settings_panels() -> Sequence[SettingsPanelDefinition]

Return settings panel definitions.

get_health_definitions

def get_health_definitions() -> Sequence[AdminHealthDefinition]

Return health check definitions to surface in the dashboard.

get_actions

def get_actions() -> Sequence[AdminActionDefinition]

Return framework-level actions.

get_routes

def get_routes() -> Sequence[AdminRouteSpec]

Return route specifications for the admin router.

on_admin_boot

async def on_admin_boot(container: ContainerResolverProtocol) -> None

Called when the admin dashboard boots.

on_admin_shutdown

async def on_admin_shutdown() -> None

Called when the admin dashboard shuts down.

render_widget

async def render_widget(
    widget_name: str,
    params: WidgetParams,
    resolver: ContainerResolverProtocol | None = None
) -> Result[WidgetViewModel, AdminError]

Render a named widget to a typed WidgetViewModel.

Parameters

Parameter	Type	Description
`widget_name`	str	Name of the widget to render.
`params`	WidgetParams	Typed, validated widget parameters.
`resolver`	ContainerResolverProtocol \| None	Optional DI resolver for lazy dependency injection.

Returns

Type	Description
Result[WidgetViewModel, AdminError]	Ok(WidgetViewModel) with structured content in ``content`` on success. Err(WidgetNotFoundError) when the widget name is unknown. Err(AdminError) for other expected domain failures. Infrastructure exceptions propagate (not caught here).

render_health_check

async def render_health_check(check_name: str) -> Result[HealthCheckPayload, AdminError]

Run a health check and return a structured health-check payload.

Parameters

Parameter	Type	Description
`check_name`	str	Name of the health check to run (matches check ID from ``get_health_definitions``).

Returns

Type	Description
Result[HealthCheckPayload, AdminError]	``Ok(HealthCheckPayload)`` describing the check result on success — the host renders it as HTML. ``Err(HealthCheckNotFoundError)`` if check_name is not served by this contributor. ``Err(AdminError)`` if the check fails for any other reason.

`AdminContributorRegistryProtocol`

Registry that collects and manages admin contributors.

register

def register(contributor: AdminContributorProtocol) -> None

Register a contributor.

get

def get(name: str) -> AdminContributorProtocol | None

Get contributor by name.

get_all

def get_all() -> Sequence[AdminContributorProtocol]

Get all registered contributors, ordered by priority.

get_by_group

def get_by_group(group: str) -> Sequence[AdminContributorProtocol]

Get contributors in a specific group.

`AdminDashboardProtocol`

Protocol for the assembled admin dashboard service.

get_all_widgets

async def get_all_widgets() -> Sequence[DashboardWidgetDefinition]

Collect widgets from all contributors.

get_all_navigation

async def get_all_navigation() -> Sequence[NavigationContribution]

Collect navigation from all contributors.

get_framework_health

async def get_framework_health() -> dict[str, object]

Aggregate health from all contributors.

execute_action

async def execute_action(
    contributor_id: str,
    action_name: str,
    params: dict[str, object],
    user_permissions: frozenset[str]
) -> object

Execute a framework-level action from a contributor.

Parameters

Parameter	Type	Description
`contributor_id`	str	Identifier of the target contributor.
`action_name`	str	Name of the action to execute.
`params`	dict[str, object]	Parameters forwarded to the action handler.
`user_permissions`	frozenset[str]	Permissions held by the requesting user.

Returns

Type	Description
object	Whatever the action handler returns.

Classes

`AdminModule`

Lexigram admin panel module.

Call configure to register the admin panel with its bundle provider and contributor system.

Usage

from lexigram.admin.config import AdminConfig

app.add_modules([
    AdminModule.configure(
        config=AdminConfig(title="My Admin"),
        resources=[UserResource, ProductResource],
    ),
])

from lexigram.admin.config import AdminConfig

app.add_modules([
    AdminModule.configure(
        config=AdminConfig(title="My Admin"),
        resources=[UserResource, ProductResource],
    ),
])

configure

def configure(
    cls,
    config: Any | None = None,
    auth_provider: Any | None = None,
    resources: list[type] | None = None,
    controllers: list[type] | None = None,
    **kwargs: Any
) -> DynamicModule

Create an AdminModule with explicit configuration.

Parameters

Parameter	Type	Description
`config`	Any \| None	AdminConfig or None for defaults.
`auth_provider`	Any \| None	Optional AuthProviderProtocol for auth integration.
`resources`	list[type] \| None	List of Resource classes to register.
`controllers`	list[type] \| None	List of controller classes to register. **kwargs: Forwarded to AdminProvider.

Returns

Type	Description
DynamicModule	A DynamicModule descriptor.

stub

def stub(
    cls,
    config: Any = None
) -> DynamicModule

Return a no-op AdminModule for testing.

Returns

Type	Description
DynamicModule	A DynamicModule with default admin configuration.

`AdminPanelStartedHook`

Payload fired after the admin panel has finished its startup sequence.

`AdminPanelStoppedHook`

Payload fired after an orderly admin panel shutdown completes.

`AdminProvider`

Orchestrates admin sub-providers for the full admin panel.

Sub-providers are focused helper classes (not Provider subclasses). This follows the EventsProvider/AuthBundleProvider pattern.

Config is accepted only in init and never mutated after construction. Sub-providers are instantiated in register() — not in init — so that no DI work happens before the container is ready.

__init__

def __init__(
    config: AdminConfig | None = None,
    auth_provider: Any | None = None,
    resources: list[type] | None = None,
    controllers: list[type] | None = None,
    extra_providers: list[Any] | None = None,
    **kwargs: Any
) -> None

config

property config() -> AdminConfig

Return current admin config.

from_config

def from_config(
    cls,
    config: AdminConfig,
    **context: Any
) -> Self

Create provider from typed config.

register

async def register(container: ContainerRegistrarProtocol) -> None

Register admin and all sub-providers.

Sub-providers are instantiated here (not in init) so that no DI resolution or heavyweight initialisation happens before the container lifecycle has started. No resolution is performed in this method — only bindings are registered.

mount_to_app

async def mount_to_app(
    app: Any,
    container: ContainerResolverProtocol
) -> None

Build and mount the admin panel onto a Starlette application.

Called by the web provider during route setup, after the Starlette app is created and all providers have booted.

Parameters

Parameter	Type	Description
`app`	Any	The Starlette application to mount the admin panel on.
`container`	ContainerResolverProtocol	The DI resolver for resolving controller dependencies.

boot

async def boot(container: ContainerResolverProtocol) -> None

Boot all sub-providers in order.

shutdown

async def shutdown() -> None

Shut down sub-providers in reverse order.

health_check

async def health_check(timeout: float = 5.0) -> HealthCheckResult

Aggregate health from all sub-providers.

`AdminResourceAccessedHook`

Payload fired when an admin resource page is accessed.

Attributes: resource_name: Registered name of the admin resource (e.g. "User"). action: CRUD action being performed (e.g. "list", "change"). user_id: Identifier of the admin user performing the action.

`AdminStatus`

Status of admin operations.

`AdminUser`

Admin user representation.

`BaseAdminContributor`

Convenience base class for admin contributors.

Provides no-op defaults for all AdminContributorProtocol methods. Subclasses override only the methods they need.

contributor_id

property contributor_id() -> str

Stable identifier for RBAC lookup — equals name.

get_resources

def get_resources() -> Sequence[type]

Return an empty sequence by default.

get_routes

def get_routes() -> Sequence[AdminRouteSpec]

Return an empty sequence by default.

get_dashboard_widgets

def get_dashboard_widgets() -> Sequence[DashboardWidgetDefinition]

Return an empty list by default.

get_navigation_items

def get_navigation_items() -> Sequence[NavigationContribution]

Return an empty list by default.

get_management_pages

def get_management_pages() -> Sequence[ManagementPageDefinition]

Return an empty list by default.

get_settings_panels

def get_settings_panels() -> Sequence[SettingsPanelDefinition]

Return an empty list by default.

get_health_definitions

def get_health_definitions() -> Sequence[AdminHealthDefinition]

Return an empty list by default.

get_actions

def get_actions() -> Sequence[AdminActionDefinition]

Return an empty list by default.

on_admin_boot

async def on_admin_boot(container: ContainerResolverProtocol) -> None

No-op boot hook.

on_admin_shutdown

async def on_admin_shutdown() -> None

No-op shutdown hook.

render_widget

async def render_widget(
    widget_name: str,
    params: WidgetParams,
    resolver: ContainerResolverProtocol | None = None
) -> Result[WidgetViewModel, AdminError]

Return a not-found error by default — override in subclasses.

render_health_check

async def render_health_check(check_name: str) -> Result[HealthCheckPayload, AdminError]

Default: this contributor does not serve the requested health check.

Parameters

Parameter	Type	Description
`check_name`	str	Name of the health check requested.

Returns

Type	Description
Result[HealthCheckPayload, AdminError]	``Err(HealthCheckNotFoundError)`` — contributor does not provide this check.

`ContributorRegistry`

Registry that collects and manages admin contributors.

Follows the Registry pattern (AGENTS.md §6.3): empty __init__, with_defaults() classmethod for pre-populated instances.

__init__

def __init__() -> None

with_defaults

def with_defaults(cls) -> ContributorRegistry

Create a registry (no built-in contributors by default).

register

def register(contributor: AdminContributorProtocol) -> None

Register a contributor, keyed by its name.

get

def get(name: str) -> AdminContributorProtocol | None

Get a contributor by name, or None.

get_all

def get_all() -> Sequence[AdminContributorProtocol]

Get all contributors sorted by priority (lower = first).

get_by_group

def get_by_group(group: str) -> Sequence[AdminContributorProtocol]

Get contributors in a specific group, sorted by priority.

`CoreAdminContributor`

Built-in contributor providing core dashboard surfaces.

Provides the framework health overview widget, the main dashboard navigation entry, and the system-wide health check surface.

__init__

def __init__() -> None

on_admin_boot

async def on_admin_boot(container: object) -> None

get_dashboard_widgets

def get_dashboard_widgets() -> Sequence[DashboardWidgetDefinition]

Return core dashboard widgets: health overview, recent activity, and metrics.

get_navigation_items

def get_navigation_items() -> Sequence[NavigationContribution]

Return core navigation: Dashboard link.

get_health_definitions

def get_health_definitions() -> Sequence[AdminHealthDefinition]

Return core health definitions.

render_widget

async def render_widget(
    widget_name: str,
    params: WidgetParams,
    resolver: ContainerResolverProtocol | None = None
) -> Result[WidgetViewModel, AdminError]

Render core widgets.

Parameters

Parameter	Type	Description
`widget_name`	str	Name of the widget to render.
`params`	WidgetParams	Widget parameters.

Returns

Type	Description
Result[WidgetViewModel, AdminError]	Result containing a WidgetViewModel with structured ``content``, or WidgetNotFoundError if the widget is not found.

render_health_check

async def render_health_check(check_name: str) -> Result[HealthCheckPayload, AdminError]

Render health check for admin core.

Parameters

Parameter	Type	Description
`check_name`	str	Name of the health check.

Returns

Type	Description
Result[HealthCheckPayload, AdminError]	Ok(HealthCheckPayload) with the core status, or Err(AdminError) when the check is unknown.

`ErrorCode`

Machine-readable error codes for admin operations.

Exceptions

`AdminError`

Base exception for all admin errors.

`AdminValidationError`

Raised when validation fails.

`ConflictError`

Raised when a resource conflict occurs.

`DataError`

Raised when a data source or database error occurs in admin.

`NotFoundError`

Raised when a resource is not found.

`NotificationError`

Raised when a notification fails to send.

`PermissionDeniedError`

Raised when permission is denied.