korean-cpc-agents / README.md
ramsi-k's picture
add demo
fc190df
|
Raw History Blame Contribute Delete
5.74 kB
metadata
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

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
Grandpa Park Chul-min λ°•μ² λ―Ό 할아버지 🌸 Garden Traditional Culture & Proverbs Grandpa
Sister Lee Min-ji 이민지 μ–Έλ‹ˆ 🎡 Bedroom K-pop & Modern Slang Sister
Brother Jung Jae-hyun μ •μž¬ν˜„ 였빠 πŸ“š Study Grammar & Academic Korean Brother
Teacher Choi Soo-jin μ΅œμˆ˜μ§„ μ„ μƒλ‹˜ ✏️ Classroom Practical Phrases & Communication Teacher

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 Main game interface with retro terminal styling

Chat with Grandmother Learning proper Korean honorifics with Grandma in the Kitchen

Chat with Grandfather Traditional Korean wisdom and proverbs in the Garden

Vocabulary & Inventory Tracking Track your Korean learning progress and cultural discoveries

Quick Start

Option 1: Docker (Recommended)

  1. Clone and navigate to project:

    git clone https://github.com/Ramsi-K/korean-cpc-agents
    cd korean-cpc-agents
    
  2. Set up environment:

    # Create .env file with your OpenAI API key
    echo "OPENAI_API_KEY=your-api-key-here" > .env
    
  3. Run with Docker Compose:

    docker compose up --build
    
  4. Play the game: Open http://localhost:7860 in your browser!

Option 2: Local Development

  1. Install dependencies:

    uv sync
    
  2. Set up your OpenAI API key:

    export OPENAI_API_KEY="your-api-key-here"
    
  3. Run the game:

    uv run python web_server.py
    
  4. Open your browser:

    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

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