Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
5d3fffa
perf(radar): refresh other students' flags once a minute
k086-cloud Nov 15, 2026
6b4371f
Merge pull request #62 from k086-cloud/perf/radar-cache-60s
k086-cloud Nov 15, 2026
b70dd39
Fix mobile Pilot overlap, review navigation and demo contrast
TraSh9178 Nov 15, 2026
7fbd193
docs(readme): describe the features added for STEMergent Hacks
k086-cloud Nov 15, 2026
a7aa7c3
Match desktop practice to the paper worksheet reference
TraSh9178 Nov 15, 2026
7f0a0a4
Merge pull request #63 from TraSh9178/codex/paper-ui-acceptance-fixes
k086-cloud Nov 15, 2026
53efd62
Merge pull request #65 from TraSh9178/codex/desktop-paper-worksheet
k086-cloud Nov 15, 2026
c2164f3
fix(i18n): preserve language across page widget cleanup
mormal1016 Nov 15, 2026
8a84322
Use one-click choices and hide storage details on student pages
k086-cloud Nov 15, 2026
291e563
Merge pull request #66 from TraSh9178/codex/paper-ui-acceptance-fixes
k086-cloud Nov 15, 2026
eb42447
Merge branch 'feat/paper-ui-pages' into feat/paper-ui
k086-cloud Nov 15, 2026
ad8a423
Add Learning Radar spider chart, one-click stuck buttons and radar page
k086-cloud Nov 15, 2026
5c4c4d9
Merge branch 'feat/paper-ui-radar' into feat/paper-ui
k086-cloud Nov 15, 2026
a33c508
Do not block saves after restoring a course with nothing saved
k086-cloud Nov 15, 2026
bdc6ea7
Keep the Dashboard save-failure warning across the rerun
k086-cloud Nov 15, 2026
dfffa4d
Keep saved question decisions when a stale session saves pending
k086-cloud Nov 15, 2026
3b15a34
Keep the app running when a built-in course update fails
k086-cloud Nov 15, 2026
cf0a8d1
Parse accessibility data files once instead of for every string
k086-cloud Nov 15, 2026
0bb0274
Replace the top header row with a collapsible paper sidebar
k086-cloud Nov 15, 2026
d27ac73
Merge branch 'feat/paper-ui-shell' into feat/paper-ui
k086-cloud Nov 15, 2026
05bfd9d
test(graph): ignore the injected stylesheet when reading page text
k086-cloud Nov 15, 2026
0a7612d
Translate remaining English strings in the Chinese interface
k086-cloud Nov 15, 2026
6423537
Merge branch 'fix/known-defects' into feat/paper-ui
k086-cloud Nov 15, 2026
7bfb8dd
Paper practice page: question card, one-click choices and clean wording
k086-cloud Nov 15, 2026
3f4c476
Merge branch 'feat/paper-ui-practice' into feat/paper-ui
k086-cloud Nov 15, 2026
eb1564f
test(practice): ignore the injected stylesheet when reading page text
k086-cloud Nov 15, 2026
2bae835
Merge pull request #67 from TraSh9178/fix/language-navigation
mormal1016 Nov 15, 2026
e7cb2e5
Merge remote-tracking branch 'upstream/main' into feat/paper-ui
k086-cloud Nov 15, 2026
202137d
test(shell): follow the language toggle's new widget key
k086-cloud Nov 15, 2026
955678b
perf(ui): ship the illustrations as WebP
k086-cloud Nov 15, 2026
70f422c
style(ui): quieter Create course card; one sample-data note in the pr…
k086-cloud Nov 15, 2026
b42aa5f
fix: address the review findings on the paper UI branch
k086-cloud Nov 15, 2026
099e03e
Merge pull request #68 from k086-cloud/feat/paper-ui
k086-cloud Nov 15, 2026
e82f3b2
Merge pull request #64 from k086-cloud/docs/readme-stemergent
k086-cloud Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions .streamlit/config.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,19 @@
[theme]
base = "light"
primaryColor = "#3C6483"
backgroundColor = "#F8F4EA"
secondaryBackgroundColor = "#FFFCF6"
textColor = "#24354A"
# Paper theme; the full palette lives in assets/paper_shell.css.
# Primary is --accent-blue-dark so text drawn in it (tabs, links) keeps 4.5:1.
primaryColor = "#4A6C8A"
backgroundColor = "#FEF7EF"
secondaryBackgroundColor = "#FAF3E9"
textColor = "#2A2F33"
linkColor = "#4A6C8A"
borderColor = "#EEE7DF"
showSidebarBorder = false
baseRadius = "0.875rem"
buttonRadius = "full"
font = "sans serif"

