@aastrika/ai-elements 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,29 @@ see at a glance what to expect when they upgrade.
 Versions follow semver: a **minor** adds something, a **patch** fixes something,
 and neither removes anything a host was using.
 
+## 0.4.1
+
+**Fixed**
+- This page now renders on npm. The architecture diagram was mermaid, which npm
+  shows as raw source, and the callouts used GitHub alert syntax. No code change
+
+## 0.4.0
+
+**Changed**
+- Generating a quiz now starts the work and polls for it, instead of waiting on
+  one long request. Nothing to change in your code — same tag, same inputs, same
+  `assessmentReady` firing once with the finished set
+
+**Why it matters**
+- No 60-second ceiling: gateways and proxies commonly close a request at one
+  minute, which capped how many languages could be asked for at once
+- The progress shown is the server's own, not an estimate
+- Closing the tab no longer loses the work
+
+**Notes for integrators**
+- Upgrade the service and the package together. A 0.3.0 element cannot read what
+  a 0.4.0 service answers, and the reverse leaves the element waiting
+
 ## 0.3.0
 
 **Added**

package/README.md

@@ -1,44 +1,37 @@
+<div align="center">
+
 # @aastrika/ai-elements
 
-**Three Aastrika features as custom elements.** Works in React, Vue, Angular,
-Svelte or plain HTML.
+**Three AI features. Three HTML tags. Any framework.**
 
