voiceground 0.1.4__py3-none-any.whl

voiceground-0.1.4.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: voiceground
+Version: 0.1.4
+Summary: Observability framework for Pipecat voice and multimodal conversational AI
+Project-URL: Homepage, https://github.com/poseneror/voiceground
+Project-URL: Documentation, https://github.com/poseneror/voiceground#readme
+Project-URL: Repository, https://github.com/poseneror/voiceground
+Project-URL: Issues, https://github.com/poseneror/voiceground/issues
+Author-email: Or Posener <posener.or@gmail.com>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: ai,conversational-ai,observability,pipecat,real-time,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: pipecat-ai>=0.0.90
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: aiohttp>=3.9; extra == 'examples'
+Requires-Dist: loguru>=0.7; extra == 'examples'
+Requires-Dist: pipecat-ai[elevenlabs,openai,silero]>=0.0.90; extra == 'examples'
+Requires-Dist: pyaudio>=0.2.14; extra == 'examples'
+Requires-Dist: python-dotenv>=1.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# Voiceground
+
+Observability framework for [Pipecat](https://github.com/pipecat-ai/pipecat) voice and multimodal conversational AI.
+
+## Features
+
+- **VoicegroundObserver**: Track conversation events following Pipecat's Observer pattern
+- **HTMLReporter**: Generate interactive HTML reports with timeline visualization
+
+## Installation
+
+```bash
+pip install voiceground
+```
+
+Or with UV:
+
+```bash
+uv add voiceground
+```
+
+## Quick Start
+
+```python
+import uuid
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.task import PipelineTask
+from voiceground import VoicegroundObserver, HTMLReporter
+
+# Create observer with HTML reporter
+conversation_id = str(uuid.uuid4())
+reporter = HTMLReporter(output_dir="./reports")
+observer = VoicegroundObserver(
+    reporters=[reporter],
+    conversation_id=conversation_id
+)
+
+# Create pipeline task with observer
+task = PipelineTask(
+    pipeline=Pipeline([...]),
+    observers=[observer]
+)
+
+# Run your pipeline
+```
+
+## Tested With
+
+Voiceground has been tested with the following Pipecat providers:
+
+### LLM Providers
+- [x] OpenAI (GPT)
+
+### STT Providers
+- [x] ElevenLabs
+
+### TTS Providers
+- [x] ElevenLabs
+
+## Event Categories
+
+Voiceground tracks the following event categories:
+
+| Category | Types | Description |
+|----------|-------|-------------|
+| `user_speak` | `start`, `end` | User speech events |
+| `bot_speak` | `start`, `end` | Bot speech events |
+| `stt` | `start`, `end` | Speech-to-text processing (includes transcription text) |
+| `llm` | `start`, `first_byte`, `end` | LLM response generation (includes generated text) |
+| `tts` | `start`, `first_byte`, `end` | Text-to-speech synthesis |
+| `tool_call` | `start`, `end` | LLM function/tool calling |
+| `system` | `start`, `end` | System events (e.g., context aggregation) |
+
+## Opinionated Metrics
+
+Voiceground tracks 7 opinionated metrics per conversation turn, providing comprehensive insights into voice conversation performance:
+
+1. **Turn Duration**: Total time from the first event to the last event in the turn (milliseconds). Measures the complete duration of a conversation turn.
+
+2. **Response Time**: Time from `user_speak:end` to `bot_speak:start` (or from the first event to `bot_speak:start` if the conversation started with bot speech). This is the end-to-end time the user experiences waiting for a response.
+
+3. **Transcription Overhead**: Time from `user_speak:end` to `stt:end` (milliseconds). Measures the latency of speech-to-text processing.
+
+4. **Voice Synthesis Overhead**: Time from `tts:start` to `bot_speak:start` (milliseconds). Measures the latency of text-to-speech synthesis.
+
+5. **LLM Response Time**: Time from `llm:start` to `llm:first_byte` (milliseconds). Measures the time-to-first-byte for the LLM response, indicating how quickly the model starts generating content.
+
+6. **System Overhead**: Time from `stt:end` to `llm:start` (milliseconds). Measures context aggregation and other system processing that occurs between transcription and LLM invocation. Includes labels/metadata about the system operations.
+
+7. **Tools Overhead**: Sum of all individual `tool_call` durations (each `tool_call:end - tool_call:start`) that occur between `llm:start` and `llm:end` (milliseconds). Measures the total time spent executing function/tool calls during LLM processing.
+
+### Metric Relationships
+
+The metrics are related as follows:
+- **Response Time** ≈ **Transcription Overhead** + **System Overhead** + **LLM Response Time** + **Tools Overhead** + **Voice Synthesis Overhead**
+- **Turn Duration** includes all events in the turn and may be longer than Response Time if there are additional events before or after the main response flow
+
+## Report Features
+
+The generated HTML reports include:
+
+- **Timeline Visualization**: Interactive timeline showing all events and their relationships
+- **Events Table**: Detailed view of all tracked events with timestamps, sources, and data
+- **Turns Table**: Conversation turns with all 7 opinionated performance metrics
+- **Metrics Summary**: Average metrics across the conversation
+- **Event Highlighting**: Hover over events or turns to see related events highlighted
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- **basic_pipeline.py**: Basic voice conversation with STT, LLM, and TTS
+- **tool_calling_pipeline.py**: Example with LLM function calling
+
+To run an example:
+
+```bash
+# Install example dependencies
+uv sync --all-extras
+
+# Set required environment variables
+export OPENAI_API_KEY=your_key
+export ELEVENLABS_API_KEY=your_key
+export VOICE_ID=your_voice_id
+
+# Run the example
+python examples/basic_pipeline.py
+```
+
+**Note**: On macOS, you'll need to install portaudio for audio support:
+```bash
+brew install portaudio
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/poseneror/voiceground.git
+cd voiceground
+
+# Install all dependencies (including dev and examples)
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+
+# Run type checking
+uv run mypy src
+
+# Build the client
+python scripts/develop.py build
+
+# Run example (requires portaudio on macOS: brew install portaudio)
+python scripts/develop.py example
+```
+
+## License
+
+BSD-2-Clause License - see [LICENSE](LICENSE) for details.
+

voiceground-0.1.4.dist-info/RECORD

@@ -0,0 +1,14 @@
+voiceground/__init__.py,sha256=SE1CXqfR1ttdwhF-wEBt4siVBEGHlmm10O0nUFFlTGw,1267
+voiceground/events.py,sha256=8UHcHYy719JDnTG7ZsehMrubokNzAJf1ZKogOwslvwo,2094
+voiceground/metrics.py,sha256=E1KpLzeAwk3Ir1fyr5XneGpk5KLCQFUoypuNudY4MP0,4927
+voiceground/observer.py,sha256=CiWR4bJOY0VpXCkh6OqGk0A6CXMokZzLLFPmGXHKZ7s,21004
+voiceground/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+voiceground/_static/index.html,sha256=EzpBg5Es8JAxYgObdxtEKIanoUsIChJxkxmsdQPiEMQ,412155
+voiceground/reporters/__init__.py,sha256=mRIrsCHV3Fqe9-W_B79mRq-Rvhi5y7x5J2argeGx0Qs,428
+voiceground/reporters/base.py,sha256=ybUOzwLEQ1cjfGphiPKOzCdgpx3CsMZOBtUjZ204Uuo,1144
+voiceground/reporters/html.py,sha256=1wiSGnpqQWPiplVfEnn97ZcSl9ZW-tQDyuEtTTt5OVk,7753
+voiceground/reporters/metrics.py,sha256=Q0HYQ0lWAo6vD5uI88hAc_Gyr_Y_BdAiXdlltbrs-No,17051
+voiceground-0.1.4.dist-info/METADATA,sha256=H33d28yvColfE8hutjAyiImZmVCEkFseI3qELc-ZyRA,6893
+voiceground-0.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+voiceground-0.1.4.dist-info/licenses/LICENSE,sha256=hTRqDroiJlNOmzbVHjoKc6HZ3DySfhjx4bjeZJHgID0,1335
+voiceground-0.1.4.dist-info/RECORD,,

voiceground-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

voiceground-0.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+BSD 2-Clause License
+
+Copyright (c) 2024, Voiceground Contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+