Deploy SAT & ACT Learning Lab 1.2.2

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.db
+*.db-wal
+*.db-shm
+.gradio/
+

DEPLOYMENT_NOTES.md

@@ -0,0 +1,102 @@
+# Deployment notes — SAT & ACT Learning Lab 1.2.2
+
+Target private Space: `DearmonAnalytics/SAT_ACT_Learning_Lab`
+
+Turso database: `dearmon-sat-act-learning-lab`
+
+Schema namespace: `sat_act_learning_lab_v1`
+
+Encrypted-source secret: `SAT_ACT_APP_FERNET_V1_2_2_F48B2CACB56D_C9A0A3E35DD0`
+
+## Runtime contract
+
+- Python 3.12 and Gradio 6.24.0 are pinned.
+- The encrypted package is authenticated with Fernet and verified against both
+  ciphertext and decrypted-archive SHA-256 hashes.
+- Python source modules load from memory; plaintext source is not extracted to
+  the Space filesystem.
+- Turso is required in production. Each process may use its own embedded
+  replica at `/tmp/dearmon-sat-act-learning-lab-{pid}.db`.
+- Authentication-sensitive account reads refresh that replica on a bounded
+  process-local interval and fail closed if a required refresh cannot complete.
+  Live timed-exam state and mutation locks are process-local, so this release
+  must run one application process for authoritative simulation/resume. A
+  multi-process topology requires a distributed exam lease/generation protocol;
+  sticky routing alone does not provide that guarantee.
+- Username accounts map to stable opaque learner IDs and store only salted
+  scrypt password records. Five failed sign-ins within 15 minutes lock the
+  account for 15 minutes, and authentication-version checks revoke old sessions
+  after a password change or recovery.
+- Legacy learner IDs use the same stable server-side HMAC secret; learner PINs
+  must not be stored or logged. Conversion requires verified name/class/PIN
+  credentials and retains the existing learner ID and mastery history.
+- Email password recovery is optional and uses an eight-digit, 15-minute,
+  single-use code with five attempts. Every account also receives a
+  one-time-display offline recovery key that is stored only as a keyed digest
+  and rotates after use or password change.
+- One-click demos have a 45-minute ordinary-use window and route all seeded/new
+  progress and simulation state to bounded process memory—not Turso,
+  instructor analytics, exports, deletion, or recovery. A started full
+  simulation may reserve blueprint duration plus a 45-minute grace period,
+  capped at four hours; sign-out or restart still erases it immediately.
+- Instructor-wide access requires a strong secret with no fallback.
+- Scored questions and answer keys are deterministic and model-independent.
+- Break It Apart is a deterministic, provider-independent, post-miss reasoning
+  DAG. It is available after every incorrect practice grade and for every
+  missed objective item reviewed after a completed simulation—never before
+  grading or during an active form. The topic is the top node; sentence,
+  quantity/unit/operation, claim/evidence, or data/variable attributes feed up
+  through the answer dependency path. These attributes are explanatory only
+  and do not create separate mastery or retention records.
+- The embedded Business Calculus avatar defaults to the male professor and
+  offers Oliver (`cedar`, speed `1.02`). Speech and live Simli video are opt-in;
+  audio retention is disabled by default. Oliver is presented as an AI teaching
+  persona, not as the real person or a source of real-world claims.
+- `SIMLI_API_KEY` and SMTP passwords stay server-side and never enter HTML,
+  browser state, public variables, logs, receipts, or health output.
+- `/healthz` reports the release/source digest and boolean configuration status
+  without returning credentials, learner identifiers, or answers.
+
+## Configuration
+
+Core secrets are `OPENAI_API_KEY`, `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN`,
+`LEARNER_ID_HMAC_SECRET`, `INSTRUCTOR_EXPORT_SECRET`, and
+`SAT_ACT_APP_FERNET_V1_2_2_F48B2CACB56D_C9A0A3E35DD0`. Live avatar video additionally uses optional
+`SIMLI_API_KEY`.
+
+Email recovery uses `AUTH_RECOVERY_EMAIL_ENABLED`, `AUTH_SMTP_HOST`,
+`AUTH_SMTP_PORT`, `AUTH_SMTP_USERNAME`, `AUTH_SMTP_PASSWORD`,
+`AUTH_SMTP_FROM_EMAIL`, `AUTH_SMTP_STARTTLS`, `AUTH_SMTP_SSL`, and optional
+`AUTH_SMTP_TIMEOUT_SECONDS`. Leave email recovery disabled unless the
+configuration is complete; offline recovery still works.
+
+Release runtime defaults include `ACCOUNT_AUTH_ENABLED=1`,
+`AUTH_SESSION_RECHECK_SECONDS=30`, `AUTH_REPLICA_SYNC_SECONDS=5`,
+`SAT_ACT_DEMO_MODE_ENABLED=1`,
+`SAT_ACT_DEMO_SESSION_TTL_SECONDS=2700`,
+`ASK_PROFESSOR_COMPONENT_DEFAULT=1`, `ASK_PROFESSOR_TTS_DEFAULT=0`, and
+`ASK_PROFESSOR_SIMLI_DEFAULT=0`. Face IDs and the pinned Simli client module are
+listed in `environment.example` used to prepare this deployment.
+
+## v1.2.2 upgrade gate
+
+Finish or explicitly abandon every active timed simulation from an earlier
+release before installing v1.2.2. Checkpoints are intentionally bound to
+app/source/form versions and cannot be resumed across this release. Back up
+Turso, preserve `LEARNER_ID_HMAC_SECRET`, and retain prior Fernet secrets and
+rollback commits needed through acceptance testing.
+
+## Key lifecycle and rollback
+
+The current loader reads only `SAT_ACT_APP_FERNET_V1_2_2_F48B2CACB56D_C9A0A3E35DD0`. A later release must generate a
+new versioned, fingerprinted secret name. The deployer adds that secret before
+the repository commit and retains earlier keys. Roll back by reverting the
+Space repository to the prior commit recorded in `deployment_receipt.json`.
+Do not delete an earlier Fernet key until its rollback revision is retired.
+
+## Legal notice
+
+This independent practice lab is not affiliated with or endorsed by College
+Board or ACT, Inc. SAT and ACT are their respective owners' trademarks. The
+lab contains original practice material only; diagnostic results are not
+official scores.

