Metadata-Version: 2.4
Name: p53-intercept
Version: 0.1.0
Summary: Point 53 Intercept — ad-hoc evaluation of verbal and visual data with offline transcription and local LLM analysis.
Author: Point 53 LLC
License-Expression: MPL-2.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Keywords: audio,local-llm,ollama,point53,transcription,vosk
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.52.0
Requires-Dist: click>=8.3.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: ollama>=0.6.1
Requires-Dist: platformdirs>=4.3.6
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: pydantic>=2.10.3
Requires-Dist: vosk>=0.3.45
Description-Content-Type: text/markdown

# Point 53 Intercept

Ad-hoc evaluation of verbal and visual data — continuous audio recording with offline transcription and local LLM analysis. Part of the [Point 53](../README.md) suite.

Records microphone and desktop audio simultaneously, transcribes in real-time using Vosk (fully offline), and processes the transcript through local LLMs via Ollama for summarization, analysis, and interactive chat.

Licensed under the Mozilla Public License, v. 2.0 — see `LICENSE`.

> *"Point 53" and "Point 53 Intercept" are trademarks of Point 53 LLC. MPL-2.0 does not grant rights to use these marks. The bare `intercept` CLI name is a functional identifier, not a trademark claim on that word alone.*

---

## Quick Start

```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh          # Linux / macOS
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Install Intercept as a global CLI tool (from a local clone for now)
uv tool install .

# Run from anywhere
intercept --name "meeting-2026-03-08" --title "Standup" --author "Me"
```

To upgrade: `uv tool upgrade p53-intercept`
To uninstall: `uv tool uninstall p53-intercept`

---

## Usage

```
intercept [OPTIONS]

Options:
  --name TEXT             Prefix name of output TXT files
  --title TEXT            Title of recorded content
  --author TEXT           Creator of recorded audio / author / owner
  --analysis_prompt TEXT  Specify a custom prompt for secondary analysis
  --chat                  Engage a chat session after analysis
  --nofile                Skip file output, save to DB only
  --desktop-only          Record only desktop (system) audio
  --mic-only              Record only microphone audio
  --help                  Show this message and exit.
```

`--desktop-only` and `--mic-only` are mutually exclusive. Running without either records both sources mixed together (default).

**During recording:** Press `q` to stop and proceed to AI post-processing or trigger an ad-hoc summary with `s`. If using `--chat`, press `Ctrl+C` to exit the chat session when finished.

```bash
intercept --name "meeting-2026-03-08"
intercept --name "lecture" --title "History 101" --author "Prof. Smith"
intercept --name "call" --analysis_prompt "Extract all action items and decisions made"
intercept --name "interview" --chat
intercept --name "standup" --nofile
intercept --name "podcast" --desktop-only    # capture only system audio
intercept --name "voicenote" --mic-only      # capture only the microphone
```

---

## Setup

### 1. Install uv

