supernpc 0.1.0
AI-Powered NPCs for Games - Local LLM NPCs with memory and emotions
Requires Python: >=3.8
Keywords: ai npc game gaming llm local dialogue memory emotions personality

# Super NPC

**AI-Powered NPCs for Games - Local LLM NPCs with Memory and Emotions**

Super NPC is a universal AI NPC system for games. Add intelligent, emotional NPCs with persistent memory to any game with just a few lines of code. Runs entirely locally using your player's hardware.

## ✨ Features

- 🧠 **Persistent Memory**: NPCs remember conversations, events, and relationships across game sessions
- 😊 **Emotional Intelligence**: NPCs have dynamic emotions that affect their behavior and responses
- 👥 **Personality System**: Big Five personality traits make each NPC unique
- 🤝 **Relationship Tracking**: NPCs build trust/familiarity with players over time
- 💬 **Natural Dialogue**: LLM-powered conversations (Ollama, OpenAI, Anthropic)
- 🔄 **Universal Integration**: REST API, Python library, Unity/Godot plugins
- 💾 **State Persistence**: JSON serialization for saving/loading NPC states
- 🚀 **Performance Optimized**: Handles 100+ concurrent NPCs efficiently

## 🚀 Quick Start

### Python Library

```python
from supernpc import NPCAgent

# Create an intelligent NPC
npc = NPCAgent(
    name="Elara",
    role="blacksmith",
    personality="friendly",
    backstory=["I've forged weapons for 20 years"]
)

# Chat with the NPC
response = npc.chat("Player", "Do you have any swords for sale?")
print(f"Elara: {response}")

# NPC remembers and emotions change
npc.save_state("elara.json")
```

### REST API Server

```bash
# Install and run
pip install supernpc[server]
supernpc-server --port 8080 --model qwen2.5:1.5b

# Any game can integrate
curl -X POST http://localhost:8080/chat \
  -d '{"npc_id": "merchant", "player": "hero", "message": "What do you sell?"}'
```

## 🎮 Engine Integrations

### Unity (C#)
```csharp
using SuperNPC.Unity;

NPCAgent npc = new NPCAgent("Guard");
string response = npc.Chat("Player", "Can I enter the castle?");
```

### Godot (GDScript)
```gdscript
extends SuperNPC

func _ready():
    npc_id = "villager"
    personality = "curious"

func _on_player_interact(message):
    var response = chat("Player", message)
    show_dialogue(response)
```

## 📦 Installation

```bash
pip install supernpc

# For development
git clone https://github.com/supernpc/npcs
cd supernpc-sdk
pip install -e .
```

## 🏗️ Architecture

```
supernpc/
├── agent.py          # Main NPCAgent class
├── memory.py         # Memory storage & retrieval
├── emotions.py       # Emotional state management
├── personality.py    # Big Five personality traits
├── relationships.py  # Trust & familiarity tracking
├── dialogue.py       # LLM integration (Ollama/OpenAI/Anthropic)
└── __init__.py       # Package exports
```

## 🤖 LLM Support

- **Ollama** (Local): `qwen2.5:1.5b`, `llama2:7b`, etc.
- **OpenAI**: GPT-4, GPT-3.5-turbo
- **Anthropic**: Claude models
- **Custom**: Extend for any API

## 📊 Example NPC States

```json
{
  "name": "Elara",
  "role": "blacksmith",
  "emotions": {"happiness": 0.7, "anger": 0.1},
  "memories": [
    {"content": "Player bought a sword", "importance": 0.6},
    {"content": "Player asked about apprentice", "importance": 0.8}
  ],
  "relationships": {
    "Player": {"trust": 0.75, "familiarity": 0.9}
  }
}
```

## 🎯 Use Cases

- **RPGs**: Shopkeepers who remember your purchases
- **Adventure Games**: NPCs with emotional arcs
- **MMOs**: Persistent NPC relationships across sessions
- **Visual Novels**: Dynamic character development
- **Simulation Games**: AI characters with realistic social behavior

## 🔧 API Reference

### NPCAgent

```python
class NPCAgent:
    def __init__(self, name, role="villager", personality=None, backstory=None)
    def chat(self, player_name, message) -> str
    def get_status(self, player_name) -> dict
    def save_state(self, filepath)
    def load_state(self, filepath)
```

### Memory System

```python
memory_store = MemoryStore(max_memories=100)
memory_store.add(Memory("Player helped me", importance=0.8))
relevant = memory_store.retrieve("help", limit=5)
```

## 🤝 Contributing

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md).

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

## 🌟 Roadmap

- [ ] Unity Asset Store package
- [ ] Godot Asset Library plugin
- [ ] Docker container with pre-configured models
- [ ] Voice synthesis integration
- [ ] Multi-language support
- [ ] WebSocket real-time dialogue
- [ ] Mobile game optimizations

## 📞 Contact & Support

### **Get Help**
- **🐛 Bug Reports:** [GitHub Issues](https://github.com/supernpc/npcs/issues/new?template=bug_report.md)
- **💡 Feature Requests:** [GitHub Issues](https://github.com/supernpc/npcs/issues/new?template=feature_request.md)
- **💬 General Discussion:** [GitHub Discussions](https://github.com/supernpc/npcs/discussions)
- **📖 Documentation:** [docs.supernpc.ai](https://supernpc.ai/docs)

### **Community**
- **Discord:** [Join our community](https://discord.gg/supernpc)
- **Twitter/X:** [@supernpc](https://twitter.com/supernpc)
- **GitHub:** [Super NPC Organization](https://github.com/supernpc)

### **Commercial Support**
For enterprise support, custom integrations, or priority assistance:
- **Email:** contact@supernpc.ai (coming soon)
- **GitHub Sponsors:** Support ongoing development

---

**Made with ❤️ for game developers who want smarter NPCs**

## 📊 Current Status

### ✅ **Completed (Phase 1)**
- [x] Extract core AI from Pygame dependencies
- [x] Create standalone supernpc package
- [x] Add multiple LLM backend support (Ollama, OpenAI, Anthropic)
- [x] JSON state serialization for any game
- [x] Python library API
- [x] REST API server implementation
- [x] Comprehensive test suite

### 🚧 **In Progress (Phase 2)**
- [ ] Unity C# bindings
- [ ] Godot GDScript integration
- [ ] Docker containerization
- [ ] Performance optimization for 100+ NPCs

### 📋 **Roadmap (Phase 3+)**
- [ ] WebSocket real-time dialogue
- [ ] Voice synthesis integration
- [ ] Multi-language support
- [ ] Unity Asset Store package
- [ ] Godot Asset Library plugin