Skip to content

Developer Quick Start

This page is the developer's five-minute on-ramp. It assumes you are comfortable with Python packaging, virtual environments, and the command line, and that your goal is to see FCC's moving parts in action quickly so you can decide how to wire them into your own code. If you want a more hand-holding introduction, start with Hello FCC instead.

Step 1 — install

FCC is a standard editable Python package. Clone, create a virtual environment, and install with the [full] umbrella extra so the Docker-compatible surface (notebooks, Streamlit, search, knowledge, RAG, Ollama, LiteLLM) is available from the start.

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext
python -m venv .venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate
pip install -e ".[full]"

Verify:

python -c "import fcc; print(fcc.__version__)"
fcc --help

The CLI entry point is declared in pyproject.toml and src/fcc/scaffold/cli.py is where it lives.

Step 2 — load a persona and a workflow

Open a Python shell and pull the registry straight from the packaged data. No configuration file or environment variable is required.

from fcc.personas.registry import PersonaRegistry
from fcc._resources import get_personas_dir

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
print(f"Loaded {len(registry)} personas")

sample = registry.get("research_catalyst")
print(sample.name, sample.fcc_phase, sample.category)
print(sample.riscear.role)

Expected output (exact counts depend on the FCC version you have installed; for v1.3.x it is 147):

Loaded 147 personas
Research Catalyst Find ...
...

Step 3 — run a mock simulation

FCC ships a deterministic mock simulation engine that requires no API key. Mock mode is the right choice for CI, for a first integration test, and for reproducible tutorials.

from fcc.simulation.engine import SimulationEngine
from fcc.scenarios.loader import ScenarioLoader

scenarios = ScenarioLoader.from_package_data()
scenario = scenarios.get("basic_fcc_cycle")

engine = SimulationEngine(registry=registry, mode="mock")
trace = engine.run(scenario)

print(f"Steps: {len(trace.steps)} · duration_ms: {trace.duration_ms}")
for step in trace.steps[:3]:
    print(f"  [{step.phase}] {step.persona_id}: {step.summary[:60]}")

The trace is deterministic — re-running the same scenario produces identical step summaries, so you can snapshot-test against it.

Step 4 — subscribe to events

Wire the event bus so you can see what the engine is emitting. This is the same bus the AURORA visualizer and the compliance subscriber listen to.

from fcc.messaging.bus import EventBus
from fcc.messaging.events import EventType

bus = EventBus()

def log_event(event):
    print(f"{event.type.value} · {event.source}")

bus.subscribe_all(log_event)

engine = SimulationEngine(registry=registry, mode="mock", event_bus=bus)
engine.run(scenario)

FCC defines 81 event types under src/fcc/messaging/events.py; the bus is thread-safe and supports filtering, serialization, and replay.

Step 5 — decide where to go next

You have touched all four load-bearing subsystems: the persona registry, the simulation engine, the scenario loader, and the event bus. From here the three developer journeys diverge.

  • Developer landing — the three journeys in context.
  • Testing Guide — how to test the code you just wrote.
  • Architecture — Development View — the package layout behind everything above.
  • Notebook 01_fcc_fundamentals.ipynb — interactive companion.
  • Notebook 34_developer_first_plugin.ipynb — the plugin-authoring follow-up.