wwbnlp 0.1.0

package/LICENSE

@@ -0,0 +1,361 @@
+Creative Commons Legal Code
+
+Attribution-NonCommercial-ShareAlike 3.0 Unported
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR
+    DAMAGES RESULTING FROM ITS USE.
+
+License
+
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
+COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
+COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
+AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
+TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY
+BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS
+CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND
+CONDITIONS.
+
+1. Definitions
+
+ a. "Adaptation" means a work based upon the Work, or upon the Work and
+    other pre-existing works, such as a translation, adaptation,
+    derivative work, arrangement of music or other alterations of a
+    literary or artistic work, or phonogram or performance and includes
+    cinematographic adaptations or any other form in which the Work may be
+    recast, transformed, or adapted including in any form recognizably
+    derived from the original, except that a work that constitutes a
+    Collection will not be considered an Adaptation for the purpose of
+    this License. For the avoidance of doubt, where the Work is a musical
+    work, performance or phonogram, the synchronization of the Work in
+    timed-relation with a moving image ("synching") will be considered an
+    Adaptation for the purpose of this License.
+ b. "Collection" means a collection of literary or artistic works, such as
+    encyclopedias and anthologies, or performances, phonograms or
+    broadcasts, or other works or subject matter other than works listed
+    in Section 1(g) below, which, by reason of the selection and
+    arrangement of their contents, constitute intellectual creations, in
+    which the Work is included in its entirety in unmodified form along
+    with one or more other contributions, each constituting separate and
+    independent works in themselves, which together are assembled into a
+    collective whole. A work that constitutes a Collection will not be
+    considered an Adaptation (as defined above) for the purposes of this
+    License.
+ c. "Distribute" means to make available to the public the original and
+    copies of the Work or Adaptation, as appropriate, through sale or
+    other transfer of ownership.
+ d. "License Elements" means the following high-level license attributes
+    as selected by Licensor and indicated in the title of this License:
+    Attribution, Noncommercial, ShareAlike.
+ e. "Licensor" means the individual, individuals, entity or entities that
+    offer(s) the Work under the terms of this License.
+ f. "Original Author" means, in the case of a literary or artistic work,
+    the individual, individuals, entity or entities who created the Work
+    or if no individual or entity can be identified, the publisher; and in
+    addition (i) in the case of a performance the actors, singers,
+    musicians, dancers, and other persons who act, sing, deliver, declaim,
+    play in, interpret or otherwise perform literary or artistic works or
+    expressions of folklore; (ii) in the case of a phonogram the producer
+    being the person or legal entity who first fixes the sounds of a
+    performance or other sounds; and, (iii) in the case of broadcasts, the
+    organization that transmits the broadcast.
+ g. "Work" means the literary and/or artistic work offered under the terms
+    of this License including without limitation any production in the
+    literary, scientific and artistic domain, whatever may be the mode or
+    form of its expression including digital form, such as a book,
+    pamphlet and other writing; a lecture, address, sermon or other work
+    of the same nature; a dramatic or dramatico-musical work; a
+    choreographic work or entertainment in dumb show; a musical
+    composition with or without words; a cinematographic work to which are
+    assimilated works expressed by a process analogous to cinematography;
+    a work of drawing, painting, architecture, sculpture, engraving or
+    lithography; a photographic work to which are assimilated works
+    expressed by a process analogous to photography; a work of applied
+    art; an illustration, map, plan, sketch or three-dimensional work
+    relative to geography, topography, architecture or science; a
+    performance; a broadcast; a phonogram; a compilation of data to the
+    extent it is protected as a copyrightable work; or a work performed by
+    a variety or circus performer to the extent it is not otherwise
+    considered a literary or artistic work.
+ h. "You" means an individual or entity exercising rights under this
+    License who has not previously violated the terms of this License with
+    respect to the Work, or who has received express permission from the
+    Licensor to exercise rights under this License despite a previous
+    violation.
+ i. "Publicly Perform" means to perform public recitations of the Work and
+    to communicate to the public those public recitations, by any means or
+    process, including by wire or wireless means or public digital
+    performances; to make available to the public Works in such a way that
+    members of the public may access these Works from a place and at a
+    place individually chosen by them; to perform the Work to the public
+    by any means or process and the communication to the public of the
+    performances of the Work, including by public digital performance; to
+    broadcast and rebroadcast the Work by any means including signs,
+    sounds or images.
+ j. "Reproduce" means to make copies of the Work by any means including
+    without limitation by sound or visual recordings and the right of
+    fixation and reproducing fixations of the Work, including storage of a
+    protected performance or phonogram in digital form or other electronic
+    medium.
+
+2. Fair Dealing Rights. Nothing in this License is intended to reduce,
+limit, or restrict any uses free from copyright or rights arising from
+limitations or exceptions that are provided for in connection with the
+copyright protection under copyright law or other applicable laws.
+
+3. License Grant. Subject to the terms and conditions of this License,
+Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+perpetual (for the duration of the applicable copyright) license to
+exercise the rights in the Work as stated below:
+
+ a. to Reproduce the Work, to incorporate the Work into one or more
+    Collections, and to Reproduce the Work as incorporated in the
+    Collections;
+ b. to create and Reproduce Adaptations provided that any such Adaptation,
+    including any translation in any medium, takes reasonable steps to
+    clearly label, demarcate or otherwise identify that changes were made
+    to the original Work. For example, a translation could be marked "The
+    original work was translated from English to Spanish," or a
+    modification could indicate "The original work has been modified.";
+ c. to Distribute and Publicly Perform the Work including as incorporated
+    in Collections; and,
+ d. to Distribute and Publicly Perform Adaptations.
+
+The above rights may be exercised in all media and formats whether now
+known or hereafter devised. The above rights include the right to make
+such modifications as are technically necessary to exercise the rights in
+other media and formats. Subject to Section 8(f), all rights not expressly
+granted by Licensor are hereby reserved, including but not limited to the
+rights described in Section 4(e).
+
+4. Restrictions. The license granted in Section 3 above is expressly made
+subject to and limited by the following restrictions:
+
+ a. You may Distribute or Publicly Perform the Work only under the terms
+    of this License. You must include a copy of, or the Uniform Resource
+    Identifier (URI) for, this License with every copy of the Work You
+    Distribute or Publicly Perform. You may not offer or impose any terms
+    on the Work that restrict the terms of this License or the ability of
+    the recipient of the Work to exercise the rights granted to that
+    recipient under the terms of the License. You may not sublicense the
+    Work. You must keep intact all notices that refer to this License and
+    to the disclaimer of warranties with every copy of the Work You
+    Distribute or Publicly Perform. When You Distribute or Publicly
+    Perform the Work, You may not impose any effective technological
+    measures on the Work that restrict the ability of a recipient of the
+    Work from You to exercise the rights granted to that recipient under
+    the terms of the License. This Section 4(a) applies to the Work as
+    incorporated in a Collection, but this does not require the Collection
+    apart from the Work itself to be made subject to the terms of this
+    License. If You create a Collection, upon notice from any Licensor You
+    must, to the extent practicable, remove from the Collection any credit
+    as required by Section 4(d), as requested. If You create an
+    Adaptation, upon notice from any Licensor You must, to the extent
+    practicable, remove from the Adaptation any credit as required by
+    Section 4(d), as requested.
+ b. You may Distribute or Publicly Perform an Adaptation only under: (i)
+    the terms of this License; (ii) a later version of this License with
+    the same License Elements as this License; (iii) a Creative Commons
+    jurisdiction license (either this or a later license version) that
+    contains the same License Elements as this License (e.g.,
+    Attribution-NonCommercial-ShareAlike 3.0 US) ("Applicable License").
+    You must include a copy of, or the URI, for Applicable License with
+    every copy of each Adaptation You Distribute or Publicly Perform. You
+    may not offer or impose any terms on the Adaptation that restrict the
+    terms of the Applicable License or the ability of the recipient of the
+    Adaptation to exercise the rights granted to that recipient under the
+    terms of the Applicable License. You must keep intact all notices that
+    refer to the Applicable License and to the disclaimer of warranties
+    with every copy of the Work as included in the Adaptation You
+    Distribute or Publicly Perform. When You Distribute or Publicly
+    Perform the Adaptation, You may not impose any effective technological
+    measures on the Adaptation that restrict the ability of a recipient of
+    the Adaptation from You to exercise the rights granted to that
+    recipient under the terms of the Applicable License. This Section 4(b)
+    applies to the Adaptation as incorporated in a Collection, but this
+    does not require the Collection apart from the Adaptation itself to be
+    made subject to the terms of the Applicable License.
+ c. You may not exercise any of the rights granted to You in Section 3
+    above in any manner that is primarily intended for or directed toward
+    commercial advantage or private monetary compensation. The exchange of
+    the Work for other copyrighted works by means of digital file-sharing
+    or otherwise shall not be considered to be intended for or directed
+    toward commercial advantage or private monetary compensation, provided
+    there is no payment of any monetary compensation in con-nection with
+    the exchange of copyrighted works.
+ d. If You Distribute, or Publicly Perform the Work or any Adaptations or
+    Collections, You must, unless a request has been made pursuant to
+    Section 4(a), keep intact all copyright notices for the Work and
+    provide, reasonable to the medium or means You are utilizing: (i) the
+    name of the Original Author (or pseudonym, if applicable) if supplied,
+    and/or if the Original Author and/or Licensor designate another party
+    or parties (e.g., a sponsor institute, publishing entity, journal) for
+    attribution ("Attribution Parties") in Licensor's copyright notice,
+    terms of service or by other reasonable means, the name of such party
+    or parties; (ii) the title of the Work if supplied; (iii) to the
+    extent reasonably practicable, the URI, if any, that Licensor
+    specifies to be associated with the Work, unless such URI does not
+    refer to the copyright notice or licensing information for the Work;
+    and, (iv) consistent with Section 3(b), in the case of an Adaptation,
+    a credit identifying the use of the Work in the Adaptation (e.g.,
+    "French translation of the Work by Original Author," or "Screenplay
+    based on original Work by Original Author"). The credit required by
+    this Section 4(d) may be implemented in any reasonable manner;
+    provided, however, that in the case of a Adaptation or Collection, at
+    a minimum such credit will appear, if a credit for all contributing
+    authors of the Adaptation or Collection appears, then as part of these
+    credits and in a manner at least as prominent as the credits for the
+    other contributing authors. For the avoidance of doubt, You may only
+    use the credit required by this Section for the purpose of attribution
+    in the manner set out above and, by exercising Your rights under this
+    License, You may not implicitly or explicitly assert or imply any
+    connection with, sponsorship or endorsement by the Original Author,
+    Licensor and/or Attribution Parties, as appropriate, of You or Your
+    use of the Work, without the separate, express prior written
+    permission of the Original Author, Licensor and/or Attribution
+    Parties.
+ e. For the avoidance of doubt:
+
+     i. Non-waivable Compulsory License Schemes. In those jurisdictions in
+        which the right to collect royalties through any statutory or
+        compulsory licensing scheme cannot be waived, the Licensor
+        reserves the exclusive right to collect such royalties for any
+        exercise by You of the rights granted under this License;
+    ii. Waivable Compulsory License Schemes. In those jurisdictions in
+        which the right to collect royalties through any statutory or
+        compulsory licensing scheme can be waived, the Licensor reserves
+        the exclusive right to collect such royalties for any exercise by
+        You of the rights granted under this License if Your exercise of
+        such rights is for a purpose or use which is otherwise than
+        noncommercial as permitted under Section 4(c) and otherwise waives
+        the right to collect royalties through any statutory or compulsory
+        licensing scheme; and,
+   iii. Voluntary License Schemes. The Licensor reserves the right to
+        collect royalties, whether individually or, in the event that the
+        Licensor is a member of a collecting society that administers
+        voluntary licensing schemes, via that society, from any exercise
+        by You of the rights granted under this License that is for a
+        purpose or use which is otherwise than noncommercial as permitted
+        under Section 4(c).
+ f. Except as otherwise agreed in writing by the Licensor or as may be
+    otherwise permitted by applicable law, if You Reproduce, Distribute or
+    Publicly Perform the Work either by itself or as part of any
+    Adaptations or Collections, You must not distort, mutilate, modify or
+    take other derogatory action in relation to the Work which would be
+    prejudicial to the Original Author's honor or reputation. Licensor
+    agrees that in those jurisdictions (e.g. Japan), in which any exercise
+    of the right granted in Section 3(b) of this License (the right to
+    make Adaptations) would be deemed to be a distortion, mutilation,
+    modification or other derogatory action prejudicial to the Original
+    Author's honor and reputation, the Licensor will waive or not assert,
+    as appropriate, this Section, to the fullest extent permitted by the
+    applicable national law, to enable You to reasonably exercise Your
+    right under Section 3(b) of this License (right to make Adaptations)
+    but not otherwise.
+
+5. Representations, Warranties and Disclaimer
+
+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING AND TO THE
+FULLEST EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR OFFERS THE WORK AS-IS
+AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE
+WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT
+LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS,
+ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT
+DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED
+WARRANTIES, SO THIS EXCLUSION MAY NOT APPLY TO YOU.
+
+6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE
+LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR
+ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES
+ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Termination
+
+ a. This License and the rights granted hereunder will terminate
+    automatically upon any breach by You of the terms of this License.
+    Individuals or entities who have received Adaptations or Collections
+    from You under this License, however, will not have their licenses
+    terminated provided such individuals or entities remain in full
+    compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
+    survive any termination of this License.
+ b. Subject to the above terms and conditions, the license granted here is
+    perpetual (for the duration of the applicable copyright in the Work).
+    Notwithstanding the above, Licensor reserves the right to release the
+    Work under different license terms or to stop distributing the Work at
+    any time; provided, however that any such election will not serve to
+    withdraw this License (or any other license that has been, or is
+    required to be, granted under the terms of this License), and this
+    License will continue in full force and effect unless terminated as
+    stated above.
+
+8. Miscellaneous
+
+ a. Each time You Distribute or Publicly Perform the Work or a Collection,
+    the Licensor offers to the recipient a license to the Work on the same
+    terms and conditions as the license granted to You under this License.
+ b. Each time You Distribute or Publicly Perform an Adaptation, Licensor
+    offers to the recipient a license to the original Work on the same
+    terms and conditions as the license granted to You under this License.
+ c. If any provision of this License is invalid or unenforceable under
+    applicable law, it shall not affect the validity or enforceability of
+    the remainder of the terms of this License, and without further action
+    by the parties to this agreement, such provision shall be reformed to
+    the minimum extent necessary to make such provision valid and
+    enforceable.
+ d. No term or provision of this License shall be deemed waived and no
+    breach consented to unless such waiver or consent shall be in writing
+    and signed by the party to be charged with such waiver or consent.
+ e. This License constitutes the entire agreement between the parties with
+    respect to the Work licensed here. There are no understandings,
+    agreements or representations with respect to the Work not specified
+    here. Licensor shall not be bound by any additional provisions that
+    may appear in any communication from You. This License may not be
+    modified without the mutual written agreement of the Licensor and You.
+ f. The rights granted under, and the subject matter referenced, in this
+    License were drafted utilizing the terminology of the Berne Convention
+    for the Protection of Literary and Artistic Works (as amended on
+    September 28, 1979), the Rome Convention of 1961, the WIPO Copyright
+    Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996
+    and the Universal Copyright Convention (as revised on July 24, 1971).
+    These rights and subject matter take effect in the relevant
+    jurisdiction in which the License terms are sought to be enforced
+    according to the corresponding provisions of the implementation of
+    those treaty provisions in the applicable national law. If the
+    standard suite of rights granted under applicable copyright law
+    includes additional rights not granted under this License, such
+    additional rights are deemed to be included in the License; this
+    License is not intended to restrict the license of any rights under
+    applicable law.
+
+
+Creative Commons Notice
+
+    Creative Commons is not a party to this License, and makes no warranty
+    whatsoever in connection with the Work. Creative Commons will not be
+    liable to You or any party on any legal theory for any damages
+    whatsoever, including without limitation any general, special,
+    incidental or consequential damages arising in connection to this
+    license. Notwithstanding the foregoing two (2) sentences, if Creative
+    Commons has expressly identified itself as the Licensor hereunder, it
+    shall have all rights and obligations of Licensor.
+
+    Except for the limited purpose of indicating to the public that the
+    Work is licensed under the CCPL, Creative Commons does not authorize
+    the use by either party of the trademark "Creative Commons" or any
+    related trademark or logo of Creative Commons without the prior
+    written consent of Creative Commons. Any permitted use will be in
+    compliance with Creative Commons' then-current trademark usage
+    guidelines, as may be published on its website or otherwise made
+    available upon request from time to time. For the avoidance of doubt,
+    this trademark restriction does not form part of this License.
+
+    Creative Commons may be contacted at https://creativecommons.org/.
+   

package/NOTICE.md

@@ -0,0 +1,28 @@
+# Attribution and licence notices
+
+World Wellbeing NLP is maintained by Peter Hughes. It consolidates his
+affectimo, bigfive, darktriad, lex-helpers, optimismo, predictage,
+predictgender, prospectimo, weighted-lexica and wellbeing_analysis projects.
+
+The research lexica belong to their cited researchers and the World Well-Being
+Project. Coefficients and adaptations retain Creative Commons
+Attribution-NonCommercial-ShareAlike 3.0 Unported. That licence contains a
+**noncommercial restriction**; this is not an MIT-licensed data package.
+
+- WWBP affect/intensity, age/gender, temporal orientation, English PERMA and
+  Spanish PERMA notices are retained in `licenses/`.
+- Historical Big Five and Dark Triad data were distributed by Peter Hughes under
+  CC BY-NC-SA 3.0 with the research attributions documented in
+  `docs/research.md`.
+- The optimism allowlist is from Peter Hughes’s optimismo project under CC
+  BY-NC-SA 3.0.
+- MIT notices for the predecessor utility projects lex-helpers (P. Hughes, 2024)
+  and weighted-lexica (Peter Hughes, 2020) are retained in `licenses/`.
+
+New implementation and documentation: Copyright 2026 Peter Hughes, distributed
+under CC BY-NC-SA 3.0. Existing third-party rights and notices are retained. See
+`LICENSE` for the full licence and `data/provenance.json` for pinned sources and
+transformations.
+
+This independent implementation is not affiliated with, endorsed by, or an
+official release of the World Well-Being Project.

package/README.md

@@ -0,0 +1,132 @@
+# wwbnlp
+
+**World Wellbeing NLP** — weighted-lexicon research tools in one typed,
+dependency-free package.
+
+Sentiment and arousal, temporal orientation, PERMA in English and Spanish, Big
+Five associations, Dark Triad scores, age and historical binary-gender scores,
+and an experimental optimism composition. This consolidates Peter Hughes’s
+earlier npm modules around one inspectable scoring engine.
+
+## Get started
+
+Install [wwbnlp](https://www.npmjs.com/package/wwbnlp) from npm:
+
+```sh
+npm install wwbnlp
+```
+
+Requires Node.js 22.12 or later. ESM and native `require()` on supported Node
+versions use the same module. The package is maintained by
+[phughesmcr](https://www.npmjs.com/~phughesmcr).
+
+```js
+import { analyse } from "wwbnlp";
+
+const result = analyse("I love spending time with my family :)", "affect");
+console.log(result.values); // AFFECT and INTENSITY scores, or null without evidence
+console.log(result.matches.AFFECT); // terms, counts, weights, contributions
+console.log(result.info); // original token count and matched feature counts
+```
+
+All analysis runs locally. The package makes no network requests and logs no
+input text.
+
+## Models
+
+| Model ID    | Replaces           | What the scores represent                                                                 | Default encoding |
+| ----------- | ------------------ | ----------------------------------------------------------------------------------------- | ---------------- |
+| `affect`    | affectimo          | AFFECT (valence) and INTENSITY (arousal)                                                  | frequency        |
+| `bigFive`   | bigfive            | O, C, E, A, N lexical association sums, **not calibrated trait predictions**              | binary           |
+| `darkTriad` | darktriad          | Historical darktriad, machiavellianism, narcissism, psychopathy linear scores             | frequency        |
+| `optimism`  | optimismo          | Affect weights restricted to the old future-term vocabulary; **experimental composition** | binary           |
+| `age`       | predictage         | AGE research regression output                                                            | frequency        |
+| `gender`    | predictgender      | GENDER historical classifier margin, **not a probability or gender identity**             | frequency        |
+| `temporal`  | prospectimo        | PAST, PRESENT, FUTURE linear scores                                                       | frequency        |
+| `perma`     | wellbeing_analysis | English positive/negative P, E, R, M, A lexical components                                | frequency        |
+| `permaEs`   | wellbeing_analysis | Spanish positive/negative P, E, R, M, A linear scores                                     | frequency        |
+
+`lex-helpers` and `weighted-lexica` become `createLexicon`, `score`, and
+`tokenize`. The [`wwbnlp/core`](docs/api.md) entry point loads the generic
+engine without bundled research data.
+
+## Explicit, inspectable results
+
+`analyse(textOrTokens, model, options)` always returns the same result shape:
+
+- `status`: `ok`, `empty`, or `no-matches`.
+- `values`: every model category; `null` when that category has no evidence.
+- `matches`: per-category `{ term, count, weight, contribution }` records.
+- `featureContributions`: supplied structural covariates and their
+  contributions.
+- `info`: `tokenCount`, `featureCount`, `matchedFeatureCount`,
+  `uniqueMatchedTerms`.
+- `warnings`: omitted structural features, where relevant.
+
+Unmatched input does not silently turn into an intercept-only prediction. Scores
+are neither clamped to a scale nor converted to labels automatically.
+
+Frequency encoding is
+`intercept + Σ(weight × occurrences / originalTokenCount)`. Unmatched tokens
+remain in the denominator. Binary encoding adds each matched term’s weight once.
+Percent encoding reports matched candidate-feature occurrences divided by all
+candidate-feature occurrences, excluding weights, intercepts and structural
+covariates.
+
+Defaults include every ngram size present in each model’s vocabulary. Supply
+`ngrams: [1]` for unigrams only, or `[]` to disable lexical matching. Ngrams are
+contiguous sequences from the same token stream, including punctuation.
+
+## Reproducibility
+
+The convenience tokenizer lowercases, normalizes Unicode to NFC and converts
+curly apostrophes. It preserves accents, social emoticons, punctuation, numbers,
+hashtags and mentions. **It is not the original studies’ tokenizer.** For
+controlled reproductions, pass the exact study token array instead; arrays are
+used as supplied.
+
+```js
+const result = analyse(["really", "good", "!"], "affect", {
+  encoding: "frequency",
+  includeIntercept: true,
+  decimals: 9,
+});
+```
+
+English PERMA includes four named structural covariates. Their weights are
+retained, but their values cannot be inferred reliably from one arbitrary text.
+Supply values measured with your research pipeline via `features`; omitted
+contributions produce warnings. Lexical-only results are not a reproduction of
+the full trained pipeline.
+
+See [API](docs/api.md), [migration](docs/migration.md), and
+[research methods and sources](docs/research.md). Each imported file has a
+pinned Git commit and SHA-256 in [data/provenance.json](data/provenance.json).
+`python3 scripts/import-data.py --check` verifies every coefficient against
+those sources.
+
+## Development
+
+```sh
+npm ci
+npm test            # shared-engine examples, edge cases and all-model regressions
+npm run check       # strict TypeScript, Deno lint and formatting
+npm pack --dry-run  # inspect the npm package
+```
+
+Deno 2 is needed for `npm run check`. The built modules also run under Deno; CI
+tests Node 22/24/26 and Deno.
+
+## Research scope and licence
+
+These historical social-media lexica produce research scores. The implementation
+does not establish current accuracy, diagnose an individual, or reproduce
+papers’ headline performance. Domain, language, tokenization and missing
+covariates affect results. The demographic models reflect historical training
+labels; Big Five associations and the optimism composition are not validated
+standalone predictors.
+
+Research coefficients retain **CC BY-NC-SA 3.0**, including the noncommercial
+restriction. The package uses the same licence. Original MIT utility notices are
+retained in `licenses/`; see [NOTICE.md](NOTICE.md) for attribution. This is an
+independent implementation, not an official WWBP distribution.

package/data/provenance.json

@@ -0,0 +1,67 @@
+{
+  "imported": "2026-10-04",
+  "sources": [
+    {
+      "repository": "wwbp/lexica",
+      "commit": "abaff9a1ae90757cfe77770fafbfcd16c92cd992",
+      "path": "affect_intensity/affect_intensity_lexicon.csv",
+      "sha256": "e8fd205f5d11ef6b51d6f5c88bf3998b35416e7e4d3f71b38c01820496b1c5cd"
+    },
+    {
+      "repository": "wwbp/lexica",
+      "commit": "abaff9a1ae90757cfe77770fafbfcd16c92cd992",
+      "path": "age_gender/emnlp14age.csv",
+      "sha256": "e7ea6de87b1d73a0e8e7615d27fdbfe25322949d2dfe66ea0b400c193b06ce1b"
+    },
+    {
+      "repository": "wwbp/lexica",
+      "commit": "abaff9a1ae90757cfe77770fafbfcd16c92cd992",
+      "path": "age_gender/emnlp14gender.csv",
+      "sha256": "2ed49285defa8c9c5b16f8443cbe134985b412071b7fdf8e4cc35d15294fcdab"
+    },
+    {
+      "repository": "wwbp/lexica",
+      "commit": "abaff9a1ae90757cfe77770fafbfcd16c92cd992",
+      "path": "temporal_orientation/temporal_orientation_lexicon.csv",
+      "sha256": "eba7978e9918ee1508ff64024ab10252e3cce1240238d373b226a55e9a504bc1"
+    },
+    {
+      "repository": "wwbp/lexica",
+      "commit": "abaff9a1ae90757cfe77770fafbfcd16c92cd992",
+      "path": "perma/permaV3_dd.csv",
+      "sha256": "6d954bbcf19d3690060b593b126930b0c580c0b5d45ef1ea95c0c544dece7079"
+    },
+    {
+      "repository": "wwbp/lexica",
+      "commit": "abaff9a1ae90757cfe77770fafbfcd16c92cd992",
+      "path": "spanish_perma/spanish_perma_v1.csv",
+      "sha256": "f57f3045fa641e25edca4ba2daee21c2ca140c7428110bde870ab737a9a19bae"
+    },
+    {
+      "repository": "phughesmcr/bigfive",
+      "commit": "6d928f158e6ad7977d43340d60513421b6a90863",
+      "path": "data/lexicon.json",
+      "sha256": "73206a96dd40fa877d42b00ac6237401fe802ee86b3a6bc1b1a3d2da67ee3ca3"
+    },
+    {
+      "repository": "phughesmcr/darktriad",
+      "commit": "f3d71c3b883489b3cccfd9e6263713032e68be49",
+      "path": "data/lexicon.json",
+      "sha256": "e55bd316f7d4f97d048c890ee15bf58d9bf29601e693d040e513a2271138d8b1"
+    },
+    {
+      "repository": "phughesmcr/optimismo",
+      "commit": "229a71b92ec692863430a3c83aa0725d10edfd2b",
+      "path": "data/future.json",
+      "sha256": "232099a4332a8274062947d363ca0be6147cd74d2c4c09f3ae6073be8f7166c5"
+    }
+  ],
+  "transformations": [
+    "CSV category labels mapped to historical public names; intercept and named structural features separated from lexical terms.",
+    "Spanish PERMA restored from original UTF-8 WWBP CSV rather than corrupted legacy JSON.",
+    "Optimism is the intersection of historical future-term allowlist and canonical affect weights; an experimental composition, not a separately trained model.",
+    "Big Five and Dark Triad retain historical repository weights.",
+    "An empty-string term with weight 0.078492 in the historical Big Five O category is excluded: it cannot represent a token.",
+    "Default ngram sizes are derived from the actual vocabulary, including age/gender phrases omitted by the historical wrappers."
+  ]
+}