Skip to content

dimafarer/dontspin

Repository files navigation

🎓 DontSpin

AI-powered adaptive learning that feels natural.

DontSpin is a serverless Python learning platform that generates unlimited personalized coding challenges, provides progressive coaching, and tracks skill mastery — all powered by AI agents that adapt in real time to each learner's demonstrated ability.

"Deliver delightful AI learning experiences that enable individuals and businesses to achieve their goals."


The Problem

When learners get stuck and spin their wheels, they're not learning — they're burning out. But when someone hands them the answer, they're not learning either.

Every existing coding platform falls into one of these traps:

Platform Style What It Does What's Missing
Problem banks (LeetCode, HackerRank) Fixed problems, binary pass/fail No personalization, no coaching, no concept progression
Guided tutorials (Codecademy, freeCodeCamp) Step-by-step walkthroughs No adaptive difficulty, learners repeat comfortable exercises
Video courses (Udemy, Coursera) Passive consumption No hands-on practice, no feedback loop

None of them combine adaptive challenge generation, progressive coaching, conceptual understanding assessment, and real-time difficulty adjustment into a single integrated experience.

How DontSpin Works

┌──────────────────────────────────────────────────────────────┐
│                     The Learner Experience                    │
│                                                              │
│   1. Get a challenge tailored to YOUR level                  │
│   2. Write code in the browser (runs via Pyodide)            │
│   3. Stuck? Ask for a hint — coaching escalates gradually    │
│   4. Submit — AI evaluates code quality AND understanding    │
│   5. Next challenge adapts based on how you performed        │
│                                                              │
│   Every challenge is unique. Every hint builds on the last.  │
│   Every level reflects genuine capability.                   │
└──────────────────────────────────────────────────────────────┘

Adaptive Challenge Generation

Challenges aren't pulled from a database. Four AI agents (built on Strands SDK with Claude Sonnet 4.6) generate them in real time based on:

  • Your skill profile — per-skill levels, weighted success rates, error patterns
  • Your learning pace — solve times, coaching frequency, consecutive skips
  • Your curriculum position — which concept you're learning, which exercise types you've completed
  • Your history — recent challenges (for deduplication), coaching interactions, session stats

A learner struggling with integer arithmetic gets easier, more focused challenges with extra hints. A learner breezing through gets pushed to harder variations. Same concept, different experience.

Progressive Coaching — Not Binary Help

Most platforms offer two modes: no help, or the complete answer. DontSpin's coaching agent provides three tiers that escalate only when the learner genuinely needs it:

Request 1 → Conceptual:  "Think about what data structure lets you look up values by key."
Request 2 → Strategic:   "A dictionary would work. Consider iterating the input to build it."
Request 3 → Tactical:    "Try: for item in data: result[item['key']] = item['value']"

The coaching agent loads your full history for this challenge — it never repeats itself, and it builds on what it's already told you. Heavy hint usage is tracked and factors into your skill progression (hint-assisted solves don't earn streak bonuses).

Predict-Observe-Explain Exercises

DontSpin implements a novel exercise methodology adapted from physics education research (PhET, University of Colorado). No other coding platform does this:

┌─────────────────────────────────────────────────┐
│  1. PREDICT: "What will this code print?"       │
│     Learner commits to an answer BEFORE running │
│                                                 │
│  2. OBSERVE: Code runs, actual output shown     │
│     Side-by-side comparison with prediction     │
│                                                 │
│  3. EXPLAIN: "Why did this happen?"             │
│     AI judges the quality of reasoning,         │
│     not just whether the prediction was right   │
└─────────────────────────────────────────────────┘

A wrong prediction with a correct explanation scores higher than a right prediction with no explanation. Understanding why matters more than guessing correctly.

Dual Mastery Dimensions

Topic mastery requires demonstrating both:

  1. Code-writing ability — can you solve the problem?
  2. Conceptual understanding — can you predict behavior and explain why?

A learner who writes working code but can't predict what // does with negative numbers hasn't truly mastered integer arithmetic. The mastery tracker requires both dimensions before advancing to the next topic.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   React +   │     │  API Gateway     │     │  4 Strands SDK  │
│   TypeScript │────►│  WebSocket API   │────►│  AI Agents      │
│   + Pyodide  │◄────│  + JWT Authorizer│◄────│  (Claude 4.6)   │
│   (browser)  │     │  + Rate Limiting │     │                 │
└─────────────┘     └──────────────────┘     └────────┬────────┘
                                                       │
                    ┌──────────────────┐               │
                    │    DynamoDB      │◄──────────────┘
                    │  Single Table    │
                    │  (8 entity types)│
                    └──────────────────┘

