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: 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
Provides-Extra: all
Requires-Dist: anthropic>=0.75.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.75.0; extra == 'anthropic'
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 Point 53 Intercept as a global CLI tool
uv tool install p53-intercept --index https://dist.point53.ai/simple/

# Run from anywhere
intercept record --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 record [OPTIONS]

Options:
  --name TEXT               Session label (becomes part of the session directory name)
  --title TEXT              Title of recorded content (recorded in manifest.json)
  --author TEXT             Creator of recorded audio / author / owner
  --analysis-prompt TEXT    Custom prompt for secondary analysis of the transcript
  --chat                    Open interactive chat after analysis
  --chat-prompt TEXT        Initial question for chat (implies --chat)
  --nofile                  Skip all file output; print only (no session directory)
  --desktop-only            Record only desktop (system) audio
  --mic-only                Record only microphone audio
  --i-understand-the-risks  Acknowledge a remote model will see this run's content
  --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 record --name "meeting-2026-03-08"
intercept record --name "lecture" --title "History 101" --author "Prof. Smith"
intercept record --name "call" --analysis-prompt "Extract all action items and decisions made"
intercept record --name "interview" --chat
intercept record --name "standup" --nofile
intercept record --name "podcast" --desktop-only    # capture only system audio
intercept record --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 p53-intercept --index https://dist.point53.ai/simple/
```

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 `capture.toml` 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 default models:

```bash
ollama pull granite4:1b        # search-suggest (real-time, per-chunk)
ollama pull gemma4:e4b         # summary + analysis
ollama pull qwen3.5:9b         # chat
```

Set `ai.ollama_host` in `capture.toml` 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/ExistentialAudio/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 `capture.toml`:**

```toml
[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/point53/intercept/capture.toml` (Pydantic-validated). On first run a fully-commented default is written and Intercept exits so you can edit before recording.

```toml
[audio]
chunk_duration = 70              # seconds per recording chunk
mic_index = 0                    # macOS only (avfoundation index)
desk_index = -1                  # macOS only; -1 = mic-only

[ai]
provider = "ollama"              # default provider for all stages
ollama_host = "http://localhost:11434"
vosk_model_dir = "vosk-model-small-en-us-0.15"

[ai.search_suggest]              # real-time, per-chunk — small & fast
model = "granite4:1b"
ctx = 8192

[ai.summary]                     # post-recording summary
model = "gemma4:e4b"
ctx = 122880

[ai.analysis]                    # optional second pass (--analysis-prompt)
model = "gemma4:e4b"
ctx = 122880

[ai.chat]                        # optional interactive session (--chat)
model = "qwen3.5:9b"
ctx = 122880

[warnings]
cloud_model = "warn"             # "warn" or "silent"
chat_turn_limit = 10             # re-warn every N --chat turns (0 disables)
```

Each `[ai.<stage>]` can set its own `provider` to mix local and cloud (e.g. local `granite4:1b` for search-suggest, Anthropic for analysis). API keys resolve env-first: `P53_<PROVIDER>_API_KEY` > vendor env (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) > `capture.toml`.

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

---

## Output

Each recording writes a self-describing session directory under
`~/.local/share/point53/intercept/sessions/<session-id>/` (the id is `<timestamp>_<name>`):

- `transcript.md` — full transcript (chunks joined)
- `notes.md` — summary, plus analysis when `--analysis-prompt` is used (the primary artifact when present)
- `metadata.json` — run metadata (title, author, timings)
- `manifest.json` — Suite v1 manifest other tools read (`type: "intercept-session"`, `ingestable_by: ["collector", "nightdesk"]`, plus the enterprise-coordination fields)

No audio is retained — chunks are transcribed in cache and discarded. There is no SQLite database; the Markdown files are the source of truth.

Use `--nofile` to skip the session directory entirely and print to the terminal 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 2.3 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.
