Built for the Dallas AI Hackathon 2026 (Tracks: Dallas AI + Data Science / ML)

Pondr is an intelligent learning platform that uses a knowledge graph canvas, ML-based knowledge decay prediction, and Google Gemini AI to personalize how you learn — and when you review — so nothing you study ever truly fades.

• Overview
• Architecture
• Tech Stack
• Features
• ML Model
• API Reference
• Database Models
• Setup & Installation
• Environment Variables
• Running the App
• Project Structure
• Gamification System

Pondr models your brain as a live knowledge graph. Each concept you're learning is a node. The ML engine continuously predicts when your retention of each concept will drop below a threshold — and recommends targeted micro-reviews before knowledge decays.

Core capabilities:

• Knowledge graph canvas (React Flow) — drag, explore, and visualize your learning as an interconnected web
• Decay prediction (XGBoost + Ebbinghaus forgetting curves) — personalized retention scoring per concept
• Gemini AI tutor — Feynman challenges, Socratic debates, quick snapshots, and adaptive quizzes
• YouTube snippet pipeline — finds the exact 2–3 minute video clip most relevant to your current gap
• Voice input — ElevenLabs STT for hands-free learning entry

┌─────────────────────────────────────────────────────┐
│                    Frontend                          │
│  React 18 + Vite │ React Flow │ Zustand │ Tailwind  │
│  Port: 5173 — /api proxied to :8000                  │
└────────────────────────┬────────────────────────────┘
                         │ HTTP / Axios
┌────────────────────────▼────────────────────────────┐
│                    Backend                           │
│  FastAPI (Python) │ Uvicorn ASGI │ Port: 8000        │
│  JWT Auth │ Beanie ODM │ Motor (async)               │
└──────┬────────┬────────┬────────┬────────┬──────────┘
       │        │        │        │        │
   MongoDB   Gemini   YouTube  Tavily  ElevenLabs
             2.5-flash  v3 API  Search    TTS/STT
                         │
                   XGBoost Model
                  (decay_model.joblib)

Data Flow:

1. User registers/logs in → JWT token issued (7-day expiry)
2. Onboarding: goal + background → Gemini generates initial knowledge graph (nodes + edges)
3. User interacts with nodes → learning events logged → XP awarded
4. Decay engine scores each node via XGBoost → updates node state (green/yellow/fading/red)
5. Gemini recommendations surface targeted YouTube clips and practice scenarios
6. Study schedule generated by Gemini → synced to Google Calendar

The main learning interface is a React Flow canvas where each concept is a node with a color-coded state:

• Drag nodes to reorganize your personal knowledge map — positions persist across sessions
• Click a node to open the learning panel (video, Feynman, Socratic, quick snapshot)
• Search to add new concepts; Gemini auto-integrates them into your existing graph
• Timeline scrubber lets you replay your learning history

Feynman Challenge — Explain a concept in plain terms; Gemini evaluates your explanation and identifies gaps, returning targeted feedback.

Socratic Debate — Gemini takes a position, you defend yours. Multi-turn debate with progressive pushback. Full conversation history passed each turn.

Quick Snapshot — 30-second Gemini summary of a concept tailored to your current knowledge level.

YouTube Snippet — Pipeline searches YouTube, extracts transcripts for top 3 results, uses Gemini to identify the most relevant 2–3 minute timestamp window for your specific gap.

Adaptive Quiz — Gemini generates a personalized quiz based on your mastery score and recent learning events.

ElevenLabs STT powers voice input on:

• Onboarding (describe your prior knowledge hands-free)
• Canvas search (speak a concept to add it)

• Full OAuth 2.0 flow — read/write access to Google Calendar
• AI-generated weekly study schedules created by Gemini (based on your hubs, availability, and decay alerts)
• Sessions auto-created as Google Calendar events with concept context

• Tavily — real-time web search for concept enrichment
• Firecrawl — intelligent web scraping for resource extraction

The XGBoost model predicts retention R(t) for each user-concept pair — the probability you still remember a concept at time t. Range: 0.0 (forgotten) → 1.0 (perfect recall).

It personalizes the Ebbinghaus stability parameter S based on 10 behavioral features.

