¿Qué es un plugin?¶

Un plugin Cortex es un paquete Python instalable que el framework descubre por entry point y ensambla en runtime si está activo en el state store.

Contrato mínimo (SPI)¶

Todo plugin implementa PluginProtocol definido en cortex_core.plugin:

Miembro	Obligatorio	Descripción
`descriptor`	Sí	`PluginDescriptor`: id, nombre, versión, `requires`, `provides`, `contributes_panels`
`api_router()`	Sí	`APIRouter` montado bajo `/api/v1`
`resource_paths()`	Sí	Segmentos de ruta que el plugin expone (p. ej. `["clients"]`)

Factory obligatoria:

def create_plugin() -> MiPlugin:
    return MiPlugin()

Entry point en pyproject.toml:

[project.entry-points."cortex.plugins"]
mi-modulo = "cortex_plugin_mi_modulo:create_plugin"

PluginDescriptor¶

PluginDescriptor(
    plugin_id="helloworld",
    display_name="Hello World",
    version="0.1.0",
    requires=(),
    optional_requires=(),
    provides=("helloworld",),
    contributes_panels=("samples",),
    stateless=True,
)

El framework valida requires / optional_requires en boot según PLUGIN_DEPS. El grafo de un caso de uso ensamblado se documenta en su paquete de instalación (véase Reservas).

Hooks opcionales de bootstrap¶

El loader importa el paquete del plugin y, si existen, invoca funciones exportadas en __init__.py:

Hook	Qué registra
`register_resources`	Manifest CUS + dashboards (recomendado)
`register_settings` / `register_configuration`	Segmentos de configuración por panel
`register_widgets`	Widgets en dashboard home
`register_mcp_tools`	Tools para agentes MCP
`register_ws_namespaces`	Handlers WebSocket
`register_listeners` / `register_observers`	Eventos de dominio
`register_dashboards`	JSON manual en `ui/` (legacy)

Si el paquete exporta register_resources, el loader no ejecuta register_dashboards ni register_forms por separado.

Lista completa y orden: Ciclo de vida.

Plugin de dominio vs entry point `cortex.panels`¶

Concepto	Entry point	Uso actual
Plugin de dominio	`cortex.plugins`	Casi todo el código de negocio
Host de panel dedicado	`cortex.panels`	Opcional: namespaces con identidad propia (`accounting`, `trainer`)

Los namespaces operations y admin son generativos: el framework los materializa con ensure_panel() cuando un plugin habilitado llama a register_resources(registry, "operations", ...). No requieren un paquete host pip.

Deprecado

Depender de cortex-plugin-panel o cortex-plugin-admin como requisito de activación. Usa namespaces generativos y contribuye módulos directamente.

Qué no es un plugin¶

Un cambio directo en cortex_framework/ o cortex_core/.
Un script suelto sin entry point ni descriptor.
Documentación de dominio en cortex-docs (docs/plugins/<id>/).

Ejemplos en el monorepo¶

Plugin	Qué ilustra
`plugins/_template`	Mínimo viable: REST + listado en `operations`
`plugins/helloworld`	Sandbox SPI: ResourceBuilder + FormBuilder (API interna)
`plugins/clients`	`ResourceBuilder` completo con CRUD

Siguiente paso¶

Anatomía de un plugin — estructura de carpetas y archivos.