Concordia

Game Master components control the simulation flow. To implement a custom GM, you must create a class that inherits from entity_component.ContextComponent and entity_component.ComponentWithLogging.

The core logic resides in the pre_act method, which reacts to different action_spec.output_type values to manage various simulation phases (e.g., generating observations, determining the next actor, or resolving actions).

To use your custom component, you must register it in the components_of_game_master dictionary using the appropriate component keys (e.g., gm_components.make_observation.DEFAULT_MAKE_OBSERVATION_COMPONENT_KEY).

import dataclasses
from concordia.typing import entity as entity_lib
from concordia.typing import entity_component

class MyGameMasterComponent(
    entity_component.ContextComponent,
    entity_component.ComponentWithLogging,
):
    def __init__(
        self,
        acting_player_names: list[str],
        components: list[str] = (),
        pre_act_label: str = "\nMyComponent",
    ):
        super().__init__()
        self._acting_player_names = acting_player_names
        self._components = components
        self._pre_act_label = pre_act_label
        self._state = {"round": 0}
    
    def get_pre_act_label(self) -> str:
        return self._pre_act_label
    
    def get_pre_act_value(self) -> str:
        return f"Current round: {self._state['round']}"
    
    def pre_act(self, action_spec: entity_lib.ActionSpec) -> str:
        """Handle different output types from the simulation engine."""
        output_type = action_spec.output_type
        
        if output_type == entity_lib.OutputType.MAKE_OBSERVATION:
            return self._handle_make_observation(action_spec)
        elif output_type == entity_lib.OutputType.NEXT_ACTION_SPEC:
            return self._handle_next_action_spec(action_spec)
        elif output_type == entity_lib.OutputType.NEXT_ACTING:
            return self._handle_next_acting()
        elif output_type == entity_lib.OutputType.RESOLVE:
            return self._resolve(action_spec)
        elif output_type == entity_lib.OutputType.NEXT_GAME_MASTER:
            return self._handle_next_gm()
        else:
            return ""

Game Master (GM) prefabs build the directors that control the environment, NPCs, and simulation logic. They are categorized by purpose:

General Purpose

• generic.py: Highly configurable via parameters; supports custom thought chains.
• situated.py: Manages world state, locations, and a "Story so far".
• situated_in_time_and_place.py: An extension of situated.py using a GenerativeClock to track time passage.

Scenario Specific

• dialogic.py: Specialized for conversation; ends repetitive dialogues.
• dialogic_and_dramaturgic.py: Manages structured "Scenes" (e.g., Prologue, Episode 1).
• game_theoretic_and_dramaturgic.py: For matrix games/social dilemmas; maps joint actions to scores.
• marketplace.py: Tuned for economic simulations with market transaction handling.
• psychology_experiment.py: A harness for injecting custom observation and action components.
• interviewer.py: Administers fixed multiple-choice questionnaires.
• open_ended_interviewer.py: Administers free-form text questionnaires.
• scripted.py: Follows a strict, fixed script; useful for generating data for fine-tuning.

Utility

• formative_memories_initializer.py: A special GM used with Role.INITIALIZER to implant memories into agents before the main simulation loop begins.

An LLM autorater is an automated evaluation system that uses a structured rubric to grade the quality of a Concordia simulation. Instead of manual human review, the autorater processes structured simulation logs to produce a graded report.

The workflow is:

1. Manual Review: Perform an initial manual review of a simulation run to identify quality signals and failure modes.
2. Codify Rubric: Create a markdown document defining scoring dimensions (e.g., Behavioral Realism), scoring criteria (1-5 scales), data extraction recipes, and known failure modes.
3. Automate: Provide the rubric and the simulation log to an LLM to generate an automated analysis.
4. Scale: Run the process across multiple experiments, models, or architectures to compare performance.

Autoraters are particularly useful for identifying failure modes like repetition loops, NPC hallucinations, or temporal incoherence and for comparing different LLM backends (e.g., comparing gemma-27b vs gemini-pro) using a standardized comparison table.

For complex behaviors, chain components so that one component's output serves as context for another. This allows for 'Chain of Thought' reasoning.

Key reasoning components include:

• SituationRepresentation: Summarizes the current situation using recent observations and relevant memories.
• QuestionOfRecentMemories: Asks the model a specific question (e.g., an 'Internal Monologue') based on the current context.

When assembling the components dictionary, ensure the component_order in ConcatActComponent matches the logical dependency (e.g., situation_representation must appear before the component that depends on it).

from concordia.contrib.components.agent import situation_representation_via_narrative
from concordia.components import agent as agent_components

@dataclasses.dataclass
class ReflectiveAgent(prefab_lib.Prefab):
    def build(self, model, memory_bank):
        name = self.params.get("name", "Agent")
        
        # 1. Base Components
        instructions = agent_components.instructions.Instructions(
            agent_name=name)
        observation = agent_components.observation.LastNObservations(
            history_length=100)
        memory = agent_components.memory.AssociativeMemory(
            memory_bank=memory_bank)
        
        # 2. Advanced Components (Chain of Thought)
        
        # Step A: Summarize the situation
        situation = situation_representation_via_narrative.SituationRepresentation(
            model=model,
            observation_component_key=agent_components.observation.DEFAULT_OBSERVATION_COMPONENT_KEY,
            declare_entity_as_protagonist=True,
        )
        
        # Step B: Apply a Guiding Principle (uses Step A context)
        principle = agent_components.question_of_recent_memories.QuestionOfRecentMemories(
            model=model,
            pre_act_label=f"{name}'s Internal Monologue",
            question=f"How can {name} best achieve their goals in this situation?",
            answer_prefix=f"{name} thinks: ",
            add_to_memory=False, # Don't clutter memory with every thought
            components=[
                "Instructions",
                "situation_representation" # <--- Depends on Step A
            ],
        )

        # 3. Assemble Components (Order matters!)
        components = {
            "Instructions": instructions,
            agent_components.memory.DEFAULT_MEMORY_COMPONENT_KEY: memory,
            agent_components.observation.DEFAULT_OBSERVATION_COMPONENT_KEY: observation,
            "situation_representation": situation,
            "guiding_principle": principle,
        }
        
        # The Act Component sees everything in 'components'
        act_component = agent_components.concat_act_component.ConcatActComponent(
            model=model,
            component_order=list(components.keys()),
        )
        
        return entity_agent_with_logging.EntityAgentWithLogging(
            agent_name=name,
            act_component=act_component,
            context_components=components,
        )