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.

property name() -> str

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

property display_name() -> str

Human-readable contributor name for the admin UI.

property group() -> str

Navigation group this contributor belongs to.

property icon() -> str

Lucide icon name for the contributor.

property priority() -> int

Ordering priority within its group (lower = first).

property version() -> str

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

property package_source() -> str

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

property contributor_id() -> str

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

property required_permissions() -> frozenset[str]

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

def get_dashboard_widgets() -> Sequence[DashboardWidgetDefinition]

Return widget definitions for the main dashboard.

def get_navigation_items() -> Sequence[NavigationContribution]

Return navigation entries for the admin sidebar.

def get_management_pages() -> Sequence[ManagementPageDefinition]

Return full management page definitions.

def get_settings_panels() -> Sequence[SettingsPanelDefinition]

Return settings panel definitions.

def get_health_definitions() -> Sequence[AdminHealthDefinition]

Return health check definitions to surface in the dashboard.

def get_actions() -> Sequence[AdminActionDefinition]

Return framework-level actions.

async def on_admin_boot(container: ContainerResolverProtocol) -> None

Called when the admin dashboard boots.

async def on_admin_shutdown() -> None

Called when the admin dashboard shuts down.

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

Execute a named action on this contributor.

Parameters

Parameter	Type	Description
`action_name`	str	Name of the action to execute.
`params`	dict[str, object]	Keyword arguments forwarded to the action handler.

Returns

Type	Description
object	Whatever the action handler returns.

async def render_widget(
    widget_name: str,
    params: WidgetParams
) -> Result[str, AdminError]

Render a named widget to an HTML fragment.

Parameters

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

Returns

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

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

Render HTML result for a health check.

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[str, AdminError]	``Ok(html_string)`` with health check result on success. ``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.

def register(contributor: AdminContributorProtocol) -> None

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

Get contributor by name.

def get_all() -> Sequence[AdminContributorProtocol]

Get all registered contributors, ordered by priority.

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

Get contributors in a specific group.

`AdminDashboardProtocol`

Protocol for the assembled admin dashboard service.

async def get_all_widgets() -> Sequence[DashboardWidgetDefinition]

Collect widgets from all contributors.

async def get_all_navigation() -> Sequence[NavigationContribution]

Collect navigation from all contributors.

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

Aggregate health from all contributors.

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

`AdminBundleProvider`

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.

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

property config() -> AdminConfig

Return current admin config.

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

Create provider from typed config.

async def register(container: ContainerRegistrarProtocol) -> None

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.

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.

async def boot(container: ContainerResolverProtocol) -> None

Boot all sub-providers in order.

async def shutdown() -> None

Shut down sub-providers in reverse order.

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

Aggregate health from all sub-providers.

`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],
    ),
])

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 AdminBundleProvider.

Returns

Type	Description
DynamicModule	A DynamicModule descriptor.

def stub(cls) -> 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.

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

property config() -> AdminConfig

Return current admin config.

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

Create provider from typed config.

async def register(container: ContainerRegistrarProtocol) -> None

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.

async def boot(container: ContainerResolverProtocol) -> None

Boot all sub-providers in order.

async def shutdown() -> None

Shut down sub-providers in reverse order.

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.

property contributor_id() -> str

Stable identifier for RBAC lookup — equals name.

def get_dashboard_widgets() -> Sequence[DashboardWidgetDefinition]