psytools 0.5.3 → 0.6.0

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.
Files changed (64) hide show
  1. package/LICENSE +33 -0
  2. package/README.md +22 -4
  3. package/SOURCES.md +36 -2
  4. package/dist/cjs/index.d.ts +1 -1
  5. package/dist/cjs/inventories/aq10.js +2 -0
  6. package/dist/cjs/inventories/asrs6.d.ts +12 -5
  7. package/dist/cjs/inventories/asrs6.js +16 -6
  8. package/dist/cjs/inventories/audit.js +2 -0
  9. package/dist/cjs/inventories/cesd.js +2 -0
  10. package/dist/cjs/inventories/dass21.js +2 -0
  11. package/dist/cjs/inventories/ecr-r.js +2 -0
  12. package/dist/cjs/inventories/erq.js +2 -0
  13. package/dist/cjs/inventories/flourishing.js +2 -0
  14. package/dist/cjs/inventories/gad7.js +2 -0
  15. package/dist/cjs/inventories/hsps.js +2 -0
  16. package/dist/cjs/inventories/k10.js +2 -0
  17. package/dist/cjs/inventories/k6.js +2 -0
  18. package/dist/cjs/inventories/mini-ipip.js +2 -0
  19. package/dist/cjs/inventories/phq9.js +2 -0
  20. package/dist/cjs/inventories/rses.js +2 -0
  21. package/dist/cjs/inventories/swls.js +2 -0
  22. package/dist/cjs/inventories/who5.js +2 -0
  23. package/dist/cjs/types.d.ts +40 -0
  24. package/dist/esm/index.d.ts +1 -1
  25. package/dist/esm/inventories/aq10.js +2 -0
  26. package/dist/esm/inventories/asrs6.d.ts +12 -5
  27. package/dist/esm/inventories/asrs6.js +16 -6
  28. package/dist/esm/inventories/audit.js +2 -0
  29. package/dist/esm/inventories/cesd.js +2 -0
  30. package/dist/esm/inventories/dass21.js +2 -0
  31. package/dist/esm/inventories/ecr-r.js +2 -0
  32. package/dist/esm/inventories/erq.js +2 -0
  33. package/dist/esm/inventories/flourishing.js +2 -0
  34. package/dist/esm/inventories/gad7.js +2 -0
  35. package/dist/esm/inventories/hsps.js +2 -0
  36. package/dist/esm/inventories/k10.js +2 -0
  37. package/dist/esm/inventories/k6.js +2 -0
  38. package/dist/esm/inventories/mini-ipip.js +2 -0
  39. package/dist/esm/inventories/phq9.js +2 -0
  40. package/dist/esm/inventories/rses.js +2 -0
  41. package/dist/esm/inventories/swls.js +2 -0
  42. package/dist/esm/inventories/who5.js +2 -0
  43. package/dist/esm/types.d.ts +40 -0
  44. package/package.json +2 -2
  45. package/schema/assessment-definition.schema.json +11 -0
  46. package/src/index.ts +2 -0
  47. package/src/inventories/aq10.ts +2 -0
  48. package/src/inventories/asrs6.ts +17 -6
  49. package/src/inventories/audit.ts +2 -0
  50. package/src/inventories/cesd.ts +2 -0
  51. package/src/inventories/dass21.ts +2 -0
  52. package/src/inventories/ecr-r.ts +2 -0
  53. package/src/inventories/erq.ts +2 -0
  54. package/src/inventories/flourishing.ts +2 -0
  55. package/src/inventories/gad7.ts +2 -0
  56. package/src/inventories/hsps.ts +2 -0
  57. package/src/inventories/k10.ts +2 -0
  58. package/src/inventories/k6.ts +2 -0
  59. package/src/inventories/mini-ipip.ts +2 -0
  60. package/src/inventories/phq9.ts +2 -0
  61. package/src/inventories/rses.ts +2 -0
  62. package/src/inventories/swls.ts +2 -0
  63. package/src/inventories/who5.ts +2 -0
  64. package/src/types.ts +42 -0
package/LICENSE CHANGED
@@ -1,3 +1,30 @@
1
+ This repository ships two different things, licensed differently.
2
+
3
+ The code — the TypeScript source, compiled output, type definitions,
4
+ scoring engine, validation, localization logic, and JSON Schema,
5
+ everything that makes psytools run — is licensed under the MIT
6
+ License below. Copyright (c) 2026 Samed Kahyaoglu.
7
+
8
+ The bundled instrument text — the titles, descriptions, instructions,
9
+ item wording, and answer-option labels of the seventeen third-party
10
+ psychological assessment instruments psytools ships, in every
11
+ language psytools provides them — is licensed by each instrument's
12
+ own rights holder, on the terms recorded instrument by instrument in
13
+ SOURCES.md. SOURCES.md, not the MIT License below, is where your
14
+ rights over any specific instrument's text come from.
15
+
16
+ Most bundled instruments are free to use, including in commercial
17
+ products. Some carry conditions of their own — mandatory attribution,
18
+ or other limits on what "free" covers. Three of them, the ECR-R, the
19
+ ERQ, and the HSPS, are licensed for non-commercial research only.
20
+ Read SOURCES.md before you rely on any instrument's text, particularly
21
+ before commercial use.
22
+
23
+ The MIT License below is the license for the code. The bundled
24
+ instrument text is licensed as described above, not under this MIT
25
+ grant.
26
+
27
+
1
28
  MIT License
2
29
 
3
30
  Copyright (c) 2026 Samed Kahyaoglu
@@ -19,3 +46,9 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
46
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
47
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
48
  SOFTWARE.
49
+
50
+
51
+ "The Software" above means the code described above — psytools' own
52
+ source, build output, and documentation. Rights over the bundled
53
+ instrument text come from that text's own rights holder, per
54
+ SOURCES.md.
package/README.md CHANGED
@@ -19,7 +19,7 @@ That's a complete depression screening: standardized items, answer validation, p
19
19
 
20
20
  ## Why psytools
21
21
 
22
- - **Batteries included** — seventeen instruments (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP, CES-D, ECR-R, ERQ, HSPS, SWLS, Flourishing, K10, K6, RSES) ship ready to use in up to five languages (English, Turkish, German, Chinese, Spanish — see the table below), with published scoring rules, citations, and categories for filtering.
22
+ - **Batteries included** — seventeen instruments (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP, CES-D, ECR-R, ERQ, HSPS, SWLS, Flourishing, K10, K6, RSES) ship ready to use in up to five languages (English, Turkish, German, Chinese, Spanish — see the table below), with published scoring rules, citations, and filtering metadata (category, target audience, respondent role).
23
23
  - **Your tests too** — therapists and researchers can define their own instruments as one plain JSON object; psytools validates, localizes, and scores them the same way.
24
24
  - **Everything is plain JSON** — assessments and responses `stringify()`/`parse()` losslessly, so definitions live in your database and travel between backend and frontend. Scoring rules are data, not code, and survive the round trip.
25
25
  - **Safe by default** — every answer is validated against the option scale, incomplete responses can't be scored accidentally, and submitted responses are immutable.
@@ -101,7 +101,7 @@ const response = AssessmentResponse.parse(assessment, rowFromDb); // answers re-
101
101
  | `k6` | Kessler Psychological Distress Scale (K6) | distress | 6 | Sum 0–24 (0–4 coding), ≥13 serious distress | en, tr, de, zh, es |
102
102
  | `rses` | Rosenberg Self-Esteem Scale | self-esteem | 10 | Sum 0–30, 5 reverse-keyed items, 15–25 normal range | en, tr, de, zh, es |
103
103
 
