Add mobile app support and opening training feature

This commit implements iOS/Android mobile app support using Capacitor
and adds a comprehensive opening training feature with LLM-powered
explanations.

## Mobile App Infrastructure

- Add Capacitor configuration for iOS/Android builds
- Create mobile build script that excludes API routes
- Update Next.js config for conditional static export
- Add layout components with generateStaticParams for static builds
- Generate 500+ static pages for offline mobile use

## Chess Engine Abstraction

- Create ChessEngine interface for pluggable implementations
- Add LocalEngine (GPL - uses stockfish.js in browser)
- Add RemoteEngine (proprietary - calls API server)
- Factory pattern selects engine based on environment
- Enables GPL compliance for web, proprietary for mobile

## Opening Training Feature

- Interactive opening repertoire training
- Move validation with engine-backed feedback
- LLM explanations using Gemini API
- Wikipedia integration for opening context
- Opening family grouping (e4, d4, c4, etc.)
- Session state management
- Real-time move feedback with evaluation

Components:
- OpeningSelector: Browse and select openings by family
- OpeningTrainer: Main training interface with chessboard
- MoveFeedback: Display move quality and LLM explanations
- WikipediaSummary: Show opening history and context
- ErrorBoundary: Graceful error handling

Services:
- openingLoader: Load and filter opening database
- engineService: Engine evaluation wrapper
- moveValidator: Validate moves against repertoire
- feedbackGenerator: Generate contextual feedback
- wikipediaService: Fetch and cache Wikipedia data
- sessionManager: Track training session state

## Wikipedia Integration

- Automatic Wikipedia article fetching for openings
- Client-side and server-side caching
- Sanitized summaries with proper formatting
- Link opening database to Wikipedia slugs
- API endpoints for on-demand fetching

## Docker Improvements

