README.md

metadata

title: My Streamlit App
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: 1.49.1
app_file: app.py
pinned: false

My Streamlit App

This is a Streamlit application deployed on Hugging Face Spaces.

Hint-Based Math Tutor (Problem 13)

A progressive hint system for math word problems that guides students without revealing answers early.

Quick Start (Local)

cd hint-tutor
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your NVIDIA_API_KEY (from NVIDIA NIM)
streamlit run app.py

Run via ngrok (for live demo from laptop)

# Terminal 1: Start Streamlit
streamlit run app.py --server.port 8501 --server.headless true

# Terminal 2: Start ngrok tunnel
ngrok http 8501
# Share the https://... URL with judges

App Features

Single Tutor tab with V2 chained pipeline:

• Progressive hints: Level 1 (Orient) → Level 2 (Strategy) → Level 3 (Walkthrough)
• Level locking: L2 requires L1; L3 requires L1+L2 or student attempt
• Guard badges: Passed / Regenerated N× / Safe fallback
• Working check (stretch): Paste working → analyzes first wrong step → targeted hint
• Final answer check: Normalized numeric comparison
• History sidebar: Timestamped log of all problems + hints in this session
• Random problems: 6 extra problems not in eval set
• Debug panel: Hidden solution + LLM call log (toggle in sidebar)

Project Structure

hint-tutor/
├── app.py                      # Streamlit app (Tutor tab + history sidebar)
├── llm.py                      # NVIDIA NIM wrapper (retry, timeout, JSON validation)
├── schemas.py                  # Pydantic models
├── pipeline_v1.py              # Naive baseline (for eval only)
├── pipeline_v2.py              # Production V2 chained pipeline
├── guardrails.py               # Input gate, leak check, fallbacks
├── arithmetic_check.py         # Deterministic step verification (sympy)
├── prompts/
│   ├── v1/hint_naive.md
│   └── v2/p0_input_gate.md p1_solver.md p2_hint_generator.md p3_leak_judge.md
│       p4_working_analyzer.md p5_targeted_hint.md
├── eval/
│   ├── problems.json           # 12 test problems
│   ├── wrong_working.json      # 12 labeled working cases
│   ├── guardrail_cases.json    # 7 guardrail tests
│   └── run_eval.py             # Evaluation runner (--version v1|v2|both)
├── results/                    # Evaluation outputs
├── PROMPT_HISTORY.md           # Timestamped prompt changes (git log format)
├── requirements.txt
├── .env.example
├── .gitignore
└── tests/
    ├── test_guardrails.py
    └── test_pipeline_v2.py

Hint Ladder

Level	Name	Allowed	Forbidden
1	Orient	Restate givens/ask, one guiding question	Operations, formulas, computed numbers, answer
2	Strategy	Concept name, first sub-goal/equation setup	Final step result, answer
3	Walkthrough	Full solution + answer	—

Pipeline V2 (Chained)

Input Gate (code + LLM P0)
    → Hidden Solver P1 (×2, temp 0 & 0.7, verify final_answer)
    → Hint Generator P2 (level N, schema validation retry)
    → Leak Guard: Code check → LLM Judge P3 (if L1/L2)
        → Regenerate ≤2× with feedback → Safe Fallback
    → Show Hint

Stretch: Student working → Arithmetic Checker + Working Analyzer P4 → Targeted Hint P5 (same leak guard)

Evaluation

Run locally:

python eval/run_eval.py --version both

Metrics:

• M1 Leak Rate L1-L2 (V1 vs V2, with/without guard)
• M2 Wrong-Step Accuracy (V2 analyze_working vs labels; V1 baseline)
• M3 Format-Validity Rate (first-try Pydantic success / total LLM calls)
• Guardrail Suite (code + P0 on 7 cases)

Outputs: eval/results/leak_v1.csv, leak_v2.csv, wrong_step_v1.csv, wrong_step_v2.csv, guardrails.csv, summary_HHMM.md

Prompt Discipline

All prompts live in versioned .md files under prompts/. Changes logged in PROMPT_HISTORY.md with format:

prompt(<card>): <what changed> | why: <failure it fixes> | vX.Y