finchvox 0.0.1__tar.gz

finchvox-0.0.1/.claude/commands/idea.md

@@ -0,0 +1,12 @@
+---
+description: Brainstorm and develop an idea into a fully formed design and spec
+argument-hint: [your idea description]
+---
+
+I've got an idea I want to talk through with you. I'd like you to help me turn it into a fully formed design and spec (and eventually an implementation plan).
+
+Check out the current state of the project in our working directory to understand where we're starting off, then ask me questions, one at a time, to help refine the idea.
+
+Ideally, the questions would be multiple choice, but open-ended questions are OK, too. Don't forget: only one question per message.
+
+Once you believe you understand what we're doing, stop and describe the design to me, in sections of maybe 200-300 words at a time, asking after each section whether it looks right so far.

finchvox-0.0.1/.claude/settings.local.json

@@ -0,0 +1,69 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:chatgpt.com)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "Bash(uv pip install:*)",
+      "Bash(pyenv global:*)",
+      "Bash(python -m pip:*)",
+      "Bash(pytest:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(brew install:*)",
+      "Bash(python test_send_spans.py:*)",
+      "Bash(pkill:*)",
+      "Bash(python -m mumbles.collector:*)",
+      "Bash(cat:*)",
+      "Bash(lsof:*)",
+      "Bash(python -m json.tool:*)",
+      "Bash(while read line)",
+      "Bash(do echo \"$line\")",
+      "Bash(python -c:*)",
+      "Bash(done)",
+      "WebFetch(domain:docs.pipecat.ai)",
+      "Bash(chmod:*)",
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(timeout 10 python:*)",
+      "Bash(curl:*)",
+      "Bash(.venv/bin/python:*)",
+      "Bash(xargs kill -9)",
+      "WebFetch(domain:loguru.readthedocs.io)",
+      "WebFetch(domain:www.coins5.dev)",
+      "Bash(python3:*)",
+      "Bash(timeout 5 python:*)",
+      "Bash(python bot.py:*)",
+      "Bash(uv run python:*)",
+      "Bash(head:*)",
+      "Bash(wc:*)",
+      "Bash(mkdir:*)",
+      "Bash(python -m mumbles.ui_server:*)",
+      "Bash(sort:*)",
+      "mcp__chrome-devtools__list_pages",
+      "mcp__chrome-devtools__navigate_page",
+      "mcp__chrome-devtools__take_snapshot",
+      "mcp__chrome-devtools__list_console_messages",
+      "mcp__chrome-devtools__list_network_requests",
+      "mcp__chrome-devtools__click",
+      "mcp__chrome-devtools__take_screenshot",
+      "mcp__chrome-devtools__evaluate_script",
+      "Bash(xargs:*)",
+      "Bash(grep:*)",
+      "WebFetch(domain:docs.honeycomb.io)",
+      "Bash(kill:*)",
+      "Bash(python -m src.mumbles.ui_server:*)",
+      "Bash(ls:*)",
+      "mcp__chrome-devtools__wait_for",
+      "Bash(pgrep:*)",
+      "Bash(git mv:*)",
+      "Bash(python -m finchvox:*)",
+      "Bash(uv --version:*)",
+      "Bash(uv build:*)",
+      "Bash(.venv/bin/finchvox:*)",
+      "Bash(rm:*)",
+      "WebFetch(domain:localhost)",
+      "Bash(unzip:*)",
+      "WebFetch(domain:hatch.pypa.io)"
+    ]
+  }
+}

finchvox-0.0.1/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Project-specific
+traces/
+PLANNING.md
+TODO.md
+
+# Environment variables
+.env
+.env.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+.worktrees/

finchvox-0.0.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to **Finchvox** will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-1-3
+
+Initial public release.

finchvox-0.0.1/LICENSE

@@ -0,0 +1,24 @@
+Finchvox Source Available License
+
+Copyright (c) 2026 Finchvox
+
+Permission is granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to use, copy,
+modify, and distribute the Software for internal or private use.
+
+You may:
+- Run the Software locally or within your organization
+- Modify the Software for your own use
+- Deploy the Software within your own infrastructure
+- Deploy the Software on behalf of a customer, provided the customer operates
+  the Software themselves
+
+You may NOT:
+- Offer the Software as a hosted service, managed service, or SaaS
+- Provide access to the Software to third parties as a service
+- Resell, rebrand, or commercially exploit the Software as a service
+
+This license does not grant you the right to use the Finchvox name, logo, or
+trademarks.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

