Perception Learning

Live demo · Education track · Persistent, source-linked learning

Perception Learning is a curriculum-linked science workspace that makes invisible reasoning observable. It combines a book-like OpenStax library, age-adjusted guided readings, saved field notes, teacher lesson controls, and interactive evidence labs. Learners commit a forecast before seeing a model, run a controlled experiment, and revise their explanation from the evidence. Teachers receive that sequence as a continuous evidence trail and can respond with one bounded instructional move.

The differentiator is the feedback loop, not a generic AI chat box:

teacher assignment → learner forecast → parameter changes → evidence run → completion
        ↑                                                                      │
        └──────────── delivered teacher response ← bounded evidence brief ─────┘

The application starts with an intentionally empty classroom—no seeded learners, fabricated activity, or manufactured analytics. A learner can join with a real class code, receive an assignment, open the exact book section or lab, contribute learning evidence, and receive teacher guidance. Learner-note excerpts are private by default and require explicit opt-in.

What actually saves

Cloudflare is deployment plumbing, not a product feature. In the interface, learners and teachers see plain Saving, Saved, Online, and useful recovery messages—not vendor terminology.

• Notes, generated study questions inserted into notes, Field Check results, guided-lesson stage, forecasts, hints, lab trials, best scores, explanations, and mastery receipts persist to the database.
• Classes begin empty. Learners appear only after joining with the real class code; assignments, progress, and teacher insight are derived only from persisted actions.
• Teacher assignments, opened/completed status, evidence events, and delivered responses persist and restore after reload.
• Pomodoro state, focus settings, and the learner's music choice persist on that browser. Spotify is opt-in and loads only after the learner selects it.
• A fresh database intentionally shows useful empty states. There is no seeded roster, fake progress, manufactured analytics, or pre-awarded achievement data.

The current hackathon identity model uses anonymous role-bound browser sessions rather than district accounts. That makes the complete demo loop real and persistent, but production use with minors still requires district identity, consent, retention, and student-data review as described in PRIVACY.md.

The deployed implementation keeps its backend on one provider:

• Cloudflare Workers serves the React application and API.
• Cloudflare Workers AI creates learning specifications, simulation code, and debriefs.
• Cloudflare D1 stores anonymous experiment history, section notes, lesson and lab progress, teacher plans, role-bound classroom sessions, assignments, evidence events, and delivered interventions.
• Cloudflare’s Vite plugin builds and serves the Worker and static assets as one application.
• No external API keys, SaaS databases, hosted fonts, analytics, or non-Cloudflare runtime services are required.

Learning loop

1. Believe — state what you think is true.
2. Forecast — commit to an outcome, confidence level, and drawn trace before the model runs.
3. Evidence — overlay the forecast and simulated result, inspect their largest divergence, and run counterfactuals.
4. Update — explain the missing mechanism, write a revised mental model, and save the before → after transition.

The app includes three fully working reference experiments—trophic cascades, compound growth, and pendulum length—so the whole loop remains available in deterministic reference mode when Workers AI is unavailable or intentionally disabled. The learning trail stores forecast traces, confidence, run counts, evidence summaries, and the learner’s revised model in D1.

Curriculum workspace

