Inspiration
As an amateur ice hockey player and team organizer, I've experienced firsthand the chaos of managing a recreational hockey team. Coaches juggle player availability via scattered WhatsApp messages, manually track statistics in spreadsheets, and struggle to make informed lineup decisions with incomplete data. When our goalie cancels 30 minutes before a game, you find out through a text message—not a proactive system.
I built PuckMind to solve these real problems with modern AI technology. The vision: an intelligent agent that doesn't just answer questions, but actively helps coaches manage their teams with visual communication, proactive warnings, and position-aware analytics.
## What it does
PuckMind is an AI-powered hockey team manager built on Google Gemini 2.5 Flash and MongoDB Atlas. It provides three standout features:
1. Visual Lineup Suggestions: When you ask for a lineup, PuckMind doesn't just list names—it generates an ASCII hockey rink showing exactly where each player should be positioned (forwards, defense, goalie) based on their statistics and availability. This visual communication makes lineup decisions instantly clear.
2. Natural Language Game Entry: Instead of clicking through forms, coaches can type "Lukas 2G 1A, Felix hat trick" and PuckMind automatically matches partial names to players and parses hockey shorthand. It understands that "hat trick" means 3 goals and handles ambiguous names intelligently.
3. Proactive Intelligence: Unlike reactive chatbots, PuckMind surfaces problems before you ask. Check your schedule and it immediately warns: "No goalie confirmed yet"—without being prompted. This proactive awareness is what separates intelligent agents from glorified search interfaces.
The system also handles the European ice hockey points system (W=3pts, OTW=2pts, OTL=1pt, L=0pts), tracks 19 different statistics across forwards/defenders/goalies, and provides a full schedule calendar with attendance tracking.
## How we built it
Architecture: PuckMind runs as a serverless application on Google Cloud Run, using Vertex AI to access Gemini 2.5 Flash. The Google Agent Development Kit (ADK) handles conversational state and tool orchestration, while MongoDB Atlas stores all team data (players, games, schedules, attendance).
Agent Design: The core agent has 19 specialized tools that handle everything from lineup suggestions to opponent analysis. Each tool is a Python function that the agent can invoke based on user queries. The key innovation was designing tools that return structured data the agent can transform into visual formats—like converting roster data into ASCII hockey rinks.
Frontend: Streamlit provides the web interface with 5 main tabs (Dashboard, Schedule, Add Game, Roster, Chat). The Game Wizard uses a 5-step workflow with "Quick Text Entry" mode for natural language parsing.
Deployment: Docker containerization with multi-stage builds targeting AMD64 architecture. Automated deployment scripts handle building, pushing to Google Container Registry, and updating Cloud Run with environment variables.
Testing: 38 test cases using pytest with mongomock for database mocking, plus a Nox pipeline running 10 sessions (tests, lint, format, type checking, security scanning).
## Challenges we ran out
Challenge 1: Visual Lineup Generation The biggest technical challenge was generating meaningful visual lineups. I didn't want simple text lists—I wanted an actual hockey rink diagram. The solution was creating an ASCII art hockey rink template and dynamically injecting player names based on position. The agent formats this as a code block, making it readable in the chat interface. This required careful spacing calculations and handling variable-length player names.
Challenge 2: Natural Language Parsing Parsing game entries like "Lukas 2G 1A, Felix hat trick" seems simple but has many edge cases: partial names ("Lukas" vs "Lukas Schäfer"), hockey shorthand ("hat trick", "G", "A"), multiple players in one string, and malformed input. I built a robust parser using regex patterns and fuzzy player matching against the MongoDB database. The key insight was letting the agent handle ambiguity—if "Lukas" matches two players, the agent asks for clarification.
Challenge 3: European vs North American Points
European ice hockey uses a 5-outcome system (W, OTW, OTL, L, plus ties in some leagues) with different point values than North American hockey. This required restructuring the entire
game result model to track result_type (regulation win, overtime win, shootout loss, etc.) and calculating standings differently. The dashboard now shows 5 separate metrics instead of
the traditional 3.
Challenge 4: MongoDB Connection on Cloud Run
Initial deployment failed with ConfigurationError: Unknown option: ssl_cert_reqs. The issue: I was using deprecated pymongo SSL parameters. MongoDB Atlas connection strings already
include TLS configuration, so the solution was removing explicit SSL parameters. This taught me to rely on connection string URIs rather than manual configuration.
Challenge 5: Fake Statistics Bug An early version automatically assigned goalies to games and estimated shots (opponent goals + 10). This created misleading statistics. The fix was separating "quick entry" (for basic game results) from "Game Wizard" (for complete stats including accurate goalie data). This distinction clarified the UX and prevented bad data.
## What we learned
AI Agent Design is Hard: Building an agent that feels intelligent (not just reactive) requires careful prompt engineering, tool design, and understanding when to make the agent proactive vs responsive. The difference between "here are the available players" and "here's your lineup AND you have no goalie confirmed" is massive for user experience.
Vertical Domain Knowledge Matters: Generic sports apps fail because they don't understand domain nuances. PuckMind works because it handles European points, position-specific stats (shooting % for forwards, blocked shots for defenders), and hockey-specific terminology. Deep domain expertise makes AI agents genuinely useful.
Visual Communication > Text Dumps: The hockey rink visualization gets more positive reactions than any other feature. Humans process visual information faster than text lists. AI agents should leverage visual formats whenever possible.
MongoDB + LLMs is Powerful: Using MongoDB Atlas with an LLM agent creates a flexible system where the schema can evolve (I added ice_time analysis later) without major refactoring. Document databases work naturally with AI agents because queries return structured JSON the LLM can reason about.
Deployment Matters: A working demo on localhost impresses no one. Deploying to Cloud Run with a public URL made the project tangible and testable by others. The discipline of containerization and CI/CD also improved code quality.
## What's next for PuckMind
- Mobile optimization for coaches managing teams from the bench
- WhatsApp integration for automated attendance reminders and game notifications
- Multi-team SaaS to support multiple teams with shared player pools
- Live game tracking with real-time stat updates via mobile app
- Advanced analytics like expected goals (xG), zone time, and player chemistry analysis
The foundation is solid—now it's about scaling to more teams and deeper analytics.
Log in or sign up for Devpost to join the conversation.