https://github.com/991o2o9/ai_agent_backend
Urban Future: Voices of the City – Backend API and core logic for the interactive city simulation. Handles AI-driven NPC behaviors, dialogue management, memory storage, and game state, enabling dynamic social interactions and decision-making in the game world.
https://github.com/991o2o9/ai_agent_backend
ai-agents fastapi npc postgresql python redis
Last synced: about 1 month ago
JSON representation
Urban Future: Voices of the City – Backend API and core logic for the interactive city simulation. Handles AI-driven NPC behaviors, dialogue management, memory storage, and game state, enabling dynamic social interactions and decision-making in the game world.
- Host: GitHub
- URL: https://github.com/991o2o9/ai_agent_backend
- Owner: 991o2o9
- Created: 2025-09-02T02:58:24.000Z (9 months ago)
- Default Branch: dev
- Last Pushed: 2025-09-04T15:16:39.000Z (9 months ago)
- Last Synced: 2025-09-04T17:28:49.409Z (9 months ago)
- Topics: ai-agents, fastapi, npc, postgresql, python, redis
- Language: Python
- Homepage:
- Size: 87.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🎮 NPC Game Backend
[](https://fastapi.tiangolo.com/)
[](https://www.python.org/)
[](https://www.postgresql.org/)
[](https://redis.io/)
[](https://www.docker.com/)
**A modern, high-performance FastAPI backend service for NPC (Non-Player Character) game interactions**
[📚 API Docs](http://localhost:8000/docs) • [🔧 Configuration](#-configuration) • [🚀 Quick Start](#-quick-start) • [🤝 Contributing](#-contributing)
---
## ✨ Features
🚀 **High Performance**
- FastAPI async framework
- Optimized database queries
- Redis caching layer
🔐 **Security First**
- JWT-based authentication
- Password hashing with Passlib
- Session management
🎮 **Game Systems**
- NPC management & interactions
- Session handling & state
- User progress tracking
🛠️ **Developer Experience**
- Auto-generated API docs
- Database migrations
- Docker containerization
## 🏗️ Architecture
```mermaid
graph TB
A[Client] -->|HTTP Requests| B[FastAPI Backend]
B --> C[Authentication Service]
B --> D[NPC Service]
B --> E[Session Service]
B --> F[User Service]
C --> G[(PostgreSQL)]
D --> G
E --> G
F --> G
B --> H[(Redis Cache)]
style A fill:#e1f5fe
style B fill:#f3e5f5
style G fill:#e8f5e8
style H fill:#fff3e0
```
## 🛠️ Tech Stack
| Category | Technology |
|----------|------------|
| **Backend** |   |
| **Database** |   |
| **Cache** |  |
| **Auth** |   |
| **DevOps** |   |
| **Tools** |  |
## 📋 Prerequisites
> **Note**: Make sure you have the following installed on your system:
- 🐍 **Python 3.11+**
- 📦 **Poetry** (dependency management)
- 🐳 **Docker & Docker Compose**
- 🐘 **PostgreSQL 15** (for local development)
- 🔴 **Redis 7** (for local development)
## 🚀 Quick Start
### 🐳 Docker Setup (Recommended)
```bash
# 1. Clone the repository
git clone
cd ai_agent_backend
# 2. Environment setup
# Create .env file with your configuration (see Configuration section below)
# 3. Launch all services
docker-compose up -d
# 4. Run database migrations
docker-compose exec backend alembic upgrade head
# 5. 🎉 You're ready to go!
# API: http://localhost:8000
# Docs: http://localhost:8000/docs
```
### 🔧 Local Development
Click to expand local development setup
```bash
# 1. Install Poetry
curl -sSL https://install.python-poetry.org | python3 -
# 2. Install dependencies
poetry install
# 3. Activate virtual environment
poetry shell
# 4. Setup environment
cp .env.example .env
# 5. Start databases
docker-compose up -d db redis
# 6. Run migrations
alembic upgrade head
# 7. Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
## 📁 Project Structure
```
ai_agent_backend/
├── 📁 alembic/ # Database migrations
│ ├── env.py
│ ├── script.py.mako
│ └── versions/
├── 📁 app/
│ ├── 📁 api/ # 🛣️ API route handlers
│ │ ├── npc.py
│ │ ├── sessions.py
│ │ └── users.py
│ ├── 📁 core/ # ⚙️ Core configuration
│ │ ├── config.py
│ │ ├── db.py
│ │ ├── redis.py
│ │ └── security.py
│ ├── 📁 models/ # 🗃️ SQLAlchemy models
│ │ ├── npc.py
│ │ ├── session.py
│ │ └── user.py
│ ├── 📁 repositories/ # 💾 Data access layer
│ │ ├── npc_repo.py
│ │ ├── session_repo.py
│ │ └── user_repo.py
│ ├── 📁 schemas/ # 📋 Pydantic schemas
│ │ ├── npc.py
│ │ ├── session.py
│ │ └── user.py
│ ├── 📁 services/ # 🧠 Business logic
│ │ ├── npc_service.py
│ │ ├── session_service.py
│ │ └── user_service.py
│ └── 📄 main.py # 🚀 FastAPI application
├── 🐳 docker-compose.yml
├── 📦 pyproject.toml
└── 📖 README.md
```
## ⚙️ Configuration
Create a `.env` file in the root directory:
```env
# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/npc_game_db
REDIS_URL=redis://localhost:6379/0
# Security Configuration
SECRET_KEY=your-super-secret-key-here-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
# Hugging Face Configuration (Required for AI NPC responses)
HUGGINGFACE_API_TOKEN=your-huggingface-api-token-here
HUGGINGFACE_MODEL=mistralai/Mistral-7B-Instruct-v0.2
HUGGINGFACE_MODEL_PROVIDER=featherless-ai
# AI API Endpoints (optional - these have sensible defaults)
HUGGINGFACE_CHAT_API_URL=https://router.huggingface.co/v1/chat/completions
HUGGINGFACE_INFERENCE_API_URL=https://api-inference.huggingface.co/models/mistralai/Mistral-7B-Instruct-v0.2
# AI Generation Settings
MAX_TOKENS=512
TEMPERATURE=0.7
TOP_P=0.9
AI_TIMEOUT=30
# Memory Settings
SHORT_MEMORY_TTL=3600
LONG_MEMORY_LIMIT=100
# Rate Limiting
MAX_REQUESTS_PER_MINUTE=60
MAX_REQUESTS_PER_HOUR=1000
```
**Important Security Notes:**
- 🔐 Never commit your `.env` file to version control
- 🔑 Generate a strong, unique `SECRET_KEY` for production
- 🎫 Get your Hugging Face API token from [Hugging Face Settings](https://huggingface.co/settings/tokens)
- 🌍 In production, use environment variables instead of `.env` files
## 📚 API Documentation
Once the server is running, explore the API:
| Service | URL | Description |
|---------|-----|-------------|
| 🏠 **Home** | http://localhost:8000 | Health check endpoint |
| 📖 **Swagger UI** | http://localhost:8000/docs | Interactive API documentation |
| 📚 **ReDoc** | http://localhost:8000/redoc | Alternative API documentation |
### 🛣️ Key Endpoints
👥 User Management
- `POST /users/register` - Register new user
- `POST /users/login` - User authentication
- `GET /users/me` - Get current user profile
🎮 Session Management
- `POST /sessions/` - Create new game session
- `GET /sessions/` - List user sessions
- `GET /sessions/{id}` - Get session details
🤖 NPC Management
- `POST /npc/` - Create new NPC
- `GET /npc/` - List all NPCs
- `GET /npc/{id}` - Get NPC details
## 🗄️ Database Operations
### Migrations
```bash
# Create new migration
alembic revision --autogenerate -m "Add new feature"
# Apply migrations
alembic upgrade head
# Rollback last migration
alembic downgrade -1
```
## 🧪 Development & Testing
```bash
# Install development dependencies
poetry install --with dev
# Run tests
pytest
# Code formatting
black .
isort .
flake8 .
```
## 🐳 Docker Commands
```bash
# 🚀 Start all services
docker-compose up -d
# 📋 View logs
docker-compose logs -f backend
# 🛑 Stop services
docker-compose down
# 🔄 Rebuild and restart
docker-compose up -d --build
# 💻 Access backend container
docker-compose exec backend bash
```
## 🔮 Roadmap
- [ ] 🌐 WebSocket support for real-time interactions
- [ ] 🧠 Advanced NPC AI behaviors using LLMs
- [ ] 💾 Enhanced game state persistence
- [ ] 👥 Multiplayer session support
- [ ] 📊 Performance monitoring and metrics
- [ ] 🚦 API rate limiting
- [ ] 🧪 Comprehensive test coverage
- [ ] 🎨 Admin dashboard
- [ ] 📱 Mobile API optimizations
## 🤝 Contributing
We welcome contributions! Here's how you can help:
1. 🍴 Fork the repository
2. 🌿 Create your feature branch (`git checkout -b feature/amazing-feature`)
3. ✅ Commit your changes (`git commit -m 'Add some amazing feature'`)
4. 📤 Push to the branch (`git push origin feature/amazing-feature`)
5. 🔃 Open a Pull Request
### 📝 Contribution Guidelines
- Follow PEP 8 style guidelines
- Add tests for new features
- Update documentation as needed
- Use conventional commit messages
## 🆘 Support
Need help? We're here for you!
- 🐛 [Create an Issue](https://github.com/your-username/ai_agent_backend/issues)
- 💬 [Discussions](https://github.com/your-username/ai_agent_backend/discussions)
- 📧 Contact the maintainer
## 👨💻 Author
**Amin Soltobekov**
[](https://www.linkedin.com/in/amin-soltobekov-482b5430b/)
[](https://github.com/yourusername)
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
**⭐ Star this repo if you find it helpful!**
Made with ❤️ and ☕ by [Amin Soltobekov](https://www.linkedin.com/in/amin-soltobekov-482b5430b/)