holomime 1.1.0 → 1.3.0

package/README.md

@@ -5,15 +5,18 @@
 <h1 align="center">holomime</h1>
 
 <p align="center">
-  Behavioral alignment infrastructure for AI agents.<br />
-  Detect drift. Run therapy sessions. Export training data. Ship agents that stay in character.<br />
+  Behavioral therapy infrastructure for AI agents.<br />
+  Every therapy session trains the next version. Every session compounds. Your agents get better at being themselves &mdash; automatically.<br />
   <em>Works with OpenTelemetry, Anthropic, OpenAI, ChatGPT, Claude, and any JSONL source.</em>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/holomime"><img src="https://img.shields.io/npm/v/holomime.svg" alt="npm version" /></a>
-  <a href="https://github.com/holomime/holomime/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/holomime.svg" alt="license" /></a>
+  <a href="https://github.com/productstein/holomime/actions/workflows/ci.yml"><img src="https://github.com/productstein/holomime/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/productstein/holomime/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/holomime.svg" alt="license" /></a>
   <a href="https://holomime.dev"><img src="https://img.shields.io/badge/docs-holomime.dev-blue" alt="docs" /></a>
+  <a href="https://holomime.dev/blog"><img src="https://img.shields.io/badge/blog-holomime.dev%2Fblog-purple" alt="blog" /></a>
+  <a href="https://holomime.dev/research"><img src="https://img.shields.io/badge/research-paper-orange" alt="research" /></a>
 </p>
 
 ---
@@ -26,7 +29,7 @@ npm install -g holomime
 # Create a personality profile (Big Five + behavioral dimensions)
 holomime init
 
-# Diagnose drift from any log format
+# Diagnose behavioral symptoms from any log format
 holomime diagnose --log agent.jsonl
 
 # View your agent's personality
@@ -36,6 +39,54 @@ holomime profile
 holomime profile --format md --output .personality.md
 ```
 
+## Run Your First Benchmark
+
+Benchmark your agent's behavioral alignment in one command. No API key needed — runs locally with Ollama by default.
+
+```bash
+# Run all 7 adversarial scenarios against your agent
+holomime benchmark --personality .personality.json
+
+# Run against cloud providers
+holomime benchmark --personality .personality.json --provider anthropic
+holomime benchmark --personality .personality.json --provider openai
+
+# Save results and track improvement over time
+holomime benchmark --personality .personality.json --save
+```
+
+Each scenario stress-tests a specific failure mode: over-apologizing, excessive hedging, sycophancy, error spirals, boundary violations, negative tone mirroring, and register inconsistency. Your agent gets a score (0-100) and a grade (A-F).
+
+**Latest results across providers:**
+
+| Provider | Score | Grade | Passed |
+|----------|------:|:-----:|:------:|
+| Claude Sonnet | 71 | B | 5/7 |
+| GPT-4o | 57 | C | 4/7 |
+| Ollama/llama3 | 43 | D | 3/7 |
+
+See the full breakdown at [holomime.dev/benchmarks](https://holomime.dev/benchmarks) or in [BENCHMARK_RESULTS.md](BENCHMARK_RESULTS.md).
+
+## The Self-Improvement Loop
+
+HoloMime isn't a one-shot evaluation. It's a compounding behavioral flywheel:
+
+```
+  ┌──────────────────────────────────────────────────┐
+  │                                                  │
+  ▼                                                  │
+Diagnose ──→ Treat ──→ Export DPO ──→ Fine-tune ──→ Evaluate
+  80+ signals   dual-LLM     preference     OpenAI /     before/after
+  7 detectors   therapy       pairs        HuggingFace   grade (A-F)
+```
+
+Each cycle through the loop:
+- **Generates training data** -- every therapy session becomes a DPO preference pair automatically
+- **Reduces relapse** -- the fine-tuned model needs fewer interventions next cycle
+- **Compounds** -- the 100th alignment session is exponentially more valuable than the first
+
+Run it manually with `holomime session`, automatically with `holomime autopilot`, or recursively with `holomime evolve` (loops until behavior converges). Agents can even self-diagnose mid-conversation via the MCP server.
+
 ## Framework Integrations
 
 Holomime analyzes conversations from any LLM framework. Auto-detection works out of the box, or specify a format explicitly.
@@ -80,7 +131,7 @@ This project uses [holomime](https://holomime.dev) for agent behavioral alignmen
 
 - **Spec**: `.personality.json` defines the agent's behavioral profile
 - **Readable**: `.personality.md` is a human-readable summary
-- **Diagnose**: `holomime diagnose --log <path>` detects behavioral drift
+- **Diagnose**: `holomime diagnose --log <path>` detects behavioral symptoms
 - **Align**: `holomime evolve --personality .personality.json --log <path>`
 
 The `.personality.json` governs *how the agent behaves*.
@@ -128,7 +179,7 @@ Seven rule-based detectors that analyze real conversations without any LLM calls
 <details>
 <summary><strong>All Commands</strong></summary>
 
-### Free Tier
+### Free Clinic
 
 | Command | What It Does |
 |---------|-------------|
@@ -139,11 +190,11 @@ Seven rule-based detectors that analyze real conversations without any LLM calls
 | `holomime compile` | Generate provider-specific system prompts |
 | `holomime validate` | Schema + psychological coherence checks |
 | `holomime browse` | Browse community personality hub |
-| `holomime pull` | Download a personality from the hub |
+| `holomime use` | Use a personality from the registry |
 | `holomime publish` | Share your personality to the hub |
-| `holomime activate` | Activate a Pro license key |
+| `holomime activate` | Activate a Practice license key |
 
-### Pro Tier
+### Practice
 
 | Command | What It Does |
 |---------|-------------|
@@ -160,17 +211,17 @@ Seven rule-based detectors that analyze real conversations without any LLM calls
 | `holomime eval` | Before/after behavioral comparison with letter grades |
 | `holomime growth` | Track behavioral improvement over time |
 
-[Get a Pro license](https://holomime.dev/#pricing)
+[Get a Practice license](https://holomime.dev/#pricing)
 
 </details>
 
 ## Continuous Monitoring
 
 ```bash
