Plugins API Reference¶

Module: fcc.plugins

The plugins module provides a registry for discovering, loading, and managing FCC plugins via setuptools entry points, plus a cross-plugin orchestration layer.

mindmap
  root((FCC Plugins))
    Personas
    Engines
    Templates
    Scorers
    Validators
    Providers
    Governance
    Scenarios
    Workflows
    Subscribers

Module Structure¶

Module	Description
`fcc.plugins.base`	`PluginType`, `PluginMeta`, and 10 plugin ABCs
`fcc.plugins.registry`	`PluginRegistry`, `DiscoveryResult`
`fcc.plugins.orchestration`	`CrossPluginOrchestrator`, dependency/interaction models
`fcc.plugins.errors`	`PluginLoadError`, `PluginConflictError`, `PluginNotFoundError`

PluginType¶

from fcc.plugins.base import PluginType

Enum mapping plugin types to entry-point groups:

Member	Value (entry-point group)
`PERSONAS`	`fcc.plugins.personas`
`ENGINES`	`fcc.plugins.engines`
`TEMPLATES`	`fcc.plugins.templates`
`SCORERS`	`fcc.plugins.scorers`
`VALIDATORS`	`fcc.plugins.validators`
`PROVIDERS`	`fcc.plugins.providers`
`GOVERNANCE`	`fcc.plugins.governance`
`SCENARIOS`	`fcc.plugins.scenarios`
`WORKFLOWS`	`fcc.plugins.workflows`
`SUBSCRIBERS`	`fcc.plugins.subscribers`

PluginMeta¶

from fcc.plugins.base import PluginMeta

Frozen dataclass with plugin metadata.

Fields: id: str, name: str, version: str, plugin_type: PluginType, description: str, author: str, source_package: str, tags: tuple[str, ...].

Method	Signature	Returns	Description
`to_dict()`	`()`	dict	Serialize
`from_dict()`	`(data: dict)`	PluginMeta	Deserialize

Plugin ABCs¶

Each plugin type has an ABC in fcc.plugins.base:

ABC	Required Methods
`PersonaPlugin`	`plugin_meta()`, `get_persona_paths()`
`EnginePlugin`	`plugin_meta()`, `get_engine_class()`
`TemplatePlugin`	`plugin_meta()`, `get_template_paths()`
`ScorerPlugin`	`plugin_meta()`, `score()`
`ValidatorPlugin`	`plugin_meta()`, `validate()`
`ProviderPlugin`	`plugin_meta()`, `provide()`
`GovernancePlugin`	`plugin_meta()`, `get_governance_rules()`
`ScenarioPlugin`	`plugin_meta()`, `get_scenario_paths()`
`WorkflowPlugin`	`plugin_meta()`, `get_workflow_paths()`
`EventSubscriberPlugin`	`plugin_meta()`, `get_subscribers()`

Example: PersonaPlugin¶

from fcc.plugins.base import PersonaPlugin, PluginMeta, PluginType
from pathlib import Path

class MyPersonaPlugin(PersonaPlugin):
    def plugin_meta(self) -> PluginMeta:
        return PluginMeta(
            id="my-personas",
            name="My Custom Personas",
            version="1.0.0",
            plugin_type=PluginType.PERSONAS,
            description="Custom domain-specific personas",
            author="My Team",
        )

    def get_persona_paths(self) -> list[Path]:
        return [Path(__file__).parent / "data" / "personas.yaml"]

PluginRegistry¶

from fcc.plugins.registry import PluginRegistry

Method	Signature	Returns	Description
`discover()`	`()`	DiscoveryResult	Scan entry points and load plugins
`get_plugins()`	`(plugin_type: PluginType)`	list	Get all plugins of a type
`get_plugin()`	`(plugin_id: str)`	Any	Get plugin by ID
`has_plugin()`	`(plugin_id: str)`	bool	Check if plugin exists
`all_plugins()`	`()`	list	Get all loaded plugins
`plugin_count`	property	int	Total loaded plugins

Usage¶

from fcc.plugins.registry import PluginRegistry
from fcc.plugins.base import PluginType

registry = PluginRegistry()
result = registry.discover()
print(f"Discovered: {result.discovered}, Loaded: {result.loaded}")

persona_plugins = registry.get_plugins(PluginType.PERSONAS)
for plugin in persona_plugins:
    meta = plugin.plugin_meta()
    print(f"  {meta.id}: {meta.name} v{meta.version}")

DiscoveryResult¶

from fcc.plugins.registry import DiscoveryResult

Field	Type	Description
`discovered`	int	Total entry points found
`loaded`	int	Successfully loaded
`errors`	list[str]	Error messages for failed plugins

CrossPluginOrchestrator¶

from fcc.plugins.orchestration import CrossPluginOrchestrator

Method	Signature	Returns	Description
`add_dependency()`	`(dep: PluginDependency)`	None	Register a dependency
`add_interaction()`	`(interaction: PluginInteraction)`	None	Register an interaction
`resolve_dependencies()`	`(plugin_id: str)`	list[PluginDependency]	Dependencies for a plugin
`reverse_dependencies()`	`(plugin_id: str)`	list[PluginDependency]	Dependents of a plugin
`get_interaction_matrix()`	`()`	dict[str, list]	Interactions by source plugin
`get_interactions_for_persona()`	`(persona_id: str)`	list[PluginInteraction]	Interactions for a persona
`validate_interactions()`	`()`	list[str]	Validation errors
`check_health()`	`(statuses: list)`	EcosystemHealthReport	Ecosystem health report
`dependency_count`	property	int	Total dependencies
`interaction_count`	property	int	Total interactions

Orchestration Models¶

PluginDependency¶

Frozen dataclass: source_plugin, target_plugin, dependency_type, description.

PluginInteraction¶

Frozen dataclass: source_persona, source_plugin, target_persona, target_plugin, interaction_type, description.

PluginHealthStatus¶

Frozen dataclass: plugin_id, healthy, persona_count, error.

EcosystemHealthReport¶

Frozen dataclass: total_plugins, healthy_plugins, unhealthy_plugins, total_personas, statuses.

Errors¶

Error	Description
`PluginLoadError`	Plugin failed to load or instantiate
`PluginConflictError`	Two plugins register the same ID
`PluginNotFoundError`	Requested plugin ID not found