Entity Simulation

def detect_entity_gap(query, existing_entities):
    referenced = extract_entity_names(query)
    missing = referenced - set(existing_entities)
    return missing

def generate_entity_on_demand(name, context):
    # LLM generates plausible entity given scenario context
    # Falls back to minimal entity creation on failure

class EnvironmentEntity(SQLModel, table=True):
    scene_id: str = Field(primary_key=True)
    timepoint_id: str = Field(foreign_key="timepoint.timepoint_id")
    location: str
    capacity: int
    ambient_temperature: float
    lighting_level: float  # 0.0-1.0 (dark to bright)
    weather: str | None = None
    architectural_style: str | None = None
    acoustic_properties: str | None = None  # "reverberant", "muffled", etc.

class AtmosphereEntity(SQLModel, table=True):
    scene_id: str = Field(primary_key=True)
    timepoint_id: str = Field(foreign_key="timepoint.timepoint_id")
    tension_level: float  # 0.0-1.0 (calm to tense)
    formality_level: float  # 0.0-1.0 (casual to formal)
    emotional_valence: float  # -1.0 to 1.0 (negative to positive)
    emotional_arousal: float  # 0.0-1.0 (calm to excited)
    social_cohesion: float  # 0.0-1.0 (divided to united)
    energy_level: float  # 0.0-1.0 (lethargic to energetic)

class CrowdEntity(SQLModel, table=True):
    scene_id: str = Field(primary_key=True)
    timepoint_id: str = Field(foreign_key="timepoint.timepoint_id")
    size: int  # Number of people present
    density: float  # 0.0-1.0 (sparse to crowded)
    mood_distribution: str = Field(sa_column=Column(JSON))  # Dict[str, float]: mood -> percentage
    movement_pattern: str  # "static", "flowing", "agitated", "orderly"
    demographic_composition: str | None = Field(default=None)
    noise_level: float  # 0.0-1.0 (quiet to loud)

steering → character → quality_gate → conditional
                                       ├→ steering (continue)
                                       ├→ END (complete)
                                       └→ character (retry)

class DialogTurn(BaseModel):
    speaker: str  # entity_id of speaker
    content: str  # what was said
    timestamp: datetime
    emotional_tone: str | None = None  # inferred emotional tone
    knowledge_references: list[str] = []  # knowledge items referenced
    confidence: float | None = 1.0  # confidence in generation
    physical_state_influence: str | None = None  # how physical state affected speech

def filter_knowledge_by_causal_time():
    # Walk Timepoint.causal_parent chain
    ancestor_timepoint_ids = build_ancestor_set(current_timepoint)
    
    # Strip any knowledge from causally inaccessible timepoints
    filtered_knowledge = [
        item for item in knowledge_items
        if item.timepoint_id in ancestor_timepoint_ids
    ]
    
    return filtered_knowledge

def strip_backwards_emotions():
    # Remove items referencing future events emotionally
    # Characters can't fear events that haven't happened in their timeline

1. entity_metadata → personality_traits
   ["analytical", "reserved", "pragmatic"]

2. personality_traits → speaking_style
   {verbosity: "terse", formality: "formal", tone: "neutral", 
    vocabulary: "technical", speech_pattern: "direct"}

3. speaking_style × emotional_state → dialog_params
   {turn_length: 80, interruption_freq: 0.1, focus: "task"}

4. All → PersonaParams → per-character LLM call
   {temperature: 0.7, top_p: 0.9, max_tokens: 150, ...}

class DialogData(BaseModel):
    turns: list[DialogTurn]
    total_duration: int | None = None  # estimated duration in seconds
    information_exchanged: list[str] = []  # knowledge items passed between entities
    relationship_impacts: dict[str, float] = {}  # entity_pair -> delta
    atmosphere_evolution: list[dict[str, float]] = []  # atmosphere changes over time

class RelationshipMetrics:
    shared_knowledge: Set[str]
    belief_alignment: float
    interaction_count: int
    trust_level: float
    power_dynamic: float

def analyze_relationship_evolution(entity_a, entity_b, timespan):
    # Track how relationship metrics change over timepoints
    
def detect_contradictions(entities, timepoint):
    # Find belief conflicts between entities

class ProspectiveState:
    entity_id: str
    forecast_horizon: timedelta
    expectations: List[Expectation]
    contingency_plans: Dict[str, List[Action]]
    anxiety_level: float
    # Extended proception (post-dialog)
    withheld_knowledge: List[Dict]       # What they chose not to say
    suppressed_impulses: List[Dict]      # What they wanted to do but held back
    episodic_memory: List[Dict]          # Personality-filtered dialog memories
    rumination_topics: List[Dict]        # Recurring concerns (decay/intensify)

class AnimismLevel:
    0: Only humans
    1: Humans + animals/buildings
    2: All objects/organisms  
    3: Abstract concepts
    4: Adaptive (AnyEntity)
    5: Spiritual (KamiEntity)
    6: AI agents

{
  "animism_level": 2,
  "entity_roster": [
    {"entity_id": "commander_tanaka", "entity_type": "human"},
    {"entity_id": "meridian_ship", "entity_type": "vehicle"},
    {"entity_id": "alien_biosphere", "entity_type": "environment"}
  ]
}