Voice SDK (#117)

Author: gregorybchris

.github/workflows/ci.yaml

@@ -27,6 +27,12 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Install system dependencies
+        shell: bash
+        run: |
+          sudo apt-get --yes update
+          sudo apt-get --yes install ffmpeg
+
       - name: Install Python dependencies
         shell: bash
         run: |
@@ -57,7 +63,7 @@ jobs:
         env:
           HUME_DEV_API_KEY: ${{ secrets.HUME_DEV_API_KEY }}
         run: |
-          poetry run pytest tests --cov=hume --cov-report=html --cov-report=xml --cov-branch -m "not service"
+          poetry run pytest tests --cov=hume --cov-report=html --cov-report=xml --cov-branch -m "(not service) and (not microphone)"
 
       - name: Run pydocstyle
         shell: bash
@@ -84,13 +90,24 @@ jobs:
   build-service:
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+
     steps:
       - uses: actions/checkout@v2
 
-      - name: Python 3.10 Setup
+      - name: Python ${{ matrix.python-version }} Setup
         uses: actions/setup-python@v2
         with:
-          python-version: "3.10"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        shell: bash
+        run: |
+          sudo apt-get --yes update
+          sudo apt-get --yes install ffmpeg
 
       - name: Install Python dependencies
         shell: bash
@@ -124,3 +141,40 @@ jobs:
         shell: bash
         run: |
           poetry run covcheck coverage.xml --config pyproject.toml --group service
+
+  build-microphone:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Python ${{ matrix.python-version }} Setup
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        shell: bash
+        run: |
+          sudo apt-get --yes update
+          sudo apt-get --yes install libasound2-dev libportaudio2 ffmpeg
+
+      - name: Install Python dependencies
+        shell: bash
+        run: |
+          pip install poetry
+          if [ -d /poetryenvs ]; then rm -rf ~/poetryenvs; fi
+          poetry config virtualenvs.path ~/poetryenvs
+          poetry install -E microphone
+
+      - name: Run pytest
+        shell: bash
+        env:
+          HUME_DEV_API_KEY: ${{ secrets.HUME_DEV_API_KEY }}
+        run: |
+          poetry run pytest tests --cov=hume --cov-report=html --cov-report=xml --cov-branch -m microphone

.vscode/settings.json

@@ -3,14 +3,12 @@
   "[markdown]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
   "[python]": { "editor.defaultFormatter": "ms-python.black-formatter" },
   "[toml]": { "editor.defaultFormatter": "tamasfe.even-better-toml" },
-  "editor.codeActionsOnSave": {
-    "source.organizeImports": "explicit"
-  },
+  "editor.codeActionsOnSave": { "source.organizeImports": "explicit" },
   "black-formatter.args": ["--config", "pyproject.toml"],
   "flake8.args": ["--max-line-length", "120"],
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.detectIndentation": true,
-  "editor.formatOnSave": true,
+  // "editor.formatOnSave": true,
   "editor.insertSpaces": true,
   "editor.rulers": [120],
   "isort.args": ["--settings-file", "pyproject.toml"],
@@ -19,5 +17,6 @@
   "pylint.path": ["pylint"],
   "pylint.args": ["--rcfile", "pyproject.toml"],
   "python.analysis.extraPaths": ["tests"],
-  "python.testing.cwd": "tests"
+  "python.testing.cwd": "tests",
+  "cSpell.words": ["agen", "cffi", "deepgram", "indata", "samplerate", "simpleaudio", "sounddevice"]
 }

docs/batch/batch-job-details.md

@@ -1 +1 @@
-::: hume._batch.batch_job_details.BatchJobDetails
+::: hume._measurement.batch.batch_job_details.BatchJobDetails

docs/batch/batch-job-state.md

@@ -1 +1 @@
-::: hume._batch.batch_job_state.BatchJobState
+::: hume._measurement.batch.batch_job_state.BatchJobState

docs/batch/batch-job-status.md

@@ -1 +1 @@
-::: hume._batch.batch_job_status.BatchJobStatus
+::: hume._measurement.batch.batch_job_status.BatchJobStatus

