Nash0x7E2
diff --git a/‎.cursor/rules/python.mdc‎
Lines changed: 9 additions & 1 deletion b/‎.cursor/rules/python.mdc‎
Lines changed: 9 additions & 1 deletion
diff --git a/‎.github/actions/python-uv-setup/action.yml‎
Lines changed: 10 additions & 2 deletions b/‎.github/actions/python-uv-setup/action.yml‎
Lines changed: 10 additions & 2 deletions
diff --git a/‎.github/labeler.yml‎
Lines changed: 165 additions & 0 deletions b/‎.github/labeler.yml‎
Lines changed: 165 additions & 0 deletions
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/ci.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.github/workflows/labeler.yml‎
Lines changed: 12 additions & 0 deletions b/‎.github/workflows/labeler.yml‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎.github/workflows/run_tests.yml‎
Lines changed: 16 additions & 0 deletions b/‎.github/workflows/run_tests.yml‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎DEVELOPMENT.md‎
Lines changed: 67 additions & 0 deletions b/‎DEVELOPMENT.md‎
Lines changed: 67 additions & 0 deletions
@@ -14,4 +14,12 @@ docstrings should follow the google style guides for docstrings.
 integration tests use
 @pytest.mark.integration
 
-@pytest.mark.asyncio is not needed (its automatic)
+@pytest.mark.asyncio is not needed (its automatic)
+
+---
+description: when running python or tests
+globs:
+alwaysApply: true
+---
+
+we use uv on this project, no python -m non-sense please. If you get in trouble with deps just stop and ask, better to have the human resolve things (no sudo brew kind of stuff please)
@@ -17,12 +17,20 @@ runs:
   using: composite
   steps:
     - name: Install the latest version of uv
-      uses: astral-sh/setup-uv@v6
+      uses: astral-sh/setup-uv@v7
       with:
         python-version: "3.13"
         version: "latest"
         enable-cache: true
-        cache-dependency-glob: "uv.lock"
+        cache-dependency-glob: |
+          **/pyproject.toml
+          **/uv.lock
+    - name: Log cache status
+      shell: bash
+      env:
+        UV_CACHE_HIT: "${{ steps.setup_uv.outputs['cache-hit'] }}"
+      run: |
+        echo "setup-uv cache hit: ${UV_CACHE_HIT}"
 
     - name: Install the project
       shell: bash
 
