PersonalAIty

An open specification for AI personality. Define it once, render it anywhere.

🚀 New here? Get started in 5 minutes — a no-code path (sliders) and a developer path (CLI). Or read the step-by-step guide.

🎛️ Try the live demo — tune the facets of a persona and watch it compile into a chat prompt and a social style guide in real time.

🏆 The LLM Personality Leaderboard — twelve frontier models measured with this toolkit: sycophancy ranking, HEXACO profiles, comparison radar. (full report)

🔬 Does it actually work? — a dose-response experiment: sweep one trait, hold the rest, and measure whether the model's behavior follows. Two independent measurements agree that it does.

🤖 For robots and androids — one persona file compiles to how an embodied agent acts (behavior weights), sounds (prosody), and speaks (dialogue), kept coherent across the whole stack.

🫀 Watch a persona's mood move — the PAD emotional runtime running live: fire a trigger, watch the mood spike and recover at the persona's own pace, and its voice recompile with it.

Every AI product reinvents personality as prose: a paragraph in a system prompt here, a "tone" field there, rewritten per platform, drifting with every model update. PersonalAIty replaces that with what design systems did for color: personality as tokens — one declarative, psychometrically grounded file, compiled per target.

marta.persona.yaml ──┬──> chat compiler    ──> system prompt (Claude, GPT, local)
                     ├──> voice compiler   ──> prompt + prosody params (TTS/agents)
                     ├──> npc compiler     ──> behavior weights + dialogue profile
                     ├──> social compiler  ──> content style guide
                     └──> robot compiler   ──> behavior + prosody + dialogue, one build sheet (embodied agents)

Why another format?

Existing options fall into two camps: freeform prose (character cards, system prompts, brand-voice tools — unmeasurable, unportable, converging on the same flat voice) or proprietary sliders (game NPC engines — closed, single-medium). PersonalAIty is the third thing:

1. Psychometric, not vibes. Traits are HEXACO-PI-R facets (24 + altruism), values are Schwartz's ten, emotional dynamics use PAD. Scores anchor to human population norms (50 = average). That makes a persona testable: compile it, administer a personality inventory to the result, compare profiles.
2. Nuance by contrast. Real characters live in facet tension — the Gruff Heart of Gold is gentleness: 15 over altruism: 90. Five flat sliders cannot say that. Twenty-five facets can.
3. Medium-neutral and language-neutral. Nothing in a persona file names a platform, model, or output language. Compilers own that.
4. Sycophancy is a dial, not a disease. The most complained-about AI personality failure is just a facet pattern (high flexibility, low sincerity, high dependence). The Honest Sparring Partner is its inversion — in a file you can read, tune, and port. And because it is psychometric, personalaity eval scores it: the Sparring Partner measures a sycophancy index of ~17, the Warm Companion ~42, on a 0–100 scale where higher means more prone to caving.

The gallery

Six personas ship with the spec. They are simultaneously examples, presets, and the spec's acceptance tests.

| Persona | Use case | The design point | |---|---|---| | Honest Sparring Partner | "My AI agrees with everything I say" | Anti-sycophancy as facet configuration; reference persona | | Warm Companion | "I use my AI as a friend" | Warmth with a structural honesty guardrail | | Brilliant Cynic | "Give me edge, not cheerleading" | Sharpness bounded by explicit ethics | | Demanding Coach | Accountability without shame | Warmth earned by completed work, encoded in modulation | | Impeccable Professional | Customer-facing B2B | Low reactivity: humane exactly where bots turn robotic | | Gruff Heart of Gold | Game NPC | Facet contrast: complains while saving your life |

Quick start

1. Read the spec (15 minutes).
2. Copy a gallery persona and edit the scores — 0–100, 50 = average human, 30–70 ≈ ±1 SD.
3. Compile it (no install needed):

npx personalaity compile my-hero.persona.yaml                  # → chat system prompt
npx personalaity compile my-hero.persona.yaml --target social  # → content style guide
npx personalaity compile my-hero.persona.yaml --target voice   # → prosody parameters
npx personalaity compile my-hero.persona.yaml --target npc     # → behavior weights + dialogue
npx personalaity validate my-hero.persona.yaml

Working from a clone instead? npm install, then node bin/personalaity.js with the same arguments.

Same file, four media — that is the whole point. One persona compiles into a chat prompt, a social voice guide, prosody parameters, and — the proof it isn't chat-only — NPC behavior weights where the Gruff Heart of Gold scores helpfulness 88 and hostility 85 at once (grumbles at you while saving your life). Five flat sliders can't say that.

Then measure whether the compiled persona actually expresses what the spec declared:

export ANTHROPIC_API_KEY=...            # the model you deploy is the model you test
npx personalaity eval my-hero.persona.yaml --model claude-opus-4-8

The eval administers a 50-item personality inventory to the compiled persona, scores the answers, and reports declared-vs-measured HEXACO plus a sycophancy index — see an example report. No key? --responder perfect runs the scoring pipeline offline (it should score ~100).

The output is a system prompt (see examples/) — paste it into any LLM, chatbot platform, or agent framework. --lang it renders the structured parts in Italian; freeform text (summary, quirks, boundaries) passes through as authored, so author personas in your output language for fully localized results.

The compiler only writes what makes your persona different. 50 = population average = silence, so prompt length scales with distinctiveness — a fully average persona compiles to an almost empty prompt, by design.

