# personanexus **Repository Path**: ipcun/personanexus ## Basic Information - **Project Name**: personanexus - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-01 - **Last Updated**: 2026-10-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ๐Ÿงฌ PersonaNexus **Define who your AI agent *is* โ€” not just what it can do.** ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg) ![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg) ![Schema Version](https://img.shields.io/badge/schema-v1.0-green.svg) ![Tests](https://img.shields.io/badge/tests-878%20passing-brightgreen.svg) > โš ๏ธ **Privacy Notice:** All agent configurations in this repository are **fictional demonstrations**. Your private agent data remains on your system and under your control. [Quick Start](#quick-start) ยท [Features](#features) ยท [CLI Reference](#cli-reference) ยท [Python API](#python-api) ยท [Examples](#examples) ยท [Contributing](#contributing) ## PersonaNexus ecosystem PersonaNexus is the identity substrate for a small ecosystem of agent-building tools: | Project | Role | Repository | |---|---|---| | **PersonaNexus** | Declarative identity schema, compiler, validation, evaluation, Studio, and team definitions | [`PersonaNexus/personanexus`](https://github.com/PersonaNexus/personanexus) | | **AgentForge** | Skill and agent factory + day-2+ lifecycle tooling. Generates PersonaNexus identities and operational skills from job/role/context inputs, then keeps live agents healthy via Tend (persona maintenance), Drill (skill-folder maintenance), Department (team synthesis from a JD corpus), and Market (corpus observability + agent gap). | [`PersonaNexus/agentforge`](https://github.com/PersonaNexus/agentforge) | | **Voice Packs** | Optional adapter-level voice/personality assets | [`PersonaNexus/voice-packs`](https://github.com/PersonaNexus/voice-packs) | See [docs/repo-product-map.md](docs/repo-product-map.md) for the canonical repo/product/package map and naming policy. --- ## Why This Exists Every team building AI agents eventually creates their own system prompt templates, personality guidelines, and safety rules โ€” all as unstructured text, scattered across codebases, impossible to validate or compose. PersonaNexus gives you: - **A declarative YAML spec** for agent identity โ€” personality traits, expertise, guardrails, communication style - **Inheritance and composition** โ€” build agents from reusable archetypes and trait mixins - **Validation at build time** โ€” catch misconfigurations before deployment - **Multi-target compilation** โ€” YAML โ†’ system prompts, SOUL.md files, or platform-specific configs - **Identity evaluation harness** โ€” run structured scenario suites with score breakdowns and A/B comparisons - **Personality framework mapping** โ€” OCEAN (Big Five), DISC, and Jungian 16-type with bidirectional mapping - **Soul analysis** โ€” reverse-map any personality file onto all three frameworks for comparison - **Multi-agent teams** โ€” governance frameworks, workflow patterns, and team validation Think of it as **Terraform for AI agent identity** โ€” declarative, composable, and platform-agnostic. ## Quick Start ### Install ```bash pip install personanexus ``` ### Define an agent ```yaml # agents/my-agent.yaml schema_version: "1.0" metadata: id: agt_scout_001 name: "Scout" version: "1.0.0" description: "A research assistant that digs deep and explains clearly" created_at: "2026-02-14T00:00:00Z" updated_at: "2026-02-14T00:00:00Z" status: active role: title: "Research Assistant" purpose: "Help users research topics thoroughly and explain findings clearly" scope: primary: - "web research and synthesis" - "fact-checking and source evaluation" personality: traits: warmth: 0.8 directness: 0.7 rigor: 0.85 humor: 0.4 communication: tone: default: "curious and direct" language: primary: "en" principles: - id: accuracy priority: 1 statement: "Never present uncertain information as fact" guardrails: hard: - id: no_fabrication rule: "Never fabricate sources or citations" enforcement: output_filter severity: critical ``` ### Validate and compile ```bash # Validate $ personanexus validate agents/my-agent.yaml โœ“ Validation successful: agents/my-agent.yaml # Compile to system prompt $ personanexus compile agents/my-agent.yaml โœ“ Compiled Scout โ†’ agents/my-agent.compiled.md # Compile to SOUL.md format $ personanexus compile agents/my-agent.yaml --target soul โœ“ Compiled Scout โ†’ agents/my-agent.SOUL.md โœ“ Compiled Scout โ†’ agents/my-agent.STYLE.md # Run an identity eval suite $ personanexus eval agents/my-agent.yaml docs/evals/identity-smoke-suite.yaml Scout v1.0.0 score: 84% PASS # Compare two identity versions on the same suite $ personanexus eval agents/my-agent.yaml docs/evals/identity-smoke-suite.yaml \ --compare agents/my-agent-v2.yaml ``` > **Note:** If your agent uses archetype inheritance (`extends:`), add `--search-path` to compilation, analysis, and eval commands so archetypes/mixins can be resolved: > ```bash > personanexus compile agents/mira.yaml --search-path examples > personanexus analyze agents/mira.yaml --search-path examples > ``` ### Analyze any personality file ```bash $ personanexus analyze agents/my-agent.yaml Scout (Identity Yaml โ€” confidence: 100%) โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“ โ”ƒ Trait โ”ƒ Value โ”ƒ Level โ”ƒ Confidence โ”ƒ โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ โ”‚ warmth โ”‚ 0.80 โ”‚ Very High โ”‚ 100% โ”‚ โ”‚ directness โ”‚ 0.70 โ”‚ High โ”‚ 100% โ”‚ โ”‚ ... โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ OCEAN (Big Five) DISC Profile Jungian Profile Openness: 0.523 Dominance: 0.527 E/I: 0.482 Conscient.: 0.700 Influence: 0.591 S/N: 0.530 ... Closest: Steady Hand Closest: ISFJ ``` ### Or scaffold interactively ```bash $ personanexus build --llm-enhance ``` ## Features ### Personality as Code Define personality on a 0โ€“1 continuous scale across 10 standardized traits (warmth, verbosity, assertiveness, humor, empathy, directness, rigor, creativity, epistemic\_humility, patience). The compiler maps each value to calibrated natural-language instructions. ### Personality Framework Mapping Configure agents using established psychological frameworks: - **Custom** โ€” set each trait directly - **OCEAN (Big Five)** โ€” openness, conscientiousness, extraversion, agreeableness, neuroticism - **DISC** โ€” with presets like *The Commander*, *The Analyst*, *The Influencer*, *The Steady Hand* - **Jungian 16-type** โ€” all 16 types (INTJ, ENFP, etc.) with role-based recommendations - **Hybrid** โ€” framework base + explicit trait overrides All modes compile to the same 10 traits and reverse-map back to any framework for analysis. ### Composable Identities Build agents from reusable archetypes and mixins โ€” no copy-paste: ```yaml extends: "archetypes/analyst" mixins: - "mixins/empathetic" overrides: personality: traits: rigor: 0.95 ``` Conflicts are handled by configurable strategies: `last_wins`, `highest`, `lowest`, `average`. Hard guardrails always use `union` โ€” they can only be added, never removed. ### Guardrails as First-Class Citizens Safety boundaries are separated from personality. Hard guardrails are immutable at runtime; soft guardrails are admin-configurable per deployment. ### Multi-Target Compiler One identity, any platform: | Target | Output | Description | |--------|--------|-------------| | `text` | `.compiled.md` | Generic system prompt (default) | | `anthropic` | `.compiled.md` | Claude-optimized with XML sections | | `openai` | `.compiled.md` | OpenAI-optimized plain text | | `soul` | `.SOUL.md` + `.STYLE.md` | SOUL.md ecosystem format | | `openclaw` | `.personality.json` | OpenClaw personality config | | `gateway` | `.gateway.json` | Runtime-neutral public deployment contract for gateways | | `json` | `.json` | Full identity as JSON | ### Identity Evaluation Harness Define eval suites in YAML or JSON, for example under `docs/evals/`, and score an identity across persona consistency, instruction adherence, guardrails, and tone. The first release is deterministic and contract-based, which makes it CI-friendly and easy to compare version A vs version B before adding live model judges. ### Soul Analysis Reverse-map any personality file โ€” SOUL.md, personality.json, or YAML โ€” onto all three frameworks. Supports side-by-side comparison with cosine similarity scoring. ### Multi-Agent Teams Define teams with governance, workflow patterns, and performance metrics using schema v2.0: ```bash personanexus validate-team teams/research-team.yaml ``` ### Dynamic & Stateful Personality (v1.1) Agents can adapt their personality in real-time based on context and evolve over time through memory: ```yaml dynamics: default_mood: "neutral" default_mode: "stranger" moods: - name: "stressed" trait_deltas: { warmth: -0.15, rigor: +0.20 } triggers: - type: "keyword" value: "urgent" - type: "sentiment_below" value: 0.3 modes: - name: "familiar" trait_overrides: { warmth: 0.70, humor: 0.45 } triggers: - type: "interaction_count_above" value: 5 memory_influences: - condition: "positive_interactions > 10" effect: "warmth +0.10 permanent" ``` **Runtime flow:** Load user state โ†’ evaluate triggers โ†’ adjust traits โ†’ recompile prompt โ†’ update memory. Per-user state is persisted as JSON files (`.personanexus/memory/`), tracking interaction count, sentiment, trust score, and custom counters. ```python from personanexus import DynamicSession session = DynamicSession(identity, user_id="user_123") result = session.process("Hello!", sentiment=0.7) print(result.active_mood, result.active_mode, result.adjusted_traits) session.save() ``` Simulate personality shifts from the CLI: ```bash personanexus simulate agents/mira-dynamics.yaml --user stranger --steps 10 ``` ### Additional Features - **Mood states** โ€” dynamic emotional states that modify personality expression - **Behavioral modes** โ€” named operating modes (formal, crisis) with overrides - **Agent relationships** โ€” typed dynamics (`defers_to`, `collaborates_with`, `mentors`, etc.) - **Interaction protocols** โ€” human and agent communication configuration - **Narrative identity** โ€” backstory, opinions, influences, tensions for SOUL.md output - **Identity Lab UI** โ€” Streamlit web UI with Playground, Setup Wizard, and Analyze modes - **Compiled prompt diff** โ€” `personanexus diff a.yaml b.yaml --compiled --target text,anthropic` shows how YAML edits change the rendered prompt, with hints about which identity fields drove the delta - **Drop-in CI** โ€” reusable [GitHub Action](.github/actions/personanexus-check/action.yml) and [pre-commit starter](examples/ci/.pre-commit-config.yaml); see [docs/ci-integration.md](docs/ci-integration.md) ## CLI Reference | Command | Description | |---------|-------------| | `personanexus validate ` | Validate a YAML identity file | | `personanexus resolve ` | Show fully resolved identity after inheritance | | `personanexus compile ` | Compile identity to system prompt or platform format | | `personanexus doctor ` | Scan a repo or directory for PersonaNexus health issues | | `personanexus analyze ` | Analyze personality โ†’ traits/OCEAN/DISC/Jungian profiles | | `personanexus init ` | Scaffold a new identity | | `personanexus build` | Interactive wizard with optional `--llm-enhance` | | `personanexus migrate ` | Migrate between schema versions | | `personanexus simulate ` | Simulate dynamic personality shifts in a mock chat loop | | `personanexus validate-team ` | Validate a team configuration | | `personanexus personality ` | Framework mapping utilities | ### Personality subcommands ```bash personanexus personality ocean-to-traits --openness 0.7 ... personanexus personality disc-to-traits --dominance 0.9 ... personanexus personality jungian-to-traits --preset intj personanexus personality list-jungian-presets personanexus personality jungian-recommend strategic_analysis personanexus personality show-profile examples/identities/mira.yaml --search-path examples ``` Run `personanexus --help` for full options. For repo-wide checks: ```bash personanexus doctor . --search-path . personanexus doctor . --search-path . --check-compile --target text --format json ``` ## Python API ```python from personanexus import ( IdentityParser, IdentityValidator, IdentityResolver, compile_identity, SoulAnalyzer, DynamicSession, ) # Parse and validate parser = IdentityParser() identity = parser.load_identity("agents/mira.yaml") validator = IdentityValidator() result = validator.validate_identity(identity) # Resolve inheritance resolver = IdentityResolver(search_paths=["examples/"]) resolved = resolver.resolve_file("agents/mira.yaml") # Compile prompt = compile_identity(resolved, target="text") soul_files = compile_identity(resolved, target="soul") # Analyze and compare analyzer = SoulAnalyzer() result = analyzer.analyze("agents/my-agent.yaml") print(result.traits, result.ocean, result.disc, result.jungian) comparison = analyzer.compare(result_a, result_b) print(comparison.similarity_score) # Dynamic sessions โ€” stateful personality that adapts per user session = DynamicSession(resolved, user_id="user_42") result = session.process("I need urgent help!", sentiment=0.3) print(result.active_mood) # e.g. "stressed" print(result.active_mode) # e.g. "stranger" โ†’ "familiar" as trust grows print(result.adjusted_traits) # traits with mood/mode adjustments applied session.save() # persist user state to .personanexus/memory/ ``` ## Examples The [`examples/`](examples/) directory contains production-ready configurations: ``` examples/ โ”œโ”€โ”€ archetypes/ # Analyst, Tutor, Support, Strategic Analyst โ”œโ”€โ”€ mixins/ # Empathetic communication, Structured output โ”œโ”€โ”€ identities/ โ”‚ โ”œโ”€โ”€ mira.yaml # Custom traits + inheritance + evaluation config โ”‚ โ”œโ”€โ”€ mira-ocean.yaml # OCEAN (Big Five) personality โ”‚ โ”œโ”€โ”€ mira-disc.yaml # DISC preset (the_analyst) โ”‚ โ”œโ”€โ”€ mira-jungian.yaml # Jungian preset (INTJ) โ”‚ โ”œโ”€โ”€ disc-detailed.yaml # DISC with explicit numeric values โ”‚ โ”œโ”€โ”€ jungian-detailed.yaml # Jungian with explicit numeric values โ”‚ โ”œโ”€โ”€ hybrid-example.yaml # OCEAN base + trait overrides โ”‚ โ”œโ”€โ”€ hybrid-jungian.yaml # Jungian base + trait overrides โ”‚ โ”œโ”€โ”€ mira-mood.yaml # Dynamic mood states โ”‚ โ”œโ”€โ”€ mira-modes.yaml # Behavioral modes (formal, crisis, etc.) โ”‚ โ”œโ”€โ”€ mira-dynamics.yaml # Dynamic personality with mood/mode shifting + memory influences โ”‚ โ”œโ”€โ”€ composition-example.yaml # Overrides + composition conflict resolution โ”‚ โ”œโ”€โ”€ voice-and-memory.yaml # Voice settings + detailed memory config โ”‚ โ”œโ”€โ”€ storyteller.yaml # Narrative identity + voice examples โ”‚ โ”œโ”€โ”€ legal-advisor.yaml # Domain-specific guardrails + behavioral modes โ”‚ โ”œโ”€โ”€ support-team.yaml # Agent relationships + escalation paths โ”‚ โ”œโ”€โ”€ crisis-responder.yaml # Mood transitions + escalation channels โ”‚ โ”œโ”€โ”€ executive-assistant.yaml # Autonomy thresholds + interaction config โ”‚ โ””โ”€โ”€ ... # + minimal, builder-generated, multi-mixin, etc. โ””โ”€โ”€ teams/ # Multi-agent team with governance ``` ## Schema JSON Schemas for IDE autocompletion: [`schemas/v1.0/schema.json`](schemas/v1.0/schema.json) (agents) and [`schemas/v2.0/schema.json`](schemas/v2.0/schema.json) (teams). ## Development ```bash git clone https://github.com/PersonaNexus/personanexus.git cd personanexus uv sync --dev uv run pytest uv run ruff check src/ tests/ ``` ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and code style guidelines. ## Related Projects | Project | Description | |---------|-------------| | [**AgentForge**](https://github.com/PersonaNexus/agentforge) | Transform job descriptions into deployable PersonaNexus agent blueprints โ€” extracts skills, maps traits, outputs ready-to-use identities. Also ships a day-2+ tooling line (`tend` / `drill` / `department` / `market`) that keeps live agents healthy: persona drift detection, skill-folder maintenance, multi-agent team synthesis, JD-corpus observability. | | [**Voice Packs**](https://github.com/PersonaNexus/voice-packs) | Weight-level personality adapters (LoRA) that encode authorial voice into model weights. 13 pre-trained packs, proven to reduce personality drift by up to 49% vs prompt-only. [Adapters on HuggingFace](https://huggingface.co/jcrowan3/voice-pack-adapters). | ## Trademark Notice PersonaNexus uses established public-domain personality frameworks: - **OCEAN (Big Five)** is based on the Five Factor Model, which is public-domain academic research. - **DISC** refers to the behavioral model by William Moulton Marston (1928), which is in the public domain. "DiSC" (stylized) is a registered trademark of Wiley. PersonaNexus is not affiliated with or endorsed by Wiley. - **Jungian types** refers to Carl Jung's typological theory (1921), which is in the public domain. "MBTI" and "Myers-Briggs" are registered trademarks of The Myers-Briggs Company. PersonaNexus is not affiliated with or endorsed by The Myers-Briggs Company. ## License MIT โ€” see [LICENSE](LICENSE).