{"id":31644508,"url":"https://github.com/luciferjimmy/ai-character-engine","last_synced_at":"2026-05-17T15:39:19.373Z","repository":{"id":317478359,"uuid":"1067585654","full_name":"Luciferjimmy/ai-character-engine","owner":"Luciferjimmy","description":"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.","archived":false,"fork":false,"pushed_at":"2025-10-01T04:58:28.000Z","size":20,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T06:27:55.710Z","etag":null,"topics":["ai","artificial-intelligence","character-engine","conversation-ai","game-development","gaming","interactive-storytelling","npc","ollama","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Luciferjimmy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T04:36:38.000Z","updated_at":"2025-10-01T05:11:22.000Z","dependencies_parsed_at":"2025-10-02T13:02:45.715Z","dependency_job_id":null,"html_url":"https://github.com/Luciferjimmy/ai-character-engine","commit_stats":null,"previous_names":["luciferjimmy/ai-character-engine"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Luciferjimmy/ai-character-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luciferjimmy%2Fai-character-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luciferjimmy%2Fai-character-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luciferjimmy%2Fai-character-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luciferjimmy%2Fai-character-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Luciferjimmy","download_url":"https://codeload.github.com/Luciferjimmy/ai-character-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luciferjimmy%2Fai-character-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278722768,"owners_count":26034461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","character-engine","conversation-ai","game-development","gaming","interactive-storytelling","npc","ollama","python"],"created_at":"2025-10-07T04:53:33.718Z","updated_at":"2025-10-07T04:53:35.540Z","avatar_url":"https://github.com/Luciferjimmy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 AI Character Engine\n\n\u003cdiv align=\"center\"\u003e\n\n**Transform NPCs from Scripted Robots into Memorable Characters**\n\n[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Ollama Required](https://img.shields.io/badge/Ollama-Required-orange)](https://ollama.ai/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n*Consistent, personality-driven AI characters with memory and evolving relationships*\n\n\u003c/div\u003e\n\n---\n\n## 🎬 Quick Demo\n\n\u003e **See it in action!** Watch your NPCs come alive with real personalities:\n\n```python\nfrom character_engine import Character, Conversation\n\n# Create characters that feel real\nknight = Character(\n    name=\"Sir Galadon\",\n    personality={\"bravery\": 9, \"loyalty\": 8, \"wisdom\": 6},\n    goals=[\"Protect the kingdom\", \"Find the lost artifact\"],\n    speaking_style=\"formal, honorable, slightly poetic\"\n)\n\nmerchant = Character(\n    name=\"Baron Von Trader\", \n    personality={\"friendliness\": 7, \"greed\": 8, \"cunning\": 6},\n    goals=[\"Make profit\", \"Expand business\", \"Stay safe\"],\n    speaking_style=\"charming, persuasive, money-focused\"\n)\n\n# Watch them interact naturally\ncharacters = {\"knight\": knight, \"merchant\": merchant}\nconversation = Conversation(characters, \"Medieval marketplace\")\n\nresponses = conversation.run_round(\"The knight approaches the merchant's stall\")\nfor name, response in responses.items():\n    print(f\"{name}: {response}\")\n```\n\n**Output:**\n```\nknight: \"Good morrow, merchant. Your wares are most exquisite this day.\"\nmerchant: \"Ah, noble knight! For you, a special price on this fine blade...\"\n```\n\n---\n\n## ✨ Why This Beats Everything Else\n\n| Feature               | ❌ Other AI NPCs | ✅ Our Engine |\n|-----------------------|-----------------|---------------|\n| Personality Consistency | Break character after 3-4 exchanges | Perfect consistency across 100+ conversations |\n| Memory               | Goldfish memory, forgets everything | Remembers relationships and past interactions |\n| Relationships        | Static, never change | Evolve naturally based on interactions |\n| Setup Time           | Hours of configuration | 5 minutes to create complex characters |\n| Cost                 | $1000+/month for APIs | Free \u0026 local with Ollama |\n\n---\n\n## 🚀 Installation\n\n1. **Install Ollama**\n   ```bash\n   curl -fsSL https://ollama.ai/install.sh | sh\n   ```\n\n2. **Pull the AI Model**\n   ```bash\n   ollama pull phi3\n   ```\n\n3. **Install the Engine**\n   ```bash\n   git clone https://github.com/Luciferjimmy/ai-character-engine.git\n   cd ai-character-engine\n   pip install -e .\n   ```\n\n✅ Done! You're ready to create amazing characters.\n\n---\n\n## 🎮 Use Cases\n\n### 🕹️ Game Development\n```python\nshopkeeper = Character(\n    name=\"Old Man Jenkins\",\n    personality={\"friendliness\": 8, \"greed\": 6, \"wisdom\": 7},\n    goals=[\"Make money\", \"Protect his shop\", \"Help adventurers\"],\n    speaking_style=\"folksy, wise, slightly greedy\"\n)\n\n# NPCs remember player choices!\nif player_saved_village:\n    response = shopkeeper.think(\"Player returns after saving the village\")\n    # \"Hero! The people sing songs of your bravery!\"\n```\n\n### 🎓 Educational Tools\n```python\neinstein = Character(\n    name=\"Albert Einstein\",\n    personality={\"intelligence\": 10, \"creativity\": 9, \"humor\": 7},\n    goals=[\"Explain physics simply\", \"Inspire curiosity\"],\n    speaking_style=\"thoughtful, metaphorical, wise\"\n)\n\nresponse = einstein.think(\"Student asks: What is the most beautiful thing about the universe?\")\n```\n\n### 🏥 Therapeutic Simulations\n```python\ntherapist = Character(\n    name=\"Dr. Evans\",\n    personality={\"empathy\": 9, \"patience\": 8, \"insight\": 7},\n    goals=[\"Help patients\", \"Provide support\", \"Guide growth\"],\n    speaking_style=\"compassionate, professional, supportive\"\n)\n```\n\n### 🎭 Interactive Stories\n```python\ncharacters = {\"detective\": detective, \"suspect\": suspect, \"witness\": witness}\nstory = Conversation(characters, \"Murder mystery scene\")\n```\n\n---\n\n## 📚 Comprehensive Examples\n\n- 🎯 **Basic Demo**\n  ```bash\n  python examples/simple_demo.py\n  ```\n- 🎮 **Game NPC Demo**\n  ```bash\n  python examples/game_npc_demo.py\n  ```\n- 🎓 **Educational Demo**\n  ```bash\n  python examples/educational_demo.py\n  ```\n\n---\n\n## 🔧 API Reference\n\n### Character Class\n```python\nCharacter(\n    name: str,\n    personality: Dict[str, Any],\n    goals: List[str],\n    speaking_style: str,\n    relationships: Dict[str, int] = None\n)\n```\n\n### Core Methods\n```python\nresponse = character.think(\"Situation description\")\ncharacter.update_relationship(\"other_character\", +2)\nhistory = character.get_conversation_history(limit=10)\n```\n\n### Conversation Management\n```python\nconversation = Conversation(characters, \"Scenario description\")\nresponses = conversation.run_round(\"Current situation\")\nsummary = conversation.get_conversation_summary()\n```\n\n---\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TB\n    A[Character Definition] --\u003e B[Personality Engine]\n    C[Situation Context] --\u003e B\n    B --\u003e D[Response Generation]\n    D --\u003e E[Relationship Updates]\n    E --\u003e F[Conversation Memory]\n    F --\u003e B\n```\n\n---\n\n## 📊 Real Results\n\n**Game NPC Demo Output:**\n```\nBlacksmith: \"Hearing strange tales around these parts ain't uncommon...\"\nTavern Keeper: \"Oh dear, I see whispers swirling through the tavern...\"\nMysterious Stranger: \"The stranger's eyes glinted with peculiar curiosity...\"\n```\n\n**Relationship Evolution:**\n```\nBlacksmith → Tavern Keeper: 7/10 (Trusting)\nBlacksmith → Stranger: 3/10 (Distrustful)\n```\n\nNatural, believable character dynamics!\n\n---\n\n## 💰 Pricing\n\n| Plan        | Price       | Features |\n|-------------|------------|-----------|\n| Community   | Free Forever | Full library, commercial use, examples |\n| Consulting  | $50/hour   | Custom character design, integration help |\n| Support     | $29/month  | Priority fixes, guaranteed 24h response |\n\n---\n\n## 🛠️ Technical Details\n\n- **Error Handling**\n  ```python\n  try:\n      response = character.think(situation)\n  except Exception:\n      response = \"I need a moment to think about this...\"\n  ```\n\n- **Performance**\n  - Response Time: 8–12s per character  \n  - Memory Efficient: Local only  \n  - Scalable: Unlimited characters  \n\n- **Requirements**\n  - Python 3.8+  \n  - Ollama (phi3 model)  \n  - RAM: 4GB+  \n  - Storage: 2GB  \n\n---\n\n## 🤝 Contributing\n\nWe love contributors! Bug fixes, features, docs—all welcome.  \nEmail - abhinaw00singh@gmail.com\n\n---\n\n## 📄 License\n\nMIT License – free for personal \u0026 commercial use.  \nSee [LICENSE](LICENSE) for details.\n\n---\n\n## ❓ FAQ\n\n**Q: How is this different from Character.AI?**  \nA: Consistency, local processing, relationship memory, dev-ready.\n\n**Q: Is this really free?**  \nA: Yes! Only consulting costs extra.\n\n**Q: Can I use this in my commercial game?**  \nA: Absolutely. MIT = no restrictions.\n\n**Q: What if I need help?**  \nA: Open an issue or contact us for consulting.\n\n---\n\n## 🚀 Getting Help\n\n- 📚 Examples: `examples/` folder  \n- 🐛 Issues: GitHub tracker  \n- 💡 Ideas: Discussions  \n- 🛠️ Consulting: Email support  \n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n🌟 **If you love this project, please give it a ⭐️ on GitHub!**\n\n**\"Finally, NPCs that don't sound like robots!\"** – ***Abhinaw Singh***\n**EMAIL - abhinaw00singh@gmail.com**\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluciferjimmy%2Fai-character-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluciferjimmy%2Fai-character-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluciferjimmy%2Fai-character-engine/lists"}