voicerun-cli 0.2.4__tar.gz

voicerun_cli-0.2.4/PKG-INFO

@@ -0,0 +1,598 @@
+Metadata-Version: 2.4
+Name: voicerun-cli
+Version: 0.2.4
+Summary: VoiceRun command-line interface
+Author-email: VoiceRun <anna@primvoices.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: black>=23.3.0
+Requires-Dist: requests>=2.32.4
+Requires-Dist: typer>=0.16.0
+Requires-Dist: websocket-client>=1.6.0
+Requires-Dist: websockets>=11.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: aiohttp>=3.8.6
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pyaudio>=0.2.11
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pygame-ce>=2.5.0
+Requires-Dist: primfunctions>=0.1.13
+Requires-Dist: g711>=1.6.5
+Requires-Dist: pygame>=2.6.1
+Requires-Dist: six>=1.17.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+
+# voicerun-cli
+
+A comprehensive command-line interface for interacting with the VoiceRun API. This CLI tool provides easy access to manage agents, functions, environments, and authentication.
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Install from PyPI](#install-from-pypi)
+- [Install from Source](#install-from-source)
+- [Development Setup](#development-setup)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Agent Management](#agent-management)
+- [Agent Functions](#agent-functions)
+- [Agent Environments](#agent-environments)
+- [Features](#features)
+- [Configuration](#configuration)
+- [API Endpoints](#api-endpoints)
+- [Requirements](#requirements)
+- [Dependencies](#dependencies)
+- [Support](#support)
+- [CLI Output Conventions](#cli-output-conventions)
+- [Developer Notes](#developer-notes)
+- [Phone Number Management](#phone-number-management)
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+
+If you do not have a uv virtual environment, you can create one with:
+```bash
+uv venv --python 3.12
+```
+
+**Note:** We recommend using uv to install the package due to the incredible speed of the package manager. The package can still be installed via pip directly, but it will be slower.
+
+Make sure you run below when you are on mac os
+
+```bash
+pip install pyaudio
+```
+
+## Installation
+
+### Install from PyPI
+
+The easiest way to install voicerun-cli is from PyPI:
+
+```bash
+pip install primcli
+```
+
+### Install from Source
+
+To install from source (for development or latest features):
+
+```bash
+uv pip install .
+```
+
+## Development Setup
+
+### Environment
+
+To switch target platform environment, update:
+`vr_cli/tools/config.py` : `API_BASE_URL` + `FRONTEND_URL`
+
+### Git Hooks
+This project includes git hooks to ensure code quality. To set up the git hooks:
+
+```bash
+python setup_hooks.py
+```
+
+This will create a pre-commit hook that automatically runs black on Python files before each commit.
+
+## Quick Start
+
+1. **Sign in to your account:**
+   ```bash
+   vr signin
+   ```
+
+2. **List your agents:**
+   ```bash
+   vr list
+   ```
+
+## Authentication
+
+### Sign In
+```bash
+vr signin
+```
+This command offers two authentication methods:
+- **Direct authentication**: Enter email and password directly in the terminal
+- **Web authentication**: Opens a browser to login through the VoiceRun website (recommended for enhanced security via Stytch)
+
+When using web authentication, the CLI will open a login URL in your browser and poll for completion. Upon successful login, your session is securely stored locally.
+
+### Sign Out
+```bash
+vr signout
+```
+Clears your authentication session and removes stored credentials.
+
+## Agent Management
+
+### List Agents
+```bash
+vr list [--all]
+```
+- `--all`: Show detailed information including creation dates and IDs
+
+### Agent Information
+```bash
+vr info <agent_name_or_id>
+```
+
+### Create Agent
+```bash
+vr create
+```
+Interactive command that prompts for:
+- Agent name (required)
+- Description (required)
+- Default voice (by name or ID, required)
+
+### Update Agent
+```bash
+vr update <agent_name_or_id>
+```
+Interactive command to modify agent properties.
+
+### Delete Agent
+```bash
+vr delete <agent_name_or_id>
+```
+Deletes an agent after confirmation.
+
+## Agent Functions
+
+### List Functions
+```bash
+vr func list <agent_name_or_id>
+```
+
+### Function Information
+```bash
+vr func info <agent_name_or_id> <function_name_or_id>
+```
+
+### Create Function
+```bash
+vr func create <agent_name_or_id> --dir <directory_path>
+```
+Creates a new function from a directory. Supports multiple programming languages:
+- Python (.py)
+- JavaScript (.js)
+- e.g. to create a new function with a display name: `vr func create <agent_name_or_id> --dir <directory_path> --display-name "v2"`
+
+### Update Function
+```bash
+vr func update <agent_name_or_id> <function_name_or_id> [--dir <directory_path>]
+```
+- `--dir`: Path to the updated code directory
+- Without `--dir`: Creates a temporary file for editing
+- e.g. from URL: https://app.primvoices.com/agents/<agent_name_or_id>/function?f=<function_name_or_id>
+
+### Delete Function
+```bash
+vr func delete <agent_name_or_id> <function_name_or_id>
+```
+
+### Deploy Function
+```bash
+vr func deploy <agent_name_or_id> <function_name_or_id>
+```
+
+### Debug Functions
+
+**NEW**: Debug functions interactively using the command-line debugger, with support for phone and advanced audio features:
+
+```bash
+vr func debug <agent_name_or_id> <function_name_or_id> [--env <environment_name_or_id>] [--phone]
+```
+- `--phone`: Start debugging via phone call (uses environment or user phone number)
+
+#### Debugger Features
+
+The CLI debugger provides the same functionality as the web UI debugger, plus:
+
+- **Real-time WebSocket communication** with the agent
+- **Send text messages** to the agent
+- **View agent responses** including text-to-speech events
+- **Monitor debug events** and logs
+- **Track conversation turns** and performance
+- **Start/stop microphone recording** (`listen`/`stop` commands)
+- **Connect/disconnect phone number** (`phone` command)
+- **Advanced audio system**: Echo cancellation, interruption detection, and dynamic echo alignment for seamless voice interaction
+
+#### Debugger Commands
+
+Once in the debugger, you can use these commands:
+
+- `send <text>` - Send a text message to the agent
+- `listen` - Start microphone recording (voice input)
+- `stop` - Stop microphone recording
+- `phone` - Connect or disconnect a phone number for call-based debugging
+- `status` - Show connection status and debug summary
+- `messages` - Show all debug messages
+- `clear` - Clear debug messages
+- `help` - Show available commands
+- `quit` - Exit debugger
+
+#### Prerequisites
+
+Before using the debugger, make sure:
+
+1. **VoiceRun Agent Server** is running on `localhost:7860`
+   ```bash
+   # In the primvoices-agents directory
+   python src/main.py
+   ```
+
+2. **WebSocket dependency** is installed:
+   ```bash
+   pip install websockets
+   ```
+
+3. **Agent and function** exist and are properly configured
+
+#### Example Debug Session
+
+```bash
+$ vr func debug my-agent my-function
+
+Starting debugger for agent: my-agent, function: my-function
+
+Debug Configuration:
+Agent: My Agent (agent-123)
+Function: My Function (func-456)
+Environment: Development (env-789)
+Language: python
+
+Starting interactive debugger...
+Connecting to WebSocket server at ws://localhost:7860/ws
+✓ Connected to ws://localhost:7860/ws
+
+VoiceRun CLI Debugger
+Type 'help' for available commands, 'quit' to exit
+
+debug> send Hello, how are you?
+→ Sent: Hello, how are you?
+🤖 Agent (nova): Hello! I'm doing well, thank you for asking. How can I help you today?
+
+debug> status
+
+Debug Summary:
+Total messages: 3
+Current turn: 1
+Connection: Connected
+Listening: No
+
+Recent Messages:
+  text (input)
+  text_to_speech (output)
+  turn_end (system)
+
+debug> quit
+Disconnected
+```
+
+## Agent Environments
+
+### List Environments
+```bash
+vr env list <agent_name_or_id>
+```
+
+### Environment Information
+```bash
+vr env info <agent_name_or_id> <environment_name_or_id>
+```
+
+### Create Environment
+```bash
+vr env create <agent_name_or_id>
+```
+Interactive command that prompts for:
+- Environment name (required)
+- Phone number (optional)
+- Recording settings
+- Redaction settings
+- STT language (English or Multi-lingual)
+- STT keywords (optional)
+- Function deployment (optional)
+- Environment variables (names required, values optional)
+
+If you choose to add a phone number, the CLI will guide you through associating a number with the environment. This enables phone-based debugging and agent interaction.
+
+### Update Environment
+```bash
+vr env update <agent_name_or_id> <environment_name_or_id>
+```
+Interactive command to modify environment properties and variables.
+
+### Delete Environment
+```bash
+vr env delete <agent_name_or_id> <environment_name_or_id>
+```
+
+### Deploy to Environment
+```bash
+vr env deploy <agent_name_or_id> <environment_name_or_id>
+```
+
+### Debug Functions
+
+**NEW**: Debug functions interactively using the command-line debugger:
+
+```bash
+vr env debug <agent_name_or_id> <environment_name_or_id>
+```
+
+#### Debugger Features
+
+The CLI debugger provides the same functionality as the web UI debugger:
+
+- **WebSocket Communication**: Real-time bidirectional communication with VoiceRun agents
+- **Audio Processing**: Capture microphone input and play agent responses
+- **Text Messaging**: Send text messages to agents
+- **Debug Monitoring**: Real-time display of debug messages and conversation turns
+- **Audio Statistics**: Monitor audio levels and speech detection
+- **Session Management**: Automatic session ID generation and management
+- **Configuration**: Environment-based configuration with custom parameters
+- **Phone Integration**: Connect to a phone number for call-based debugging and agent interaction
+
+#### Debugger Commands
+
+Once in the debugger, you can use these commands:
+
+- `help` - Show help information
+- `status` - Show connection status
+- `config` - Show running agent, environment, and function
+- `messages` - Show recent debug messages
+- `debug <ID>` - Show detailed debugging info for a specific message
+- `clear` - Clear message history
+- `quit`, `exit`, `q`, or `x` - Exit debugger
+- `send <text>` - Send a text message to an agent (also runs when typing any text that's not a command)
+- `listen` - Start microphone recording
+- `stop` - Stop microphone recording
+- `phone` - Connect or disconnect a phone number
+
+#### Example Debug Session
+
+```bash
+$ vr env debug my-agent my-environment
+
+Debugging function 'my-agent' in environment 'my-environment'
+VoiceRun Debugger
+Type 'help' for available commands, or 'quit' to exit
+⠼ Connected!
+
+ start (turn 0)
+
+Agent: Hello from your agent
+
+ turn_end (turn 0)
+
+debugger> Hello!
+Sent: Hello!
+
+You: Hello!
+
+Agent: Agent heard hello!
+
+ turn_end (turn 1)
+
+debugger> config
+Agent: my-agent
+Agent ID: agent-123
+Environment: my-environment
+Environment ID: environment-456
+Function: my-function
+Function ID: function-789
+
+debugger> quit
+Goodbye!
+```
+
+## Features
+
+### Rich Terminal Output
+- Color-coded tables and information displays
+- Formatted dates and timestamps
+- Clear status indicators (Yes/No, On/Off)
+
+### Secure Authentication
+- Session cookie management
+- Secure credential storage
+- Direct or web-based authentication using Stytch
+
+### File Management
+- Automatic language detection from file extensions
+- Temporary file creation for code editing
+- Support for multiple programming languages
+
+### Interactive Prompts
+- Confirmation dialogs for destructive operations
+- Default value suggestions
+- Clear error messages and help text
+- **All prompts require non-empty input by default unless otherwise specified.**
+- To allow empty input, the `validation` parameter can be set to `None` in the prompt utility.
+- All prompts and confirmations use single quotes around referenced names/IDs and enforce clear, imperative language.
+
+### Advanced Audio System
+- Real-time microphone capture and playback with PyAudio and pygame
+- **Echo cancellation**: Removes agent output from mic input to prevent feedback
+- **Interruption detection**: Detects when a human interrupts agent speech and stops playback for immediate response
+- **Dynamic echo alignment**: Automatically calibrates echo delay for robust interruption detection
+- **Hysteresis**: Prevents false stops during brief pauses in conversation
+- All audio features are available in the debugger and during phone-based sessions
+
+### Phone Number Management
+
+#### User Phone Number
+
+Manage your user phone number for call-based agent interaction:
+
+```bash
+vr phone
+```
+- View your current phone number
+- Add a new phone number if none is set
+
+#### Environment Phone Number
+
+When creating or updating an environment, you can associate a phone number for inbound/outbound calls. This enables phone-based debugging and agent interaction.
+
+- Add a phone number during `vr env create` or `vr env update`
+- Use the `phone` command in the debugger to connect/disconnect calls
+
+## Configuration
+
+The CLI automatically manages configuration in your home directory:
+- Authentication cookies: `~/.voicerun_cookie`
+- Session management and API endpoints
+
+## API Endpoints
+
+- **API Base URL**: `https://api.primvoices.com`
+- **Frontend URL**: `https://app.primvoices.com`
+
+## Requirements
+
+- Python 3.7 or higher
+- Internet connection for API access
+
+## Dependencies
+
+- `typer`: Command-line interface framework
+- `requests`: HTTP client for API communication
+- `rich`: Rich terminal output formatting
+
+## CLI Output Conventions
+
+The VoiceRun CLI uses consistent output conventions for all commands to ensure clarity and a professional user experience. These conventions are enforced throughout the codebase:
+
+- **Success messages:**
+  - Printed in **bold green** using Rich.
+  - Use `print_success()` utility.
+  - Example: `[bold green]Agent created successfully![/bold green]`
+
+- **Warning messages:**
+  - Printed in **bold yellow** with a `Warning:` prefix using Rich.
+  - Use `print_warning()` utility.
+  - Example: `[bold yellow]Warning: No Set-Cookie header received[/bold yellow]`
+
+- **Error messages:**
+  - Printed in **bold red** with an `Error:` prefix using Rich.
+  - Use `print_error()` utility.
+  - Example: `[bold red]Error: Unauthorized. Please sign in with vr signin.[/bold red]`
+
+- **IDs:**
+  - Always styled as **blue** in output: `[blue]{id}[/blue]`
+  - Applies to all user-facing output, including tables and error messages.
+
+- **File paths and URLs:**
+  - Always styled as **cyan** in output: `[cyan]{path_or_url}[/cyan]`
+  - Applies to all user-facing output, including error/warning messages and informational output.
+
+- **Tables and formatted output:**
+  - The CLI uses the [Rich](https://rich.readthedocs.io/) library for all tables and styled output.
+  - Table headers use the color defined in `TITLE_COLOR` in `utils/config.py`.
+
+- **Prompts and Confirmations:**
+  - All interactive prompts use the `prompt` and `confirm` utilities from `vr_cli/utils/utils.py`.
+  - Prompts require non-empty input by default. To allow empty input, pass `validation=None`.
+  - Prompts and confirmations use single quotes for referenced names/IDs and clear, imperative language.
+
+**Note:**
+- All output and prompt utilities are defined in `vr_cli/utils/utils.py`.
+- Please follow these conventions for any new commands or output added to the CLI.
+
+## Developer Notes
+
+### Adding New Commands
+- Use Typer's `@app.command` decorator for new commands.
+- Use the `prompt` and `confirm` utilities for all user input. By default, prompts require non-empty input. For optional input, set `validation=None`.
+- Always use single quotes around referenced names/IDs in prompts and confirmations.
+- Use the output utilities (`print_success`, `print_error`, `print_warning`, `print_info`) for all user-facing output.
+- Style IDs as blue and file paths as cyan using Rich markup.
+- Table headers should use the color defined in `TITLE_COLOR` in `utils/config.py`.
+
+### Testing Agents
+
+**NEW**: Test your agents interactively using text input:
+
+```bash
+vr env run <agent_name_or_id> <environment_name_or_id>
+```
+
+This command starts an interactive session where you can:
+- Send text messages to your agent
+- See real-time responses from your agent function
+- View conversation history
+- Use built-in commands like `help`, `status`, `clear`, `history`
+
+#### Requirements for Real Agent Testing
+
+To test with real agent responses (not simulated), you need:
+
+1. **API Key**: Set the `PRIMVOICES_API_KEY` environment variable
+2. **PrimVoices Agents**: The `primvoices-agents` project must be available in the same directory
+3. **Deployed Function**: A function must be deployed to the environment you're testing
+
+#### Example Session
+
+```
+$ vr env run my-agent development
+
+Starting interactive session for agent 'my-agent' in environment 'development'
+Type your messages and press Enter. Type 'quit' or 'exit' to end the session.
+Type 'help' for available commands.
+
+Agent function loaded successfully!
+You can now interact with your agent using text messages.
+
+You: Hello, how are you?
+Agent: Hello! I'm doing well, thank you for asking. How can I help you today?
+
+You: What's the weather like?
+Agent: I don't have access to real-time weather information, but I can help you with other questions or tasks. What would you like to know?
+
+You: help
+┌─ Help ──────────────────────────────────────────────────────────────────────┐
+│ Available commands:                                                         │
+│ - help: Show this help message                                             │
+│ - quit/exit: End the session                                               │
+│ - clear: Clear the conversation history                                    │
+│ - history: Show conversation history                                       │
+│ - status: Show current session status                                      │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+You: quit
+Ending session...
+Session ended. Total messages: 4
+```