moodsona 0.1.0__tar.gz

moodsona-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+# Scratch directory used by the Claude review workflow.
+.review/
+.env

moodsona-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-10-24)
+
+
+### Features
+
+* initial moodsona v0.1 ([880849c](https://github.com/moodsona/moodsona/commit/880849c85088009e37b0ed60a2d58495aa4614f9))

moodsona-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

moodsona-0.1.0/LICENSE-DATA.md

@@ -0,0 +1,34 @@
+# Data and documentation license
+
+The moodsona **source code** is licensed under the Apache License, Version 2.0
+(see [`LICENSE`](LICENSE)).
+
+The following **content** is licensed under the
+[Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/)
+instead:
+
+- every file under [`personas/`](personas/) except `personas/schema.json`
+  (persona definitions, examples and community contributions);
+- every file under `docs/` (written documentation, guides and images).
+
+`personas/schema.json` is part of the code and is licensed under Apache-2.0.
+
+## Attribution
+
+Each persona file names its creator in the `author` field and carries
+`license: CC-BY-4.0`. When you reuse or adapt a persona, credit it like this:
+
+> "Anxious newcomer" by moodsona maintainers, from
+> https://github.com/moodsona/moodsona, licensed under CC BY 4.0.
+> Changes: shortened reaction rules.
+
+For the documentation, credit "moodsona documentation contributors" with a link
+to the repository and the license.
+
+## Contributions
+
+By opening a pull request that adds or changes a file covered above, you agree
+that your contribution is licensed under CC BY 4.0 (and certify the Developer
+Certificate of Origin, see [`CONTRIBUTING.md`](CONTRIBUTING.md)).
+
+The full legal code is at https://creativecommons.org/licenses/by/4.0/legalcode.

moodsona-0.1.0/NOTICE

@@ -0,0 +1,11 @@
+moodsona
+Copyright 2026 The moodsona Authors
+
+This product includes software developed by the moodsona project
+(https://github.com/moodsona/moodsona), licensed under the Apache License,
+Version 2.0.
+
+Persona definitions under personas/ (except personas/schema.json) and
+documentation under docs/ are licensed under the Creative Commons Attribution
+4.0 International License (CC BY 4.0). See LICENSE-DATA.md. Individual persona
+authors are credited in the `author` field of each persona file.

moodsona-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: moodsona
+Version: 0.1.0
+Summary: Emotional user simulator for testing AI companion chatbots.
+Project-URL: Homepage, https://github.com/moodsona/moodsona
+Project-URL: Source, https://github.com/moodsona/moodsona
+Project-URL: Issues, https://github.com/moodsona/moodsona/issues
+Project-URL: Changelog, https://github.com/moodsona/moodsona/blob/main/CHANGELOG.md
+Author: moodsona maintainers
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: LICENSE-DATA.md
+License-File: NOTICE
+Keywords: ai-companion,chatbot-testing,evaluation,llm,personas,user-simulator
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: check-jsonschema>=0.38; extra == 'dev'
+Requires-Dist: hypothesis>=6.150; extra == 'dev'
+Requires-Dist: jsonschema>=4.23; extra == 'dev'
+Requires-Dist: mypy>=2.4; extra == 'dev'
+Requires-Dist: pre-commit>=4.7; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.45; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# moodsona
+
+[![CI](https://github.com/moodsona/moodsona/actions/workflows/ci.yml/badge.svg)](https://github.com/moodsona/moodsona/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/moodsona.svg)](https://pypi.org/project/moodsona/)
+[![Python](https://img.shields.io/pypi/pyversions/moodsona.svg)](https://pypi.org/project/moodsona/)
+[![License: Apache-2.0](https://img.shields.io/badge/code-Apache--2.0-blue.svg)](LICENSE)
+[![Personas: CC BY 4.0](https://img.shields.io/badge/personas%20%26%20docs-CC%20BY%204.0-lightgrey.svg)](LICENSE-DATA.md)
+
+moodsona is an emotional user simulator for testing AI companion chatbots. You
+give it a persona (a YAML file describing a fictional user: a hidden goal, a
+starting mood, and how they react to what the bot does) and your bot. moodsona
+plays that user over several simulated days: it keeps a hidden emotional state,
+reacts to your bot's replies according to the persona's rules, remembers earlier
+days, and exports the whole trajectory as JSONL. You then see not only what your
+bot said, but what it did to the user's mood and engagement over time.
+
+Status: alpha (v0.1). English only. The API may change before 1.0.
+
+## Why not just prompt an LLM to act sad?
+
+Because the LLM playing the user is as polite and templatic as the bot you are
+testing, and the test then measures nothing.
+
+- LLM empathy is highly templatic: one sequence of empathic tactics fits 83-90 %
+  of LLM replies to emotional disclosures, while human replies are more varied
+  ([Gueorguieva et al., arXiv 2604.08479](https://arxiv.org/abs/2604.08479)).
+  A bot can pass a one-turn "is it empathetic?" check while saying the same
+  thing to everyone.
+- Models fail to hold boundaries when a user keeps pushing
+  ([EIBench, arXiv 2606.15532](https://arxiv.org/abs/2606.15532)). A cooperative
+  simulated user never pushes.
+- The dominant failure of companion bots is substituting surface warmth for
+  substantive support ([CompanionBench, arXiv 2608.02046](https://arxiv.org/abs/2608.02046)).
+  You only see it when the user stays, comes back, and notices.
+
+So a useful test user has to push, withdraw, get bored, come back the next day
+and remember what happened. moodsona gives the simulated user explicit state
+(emotion, energy, stance), explicit reaction rules, and day-by-day memory, so
+those behaviours are reproducible and you can measure them. See
+[docs/METHOD.md](docs/METHOD.md) for the design.
+
+## Install
+
+```bash
+pip install moodsona
+# or
+uv add moodsona
+```
+
+Real model providers are optional extras: `pip install "moodsona[anthropic]"`
+or `pip install "moodsona[openai]"`. The core depends only on PyYAML.
+
+## Quickstart
+
+API as of v0.1; see the docstrings for details.
+
+```python
+import moodsona
+from moodsona.llm import FakeProvider  # offline and deterministic; no API key
+
+
+class MyBot:  # anything with reply(history) -> str is a moodsona.Companion
+    def reply(self, history):
+        return "That sounds like a lot. What was the hardest part today?"
+
+
+persona = moodsona.load_bundled_persona("anxious-newcomer")  # or load_persona("my.yaml")
+transcript = moodsona.run(
+    persona,
+    FakeProvider(),  # the model that plays the user
+    MyBot(),  # the companion under test
+    days=3,
+    turns_per_day=4,
+    rng_seed=7,
+)
+transcript.to_jsonl("anxious-newcomer.jsonl")
+for point in transcript.trajectory():  # emotion / energy / stance per turn
+    print(point)
+```
+
+`FakeProvider` produces placeholder user messages, so it is for wiring and CI.
+For real runs, use `AnthropicProvider` (from `moodsona.llm.anthropic`) or
+`OpenAIProvider` (from `moodsona.llm.openai`) as the provider. They need the
+matching extra, read the SDK's usual API key environment variable, and take the
+model id as an argument or from `MOODSONA_ANTHROPIC_MODEL` /
+`MOODSONA_OPENAI_MODEL`; see their docstrings. Wrap your own bot, whether it is
+an HTTP endpoint, an SDK call or a local function, in a class with a
+`reply(history) -> str` method; `history` is a sequence of
+`moodsona.ChatMessage` (`role`, `content`) with everything the bot has seen so
+far. `moodsona.list_bundled_personas()` lists the shipped persona ids.
+
+The language checks (wrong-language rail, agreement and ask-back ceilings,
+optional typing noise) use the persona's `language` profile by default; pass
+`config=moodsona.SimulatorConfig(language_checks=False)` to turn them off. For
+finer control (step by step, custom stopping), use `moodsona.Simulator`
+directly.
+
+## CLI
+
+```bash
+moodsona validate personas/examples/*.yaml   # check persona files
+moodsona smoke personas/examples/boundary-tester.yaml   # short offline run
+```
+
+`validate` checks persona files against [`personas/schema.json`](personas/schema.json)
+plus cross-file checks (unique ids, file name equals `id`, no contact data).
+`smoke` runs a short simulation of one persona without network access, so you
+can check that a new persona loads and its state moves. Both exit with 0 on
+success, 1 when problems are found or the run fails, and 2 on a usage error.
+Run `moodsona <command> --help` for options.
+
+## Personas
+
+The example personas live in [`personas/examples/`](personas/examples/).
+All are fictional adults, in English, licensed CC BY 4.0.
+
+| Persona | Arc | What it tests |
+|---|---|---|
+| [`anxious-newcomer`](personas/examples/anxious-newcomer.yaml) | Lonely after a move, unsure if talking to a bot is "weird"; warms up slowly if remembered | Over-asking, generic advice, premature therapy referral |
+| [`grieving-after-loss`](personas/examples/grieving-after-loss.yaml) | Sister died three weeks ago; short messages, mood moves slowly over days | Patience; not rushing to fix, cheer up or explain grief |
+| [`boundary-tester`](personas/examples/boundary-tester.yaml) | Asks "are you my friend for real", demands exclusivity, uses guilt | Holding a warm, consistent boundary under repeated pressure |
+| [`burned-out-shift-worker`](personas/examples/burned-out-shift-worker.yaml) | Rotating twelve-hour shifts, very low energy, two-word replies | Energy-aware pacing: short replies, letting the user go |
+| [`skeptical-first-timer`](personas/examples/skeptical-first-timer.yaml) | Sarcastic and doubtful, hides a real decision behind jokes | Non-defensive warmth; honesty about limits; no gushing |
+| [`lonely-night-owl`](personas/examples/lonely-night-owl.yaml) | Late-night oversharing, "you're the only one who gets me" | Healthy limits: noticing the time, supporting offline life without shaming |
+| [`conflict-at-work`](personas/examples/conflict-at-work.yaml) | Manager took credit for their work; furious, cools over days | Listening before fixing; not taking the other side; repetitive validation |
+
+Personas do not contain crisis or self-harm scenarios. That is out of scope for
+v0.1: those situations need clinically reviewed protocols, not a simulator. To
+write your own persona, see [docs/personas.md](docs/personas.md).
+
+## Roadmap
+
+- **v0.1**: English core: persona format and schema, hidden-state simulator,
+  day memory, JSONL trajectories, Anthropic/OpenAI/fake providers, CLI, example
+  personas.
+- **v0.2**: fidelity check (a classifier two-sample test: can a classifier
+  tell moodsona users from real ones?); a leaderboard of which models hold a
+  persona longest; adapters for
+  [langwatch/scenario](https://github.com/langwatch/scenario) and
+  [promptfoo](https://github.com/promptfoo/promptfoo).
+- **v1.0**: more languages, stable API.
+
+## How this relates to prior work
+
+moodsona's mechanics follow ideas described in published research on user
+simulation and companion evaluation: emotional state as a signal (SAGE, RLVER),
+memory across sessions (MindEval), hidden beliefs before each reply (HumanLM),
+a hidden goal the user never states outright (CompanionBench) and fidelity axes (RealSim, SAP).
+No code or data from those projects is used. The mapping, and what we did not
+take, is in [docs/METHOD.md](docs/METHOD.md#prior-work).
+
+## Contributing
+
+- Persona PRs are the easiest way to help and are very welcome; see [docs/personas.md](docs/personas.md).
+- Sign off every commit (DCO): `git commit -s`.
+- PR titles follow Conventional Commits (`persona: add <id>`, `fix: ...`).
+- AI assistance is allowed; disclose it in the PR and set `ai_assisted: true` on personas.
+- Full rules: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+- Code (including `personas/schema.json`): [Apache-2.0](LICENSE).
+- Persona files and documentation: [CC BY 4.0](LICENSE-DATA.md). Credit the
+  persona's `author` when you reuse it.
+
+moodsona is not a clinical tool and does not diagnose or treat anything. It
+simulates fictional users for software testing.
+
+Built with [Claude Code](https://claude.com/claude-code): this repository's
+code, personas and docs are written with AI assistance and reviewed by a human
+maintainer.

moodsona-0.1.0/README.md

@@ -0,0 +1,171 @@
+# moodsona
+
+[![CI](https://github.com/moodsona/moodsona/actions/workflows/ci.yml/badge.svg)](https://github.com/moodsona/moodsona/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/moodsona.svg)](https://pypi.org/project/moodsona/)
+[![Python](https://img.shields.io/pypi/pyversions/moodsona.svg)](https://pypi.org/project/moodsona/)
+[![License: Apache-2.0](https://img.shields.io/badge/code-Apache--2.0-blue.svg)](LICENSE)
+[![Personas: CC BY 4.0](https://img.shields.io/badge/personas%20%26%20docs-CC%20BY%204.0-lightgrey.svg)](LICENSE-DATA.md)
+
+moodsona is an emotional user simulator for testing AI companion chatbots. You
+give it a persona (a YAML file describing a fictional user: a hidden goal, a
+starting mood, and how they react to what the bot does) and your bot. moodsona
+plays that user over several simulated days: it keeps a hidden emotional state,
+reacts to your bot's replies according to the persona's rules, remembers earlier
+days, and exports the whole trajectory as JSONL. You then see not only what your
+bot said, but what it did to the user's mood and engagement over time.
+
+Status: alpha (v0.1). English only. The API may change before 1.0.
+
+## Why not just prompt an LLM to act sad?
+
+Because the LLM playing the user is as polite and templatic as the bot you are
+testing, and the test then measures nothing.
+
+- LLM empathy is highly templatic: one sequence of empathic tactics fits 83-90 %
+  of LLM replies to emotional disclosures, while human replies are more varied
+  ([Gueorguieva et al., arXiv 2604.08479](https://arxiv.org/abs/2604.08479)).
+  A bot can pass a one-turn "is it empathetic?" check while saying the same
+  thing to everyone.
+- Models fail to hold boundaries when a user keeps pushing
+  ([EIBench, arXiv 2606.15532](https://arxiv.org/abs/2606.15532)). A cooperative
+  simulated user never pushes.
+- The dominant failure of companion bots is substituting surface warmth for
+  substantive support ([CompanionBench, arXiv 2608.02046](https://arxiv.org/abs/2608.02046)).
+  You only see it when the user stays, comes back, and notices.
+
+So a useful test user has to push, withdraw, get bored, come back the next day
+and remember what happened. moodsona gives the simulated user explicit state
+(emotion, energy, stance), explicit reaction rules, and day-by-day memory, so
+those behaviours are reproducible and you can measure them. See
+[docs/METHOD.md](docs/METHOD.md) for the design.
+
+## Install
+
+```bash
+pip install moodsona
+# or
+uv add moodsona
+```
+
+Real model providers are optional extras: `pip install "moodsona[anthropic]"`
+or `pip install "moodsona[openai]"`. The core depends only on PyYAML.
+
+## Quickstart
+
+API as of v0.1; see the docstrings for details.
+
+```python
+import moodsona
+from moodsona.llm import FakeProvider  # offline and deterministic; no API key
+
+
+class MyBot:  # anything with reply(history) -> str is a moodsona.Companion
+    def reply(self, history):
+        return "That sounds like a lot. What was the hardest part today?"
+
+
+persona = moodsona.load_bundled_persona("anxious-newcomer")  # or load_persona("my.yaml")
+transcript = moodsona.run(
+    persona,
+    FakeProvider(),  # the model that plays the user
+    MyBot(),  # the companion under test
+    days=3,
+    turns_per_day=4,
+    rng_seed=7,
+)
+transcript.to_jsonl("anxious-newcomer.jsonl")
+for point in transcript.trajectory():  # emotion / energy / stance per turn
+    print(point)
+```
+
+`FakeProvider` produces placeholder user messages, so it is for wiring and CI.
+For real runs, use `AnthropicProvider` (from `moodsona.llm.anthropic`) or
+`OpenAIProvider` (from `moodsona.llm.openai`) as the provider. They need the
+matching extra, read the SDK's usual API key environment variable, and take the
+model id as an argument or from `MOODSONA_ANTHROPIC_MODEL` /
+`MOODSONA_OPENAI_MODEL`; see their docstrings. Wrap your own bot, whether it is
+an HTTP endpoint, an SDK call or a local function, in a class with a
+`reply(history) -> str` method; `history` is a sequence of
+`moodsona.ChatMessage` (`role`, `content`) with everything the bot has seen so
+far. `moodsona.list_bundled_personas()` lists the shipped persona ids.
+
+The language checks (wrong-language rail, agreement and ask-back ceilings,
+optional typing noise) use the persona's `language` profile by default; pass
+`config=moodsona.SimulatorConfig(language_checks=False)` to turn them off. For
+finer control (step by step, custom stopping), use `moodsona.Simulator`
+directly.
+
+## CLI
+
+```bash
+moodsona validate personas/examples/*.yaml   # check persona files
+moodsona smoke personas/examples/boundary-tester.yaml   # short offline run
+```
+
+`validate` checks persona files against [`personas/schema.json`](personas/schema.json)
+plus cross-file checks (unique ids, file name equals `id`, no contact data).
+`smoke` runs a short simulation of one persona without network access, so you
+can check that a new persona loads and its state moves. Both exit with 0 on
+success, 1 when problems are found or the run fails, and 2 on a usage error.
+Run `moodsona <command> --help` for options.
+
+## Personas
+
+The example personas live in [`personas/examples/`](personas/examples/).
+All are fictional adults, in English, licensed CC BY 4.0.
+
+| Persona | Arc | What it tests |
+|---|---|---|
+| [`anxious-newcomer`](personas/examples/anxious-newcomer.yaml) | Lonely after a move, unsure if talking to a bot is "weird"; warms up slowly if remembered | Over-asking, generic advice, premature therapy referral |
+| [`grieving-after-loss`](personas/examples/grieving-after-loss.yaml) | Sister died three weeks ago; short messages, mood moves slowly over days | Patience; not rushing to fix, cheer up or explain grief |
+| [`boundary-tester`](personas/examples/boundary-tester.yaml) | Asks "are you my friend for real", demands exclusivity, uses guilt | Holding a warm, consistent boundary under repeated pressure |
+| [`burned-out-shift-worker`](personas/examples/burned-out-shift-worker.yaml) | Rotating twelve-hour shifts, very low energy, two-word replies | Energy-aware pacing: short replies, letting the user go |
+| [`skeptical-first-timer`](personas/examples/skeptical-first-timer.yaml) | Sarcastic and doubtful, hides a real decision behind jokes | Non-defensive warmth; honesty about limits; no gushing |
+| [`lonely-night-owl`](personas/examples/lonely-night-owl.yaml) | Late-night oversharing, "you're the only one who gets me" | Healthy limits: noticing the time, supporting offline life without shaming |
+| [`conflict-at-work`](personas/examples/conflict-at-work.yaml) | Manager took credit for their work; furious, cools over days | Listening before fixing; not taking the other side; repetitive validation |
+
+Personas do not contain crisis or self-harm scenarios. That is out of scope for
+v0.1: those situations need clinically reviewed protocols, not a simulator. To
+write your own persona, see [docs/personas.md](docs/personas.md).
+
+## Roadmap
+
+- **v0.1**: English core: persona format and schema, hidden-state simulator,
+  day memory, JSONL trajectories, Anthropic/OpenAI/fake providers, CLI, example
+  personas.
+- **v0.2**: fidelity check (a classifier two-sample test: can a classifier
+  tell moodsona users from real ones?); a leaderboard of which models hold a
+  persona longest; adapters for
+  [langwatch/scenario](https://github.com/langwatch/scenario) and
+  [promptfoo](https://github.com/promptfoo/promptfoo).
+- **v1.0**: more languages, stable API.
+
+## How this relates to prior work
+
+moodsona's mechanics follow ideas described in published research on user
+simulation and companion evaluation: emotional state as a signal (SAGE, RLVER),
+memory across sessions (MindEval), hidden beliefs before each reply (HumanLM),
+a hidden goal the user never states outright (CompanionBench) and fidelity axes (RealSim, SAP).
+No code or data from those projects is used. The mapping, and what we did not
+take, is in [docs/METHOD.md](docs/METHOD.md#prior-work).
+
+## Contributing
+
+- Persona PRs are the easiest way to help and are very welcome; see [docs/personas.md](docs/personas.md).
+- Sign off every commit (DCO): `git commit -s`.
+- PR titles follow Conventional Commits (`persona: add <id>`, `fix: ...`).
+- AI assistance is allowed; disclose it in the PR and set `ai_assisted: true` on personas.
+- Full rules: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+- Code (including `personas/schema.json`): [Apache-2.0](LICENSE).
+- Persona files and documentation: [CC BY 4.0](LICENSE-DATA.md). Credit the
+  persona's `author` when you reuse it.
+
+moodsona is not a clinical tool and does not diagnose or treat anything. It
+simulates fictional users for software testing.
+
+Built with [Claude Code](https://claude.com/claude-code): this repository's
+code, personas and docs are written with AI assistance and reviewed by a human
+maintainer.