README.md

---
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

![SAT and ACT Skills and Topic Graph preview with sample learning progress](space-preview.png)

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](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.