Data Learning Apps

Data Learning Apps is a collection of interactive demos that explain technical concepts through visuals and exploration. Each app lives under apps/<app_slug>/ and may use different frameworks such as Streamlit, Dash, or custom frontends. The shared goal is to make certain systems or methods more intuitive, by letting people poke at them directly. App-specific setup notes live in each app’s README.md, while testing instructions are documented in apps/<app_slug>/tests/TESTS.md.

Design documents

Every app includes a DESIGN.md that outlines the functional goals of the experience: what the demo teaches, how the content is structured, and how interactive elements guide the learning journey. Draft or update the design document before changing an app so the educational story is settled first. A reusable template is available at DESIGN_TEMPLATE.md in the project root.

Available apps

• Gradient Descent Explorer (apps/gradient_descent/): Tune learning-rate controls and visualize how gradient descent optimizes a linear regression model. See apps/gradient_descent/README.md for run commands and tests.
• Fuzzy Inverted Index Explorer (apps/fuzzy_inverted_index/): Learn how n-gram fragmentation turns an inverted index into a fuzzy search engine with scoring explanations. See apps/fuzzy_inverted_index/README.md for details.

Getting started

1. Install Python 3.10+.

2. Create and activate a virtual environment.

3. Install Python dependencies:

   pip install -r requirements.txt

Development workflow

• Review the relevant app’s DESIGN.md before making changes to keep the learning story aligned with the implementation.
• Keep each app self-contained with its own README.md, DESIGN.md, tests/TESTS.md, and any framework-specific notes.
• Run the commands listed in tests/TESTS.md and the app’s own tests/TESTS.md before wrapping up changes.
• Automation- or AI-specific guidelines for working in this repository live in AGENTS.md (root and per-app).

Creating new apps

1. Create a new directory under apps/ (for example, apps/new_concept/).
2. Copy DESIGN_TEMPLATE.md to apps/new_concept/DESIGN.md and complete it to describe the learning experience. Iterate on the design until it is approved.
3. Add any framework-specific instructions to apps/new_concept/AGENTS.md.
4. Build the app according to the approved design document.
5. Provide automated checks and document them in apps/new_concept/tests/TESTS.md.
6. Add an apps/new_concept/README.md describing the experience and run instructions.
7. Update the root README.md and tests/TESTS.md to reference the new app.