Practice speaking Japanese with AI native speakers and build your vocabulary through real conversations.

Core Purpose: Have natural conversations with Japanese-speaking AI characters while the app automatically extracts and saves vocabulary words that appear during your chat. Review these words later as flashcards to reinforce your learning.

Powered by OpenAI's Realtime API for authentic, low-latency voice interactions.

• Low-latency voice chat powered by OpenAI Realtime API
• Natural turn detection with Server VAD
• High-quality 24kHz audio
• Continuous conversation mode

• Automatic Vocabulary Extraction: Real-time word analysis during conversations
• JLPT Level Classification: Automatic N5-N1 difficulty classification
• Korean Translations: Korean meanings for all vocabulary
• Filtering Options: View words by JLPT level
• Export Learning Materials: Download vocabulary lists

• Yuki Sensei (雪先生): Professional Japanese teacher
• Tanaka San (田中さん): Business professional
• Sakura Chan (さくらちゃん): Friendly student
• Kenji Kun (健二くん): Casual friend
• Yamada Sensei (山田先生): Academic professor
• AI Assistant: Helpful AI companion

• Python 3.8+
• OpenAI API Key with Realtime API access
• Microphone for voice input

# Clone repository
git clone [repository-url]
cd conversation-bot

# Install uv if you don't have it (ultra-fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install packages
uv venv --python 3.11
source .venv/bin/activate
uv pip install -r requirements.txt

# Clone repository
git clone [repository-url]
cd conversation-bot

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install packages
pip install -r requirements.txt

# Setup and install
make setup       # Creates virtual environment
source .venv/bin/activate
make install     # Installs packages

# Create .env file
cp .env.example .env

# Edit .env and add your OpenAI API key
OPENAI_API_KEY=your-api-key-here

# Basic run
streamlit run main.py

Or use helper scripts:

./run_dev.sh   # Development mode (auto-reload, debug logs)
./run_prod.sh  # Production mode

Open browser at http://localhost:8501

1. Connect: Enter your OpenAI API key and click "Connect"
2. Choose Your Partner: Select an AI character that matches your learning style
3. Start Speaking: Click "Start Conversation" and speak naturally in Japanese
4. Build Vocabulary: As you converse, new words automatically appear in the vocabulary panel with:
   • Furigana (reading hints)
   • Korean translations
   • JLPT level indicators
5. Filter by Level: Use the dropdown to focus on words at your level
6. Review Later: Export your vocabulary list as a study sheet for flashcard review

• All Levels: Show all vocabulary
• N5 only: Beginner words only
• N4+: N4 and above (intermediate-advanced)
• N3+: N3 and above (upper-intermediate-advanced)
• N2+: N2 and above (advanced-expert)
• N1 only: Expert level only

• Frontend: Streamlit (Wide Layout)
• Voice API: OpenAI Realtime API (GPT-4)
• Audio: PyAudio, WebSocket
• Vocabulary Analysis: GPT-4 context-aware analysis
• TTS Voices: Alloy, Echo, Shimmer

conversation-bot/
├── main.py                     # Main application
├── src/
│   └── vocabulary_analyzer.py  # Vocabulary analysis module
├── config/
│   └── personas.json           # AI character configurations
├── run_dev.sh                  # Development script
├── run_prod.sh                 # Production script
└── requirements.txt            # Dependencies

• Requires stable internet connection
• Microphone permissions required
• OpenAI API usage incurs costs
• Realtime API beta access required
• Chrome/Edge browser recommended

• Clear Chat Button: Due to Streamlit's state management, the Clear Chat button may not immediately clear messages from the display. Messages will be cleared when the next interaction occurs. This is a known Streamlit limitation.
• Multiple Voice Sessions: Occasionally, multiple voice responses may overlap. If this happens, disconnect and reconnect.
• Voice Recognition Delay: There may be a 1-2 second delay before your speech is recognized and processed.
• Browser Compatibility: Best performance on Chrome and Edge. Safari and Firefox may have audio issues.

• Database Integration: Save conversation history and vocabulary lists with SQLite
• Fix Clear Chat: Resolve Streamlit state management issue
• Export to Anki: Generate flashcard decks from vocabulary
• Prevent Audio Overlap: Fix multiple voice sessions issue

• User Profiles: Track learning progress over time
• Example Sentences: Add context sentences for each vocabulary word
• Spaced Repetition: Implement review scheduling for vocabulary
• Learning Analytics: Show vocabulary growth and speaking time stats

• Mobile App: React Native version for on-the-go practice
• Scenario Mode: Structured conversations (restaurant, shopping, etc.)
• Grammar Detection: Identify and explain grammar patterns
• Offline Vocabulary: Cache vocabulary for offline review

Please submit bug reports and feature requests via Issues. Check the TODO list above for areas where contributions are welcome!

MIT License