[theme.sidebar]
backgroundColor = "#FEF7EF"
secondaryBackgroundColor = "#FAF3E9"
textColor = "#2A2F33"
66 changes: 49 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,20 @@ Turn course materials into focused exam practice.

ExamPilot is a Streamlit learning platform that combines document extraction, AI-assisted course preparation, practice exams, progress tracking, and an interactive knowledge map.

Built for HackRU Fall 2026.
Built for HackRU Fall 2026 and extended in November 2026 for STEMergent Hacks.

**Live demo:** https://exampilot-jl9eqsvbgoyedczbroxrzu.streamlit.app/ — register any account and try the built-in demo courses. AI generation is turned off on the public demo.

## Added for STEMergent Hacks (November 2026)

- **Step hints:** In Topic Practice, a question can reveal up to three hints, one at a time. The number of hints shown is saved with the result and appears in answer review. The 15 original demo questions have hints, and Claude is asked to write them for generated questions.
- **Concept Lab:** Interactive Calculus I experiments for limits, derivatives (secant to tangent), and the corner of |x| at 0, where the function is continuous but not differentiable. Each follows predict, explore, and explain steps; predictions never create grades or mastery evidence. See [Guided Concept Lab](docs/guided_concept_lab.md).
- **Learning Radar:** On the Knowledge Map of the three demo courses, a student can mark a topic "I'm stuck here", optionally with a reason (concept unclear, calculation errors, can't understand the question, or don't know where to start). The Knowledge Map shows how many students are stuck on each flagged topic, and Study Plan lists the three most-flagged topics with a practice shortcut. Counts add real flags to sample data from `data/radar_sample.json`; where sample data is included, the count is labelled "Includes sample data". A topic with no sample data shows "Some students flagged this" instead of a number until it has at least three real flags.
- **Accessibility and language:** A Simplified English toggle shows plainer wording for the 15 original demo questions. A Chinese interface toggle translates most interface text and adds Chinese translations after key terms in practice questions; uploaded material and AI-generated answers keep their original language.
- **Learning DNA and practice insights:** During practice, students can record their confidence and see a review-before-submit check. After grading, results show estimated focus time and hint use, accept a written reflection on any question, with an optional reason for each missed one, and offer a smart review list. Learning DNA separates each topic's computation and conceptual evidence. See [Learning DNA](docs/learning_dna.md) and [Practice insights and reflection](docs/practice_insights.md).
- **Guided Limits review:** After a student misses the Calculus I demo's factorisation limit question in Topic Practice, the result page asks where they got stuck, walks through the factoring step, and checks a new follow-up limit question. If they pick one of the two specific reasons, they can also share it anonymously with Learning Radar. The Dashboard's Try one question card can start this question.
- **Larger demo question banks:** Each demo now has at least 30 questions, and Calculus I grows to 15 topics, 66 questions and 20 relationships. The added questions are drafts pending review (see [Demo Courses](#demo-courses)). See [Calculus knowledge expansion](docs/calculus_knowledge_expansion.md) and [Demo question bank expansion](docs/demo_question_bank.md).

## Screenshots

| Dashboard | Study Plan |
Expand All @@ -22,13 +32,17 @@ Built for HackRU Fall 2026.

- **Course materials:** Extract text from UTF-8 TXT, text-based PDF and PPTX, and PNG/JPG/JPEG images.
- **AI-assisted preparation:** Generate candidate topics and multiple-choice questions with Claude, then confirm the topics to practise.
- **Practice:** Take Mock Exams or Topic Practice sessions with scoring, answer review, and explanations.
- **Progress:** Track results and topic mastery separately for each course and practice mode.
- **Knowledge Map:** Explore topic relationships, inspect topic details, view mastery colours, and ask Claude to suggest connections from your saved material (applied only after you review them).
- **Practice:** Take Mock Exams or Topic Practice sessions with scoring, answer review, and explanations. Topic Practice offers step hints; results add practice insights, a smart review list, and written reflections.
- **Progress:** Track results and topic mastery separately for each course and practice mode, with a Learning DNA profile of computation and conceptual evidence.
- **Knowledge Map:** Explore topic relationships, inspect topic details, view mastery colours, and ask Claude to suggest connections from your saved material (applied only after you review them). On the demo courses, Learning Radar shows where students are stuck.
- **Concept Lab:** Explore limits, derivatives, and differentiability in interactive Calculus I experiments.
- **Accessibility and language:** Simplified English wording for the original demo questions, and a Chinese interface that also translates key terms in questions.
- **Anki export:** Preview cards and download all questions or questions from weak/developing topics as UTF-8 TSV.
- **Accounts and persistence:** Register, log in, and save or restore courses and graded practice records through PostgreSQL.
- **Pilot assistant:** Ask course-related questions through a draggable floating assistant.

The features added in November 2026 are described in more detail under [Added for STEMergent Hacks](#added-for-stemergent-hacks-november-2026).

AI-generated topics, questions, answers, explanations, and relationships require human review.

## Demo Courses
Expand All @@ -37,9 +51,11 @@ Three built-in courses provide practice content without requiring AI generation:

| Course | Topics | Questions | Relationships |
|---|---:|---:|---:|
| Introduction to Microeconomics | 3 | 3 | 2 |
| Calculus I | 3 | 3 | 2 |
| Python Basics | 3 | 9 | 0 |
| Introduction to Microeconomics | 3 | 30 | 2 |
| Calculus I | 15 | 66 | 20 |
| Python Basics | 3 | 30 | 0 |

The questions added in November 2026 (27, 63, and 21 respectively) are drafts marked pending review. They are excluded from practice until approved in Study Plan, so the questions available for practice out of the box are 3, 3, and 9.

Demo content does not require a Claude API key. The normal application still requires a working account database to register or log in.

Expand Down Expand Up @@ -192,23 +208,25 @@ See [document processing and Claude usage](docs/claude_usage.md) for supported f
2. Open a built-in Demo or create a course from uploaded materials.
3. Extract and review the text.
4. Generate candidate topics when using your own materials.
5. Review the topics and explicitly confirm the exam scope.
6. Generate questions if needed, then start Mock Exam or Topic Practice.
7. Submit answers and review the score and explanations.
8. Inspect Progress and Knowledge Map.
9. Preview or download Anki cards for further review.
5. Review the topics and explicitly confirm the exam scope. Approve any pending questions you want to practise.
6. Generate questions if needed, then start Mock Exam or Topic Practice. In Topic Practice, reveal hints one at a time if you get stuck.
7. Submit answers and review the score, explanations, practice insights, and smart review list; reflect on missed questions.
8. Try the Calculus I limits, derivatives, and corner experiments in Concept Lab.
9. Inspect Progress (including Learning DNA) and Knowledge Map. On a demo course, mark a topic "I'm stuck here" if it is giving you trouble.
10. Preview or download Anki cards for further review.

Pilot is available after login. It uses the selected course's topic summaries and relationships; open a course before asking a question.

## Data Persistence and Privacy

### Saved to PostgreSQL

- Course packages
- Course packages, including their learning state: confirmed exam scope, question review decisions, extracted material text (not the original files), practice order, and practice insights such as confidence, hints shown, tracked focus time, and reflections
- Exam sessions
- Submitted answer results
- Learning Radar flags: account ID, course ID, topic ID, an optional reason, and when the flag was created (table `radar_flags`, created by [`db/migrations/003_learning_radar.sql`](db/migrations/003_learning_radar.sql))

Database operations use the authenticated account's server-side user ID. Course records are scoped by account.
Database operations use the authenticated account's server-side user ID. Course records are scoped by account. Learning Radar shows other students only per-topic and per-reason totals, not who flagged a topic.

On login, the application discovers saved courses and restores their histories. Topic statistics and mastery are recalculated from the restored records.

Expand All @@ -220,10 +238,12 @@ Saving and restoring require a working database connection. A successful local g
- Pilot conversations and input drafts
- Account avatars
- Uploaded document previews
- Unfinished practice sessions set aside when you start a new one
- Accessibility and interface-language settings

Pilot conversations and avatars are not restored from PostgreSQL or synchronised across devices.

Signing out clears the current session. Saved learning records can be restored after signing in again; unsaved records do not have that guarantee.
Signing out clears the current session; only the interface-language choice is kept. Saved learning records can be restored after signing in again; unsaved records do not have that guarantee.

### Restore conflicts

Expand Down Expand Up @@ -271,12 +291,12 @@ These labels summarise recorded practice performance; they are not a formal asse

```text
app.py Application entry point and authentication guard
pages/ Dashboard, study, practice, progress, graph, and Anki
pages/ Dashboard, study, practice, progress, graph, Concept Lab, and Anki
services/ AI, extraction, authentication, persistence, and engines
models/schemas.py Shared Pydantic data models
components/ Interactive knowledge-map components
assets/ UI styles, illustrations, and Pilot frontend assets
data/ Built-in Demo course packages
data/ Built-in Demo course packages, hints, simplified wording, Chinese key terms, and Radar sample data
db/ Learning-data and account SQL schemas
tests/ Automated tests
docs/ Setup guides, contracts, and development records
Expand Down Expand Up @@ -331,5 +351,17 @@ Record the exact commit and environment when reporting real integration results.
- [Testing on another computer](docs/other_computer_testing.md)
- [Floating Pilot assistant](docs/floating_tutor.md)
- [Shared UI typography](docs/ui_typography.md)
- [Guided Concept Lab](docs/guided_concept_lab.md)
- [Learning DNA](docs/learning_dna.md)
- [Practice insights and reflection](docs/practice_insights.md)
- [Calculus knowledge expansion](docs/calculus_knowledge_expansion.md)
- [Demo question bank expansion](docs/demo_question_bank.md)
- [Shared built-in examples](docs/shared_demo_catalog.md)
- [Learning flow UX](docs/learning_flow_ux.md)
- [Student-facing detail audit](docs/student_facing_details.md)
- [Question quality and mistake review](docs/question_quality_review.md)
- [Knowledge Map exploration](docs/knowledge_map_exploration.md) (in Chinese)
- [Learning continuity, mastery evidence, and question review](docs/learning_continuity_review.md) (in Chinese)
- [Database reliability](docs/database_reliability.md) (in Chinese)

Some development documents describe earlier branch snapshots and their test results. Their historical status statements should not be treated as the current release status.
72 changes: 33 additions & 39 deletions app.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
from pathlib import Path

from services.i18n import tr
import streamlit as st

Expand All @@ -10,14 +12,19 @@
from services.auth_ui import render_auth_page
from services.account_ui import render_account_page, render_account_controls
from services.accessibility import render_accessibility_controls
from services.ui_style import apply_app_styles
from services.ui_style import BRAND_LOGO, BRAND_PLANE, apply_app_styles
from services.tutor_assistant_ui import clear_tutor_browser_state, render_tutor_assistant

ROOT = Path(__file__).resolve().parent
# Another change adds this page; list it only once its file is present.
LEARNING_RADAR_PAGE = ROOT / "pages" / "7_Learning_Radar.py"

st.set_page_config(
page_title="ExamPilot",
page_icon="📚",
layout="wide",
initial_sidebar_state="collapsed",
# Streamlit opens the sidebar on wide screens and keeps it closed on phones.
initial_sidebar_state="auto",
)

user = current_user(st.session_state)
Expand All @@ -35,6 +42,8 @@
from services.demo_updates import sync_demo_catalog
sync_demo_catalog(st.session_state)
apply_app_styles()
# The full logo heads the sidebar; the plane stays top-left when it is collapsed.
st.logo(str(BRAND_LOGO), icon_image=str(BRAND_PLANE), size="large")
account_page = st.Page(
render_account_page, title=tr("My account"), icon=":material/account_circle:",
url_path="account", visibility="hidden",
Expand All @@ -43,8 +52,8 @@
pages = [
st.Page(
"pages/0_Dashboard.py",
title=tr("Dashboard"),
icon=":material/dashboard:",
title=tr("Home"),
icon=":material/home:",
default=True,
),
st.Page(
Expand All @@ -67,6 +76,16 @@
title=tr("Knowledge Map"),
icon=":material/hub:",
),
]
if LEARNING_RADAR_PAGE.exists():
pages.append(
st.Page(
"pages/7_Learning_Radar.py",
title=tr("Learning Radar"),
icon=":material/radar:",
)
)
pages += [
st.Page(
"pages/6_Concept_Lab.py",
title=tr("Concept Lab"),
Expand All @@ -79,7 +98,8 @@
),
]

navigation = st.navigation([*pages, account_page], position="hidden")
# Default position: the page list lives in Streamlit's collapsible sidebar.
navigation = st.navigation([*pages, account_page])
# Page widgets are cleaned up during navigation; rehydrate a course's saved
# scope once when entering its study page, not on every form interaction.
if st.session_state.get("_learning_page_path") != navigation.url_path:
Expand All @@ -96,44 +116,18 @@
if selected_course is not None:
st.session_state.pop(f"scope_initialised_{selected_course.course_id}", None)
st.session_state["_learning_page_path"] = navigation.url_path
with st.container(key="flight_header"):
brand, home, practice, review, account = st.columns(
[1.65, 0.85, 0.95, 1.2, 0.95], gap="small", vertical_alignment="center"
)
with brand:
st.markdown(
'<div class="flight-brand"><span aria-hidden="true">✈</span> ExamPilot</div>',
unsafe_allow_html=True,
)
with home:
st.page_link(pages[0], label=tr("Home"), icon=":material/home:", width="stretch")
with practice:
st.page_link(pages[2], label=tr("Practice"), icon=":material/edit_note:", width="stretch")
with review, st.popover(tr("Review & tools"), width="stretch"):
for page in (pages[1], pages[3], pages[4], pages[5], pages[6]):
st.page_link(page, width="stretch")
with account, st.popover(tr("Account"), icon=":material/account_circle:", width="stretch"):
render_account_controls(account_page)
with st.expander(tr("Accessibility settings")):
render_accessibility_controls()

# Account, save status and accessibility settle at the bottom of the sidebar.
with st.sidebar, st.container(key="sidebar_footer"):
render_account_controls(account_page)
with st.container(key="flight_sync_status"):
render_sidebar_status()
with st.expander(tr("Accessibility settings")):
render_accessibility_controls()

if selected_course := st.session_state.get("current_course"):
with st.container(key="flight_course_context"):
st.caption(f"{selected_course.course_name} / {navigation.title}")

with st.container(key="flight_sync_status"):
render_sidebar_status()

# Reserve room for the floating entry at the bottom of narrow study pages.
st.markdown(
"""<style>
@media (max-width: 480px) {
[data-testid="stMain"] [data-testid="stMainBlockContainer"] {
padding-bottom: 6rem;
}
}
</style>""",
unsafe_allow_html=True,
)
render_tutor_assistant()
navigation.run()
Loading
Loading