Skip to content

README.md

Latest commit

 

History

History
238 lines (189 loc) · 10.3 KB

README.md

File metadata and controls

238 lines (189 loc) · 10.3 KB

Linaw Logo

Linaw

Unlock deeper understanding, one word at a time.

An AI-powered reading companion that explains complex English terms in Philippine languages — not through literal translation, but through localized understanding.

📌 Problem Statement

Filipino students studying English-medium textbooks often encounter unfamiliar academic vocabulary. Traditional tools like Google Translate offer literal word-for-word translations that strip away meaning and context — "Photosynthesis" simply becomes "Fotosintesis", which helps no one.

Linaw solves this by providing context-aware, AI-generated explanations delivered in the student's own regional language — the way a friend would explain it.

✨ Key Features

🧠 AI-Powered Contextual Definitions

  • Highlight any word or phrase in a PDF and get a context-aware English definition generated by Gemini AI
  • Definitions adapt based on surrounding text using n-gram context extraction

🌏 Translation to 7 Philippine Languages

  • Tagalog
  • Cebuano
  • Hiligaynon
  • Bikolano
  • Ilocano
  • Pangasinense
  • Waray

📖 Interactive PDF Notebook

  • Upload and read PDFs directly in the browser via react-pdf
  • Scrollable, multi-page document viewer
  • Select text directly on the PDF to trigger definitions
  • Upload documents to Firebase Storage for persistent access

🔌 Chrome Extension Side Panel

  • Browse any website and highlight words to get instant definitions
  • Side panel opens contextually without leaving the page
  • Full feature parity with the notebook (definitions, translations, confused-with terms)

🃏 Flashcard Quiz

  • Auto-generates flashcard quizzes from your lookup history
  • Tracks scores and progress per notebook via Firestore
  • Retake quizzes to reinforce learning

🖼️ Visual Illustrations

  • Search for related images via Unsplash API for visual learning
  • Fullscreen viewer with zoom and navigation

🔊 Text-to-Speech

  • Listen to definitions spoken aloud via the Web Speech API

⚠️ Confused-With Terms

  • For every definition, Linaw returns the 3 most commonly confused words/phrases
  • Click any confused term to immediately look it up

🔍 Smart Selection

  • Semantic word gate validates selections before sending to AI (prevents defining random characters)
  • N-gram correction suggests better highlight boundaries (e.g., "osmosi" → "osmosis")

⚙️ Customizable Settings

  • Toggle English definitions, language context, confused-with terms
  • Choose whether to confirm before defining

💾 Global Dictionary Cache

  • Definitions are cached in Firestore's global_dictionary collection
  • Repeated lookups are instant — no API calls needed

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                        Client                           │
│                                                         │
│   ┌──────────────────┐     ┌──────────────────────┐     │
│   │  React Web App   │     │  Chrome Extension    │     │
│   │  (Vite + TW4)    │     │  (Side Panel)        │     │
│   └────────┬─────────┘     └──────────┬───────────┘     │
│            │                          │                 │
└────────────┼──────────────────────────┼─────────────────┘
             │                          │
             ▼                          ▼
┌─────────────────────────────────────────────────────────┐
│              FastAPI Backend (Render)                   │
│                                                         │
│   • /api/define          — AI-powered definitions       │
│   • /api/define-only     — Phase 1: definition only     │
│   • /api/translate-def   — Phase 2: translation         │
│   • /sources/upload      — PDF upload to Firebase       │
│   • /api/translate       — Proxy to translator service  │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│         Linaw Translator (Modal — A10G GPU)             │
│                                                         │
│   • NLLB 1.3B (CTranslate2 INT8) for low-resource       │
│     languages                                           │
│   • Gemini provider for higher-resource languages       │
│   • Automatic fallback routing                          │
└─────────────────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Firebase                             │
│                                                         │
│   • Auth         — Google & Email sign-in               │
│   • Firestore    — User data, notebooks, quiz scores,   │
│                    global dictionary cache              │
│   • Storage      — Uploaded PDF documents               │
└─────────────────────────────────────────────────────────┘

🛠️ Tech Stack

Layer Technology
Frontend React 19, Vite 7, Tailwind CSS 4, react-pdf, Lucide Icons
Backend API Python, FastAPI, Pydantic, Uvicorn
AI/ML Gemini 2.5 Flash (definitions), NLLB-200-distilled-1.3B (translation)
Translation Infra Modal (serverless GPU - A10G), CTranslate2 (INT8 quantized inference)
Database & Auth Firebase Auth, Cloud Firestore, Firebase Storage
Browser Extension Chrome Manifest V3, Side Panel API
Image Search Unsplash API
Deployment Render (backend), Vercel/Netlify (frontend), Modal (translator)

🚀 Getting Started

Prerequisites

  • Python 3.10+
  • Node.js 18+
  • A Google AI Studio API key (Gemini)
  • A Firebase project with Auth, Firestore, and Storage enabled

1. Clone the Repository

git clone https://github.com/your-team/Linaw.git
cd Linaw

2. Backend Setup

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Mac/Linux

# Install dependencies
pip install -r requirements.txt

# Start the backend
uvicorn main:app --reload

3. Frontend Setup

cd linaw-app
npm install
npm run dev

4. Environment Variables

Create linaw-app/.env:

VITE_APP_FIREBASE_API_KEY=your_firebase_api_key
VITE_APP_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_APP_FIREBASE_PROJECT_ID=your_project_id
VITE_APP_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_APP_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_APP_FIREBASE_APP_ID=your_app_id
VITE_APP_UNSPLASH_API_KEY=your_unsplash_key
VITE_APP_BACKEND_URL=http://localhost:8000

📁 Project Structure

Linaw/
├── main.py                  # FastAPI backend (definitions, upload, translation proxy)
├── firebase_config.py       # Firebase Admin SDK initialization
├── requirements.txt         # Python dependencies
├── linaw-app/               # React frontend + Chrome extension
│   ├── src/
│   │   ├── pages/           # Home, Notebook, Auth, Dashboard, Settings
│   │   ├── components/      # UI components (Explain, Reader, FlashcardQuiz, etc.)
│   │   ├── extension/       # Chrome extension side panel
│   │   ├── services/        # API clients, dictionary, n-gram, translation services
│   │   └── context/         # React contexts (Auth, Settings)
│   └── public/              # Static assets, extension manifest
├── linaw-translator/        # Modal-hosted translation microservice
│   ├── main.py              # Modal app with NLLB + Gemini providers
│   └── providers/           # Translation provider factory (NLLB, Gemini)
└── README.md

👥 Team

Built with ❤️ for Filipino students everywhere.

Linaw - "Clarity" in Bisaya 🌊