Ecosystem API Reference¶

Module: fcc.plugins.orchestration and fcc.data.ecosystem

The ecosystem module manages the FCC plugin ecosystem, including project registration, cross-plugin dependencies, interaction matrices, and health monitoring. Configuration data lives in src/fcc/data/ecosystem/.

flowchart TD
    subgraph Config
        PD[plugin_dependencies.yaml]
        PI[plugin_interactions.yaml]
    end
    PD --> CPO[CrossPluginOrchestrator]
    PI --> CPO
    CPO --> DR[Dependency Resolution]
    CPO --> IM[Interaction Matrix]
    CPO --> HC[Health Check]
    HC --> EHR[EcosystemHealthReport]

Ecosystem Data Files¶

File	Description
`plugin_dependencies.yaml`	Declares inter-plugin dependencies with types and descriptions
`plugin_interactions.yaml`	Maps cross-plugin persona interactions with direction metadata

plugin_dependencies.yaml Structure¶

dependencies:
  - source_plugin: constel
    target_plugin: fcc-core
    dependency_type: provides_taxonomy
    description: "CONSTEL provides knowledge graph taxonomies to FCC core"
  - source_plugin: paom
    target_plugin: fcc-core
    dependency_type: provides_personas
    description: "PAOM contributes additional personas to FCC"

plugin_interactions.yaml Structure¶

interactions:
  - source_persona: OA
    source_plugin: constel
    target_persona: STE
    target_plugin: fcc-core
    interaction_type: peer
    description: "Ontology Architect aligns with Semantic Taxonomy Engineer"

Loading Ecosystem Configuration¶

import yaml
from pathlib import Path
from fcc._resources import get_data_path
from fcc.plugins.orchestration import (
    CrossPluginOrchestrator,
    PluginDependency,
    PluginInteraction,
)

# Load dependencies
deps_path = get_data_path("ecosystem", "plugin_dependencies.yaml")
with deps_path.open() as f:
    deps_data = yaml.safe_load(f)

dependencies = [
    PluginDependency.from_dict(d)
    for d in deps_data.get("dependencies", [])
]

# Load interactions
ints_path = get_data_path("ecosystem", "plugin_interactions.yaml")
with ints_path.open() as f:
    ints_data = yaml.safe_load(f)

interactions = [
    PluginInteraction.from_dict(i)
    for i in ints_data.get("interactions", [])
]

# Create orchestrator
orchestrator = CrossPluginOrchestrator(dependencies, interactions)

CrossPluginOrchestrator¶

See the Plugins API Reference for the full API. Key ecosystem-specific operations:

Dependency Resolution¶

# What does CONSTEL depend on?
deps = orchestrator.resolve_dependencies("constel")
for dep in deps:
    print(f"  {dep.source_plugin} -> {dep.target_plugin} ({dep.dependency_type})")

# Who depends on FCC core?
rdeps = orchestrator.reverse_dependencies("fcc-core")

Interaction Matrix¶

# Get all interactions grouped by source plugin
matrix = orchestrator.get_interaction_matrix()
for plugin_id, interactions in matrix.items():
    print(f"{plugin_id}: {len(interactions)} interactions")

# Get interactions for a specific persona
persona_interactions = orchestrator.get_interactions_for_persona("STE")

Ecosystem Health Check¶

from fcc.plugins.orchestration import PluginHealthStatus

statuses = [
    PluginHealthStatus(plugin_id="fcc-core", healthy=True, persona_count=84),
    PluginHealthStatus(plugin_id="paom", healthy=True, persona_count=30),
]

report = orchestrator.check_health(statuses)
print(f"Total plugins: {report.total_plugins}")
print(f"Healthy: {report.healthy_plugins}")
print(f"Total personas: {report.total_personas}")

# Iterate unhealthy plugins
for status in report.statuses:
    if not status.healthy:
        print(f"  UNHEALTHY: {status.plugin_id} - {status.error}")

Validation¶

errors = orchestrator.validate_interactions()
if errors:
    for err in errors:
        print(f"  Validation error: {err}")
else:
    print("All interactions valid")

EcosystemHealthReport¶

Frozen dataclass summarizing ecosystem health:

Field	Type	Description
`total_plugins`	int	Total plugins in ecosystem
`healthy_plugins`	int	Plugins reporting healthy status
`unhealthy_plugins`	int	Plugins with errors
`total_personas`	int	Sum of persona counts across plugins
`statuses`	tuple[PluginHealthStatus, ...]	Per-plugin status details

Ecosystem Dashboard¶

The ecosystem can be visualized through the CLI dashboard:

fcc dashboard ecosystem

This renders an ASCII table via fcc.dashboard.ecosystem.render_ecosystem_dashboard() showing project names, tiers, maturity, test counts, and port status. See the Dashboard API Reference for details.