1,000 synthetic learner records generated with realistic behavioral distributions (backend/ml/generate_dataset.py). Model trained with backend/ml/train_model.py and serialized to backend/ml/decay_model.joblib.

• days_since_review = 0 → return retention 1.0 (skip model)
• last_reviewed is null → set days_since_review = 99, return retention 0.0
• review_count = 0 → skip model, return state red
• All predictions clipped to [0.0, 1.0]
• Model file missing → log warning, return 0.5 default

All endpoints (except Auth and Health) require Authorization: Bearer <token>.

All models use MongoDB + Beanie ODM (async Pydantic documents).

Core user record with auth, profile, and gamification fields. has_onboarded gates the onboarding flow. Google OAuth tokens stored for Calendar access.

A learning topic (e.g., "Machine Learning", "React Development"). Each hub has its own node subgraph.

A single concept in the knowledge graph. Tracks Ebbinghaus parameters (stability_s, retention_rt), canvas position, mastery score, and decay state.

Every user interaction logged as an event: view, rewatch, practice, feynman, snapshot, quiz. XP earned per event stored here.

Gemini-generated recommendation for a node, including YouTube video ID and exact timestamp window.

Directed edge between two ConceptNodes with type: prerequisite or related.

AI-generated weekly study schedule. Contains embedded StudySession objects with optional Google Calendar event IDs.

Defines unlock conditions and XP rewards for the achievement system.

• Python 3.11+
• Node.js 18+
• MongoDB (local or Atlas)
• API keys: Gemini, YouTube, ElevenLabs, Tavily, Firecrawl
• (Optional) Google Cloud project with OAuth 2.0 credentials for Calendar

git clone <repo-url>
cd HackAI2026
cp example.env .env
# Edit .env with your API keys

cd backend
python -m venv venv
source venv/bin/activate       # Windows: venv\Scripts\activate
pip install -r requirements.txt

# From backend/
python ml/generate_dataset.py  # Generates synthetic dataset (1000 records)
python ml/train_model.py       # Trains XGBoost, saves decay_model.joblib + metrics.json

python database/seed.py
# Demo user: alex@pondr.dev / demo1234

cd ../frontend
npm install

Copy example.env to .env at the project root:

# Database
MONGO_DB_URI=mongodb://localhost:27017
MONGO_DB_NAME=pondr

# AI APIs
GEMINI_API_KEY=your_gemini_api_key
YOUTUBE_API_KEY=your_youtube_data_api_key
ELEVENLABS_API_KEY=your_elevenlabs_api_key
TAVILY_API_KEY=your_tavily_api_key
FIRECRAWL_API_KEY=your_firecrawl_api_key

# Google OAuth (for Calendar + Sign-In)
GOOGLE_CLIENT_ID=your_google_oauth_client_id
GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret
GOOGLE_REDIRECT_URI=http://localhost:5173

# App Security
SECRET_KEY=change_this_to_a_random_32_char_string

# CORS
CORS_ORIGINS=http://localhost:5173

# ngrok (optional — for exposing local backend publicly)
# NGROK_URL=https://xxxx.ngrok-free.app

# ML Thresholds
DECAY_THRESHOLD=0.70
DECAY_ALERT_WINDOW_DAYS=3

# Terminal 1: Backend
cd backend
uvicorn main:app --reload --port 8000

# Terminal 2: Frontend
cd frontend
npm run dev

App: http://localhost:5173 API docs (Swagger): http://localhost:8000/docs

If you need to share the backend publicly (e.g., for Google OAuth callbacks or mobile testing), use ngrok:

ngrok http 8000
# Outputs something like: https://abcd1234.ngrok-free.app

Then update your .env:

NGROK_URL=https://abcd1234.ngrok-free.app
CORS_ORIGINS=http://localhost:5173,https://abcd1234.ngrok-free.app
GOOGLE_REDIRECT_URI=https://abcd1234.ngrok-free.app

The backend automatically adds the NGROK_URL to CORS allowed origins and also allows any *.ngrok-free.app subdomain via regex — no backend restart required after setting the env var.

