🎮 NPC Simulator - AI Conversation System

A stateful, personality-driven conversational AI system where each NPC (Non-Player Character) has unique traits, memory, and behavior patterns. Built with Spring Boot, MongoDB, Redis, and LLM APIs.

🧠 Overview

This is a production-grade implementation of the NPC Simulator HLD from the ChatGPT conversation. The system implements all 7 major components:

1. API Gateway — Authentication, rate limiting, routing
2. Conversation Service — Main backend orchestration (Java Spring Boot)
3. Character Engine — Personality and behavioral definition
4. Memory Service — Short-term (Redis) + long-term (MongoDB) memory
5. Prompt Builder — Combines personality + memory + user input
6. AI Service — Calls LLM (OpenAI/Anthropic, direct or via FastAPI)
7. Post Processor — Quality assurance and safety filtering

🏗️ Architecture

Client (Web / Mobile)
    ↓
API Gateway (Authentication, Rate Limiting)
    ↓
Conversation Service (Spring Boot)
    ├─ Character Engine (Personality Layer)
    ├─ Memory Service (Redis + MongoDB)
    ├─ Prompt Builder
    └─ AI Service (LLM Integration)
    ↓
Post Processor (Quality Check)
    ↓
Response → Client

📋 Features

• ✅ Stateful Conversations — Each user-NPC pair has independent session management
• ✅ Personality-Driven — NPCs have customizable traits, tone, and behavior
• ✅ Multi-Layer Memory — Short-term (Redis for speed) + long-term (MongoDB for persistence)
• ✅ LLM Flexibility — Support for OpenAI and Anthropic APIs
• ✅ Scalable Architecture — Horizontal scaling with stateless services
• ✅ Optional FastAPI Wrapper — Advanced orchestration and caching layer
• ✅ Docker Support — Full containerization with docker-compose
• ✅ Quality Assurance — Response filtering and confidence scoring

🚀 Quick Start

Prerequisites

• Java 17+
• Maven 3.8+
• Docker & Docker Compose (optional, for containerized setup)
• MongoDB 7.0+
• Redis 7+
• LLM API Key (OpenAI or Anthropic)

Option 1: Docker Compose (Recommended)

# Set environment variables
export LLM_API_KEY=your-openai-api-key
export LLM_API_TYPE=openai  # or 'anthropic'

# Start all services
docker-compose up -d

# Verify services
docker-compose ps

# Check backend health
curl http://localhost:8080/api/npcs

Option 2: Local Development

1. Start MongoDB:

mongod --dbpath ./data/mongodb

2. Start Redis:

redis-server

3. Build the backend:

mvn clean package

4. Run the backend:

java -jar target/npc-simulator-backend-0.1.0-MVP.jar

The application will start on http://localhost:8080/api

📚 API Endpoints

1. NPCs (List and retrieve NPC definitions)

Get all NPCs:

GET /api/npcs

Get specific NPC:

GET /api/npcs/{npcId}

Response example:

{
  "id": "npc_123",
  "name": "Alex Manager",
  "description": "Sarcastic and impatient project manager",
  "personality": {
    "primaryTrait": "sarcastic",
    "traits": ["impatient", "direct", "technical"],
    "tone": "professional",
    "background": "10 years of project management experience",
    "speakingStyle": "uses technical jargon, speaks concisely"
  },
  "isActive": true
}

2. Sessions (Create and manage conversations)

Create a new session:

POST /api/sessions
Header: X-User-Id: user_123
Body:
{
  "npcId": "npc_123",
  "sessionContext": "Discussing project delays"
}

Get user sessions:

GET /api/sessions
Header: X-User-Id: user_123

Get specific session:

GET /api/sessions/{sessionId}
Header: X-User-Id: user_123

Close a session:

DELETE /api/sessions/{sessionId}

3. Chat (Send messages and get NPC responses)

Send message:

POST /api/chat/message
Header: X-User-Id: user_123
Body:
{
  "sessionId": "session_xyz",
  "content": "Why is the project delayed?"
}

Response example:

{
  "id": "msg_456",
  "sessionId": "session_xyz",
  "role": "npc",
  "content": "Well, the team was waiting for requirements clarification, but sure, let's pretend it's just bad planning.",
  "timestamp": "2024-04-16T10:30:00",
  "modelUsed": "gpt-4",
  "confidenceScore": 0.95
}

