@holdyourvoice/hyv 2.3.1 → 2.4.0

package/README.md

@@ -1,99 +1,131 @@
-# hold your voice
+# Hold Your Voice
 
-make your ai agent sound exactly like you.
+Portable writing-voice toolkit. Works in any AI coding tool or terminal.
+Zero dependencies outside Python 3.10+.
 
-`hyv` is a CLI-first voice gate layer for AI workflows. it scans text for AI writing patterns, builds a voice profile from your own writing, and rewrites drafts to match your personal style.
+- build a voice profile from a writer's own samples
+- scan drafts for AI-writing patterns (220+ rules across 31 regex patterns)
+- rewrite only the flagged lines — no flattening
+- **profile evolves with every session** — patterns you accept get stronger,
+  patterns you ignore fade away
+- auto-sync profiles to Cloudflare R2 for backup (near-zero cost)
 
-## install
+## Install
 
 ```bash
-npm i -g @holdyourvoice/hyv
+npm install -g @holdyourvoice/hyv
 ```
 
-this automatically configures MCP for Claude Desktop if it's installed.
-
-## quick start
+Or clone and run directly:
 
 ```bash
-# sign in (opens browser)
-hyv init
+git clone https://github.com/holdyourvoice/hold-your-voice.git
+cd hold-your-voice
+python3 scripts/hold_voice.py --help
+```
 
-# create your voice profile
-hyv new my-voice
+## Quick start
 
-# scan a draft for AI patterns
-hyv scan draft.md
+### 1. Build a voice profile
 
-# generate a rewrite prompt
-hyv rewrite draft.md
+```bash
+hyv profile \
+  --name "my voice" \
+  --out .hold-your-voice/voice-profile.json \
+  path/to/writing-samples/
 ```
 
-## MCP server
-
-`hyv` includes a built-in MCP server for Claude Desktop, Claude Code, and other MCP hosts.
+### 2. Scan a draft for AI patterns
 
 ```bash
-# start the MCP server (used by Claude Desktop automatically)
-hyv mcp
+hyv scan --meta .hold-your-voice/voice-profile.meta.json draft.md
 ```
 
-### tools
+### 3. Rewrite flagged lines only
 
-| tool | description |
-|------|-------------|
-| `hyv_rewrite` | rewrite text to match your voice profile |
-| `hyv_scan` | scan text for AI writing patterns |
-| `hyv_profiles` | list your voice profiles |
-| `hyv_validate` | validate text against a voice profile |
+```bash
+hyv rewrite-prompt \
+  --profile .hold-your-voice/voice-profile.json \
+  --meta .hold-your-voice/voice-profile.meta.json \
+  draft.md
+```
 
-### prompts
+### 4. After user accepts the revision, evolve the profile
 
-| prompt | description |
-|--------|-------------|
-| `hyv-status` | show account context, profiles, and usage |
+```bash
+hyv profile-evolve \
+  --original draft.md \
+  --accepted accepted.md \
+  --profile .hold-your-voice/voice-profile.json
+```
 
-## commands
+This automatically diffs original vs accepted, extracts which patterns the user
+kept and which they overrode, updates temporal confidence weights, merges new
+stats, and **auto-syncs to Cloudflare R2** if configured.
 
-| command | description |
-|---------|-------------|
-| `hyv init` | authenticate with hold your voice |
-| `hyv status` | show CLI and auth status |
-| `hyv new <name>` | create a voice profile |
-| `hyv profiles` | list voice profiles |
-| `hyv rename <name>` | rename a voice profile |
-| `hyv scan <file>` | scan text for AI patterns |
-| `hyv rewrite <file>` | generate rewrite prompt |
-| `hyv sync` | sync profiles from server |
-| `hyv doctor` | diagnose and fix issues |
-| `hyv mcp` | start MCP server |
-| `hyv export [format]` | export profile for LLMs |
-| `hyv plan` | manage subscription |
-
-## voice profiles
-
-profiles are stored in `~/.hyv/profiles/` as markdown files. create one with:
+## Cloud sync (optional)
+
+Set once:
 
 ```bash
-hyv new my-voice
+export HYV_R2_ACCESS_KEY_ID="your-access-key"
+export HYV_R2_SECRET_ACCESS_KEY="your-secret-key"
+export HYV_R2_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
+export HYV_R2_BUCKET="hyv-voice-profiles"
+pip install boto3
 ```
 
