README.md

metadata

title: SAT & ACT Learning Lab
emoji: 🧭
colorFrom: indigo
colorTo: yellow
sdk: gradio
sdk_version: 6.24.0
python_version: 3.12.13
app_file: app.py
pinned: false
license: other
short_description: Dynamic SAT/ACT practice, mastery, and reasoning graphs
thumbnail: >-
  https://huggingface.co/spaces/DearmonAnalytics/SAT_ACT_Learning_Lab/resolve/main/space-preview.png

Dearmon Analytics SAT & ACT Learning Lab

Release 1.8.18+hfbuild6 provides original dynamic practice for current SAT and ACT skill blueprints, a complete eight-level question-skill hierarchy, individual mastery tracking, targeted practice, and test-like diagnostic sessions with separate raw results and unofficial practice-score estimates. It adds username/password accounts, secure recovery, an isolated one-click demo, and the embedded teaching avatar layer used by the Dearmon Analytics Business Calculus platform. Release 1.2.0 introduced deterministic post-miss Break It Apart attribute graphs. Signed-in students can also download their complete personalized Topic Graph as a branded PNG, printable PDF, accessible hierarchy-and-concepts CSV, and verification manifest; demo sessions remain nonexportable.

Release 1.8.18+hfbuild6 retains the exact Dearmon Analytics paper, ink, blue, teal, and coral system established in v1.4.4 for the compact 1,240-pixel workspace. Bundled Inter, Source Serif 4, and Geist Mono fonts are served from same-origin routes. The compact test chooser and closely stacked Section → Domain → Narrow Topic rails use one restrained DA gradient rule, flat accessible controls, and shadow-free surfaces. Practice variation settings are collapsed under Test Tools.

Next-lesson routing advances from the authoritative active-question path, so stale browser selector state cannot regenerate the same lesson. Solution-count feedback works the actual linear equation, including the cancellation that produces a true identity and why that identity means every real value works.

The answer record freezes elapsed time and its blueprint target at grading, then reports their exact reduced fraction and pace comparison. Learner/account and instructor attempt CSVs expose the timing values while legacy untimed rows remain blank. Shared math normalization serves both lesson surfaces and printable exam/answer-key PDFs so raw LaTeX is never the learner-facing fallback. The collapsed item-specific Concepts Needed swim lane, complete analogous worked examples, separate hints, and mastery whitening remain.

Release 1.8.18+hfbuild6 assigns all 1,983 trusted built-in question profiles their full Exam → Section → Official Domain → Official Skill Family → Narrow Exam Target → Prerequisite Bundle → Atomic Skill → Observable Failure Attribute path. Each stable profile contains its complete ancestor and transitive- prerequisite closure, format/context tags, and explicit scoring role. Unknown or incomplete profiles fail closed. A single miss is never treated as proof of a foundational gap; retained reports require repeated independent evidence. The coverage set is 1,832 deterministic template profiles (1,780 objective and 52 ACT Writing essay families), 145 immutable ACT passage-bank items, and 6 dedicated order-of-operations remediation templates; 1,925 profiles are potentially objective-score eligible after their enclosing activity rules.

Tracking schema 1.3.0 is additive: it adds versioned hierarchy nodes/edges, question profiles/members, and immutable question-instance bindings. Per-attempt skill opportunities join those bindings to the existing attempts and learning signals; a missing signal stays missing. Earlier learner, mastery, recovery, and diagnostic records remain compatible, and historical rows are not assigned fine-grained evidence that they did not originally retain.

The deterministic score estimator preserves raw correct/incorrect/omitted counts, then separately presents clearly unofficial SAT section/total or ACT section/Composite estimates, plausible intervals, evidence sufficiency, and confidence. The ACT Composite uses English, Math, and Reading; optional Science is reported separately, and optional Writing remains human reviewed. Hidden pretest/EFT items and AI supplemental printable items are excluded. Fewer than eight observed items or less than one quarter of a standard section remains a preliminary, very-low-confidence result below the reporting threshold.

Release 1.8.18+hfbuild6 retains one OpenAI-assisted follow-up beneath each graded explanation and a signed-in cross-question Learning Diagnostic. The diagnostic unlocks only after strict majority coverage of both Reading and Math for the same exam. It sends OpenAI only allowlisted aggregate performance evidence—not learner identity, raw questions, selected responses, or answer keys—and rejects output outside the server-approved finding/remediation schema. A successfully retained report unlocks deterministic Guided Examples from basic to complex and specific Targeted Practice; those workspaces remain disabled before the gate and report are complete.

