personalitygen 0.1.0__tar.gz

personalitygen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 B.T. Franklin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

personalitygen-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: personalitygen
+Version: 0.1.0
+Summary: Generate and manage simulated human-like personalities based on the Big Five model.
+Keywords: personality,big-five,ocean,simulation
+Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
+License: MIT
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Project-URL: Homepage, https://github.com/btfranklin/personalitygen
+Project-URL: Issues, https://github.com/btfranklin/personalitygen/issues
+Project-URL: Changelog, https://github.com/btfranklin/personalitygen/releases
+Project-URL: Repository, https://github.com/btfranklin/personalitygen.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# personalitygen
+
+![personalitygen social preview](.github/social%20preview/personalitygen_social_preview.jpg)
+
+`personalitygen` generates and manages simulated human-like personalities based on the Big Five (OCEAN) model. It is designed for
+simulation, storytelling, and testing scenarios where you want plausible, varied personality profiles without running surveys.
+
+## Intent and scope
+
+- Generate full Big Five profiles with sub-trait components and aggregate scores.
+- Bias outputs by life stage using tuned Gaussian distributions (child, young adult, adult).
+- Derive a conflict-resolution style from trait weights, plus mapped concern-for-self/others.
+- Support deterministic generation by accepting a seeded random source.
+- Stay lightweight and dependency-free (pure Python).
+
+This package is not a clinical assessment tool and does not implement questionnaires or scoring rubrics.
+
+## Model overview
+
+- Big Five traits: openness, conscientiousness, extraversion, agreeableness, neuroticism.
+- Each trait is composed of three sub-traits and a weighted aggregate score.
+- Life stage influences distribution means and standard deviations for sampling.
+- Conflict-resolution style is selected from avoiding, obliging, integrating, dominating, or compromising based on trait scores.
+
+## Usage
+
+```python
+from personalitygen import BigFivePersonality, LifeStage
+
+personality = BigFivePersonality.random(LifeStage.ADULT)
+print(personality.trait_configuration)
+print(personality.conflict_resolution_configuration)
+```
+
+If you want deterministic output, pass a seeded random number generator:
+
+```python
+import random
+from personalitygen import BigFiveTraitConfiguration, LifeStage
+
+rng = random.Random(42)
+traits = BigFiveTraitConfiguration.random(LifeStage.YOUNG_ADULT, rng=rng)
+print(traits)
+```
+
+## Development
+
+```bash
+pdm install --group dev
+pdm run test
+```

personalitygen-0.1.0/README.md

@@ -0,0 +1,51 @@
+# personalitygen
+
+![personalitygen social preview](.github/social%20preview/personalitygen_social_preview.jpg)
+
+`personalitygen` generates and manages simulated human-like personalities based on the Big Five (OCEAN) model. It is designed for
+simulation, storytelling, and testing scenarios where you want plausible, varied personality profiles without running surveys.
+
+## Intent and scope
+
+- Generate full Big Five profiles with sub-trait components and aggregate scores.
+- Bias outputs by life stage using tuned Gaussian distributions (child, young adult, adult).
+- Derive a conflict-resolution style from trait weights, plus mapped concern-for-self/others.
+- Support deterministic generation by accepting a seeded random source.
+- Stay lightweight and dependency-free (pure Python).
+
+This package is not a clinical assessment tool and does not implement questionnaires or scoring rubrics.
+
+## Model overview
+
+- Big Five traits: openness, conscientiousness, extraversion, agreeableness, neuroticism.
+- Each trait is composed of three sub-traits and a weighted aggregate score.
+- Life stage influences distribution means and standard deviations for sampling.
+- Conflict-resolution style is selected from avoiding, obliging, integrating, dominating, or compromising based on trait scores.
+
+## Usage
+
+```python
+from personalitygen import BigFivePersonality, LifeStage
+
+personality = BigFivePersonality.random(LifeStage.ADULT)
+print(personality.trait_configuration)
+print(personality.conflict_resolution_configuration)
+```
+
+If you want deterministic output, pass a seeded random number generator:
+
+```python
+import random
+from personalitygen import BigFiveTraitConfiguration, LifeStage
+
+rng = random.Random(42)
+traits = BigFiveTraitConfiguration.random(LifeStage.YOUNG_ADULT, rng=rng)
+print(traits)
+```
+
+## Development
+
+```bash
+pdm install --group dev
+pdm run test
+```