[uv](https://docs.astral.sh/uv/) manages Python versions, dependencies, and virtual environments automatically.

```bash
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. Install Intercept

**Option A — Global CLI tool (recommended for end users):**

```bash
uv tool install .      # from a clone of the repo
```

This installs `intercept` into an isolated environment and adds it to your PATH. No manual venv management needed.

**Option B — Local development clone:**

```bash
uv sync
uv run intercept --help
```

### 3. Vosk model

Vosk models are **not bundled** with Intercept. Download one from https://alphacephei.com/vosk/models and extract it into the project directory (or any path you configure).

```bash
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip
```

Set `ai.vosk-model-dir` in `config.json` to match the extracted directory name.

#### Model licensing — read before choosing

The Vosk *library* is Apache-2.0, but individual *models* at alphacephei.com carry **different licenses per model**. You are responsible for verifying the license of any model you download, especially for commercial or redistribution use.

- **Recommended for general English use:** `vosk-model-small-en-us-0.15` — Apache-2.0, ~40 MB. Compatible with Intercept's MPL-2.0 license for any use case.
- **Large / language-specific models:** verify the license on the model's row on the Vosk models page before use. Some are Apache-2.0; others are custom terms or non-commercial. If the page does not state a license for a model, treat it as "all rights reserved" until clarified.

Intercept itself ships no model files; nothing in this repo is constrained by Vosk model terms.

### 4. Ollama

Install Ollama from https://ollama.com and pull the models referenced in `config.json`.

```bash
ollama pull <model-name>
```

Set `ai.ollama-host` in `config.json` to your Ollama server address (default: `http://localhost:11434`).

Ollama models each carry their own licenses from their respective publishers; confirm before commercial use.

---

## Platform-Specific Setup

### GNU/Linux (PulseAudio / PipeWire)

**Dependencies:**

```bash
# Debian / Ubuntu
sudo apt install ffmpeg pulseaudio-utils

# Fedora
sudo dnf install ffmpeg pulseaudio-utils

# Arch
sudo pacman -S ffmpeg libpulse
```

Desktop audio capture works out of the box via PulseAudio's monitor source. `pactl` is used at startup to detect it automatically — no additional configuration needed.

**Verify audio:**
```bash
pactl get-default-sink
```

---

### macOS

**Dependencies:**

```bash
brew install ffmpeg
```

**Desktop audio capture (optional):**

macOS has no native loopback. To capture system audio alongside the microphone, install [BlackHole](https://github.com/ExistingSound/BlackHole):

```bash
brew install blackhole-2ch
```

After installing BlackHole, create an **Aggregate Device** in `Audio MIDI Setup.app` that combines your microphone and BlackHole, then set that aggregate device as your system input. Route system audio output through BlackHole as well.

**Find your avfoundation device indices:**

```bash
ffmpeg -f avfoundation -list_devices true -i "" 2>&1 | grep -A 20 "AVFoundation audio"
```

Note the index numbers next to your microphone and BlackHole device.

**Update `config.json`:**

```json
"audio": {
    "mic_index": 0,
    "desk_index": 1
}
```

- `mic_index`: avfoundation index of your microphone (or aggregate device)
- `desk_index`: avfoundation index of your BlackHole device
- Set `desk_index` to `-1` to disable desktop audio capture and record mic only (equivalent to always passing `--mic-only`)

**Microphone permission:**

macOS will prompt for microphone access on first run. Approve it in System Settings → Privacy & Security → Microphone.

---

## Configuration

All runtime settings live in `config.json`:

```json
{
    "audio": {
        "mic_index": 0,
        "desk_index": 0,
        "chunk-duration": 70
    },
    "ai": {
        "ollama-host": "http://localhost:11434",
        "vosk-model-dir": "vosk-model-small-en-us-0.15",
        "search-suggest-model": "granite4:1b",
        "search-suggest-ctx": 3072,
        "summary-model": "cogito:70b",
        "summary-ctx": 122880,
        "analysis-model": "cogito:70b",
        "analysis-ctx": 122880,
        "chat-model": "nemotron-3-nano:30b",
        "chat-ctx": 122880
    }
}
```

| Key | Description |
|---|---|
| `audio.chunk-duration` | Seconds per recording chunk |
| `audio.mic_index` | Microphone device index (macOS only) |
| `audio.desk_index` | Desktop audio device index (macOS only; `-1` to disable) |
| `ai.ollama-host` | Ollama server address |
| `ai.vosk-model-dir` | Path to extracted Vosk model directory |
| `ai.*-model` | Ollama model name for each stage |
| `ai.*-ctx` | Context window size for each stage |

**Stages:** `search-suggest` (per-chunk real-time), `summary` (post-recording), `analysis` (optional second pass), `chat` (optional interactive session).

---

## Output

Each run produces:

- `{name}_transcript.txt` — full transcript with summary prepended
- `{name}_analysis.txt` — analysis output (if `--analysis_prompt` was used)
- `storage.db` — SQLite history of all runs (`History` table)

Use `--nofile` to skip the text files and write to the database only.

---

## License and Attribution

- **Intercept source code:** Mozilla Public License, v. 2.0 — see `LICENSE`.
- **Third-party runtime dependencies and external tools:** see `NOTICE` for a summary and `THIRD_PARTY_LICENSES.md` for full attribution.
- **Vosk models and Ollama models:** not distributed with Intercept; each carries its own license from its respective publisher.
- **Trademarks:** "Point 53" and "Point 53 Intercept" are trademarks of Point 53 LLC. MPL-2.0 section 10.4 excludes trademark rights from the copyright/patent grant — nothing in the license authorizes use of these marks. The CLI command `intercept` is a functional identifier, not a trademark claim on the generic English word.
