--- title: "Session Catalog (Teacher Sessions)" url: https://docs.growamal.com/en/guides/session-catalog/ language: en --- # Session Catalog The Session Catalog gives teachers a fast, reliable path to preparing a class session without waiting for an AI draft. The catalog is a library of **pre-authored blueprints** — each one a curated set of sub-skills, a theme, and a target session length, written offline and quality-checked before publication. There is no generated content and no LLM anywhere on this path. When you pick a blueprint, Amal uses it as an instruction set. For every eligible student in your class, the system selects items from the item bank, personalizes the order and scaffold level based on each student's skill-status and active support plan, and delivers the result as an online practice queue or a printable worksheet with a QR code. The question bank, the ISM assembly engine, and each student's profile all stay as they are — the blueprint only defines the topic and sub-skill focus. > **Note:** **No questions are written at session time.** The blueprint picks existing items > from the bank; it does not generate new ones. ## The three tabs Navigate to **Sessions** in the teacher sidebar. The hub opens to three tabs: ### ⭐ Recommended The recommended tab shows blueprints that Amal thinks are most relevant for your class right now. The ranking is based on which sub-skills appear most frequently as areas of active need across your students — weighted by RTI support level — so students who need more intensive practice have a stronger influence on the ranking. Each row shows: - The blueprint name and its primary focus. - **"Why recommended"** — expand to see the matched sub-skills and how many students in your class have active need in those areas. The count is a plain number of students, not a percentage or a severity score. - A **"Pick"** button to start the session wizard for that blueprint. > **Warning:** The recommended list is a suggestion. You are not required to follow it. Any blueprint > in the catalog is available via the **Browse** tab, and you always confirm before > anything is sent to students. ### Browse The browse tab shows the full operational catalog. Use the filters to narrow by: - **Grade** — matches your class's grade level by default. - **Theme** — content topic (e.g., a named reading theme or skill family). - **Sub-skill** — the primary targeted literacy sub-skill. - **Keyword** — free-text search across title and tags. Results page with a "Load more" control (`cursor`-based paging). Each `BlueprintCard` shows the blueprint name, theme, the primary sub-skill, and the target session length. ### Recently generated The recently-generated tab lists sessions your class has had in the past, most recent first. Each row shows the blueprint used, the session state (`draft` / `previewed` / `delivered` / `cancelled`), and the delivery mode (online or printable). Row links open the session detail in read-only mode so you can review what was sent. The **"New session"** button always routes back to the full blueprint wizard — a prior session is never reused as-is to protect per-student personalization accuracy. --- ## Pick → edit → accept → deliver ### Step 1: Pick a blueprint Click **"Pick"** on any blueprint card (from the recommended or browse tab). Amal creates a `draft` session pinned to that blueprint's version. The draft opens the session detail page. ### Step 2: Edit (optional) In the draft state you can adjust: - **Target sub-skills** — add or remove sub-skills from the blueprint's default set. The set must stay between 1 and 5 sub-skills. If you add a sub-skill with limited item bank coverage for your grade, an inline amber note appears; this is advisory and does not block you from proceeding. - **Theme** — swap the content theme if a different one is more relevant to your current unit. These edits adjust the instruction set for the ISM assembly engine. No items are selected or generated until you accept. To discard the session entirely, use the **"Cancel session"** button (a confirmation dialog appears). A cancelled session remains in the recently-generated tab for reference. ### Step 3: Accept Click **"Accept"** to close the draft and trigger the per-student fan-out. For each eligible student: 1. Amal checks the student's current skill-status, active support plan (bundle assignment if any), and scaffold tier. 2. The ISM assembly engine selects items from the bank according to the blueprint's (sub-skills, theme, grade) instruction set and the student's personalization context. 3. A session slot is created for the student. The preview surface shows how many students were included and how many were temporarily excluded (see "Students not included" below). You cannot re-edit after accepting. ### Step 4: Deliver Once the session is in `previewed` state you can deliver it in one or both modes: #### Online delivery **"Distribute online"** queues a practice session for each included student. The next time a student opens Amal, the session will be waiting in their practice queue. The system is idempotent: running distribute more than once for the same student shows "already delivered" rather than creating a duplicate. #### Printable PDFs **"Generate PDFs"** produces a per-student PDF and a ZIP download of all sheets. Each sheet is A4, RTL, and includes a QR code the student can use to submit answers digitally. If any student-facing PDF string contains a language-safety violation, the API returns 422 and PDF generation is rejected for the whole batch. The session remains in `previewed` state; correct the content issue and retry. The `filter_failed` state is reserved for future partial-failure detection and is not currently written by the system. --- ## Students not included When you accept a session, students who currently have a `do_not_decide_yet` signal — meaning the system does not yet have enough data to determine their skill profile — are automatically held out of the fan-out. These students are listed in the **"Not included"** section on the previewed state with a growth-framed reason. You can manually include a student by clicking **"Include"** next to their name. A confirmation dialog opens; there is no free-text reason field — the override is recorded by the system with a fixed reason code. Manually included students receive an ISM-assembled session using whatever profile data is currently available. > **Warning:** If **all** students in your class are temporarily excluded, delivery buttons are > disabled. You can either include students manually one by one, or return later when > more assessment data has been collected. --- ## Personalization still happens per student The blueprint defines the topic and sub-skill focus. Personalization happens **inside** that focus, per student: - Item difficulty is matched to the student's current ability estimate. - If the student has an active support plan (bundle assignment), the ISM engine uses bundle-context mode — items are selected to reinforce the bundle's anchor and supporting threads. - Scaffold level is an internal ISM signal; it is never shown to the student. Two students in the same class who receive the same blueprint will get different items, different item orders, and potentially different session lengths depending on their individual profiles. --- ## API endpoints Teacher routes require authentication and are ClassTeacher-scoped. | Method | Path | Purpose | |---|---|---| | `GET` | `/api/sessions/catalog` | Browse / search / filter operational blueprints (FR-SGE-15) | | `GET` | `/api/sessions/catalog/recommended` | RTI-weighted recommended list for a class (FR-SGE-16) | | `GET` | `/api/sessions/recently-generated` | Recently-generated sessions for a class (FR-SGE-13) | | `POST` | `/api/sessions/from-blueprint` | Pick a blueprint and create a `draft` session (FR-SGE-17) | | `PATCH` | `/api/sessions/:id/edit` | Edit sub-skills / theme while in `draft` state (FR-SGE-17) | | `POST` | `/api/sessions/:id/accept` | Accept draft and trigger per-student ISM fan-out (FR-SGE-5) | | `POST` | `/api/sessions/:id/distribute-online` | Queue online practice for included students (FR-SGE-6) | | `POST` | `/api/sessions/:id/generate-pdfs` | Produce per-student printable PDFs + ZIP (FR-SGE-7) | | `POST` | `/api/sessions/:id/deliver-mixed` | «مختلط»: deliver each child in the medium frozen at accept, online and paper in one action (FR-TV3-16) | | `POST` | `/api/sessions/:id/recipients/:studentId/include` | Manually include an excluded student (FR-SGE-14) | | `POST` | `/api/sessions/:id/cancel` | Cancel a draft session | | `GET` | `/api/sessions/:id` | Session detail (teacher read) | | `GET` | `/api/sessions/:id/audit` | Full V-6 replay pin set + aggregate snapshot (requires `RUN_BACKOFFICE`) | For full request/response shapes see the [API Reference](https://docs.growamal.com/en/api-reference/). **Rate limit (admins and support):** each teacher may create at most **30 sessions per 15 minutes** (`POST /api/sessions/from-blueprint`). The 31st answers `429` with the body `{ "code": "RATE_LIMITED", "message": "Too many sessions created in the last 15 minutes", "retryAfter": }`. The teacher can create again once `retryAfter` has passed; the runbook (`docs/runbooks/wp-tdv3.md` §9) covers clearing one teacher's window on a support ticket. --- ## Admin: importing and approving blueprints Before any blueprint appears in the teacher catalog, an administrator imports a batch and a subject-matter expert approves it. These routes require the `RUN_BACKOFFICE` permission and are not available to teachers. | Method | Path | Purpose | |---|---|---| | `POST` | `/api/session-blueprints/import` | Import a JSON batch of blueprints; returns a `batchId` | | `GET` | `/api/session-blueprints/import` | List all blueprint import batches | | `GET` | `/api/session-blueprints/import/:batchId` | Inspect a specific import batch | | `POST` | `/api/session-blueprints/:batchId/approve` | Approve a batch; blueprints become visible in the catalog | | `GET` | `/api/session-blueprints/:id` | Single blueprint detail (admin read) | Blueprints start in `pending_review` status after import. Only approved (`operational`) blueprints appear in `GET /api/sessions/catalog` or `GET /api/sessions/catalog/recommended`. No blueprint is auto-approved on import. --- ## Wave-2 note Free-text topic input and document upload (both of which required a Teacher AI language model on the session path) are deferred to Wave 2. Wave 1 uses pre-authored blueprints only. --- ## Related guides - [Session Blueprints](https://docs.growamal.com/en/guides/intervention-bundles/): how blueprints are structured and authored - [Intervention Bundles](https://docs.growamal.com/en/guides/intervention-bundles/): how a bundle assignment influences ISM bundle-context mode - [Student Profiles](https://docs.growamal.com/en/guides/student-profiles/): the profile signals the fan-out reads per student - [Task Delivery](https://docs.growamal.com/en/guides/task-delivery/): how the ISM engine selects and serves items from the bank - [Teacher Activation Workflow](https://docs.growamal.com/en/guides/teacher-activation/): the separate surface for activating support plans