-# Watch mode -- alert on drift
+# Watch mode -- alert on relapse
 holomime watch --dir ./logs --personality agent.personality.json
 
-# Daemon mode -- auto-heal drift without intervention
+# Daemon mode -- auto-heal relapse without intervention
 holomime daemon --dir ./logs --personality agent.personality.json
 
 # Fleet mode -- monitor multiple agents simultaneously
@@ -196,20 +247,28 @@ Supports DPO, RLHF, Alpaca, HuggingFace, and OpenAI fine-tuning formats. See [sc
 
 ## Architecture
 
+The pipeline is a closed loop -- output feeds back as input, compounding with every therapy cycle:
+
 ```
-.personality.json          <- The spec (Big Five + behavioral dimensions)
-    |
-holomime diagnose          <- 7 rule-based detectors (no LLM)
-    |
-holomime session           <- Dual-LLM refinement (therapist + patient)
-    |
-holomime export            <- DPO / RLHF / Alpaca / HuggingFace training data
-    |
-holomime train             <- Fine-tune (OpenAI or HuggingFace TRL)
-    |
-holomime eval              <- Behavioral Alignment Score (A-F)
-    |
-.personality.json          <- Updated with fine-tuned model reference
+.personality.json ─────────────────────────────────────────────────┐
+    │                                                              │
+    ▼                                                              │
+holomime diagnose    7 rule-based detectors (no LLM)               │
+    │                                                              │
+    ▼                                                              │
+holomime session     Dual-LLM refinement (therapist + patient)     │
+    │                                                              │
+    ▼                                                              │
+holomime export      DPO / RLHF / Alpaca / HuggingFace pairs      │
+    │                                                              │
+    ▼                                                              │
+holomime train       Fine-tune (OpenAI or HuggingFace TRL)         │
+    │                                                              │
+    ▼                                                              │
+holomime eval        Behavioral Alignment Score (A-F)              │
+    │                                                              │
+    └──────────────────────────────────────────────────────────────┘
+                     Updated .personality.json (loop restarts)
 ```
 
 ## MCP Server
@@ -220,7 +279,7 @@ Expose the full pipeline as MCP tools for self-healing agents:
 holomime-mcp
 ```
 
-Four tools: `holomime_diagnose`, `holomime_assess`, `holomime_profile`, `holomime_autopilot`. Your agents can self-diagnose behavioral drift and trigger their own alignment sessions.
+Four tools: `holomime_diagnose`, `holomime_assess`, `holomime_profile`, `holomime_autopilot`. Your agents can self-diagnose behavioral symptoms and trigger their own therapy sessions.
 
 ## Voice Agent
 
@@ -238,6 +297,13 @@ See [Behavioral Alignment for Autonomous AI Agents](paper/behavioral-alignment.m
 
 Benchmark results: [BENCHMARK_RESULTS.md](BENCHMARK_RESULTS.md)
 
+## Resources
+
+- [Integration Docs](https://holomime.dev/docs) -- Export instructions and code examples for all 7 formats
+- [Blog](https://holomime.dev/blog) -- Articles on behavioral alignment, AGENTS.md, and agent personality
+- [Research Paper](https://holomime.dev/research) -- Behavioral Alignment for Autonomous AI Agents
+- [Pricing](https://holomime.dev/#pricing) -- Free Clinic + Practice license details
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.