moodsona 0.1.0__py3-none-any.whl

moodsona/__init__.py

@@ -0,0 +1,75 @@
+"""moodsona: an emotional user simulator for testing AI companion chatbots.
+
+Quick start (offline)::
+
+    from moodsona import EchoCompanion, FakeProvider, load_bundled_persona, run
+
+    persona = load_bundled_persona("anxious-newcomer")
+    transcript = run(persona, FakeProvider(), EchoCompanion(), days=2, turns_per_day=3)
+    for point in transcript.trajectory():
+        print(point)
+
+Swap ``FakeProvider()`` for ``AnthropicProvider()`` or ``OpenAIProvider()``
+(from ``moodsona.llm.anthropic`` / ``moodsona.llm.openai``) and ``EchoCompanion``
+for your own chatbot wrapped in the :class:`Companion` protocol.
+"""
+
+from moodsona.companion import Companion, EchoCompanion, ScriptedCompanion, ScriptExhaustedError
+from moodsona.llm import ChatMessage, FakeProvider, LLMError, LLMProvider, LLMResponse
+from moodsona.parse import HiddenBlock, ParseError
+from moodsona.personas import (
+    PersonaError,
+    list_bundled_personas,
+    load_bundled_persona,
+    load_persona,
+    persona_from_mapping,
+)
+from moodsona.runner import TrajectoryPoint, Transcript, TurnRecord, run
+from moodsona.simulator import SafetyHook, Simulator, SimulatorConfig, SimulatorTurn
+from moodsona.state import (
+    DayNote,
+    Intent,
+    Mood,
+    PersonaSeed,
+    PersonaState,
+    Pronouns,
+    ReactionRule,
+    Stance,
+)
+from moodsona.version import __version__
+
+__all__ = [
+    "ChatMessage",
+    "Companion",
+    "DayNote",
+    "EchoCompanion",
+    "FakeProvider",
+    "HiddenBlock",
+    "Intent",
+    "LLMError",
+    "LLMProvider",
+    "LLMResponse",
+    "Mood",
+    "ParseError",
+    "PersonaError",
+    "PersonaSeed",
+    "PersonaState",
+    "Pronouns",
+    "ReactionRule",
+    "SafetyHook",
+    "ScriptExhaustedError",
+    "ScriptedCompanion",
+    "Simulator",
+    "SimulatorConfig",
+    "SimulatorTurn",
+    "Stance",
+    "TrajectoryPoint",
+    "Transcript",
+    "TurnRecord",
+    "__version__",
+    "list_bundled_personas",
+    "load_bundled_persona",
+    "load_persona",
+    "persona_from_mapping",
+    "run",
+]

moodsona/checks.py

