Yachay Lab

The free virtual STEM lab for every student who never had one.

Comment

Yachay Lab — Project Story

🌿 Inspiration

I grew up in Huánuco, Peru — a city in the Andes where most surrounding schools have no science laboratory. Students memorize formulas like:

$$T = 2\pi\sqrt{\frac{L}{g}}$$

...but never actually swing a pendulum and feel why the period doesn't depend on mass. They write $F = ma$ on exams without ever pushing something and measuring the acceleration. STEM becomes an abstract language disconnected from reality.

The statistics paint a clear picture: over 70% of rural schools across Latin America lack access to a functional science laboratory. In Peru alone, hundreds of thousands of students graduate secondary school having never performed a real physics or chemistry experiment.

When I learned about DSH Hacks V1's theme — AI and STEM education — I didn't need to think twice. The problem was right outside my window. The solution had to be digital, free, and powerful enough to replace a physical lab on any browser-enabled device.

I named it Yachay Lab. Yachay (야차이) means "to learn" in Quechua, the ancestral language of the Andes. It felt right.

⚗️ What it does

Yachay Lab is a complete virtual STEM laboratory with an embedded AI tutor, accessible from any browser, completely free, with no ads and no mandatory registration.

17 Interactive Simulators

Students can run real-time physics and chemistry experiments by adjusting sliders and watching the phenomenon animate on canvas:

Area Simulators
⚡ Physics URM, MRUA, Free Fall, Projectile Motion, Simple Pendulum, Hooke's Law, Waves, Ohm's Law, Optics, Mechanical Energy, Statics I, Statics II
🧪 Chemistry pH & Acid-Base, Ideal Gases, Chemical Reactions, Titration, Periodic Table

For example, in the Statics I simulator, students can place up to 3 force vectors at any magnitude and angle, and watch the resultant and equilibrant vectors update in real time, verifying $\sum F = 0$ visually.

In the Ideal Gases simulator, students manipulate $P$, $V$, $n$, and $T$ and watch animated particles respond to $PV = nRT$.

🤖 Yachay AI Tutor

Powered by Groq + LLaMA 3.3 70B Versatile, Yachay uses the Socratic method — it never gives the direct answer. Instead, it responds with guiding questions, analogies from the Amazon rainforest, and step-by-step hints. Students can type or speak their questions using the Web Speech API.

Example interaction:

Student: Why does the Moon have less gravity than Earth?

Yachay: Great question! Before I answer — what do you think determines how strong a planet's gravity is? Its size, its mass, or something else entirely? 🌿

🎯 Adaptive Practice with Elo

An Elo rating system (K=32) tracks performance per topic — Physics, Chemistry, Mathematics — and automatically adjusts difficulty. The formula used is:

$$E = \frac{1}{1 + 10^{(1000 - \text{Elo})/400}}$$

$$\text{Elo}{new} = \text{Elo}{old} + K \cdot (S - E)$$

Where $S = 1$ for a correct answer and $S = 0$ for incorrect.

⚔️ STEM Battle Mode

Students challenge friends in real-time 1v1 quiz battles via a 6-character room code. Both players answer the same questions simultaneously, with a 15-second timer per round. The system is built on Supabase Realtime for live synchronization.

🏆 Ranking, Achievements & Missions

  • Global ranking with live Elo scores, streak, XP, and country flags
  • 30 achievements across 4 categories (Physics, Chemistry, Practice, Social)
  • 4 daily missions generated by seeded PRNG — renewed at midnight
  • Monthly season challenge with exclusive badge and progress bar
  • Streak system with 6 milestones (🌱 → 🥉 → 🥈 → 🥇 → 🏅 → 💎)

📝 AI Exam Generator

Groq generates a personalized exam based on the student's current Elo level — questions, options, explanations, and a downloadable certificate of completion (PNG, generated with Canvas API).

🛠️ How we built it

The entire project is built with vanilla JavaScript, HTML5 and CSS3 — no framework, no build step, no npm. Just open index.html.

Physics Engine

All 17 simulators use the Canvas API with semi-implicit Euler integration. For projectile motion:

$$x(t) = x_0 + v_0 \cos(\theta) \cdot t$$ $$y(t) = y_0 + v_0 \sin(\theta) \cdot t - \frac{1}{2}gt^2$$

The simulation runs at 60 FPS via requestAnimationFrame, recalculating the particle position each frame based on the current slider values.

AI Integration

// Groq API call with Socratic system prompt
const res = await fetch('https://api.groq.com/openai/v1/chat/completions', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + GROQ_KEY },
  body: JSON.stringify({
    model: 'llama-3.3-70b-versatile',
    messages: [
      { role: 'system', content: SOCRATIC_PROMPT },
      ...conversationHistory
    ]
  })
});

The system prompt instructs LLaMA to use Amazonian analogies, never give direct answers, and ask one guiding question per response.

