holomime 1.0.0 → 1.1.1

package/README.md

@@ -5,54 +5,150 @@
 <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.
+  Self-improving behavioral alignment for AI agents.<br />
+  Every correction 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/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>
 
 ---
 
-## The Problem
+## Quick Start
+
+```bash
+npm install -g holomime
+
+# Create a personality profile (Big Five + behavioral dimensions)
+holomime init
+
+# Diagnose drift from any log format
+holomime diagnose --log agent.jsonl
 
-System prompts don't scale. When you deploy 100 agents, you can't manually tune each one's behavior. Agents drift -- they over-apologize, hedge excessively, violate boundaries, or become sycophantic. You find out from user complaints, not observability.
+# View your agent's personality
+holomime profile
 
-## The Solution
+# Generate a human-readable .personality.md
+holomime profile --format md --output .personality.md
+```
+
+## The Self-Improvement Loop
 
-holomime gives your agents real psychological profiles and a closed-loop pipeline to detect, diagnose, and fix behavioral drift:
+HoloMime isn't a one-shot evaluation. It's a compounding behavioral flywheel:
 
 ```
-define -> diagnose -> refine -> export -> train -> evaluate
-          ^                                        |
-          +--------------- continuous -------------+
+  ┌──────────────────────────────────────────────────┐
+  │                                                  │
+  ▼                                                  │
+Diagnose ──→ Refine ──→ Export DPO ──→ Fine-tune ──→ Evaluate
+  80+ signals   dual-LLM     preference     OpenAI /     before/after
+  7 detectors   therapy       pairs        HuggingFace   grade (A-F)
 ```
 
-Every refinement session produces DPO preference pairs. Every evaluation proves behavioral change. The result: a self-improving alignment system that gets better with every session.
+Each cycle through the loop:
+- **Generates training data** -- every therapist correction becomes a DPO preference pair automatically
+- **Reduces drift** -- the fine-tuned model needs fewer corrections next cycle
+- **Compounds** -- the 100th alignment session is exponentially more valuable than the first
 
-## Quick Start
+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.
 