@@ -0,0 +1,165 @@
+---
+# Core Framework Components
+agents-core:
+  - agents-core/**
+  - '!agents-core/**/tests/**'
+  - '!agents-core/**/__pycache__/**'
+
+# Plugin System
+plugins:
+  - plugins/**
+  - '!plugins/**/tests/**'
+  - '!plugins/**/__pycache__/**'
+
+# Specific Plugin Labels
+plugin-getstream:
+  - plugins/getstream/**
+  - '!plugins/getstream/**/tests/**'
+
+plugin-openai:
+  - plugins/openai/**
+  - '!plugins/openai/**/tests/**'
+
+plugin-gemini:
+  - plugins/gemini/**
+  - '!plugins/gemini/**/tests/**'
+
+plugin-deepgram:
+  - plugins/deepgram/**
+  - '!plugins/deepgram/**/tests/**'
+
+plugin-ultralytics:
+  - plugins/ultralytics/**
+  - '!plugins/ultralytics/**/tests/**'
+
+plugin-elevenlabs:
+  - plugins/elevenlabs/**
+  - '!plugins/elevenlabs/**/tests/**'
+
+plugin-cartesia:
+  - plugins/cartesia/**
+  - '!plugins/cartesia/**/tests/**'
+
+plugin-kokoro:
+  - plugins/kokoro/**
+  - '!plugins/kokoro/**/tests/**'
+
+plugin-moonshine:
+  - plugins/moonshine/**
+  - '!plugins/moonshine/**/tests/**'
+
+plugin-silero:
+  - plugins/silero/**
+  - '!plugins/silero/**/tests/**'
+
+plugin-smart-turn:
+  - plugins/smart_turn/**
+  - '!plugins/smart_turn/**/tests/**'
+
+plugin-wizper:
+  - plugins/wizper/**
+  - '!plugins/wizper/**/tests/**'
+
+plugin-xai:
+  - plugins/xai/**
+  - '!plugins/xai/**/tests/**'
+
+plugin-krisp:
+  - plugins/krisp/**
+  - '!plugins/krisp/**/tests/**'
+
+plugin-anthropic:
+  - plugins/anthropic/**
+  - '!plugins/anthropic/**/tests/**'
+
+# Examples and Demos
+examples:
+  - examples/**
+  - '!examples/**/tests/**'
+  - '!examples/**/__pycache__/**'
+
+# Testing
+tests:
+  - tests/**
+  - '**/tests/**'
+  - '**/test_*.py'
+  - '**/*_test.py'
+
+# Documentation
+docs:
+  - docs/**
+  - '*.md'
+  - '!README.md'
+
+# Configuration and Build
+config:
+  - '*.toml'
+  - '*.yml'
+  - '*.yaml'
+  - '*.json'
+  - '*.ini'
+  - '*.cfg'
+  - 'pyproject.toml'
+  - 'pytest.ini'
+  - 'conftest.py'
+
+# CI/CD and GitHub
+ci:
+  - '.github/**'
+  - '*.yml'
+  - '*.yaml'
+
+# Core Agent System
+core-agents:
+  - agents-core/vision_agents/core/agents/**
+  - agents-core/vision_agents/core/events/**
+  - agents-core/vision_agents/core/edge/**
+
+# Core Infrastructure
+core-infrastructure:
+  - agents-core/vision_agents/core/llm/**
+  - agents-core/vision_agents/core/stt/**
+  - agents-core/vision_agents/core/tts/**
+  - agents-core/vision_agents/core/vad/**
+  - agents-core/vision_agents/core/turn_detection/**
+  - agents-core/vision_agents/core/processors/**
+  - agents-core/vision_agents/core/mcp/**
+  - agents-core/vision_agents/core/observability/**
+  - agents-core/vision_agents/core/utils/**
+
+# CLI and Development Tools
+cli:
+  - agents-core/vision_agents/core/cli.py
+  - dev.py
+  - DEVELOPMENT.md
+
+# Dependencies
+dependencies:
+  - 'uv.lock'
+  - 'requirements*.txt'
+  - 'poetry.lock'
+  - 'Pipfile.lock'
+
+# Assets and Resources
+assets:
+  - assets/**
+  - '*.png'
+  - '*.jpg'
+  - '*.jpeg'
+  - '*.gif'
+  - '*.mp4'
+  - '*.wav'
+  - '*.mp3'
+
+# License and Legal
+legal:
+  - LICENSE
+  - LICENSE.*
+  - '*.license'
+
+# README and Project Info
+project-info:
+  - README.md
+  - CHANGELOG.md
+  - CONTRIBUTING.md
+  - SECURITY.md
@@ -10,7 +10,7 @@ jobs:
     uses: ./.github/workflows/run_tests.yml
     with:
       marker: 'not integration'
-
+    secrets: inherit
 
 # Cancel in-flight runs for the same branch/PR when new commits arrive
 concurrency:
 
@@ -0,0 +1,12 @@
+name: "Pull Request Labeler"
+on:
+- pull_request_target
+
+jobs:
+  labeler:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/labeler@v5
@@ -24,6 +24,9 @@ jobs:
         run: uv run mypy --install-types --non-interactive agents-core/vision_agents
       - name: Mypy plugins
         run: uv run mypy --install-types --non-interactive --exclude 'plugins/.*/tests/.*' plugins
+      - name: Show environment name
+        run: |
+          echo "Environment: ${{ job.environment }}"
 
   test:
     name: Test "${{ inputs.marker }}"