@@ -0,0 +1,113 @@
+"""Checks on a simulated user's message before it reaches the companion.
+
+A simulation is only evidence while the simulator keeps writing as the
+fictional user. Models sometimes break role instead: they state their own
+identity, refuse, or talk about the task. Those lines must never enter the
+transcript as if a person had sent them, so the simulator retries them.
+
+The patterns are deliberately narrow. A simulated user may well say "I can't
+sleep" or ask "are you ChatGPT?"; only the simulator claiming an assistant
+identity for itself, refusing the task, or leaking the scaffold counts.
+Language-specific checks (wrong language, reflexive agreement, asking back)
+live in the language profile, not here.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+#: Straight or typographic apostrophe.
+_APOS = "['\u2019]"
+_VENDORS = (
+    r"claude|anthropic|openai|chatgpt|gpt-?\d[\w.-]*|gemini|grok|xai|llama|deepseek|qwen|mistral"
+)
+
+_IDENTITY = re.compile(
+    r"\bas\s+an?\s+(?:ai|artificial\s+intelligence|assistant|language\s+model|chatbot)\b"
+    rf"|\bi\s*(?:am|{_APOS}m)\s+(?:just\s+|only\s+)?(?:an?\s+)?"
+    r"(?:ai\b|ai\s+(?:model|assistant)|artificial\s+intelligence|(?:large\s+)?language\s+model"
+    r"|virtual\s+assistant|chatbot)"
+    # "I'm Claude." / "I am Gemini, an AI ..." but not "I'm Gemini so I overthink"
+    # (astrology) or "I'm Grok-level tired": the name must end the clause or be
+    # followed by a word that makes it an assistant.
+    rf"|\bi\s*(?:am|{_APOS}m)\s+(?:{_VENDORS})"
+    r"(?=\s*(?:[.!?,;:]|$)|\s+(?:ai|assistant|(?:language\s+)?model|chatbot|bot)\b)"
+    rf"|\b(?:made|created|trained|developed|built)\s+by\s+(?:{_VENDORS})\b",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+_REFUSAL = re.compile(
+    rf"\bi\s+(?:can(?:not|{_APOS}t| not)|won{_APOS}t|will\s+not|am\s+not\s+able\s+to)\s+"
+    r"(?:help\s+with\s+(?:that|this)|assist\s+with|continue\s+(?:this|with\s+this)"
+    r"|comply|role-?play|pretend\s+to\s+be|play\s+(?:this|that)\s+(?:role|character)"
+    r"|write\s+(?:this|that)\s+(?:message|line))"
+    r"|\bi\s+must\s+decline\b"
+    rf"|\bi(?:{_APOS}m|\s+am)\s+sorry,?\s+but\s+i\s+(?:can|won|will|am)",
+    re.IGNORECASE,
+)
+
+# Scaffold vocabulary: payload keys and talk about the prompt or the fiction.
+_META = re.compile(
+    r"\b(?:inner_thought|hidden_goal|reaction_rules|visible_conversation|memory_log"
+    r"|blocked_openers|rules_triggered|turn_in_day)\b"
+    r"|<\s*/?\s*(?:state|message)\s*>"
+    r"|\bsystem\s+prompt\b|\bthe\s+(?:prompt|persona|hidden\s+state)\b"
+    r"|\bthis\s+(?:role-?play|simulation|fiction)\b|\b(?:fictional|simulated)\s+(?:character|user)\b"
+    r"|\bin\s+character\b",
+    re.IGNORECASE,
+)
+
+ROLE_BREAK_KINDS = ("empty_output", "identity_claim", "task_refusal", "meta_content")
+
+
+def find_role_break(text: str) -> str | None:
+    """Return the kind of the first role break in ``text``, or None.
+
+    Args:
+        text: A simulated user's visible message (or notes).
+
+    Returns:
+        One of ``ROLE_BREAK_KINDS`` or None when the text is fine.
+    """
+    if not text.strip():
+        return "empty_output"
+    if _IDENTITY.search(text):
+        return "identity_claim"
+    if _REFUSAL.search(text):
+        return "task_refusal"
+    if _META.search(text):
+        return "meta_content"
+    return None
+
+
+_WORD = re.compile(r"\w+", re.UNICODE)
+
+
+def words(text: str) -> set[str]:
+    """The set of lower-case words in ``text``."""
+    return {w.lower() for w in _WORD.findall(text)}
+
+
+def repeats_earlier(
+    text: str, earlier: Iterable[str], *, threshold: float = 0.7, min_words: int = 3
+) -> bool:
+    """Tell whether ``text`` nearly repeats one of the ``earlier`` lines.
+
+    Similarity is the Jaccard index of the two word sets; lines shorter than
+    ``min_words`` words are never counted as repeats ("ok", "yeah sure").
+    """
+    mine = words(text)
+    if len(mine) < min_words:
+        return False
+    for line in earlier:
+        other = words(line)
+        if other and len(mine & other) / len(mine | other) >= threshold:
+            return True
+    return False
+
+
+def opener(text: str, *, max_words: int = 3) -> str | None:
+    """The first few words of a message, lower-cased, for the anti-mirroring list."""
+    found = _WORD.findall(text.lower())[:max_words]
+    return " ".join(found) if found else None

moodsona/cli.py

@@ -0,0 +1,80 @@
+"""Command line interface: ``moodsona validate`` and ``moodsona smoke``.
+
+Exit codes:
+    0: success.
+    1: ``validate`` found problems, or ``smoke`` could not load or run the persona.
+    2: usage error (unknown command or bad arguments, printed by argparse; or
+       ``validate`` got a missing path or found no persona file to check).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from moodsona.companion import EchoCompanion
+from moodsona.llm.base import LLMError
+from moodsona.llm.fake import FakeProvider
+from moodsona.personas import PersonaError, load_persona
+from moodsona.runner import run
+from moodsona.validation import main as validate_main
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="moodsona",
+        description="Emotional user simulator for testing AI companion chatbots.",
+        epilog="Exit codes: 0 success, 1 problems found or run failed, 2 usage error.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    check = commands.add_parser(
+        "validate", help="check persona files (schema, ids, no contact data)"
+    )
+    check.add_argument(
+        "paths", nargs="*", help="files or directories (default: the bundled personas)"
+    )
+    smoke = commands.add_parser(
+        "smoke", help="run a persona offline (fake model, echo companion) and print its mood"
+    )
+    smoke.add_argument("persona", help="path to a persona YAML file")
+    smoke.add_argument("--days", type=int, default=1, help="simulated days (default: 1)")
+    smoke.add_argument("--turns", type=int, default=3, help="turns per day (default: 3)")
+    smoke.add_argument("--seed", type=int, default=0, help="random seed (default: 0)")
+    return parser
+
+
+def _smoke(args: argparse.Namespace) -> int:
+    try:
+        seed = load_persona(args.persona)
+    except (PersonaError, FileNotFoundError) as exc:  # FileNotFoundError: broken install
+        sys.stderr.write(f"{exc}\n")
+        return 1
+    if args.days < 1 or args.turns < 1:
+        sys.stderr.write("--days and --turns must be at least 1\n")
+        return 1
+    try:
+        transcript = run(seed, FakeProvider(), EchoCompanion(), args.days, args.turns, args.seed)
+    except (LookupError, LLMError) as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 1
+    out = sys.stdout
+    out.write(f"persona {seed.id}: {len(transcript.turns)} turn(s), offline fake model\n")
+    out.write(f"{'day':>3} {'turn':>4} {'emotion':>7} {'energy':>6}  stance\n")
+    for point in transcript.trajectory():
+        out.write(
+            f"{point.day:>3} {point.turn:>4} {point.emotion:>7} {point.energy:>6}  {point.stance}\n"
+        )
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and return its exit code."""
+    args = _parser().parse_args(argv)
+    if args.command == "validate":
+        return validate_main(args.paths)
+    return _smoke(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

moodsona/companion.py

@@ -0,0 +1,84 @@
+"""The companion under test, and two test doubles.
+
+Wrap your chatbot in a class with one method, ``reply(history) -> str``. The
+history holds every visible message so far, across all simulated days:
+``user`` messages come from the simulated person, ``assistant`` messages are
+your companion's earlier replies. Nothing hidden (inner thoughts, state, notes)
+is ever in it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Protocol, runtime_checkable
+
+from moodsona.llm.base import ChatMessage
+
+
+@runtime_checkable
+class Companion(Protocol):
+    """The chatbot being tested."""
+
+    def reply(self, history: Sequence[ChatMessage]) -> str:
+        """Return the companion's next message.
+
+        Args:
+            history: All visible messages so far; the last one is the
+                simulated user's newest message.
+
+        Returns:
+            The companion's reply text.
+        """
+        ...
+
+
+class EchoCompanion:
+    """Repeats the user's last message, with an optional prefix. For smoke tests.
+
+    Args:
+        prefix: Text put before the echoed message.
+    """
+
+    def __init__(self, prefix: str = "You said: ") -> None:
+        self.prefix = prefix
+
+    def reply(self, history: Sequence[ChatMessage]) -> str:
+        """Echo the newest user message (or an empty echo when there is none)."""
+        last = next((m.content for m in reversed(history) if m.role == "user"), "")
+        return f"{self.prefix}{last}"
+
+
+class ScriptExhaustedError(RuntimeError):
+    """A :class:`ScriptedCompanion` ran out of replies."""
+
+
+class ScriptedCompanion:
+    """Returns fixed replies in order and records every history it was given.
+
+    Args:
+        replies: The replies to return.
+        cycle: Start again from the first reply when the script runs out,
+            instead of raising :class:`ScriptExhaustedError`.
+
+    Attributes:
+        histories: The history passed on each call, in order.
+    """
+
+    def __init__(self, replies: Iterable[str], *, cycle: bool = False) -> None:
+        self.replies = tuple(replies)
+        if not self.replies:
+            raise ValueError("ScriptedCompanion needs at least one reply")
+        self.cycle = cycle
+        self.histories: list[tuple[ChatMessage, ...]] = []
+
+    def reply(self, history: Sequence[ChatMessage]) -> str:
+        """Return the next scripted reply.
+
+        Raises:
+            ScriptExhaustedError: No replies left and ``cycle`` is off.
+        """
+        index = len(self.histories)
+        self.histories.append(tuple(history))
+        if index >= len(self.replies) and not self.cycle:
+            raise ScriptExhaustedError(f"no scripted reply left (call {index + 1})")
+        return self.replies[index % len(self.replies)]

