Add contributing guide and developement setup

.changeset/weak-peaches-clap.md

@@ -0,0 +1,5 @@
+---
+"livekit-agents": patch
+---
+
+Add contributing guide and developement setup

.gitignore

@@ -130,6 +130,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+livekitenv/
 
 # Spyder project settings
 .spyderproject

CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to LiveKit
+
+LiveKit is an open-source platform for building real-time audio/video experiences. The Agents framework is under active development in a rapidly evolving field. We welcome and appreciate contributions of any kind, be it feedback, bugfixes, features, new plugins and tools, or better documentation.
+
+## 🤝 What We're Looking For
+
+- Bug fixes and improvements to existing features
+- New features and plugins
+- Documentation improvements and examples
+- Test coverage improvements
+- Performance optimizations
+
+## 👩‍💻 How to contribute
+
+Please follow the [fork and pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow:
+
+1. Fork the repository
+2. Create a new branch for your feature: `git checkout -b feature-name`
+3. Add your feature or improvement
+4. Commit your changes: `git commit -m 'Add new feature'`
+5. Push to your fork: `git push origin feature-name`
+6. Open a pull request with a detailed description of changes
+
+## 🔧 Development setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-username/livekit.git
+   cd livekit
+   ```
+
+2. Create a virtual environment:
+   - For Unix: `./scripts/create_venv.sh`
+   - For Windows: `.\scripts\create_venv.bat`
+   - This setup will:
+     - Create a `livekitenv` virtual environment
+     - Install required packages
+     - Install the `livekit/agents` package in editable mode
+
+3. Activate the virtual environment:
+   - Unix: `source livekitenv/bin/activate`
+   - Windows: `livekitenv\Scripts\activate`
+
+
+## ✅ Testing
+
+1. Run the test suite:
+   ```bash
+   pytest
+   ```
+
+## 🎨 Code Style and Validation
+
+Before submitting a pull request, ensure your code meets our quality standards:
+
+1. Run the formatting script:
+   - Unix: `./scripts/format.sh`
+   - Windows: `.\scripts\format.bat`
+
+These scripts will:
+- Format code with `ruff`
+- Run static type checks with `mypy`
+- Execute unit tests with `pytest`
+
+## 🐛 Troubleshooting
+
+Common issues and solutions:
+- Virtual environment creation fails: Ensure Python 3.8+ is installed
+- Import errors: Check if virtual environment is activated
+- Test failures: Ensure all dependencies are installed
+
+## 📚 Resources
+
+- [Documentation](https://docs.livekit.io/agents)
+- [Python SDK](https://docs.livekit.io/python/livekit/)
+- [Slack Community](https://livekit.io/join-slack)
+
+## ❓ Getting Help
+
+- Check existing issues and documentation first
+- Open an issue for bugs or feature requests
+- Join our [Slack community](https://livekit.io/join-slack) for questions
+

README.md

@@ -89,7 +89,7 @@ Documentation on the framework and how to use it can be found [here](https://doc
 
 ## Contributing
 
-The Agents framework is under active development in a rapidly evolving field. We welcome and appreciate contributions of any kind, be it feedback, bugfixes, features, new plugins and tools, or better documentation. You can file issues under this repo, open a PR, or chat with us in LiveKit's [Slack community](https://livekit.io/join-slack).
+The Agents framework is under active development in a rapidly evolving field. We welcome and appreciate contributions of any kind, be it feedback, bugfixes, features, new plugins and tools, or better documentation. Please read the [contributing guide](https://github.com/livekit/agents/blob/main/CONTRIBUTING.md) for more information.
 
 <!--BEGIN_REPO_NAV-->
 <br/><table>

livekit-agents/setup.py

@@ -60,6 +60,13 @@
         "typing-extensions~=4.12",
     ],
     extras_require={
+        "dev": [
+            "mypy",
+            "pytest",
+            "ruff",
+            "types-pyyaml",
+            "timeout-decorator",
+        ],
         ':sys_platform=="win32"': [
             "colorama"
         ],  # fix logs color on windows (devmode only)

livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/models.py

@@ -71,9 +71,7 @@
 ]
 
 GroqAudioModels = Literal[
-    "whisper-large-v3",
-    "distil-whisper-large-v3-en",
-    "whisper-large-v3-turbo"
+    "whisper-large-v3", "distil-whisper-large-v3-en", "whisper-large-v3-turbo"
 ]
 
 DeepSeekChatModels = Literal[

livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/stt.py

@@ -27,7 +27,7 @@
 
 import openai
 
-from .models import WhisperModels, GroqAudioModels
+from .models import GroqAudioModels, WhisperModels
 
 
 @dataclass
@@ -81,7 +81,6 @@ def __init__(
             ),
         )
 
-
     @staticmethod
     def with_groq(
         *,
@@ -98,7 +97,7 @@ def with_groq(
         ``api_key`` must be set to your Groq API key, either using the argument or by setting
         the ``GROQ_API_KEY`` environmental variable.
         """
-        
+
         # Use environment variable if API key is not provided
         api_key = api_key or os.environ.get("GROQ_API_KEY")
         if api_key is None:

scripts/_utils.bat

@@ -0,0 +1,26 @@
+@echo off
+call :%~1 "%~2"
+goto :eof
+
+:: Function to pause the script until a key is pressed
+:space_to_continue
+echo Press any key to continue...
+pause > nul
+goto :eof
+
+:: Function to print a horizontal line
+:print_horizontal_line
+echo ------------------------------------------------------------
+goto :eof
+
+:: Function to print a heading with horizontal lines
+:print_heading
+call :print_horizontal_line
+echo -*- %~1
+call :print_horizontal_line
+goto :eof
+
+:: Function to print a status message
+:print_info
+echo -*- %~1
+goto :eof

scripts/create_venv.bat

@@ -0,0 +1,84 @@
+:: create_venv.bat - Create a new virtual environment for livekit agents development
+@echo off
+setlocal
+
+set "CURR_DIR=%~dp0"
+set "REPO_ROOT=%~dp0.."
+set "VENV_DIR=%REPO_ROOT%\livekitenv"
+set "UTILS_BAT=%CURR_DIR%_utils.bat"
+
+
+
+:: Check if Python is available
+where python >nul 2>&1
+if %ERRORLEVEL% neq 0 (
+    echo ERROR: Python is not installed or not in PATH
+    exit /b 1
+)
+
+call "%UTILS_BAT%" print_heading "livekit agents dev setup"
+
+:: Check if VENV_DIR exists and virtual environment is not active
+if defined VIRTUAL_ENV (
+    echo Virtual environment is active. Deactivate using %VENV_DIR%\Scripts\deactivate before running this script.
+    exit /b 1
+)
+
+:: Try to remove existing venv if it exists
+if exist "%VENV_DIR%" (
+    call "%UTILS_BAT%" print_heading "Removing existing venv: %VENV_DIR%"
+    rd /s /q "%VENV_DIR%" 2>nul
+    if exist "%VENV_DIR%" (
+        echo WARNING: Could not remove existing virtual environment
+        echo Please close any programs that might be using the virtual environment
+        echo or remove the directory manually: %VENV_DIR%
+        exit /b 1
+    )
+)
+
+:: Create the virtual environment
+call "%UTILS_BAT%" print_heading "Creating livekit venv: %VENV_DIR%"
+python -m venv "%VENV_DIR%" 2>nul
+if %ERRORLEVEL% neq 0 (
+    echo ERROR: Failed to create virtual environment
+    echo Please ensure you have write permissions to: %VENV_DIR%
+    echo Try running the script as Administrator
+    exit /b %ERRORLEVEL%
+)
+
+:: Verify venv creation
+if not exist "%VENV_DIR%\Scripts\python.exe" (
+    echo ERROR: Virtual environment creation failed
+    echo Please check if you have sufficient disk space and permissions
+    exit /b 1
+)
+
+call "%UTILS_BAT%" print_heading "Upgrading pip to the latest version"
+call "%VENV_DIR%\Scripts\python.exe" -m pip install --upgrade pip
+if %ERRORLEVEL% neq 0 (
+    echo ERROR: Failed to upgrade pip
+    echo Please run the script as Administrator or check your network connection
+    exit /b %ERRORLEVEL%
+)
+
+call "%UTILS_BAT%" print_heading "Installing base python packages"
+call "%VENV_DIR%\Scripts\pip" install pip-tools twine build
+if %ERRORLEVEL% neq 0 ( 
+    echo ERROR: Failed to install required packages
+    echo Please check your network connection and try again
+    exit /b %ERRORLEVEL%
+)
+
+:: Install workspace packages
+call "%VENV_DIR%\Scripts\activate"
+if %ERRORLEVEL% neq 0 (
+    echo ERROR: Failed to activate virtual environment
+    exit /b %ERRORLEVEL%
+)
+
+call "%CURR_DIR%install.bat"
+
+call "%UTILS_BAT%" print_heading "Virtual environment created successfully!"
+echo To activate, run: %VENV_DIR%\Scripts\activate
+
+endlocal

scripts/format.bat

@@ -0,0 +1,55 @@
+@echo off
+:: Formats livekit agents
+
+set "CURR_DIR=%~dp0"
+set "REPO_ROOT=%~dp0.."
+set "UTILS_BAT=%CURR_DIR%_utils.bat"
+
+:main
+call "%UTILS_BAT%" print_heading "Formatting livekit agents"
+
+:: Ensure virtual environment tools are available
+if not exist "%REPO_ROOT%\livekitenv\Scripts\ruff.exe" (
+    echo ERROR: Ruff is not installed in the virtual environment.
+    goto :eof
+)
+
+if not exist "%REPO_ROOT%\livekitenv\Scripts\mypy.exe" (
+    echo ERROR: Mypy is not installed in the virtual environment.
+    goto :eof
+)
+
+if not exist "%REPO_ROOT%\livekitenv\Scripts\pytest.exe" (
+    echo ERROR: Pytest is not installed in the virtual environment.
+    goto :eof
+)
+
+call "%UTILS_BAT%" print_heading "Running: ruff format %REPO_ROOT%"
+call "%REPO_ROOT%\livekitenv\Scripts\ruff" format "%REPO_ROOT%"
+if %ERRORLEVEL% neq 0 (
+    echo Failed to format with ruff.
+    goto :eof
+)
+
+call "%UTILS_BAT%" print_heading "Running: ruff check %REPO_ROOT%"
+call "%REPO_ROOT%\livekitenv\Scripts\ruff" check "%REPO_ROOT%"
+if %ERRORLEVEL% neq 0 (
+    echo Failed ruff check.
+    goto :eof
+)
+
+call "%UTILS_BAT%" print_heading "Running: mypy %REPO_ROOT%"
+call "%REPO_ROOT%\livekitenv\Scripts\mypy" "%REPO_ROOT%"
+if %ERRORLEVEL% neq 0 (
+    echo Failed mypy check.
+    goto :eof
+)
+
+call "%UTILS_BAT%" print_heading "Running: pytest %REPO_ROOT%"
+call "%REPO_ROOT%\livekitenv\Scripts\pytest" "%REPO_ROOT%"
+if %ERRORLEVEL% neq 0 (
+    echo Failed pytest.
+    goto :eof
+)
+
+goto :eof

scripts/install.bat

@@ -0,0 +1,31 @@
+@echo off
+:: Install Livekit-agents
+
+set "CURR_DIR=%~dp0"
+set "REPO_ROOT=%~dp0.."
+set "UTILS_BAT=%CURR_DIR%_utils.bat"
+
+:main
+call "%UTILS_BAT%" print_heading "Installing livekit-agents"
+
+:: Ensure virtual environment and pip are available
+if not exist "%REPO_ROOT%\livekitenv\Scripts\pip.exe" (
+    echo ERROR: pip is not installed in the virtual environment.
+    goto :eof
+)
+
+@REM call "%UTILS_BAT%" print_heading "Installing requirements.txt"
+@REM call "%REPO_ROOT%\livekitenv\Scripts\pip" install --no-deps -r "%REPO_ROOT%\livekit-agents\requirements.txt"
+@REM if %ERRORLEVEL% neq 0 (
+@REM     echo Failed to install requirements.
+@REM     goto :eof
+@REM )
+
+call "%UTILS_BAT%" print_heading "Installing livekit agents with [dev] extras"
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install --editable "%REPO_ROOT%\livekit-agents[dev]"
+if %ERRORLEVEL% neq 0 (
+    echo Failed to install livekit-agents.
+    goto :eof
+)
+call "%CURR_DIR%install_plugins_editable.bat"
+goto :eof

scripts/install_plugins_editable.bat

@@ -0,0 +1,26 @@
+@echo off
+setlocal
+
+set "REPO_ROOT=%~dp0.."
+set "UTILS_BAT=%CURR_DIR%_utils.bat"
+
+if "%VIRTUAL_ENV%"=="" (
+    echo You are not in a virtual environment.
+    exit /b 1
+)
+
+call "%UTILS_BAT%" print_heading "Installing livekit plugins in editable mode"
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-azure" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-cartesia" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-deepgram" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-elevenlabs" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-google" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-minimal" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-nltk" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-openai" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-rag" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-silero" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-browser" --config-settings editable_mode=strict
+call "%REPO_ROOT%\livekitenv\Scripts\pip" install -e "%REPO_ROOT%\livekit-plugins\livekit-plugins-llama-index" --config-settings editable_mode=strict
+
+endlocal