🎓 TyporaX-AI — AI Language Coach

TyporaX-AI is a personalized Dutch language learning platform powered by lightning-fast Groq AI models. Practice with specialized expert coaches, enjoy immersive podcast conversations, and receive real-time assessment with desktop PWA experience.

🌟 We're an open-source project and we welcome contributors! Whether you're fixing a typo or adding a new feature, your contributions help make language learning accessible to everyone. See how to contribute →

✨ Features

🎙️ Dutch Podcast Expert - Interactive Emma & Daan conversations with voice synthesis
🤖 AI Expert Coaches - Healthcare Expert, IT Interview Coach, Language Tutor
📊 Real-Time Assessment - Live feedback on grammar, fluency, and vocabulary
💻 PWA Desktop App - Install as native desktop application
🎯 Personality-Based Learning - MBTI-optimized study methods
🎴 Anki Flashcards - Auto-generated spaced repetition cards
🔊 Audio Pronunciation - Natural Dutch speech synthesis (Edge-TTS)
📈 Progress Tracking - Monitor your learning journey

🚀 Quick Start

Prerequisites

Python 3.13+
~2GB RAM

Installation

# Clone repository
git clone https://github.com/Yusuprozimemet/TyporaX-AI.git
cd TyporaX-AI

# Create environment
conda create -n env python=3.13
conda activate env

# Install dependencies
pip install -r requirements.txt

# Setup API key (get free key from groq.com)
echo "GROQ_API_KEY=your_groq_api_key" > .env

# Launch application
python main.py

Access: Open browser to http://localhost:8000 → Install as PWA for desktop experience

📂 Project Structure

TyporaX-AI/
├── main.py                    # FastAPI application
├── requirements.txt           # Dependencies
├── templates/index.html       # Web interface
├── static/                    # CSS, JS, images
├── src/
│   ├── api/                   # API routes
│   │   ├── main_router.py     # Core endpoints
│   │   ├── chat_router.py     # Expert chat
│   │   └── assessment_router.py # Live assessment
│   ├── services/              # Business logic
│   │   ├── lesson_bot.py      # Lesson generation
│   │   ├── assessment.py      # Language analysis
│   │   └── calibrator.py      # Learning method
│   ├── utils/                 # Utilities
│   │   ├── audio.py           # TTS engine
│   │   ├── anki.py            # Flashcard export
│   │   └── pdf.py             # Report generation
│   └── experts/               # Expert personalities
│       ├── dutch_podcast_expert.py
│       ├── healthcare_expert.py
│       └── it_backend_interviewer.py
└── data/users/{user_id}/      # User profiles & progress

🎯 How It Works

1. Dutch Podcast Experience

Interactive Emma & Daan conversations → Real-time voice synthesis → Immersive listening practice

2. Expert Chat

Choose an expert → Practice Dutch conversation → Get AI responses tailored to domain

3. Real-Time Assessment

Every message analyzed for:

Grammar & Fluency (0-10 scores)
Vocabulary Level (Beginner → Advanced)
Better Version (Corrected sentences)
Live Hints (Language tips, conversation tips, expert-specific guidance)

4. Desktop PWA

Install as App: Native desktop experience
Draggable Panels: Customizable assessment interface
Offline Ready: Works without internet connection

5. Export Resources

📄 PDF learning plans
🎴 Anki flashcard decks
🔊 Audio pronunciation files

⚙️ Configuration

Environment Setup

# Required: Groq API key (free at groq.com)
export GROQ_API_KEY="your_groq_api_key"

# Optional: Backup HuggingFace token
export HF_TOKEN="your_huggingface_token"

# Optional: Custom data directory
export TYPORAX_DATA_DIR="/custom/path"

Expert Customization

Edit prompts in prompts/ directory:

dutch_podcast_expert.json - Podcast conversations
healthcare_expert.json - Medical scenarios
it_backend_interviewer.json - Tech interviews
assessment.json - Language analysis
app.json - General language coaching

🔧 API Endpoints

Endpoint	Method	Description
`/`	GET	Web interface
`/api/chat`	POST	Expert conversation
`/api/assessment`	POST	Language analysis
`/api/generate-lesson`	POST	Create daily lesson
`/download/pdf/{user_id}`	GET	Learning plan PDF
`/download/anki/{user_id}`	GET	Flashcard deck
`/download/audio/{user_id}`	GET	Pronunciation audio

🛠️ Development

Adding New Expert

Create personality file in src/experts/
Add prompt template in prompts/
Register in expert router
Update frontend expert selector

Testing

# Test lesson generation
python -c "from src.services.lesson_bot import run_lesson_bot; print(run_lesson_bot('test', 'dutch'))"

# Run application
python main.py

