💬 FluentIn: Korean Language Learning App

FluentIn is a Django-based Korean language learning app with real-time audio, comprehension checks, ChatGPT-powered feedback, and ANKI-style spaced repetition that can use a learner’s personal ANKI deck.

---

📁 Project Structure

fluentin
- fluentin
-- manage.py
-- db.sqlite3                     # demo/dev DB (optional)
-- requirements.txt               # Python deps (example)
-- fluentin                       # Django project
--- __init__.py
--- settings.py                   # externalize secrets in prod
--- urls.py                       # routes -> training.urls
--- wsgi.py
-- training                       # main app
--- __init__.py
--- models.py
--- urls.py                       # endpoints (see Routes)
--- views.py                      # UI #1
--- views2.py                     # UI #2
--- views3.py                     # UI #3 (simple login)
--- templates
---- base.html                    # UI #1
---- base2.html                   # UI #2
---- base3.html                   # UI #3
--- scenarios                     # CSV topics
--- anki_file                     # put your collection.anki2 here
-- static                         # collected static (prod)

---

📌 2 Ways to Run The Project & Where to Place OpenAI API Keys

Running the project

• FluentIn is a Django web application. You can run it locally by setting up a Django server and placing the project folder inside your local environment.
• Alternatively, you may also create a Django instance via AWS Lightsail and place the folder inside /home/bitnami/projects/.
• These are discussed in detail in the next 2 sections below.

API keys

You’ll need to insert a valid ChatGPT API key in the following files/lines:

fluentin/training/viewsX.py           # X = 1, 2, or 3 (different UI flows)
  - line 152
  - line 523
  - line 668

fluentin/training/templates/baseX.html
  - line 591

Note: views1, views2, and views3 represent different versions of the interaction flow. The version currently running at the link above uses views2.py along with its corresponding template, base2.html.

---

🚀 Run Locally (simple Django dev server)

Prereqs

• Python 3.8–3.11
• ffmpeg for audio
  • macOS: brew install ffmpeg
  • Ubuntu: sudo apt-get install -y ffmpeg
• (If using mic features) PortAudio dev headers
  • macOS: brew install portaudio
  • Ubuntu: sudo apt-get install -y portaudio19-dev

Steps

# 1) Clone
git clone https://github.com/<you>/<repo>.git
cd fluentin

# 2) (Optional) create venv
python3 -m venv .venv
# macOS/Linux:
source .venv/bin/activate
# Windows (PowerShell):
# .venv\Scripts\Activate.ps1

# 3) Install deps
pip install -r requirements.txt

# 4) Env (example)
export OPENAI_API_KEY="sk-XXXX..."      # Windows (PowerShell): setx OPENAI_API_KEY "sk-XXXX..."
export DJANGO_DEBUG="True"

# 5) Migrate DB
cd fluentin
python manage.py migrate

# 6) (Optional) add your Anki deck (see section below)

# 7) Run the server (Django dev server)
python manage.py runserver
# open http://127.0.0.1:8000/

---

☁️ Quick Deploy on AWS Lightsail (Recommended)

1. Create a Django AWS Lightsail instance.
2. SSH into the instance.
3. Install Python + dependencies (Ubuntu example):

sudo apt-get update
sudo apt-get install -y python3-pip python3-venv ffmpeg portaudio19-dev

4. Copy this project to the instance (e.g., git clone ...).
5. Set the OpenAI API Keys in the following locations

fluentin/training/viewsX.py           # X = 1, 2, or 3 (different UI flows)
  - line 152
  - line 523
  - line 668

fluentin/training/templates/baseX.html
  - line 591

6. Start Django bound to all interfaces:

python manage.py runserver 0.0.0.0:8000

7. In Lightsail Networking, allow port 8000 (or proxy via Nginx on port 80 later). This is oftentimes automatically done by the lightsail instance already
8. Visit: http://<your-lightsail-public-ip>:8000/

This is a minimal deploy using Django’s dev server.

---

✨ Features

• Real-time audio prompts (TTS) and optional mic capture for responses
• Comprehension checks with instant pass/fail feedback
• ChatGPT-powered hints, corrections, and example sentences
• Anki-style spaced repetition sourced from your own collection.anki2
• Multiple UIs (three interchangeable views) to test learning flows
• Scenario CSVs for quick topic-based practice (greetings, travel, etc.)

---

🔗 Routes

UI Entrypoints

• / → Home (UI #1)
• /home_copy/ → Home (UI #2)
• /home_copy_with_login/ → Home (UI #3, simple login)

Interactive Endpoints (per-UI variants with 2/3 suffixes)

• /get_new_word, /get_new_word2, /get_new_word3
• /start_conversation, /start_conversation2, /start_conversation3
• /send_response, /send_response2, /send_response3
• /send_comprehension_check, /send_comprehension_check2, /send_comprehension_check3

---

🧩 Using Your Anki Deck

1. Close Anki on your machine (to release locks).
2. Copy your collection.anki2 (and any -shm / -wal sidecars if present) into:

fluentin/fluentin/training/anki_file/

3. Run the app; spaced-repetition selection will read from your deck.

---

🛠 Troubleshooting

• ModuleNotFoundError → Activate venv, pip install -r requirements.txt.
• PortAudio / mic errors → Install PortAudio dev headers (see prereqs).
• ffmpeg not found → Install with your package manager.
• OpenAI auth → Ensure OPENAI_API_KEY is set in the same shell/process running Django.
• 403/CSRF (remote access) → Add your host/IP to ALLOWED_HOSTS in settings.py.
• Static files (prod) → Run python manage.py collectstatic and serve via a web server (e.g., Nginx).

---

🪪 License

This project is licensed for internal use.

---

📎 Acknowledgments

Built by Dr. Ryan Baker, Zhongtian Huang and Neithan Casano.