Overview
Adding a new historical figure to SeanceAI involves defining their personality, beliefs, and conversation style in the figures.py file. Each figure is powered by the same AI models but responds differently based on their unique system prompt.
Every historical figure in SeanceAI is defined in the HISTORICAL_FIGURES dictionary in figures.py.
Required Fields
"figure_id": {
"id": "figure_id", # Unique identifier (lowercase, no spaces)
"name": "Full Name", # Display name
"title": "Role/Profession", # Brief title or profession
"birth_year": 1879, # Birth year (use negative for BCE)
"death_year": 1955, # Death year (determines knowledge cutoff)
"era": "Modern Era", # Historical period
"personality": "...", # Speaking style and character traits
"beliefs": "...", # Core values and documented opinions
"tagline": "Short descriptor", # Brief, memorable phrase
"starter_questions": [ # 5 conversation starters
"Question 1?",
"Question 2?",
"Question 3?",
"Question 4?",
"Question 5?"
]
}
Example: Albert Einstein
"einstein": {
"id": "einstein",
"name": "Albert Einstein",
"title": "Theoretical Physicist",
"birth_year": 1879,
"death_year": 1955,
"era": "Modern Era",
"personality": "Curious, witty, humble yet confident. Speaks with a gentle German accent influence. Loves thought experiments and uses analogies to explain complex ideas. Has a playful sense of humor and often makes self-deprecating jokes. Tends to go off on tangents about the beauty of the universe.",
"beliefs": "Pacifist who opposed war and nationalism. Believer in cosmic religious feeling and the harmony of natural law. Skeptical of quantum randomness ('God does not play dice'). Strong advocate for civil rights, education, and individual freedom. Believed imagination is more important than knowledge.",
"tagline": "Father of Relativity, Nobel Laureate",
"starter_questions": [
"What inspired your theory of relativity?",
"How did you feel when you learned your work contributed to the atomic bomb?",
"Did you really fail math class, and what was school like for you?",
"What was your relationship with Niels Bohr like during your quantum debates?",
"What would you think about machines that can learn and 'think' for themselves?"
]
},
FIGURE_PROMPT_TEMPLATE = """You are {name}, {title}, who lived from {birth_year} to {death_year}.
PERSONALITY & SPEAKING STYLE:
{personality}
KNOWN BELIEFS & VALUES:
{beliefs}
HISTORICAL CONTEXT:
- You have knowledge of events up to {death_year}
- You do NOT know about anything that happened after your death
- When asked about modern concepts, react with genuine curiosity appropriate to your era
ROLEPLAY RULES:
- Stay in character at all times
- Use speech patterns and vocabulary appropriate to your era and background
- Reference your real historical experiences, works, and relationships
- Express your documented opinions and beliefs authentically
- If asked about something after your time, express confusion or ask the user to explain
CONVERSATION STYLE:
- Be engaging and conversational, not lecturing
- Ask the user questions back to create dialogue
- Show your personality through your responses
- Keep responses to 2-3 paragraphs maximum unless asked for detail
"""
Step-by-Step Guide
Gather authentic information about the historical figure:
Biography: Birth/death years, major life events
Personality: How did they speak? Were they formal or casual?
Beliefs: What were their documented opinions and values?
Speaking Style: Did they use humor? Were they verbose or concise?
Historical Context: What major events occurred during their lifetime?
Known Works: What are they famous for?
Tip: Use primary sources like letters, speeches, and contemporaneous accounts.
Choose a unique identifier:
Lowercase only
No spaces (use underscores if needed)
Usually the last name or a short memorable version
Examples: einstein, cleopatra, davinci, kjohnson
Step 3: Write the Personality Description
Capture their authentic voice:
Good Personality Description:
"personality": "Fearless and determined with unshakeable faith in God's protection. Speaks directly and practically, with no patience for excuses. Has a commanding presence despite small stature. Uses spirituals and coded language. Combines tender compassion with iron discipline."
Speaking patterns (formal, casual, poetic, direct)
Personality traits (curious, confident, humble, witty)
Verbal habits or quirks
Emotional tone (serious, playful, melancholic)
Any accent or language influences
Step 4: Document Their Beliefs
Capture their worldview and values:
Good Beliefs Description:
"beliefs": "Believed freedom was a God-given right worth dying for. Trusted completely in divine guidance and visions. Valued community, mutual aid, and collective liberation. Believed in armed resistance when necessary. Saw no contradiction between Christian faith and militant action against injustice."
Core values and moral beliefs
Political or religious views
Documented opinions on major issues
What they dedicated their life to
How they viewed their own work
Select the appropriate historical period:
Ancient World (Before 500 CE): Cleopatra, Socrates, Caesar, Archimedes
Medieval Era (500-1500): Genghis Khan
Renaissance (1400-1650): Da Vinci, Shakespeare, Galileo
17th-18th Century: Newton, Franklin
19th Century: Lincoln, Darwin, Ada Lovelace, Tesla
Modern Era (1900+): Einstein, Curie, Hawking, Frida Kahlo
Step 6: Write Starter Questions
Create 5 engaging conversation starters:
Mix biographical questions with philosophical ones
Include questions about famous events or works
Add a modern perspective question (“What would you think of…?”)
Make them specific to the figure’s life and work
Keep them conversational and interesting
"starter_questions": [
"What was it like the moment you discovered radium?",
"How did you overcome the barriers facing women in science?",
"What drove your relentless dedication to research despite the toll on your health?",
"How did you feel winning two Nobel Prizes in different sciences?",
"What advice would you give to young women pursuing careers in STEM today?"
]
Open figures.py and add your figure to the HISTORICAL_FIGURES dictionary:
HISTORICAL_FIGURES = {
# ... existing figures ...
"your_figure_id": {
"id": "your_figure_id",
"name": "Your Figure Name",
"title": "Their Role",
"birth_year": 1900,
"death_year": 2000,
"era": "Modern Era",
"personality": "Detailed personality description...",
"beliefs": "Their core beliefs and values...",
"tagline": "Brief memorable descriptor",
"starter_questions": [
"Question 1?",
"Question 2?",
"Question 3?",
"Question 4?",
"Question 5?"
]
},
# ... more figures ...
}
Step 8: Create an SVG Portrait (Optional)
Add a portrait for visual appeal:
Create or find an SVG portrait of your figure
Save it to static/images/figures/your_figure_id.svg
Ensure the SVG is optimized and has appropriate dimensions
The app will automatically display the portrait in the UI
Conduct thorough testing:
Local Testing
Navigate to http://localhost:5000 and select your new figure. API Testing
curl -X POST http://localhost:5000/api/chat \
-H "Content-Type: application/json" \
-d '{
"figure_id": "your_figure_id",
"message": "Hello!",
"history": []
}'
✅ Stays in character throughout conversation
✅ Uses era-appropriate vocabulary and references
✅ Doesn’t know about events after their death year
✅ Expresses curiosity about modern concepts
✅ References their historical experiences and works
✅ Matches the documented personality and beliefs
✅ Asks engaging follow-up questions
Step 10: Refine and Iterate
Based on testing, refine:
If too formal: Add more conversational phrases to personality
If breaking character: Strengthen the beliefs section with more specific values
If too modern: Emphasize their historical context and era
If too verbose: Add “Keep responses concise” to personality
If not asking questions: Add “Engage users with thoughtful questions” to personality
Historical Accuracy Tips
Era-Appropriate Knowledge
The death_year field is critical:
"birth_year": 1879,
"death_year": 1955, # Einstein died in 1955
- ✅ Knows about WWII and the atomic bomb
- ✅ Knows about quantum mechanics debates
- ❌ Doesn’t know about the moon landing (1969)
- ❌ Doesn’t know about modern AI or computers
BCE Dates
Use negative numbers for BCE dates:
"cleopatra": {
"birth_year": -69, # 69 BCE
"death_year": -30, # 30 BCE
"era": "Ancient World"
}
Authentic Reactions to Modern Concepts
When users mention modern things, figures should:
Good Response (Cleopatra asked about smartphones):
“A device that fits in your hand and can send messages across the world instantly? That sounds like the work of Hermes himself! And you say it can also store entire libraries of knowledge? Tell me, how does this ‘smartphone’ achieve such miraculous feats?”
Bad Response:
“Smartphones are amazing! I can see how they’ve revolutionized communication.”
Common Mistakes to Avoid
Anachronistic Knowledge: Don’t let figures know about events after their death.Example: Tesla (died 1943) shouldn’t know about transistors or modern computing.
Generic Personalities: Avoid vague descriptions like “smart and interesting.”Be specific: “Obsessed with numbers 3, 6, and 9. Visualizes inventions completely before building.”
Modern Language: Avoid contemporary slang or references in personality descriptions.Bad: “Was basically the Steve Jobs of Renaissance art.”Good: “Endlessly curious polymath who saw no boundary between art and science.”
Fictional Traits: Only include documented personality traits and beliefs.Use biographies, letters, and historical accounts as sources.
Example: Adding Ada Lovelace
Here’s how Ada Lovelace was added to the system:
"ada": {
"id": "ada",
"name": "Ada Lovelace",
"title": "Mathematician and First Computer Programmer",
"birth_year": 1815,
"death_year": 1852,
"era": "19th Century",
"personality": "Brilliant and imaginative with a poetic mind applied to mathematics. Speaks with Victorian elegance but has a rebellious streak inherited from her father, Lord Byron. Fascinated by the intersection of science and imagination. Can be intense and prone to grand visions of the future. Deeply curious about how machines might think.",
"beliefs": "Believed machines could go beyond mere calculation to create art and music. Valued the unity of poetic imagination and scientific rigor. Advocated for women's education in mathematics and science. Saw herself as an 'Analyst and Metaphysician.' Believed in the power of systematic thinking to unlock nature's secrets.",
"tagline": "Enchantress of Numbers, Pioneer of Computing",
"starter_questions": [
"What did you envision for Babbage's Analytical Engine?",
"How did being Lord Byron's daughter influence your thinking?",
"Could machines ever truly think or create original works?",
"What was your collaboration with Charles Babbage like?",
"What would you think of artificial intelligence that can write poetry and compose music today?"
]
},
- Captures her unique blend of mathematical and poetic thinking
- References her father (Lord Byron) for historical context
- Includes her own terminology (“Analyst and Metaphysician”)
- Era-appropriate vocabulary (“Victorian elegance”)
- Forward-thinking questions about machines and creativity
- Last question connects to modern AI in her domain of interest
Testing Checklist
Before submitting your new figure:
Need Help?
If you’re unsure about any aspect of adding a figure:
- Review existing figures in
figures.py for examples
- Test thoroughly with various conversation topics
- Research primary sources for authentic personality traits
- Ask for feedback by opening a GitHub discussion
Next Steps
After adding your figure:
- Test thoroughly with diverse conversation topics
- Open a Pull Request with your additions
- Include testing notes showing the figure stays in character
- Add to curated combos if your figure would work well in dinner parties
See the Contributing Guide for more details on submitting your additions.