TextBookLive

TextBookLive is a web application that transforms images of study materials and textual prompts into live, interactive language learning exercises.

Disclaimer: This project is intended for educational purposes. Users are solely responsible for ensuring they have the legal rights to any content they upload or generate.

Features

• Upload Anything: Upload an image or provide a description of the material you want to learn from.
• AI Generation: The system analyzes the image and generates interactive exercises.
• Live Feedback: Complete the exercises and get immediate validation.

Getting Started

Project Structure

• Backend (/backend): Written in Go. Handles file uploads and integration with the Gemini VLM API to generate exercises.
• Frontend (/frontend): Built with Lit web components and TypeScript. Implements the A2UI (Agent-to-User Interface) framework and communicates via ag-ui.

Prerequisites

1. Gemini API Key: Get a valid API key from Google AI Studio.
2. Firebase Project: Set up Authentication (Email/Password & Google) and generate a Service Account Key. See the Firebase docs for more details.

Environment Setup

1. Copy .env.example to .env in the root directory:

   cp .env.example .env

2. Fill in the .env file with your Gemini API Key and Firebase Configuration (Web API Key, domains, etc.).
3. Place your Firebase Service Account JSON file in backend/textbooklive-service-key.json.

Running with Docker

You can launch the entire project (database, backend, frontend) using Docker Compose:

docker compose up --build -d

Apply the database schema:

docker compose exec -T db psql -U postgres -d textbooklive < backend/internal/db/schema.sql

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080

Development Setup

If you prefer to run the backend and frontend locally for development, you can run them without containerization.

Database Local Setup

1. Start only the database:

   docker compose up db -d

2. Follow the backend and frontend setup below.

Backend Local Setup

1. Place your Firebase Service Account JSON file in backend/textbooklive-service-key.json or explicitly export the GOOGLE_APPLICATION_CREDENTIALS environment variable to its path.
2. Set the following environment variables:

GEMINI_API_KEY="your_api_key"
GOOGLE_APPLICATION_CREDENTIALS="$(pwd)/textbooklive-service-key.json"

3. Run the go project from the backend/ directory:

go run cmd/server/main.go

Frontend Local Setup

1. Create a .env file in the frontend/ directory (or use the root .env if your Vite config resolves it) with the following content matched from your Firebase config:

   VITE_FIREBASE_API_KEY=your_firebase_api_key

2. Build and run:

npm install
npm run dev

3. Access the frontend at http://localhost:3000.

Architecture Notes

• A2UI: The UI is dynamically rendered based on the AI's response. The backend returns a JSON description of the UI components (inputs, questions), which the frontend interprets and renders. The spec is available in the frontend/specification directory after running make spec-setup.
• ag-ui: Handles the communication protocol between the client and the agentic backend.