Guest Identity System

Guests get a unique, persistent identity without creating an account:

IP Address → ipapi.co → { city, country, flag, timezone }
IP + navigator.userAgent → SHA-256 (Web Crypto API) → guestId

This allows streak tracking, ranking, and progress persistence for students who can't or won't create an account.

Database

Supabase PostgreSQL stores:

  • profiles — Elo, XP, streak, sims, country
  • battles — real-time multiplayer state
  • achievements — unlocked badges per user
  • guest_sessions — geo data for anonymous users

Realtime channels sync battle state and rankings across devices.

Tech Stack Summary

Layer Technology
Frontend Vanilla JS, HTML5, CSS3
AI Groq API, LLaMA 3.3 70B
Physics Canvas API, Euler integration
Auth & ID Web Crypto API (SHA-256), ipapi.co
Voice Web Speech API (recognition + synthesis)
Database Supabase PostgreSQL + Realtime
Charts Chart.js (Elo progress)
Certificates Canvas API (PNG generation)
Hosting GitHub Pages

😤 Challenges we ran into

1. Physics accuracy on Canvas

Getting the pendulum simulation to match $T = 2\pi\sqrt{L/g}$ exactly required switching from simple Euler to semi-implicit Euler integration. The naive approach accumulated energy over time, making the pendulum gradually swing wider — physically wrong.

2. Real-time multiplayer without a backend

Implementing 1v1 battles that feel instantaneous without a traditional server was the biggest technical challenge. The solution was Supabase's Postgres-based Realtime channels: each answer is an upsert to the battles table, and both clients subscribe to changes via WebSocket.

3. Guest identity without cookies

Hashing the user's IP + user agent via SHA-256 gives a stable, persistent identifier that works across sessions — but it had to be done client-side using the Web Crypto API, which is asynchronous and required careful Promise chaining to not block the UI.

4. AI that teaches, doesn't tell

Tuning the Groq system prompt so Yachay genuinely uses the Socratic method — rather than just prefacing answers with a question — took many iterations. The key was explicitly forbidding direct answers and requiring the response to end with an open question.

5. Keeping it truly offline-capable

Making 17 simulators, the practice system, achievements, daily missions and the AI tutor all work without internet (using local fallbacks) while still syncing to Supabase when available required a careful "local-first, sync-when-online" architecture.

🏅 Accomplishments that we're proud of

  • 17 fully functional physics and chemistry simulators built from scratch with Canvas API — no physics library
  • A Socratic AI tutor that genuinely guides instead of answering, powered by one of the fastest inference APIs available (Groq)
  • Real-time multiplayer battles synchronized via Supabase Realtime across different devices and locations
  • Guest geo-identity system using SHA-256 fingerprinting — students in rural areas with no email can still have persistent progress
  • Statics I & II simulators — visualizing $\sum F = 0$ and $x_{cm} = \frac{\sum m_i x_i}{\sum m_i}$ interactively, which I haven't seen in any other free STEM tool
  • The entire project runs on vanilla JS with zero dependencies at runtime — it loads in under 2 seconds on a 3G connection
  • A complete gamification engine (Elo, achievements, daily missions, seasons, streak, ranking) built without any external library

📚 What we learned

  • Canvas API is powerful enough to build a complete physics engine — no Three.js or p5.js needed
  • Groq's inference speed (700+ tokens/second) makes real-time AI tutoring feel like a human conversation, not a loading spinner
  • The Socratic method is hard to implement in AI — you have to be very explicit in the system prompt about what the model is not allowed to do
  • Supabase Realtime with Postgres changes is a genuine alternative to Firebase for multiplayer games at this scale
  • Local-first architecture is the right default for education apps targeting low-connectivity regions — sync is a bonus, not a requirement
  • Building for accessibility-first (guest mode, no registration required, free, offline-capable) dramatically increases reach to underserved communities

🚀 What's next for Yachay Lab

Short term (next 30 days)

  • PWA with Service Worker — install Yachay Lab on mobile and use it completely offline, including AI responses cached from previous sessions
  • Classroom Mode — teachers create a class with a code, students join, and the teacher sees real-time progress on a dashboard
  • Biology simulators — cell division, DNA replication, ecosystem simulations

Medium term

  • Adaptive curriculum — Yachay AI generates a personalized weekly study plan based on Elo performance across topics
  • Video explanations — short 60-second AI-narrated videos for each concept, generated on demand
  • Regional partnerships — collaborate with Peruvian and Bolivian education ministries to integrate Yachay Lab into official curricula

Long term vision

Yachay Lab aims to become the free Khan Academy of Latin American STEM — but interactive, AI-powered, and built for students who have a phone but no lab, a teacher but no equipment, a desire to learn but no resources.

The name says it all. Yachay — to learn. For everyone. Everywhere.

Built With

Share this project:

Updates