@aastrika/ai-elements 0.3.0 → 0.4.0

package/README.md

@@ -1,44 +1,37 @@
-# @aastrika/ai-elements
+<div align="center">
 
-**Three Aastrika features as custom elements.** Works in React, Vue, Angular,
-Svelte or plain HTML.
+# @aastrika/ai-elements
 
-| 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)* |
+**Three AI features. Three HTML tags. Any framework.**
 
-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.
+[![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)
 
----
+</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,43 @@ 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">
 
-> **You also need gateway access.** The package authenticates nobody — see
-> [Access](#access) for the groups each feature requires.
+**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>
 
-## How it fits together
+> [!IMPORTANT]
+> **You also need gateway access.** This package authenticates nobody — your
+> gateway decides. See [Access](#access) for the groups each feature needs.
 
-```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
+## Where to look
 
-    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 |
+| **[Setup](#setup)** | Install · access · configure · mount |
+| **[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,45 +86,65 @@ 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.**
+
+```
+ upload ──▶ pick style ──▶ review the plan ──▶ generate ──▶ play / download
+            language        free, revisable      the only
+            voice           cost shown first     paid step
+```
+
+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.
 
-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.
+While it renders they see five-phase progress and a live log. At the end they
+can play it, download it, or delete it.
 
-[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/content-studio/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
 ### `<aastrika-assessment>`
 
-Files and links in, a validated multiple-choice set out — with control over
-language, question count, difficulty and Bloom level.
+**Training material goes in. A validated MCQ set comes out — in as many
+languages as you need.**
 
-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.
+```
+ files & links ──▶ settings ──▶ questions ──▶ review each ──▶ export
+                   language      checked       language on     xlsx / csv
+                   count         before you    its own tab
+                   difficulty    see them
+```
 
-[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/assessment/README.md)
+Every question is checked before it reaches the user: exactly one correct
+option, no duplicates, nothing the source material does not support.
+
+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/docs/API.md)
 
 ### `<aastrika-reports>`
 
-Who used what, and what it cost — totals for videos, assessments, people and
-estimated spend, split by tool, with a searchable table of creators.
+**Who made what, and what it cost.**
 
-**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.
+Totals for videos, assessments, people and estimated spend, split by tool, with
+a searchable table of creators.
 
-[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/reports/README.md)
+> [!WARNING]
+> **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)
 
 ---
 
 ## Setup
 
-The [Quick start](#quick-start) above is the whole integration. What each step
+The [Quick start](#ship-it-in-three-steps) above is the whole integration. What each step
 is actually doing:
 
 | | Step | Notes |
@@ -153,7 +156,8 @@ is actually doing:
 
 ---
 
-## Framework notes
+<details>
+<summary><b>React · Angular · Vue · plain HTML</b></summary>
 
 ### React
 
@@ -254,31 +258,79 @@ calling it, as above, prevents both.
 
 ---
 
+</details>
+
+---
+
+## How it fits together
+
+```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
+```
+
+**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.
+
+---
+
 ## 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.
+
+> [!NOTE]
+> **`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.
 
 ---
 
@@ -296,12 +348,14 @@ needs:
 Deleting anything needs `contentAdmin` as well. Without `contentUpdate` the
 features still work, but the revise step returns 403.
 
+> [!CAUTION]
 > **`generate-video` is the only call that spends real money**, and it sits on a
 > deliberately low rate limit. Users see a cost estimate before triggering it.
 
 ---
 
-## Theming
+<details>
+<summary><b>Theming with CSS custom properties</b></summary>
 
 CSS custom properties are the styling surface:
 
@@ -321,6 +375,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
@@ -429,7 +487,8 @@ any DOM event: `(videoReady)="onReady($event)"`.
 
 ---
 
-## When it does not work
+<details>
+<summary><b>Troubleshooting — symptom → cause</b></summary>
 
 | Symptom | Cause |
 |---|---|
@@ -443,11 +502,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 +535,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>
+
+---
+