Currently in Beta - Free for all users while we test and improve. Paid plans coming to help cover AI costs.
A comprehensive Chamorro language learning platform with AI tutoring, flashcards, quizzes, games, stories, and conversation practice. Built with RAG using 45,000+ chunks from Chamorro dictionaries and educational resources.
📚 New to the team? Start with the Developer Setup Guide for step-by-step onboarding.
Live: hafagpt.com | Frontend: chamorro-chatbot-frontend
| Feature | Description |
|---|---|
| 🤖 AI Chat | RAG-enhanced chatbot with 3 modes (English, Chamorro, Learn) |
| 💬 Conversation Practice | 7 role-play scenarios with AI characters |
| 📖 Story Mode | 24 bilingual stories with tap-to-translate |
| 🎴 Flashcards | Curated decks + dictionary-based (10,350+ words) |
| 📝 Quizzes | Multiple choice, fill-in-blank, type answer |
| 📚 Vocabulary Browser | Searchable dictionary with 12 categories |
| 🎮 Learning Games | Memory Match, Word Scramble, Falling Words, Word Catch, Wordle |
| 💳 Freemium Model | Free tier with daily limits, Premium for unlimited |
| 🔐 Admin Dashboard | User management, stats, whitelist controls |
# 1. Clone & install
git clone https://github.com/Shimizu-Technology/HafaGPT-API.git
cd HafaGPT-API
uv sync
# 2. Set up environment
cp .env.example .env
# Edit .env with your API keys (see documentation/SETUP_GUIDE.md)
# 3. Run the server
uv run uvicorn api.main:app --reload --port 8000
# 4. Test it
curl http://localhost:8000/api/healthFull setup guide: documentation/SETUP_GUIDE.md
| Layer | Technology |
|---|---|
| Backend | FastAPI + Python 3.12 |
| Database | Neon PostgreSQL + PGVector |
| LLM | DeepSeek V3 (via OpenRouter) |
| Embeddings | OpenAI text-embedding-3-small |
| Auth | Clerk |
| Storage | AWS S3 |
| Frontend | React 18 + TypeScript + Vite |
| Deployment | Render (API) + Netlify (Frontend) |
HafaGPT-API/
├── api/ # FastAPI endpoints
│ ├── main.py # Main application
│ ├── models.py # Pydantic models
│ └── chatbot_service.py # LLM integration
├── src/rag/ # RAG system
│ ├── chamorro_rag.py # Core RAG logic
│ └── manage_rag_db.py # Knowledge base management
├── dictionary_data/ # Chamorro dictionary (13,800+ entries)
├── documentation/ # 📚 Detailed docs
├── evaluation/ # Test suite & benchmarks
└── alembic/ # Database migrations
| Document | Description |
|---|---|
| SETUP_GUIDE.md | 🚀 Start here - local development setup |
| HOW_AUTH_WORKS.md | 🔐 Clerk auth (if you're used to bcrypt/JWT) |
| HOW_MIGRATIONS_WORK.md | 🗄️ Alembic (if you're used to Rails) |
| HOW_RAG_WORKS.md | 🔍 How the AI knowledge base works |
| HOW_DEPLOYMENT_WORKS.md | 🚀 Gunicorn, Render, production setup |
📂 More docs: documentation/ folder
# Required
DATABASE_URL=postgresql://...
OPENAI_API_KEY=sk-... # For embeddings
OPENROUTER_API_KEY=sk-or-... # For DeepSeek
CLERK_SECRET_KEY=sk_... # For auth
# Optional
AWS_ACCESS_KEY_ID=... # For file uploads
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=...
CHAT_MODEL=deepseek-v3 # Model selectionPOST /api/chat- Send message to AI tutorPOST /api/chat/stream- Streaming response
GET /api/vocabulary/categories- List categoriesGET /api/vocabulary/search?q=...- Search dictionaryGET /api/daily-word- Word of the day
POST /api/quiz/generate- Generate quizPOST /api/quiz/results- Save quiz resultPOST /api/games/results- Save game result
GET /api/admin/stats- Platform statisticsGET /api/admin/users- List usersPATCH /api/admin/users/:id- Update user
Full API docs: http://localhost:8000/docs
| Service | Cost |
|---|---|
| Render Standard (API) | $25 |
| Neon PostgreSQL | $0 (free tier) |
| DeepSeek V3 | $0.50-2 |
| OpenAI Embeddings | $0.30 |
| OpenAI TTS | $0.50-2 |
| AWS S3 | $0.05 |
| Total | ~$26-30 |
- Create a feature branch
- Make your changes
- Test locally
- Submit a pull request
MIT License - See LICENSE file
Built with ❤️ for the Chamorro language community 🌺