Lexifyd Context-Aware Lexical Game (Prototype)

This repo implements the Lexifyd Polysemy Challenge described in PS01.pdf:

• A Data Engine that generates multiple senses for an ambiguous Tamil word, produces distinct sentences for each sense, and creates smart distractors (grammatical but wrong-in-context).
• A Mini-game UI where the learner drags the correct meaning into the sentence slot.
• A Semantic Web visualization to explore how a root word branches into senses and examples.

How to Run from Scratch

1) Prerequisites (Docker, Redis & PostgreSQL)

The backend uses Redis as a fast caching layer and PostgreSQL for persistent storage. Before starting the backend, make sure you have Docker installed and spin up the required containers by running:

# Start Redis for caching
docker run -d -p 6379:6379 --name lexifyd-redis redis:latest

# Start PostgreSQL for the main database
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=1234 -e POSTGRES_USER=postgres -e POSTGRES_DB=postgres --name lexifyd-db postgres:15

(Note: If you skip running PostgreSQL, the backend will gracefully fall back to a local SQLite file (lexifyd.db), but using Postgres is recommended.)

2) Backend (FastAPI)

Open a terminal in the project root folder and run:

cd backend

# Create and activate a virtual environment
python -m venv .venv

# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# On Linux / macOS:
# source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the backend server
uvicorn app.main:app --reload

The backend server will start at http://localhost:8000.

3) Frontend (Vite + TypeScript)

Open a new terminal in the project root folder and run:

cd frontend

# Install Node.js dependencies
npm install

# Start the frontend development server
npm run dev

The frontend will print a local URL (typically http://localhost:5173). Open this URL in your browser to play the game!

LLM Provider Configuration (Required for generation)

The game's data engine uses Google Gemini to generate dynamic Tamil sentences and distractors. To enable this, you need to configure your API key.

1. Navigate to the backend folder.
2. Create a file named .env in the backend directory (you can copy or rename .env.example).
3. Add the following two lines to your .env file:

LEXIFYD_PROVIDER=gemini
LEXIFYD_GEMINI_API_KEY=your_google_gemini_api_key_here

Replace your_google_gemini_api_key_here with your valid Gemini API key. Once saved, restart the backend server so it can load the key.

You can also use OLLama key too if you change the code logic in the backend code.