{"repo": "bigbadman-lab/clawspeak", "files": {"README.md": {"e3c44f07a54c39be3413519e7929a8fb539ab4ad": {"t": 1785674533.051073, "n": 4717, "h": "88b7ee5ce066f5ad", "c": "<p align=\"center\">\n  <img src=\"assets/clawspeak-banner.png\" alt=\"ClawSpeak banner\" width=\"100%\" />\n</p>\n\n# ClawSpeak 🦞\n\n![CI](https://github.com/bigbadman-lab/clawspeak/actions/workflows/ci.yml/badge.svg)\n![License](https://img.shields.io/github/license/bigbadman-lab/clawspeak)\n![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)\n\n**Tone-only voice overlays for agent outputs. Draft → ClawSpeak → final.**\n\n## Introduction\n\nClawSpeak rewrites text into a selected local voice or persona. Meaning, safety, and capabilities stay unchanged—only tone and style change. It works with OpenAI, Grok (xAI), and any OpenAI-compatible provider. Ship it as an NPM package or as an OpenClaw plugin.\n\n## 20-Second Demo\n\n```ts\nimport { createVoicedTextAgent, openAICompatAdapter } from \"clawspeak\";\n\nconst adapter = openAICompatAdapter({\n  apiKey: process.env.OPENAI_API_KEY,\n  model: \"gpt-4.1-mini\"\n});\n\nconst baseAgent = async (input) => {\n  return \"Explain what staking is in simple terms.\";\n};\n\nconst glasgowAgent = createVoicedTextAgent({\n  agent: baseAgent,\n  voiceId: \"glaswegian\",\n  model: adapter\n});\n\nconsole.log(await glasgowAgent(\"\"));\n```\n\n## What It Does\n\n- **Deterministic tone rewrite** — Same input and voice yield consistent style.\n- **Preserves meaning** — No new facts, no dropped content.\n- **Slang cap enforcement** — Per-voice limits; metadata reports overuse.\n- **Anti-caricature guardrails** — Flags heavy phonetic spelling and banned phrases.\n- **Clarity heuristics** — Optional warnings for long sentences or complex wording.\n- **Provider-agnostic** — OpenAI, Grok (xAI), and any OpenAI-compatible API.\n- **Multiple regional and stylistic voices** — Including blunt and ultra-polite modes.\n\n## Voices\n\n- east_end_londoner\n- scouse\n- glaswegian\n- geordie\n- dublin\n- new_yorker\n- texan\n- southern_us\n- californian\n- overly_polite\n- very_rude\n- raig_bait_chef\n\nVoices are designed to remain broadly understandable, avoid stereotypes, and preserve meaning exactly.\n\nUse `listVoices()` for labels and descriptions.\n\n## Install\n\n```bash\nnpm i clawspeak\n```\n\n## Usage (OpenAI)\n\n```ts\nimport { listVoices, applyVoice, openAICompatAdapter } from \"clawspeak\";\n\nconst adapter = openAICompatAdapter({\n  apiKey: process.env.OPENAI_API_KEY,\n  model: \"gpt-4.1-mini\",\n  baseUrl: \"https://api.openai.com/v1\"\n});\n\nconst res = await applyVoice({\n  text: \"Explain this in 3 bullet points.\",\n  voiceId: \"glaswegian\",\n  model: adapter,\n  options: { strength: 0.55, returnMetadata: true }\n});\n\nconsole.log(res.text);\nconsole.log(res.meta);\n```\n\n## Usage (Grok / xAI)\n\nSame API; swap base URL and model:\n\n```ts\nconst adapter = openAICompatAdapter({\n  apiKey: process.env.XAI_API_KEY,\n  model: \"grok-2-latest\",\n  baseUrl: \"https://api.x.ai/v1\"\n});\n\nconst res = await applyVoice({ text: \"...\", voiceId: \"dublin\", model: adapter });\nconsole.log(res.text);\n```\n\n## Local voice testing (no OpenClaw required)\n\nClawSpeak is a tone-only post-processing layer.\nIt requires a `ModelAdapter` because rewrites are performed by an LLM.\n\nYou can test voices locally without OpenClaw using the OpenAI-compatible adapter.\n\n### 1. Install and build\n\n```bash\npnpm install\npnpm --filter clawspeak build\n```\n\n### 2. Set your API key\n\n```bash\nexport LLM_API_KEY=\"sk-...\"\n```\n\nOptional environment variables:\n\n```bash\nexport LLM_MODEL=\"gpt-4o-mini\"\nexport LLM_BASE_URL=\"https://api.openai.com/v1\"\n```\n\n### 3. Run the local test harness\n\n```bash\nnode scripts/test-raig.mjs\n```\n\nThis will:\n\n- Print available voices\n- Rewrite sample text using raig_bait_chef\n- Output guardrail metadata\n\n### Direct usage example\n\n```ts\nimport {\n  applyVoice,\n  openAICompatAdapter\n} from \"clawspeak\";\n\nconst model = openAICompatAdapter({\n  apiKey: process.env.LLM_API_KEY!,\n  model: \"gpt-4o-mini\"\n});\n\nconst result = await applyVoice({\n  text: \"Explain what this library does.\",\n  voiceId: \"raig_bait_chef\",\n  model,\n  options: { strength: 0.8 }\n});\n\nconsole.log(result.text);\n```\n\nClawSpeak modifies tone only.\nIt does not alter meaning, safety boundaries, or factual content.\n\n## OpenClaw Plugin\n\nThe **@clawspeak/openclaw** plugin exposes ClawSpeak as tools for OpenClaw-compatible agents:\n\n- **clawspeak_list** — List available voices.\n- **clawspeak_apply** — Rewrite text into a voice.\n- **clawspeak_preview** — Preview a voice on sample text.\n\nThe plugin ships with a **SKILL.md** so agents know when and how to use the overlay. See `packages/openclaw` and [packages/openclaw/README.md](packages/openclaw/README.md).\n\n## Repo Structure\n\n```\npackages/clawspeak   — Core library (voices, adapter, guardrails, createVoicedAgent)\npackages/openclaw    — OpenClaw plugin + Skill\nexamples/node-basic  — Minimal Node example with .env\n```\n\n## License\n\nMIT\n"}}}}