Skip to content

Hello FCC

Your very first FCC program. This tutorial takes about 5 minutes and requires no API keys or external services.

Prerequisites

If you have not installed FCC yet, here is the quickest way:

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 .

Step 1: Verify Installation

Open a Python interpreter and check that FCC is installed:

import fcc
print(f"FCC version: {fcc.__version__}")

You should see: FCC version: 1.0.1

Step 2: Meet Your First Persona

A persona is a predefined AI "expert" with a specific role, style, and set of skills. FCC comes with 102 built-in personas. Let us meet one:

from fcc.personas.registry import PersonaRegistry

# Load all built-in personas
registry = PersonaRegistry.from_package_data()

# How many personas are there?
print(f"Total personas: {len(registry.all())}")

# Get a specific persona
persona = registry.get("research_catalyst")
print(f"\nMeet: {persona.name}")
print(f"Category: {persona.category}")
print(f"Role: {persona.riscear.role}")

Step 3: Explore Categories

Personas are organized into 20 categories. Each category groups personas with similar expertise:

categories = sorted(registry.categories())
print(f"\nThere are {len(categories)} categories:\n")

for cat in categories:
    count = len(registry.by_category(cat))
    print(f"  {cat}: {count} personas")

Step 4: Run Your First Simulation

A simulation runs a scenario through the FCC cycle using selected personas. The "mock" mode works without any API keys:

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

# Load scenarios
scenarios = ScenarioLoader.from_package_data()

# Pick a simple scenario
scenario = scenarios.get("basic_fcc_cycle")
print(f"\nScenario: {scenario.title}")

# Create a simulation engine in mock mode (no API key needed)
engine = SimulationEngine(registry=registry, mode="mock")

# Run it
trace = engine.run(scenario)

# See the results
print(f"\nSimulation completed in {trace.duration_ms}ms")
print(f"Steps taken: {len(trace.steps)}\n")

for step in trace.steps:
    print(f"  [{step.phase}] {step.persona_id}")
    print(f"    {step.summary[:70]}...")
    print()

Step 5: What Just Happened?

Let us break down what you just did:

  1. Loaded personas: The PersonaRegistry loaded 102 persona definitions from YAML files bundled with the package.

  2. Loaded a scenario: The ScenarioLoader loaded a pre-defined scenario that specifies which personas to use and in what order.

  3. Ran a simulation: The SimulationEngine in "mock" mode executed each step of the scenario, producing deterministic (reproducible) output.

  4. Inspected the trace: The trace captures every step of the simulation, including which persona acted, what phase it was in (FIND, CREATE, or CRITIQUE), and a summary of the output.

What Next?

You have just completed your first FCC interaction. Here are some next steps:

  • Learn the vocabulary: Read the Glossary to understand key FCC terms.
  • Take a visual tour: See the Visual Tour to explore the web frontend.
  • Try more prompts: See SAMPLE_PROMPTS.md beginner prompts B1-B10.
  • Go deeper: Open notebooks/01_fcc_fundamentals.ipynb in Jupyter for an interactive guide.
  • Full setup: Follow GETTING_STARTED.md for all installation options and advanced features.

Troubleshooting

"ModuleNotFoundError: No module named 'fcc'" - Make sure you activated your virtual environment: source .venv/bin/activate - Make sure you installed FCC: pip install -e .

"KeyError: 'basic_fcc_cycle'" - Make sure you cloned the full repository (the scenarios are in src/fcc/data/scenarios/)

"PermissionError" on Windows - Try running your terminal as Administrator - Use python -m venv .venv instead of make venv