-the onboarding walks you through questions about your writing style, audience, and tone. the profile is saved locally and synced to the server.
+`profile-evolve` auto-syncs after every session (> 23h since last sync).
+R2 has zero egress fees. With ~20KB profiles, annual cost is $0.
+
+## What the learning does
+
+After a few days of use:
+
+- `ai_vocab_density` — confidence 0.76 → reliably catches AI-speak
+- `inflated_verbs` — confidence 0.32 → user removes most of these
+- `em_dash` — confidence 0.08 → user uses em dashes, pattern auto-suppressed
+
+Patterns track `first_seen`, `last_confirmed`, per-date contradictions,
+`status` (active/declining/stale), and `source_samples` for full provenance.
+Untouched patterns decay over 14 days. Contradicted patterns drop to declining
+after 3 overrides, stale after 5.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `hyv profile` | Build voice profile from samples |
+| `hyv scan` | Flag AI-writing patterns in a draft |
+| `hyv rewrite-prompt` | Generate line-level rewrite prompt |
+| `hyv profile-evolve` | **Auto-evolve** — extract signals + update meta + merge stats |
+| `hyv profile-update` | Merge new samples into existing profile (rolling averages) |
+| `hyv profile-status` | Pretty-print learning state with confidence bars |
+| `hyv reinforce` | Diff original vs accepted, emit signal report |
+| `hyv profile-export` | Bundle profile into .hyv file |
+| `hyv profile-import` | Import .hyv bundle |
+| `hyv-sync` | Manually sync to R2 (runs automatically via evolve) |
+
+## Why `.hold-your-voice/`
 
-## content formats
+Profiles live in your project. They're not hidden in `~/.codex/` or `~/.commandcode/` —
+they're in `.hold-your-voice/` at the root of whatever project you're writing for.
+Portable. Version-control-able. No global state.
 
-`hyv scan` and `hyv rewrite` detect 220+ AI writing patterns across categories:
+## Changelog
 
-- **ai-slop** — overused AI words (delve, leverage, tapestry, pivotal, foster)
-- **formulaic** — connector words (firstly, moreover, in conclusion)
-- **voice-drift** — hedging language (arguably, perhaps, some might say)
-- **structure** — AI structural tells (antithesis, signpost claims, lesson setups)
+### 0.2.0 — auto-improving profiles
 
-## environment variables
+- `profile-evolve` replaces manual reinforce + update — one command per session
+- Temporal pattern confidence tracking (active/declining/stale lifecycle)
+- `scan --meta` and `rewrite-prompt --meta` filter out learned-not-applicable patterns
+- Voice.md as standard readable output (`profile-status --write-voice`)
+- Auto-sync to Cloudflare R2 with daily rate-limiting and 1MB safety cap
+- Universal `hyv` / `hyv-sync` CLI — works in any tool, not just Codex
 
-| variable | description |
-|----------|-------------|
-| `HYV_API_URL` | API base URL (default: `https://holdyourvoice.com`) |
+### 0.1.0 — initial
 
-## license
+- `profile`, `scan`, `rewrite-prompt` commands
+- 220+ AI-writing pattern detection (31 regex + 9 structural signals)
+- `reinforce`, `profile-update`, `profile-export/import`
 
-UNLICENSED — [holdyourvoice.com](https://holdyourvoice.com)

package/package.json

@@ -1,54 +1,36 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "2.3.1",
-  "description": "Hold Your Voice \u2014 voice gate layer for AI workflows. make your ai agent sound exactly like you! includes 220+ AI pattern detection engine.",
-  "main": "dist/index.js",
+  "version": "2.4.0",
+  "description": "Hold Your Voice engine — portable voice profiling, AI pattern detection, and self-improving profiles. Works anywhere Python 3.10+ runs.",
   "bin": {
-    "hyv": "dist/index.js",
-    "hyvoice": "dist/index.js"
-  },
-  "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --format=cjs --banner:js='#!/usr/bin/env node'",
-    "dev": "npm run build && node dist/index.js",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.js"
+    "hyv-voice": "scripts/hold_voice.py",
+    "hyv-sync": "scripts/hold_voice_sync.py"
   },
+  "files": [
+    "scripts/hold_voice.py",
+    "scripts/hold_voice_sync.py",
+    "assets/",
+    "skills/"
+  ],
   "keywords": [
     "voice",
     "writing",
     "ai",
     "cli",
     "brand-voice",
+    "hold-your-voice",
+    "ai-detection",
     "content-gate",
     "hyv"
   ],
   "author": "Hold Your Voice",
-  "license": "UNLICENSED",
-  "private": false,
-  "dependencies": {
-    "chalk": "^4.1.2",
-    "commander": "^12.1.0",
-    "open": "^8.4.2",
-    "glob": "^11.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "esbuild": "^0.20.0",
-    "typescript": "^5.3.3"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "dist",
-    "scripts/",
-    "assets/",
-    "skills/",
-    "README.md",
-    "agents/"
-  ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shashank-sn/hold-your-voice-app.git"
+    "url": "git+https://github.com/holdyourvoice/hold-your-voice.git"
+  },
+  "homepage": "https://holdyourvoice.com",
+  "engines": {
+    "node": ">=16"
   }
 }