docs/batch/batch-job.md

@@ -1 +1 @@
-::: hume._batch.batch_job.BatchJob
+::: hume._measurement.batch.batch_job.BatchJob

docs/batch/hume-batch-client.md

@@ -1 +1 @@
-::: hume._batch.hume_batch_client.HumeBatchClient
+::: hume._measurement.batch.hume_batch_client.HumeBatchClient

docs/batch/transcription-config.md

@@ -1 +1 @@
-::: hume._batch.transcription_config.TranscriptionConfig
+::: hume._measurement.batch.transcription_config.TranscriptionConfig

docs/index.md

@@ -12,16 +12,106 @@ Basic installation:
 pip install hume
 ```
 
-WebSocket and streaming features can be enabled with:
+## Requirements
+
+To use the basic functionality of `HumeVoiceClient`, `HumeBatchClient` or `HumeStreamClient` there are no additional system dependencies, however using the audio playback functionality of the EVI `MicrophoneInterface` may require a few extra dependencies depending on your operating system.
+
+### Linux
+
+- `libasound2-dev`
+- `libportaudio2`
+
+You can install these dependencies with:
 
 ```bash
-pip install "hume[stream]"
+sudo apt-get --yes update
+sudo apt-get --yes install libasound2-dev libportaudio2
 ```
 
 ## Basic Usage
 
 Jupyter example notebooks can be found in the [Python SDK GitHub repo](https://github.com/HumeAI/hume-python-sdk/tree/main/examples/README.md).
 
+### Stream an EVI chat session
+
+Start a new session using your device's microphone:
+
+> Note: to use audio playback functionality in the MicrophoneInterface run `pip install hume[microphone]`
+
+```python
+import asyncio
+
+from hume import HumeVoiceClient, MicrophoneInterface
+
+async def main() -> None:
+    client = HumeVoiceClient("<your-api-key>")
+
+    async with client.connect() as socket:
+        await MicrophoneInterface.start(socket)
+
+asyncio.run(main())
+```
+
+Using a custom voice config:
+
+```py
+import asyncio
+
+from hume import HumeVoiceClient, MicrophoneInterface
+
+async def main() -> None:
+    client = HumeVoiceClient("<your-api-key>")
+
+    async with client.connect(config_id="<your-config-id>") as socket:
+        await MicrophoneInterface.start(socket)
+
+asyncio.run(main())
+```
+
+### Managing voice configs
+
+Create a new config:
+
+```py
+from hume import HumeVoiceClient, VoiceConfig
+
+client = HumeVoiceClient("<your-api-key">)
+config: VoiceConfig = client.create_config(
+    name=f"silly-poet",
+    prompt="you are a silly poet",
+)
+print("Created config: ", config.id)
+```
+
+Get an existing config:
+
+```py
+from hume import HumeVoiceClient
+
+client = HumeVoiceClient("<your-api-key">)
+config = client.get_config("<YOUR CONFIG ID>")
+print("Fetched config: ", config.name)
+```
+
+List all your configs:
+
+```py
+from hume import HumeVoiceClient
+
+client = HumeVoiceClient("<your-api-key">)
+for config in client.iter_configs():
+    print(f"- {config.name} ({config.id})")
+```
+
+Delete a config:
+
+```py
+from hume import HumeVoiceClient
+
+client = HumeVoiceClient("<your-api-key">)
+client.delete_config("<YOUR CONFIG ID>")
+```
+
 ### Submit a new batch job
 
 > Note: Your personal API key can be found in the profile section of [beta.hume.ai](https://beta.hume.ai)
@@ -64,8 +154,6 @@ print(job)
 
 ### Stream predictions over a WebSocket
 
-> Note: `pip install "hume[stream]"` is required to use WebSocket features
-
 ```python
 import asyncio
 

docs/stream/hume-stream-client.md

@@ -1 +1 @@
-::: hume._stream.hume_stream_client.HumeStreamClient
+::: hume._measurement.stream.hume_stream_client.HumeStreamClient