🔧 Configuration

Environment Variables

# MongoDB
SPRING_DATA_MONGODB_URI=mongodb://localhost:27017/npc_simulator

# Redis
SPRING_REDIS_HOST=localhost
SPRING_REDIS_PORT=6379

# LLM API
LLM_API_KEY=sk-...
LLM_API_TYPE=openai  # or 'anthropic'
LLM_MODEL=gpt-4
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=500

# JWT
JWT_SECRET=your-secret-key

# FastAPI Wrapper (optional)
USE_FASTAPI_WRAPPER=false
FASTAPI_URL=http://localhost:8000

YAML Configuration

See src/main/resources/application.yml for all configurable options.

🎭 Creating Custom NPCs

Via MongoDB (Direct)

# Connect to MongoDB
mongosh mongodb://localhost:27017/npc_simulator

# Insert custom NPC
db.npcs.insertOne({
  "_id": ObjectId(),
  "name": "Customer Support Agent",
  "description": "Friendly and patient support specialist",
  "personality": {
    "primaryTrait": "empathetic",
    "traits": ["patient", "helpful", "knowledgeable"],
    "tone": "friendly",
    "background": "5 years in customer support",
    "speakingStyle": "uses a warm, conversational tone",
    "behavioralRules": {
      "rule1": "Always acknowledge customer frustration",
      "rule2": "Provide solutions rather than explanations"
    }
  },
  "config": {
    "maxTokens": 300,
    "temperature": 0.6
  },
  "createdAt": new Date(),
  "updatedAt": new Date(),
  "isActive": true
})

🔄 End-to-End Chat Flow

This is how a user message becomes an NPC response:

1. User sends message → Chat endpoint receives request
2. API Gateway → Validates authentication (via X-User-Id header)
3. Session & NPC retrieval → Fetches active session and NPC config
4. Character Engine → Builds personality context from NPC traits
5. Memory Service → Retrieves last 5 messages + relevant memories
6. Prompt Builder → Combines personality + memory + user message
7. AI Service → Calls OpenAI/Anthropic API with final prompt
8. Post Processor → Validates confidence, filters unsafe content, trims length
9. Response saved → Stores both user and NPC messages in MongoDB
10. Cache updated → Recent messages cached in Redis for speed
11. Response returned → User receives NPC reply with metadata

📊 Data Models

User

{
  id: String,           // MongoDB ObjectId
  name: String,
  email: String,
  passwordHash: String,
  createdAt: LocalDateTime,
  updatedAt: LocalDateTime,
  isActive: Boolean
}

NPC

{
  id: String,
  name: String,
  description: String,
  personality: {
    primaryTrait: String,
    traits: List<String>,
    tone: String,
    background: String,
    speakingStyle: String,
    behavioralRules: Map<String, String>
  },
  config: Map<String, Object>,
  createdAt: LocalDateTime,
  updatedAt: LocalDateTime,
  isActive: Boolean
}

Session

{
  id: String,
  userId: String,
  npcId: String,
  startedAt: LocalDateTime,
  lastActivityAt: LocalDateTime,
  messageCount: Integer,
  sessionContext: String,
  isActive: Boolean
}

Message

{
  id: String,
  sessionId: String,
  role: String,           // "user" or "npc"
  content: String,
  timestamp: LocalDateTime,
  internalPrompt: String, // (NPC only) Actual prompt sent to LLM
  modelUsed: String,      // (NPC only) Model name (gpt-4, claude-3, etc.)
  confidenceScore: Double // (NPC only) 0.0-1.0
}

📈 Scalability

Stateless Design

• No server-side state except databases
• Load balance across multiple instances
• Each service can scale independently

Caching Strategy

• Short-term: Redis for recent messages (TTL: 1 hour)
• Long-term: MongoDB for persistence
• Optional: Vector DB for semantic search

Performance Optimization

• Connection pooling (HTTP, MongoDB, Redis)
• Response caching by prompt hash
• Batch operations for bulk inserts
• Index optimization on frequently queried fields

🔐 Security

Current Implementation

• JWT authentication via X-User-Id header
• Basic rate limiting configuration
• Content moderation in Post Processor

Recommendations for Production