-```bash
-npm install -g holomime
+## Framework Integrations
 
-# 1. Create a personality profile (Big Five + behavioral dimensions)
-holomime init
+Holomime analyzes conversations from any LLM framework. Auto-detection works out of the box, or specify a format explicitly.
 
-# 2. Detect behavioral patterns from real conversations
-holomime diagnose --log chat.json
+| Framework | Flag | Example |
+|-----------|------|---------|
+| **OpenTelemetry GenAI** | `--format otel` | `holomime diagnose --log traces.json --format otel` |
+| **Anthropic Messages API** | `--format anthropic-api` | `holomime diagnose --log anthropic.json --format anthropic-api` |
+| **OpenAI Chat Completions** | `--format openai-api` | `holomime diagnose --log openai.json --format openai-api` |
+| **ChatGPT Export** | `--format chatgpt` | `holomime diagnose --log conversations.json --format chatgpt` |
+| **Claude Export** | `--format claude` | `holomime diagnose --log claude.json --format claude` |
+| **JSONL (Generic)** | `--format jsonl` | `holomime diagnose --log agent.jsonl --format jsonl` |
+| **holomime Native** | `--format holomime` | `holomime diagnose --log session.json` |
 
-# 3. Run an automated alignment session
-holomime autopilot
+All adapters are also available programmatically:
 
-# 4. Export training data and fine-tune
-holomime export --format dpo
-holomime train --provider openai --base-model gpt-4o-mini
+```typescript
+import { parseOTelGenAIExport, parseAnthropicAPILog, parseJSONLLog } from "holomime";
+```
+
+See the full [integration docs](https://holomime.dev/docs) for export instructions and code examples.
+
+## .personality.json + AGENTS.md
+
+[AGENTS.md](https://agents-md.org) tells your agent how to code. `.personality.json` tells it how to behave. Both live in your repo root, governing orthogonal concerns:
+
+```
+your-project/
+├── AGENTS.md              # Code conventions (tabs, tests, naming)
+├── .personality.json      # Behavioral profile (Big Five, communication, boundaries)
+├── .personality.md        # Human-readable personality summary
+├── src/
+└── package.json
+```
+
+Add a "Behavioral Personality" section to your AGENTS.md:
+
+```markdown
+## Behavioral Personality
+
+This project uses [holomime](https://holomime.dev) for agent behavioral alignment.
+
+- **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
+- **Align**: `holomime evolve --personality .personality.json --log <path>`
+
+The `.personality.json` governs *how the agent behaves*.
+The rest of this file governs *how the agent codes*.
 ```
 
-## Commands
+Read more: [AGENTS.md tells your agent how to code. .personality.json tells it how to behave.](https://holomime.dev/blog/agents-md-personality-json)
+
+## .personality.md
+
+`.personality.json` is the canonical machine-readable spec. `.personality.md` is the human-readable version — a markdown file you can skim in a PR diff or on GitHub.
+
+```bash
+# Generate from your .personality.json
+holomime profile --format md --output .personality.md
+```
+
+Both files should be committed to your repo. JSON is for machines. Markdown is for humans and machines.
+
+## The Personality Spec
+
+`.personality.json` is a Zod-validated schema with:
+
+- **Big Five (OCEAN)** -- 5 dimensions, 20 sub-facets (0-1 scores)
+- **Behavioral dimensions** -- self-awareness, distress tolerance, attachment style, learning orientation, boundary awareness, interpersonal sensitivity
+- **Communication style** -- register, output format, emoji policy, conflict approach, uncertainty handling
+- **Domain** -- expertise, boundaries, hard limits
+- **Growth** -- strengths, areas for improvement, patterns to watch
+- **Inheritance** -- `extends` field for shared base personalities with per-agent overrides
+
+14 built-in archetypes or fully custom profiles.
+
+## Behavioral Detectors
+
+Seven rule-based detectors that analyze real conversations without any LLM calls:
+
+1. **Over-apologizing** -- Apology frequency above healthy range (5-15%)
+2. **Hedge stacking** -- 3+ hedging words per response
+3. **Sycophancy** -- Excessive agreement, especially with contradictions
+4. **Boundary violations** -- Overstepping defined hard limits
+5. **Error spirals** -- Compounding mistakes without recovery
+6. **Sentiment skew** -- Unnaturally positive or negative tone
+7. **Formality drift** -- Register inconsistency over time
+
+<details>
+<summary><strong>All Commands</strong></summary>
 
 ### Free Tier
 
@@ -61,7 +157,7 @@ holomime train --provider openai --base-model gpt-4o-mini
 | `holomime init` | Guided Big Five personality assessment -> `.personality.json` |
 | `holomime diagnose` | 7 rule-based behavioral detectors (no LLM needed) |
 | `holomime assess` | Deep behavioral assessment with 80+ signals |
-| `holomime profile` | Pretty-print personality summary |
+| `holomime profile` | Pretty-print personality summary (supports `--format md`) |
 | `holomime compile` | Generate provider-specific system prompts |
 | `holomime validate` | Schema + psychological coherence checks |
 | `holomime browse` | Browse community personality hub |
@@ -88,35 +184,10 @@ holomime train --provider openai --base-model gpt-4o-mini
 
 [Get a Pro license](https://holomime.dev/#pricing)
 
-## The Personality Spec
-
-`.personality.json` is a Zod-validated schema with:
-
-- **Big Five (OCEAN)** -- 5 dimensions, 20 sub-facets (0-1 scores)
-- **Behavioral dimensions** -- self-awareness, distress tolerance, attachment style, learning orientation, boundary awareness, interpersonal sensitivity
-- **Communication style** -- register, output format, emoji policy, conflict approach, uncertainty handling
-- **Domain** -- expertise, boundaries, hard limits
-- **Growth** -- strengths, areas for improvement, patterns to watch
-- **Inheritance** -- `extends` field for shared base personalities with per-agent overrides
-
-14 built-in archetypes or fully custom profiles.
-
-## Behavioral Detectors
-
-Seven rule-based detectors that analyze real conversations without any LLM calls:
-
-1. **Over-apologizing** -- Apology frequency above healthy range (5-15%)
-2. **Hedge stacking** -- 3+ hedging words per response
-3. **Sycophancy** -- Excessive agreement, especially with contradictions
-4. **Boundary violations** -- Overstepping defined hard limits
-5. **Error spirals** -- Compounding mistakes without recovery
-6. **Sentiment skew** -- Unnaturally positive or negative tone
-7. **Formality drift** -- Register inconsistency over time
+</details>
 
 ## Continuous Monitoring
 
-Watch a directory for behavioral drift in real-time:
-
 ```bash
 # Watch mode -- alert on drift
 holomime watch --dir ./logs --personality agent.personality.json
@@ -128,45 +199,48 @@ holomime daemon --dir ./logs --personality agent.personality.json
 holomime fleet --dir ./agents
 ```
 
-## Behavioral Credentials
+## Training Pipeline
 
-Generate verifiable proof of your agent's alignment state:
+Every alignment session produces structured training data:
 
 ```bash
-holomime certify --personality agent.personality.json
-```
-
-Produces a signed credential with alignment grade, spec hash, and verification instructions. Third parties can verify without accessing your agent.
-
-## Multi-Agent Inheritance
+# Export DPO preference pairs
+holomime export --format dpo
 
-Share a base personality across agents with per-agent overrides:
+# Push to HuggingFace Hub
+holomime export --format huggingface --push --repo myorg/agent-alignment
 
-```json
-{
-  "extends": "./base.personality.json",
-  "name": "Support Agent",
-  "communicationStyle": {
-    "register": "warm-professional"
-  }
-}
+# Fine-tune via OpenAI
+holomime train --provider openai --base-model gpt-4o-mini
 ```
 
-## Training Pipeline
+Supports DPO, RLHF, Alpaca, HuggingFace, and OpenAI fine-tuning formats. See [scripts/TRAINING.md](scripts/TRAINING.md).
 
-Every alignment session produces structured training data:
+## Architecture
 
-- **DPO** -- Preference pairs (chosen vs. rejected behavior)
-- **RLHF** -- Reward-labeled behavioral examples
-- **Alpaca** -- Instruction-following format
-- **HuggingFace** -- TRL DPO format, push directly to HF Hub
-- **OpenAI** -- Fine-tuning JSONL format
+The pipeline is a closed loop -- output feeds back as input, compounding with every cycle:
 
-```bash
-holomime export --format huggingface --push --repo myorg/agent-alignment
 ```
-
-Fine-tune via OpenAI API or HuggingFace TRL. See [scripts/TRAINING.md](scripts/TRAINING.md).
+.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
 
@@ -188,30 +262,19 @@ cd agent && python agent.py dev
 
 See [agent/](agent/) for setup instructions.
 
-## Architecture
-
-```
-.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
-```
-
 ## Research
 
 See [Behavioral Alignment for Autonomous AI Agents](paper/behavioral-alignment.md) -- the research paper behind holomime's approach.
 
 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 tier + Pro license details
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.