AI Module

The AI module contains personality, character classes, goals, and decision-making.

Personality

class simulation_framework.src.ai.personality.Personality(curiosity: 'float' = 0.5, bravery: 'float' = 0.5, sociability: 'float' = 0.5, greed: 'float' = 0.5, patience: 'float' = 0.5, aggression: 'float' = 0.3, industriousness: 'float' = 0.5, caution: 'float' = 0.5)

Bases: object

aggression: float = 0.3

bravery: float = 0.5

caution: float = 0.5

classmethod create_archetype(archetype: str) → Personality

Create personality based on common archetypes

curiosity: float = 0.5

classmethod from_dict(data: Dict[str, float]) → Personality

get_action_modifier(action_type: str) → float

Get personality modifier for different action types

get_dominant_traits(threshold: float = 0.6) → list[str]

Return traits that are above the threshold

get_exploration_desire(known_area_percentage: float) → float

Calculate desire to explore based on how much is known

get_risk_tolerance() → float

Calculate overall risk tolerance (0-1)

get_social_preference() → float

Calculate preference for social interactions

greed: float = 0.5

industriousness: float = 0.5

patience: float = 0.5

classmethod randomize(seed: int | None = None) → Personality

should_engage_in_combat(enemy_strength: float, own_strength: float, potential_loot_value: float = 0.0) → bool

Determine if agent should engage in combat

should_initiate_trade(potential_profit: float, relationship: float = 0.5) → bool

Determine if agent should initiate a trade

similarity_to(other: Personality) → float

Calculate similarity between two personalities (0-1, higher is more similar)

sociability: float = 0.5

to_dict() → Dict[str, float]

Character Class

class simulation_framework.src.ai.character_class.CharacterClass(name: 'str', description: 'str', skill_affinities: 'Dict[str, float]' = <factory>, preferred_actions: 'List[str]' = <factory>, starting_stats_bonus: 'Dict[str, int]' = <factory>, equipment_preferences: 'List[str]' = <factory>)

Bases: object

calculate_effectiveness(activity_type: str, skill_levels: Dict[str, int]) → float

Calculate how effective this class is at a given activity

classmethod create_alchemist() → CharacterClass

classmethod create_blacksmith() → CharacterClass

classmethod create_explorer() → CharacterClass

classmethod create_farmer() → CharacterClass

classmethod create_hunter() → CharacterClass

classmethod create_mage() → CharacterClass

classmethod create_trader() → CharacterClass

classmethod create_warrior() → CharacterClass

description: str

equipment_preferences: List[str]

classmethod from_dict(data: Dict[str, Any]) → CharacterClass

get_action_preference(action_type: str) → float

Get preference modifier for action types (0.5-1.5)

get_class_specialization() → str

Get the primary specialization of this class

get_preferred_biome() → str | None

Get the preferred biome for this class

get_skill_modifier(skill_name: str) → float

Get multiplier for skill experience gain

get_starting_equipment() → List

Get list of starting items for this class

get_stat_bonus(stat_name: str) → int

Get starting stat bonus for this class

is_preferred_skill(skill_name: str) → bool

Check if this skill is preferred by this class

name: str

preferred_actions: List[str]

skill_affinities: Dict[str, float]

starting_stats_bonus: Dict[str, int]

to_dict() → Dict[str, Any]

class simulation_framework.src.ai.character_class.SkillType(value)

Bases: Enum

An enumeration.

ARCHERY = 'archery'

COMBAT = 'combat'

CRAFTING = 'crafting'

EXPLORATION = 'exploration'

FISHING = 'fishing'

FORAGING = 'foraging'

MAGIC = 'magic'

MINING = 'mining'

TRADING = 'trading'

WOODCUTTING = 'woodcutting'

simulation_framework.src.ai.character_class.get_character_class(name: str) → CharacterClass | None

Get a character class by name

simulation_framework.src.ai.character_class.get_random_character_class() → CharacterClass

Get a random character class

Goals

class simulation_framework.src.ai.goal.AttackEnemyGoal(target_id: int, priority: int = 8)

Bases: Goal

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

class simulation_framework.src.ai.goal.CraftItemGoal(item_name: str, quantity: int = 1, priority: int = 5)

Bases: Goal

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

class simulation_framework.src.ai.goal.ExploreGoal(target_area: Tuple[int, int, int] | None = None, priority: int = 4)

Bases: Goal

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

class simulation_framework.src.ai.goal.FleeFromDangerGoal(danger_source_id: int, priority: int = 9)

Bases: Goal

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

class simulation_framework.src.ai.goal.GatherResourceGoal(resource_type: str, target_quantity: int = 10, priority: int = 6)

Bases: Goal

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

class simulation_framework.src.ai.goal.Goal(priority: int = 5, name: str = 'Goal')

