Panel hosts¶

Un panel host es un producto UI independiente: ruta base, título, tema y módulo home. Se registra con entry point cortex.panels.

Cuándo crear un host¶

Necesitas una app con URL propia (/accounting/, /samples/).
El panel tiene identidad de marca, tema o default_route distintos.
No basta con contribuir un módulo a panel.

Entry point¶

[project.entry-points."cortex.panels"]
samples = "cortex_plugin_reference:configure_panel"

configure_panel¶

from cortex_framework.panel.builder import PanelBuilder

def configure_panel(builder: PanelBuilder) -> None:
    (
        builder.id("samples")
        .path("/samples")
        .title("Samples")
        .namespace("samples")
        .auth(scopes=("samples",))
    )

Panel con home module:

def configure_panel(builder: PanelBuilder) -> None:
    manifest, dashboards = build_home_module()
    (
        builder.id("panel")
        .path("/panel")
        .title("Operación")
        .namespace("panel")
        .theme(skin="shadcn", sidebar_width="272px")
        .brand(title="CORTEX-IA", version="0.5.1")
        .default_route("/panel/booking/agenda")
        .home_module(manifest, dashboards)
    )

Referencias:

plugins/reference/cortex_plugin_reference/provider.py
plugins/panel/cortex_plugin_panel/provider.py
plugins/admin/cortex_plugin_admin/provider.py — parametrización (/admin/)

PanelBuilder — API¶

Método	Descripción
`.id(str)`	Id del panel (`panel_id`)
`.path(str)`	Prefijo URL del shell
`.title(str)`	Título en UI
`.namespace(str)`	Namespace API (`GET /{namespace}/info`)
`.auth(scopes=...)`	Scopes OIDC (futuro)
`.theme(skin=, sidebar_width=)`	Skin y layout
`.brand(title=, version=)`	Marca en sidebar
`.default_route(str)`	Ruta al entrar al panel
`.home_module(manifest, dashboards)`	Módulo home embebido
`.nav_group(id, label, sort)`	Grupos de navegación

Host con API custom (opcional)¶

def create_panel_host(configuration: PanelConfiguration) -> PanelHostPlugin:
    return MiPanelHost(configuration)

Por defecto el host expone GET /{namespace}/info.

Activación¶

export CORTEX_ENABLED_PANELS=panel,accounting,samples

Los plugins de negocio y los hosts se filtran por separado.

Dashboard del panel¶

Cada host declara un módulo home con pantalla Dashboard (path: ""). Los plugins inyectan widgets con register_widgets + WidgetDefinition; en boot, merge_panel_infrastructure los fusiona en el dashboard del host sin reemplazarlo.

from cortex_core.spi import WidgetDefinition, WidgetKind
from cortex_framework.registries.widgets import WidgetRegistryApi

def register_widgets(registry: WidgetRegistryApi) -> None:
    registry.register(
        "admin",
        WidgetDefinition(
            widget_id="sales-kpi",
            kind=WidgetKind.STAT_CARD,
            panel_id="admin",
            title="Ventas",
            config={"path": "/api/v1/sales/sales", "grid": {"xs": 12, "md": 3}},
            plugin_id="sales",
        ),
    )

default_route del panel suele apuntar al dashboard (/admin, /accounting, …).

Plugins en varios paneles¶

Un mismo plugin puede registrar recursos o widgets en uno o varios paneles:

from cortex_framework.ui import ResourceBuilder, register_resource, register_resource_for_panels

# Misma configuración en varios paneles
register_resource_for_panels(registry, ("panel", "admin"), "reports", configure)

# Configuraciones distintas por panel
register_resource(registry, "admin", "payments", configure_crud)
register_resource(registry, "panel", "payments", configure_readonly)

Los widgets (register_widgets) y settings (register_settings) también filtran por panel_id.

Siguiente paso¶

Primeros pasos para registrar módulos de dominio en tu host.

Ver ADR 011 y ADR 004.