Pinochle Academy

An interactive app for learning and playing partnership Pinochle, with a world-class AI coach that explains the reasoning behind every decision — options, tradeoffs, and what your opponents are likely to do and why.

Built with Vite + React + TypeScript + Tailwind CSS v4. The game engine is fully deterministic and real (no mock data); coaching prose is generated by LLMs via OpenRouter, grounded on the engine's own analysis so it cannot invent rules.

Features

• Interactive Tutorial — step-by-step lessons from zero.
• Trick-Play Trainer (Practice) — play a hand against 3 AI seats; click any legal card for instant coaching, with an "Explain deeper" Panel of Coaches that shows multiple models' master-level analysis side by side.
• Bid Lab — hand-based bidding drills with reasoning.
• Meld Finder — a mini-game for spotting runs, marriages, pinochles, and arounds (singles and doubles).
• Full Game — a complete 4-player partnership match: Bidding → Trump → Melding → 12 Tricks, coached throughout.
• Glossary — ranks, melds, scoring, rules, and strategy reference.
• Floating Coach Chat — ask follow-up questions anywhere; it sees your live hand, trump, trick, and score for specific answers.
• XP / level / streak persisted to localStorage, win celebrations.

Rulesets

Two selectable variants share one engine:

• Standard Partnership — 48-card double deck (two each of A, 10, K, Q, J, 9), 12 cards per hand, 12 tricks.
• Double-Deck (Tournament) — 80-card deck (four each of A, 10, K, Q, J, no 9s), 20 cards per hand, 20 tricks.

Getting started

npm install
npm run dev        # start the dev server (http://localhost:5173)
npm run build      # production build (single-file dist/index.html)
npm test           # run the engine assertions
npm run typecheck  # tsc --noEmit

AI coach configuration (optional)

The app works fully offline with a real, deterministic rule-based coach. To enable the richer LLM coaching and the chat, copy .env.example to .env and fill in your OpenRouter key and model id(s):

cp .env.example .env
# then edit .env:
VITE_OPENROUTER_API_KEY=sk-or-...
VITE_COACH_MODEL_1=google/gemini-...     # default quick-take coach
VITE_COACH_MODEL_2=x-ai/grok-...         # also queried in the deep panel

Notes:

• You select the models. No model id is hardcoded. Pick current ones from https://openrouter.ai/models.
• Vite only exposes VITE_-prefixed variables to the browser. .env is gitignored — never commit a real key.
• Prefer non-"reasoning" models for coaching, or allow a generous token budget; reasoning models spend most of their tokens thinking before answering.

Project structure

src/
  lib/
    pinochle.ts      # deck, dealing, melds, legality, trick logic, AI, rulesets
    analysis.ts      # grounded per-decision analysis (options + opponent reads)
    coach.ts         # quick take, panel-of-coaches, chat (OpenRouter + fallback)
    pinochle.test.ts # dependency-free engine assertions (npm test)
  components/        # Card, UI primitives, CoachPanel, CoachChat
  hooks/useXP.ts     # XP/level/streak persistence
  views/             # Landing, Tutorial, Practice, BidLab, MeldFinder, FullGame, Glossary