personalitygen-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "personalitygen"
+version = "0.1.0"
+description = "Generate and manage simulated human-like personalities based on the Big Five model."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "B.T. Franklin", email = "brandon.franklin@gmail.com" },
+]
+keywords = [
+    "personality",
+    "big-five",
+    "ocean",
+    "simulation",
+]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/btfranklin/personalitygen"
+Issues = "https://github.com/btfranklin/personalitygen/issues"
+Changelog = "https://github.com/btfranklin/personalitygen/releases"
+Repository = "https://github.com/btfranklin/personalitygen.git"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+packages = [
+    { include = "personalitygen", from = "src" },
+]
+
+[tool.pdm.build]
+excludes = [
+    "tests/**",
+]
+
+[tool.pdm.scripts]
+test = "pytest"
+lint = "flake8 src tests"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "flake8>=7.3.0",
+]

personalitygen-0.1.0/src/personalitygen/__init__.py

@@ -0,0 +1,30 @@
+"""Public interface for personalitygen."""
+
+from personalitygen.enums import LifeStage, PriorityLevel
+from personalitygen.personality import (
+    BigFiveConflictResolutionConfiguration,
+    BigFiveConflictResolutionStyle,
+    BigFivePersonality,
+    BigFiveTraitConfiguration,
+)
+from personalitygen.traits import (
+    BigFiveAgreeableness,
+    BigFiveConscientiousness,
+    BigFiveExtraversion,
+    BigFiveNeuroticism,
+    BigFiveOpenness,
+)
+
+__all__ = [
+    "BigFiveAgreeableness",
+    "BigFiveConscientiousness",
+    "BigFiveConflictResolutionConfiguration",
+    "BigFiveConflictResolutionStyle",
+    "BigFiveExtraversion",
+    "BigFiveNeuroticism",
+    "BigFiveOpenness",
+    "BigFivePersonality",
+    "BigFiveTraitConfiguration",
+    "LifeStage",
+    "PriorityLevel",
+]

personalitygen-0.1.0/src/personalitygen/__init__.pyi

@@ -0,0 +1,5 @@
+from personalitygen.enums import LifeStage as LifeStage, PriorityLevel as PriorityLevel
+from personalitygen.personality import BigFiveConflictResolutionConfiguration as BigFiveConflictResolutionConfiguration, BigFiveConflictResolutionStyle as BigFiveConflictResolutionStyle, BigFivePersonality as BigFivePersonality, BigFiveTraitConfiguration as BigFiveTraitConfiguration
+from personalitygen.traits import BigFiveAgreeableness as BigFiveAgreeableness, BigFiveConscientiousness as BigFiveConscientiousness, BigFiveExtraversion as BigFiveExtraversion, BigFiveNeuroticism as BigFiveNeuroticism, BigFiveOpenness as BigFiveOpenness
+
+__all__ = ['BigFiveAgreeableness', 'BigFiveConscientiousness', 'BigFiveConflictResolutionConfiguration', 'BigFiveConflictResolutionStyle', 'BigFiveExtraversion', 'BigFiveNeuroticism', 'BigFiveOpenness', 'BigFivePersonality', 'BigFiveTraitConfiguration', 'LifeStage', 'PriorityLevel']

personalitygen-0.1.0/src/personalitygen/constants.py

@@ -0,0 +1,4 @@
+"""Shared constants for personalitygen."""
+
+UNIT_RANGE_MIN = 0.0
+UNIT_RANGE_MAX = 1.0

personalitygen-0.1.0/src/personalitygen/constants.pyi