• OpenStax shelf — 18 guided sections across Physics, Biology 2e, Chemistry 2e, Anatomy & Physiology 2e, and Learning AI are organized as tactile book covers with direct links to each official source.
• Layered reader — each guided section has simpler, core, and deeper authored explanations, optional browser read-aloud, key vocabulary, misconceptions, source attribution, and a proof desk.
• Field notebook — learners save questions, observations, equations, and model updates beside the section that produced them. Notes persist in D1 and remain searchable.
• Teacher studio — teachers choose an age band, lesson sequence, duration, accommodations, student groups, and visualization mode. A model-review checklist gates presentation, and progress insights come from actual saved experiment records on the classroom device.
• Live classroom loop — teachers copy a class code, learners join from the Class tab, assignments arrive in an action-first Today queue, and the correct OpenStax lesson or simulation opens directly. A matching simulation run or Field Check automatically returns completion evidence to the learner and teacher; opened, completed, and not-started counts reconcile in the assignment ledger.
• Insight dashboard — every metric begins with a persisted learner action. Teachers can inspect a chronological trace, see private-vs-shared note state, generate a bounded evidence brief, and deliver a nudge or next-lesson move back to the learner. The brief explicitly avoids diagnoses and automated grades.
• Source-linked guided investigation — OpenStax Physics §9.2 places the exact official source beside a one-interaction-at-a-time guide. Learners predict first, compare a pinned smooth-track baseline with a friction run, receive graduated misconception-specific hints, explain the transfer, pass unscaffolded retrieval, revise their belief, and return the complete evidence trail to the teacher.
• 3D evidence mission — the complete launch demo aligns to OpenStax Physics §5.5. Learners compare two deterministic pendulums, change one variable at a time, inspect the model boundary above 15°, and earn evidence points for testing a forecast rather than maintaining a superficial streak.
• Multi-book evidence labs — Biology 2e §46.2 follows compounding energy loss through four trophic levels; Chemistry 2e §7.6 compares electron geometry with the molecular shape left after lone pairs are hidden; Anatomy & Physiology 2e §3.2 traces protein cargo from rough ER through Golgi and vesicles to the membrane. Each lab has forecast-first controls, adjustable parameters, repeatable evidence, keyboard and touch support, and a direct OpenStax source.
• Learning AI course — five source-linked lessons progress from data and generalization through classification, neural-network intuition, tokens/embeddings/context, and responsible evaluation. Each uses a deterministic manipulable model instead of turning the lesson into a generic chatbot.
• Restorable lab work — all curriculum labs save the learner's latest prediction, parameter, observed outcome, evidence, trial count, and non-regressing best score. Returning to the same lab restores the completed run.

The application does not ingest whole textbooks into a generative model. Its guided copy is original product-authored material with section-level attribution and official source links. Workers AI receives the small learning specification needed to create a model. This keeps the lesson auditable and respects the additional reuse and AI restrictions attached to some OpenStax titles.

Architecture

