Skip to content

Chapter 7: Getting Started

Learning Objectives

By the end of this chapter you will be able to:

  1. Install the FCC package from source with development dependencies.
  2. Run the test suite and verify your installation.
  3. Execute your first FCC simulation using the mock engine.
  4. Generate documentation for a persona using the CLI.
  5. Explore the persona catalog and workflow graphs interactively.

The flowchart below walks through the end-to-end setup path: installing Python, cloning the repository, creating a virtual environment, verifying tests, and running a first mock simulation.

flowchart TD
    START[Start] --> Q1{Python 3.10+?}
    Q1 -->|No| INST1[Install Python 3.10+]
    Q1 -->|Yes| CLONE[Clone Repository]
    INST1 --> CLONE
    CLONE --> VENV[Create Virtual Environment]
    VENV --> INSTALL[pip install -e .'dev']
    INSTALL --> VERIFY{Tests Pass?}
    VERIFY -->|No| FIX[Check Python version & deps]
    FIX --> VERIFY
    VERIFY -->|Yes| EXPLORE[Explore Persona Catalog]
    EXPLORE --> SIM[Run Mock Simulation]
    SIM --> DOCS[Generate Documentation]
    DOCS --> READY[Ready to Build]

    style START fill:#9C27B0,color:#fff
    style READY fill:#4CAF50,color:#fff

The loop at the tests-pass gate is deliberate: it catches environment issues (missing optional deps, wrong Python version) before you invest time authoring personas or workflows.

Prerequisites

Before you begin, make sure you have:

  • Python 3.10 or later. Check with python --version.
  • pip (latest version). Upgrade with pip install --upgrade pip.
  • Git for cloning the repository.
  • A terminal (bash, zsh, or PowerShell).

Optional but recommended:

  • Make for convenience commands.
  • Jupyter for running the companion notebooks.

Step 1: Clone and Install

Clone the repository and install the package in development mode:

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext

# Option A: Using Make (recommended)
make venv && source .venv/bin/activate
make install-dev

# Option B: Manual
python -m venv .venv
source .venv/bin/activate    # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

The -e flag installs the package in "editable" mode, meaning changes to the source code take effect immediately without reinstalling. The [dev] extra pulls in test and development dependencies (pytest, ruff, etc.).

Verify Installation

python -c "import fcc; print(fcc.__version__)"
# Expected output: 0.7.0

If you see the version number, the package is installed correctly.

Step 2: Run the Test Suite

The test suite is the fastest way to verify that everything works:

# Option A: Using Make
make test

# Option B: Direct pytest
pytest tests/ -x --tb=short

You should see 6,179 tests passing. The -x flag stops at the first failure, and --tb=short keeps the output readable.

If tests fail, check:

  1. You are using Python 3.10+.
  2. You installed with [dev] extras.
  3. Your virtual environment is activated.

Step 3: Explore the Persona Catalog

The FCC CLI provides a dashboard for exploring the persona catalog:

fcc dashboard personas

This displays an ASCII table of all 102 core personas, 45 vertical personas, and 23 plugin personas, organized by category. You can filter by category, FCC phase, or champion status.

To inspect a specific persona's R.I.S.C.E.A.R. specification:

fcc validate --persona research_analyst

This loads the persona's YAML definition, validates it against the JSON schema, and displays its full specification.

Programmatic Access

If you prefer Python over the CLI:

from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry()
registry.load_all()

# List all personas
for persona in registry.all():
    print(f"{persona.id}: {persona.spec.role}")

# Get a specific persona
analyst = registry.get("research_analyst")
print(analyst.spec.role)
print(analyst.spec.constraints)

# Filter by category
data_personas = registry.by_category("data_engineering")
for p in data_personas:
    print(f"  {p.id}")

# Find champions
champions = registry.champions()
for c in champions:
    print(f"  {c.id} champions {c.champion_of}, orchestrates {c.orchestrates}")

Step 4: Run Your First Simulation

A simulation executes a workflow graph with personas producing outputs at each node. The mock engine generates deterministic outputs (no AI API calls required):

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

# Load a starter scenario
loader = ScenarioLoader()
scenario = loader.load("competitive_analysis")

# Create engine in mock mode
engine = SimulationEngine(mode="mock")

# Run the simulation
result = engine.run(scenario)

# Inspect the trace
for step in result.trace.steps:
    print(f"Node: {step.node_id}")
    print(f"Persona: {step.persona_id}")
    print(f"Phase: {step.phase}")
    print(f"Output preview: {step.output[:100]}...")
    print()

The mock engine is deterministic -- running the same scenario twice produces the same trace. This makes it ideal for testing and development.

AI-Powered Simulation

To use real AI models, configure your API keys and switch to AI mode:

# Set your API key (Anthropic or OpenAI)
export ANTHROPIC_API_KEY="your-key-here"
# or
export OPENAI_API_KEY="your-key-here"

engine = SimulationEngine(mode="ai", provider="anthropic")
result = engine.run(scenario)

AI-powered simulations produce richer, more varied outputs but require API access and incur costs. Start with mock mode until you are comfortable with the workflow.

Step 5: Generate Documentation

The docs-as-code generator produces comprehensive documentation for personas:

# Generate docs for all personas
fcc generate-docs --output-dir ./generated_docs

# Generate docs for a specific persona
fcc generate-docs --persona research_analyst --output-dir ./generated_docs

The generator produces up to 56 files per persona, including:

  • R.I.S.C.E.A.R. specification pages
  • Dimension profiles
  • Cross-reference maps
  • Collaboration guides
  • Archetype interaction guides

Explore the Generated Docs

ls generated_docs/research_analyst/
# riscear.md  dimensions.md  cross_references.md  collaboration.md  ...

Each file uses Jinja2 templates from src/fcc/templates/docs/, which you can customize for your organization's style.

Step 6: Try the Streamlit Apps (Optional)

If you have Streamlit installed, the interactive apps provide visual exploration:

pip install streamlit plotly

# Persona explorer
streamlit run apps/streamlit/persona_explorer.py

# Workflow visualizer
streamlit run apps/streamlit/workflow_visualizer.py

These apps let you browse personas, visualize workflow graphs, and run simulations through a web interface.

Step 7: Open a Notebook (Optional)

The companion Jupyter notebooks provide guided, interactive explorations:

pip install jupyter notebook matplotlib pandas

jupyter notebook notebooks/

Start with Notebook 01: Getting Started, which walks through the same steps as this chapter but with inline visualizations and interactive cells.

Troubleshooting

Problem Solution
ModuleNotFoundError: No module named 'fcc' Activate your virtual environment and install with pip install -e .
Tests fail with import errors Ensure you installed with [dev] extras
CLI commands not found Ensure the package is installed (the CLI is registered via entry points)
Streamlit apps fail to start Install optional extras: pip install streamlit plotly
Notebooks fail with missing dependencies Install optional extras: pip install jupyter matplotlib pandas

Key Takeaways

  • Install FCC with pip install -e ".[dev]" for development or pip install -e . for core use.
  • The test suite (6,179 tests) is the fastest verification that everything works.
  • The mock simulation engine requires no API keys and produces deterministic results.
  • The CLI provides dashboards, validation, and documentation generation.
  • Streamlit apps and Jupyter notebooks offer visual and interactive alternatives.

Cross-References

← Chapter 6: Ecosystem Overview | Next: Chapter 8 -- Where to Go Next →