• Implement proper OAuth2/JWT token validation
• Add rate limiting with Redis
• Enable HTTPS/TLS
• Use API keys for LLM API calls
• Implement audit logging
• Add request/response encryption for sensitive data

🧪 Testing

Unit Tests

mvn test

Integration Tests

mvn verify

Manual Testing

# Create a session
curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" \
  -H "X-User-Id: test_user" \
  -d '{"npcId": "npc_123", "sessionContext": "test"}'

# Send a chat message
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -H "X-User-Id: test_user" \
  -d '{"sessionId": "session_xyz", "content": "Hello!"}'

🚀 Advanced Features

1. Python FastAPI Wrapper (Optional)

For advanced LLM orchestration:

docker-compose --profile fastapi up

Endpoints:

• POST /v1/prompt — Process prompt with caching
• POST /v1/semantic-search — Search memories by semantic similarity

2. Multi-NPC Conversations

Support for multiple NPCs in one session (future enhancement)

3. Personality Evolution

NPCs adapt based on conversation history (future enhancement)

4. Analytics Dashboard

Track engagement metrics and popular NPCs (future enhancement)

📝 Logs and Monitoring

Logs are written to console and can be sent to centralized logging services:

# src/main/resources/application.yml
logging:
  level:
    root: INFO
    com.npcsimulator: DEBUG

🛠️ Troubleshooting

MongoDB Connection Error

Check if MongoDB is running:
mongosh mongodb://localhost:27017

If using Docker:
docker logs npc-simulator-mongodb

Redis Connection Error

Check if Redis is running:
redis-cli ping

If using Docker:
docker logs npc-simulator-redis

LLM API Error

Verify API key:
echo $LLM_API_KEY

Test API connection:
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "hello"}]}' 

Memory/Cache Issues

Clear Redis cache:

redis-cli FLUSHALL

Or via Docker:
docker exec npc-simulator-redis redis-cli FLUSHALL

📚 Project Structure

npc-simulator/
├── src/main/java/com/npcsimulator/
│   ├── api/
│   │   ├── controller/          # REST endpoints
│   │   └── dto/                 # Data transfer objects
│   ├── domain/
│   │   ├── model/               # Entity classes
│   │   └── repository/          # Data access layer
│   ├── service/
│   │   ├── ai/                  # AI/LLM service
│   │   ├── CharacterEngine.java
│   │   ├── MemoryService.java
│   │   ├── PromptBuilder.java
│   │   ├── PostProcessor.java
│   │   ├── ConversationService.java (Orchestrator)
│   │   └── ...
│   └── config/                  # Spring configurations
├── src/main/resources/
│   └── application.yml          # Configuration
├── fastapi_wrapper/
│   ├── main.py                  # FastAPI app
│   ├── requirements.txt
│   └── Dockerfile
├── pom.xml                       # Maven dependencies
├── Dockerfile                    # Backend container
├── docker-compose.yml            # Full stack setup
└── README.md                     # This file

🎯 Interview Summary (30 seconds)

"I designed a scalable, stateful AI conversation system where each NPC has unique personality traits and maintains conversation history. The backend (Spring Boot) orchestrates seven components: an API Gateway for security, Conversation Service for coordination, Character Engine for personality definition, Memory Service with Redis caching for performance, Prompt Builder for intelligent input construction, AI Service for LLM integration with both direct APIs and optional FastAPI wrapper, and Post Processor for response quality assurance. The system persists conversations in MongoDB while using Redis for sub-second response times, supports both OpenAI and Anthropic APIs, and scales horizontally with a stateless architecture."

🔮 Future Enhancements

• Multi-NPC group conversations
• NPC personality evolution over time
• Semantic memory with vector DB
• Prompt caching to reduce costs
• Advanced analytics dashboard
• Voice integration (TTS/STT)
• Real-time streaming responses
• Fine-tuned models for specific NPCs

📞 Support

For issues or questions:

1. Check the troubleshooting section
2. Review Docker logs: docker-compose logs -f
3. Enable debug logging in application.yml

📄 License

MIT License - Feel free to use for any purpose

🙏 Acknowledgments

Built from the NPC Simulator HLD discussion on ChatGPT. References production best practices in:

• Microservices architecture
• Cache-aside pattern
• API design
• LLM integration

---

Happy building! 🚀