{"id":51247269,"url":"https://github.com/docxology/active-inference-pocket-lab","last_synced_at":"2026-06-29T05:03:36.527Z","repository":{"id":351903902,"uuid":"1187509919","full_name":"docxology/active-inference-pocket-lab","owner":"docxology","description":"Active Inference Pocket Lab — portable simulation and learning environment for Active Inference experiments","archived":false,"fork":false,"pushed_at":"2026-04-18T21:12:51.000Z","size":598,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T02:27:45.355Z","etag":null,"topics":["active-inference","bayesian-modeling","education","pocket-lab","python","research","simulation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docxology.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-20T20:09:58.000Z","updated_at":"2026-04-18T21:12:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/docxology/active-inference-pocket-lab","commit_stats":null,"previous_names":["docxology/active-inference-pocket-lab"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/docxology/active-inference-pocket-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Factive-inference-pocket-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Factive-inference-pocket-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Factive-inference-pocket-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Factive-inference-pocket-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docxology","download_url":"https://codeload.github.com/docxology/active-inference-pocket-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Factive-inference-pocket-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34913587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["active-inference","bayesian-modeling","education","pocket-lab","python","research","simulation"],"created_at":"2026-06-29T05:03:36.000Z","updated_at":"2026-06-29T05:03:36.519Z","avatar_url":"https://github.com/docxology.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spin — The Active Inference Pocket Lab\n\n\u003e \"You are an architect of a world in formation.\"\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## Overview\n\n**Spin** is a mobile-first, browser-based interactive laboratory for learning [Active Inference](https://en.wikipedia.org/wiki/Free_energy_principle#Active_inference). It transforms the 10 chapters of *Active Inference: The Free Energy Principle in Mind, Brain, and Behavior* (Parr, Pezzulo \u0026 Friston, MIT Press 2022) into hands-on learning modules with three parallel experience streams.\n\n### Genesis\n\nThis project grew from a single creative brief — [**The Seed**](doc/initial-pocket-lab-prompt.md) — which defines the constitutional narrative, the core philosophy, the Triple-Stream Architecture, and the mandate for Module 1. Every design token, animation curve, and interaction pattern in this codebase traces back to that document. It is preserved exactly as-written in `doc/initial-pocket-lab-prompt.md`. For the full documentation suite, see [**doc/**](doc/README.md).\n\n### The Triple-Stream Architecture (\"The Helix\")\n\nEach module offers three learning paths that users can switch between at any time:\n\n| Stream | Audience | Focus |\n|--------|----------|-------|\n| 💓 **Pulse** | Enthusiast | Conversational language, 2-minute micro-inferences, high-school math |\n| ✨ **Vision** | Artist | Interactive animations, generative art, \"Variable Hearth\" sliders |\n| 🔬 **Core** | Academic | Clean LaTeX equations, sandbox environments, derivation steps |\n\n### Core Philosophy\n\n- **Aggressive Generosity**: Large touch targets, breathable typography, never worship information density\n- **The Physics of the Drawer**: No teleporting — use sliders and drawers for spatial reality\n- **Seasonal Rhythms**: Activity Banking, planned pauses, hibernate mode — no penalties for rest\n- **The First Threshold**: Every module starts with a physical action (slider, drag, or tilt)\n- **The Hearth**: Replace leaderboards with warmth, clarity badges, and \"Good Questions\"\n- **Visible Pathing**: Proficiency maps showing exactly what's required — no hidden gates\n\n### Learner experience (design commitments)\n\n- **Triple streams**: Pulse, Vision, and Core run in parallel; learners switch anytime without losing place.\n- **Legible knowledge**: Each module pulls **terms** and **retrieval questions** from [`src/data/modules.js`](src/data/modules.js) — glossary deep links (`/glossary#key`) and a short **Core quiz** at the end make uncertainty and recall explicit, not hidden.\n- **Warm feedback**: Quizzes are framed as retrieval (no timers, generous explanations); motion and haptics reward participation, not speed.\n- **Installable shell**: PWA assets live under [`public/`](public/) (`manifest.webmanifest`, `sw.js`); Settings includes reduced motion, haptics, and font scale.\n\n## The 10 Modules\n\n| # | Title | Chapter Basis |\n|---|-------|---------------|\n| 1 | 🌀 The First Orbit | Overview / Introduction |\n| 2 | 🛤️ The Low Road | The Low Road to Active Inference |\n| 3 | 🏔️ The High Road | The High Road to Active Inference |\n| 4 | 🏛️ The Generative Architecture | Generative Models |\n| 5 | 🧠 Message Passing | Message Passing \u0026 Neurobiology |\n| 6 | 📐 A Recipe for Designing Models | A Recipe for Designing Models |\n| 7 | 🎲 Discrete Worlds | Active Inference in Discrete Time |\n| 8 | 🌊 Continuous Flow | Active Inference in Continuous Time |\n| 9 | 📊 Model-Based Data Analysis | Model-Based Data Analysis |\n| 10 | 🌐 The Whole Orbit | A Broader View |\n\nAll **10 modules** ship **Pulse**, **Vision**, and **Core** streams (`src/modules/module1` … `module10`), lazy-loaded from [`ModulePage.jsx`](src/pages/ModulePage.jsx) and marked available in [`src/data/modules.js`](src/data/modules.js).\n\n## Quick Start\n\n### One Command\n\n```bash\n./run.sh         # Install deps → run tests → start dev server\n```\n\nOr use individual commands:\n\n```bash\n./run.sh dev     # Start dev server only (skip tests)\n./run.sh test    # Run tests only\n./run.sh build   # Production build\n./run.sh preview # Build + preview production\n./run.sh lint    # Run linter + formatter\n./run.sh clean   # Remove node_modules and dist\n./run.sh help    # Show all commands\n```\n\n### Manual Setup\n\n```bash\nnpm install\nnpm run dev      # → http://localhost:5173 (mobile viewport recommended)\nnpm test         # Run all tests (65 tests, 11 files — registry, bundles, UI)\nnpm run build    # Production build\n```\n\n## Project Architecture\n\n```\npublic/                 # PWA: manifest.webmanifest, sw.js, icons, _redirects\nsrc/\n├── components/\n│   ├── interactive/    # InferenceSlider, MathBlock, interactives, Quiz, …\n│   └── layout/         # AppShell, TopBar, BottomNav, StreamSwitcher, …\n├── contexts/           # AppContext, ActivityBankContext, SettingsContext\n├── data/               # Module registry, glossary, badges\n├── modules/\n│   ├── module1/ … module10/   # PulseStream, VisionStream, CoreStream per module\n│   └── shared/         # useStreamProgress, glossary line, Core retrieval helpers\n├── pages/              # Home, modules, glossary, search, settings, …\n├── styles/             # Design tokens + global CSS\n├── utils/              # Shared helpers (e.g. activeInference)\n└── test/               # Vitest setup\n```\n\n### Key Design Decisions\n\n- **React + Vite** for fast dev iteration and mobile-optimized builds\n- **Framer Motion** for physics-based spring animations (drawer, stream switcher, rewards)\n- **KaTeX** for client-side LaTeX rendering in the Core stream\n- **CSS Custom Properties** design token system (no utility-class framework)\n- **Context + useReducer** for state management (no external state library needed)\n- **LocalStorage** persistence for Activity Banking (bookmark, sessions, streaks)\n\n## Tech Stack\n\n- **Framework**: React 19 + Vite 8\n- **Routing**: React Router v7\n- **Animation**: Framer Motion\n- **Math**: KaTeX\n- **Testing**: Vitest + Testing Library\n- **Linting**: ESLint + Prettier\n\n## TODO\n\n- [x] Triple-stream implementations for modules 1–10\n- [x] PWA manifest and service worker (`public/`)\n- [ ] Offline storage with IndexedDB (beyond installable shell)\n- [ ] Server-synced progress (when backend is ready)\n- [ ] Hearth social features (shared questions, group streaks)\n- [ ] Full accessibility pass (screen reader + keyboard run-through; track in releases)\n- [ ] Performance profiling for canvas animations\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT — See [LICENSE](LICENSE) for details.\n\n## References\n\n- Parr, T., Pezzulo, G., \u0026 Friston, K. J. (2022). *Active Inference: The Free Energy Principle in Mind, Brain, and Behavior*. MIT Press.\n- [Active Inference Institute](https://www.activeinference.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocxology%2Factive-inference-pocket-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocxology%2Factive-inference-pocket-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocxology%2Factive-inference-pocket-lab/lists"}