Wed, Oct 08, 25, README TUI - Auto-imported from uconGPT project

Auto-imported from: D:/repos/aiegoo/uconGPT/eng2Fix/kor2fix/README_TUI.md
Original filename: README_TUI.md
Import date: Wed, Oct 08, 25

Korean Learning Advanced TUI

๐ŸŽฏ Overview

Advanced Text User Interface (TUI) for Korean language learning with multi-backend AI support. Built with Pythonโ€™s Textual framework for a modern terminal experience.

Korean TUI Demo (Screenshots will be added)

โœจ Features

  • ๐ŸŽจ Rich Terminal Interface: Modern TUI with colors, borders, and responsive design
  • ๐Ÿ”„ Multi-Backend Support: Switch between Ollama (Mistral) and self-hosted models
  • ๐Ÿ‡ฐ๐Ÿ‡ท Korean Learning Focus: Specialized prompts and learning modes
  • โŒจ๏ธ Keyboard Navigation: Intuitive controls and shortcuts
  • ๐Ÿ“ Session Logging: Track learning progress and conversations
  • ๐ŸŒ“ Dark/Light Mode: Toggle interface themes

๐Ÿš€ Quick Start

Prerequisites

  • Python 3.8+ (recommended 3.10+)
  • Modern terminal with Unicode support
  • At least one AI backend running (Ollama or self-hosted)

Installation

# Clone repository
cd /home/hsyyu/repo/kor2unity

# Install dependencies
pip install textual httpx

# Run the TUI
cd scripts
python kor2unity_advanced_tui.py

One-Line Start (with Ollama)

cd /home/hsyyu/repo/kor2unity/scripts && python kor2unity_advanced_tui.py

๐Ÿ“š Documentation

๐Ÿ—๏ธ Architecture

File Structure

/home/hsyyu/repo/kor2unity/
โ”œโ”€โ”€ scripts/
โ”‚   โ”œโ”€โ”€ kor2unity_advanced_tui.py    # ๐ŸŽฏ Main TUI application
โ”‚   โ””โ”€โ”€ llm_api.py                   # ๐Ÿ”ง Self-hosted API server  
โ”œโ”€โ”€ docs/
โ”‚   โ”œโ”€โ”€ KOREAN_TUI_SETUP.md          # ๐Ÿ“– Complete setup guide
โ”‚   โ”œโ”€โ”€ QUICK_START.md               # โšก Quick start guide
โ”‚   โ””โ”€โ”€ screenshots/                 # ๐Ÿ“ธ Demo images
โ”œโ”€โ”€ logs/
โ”‚   โ””โ”€โ”€ korean_learning.log          # ๐Ÿ“ Session logs
โ””โ”€โ”€ requirements.txt                 # ๐Ÿ“ฆ Dependencies

Supported Backends

| Backend | Port | Model | Purpose | |โ€”โ€”โ€”|โ€”โ€”|โ€”โ€”-|โ€”โ€”โ€”| | Ollama | 11434 | Mistral | Fast general responses | | Self-hosted | 8204 | Llama2+MiniGPT4 | Korean learning specialized | | Container | 8203 | Ollama | Fallback option | | Legacy | 8201 | Various | Compatibility |

๐ŸŽฎ Usage

Keyboard Controls

  • Enter โ†’ Send message
  • e โ†’ Switch API endpoint
  • d โ†’ Toggle dark/light mode
  • Ctrl+E โ†’ Scroll to bottom
  • q โ†’ Quit application

Learning Commands

# Basic Korean greetings
์•ˆ๋…•ํ•˜์„ธ์š” (Hello)

# Grammar questions  
How do I conjugate verbs in Korean?

# Translation requests
Translate "I love learning Korean" to Korean

# Cultural questions
Tell me about Korean honorifics

๐Ÿ”ง Configuration

API Endpoints

Edit scripts/kor2unity_advanced_tui.py:

KOREAN_API_ENDPOINTS = {
    "ollama_primary": "http://localhost:11434/api/generate",
    "self_hosted": "http://localhost:8204/korean-learning",
    "ollama_container": "http://localhost:8203/api/generate",
    "legacy_api": "http://localhost:8201/chat"
}

Environment Variables

# Optional: Set custom model
export MISTRAL_MODEL="mistral:7b"

# Optional: Set custom timeout
export OLLAMA_TIMEOUT_SECONDS="60"

# Optional: Set log level
export LOG_LEVEL="INFO"

๐Ÿ› Troubleshooting

Common Issues

# Missing dependencies
pip install textual httpx

# Ollama not running
ollama serve

# Self-hosted API not running  
cd /home/hsyyu && python llm_api.py

# Korean fonts not displaying
sudo apt-get install fonts-noto-cjk

# Check running services
netstat -tulpn | grep -E "(8204|11434)"

Health Checks

# Test Ollama
curl -X POST http://localhost:11434/api/generate -d '{"model":"mistral","prompt":"test","stream":false}'

# Test self-hosted API
curl -X POST http://localhost:8204/korean-learning -d '{"question":"test","korean_mode":true}'

# View logs
tail -f ~/repo/kor2unity/logs/korean_learning.log

๐Ÿค Contributing

Development Setup

# Install development dependencies
pip install -r requirements.txt
pip install pytest black flake8

# Format code
black scripts/kor2unity_advanced_tui.py

# Run tests
pytest tests/

Adding New Features

  1. New endpoints: Modify KOREAN_API_ENDPOINTS dict
  2. UI components: Add to Textual compose() method
  3. Learning modes: Extend learning_mode options
  4. Keyboard shortcuts: Update BINDINGS list

๐Ÿ“Š Performance

Benchmarks

  • Startup time: ~2-3 seconds
  • Response time: 1-5 seconds (depends on backend)
  • Memory usage: ~50-100 MB
  • CPU usage: Minimal when idle

Optimization Tips

  1. Use Ollama for faster responses
  2. Enable logging only when needed
  3. Use modern terminal with GPU acceleration
  4. Keep model files on SSD storage

๐Ÿ“ License

MIT License - See LICENSE file for details

๐Ÿ™ Acknowledgments

  • Textual Framework - Rich terminal interface
  • Ollama - Local LLM serving
  • Korean Language Community - Learning resources and feedback

๐Ÿ“ž Support

  • Issues: Create GitHub issue with logs and screenshots
  • Documentation: See docs/ directory
  • Logs: Check ~/repo/kor2unity/logs/korean_learning.log

Ready to learn Korean? Start the TUI and type ์•ˆ๋…•ํ•˜์„ธ์š”! ๐Ÿ‡ฐ๐Ÿ‡ท