pop-persona 0.1.7

Framework-neutral persona object protocol for agent runtimes.

Persona Object Protocol (POP)

A lightweight draft protocol for portable persona objects in multimodal AI systems

POP is a lightweight public draft for representing portable persona objects with explicit boundaries. POP is a framework-neutral persona object protocol for agent runtimes. It is positioning-first and protocol-oriented: not a product, not a persona generation pipeline, and not a full runtime stack.

Preferred scholarly citation for POP is the POP-Core paper: 10.5281/zenodo.18907957.

The repository itself is separately archived on Zenodo at 10.5281/zenodo.18898252 for version-specific software citation.

For minimal citation guidance, see docs/cite-pop.md.

Digital Biosphere Ecosystem

This repository is part of the Digital Biosphere Architecture.

Architecture overview: digital-biosphere-architecture

Positioning

• POP is not a full agent framework.
• POP is not a prompt template library.
• POP is not a memory or permissions system.
• POP focuses on portable persona objects and adapter-based runtime projection.

Ecosystem Direction

• LangChain integration
• CrewAI projection
• Microsoft Agent Framework exploration
• LlamaIndex exploration

For the current ecosystem plan, see docs/pop-ecosystem-roadmap.md. For the adapter strategy, see docs/pop-adapter-model.md.

Runtime Adapter Layer

The runtime-facing adapter surface is documented in docs/runtime-adapters.md. The current LangChain and CrewAI adapters are early-preview scaffolds that bind canonical POP persona objects to runtime-oriented representations without changing the schema baseline.

Runtime Integrations (Early Preview)

LangChain integration scaffolds are available through the optional langchain extra, and CrewAI integration scaffolds are available through the optional crewai extra. The canonical schema baseline remains v0.1.0 while runtime-facing binding surfaces continue to evolve.

Install examples:

pip install "pop-persona[langchain]"
pip install "pop-persona[crewai]"

Example scripts:

• examples/integrations/langchain_minimal.py
• examples/integrations/crewai_minimal.py

Execution-Layer Helpers (Early Preview)

LangChain execution helpers are available through optional runtime integration surfaces, and CrewAI execution helpers are available through optional runtime integration surfaces. The canonical schema baseline remains v0.1.0.

Execution-layer examples:

• examples/integrations/langchain_create_agent_minimal.py
• examples/integrations/langchain_execution_minimal.py
• examples/integrations/crewai_execution_minimal.py

LangChain Execution Contract (Early Preview)

LangChain execution helpers are available through the optional langchain extra. They are aligned with LangChain v1 create_agent, middleware, and runtime-context helper surfaces, but they are not official LangChain runtime objects. The canonical schema baseline remains v0.1.0.

The main LangChain-facing entry point in this release line is create_langchain_execution_bundle(...). Optional langchain support enables richer helper/spec paths, while compatibility helpers remain available but are no longer the primary documented path.

LangChain contract examples:

• examples/integrations/langchain_create_agent_minimal.py
• examples/integrations/langchain_execution_minimal.py
• examples/integrations/langchain_installed_contract_minimal.py

Compatibility helpers from the earlier execution scaffolding line are retained for backward compatibility. The primary LangChain-facing surface in the current release line is:

• create_langchain_execution_bundle(...)
• create_langchain_create_agent_kwargs(...)
• create_langchain_context_bundle(...)
• create_langchain_middleware_bundle(...)
• maybe_build_langchain_agent_spec(...)

LangChain Minimal Adoption (Early Preview)

The primary LangChain-facing entry point remains create_langchain_execution_bundle(...). This path is designed to reduce first-adoption friction and to keep installed-package smoke validation easy to reproduce.

Compatibility helpers remain available for backward compatibility, but they are not the recommended primary path for first adoption. The canonical schema baseline remains v0.1.0.

Minimal-adoption references:

• examples/integrations/langchain_minimal_20_lines.py
• examples/integrations/langchain_installed_smoke_minimal.py
• docs/quickstart/langchain-minimal-adoption.md

