---
title: Korean Cpc Agents
emoji: 💻
colorFrom: indigo
colorTo: green
sdk: docker
pinned: false
license: mit
short_description: Interactive Korean language learning  MUD game
---

# Korean Learning MUD Game 🇰🇷

Interactive Korean language learning through conversation with AI-powered Korean family members in a retro MUD-style game.

![Korean Family Portrait](assets/images/Family%20portraits%202ChatGPT%20Image%20Aug%2017,%202025,%2010_48_14%20PM.png)

> **Live Demo:** Hosted on HuggingFace Spaces for easy access

## Features

- 🏠 **Explore a Korean Family House** - Navigate through 6 rooms (Hall, Kitchen, Garden, Bedroom, Study, Classroom)
- 👨‍👩‍👧‍👦 **Chat with Unique NPCs** - Each family member has distinct personalities and teaching styles
- 🔍 **Examine Cultural Objects** - Interactive objects in each room teach Korean vocabulary and culture
- 🎨 **Retro Terminal Aesthetic** - Beautiful brown/tan Korean traditional vibes
- 📚 **Progressive Learning System** - Smart vocabulary tracking with no repeats
- 💬 **Natural Conversation** - Chat naturally with AI agents powered by CrewAI
- 🎒 **Inventory System** - Collect examined objects and track learning progress

## Korean Family Members

Meet your Korean language teachers - each AI agent has a unique personality and teaching style powered by CrewAI:

| Family Member             | Korean Name     | Room         | Teaching Focus                    | Avatar                                                                                            |
| ------------------------- | --------------- | ------------ | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Grandma Kim Soon-ja**   | 김순자 할머니   | 🍳 Kitchen   | Honorifics & Formal Speech        | ![Grandma](assets/images/Ahjumma%20ChatGPT%20Image%20Mar%2026,%202025,%2005_36_15%20PM.png)       |
| **Grandpa Park Chul-min** | 박철민 할아버지 | 🌸 Garden    | Traditional Culture & Proverbs    | ![Grandpa](assets/images/Ahjussi%20ChatGPT%20Image%20May%205,%202025,%2004_37_07%20PM.png)        |
| **Sister Lee Min-ji**     | 이민지 언니     | 🎵 Bedroom   | K-pop & Modern Slang              | ![Sister](assets/images/K-pop%20trainee%20ChatGPT%20Image%20May%205,%202025,%2004_35_54%20PM.png) |
| **Brother Jung Jae-hyun** | 정재현 오빠     | 📚 Study     | Grammar & Academic Korean         | ![Brother](assets/images/SunbaeOppa%20ChatGPT%20Image%20May%205,%202025,%2004_07_13%20PM.png)     |
| **Teacher Choi Soo-jin**  | 최수진 선생님   | ✏️ Classroom | Practical Phrases & Communication | ![Teacher](assets/images/SeonsaengnimChatGPT%20Image%20Aug%2017,%202025,%2010_41_39%20PM.png)     |

## How to Play

### Basic Commands

- `look` - Look around your current room
- `go [room]` - Move to another room (kitchen, garden, bedroom, study, classroom, hall)
- `examine [object]` - Examine objects to learn Korean vocabulary
- `chat [message]` - Talk to the Korean family member in your room
- `help` - Show all available commands
- `map` - See the house layout and room locations

### Game Flow

1. **Start in the Hall** - Central hub connecting all rooms
2. **Visit Family Members** - Each room has a different Korean family member
3. **Examine Objects** - Learn vocabulary and cultural context
4. **Practice Conversations** - Natural Korean language practice
5. **Track Progress** - See words learned and objects examined

## Screenshots

![Game Running](assets/images/app-running.png)
_Main game interface with retro terminal styling_

![Chat with Grandmother](assets/images/chat-grandmother.png)
_Learning proper Korean honorifics with Grandma in the Kitchen_

![Chat with Grandfather](assets/images/chat-grandfather.png)
_Traditional Korean wisdom and proverbs in the Garden_

![Vocabulary & Inventory Tracking](assets/images/chat-words+inventory.png)
_Track your Korean learning progress and cultural discoveries_

## Quick Start

### Option 1: Docker (Recommended)

1. **Clone and navigate to project:**

   ```bash
   git clone https://github.com/Ramsi-K/korean-cpc-agents
   cd korean-cpc-agents
   ```

2. **Set up environment:**

   ```bash
   # Create .env file with your OpenAI API key
   echo "OPENAI_API_KEY=your-api-key-here" > .env
   ```

3. **Run with Docker Compose:**

   ```bash
   docker compose up --build
   ```

4. **Play the game:**
   Open http://localhost:7860 in your browser!

### Option 2: Local Development

1. **Install dependencies:**

   ```bash
   uv sync
   ```

2. **Set up your OpenAI API key:**

   ```bash
   export OPENAI_API_KEY="your-api-key-here"
   ```

3. **Run the game:**

   ```bash
   uv run python web_server.py
   ```

4. **Open your browser:**

   ```bash
   http://localhost:7860
   ```

## Technology Stack

- **Backend:** FastAPI + Python
- **AI Agents:** CrewAI with OpenAI GPT models
- **Frontend:** Vanilla HTML/CSS/JavaScript with retro terminal styling
- **Package Management:** uv
- **Game Engine:** Custom MUD-style text adventure system

## Project Structure

```yaml
korean-cpc-agents/
├── src/korean_cpc_agents/    # Core game logic and AI agents
├── korean_mud_game.html      # Frontend interface
├── web_server.py            # FastAPI backend server
├── assets/images/           # Game images and sprites
└── examples/               # Screenshots and demos
```

## License

Open source - feel free to fork and create your own language learning MUD games!

---

*Learn Korean through immersive conversations with AI-powered family members! 한국어를 배워보세요! 🇰🇷*🫰
[With Love](assets/images/Ahjumma%20and%20Ahjussi.png)