104
- ¹ The `ecr-r` and `hsps` Turkish packs reproduce **published, validated Turkish adaptations** (Sümer and colleagues — see [SOURCES.md](SOURCES.md)); other locales can follow once verified sources are available. `ecr-r`, `erq`, and `hsps` are licensed for **non-commercial research use only** — check [SOURCES.md](SOURCES.md) before shipping them in a product. Each definition also carries `categories` for filtering (e.g. `inventories` entries with `categories.includes("depression")`).
104
+ ¹ The `ecr-r` and `hsps` Turkish packs reproduce **published, validated Turkish adaptations** (Sümer and colleagues — see [SOURCES.md](SOURCES.md)); other locales can follow once verified sources are available. `ecr-r`, `erq`, and `hsps` are licensed for **non-commercial research use only** — check [SOURCES.md](SOURCES.md) before shipping them in a product. `asrs6` is free to ship, commercially included, but its license makes attribution mandatory: render `meta.attribution` wherever it appears.
105
105
 
106
106
  ```ts
107
107
  import { loadInventory, inventories, dass21 } from "psytools";
@@ -121,6 +121,14 @@ const result = assessment.evaluate(response);
121
121
  // ], flags: [] }
122
122
  ```
123
123
 
124
+ ### Filtering metadata
125
+
126
+ Every definition carries three optional fields for picking the right instrument: `categories` (what it measures — e.g. `inventories` entries with `categories.includes("depression")`), `audience` (the age band(s) it is written and validated for — `adult`, `adolescent`, `child`), and `respondent` (whose report the answers are — `self`, `parent`, `teacher`, `clinician`). Bundled inventories draw from the vocabularies exported as `InventoryCategory`, `InventoryAudience`, and `InventoryRespondent`; the fields themselves are plain strings, so your own definitions can use their own taxonomy.
127
+
128
+ Audience and respondent are separate axes because instruments *about* children are commonly filled in by someone else — a parent-report ADHD scale is `audience: ["child"]`, `respondent: "parent"`. `audience` is an array, since one wording is often validated across bands; `respondent` is a single value, since a definition is written from exactly one point of view. Parent- and teacher-report forms of the same instrument say "your child" and "this student", so they are separate definitions with separate ids, not one definition with two respondents.
129
+
130
+ Neither field encodes the recall timeframe or the administration mode: a retrospective instrument answered by an adult about their own childhood is `["adult"]` + `"self"`, with the childhood framing in `instructions`, and a clinician reading items aloud to a client is still `"self"` because the answers are the client's own report. Every bundled inventory is `respondent: "self"` and `audience: ["adult"]`, except `rses` — Rosenberg developed the scale on high-school students and the same ten items are standard for both bands, so it is `["adolescent", "adult"]`.
131
+
124
132
  ## Defining your own assessment
125
133
 
126
134
  An assessment is one plain object — questions, an enumerated option scale, and optional declarative scoring:
@@ -273,9 +281,19 @@ npm run build # ESM + CJS + type declarations into dist/
273
281
 
274
282
  - **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.
275
283
  - **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.
