Project Info
This project did not submit a demo video on Devpost.
About the Project We are a bunch of amateur players who love playing chess, but over time we noticed that our improvement has become stagnant. Like many college students, we neither have the time nor the financial means to invest in professional coaching to take our game to the next level. This frustration sparked the idea behind Pawn Up—a project built to help players like us break through the plateau and improve their chess skills in their own time, without expensive coaches or overwhelming resources. What Inspired Us As passionate chess players, we struggled with finding affordable and effective ways to improve. Chess can be an expensive hobby if you want to seek professional help or guidance. The available tools often lacked the depth we needed or came with hefty price tags. We wanted something that would provide personalized feedback, targeted training, and insights that anyone could access—regardless of their financial situation. How We Built It We started by integrating Lichess authentication to fetch a user's game history, allowing them to directly analyze their own performance. With Groq and Llama3.1, we leveraged AI to categorize mistakes, generate feedback, and suggest relevant puzzles to help users train and improve. We also levergae ChromaDB for vector search features and Gemini pro and Gemini embedding Our project features four key components: Analyze: Fetches the user's last 10 games, provides analysis on each move, and visualizes a heatmap showing the performance of legal moves for each piece. Users can also interact with the game for deeper analysis. Train: Using AI, the system analyzes the user's past games and suggests categorized puzzles that target areas of improvement. Search: We created a vector database storing thousands of grandmaster games. Users can search for specific games and replay them with detailed analysis, just like with their own games. Upload: Users can upload their own chess games and perform the same analyses and training as with the Search feature. What We Learned Throughout the development of Pawn Up, we gained a deeper understanding of AI-powered analysis and how to work with complex game datasets. We learned how to integrate chess engines, handle large amounts of data, and create user-friendly interfaces. Additionally, we explored how LLMs (large language models) can provide meaningful feedback and how vector databases can be used to store and retrieve massive datasets efficiently. Challenges We Faced One of the main challenges we encountered was making the AI feedback meaningful for players across various skill levels. It was crucial that the system didn’t just provide generic advice but rather tailored suggestions that were both practical and actionable. Handling large amounts of chess data efficiently, without compromising on speed and usability, also posed a challenge. Building the vector database to store and search through grandmaster games was a particularly challenging but rewarding experience. Despite these hurdles, we’re proud of what we’ve built. Pawn Up is the solution we wish we had when we first started hitting that plateau in our chess journeys, and we hope it can help others as well.
This project was made for CalHacks 2024
Overview
It is a chess AI tutor that evaluates your lichess games and helps you improve through customized puzzles, using AI to evaluate and understand every move possible.
Installation Guide
-
Clone the repository
-
Install the dependencies (npm install, pip install)
-
Run the frontend (npm run dev)
-
Run the backend (flask --app app run)
-
Run search backend ( npm start )
-
Start the Chroma DB with chroma run --path ./getting-started
Read the docs for more clarification ( https://docs.trychroma.com/getting-started )
APIs KEYS
- Google Gemini API
- RAPID CHESS API
- Llama API
- Groq API
How it works
- Get customized puzzles based on your lichess games
- Evaluate your games and give you personalized feedback with AI
- Upload your games to the database and view them in the website or search for popular games with semantic search
- Example: "Carlsen, Nakamura, Queens openings"
Results
Analysis
View
Metric
- 18
- 13
- 13
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- ExpressIn code
- Google GeminiIn code
- HTMLIn code
- JavaScriptIn code
- PythonIn code
- ReactIn code
- Tailwind CSSIn code
- DockerClaimed
- FlaskClaimed
- Node.jsClaimed
8 of 11 appear in the indexed code. 3 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
80 KB
Source files
25
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
satwikug25/CalHacks
54 files · 55.9 MB · @ f7ea697
Structure
Interface
10 files · 19%Screens, components and styles rendered to the user.
Application logic
12 files · 22%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- JavaScript77%
- Python16%
- Markdown3%
- CSS2%
- HTML0%
- YAML0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
frontend/package.json
npm · 26- @bity/oauth2-auth-code-pkce
- @chakra-ui/react
- @emotion/react
- @emotion/styled
- axios
- chess.js
- framer-motion
- react
- react-chessboard
- react-dom
- react-icons
- react-router-dom
- shadcn-ui
- +13 more
search-engine-nodejs-server/package.json
npm · 13- @google/generative-ai
- @singlestore/client
- axios
- body-parser
- chromadb
- chromadb-default-embed
- cors
- dotenv
- express
- llama-node
- mysql2
- nodemon
- punycode
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
AI-categorized mistakes and puzzle recommendations (Train)Verified
Using AI, the system analyzes the user's past games and suggests categorized puzzles that target areas of improvement
Claimed on Devposthigh confidencebackend/app.py:252— get_llama_feedback prompts Groq to return strengths/areas_for_improvement/recommended_themes from a fixed puzzle-category listbackend/app.py:319— get_puzzles fetches puzzles per recommended theme from the RapidAPI chess-puzzles endpointfrontend/src/app/Train.jsx:30— fetchTrainingData calls /analyze_and_get_puzzles and renders an interactive puzzle-solving board
ChromaDB vector database for semantic searchVerified
We also leverage ChromaDB for vector search features
Claimed on Devposthigh confidencesearch-engine-nodejs-server/server.js:4— Imports and instantiates ChromaClient, creates 'chess_games' collection, used for add/querysearch-engine-nodejs-server/docker-compose.yml:4— Docker service running the chromadb/chroma image
Fetch and analyze last games from LichessVerified
Fetches the user's last 10 games, provides analysis on each move
Claimed on Devposthigh confidencebackend/app.py:223— get_games/<username> pulls up to 10 rapid games from Lichess APIbackend/methods.py:6— getGames fetches up to 25 games used for feedback generationfrontend/src/app/Analyze.jsx:15— Fetches games from /get_games/<username> and renders selectable games
Groq + Llama3.1 for AI feedbackVerified
With Groq and Llama3.1, we leveraged AI to categorize mistakes, generate feedback, and suggest relevant puzzles
Claimed on Devposthigh confidencebackend/app.py:23— Groq client initialized with GROQ_API_KEYbackend/app.py:136— model set to llama-3.1-70b-versatile, used across ask_question, get_evaluation, and get_llama_feedback
Interactive game chat / deeper analysis Q&AVerified
Users can also interact with the game for deeper analysis
Claimed on Devposthigh confidencefrontend/src/app/components/ChessGameChat.jsx:78— handleAskQuestion posts question/pgn/currentMove to /ask_questionbackend/app.py:138— ask_question endpoint sends prompt to Groq Llama model and returns a chess-specific answer
Lichess OAuth authenticationVerified
Integrating Lichess authentication to fetch a user's game history
Claimed on readmehigh confidencebackend/app.py:38— PKCE OAuth flow against lichess.org/oauth, exchanges code for access_token at /callback and fetches account info
Move-level heatmap of legal movesVerified
Visualizes a heatmap showing the performance of legal moves for each piece
Claimed on Devposthigh confidencefrontend/src/app/components/ChessGameChat.jsx:142— onSquareClick fetches per-move evaluations from /get_evaluation and colors squares via getColorFromEvaluation based on eval scorebackend/app.py:180— get_evaluation endpoint returns an array of eval scores for each possible move via Groq
Gemini Pro and Gemini embeddingsCode-supported
and Gemini pro and Gemini embedding
Claimed on Devpostmedium confidencesearch-engine-nodejs-server/server.js:5— Uses GoogleGenerativeAI with gemini-1.5-flash for descriptions and text-embedding-004 for embeddings; note the model used is gemini-1.5-flash, not explicitly 'Gemini Pro' as claimed
Semantic natural-language search (e.g. player/opening names)Code-supported
search for popular games with semantic search, Example: Carlsen, Nakamura, Queens openings
Claimed on readmemedium confidencesearch-engine-nodejs-server/server.js:74— Search embeds the free-text query and does a nearest-neighbor query against stored game embeddings/descriptions, consistent with semantic search, but no seeded 'thousands of grandmaster games' dataset was found in this clone to confirm the described scale
Upload own games for analysis/trainingCode-supported
Users can upload their own chess games and perform the same analyses and training as with the Search feature
Claimed on Devpostmedium confidencefrontend/src/app/UploadSearch.jsx:80— Parses PGN files or manual form input and posts each game to the upload backendsearch-engine-nodejs-server/server.js:52— /upload endpoint generates a Gemini description, embeds the game, and stores it in the ChromaDB collection
Vector search over grandmaster games (Search)Code-supported
We created a vector database storing thousands of grandmaster games. Users can search for specific games and replay them with detailed analysis
Claimed on Devpostmedium confidencesearch-engine-nodejs-server/server.js:74— /search endpoint embeds the query with Gemini and queries a ChromaDB collection, returning games rendered in a replayable boardfrontend/src/app/Search.jsx:21— handleSearchCall posts to /search and displays a move-by-move replay UI
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.