Skip to content

Model Card Generation

Duration: 45 minutes Level: Advanced Module: fcc.evaluation.card_generator

This tutorial teaches you how to generate Model Cards (Mitchell et al. 2019) and Datasheets (Gebru et al. 2021) for FCC personas, workflows, and categories. You will produce structured documentation that satisfies regulatory requirements and supports responsible AI practices.

Prerequisites

What Are Model Cards?

Model Cards are short documents that describe an ML model's intended use, performance characteristics, ethical considerations, and limitations. The FCC framework extends this concept to personas, workflows, and categories -- treating each as a "model" that requires transparent documentation.

Step 1: Generate a Single Persona Card

from fcc.evaluation.card_generator import ModelCardGenerator
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_data_dir()
generator = ModelCardGenerator(version="0.9.0")

# Generate a card for the Research Curator
spec = registry.get("RC")
card = generator.from_persona(spec)

print(f"Name: {card.model_name}")
print(f"Type: {card.model_type}")
print(f"Intended use: {card.intended_use}")
print(f"Risk category: {card.risk_category}")
print(f"R.I.S.C.E.A.R.: {card.riscear_summary}")

Step 2: Add Benchmark Metrics

Attach CLEAR+ metrics from a benchmark run:

from fcc.evaluation.runner import BenchmarkRunner
from fcc.evaluation.benchmark import BenchmarkSuite

suite = BenchmarkSuite.from_yaml("src/fcc/data/evaluation/baseline_benchmarks.yaml")
runner = BenchmarkRunner(mock=True)
results = runner.run_suite(suite)

# Map results by persona
benchmarks = {r.spec.name: r for r in results}

# Generate card with metrics
card = generator.from_persona(spec, benchmark=results[0])
print(f"Metrics: {card.metrics.to_dict()}")
print(f"Evaluation: {card.evaluation_results}")

Step 3: Add Constitution and Risk Category

Include constitution information for risk classification:

from fcc.governance.constitution_registry import ConstitutionRegistry

const_reg = ConstitutionRegistry.from_registry(registry)
constitution = const_reg.get("RC")

card = generator.from_persona(spec, constitution=constitution)
print(f"Risk category: {card.risk_category}")
print(f"Constitution: {card.constitution_summary}")

Risk category mapping:

Constitution Profile Risk Category
3+ hard-stop rules HIGH
Any mandatory patterns LIMITED
Only preferred patterns MINIMAL

Step 4: Generate Workflow and Category Cards

# Workflow card
from fcc.workflow.graph import WorkflowGraph

graph = WorkflowGraph.from_json("src/fcc/data/workflows/base_sequence.json")
wf_card = generator.from_workflow(graph, registry)
print(f"Workflow card: {wf_card.model_name}")

# Category card
cat_card = generator.from_category("governance", registry)
print(f"Category card: {cat_card.model_name}")
print(f"Collaborators: {cat_card.collaborators}")

Step 5: Batch Generation

Generate all cards at once (102 persona + 7 workflow + 20 category):

all_cards = generator.from_registry(
    registry,
    benchmarks=benchmarks,
    constitution_registry=const_reg,
)
print(f"Total cards generated: {len(all_cards)}")

Step 6: Render to Markdown

md = generator.render_markdown(card)
print(md[:500])

The Markdown output includes front matter, overview, intended use, R.I.S.C.E.A.R. summary, CLEAR+ metrics table, constitution tiers, collaborator list, ethical considerations, and limitations.

Step 7: Batch Write to Disk

count = generator.batch_render(
    all_cards,
    "output/model_cards",
    fmt="markdown",
)
print(f"Written {count} model card files")

This creates: - output/model_cards/personas/ -- 102 persona cards - output/model_cards/workflows/ -- 7 workflow cards - output/model_cards/categories/ -- 20 category cards

Step 8: Generate a Datasheet

datasheet = generator.generate_datasheet("FCC Persona Dataset", registry)
print(f"Dataset: {datasheet.dataset_name}")
print(f"Composition: {datasheet.composition}")
print(f"Ethical considerations: {datasheet.ethical_considerations}")

The datasheet follows the 12-section structure from Gebru et al. 2021, covering purpose, composition, collection process, preprocessing, uses, distribution, maintenance, ethics, and limitations.

Step 9: JSON Output

For programmatic consumption, render as JSON:

json_str = ModelCardGenerator.render_json(card)
print(json_str[:300])

Best Practices

  1. Generate cards with every release -- Include card generation in CI
  2. Always include limitations -- Every persona has constraints
  3. Review risk categories -- Re-run classification when constitutions change
  4. Pair with datasheets -- Model cards describe the model; datasheets describe the data
  5. Keep cards versioned -- The model_version field should match the package version

Summary

In this tutorial you learned how to:

  • Generate model cards for personas, workflows, and categories
  • Attach CLEAR+ benchmark metrics to cards
  • Map constitutions to EU AI Act risk categories
  • Render cards as Markdown or JSON
  • Batch-generate all cards for the full registry
  • Generate datasheets for persona datasets

Next Steps