Progress & Reports includes three responsive hierarchical mastery wheels. SAT shows Reading and Writing plus Math; ACT combines English and Reading as Reading/Language and shows Math separately. Domain and narrow-topic angles stay fixed to the curriculum, radial depth shows scored attempts toward four, and color independently shows raw accuracy. Untouched topics say Unassessed rather than 0%. Exact native tables provide the same aggregate data for keyboard, touch, print, and assistive-technology access.

The third wheel shows topic/skill mastery, with cumulative correct tagged questions divided by attempts. The Skill Taxonomy Graph sits below the topic graph. Both display per-entry potential score loss, allowing blind-guessing credit (25% for four choices; no assumed credit for typed answers). A complete CSV/JSON catalog explains the modeled question mix and reports expected correct answers retained. These conditional losses overlap and must not be added.

The Printable Exam Builder requires an active demo or signed-in learner so every generated file has a cleanup owner. It creates a clean Dearmon Analytics-branded student PDF and a separate answer-key PDF from selected or previously missed topics. Both carry the same random form code. Core scored questions, their complete skill profiles, their answer keys, and score eligibility are deterministic. After the active learner has completed every built-in question type for an exact topic, explicit opt-in can create separately labeled, independently reviewed AI supplemental items for printing only. They never decide correctness or alter skill evidence, mastery, readiness, routing, diagnostics, or score estimates.

After every incorrectly graded practice question, and for every missed objective item reviewed after a completed simulation, Break It Apart constructs a directed acyclic reasoning graph with the tested topic at the top. Sentence items diagram subjects, verbs, direct objects, complements, modifiers, and dependent clauses. Math items build from quantities and units through order of operations and intermediate dependencies. Reading and science items connect claims, evidence, data, variables, and conclusions. The graph is deterministic, makes no model or provider call, and is unavailable before an incorrect grade or completed simulation. Its attributes are explanatory scaffolds, not separate attribute-level mastery or retention records.

Service configuration

This private Space uses the separate Turso database dearmon-sat-act-learning-lab and schema namespace sat_act_learning_lab_v1. Its encrypted application uses the versioned Space secret SAT_ACT_APP_FERNET_V1_8_18_HFBUILD6_FA5015374498_45CC1E1A0BC7.

Required Space secrets are OPENAI_API_KEY, TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, LEARNER_ID_HMAC_SECRET, INSTRUCTOR_EXPORT_SECRET, and the versioned Fernet secret named above. There is no default instructor password.

SIMLI_API_KEY is optional and enables learner-initiated live avatar video. The avatar defaults to the male-professor style, Oliver is selectable, and Oliver's speech profile uses the cedar voice at speed 1.02. The component is shown by default, but speech and live video both default off until the learner opts in. Oliver is an AI-generated teaching persona, not the real person or a source of real-world claims. The Simli key remains server-side and must never appear in HTML, browser state, logs, public variables, or /healthz. Text tutoring remains available when Simli is absent or unavailable.

The Simli 3.0.2 browser client is packaged with this release and served from the same-origin /_simli/client.mjs route with integrity verification and safe response headers. The browser does not import the avatar client from esm.sh or another runtime CDN. If video startup fails, the learner can continue with text tutoring or spoken replies. The bundled dependency licenses are retained in THIRD_PARTY_NOTICES.md.

Username passwords are stored as independently salted scrypt records. Account lockouts persist in the database, password changes revoke earlier sessions, and verified legacy name/class/PIN profiles can be converted without moving their mastery history. Each account receives a one-time-display offline recovery key that rotates after use. Account email on Hugging Face uses Resend over HTTPS because standard SMTP ports are blocked. Set AUTH_EMAIL_PROVIDER=resend, AUTH_EMAIL_FROM=jacob@dearmonanalytics.com, AUTH_RESEND_API_KEY as a Space Secret, and AUTH_RECOVERY_EMAIL_ENABLED=1. The private kit includes SETUP_EMAIL.bat and docs/EMAIL_RECOVERY_SETUP.md for configuration and delivery checks. The consumer Resend sender is jacob@dearmonanalytics.com. Setup repairs a different saved sender while preserving the existing Resend Secret. Provider credentials belong in Secrets, never public Variables or source. Use the code from your most recent request: codes expire 15 minutes after the request, work once, and are replaced by a newly requested code. Delayed emails may arrive out of order. A saved offline recovery key remains available when email is unavailable.