- Add entrypoint script for automatic data setup
- Fetch Wikipedia data on first container startup
- Generate opening move index automatically
- Remove generated data from git (public/openings/*.json, public/wikipedia/*.json)
- Add READMEs explaining data requirements
- Update .gitignore for generated files

## Dual Licensing Strategy

- Add LICENSING.md explaining dual licensing approach
- GPL-3.0 for web builds (includes Stockfish)
- Proprietary option for mobile builds (no GPL code)
- Single codebase, multiple licensing models
- Legal compliance documented

## API Endpoints

- POST /api/v1/llm/opening-explanation - Get LLM move explanations
- GET /api/v1/wikipedia/summary - Fetch Wikipedia summaries

## Type Updates

- Add openingTraining types
- Update Tutor component to use ChessEngine interface
- Add Gemini error handling types

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Stefan
2025-12-07 18:40:58 +01:00
parent 52dd32eb15
commit 002ed92bea
57 changed files with 7015 additions and 234280 deletions
@@ -0,0 +1,114 @@
import { NextRequest, NextResponse } from 'next/server';
import { GoogleGenerativeAI } from '@google/generative-ai';
import {
OPENING_TUTOR_SYSTEM_PROMPT,
OPENING_TUTOR_TEMPERATURE,
OPENING_TUTOR_MAX_TOKENS,
generateFallbackExplanation,
} from '@/lib/server/openingTutorPrompt';
export const runtime = 'nodejs';
export const maxDuration = 10; // 10 second timeout
/**
* Opening Explanation API Endpoint
* Generates educational explanations for chess moves using LLM
*/
export async function POST(request: NextRequest) {
try {
const body = await request.json();
const {
prompt,
moveSan,
category,
theoreticalMoves,
evalChange,
bestMove,
} = body;
if (!prompt) {
return NextResponse.json(
{ error: 'Missing prompt parameter' },
{ status: 400 }
);
}
// Check for API key
const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey) {
console.warn('GEMINI_API_KEY not configured, using fallback explanation');
const fallback = generateFallbackExplanation(
category,
moveSan,
theoreticalMoves,
evalChange,
bestMove
);
return NextResponse.json({
explanation: fallback,
usedFallback: true,
});
}
// Initialize Gemini API
const genAI = new GoogleGenerativeAI(apiKey);
const model = genAI.getGenerativeModel({
model: 'gemini-1.5-flash',
generationConfig: {
temperature: OPENING_TUTOR_TEMPERATURE,
maxOutputTokens: OPENING_TUTOR_MAX_TOKENS,
},
systemInstruction: OPENING_TUTOR_SYSTEM_PROMPT,
});
// Generate explanation
const result = await model.generateContent(prompt);
const response = result.response;
const explanation = response.text();
if (!explanation || explanation.trim().length === 0) {
// Empty response - use fallback
const fallback = generateFallbackExplanation(
category,
moveSan,
theoreticalMoves,
evalChange,
bestMove
);
return NextResponse.json({
explanation: fallback,
usedFallback: true,
});
}
return NextResponse.json({
explanation: explanation.trim(),
usedFallback: false,
});
} catch (error) {
console.error('LLM explanation error:', error);
// Try to extract fallback params from request
let fallbackExplanation = 'Unable to generate explanation at this time.';
try {
const body = await request.json();
if (body.moveSan && body.category) {
fallbackExplanation = generateFallbackExplanation(
body.category,
body.moveSan,
body.theoreticalMoves || [],
body.evalChange,
body.bestMove
);
}
} catch {
// Ignore fallback generation errors
}
return NextResponse.json({
explanation: fallbackExplanation,
usedFallback: true,
error: 'LLM request failed',
});
}
}
+129
View File
@@ -0,0 +1,129 @@
import { NextRequest, NextResponse } from 'next/server';
export const runtime = 'nodejs';
/**
* Wikipedia Summary API Endpoint
* Fetches Wikipedia article summaries for chess openings
*/
export async function GET(request: NextRequest) {
const { searchParams } = new URL(request.url);
const openingName = searchParams.get('opening');
if (!openingName) {
return NextResponse.json(
{ error: 'Missing opening parameter' },
{ status: 400 }
);
}
try {
console.log('[Wikipedia API] Searching for:', openingName);
// Step 1: Use Wikipedia Search API to find the best matching article
// This handles partial matches, redirects, and disambiguations
const searchUrl = new URL('https://en.wikipedia.org/w/api.php');
searchUrl.searchParams.set('action', 'opensearch');
searchUrl.searchParams.set('search', openingName);
searchUrl.searchParams.set('limit', '5'); // Get top 5 results
searchUrl.searchParams.set('namespace', '0'); // Main articles only
searchUrl.searchParams.set('format', 'json');
const searchResponse = await fetch(searchUrl.toString(), {
headers: {
'User-Agent': 'ChessTutorApp/1.0 (Educational chess training app)',
},
});
if (!searchResponse.ok) {
console.error('[Wikipedia API] Search failed:', searchResponse.status);
return NextResponse.json(
{
error: 'Wikipedia search failed',
fallback: 'No background information available for this opening.',
},
{ status: 404 }
);
}
const searchData = await searchResponse.json();
// OpenSearch returns: [query, [titles], [descriptions], [urls]]
const titles = searchData[1] as string[];
const descriptions = searchData[2] as string[];
if (!titles || titles.length === 0) {
console.log('[Wikipedia API] No results found for:', openingName);
return NextResponse.json(
{
error: 'Wikipedia article not found',
fallback: 'No background information available for this opening.',
},
{ status: 404 }
);
}
// Find best match (prioritize chess-related articles)
let bestMatch = titles[0]; // Default to first result
for (let i = 0; i < titles.length; i++) {
const title = titles[i];
const description = descriptions[i] || '';
// Prioritize results with chess-related keywords
if (
description.toLowerCase().includes('chess') ||
description.toLowerCase().includes('opening') ||
title.toLowerCase().includes('chess')
) {
bestMatch = title;
break;
}
}
console.log('[Wikipedia API] Best match:', bestMatch, 'from', titles.length, 'results');
// Step 2: Fetch summary for the best matching article
const summaryUrl = `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(
bestMatch
)}`;
const summaryResponse = await fetch(summaryUrl, {
headers: {
'User-Agent': 'ChessTutorApp/1.0 (Educational chess training app)',
},
});
if (!summaryResponse.ok) {
console.error('[Wikipedia API] Summary fetch failed for:', bestMatch);
return NextResponse.json(
{
error: 'Wikipedia article not found',
fallback: 'No background information available for this opening.',
},
{ status: 404 }
);
}
const data = await summaryResponse.json();
// Format the response
const summary = {
openingName,
title: data.title,
extract: data.extract,
url:
data.content_urls?.desktop?.page ||
`https://en.wikipedia.org/wiki/${encodeURIComponent(bestMatch)}`,
fetchedAt: Date.now(),
expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
};
console.log('[Wikipedia API] Successfully fetched:', data.title);
return NextResponse.json(summary);
} catch (error) {
console.error('[Wikipedia API] Error:', error);
return NextResponse.json(
{ error: 'Failed to fetch Wikipedia summary' },
{ status: 500 }
);
}
}
@@ -0,0 +1,23 @@
// Server component layout for static export
// This allows generateStaticParams while the page remains a client component
export async function generateStaticParams() {
// Generate params for root ECO codes (A00-E99)
// This creates 500 static pages for the mobile build
const ecoRoots = [];
for (const letter of ['A', 'B', 'C', 'D', 'E']) {
for (let num = 0; num <= 99; num++) {
const eco = `${letter}${String(num).padStart(2, '0')}`;
ecoRoots.push({ openingId: eco });
}
}
return ecoRoots;
}
export default function OpeningIdLayout({
children,
}: {
children: React.ReactNode;
}) {
return children;
}
@@ -0,0 +1,151 @@
'use client';
import { useEffect, useState } from 'react';
import { useParams, useRouter } from 'next/navigation';
import { ArrowLeft } from 'lucide-react';
import Header from '@/components/Header';
import { useTranslation } from '@/lib/i18n/useTranslation';
import { SupportedLanguage } from '@/lib/i18n/translations';
import { OpeningMetadata } from '@/lib/openings';
import { OpeningTrainingProvider } from '@/contexts/OpeningTrainingContext';
import OpeningTrainer from '@/components/OpeningTrainer/OpeningTrainer';
import { OpeningTrainerErrorBoundary } from '@/components/OpeningTrainer/ErrorBoundary';
import { getOpeningByEco } from '@/lib/openingTrainer/openingLoader';
import { Personality, PERSONALITIES } from '@/lib/personalities';
export default function OpeningTrainingPage() {
const params = useParams();
const router = useRouter();
const openingId = params.openingId as string;
const [language, setLanguage] = useState<SupportedLanguage>('en');
const [mounted, setMounted] = useState(false);
const [opening, setOpening] = useState<OpeningMetadata | null>(null);
const [isLoading, setIsLoading] = useState(true);
const [selectedPersonality, setSelectedPersonality] = useState<Personality>(PERSONALITIES[0]);
const [apiKey, setApiKey] = useState<string>('');
useEffect(() => {
const storedLang = localStorage.getItem('chess_tutor_language');
if (storedLang) setLanguage(storedLang as SupportedLanguage);
// Load API key
const storedApiKey = localStorage.getItem('gemini_api_key');
if (storedApiKey) setApiKey(storedApiKey);
// Load personality
const storedPersonalityId = localStorage.getItem('chess_tutor_personality');
if (storedPersonalityId) {
const personality = PERSONALITIES.find(p => p.id === storedPersonalityId);
if (personality) setSelectedPersonality(personality);
}
setMounted(true);
}, []);
const t = useTranslation(language);
useEffect(() => {
if (mounted) {
loadOpening();
}
}, [openingId, mounted]);
const loadOpening = () => {
setIsLoading(true);
// Find opening by ECO code
const foundOpening = getOpeningByEco(openingId);
if (!foundOpening) {
// Opening not found - redirect back to selection
router.push('/learning/openings');
return;
}
setOpening(foundOpening);
setIsLoading(false);
};
if (!mounted) return null;
if (isLoading) {
return (
<>
<Header language={language} />
<div className="flex-grow bg-gray-100 dark:bg-gray-900 p-4 flex flex-col">
<div className="max-w-6xl mx-auto w-full">
<div className="flex items-center justify-center min-h-[400px]">
<div className="text-center space-y-4">
<div className="w-12 h-12 border-4 border-blue-600 border-t-transparent rounded-full animate-spin mx-auto"></div>
<p className="text-gray-600 dark:text-gray-400">Loading opening training session...</p>
</div>
</div>
</div>
</div>
</>
);
}
if (!opening) {
return (
<>
<Header language={language} />
<div className="flex-grow bg-gray-100 dark:bg-gray-900 p-4 flex flex-col">
<div className="max-w-6xl mx-auto w-full">
<div className="text-center py-12">
<h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
Opening Not Found
</h2>
<p className="text-gray-600 dark:text-gray-400 mb-6">
The requested opening could not be found.
</p>
<button
onClick={() => router.push('/learning/openings')}
className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors"
>
Back to Opening Selection
</button>
</div>
</div>
</div>
</>
);
}
return (
<>
<Header language={language} />
<div className="flex-grow bg-gray-100 dark:bg-gray-900 p-4 flex flex-col">
<div className="max-w-6xl mx-auto w-full">
{/* Header */}
<div className="mb-6 flex items-center justify-between">
<button
onClick={() => router.push('/learning/openings')}
className="p-2 md:px-4 md:py-2 bg-gray-200 dark:bg-gray-700 rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 text-sm font-medium transition-colors flex items-center gap-2"
>
<ArrowLeft size={20} />
<span className="hidden md:inline">Back to Opening Selection</span>
</button>
</div>
<div className="mb-6">
<h1 className="text-3xl font-bold text-gray-900 dark:text-white">{opening.name}</h1>
<p className="text-gray-600 dark:text-gray-400">ECO: {opening.eco}</p>
</div>
<OpeningTrainerErrorBoundary>
<OpeningTrainingProvider>
<OpeningTrainer
opening={opening}
personality={selectedPersonality}
apiKey={apiKey}
language={language}
/>
</OpeningTrainingProvider>
</OpeningTrainerErrorBoundary>
</div>
</div>
</>
);
}
+90
View File
@@ -0,0 +1,90 @@
'use client';
import { useState, useEffect, useMemo } from 'react';
import { useRouter } from 'next/navigation';
import { ArrowLeft } from 'lucide-react';
import Header from '@/components/Header';
import OpeningSelector from '@/components/OpeningTrainer/OpeningSelector';
import FamilySelector from '@/components/OpeningTrainer/FamilySelector';
import { useTranslation } from '@/lib/i18n/useTranslation';
import { SupportedLanguage } from '@/lib/i18n/translations';
import { getEcoRootOpenings } from '@/lib/openingTrainer/openingLoader';
import { groupOpeningsByFamily } from '@/lib/openingTrainer/openingFamilies';
export default function OpeningsPage() {
const router = useRouter();
const [language, setLanguage] = useState<SupportedLanguage>('en');
const [mounted, setMounted] = useState(false);
const [selectedFamily, setSelectedFamily] = useState<string | null>(null);
useEffect(() => {
const storedLang = localStorage.getItem('chess_tutor_language');
if (storedLang) setLanguage(storedLang as SupportedLanguage);
setMounted(true);
}, []);
const t = useTranslation(language);
// Get ECO root openings for display
const allOpenings = useMemo(() => {
return getEcoRootOpenings();
}, []);
// Group openings by family
const openingFamilies = useMemo(() => {
return groupOpeningsByFamily(allOpenings);
}, [allOpenings]);
const handleSelectFamily = (familyName: string) => {
setSelectedFamily(familyName);
};
const handleBackToFamilies = () => {
setSelectedFamily(null);
};
if (!mounted) return null;
return (
<>
<Header language={language} />
<div className="flex-grow bg-gray-100 dark:bg-gray-900 p-4 flex flex-col">
<div className="max-w-6xl mx-auto w-full">
{/* Header */}
<div className="mb-8 flex items-center justify-between">
<button
onClick={() => router.push('/learning')}
className="p-2 md:px-4 md:py-2 bg-gray-200 dark:bg-gray-700 rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 text-sm font-medium transition-colors flex items-center gap-2"
>
<ArrowLeft size={20} />
<span className="hidden md:inline">{t.learning.backToMenu}</span>
</button>
</div>
{!selectedFamily ? (
<>
<h1 className="text-3xl font-bold text-gray-900 dark:text-white mb-2">
Opening Training
</h1>
<p className="text-gray-600 dark:text-gray-400 mb-8">
Select an opening family to explore. Each family contains multiple variations
with engine-backed feedback and AI-powered explanations.
</p>
<FamilySelector
families={openingFamilies}
onSelectFamily={handleSelectFamily}
/>
</>
) : (
<OpeningSelector
openings={allOpenings}
selectedFamily={selectedFamily}
onBackToFamilies={handleBackToFamilies}
/>
)}
</div>
</div>
</>
);
}
+18 -5
View File
@@ -145,11 +145,24 @@ export default function LearningAreaPage() {
</h2>
</div>
<div className="bg-white dark:bg-gray-800 p-8 rounded-xl border-2 border-dashed border-gray-300 dark:border-gray-600 text-center">
<p className="text-gray-500 dark:text-gray-400 text-lg">
{t.learning.comingSoon}
</p>
</div>
<button
onClick={() => router.push('/learning/openings')}
className="w-full group bg-white dark:bg-gray-800 p-8 rounded-xl hover:bg-purple-50 dark:hover:bg-gray-700 transition-all border-2 border-transparent hover:border-purple-500 dark:hover:border-purple-400 shadow-sm hover:shadow-md text-left"
>
<div className="flex items-center gap-4">
<div className="text-5xl group-hover:scale-110 transition-transform">
📖
</div>
<div>
<h3 className="font-bold text-gray-900 dark:text-white text-xl mb-2">
Opening Training
</h3>
<p className="text-gray-600 dark:text-gray-400">
Practice opening repertoire with engine-backed feedback and AI explanations
</p>
</div>
</div>
</button>
</div>
</div>
</div>
@@ -0,0 +1,17 @@
// Server component layout for static export
// This allows generateStaticParams while the page remains a client component
export async function generateStaticParams() {
const patterns = ['pin', 'skewer', 'fork', 'discovered_attack', 'discovered_check'];
return patterns.map((pattern) => ({
pattern,
}));
}
export default function TacticsPatternLayout({
children,
}: {
children: React.ReactNode;
}) {
return children;
}
+4 -4
View File
@@ -2,7 +2,7 @@
import { useState, useEffect, useRef } from "react";
import { useRouter, useParams } from "next/navigation";
import { Chess, Move } from "chess.js";
import { Chess, Move, Square } from "chess.js";
import { Chessboard } from "react-chessboard";
import { ArrowLeft, CheckCircle, XCircle, RefreshCw, SkipForward } from "lucide-react";
import Header from "@/components/Header";
@@ -153,7 +153,7 @@ export default function TacticalPracticePage() {
if (setupError) {
return (
<div className="min-h-screen bg-gray-50 dark:bg-gray-900">
<Header language={language} onLanguageChange={setLanguage} />
<Header language={language} />
<div className="container mx-auto px-4 py-8">
<div className="max-w-2xl mx-auto">
<div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-6">
@@ -218,7 +218,7 @@ export default function TacticalPracticePage() {
return t.learning.patterns[mapping[pattern]];
};
const onDrop = ({ sourceSquare, targetSquare }: { sourceSquare: string; targetSquare: string | null }) => {
const onDrop = ({ sourceSquare, targetSquare }: { sourceSquare: Square; targetSquare: Square | null }) => {
if (!targetSquare || feedback !== 'none') return false;
// Additional validation: Check if there's actually a piece on the source square
@@ -571,7 +571,7 @@ export default function TacticalPracticePage() {
position: fen,
onPieceDrop: ({ sourceSquare, targetSquare }) => {
console.log('🎲 onPieceDrop called with:', { sourceSquare, targetSquare });
return onDrop({ sourceSquare, targetSquare });
return onDrop({ sourceSquare: sourceSquare as Square, targetSquare: targetSquare as Square | null });
},
darkSquareStyle: { backgroundColor: '#779954' },
lightSquareStyle: { backgroundColor: '#e9edcc' },