Portability Demo

An early cross-runtime portability scaffold is available at examples/cross-runtime-persona-portability/README.md.

Canonical JSON Schema

POP provides a canonical JSON Schema for persona objects at schema/pop-persona.schema.json. The current schema is an early preview intended to define the core structural boundary of a POP persona object. Within that boundary, persona remains separate from memory, tools, and permissions.

schema/pop-persona.schema.json is the current preview alias. schema/versions/ contains versioned historical snapshots, and those versioned schemas are the normative references for stable review and comparison.

Valid and invalid fixtures are maintained under fixtures/valid/ and fixtures/invalid/ to support strict validation and protocol regression testing.

Release Baseline

v0.1.0 is the first tagged baseline release for POP. Versioned schemas under schema/versions/ are the normative snapshots, while the current alias continues to track the latest preview surface.

TestPyPI smoke and Trusted Publishing setup are part of the release-readiness path for this baseline.

For the current public packaging position, see docs/releases/v0.1.1-announcement.md. The runtime adapter release is documented at docs/releases/v0.1.2-release-notes.md. The current execution-layer release is documented at docs/releases/v0.1.7-release-notes.md. A public release announcement is available in English at docs/releases/v0.1.5-announcement.md and in Chinese at docs/releases/v0.1.5-announcement.zh.md. For a maintainer-facing LangChain summary, see docs/langchain-maintainer-note.md. The previous execution-layer increment remains documented at docs/releases/v0.1.3-release-notes.md. The LangChain contract-focused release plan is documented in docs/releases/v0.1.5-plan.md. The next positioning draft is documented in docs/releases/v0.1.6-plan.md. The early release chronology is summarized in docs/pop-evolution-v0.1.0-v0.1.4.md.

TestPyPI and Trusted Publishing

TestPyPI is used for first publication smoke validation. Trusted Publishing is planned through GitHub Actions with OIDC, and real PyPI publication follows successful smoke validation and release discipline.

PyPI Publication Path

Real PyPI publication is prepared through a dedicated GitHub Actions workflow and a separate pypi environment. The recommended order is: configure the PyPI Trusted Publisher, dispatch the PyPI publish workflow, and then validate installation from the public PyPI index in a clean virtual environment.

Python SDK (Early Preview)

A minimal Python SDK is provided as an early preview for loading, validating, and projecting canonical POP persona objects.

Install from the repository root:

pip install -e .

Strict schema validation is available through an optional dependency:

pip install -e '.[schema]'
pip install "pop-persona[schema]"

For package build and release-readiness checks:

pip install -e '.[dev,schema]'

CLI example:

pop-inspect examples/cross-runtime-persona-portability/personas/lawyer_persona.json
pop-inspect --list-schema-versions
pop-inspect --strict-schema examples/cross-runtime-persona-portability/personas/lawyer_persona.json

Core installation provides lightweight inspection. Strict schema validation requires the optional schema extra.

TestPyPI smoke example:

python -m pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple "pop-persona[schema]"

Python API example:

from pop import load_persona, validate_persona
from pop.projections import project_to_crewai, project_to_langchain

persona = load_persona(
    "examples/cross-runtime-persona-portability/personas/lawyer_persona.json"
)
validate_persona(persona)

langchain_view = project_to_langchain(persona)
crewai_view = project_to_crewai(persona)

POP-Core Paper

Zhang, B. (2026). POP-Core: Formal Semantics and Interoperability of Portable Persona Objects. Zenodo. https://doi.org/10.5281/zenodo.18907957

What POP is

POP defines a minimal object layer for packaging persona definitions in a portable and inspectable form. It focuses on persona object representation, plugin attachment entry points, separation from memory and permissions, and basic governance boundaries.

What POP solves

POP provides a minimal shared structure for describing persona objects across systems. Its purpose is to keep persona definitions distinct from memory stores, capability grants, and application-specific orchestration logic.