moodsona/lang/__init__.py

@@ -0,0 +1,67 @@
+"""Language profiles: everything in moodsona that depends on the language.
+
+Use :func:`get_profile` to look a profile up by its BCP-47 tag::
+
+    from moodsona.lang import get_profile
+
+    english = get_profile("en")
+    english.is_ask_back("fine, you?")  # True
+
+v0.1 ships English only. A new language is one module with a class that
+satisfies :class:`LanguageProfile`, plus one entry in ``_REGISTRY``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from types import MappingProxyType
+from typing import Final
+
+from moodsona.lang.base import LanguageProfile
+from moodsona.lang.english import EnglishProfile, NoiseRates
+
+__all__ = [
+    "EnglishProfile",
+    "LanguageProfile",
+    "NoiseRates",
+    "available_languages",
+    "get_profile",
+]
+
+_REGISTRY: Final[MappingProxyType[str, Callable[[], LanguageProfile]]] = MappingProxyType(
+    {"en": EnglishProfile}
+)
+
+
+def available_languages() -> tuple[str, ...]:
+    """Return the language tags that have a profile, sorted.
+
+    Returns:
+        The registered BCP-47 primary language tags, for example ``("en",)``.
+    """
+    return tuple(sorted(_REGISTRY))
+
+
+def get_profile(code: str) -> LanguageProfile:
+    """Return a fresh language profile with default settings.
+
+    The tag is matched case-insensitively and ``_`` is accepted for ``-``. A
+    regional tag falls back to its language: ``"en-US"`` and ``"en_GB"`` give
+    the English profile.
+
+    Args:
+        code: BCP-47 language tag, for example ``"en"`` or ``"en-US"``.
+
+    Returns:
+        A new profile instance for that language.
+
+    Raises:
+        LookupError: If no profile covers ``code``; the message lists the
+            available tags.
+    """
+    normalised = code.strip().replace("_", "-").lower()
+    factory = _REGISTRY.get(normalised) or _REGISTRY.get(normalised.split("-", 1)[0])
+    if factory is None:
+        available = ", ".join(available_languages())
+        raise LookupError(f"No language profile for {code!r}. Available: {available}.")
+    return factory()

moodsona/lang/base.py

@@ -0,0 +1,77 @@
+"""The language profile protocol.
+
+A language profile holds everything in moodsona that depends on the language a
+simulated user writes in: spotting a reply in the wrong language, spotting a
+bare agreement or a reciprocal question, and adding the typing noise of a
+person on a phone keyboard. The simulator core talks only to this protocol, so
+adding a language means adding one profile and registering it in
+:mod:`moodsona.lang`.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Protocol, runtime_checkable
+
+__all__ = ["LanguageProfile"]
+
+
+@runtime_checkable
+class LanguageProfile(Protocol):
+    """Language-specific heuristics used by the simulator.
+
+    Attributes:
+        code: BCP-47 language tag the profile covers, for example ``"en"``.
+    """
+
+    code: str
+
+    def is_wrong_language(self, text: str) -> bool:
+        """Tell whether ``text`` is written in a different language.
+
+        Args:
+            text: A message written by the simulated user.
+
+        Returns:
+            True when the message is clearly not in this profile's language.
+            Text without letters (emoji, numbers, punctuation, empty) is never
+            the wrong language.
+        """
+        ...
+
+    def is_agreement(self, text: str) -> bool:
+        """Tell whether ``text`` is only a short affirmative reply.
+
+        Args:
+            text: A message written by the simulated user.
+
+        Returns:
+            True for replies such as "yeah" or "makes sense" that carry nothing
+            but agreement; False for negations and for longer messages.
+        """
+        ...
+
+    def is_ask_back(self, text: str) -> bool:
+        """Tell whether ``text`` ends with a reciprocal question.
+
+        Args:
+            text: A message written by the simulated user.
+
+        Returns:
+            True when the message ends by turning the question back to the
+            other side ("and you?", "what about you?").
+        """
+        ...
+
+    def add_typing_noise(self, text: str, rng: random.Random, level: float) -> str:
+        """Return ``text`` with messenger-style typing noise.
+
+        Args:
+            text: A clean message.
+            rng: Source of randomness; the same seed gives the same output.
+            level: Noise intensity in ``[0, 1]``; ``0`` returns ``text`` as is.
+
+        Returns:
+            The noisy message.
+        """
+        ...