# ThotStream Lite 🎙️

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.8+](https://img.shields.io/badge/Python-3.8+-brightgreen.svg)](pyproject.toml)
[![Multi-OS: Linux | macOS | Windows](https://img.shields.io/badge/OS-Linux%20%7C%20macOS%20%7C%20Windows-orange.svg)](docs/PLATFORMS.md)
[![Dependencies: Zero](https://img.shields.io/badge/Dependencies-0%20(stdlib)-success.svg)](pyproject.toml)

> **Minimalist, zero-dependency, cross-compatible AI-to-audio speech engine and MCP server.**  
> Stream internal thoughts, tool actions, and responses in real-time with 1 local voice.

---

## ⚡ Core Highlights

- **Zero Mandatory Dependencies**: Runs entirely on Python 3.8+ standard library (`subprocess`, `threading`, `queue`, `shutil`).
- **Verified Cross-Platform**:
  - **macOS**: Built-in `say` CLI and `afplay` CoreAudio playback (0 MB install).
  - **Linux**: Intelligent auto-cascade across `spd-say` (speech-dispatcher), `espeak-ng`, `espeak`, plus ALSA (`aplay`), PulseAudio (`paplay`), and PipeWire (`pw-play`).
  - **Windows**: Built-in `System.Speech` via PowerShell (0 MB install).
  - **Any OS (Neural Upgrade)**: Automatically detects local [Piper TTS](https://github.com/rhasspy/piper) ONNX models for neural voice output.
- **Universal Multi-Adapter**:
  - **MCP Server**: Stdio JSON-RPC 2.0 compliant with Claude Desktop, Antigravity IDE, Cursor, and Continue.
  - **CLI Pipe & Wrapper**: Transparent `stdout` interception (`thotstream-wrap`) for zero token overhead in terminal harnesses (Freebuff, Gemini CLI, Claude Code CLI).
  - **Skill Card**: Standard `SKILL.md` instruction specification for prompt-driven agents.
- **Non-Blocking Threaded Architecture**: Speech synthesis and audio playback occur on an asynchronous worker thread, ensuring LLM text generation is never blocked.

---

## 🚀 Quickstart (60 Seconds)

### 1. Install (Editable / Zero Dependencies)

```bash
cd packages/thotstream-lite
pip install -e .
```

### 2. Verify Your System Audio Driver

```bash
thotstream-lite --status
```

Example outputs:
- **macOS**: `Audio Driver: say`
- **Linux**: `Audio Driver: spd-say` (or `espeak-ng`)
- **Windows**: `Audio Driver: sapi5`
- **With Piper**: `Audio Driver: piper`

---

## 🔌 Integration Modes

### Mode A: Claude Desktop & Antigravity IDE (MCP)

Add to `claude_desktop_config.json` or `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "thotstream": {
      "command": "python",
      "args": ["-m", "thotstream_lite.mcp_server"]
    }
  }
}
```

The agent receives three dedicated audio tools:
- `speak_thought(text)`: Narrate internal reasoning or hypotheses.
- `speak_action(text)`: Announce tool execution intent before running.
- `speak_response(text)`: Speak the final answer aloud.

See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for full setup screenshots.

---

### Mode B: CLI Streaming Interception (Freebuff / Terminal CLIs)

Zero token overhead. The LLM generates text normally with XML tags; ThotStream Lite intercepts and speaks them out-of-band:

```bash
# 1. Pipe streaming stdout from any agent
freebuff --mode agent | thotstream-lite --listen

# 2. Or wrap the CLI command directly
thotstream-lite freebuff --mode agent
```

---

### Mode C: Python SDK

```python
from thotstream_lite import ThotStreamLite

engine = ThotStreamLite()

# Asynchronous, non-blocking queue calls
engine.speak_thought("Formulating system architecture hypothesis.")
engine.speak_action("Querying vector database for matching nodes.")
engine.speak_response("Operation completed successfully.")

# Drain and shutdown
engine.drain()
engine.shutdown()
```

---

## 📂 Documentation & Examples

- 📘 [Architecture Deep-Dive](docs/ARCHITECTURE.md): Threaded queue model, driver dispatch, and fail-open guarantees.
- 🌐 [Platform Compatibility Matrix](docs/PLATFORMS.md): Complete Linux, macOS, and Windows compatibility details.
- 🔌 [Integration Guides](docs/INTEGRATIONS.md): Config guides for Claude Desktop, Antigravity, and Freebuff.
- 💡 [Code Examples](examples/):
  - [01_claude_desktop_mcp.json](examples/01_claude_desktop_mcp.json)
  - [02_python_sdk_basic.py](examples/02_python_sdk_basic.py)
  - [03_streaming_tags_demo.py](examples/03_streaming_tags_demo.py)
  - [04_freebuff_pipe_listener.sh](examples/04_freebuff_pipe_listener.sh)
  - [04_freebuff_pipe_listener.ps1](examples/04_freebuff_pipe_listener.ps1)
  - [05_custom_piper_model.py](examples/05_custom_piper_model.py)

---

## ⚖️ Legal Disclaimer & Responsible AI Use

**THOTSTREAM LITE IS DISTRIBUTED UNDER THE MIT LICENSE ON AN "AS IS" AND "AS AVAILABLE" BASIS, WITHOUT WARRANTIES OR GUARANTEES OF ANY KIND.**

- **User Responsibility**: The user/operator assumes 100% legal and operational responsibility for any text ingested, commands executed, and audio synthesized through this software.
- **Voice Rights & Regulations**: Maintainers do not bundle or license third-party voice models. Users are solely responsible for compliance with voice likeness, copyright, and AI synthesis regulations.

Read the full legal notice in [DISCLAIMER.md](DISCLAIMER.md) and [LICENSE](LICENSE).