🐛 Troubleshooting

Port already in use:

# Change port in main.py
uvicorn.run(app, host="0.0.0.0", port=8001)

PDF generation issues (Windows):

conda install -c conda-forge gtk3 reportlab

Memory issues:

# Use lighter model or CPU-only
export CUDA_VISIBLE_DEVICES=""

🤝 Contributing

We welcome contributions from everyone! 🎉 Whether you're a developer, language expert, designer, or just passionate about education technology, there's a place for you here.

🌟 Why Contribute?

🚀 Help make language learning accessible to everyone
💡 Share your expertise and ideas
🌍 Join a community of developers and educators
📚 Learn FastAPI, AI integration, and modern web development
✨ See your code make a real impact

🎯 How to Contribute

For First-Time Contributors

Fork the repository - Click the "Fork" button at the top right

Clone your fork

git clone https://github.com/YOUR_USERNAME/TyporaX-AI.git
cd TyporaX-AI

Set up development environment

conda create -n env python=3.13
conda activate env
pip install -r requirements.txt

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes - Write code, fix bugs, improve docs
Test your changes
```
python main.py  # Test the application
```

Commit with clear messages

git add .
git commit -m "Add: Brief description of your change"

Push to your fork

git push origin feature/your-feature-name

Open a Pull Request - Go to the original repository and click "New Pull Request"

Contribution Ideas

🐛 Bug Fixes

Fix reported issues in GitHub Issues
Improve error handling
Fix typos or broken links

✨ New Features

Add support for new languages (French, Spanish, German, etc.)
Create new expert personalities (Business Coach, Travel Guide, etc.)
Implement new assessment metrics
Add gamification features (badges, streaks, etc.)

🎨 UI/UX Improvements

Enhance the web interface design
Improve mobile responsiveness
Add dark mode support
Create better visualizations for progress tracking

📚 Documentation

Improve README or other docs
Add code comments
Create tutorials or video guides
Translate documentation to other languages

🔧 Code Quality

Refactor code for better performance
Add unit tests
Improve code organization
Optimize API endpoints

🌐 Localization

Translate UI to other languages
Add language-specific learning content
Adapt cultural references

📝 Contribution Guidelines

Code Style: Follow PEP 8 for Python code
Commit Messages: Use clear, descriptive commit messages (e.g., "Add: Spanish language support", "Fix: Audio playback issue")
Testing: Test your changes thoroughly before submitting
Documentation: Update docs if you change functionality
Small PRs: Keep pull requests focused on a single feature or fix

🐛 Reporting Issues

Found a bug? Have a suggestion? Please open an issue on GitHub:

Check if the issue already exists
Use a clear, descriptive title
Provide detailed steps to reproduce (for bugs)
Include your environment details (OS, Python version, etc.)

💬 Getting Help

Questions? Open a discussion on GitHub Discussions
Stuck? Comment on the issue you're working on
Ideas? Share them in GitHub Issues with the "enhancement" label

🎓 Learning Resources

New to the technologies we use?

🏆 Recognition

All contributors will be:

Listed in our Contributors section
Credited in release notes
Part of a growing open-source community

Thank you for helping make language learning better for everyone! 💙

👥 Contributors

We appreciate all contributions to this project! 🙏

Want to see your name here? Start contributing today!

📜 License

This project is licensed under the Apache 2.0 License - see LICENSE file.

This means you can:

✅ Use this software commercially
✅ Modify and distribute
✅ Use privately
✅ Use patents (if any)

With the conditions:

📋 Include original license and copyright
📝 State significant changes made

🙏 Acknowledgments

Hugging Face - AI model infrastructure
FastAPI - Modern web framework
Edge TTS - Natural speech synthesis

TyporaX-AI v8 - Where personality meets AI to unlock your language learning potential TyporaX-AI v8 - Where personality meets AI to unlock your language learning potential

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
config		config
data/users/alex		data/users/alex
prompts		prompts
scripts		scripts
src		src
static		static
templates		templates
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.py		app.py
app_legacy.py		app_legacy.py
app_original.py		app_original.py
main.py		main.py
manifest.json		manifest.json
pytest.ini		pytest.ini
requirements.txt		requirements.txt
structure.py		structure.py
test_assessment.py		test_assessment.py
test_audio_fix.py		test_audio_fix.py
test_config.py		test_config.py
test_imports.py		test_imports.py
test_improved_podcast.py		test_improved_podcast.py
test_lesson_gen.py		test_lesson_gen.py
test_podcast.py		test_podcast.py
test_tax_authority.py		test_tax_authority.py
test_voices.py		test_voices.py

License

Yusuprozimemet/TyporaX-AI

Folders and files

Latest commit

History

Repository files navigation