psytools 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -169,6 +169,27 @@ Minimization is the default, at every layer:
169
169
 
170
170
  Merged definitions remain one self-contained JSON object — locale loading never breaks the `stringify → DB → parse` round trip.
171
171
 
172
+ ### Local translation overrides
173
+
174
+ The bundled translations are unverified AI output (see [Translation provenance](#important-notes) below) — you may want to reword a specific question, option label, or instruction locally without forking the inventory. `loadInventory` accepts `overrides`: one or more partial locale packs, applied **after** the built-in packs, later-wins:
175
+
176
+ ```ts
177
+ const phq9 = await loadInventory("phq9", {
178
+ locales: ["tr"],
179
+ overrides: {
180
+ id: "phq9",
181
+ locale: "tr",
182
+ // Only the bits you want to change — everything else keeps the
183
+ // bundled tr text (or falls back to English if tr was never loaded).
184
+ questions: {
185
+ "phq9-3": { text: "Uykuya dalmakta veya uykuyu sürdürmekte güçlük" },
186
+ },
187
+ },
188
+ });
189
+ ```
190
+
191
+ An override pack has the same shape as a bundled `InventoryLocalePack` (see [`applyLocale`](#data-minimization) above), but every field except `id`/`locale`/`questions` is optional, and `questions` only needs entries for what you're changing. Pass an array to apply several overrides in order; option-count mismatches and unknown question ids still throw `invalid_argument`, same as a bundled pack. This is a local, in-memory concern — psytools doesn't track override provenance or verification status; that's still on you and your own docs.
192
+
172
193
  ### Missing answers
173
194
 
174
195
  Declarative scoring takes an optional missing-data policy governing how incomplete answer sets are scored (they reach the scorer via raw answer maps or `allowIncomplete`):
@@ -183,6 +204,8 @@ scoring: {
183
204
 
184
205
  `ignore` sums what is answered (partial totals understate severity — use deliberately); `prorate` scales the raw score up to the full item count (rounded) and refuses to score below `minAnswered`; `require-complete` throws unless every contributing non-optional item is answered. For subscale scoring the policy applies to each subscale independently.
185
206
 
207
+ The bundled inventories ship with policies (PHQ-9/GAD-7/DASS-21/Mini-IPIP prorate with thresholds, WHO-5/ASRS/AQ-10 require-complete, AUDIT ignores to match its skip logic) — see [SOURCES.md](SOURCES.md#missing-data-policies) for the rationale and how to override.
208
+
186
209
  ## Custom evaluation
187
210
 
188
211
  Declarative scoring is optional. Pass an evaluator for anything beyond sums and subscales — it can return a single scale, multiple scales, a category, or arbitrary data:
@@ -222,7 +245,7 @@ const history = rows
222
245
  | `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
223
246
  | `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
224
247
  | `validateDefinition(input)` | Non-throwing structural validation of definitions |
225
- | `loadInventory(id, { locales? })` / `inventories` | Predefined instruments (async; English-only base definitions also exported by name) |
248
+ | `loadInventory(id, { locales?, overrides? })` / `inventories` | Predefined instruments (async; English-only base definitions also exported by name); `overrides` applies local partial locale packs after the built-in ones |
226
249
  | `applyLocale(definition, pack)` / `availableLocales(id)` / `localePacks` | Lazy per-inventory locale packs |
227
250
  | `localizeText(text, locale, fallback?)` / `collectLocales(texts)` / `pickLocales(definition, locales)` | Locale helpers |
228
251
  | `PsytoolsError` | All errors carry a `code` typed as `PsytoolsErrorCode` (e.g. `invalid_value`, `already_submitted`) |
@@ -240,7 +263,7 @@ npm run build # ESM + CJS + type declarations into dist/
240
263
  - **Not a diagnostic tool.** Scores, severity bands, and flags implement the published scoring rules of screening instruments; they are not diagnoses and do not replace clinical judgment.
241
264
  - **Crisis-relevant answers.** PHQ-9 item 9 raises a `suicidality` flag — applications should surface this to a responsible clinician and provide crisis resources to respondents.
242
265
  - **Instrument licensing.** [SOURCES.md](SOURCES.md) flags every bundled instrument as **Free** (PHQ-9, GAD-7, DASS-21, WHO-5 — usable without permission, including commercially) or **Free with conditions** (ASRS v1.1, AQ-10 — free for clinical/research use; verify with the rights holder before embedding in commercial products). Each inventory's `meta.licenseFlag` carries the same flag programmatically.
243
- - **Translation provenance.** English texts are reproduced from the original instruments. Turkish and German texts are AI translations (Anthropic Claude, model `claude-fable-5`) of the original English — official translations were **not** consulted and the texts are unverified; see [SOURCES.md](SOURCES.md). Obtain and compare the official version for your language before clinical use. Corrections: <samed@luckys.dev>.
266
+ - **Translation provenance.** English texts are reproduced from the original instruments. Turkish, German, Simplified Chinese, and Spanish texts are AI translations (Anthropic Claude, model `claude-fable-5`) of the original English — official translations were **not** consulted and the texts are unverified. This status is documentation-only: psytools does not track or expose per-pack verification programmatically (no `verified` field, no gating option, no status API) — read [SOURCES.md](SOURCES.md) and decide for yourself whether the bundled wording is fit for your use case. If it isn't for a specific item, use [local overrides](#local-translation-overrides) rather than forking the package. Obtain and compare the official version for your language before clinical use. Corrections: <samed@luckys.dev>.
244
267
 
245
268
  ## License
246
269
 
package/SOURCES.md CHANGED
@@ -28,6 +28,21 @@ Official validated translations exist for most of these instruments, but they we
28
28
 
29
29
  Non-English texts live as one file per inventory per language under [`src/locales/<locale>/`](src/locales) — exactly the unit a native-speaker reviewer needs. Verification contributions are very welcome.
30
30
 
31
+ This table is the only place translation status is tracked — psytools has no `verified` field, no gating option, and no API to query pack status at runtime; that would overstate a confidence level nobody has confirmed. If you've corrected a specific item's wording for your own use and don't want to wait on an upstream fix, apply it locally with `loadInventory(id, { overrides })` (see the README's [local translation overrides](README.md#local-translation-overrides)) rather than forking the package — or, better, send the correction upstream so everyone benefits.
32
+
33
+ ## Missing-data policies
34
+
35
+ Bundled inventories ship with declarative missing-data policies (`scoring.missing`). **The prorating thresholds are implementation choices reflecting common research practice — they are not part of the instruments' official scoring rules.** Override by cloning the definition if your protocol differs.
36
+
37
+ | Inventory | Policy | Rationale |
38
+ | --- | --- | --- |
39
+ | `phq9` | prorate, ≥7 of 9 answered | Common research practice (≈75% completion) |
40
+ | `gad7` | prorate, ≥6 of 7 answered | Common research practice |
41
+ | `dass21` | prorate, ≥6 of 7 per subscale | DASS manual tolerates occasional missing items |
42
+ | `mini-ipip` | prorate, ≥3 of 4 per trait | IPIP scoring is mean-based; prorating is equivalent |
43
+ | `who5`, `asrs6`, `aq10` | require-complete | Short instruments; cutoffs/counts are undefined for partial data |
44
+ | `audit` | ignore | Unanswered items score 0, matching the instrument's skip logic (e.g. non-drinkers skipping items 2–8) |
45
+
31
46
  ## PHQ-9 — Patient Health Questionnaire-9 (`phq9`)
32
47
 
33
48
  **License: Free.** Developed with an educational grant from Pfizer Inc. The copyright holders state that no permission is required to reproduce, translate, display, or distribute the PHQ screeners. Official repository: <https://www.phqscreeners.com>.
@@ -112,6 +112,7 @@ exports.aq10 = {
112
112
  ],
113
113
  scoring: {
114
114
  kind: "count",
115
+ missing: { strategy: "require-complete" },
115
116
  items: [
116
117
  { questionId: "aq10-1", minValue: 2 },
117
118
  { questionId: "aq10-2", minValue: 2 },
@@ -70,6 +70,7 @@ exports.asrs6 = {
70
70
  ],
71
71
  scoring: {
72
72
  kind: "count",
73
+ missing: { strategy: "require-complete" },
73
74
  items: [
74
75
  { questionId: "asrs6-1", minValue: 2 },
75
76
  { questionId: "asrs6-2", minValue: 2 },
@@ -169,6 +169,7 @@ exports.audit = {
169
169
  ],
170
170
  scoring: {
171
171
  kind: "sum",
172
+ missing: { strategy: "ignore" },
172
173
  bands: [
173
174
  {
174
175
  id: "zone-1",
@@ -200,6 +200,7 @@ exports.dass21 = {
200
200
  ],
201
201
  scoring: {
202
202
  kind: "subscales",
203
+ missing: { strategy: "prorate", minAnswered: 6 },
203
204
  subscales: [
204
205
  {
205
206
  id: "depression",
@@ -68,6 +68,7 @@ exports.gad7 = {
68
68
  ],
69
69
  scoring: {
70
70
  kind: "sum",
71
+ missing: { strategy: "prorate", minAnswered: 6 },
71
72
  bands: [
72
73
  {
73
74
  id: "minimal",
@@ -1,4 +1,4 @@
1
- import type { AssessmentDefinition } from "../types.ts";
1
+ import type { AssessmentDefinition, InventoryLocalePack } from "../types.ts";
2
2
  import { Assessment } from "../assessment.ts";
3
3
  import { phq9 } from "./phq9.ts";
4
4
  import { gad7 } from "./gad7.ts";
@@ -22,8 +22,16 @@ export type InventoryId = "phq9" | "gad7" | "dass21" | "who5" | "asrs6" | "aq10"
22
22
  * default). The returned assessment's definition is still one complete,
23
23
  * serializable JSON object containing exactly the requested locales.
24
24
  *
25
- * @throws PsytoolsError `unknown_inventory` | `unknown_locale`
25
+ * `options.overrides` applies one or more local, partial locale packs
26
+ * (same shape as the bundled ones) after the built-in packs, so a consumer
27
+ * can reword specific questions/options/instructions without forking the
28
+ * inventory. Later overrides win over earlier ones and over the built-in
29
+ * text; each is validated exactly like a bundled pack (unknown question
30
+ * ids and option-count mismatches still throw `invalid_argument`).
31
+ *
32
+ * @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
26
33
  */
27
34
  export declare function loadInventory(id: InventoryId | string, options?: {
28
35
  locales?: string[];
36
+ overrides?: InventoryLocalePack | InventoryLocalePack[];
29
37
  }): Promise<Assessment>;
@@ -45,7 +45,14 @@ exports.inventories = {
45
45
  * default). The returned assessment's definition is still one complete,
46
46
  * serializable JSON object containing exactly the requested locales.
47
47
  *
48
- * @throws PsytoolsError `unknown_inventory` | `unknown_locale`
48
+ * `options.overrides` applies one or more local, partial locale packs
49
+ * (same shape as the bundled ones) after the built-in packs, so a consumer
50
+ * can reword specific questions/options/instructions without forking the
51
+ * inventory. Later overrides win over earlier ones and over the built-in
52
+ * text; each is validated exactly like a bundled pack (unknown question
53
+ * ids and option-count mismatches still throw `invalid_argument`).
54
+ *
55
+ * @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
49
56
  */
50
57
  async function loadInventory(id, options) {
51
58
  const definition = exports.inventories[id];
@@ -63,5 +70,13 @@ async function loadInventory(id, options) {
63
70
  }
64
71
  merged = (0, i18n_ts_1.applyLocale)(merged, (await loader()).default);
65
72
  }
73
+ const overrides = options?.overrides
74
+ ? Array.isArray(options.overrides)
75
+ ? options.overrides
76
+ : [options.overrides]
77
+ : [];
78
+ for (const override of overrides) {
79
+ merged = (0, i18n_ts_1.applyLocale)(merged, override);
80
+ }
66
81
  return new assessment_ts_1.Assessment(merged);
67
82
  }
@@ -190,6 +190,7 @@ exports.miniIpip = {
190
190
  ],
191
191
  scoring: {
192
192
  kind: "subscales",
193
+ missing: { strategy: "prorate", minAnswered: 3 },
193
194
  subscales: [
194
195
  {
195
196
  id: "extraversion",
@@ -81,6 +81,7 @@ exports.phq9 = {
81
81
  ],
82
82
  scoring: {
83
83
  kind: "sum",
84
+ missing: { strategy: "prorate", minAnswered: 7 },
84
85
  bands: [
85
86
  {
86
87
  id: "minimal",
@@ -87,6 +87,7 @@ exports.who5 = {
87
87
  ],
88
88
  scoring: {
89
89
  kind: "sum",
90
+ missing: { strategy: "require-complete" },
90
91
  multiplier: 4,
91
92
  bands: [
92
93
  {
@@ -161,17 +161,21 @@ export interface AssessmentDefinition {
161
161
  * One language for one inventory, shipped as a separate lazily-loadable
162
162
  * module so that only requested locales are bundled and held in memory.
163
163
  * Merge into a base definition with `applyLocale`.
164
+ *
165
+ * Packs are partial: every field but `id`/`locale` is optional, so the same
166
+ * shape also works as a small local override (e.g. reword one question) via
167
+ * `loadInventory(id, { overrides })` — no need to restate the whole pack.
164
168
  */
165
169
  export interface InventoryLocalePack {
166
170
  /** Id of the inventory this pack translates. */
167
171
  id: string;
168
172
  /** BCP-47 language tag of the pack, e.g. `"tr"`. */
169
173
  locale: string;
170
- title: string;
174
+ title?: string;
171
175
  description?: string;
172
176
  instructions?: string;
173
- /** Labels of the assessment-level option scale, by option index. */
174
- options: string[];
177
+ /** Labels of the assessment-level option scale, by option index. Length must match the option scale's when present. */
178
+ options?: string[];
175
179
  /** Per-question texts (and option labels for question-level scales), by question id. */
176
180
  questions: Record<string, {
177
181
  text: string;
@@ -109,6 +109,7 @@ export const aq10 = {
109
109
  ],
110
110
  scoring: {
111
111
  kind: "count",
112
+ missing: { strategy: "require-complete" },
112
113
  items: [
113
114
  { questionId: "aq10-1", minValue: 2 },
114
115
  { questionId: "aq10-2", minValue: 2 },
@@ -67,6 +67,7 @@ export const asrs6 = {
67
67
  ],
68
68
  scoring: {
69
69
  kind: "count",
70
+ missing: { strategy: "require-complete" },
70
71
  items: [
71
72
  { questionId: "asrs6-1", minValue: 2 },
72
73
  { questionId: "asrs6-2", minValue: 2 },
@@ -166,6 +166,7 @@ export const audit = {
166
166
  ],
167
167
  scoring: {
168
168
  kind: "sum",
169
+ missing: { strategy: "ignore" },
169
170
  bands: [
170
171
  {
171
172
  id: "zone-1",
@@ -197,6 +197,7 @@ export const dass21 = {
197
197
  ],
198
198
  scoring: {
199
199
  kind: "subscales",
200
+ missing: { strategy: "prorate", minAnswered: 6 },
200
201
  subscales: [
201
202
  {
202
203
  id: "depression",
@@ -65,6 +65,7 @@ export const gad7 = {
65
65
  ],
66
66
  scoring: {
67
67
  kind: "sum",
68
+ missing: { strategy: "prorate", minAnswered: 6 },
68
69
  bands: [
69
70
  {
70
71
  id: "minimal",
@@ -1,4 +1,4 @@
1
- import type { AssessmentDefinition } from "../types.ts";
1
+ import type { AssessmentDefinition, InventoryLocalePack } from "../types.ts";
2
2
  import { Assessment } from "../assessment.ts";
3
3
  import { phq9 } from "./phq9.ts";
4
4
  import { gad7 } from "./gad7.ts";
@@ -22,8 +22,16 @@ export type InventoryId = "phq9" | "gad7" | "dass21" | "who5" | "asrs6" | "aq10"
22
22
  * default). The returned assessment's definition is still one complete,
23
23
  * serializable JSON object containing exactly the requested locales.
24
24
  *
25
- * @throws PsytoolsError `unknown_inventory` | `unknown_locale`
25
+ * `options.overrides` applies one or more local, partial locale packs
26
+ * (same shape as the bundled ones) after the built-in packs, so a consumer
27
+ * can reword specific questions/options/instructions without forking the
28
+ * inventory. Later overrides win over earlier ones and over the built-in
29
+ * text; each is validated exactly like a bundled pack (unknown question
30
+ * ids and option-count mismatches still throw `invalid_argument`).
31
+ *
32
+ * @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
26
33
  */
27
34
  export declare function loadInventory(id: InventoryId | string, options?: {
28
35
  locales?: string[];
36
+ overrides?: InventoryLocalePack | InventoryLocalePack[];
29
37
  }): Promise<Assessment>;
@@ -32,7 +32,14 @@ export const inventories = {
32
32
  * default). The returned assessment's definition is still one complete,
33
33
  * serializable JSON object containing exactly the requested locales.
34
34
  *
35
- * @throws PsytoolsError `unknown_inventory` | `unknown_locale`
35
+ * `options.overrides` applies one or more local, partial locale packs
36
+ * (same shape as the bundled ones) after the built-in packs, so a consumer
37
+ * can reword specific questions/options/instructions without forking the
38
+ * inventory. Later overrides win over earlier ones and over the built-in
39
+ * text; each is validated exactly like a bundled pack (unknown question
40
+ * ids and option-count mismatches still throw `invalid_argument`).
41
+ *
42
+ * @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
36
43
  */
37
44
  export async function loadInventory(id, options) {
38
45
  const definition = inventories[id];
@@ -50,5 +57,13 @@ export async function loadInventory(id, options) {
50
57
  }
51
58
  merged = applyLocale(merged, (await loader()).default);
52
59
  }
60
+ const overrides = options?.overrides
61
+ ? Array.isArray(options.overrides)
62
+ ? options.overrides
63
+ : [options.overrides]
64
+ : [];
65
+ for (const override of overrides) {
66
+ merged = applyLocale(merged, override);
67
+ }
53
68
  return new Assessment(merged);
54
69
  }
@@ -187,6 +187,7 @@ export const miniIpip = {
187
187
  ],
188
188
  scoring: {
189
189
  kind: "subscales",
190
+ missing: { strategy: "prorate", minAnswered: 3 },
190
191
  subscales: [
191
192
  {
192
193
  id: "extraversion",
@@ -78,6 +78,7 @@ export const phq9 = {
78
78
  ],
79
79
  scoring: {
80
80
  kind: "sum",
81
+ missing: { strategy: "prorate", minAnswered: 7 },
81
82
  bands: [
82
83
  {
83
84
  id: "minimal",
@@ -84,6 +84,7 @@ export const who5 = {
84
84
  ],
85
85
  scoring: {
86
86
  kind: "sum",
87
+ missing: { strategy: "require-complete" },
87
88
  multiplier: 4,
88
89
  bands: [
89
90
  {
@@ -161,17 +161,21 @@ export interface AssessmentDefinition {
161
161
  * One language for one inventory, shipped as a separate lazily-loadable
162
162
  * module so that only requested locales are bundled and held in memory.
163
163
  * Merge into a base definition with `applyLocale`.
164
+ *
165
+ * Packs are partial: every field but `id`/`locale` is optional, so the same
166
+ * shape also works as a small local override (e.g. reword one question) via
167
+ * `loadInventory(id, { overrides })` — no need to restate the whole pack.
164
168
  */
165
169
  export interface InventoryLocalePack {
166
170
  /** Id of the inventory this pack translates. */
167
171
  id: string;
168
172
  /** BCP-47 language tag of the pack, e.g. `"tr"`. */
169
173
  locale: string;
170
- title: string;
174
+ title?: string;
171
175
  description?: string;
172
176
  instructions?: string;
173
- /** Labels of the assessment-level option scale, by option index. */
174
- options: string[];
177
+ /** Labels of the assessment-level option scale, by option index. Length must match the option scale's when present. */
178
+ options?: string[];
175
179
  /** Per-question texts (and option labels for question-level scales), by question id. */
176
180
  questions: Record<string, {
177
181
  text: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "psytools",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
4
4
  "description": "Zero-dependency toolkit for psychological assessments: data models, response validation, scoring, and predefined inventories (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP) in multiple languages.",
5
5
  "keywords": [
6
6
  "psychology",
@@ -111,6 +111,7 @@ export const aq10: AssessmentDefinition = {
111
111
  ],
112
112
  scoring: {
113
113
  kind: "count",
114
+ missing: { strategy: "require-complete" },
114
115
  items: [
115
116
  { questionId: "aq10-1", minValue: 2 },
116
117
  { questionId: "aq10-2", minValue: 2 },
@@ -69,6 +69,7 @@ export const asrs6: AssessmentDefinition = {
69
69
  ],
70
70
  scoring: {
71
71
  kind: "count",
72
+ missing: { strategy: "require-complete" },
72
73
  items: [
73
74
  { questionId: "asrs6-1", minValue: 2 },
74
75
  { questionId: "asrs6-2", minValue: 2 },
@@ -170,6 +170,7 @@ export const audit: AssessmentDefinition = {
170
170
  ],
171
171
  scoring: {
172
172
  kind: "sum",
173
+ missing: { strategy: "ignore" },
173
174
  bands: [
174
175
  {
175
176
  id: "zone-1",
@@ -202,6 +202,7 @@ export const dass21: AssessmentDefinition = {
202
202
  ],
203
203
  scoring: {
204
204
  kind: "subscales",
205
+ missing: { strategy: "prorate", minAnswered: 6 },
205
206
  subscales: [
206
207
  {
207
208
  id: "depression",
@@ -67,6 +67,7 @@ export const gad7: AssessmentDefinition = {
67
67
  ],
68
68
  scoring: {
69
69
  kind: "sum",
70
+ missing: { strategy: "prorate", minAnswered: 6 },
70
71
  bands: [
71
72
  {
72
73
  id: "minimal",
@@ -1,4 +1,4 @@
1
- import type { AssessmentDefinition } from "../types.ts";
1
+ import type { AssessmentDefinition, InventoryLocalePack } from "../types.ts";
2
2
  import { Assessment } from "../assessment.ts";
3
3
  import { PsytoolsError } from "../errors.ts";
4
4
  import { applyLocale } from "../i18n.ts";
@@ -46,11 +46,18 @@ export type InventoryId =
46
46
  * default). The returned assessment's definition is still one complete,
47
47
  * serializable JSON object containing exactly the requested locales.
48
48
  *
49
- * @throws PsytoolsError `unknown_inventory` | `unknown_locale`
49
+ * `options.overrides` applies one or more local, partial locale packs
50
+ * (same shape as the bundled ones) after the built-in packs, so a consumer
51
+ * can reword specific questions/options/instructions without forking the
52
+ * inventory. Later overrides win over earlier ones and over the built-in
53
+ * text; each is validated exactly like a bundled pack (unknown question
54
+ * ids and option-count mismatches still throw `invalid_argument`).
55
+ *
56
+ * @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
50
57
  */
51
58
  export async function loadInventory(
52
59
  id: InventoryId | string,
53
- options?: { locales?: string[] },
60
+ options?: { locales?: string[]; overrides?: InventoryLocalePack | InventoryLocalePack[] },
54
61
  ): Promise<Assessment> {
55
62
  const definition = inventories[id];
56
63
  if (!definition) {
@@ -69,5 +76,13 @@ export async function loadInventory(
69
76
  }
70
77
  merged = applyLocale(merged, (await loader()).default);
71
78
  }
79
+ const overrides = options?.overrides
80
+ ? Array.isArray(options.overrides)
81
+ ? options.overrides
82
+ : [options.overrides]
83
+ : [];
84
+ for (const override of overrides) {
85
+ merged = applyLocale(merged, override);
86
+ }
72
87
  return new Assessment(merged);
73
88
  }
@@ -189,6 +189,7 @@ export const miniIpip: AssessmentDefinition = {
189
189
  ],
190
190
  scoring: {
191
191
  kind: "subscales",
192
+ missing: { strategy: "prorate", minAnswered: 3 },
192
193
  subscales: [
193
194
  {
194
195
  id: "extraversion",
@@ -80,6 +80,7 @@ export const phq9: AssessmentDefinition = {
80
80
  ],
81
81
  scoring: {
82
82
  kind: "sum",
83
+ missing: { strategy: "prorate", minAnswered: 7 },
83
84
  bands: [
84
85
  {
85
86
  id: "minimal",
@@ -86,6 +86,7 @@ export const who5: AssessmentDefinition = {
86
86
  ],
87
87
  scoring: {
88
88
  kind: "sum",
89
+ missing: { strategy: "require-complete" },
89
90
  multiplier: 4,
90
91
  bands: [
91
92
  {
package/src/types.ts CHANGED
@@ -176,17 +176,21 @@ export interface AssessmentDefinition {
176
176
  * One language for one inventory, shipped as a separate lazily-loadable
177
177
  * module so that only requested locales are bundled and held in memory.
178
178
  * Merge into a base definition with `applyLocale`.
179
+ *
180
+ * Packs are partial: every field but `id`/`locale` is optional, so the same
181
+ * shape also works as a small local override (e.g. reword one question) via
182
+ * `loadInventory(id, { overrides })` — no need to restate the whole pack.
179
183
  */
180
184
  export interface InventoryLocalePack {
181
185
  /** Id of the inventory this pack translates. */
182
186
  id: string;
183
187
  /** BCP-47 language tag of the pack, e.g. `"tr"`. */
184
188
  locale: string;
185
- title: string;
189
+ title?: string;
186
190
  description?: string;
187
191
  instructions?: string;
188
- /** Labels of the assessment-level option scale, by option index. */
189
- options: string[];
192
+ /** Labels of the assessment-level option scale, by option index. Length must match the option scale's when present. */
193
+ options?: string[];
190
194
  /** Per-question texts (and option labels for question-level scales), by question id. */
191
195
  questions: Record<string, { text: string; options?: string[] }>;
192
196
  /** Band labels by band id (sum and count scoring). */