Scope

POP v0.1 covers:

• a minimal persona core
• optional memory hook declarations
• optional plugin manifest declarations
• explicit safety and governance boundaries
• simple draft version labeling

Non-goals

POP is not:

• a full personality generation system
• a model training or fine-tuning method
• a robotics stack
• a digital immortality framework
• a universal cross-model persona injection method
• a substitute for permission, identity, or memory systems

Minimal structure

A POP object is intentionally small. The reference structure in this repository includes:

• schema_version for draft compatibility
• id, name, and description for identity and positioning
• traits, anchors, and behavior for the persona core
• memory_hooks as references to separate memory subsystems
• plugins as declarative attachment entry points

The object does not embed long-term memory, permission grants, or execution policy.

Relationship to adjacent work

POP complements adjacent work on persona steering, persona consistency, agent tooling, and agent security. It does not replace those areas. Its role is narrower: to define a portable persona object layer that other systems can interpret, constrain, or extend.

For external messaging and positioning copy, see docs/communication-kit.md.

Repository structure

.
├── .zenodo.json
├── CITATION.cff
├── LICENSE
├── README.md
├── adapters
│   ├── crewai
│   ├── langchain
│   ├── llamaindex
│   └── microsoft-agent-framework
├── docs
│   ├── README.md
│   ├── cite-pop.md
│   ├── communication-kit.md
│   ├── pop-adapter-model.md
│   ├── pop-ecosystem-roadmap.md
│   └── short-outreach-kit.md
├── examples
│   ├── cross-runtime-persona-portability
│   ├── caregiver.persona.json
│   ├── companion.persona.json
│   └── mentor.persona.json
├── schema
│   └── persona.schema.json
└── spec
    └── pop-0.1.md

Status

This repository contains a positioning-first v0.1.0-draft. It is a draft protocol, not a stable standard, and not a guarantee of high-fidelity persona transfer across models or products.

For a forward-looking RFC-style core draft, see spec/POP-core.md. For the draft canonical JSON binding, see spec/POP-json-binding.md and schema/pop.schema.json. For minimal runtime integration patterns, see docs/interop.md.

CLI

The repository now includes a minimal reference CLI for POP:

python3 -m pip install -e .
pop validate examples/mentor.v1.json
pop project examples/mentor.v1.json --runtime prompt
pop migrate-pop01 examples/mentor.persona.json

For direct local execution without installation:

python3 cli/pop_cli.py validate examples/mentor.v1.json

LangChain Integration

POP now includes a first runtime integration for LangChain:

python3 -m pip install -e ".[langchain]"
python3 examples/langchain_agent.py examples/mentor.v1.json --print-config

Middleware-oriented preview package:

python3 examples/langchain_middleware_demo.py --print-config

The installed package exposes langchain_pop as a middleware-oriented preview layer for LangChain agents. It injects the POP-derived system prompt, preserves persona identity in runtime state, and filters tools against POP boundaries.

An extraction-ready standalone package scaffold is available at integrations/langchain-pop.

If you have OPENAI_API_KEY configured, you can invoke a live LangChain agent:

python3 examples/langchain_agent.py examples/mentor.v1.json --model gpt-4.1-mini
python3 examples/langchain_middleware_demo.py --invoke --model gpt-4.1-mini

Package API:

from pop_protocol.adapters.langchain import create_langchain_agent, pop_to_langchain_config
from langchain_pop.agent import create_pop_agent
from langchain_pop.middleware import POPMiddleware

CI And Packaging

The repository includes a GitHub Actions workflow at .github/workflows/validate.yml that:

• validates all JSON example objects with pop validate
• builds the Python distribution with python -m build

Typical local packaging commands:

python3 -m pip install -e .
python3 -m pip install build
python3 -m build

The repository includes dedicated TestPyPI and PyPI trusted publishing workflows under .github/workflows/, and package publication now follows tagged release and smoke-validation discipline.