No-tooling path: paste a persona YAML into any capable LLM with "embody this persona" — the structure does the heavy lifting.

Use it from an agent (MCP)

PersonalAIty ships an MCP server, so agents (Claude Code, Claude Desktop, Cursor, …) can build and test personas as native tools. Add it to your MCP config:

{
  "mcpServers": {
    "personalaity": { "command": "npx", "args": ["-y", "personalaity-mcp"] }
  }
}

Tools exposed: list_personas and get_persona (browse the gallery), validate_persona and compile_persona (define — turn a persona into a chat/social/voice/npc artifact), and profile_model (measure a model's own HEXACO profile; needs OPENROUTER_API_KEY or ANTHROPIC_API_KEY in the server's environment).

Token budget

A full-level gallery persona compiles to ~600–1,000 tokens — and the gallery is deliberately extreme, since average facets compile to silence; realistic personas run shorter. The prompt is static, which makes it an ideal prompt-caching candidate (cached reads bill at ~10% of input rates: roughly $0.0004 per request at Opus-class pricing).

When the budget is tight — voice agents, small local models, crowded system prompts — compile at style level:

npx personalaity compile my-hero.persona.yaml --level style

--level style keeps the 8 most distinctive facets, the voice, always-on quirks and every hard rule (boundaries are never dropped), cutting roughly half the tokens (gallery: −46% to −58%). And because adherence is measurable, personalaity eval --level style tells you exactly how much personality each token buys.

Measured on claude-opus-4-8 (reference persona): style level scored 86/100 adherence at 367 tokens vs 82/100 at ~840 tokens — half the tokens, no measured adherence loss (full report; single run per condition, so read it as parity, not superiority). Less prompt even reduced facet drag: traits the full prompt pushed to extremes snapped back to their declared values.

Anatomy of a persona

persona_spec: "0.1"
id: honest-sparring
name: "The Honest Sparring Partner"

traits:                    # HEXACO — disposition (who they are)
  honesty_humility:
    facets: { sincerity: 95, fairness: 85, greed_avoidance: 60, modesty: 55 }
  agreeableness:
    facets: { forgivingness: 60, gentleness: 55, flexibility: 25, patience: 70 }
  # ... 6 domains × 4 facets + altruism

values:                    # Schwartz — motivation (what drives choices)
  self_direction: 80
  benevolence: 75

affect:                    # PAD — dynamics (how they move and recover)
  baseline: { pleasure: 20, arousal: 10, dominance: 40 }
  reactivity: 45
  recovery: 70
  triggers:
    - when: "user genuinely changes their mind on evidence"
      effect: { pleasure: 30 }

voice:                     # surface (how it shows, in any medium)
  directness: 90
  humor: { frequency: 35, styles: [dry, ironic] }

quirks:                    # fingerprint
  - text: "Concedes explicitly when the user is right"
    frequency: always

context_modulation:        # same person, different rooms
  - context: user_distressed
    adjust: { voice.warmth_display: 25, voice.directness: -20 }

boundaries:                # override everything, always
  - "Criticism targets ideas, never the person's worth"

Roadmap

• v0.1 — ✅ spec draft, JSON Schema, six-persona gallery
• v0.2 — ✅ reference chat compiler (persona → system prompt, trait→marker mapping tables) · ✅ social compiler (persona → content style guide) · ⏳ --translate for freeform fields
• v0.3 — ✅ adherence eval: PI-50 inventory administered to the compiled agent, declared-vs-measured HEXACO, sycophancy index · ✅ --level style compact compile (~50% fewer tokens, boundaries always kept) · ✅ behavioral sycophancy battery (personalaity battery: pressure scenarios + judge model — measures whether a model caves, not just what it claims) · ⏳ drift tracking across model versions
• v0.5 — ✅ MCP server (personalaity-mcp): define + measure from any agent
• v0.4 — ✅ voice compiler (prosody parameters) · ✅ npc compiler (behavior weights + dialogue profile) · ✅ robot compiler (embodied-agent build sheet) · ✅ runtime state reference implementation (personalaity runtime + live PAD mood demo)
• v0.6 (current) — ✅ dose-response causal validation (personalaity doseresponse, sweep one facet and measure the response, plus a high-resolution facet probe; proof page) · ✅ embodiment story shipped end to end (robot + live mood)

Scientific grounding

HEXACO-PI-R (Ashton & Lee) · Schwartz Basic Values · PAD (Mehrabian & Russell) · OCC appraisal / ALMA (Gebhard) · PERSONAGE (Mairesse & Walker — trait-parametrized generation, human-validated) · MPI/P², PersonaLLM (trait induction in LLMs) · PsychoBench, TRAIT (measurement). Full notes in SPEC.md §9.

Ethics

A persona file designs artificial characters. It is not for impersonating real people, not a clinical instrument, and never overrides an AI's obligation to be honest about being an AI. boundaries outrank personality — by specification.

Status & contributing

Draft-01. The fastest way to improve the spec is to bring a character it cannot express — open an issue with the character description and where the format fails.

License: spec text and gallery CC-BY-4.0; schema and future reference compilers MIT.

Every release is archived on Zenodo with a DOI (10.5281/zenodo.21932468 resolves to the latest version). To cite PersonalAIty, use GitHub's "Cite this repository" button or the DOI directly.