Bases: ABC

get_estimated_duration(agent: Entity, world: World) → int

Estimate how many ticks this goal will take

abstract get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

abstract get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

abstract is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

abstract is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

on_action_completed(action: Action, success: bool, agent: Entity, world: World) → None

Called when an action for this goal completes

should_abandon(agent: Entity, world: World) → bool

Check if this goal should be abandoned

class simulation_framework.src.ai.goal.RestGoal(priority: int = 3)

Bases: Goal

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

class simulation_framework.src.ai.goal.TradeGoal(target_id: int | None = None, offered_items: List[Tuple[str, int]] | None = None, requested_items: List[Tuple[str, int]] | None = None, priority: int = 5)

Bases: Goal

Goal for trading items with other entities

get_next_action(agent: Entity, world: World) → Action | None

Get the next action to work towards this goal

get_utility(agent: Entity, world: World) → float

Calculate utility score for this goal (0-1)

is_complete(agent: Entity, world: World) → bool

Check if this goal has been completed

is_valid(agent: Entity, world: World) → bool

Check if this goal is still valid/achievable

Decision Maker

class simulation_framework.src.ai.decision_maker.DecisionMaker

Bases: object

evaluate_all_goals(agent: Entity, world: World, current_goals: List[Goal]) → List[Tuple[Goal, float]]

Evaluate utility of all possible goals

get_decision_summary(agent: Entity) → Dict[str, any]

Get summary of decision-making state for debugging

reset_decision_cooldown() → None

Reset the decision cooldown (for testing or special cases)

select_goal(agent: Entity, world: World, current_goals: List[Goal], selection_method: str = 'utility_weighted') → Goal | None

Select the best goal for the agent

Spatial Memory

Spatial Memory System for Agent World Knowledge.

Agents remember explored tiles, resource locations, and entity sightings. Reduces need for constant world scanning.

class simulation_framework.src.ai.spatial_memory.EntityMemory(entity_id: int, last_seen_position: Tuple[int, int], last_seen_tick: int, entity_type: str, was_hostile: bool = False)

Bases: object

Memory of another entity

entity_id: int

entity_type: str

last_seen_position: Tuple[int, int]

last_seen_tick: int

was_hostile: bool = False

class simulation_framework.src.ai.spatial_memory.ResourceMemory(position: Tuple[int, int], resource_type: str, last_seen_tick: int, last_seen_quantity: int = 0, was_depleted: bool = False, depletion_tick: int = 0)

Bases: object

Memory of a resource location

depletion_tick: int = 0

last_seen_quantity: int = 0

last_seen_tick: int

position: Tuple[int, int]

resource_type: str

was_depleted: bool = False

class simulation_framework.src.ai.spatial_memory.SpatialMemory(memory_duration: int = 100)

Bases: object

Agent’s memory of the world.

Stores information about: - Explored tiles - Known resource locations - Entity sightings - Terrain layout

forget_old_memories(current_tick: int) → None

Remove memories older than memory duration

get_exploration_percentage(world_size: Tuple[int, int]) → float

Calculate percentage of world explored

get_known_entity(entity_id: int) → EntityMemory | None

Get memory of an entity

get_known_resources(resource_type: str, agent_position: Tuple[int, int], current_tick: int, max_age: int | None = None) → List[Tuple[float, Tuple[int, int]]]

Get known resource locations sorted by distance.

Returns list of (distance, position) tuples. Filters out old memories and known depleted resources.

get_memory_summary() → Dict

Get summary of memory contents for debugging

get_nearby_entities(agent_position: Tuple[int, int], max_distance: float, current_tick: int, max_age: int = 50) → List[EntityMemory]

Get memories of nearby entities

get_nearest_known_resource(resource_type: str, agent_position: Tuple[int, int], current_tick: int) → Tuple[int, int] | None

Get nearest known resource position

has_visited(position: Tuple[int, int]) → bool

Check if agent has visited a tile

remember_entity(entity_id: int, position: Tuple[int, int], entity_type: str, was_hostile: bool, current_tick: int) → None

Remember seeing an entity

remember_resource(resource_type: str, position: Tuple[int, int], quantity: int, current_tick: int) → None

Remember seeing a resource at a location

remember_tile(position: Tuple[int, int], terrain_type: str, has_resources: bool, is_passable: bool, current_tick: int) → None

Remember visiting a tile

class simulation_framework.src.ai.spatial_memory.TileMemory(position: Tuple[int, int], terrain_type: str, last_visited_tick: int, has_resources: bool = False, is_passable: bool = True)

Bases: object

Memory of a tile

has_resources: bool = False

is_passable: bool = True

last_visited_tick: int

position: Tuple[int, int]

terrain_type: str