holomime 1.0.0 → 1.1.0

package/README.md

@@ -6,7 +6,8 @@
 
 <p align="center">
   Behavioral alignment infrastructure for AI agents.<br />
-  Detect drift. Run therapy sessions. Export training data. Ship agents that stay in character.
+  Detect drift. Run therapy sessions. Export training data. Ship agents that stay in character.<br />
+  <em>Works with OpenTelemetry, Anthropic, OpenAI, ChatGPT, Claude, and any JSONL source.</em>
 </p>
 
 <p align="center">
@@ -17,42 +18,115 @@
 
 ---
 
-## The Problem
+## Quick Start
+
+```bash
+npm install -g holomime
 
-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.
+# Create a personality profile (Big Five + behavioral dimensions)
+holomime init
 
-## The Solution
+# Diagnose drift from any log format
+holomime diagnose --log agent.jsonl
 
-holomime gives your agents real psychological profiles and a closed-loop pipeline to detect, diagnose, and fix behavioral drift:
+# View your agent's personality
+holomime profile
 
+# Generate a human-readable .personality.md
+holomime profile --format md --output .personality.md
 ```
-define -> diagnose -> refine -> export -> train -> evaluate
-          ^                                        |
-          +--------------- continuous -------------+
+
+## Framework Integrations
+
+Holomime analyzes conversations from any LLM framework. Auto-detection works out of the box, or specify a format explicitly.
+
+| 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` |
+
+All adapters are also available programmatically:
+
+```typescript
+import { parseOTelGenAIExport, parseAnthropicAPILog, parseJSONLLog } from "holomime";
 ```
 
-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.
+See the full [integration docs](https://holomime.dev/docs) for export instructions and code examples.
 
-## Quick Start
+## .personality.json + AGENTS.md
 
-```bash
-npm install -g holomime
+[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:
 
-# 1. Create a personality profile (Big Five + behavioral dimensions)
-holomime init
+```
+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
+```
 
-# 2. Detect behavioral patterns from real conversations
-holomime diagnose --log chat.json
+Add a "Behavioral Personality" section to your AGENTS.md:
 
-# 3. Run an automated alignment session
-holomime autopilot
+```markdown
+## Behavioral Personality
 
-# 4. Export training data and fine-tune
-holomime export --format dpo
-holomime train --provider openai --base-model gpt-4o-mini
+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 +135,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 +162,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 +177,40 @@ 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:
-
-- **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
+## Architecture
 
-```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          <- 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
+```
 
 ## MCP Server
 
@@ -188,24 +232,6 @@ 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.