-| Tag | What it does |
-|---|---|
-| `<aastrika-content-studio>` | A document becomes a narrated, illustrated training video |
-| `<aastrika-assessment>` | Source material becomes a validated MCQ set |
-| `<aastrika-reports>` | Who used what, and what it cost *(admin only)* |
+[![npm](https://img.shields.io/npm/v/@aastrika/ai-elements?color=A98229&label=npm)](https://www.npmjs.com/package/@aastrika/ai-elements)
+[![size](https://img.shields.io/badge/gzipped-99%20kB-A98229)](https://www.npmjs.com/package/@aastrika/ai-elements)
+[![deps](https://img.shields.io/badge/dependencies-0-A98229)](https://www.npmjs.com/package/@aastrika/ai-elements)
+[![licence](https://img.shields.io/npm/l/@aastrika/ai-elements?color=A98229)](https://github.com/Sphere/aastrika-ai-service/blob/master/LICENSE)
 
-One file, **~99 kB gzipped** (86 kB brotli), **no dependencies**. Angular is compiled
-inside, so you never install it and never upgrade because we did.
+</div>
 
----
-
-## Contents
+```html
+<aastrika-content-studio></aastrika-content-studio>   <!-- document → narrated video -->
+<aastrika-assessment></aastrika-assessment>           <!-- material → MCQ set, translated -->
+<aastrika-reports></aastrika-reports>                 <!-- who used what, and what it cost -->
+```
 
-| | |
-|---|---|
-| [The three features](#the-three-features) | What each element does |
-| [Setup](#setup) | Install, access, configure, mount |
-| [Integration guide](../../../docs/INTEGRATION.md) | Step by step, both auth paths |
-| [Angular example](../../lib-demo-app/) | A runnable app |
-| [Framework notes](#framework-notes) | React · Angular · Plain HTML |
-| [Configuration](#configuration) | The three values, and why two are functions |
-| [Access](#access) | Which gateway groups each feature needs |
-| [Theming](#theming) | CSS custom properties |
-| [Knowing when something failed](#knowing-when-something-failed) | Routing errors to your monitoring |
-| [Inputs and events](#inputs-and-events) | Opening the form set up, and acting on the result |
-| [When it does not work](#when-it-does-not-work) | Symptom → cause |
-| [Browser support](#browser-support) · [Server rendering](#server-rendering) | Constraints |
+Works in **React, Vue, Angular, Svelte or plain HTML**. Angular is compiled
+inside the package, so you never install it and never upgrade because we did.
 
 ---
 
-## Quick start
+## Ship it in three steps
+
+**1 — Install.** No peer dependencies, nothing to match.
 
 ```bash
 npm i @aastrika/ai-elements
 ```
 
+**2 — Configure once**, before anything renders.
+
 ```js
 import { configure } from '@aastrika/ai-elements';
 
@@ -49,53 +42,41 @@ configure({
 });
 ```
 
+**3 — Write the tag.** Importing the package registers it, so there is no step 4.
+
 ```html
-<aastrika-content-studio></aastrika-content-studio>
+<aastrika-assessment default-language="hi" default-translate-into="ta,or"></aastrika-assessment>
 ```
 
-That is the whole integration. The rest of this file is detail.
+<div align="center">
+
+**That is the whole integration.**
+A trainer uploads a PDF and gets a validated quiz in Hindi, Tamil and Odia —
+same questions, same answer key, ready to download.
+
+</div>
 
-> **You also need gateway access.** The package authenticates nobody — see
-> [Access](#access) for the groups each feature requires.
+> **You also need gateway access.** This package authenticates nobody — your
+> gateway decides. See [Access](#access) for the groups each feature needs.
 
 ---
 
-## How it fits together
+## Where to look
 
-```mermaid
-flowchart LR
-    subgraph host["Your application"]
-        cfg["configure()"]
-        tag["&lt;aastrika-content-studio&gt;"]
-    end
-
-    subgraph pkg["@aastrika/ai-elements"]
-        el["Custom element"]
-        int["Interceptor"]
-    end
-
-    subgraph svc["Aastrika"]
-        gw["Gateway<br/>checks the token"]
-        api["AI service"]
-    end
-
-    cfg -.->|apiBase · auth · creator| int
-    tag --> el
-    el --> int
-    int -->|"Authorization<br/>creator in the body"| gw
-    gw --> api
-    api -.->|JSON| el
-    el -.->|onError| cfg
-
-    classDef a fill:#0F766E,stroke:none,color:#fff
-    classDef b fill:#f1f5f4,stroke:#cbd5d3,color:#16181d
-    class el,int a
-    class cfg,tag,gw,api b
-```
+| | |
+|---|---|
+| **[The three features](#the-three-features)** | What each element actually does |
+| **[Configuration](#configuration)** | The three values, and why two are functions |
+| **[Access](#access)** | Which gateway groups each feature needs |
+| **[Inputs and events](#inputs-and-events)** | Open the form set up, act on the result |
+| **[Error reporting](#knowing-when-something-failed)** | Route failures to your monitoring |
+| | |
+| [Integration guide ↗](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/INTEGRATION.md) | Step by step, both auth paths |
+| [Runnable Angular app ↗](https://github.com/Sphere/aastrika-ai-service/tree/master/frontend/lib-demo-app) | Clone it, change one line, run it |
+| [Changelog ↗](./CHANGELOG.md) | What changed in each version |
 
-**Your application supplies three values. The package does the rest** — builds
-every request from `apiBase`, calls your two functions on each one, and renders
-into your page, styled through CSS custom properties.
+*Framework notes, theming, troubleshooting and server rendering are collapsed
+below — open the one you need.*
 
 ---
 
@@ -103,57 +84,63 @@ into your page, styled through CSS custom properties.
 
 ### `<aastrika-content-studio>`
 
-Upload a PDF, pick a style, language and voice, and get back a narrated,
-illustrated training video.
+**A PDF goes in. A narrated, illustrated training video comes out.**
 
-Planning is free and repeatable — the user sees the scene-by-scene plan and a
-cost estimate, and can revise it in writing as many times as they like. Only
-**Generate video** spends money, and the user sees what it will cost first.
-While it renders they get five-phase progress and a live log; at the end they
-can play, download or delete it.
+```
+ upload ──▶ pick style ──▶ review the plan ──▶ generate ──▶ play / download
+            language        free, revisable      the only
+            voice           cost shown first     paid step
+```
 
-[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/content-studio/README.md)
+The user uploads source material, picks a style, language and voice, and sees a
+scene-by-scene plan with an estimated cost. **Planning is free and repeatable** —
+they can rewrite it in plain words as often as they like. Only *Generate video*
+spends money, and the estimate is on screen before they commit.
 
-### `<aastrika-assessment>`
+While it renders they see five-phase progress and a live log. At the end they
+can play it, download it, or delete it.
 
-Files and links in, a validated multiple-choice set out — with control over
-language, question count, difficulty and Bloom level.
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
-Every question is checked before it is returned: one correct option, no
-duplicates, nothing the source material does not support. The user can fix
-wording, re-tick the correct option, then export XLSX or CSV.
+### `<aastrika-assessment>`
 
-[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/assessment/README.md)
+**Training material goes in. A validated MCQ set comes out — in as many
+languages as you need.**
 
-### `<aastrika-reports>`
+```
+ files & links ──▶ settings ──▶ questions ──▶ review each ──▶ export
+                   language      checked       language on     xlsx / csv
+                   count         before you    its own tab
+                   difficulty    see them
+```
 
-Who used what, and what it cost — totals for videos, assessments, people and
-estimated spend, split by tool, with a searchable table of creators.
+Every question is checked before it reaches the user: exactly one correct
+option, no duplicates, nothing the source material does not support.
 
-**Needs `contentAdmin` at the gateway**, and most consumers should not have it:
-spend figures are not for a partner's ordinary users. The service applies no
-role check of its own, so the gateway's ACL is the only thing keeping them
-apart.
+Ask for other languages and you get the **same** questions translated — same
+order, same options, same answer key — so one answer key marks every paper and
+scores compare across them. The reviewer reads each language on its own tab and
+fixes wording in place; the correct option is shared, so it is set once.
 
-[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/reports/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
----
+### `<aastrika-reports>`
 
-## Setup
+**Who made what, and what it cost.**
 
-The [Quick start](#quick-start) above is the whole integration. What each step
-is actually doing:
+Totals for videos, assessments, people and estimated spend, split by tool, with
+a searchable table of creators.
 
-| | Step | Notes |
-|---|---|---|
-| **1** | `npm i @aastrika/ai-elements` | No peer dependencies, no framework to match. Any bundler, or none |
-| **2** | Get gateway access | The package authenticates nobody — your gateway decides. See [Access](#access), then ask the Aastrika platform team |
-| **3** | `configure({ ... })` | Once, before the first element renders. Two of the three values are **functions** — see [Configuration](#configuration) |
-| **4** | Write the tag | Registration happens on import, so there is no third step |
+> **Needs `contentAdmin`, and most consumers should not have it.** Spend figures
+> are not for a partner's ordinary users. The service applies no role check of
+> its own — the gateway's ACL is the only thing keeping them apart.
+
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
 ---
 
-## Framework notes
+<details>
+<summary><b>React · Angular · Vue · plain HTML</b></summary>
 
 ### React
 
@@ -254,31 +241,57 @@ calling it, as above, prevents both.
 
 ---
 
+</details>
+
+---
+
+## How it fits together
+
+```
+  Your application                 @aastrika/ai-elements              Aastrika
+  ────────────────                 ─────────────────────              ────────
+  configure() ─────── apiBase ───▶ interceptor ─── Authorization ───▶ gateway
+                      auth              ▲          creator in body       │
+                      creator           │                                ▼
+  <aastrika-… >  ────────────────▶ element ◀────────── JSON ────────  AI service
+                      ▲                 │
+                      └──── onError ────┘
+```
+
+Your application supplies three values. The package builds every request from
+`apiBase`, calls your two functions on each one, and renders into your page.
+
+---
+
 ## Configuration
 
-Three things, and nothing else.
+Three values. That is the whole contract.
 
-| | |
-|---|---|
-| `apiBase` | Where the service is, no trailing slash. Empty string means same-origin. |
-| `getAuthHeaders` | Headers proving the caller may use the service — in practice a bearer token. |
-| `creator` | Who is signed into **your** application — their name or email, shown as-is in the usage report. |
-| `onError` | Optional. Called whenever a request fails, so your monitoring hears about it. |
+| | | |
+|---|---|---|
+| `apiBase` | **required** | Where the service is, no trailing slash. `''` means same-origin |
+| `getAuthHeaders` | **required** | Headers proving the caller may use the service — a bearer token in practice |
+| `creator` | **required** | Who is signed into *your* app. A name or email, shown as-is in the usage report |
+| `onError` | optional | Called whenever a request fails, so your monitoring hears about it |
 
-**Both are functions, and both are called on every request.** Tokens expire: a
-string handed over at startup stops working mid-session and the package has no
-way to ask for a fresh one. A function lets you return whatever your own auth
-library currently holds, and lets you switch user without reloading.
+### Why two of them are functions
 
-`creator` should be a **name or email** — it is displayed as-is in the usage
-report, so `asha.kumari` reads well and a UUID does not.
+Tokens expire. A string handed over at startup stops working mid-session, and
+the package has no way to ask for a fresh one.
 
-`creator` is **attribution, not identity**. It is recorded against anything the
-call creates and the usage report groups by it. Nothing verifies it — the
-gateway decides whether the call is allowed at all.
+```js
+getAuthHeaders: async () => ({ Authorization: `Bearer ${await auth.token()}` }),
+//              ^^^^^ called on every request, so a refreshed token just works
+```
 
-The package authenticates nobody and has no login of its own. You are already
-signed in, and you know who that is better than we could.
+The same goes for `creator`: a function lets you switch user without reloading
+the page.
+
+> **`creator` is attribution, not identity.** It is recorded against whatever
+> the call creates and the usage report groups by it. Nothing verifies it — the
+> gateway decides whether the call is allowed at all.
+>
+> Use `asha.kumari`, not a UUID. It appears as-is in the report.
 
 ---
 
@@ -301,7 +314,8 @@ features still work, but the revise step returns 403.
 
 ---
 
-## Theming
+<details>
+<summary><b>Theming with CSS custom properties</b></summary>
 
 CSS custom properties are the styling surface:
 
@@ -321,6 +335,10 @@ stylesheet is broad, scope it away from the three tags.
 
 ---
 
+</details>
+
+---
+
 ## Knowing when something failed
 
 The elements show their own error to the user. `onError` is the second copy, for
@@ -376,21 +394,7 @@ All are **starting values** the user can still change.
 </aastrika-content-studio>
 ```
 
-### One quiz, several languages
-
-`default-translate-into` produces the **same** questions in other languages —
-same order, same options, same answer key — so one answer key marks every
-language and scores compare across them.
-
-```html
-<aastrika-assessment default-language="hi" default-translate-into="en,mr">
-</aastrika-assessment>
-```
-
-The reviewer gets a tab per language. Excel holds every language, one sheet
-each; CSV holds one language at a time.
-
-`assessmentReady` reports what came back:
+### Translations, in the event
 
 ```js
 el.addEventListener('assessmentReady', (e) => {
@@ -401,8 +405,8 @@ el.addEventListener('assessmentReady', (e) => {
 
 `languages` can be shorter than what was asked for. A translation is checked for
 question count, ids, answer key, clinical numbers and script; one that fails is
-dropped rather than stored wrong. What is **not** checked is whether the
-translation reads well — that still needs someone who speaks the language.
+dropped rather than stored wrong. What is **not** checked is whether it reads
+well — that still needs someone who speaks the language.
 
 ### Events
 
@@ -429,7 +433,8 @@ any DOM event: `(videoReady)="onReady($event)"`.
 
 ---
 
-## When it does not work
+<details>
+<summary><b>Troubleshooting — symptom → cause</b></summary>
 
 | Symptom | Cause |
 |---|---|
@@ -443,11 +448,16 @@ any DOM event: `(videoReady)="onReady($event)"`.
 
 ---
 
+</details>
+
+---
+
 ## Browser support
 
 Any browser with Custom Elements v1 — everything since 2018.
 
-## Server rendering
+<details>
+<summary><b>Server rendering (Next.js, Angular Universal)</b></summary>
 
 **Import this package only in browser code.** It is not server-renderable, and
 the failure is a crash rather than an empty box: `@angular/elements` declares a
@@ -471,3 +481,8 @@ Angular Universal: keep the import inside a browser-only guard, or load it in
 Nothing is lost by this. The elements have no server-rendered output to hydrate
 — they fetch everything at runtime — so a client-only import renders exactly the
 same page.
+
+</details>
+
+---
+