finchvox-0.0.1/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: finchvox
+Version: 0.0.1
+Summary: Voice AI observability dev tool for Pipecat
+License: Finchvox Source Available License
+        
+        Copyright (c) 2026 Finchvox
+        
+        Permission is granted, free of charge, to any person obtaining a copy of this
+        software and associated documentation files (the "Software"), to use, copy,
+        modify, and distribute the Software for internal or private use.
+        
+        You may:
+        - Run the Software locally or within your organization
+        - Modify the Software for your own use
+        - Deploy the Software within your own infrastructure
+        - Deploy the Software on behalf of a customer, provided the customer operates
+          the Software themselves
+        
+        You may NOT:
+        - Offer the Software as a hosted service, managed service, or SaaS
+        - Provide access to the Software to third parties as a service
+        - Resell, rebrand, or commercially exploit the Software as a service
+        
+        This license does not grant you the right to use the Finchvox name, logo, or
+        trademarks.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0
+Requires-Dist: opentelemetry-proto>=1.27.0
+Requires-Dist: protobuf<6.0.0,>=4.25.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: ruff>=0.14.10
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# <img src="ui/images/finchvox-logo.png" height=24 /> Finchvox - elevated debuggability for Voice AI apps
+
+Do your eyes bleed like a Vecna victim watching Pipecat logs fly by? Do OpenTelemetry traces look impressive … yet explain nothing? If so, meet Finchvox, a local debuggability tool purpose-built for Voice AI apps. 
+
+Finchvox unifies conversation audio and traces in a single UI, highlighting voice-specific problems like interruptions and high user <-> bot latency. Good luck convincing DataDog to add that!
+
+<a href="./docs/demo.gif"><img src="./docs/screenshot.png" /></a>
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage---finchvox-server)
+- [Setup](#setup)
+  - [✨ AI Install](#-let-your-ai-coding-agent-do-the-work)
+  - [Step 1 – Enable Tracing in Your Pipecat Application](#step-1---enable-tracing-in-your-pipecat-application)
+  - [Step 2 – Enable Audio Recording](#step-2---enable-audio-recording)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+- Python 3.10 or higher
+- A Pipecat Voice AI application
+
+## Installation
+
+```bash
+# uv
+uv add finchvox "pipecat-ai[tracing]"
+
+# Or with pip
+pip install finchvox "pipecat-ai[tracing]"
+```
+
+## Usage - Finchvox server
+
+```bash
+uv run finchvox start
+```
+
+For the list of available options, run:
+
+```bash
+uv run finchvox --help
+```
+
+## Setup
+
+### ✨ Let your AI coding agent do the work!
+
+Try this starter prompt:
+
+```
+Follow the "Setup" instructions at https://github.com/itsderek23/finchvox/blob/main/README.md to setup tracing and audio recording for finchvox. 
+```
+
+### Step 1 - Enable Tracing in Your Pipecat Application
+
+```python
+import os
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from pipecat.utils.tracing.setup import setup_tracing
+```
+
+```python
+# Step 1: Initialize OpenTelemetry with your chosen exporter
+exporter = OTLPSpanExporter(
+    endpoint="http://localhost:4317",
+    insecure=True,
+)
+
+setup_tracing(
+    service_name="my-voice-app",
+    exporter=exporter,
+)
+
+# Step 2: Enable tracing in your PipelineTask
+task = PipelineTask(
+    pipeline,
+    params=PipelineParams(
+        enable_metrics=True
+    ),
+    enable_tracing=True,
+    enable_turn_tracking=True
+)
+```
+
+For the full list of OpenTelemetry setup options, see the [Pipecat OpenTelemetry docs](https://docs.pipecat.ai/server/utilities/opentelemetry#overview).
+
+### Step 2 - Enable Audio Recording
+
+Import the audio recorder and add it to your pipeline:
+
+```python
+from finchvox.audio_recorder import ConversationAudioRecorder
+```
+
+```python
+audio_recorder = ConversationAudioRecorder()
+
+pipeline = Pipeline(
+  [
+      # Other processors, like STT, LLM, TTS, etc.
+      audio_recorder.get_processor(),
+      # context_aggregator.assistant(),
+  ]
+)
+```
+
+Start and stop recording on client connect/disconnect events:
+
+```python
+@transport.event_handler("on_client_connected")
+async def on_client_connected(transport, client):
+    await audio_recorder.start_recording()
+
+    # Other initialization logic...
+
+@transport.event_handler("on_client_disconnected")
+async def on_client_disconnected(transport, client):
+    await audio_recorder.stop_recording()
+
+    # Other cleanup logic...
+```
+
+## Troubleshooting
+
+### Port already in use
+
+If port 4317 is already occupied:
+
+```bash
+# Find process using port
+lsof -i :4317
+
+# Kill the process
+kill -9 <PID>
+```
+
+### No spans being written
+
+1. Check collector is running: Look for "OTLP collector listening on port 4317" log message
+2. Verify client endpoint: Ensure Pipecat is configured to send to `http://localhost:4317`

finchvox-0.0.1/README.md

@@ -0,0 +1,143 @@
+# <img src="ui/images/finchvox-logo.png" height=24 /> Finchvox - elevated debuggability for Voice AI apps
+
+Do your eyes bleed like a Vecna victim watching Pipecat logs fly by? Do OpenTelemetry traces look impressive … yet explain nothing? If so, meet Finchvox, a local debuggability tool purpose-built for Voice AI apps. 
+
+Finchvox unifies conversation audio and traces in a single UI, highlighting voice-specific problems like interruptions and high user <-> bot latency. Good luck convincing DataDog to add that!
+
+<a href="./docs/demo.gif"><img src="./docs/screenshot.png" /></a>
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage---finchvox-server)
+- [Setup](#setup)
+  - [✨ AI Install](#-let-your-ai-coding-agent-do-the-work)
+  - [Step 1 – Enable Tracing in Your Pipecat Application](#step-1---enable-tracing-in-your-pipecat-application)
+  - [Step 2 – Enable Audio Recording](#step-2---enable-audio-recording)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+- Python 3.10 or higher
+- A Pipecat Voice AI application
+
+## Installation
+
+```bash
+# uv
+uv add finchvox "pipecat-ai[tracing]"
+
+# Or with pip
+pip install finchvox "pipecat-ai[tracing]"
+```
+
+## Usage - Finchvox server
+
+```bash
+uv run finchvox start
+```
+
+For the list of available options, run:
+
+```bash
+uv run finchvox --help
+```
+
+## Setup
+
+### ✨ Let your AI coding agent do the work!
+
+Try this starter prompt:
+
+```
+Follow the "Setup" instructions at https://github.com/itsderek23/finchvox/blob/main/README.md to setup tracing and audio recording for finchvox. 
+```
+
+### Step 1 - Enable Tracing in Your Pipecat Application
+
+```python
+import os
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from pipecat.utils.tracing.setup import setup_tracing
+```
+
+```python
+# Step 1: Initialize OpenTelemetry with your chosen exporter
+exporter = OTLPSpanExporter(
+    endpoint="http://localhost:4317",
+    insecure=True,
+)
+
+setup_tracing(
+    service_name="my-voice-app",
+    exporter=exporter,
+)
+
+# Step 2: Enable tracing in your PipelineTask
+task = PipelineTask(
+    pipeline,
+    params=PipelineParams(
+        enable_metrics=True
+    ),
+    enable_tracing=True,
+    enable_turn_tracking=True
+)
+```
+
+For the full list of OpenTelemetry setup options, see the [Pipecat OpenTelemetry docs](https://docs.pipecat.ai/server/utilities/opentelemetry#overview).
+
+### Step 2 - Enable Audio Recording
+
+Import the audio recorder and add it to your pipeline:
+
+```python
+from finchvox.audio_recorder import ConversationAudioRecorder
+```
+
+```python
+audio_recorder = ConversationAudioRecorder()
+
+pipeline = Pipeline(
+  [
+      # Other processors, like STT, LLM, TTS, etc.
+      audio_recorder.get_processor(),
+      # context_aggregator.assistant(),
+  ]
+)
+```
+
+Start and stop recording on client connect/disconnect events:
+
+```python
+@transport.event_handler("on_client_connected")
+async def on_client_connected(transport, client):
+    await audio_recorder.start_recording()
+
+    # Other initialization logic...
+
+@transport.event_handler("on_client_disconnected")
+async def on_client_disconnected(transport, client):
+    await audio_recorder.stop_recording()
+
+    # Other cleanup logic...
+```
+
+## Troubleshooting
+
+### Port already in use
+
+If port 4317 is already occupied:
+
+```bash
+# Find process using port
+lsof -i :4317
+
+# Kill the process
+kill -9 <PID>
+```
+
+### No spans being written
+
+1. Check collector is running: Look for "OTLP collector listening on port 4317" log message
+2. Verify client endpoint: Ensure Pipecat is configured to send to `http://localhost:4317`

finchvox-0.0.1/docs/DEVELOPMENT.md

@@ -0,0 +1,64 @@
+# Development Guide
+
+
+## Testing
+
+### Run Automated Tests
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=finchvox.collector --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_writer.py -v
+```
+
+### Manual Testing with otel-cli
+
+For testing without a Pipecat application:
+
+#### Via `otel-cli`
+
+```bash
+# Install otel-cli (macOS)
+brew install otel-cli
+
+# Send a test span
+otel-cli span --endpoint localhost:4317 --name "test-span" --service "test-service"
+
+# Send multiple spans in same trace (they'll be grouped in one file)
+otel-cli span --endpoint localhost:4317 --name "span-1" --service "test" --traceparent "00-12345678901234567890123456789012-1234567890123456-01"
+otel-cli span --endpoint localhost:4317 --name "span-2" --service "test" --traceparent "00-12345678901234567890123456789012-1234567890123457-01"
+```
+
+#### Via test_send_spans.py
+
+```bash
+# Run the test script to send sample spans
+python tests/test_send_spans.py
+```
+
+
+### Running Tests
+
+```bash
+# Watch mode (requires pytest-watch)
+pip install pytest-watch
+ptw tests/
+```
+
+### Tests failing
+
+```bash
+# Ensure dependencies are installed
+uv pip install --system -e ".[dev]"
+
+# Run tests with verbose output
+pytest tests/ -v
+
+# Check Python version (requires 3.10+)
+python --version
+```

finchvox-0.0.1/docs/RELEASING.md

@@ -0,0 +1,139 @@
+# Releasing FinchVox to PyPI
+
+Step-by-step guide for manually releasing FinchVox to PyPI.
+
+## Prerequisites
+
+- [ ] PyPI account with API token configured
+- [ ] `uv` installed (or `pip`)
+- [ ] Clean git working directory
+
+## Release Workflow
+
+### 1. Update Version
+
+Edit `pyproject.toml`:
+```toml
+version = "0.0.2"  # Increment version
+```
+
+### 2. Update Changelog (Optional)
+
+Add release notes to `CHANGELOG.md`.
+
+### 3. Commit and Tag
+
+```bash
+# Commit changes
+git add -A
+git commit -m "Release v0.0.2"
+
+# Create git tag
+git tag v0.0.2
+
+# Push commits and tags
+git push && git push --tags
+```
+
+## Build Package
+
+### 1. Clean Previous Builds
+
+```bash
+rm -rf dist/
+```
+
+### 2. Build
+
+```bash
+uv build
+```
+
+Expected output: Creates `dist/finchvox-0.0.2-py3-none-any.whl` and `dist/finchvox-0.0.2.tar.gz`
+
+### 3. Verify Build
+
+```bash
+ls -lh dist/
+```
+
+## Test Locally
+
+### 1. Create Test Environment
+
+```bash
+python -m venv test-env
+source test-env/bin/activate
+```
+
+### 2. Install from Wheel
+
+```bash
+pip install dist/finchvox-0.0.2-py3-none-any.whl
+```
+
+### 3. Verify Installation
+
+```bash
+# Test CLI
+finchvox --help
+
+# Test import
+python -c "import finchvox; print('OK')"
+```
+
+### 4. Cleanup
+
+```bash
+deactivate
+rm -rf test-env
+```
+
+## Upload to PyPI
+
+### 1. Install Twine (if needed)
+
+```bash
+pip install twine
+```
+
+### 2. Upload
+
+```bash
+twine upload dist/*
+```
+
+Enter your PyPI API token when prompted.
+
+### 3. Verify Upload
+
+Visit: https://pypi.org/project/finchvox/
+
+### 4. Test Install from PyPI
+
+```bash
+pip install finchvox==0.0.2
+```
+
+## Troubleshooting
+
+**Build fails:**
+- Check `pyproject.toml` syntax
+- Verify `src/finchvox/` structure
+
+**Upload fails:**
+- Verify PyPI API token is correct
+- Check if version already exists on PyPI (can't overwrite)
+- Ensure `~/.pypirc` is configured if not using token prompt
+
+**Import fails after install:**
+- Verify `src/` directory structure matches `packages` in `pyproject.toml`
+- Check `hatchling.build.targets.wheel` configuration
+
+**Missing UI files in package:**
+- Verify `force-include` section in `pyproject.toml`
+- Check that `ui/` directory exists and contains files
+
+**Version not updating:**
+- Clear pip cache: `pip cache purge`
+- Use `--no-cache-dir`: `pip install --no-cache-dir finchvox==0.0.2`