A sophisticated Python framework for modeling and simulating psychological personality systems. This project enables dynamic personality evolution through event simulation, allowing for realistic modeling of how life experiences shape personality traits and psychological attributes.
The Conceptual Personality Builder is designed to provide a comprehensive, extensible system for representing and evolving personality profiles. Whether you're building AI systems, psychological simulations, game character development, or behavioral modeling tools, this framework offers a structured approach to personality representation based on established psychological concepts.
- 11 Interconnected Personality Attributes: Model different psychological dimensions including Character, Emotional Style, Self-Concept, Self-Esteem, Temperament, and more
- Event-Driven Evolution: Watch personalities evolve realistically through life events across multiple domains (Career, Health, Relationships, etc.)
- Intelligent Categorization: Events are organized by Valencia (Positive/Negative/Neutral), Domain, and Controllability level
- Dynamic Event Discovery: Automatically discovers and catalogs all available events in your system
- Extensible Architecture: Easy to add new events, personality attributes, or psychological dimensions
This repository is designed to be flexible and open for collaboration:
You can fork or clone this repository and adapt it to your needs:
- Use the personality system as-is for character development, AI behavior, or simulations
- Extend personality attributes with your own psychological dimensions
- Create domain-specific event libraries for your use case
- Integrate with game engines, chatbots, or behavioral AI systems
If you'd like to contribute and help improve this framework:
- Fork the repository and create a branch for your changes
- Add new events following the established patterns
- Extend personality attributes if needed for your use case
- Submit a pull request with clear documentation of your additions
- Python 3.9+: Core language for the framework
- OOP Architecture: Object-oriented design for clean, extensible code
- No External Dependencies: Uses only Python standard library (importlib, inspect, os)
This lightweight approach ensures maximum portability and minimal setup friction.
Conceptual-Personality-Builder/
├── Actions/ # Event Library (organized by psychology)
│ ├── Positive/ # Valencia: Positive events
│ ├── Negative/ # Valencia: Negative events
│ └── Neutral/ # Valencia: Neutral events
│ └── DOMAIN/ # Domain: Career, Health, Relationships, etc.
│ ├── eventControllable.py # Events the person can control
│ ├── eventPartiallyControllable.py # Mixed control events
│ └── eventUncontrollable.py # Events beyond person's control
│
├── PersonalityAtributes/ # Core personality classes
│ ├── Character.py # How person presents themselves
│ ├── EmotionalStyle.py # Emotional regulation & expression
│ ├── SelfConcept.py # How person sees themselves
│ ├── SelfEsteem.py # Self-worth and confidence
│ ├── Temperament.py # Innate behavioral tendencies
│ ├── ThoughtPatterns.py # Cognitive styles
│ ├── Environment.py # Adaptability to changes
│ ├── HabitualBehavior.py # Consistency of behaviors
│ ├── InternalNeeds.py # Psychological needs
│ ├── LifeExperience.py # Life events collection
│ ├── Motivations.py # Drive and goals
│ └── __init__.py
│
├── PersonalityBuilder/ # Aggregator & orchestrator
│ ├── PersonalityBuilder.py # Unified personality management
│ └── __init__.py
│
├── Main/ # Application entry points
│ ├── main.py # Core simulation engine
│ ├── discover_events.py # Event exploration tool
│ └── display_person.py # Personality visualization tool
│
├── Aditional/ # Supporting classes
│ └── PersonalInformation.py # Demographic & personal data
│
└── README.md # This file
Events are organized using a 4-dimensional taxonomy:
- Positive: Events with beneficial outcomes
- Negative: Events with harmful or stressful outcomes
- Neutral: Events with mixed or ambiguous valence
- CAREER: Job, profession, work achievements, unemployment
- HEALTH: Physical/mental health, illness, fitness, medical events
- RELATIONSHIPS: Romance, family, friendships, social connections
- TRAUMA: Abuse, loss, severe stress, PTSD triggers
- PERSONAL_GROWTH: Learning, skill development, self-improvement
- FINANCIAL: Money, poverty, wealth, economic changes
- SOCIAL: Community, status, social acceptance/rejection
- EXISTENTIAL: Meaning, purpose, mortality, philosophy
- LEGAL: Crime, justice, legal matters
- EDUCATIONAL: School, learning outcomes, academic achievement
- eventControllable.py: Person directly caused/controlled this (their choice, effort, action)
- eventPartiallyControllable.py: Mixed agency (person participated, but others had decision power)
- eventUncontrollable.py: Happened to person (luck, circumstances, others' decisions)
Within each .py file, events are organized by duration comments:
# ACUTE: Single, time-limited event (e.g., job interview, injury, argument)# CHRONIC: Ongoing, persistent condition (e.g., chronic illness, ongoing conflict)# RECURRENT: Repeating pattern across time (e.g., seasonal depression, repeated rejections)# EPISODIC: Multiple discrete instances of similar events (e.g., multiple achievements)
Example Path: Actions/Negative/HEALTH/eventUncontrollable.py → ACUTE section
- Meaning: A negative, health-related event beyond person's control, happening suddenly
Each event function follows a consistent, proven pattern:
def CompletedProfessionalCertification(personality_builder):
"""
-Event Description: Person completed a professional certification through dedicated effort
-Controllability: This is controllable because the person chose to pursue it, invested time,
studied, and took the examination themselves. Their agency was direct.
-Psychological Impact: This positive controllable event boosts self-efficacy, demonstrates
achievement capability, and strengthens career-focused self-esteem. The person recognizes
their capacity to accomplish challenging goals through effort.
"""
# 1. GET CURRENT VALUES
current_self_efficacy = personality_builder.self_esteem.general_self_efficacy
current_achievement_motivation = personality_builder.motivations.achievement_motivation
current_academic_self_esteem = personality_builder.self_esteem.academic_professional_self_esteem
current_global_self_esteem = personality_builder.self_esteem.global_self_esteem
# 2. CALCULATE NEW VALUES (with validation: min 0, max 100)
new_self_efficacy = min(100, current_self_efficacy + 8)
new_achievement_motivation = min(100, current_achievement_motivation + 6)
new_academic_self_esteem = min(100, current_academic_self_esteem + 10)
new_global_self_esteem = min(100, current_global_self_esteem + 5)
# 3. PRINT BEFORE STATE
print("[Before Event]")
print(f" General Self-Efficacy: {current_self_efficacy}")
print(f" Achievement Motivation: {current_achievement_motivation}")
print(f" Academic/Professional Self-Esteem: {current_academic_self_esteem}")
print(f" Global Self-Esteem: {current_global_self_esteem}")
# 4. APPLY CHANGES using setter methods
personality_builder.self_esteem.set_general_self_efficacy(new_self_efficacy)
personality_builder.motivations.set_achievement_motivation(new_achievement_motivation)
personality_builder.self_esteem.set_academic_professional_self_esteem(new_academic_self_esteem)
personality_builder.self_esteem.set_global_self_esteem(new_global_self_esteem)
# 5. UPDATE LIFE EXPERIENCE
personality_builder.life_experience.add_major_achievement("Professional Certification Completed")
personality_builder.life_experience.add_positive_experience("Career milestone achieved through personal effort")
# 6. PRINT AFTER STATE with deltas
print("\n[After Event]")
print(f" General Self-Efficacy: {new_self_efficacy} (+{new_self_efficacy - current_self_efficacy:.2f})")
print(f" Achievement Motivation: {new_achievement_motivation} (+{new_achievement_motivation - current_achievement_motivation:.2f})")
print(f" Academic/Professional Self-Esteem: {new_academic_self_esteem} (+{new_academic_self_esteem - current_academic_self_esteem:.2f})")
print(f" Global Self-Esteem: {new_global_self_esteem} (+{new_global_self_esteem - current_global_self_esteem:.2f})")
# 7. PRINT PERSONALITY EVOLUTION NARRATIVE (3-4 sentences)
print("\n[Personality Evolution]")
print("The person experiences a significant boost in self-efficacy and achievement motivation.")
print("Their academic/professional self-esteem increases substantially, as they've proven their capacity")
print("to master complex material and achieve demanding goals. This success ripples into broader")
print("self-esteem improvements, strengthening their global sense of competence and self-worth.")Key Principles:
- Always validate values:
min(100, max(0, value))to keep within 0-100 range - Use
{delta:.2f}for formatting deltas to 2 decimal places - Print before/after/evolution for immediate feedback and debugging
- Use
+for positive deltas,-is automatic for negative - Write evolution narrative in clear, psychological language (3-4 sentences)
Three exemplar events are included demonstrating each controllability level (found in Actions/Positive/CAREER/):
- File:
eventControllable.py| Duration: ACUTE - Scenario: Person completed a professional certification through their own effort
- Controllability: Fully controllable—they chose to pursue it
- Attributes Modified: 4 (Self-Efficacy, Achievement Motivation, Academic/Professional Self-Esteem, Global Self-Esteem)
- Key Insight: Shows how achievement builds confidence and career-focused identity
- File:
eventPartiallyControllable.py| Duration: ACUTE - Scenario: Person applied for promotion and was selected by management
- Controllability: Partially controllable—they prepared and applied, but others made final decision
- Attributes Modified: 5 (Locus of Control moves toward balanced internal/external)
- Key Insight: Demonstrates realistic psychological response to external validation of effort
- File:
eventUncontrollable.py| Duration: ACUTE - Scenario: Person unexpectedly offered their dream job without applying
- Controllability: Uncontrollable—pure luck, timing, or external circumstances
- Attributes Modified: 7 (Major boost but includes imposter syndrome warning)
- Key Insight: Shows how external agency events create different psychological responses, including potential negative feelings despite positive outcome
All three examples use consistent patterns and are fully functional—run them directly in Main/main.py.
from PersonalityBuilder.PersonalityBuilder import PersonalityBuilder
from Aditional.PersonalInformation import PersonalInformation
# Step 1: Create person with demographic information
info = PersonalInformation(
name="Alice",
age=28,
gender="Female",
occupation="Software Engineer"
)
person = PersonalityBuilder(info)
# Step 2: Display current personality state
person.describe()
# Step 3: Discover available events
person.discover_available_events()
# Step 4: Apply an event and observe evolution
from Actions.Positive.CAREER.eventControllable import CompletedProfessionalCertification
CompletedProfessionalCertification(person)
# Step 5: Check changes in personality
print(f"New Self-Efficacy: {person.self_esteem.general_self_efficacy}")
print(f"Achievement History: {person.life_experience.major_achievements}")
# Step 6: Apply multiple events in sequence
from Actions.Positive.CAREER.eventPartiallyControllable import PromotionAfterApplication
PromotionAfterApplication(person)A standalone script that displays all available events organized hierarchically:
[AVAILABLE EVENTS IN SYSTEM]
[Positive > CAREER > eventControllable.py]
> CompletedProfessionalCertification()
[Positive > CAREER > eventPartiallyControllable.py]
> PromotionAfterApplication()
[Positive > CAREER > eventUncontrollable.py]
> UnexpectedlyOfferedDreamJob()
Usage:
python Main/discover_events.pyUtility to inspect complete current state of a personality:
python Main/display_person.pyDisplays:
- Personal demographic information (name, age, gender, occupation)
- All 11 personality attributes with current values (0-100)
- Life experience records (achievements, traumas, positive/negative experiences)
- Easy reference for personality debugging
The main orchestrator that:
- Creates a person with initial personality
- Initializes all personality attributes
- Shows available events
- Displays current personality state
- Simulates event application
- Demonstrates personality evolution
1. Choose the Correct Location
Actions/
[Valencia - Positive/Negative/Neutral]/
[Domain - CAREER/HEALTH/RELATIONSHIPS/etc]/
[Controllability - eventControllable/eventPartiallyControllable/eventUncontrollable].py
Choose the file that matches your event's characteristics.
2. Follow the Docstring Format (Required for event discovery)
def YourEventName(personality_builder):
"""
-Event Description: Clear explanation of what is happening to the person
-Controllability: Explain why this event fits this controllability level for the person
-Psychological Impact: Describe which psychological attributes change and why (2-3 sentences)
"""3. Implement Following the Pattern
# Get current values
current_value = personality_builder.attribute_class.attribute_name
# Calculate new values (validate!)
new_value = min(100, max(0, current_value + delta))
# Print before
print(f"[Before] Attribute: {current_value}")
# Apply changes
personality_builder.attribute_class.set_attribute_name(new_value)
# Update life experience
personality_builder.life_experience.add_major_achievement("Description")
# Print after with delta
print(f"[After] Attribute: {new_value} (+{new_value - current_value:.2f})")
# Print evolution narrative (3-4 sentences)
print("[Personality Evolution] Description of psychological change...")4. Magnitude Guidelines (Recommended delta ranges)
- Small events: ±2 to ±5 points (e.g., minor criticism, small success)
- Medium events: ±6 to ±10 points (e.g., job loss, relationship improvement)
- Major life events: ±11 to ±15 points (e.g., marriage, serious illness)
- Extreme events: Up to ±20 points (e.g., trauma, life-changing achievement)
- Never exceed ±20 points in a single event for realistic evolution
5. Test Your Event
from Actions.Negative.HEALTH.eventUncontrollable import YourEventName
person = PersonalityBuilder(PersonalInformation("Test", 30, "M", "Tester"))
YourEventName(person)6. Commit Pattern (What variables to modify) Different events naturally modify different attributes:
| Event Type | Likely Attributes |
|---|---|
| Success/Achievement | Self-Efficacy, Self-Esteem, Motivations, Achievement Motivation |
| Failure/Rejection | Self-Esteem, Self-Concept, Motivations, Thought Patterns |
| Social Events | Emotional Style, Character, Temperament |
| Health Events | Temperament, Thought Patterns, Internal Needs |
| Trauma | All attributes can be impacted (±15-20) |
All attributes use a 0-100 scale with semantic interpretations:
- Represents moral consistency, integrity, and authenticity
- High (70-100): Principled, reliable, morally consistent
- Mid (40-60): Mixed morality, situational ethics
- Low (0-30): Unreliable, unprincipled, deceptive
- Represents emotional regulation and expressiveness
- High (70-100): Emotionally controlled, stable, composed
- Mid (40-60): Moderate emotional expression
- Low (0-30): Emotionally volatile, reactive, overwhelmed
- How the person understands their own identity
- High (70-100): Clear self-understanding, coherent identity
- Mid (40-60): Somewhat confused identity, developing self-awareness
- Low (0-30): Identity confusion, unclear self-image
- Contains multiple sub-dimensions of self-worth
- General Self-Efficacy: Belief in ability to handle challenges
- Global Self-Esteem: Overall self-worth
- Academic/Professional Self-Esteem: Career-specific confidence
- Social Self-Esteem: Confidence in social situations
- Innate emotional reactivity and behavioral persistence
- High (70-100): Calm, persistent, steady responses
- Mid (40-60): Moderate reactivity and persistence
- Low (0-30): Highly reactive, easily discouraged
- Cognitive style and processing preferences
- High (70-100): Analytical, logical, systematic thinking
- Low (0-30): Intuitive, creative, holistic thinking
- Used to model cognitive approaches to problems
- Adaptability and comfort with environmental changes
- High (70-100): Adaptable, comfortable with change
- Low (0-30): Rigid, uncomfortable with new situations
- Consistency and automaticity of daily behaviors
- High (70-100): Routine-oriented, consistent habits
- Low (0-30): Spontaneous, inconsistent behavior
- Psychological motivations and needs (Maslow-inspired)
- High (70-100): Strong intrinsic motivation
- Low (0-30): Struggling with basic needs
- Collection of major achievements, traumas, and experiences
- Not a 0-100 scale but a repository
- Lists: major_achievements, traumas, positive_experiences, negative_experiences
- Goal orientation and drive
- Achievement Motivation: Drive to succeed
- Growth Motivation: Desire to develop
- Social Motivation: Desire for connection
# Clone the repository
git clone https://github.com/Airam21170247/Conceptual-Personality-Builder.git
# Navigate to project directory
cd Conceptual-Personality-Builder
# Verify Python installation
python --version # Should be 3.9 or higher
# Run the main simulation
python Main/main.py
# Explore available events
python Main/discover_events.py
# View person's personality state
python Main/display_person.py# Create a personality-driven character
from PersonalityBuilder.PersonalityBuilder import PersonalityBuilder
from Aditional.PersonalInformation import PersonalInformation
# Initialize
person = PersonalityBuilder(PersonalInformation("Sarah", 25, "Female", "Designer"))
# View initial state
print("=== Initial Personality ===")
person.describe()
# Simulate a positive career event
from Actions.Positive.CAREER.eventControllable import CompletedProfessionalCertification
print("\n=== Event: Professional Certification ===")
CompletedProfessionalCertification(person)
# View evolved state
print("\n=== Updated Personality ===")
person.describe()
# Check specific attributes
print(f"\nGeneral Self-Efficacy: {person.self_esteem.general_self_efficacy}/100")
print(f"Achievements: {person.life_experience.major_achievements}")# Apply multiple events in sequence to see compound effects
from Actions.Positive.CAREER.eventControllable import CompletedProfessionalCertification
from Actions.Positive.CAREER.eventPartiallyControllable import PromotionAfterApplication
CompletedProfessionalCertification(person)
PromotionAfterApplication(person)
# Observe cumulative personality evolution
print(f"Final Self-Efficacy: {person.self_esteem.general_self_efficacy}")# Snapshot personality at different time points
initial_state = {
'self_efficacy': person.self_esteem.general_self_efficacy,
'achievement': person.motivations.achievement_motivation,
'experiences': len(person.life_experience.positive_experiences)
}
# Apply events...
final_state = {...}
# Compare changes
print(f"Self-Efficacy change: {final_state['self_efficacy'] - initial_state['self_efficacy']}")This framework can be integrated into:
- Game engines (character personality-based decision making)
- Chatbots (personality-consistent responses)
- AI systems (behavioral modeling)
- Simulations (social dynamics, psychology research)
- Educational tools (psychology teaching, behavioral training)
- Personality Interactions: Model how one attribute influences another over time (e.g., trauma reduces self-esteem, which increases social anxiety)
- Event Chains: Create dependencies where event A makes event B more/less likely
- Statistical Analysis: Track personality statistics across event sequences
- Visualization: Graph personality evolution over time
- Narrative Generation: Automatically create story text describing personality change
- Multiplayer Dynamics: Model personality changes in relationships with other personalities
- Decision Trees: Make future events depend on current personality state
- Extended Domains: Add more specific event categories based on use case
Interested in contributing? Consider:
- Adding Events: Create CHRONIC, RECURRENT, or EPISODIC examples in existing domains
- New Domains: Propose additional life domains beyond the current 10
- Personality Metrics: Add derived metrics (e.g., emotional resilience = self_esteem + temperament)
- Event Libraries: Build domain-specific event sets (e.g., "Medical Events", "Academic Events")
- Integrations: Connect with external APIs or systems
- Tools: Build utilities for visualization, analysis, or event creation
- Documentation: Improve examples and documentation for specific use cases
To contribute:
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes following the established patterns
- Test thoroughly
- Commit with clear messages:
git commit -m "Add X events for Y domain" - Push to your fork:
git push origin feature/your-feature - Submit a pull request with description of your contribution
This project is open source and available for personal and commercial use. Attribution is appreciated but not required.
Citation (if used in research or academic work):
Conceptual Personality Builder - A Python Framework for Dynamic Personality Simulation
https://github.com/Airam21170247/Conceptual-Personality-Builder
Q: Can I use this for game character development?
A: Absolutely! The personality evolution system creates realistic character arcs based on in-game events.
Q: Is this based on real psychology?
A: The framework uses established psychological concepts (self-efficacy theory, locus of control, personality models) but is a simplified computational model for simulation purposes.
Q: How many events can I add?
A: No limit. The system dynamically discovers all events. Scale as needed for your use case.
Q: Can I modify existing personality attributes?
A: Yes. Each attribute class uses setter methods for validation. You can extend or customize.
Q: What Python versions are supported?
A: Python 3.9 and above.
For questions, issues, or suggestions:
- Review the example events in
Actions/Positive/CAREER/for implementation patterns - Check individual PersonalityAttribute classes for available methods
- Examine
PersonalityBuilder.pyto understand the aggregation system - Run
discover_events.pyto see your event catalog
Version: 1.0
Last Updated: December 2025
Python Version: 3.9+
Status: Active Development