HackAI2026/
├── .env                          # API keys (never commit)
├── example.env                   # Environment template
├── CLAUDE.md                     # Development guide
├── README.md                     # This file
├── backend/
│   ├── main.py                   # FastAPI entry point + router registration
│   ├── requirements.txt
│   ├── database/
│   │   ├── models.py             # All Beanie document models
│   │   ├── connection.py         # Motor client + Beanie initialization
│   │   └── seed.py               # Demo data seeder
│   ├── ml/
│   │   ├── generate_dataset.py   # Synthetic learner data generation
│   │   ├── train_model.py        # XGBoost training + metrics
│   │   ├── predict.py            # Inference + retention scoring
│   │   ├── evaluate.py           # RMSE, MAE, lift computation
│   │   ├── decay_model.joblib    # Serialized trained model
│   │   ├── dataset.csv           # Training data
│   │   └── metrics.json          # Model performance metrics
│   ├── api/
│   │   ├── deps.py               # JWT get_current_user dependency
│   │   ├── auth.py               # Auth endpoints (register/login/google/guest)
│   │   ├── users.py              # Onboarding, user profile
│   │   ├── graph.py              # Canvas state, events, positions, history
│   │   ├── gemini.py             # AI recommendations, Feynman, Socratic
│   │   ├── youtube.py            # Video snippet pipeline
│   │   ├── assess.py             # Quiz generation & grading
│   │   ├── search.py             # Web search + scraping
│   │   ├── calendar.py           # Google Calendar integration
│   │   └── speech.py             # ElevenLabs STT/TTS
│   └── services/
│       ├── auth_service.py       # JWT, bcrypt, authentication logic
│       ├── gemini_service.py     # All Gemini prompts + retry logic
│       ├── youtube_service.py    # YouTube search + transcript pipeline
│       ├── graph_service.py      # NetworkX graph operations
│       ├── google_oauth_service.py # OAuth code exchange + token refresh
│       ├── calendar_service.py   # Google Calendar CRUD
│       ├── search_service.py     # Tavily web search
│       ├── firecrawl_service.py  # Web scraping
│       └── gamification_service.py # XP, levels, streaks, achievements
└── frontend/
    ├── package.json
    ├── vite.config.js            # Vite + /api proxy to :8000
    ├── tailwind.config.js        # Custom dark theme colors
    └── src/
        ├── App.jsx               # Router + RequireAuth HOC
        ├── api/client.js         # Axios instance + 401 auto-guest interceptor
        ├── store/useStore.js     # Zustand: auth, hubs, graph, gamification
        ├── pages/
        │   ├── Landing.jsx       # Public homepage
        │   ├── Login.jsx         # Auth UI (email + Google OAuth)
        │   ├── Onboarding.jsx    # Goal/background + voice input
        │   ├── Canvas.jsx        # Main React Flow canvas
        │   ├── ConceptPage.jsx   # Single concept learning
        │   ├── QuizPage.jsx      # Adaptive quiz UI
        │   ├── Dashboard.jsx     # Hub overview + gamification
        │   ├── Hubs.jsx          # Browse learning topics
        │   └── Planner.jsx       # Google Calendar week view
        └── components/
            ├── canvas/           # ConceptNode, RecommendationCard, TimelineScrubber
            ├── learning/         # FeynmanChallenge, SocraticDebate, QuickSnapshot, VideoSnippet
            ├── gamification/     # XPBar, StreakCounter, LevelBadge, AchievementToast
            ├── auth/             # GoogleSignIn button
            ├── calendar/         # WeekView
            └── ui/               # Sidebar, MetricsPanel

Register/Login → JWT (7-day, HS256) → localStorage (pondr_token)
     ↓
All API calls: Authorization: Bearer <token>
     ↓
Backend: get_current_user() → decode JWT → fetch User from MongoDB
     ↓
401 response → Axios interceptor → auto guest login → retry

Google OAuth: Exchanges auth code for Google tokens, links by google_id or email, stores refresh token for Calendar access, returns Pondr JWT.

Demo credentials: alex@pondr.dev / demo1234

Built with Google Gemini 2.5 Flash, XGBoost, React Flow, and FastAPI.