Stack:
Tools:
Stats:

Language Quiz Service

A FastAPI-powered backend service for generating AI-driven language learning quizzes and content. This service provides REST APIs for creating French language learning materials including verbs, sentences, and grammar problems.

Problem generation example:

A difficulty selector is still needed and on the todo list, as is the shortest sentence almost always being correct issue.

🚀 Quick Start

FastAPI Service (Recommended)

Start the FastAPI development server:

make dev

Or manually with uvicorn:

poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

The service will be available at:

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

📋 Prerequisites

Dependencies

Install via Poetry:

pipx install poetry
pipx inject poetry poetry-plugin-shell
poetry install

Environment Variables

Required environment variables to operate the conolse app (create a .env file in the project root):

# OpenAI API Key
OPENAI_API_KEY=your_openai_api_key

# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_key
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_PROJECT_REF=your_supabase_project_ref

# Optional: Server Configuration
WEB_HOST=0.0.0.0
WEB_PORT=8000

🖥️ Command Line Interface

The CLI provides direct access to core functionality for development and testing with flexible output formatting:

Initialize the database:

lqs database init

Generate some random problems:

lqs problem random --count 5

Get a random verb with different output formats:

# Pretty format (default) - colorized tree view
lqs verb random

# Compact format - single line key=value pairs
lqs verb random --format compact

# Table format - structured table with types
lqs verb random --format table

# JSON format - raw JSON for scripting
lqs verb random --json

Generate sentences:

lqs sentence new --quantity 3

Output Format Options: All CLI commands support consistent output formatting:

• --format pretty (default): Colorized tree view with emojis
• --format compact: Single-line key=value format
• --format table: Structured table with data types
• --json: Raw JSON output for scripting and automation

🔧 Development

Code Quality

Install pre-commit hooks:

make install-githooks

Available Make Commands

make help          # Show all available commands
make dev           # Start FastAPI with auto-reload
make serve         # Start FastAPI server
make test          # Run tests
make lint          # Run linting
make format        # Format code
make check         # Run format, lint, and test

Testing

make test             # All tests
make test-unit        # Unit tests only
make test-integration # Integration tests only

See tests/TESTING.md for test strategy and organization.

📡 API Endpoints

Health & Status

• GET / - Service information
• GET /health - Health check

Core Resources

• GET /api/v1/problems/random - Generate random grammar problem
• GET /api/v1/sentences/random - Generate random sentence
• GET /api/v1/verbs/random - Get random verb

Full API documentation available at /docs when running the service.

🏗️ Architecture

The service is layed out as follows:

src/
├── api/                 # REST API endpoints
├── cli/                 # Command-line interface
├── core/                # Configuration and utilities
├── clients/             # External service clients
├── repositories/        # Data access layer
├── schemas/             # Pydantic models
├── services/            # Business logic layer
└── main.py              # FastAPI application entry point