276
- - **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.
284
+ - **Instrument licensing.** [SOURCES.md](SOURCES.md) records who holds the rights to each bundled instrument and flags it **Free** (PHQ-9, GAD-7, DASS-21, WHO-5, AUDIT, Mini-IPIP, CES-D, K10, K6 — usable without permission, including commercially), **Free with conditions** (ASRS screener, AQ-10, SWLS, Flourishing Scale, RSES — free as distributed, but the conditions differ per instrument: the ASRS screener requires attribution, the AQ-10's commercial terms are unstated), or **Research only** (ECR-R, ERQ, HSPS — not licensed for clinical products or personnel selection). Each inventory's `meta.licenseFlag` carries the flag programmatically; read the instrument's section before shipping it.
285
+ - **Required attribution.** Where a license fixes the exact credit line that must be displayed, the inventory carries it verbatim in `meta.attribution` — render it wherever the instrument or its results appear. Today only `asrs6` sets it (© New York University and the President and Fellows of Harvard College). It is deliberately separate from `meta.reference`, which is the scientific citation: an academic reference is not a copyright attribution, and only one of the two is a license obligation.
277
286
  - **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>.
278
287
 
279
288
  ## License
280
289
 
281
- MIT
290
+ The code is MIT — Samed Kahyaoglu, 2026. See [LICENSE](LICENSE).
291
+
292
+ The bundled instrument text is a separate matter: each of the seventeen instruments is licensed by its own rights holder, on terms that differ instrument to instrument. The quick answer:
293
+
294
+ - **Nine ship free, including in commercial products, no permission needed:** PHQ-9, GAD-7, DASS-21, WHO-5, AUDIT, Mini-IPIP, CES-D, K10, K6.
295
+ - **The ASRS-v1.1 screener (`asrs6`) ships free, including commercially, with one mandatory condition — attribution.** Render the credit line psytools ships in `meta.attribution` wherever the screener or its results appear.
296
+ - **Three ship for non-commercial research only: ECR-R, ERQ, and HSPS.** Commercial use of any of these needs permission directly from that instrument's own rights holder (R. C. Fraley for the ECR-R; the Stanford Psychophysiology Laboratory for the ERQ; Elaine Aron for the HSPS) — that permission is theirs to give, not psytools'.
297
+ - **AQ-10, RSES, SWLS, and the Flourishing Scale ship free with conditions of their own, and the conditions aren't uniform.** AQ-10's and RSES's rights holders haven't addressed commercial use (confirm with them before shipping commercially). SWLS's and the Flourishing Scale's rights holder (Ed Diener and co-authors) licenses them for non-commercial purposes only — treat those two like the research-only three for commercial shipping.
298
+
299
+ [SOURCES.md](SOURCES.md) has the full record for every instrument — rights holder, citation, exact conditions, translation provenance. Read the relevant section before you ship an instrument, especially any instrument outside the first two bullets above.
package/SOURCES.md CHANGED
@@ -9,7 +9,7 @@ psytools is integrated into real products, so this file states precisely — per
9
9
  | Flag | Meaning |
10
10
  | --- | --- |
11
11
  | **Free** | Public domain or explicitly free for any use, including commercial products, without permission. |
12
- | **Free with conditions** | Free for clinical and research use as distributed; embedding in commercial products is not explicitly licensed — verify with the rights holder before shipping. |
12
+ | **Free with conditions** | Free to use as distributed, but the rights holder attaches conditions — mandatory attribution, limits on modification, or commercial terms that are simply unstated. The conditions differ per instrument, so read that instrument's section below before shipping. |
13
13
  | **Research only** | Usable in non-commercial research contexts only; not licensed for clinical products, diagnosis, or personnel selection. Carried by the ECR-R, ERQ, and HSPS — see their sections. |
14
14
 
15
15
  ## Translation provenance — read this before clinical use
@@ -32,6 +32,17 @@ Non-English texts live as one file per inventory per language under [`src/locale
32
32
 
33
33
  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.
34
34
 
35
+ ## Target audience & respondent
36
+
37
+ Each inventory declares two independent axes in its definition: `audience`, the age band(s) the instrument is written and validated for — who it is *about* — and `respondent`, whose report the answers are. They are separate because instruments about children are commonly completed by a parent or a teacher rather than by the child.
38
+
39
+ **Every bundled inventory is `respondent: "self"` and `audience: ["adult"]`, except where its section below states otherwise.** One deviates today: the RSES is `["adolescent", "adult"]`.
40
+
41
+ Two things `audience` and `respondent` deliberately do *not* encode:
42
+
43
+ - **The recall timeframe.** A retrospective instrument answered by an adult about their own childhood is `audience: ["adult"]`, `respondent: "self"` — the childhood framing lives in `instructions` and `meta.timeframe`, not here.
44
+ - **The administration mode.** An interviewer-read self-report — the K10's full interview form, for example — is still `respondent: "self"`, because the answers are the client's own report. `"clinician"` is reserved for instruments where the clinician is the informant, rating the client from their own observation.
45
+
35
46
  ## Missing-data policies
36
47
 
37
48
  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.
@@ -95,17 +106,26 @@ Bundled inventories ship with declarative missing-data policies (`scoring.missin
95
106
 
96
107
  ## ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (`asrs6`)
97
108
 
98
- **License: Free with conditions.** Copyright is held by the World Health Organization and the Workgroup on Adult ADHD (Harvard Medical School / NYU). The screener is distributed free of charge for clinical and research use. Embedding in commercial products is not explicitly covered by the public distribution terms — verify with the rights holders (Harvard NCS/ASRS distribution) before shipping commercially.
109
+ **License: Free with conditions.** Copyright is held by **New York University and the President and Fellows of Harvard College**; licensing is administered by NYU Technology Opportunities & Ventures (<https://license.tov.med.nyu.edu/product/asrs6Qscreener>). The WHO's name is in the instrument's title, not on its copyright. The licensing page states: "The screener is freely available for clinical and non-clinical use, including commercial use, but does require attribution. This is an evidence-based tool, and as such no other modifications, other than creating electronic versions, are permitted." Commercial use therefore needs no separate permission; the two conditions below are what the flag refers to.
110
+
111
+ - **Attribution is mandatory.** Display this credit line, verbatim, wherever the screener or its results appear. It ships in `meta.attribution` so applications can render it:
99
112
 
113
+ > The 6-question Adult Self-Report Scale-Version1.1 (ASRS-V1.1) Screener is a subset of the 18-question Adult ADHD Self-Report Scale-Version1.1 (Adult ASRSV1.1) Symptom Checklist. © New York University and the President and Fellows of Harvard College.
114
+
115
+ This is the copyright attribution the license demands, which is a different thing from the scientific citation below — hence two fields, `meta.attribution` and `meta.reference`.
116
+ - **Whether translation is a permitted "modification" is unresolved.** The license permits no modifications "other than creating electronic versions" and says nothing about translation in either direction. psytools ships `asrs6` in tr, de, zh, and es as AI translations, so their standing under that clause is an open question. Settling it takes a direct question to NYU TOV, which has not been put to them yet; this file will be updated when there is an answer. One fact that bears on it without settling it: NYU TOV distributes its own official translations of the screener in about fifteen languages (Arabic, Chinese, Dutch, French, German, Hebrew, Italian, Japanese, Norwegian, Portuguese, Russian, Serbian, Spanish, Swedish, Thai — Turkish is not among them). A rights holder that maintains its own translations cuts somewhat against reading third-party translation as freely permitted. The English text is unaffected either way.
100
117
  - **Citation:** Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): A short screening scale for use in the general population. *Psychological Medicine, 35*(2), 245–256.
101
118
  - **Scoring:** Count of screen-positive items (items 1–3 from "Sometimes", items 4–6 from "Often"); ≥4 positives = positive screen, per the ASRS-v1.1 screener key.
102
119
 
120
+ *Correction, 2026-07-29:* psytools up to and including 0.5.3 named the World Health Organization and the Workgroup on Adult ADHD as the rights holders, carried no attribution, and hedged on commercial use. All three were wrong. The record above follows the rights holder's current licensing page.
121
+
103
122
  ## AQ-10 — Autism Spectrum Quotient, 10-item adult version (`aq10`)
104
123
 
105
124
  **License: Free with conditions.** Copyright is held by the Autism Research Centre (ARC), University of Cambridge. ARC distributes its measures free of charge and the AQ-10 is recommended by NICE (CG142) for adult screening in clinical practice. Commercial redistribution is not explicitly licensed — verify with ARC before shipping commercially.
106
125
 
107
126
  - **Citation:** Allison, C., Auyeung, B., & Baron-Cohen, S. (2012). Toward brief "Red Flags" for autism screening: The Short Autism Spectrum Quotient and the Short Quantitative Checklist in 1,000 cases and 3,000 controls. *Journal of the American Academy of Child & Adolescent Psychiatry, 51*(2), 202–212.
108
127
  - **Scoring:** 1 point per item in the trait direction (agree on items 1, 7, 8, 10; disagree on the rest); ≥6 suggests specialist referral, per Allison et al. (2012).
128
+ - **Audience:** Allison et al. (2012) published three AQ-10 forms — adult, adolescent, and child. psytools bundles the **adult self-report** form only (`audience: ["adult"]`, `respondent: "self"`); the adolescent and child forms are completed by a parent and are not included.
109
129
 
110
130
  ## CES-D — Center for Epidemiologic Studies Depression Scale (`cesd`)
111
131
 
@@ -172,3 +192,17 @@ Bundled inventories ship with declarative missing-data policies (`scoring.missin
172
192
 
173
193
  - **Citation:** Rosenberg, M. (1965). *Society and the Adolescent Self-Image.* Princeton, NJ: Princeton University Press.
174
194
  - **Scoring:** Items scored 0–3 (Strongly disagree = 0 … Strongly agree = 3), items 2, 5, 6, 8, 9 reverse-scored, sum 0–30. Scores 15–25 are commonly described as the normal range (University of Maryland scoring guidance).
195
+ - **Audience — deviates from the default:** `audience: ["adolescent", "adult"]`. Rosenberg developed the scale on high-school students (*Society and the Adolescent Self-Image*), and the same ten items are the standard self-esteem measure for adolescents and adults alike — the wording does not change between bands.
196
+
197
+ ## Instruments evaluated and not bundled
198
+
199
+ Instruments considered for inclusion and not shipped, each checked against the rights holder's own published terms. Recorded so the same ground is not covered twice. Today's entries all come from one sweep of widely used ADHD instruments (July 2026); five are blocked by their licensing and one is waiting on a permission request.
200
+
201
+ - **ASRS v1.1, full 18-item Symptom Checklist** — © New York University and the President and Fellows of Harvard College. A separate product on the same NYU TOV platform from the 6-item screener, and the screener's free-commercial grant does not extend to it: clinical use is routed to a different site, research use requires an institutional signatory, and no commercial tier is offered. Not bundled.
202
+ - **ASRS-5 (DSM-5-aligned, 6 items)** — © New York University / NYU Langone Health. A different instrument from the v1.1 screener despite the similar name and length. Only a research-and-academic license is publicly offered, and the rights holder's own product listing calls the scoring rules proprietary. Not bundled.
203
+ - **WURS-25 (Wender Utah Rating Scale)** — American Psychiatric Association Publishing (*American Journal of Psychiatry*, 1993). No free-redistribution grant could be found; the "public domain" claim repeated across the web traces to no source. Not bundled.
204
+ - **SNAP-IV** — James M. Swanson / University of California, Irvine. Neither the instrument nor the developer's own published history of the scale carries a copyright or license statement at all. The absence of a grant is not a grant. Not bundled.
205
+ - **NICHQ Vanderbilt Assessment Scales (parent and teacher forms)** — © 2012 American Academy of Pediatrics, printed "All Rights Reserved" on the instrument. Free to download and administer, which is not the same as licensed to redistribute inside a package. Not bundled.
206
+ - **WFIRS-P / WFIRS-S (Weiss Functional Impairment Rating Scale)** — © Margaret Danielle Weiss, MD PhD. Permissive terms, but the notice asks that the author be contacted before translation. **Blocked on a permission request we intend to make, not on a refusal** — so this one may yet arrive.
207
+
208
+ Hold rights to any of these, or know of a grant we missed? Please write to <samed@luckys.dev> — a correction here is as welcome as one to a bundled instrument.
@@ -1,4 +1,4 @@
1
- export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, InventoryCategory, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, MissingDataPolicy, MissingDataStrategy, ScoringDefinition, ValidationIssueCode, AnswerMap, InventoryLocalePack, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
1
+ export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, InventoryCategory, InventoryAudience, InventoryRespondent, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, MissingDataPolicy, MissingDataStrategy, ScoringDefinition, ValidationIssueCode, AnswerMap, InventoryLocalePack, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
2
2
  export { PsytoolsError } from "./errors.ts";
3
3
  export type { PsytoolsErrorCode } from "./errors.ts";
4
4
  export { localizeText, collectLocales, pickLocales, applyLocale } from "./i18n.ts";
@@ -15,6 +15,8 @@ exports.aq10 = {
15
15
  id: "aq10",
16
16
  version: "1.0.0",
17
17
  categories: ["autism"],
18
+ audience: ["adult"],
19
+ respondent: "self",
18
20
  title: {
19
21
  en: "Autism Spectrum Quotient (AQ-10) — Adult",
20
22
  },
@@ -2,10 +2,17 @@ import type { AssessmentDefinition } from "../types.ts";
2
2
  /**
3
3
  * ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (Part A).
4
4
  *
5
- * Developed by the WHO and the Workgroup on Adult ADHD (Harvard Medical
6
- * School / NYU). Items 1–3 count as screen-positive from "Sometimes" and
7
- * items 4–6 from "Often"; four or more positive items indicate symptoms
8
- * highly consistent with adult ADHD and warrant further investigation
9
- * (Kessler et al., 2005). Free to distribute and score.
5
+ * A subset of the 18-question ASRS v1.1 Symptom Checklist, developed with the
6
+ * WHO's Workgroup on Adult ADHD. Items 1–3 count as screen-positive from
7
+ * "Sometimes" and items 4–6 from "Often"; four or more positive items indicate
8
+ * symptoms highly consistent with adult ADHD and warrant further investigation
9
+ * (Kessler et al., 2005).
10
+ *
11
+ * Copyright is held by New York University and the President and Fellows of
12
+ * Harvard College, and licensing is administered by NYU Technology
13
+ * Opportunities & Ventures — not by the WHO. Free for clinical, non-clinical
14
+ * and commercial use, but attribution is mandatory: render `meta.attribution`
15
+ * verbatim wherever the screener or its results appear. See `meta.license` for
16
+ * the open question about translation.
10
17
  */
11
18
  export declare const asrs6: AssessmentDefinition;
@@ -4,16 +4,25 @@ exports.asrs6 = void 0;
4
4
  /**
5
5
  * ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (Part A).
6
6
  *
7
- * Developed by the WHO and the Workgroup on Adult ADHD (Harvard Medical
8
- * School / NYU). Items 1–3 count as screen-positive from "Sometimes" and
9
- * items 4–6 from "Often"; four or more positive items indicate symptoms
10
- * highly consistent with adult ADHD and warrant further investigation
11
- * (Kessler et al., 2005). Free to distribute and score.
7
+ * A subset of the 18-question ASRS v1.1 Symptom Checklist, developed with the
8
+ * WHO's Workgroup on Adult ADHD. Items 1–3 count as screen-positive from
9
+ * "Sometimes" and items 4–6 from "Often"; four or more positive items indicate
10
+ * symptoms highly consistent with adult ADHD and warrant further investigation
11
+ * (Kessler et al., 2005).
12
+ *
13
+ * Copyright is held by New York University and the President and Fellows of
14
+ * Harvard College, and licensing is administered by NYU Technology
15
+ * Opportunities & Ventures — not by the WHO. Free for clinical, non-clinical
16
+ * and commercial use, but attribution is mandatory: render `meta.attribution`
17
+ * verbatim wherever the screener or its results appear. See `meta.license` for
18
+ * the open question about translation.
12
19
  */
13
20
  exports.asrs6 = {
14
21
  id: "asrs6",
15
22
  version: "1.0.0",
16
23
  categories: ["adhd"],
24
+ audience: ["adult"],
25
+ respondent: "self",
17
26
  title: {
18
27
  en: "Adult ADHD Self-Report Scale (ASRS-v1.1) Screener",
19
28
  },
@@ -101,7 +110,8 @@ exports.asrs6 = {
101
110
  },
102
111
  meta: {
103
112
  reference: "Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): a short screening scale for use in the general population. Psychological Medicine, 35(2), 245-256.",
104
- license: "Free with conditions — (c) WHO / Workgroup on Adult ADHD; free for clinical and research use. Verify licensing with the rights holders before embedding in commercial products.",
113
+ attribution: "The 6-question Adult Self-Report Scale-Version1.1 (ASRS-V1.1) Screener is a subset of the 18-question Adult ADHD Self-Report Scale-Version1.1 (Adult ASRSV1.1) Symptom Checklist. © New York University and the President and Fellows of Harvard College.",
114
+ license: "Free with conditions — © New York University and the President and Fellows of Harvard College; licensing administered by NYU Technology Opportunities & Ventures (license.tov.med.nyu.edu/product/asrs6Qscreener). Freely available for clinical and non-clinical use, including commercial use, but attribution is required: display meta.attribution verbatim wherever the screener or its results appear. No modifications other than creating electronic versions are permitted, and the license does not say whether translation is a modification — so the standing of the bundled tr/de/zh/es translations is unresolved, pending a question to NYU TOV. See SOURCES.md.",
105
115
  licenseFlag: "free-with-conditions",
106
116
  translationProvenance: "en: reproduced from the original. Other locales (tr, de, zh, es): AI translation (Anthropic Claude, claude-fable-5) from the original English; official translations were not consulted and the texts are unverified. See SOURCES.md.",
107
117
  timeframe: "past 6 months",
@@ -54,6 +54,8 @@ exports.audit = {
54
54
  id: "audit",
55
55
  version: "1.0.0",
56
56
  categories: ["substance-use"],
57
+ audience: ["adult"],
58
+ respondent: "self",
57
59
  title: {
58
60
  en: "Alcohol Use Disorders Identification Test (AUDIT)",
59
61
  },
@@ -14,6 +14,8 @@ exports.cesd = {
14
14
  id: "cesd",
15
15
  version: "1.0.0",
16
16
  categories: ["depression"],
17
+ audience: ["adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "Center for Epidemiologic Studies Depression Scale (CES-D)",
19
21
  },
@@ -35,6 +35,8 @@ exports.dass21 = {
35
35
  id: "dass21",
36
36
  version: "1.0.0",
37
37
  categories: ["depression", "anxiety", "stress"],
38
+ audience: ["adult"],
39
+ respondent: "self",
38
40
  title: {
39
41
  en: "Depression Anxiety Stress Scales (DASS-21)",
40
42
  },
@@ -28,6 +28,8 @@ exports.ecrR = {
28
28
  id: "ecr-r",
29
29
  version: "1.0.0",
30
30
  categories: ["attachment", "relationships"],
31
+ audience: ["adult"],
32
+ respondent: "self",
31
33
  title: {
32
34
  en: "Experiences in Close Relationships-Revised (ECR-R)",
33
35
  },
@@ -28,6 +28,8 @@ exports.erq = {
28
28
  id: "erq",
29
29
  version: "1.0.0",
30
30
  categories: ["emotion-regulation"],
31
+ audience: ["adult"],
32
+ respondent: "self",
31
33
  title: {
32
34
  en: "Emotion Regulation Questionnaire (ERQ)",
33
35
  },
@@ -16,6 +16,8 @@ exports.flourishing = {
16
16
  id: "flourishing",
17
17
  version: "1.0.0",
18
18
  categories: ["well-being"],
19
+ audience: ["adult"],
20
+ respondent: "self",
19
21
  title: {
20
22
  en: "Flourishing Scale (FS)",
21
23
  },
@@ -14,6 +14,8 @@ exports.gad7 = {
14
14
  id: "gad7",
15
15
  version: "1.0.0",
16
16
  categories: ["anxiety"],
17
+ audience: ["adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "Generalized Anxiety Disorder Scale (GAD-7)",
19
21
  },
@@ -26,6 +26,8 @@ exports.hsps = {
26
26
  id: "hsps",
27
27
  version: "1.0.0",
28
28
  categories: ["sensory-processing", "personality"],
29
+ audience: ["adult"],
30
+ respondent: "self",
29
31
  title: {
30
32
  en: "Highly Sensitive Person Scale (HSPS)",
31
33
  },
@@ -16,6 +16,8 @@ exports.k10 = {
16
16
  id: "k10",
17
17
  version: "1.0.0",
18
18
  categories: ["distress"],
19
+ audience: ["adult"],
20
+ respondent: "self",
19
21
  title: {
20
22
  en: "Kessler Psychological Distress Scale (K10)",
21
23
  },
@@ -16,6 +16,8 @@ exports.k6 = {
16
16
  id: "k6",
17
17
  version: "1.0.0",
18
18
  categories: ["distress"],
19
+ audience: ["adult"],
20
+ respondent: "self",
19
21
  title: {
20
22
  en: "Kessler Psychological Distress Scale (K6)",
21
23
  },
@@ -14,6 +14,8 @@ exports.miniIpip = {
14
14
  id: "mini-ipip",
15
15
  version: "1.0.0",
16
16
  categories: ["personality"],
17
+ audience: ["adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "Mini-IPIP Big Five Personality Scale",
19
21
  },
@@ -15,6 +15,8 @@ exports.phq9 = {
15
15
  id: "phq9",
16
16
  version: "1.0.0",
17
17
  categories: ["depression"],
18
+ audience: ["adult"],
19
+ respondent: "self",
18
20
  title: {
19
21
  en: "Patient Health Questionnaire (PHQ-9)",
20
22
  },
@@ -14,6 +14,8 @@ exports.rses = {
14
14
  id: "rses",
15
15
  version: "1.0.0",
16
16
  categories: ["self-esteem"],
17
+ audience: ["adolescent", "adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "Rosenberg Self-Esteem Scale (RSES)",
19
21
  },
@@ -16,6 +16,8 @@ exports.swls = {
16
16
  id: "swls",
17
17
  version: "1.0.0",
18
18
  categories: ["well-being"],
19
+ audience: ["adult"],
20
+ respondent: "self",
19
21
  title: {
20
22
  en: "Satisfaction with Life Scale (SWLS)",
21
23
  },
@@ -14,6 +14,8 @@ exports.who5 = {
14
14
  id: "who5",
15
15
  version: "1.0.0",
16
16
  categories: ["well-being"],
17
+ audience: ["adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "WHO-5 Well-Being Index",
19
21
  },
@@ -138,6 +138,18 @@ export type ScoringDefinition = SumScoring | SubscaleScoring | CountScoring;
138
138
  * string, so custom assessments are free to define their own taxonomy.
139
139
  */
140
140
  export type InventoryCategory = "depression" | "anxiety" | "stress" | "well-being" | "adhd" | "autism" | "substance-use" | "personality" | "attachment" | "relationships" | "emotion-regulation" | "sensory-processing" | "distress" | "self-esteem";
141
+ /**
142
+ * Age bands used by the bundled inventories to say who an instrument is
143
+ * *about*. `AssessmentDefinition.audience` accepts any string, so custom
144
+ * assessments are free to define their own bands.
145
+ */
146
+ export type InventoryAudience = "adult" | "adolescent" | "child";
147
+ /**
148
+ * Whose report the answers are, in the bundled inventories.
149
+ * `AssessmentDefinition.respondent` accepts any string, so custom
150
+ * assessments are free to define their own roles.
151
+ */
152
+ export type InventoryRespondent = "self" | "parent" | "teacher" | "clinician";
141
153
  /**
142
154
  * The complete, serializable description of an assessment.
143
155
  *
@@ -155,6 +167,34 @@ export interface AssessmentDefinition {
155
167
  * any strings.
156
168
  */
157
169
  categories?: string[];
170
+ /**
171
+ * Age band(s) the instrument is written and validated for — who it is
172
+ * *about*, which is the person answering only when `respondent` is
173
+ * `"self"`. An array because one wording is often validated across
174
+ * bands (the RSES is standard for adolescents and adults alike).
175
+ *
176
+ * A retrospective instrument stays with the person answering: an adult
177
+ * recalling their own childhood is `["adult"]` + `"self"`, and the
178
+ * childhood framing belongs in `instructions`. Bundled inventories use
179
+ * `InventoryAudience` values; custom definitions may use any strings.
180
+ */
181
+ audience?: string[];
182
+ /**
183
+ * Whose report the answers are: the person the assessment is about
184
+ * (`"self"`) or a proxy informant (`"parent"`, `"teacher"`, ...). Scalar
185
+ * rather than an array because a definition is written from exactly one
186
+ * point of view — parent- and teacher-report forms of the same
187
+ * instrument are separate definitions with their own item wording
188
+ * ("your child" vs "I"), so they cannot share one entry here.
189
+ *
190
+ * Not the administration mode: a clinician reading the K10 aloud as an
191
+ * interview is still `"self"`, because the answers are the client's own
192
+ * report. `"clinician"` means the clinician is the informant, rating the
193
+ * client from their own observation. `ResponseData.respondentId` then
194
+ * identifies which individual answered. Bundled inventories use
195
+ * `InventoryRespondent` values; custom definitions may use any strings.
196
+ */
197
+ respondent?: string;
158
198
  title: LocalizedText;
159
199
  description?: LocalizedText;
160
200
  /** Instructions shown to the respondent (incl. the recall timeframe). */
@@ -1,4 +1,4 @@
1
- export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, InventoryCategory, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, MissingDataPolicy, MissingDataStrategy, ScoringDefinition, ValidationIssueCode, AnswerMap, InventoryLocalePack, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
1
+ export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, InventoryCategory, InventoryAudience, InventoryRespondent, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, MissingDataPolicy, MissingDataStrategy, ScoringDefinition, ValidationIssueCode, AnswerMap, InventoryLocalePack, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
2
2
  export { PsytoolsError } from "./errors.ts";
3
3
  export type { PsytoolsErrorCode } from "./errors.ts";
4
4
  export { localizeText, collectLocales, pickLocales, applyLocale } from "./i18n.ts";
@@ -12,6 +12,8 @@ export const aq10 = {
12
12
  id: "aq10",
13
13
  version: "1.0.0",
14
14
  categories: ["autism"],
15
+ audience: ["adult"],
16
+ respondent: "self",
15
17
  title: {
16
18
  en: "Autism Spectrum Quotient (AQ-10) — Adult",
17
19
  },
@@ -2,10 +2,17 @@ import type { AssessmentDefinition } from "../types.ts";
2
2
  /**
3
3
  * ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (Part A).
4
4
  *
5
- * Developed by the WHO and the Workgroup on Adult ADHD (Harvard Medical
6
- * School / NYU). Items 1–3 count as screen-positive from "Sometimes" and
7
- * items 4–6 from "Often"; four or more positive items indicate symptoms
8
- * highly consistent with adult ADHD and warrant further investigation
9
- * (Kessler et al., 2005). Free to distribute and score.
5
+ * A subset of the 18-question ASRS v1.1 Symptom Checklist, developed with the
6
+ * WHO's Workgroup on Adult ADHD. Items 1–3 count as screen-positive from
7
+ * "Sometimes" and items 4–6 from "Often"; four or more positive items indicate
8
+ * symptoms highly consistent with adult ADHD and warrant further investigation
9
+ * (Kessler et al., 2005).
10
+ *
11
+ * Copyright is held by New York University and the President and Fellows of
12
+ * Harvard College, and licensing is administered by NYU Technology
13
+ * Opportunities & Ventures — not by the WHO. Free for clinical, non-clinical
14
+ * and commercial use, but attribution is mandatory: render `meta.attribution`
15
+ * verbatim wherever the screener or its results appear. See `meta.license` for
16
+ * the open question about translation.
10
17
  */
11
18
  export declare const asrs6: AssessmentDefinition;
@@ -1,16 +1,25 @@
1
1
  /**
2
2
  * ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (Part A).
3
3
  *
4
- * Developed by the WHO and the Workgroup on Adult ADHD (Harvard Medical
5
- * School / NYU). Items 1–3 count as screen-positive from "Sometimes" and
6
- * items 4–6 from "Often"; four or more positive items indicate symptoms
7
- * highly consistent with adult ADHD and warrant further investigation
8
- * (Kessler et al., 2005). Free to distribute and score.
4
+ * A subset of the 18-question ASRS v1.1 Symptom Checklist, developed with the
5
+ * WHO's Workgroup on Adult ADHD. Items 1–3 count as screen-positive from
6
+ * "Sometimes" and items 4–6 from "Often"; four or more positive items indicate
7
+ * symptoms highly consistent with adult ADHD and warrant further investigation
8
+ * (Kessler et al., 2005).
9
+ *
10
+ * Copyright is held by New York University and the President and Fellows of
11
+ * Harvard College, and licensing is administered by NYU Technology
12
+ * Opportunities & Ventures — not by the WHO. Free for clinical, non-clinical
13
+ * and commercial use, but attribution is mandatory: render `meta.attribution`
14
+ * verbatim wherever the screener or its results appear. See `meta.license` for
15
+ * the open question about translation.
9
16
  */
10
17
  export const asrs6 = {
11
18
  id: "asrs6",
12
19
  version: "1.0.0",
13
20
  categories: ["adhd"],
21
+ audience: ["adult"],
22
+ respondent: "self",
14
23
  title: {
15
24
  en: "Adult ADHD Self-Report Scale (ASRS-v1.1) Screener",
16
25
  },
@@ -98,7 +107,8 @@ export const asrs6 = {
98
107
  },
99
108
  meta: {
100
109
  reference: "Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): a short screening scale for use in the general population. Psychological Medicine, 35(2), 245-256.",
101
- license: "Free with conditions — (c) WHO / Workgroup on Adult ADHD; free for clinical and research use. Verify licensing with the rights holders before embedding in commercial products.",
110
+ attribution: "The 6-question Adult Self-Report Scale-Version1.1 (ASRS-V1.1) Screener is a subset of the 18-question Adult ADHD Self-Report Scale-Version1.1 (Adult ASRSV1.1) Symptom Checklist. © New York University and the President and Fellows of Harvard College.",
111
+ license: "Free with conditions — © New York University and the President and Fellows of Harvard College; licensing administered by NYU Technology Opportunities & Ventures (license.tov.med.nyu.edu/product/asrs6Qscreener). Freely available for clinical and non-clinical use, including commercial use, but attribution is required: display meta.attribution verbatim wherever the screener or its results appear. No modifications other than creating electronic versions are permitted, and the license does not say whether translation is a modification — so the standing of the bundled tr/de/zh/es translations is unresolved, pending a question to NYU TOV. See SOURCES.md.",
102
112
  licenseFlag: "free-with-conditions",
103
113
  translationProvenance: "en: reproduced from the original. Other locales (tr, de, zh, es): AI translation (Anthropic Claude, claude-fable-5) from the original English; official translations were not consulted and the texts are unverified. See SOURCES.md.",
104
114
  timeframe: "past 6 months",
@@ -51,6 +51,8 @@ export const audit = {
51
51
  id: "audit",
52
52
  version: "1.0.0",
53
53
  categories: ["substance-use"],
54
+ audience: ["adult"],
55
+ respondent: "self",
54
56
  title: {
55
57
  en: "Alcohol Use Disorders Identification Test (AUDIT)",
56
58
  },
@@ -11,6 +11,8 @@ export const cesd = {
11
11
  id: "cesd",
12
12
  version: "1.0.0",
13
13
  categories: ["depression"],
14
+ audience: ["adult"],
15
+ respondent: "self",
14
16
  title: {
15
17
  en: "Center for Epidemiologic Studies Depression Scale (CES-D)",
16
18
  },
@@ -32,6 +32,8 @@ export const dass21 = {
32
32
  id: "dass21",
33
33
  version: "1.0.0",
34
34
  categories: ["depression", "anxiety", "stress"],
35
+ audience: ["adult"],
36
+ respondent: "self",
35
37
  title: {
36
38
  en: "Depression Anxiety Stress Scales (DASS-21)",
37
39
  },
@@ -25,6 +25,8 @@ export const ecrR = {
25
25
  id: "ecr-r",
26
26
  version: "1.0.0",
27
27
  categories: ["attachment", "relationships"],
28
+ audience: ["adult"],
29
+ respondent: "self",
28
30
  title: {
29
31
  en: "Experiences in Close Relationships-Revised (ECR-R)",
30
32
  },
@@ -25,6 +25,8 @@ export const erq = {
25
25
  id: "erq",
26
26
  version: "1.0.0",
27
27
  categories: ["emotion-regulation"],
28
+ audience: ["adult"],
29
+ respondent: "self",
28
30
  title: {
29
31
  en: "Emotion Regulation Questionnaire (ERQ)",
30
32
  },
@@ -13,6 +13,8 @@ export const flourishing = {
13
13
  id: "flourishing",
14
14
  version: "1.0.0",
15
15
  categories: ["well-being"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Flourishing Scale (FS)",
18
20
  },
@@ -11,6 +11,8 @@ export const gad7 = {
11
11
  id: "gad7",
12
12
  version: "1.0.0",
13
13
  categories: ["anxiety"],
14
+ audience: ["adult"],
15
+ respondent: "self",
14
16
  title: {
15
17
  en: "Generalized Anxiety Disorder Scale (GAD-7)",
16
18
  },
@@ -23,6 +23,8 @@ export const hsps = {
23
23
  id: "hsps",
24
24
  version: "1.0.0",
25
25
  categories: ["sensory-processing", "personality"],
26
+ audience: ["adult"],
27
+ respondent: "self",
26
28
  title: {
27
29
  en: "Highly Sensitive Person Scale (HSPS)",
28
30
  },
@@ -13,6 +13,8 @@ export const k10 = {
13
13
  id: "k10",
14
14
  version: "1.0.0",
15
15
  categories: ["distress"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Kessler Psychological Distress Scale (K10)",
18
20
  },
@@ -13,6 +13,8 @@ export const k6 = {
13
13
  id: "k6",
14
14
  version: "1.0.0",
15
15
  categories: ["distress"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Kessler Psychological Distress Scale (K6)",
18
20
  },
@@ -11,6 +11,8 @@ export const miniIpip = {
11
11
  id: "mini-ipip",
12
12
  version: "1.0.0",
13
13
  categories: ["personality"],
14
+ audience: ["adult"],
15
+ respondent: "self",
14
16
  title: {
15
17
  en: "Mini-IPIP Big Five Personality Scale",
16
18
  },
@@ -12,6 +12,8 @@ export const phq9 = {
12
12
  id: "phq9",
13
13
  version: "1.0.0",
14
14
  categories: ["depression"],
15
+ audience: ["adult"],
16
+ respondent: "self",
15
17
  title: {
16
18
  en: "Patient Health Questionnaire (PHQ-9)",
17
19
  },
@@ -11,6 +11,8 @@ export const rses = {
11
11
  id: "rses",
12
12
  version: "1.0.0",
13
13
  categories: ["self-esteem"],
14
+ audience: ["adolescent", "adult"],
15
+ respondent: "self",
14
16
  title: {
15
17
  en: "Rosenberg Self-Esteem Scale (RSES)",
16
18
  },
@@ -13,6 +13,8 @@ export const swls = {
13
13
  id: "swls",
14
14
  version: "1.0.0",
15
15
  categories: ["well-being"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Satisfaction with Life Scale (SWLS)",
18
20
  },
@@ -11,6 +11,8 @@ export const who5 = {
11
11
  id: "who5",
12
12
  version: "1.0.0",
13
13
  categories: ["well-being"],
14
+ audience: ["adult"],
15
+ respondent: "self",
14
16
  title: {
15
17
  en: "WHO-5 Well-Being Index",
16
18
  },
@@ -138,6 +138,18 @@ export type ScoringDefinition = SumScoring | SubscaleScoring | CountScoring;
138
138
  * string, so custom assessments are free to define their own taxonomy.
139
139
  */
140
140
  export type InventoryCategory = "depression" | "anxiety" | "stress" | "well-being" | "adhd" | "autism" | "substance-use" | "personality" | "attachment" | "relationships" | "emotion-regulation" | "sensory-processing" | "distress" | "self-esteem";
141
+ /**
142
+ * Age bands used by the bundled inventories to say who an instrument is
143
+ * *about*. `AssessmentDefinition.audience` accepts any string, so custom
144
+ * assessments are free to define their own bands.
145
+ */
146
+ export type InventoryAudience = "adult" | "adolescent" | "child";
147
+ /**
148
+ * Whose report the answers are, in the bundled inventories.
149
+ * `AssessmentDefinition.respondent` accepts any string, so custom
150
+ * assessments are free to define their own roles.
151
+ */
152
+ export type InventoryRespondent = "self" | "parent" | "teacher" | "clinician";
141
153
  /**
142
154
  * The complete, serializable description of an assessment.
143
155
  *
@@ -155,6 +167,34 @@ export interface AssessmentDefinition {
155
167
  * any strings.
156
168
  */
157
169
  categories?: string[];
170
+ /**
171
+ * Age band(s) the instrument is written and validated for — who it is
172
+ * *about*, which is the person answering only when `respondent` is
173
+ * `"self"`. An array because one wording is often validated across
174
+ * bands (the RSES is standard for adolescents and adults alike).
175
+ *
176
+ * A retrospective instrument stays with the person answering: an adult
177
+ * recalling their own childhood is `["adult"]` + `"self"`, and the
178
+ * childhood framing belongs in `instructions`. Bundled inventories use
179
+ * `InventoryAudience` values; custom definitions may use any strings.
180
+ */
181
+ audience?: string[];
182
+ /**
183
+ * Whose report the answers are: the person the assessment is about
184
+ * (`"self"`) or a proxy informant (`"parent"`, `"teacher"`, ...). Scalar
185
+ * rather than an array because a definition is written from exactly one
186
+ * point of view — parent- and teacher-report forms of the same
187
+ * instrument are separate definitions with their own item wording
188
+ * ("your child" vs "I"), so they cannot share one entry here.
189
+ *
190
+ * Not the administration mode: a clinician reading the K10 aloud as an
191
+ * interview is still `"self"`, because the answers are the client's own
192
+ * report. `"clinician"` means the clinician is the informant, rating the
193
+ * client from their own observation. `ResponseData.respondentId` then
194
+ * identifies which individual answered. Bundled inventories use
195
+ * `InventoryRespondent` values; custom definitions may use any strings.
196
+ */
197
+ respondent?: string;
158
198
  title: LocalizedText;
159
199
  description?: LocalizedText;
160
200
  /** Instructions shown to the respondent (incl. the recall timeframe). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "psytools",
3
- "version": "0.5.3",
3
+ "version": "0.6.0",
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, CES-D, ECR-R, ERQ, HSPS, SWLS, Flourishing, K10, K6, RSES) in multiple languages.",
5
5
  "keywords": [
6
6
  "psychology",
@@ -41,7 +41,7 @@
41
41
  "screening",
42
42
  "likert"
43
43
  ],
44
- "license": "MIT",
44
+ "license": "SEE LICENSE IN LICENSE",
45
45
  "author": "Samed Kahyaoglu <samed@luckys.dev>",
46
46
  "repository": {
47
47
  "type": "git",
@@ -14,6 +14,17 @@
14
14
  "description": "What the assessment measures, e.g. [\"depression\"]. Bundled inventories use a small controlled vocabulary; custom definitions may use any strings.",
15
15
  "items": { "type": "string", "minLength": 1 }
16
16
  },
17
+ "audience": {
18
+ "type": "array",
19
+ "description": "Age band(s) the instrument is written and validated for — who it is about, e.g. [\"adult\"]. Bundled inventories use a small controlled vocabulary (adult, adolescent, child); custom definitions may use any strings.",
20
+ "items": { "type": "string", "minLength": 1 }
21
+ },
22
+ "respondent": {
23
+ "type": "string",
24
+ "minLength": 1,
25
+ "description": "Whose report the answers are: \"self\" for the person the assessment is about, otherwise a proxy informant (\"parent\", \"teacher\", \"clinician\"). Not the administration mode — an interviewer-read self-report is still \"self\". Custom definitions may use any string.",
26
+ "examples": ["self", "parent", "teacher", "clinician"]
27
+ },
17
28
  "title": { "$ref": "#/$defs/localizedText" },
18
29
  "description": { "$ref": "#/$defs/localizedText" },
19
30
  "instructions": { "$ref": "#/$defs/localizedText" },
package/src/index.ts CHANGED
@@ -4,6 +4,8 @@ export type {
4
4
  AssessmentQuestion,
5
5
  AssessmentDefinition,
6
6
  InventoryCategory,
7
+ InventoryAudience,
8
+ InventoryRespondent,
7
9
  ScoreBand,
8
10
  ScoreFlag,
9
11
  SumScoring,
@@ -14,6 +14,8 @@ export const aq10: AssessmentDefinition = {
14
14
  id: "aq10",
15
15
  version: "1.0.0",
16
16
  categories: ["autism"],
17
+ audience: ["adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "Autism Spectrum Quotient (AQ-10) — Adult",
19
21
  },
@@ -3,16 +3,25 @@ import type { AssessmentDefinition } from "../types.ts";
3
3
  /**
4
4
  * ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (Part A).
5
5
  *
6
- * Developed by the WHO and the Workgroup on Adult ADHD (Harvard Medical
7
- * School / NYU). Items 1–3 count as screen-positive from "Sometimes" and
8
- * items 4–6 from "Often"; four or more positive items indicate symptoms
9
- * highly consistent with adult ADHD and warrant further investigation
10
- * (Kessler et al., 2005). Free to distribute and score.
6
+ * A subset of the 18-question ASRS v1.1 Symptom Checklist, developed with the
7
+ * WHO's Workgroup on Adult ADHD. Items 1–3 count as screen-positive from
8
+ * "Sometimes" and items 4–6 from "Often"; four or more positive items indicate
9
+ * symptoms highly consistent with adult ADHD and warrant further investigation
10
+ * (Kessler et al., 2005).
11
+ *
12
+ * Copyright is held by New York University and the President and Fellows of
13
+ * Harvard College, and licensing is administered by NYU Technology
14
+ * Opportunities & Ventures — not by the WHO. Free for clinical, non-clinical
15
+ * and commercial use, but attribution is mandatory: render `meta.attribution`
16
+ * verbatim wherever the screener or its results appear. See `meta.license` for
17
+ * the open question about translation.
11
18
  */
12
19
  export const asrs6: AssessmentDefinition = {
13
20
  id: "asrs6",
14
21
  version: "1.0.0",
15
22
  categories: ["adhd"],
23
+ audience: ["adult"],
24
+ respondent: "self",
16
25
  title: {
17
26
  en: "Adult ADHD Self-Report Scale (ASRS-v1.1) Screener",
18
27
  },
@@ -101,8 +110,10 @@ export const asrs6: AssessmentDefinition = {
101
110
  meta: {
102
111
  reference:
103
112
  "Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): a short screening scale for use in the general population. Psychological Medicine, 35(2), 245-256.",
113
+ attribution:
114
+ "The 6-question Adult Self-Report Scale-Version1.1 (ASRS-V1.1) Screener is a subset of the 18-question Adult ADHD Self-Report Scale-Version1.1 (Adult ASRSV1.1) Symptom Checklist. © New York University and the President and Fellows of Harvard College.",
104
115
  license:
105
- "Free with conditions — (c) WHO / Workgroup on Adult ADHD; free for clinical and research use. Verify licensing with the rights holders before embedding in commercial products.",
116
+ "Free with conditions — © New York University and the President and Fellows of Harvard College; licensing administered by NYU Technology Opportunities & Ventures (license.tov.med.nyu.edu/product/asrs6Qscreener). Freely available for clinical and non-clinical use, including commercial use, but attribution is required: display meta.attribution verbatim wherever the screener or its results appear. No modifications other than creating electronic versions are permitted, and the license does not say whether translation is a modification — so the standing of the bundled tr/de/zh/es translations is unresolved, pending a question to NYU TOV. See SOURCES.md.",
106
117
  licenseFlag: "free-with-conditions",
107
118
  translationProvenance:
108
119
  "en: reproduced from the original. Other locales (tr, de, zh, es): AI translation (Anthropic Claude, claude-fable-5) from the original English; official translations were not consulted and the texts are unverified. See SOURCES.md.",
@@ -55,6 +55,8 @@ export const audit: AssessmentDefinition = {
55
55
  id: "audit",
56
56
  version: "1.0.0",
57
57
  categories: ["substance-use"],
58
+ audience: ["adult"],
59
+ respondent: "self",
58
60
  title: {
59
61
  en: "Alcohol Use Disorders Identification Test (AUDIT)",
60
62
  },
@@ -13,6 +13,8 @@ export const cesd: AssessmentDefinition = {
13
13
  id: "cesd",
14
14
  version: "1.0.0",
15
15
  categories: ["depression"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Center for Epidemiologic Studies Depression Scale (CES-D)",
18
20
  },
@@ -37,6 +37,8 @@ export const dass21: AssessmentDefinition = {
37
37
  id: "dass21",
38
38
  version: "1.0.0",
39
39
  categories: ["depression", "anxiety", "stress"],
40
+ audience: ["adult"],
41
+ respondent: "self",
40
42
  title: {
41
43
  en: "Depression Anxiety Stress Scales (DASS-21)",
42
44
  },
@@ -28,6 +28,8 @@ export const ecrR: AssessmentDefinition = {
28
28
  id: "ecr-r",
29
29
  version: "1.0.0",
30
30
  categories: ["attachment", "relationships"],
31
+ audience: ["adult"],
32
+ respondent: "self",
31
33
  title: {
32
34
  en: "Experiences in Close Relationships-Revised (ECR-R)",
33
35
  },
@@ -28,6 +28,8 @@ export const erq: AssessmentDefinition = {
28
28
  id: "erq",
29
29
  version: "1.0.0",
30
30
  categories: ["emotion-regulation"],
31
+ audience: ["adult"],
32
+ respondent: "self",
31
33
  title: {
32
34
  en: "Emotion Regulation Questionnaire (ERQ)",
33
35
  },
@@ -15,6 +15,8 @@ export const flourishing: AssessmentDefinition = {
15
15
  id: "flourishing",
16
16
  version: "1.0.0",
17
17
  categories: ["well-being"],
18
+ audience: ["adult"],
19
+ respondent: "self",
18
20
  title: {
19
21
  en: "Flourishing Scale (FS)",
20
22
  },
@@ -13,6 +13,8 @@ export const gad7: AssessmentDefinition = {
13
13
  id: "gad7",
14
14
  version: "1.0.0",
15
15
  categories: ["anxiety"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Generalized Anxiety Disorder Scale (GAD-7)",
18
20
  },
@@ -26,6 +26,8 @@ export const hsps: AssessmentDefinition = {
26
26
  id: "hsps",
27
27
  version: "1.0.0",
28
28
  categories: ["sensory-processing", "personality"],
29
+ audience: ["adult"],
30
+ respondent: "self",
29
31
  title: {
30
32
  en: "Highly Sensitive Person Scale (HSPS)",
31
33
  },
@@ -15,6 +15,8 @@ export const k10: AssessmentDefinition = {
15
15
  id: "k10",
16
16
  version: "1.0.0",
17
17
  categories: ["distress"],
18
+ audience: ["adult"],
19
+ respondent: "self",
18
20
  title: {
19
21
  en: "Kessler Psychological Distress Scale (K10)",
20
22
  },
@@ -15,6 +15,8 @@ export const k6: AssessmentDefinition = {
15
15
  id: "k6",
16
16
  version: "1.0.0",
17
17
  categories: ["distress"],
18
+ audience: ["adult"],
19
+ respondent: "self",
18
20
  title: {
19
21
  en: "Kessler Psychological Distress Scale (K6)",
20
22
  },
@@ -13,6 +13,8 @@ export const miniIpip: AssessmentDefinition = {
13
13
  id: "mini-ipip",
14
14
  version: "1.0.0",
15
15
  categories: ["personality"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Mini-IPIP Big Five Personality Scale",
18
20
  },
@@ -14,6 +14,8 @@ export const phq9: AssessmentDefinition = {
14
14
  id: "phq9",
15
15
  version: "1.0.0",
16
16
  categories: ["depression"],
17
+ audience: ["adult"],
18
+ respondent: "self",
17
19
  title: {
18
20
  en: "Patient Health Questionnaire (PHQ-9)",
19
21
  },
@@ -13,6 +13,8 @@ export const rses: AssessmentDefinition = {
13
13
  id: "rses",
14
14
  version: "1.0.0",
15
15
  categories: ["self-esteem"],
16
+ audience: ["adolescent", "adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "Rosenberg Self-Esteem Scale (RSES)",
18
20
  },
@@ -15,6 +15,8 @@ export const swls: AssessmentDefinition = {
15
15
  id: "swls",
16
16
  version: "1.0.0",
17
17
  categories: ["well-being"],
18
+ audience: ["adult"],
19
+ respondent: "self",
18
20
  title: {
19
21
  en: "Satisfaction with Life Scale (SWLS)",
20
22
  },
@@ -13,6 +13,8 @@ export const who5: AssessmentDefinition = {
13
13
  id: "who5",
14
14
  version: "1.0.0",
15
15
  categories: ["well-being"],
16
+ audience: ["adult"],
17
+ respondent: "self",
16
18
  title: {
17
19
  en: "WHO-5 Well-Being Index",
18
20
  },
package/src/types.ts CHANGED
@@ -167,6 +167,20 @@ export type InventoryCategory =
167
167
  | "distress"
168
168
  | "self-esteem";
169
169
 
170
+ /**
171
+ * Age bands used by the bundled inventories to say who an instrument is
172
+ * *about*. `AssessmentDefinition.audience` accepts any string, so custom
173
+ * assessments are free to define their own bands.
174
+ */
175
+ export type InventoryAudience = "adult" | "adolescent" | "child";
176
+
177
+ /**
178
+ * Whose report the answers are, in the bundled inventories.
179
+ * `AssessmentDefinition.respondent` accepts any string, so custom
180
+ * assessments are free to define their own roles.
181
+ */
182
+ export type InventoryRespondent = "self" | "parent" | "teacher" | "clinician";
183
+
170
184
  /**
171
185
  * The complete, serializable description of an assessment.
172
186
  *
@@ -184,6 +198,34 @@ export interface AssessmentDefinition {
184
198
  * any strings.
185
199
  */
186
200
  categories?: string[];
201
+ /**
202
+ * Age band(s) the instrument is written and validated for — who it is
203
+ * *about*, which is the person answering only when `respondent` is
204
+ * `"self"`. An array because one wording is often validated across
205
+ * bands (the RSES is standard for adolescents and adults alike).
206
+ *
207
+ * A retrospective instrument stays with the person answering: an adult
208
+ * recalling their own childhood is `["adult"]` + `"self"`, and the
209
+ * childhood framing belongs in `instructions`. Bundled inventories use
210
+ * `InventoryAudience` values; custom definitions may use any strings.
211
+ */
212
+ audience?: string[];
213
+ /**
214
+ * Whose report the answers are: the person the assessment is about
215
+ * (`"self"`) or a proxy informant (`"parent"`, `"teacher"`, ...). Scalar
216
+ * rather than an array because a definition is written from exactly one
217
+ * point of view — parent- and teacher-report forms of the same
218
+ * instrument are separate definitions with their own item wording
219
+ * ("your child" vs "I"), so they cannot share one entry here.
220
+ *
221
+ * Not the administration mode: a clinician reading the K10 aloud as an
222
+ * interview is still `"self"`, because the answers are the client's own
223
+ * report. `"clinician"` means the clinician is the informant, rating the
224
+ * client from their own observation. `ResponseData.respondentId` then
225
+ * identifies which individual answered. Bundled inventories use
226
+ * `InventoryRespondent` values; custom definitions may use any strings.
227
+ */
228
+ respondent?: string;
187
229
  title: LocalizedText;
188
230
  description?: LocalizedText;
189
231
  /** Instructions shown to the respondent (incl. the recall timeframe). */