React + Vite
    │
    ├── /api/spec ─────────── Cloudflare Workers AI
    ├── /api/generate-sim ─── Cloudflare Workers AI
    ├── /api/debrief ──────── Cloudflare Workers AI
    ├── /api/experiments ──── Cloudflare D1
    ├── /api/notes ────────── Cloudflare D1
    ├── /api/teacher-plan ─── Cloudflare D1
    ├── /api/guided-lessons ─ Workers AI → schema validator → D1
    ├── /api/guided-progress  Cloudflare D1
    ├── /api/curriculum-progress  Cloudflare D1
    ├── /api/classrooms/* ─── Cloudflare D1
    ├── /api/assignments ──── Cloudflare D1
    └── /api/learning-events  Cloudflare D1
                                  │
generated MODEL source ── validated ── CSP-sandboxed iframe ── forecast/evidence overlay

Workers AI is accessed only through the Worker’s AI binding. The model identifiers in worker/ai.ts refer to models hosted behind Cloudflare Workers AI; the browser never contacts a model vendor and the project does not contain a third-party AI key.

Generated simulations must satisfy one small deterministic contract: a MODEL object with metadata, parameters, a step count, and init, step, and readout functions. Source validation rejects networking, imports, storage, DOM access, randomness, clocks, workers, and prototype access. Validated source then runs in an iframe with sandbox="allow-scripts" and a default-src 'none' content security policy.

Local development

Use Node.js 22 or 24 and a Cloudflare account authenticated with Wrangler.

npm install
npm run dev

Open http://127.0.0.1:5173.

npm run dev applies pending local D1 migrations automatically and uses wrangler.offline.jsonc. It still runs the real Cloudflare Worker and local D1 database, but selects the built-in reference experiments and consumes no Workers AI quota.

Judge-ready local walkthrough

1. Open Teach. Copy the class code from the dashboard.
2. Open Class, join as a learner with that code, then return to Teach.
3. Choose Assign learning. The composer targets only learners who actually joined the class.
4. Assign Physics 9.2 · Mechanical energy, return to Class, and start it. The official source opens beside the guided investigation.
5. Return to Teach, open the live learner trace, and send a nudge.
6. Complete the evidence run, then return to Class to see the assignment under Evidence returned. Open Teach to verify the opened/completed funnel and send a nudge.

An empty class is expected on a fresh database. The dashboard explains how to add the first learner instead of inventing a success state.

For live Workers AI during development:

npm run dev:ai

Cloudflare remote development requires Workers onboarding to be complete for the account, including a workers.dev subdomain. No .env API token is needed for AI.

Verification

npm run check

That command:

• regenerates Cloudflare binding types;
• type-checks the React app, Worker, evaluator, and tests;
• runs Worker integration tests inside Cloudflare’s Vitest/Miniflare environment;
• applies the real D1 migration in the test runtime;
• verifies all reference simulations are deterministic and produce their intended qualitative outcomes;
• verifies every published curriculum section reaches a teacher-reviewed interactive lab, including configured parameter boundaries;
• runs the offline evaluation harness;
• creates the production build.

To evaluate the running app through its HTTP API:

npm run dev
# in another terminal
npm run eval

Set PERCEPTION_EVAL_BASE if the app is running at a different origin.

Deploy to Cloudflare

1. Authenticate and complete Workers onboarding:

   npx wrangler login
   npx wrangler whoami

2. Apply the D1 schema:

   npm run db:migrate:remote

3. Deploy the Worker, static assets, Workers AI binding, and D1 binding:

   npm run deploy

The Wrangler configuration can automatically provision the named D1 database on the first deploy. If the first request to experiment history arrives before the migration is applied, the API returns a clear migration-required response instead of failing silently.

Cloudflare publishes current Workers AI included usage and pricing on its official pricing page. The application’s deterministic reference mode is also suitable for demos where zero AI usage is preferred.

Useful commands

Command	Purpose
npm run dev	Local Worker + D1 in deterministic reference mode
npm run dev:ai	Local UI with remote Cloudflare Workers AI
npm run test	Worker, D1, security, and simulation tests
npm run test:e2e	Full desktop and mobile learner/teacher browser suite
npm run eval:offline	Qualitative checks for built-in experiments
npm run eval	Exercise the running HTTP pipeline
npm run build	Type-check and create the production bundle
npm run deploy	Build and deploy to Cloudflare
npm run db:migrate:remote	Apply production D1 migrations

OpenAI Build Week

Perception Learning is an Education track project built through an iterative Codex workflow for OpenAI Build Week. GPT‑5.6 and Codex accelerated the parts that required the most cross-domain reasoning:

• translating the product thesis—make learner reasoning observable—into a complete teacher/learner information architecture;
• mapping multiple OpenStax science sections into forecast-first deterministic models rather than generic generated quizzes;
• building and validating the sandboxed simulation contract and scientific evaluation cases;
• implementing the Cloudflare Worker, Workers AI boundaries, D1 schema, migrations, classroom delivery loop, and integration tests;
• performing a harsh product audit, then using the findings to replace simulated delivery with role-aware sessions, real join codes, learner inboxes, privacy defaults, and responsive browser QA;
• refining the warm field-guide visual system and restrained glass instruments across desktop and mobile.

Key product decisions made during the Codex build:

1. AI proposes; deterministic code proves. Simulations run a validated, inspectable model contract instead of asking a language model for scientific outputs at runtime.
2. Evidence over surveillance. Teachers see learning actions, explicit stuck signals, and optionally shared note excerpts—not diagnoses or automatic grades.
3. A complete loop beats a broad feature list. An assignment must reach a learner, open the intended activity, return evidence, and receive a delivered response.
4. Cloudflare remains the runtime. Workers, Workers AI, D1, static assets, logs, and deployment stay in one platform; OpenAI is the Build Week development workflow, not an unnecessary production dependency.

See DEMO_SCRIPT.md for a sub-three-minute recording plan and SUBMISSION_CHECKLIST.md for the remaining Devpost-owned steps, including the public repository/demo URL, YouTube upload, and /feedback session ID.

Project map

src/                    React interface and client-side state machine
worker/                 Cloudflare Worker API, Workers AI calls, prompts
shared/                 Simulation contract, types, reference experiments
migrations/             D1 schema
test/                   Cloudflare Worker and simulation integration tests
eval/                   Offline and live qualitative evaluation harness
docs/design/            Accepted visual direction used for implementation
public/_headers         Production security headers
wrangler.jsonc          Worker, assets, AI, D1, and observability configuration
wrangler.offline.jsonc  Local Cloudflare runtime without a remote AI binding

The source code is MIT licensed. OpenStax books remain governed by their own licenses and are linked and attributed at the section level; this repository does not relicense OpenStax content. Before use with real minors, read PRIVACY.md: the hackathon build uses anonymous browser sessions and is not a replacement for district identity, consent, retention, or student-data review.

The current design system and product art direction are documented in DESIGN.md. The earlier accepted concept remains in docs/design/perception-learning-redesign-concept.png.