Metadata-Version: 2.1
Name: personalitygen
Version: 0.2.0
Summary: Generate simulated character personalities for games, stories, and simulations.
Keywords: personality,big-five,ocean,abbf,simulation
Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
License: 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.
         
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](https://raw.githubusercontent.com/btfranklin/personalitygen/main/.github/social%20preview/personalitygen_social_preview.jpg "personalitygen")

[![Build Status](https://github.com/btfranklin/personalitygen/actions/workflows/python-package.yml/badge.svg)](https://github.com/btfranklin/personalitygen/actions/workflows/python-package.yml) [![Supports Python versions 3.11+](https://img.shields.io/pypi/pyversions/personalitygen.svg)](https://pypi.python.org/pypi/personalitygen)

`personalitygen` generates simulated character personalities for games, storytelling, simulations, and tests. It supports
conventional Big Five (OCEAN) profiles and Adaptive Bifurcated Big Five (ABBF) signed-vector profiles.

## Intent and scope

- Generate full Big Five profiles with sub-trait components and aggregate scores.
- Generate ABBF profiles as signed 5D vectors with dominant poles.
- 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.
- Project Big Five profiles into ABBF vectors for systems that want both model shapes.
- Support deterministic generation by accepting a seeded random source.
- Stay lightweight and dependency-free (pure Python).

## Model overview

- Big Five traits: openness, conscientiousness, extraversion, agreeableness, neuroticism.
- Each trait is composed of three sub-traits and an 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.
- ABBF profiles use five signed axes in chart order: order, chaos, cooperation, conflict, and competition.
- Positive ABBF values select the chart's left pole; negative values select the chart's right pole.

## 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)
```

ABBF profiles can be generated directly or projected from Big Five traits:

```python
from personalitygen import AdaptiveBifurcatedProfile

profile = AdaptiveBifurcatedProfile.random()
print(profile.vector)
print(profile.dominant_poles(threshold=0.2))

projected = AdaptiveBifurcatedProfile.from_big_five(traits)
print(projected.cosine_similarity(profile))
```

## Development

This package targets Python 3.11+.

```bash
pdm install --group dev
pdm run test
pdm run lint
```

Deeper architecture, quality, and maintenance guidance lives in [`docs/`](docs/README.md).
Simulation recipes live in [`docs/USAGE.md`](docs/USAGE.md), and runnable examples live in [`examples/`](examples/).
