API Reference¶

The FCC (Find, Create, Critique) Agent Team Framework exposes a Python API organized into six modules. Install the package in editable mode and import directly -- no sys.path manipulation required.

pip install -e .

Resource Helpers¶

Every data path used by the library is resolved through fcc._resources. Use these helpers instead of hard-coding paths so your code works regardless of installation location.

from fcc._resources import (
    get_data_dir,        # root data/ directory
    get_personas_dir,    # data/personas/
    get_schemas_dir,     # data/schemas/
    get_workflows_dir,   # data/workflows/
    get_scenarios_dir,   # data/scenarios/
    get_governance_dir,  # data/governance/
    get_docs_data_dir,   # data/docs/
    get_templates_dir,   # templates/ (Jinja2)
)

Quick Reference¶

Module	Class / Function	Import Path	Purpose
personas	`PersonaSpec`	`fcc.personas.models`	Immutable persona dataclass (frozen)
	`RISCEARSpec`	`fcc.personas.models`	10-component R.I.S.C.E.A.R. specification
	`RatingDimensions`	`fcc.personas.models`	7-dimension rating model
	`DiscernmentTrait`	`fcc.personas.models`	Discernment Matrix trait
	`DesignTargetFactor`	`fcc.personas.models`	Design Target Factor
	`Deliverable`	`fcc.personas.models`	Named deliverable
	`Collaboration`	`fcc.personas.models`	Collaboration link
	`PersonaRegistry`	`fcc.personas.registry`	Load, query, merge persona collections
	`CrossReferenceEntry`	`fcc.personas.cross_reference`	Single persona-to-persona interaction
	`CrossReferenceMatrix`	`fcc.personas.cross_reference`	Queryable interaction map
	`DimensionAttribute`	`fcc.personas.dimensions`	Attribute within a dimension
	`PersonaDimension`	`fcc.personas.dimensions`	Named dimension with attributes
	`PersonaDimensionProfile`	`fcc.personas.dimensions`	Full 9-category, 56-dimension profile
	`DimensionRegistry`	`fcc.personas.dimensions`	Canonical dimension definitions
workflow	`WorkflowNode`	`fcc.workflow.models`	Node in the workflow graph
	`WorkflowEdge`	`fcc.workflow.models`	Directed edge (handoff / feedback)
	`WorkflowMeta`	`fcc.workflow.models`	Graph metadata
	`WorkflowGraph`	`fcc.workflow.graph`	In-memory graph with traversal
simulation	`Message`	`fcc.simulation.messages`	Message flowing through the graph
	`MessageHistory`	`fcc.simulation.messages`	Collected trace of simulation events
	`SimulationEngine`	`fcc.simulation.engine`	Deterministic BFS simulator
	`AISimulationEngine`	`fcc.simulation.ai_engine`	AI-powered simulator
	`AISimulationResult`	`fcc.simulation.ai_engine`	Result of an AI simulation run
	`AIClient`	`fcc.simulation.ai_client`	Unified multi-provider AI client
	`AIProvider`	`fcc.simulation.ai_client`	Provider enum (OpenAI, Anthropic, Azure, Mock)
	`AIResponse`	`fcc.simulation.ai_client`	Structured AI response
	`PromptTemplate`	`fcc.simulation.prompts`	Renderable prompt with variable substitution
	`get_prompt_for_persona`	`fcc.simulation.prompts`	Default prompt for a persona ID
	`build_persona_system_prompt`	`fcc.simulation.prompts`	Rich system prompt from R.I.S.C.E.A.R.
scenarios	`ScenarioLoader`	`fcc.scenarios.loader`	Load and query scenario JSON files
	`FCCValidator`	`fcc.scenarios.validators`	Rule-based validation framework
	`ValidationResult`	`fcc.scenarios.models`	Single validation result
	`ValidationSeverity`	`fcc.scenarios.models`	Severity enum
governance	`Tag`	`fcc.governance.tags`	Capability tag with hierarchy
	`TagRegistry`	`fcc.governance.tags`	YAML-driven tag registry
	`QualityGate`	`fcc.governance.quality_gates`	Quality gate definition
	`GateResult`	`fcc.governance.quality_gates`	Gate execution result
	`QualityGateRunner`	`fcc.governance.quality_gates`	Load and execute quality gates
scaffold	`DocGenerator`	`fcc.scaffold.doc_generator`	Docs-as-code generator
	`get_jinja_env`	`fcc.scaffold.engine`	Jinja2 environment factory
	`render_template`	`fcc.scaffold.engine`	Render a single template
	`render_to_file`	`fcc.scaffold.engine`	Render and write to disk

Minimal Working Example¶

from fcc._resources import get_personas_dir, get_workflows_dir
from fcc.personas.registry import PersonaRegistry
from fcc.workflow.graph import WorkflowGraph
from fcc.simulation.engine import SimulationEngine

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

# Load the base workflow and run a deterministic simulation
graph = WorkflowGraph.from_json(get_workflows_dir() / "base_sequence.json")
engine = SimulationEngine(graph)
history = engine.run(start_node="RC", initial_payload="API migration plan")

for event in history.events:
    print(f"  Step {event['step']}: {event['actor']}")

Module-by-Module Documentation¶

Personas -- PersonaSpec, RISCEARSpec, PersonaRegistry, CrossReferenceMatrix, DimensionRegistry
Workflow -- WorkflowGraph, traversal, edge types
Simulation -- SimulationEngine, AISimulationEngine, AIClient, prompts
Scenarios -- ScenarioLoader, FCCValidator
Governance -- TagRegistry, QualityGateRunner
Scaffold -- DocGenerator, template engine, CLI programmatic equivalents