README.md

@@ -1,13 +1,98 @@
 ---
-title: SAT ACT Learning Lab
-emoji: 🔥
-colorFrom: gray
-colorTo: gray
+title: SAT & ACT Learning Lab
+emoji: 🧭
+colorFrom: indigo
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.26.0
-python_version: '3.13'
+sdk_version: 6.24.0
+python_version: "3.12"
 app_file: app.py
 pinned: false
+license: other
+short_description: Dynamic SAT/ACT practice, mastery, and reasoning graphs
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Dearmon Analytics SAT & ACT Learning Lab
+
+Release `1.2.2` provides original dynamic practice for current SAT and
+ACT skill blueprints, a four-level topic graph, individual mastery tracking,
+targeted practice, and test-like diagnostic sessions. 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.
+
+The question engine and answer keys are deterministic. The optional AI teaching
+assistant can explain concepts and student work but does not create scored
+questions, decide correctness, or alter answer keys.
+
+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_2_2_F48B2CACB56D_C9A0A3E35DD0`.
+
+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.
+
+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. Email one-time-code recovery is optional;
+configure `AUTH_RECOVERY_EMAIL_ENABLED`, `AUTH_SMTP_HOST`, `AUTH_SMTP_PORT`,
+`AUTH_SMTP_USERNAME`, `AUTH_SMTP_PASSWORD`, `AUTH_SMTP_FROM_EMAIL`,
+`AUTH_SMTP_STARTTLS`, `AUTH_SMTP_SSL`, and optional
+`AUTH_SMTP_TIMEOUT_SECONDS`; keep provider credentials as Space secrets. Email
+codes expire after 15 minutes and are single-use. Without SMTP, offline
+recovery remains available.
+
+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
+
+Before replacing any earlier release with v1.2.2, every active timed simulation
+must be finished or explicitly abandoned. Saved forms are bound to the app
+version and encrypted-source fingerprint, so v1.2.2 intentionally rejects older
+checkpoints. Preserve `LEARNER_ID_HMAC_SECRET` and retain every prior versioned
+Fernet secret and rollback commit needed through acceptance testing.
+
+## 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.

release_manifest.json

@@ -0,0 +1,97 @@
+{
+  "built_utc": "2026-08-29T21:32:04+00:00",
+  "database_name": "dearmon-sat-act-learning-lab",
+  "encrypted_payload_sha256": "624ee6c73861cb1664781dea08df4acf727f0d93e4e04186947f777520d5fab1",
+  "entry_module": "sat_act_lab.app_main",
+  "fernet_secret_name": "SAT_ACT_APP_FERNET_V1_2_2_F48B2CACB56D_C9A0A3E35DD0",
+  "key_fingerprint_sha256_prefix": "C9A0A3E35DD0",
+  "plaintext_archive_sha256": "f48b2cacb56d10f6d361cfdf5e01a4a4c4637f1b6b1ec01aab32bdbede584904",
+  "release_version": "1.2.2",
+  "schema_namespace": "sat_act_learning_lab_v1",
+  "schema_version": "dearmon-sat-act-release-v1",
+  "source_members": {
+    "sat_act_lab/__init__.py": {
+      "bytes": 71,
+      "sha256": "31ffa487949f215cc8112867e1a4e0d3f371a63865950dd364a6b5f0fa999877"
+    },
+    "sat_act_lab/act_english_bank.py": {
+      "bytes": 79622,
+      "sha256": "f27b4dbc7380b15856a09156e10193e01e9ee986afa307f81e85f8255a4bc42a"
+    },
+    "sat_act_lab/act_reading_bank.py": {
+      "bytes": 62923,
+      "sha256": "ab2b3374bd4cf52c85c700f487979a5968a4baa701fda260bc826ace98e18db8"
+    },
+    "sat_act_lab/act_science_bank.py": {
+      "bytes": 43952,
+      "sha256": "5959db1e6a007f9384978c2a65af82e9bfd81216db939a1d852a91852badef8e"
+    },
+    "sat_act_lab/app_main.py": {
+      "bytes": 240007,
+      "sha256": "ae4c6090cfded3affe6830fe04869d6a85868eaa6f8e54f763aa737134ad8929"
+    },
+    "sat_act_lab/attribute_graph.py": {
+      "bytes": 119752,
+      "sha256": "be633962117561ae8ee2f02cf43c1b1612d7faf79916d2af52c5596db1ec8b0a"
+    },
+    "sat_act_lab/auth.py": {
+      "bytes": 52719,
+      "sha256": "ca3a1ed2540a3c7a617286e26dedd0901caef39126684b0e3a62f0fa13fe4c67"
+    },
+    "sat_act_lab/avatar.py": {
+      "bytes": 73246,
+      "sha256": "1456fe4834dec9636845ee0dd4794c4750abda703a5278079ce41b09d0fbbbff"
+    },
+    "sat_act_lab/blueprints.py": {
+      "bytes": 49657,
+      "sha256": "7c9cf2c1532818203b7a52de24d61031aeb65d31ccd7f6be627c0bb2c99ecf93"
+    },
+    "sat_act_lab/curriculum.py": {
+      "bytes": 34704,
+      "sha256": "0ace42ff71e3eee09b7b0828807cda7ecad2ea86caeda9cb67c0b941ab70c960"
+    },
+    "sat_act_lab/demo_sessions.py": {
+      "bytes": 37662,
+      "sha256": "544b2163c3d39259108847468d8f9bb027ae65d3b13ee934a8f6d9a43d167943"
+    },
+    "sat_act_lab/exam_engine.py": {
+      "bytes": 100384,
+      "sha256": "2abb720cd5a0a5a459cbcdc7ec1a8919ea50d7203cc809adccdefed4317e3a7f"
+    },
+    "sat_act_lab/question_engine.py": {
+      "bytes": 221287,
+      "sha256": "929d8e424bbb845e69cab76f6e591f9bfb1f825c00733cd90efce089ea1a89a2"
+    },
+    "sat_act_lab/tracking.py": {
+      "bytes": 139074,
+      "sha256": "c814032247eac63b59d7c619aa172af6340840bc2d1cd5e2b9e5294862231d82"
+    }
+  },
+  "space_file_hashes": {
+    ".gitignore": {
+      "bytes": 56,
+      "sha256": "3b1fdd8eb2e17dc4edae8387f1bc9a18a8072a8d6fae3a71041f00f0b9b04103"
+    },
+    "DEPLOYMENT_NOTES.md": {
+      "bytes": 5663,
+      "sha256": "75c5b9f2879c7d8c3edf341a9193651d35fc803480cb03082ab94e09bd495057"
+    },
+    "README.md": {
+      "bytes": 5113,
+      "sha256": "834bcec62692addb45ba46e4936455adf94b202cc5ff9fce0c046b5474684e4e"
+    },
+    "app.py": {
+      "bytes": 556664,
+      "sha256": "22acd56b8e17e47ab11c2eeea2ba2fc5f20e6a24db71f1d069f7fdc54f23e8f8"
+    },
+    "requirements.txt": {
+      "bytes": 287,
+      "sha256": "1cfe1a2b7efb8ba2372a283d5897316f691a693b23b53e0169888569060d1776"
+    },
+    "runtime.txt": {
+      "bytes": 13,
+      "sha256": "3c06f1fa700cc89985a58f039c6e5b4a973fc52e2c50b4fb092c0f89eb532f3a"
+    }
+  },
+  "target_space": "DearmonAnalytics/SAT_ACT_Learning_Lab"
+}

requirements.txt

@@ -0,0 +1,18 @@
+gradio==6.24.0
+gradio-client==2.6.0
+huggingface-hub==1.27.0
+fastapi==0.141.1
+starlette==1.6.0
+jinja2==3.1.6
+uvicorn==0.41.0
+numpy==2.5.2
+pandas==3.0.5
+matplotlib==3.10.8
+sympy==1.14.0
+requests==2.34.2
+pillow==12.1.1
+python-docx==1.2.0
+libsql==0.1.11
+openai==2.54.0
+cryptography==46.0.7
+

runtime.txt

@@ -0,0 +1,2 @@
+python-3.12
+