@@ -40,11 +43,24 @@ jobs:
       STREAM_API_KEY: ${{ secrets.STREAM_API_KEY }}
       STREAM_API_SECRET: ${{ secrets.STREAM_API_SECRET }}
       XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
+      AWS_BEARER_TOKEN_BEDROCK: "${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}"
+      _BEARER_TOKEN_BEDROCK: "${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}"
     timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v5
       - uses: ./.github/actions/python-uv-setup
+      - name: Export AWS_BEARER_TOKEN_BEDROCK (heredoc)
+        shell: bash
+        run: |
+          {
+            echo 'AWS_BEARER_TOKEN_BEDROCK<<EOF'
+            echo "${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}"
+            echo 'EOF'
+          } >> "$GITHUB_ENV"
+
+      - name: Verify presence
+        run: uv run python -c "import os; v=os.getenv('AWS_BEARER_TOKEN_BEDROCK'); print('exists', v is not None, 'len', 0 if v is None else len(v))"
       - name: Run test
         run: uv run pytest -n auto -m "${{ inputs.marker }}"
       - name: Run plugin test
 
@@ -109,6 +109,73 @@ To see how the agent work open up agents.py
 * The LLM uses the VideoForwarder to write the video to a websocket or webrtc connection
 * The STS writes the reply on agent.llm.audio_track and the RealtimeTranscriptEvent / RealtimePartialTranscriptEvent
 
+## Audio management
+
+Some important things about audio inside the library:
+
+1. WebRTC uses Opus 48khz stereo but inside the library audio is always in PCM format
+2. Plugins / AI models work with different PCM formats, usually 16khz mono
+3. PCM data is always passed around using the `PcmData` object which contains information about sample rate, channels and format
+4. Text-to-speech plugins automatically return PCM in the format needed by WebRTC. This is exposed via the `set_output_format` method
+5. Audio resampling can be done using `PcmData.resample` method
+6. When resampling audio in chunks, it is important to re-use the same `av.AudioResampler` resampler (see `PcmData.resample` and `core.tts.TTS`)
+7. Adjusting from stereo to mono and vice-versa can be done using the `PcmData.resample` method
+
+Some ground rules:
+
+1. Do not build code to resample / adjust audio unless it is not covered already by `PcmData`
+2. Do not pass PCM as plain bytes around and write code that assumes specific sample rate or format. Use `PcmData` instead
+
+## Example
+
+```python
+import asyncio
+from vision_agents.core.edge.types import PcmData
+from openai import AsyncOpenAI
+
+async def example():
+    client = AsyncOpenAI(api_key="sk-42")
+
+    resp = await client.audio.speech.create(
+        model="gpt-4o-mini-tts",
+        voice="alloy",
+        input="pcm is cool, give me some of that please",
+        response_format="pcm",
+    )
+
+    # load response into PcmData, note that you need to specify sample_rate, channels and format
+    pcm_data = PcmData.from_bytes(
+        resp.content, sample_rate=24_000, channels=1, format="s16"
+    )
+
+    # check if pcm_data is stereo (it's not in this case ofc)
+    print(pcm_data.stereo)
+
+    # write the pcm to file
+    with open("test.wav", "wb") as f:
+        f.write(pcm_data.to_wav_bytes())
+
+    # resample pcm to be 48khz stereo
+    resampled_pcm = pcm_data.resample(48_000, 2)
+
+    # play-out pcm using ffplay
+    from vision_agents.core.edge.types import play_pcm_with_ffplay
+
+    await play_pcm_with_ffplay(resampled_pcm)
+
+if __name__ == "__main__":
+    asyncio.run(example())
+```
+
+
+### Testing audio manually
+
+Sometimes you need to test audio manually, here's some tips:
+
+1. Do not use earplugs when testing PCM playback ;)
+2. You can use the `PcmData.to_wav_bytes` method to convert PCM into wav bytes (see `manual_tts_to_wav` for an example)
+3. If you have `ffplay` installed, you can playback pcm directly to check if audio is correct
+
 ## Dev / Contributor Guidelines
 
 ### Light wrapping