The one-click demo has a 45-minute ordinary-use window and starts with clearly labeled sample progress. Starting a full simulation reserves its blueprint duration plus a 45-minute completion grace period, capped at four hours. Demo practice and simulation state remain in bounded server memory only: they are not written to Turso, included in instructor analytics or exports, or eligible for account recovery. Sign-out/reset or process restart removes the session immediately; otherwise it disappears at the applicable expiry.

Audio/video are opt-in and audio retention is disabled by default. Deployments serving minors need appropriate notice, consent, provider review, access controls, and retention policies.

Upgrade note

Version 1.8.18+hfbuild6 uses immutable item/timing/scoring snapshots and explicit recovery compatibility contracts. Resume only a saved contract that is explicitly supported; legacy checkpoints follow the tested compatibility allowlist. Incompatible work stays blocked and requires an approved transition or learner choice, never silent regeneration/abandonment. Back up only inside the authorized hosting boundary, preserve identity/source keys, and retain current audit/tombstones/holds/revocations. Rollback requires compatible data and a new reviewed release manifest; it cannot restore expired/revoked access or overwrite legitimate new learner work.

The owner kit ships no decryption key or production data. Its first local build creates the matching source key/payload. Deployment defaults to local dry-run; only explicit --execute plus DEPLOY opens remote changes. Python 3.12.13 is the validated application patch. This Space explicitly selects python_version: "3.12.13"; the builder verifies agreement with runtime.txt and the loader. Health verification records the actual interpreter before deployment succeeds.

Independent practice-content notice

This is an independent educational practice product. It is not affiliated with, endorsed by, or sponsored by College Board or ACT, Inc. SAT is a trademark of College Board; ACT is a trademark of ACT, Inc. All practice questions, passages, data, explanations, and figures in this lab are original content. Practice results are diagnostic and are not official scores.

Two ways to test

Adaptive Test prioritizes personal content weaknesses with high modeled score opportunities, adjusting the next question and difficulty after every answer. Choose 10, 20 or 30 questions; results include answer review and ranked study priorities after completion. Blind guessing and sparse evidence are accounted for. These are conditional study priorities, not guaranteed gains.

Normal Test · Exam Simulation follows the standard timed blueprint, including SAT module routing, independently of saved weakness priorities. Targeted adaptive accuracy is kept separate from normal score estimates. Completed adaptive work is saved to cumulative mastery. Signed-in unfinished adaptive tests have encrypted recovery checkpoints; use the saved recovery boundary after reconnecting.

Diagnostic prerequisite and database upgrade

The diagnostic must be fully completed and saved before adaptive testing unlocks for the same learner and exam. Partial responses, older practice or demo sample history cannot unlock it. Normal testing remains available independently. The latest completed diagnostic seeds adaptive priorities alongside eligible practice history, with its actual item-level guessing adjustment preserved.

Tracking schema 1.5.0 retains additive checkpoint storage and completed learner history. Run repeat-safe migrations and an authorized host-side backup before deployment. Current immutable recovery contracts preserve compatible work across releases; unsupported historical contracts remain blocked for an explicit transition. Keep security decision stores and reviewer revocations independent of database rollback.

Institutional controls and OMES readiness

The institutional profile blocks unapproved student processing and external AI/Simli services. It disables public signup, demos and legacy PIN entry and implements OIDC code/PKCE, explicit MFA assertion checks, provisioned issuer/subject identity, individual staff roles/class scopes and server-side ownership guards. Recovery email requires verified TLS. Accessible chart tables, keyboard improvements and owned diagnostic exports are included; framework analytics remains disabled.

Read the source package's docs/OMES_PLATFORM_READINESS.md, docs/INSTITUTIONAL_IDENTITY.md, docs/SECURITY_IMPLEMENTATION.md and docs/ASSESSMENT_RECOVERY.md. Use deployment/institutional/README.md for a new approved container deployment. The institutional HF updater only updates a preprovisioned approved target with protected roster and persistent storage. Code/configuration does not establish State-approved MFA, completed human accessibility/ACR acceptance, educator signoff on standards alignment, actual U.S. hosting/encryption/backup evidence, signed IT terms or supplier/AI authorization. Run the redacted preflight and obtain the actual applicable external records before covered performance.

Tracking schema is 1.5.0. Authenticated diagnostic/adaptive checkpoints now survive supported same-version restarts; recovery validates the learner, exact release/source compatibility and checkpoint revision. Unsaved browser input is outside that boundary. Production acceptance must separately prove remote durability, restored keys/database and provider backups. Consumer accounts remain available in consumer mode; institutional use requires its own approved OIDC roster and dedicated deployment/database.