@@ -0,0 +1,2 @@
+UNIT_RANGE_MIN: float
+UNIT_RANGE_MAX: float

personalitygen-0.1.0/src/personalitygen/enums.py

@@ -0,0 +1,17 @@
+"""Enums for personalitygen."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class LifeStage(str, Enum):
+    CHILD = "child"
+    YOUNG_ADULT = "young_adult"
+    ADULT = "adult"
+
+
+class PriorityLevel(str, Enum):
+    LOW = "low"
+    MODERATE = "moderate"
+    HIGH = "high"

personalitygen-0.1.0/src/personalitygen/enums.pyi

@@ -0,0 +1,11 @@
+from enum import Enum
+
+class LifeStage(str, Enum):
+    CHILD = 'child'
+    YOUNG_ADULT = 'young_adult'
+    ADULT = 'adult'
+
+class PriorityLevel(str, Enum):
+    LOW = 'low'
+    MODERATE = 'moderate'
+    HIGH = 'high'

personalitygen-0.1.0/src/personalitygen/personality.py

@@ -0,0 +1,228 @@
+"""Top-level personality configuration models."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from enum import Enum
+from typing import Self
+
+from personalitygen.enums import LifeStage, PriorityLevel
+from personalitygen.randomness import RandomSource
+from personalitygen.traits import (
+    BigFiveAgreeableness,
+    BigFiveConscientiousness,
+    BigFiveExtraversion,
+    BigFiveNeuroticism,
+    BigFiveOpenness,
+)
+
+
+def _weighted_choice(
+    weights: dict["BigFiveConflictResolutionStyle", float],
+    *,
+    rng: RandomSource | None = None,
+) -> "BigFiveConflictResolutionStyle":
+    if not weights:
+        raise ValueError("weights must be non-empty")
+    if any(weight < 0.0 for weight in weights.values()):
+        raise ValueError("weights must be non-negative")
+    source = rng if rng is not None else random
+    total = sum(weights.values())
+    if total <= 0.0:
+        weights = {style: 1.0 for style in weights}
+        total = float(len(weights))
+
+    threshold = source.uniform(0.0, total)
+    for style, weight in weights.items():
+        threshold -= weight
+        if threshold <= 0.0:
+            return style
+    return next(iter(weights))
+
+
+class BigFiveConflictResolutionStyle(str, Enum):
+    # Concern for self: low. Concern for others: low. Tries to avoid conflict.
+    AVOIDING = "avoiding"
+    # Concern for self: low. Concern for others: high. Accommodates others.
+    OBLIGING = "obliging"
+    # Concern for self: high. Concern for others: high. Collaborates.
+    INTEGRATING = "integrating"
+    # Concern for self: high. Concern for others: low. Competes to win.
+    DOMINATING = "dominating"
+    # Concern for self: moderate. Concern for others: moderate. Trades off.
+    COMPROMISING = "compromising"
+
+    @classmethod
+    def random(
+        cls,
+        trait_configuration: BigFiveTraitConfiguration,
+        *,
+        rng: RandomSource | None = None,
+    ) -> Self:
+        # These weights are loosely based on:
+        # Priyadarshini, S. (2017). Effect of Personality on Conflict
+        # Resolution Styles. IRA-International Journal of Management &
+        # Social Sciences, 7(2), 196-207.
+        style_levels = {
+            cls.AVOIDING: trait_configuration.neuroticism.score * 0.7
+            + trait_configuration.openness.score * -0.1
+            + trait_configuration.agreeableness.score * 0.2
+            + trait_configuration.conscientiousness.score * -0.2,
+            cls.OBLIGING: trait_configuration.neuroticism.score * 0.2
+            + trait_configuration.extraversion.score * -0.2
+            + trait_configuration.openness.score * -0.1
+            + trait_configuration.agreeableness.score * 0.3,
+            cls.INTEGRATING: trait_configuration.openness.score * 0.1
+            + trait_configuration.agreeableness.score * 0.2
+            + trait_configuration.conscientiousness.score * 0.1,
+            cls.DOMINATING: trait_configuration.neuroticism.score * -0.2
+            + trait_configuration.extraversion.score * 0.2
+            + trait_configuration.openness.score * -0.2
+            + trait_configuration.agreeableness.score * -0.4
+            + trait_configuration.conscientiousness.score * 0.2,
+            cls.COMPROMISING: trait_configuration.neuroticism.score * 0.1
+            + trait_configuration.extraversion.score * 0.1
+            + trait_configuration.conscientiousness.score * -0.2,
+        }
+
+        # Keep a small chance of selecting counter-indicated styles.
+        minimum_weight = 0.1
+        weights = {
+            style: max(level, minimum_weight)
+            for style, level in style_levels.items()
+        }
+        return _weighted_choice(weights, rng=rng)
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveTraitConfiguration:
+    # Appreciation for art, emotion, adventure, and curiosity.
+    # Opposite: closedness.
+    openness: BigFiveOpenness
+    # Self-discipline, dutifulness, and achievement orientation.
+    # Opposite: undisciplined.
+    conscientiousness: BigFiveConscientiousness
+    # Energy, sociability, and stimulation-seeking.
+    # Opposite: introversion.
+    extraversion: BigFiveExtraversion
+    # Compassion and cooperation toward others.
+    # Opposite: antagonism.
+    agreeableness: BigFiveAgreeableness
+    # Tendency toward unpleasant emotions and instability.
+    # Opposite: emotional stability.
+    neuroticism: BigFiveNeuroticism
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        return cls(
+            openness=BigFiveOpenness.random(life_stage, rng=rng),
+            conscientiousness=BigFiveConscientiousness.random(
+                life_stage, rng=rng
+            ),
+            extraversion=BigFiveExtraversion.random(life_stage, rng=rng),
+            agreeableness=BigFiveAgreeableness.random(life_stage, rng=rng),
+            neuroticism=BigFiveNeuroticism.random(life_stage, rng=rng),
+        )
+
+    def __str__(self) -> str:
+        return (
+            "openness: "
+            f"{self.openness}\n"
+            "conscientiousness: "
+            f"{self.conscientiousness}\n"
+            "extraversion: "
+            f"{self.extraversion}\n"
+            "agreeableness: "
+            f"{self.agreeableness}\n"
+            "neuroticism: "
+            f"{self.neuroticism}"
+        )
+
+
+_STYLE_TO_CONCERNS: dict[
+    BigFiveConflictResolutionStyle, tuple[PriorityLevel, PriorityLevel]
+] = {
+    BigFiveConflictResolutionStyle.AVOIDING: (
+        PriorityLevel.LOW,
+        PriorityLevel.LOW,
+    ),
+    BigFiveConflictResolutionStyle.OBLIGING: (
+        PriorityLevel.LOW,
+        PriorityLevel.HIGH,
+    ),
+    BigFiveConflictResolutionStyle.INTEGRATING: (
+        PriorityLevel.HIGH,
+        PriorityLevel.HIGH,
+    ),
+    BigFiveConflictResolutionStyle.DOMINATING: (
+        PriorityLevel.HIGH,
+        PriorityLevel.LOW,
+    ),
+    BigFiveConflictResolutionStyle.COMPROMISING: (
+        PriorityLevel.MODERATE,
+        PriorityLevel.MODERATE,
+    ),
+}
+
+
+def _validate_style_concerns() -> None:
+    expected = set(BigFiveConflictResolutionStyle)
+    actual = set(_STYLE_TO_CONCERNS)
+    if expected != actual:
+        missing = {style.value for style in expected - actual}
+        extra = {style.value for style in actual - expected}
+        raise ValueError(
+            "Conflict resolution styles and concern mapping are out of sync. "
+            f"Missing: {sorted(missing)}. Extra: {sorted(extra)}."
+        )
+
+
+_validate_style_concerns()
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveConflictResolutionConfiguration:
+    conflict_resolution_style: BigFiveConflictResolutionStyle
+    concern_for_self: PriorityLevel
+    concern_for_others: PriorityLevel
+
+    @classmethod
+    def random(
+        cls,
+        trait_configuration: BigFiveTraitConfiguration,
+        *,
+        rng: RandomSource | None = None,
+    ) -> Self:
+        style = BigFiveConflictResolutionStyle.random(
+            trait_configuration, rng=rng
+        )
+        concern_for_self, concern_for_others = _STYLE_TO_CONCERNS[style]
+        return cls(
+            conflict_resolution_style=style,
+            concern_for_self=concern_for_self,
+            concern_for_others=concern_for_others,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BigFivePersonality:
+    trait_configuration: BigFiveTraitConfiguration
+    conflict_resolution_configuration: BigFiveConflictResolutionConfiguration
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        trait_configuration = BigFiveTraitConfiguration.random(
+            life_stage, rng=rng
+        )
+        conflict_configuration = BigFiveConflictResolutionConfiguration.random(
+            trait_configuration, rng=rng
+        )
+        return cls(
+            trait_configuration=trait_configuration,
+            conflict_resolution_configuration=conflict_configuration,
+        )

personalitygen-0.1.0/src/personalitygen/personality.pyi

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from enum import Enum
+from personalitygen.enums import LifeStage as LifeStage, PriorityLevel as PriorityLevel
+from personalitygen.randomness import RandomSource as RandomSource
+from personalitygen.traits import BigFiveAgreeableness as BigFiveAgreeableness, BigFiveConscientiousness as BigFiveConscientiousness, BigFiveExtraversion as BigFiveExtraversion, BigFiveNeuroticism as BigFiveNeuroticism, BigFiveOpenness as BigFiveOpenness
+from typing import Self
+
+class BigFiveConflictResolutionStyle(str, Enum):
+    AVOIDING = 'avoiding'
+    OBLIGING = 'obliging'
+    INTEGRATING = 'integrating'
+    DOMINATING = 'dominating'
+    COMPROMISING = 'compromising'
+    @classmethod
+    def random(cls, trait_configuration: BigFiveTraitConfiguration, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFiveTraitConfiguration:
+    openness: BigFiveOpenness
+    conscientiousness: BigFiveConscientiousness
+    extraversion: BigFiveExtraversion
+    agreeableness: BigFiveAgreeableness
+    neuroticism: BigFiveNeuroticism
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFiveConflictResolutionConfiguration:
+    conflict_resolution_style: BigFiveConflictResolutionStyle
+    concern_for_self: PriorityLevel
+    concern_for_others: PriorityLevel
+    @classmethod
+    def random(cls, trait_configuration: BigFiveTraitConfiguration, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFivePersonality:
+    trait_configuration: BigFiveTraitConfiguration
+    conflict_resolution_configuration: BigFiveConflictResolutionConfiguration
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...

personalitygen-0.1.0/src/personalitygen/randomness.py

@@ -0,0 +1,50 @@
+"""Random utilities used by personalitygen."""
+
+from __future__ import annotations
+
+import random
+import statistics
+from typing import Protocol
+
+
+class RandomSource(Protocol):
+    """Minimal interface needed for deterministic sampling."""
+
+    def gauss(self, mu: float, sigma: float) -> float: ...
+
+    def uniform(self, a: float, b: float) -> float: ...
+
+
+def _coerce_rng(rng: RandomSource | None) -> RandomSource:
+    return rng if rng is not None else random
+
+
+def random_gaussian(
+    *,
+    mean: float,
+    stddev: float,
+    min_value: float,
+    max_value: float,
+    rng: RandomSource | None = None,
+) -> float:
+    """Draw a truncated Gaussian sample within the provided bounds."""
+    if stddev <= 0:
+        raise ValueError("stddev must be positive")
+    if min_value > max_value:
+        raise ValueError("min_value must be <= max_value")
+
+    source = _coerce_rng(rng)
+    distribution = statistics.NormalDist(mean, stddev)
+    lower = distribution.cdf(min_value)
+    upper = distribution.cdf(max_value)
+    if lower >= upper:
+        return max(min_value, min(max_value, mean))
+
+    cdf_epsilon = 1e-12
+    lower = max(lower, cdf_epsilon)
+    upper = min(upper, 1.0 - cdf_epsilon)
+    if lower >= upper:
+        return max(min_value, min(max_value, mean))
+
+    u = source.uniform(lower, upper)
+    return distribution.inv_cdf(u)

personalitygen-0.1.0/src/personalitygen/randomness.pyi

@@ -0,0 +1,7 @@
+from typing import Protocol
+
+class RandomSource(Protocol):
+    def gauss(self, mu: float, sigma: float) -> float: ...
+    def uniform(self, a: float, b: float) -> float: ...
+
+def random_gaussian(*, mean: float, stddev: float, min_value: float, max_value: float, rng: RandomSource | None = None) -> float: ...

personalitygen-0.1.0/src/personalitygen/traits.py

@@ -0,0 +1,345 @@
+"""Big Five trait models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Self
+
+from personalitygen.constants import UNIT_RANGE_MAX, UNIT_RANGE_MIN
+from personalitygen.enums import LifeStage
+from personalitygen.randomness import RandomSource, random_gaussian
+
+
+def _validate_unit_range(*values: float) -> None:
+    for value in values:
+        if not (UNIT_RANGE_MIN <= value <= UNIT_RANGE_MAX):
+            raise ValueError(
+                "All trait components must be in the range 0.0...1.0"
+            )
+
+
+def _format_score(value: float) -> str:
+    return format(value, ".2g")
+
+
+_TRAIT_SAMPLE_MIN = 0.01
+
+
+@dataclass(frozen=True, slots=True)
+class _TraitConfig:
+    stddev: float
+    means_by_stage: dict[LifeStage, tuple[float, float, float]]
+
+
+def _sample_trait(
+    life_stage: LifeStage,
+    config: _TraitConfig,
+    *,
+    rng: RandomSource | None = None,
+) -> tuple[float, float, float]:
+    means = config.means_by_stage.get(life_stage)
+    if means is None:
+        raise ValueError(f"Unsupported life stage: {life_stage}")
+
+    mean_a, mean_b, mean_c = means
+    return (
+        random_gaussian(
+            stddev=config.stddev,
+            mean=mean_a,
+            max_value=UNIT_RANGE_MAX,
+            min_value=_TRAIT_SAMPLE_MIN,
+            rng=rng,
+        ),
+        random_gaussian(
+            stddev=config.stddev,
+            mean=mean_b,
+            max_value=UNIT_RANGE_MAX,
+            min_value=_TRAIT_SAMPLE_MIN,
+            rng=rng,
+        ),
+        random_gaussian(
+            stddev=config.stddev,
+            mean=mean_c,
+            max_value=UNIT_RANGE_MAX,
+            min_value=_TRAIT_SAMPLE_MIN,
+            rng=rng,
+        ),
+    )
+
+
+_OPENNESS_CONFIG = _TraitConfig(
+    stddev=0.16,
+    means_by_stage={
+        LifeStage.CHILD: (0.80, 0.85, 0.85),
+        LifeStage.YOUNG_ADULT: (0.70, 0.75, 0.75),
+        LifeStage.ADULT: (0.60, 0.65, 0.65),
+    },
+)
+
+_CONSCIENTIOUSNESS_CONFIG = _TraitConfig(
+    stddev=0.22,
+    means_by_stage={
+        LifeStage.CHILD: (0.50, 0.55, 0.50),
+        LifeStage.YOUNG_ADULT: (0.60, 0.65, 0.60),
+        LifeStage.ADULT: (0.70, 0.75, 0.70),
+    },
+)
+
+_EXTRAVERSION_CONFIG = _TraitConfig(
+    stddev=0.27,
+    means_by_stage={
+        LifeStage.CHILD: (0.72, 0.70, 0.72),
+        LifeStage.YOUNG_ADULT: (0.62, 0.60, 0.62),
+        LifeStage.ADULT: (0.52, 0.50, 0.52),
+    },
+)
+
+_AGREEABLENESS_CONFIG = _TraitConfig(
+    stddev=0.18,
+    means_by_stage={
+        LifeStage.CHILD: (0.55, 0.55, 0.40),
+        LifeStage.YOUNG_ADULT: (0.65, 0.65, 0.50),
+        LifeStage.ADULT: (0.75, 0.75, 0.60),
+    },
+)
+
+_NEUROTICISM_CONFIG = _TraitConfig(
+    stddev=0.32,
+    means_by_stage={
+        LifeStage.CHILD: (0.70, 0.60, 0.55),
+        LifeStage.YOUNG_ADULT: (0.60, 0.50, 0.45),
+        LifeStage.ADULT: (0.50, 0.40, 0.35),
+    },
+)
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveOpenness:
+    aesthetic_sensitivity_score: float
+    creative_imagination_score: float
+    intellectual_curiosity_score: float
+    score: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        _validate_unit_range(
+            self.aesthetic_sensitivity_score,
+            self.creative_imagination_score,
+            self.intellectual_curiosity_score,
+        )
+        object.__setattr__(
+            self,
+            "score",
+            (
+                self.aesthetic_sensitivity_score
+                + self.creative_imagination_score
+                + self.intellectual_curiosity_score
+            )
+            / 3,
+        )
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        (
+            aesthetic_sensitivity,
+            creative_imagination,
+            intellectual_curiosity,
+        ) = _sample_trait(life_stage, _OPENNESS_CONFIG, rng=rng)
+        return cls(
+            aesthetic_sensitivity_score=aesthetic_sensitivity,
+            creative_imagination_score=creative_imagination,
+            intellectual_curiosity_score=intellectual_curiosity,
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"{_format_score(self.score)} "
+            f"{{A:{_format_score(self.aesthetic_sensitivity_score)} "
+            f"C:{_format_score(self.creative_imagination_score)} "
+            f"I:{_format_score(self.intellectual_curiosity_score)}}}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveConscientiousness:
+    organization_score: float
+    responsibility_score: float
+    productivity_score: float
+    score: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        _validate_unit_range(
+            self.organization_score,
+            self.responsibility_score,
+            self.productivity_score,
+        )
+        object.__setattr__(
+            self,
+            "score",
+            (
+                self.organization_score
+                + self.responsibility_score
+                + self.productivity_score
+            )
+            / 3,
+        )
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        organization, responsibility, productivity = _sample_trait(
+            life_stage, _CONSCIENTIOUSNESS_CONFIG, rng=rng
+        )
+        return cls(
+            organization_score=organization,
+            responsibility_score=responsibility,
+            productivity_score=productivity,
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"{_format_score(self.score)} "
+            f"{{O:{_format_score(self.organization_score)} "
+            f"R:{_format_score(self.responsibility_score)} "
+            f"P:{_format_score(self.productivity_score)}}}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveExtraversion:
+    assertiveness_score: float
+    sociability_score: float
+    energy_level_score: float
+    score: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        _validate_unit_range(
+            self.assertiveness_score,
+            self.sociability_score,
+            self.energy_level_score,
+        )
+        object.__setattr__(
+            self,
+            "score",
+            (
+                self.assertiveness_score
+                + self.sociability_score
+                + self.energy_level_score
+            )
+            / 3,
+        )
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        assertiveness, sociability, energy_level = _sample_trait(
+            life_stage, _EXTRAVERSION_CONFIG, rng=rng
+        )
+        return cls(
+            assertiveness_score=assertiveness,
+            sociability_score=sociability,
+            energy_level_score=energy_level,
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"{_format_score(self.score)} "
+            f"{{A:{_format_score(self.assertiveness_score)} "
+            f"S:{_format_score(self.sociability_score)} "
+            f"E:{_format_score(self.energy_level_score)}}}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveAgreeableness:
+    compassion_score: float
+    respectfulness_score: float
+    trust_score: float
+    score: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        _validate_unit_range(
+            self.compassion_score,
+            self.respectfulness_score,
+            self.trust_score,
+        )
+        object.__setattr__(
+            self,
+            "score",
+            (
+                self.compassion_score
+                + self.respectfulness_score
+                + self.trust_score
+            )
+            / 3,
+        )
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        compassion, respectfulness, trust = _sample_trait(
+            life_stage, _AGREEABLENESS_CONFIG, rng=rng
+        )
+        return cls(
+            compassion_score=compassion,
+            respectfulness_score=respectfulness,
+            trust_score=trust,
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"{_format_score(self.score)} "
+            f"{{C:{_format_score(self.compassion_score)} "
+            f"R:{_format_score(self.respectfulness_score)} "
+            f"T:{_format_score(self.trust_score)}}}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BigFiveNeuroticism:
+    anxiety_score: float
+    emotional_volatility_score: float
+    depression_score: float
+    score: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        _validate_unit_range(
+            self.anxiety_score,
+            self.emotional_volatility_score,
+            self.depression_score,
+        )
+        object.__setattr__(
+            self,
+            "score",
+            (
+                self.anxiety_score
+                + self.emotional_volatility_score
+                + self.depression_score
+            )
+            / 3,
+        )
+
+    @classmethod
+    def random(
+        cls, life_stage: LifeStage, *, rng: RandomSource | None = None
+    ) -> Self:
+        anxiety, emotional_volatility, depression = _sample_trait(
+            life_stage, _NEUROTICISM_CONFIG, rng=rng
+        )
+        return cls(
+            anxiety_score=anxiety,
+            emotional_volatility_score=emotional_volatility,
+            depression_score=depression,
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"{_format_score(self.score)} "
+            f"{{A:{_format_score(self.anxiety_score)} "
+            f"E:{_format_score(self.emotional_volatility_score)} "
+            f"D:{_format_score(self.depression_score)}}}"
+        )

personalitygen-0.1.0/src/personalitygen/traits.pyi

@@ -0,0 +1,60 @@
+from dataclasses import dataclass, field
+from personalitygen.constants import UNIT_RANGE_MAX as UNIT_RANGE_MAX, UNIT_RANGE_MIN as UNIT_RANGE_MIN
+from personalitygen.enums import LifeStage as LifeStage
+from personalitygen.randomness import RandomSource as RandomSource, random_gaussian as random_gaussian
+from typing import Self
+
+@dataclass(frozen=True, slots=True)
+class _TraitConfig:
+    stddev: float
+    means_by_stage: dict[LifeStage, tuple[float, float, float]]
+
+@dataclass(frozen=True, slots=True)
+class BigFiveOpenness:
+    aesthetic_sensitivity_score: float
+    creative_imagination_score: float
+    intellectual_curiosity_score: float
+    score: float = field(init=False)
+    def __post_init__(self) -> None: ...
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFiveConscientiousness:
+    organization_score: float
+    responsibility_score: float
+    productivity_score: float
+    score: float = field(init=False)
+    def __post_init__(self) -> None: ...
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFiveExtraversion:
+    assertiveness_score: float
+    sociability_score: float
+    energy_level_score: float
+    score: float = field(init=False)
+    def __post_init__(self) -> None: ...
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFiveAgreeableness:
+    compassion_score: float
+    respectfulness_score: float
+    trust_score: float
+    score: float = field(init=False)
+    def __post_init__(self) -> None: ...
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...
+
+@dataclass(frozen=True, slots=True)
+class BigFiveNeuroticism:
+    anxiety_score: float
+    emotional_volatility_score: float
+    depression_score: float
+    score: float = field(init=False)
+    def __post_init__(self) -> None: ...
+    @classmethod
+    def random(cls, life_stage: LifeStage, *, rng: RandomSource | None = None) -> Self: ...