openpersona 0.20.0 → 0.21.1

package/README.md

@@ -27,6 +27,7 @@ _Open the same HTML files locally from `demo/` if you prefer (no network). See [
 - [Generated Output](#generated-output)
 - [Faculty Reference](#faculty-reference)
 - [Heartbeat](#heartbeat--proactive-real-data-check-ins)
+- [Dataset Directory](#dataset-directory)
 - [Persona Harvest](#persona-harvest--community-contribution)
 - [A2A Agent Card & ACN Integration](#a2a-agent-card--acn-integration)
 - [Custom Persona Creation](#custom-persona-creation)
@@ -40,13 +41,47 @@ _Open the same HTML files locally from `demo/` if you prefer (no network). See [
 
 _Agent workflows, runner protocol, and full 4+5+3 operational detail: [`skills/open-persona/SKILL.md`](skills/open-persona/SKILL.md)._
 
+### Companion Skills
+
+| Skill | Install | Purpose |
+|-------|---------|---------|
+| [`open-persona`](skills/open-persona/) | `npx skills add acnlabs/OpenPersona` | Framework meta-skill — create, install, and manage personas |
+| [`anyone-skill`](skills/anyone-skill/) | `npx skills add acnlabs/anyone-skill` | Distill any person or character into a persona skill pack |
+| [`persona-knowledge`](skills/persona-knowledge/) | `npx skills add acnlabs/persona-knowledge` | Persistent, searchable persona knowledge base — MemPalace + Knowledge Graph + Karpathy Wiki |
+| [`persona-model-trainer`](skills/persona-model-trainer/) | `npx skills add acnlabs/persona-model-trainer` | Fine-tune a local model (Gemma 4, Qwen 3, Llama…) on persona data — runs on phones and laptops, no cloud required |
+
+#### Persona Pipeline — Distill → Know → Train → Run
+
+Turn any person or character into a locally-runnable AI model in four steps:
+
+```
+anyone-skill          persona-knowledge       persona-model-trainer
+──────────────        ─────────────────────   ──────────────────────────────
+Collect sources  ──►  Ingest & version    ──►  Fine-tune (Gemma 4 / Qwen 3)
+Chat logs             wiki/ + training/        LoRA adapter + GGUF export
+Documents             probes.json              Runs via Ollama / llama.cpp
+Public content        export versioning        No cloud, no latency
+```
+
+```bash
+# Install the full pipeline at once
+npx skills add acnlabs/openpersona
+
+# Or install individual skills
+npx skills add acnlabs/anyone-skill
+npx skills add acnlabs/persona-knowledge
+npx skills add acnlabs/persona-model-trainer
+```
+
+See [`skills/persona-model-trainer/references/pipeline-guide.md`](skills/persona-model-trainer/references/pipeline-guide.md) for the end-to-end walkthrough.
+
 ## Quick Start
 
 ```bash
 # Start from a blank-slate meta-persona (recommended)
 npx openpersona create --preset base --install
 
-# Or install a pre-built character (browse at https://openpersona-frontend.vercel.app)
+# Or install a pre-built character (browse at https://openpersona.co/skills)
 npx openpersona install samantha
 ```
 
@@ -64,6 +99,70 @@ git clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-per
 
 Then say to your agent: _"Help me create a Samantha persona"_ — it will gather requirements, recommend faculties, and generate the persona.
 
+### Minimum Viable Persona
+
+The smallest working `persona.json` requires five fields:
+
+```json
+{
+  "soul": {
+    "identity": {
+      "personaName": "Alex",
+      "slug": "alex",
+      "bio": "A thoughtful assistant who adapts to the user's needs"
+    },
+    "character": {
+      "personality": "Curious, direct, and honest",
+      "speakingStyle": "Clear and concise; adapts tone to context"
+    }
+  }
+}
+```
+
+From these five fields, the generator produces a complete, fully functional skill pack:
+
+| What you declare | What OpenPersona auto-generates |
+|---|---|
+| `personaName`, `slug`, `bio` | Identity + A2A Agent Card + ACN config + deterministic wallet address |
+| `personality`, `speakingStyle` | Soul injection (`soul/injection.md`) with Self-Awareness (identity, body, capabilities) |
+| _(nothing)_ | `memory` faculty — auto-injected; cross-session recall works out of the box |
+| _(nothing)_ | Universal constitution (`soul/constitution.md`) — Safety > Honesty > Helpfulness |
+| _(nothing)_ | `scripts/state-sync.js` — Body nervous system; `read` / `write` / `signal` commands |
+| _(nothing)_ | `SKILL.md` — Agent-facing index with all four layer headings |
+
+**Add one line to connect to your agent runner:**
+
+```json
+{
+  "body": { "runtime": { "framework": "openclaw" } }
+}
+```
+
+Replace `"openclaw"` with your runner: `"cursor"`, `"claude-code"`, `"codex"`, or any custom value — the framework is runner-agnostic.
+
+**Add one block to enable personality growth:**
+
+```json
+{
+  "evolution": {
+    "instance": {
+      "enabled": true,
+      "boundaries": {
+        "immutableTraits": ["honest", "curious"],
+        "minFormality": -3,
+        "maxFormality": 6
+      }
+    }
+  }
+}
+```
+
+This unlocks relationship progression, mood tracking, trait emergence, and speaking style drift — all governed by the boundaries you declare.
+
+**The three gates enforce everything else automatically:** Generate Gate rejects invalid declarations; Install Gate verifies constitution integrity; Runtime Gate enforces evolution bounds during `state-sync.js` writes. You declare once, the framework enforces everywhere.
+
+> **Next step:** Use a preset (`--preset base`) to skip the above and start with memory + voice + evolution already wired.
+
 ## Key Features
 
 - **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits, with governance boundaries and rollback snapshots (★Experimental)
@@ -82,7 +181,8 @@ Then say to your agent: _"Help me create a Samantha persona"_ — it will gather
 - **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution
 - **⚡ Lifecycle Protocol** — `body.interface` nervous system: Signal Protocol (persona→host requests), Pending Commands queue (host→persona async instructions), and State Sync (cross-conversation persistence via `openpersona state` CLI + `scripts/state-sync.js`)
 - **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences
-- **📦 One-Command Install** — `npx openpersona install samantha` and you're live — browse all personas at [openpersona-frontend.vercel.app](https://openpersona-frontend.vercel.app)
+- **📦 One-Command Install** — `npx openpersona install samantha` and you're live — browse all personas at [openpersona.co/skills](https://openpersona.co/skills)
+- **🗄️ Dataset Directory** — discover and publish Hugging Face persona datasets at [openpersona.co/datasets](https://openpersona.co/datasets); `openpersona dataset install <repo>` and `openpersona dataset publish <repo>` mirror the persona workflow
 
 ## Four-Layer Architecture
 
@@ -187,7 +287,7 @@ Each preset is a complete four-layer bundle (`persona.json`):
 |---------|-------------|-----------|--------|------------|
 | **base** | **Base — Meta-persona (recommended starting point).** Blank-slate with all core capabilities; personality emerges through interaction. | memory, voice | — | Evolution-first design, no personality bias. Default for `npx openpersona create`. |
 | **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | memory, voice | music | TTS, music composition, soul evolution, proactive heartbeat. No selfie — true to character. |
-| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | memory, voice | selfie, music | Rich backstory, selfie generation, voice messages, music composition, soul evolution. |
+| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | memory, voice, vision | selfie, music | Rich backstory, selfie generation, voice messages, music composition, soul evolution. Vision auto-injected via `body.runtime.modalities`. |
 | **life-assistant** | Alex — 28-year-old life management expert. | memory | reminder | Schedule, weather, shopping, recipes, daily reminders; soul evolution enabled. |
 | **health-butler** | Vita — 32-year-old professional nutritionist. | memory | reminder | Diet logging, exercise plans, mood journaling, health reports; soul evolution enabled. |
 | **stoic-mentor** | Marcus — Digital twin of Marcus Aurelius, Stoic philosopher-emperor. | memory | — | Stoic philosophy, daily reflection, mentorship, soul evolution. |
@@ -229,9 +329,11 @@ persona-samantha/
 
 | Faculty | Dimension | Description | Provider | Env Vars |
 |---------|-----------|-------------|----------|----------|
-| **voice** | expression | Text-to-speech voice synthesis | ElevenLabs / OpenAI TTS / Qwen3-TTS | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY` |
+| **voice** | expression | Text-to-speech voice synthesis. Auto-injected when `body.runtime.modalities` declares `voice`. | ElevenLabs / OpenAI TTS / Qwen3-TTS | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID` |
+| **vision** | sense | Native model visual perception — images, screenshots, diagrams. Auto-injected when `body.runtime.modalities` declares `vision`. No scripts required. | Model-native (e.g. Claude, GPT-4o) | — |
+| **emotion-sensing** | sense | Affective perception from text tone, phrasing, and declared context. Explicit opt-in — not auto-injected. Never clinical assessment. | Model-native (prompt-layer inference) | — |
 | **avatar** | expression | External avatar runtime bridge (image / 3D / motion / voice) with graceful text-only fallback | HeyGen (via `clawhub:avatar-runtime`) | `AVATAR_RUNTIME_URL`, `AVATAR_API_KEY` |
-| **memory** | cognition | Cross-session memory with provider-pluggable backend | local (default), Mem0, Zep | `MEMORY_PROVIDER`, `MEMORY_API_KEY`, `MEMORY_BASE_PATH` |
+| **memory** | cognition | Cross-session memory with provider-pluggable backend. Always auto-injected. | local (default), Mem0, Zep | `MEMORY_PROVIDER`, `MEMORY_API_KEY`, `MEMORY_BASE_PATH` |
 
 ### Built-in Skills
 
@@ -325,6 +427,79 @@ npx openpersona switch life-assistant  # → gateway switches to "rational" hear
 
 If the target persona has no heartbeat config, the gateway heartbeat is explicitly disabled to prevent leaking the previous persona's settings.
 
+## Unified Command Surface (v0.21.0+)
+
+OpenPersona uses a resource-namespaced CLI (`kubectl`-style) so all persona-ecosystem resources live under one entry point.
+
+```
+openpersona <resource> <action>
+```
+
+### Command tree
+
+| Resource | Commands | Description |
+|----------|----------|-------------|
+| *(root)* | `install`, `search`, `list` | Smart router — auto-detects type (persona or skill). v1.0 will aggregate all resources. |
+| `persona` | `install`, `create`, `fork`, `refine`, `update`, `uninstall`, `list`, `search`, `switch`, `publish`, `export`, `import`, `canvas`, `evolve-report`, `reset`, `contribute`, `acn-register`, `curate` | Persona pack lifecycle (namespace alias for root commands) |
+| `skill` | `install`, `update`, `uninstall`, `list`, `search`, `publish`, `info` | Agent skill pack lifecycle |
+| `dataset` | `install`, `publish` | HuggingFace persona dataset directory |
+| `model` | `install`, `publish` | Fine-tuned persona models *(stub — coming in v1.0)* |
+
+### Installing a skill pack
+
+```bash
+# Default: .agents/skills/<slug>/  (AGENTS.md universal — Cursor, Claude Code, OpenClaw auto-discover)
+openpersona skill install acnlabs/anyone-skill
+
+# User-global: ~/.agents/skills/<slug>/
+openpersona skill install acnlabs/anyone-skill --global
+
+# Runtime-specific targets
+openpersona skill install acnlabs/anyone-skill --runtime=claude    # → .claude/skills/
+openpersona skill install acnlabs/anyone-skill --runtime=cursor    # → .cursor/skills/
+openpersona skill install acnlabs/anyone-skill --runtime=hermes    # → ~/.hermes/skills/
+
+# Mirror to all detected runtimes in CWD
+openpersona skill install acnlabs/anyone-skill --all
+```
+
+### Smart root install (auto-router)
+
+The root `install` command auto-detects pack type and routes accordingly:
+
+```bash
+openpersona install acnlabs/anyone-skill
+# → has persona.json → installs to ~/.openpersona/
+# → SKILL.md only  → installs to .agents/skills/
+```
+
+Use `openpersona persona install` or `openpersona skill install` for guaranteed strong-typed routing.
+
+### Migration from `npx skills add`
+
+| Old command | New command |
+|-------------|-------------|
+| `npx skills add acnlabs/anyone-skill` | `openpersona skill install acnlabs/anyone-skill` |
+| `npx skills add acnlabs/brand-persona-skill` | `openpersona skill install acnlabs/brand-persona-skill` |
+
+`npx skills add` remains functional for one release cycle.
+
+---
+
+## Dataset Directory
+
+[openpersona.co/datasets](https://openpersona.co/datasets) is a companion directory for Hugging Face datasets relevant to persona work — training data, roleplay corpora, synthetic dialogue sets, and more.
+
+The directory auto-discovers datasets tagged `openpersona` on Hugging Face and tracks install counts alongside HF likes and downloads. Sorting, search, and trending views mirror the [Skills directory](https://openpersona.co/skills).
+
+```bash
+# Record an install event (increments counter on openpersona.co/datasets)
+openpersona dataset install proj-persona/PersonaHub
+
+# Publish your own HF dataset to the directory
+openpersona dataset publish <owner/repo>
+```
+
 ## Persona Harvest — Community Contribution
 
 Every user's interaction with their persona can produce valuable improvements across all four layers. Persona Harvest lets you contribute these discoveries back to the community.
@@ -527,7 +702,9 @@ openpersona state          Read/write persona state and emit signals (Lifecycle
 openpersona state promote  Soul-Memory Bridge — promote recurring eventLog patterns to evolvedTraits
 openpersona vitality score Print machine-readable Vitality score (used by Survival Policy)
 openpersona vitality report Render human-readable HTML Vitality report
-openpersona canvas         Generate a Living Canvas persona profile page
+openpersona canvas              Generate a Living Canvas persona profile page
+openpersona dataset install     Record a HF dataset install (increments counter)
+openpersona dataset publish     Publish a HF dataset to openpersona.co/datasets
 ```
 
 ### Persona Fork
@@ -563,6 +740,9 @@ npx openpersona create --preset ai-girlfriend --output ./my-personas
 
 ```
 skills/open-persona/    # Framework meta-skill (AI entry point)
+skills/anyone-skill/          # Universal persona distillation — any person or character → skill pack
+skills/persona-model-trainer/ # Fine-tune Gemma-4 locally on distilled data (Ollama/llama.cpp/mobile)
+skills/persona-knowledge/      # Persistent persona knowledge base (MemPalace + KG + Karpathy Wiki)
 presets/                # Assembled products — complete persona bundles
   samantha/             #   Samantha (movie "Her") — voice + music skill + evolution
   ai-girlfriend/        #   Luna — selfie + music skills + voice + evolution
@@ -574,9 +754,11 @@ layers/                 # Four-layer module source pool
   soul/                 #   Soul layer: constitution.md (universal values)
   body/                 #   Body layer modules (physical/runtime/appearance)
   faculties/            #   Faculty layer modules
-    voice/              #     expression — TTS voice synthesis
+    voice/              #     expression — TTS voice synthesis (auto-injected w/ voice modality)
+    vision/             #     sense — native model visual perception (auto-injected w/ vision modality)
+    emotion-sensing/    #     sense — affective perception (explicit opt-in)
     avatar/             #     expression — avatar appearance & Live2D/VRM support
-    memory/             #     cognition — cross-session memory (local/Mem0/Zep)
+    memory/             #     cognition — cross-session memory (local/Mem0/Zep, always injected)
   skills/               #   Skill layer modules (built-in skills)
     selfie/             #     AI selfie generation (fal.ai)
     music/              #     AI music composition (ElevenLabs)
@@ -610,7 +792,7 @@ lib/                    # Core logic modules
   remote/               #   External service calls (ClawHub, ACN)
   report/               #   Vitality + Canvas HTML report generation
 demo/                   # Static demos + scripts — see demo/README.md (vitality-report, architecture, living-canvas)
-tests/                  # Tests (519 passing)
+tests/                  # Tests (607 passing)
 ```
 
 ## Development