https://github.com/luciferjimmy/ai-character-engine
The AI Character Engine empowers developers to create deeply immersive AI characters with unbreakable personality consistency, conversation memory, and relationships that evolve naturally. Unlike cloud-based services, it runs entirely locally, offering complete privacy and zero costs—perfect for next-generation games, educational tools.
https://github.com/luciferjimmy/ai-character-engine
ai artificial-intelligence character-engine conversation-ai game-development gaming interactive-storytelling npc ollama python
Last synced: 28 days ago
JSON representation
The AI Character Engine empowers developers to create deeply immersive AI characters with unbreakable personality consistency, conversation memory, and relationships that evolve naturally. Unlike cloud-based services, it runs entirely locally, offering complete privacy and zero costs—perfect for next-generation games, educational tools.
- Host: GitHub
- URL: https://github.com/luciferjimmy/ai-character-engine
- Owner: Luciferjimmy
- License: mit
- Created: 2025-10-01T04:36:38.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-01T04:58:28.000Z (9 months ago)
- Last Synced: 2025-10-01T06:27:55.710Z (9 months ago)
- Topics: ai, artificial-intelligence, character-engine, conversation-ai, game-development, gaming, interactive-storytelling, npc, ollama, python
- Language: Python
- Homepage:
- Size: 19.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🤖 AI Character Engine
**Transform NPCs from Scripted Robots into Memorable Characters**
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://ollama.ai/)
[](CONTRIBUTING.md)
*Consistent, personality-driven AI characters with memory and evolving relationships*
---
## 🎬 Quick Demo
> **See it in action!** Watch your NPCs come alive with real personalities:
```python
from character_engine import Character, Conversation
# Create characters that feel real
knight = Character(
name="Sir Galadon",
personality={"bravery": 9, "loyalty": 8, "wisdom": 6},
goals=["Protect the kingdom", "Find the lost artifact"],
speaking_style="formal, honorable, slightly poetic"
)
merchant = Character(
name="Baron Von Trader",
personality={"friendliness": 7, "greed": 8, "cunning": 6},
goals=["Make profit", "Expand business", "Stay safe"],
speaking_style="charming, persuasive, money-focused"
)
# Watch them interact naturally
characters = {"knight": knight, "merchant": merchant}
conversation = Conversation(characters, "Medieval marketplace")
responses = conversation.run_round("The knight approaches the merchant's stall")
for name, response in responses.items():
print(f"{name}: {response}")
```
**Output:**
```
knight: "Good morrow, merchant. Your wares are most exquisite this day."
merchant: "Ah, noble knight! For you, a special price on this fine blade..."
```
---
## ✨ Why This Beats Everything Else
| Feature | ❌ Other AI NPCs | ✅ Our Engine |
|-----------------------|-----------------|---------------|
| Personality Consistency | Break character after 3-4 exchanges | Perfect consistency across 100+ conversations |
| Memory | Goldfish memory, forgets everything | Remembers relationships and past interactions |
| Relationships | Static, never change | Evolve naturally based on interactions |
| Setup Time | Hours of configuration | 5 minutes to create complex characters |
| Cost | $1000+/month for APIs | Free & local with Ollama |
---
## 🚀 Installation
1. **Install Ollama**
```bash
curl -fsSL https://ollama.ai/install.sh | sh
```
2. **Pull the AI Model**
```bash
ollama pull phi3
```
3. **Install the Engine**
```bash
git clone https://github.com/Luciferjimmy/ai-character-engine.git
cd ai-character-engine
pip install -e .
```
✅ Done! You're ready to create amazing characters.
---
## 🎮 Use Cases
### 🕹️ Game Development
```python
shopkeeper = Character(
name="Old Man Jenkins",
personality={"friendliness": 8, "greed": 6, "wisdom": 7},
goals=["Make money", "Protect his shop", "Help adventurers"],
speaking_style="folksy, wise, slightly greedy"
)
# NPCs remember player choices!
if player_saved_village:
response = shopkeeper.think("Player returns after saving the village")
# "Hero! The people sing songs of your bravery!"
```
### 🎓 Educational Tools
```python
einstein = Character(
name="Albert Einstein",
personality={"intelligence": 10, "creativity": 9, "humor": 7},
goals=["Explain physics simply", "Inspire curiosity"],
speaking_style="thoughtful, metaphorical, wise"
)
response = einstein.think("Student asks: What is the most beautiful thing about the universe?")
```
### 🏥 Therapeutic Simulations
```python
therapist = Character(
name="Dr. Evans",
personality={"empathy": 9, "patience": 8, "insight": 7},
goals=["Help patients", "Provide support", "Guide growth"],
speaking_style="compassionate, professional, supportive"
)
```
### 🎭 Interactive Stories
```python
characters = {"detective": detective, "suspect": suspect, "witness": witness}
story = Conversation(characters, "Murder mystery scene")
```
---
## 📚 Comprehensive Examples
- 🎯 **Basic Demo**
```bash
python examples/simple_demo.py
```
- 🎮 **Game NPC Demo**
```bash
python examples/game_npc_demo.py
```
- 🎓 **Educational Demo**
```bash
python examples/educational_demo.py
```
---
## 🔧 API Reference
### Character Class
```python
Character(
name: str,
personality: Dict[str, Any],
goals: List[str],
speaking_style: str,
relationships: Dict[str, int] = None
)
```
### Core Methods
```python
response = character.think("Situation description")
character.update_relationship("other_character", +2)
history = character.get_conversation_history(limit=10)
```
### Conversation Management
```python
conversation = Conversation(characters, "Scenario description")
responses = conversation.run_round("Current situation")
summary = conversation.get_conversation_summary()
```
---
## 🏗️ Architecture
```mermaid
graph TB
A[Character Definition] --> B[Personality Engine]
C[Situation Context] --> B
B --> D[Response Generation]
D --> E[Relationship Updates]
E --> F[Conversation Memory]
F --> B
```
---
## 📊 Real Results
**Game NPC Demo Output:**
```
Blacksmith: "Hearing strange tales around these parts ain't uncommon..."
Tavern Keeper: "Oh dear, I see whispers swirling through the tavern..."
Mysterious Stranger: "The stranger's eyes glinted with peculiar curiosity..."
```
**Relationship Evolution:**
```
Blacksmith → Tavern Keeper: 7/10 (Trusting)
Blacksmith → Stranger: 3/10 (Distrustful)
```
Natural, believable character dynamics!
---
## 💰 Pricing
| Plan | Price | Features |
|-------------|------------|-----------|
| Community | Free Forever | Full library, commercial use, examples |
| Consulting | $50/hour | Custom character design, integration help |
| Support | $29/month | Priority fixes, guaranteed 24h response |
---
## 🛠️ Technical Details
- **Error Handling**
```python
try:
response = character.think(situation)
except Exception:
response = "I need a moment to think about this..."
```
- **Performance**
- Response Time: 8–12s per character
- Memory Efficient: Local only
- Scalable: Unlimited characters
- **Requirements**
- Python 3.8+
- Ollama (phi3 model)
- RAM: 4GB+
- Storage: 2GB
---
## 🤝 Contributing
We love contributors! Bug fixes, features, docs—all welcome.
Email - abhinaw00singh@gmail.com
---
## 📄 License
MIT License – free for personal & commercial use.
See [LICENSE](LICENSE) for details.
---
## ❓ FAQ
**Q: How is this different from Character.AI?**
A: Consistency, local processing, relationship memory, dev-ready.
**Q: Is this really free?**
A: Yes! Only consulting costs extra.
**Q: Can I use this in my commercial game?**
A: Absolutely. MIT = no restrictions.
**Q: What if I need help?**
A: Open an issue or contact us for consulting.
---
## 🚀 Getting Help
- 📚 Examples: `examples/` folder
- 🐛 Issues: GitHub tracker
- 💡 Ideas: Discussions
- 🛠️ Consulting: Email support
---
🌟 **If you love this project, please give it a ⭐️ on GitHub!**
**"Finally, NPCs that don't sound like robots!"** – ***Abhinaw Singh***
**EMAIL - abhinaw00singh@gmail.com**