Add raw python API example (#60)

README.md

@@ -12,7 +12,8 @@ This repository contains examples of how to use the [Hume API](https://docs.hume
 | [`evi-next-js-pages-router`](/evi-next-js-pages-router/README.md)   | Typescript | Next.js   |
 | [`evi-typescript-example`](/evi-typescript-example/README.md)       | Typescript |           |
 | [`evi-embed-vue`](/evi-embed-vue/README.md) | Typescript     | Vue           |
-| [`evi-python-example`](/evi-python-example/README.md)               | Python     |           |
+| [`evi-python-example`](/evi-python-example/README.md)               | Python     | Hume Python SDK |
+| [`evi-python-api-example`](/evi-python-api-example/README.md)               | Python     |           |
 | [`meld`](/meld/README.md) (`evi-react-example`)                     | Typescript | React     |
 
 ## [Expression Measurement API](https://dev.hume.ai/docs/expression-measurement-api/overview)

evi-python-api-example/.gitignore

@@ -0,0 +1,4 @@
+.env
+.DS_store
+*.pyc
+__pycache__/

evi-python-api-example/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hume AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

evi-python-api-example/README.md

@@ -0,0 +1,68 @@
+<div align="center">
+  <img src="https://storage.googleapis.com/hume-public-logos/hume/hume-banner.png">
+  <h1>Empathic Voice Interface | Sample Implementation</h1>
+  <p>
+    <strong>Jumpstart your development with Hume's Empathic Voice Interface!</strong>
+  </p>
+</div>
+
+## Overview
+
+This project features a sample implementation of Hume's [Empathic Voice Interface](https://hume.docs.buildwithfern.com/docs/empathic-voice-interface-evi/overview) using Hume's API with Python in a terminal window.
+
+## Setting up a virtual environment (optional)
+
+Before you install the dependencies, you might want to create a virtual environment to isolate your package installations. To create a virtual environment, run the following commands in your terminal:
+
+```bash
+# Create a virtual environment in the directory 'evi-env'
+python -m venv evi-env
+
+# Activate the virtual environment
+# On Mac/Linux:
+source evi-env/bin/activate
+```
+
+After activating the virtual environment, you can proceed with the installation of dependencies as described below.
+
+## Dependencies
+
+In order to run it, you need to install the `requirements.txt` using `pip`:
+
+### Mac
+
+```bash
+pip install -r requirements_mac.txt 
+```
+
+### Linux
+
+```bash
+pip install -r requirements_linux.txt 
+```
+
+## Environment variables
+
+Either create a `.env` file or set environment variables for HUME_API_KEY and HUME_CLIENT_SECRET.
+
+Example `.env` file:
+
+```bash
+HUME_API_KEY="autj04acqK3jpfERQJpkg7829AATGUEvlAR7SYmmOB5ZZVbZD"
+HUME_CLIENT_SECRET="gnxftyfpcagTyB1hgffGis2zHgkUiQZN3Fo46Tj9vMchBBupgAXhM8pamd2Aw9Qd"
+```
+
+Example terminal commands to set environment variables manually:
+```bash
+export HUME_API_KEY="autj04acqK3jpfERQJpkg7829AATGUEvlAR7SYmmOB5ZZVbZD"
+export HUME_CLIENT_SECRET="gnxftyfpcagTyB1hgffGis2zHgkUiQZN3Fo46Tj9vMchBBupgAXhM8pamd2Aw9Qd"
+```
+
+## Usage
+
+```bash
+cd src
+python main.py
+```
+
+

evi-python-api-example/requirements_linux.txt

@@ -0,0 +1,21 @@
+certifi==2024.2.2
+cffi==1.16.0
+charset-normalizer==3.3.2
+gevent==24.2.1
+greenlet==3.0.3
+idna==3.6
+numpy==1.26.4
+playsound==1.3.0
+PyAudio==0.2.14
+pycparser==2.21
+requests==2.31.0
+setuptools==69.1.1
+simpleaudio==1.0.4
+sounddevice==0.4.6
+soundfile
+urllib3==2.2.1
+websockets==12.0
+wheel==0.42.0
+zope.event==5.0
+zope.interface==6.2
+python-dotenv

evi-python-api-example/requirements_mac.txt

@@ -0,0 +1,174 @@
+certifi==2024.2.2
+cffi==1.16.0
+charset-normalizer==3.3.2
+gevent==24.2.1
+greenlet==3.0.3
+idna==3.6
+numpy==1.26.4
+playsound==1.3.0
+PyAudio==0.2.14
+pycparser==2.21
+pyobjc==10.1
+pyobjc-core==10.1
+pyobjc-framework-Accessibility==10.1
+pyobjc-framework-Accounts==10.1
+pyobjc-framework-AddressBook==10.1
+pyobjc-framework-AdServices==10.1
+pyobjc-framework-AdSupport==10.1
+pyobjc-framework-AppleScriptKit==10.1
+pyobjc-framework-AppleScriptObjC==10.1
+pyobjc-framework-ApplicationServices==10.1
+pyobjc-framework-AppTrackingTransparency==10.1
+pyobjc-framework-AudioVideoBridging==10.1
+pyobjc-framework-AuthenticationServices==10.1
+pyobjc-framework-AutomaticAssessmentConfiguration==10.1
+pyobjc-framework-Automator==10.1
+pyobjc-framework-AVFoundation==10.1
+pyobjc-framework-AVKit==10.1
+pyobjc-framework-AVRouting==10.1
+pyobjc-framework-BackgroundAssets==10.1
+pyobjc-framework-BusinessChat==10.1
+pyobjc-framework-CalendarStore==10.1
+pyobjc-framework-CallKit==10.1
+pyobjc-framework-CFNetwork==10.1
+pyobjc-framework-Cinematic==10.1
+pyobjc-framework-ClassKit==10.1
+pyobjc-framework-CloudKit==10.1
+pyobjc-framework-Cocoa==10.1
+pyobjc-framework-Collaboration==10.1
+pyobjc-framework-ColorSync==10.1
+pyobjc-framework-Contacts==10.1
+pyobjc-framework-ContactsUI==10.1
+pyobjc-framework-CoreAudio==10.1
+pyobjc-framework-CoreAudioKit==10.1
+pyobjc-framework-CoreBluetooth==10.1
+pyobjc-framework-CoreData==10.1
+pyobjc-framework-CoreHaptics==10.1
+pyobjc-framework-CoreLocation==10.1
+pyobjc-framework-CoreMedia==10.1
+pyobjc-framework-CoreMediaIO==10.1
+pyobjc-framework-CoreMIDI==10.1
+pyobjc-framework-CoreML==10.1
+pyobjc-framework-CoreMotion==10.1
+pyobjc-framework-CoreServices==10.1
+pyobjc-framework-CoreSpotlight==10.1
+pyobjc-framework-CoreText==10.1
+pyobjc-framework-CoreWLAN==10.1
+pyobjc-framework-CryptoTokenKit==10.1
+pyobjc-framework-DataDetection==10.1
+pyobjc-framework-DeviceCheck==10.1
+pyobjc-framework-DictionaryServices==10.1
+pyobjc-framework-DiscRecording==10.1
+pyobjc-framework-DiscRecordingUI==10.1
+pyobjc-framework-DiskArbitration==10.1
+pyobjc-framework-DVDPlayback==10.1
+pyobjc-framework-EventKit==10.1
+pyobjc-framework-ExceptionHandling==10.1
+pyobjc-framework-ExecutionPolicy==10.1
+pyobjc-framework-ExtensionKit==10.1
+pyobjc-framework-ExternalAccessory==10.1
+pyobjc-framework-FileProvider==10.1
+pyobjc-framework-FileProviderUI==10.1
+pyobjc-framework-FinderSync==10.1
+pyobjc-framework-FSEvents==10.1
+pyobjc-framework-GameCenter==10.1
+pyobjc-framework-GameController==10.1
+pyobjc-framework-GameKit==10.1
+pyobjc-framework-GameplayKit==10.1
+pyobjc-framework-HealthKit==10.1
+pyobjc-framework-ImageCaptureCore==10.1
+pyobjc-framework-InputMethodKit==10.1
+pyobjc-framework-InstallerPlugins==10.1
+pyobjc-framework-InstantMessage==10.1
+pyobjc-framework-Intents==10.1
+pyobjc-framework-IntentsUI==10.1
+pyobjc-framework-IOBluetooth==10.1
+pyobjc-framework-IOBluetoothUI==10.1
+pyobjc-framework-IOSurface==10.1
+pyobjc-framework-iTunesLibrary==10.1
+pyobjc-framework-KernelManagement==10.1
+pyobjc-framework-LatentSemanticMapping==10.1
+pyobjc-framework-LaunchServices==10.1
+pyobjc-framework-libdispatch==10.1
+pyobjc-framework-libxpc==10.1
+pyobjc-framework-LinkPresentation==10.1
+pyobjc-framework-LocalAuthentication==10.1
+pyobjc-framework-LocalAuthenticationEmbeddedUI==10.1
+pyobjc-framework-MailKit==10.1
+pyobjc-framework-MapKit==10.1
+pyobjc-framework-MediaAccessibility==10.1
+pyobjc-framework-MediaLibrary==10.1
+pyobjc-framework-MediaPlayer==10.1
+pyobjc-framework-MediaToolbox==10.1
+pyobjc-framework-Metal==10.1
+pyobjc-framework-MetalFX==10.1
+pyobjc-framework-MetalKit==10.1
+pyobjc-framework-MetalPerformanceShaders==10.1
+pyobjc-framework-MetalPerformanceShadersGraph==10.1
+pyobjc-framework-MetricKit==10.1
+pyobjc-framework-MLCompute==10.1
+pyobjc-framework-ModelIO==10.1
+pyobjc-framework-MultipeerConnectivity==10.1
+pyobjc-framework-NaturalLanguage==10.1
+pyobjc-framework-NetFS==10.1
+pyobjc-framework-Network==10.1
+pyobjc-framework-NetworkExtension==10.1
+pyobjc-framework-NotificationCenter==10.1
+pyobjc-framework-OpenDirectory==10.1
+pyobjc-framework-OSAKit==10.1
+pyobjc-framework-OSLog==10.1
+pyobjc-framework-PassKit==10.1
+pyobjc-framework-PencilKit==10.1
+pyobjc-framework-PHASE==10.1
+pyobjc-framework-Photos==10.1
+pyobjc-framework-PhotosUI==10.1
+pyobjc-framework-PreferencePanes==10.1
+pyobjc-framework-PushKit==10.1
+pyobjc-framework-Quartz==10.1
+pyobjc-framework-QuickLookThumbnailing==10.1
+pyobjc-framework-ReplayKit==10.1
+pyobjc-framework-SafariServices==10.1
+pyobjc-framework-SafetyKit==10.1
+pyobjc-framework-SceneKit==10.1
+pyobjc-framework-ScreenCaptureKit==10.1
+pyobjc-framework-ScreenSaver==10.1
+pyobjc-framework-ScreenTime==10.1
+pyobjc-framework-ScriptingBridge==10.1
+pyobjc-framework-SearchKit==10.1
+pyobjc-framework-Security==10.1
+pyobjc-framework-SecurityFoundation==10.1
+pyobjc-framework-SecurityInterface==10.1
+pyobjc-framework-SensitiveContentAnalysis==10.1
+pyobjc-framework-ServiceManagement==10.1
+pyobjc-framework-SharedWithYou==10.1
+pyobjc-framework-SharedWithYouCore==10.1
+pyobjc-framework-ShazamKit==10.1
+pyobjc-framework-Social==10.1
+pyobjc-framework-SoundAnalysis==10.1
+pyobjc-framework-Speech==10.1
+pyobjc-framework-SpriteKit==10.1
+pyobjc-framework-StoreKit==10.1
+pyobjc-framework-Symbols==10.1
+pyobjc-framework-SyncServices==10.1
+pyobjc-framework-SystemConfiguration==10.1
+pyobjc-framework-SystemExtensions==10.1
+pyobjc-framework-ThreadNetwork==10.1
+pyobjc-framework-UniformTypeIdentifiers==10.1
+pyobjc-framework-UserNotifications==10.1
+pyobjc-framework-UserNotificationsUI==10.1
+pyobjc-framework-VideoSubscriberAccount==10.1
+pyobjc-framework-VideoToolbox==10.1
+pyobjc-framework-Virtualization==10.1
+pyobjc-framework-Vision==10.1
+pyobjc-framework-WebKit==10.1
+requests==2.31.0
+setuptools==69.1.1
+simpleaudio==1.0.4
+sounddevice==0.4.6
+soundfile==0.12.1
+urllib3==2.2.1
+websockets==12.0
+wheel==0.42.0
+zope.event==5.0
+zope.interface==6.2
+python-dotenv

evi-python-api-example/src/authenticator.py

@@ -0,0 +1,71 @@
+# authenticator.py
+
+import base64
+import requests
+
+
+class Authenticator:
+    """
+    A class to handle authentication with Hume AI's API via OAuth2.
+
+    Attributes:
+        api_key (str): The API key provided by Hume AI.
+        client_secret (str): The client secret provided by Hume AI.
+        host (str): The host URL of the API (default is "test-api.hume.ai").
+    """
+
+    def __init__(self, api_key: str, client_secret: str, host: str = "test-api.hume.ai"):
+        """
+        Initialize the Authenticator with the provided API key, client secret, and host.
+
+        Args:
+            api_key (str): The API key provided by Hume AI.
+            client_secret (str): The client secret provided by Hume AI.
+            host (str, optional): The host URL of the API. Defaults to "test-api.hume.ai".
+        """
+        self.api_key = api_key
+        self.client_secret = client_secret
+        self.host = host
+
+    def fetch_access_token(self) -> str:
+        """
+        Fetch an access token from Hume AI's OAuth2 service.
+
+        This method constructs the necessary headers and body for the OAuth2 client credentials
+        grant, makes the POST request to the OAuth2 token endpoint, and extracts the access token
+        from the response.
+
+        Returns:
+            str: The access token.
+
+        Raises:
+            ValueError: If the access token is not found in the response.
+        """
+        # Prepare the authorization string
+        auth_string = f"{self.api_key}:{self.client_secret}"
+        encoded = base64.b64encode(auth_string.encode()).decode()
+
+        # Set up the headers
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Authorization": f"Basic {encoded}",
+        }
+
+        # Prepare the body
+        data = {
+            "grant_type": "client_credentials",
+        }
+
+        # Make the POST request to the OAuth2 token endpoint
+        response = requests.post(
+            f"https://{self.host}/oauth2-cc/token", headers=headers, data=data
+        )
+
+        # Parse the JSON response
+        data = response.json()
+
+        # Extract the access token, raise an error if not found
+        if "access_token" not in data:
+            raise ValueError("Access token not found in response")
+
+        return data["access_token"]