Agents:
  🎯 Challenge Generator — creates personalized exercises
  📝 Code Evaluator — judges code quality + conceptual understanding
  🆘 Coaching Agent — progressive hints that build on each other
  👋 Welcome Agent — conversational onboarding + profile reconfiguration

Extensible Learning Plans

The engine is plan-agnostic. Learning plans are pluggable modules that provide curriculum structure and agent personality without changing any engine code:

┌─────────────────────────────────────────────┐
│              DontSpin Engine                 │
│  (agents, skill algorithm, mastery tracker, │
│   streaming, auth, DynamoDB operations)     │
│                                             │
│         ┌───────────────────────┐           │
│         │    Plan Interface     │           │
│         │  • curriculum map     │           │
│         │  • 4 voice profiles   │           │
│         │  • plan_id            │           │
│         └───────┬───────────────┘           │
└─────────────────┼───────────────────────────┘
                  │
       ┌──────────┴──────────┐
       │                     │
  ┌────┴─────┐         ┌────┴─────┐
  │  PLYMI   │         │  Future  │
  │  Plan    │         │  Plans   │
  │          │         │ (ATBS,   │
  │ 10 levels│         │  Django, │
  │ mapped to│         │  boto3)  │
  │ PLYMI    │         │          │
  │ textbook │         │ Same     │
  │ modules  │         │ engine,  │
  │          │         │ different│
  │ Unique   │         │ content  │
  │ voice per│         │ & voice  │
  │ agent    │         │          │
  └──────────┘         └──────────┘

Adding a new learning plan means creating a curriculum map and four voice profile strings. No engine code changes. No agent rewrites. No infrastructure updates.

Tech Stack

Layer Technology
Frontend React + TypeScript + Vite, Zustand, Monaco Editor, Pyodide (browser Python)
Backend Python 3.12 Lambda, Strands SDK agents, Claude Sonnet 4.6
Data DynamoDB single-table design (8 entity types)
API API Gateway WebSocket with JWT authorizer + rate limiting
Auth Amazon Cognito
Hosting S3 + CloudFront (private bucket, OAC, COOP/COEP headers)
Infrastructure AWS CDK (Python), two stacks
Testing 83 tests: Hypothesis (backend), Vitest + fast-check (frontend), CDK assertions

The Skill Algorithm

DontSpin uses a weighted progression algorithm that goes beyond simple pass/fail:

                    Success
                       │
          ┌────────────┼────────────┐
          │            │            │
     Fast solve   Normal solve  Slow solve
     + no hints   + few hints   + many hints
          │            │            │
       +3 levels    +1 level    +1 level
     (speed bonus  (base)      (dampened,
      + streak                  coaching
      bonus)                    penalty)
          │            │            │
          └────────────┼────────────┘
                       │
                    Failure
                       │
              weighted rate < 0.40?
              ┌────────┴────────┐
              │                 │
           Yes: -1           No: 0
           level             (no change)

Levels reflect genuine understanding. A learner who solves fast without hints progresses quickly. A learner who needs tactical hints on every problem stays at their current level until they demonstrate independence.

What Makes This Different

Capability DontSpin Traditional Platforms
Challenge source AI-generated, unlimited, unique per learner Fixed problem bank
Difficulty Adapts per-skill based on 8+ signals Static levels or manual selection
Coaching 3-tier progressive hints with memory Binary: no help or full solution
Assessment Code quality + conceptual understanding Output matching only
Exercise types Code writing + prediction + investigation + efficiency Code writing only
Progression Dual mastery (code ability + conceptual) Single dimension (pass/fail)
Personalization Real-time, per-skill, per-session None or coarse-grained

Running Locally

# Backend tests
cd backend/agents && python -m pytest tests/ -v --tb=short

# Frontend
cd frontend && npm install && npm run dev

# Frontend tests
cd frontend && npx vitest --run

# CDK deploy
cd infrastructure && cdk deploy DontSpinBackendStack
cd infrastructure && cdk deploy DontSpinFrontendStack

Project Status

  • ✅ 4 AI agents streaming over WebSocket
  • ✅ Adaptive skill algorithm with 8+ personalization signals
  • ✅ Predict-Observe-Explain exercise methodology
  • ✅ Dual mastery tracking (code + conceptual)
  • ✅ Extensible learning plan framework (PLYMI active)
  • ✅ JWT-authenticated WebSocket with rate limiting
  • ✅ 83 automated tests (property-based + unit + CDK assertions)
  • ✅ Deployed and live on AWS

DontSpin doesn't make learning easy. It makes the struggle productive. Every challenge is calibrated. Every hint is earned. Every level reflects real capability.

We don't spin wheels. We build engineers.

About

AI-powered Python learning platform — adaptive coding challenges, Socratic ▎ coaching, and mastery tracking. Built serverless on AWS with Claude (Bedrock) ▎ and the Strands agent SDK

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors