holomime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 holomime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+<p align="center">
+  <img src="https://holomime.dev/logo-icon.svg" alt="holomime" width="80" />
+</p>
+
+<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.
+</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://holomime.dev"><img src="https://img.shields.io/badge/docs-holomime.dev-blue" alt="docs" /></a>
+</p>
+
+---
+
+## The Problem
+
+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.
+
+## The Solution
+
+holomime gives your agents real psychological profiles and a closed-loop pipeline to detect, diagnose, and fix behavioral drift:
+
+```
+define -> diagnose -> refine -> export -> train -> evaluate
+          ^                                        |
+          +--------------- continuous -------------+
+```
+
+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.
+
+## Quick Start
+
+```bash
+npm install -g holomime
+
+# 1. Create a personality profile (Big Five + behavioral dimensions)
+holomime init
+
+# 2. Detect behavioral patterns from real conversations
+holomime diagnose --log chat.json
+
+# 3. Run an automated alignment session
+holomime autopilot
+
+# 4. Export training data and fine-tune
+holomime export --format dpo
+holomime train --provider openai --base-model gpt-4o-mini
+```
+
+## Commands
+
+### Free Tier
+
+| Command | What It Does |
+|---------|-------------|
+| `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 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 publish` | Share your personality to the hub |
+| `holomime activate` | Activate a Pro license key |
+
+### Pro Tier
+
+| Command | What It Does |
+|---------|-------------|
+| `holomime session` | Live dual-LLM alignment session with supervisor mode |
+| `holomime autopilot` | Automated diagnose -> refine -> apply loop |
+| `holomime evolve` | Recursive alignment -- evolve until converged |
+| `holomime benchmark` | 7-scenario behavioral stress test with letter grades |
+| `holomime watch` | Continuous drift detection on a directory |
+| `holomime daemon` | Background drift detection with auto-healing |
+| `holomime fleet` | Monitor multiple agents from a single dashboard |
+| `holomime certify` | Generate verifiable behavioral credentials |
+| `holomime export` | Convert sessions to DPO / RLHF / Alpaca / HuggingFace / OpenAI |
+| `holomime train` | Fine-tune via OpenAI or HuggingFace TRL |
+| `holomime eval` | Before/after behavioral comparison with letter grades |
+| `holomime growth` | Track behavioral improvement over time |
+
+[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
+
+## 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
+
+# Daemon mode -- auto-heal drift without intervention
+holomime daemon --dir ./logs --personality agent.personality.json
+
+# Fleet mode -- monitor multiple agents simultaneously
+holomime fleet --dir ./agents
+```
+
+## Behavioral Credentials
+
+Generate verifiable proof of your agent's alignment state:
+
+```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
+
+Share a base personality across agents with per-agent overrides:
+
+```json
+{
+  "extends": "./base.personality.json",
+  "name": "Support Agent",
+  "communicationStyle": {
+    "register": "warm-professional"
+  }
+}
+```
+
+## Training Pipeline
+
+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
+
+```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).
+
+## MCP Server
+
+Expose the full pipeline as MCP tools for self-healing agents:
+
+```bash
+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.
+
+## Voice Agent
+
+LiveKit-powered voice agent with personality-matched TTS. 14 archetype voices via Cartesia or ElevenLabs.
+
+```bash
+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)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
+
+## License
+
+[MIT](LICENSE)