Upload 217 files

audio/sent-to-BOT.txt

@@ -0,0 +1,18 @@
+{"timestamp":"2025-01-17 11:07:06","streamId":"C:\\record\\0.1.0.18.0_CallID_9911011200_051025154759.wav","callerId":"9911011200","channelId":"0.1.0.18.0","event":"answer","callDirection":"incoming","did":"0120111222","callId":"0.1.0.18.0_CallID","cid":"CallID","extraParams":""} (15:47:59.580)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"sAIwAzACcAPQAmAFIAVwAjgAcPzQ/BACwAuAEEAJwPWA4ADbgOWQ/YAQgBaAEEAKwArADEAJ0PyA7IDlgOpA9+AFQAzAC+AF6AFYAJD9IPvA90D1wPag+OD7kP3o/tADwAqAEMAN4AVw/cD3YPnw/BADIAZgBWAGoAbACsAKoAUQ/EDzQPTg+vACoAZgBagBkAPADoAXgBNw/QDfAMsAz4DmYAWAGoAdgBqAGIAXgBPgBIDvAN0A2YDkYPhACYAQgBHADEAKIAWw/EDzgOqA6YDvwPdYAWAFQAlADIAQwA/gByj/QPbA9GD4qP5gBSAGwAnAC8AKQAnQA7D9QPbA88D2oPvYAfAD4AXgBJADQAjADUAOsAOA7ADVANOA43j/gBgAIYAbgBWAE8AOIARA84DhANuA5MD3wAmAEoASQA4=","callId":"0.1.0.18.0","extraParams":""} (15:48:09.927)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"gBGAEoASgBeAGIAUwAwYAGD4wPWA74DrgO3A9KD7iACwA2AHQAvACfACUPxg+qD6YPog+7D9SAFgBkALwAzACsAIYAXYAdD94Plg+CD5YPmg+KD5UP0oAbACWAHQAmAFoARgBNACiACYANgAMALQA+D6wPBA9uD5wPKA78DxYPlgBcAKwAqAEYAZgBiAEcAIEAIY/sD3gO6A6IDswPPA92D7UALACcANwAmwAgj/4PtA98D0QPZg+pgA4AVACkAPgBDADUAK4AX4AJD8YPnA9sD0QPRA9iD6WP5IAPACwAhACSAH4AUQA4gAKP9w/VgACP/A8cDwYPvA98DxwPNA9Qj+oAdgBkAKgBaAGIAVgBJADGAH8AJA94DtgOuA7IDuwPHA9sj/QAhACkAIoAegBWgAoPvg+aD6cPzI/pgBYAY=","callId":"0.1.0.18.0","extraParams":""} (15:48:10.020)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"QPWg+KD7iADACcANwA1ADkANQAygB2gAYPtg+cD1wPFA8cDzwPWg+TD8eP/QA6AGoAfgB8AIwAggByAF4AQgBFACGAHIAPj/eP4o/jD9EP3Y/qj/GP/o/ggBWACI/xgAWAC4AKj/SP/o/9gAiACIAXADEP2w/XgAoPog+ED2wPeg+SD7CP7oAOAHwAjACcAKwAnACWAF2ACQ/WD7YPjA9ED1QPbA9+D5oPvQ/QgB8ANgBSAGYAfgB+AG4AUgBZAD8AKoAQgACAAI//D8kP1o/kj++P7Y/zgA6ADoAEgAeAD4AOj/qP74/ij/2P5o/kj/IPuw/SgAIPtg+WD5UPwQ/DD88P0Y/+AF4AQgBCAHoAegB5ADyACY/7j+oPvA92D5YPog+iD7cPz4/vgA0ALQA+AEoAagBiAEoAUgBjAD8AI=","callId":"0.1.0.18.0","extraParams":""} (15:48:10.061)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"SP6Y/5gBUANgBGAFIAYgBmAFIARwAmgA8P3g+6D6oPkg+eD5oPtw/Wj/iAHQA+AFYAagBiAGoAWgBDAC2ACoANj/aP6I/tj/qP+Y/zgAmACIAEgA2P9I/xj/mP6Q/Tj+eP6I/tj+KP8o/wj/SADI/xD9cP3Y/lD94PtQ/JD9GP7o/vj+yP/4AbACEANgBGAFYAUgBWAE8AJoASj/0Pyg++D5oPlg+lD80P1YALADoAWgBiAH4AZgBSAEOAHo/vD9kPyg++D7sP1I/gj/aABIAZgBeAFIAagAKACI/3j+iP7Y/pj+2P5I/4j+SP5Y/nj+MP1Q/Vj+KP9YAMgB8AKQAyAEkAOQAugByACo/wj/8P2Q/fD90P0I/qj+OP+I/gj/WP8I/1j/2P9IAKgAiAHIAfgBEAOQAxAD0AKQAogBiAA=","callId":"0.1.0.18.0","extraParams":""} (15:48:10.103)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"6P6I/0gAKAGYAdgBWAE4AGj/6P5o/ij+qP4IADgBUAJwApgBGADw/fD8UP0I/7gAqAG4AXgAmP9Y/4gAiAFoASgAiP7Q/Tj+mP/4AIgBSAFoAPj/eP8Y/zj/2P6I/hj/qABQAjADEAMIARj/OP6w/XD90P1I/xgB0ALQAxADWAFI/uD7oPtQ/RgAyAFwAlgB6P+I/5gA4ATAC6AGwPWA5YDlwPZADYAZgBSgBwgAqABgBdACQPeA7IDrwPfgBsAOwAygBnACmAFYAYj+YPlA9cD14Pu4AeAF4AbgBWAEMAL4//D8oPrg+SD7KP7oAeAE4AVgBHACaAAY/rD90P0I/jj+6P5wAmAFIAUoAVD8oPow/Dj/2ABoADj/CP8oAdADQArADyAFQPCA4IDkYPnADIAVgBBACKAFYAfgB8j+wPA=","callId":"0.1.0.18.0","extraParams":""} (15:48:11.922)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"QPeoAcAKgBKAGYAdgB+AHIAWgBDACbACcPxg+WD4IPgg+KD44PhA98D0QPPA8kDzwPTA9iD4oPmg+3D9KP9oAWAEYAfAC8APgBKAFIAUgBOAEEAM4AcQA8j/WP4w/eD7oPrA9kDwgOuA6oDqgOyA7YDvwPKg+DgAoAfADYASgBWAF4AVgBLADKAHyAEg+8D2wPTA9ED2wPeg+aD6oPrg+qD7cPwQ/RD9MPzg+9D88P2o/7gB8ANgBkAJQAzADUAPwA/ADsAMQAogB+AE8ANQA6gB6P8g+8DygOuA6IDogOqA7YDtgO/A82D6yAFACUAPgBKAFIAVgBOAEMAMQAmgBHj+oPhA9EDyQPLA80D1QPeg+KD6MP24/2gBuABY/nD84Psw/LD9uP+YAfAD4AZACUALQAxADcAMwAtACkAJwAg=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.020)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"wA2gB+AGwAhACkALwA1AD0AOwA1ADcAOgBWAHIAYoAWA6gDZANMA38DykAMgB9gBkP0wA4ARgB0AIYAYMANA8YDogOpA9TgAIARoAWD7IPlw/cj+wPSA5gDZANUA2YDjYPhACYASgBWAEkAOQAvAC0AMQAngBUAIgBCAGIAcgBqAFYAXgBuAF3ADgOUAzQDFAM+A6Hj/wApACWAHQAqAFIAagBfgB8DzgOiA6ED0cANACsAIiAF4/iAEQAn4/4DqANcAzQDTgOTg+cALgBKAEkAPQA5ADoAQgBDAC/ADKAGgB4ASgBiAGIAQwAzAD4AQoASA7QDXAM0A0YDjQPcgBcAIwAhADYAXgB+AHEAOoPiA6oDowPIQA0ANwAxgBbD88P1ACEALIPkA2wDHAMcA2cDxQAqAFoAUwA/ADEAPgBI=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.100)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"gBuAG4AZgBeAFYAUgBWAFEANqP6A74DmgOeA7UDxQPGA7sDyUPwgB0ALoAcgBKAGwA6AFMAP4AUo/rD8qAHgBaAG8AKg+oDvgOaA5YDrQPCA7oDpgOiA7uD4KAFQAzAC8ALACIAQgBSAFYAUgBSAFoAWgBaAFIARwAlY/8D3wPRA9sD2QPTA8cDxQPYw/WgBOACw/BD9MAJACkANwAnQAgj+WP/QAvADmAGQ/aD4QPXA88DzwPNA8YDtgOyA7sDyQPdg+SD6EP0QA0AKQA7AD4ARgBSAGIAZgBeAFYARwAtgBBD9IPhA9sD1QPRA8kDxQPOg+ND80P0w/bj+UAPACUAMwAqgBtAD0AMgBGgBUP3g+ED0QPCA7oDtgOyA64DpgOuA7sDxQPZg+eD7uABgB0AOgBGAE4AXgBqAHYAegB0=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.140)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"gBmAE0ALoARI/+D7IPnA9UDzwPFA80D3IPoQ/Lj+OACwAuAGQAnACMAIwAjACKAHYAQoAGD7QPWA74DqgOeA5oDkgOKA5IDngOxA8sD2IPpI/yAFQAvAD4ASgBSAGIAcgB8AIYAfgBqAFEANYAeQAsj+oPrA9kD0wPPA9SD4YPkg+9D8CP4oASAEYATwA9ADMAOQAxADCAFw/SD4QPKA7YDqgOmA54DlgOaA6IDrQPDA9WD6KADgBUALwA+AEoAUgBaAGYAdgB8AIYAdgBdAD0AIeAHg+8D2QPKA7oDtgO9A8kD2YPoI/tgA4ARACMAKwAvACsAIoAbQAzgBCP7g+kD3wPKA7oDrgOiA54DngOeA6IDqgO7A8sD3EP0wA0AJwA6AEoAVgBaAGIAagBuAG4AagBaAEUAL4AX4/yD7QPc=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.164)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"cAKgBsAKwA6AEoAWgBmAGYAYgBaAFIAQQAxACHADmP/Q/KD64PjA90D3wPfg+CD6YPsQ/dD9OP74/8gAOAD4/3j/kP0w/OD6oPjA9sD1wPTA80DzQPNA88DzQPTA9cD3IPmg+6j+eAEgBcAIwAvADoARgBSAFIATgBKAEEANQApgB5ADKAFI/5D9UPyg+yD74Ptw/Qj+mP5o/zj/aP84AOgAWABo/6j+MP2g+2D6IPnA9kD1wPRA88DywPLA8kDzwPPA9MD2oPig+pD9KAAQA6AGwAlADEAPgBGAE4ATgBOAE4AQwA1AC+AH4ATQAqgAeP7w/KD7oPtQ/HD80PyQ/bD9OP64/wgBKAF4ABgA6P5w/RD8YPrA98D1wPTA8sDxwPBA8MDwQPFA8kD0wPag+RD9KACwA+AHQAtADoARgBQ=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.239)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"gBWAFoAWgBSAEoAQwAxACaAF6AGo/uD7IPlA98D1wPVA9sD2IPig+aD6cPzY/rgAqAG4AcgB+ACo//D94Psg+UD2QPVA80DxQPBA8MDwwPFA80D2oPgQ/Kj/8ALgBkALwA6AEYAUgBeAGIAYgBeAFYATQA9ACyAHsAKo/iD7IPhA9UD0QPNA9ED1wPag+GD6kPyo/sgAUALwAvACsAKYARgA0P2g++D4wPbA9MDyQPFA8MDwQPFA80D1wPeg+lj+mAFgBcAJQA2AEIAUgBaAGIAYgBeAFoATwA9ACyAHcAKQ/aD5wPXA8sDwgO9A8EDxQPNA9qD4YPtY/ggBcANgBSAGIAagBSAEEAJI/3D8IPnA9kD0wPGA74DvgO+A78DxwPTA9mD6iP4wAiAGwApADoARgBWAF4AZgBmAGYAXgBQ=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.260)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"gBHADKAHMANI/iD6wPbA88DxwPDA8MDxwPNA9mD4IPvQ/ZgAsAJgBOAE4ARgBPACCAGY/hD8YPlA90D1wPLA8UDwQPHA8cDzQPXA9yD7uP4wAiAFwAhAC0AOgBCAEoAUgBWAFYAVgBOAEMANwAngBYgBUP2g+UD2wPPA8UDxwPFA8kD0QPZg+OD6cP2Y/3gBkAIwA1AD0AK4ASgAeP5w/KD64PhA90D1wPRA9ED0QPXA9mD4oPqw/agAcAOgBkAJwAvADoAQgBKAE4ATgBOAEsAPwAxACSAF2ACw/CD5wPXA88DxwPFA8kDzQPXA9yD6kPzo/mgBUAPgBGAFoAVgBaAEEAMIAej+sPxg+mD4QPbA9MDzQPPA88D0wPXA9yD6sP3YAPADoAdAC8ANgBCAEoAUgBSAFIAUgBJAD8ALoAc=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.280)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"4AbADoAQgBOAGIAbgBmAGYAYgBWAEoAQwAogBsAIsAJA8sD28PyA5QDfwPOA7wDfgO3IAED3YPlADoARwA6AFoAagBSAE8AOoAawA3D9wPXA8sDxgOyA5oDogOqA54DmgO5A8kDxIPhoALgBIARAC8AOgBCAE4AWgBWAFYAVgBKAEYAQQAngBEALUAOA78D2mP+A5QDdwPTA8wDfgO2gBlgAcPyAEIAZgBOAFoAagBKAEEAOsALg+3D8wPWA7IDtQPCA6YDkgOqA7IDpgO3A80D1oPlYABACoAVADEAOwA6AE4AWgBSAFIAVgBLAD8APQAmgBsAKeP+A7yD4oPmA4wDfwPFA8oDmQPIwAxACoASAEIATgBKAFoAUwAvAC8AKOP5A9mD5QPaA7IDsQPGA7IDogO5A8IDvwPJA9qD4GP4=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.401)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"MANACEAMwA1ADoAQgBKAEYAQQA/ADsANQAxAC0AIIAbgBmAHQAloASD4IPrg+EDxgOyA6oDsgOzA8MD0wPYo/iAGwAlADIAQgBOAEoAQQA7ACBACOP7A98DwgOuA6YDngOWA5oDqgO7A9OD6GADgBcALwA6AEIASgBOAE4ARwA/ADkANQAxACaAGYATwAsgBaAFoAaD7IPig+cD2wPPA8sDzwPHA8cD0wPUg+fD8iADwAyAHwArADMAOQA7ADEALwAjQA/j/MPzA98DzQPCA7oDtgO2A70DywPWg+fD96AGgBUAIwApADEANwA1ADkANQA1ADEALwAmgB+AFsAPYAUgAGP/Q/KD64Png+MD3QPfA9kD2QPZA9yD4oPng+5D9+P/4AfADoAXgBqAHYAcgByAGIARQAogASP4w/CD64Pg=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.440)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"+AH4ABgAKP8o/nD9EP3w/BD9kP0I/pj+SP/4/8gAKAG4ARACcAJwAlACUALoAYgBKAEYASgBKAFIAagB6AHYAcgBaAG4ANj/6P4o/pD9sPxQ/HD80PxQ/Tj+KAB4AXACcAOwA5AD0AOwAzACeP/Q/ZD8IPvg+aD5IPrg+hD8UP2I/uj/KAFwAlAD4ATgBKAEUAJ4AJj/GP4w/dD8sP3Q/Xj++P/YAMgBsAJwA7ADoAdACfADeADY/8j+4Pvg+qD7wPbA9RD8IARgB8AIQAtAC0AJQAvAC6AH6P4g+UD2QPJA8EDwgO2A7cDxQPag+Tj+IATgB8AIQArADMAMQAggBCgAkP3Q/OD7IPug+hD8UP3IAWAFIAagBqAHoAegB0AMQAlQ/MD3wPXA90D34Pig+EDzwPUoAcAOgBHAD4AQwA0=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.498)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"gOwQ/YAWACOAFeAHgBGAGYAQSAFA8IDggOFA8MD2QPJA9FgBQArADEAKKABA9sD3eP4Y/6D72P9gB8ANgBBADGAFMAPgBJAD6P8w/DD8CADgBeAHEANo/3j+4AWAGoAbQPYA1YDiYPqg+4DrgOWA7Ej/gBoAJYAUoAaAE4AegBPo/4DsgOCA5EDyQPSA7IDsYPkgB0AMwAi4/qD48PygBGAEkPzg+tACwAvADUAJCAFI/iAEQAgwAmD6IPvQAsAJwAygB2j/UP2YACAHgBKAEMD0AN+A6jD9IPqA64DmgO94AIAUgBtADqAGgBSAHYASSABA8YDogOvA80D0gO/A8ND9QAlACyAHaAAw/bj/CABg+8D2IPoQA2AHYAbwA7ACYATACEAJ6AEw/NgAQAhACWAFqAAY//gAEAIgBcAMwAs=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.559)
+{"sampleRate":16000,"streamId":"0.1.0.18.0","chunk":1,"chunk_durn_ms":20,"channelId":"","event":"media","payload":"wAjQA0gBOAAoAKAFQApgBuD6wPVg+WD7oPkg+MD3oPoQ/bADgBKAGUAIgOYA34DvYPjA9sDyQPQwA4AdACWAFqAE8ANACOAEoPnA8UD0WABADcALWP5g+SAEQAxQAoDtgOfA8CD64Pog+ED34PrgBkANoAf4AaAFwAvACRACeAFgBGAFIAagB6AFCP+g+zD8IPrA96D4oPrg++D6kPxgBYASgBlIAADbAN3A88D3wPHA8uD7gBEAJwAnwA84/yAFwAo4/0DywPJg+iAFQA7ACaD4QPfgB0AJwPOA4oDpwPcY/hj/kPzg+egAQA7ADLgAqP/ACMAL4AawA6AEoAfADYAQQAloAHD9CP6g+sDzQPHA86D44Ptg+mD48P3ADYARwPMA2YDmYPvg+UD04PmgB4AaACeAHaAHeP9AC0AM4Pk=","callId":"0.1.0.18.0","extraParams":""} (15:48:12.700)

deepgram/__init__.py

@@ -0,0 +1,383 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+# version
+__version__ = "0.0.0"
+
+# entry point for the deepgram python sdk
+import logging
+from .utils import VerboseLogger
+from .utils import (
+    NOTICE,
+    SPAM,
+    SUCCESS,
+    VERBOSE,
+    WARNING,
+    ERROR,
+    FATAL,
+    CRITICAL,
+    INFO,
+    DEBUG,
+    NOTSET,
+)
+
+from .client import Deepgram, DeepgramClient
+from .client import DeepgramClientOptions, ClientOptionsFromEnv
+from .client import (
+    DeepgramError,
+    DeepgramTypeError,
+    DeepgramModuleError,
+    DeepgramApiError,
+    DeepgramUnknownApiError,
+)
+from .errors import DeepgramApiKeyError
+
+# listen/read client
+from .client import ListenRouter, ReadRouter, SpeakRouter, AgentRouter
+
+# common
+from .client import (
+    TextSource,
+    BufferSource,
+    StreamSource,
+    FileSource,
+    UrlSource,
+)
+from .client import BaseResponse
+from .client import (
+    Average,
+    Intent,
+    Intents,
+    IntentsInfo,
+    Segment,
+    SentimentInfo,
+    Sentiment,
+    Sentiments,
+    SummaryInfo,
+    Topic,
+    Topics,
+    TopicsInfo,
+)
+from .client import (
+    ModelInfo,
+    Hit,
+    Search,
+)
+from .client import (
+    OpenResponse,
+    CloseResponse,
+    UnhandledResponse,
+    ErrorResponse,
+)
+
+# speect-to-text WS
+from .client import LiveClient, AsyncLiveClient  # backward compat
+from .client import ListenWebSocketClient, AsyncListenWebSocketClient
+from .client import LiveTranscriptionEvents
+from .client import LiveOptions, ListenWebSocketOptions
+from .client import (
+    #### top level
+    LiveResultResponse,
+    ListenWSMetadataResponse,
+    SpeechStartedResponse,
+    UtteranceEndResponse,
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # UnhandledResponse,
+    # ErrorResponse,
+    #### unique
+    ListenWSMetadata,
+    ListenWSAlternative,
+    ListenWSChannel,
+    ListenWSWord,
+)
+
+# prerecorded
+from .client import PreRecordedClient, AsyncPreRecordedClient  # backward compat
+from .client import ListenRESTClient, AsyncListenRESTClient
+from .client import (
+    # common
+    # UrlSource,
+    # BufferSource,
+    # StreamSource,
+    # TextSource,
+    # FileSource,
+    # unique
+    PreRecordedStreamSource,
+    PrerecordedSource,
+    ListenRestSource,
+    SpeakRESTSource,
+)
+from .client import (
+    ListenRESTOptions,
+    PrerecordedOptions,
+)
+from .client import (
+    #### top level
+    AsyncPrerecordedResponse,
+    PrerecordedResponse,
+    SyncPrerecordedResponse,
+    #### shared
+    # Average,
+    # Alternative,
+    # Channel,
+    # Intent,
+    # Intents,
+    # IntentsInfo,
+    # Segment,
+    # SentimentInfo,
+    # Sentiment,
+    # Sentiments,
+    # SummaryInfo,
+    # Topic,
+    # Topics,
+    # TopicsInfo,
+    # Word,
+    #### unique
+    Entity,
+    Hit,
+    ListenRESTMetadata,
+    ModelInfo,
+    Paragraph,
+    Paragraphs,
+    ListenRESTResults,
+    Search,
+    Sentence,
+    Summaries,
+    SummaryV1,
+    SummaryV2,
+    Translation,
+    Utterance,
+    Warning,
+    ListenRESTAlternative,
+    ListenRESTChannel,
+    ListenRESTWord,
+)
+
+# read
+from .client import ReadClient, AsyncReadClient
+from .client import AnalyzeClient, AsyncAnalyzeClient
+from .client import (
+    AnalyzeOptions,
+    AnalyzeStreamSource,
+    AnalyzeSource,
+)
+from .client import (
+    #### top level
+    AsyncAnalyzeResponse,
+    SyncAnalyzeResponse,
+    AnalyzeResponse,
+    #### shared
+    # Average,
+    # Intent,
+    # Intents,
+    # IntentsInfo,
+    # Segment,
+    # SentimentInfo,
+    # Sentiment,
+    # Sentiments,
+    # SummaryInfo,
+    # Topic,
+    # Topics,
+    # TopicsInfo,
+    #### unique
+    AnalyzeMetadata,
+    AnalyzeResults,
+    AnalyzeSummary,
+)
+
+# speak
+## speak REST
+from .client import (
+    #### top level
+    SpeakRESTOptions,
+    SpeakOptions,  # backward compat
+    #### common
+    # TextSource,
+    # BufferSource,
+    # StreamSource,
+    # FileSource,
+    #### unique
+    SpeakSource,
+    SpeakRestSource,
+)
+
+from .client import (
+    SpeakClient,  # backward compat
+    SpeakRESTClient,
+    AsyncSpeakRESTClient,
+)
+
+from .client import (
+    SpeakResponse,  # backward compat
+    SpeakRESTResponse,
+)
+
+## speak WebSocket
+from .client import SpeakWebSocketEvents, SpeakWebSocketMessage
+
+from .client import (
+    SpeakWSOptions,
+)
+
+from .client import (
+    SpeakWebSocketClient,
+    AsyncSpeakWebSocketClient,
+    SpeakWSClient,
+    AsyncSpeakWSClient,
+)
+
+from .client import (
+    #### top level
+    SpeakWSMetadataResponse,
+    FlushedResponse,
+    ClearedResponse,
+    WarningResponse,
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # UnhandledResponse,
+    # ErrorResponse,
+)
+
+# manage
+from .client import ManageClient, AsyncManageClient
+from .client import (
+    ProjectOptions,
+    KeyOptions,
+    ScopeOptions,
+    InviteOptions,
+    UsageRequestOptions,
+    UsageSummaryOptions,
+    UsageFieldsOptions,
+)
+
+# manage client responses
+from .client import (
+    #### top level
+    Message,
+    ProjectsResponse,
+    ModelResponse,
+    ModelsResponse,
+    MembersResponse,
+    KeyResponse,
+    KeysResponse,
+    ScopesResponse,
+    InvitesResponse,
+    UsageRequest,
+    UsageResponse,
+    UsageRequestsResponse,
+    UsageSummaryResponse,
+    UsageFieldsResponse,
+    BalancesResponse,
+    #### shared
+    Project,
+    STTDetails,
+    TTSMetadata,
+    TTSDetails,
+    Member,
+    Key,
+    Invite,
+    Config,
+    STTUsageDetails,
+    Callback,
+    TokenDetail,
+    SpeechSegment,
+    TTSUsageDetails,
+    STTTokens,
+    TTSTokens,
+    UsageSummaryResults,
+    Resolution,
+    UsageModel,
+    Balance,
+)
+
+# selfhosted
+from .client import (
+    OnPremClient,
+    AsyncOnPremClient,
+    SelfHostedClient,
+    AsyncSelfHostedClient,
+)
+
+
+# agent
+from .client import AgentWebSocketEvents
+
+# websocket
+from .client import (
+    AgentWebSocketClient,
+    AsyncAgentWebSocketClient,
+)
+
+from .client import (
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # ErrorResponse,
+    # UnhandledResponse,
+    #### unique
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+)
+
+from .client import (
+    # top level
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+    # sub level
+    Listen,
+    ListenProvider,
+    Speak,
+    SpeakProvider,
+    Header,
+    Item,
+    Properties,
+    Parameters,
+    Function,
+    Think,
+    ThinkProvider,
+    Agent,
+    Input,
+    Output,
+    Audio,
+    Endpoint,
+)
+
+# utilities
+# pylint: disable=wrong-import-position
+from .audio import Microphone, DeepgramMicrophoneError
+from .audio import (
+    INPUT_LOGGING,
+    INPUT_CHANNELS,
+    INPUT_RATE,
+    INPUT_CHUNK,
+)
+
+LOGGING = INPUT_LOGGING
+CHANNELS = INPUT_CHANNELS
+RATE = INPUT_RATE
+CHUNK = INPUT_CHUNK
+
+from .audio import Speaker
+from .audio import (
+    OUTPUT_LOGGING,
+    OUTPUT_CHANNELS,
+    OUTPUT_RATE,
+    OUTPUT_CHUNK,
+)
+
+# pylint: enable=wrong-import-position

deepgram/audio/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from .microphone import Microphone
+from .microphone import DeepgramMicrophoneError
+from .microphone import (
+    LOGGING as INPUT_LOGGING,
+    CHANNELS as INPUT_CHANNELS,
+    RATE as INPUT_RATE,
+    CHUNK as INPUT_CHUNK,
+)
+
+from .speaker import Speaker
+from .speaker import DeepgramSpeakerError
+from .speaker import (
+    LOGGING as OUTPUT_LOGGING,
+    CHANNELS as OUTPUT_CHANNELS,
+    RATE as OUTPUT_RATE,
+    CHUNK as OUTPUT_CHUNK,
+    PLAYBACK_DELTA as OUTPUT_PLAYBACK_DELTA,
+)

deepgram/audio/microphone/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from .microphone import Microphone
+from .constants import LOGGING, CHANNELS, RATE, CHUNK
+from .errors import DeepgramMicrophoneError

deepgram/audio/microphone/constants.py

@@ -0,0 +1,11 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from ...utils import verboselogs
+
+# Constants for microphone
+LOGGING = verboselogs.WARNING
+CHANNELS = 1
+RATE = 16000
+CHUNK = 8194

deepgram/audio/microphone/errors.py

@@ -0,0 +1,21 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+
+# exceptions for microphone
+class DeepgramMicrophoneError(Exception):
+    """
+    Exception raised for known errors related to Microphone library.
+
+    Attributes:
+        message (str): The error message describing the exception.
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.name = "DeepgramMicrophoneError"
+        self.message = message
+
+    def __str__(self):
+        return f"{self.name}: {self.message}"

deepgram/audio/microphone/microphone.py

@@ -0,0 +1,302 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+import inspect
+import asyncio
+import threading
+from typing import Optional, Callable, Union, TYPE_CHECKING
+import logging
+
+from ...utils import verboselogs
+
+from .constants import LOGGING, CHANNELS, RATE, CHUNK
+
+if TYPE_CHECKING:
+    import pyaudio
+
+
+class Microphone:  # pylint: disable=too-many-instance-attributes
+    """
+    This implements a microphone for local audio input. This uses PyAudio under the hood.
+    """
+
+    _logger: verboselogs.VerboseLogger
+
+    _audio: Optional["pyaudio.PyAudio"] = None
+    _stream: Optional["pyaudio.Stream"] = None
+
+    _chunk: int
+    _rate: int
+    _format: int
+    _channels: int
+    _input_device_index: Optional[int]
+    _is_muted: bool
+
+    _asyncio_loop: asyncio.AbstractEventLoop
+    _asyncio_thread: Optional[threading.Thread] = None
+    _exit: threading.Event
+
+    _push_callback_org: Optional[Callable] = None
+    _push_callback: Optional[Callable] = None
+
+    def __init__(
+        self,
+        push_callback: Optional[Callable] = None,
+        verbose: int = LOGGING,
+        rate: int = RATE,
+        chunk: int = CHUNK,
+        channels: int = CHANNELS,
+        input_device_index: Optional[int] = None,
+    ):  # pylint: disable=too-many-positional-arguments
+        # dynamic import of pyaudio as not to force the requirements on the SDK (and users)
+        import pyaudio  # pylint: disable=import-outside-toplevel
+
+        self._logger = verboselogs.VerboseLogger(__name__)
+        self._logger.addHandler(logging.StreamHandler())
+        self._logger.setLevel(verbose)
+
+        self._exit = threading.Event()
+
+        self._audio = pyaudio.PyAudio()
+        self._chunk = chunk
+        self._rate = rate
+        self._format = pyaudio.paInt16
+        self._channels = channels
+        self._is_muted = False
+
+        self._input_device_index = input_device_index
+        self._push_callback_org = push_callback
+
+    def _start_asyncio_loop(self) -> None:
+        self._asyncio_loop = asyncio.new_event_loop()
+        self._asyncio_loop.run_forever()
+
+    def is_active(self) -> bool:
+        """
+        is_active - returns the state of the stream
+
+        Args:
+            None
+
+        Returns:
+            True if the stream is active, False otherwise
+        """
+        self._logger.debug("Microphone.is_active ENTER")
+
+        if self._stream is None:
+            self._logger.error("stream is None")
+            self._logger.debug("Microphone.is_active LEAVE")
+            return False
+
+        val = self._stream.is_active()
+        self._logger.info("is_active: %s", val)
+        self._logger.info("is_exiting: %s", self._exit.is_set())
+        self._logger.debug("Microphone.is_active LEAVE")
+        return val
+
+    def set_callback(self, push_callback: Callable) -> None:
+        """
+        set_callback - sets the callback function to be called when data is received.
+
+        Args:
+            push_callback (Callable): The callback function to be called when data is received.
+                                      This should be the websocket send function.
+
+        Returns:
+            None
+        """
+        self._push_callback_org = push_callback
+
+    def start(self) -> bool:
+        """
+        starts - starts the microphone stream
+
+        Returns:
+            bool: True if the stream was started, False otherwise
+        """
+        self._logger.debug("Microphone.start ENTER")
+
+        self._logger.info("format: %s", self._format)
+        self._logger.info("channels: %d", self._channels)
+        self._logger.info("rate: %d", self._rate)
+        self._logger.info("chunk: %d", self._chunk)
+        # self._logger.info("input_device_id: %d", self._input_device_index)
+
+        if self._push_callback_org is None:
+            self._logger.error("start failed. No callback set.")
+            self._logger.debug("Microphone.start LEAVE")
+            return False
+
+        if inspect.iscoroutinefunction(self._push_callback_org):
+            self._logger.verbose("async/await callback - wrapping")
+            # Run our own asyncio loop.
+            self._asyncio_thread = threading.Thread(target=self._start_asyncio_loop)
+            self._asyncio_thread.start()
+
+            self._push_callback = lambda data: (
+                asyncio.run_coroutine_threadsafe(
+                    self._push_callback_org(data), self._asyncio_loop
+                ).result()
+                if self._push_callback_org
+                else None
+            )
+        else:
+            self._logger.verbose("regular threaded callback")
+            self._asyncio_thread = None
+            self._push_callback = self._push_callback_org
+
+        if self._audio is not None:
+            self._stream = self._audio.open(
+                format=self._format,
+                channels=self._channels,
+                rate=self._rate,
+                input=True,
+                output=False,
+                frames_per_buffer=self._chunk,
+                input_device_index=self._input_device_index,
+                stream_callback=self._callback,
+            )
+
+        if self._stream is None:
+            self._logger.error("start failed. No stream created.")
+            self._logger.debug("Microphone.start LEAVE")
+            return False
+
+        self._exit.clear()
+        if self._stream is not None:
+            self._stream.start_stream()
+
+        self._logger.notice("start succeeded")
+        self._logger.debug("Microphone.start LEAVE")
+        return True
+
+    def mute(self) -> bool:
+        """
+        mute - mutes the microphone stream
+
+        Returns:
+            bool: True if the stream was muted, False otherwise
+        """
+        self._logger.verbose("Microphone.mute ENTER")
+
+        if self._stream is None:
+            self._logger.error("mute failed. Library not initialized.")
+            self._logger.verbose("Microphone.mute LEAVE")
+            return False
+
+        self._is_muted = True
+
+        self._logger.notice("mute succeeded")
+        self._logger.verbose("Microphone.mute LEAVE")
+        return True
+
+    def unmute(self) -> bool:
+        """
+        unmute - unmutes the microphone stream
+
+        Returns:
+            bool: True if the stream was unmuted, False otherwise
+        """
+        self._logger.verbose("Microphone.unmute ENTER")
+
+        if self._stream is None:
+            self._logger.error("unmute failed. Library not initialized.")
+            self._logger.verbose("Microphone.unmute LEAVE")
+            return False
+
+        self._is_muted = False
+
+        self._logger.notice("unmute succeeded")
+        self._logger.verbose("Microphone.unmute LEAVE")
+        return True
+
+    def is_muted(self) -> bool:
+        """
+        is_muted - returns the state of the stream
+
+        Args:
+            None
+
+        Returns:
+            True if the stream is muted, False otherwise
+        """
+        self._logger.spam("Microphone.is_muted ENTER")
+
+        if self._stream is None:
+            self._logger.spam("is_muted: stream is None")
+            self._logger.spam("Microphone.is_muted LEAVE")
+            return False
+
+        val = self._is_muted
+
+        self._logger.spam("is_muted: %s", val)
+        self._logger.spam("Microphone.is_muted LEAVE")
+        return val
+
+    def finish(self) -> bool:
+        """
+        finish - stops the microphone stream
+
+        Returns:
+            bool: True if the stream was stopped, False otherwise
+        """
+        self._logger.debug("Microphone.finish ENTER")
+
+        self._logger.notice("signal exit")
+        self._exit.set()
+
+        # Stop the stream.
+        if self._stream is not None:
+            self._logger.notice("stopping stream...")
+            self._stream.stop_stream()
+            self._stream.close()
+            self._logger.notice("stream stopped")
+
+        # clean up the thread
+        if (
+            # inspect.iscoroutinefunction(self._push_callback_org)
+            # and
+            self._asyncio_thread
+            is not None
+        ):
+            self._logger.notice("stopping _asyncio_loop...")
+            self._asyncio_loop.call_soon_threadsafe(self._asyncio_loop.stop)
+            self._asyncio_thread.join()
+            self._logger.notice("_asyncio_thread joined")
+        self._stream = None
+        self._asyncio_thread = None
+
+        self._logger.notice("finish succeeded")
+        self._logger.debug("Microphone.finish LEAVE")
+
+        return True
+
+    def _callback(
+        self, input_data, frame_count, time_info, status_flags
+    ):  # pylint: disable=unused-argument
+        """
+        The callback used to process data in callback mode.
+        """
+        # dynamic import of pyaudio as not to force the requirements on the SDK (and users)
+        import pyaudio  # pylint: disable=import-outside-toplevel
+
+        if self._exit.is_set():
+            self._logger.notice("_callback exit is Set. stopping...")
+            return None, pyaudio.paAbort
+
+        if input_data is None:
+            self._logger.warning("input_data is None")
+            return None, pyaudio.paContinue
+
+        try:
+            if self._is_muted:
+                size = len(input_data)
+                input_data = b"\x00" * size
+
+            self._push_callback(input_data)
+        except Exception as e:
+            self._logger.error("Error while sending: %s", str(e))
+            raise
+
+        return input_data, pyaudio.paContinue

deepgram/audio/speaker/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from .speaker import Speaker
+from .errors import DeepgramSpeakerError
+from .constants import LOGGING, CHANNELS, RATE, CHUNK, PLAYBACK_DELTA

deepgram/audio/speaker/constants.py

@@ -0,0 +1,15 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from ...utils import verboselogs
+
+# Constants for speaker
+LOGGING = verboselogs.WARNING
+TIMEOUT = 0.050
+CHANNELS = 1
+RATE = 16000
+CHUNK = 8194
+
+# Constants for speaker
+PLAYBACK_DELTA = 2000

deepgram/audio/speaker/errors.py

@@ -0,0 +1,21 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+
+# exceptions for speaker
+class DeepgramSpeakerError(Exception):
+    """
+    Exception raised for known errors related to Speaker library.
+
+    Attributes:
+        message (str): The error message describing the exception.
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.name = "DeepgramSpeakerError"
+        self.message = message
+
+    def __str__(self):
+        return f"{self.name}: {self.message}"

deepgram/audio/speaker/speaker.py

@@ -0,0 +1,380 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+import asyncio
+import inspect
+import queue
+import threading
+from typing import Optional, Callable, Union, TYPE_CHECKING
+import logging
+from datetime import datetime
+
+import websockets
+
+from ...utils import verboselogs
+from .constants import LOGGING, CHANNELS, RATE, CHUNK, TIMEOUT, PLAYBACK_DELTA
+
+from ..microphone import Microphone
+
+if TYPE_CHECKING:
+    import pyaudio
+
+HALF_SECOND = 0.5
+
+
+class Speaker:  # pylint: disable=too-many-instance-attributes
+    """
+    This implements a speaker for local audio output. This uses PyAudio under the hood.
+    """
+
+    _logger: verboselogs.VerboseLogger
+
+    _audio: Optional["pyaudio.PyAudio"] = None
+    _stream: Optional["pyaudio.Stream"] = None
+
+    _chunk: int
+    _rate: int
+    _channels: int
+    _output_device_index: Optional[int] = None
+
+    # last time we received audio
+    _last_datagram: datetime = datetime.now()
+    _last_play_delta_in_ms: int
+    _lock_wait: threading.Lock
+
+    _queue: queue.Queue
+    _exit: threading.Event
+
+    _thread: Optional[threading.Thread] = None
+    # _asyncio_loop: asyncio.AbstractEventLoop
+    # _asyncio_thread: threading.Thread
+    _receiver_thread: Optional[threading.Thread] = None
+    _loop: Optional[asyncio.AbstractEventLoop] = None
+
+    _push_callback_org: Optional[Callable] = None
+    _push_callback: Optional[Callable] = None
+    _pull_callback_org: Optional[Callable] = None
+    _pull_callback: Optional[Callable] = None
+
+    _microphone: Optional[Microphone] = None
+
+    def __init__(
+        self,
+        pull_callback: Optional[Callable] = None,
+        push_callback: Optional[Callable] = None,
+        verbose: int = LOGGING,
+        rate: int = RATE,
+        chunk: int = CHUNK,
+        channels: int = CHANNELS,
+        last_play_delta_in_ms: int = PLAYBACK_DELTA,
+        output_device_index: Optional[int] = None,
+        microphone: Optional[Microphone] = None,
+    ):  # pylint: disable=too-many-positional-arguments
+        # dynamic import of pyaudio as not to force the requirements on the SDK (and users)
+        import pyaudio  # pylint: disable=import-outside-toplevel
+
+        self._logger = verboselogs.VerboseLogger(__name__)
+        self._logger.addHandler(logging.StreamHandler())
+        self._logger.setLevel(verbose)
+
+        self._exit = threading.Event()
+        self._queue = queue.Queue()
+
+        self._last_datagram = datetime.now()
+        self._lock_wait = threading.Lock()
+
+        self._microphone = microphone
+
+        self._audio = pyaudio.PyAudio()
+        self._chunk = chunk
+        self._rate = rate
+        self._format = pyaudio.paInt16
+        self._channels = channels
+        self._last_play_delta_in_ms = last_play_delta_in_ms
+        self._output_device_index = output_device_index
+
+        self._push_callback_org = push_callback
+        self._pull_callback_org = pull_callback
+
+    def set_push_callback(self, push_callback: Callable) -> None:
+        """
+        set_push_callback - sets the callback function to be called when data is sent.
+
+        Args:
+            push_callback (Callable): The callback function to be called when data is send.
+                                      This should be the websocket handle message function.
+
+        Returns:
+            None
+        """
+        self._push_callback_org = push_callback
+
+    def set_pull_callback(self, pull_callback: Callable) -> None:
+        """
+        set_pull_callback - sets the callback function to be called when data is received.
+
+        Args:
+            pull_callback (Callable): The callback function to be called when data is received.
+                                      This should be the websocket recv function.
+
+        Returns:
+            None
+        """
+        self._pull_callback_org = pull_callback
+
+    def start(self, active_loop: Optional[asyncio.AbstractEventLoop] = None) -> bool:
+        """
+        starts - starts the Speaker stream
+
+        Args:
+            socket (Union[SyncClientConnection, AsyncClientConnection]): The socket to receive audio data from.
+
+        Returns:
+            bool: True if the stream was started, False otherwise
+        """
+        self._logger.debug("Speaker.start ENTER")
+
+        self._logger.info("format: %s", self._format)
+        self._logger.info("channels: %d", self._channels)
+        self._logger.info("rate: %d", self._rate)
+        self._logger.info("chunk: %d", self._chunk)
+        # self._logger.info("output_device_id: %d", self._output_device_index)
+
+        # Automatically get the current running event loop
+        if inspect.iscoroutinefunction(self._push_callback_org) and active_loop is None:
+            self._logger.verbose("get default running asyncio loop")
+            self._loop = asyncio.get_running_loop()
+
+        self._exit.clear()
+        self._queue = queue.Queue()
+
+        if self._audio is not None:
+            self._stream = self._audio.open(
+                format=self._format,
+                channels=self._channels,
+                rate=self._rate,
+                input=False,
+                output=True,
+                frames_per_buffer=self._chunk,
+                output_device_index=self._output_device_index,
+            )
+
+        if self._stream is None:
+            self._logger.error("start failed. No stream created.")
+            self._logger.debug("Speaker.start LEAVE")
+            return False
+
+        self._push_callback = self._push_callback_org
+        self._pull_callback = self._pull_callback_org
+
+        # start the play thread
+        self._thread = threading.Thread(
+            target=self._play, args=(self._queue, self._stream, self._exit), daemon=True
+        )
+        self._thread.start()
+
+        # Start the stream
+        if self._stream is not None:
+            self._stream.start_stream()
+
+        # Start the receiver thread within the start function
+        self._logger.verbose("Starting receiver thread...")
+        self._receiver_thread = threading.Thread(target=self._start_receiver)
+        self._receiver_thread.start()
+
+        self._logger.notice("start succeeded")
+        self._logger.debug("Speaker.start LEAVE")
+
+        return True
+
+    def wait_for_complete_with_mute(self, mic: Microphone):
+        """
+        This method will mute/unmute a Microphone and block until the speak is done playing sound.
+        """
+        self._logger.debug("Speaker.wait_for_complete ENTER")
+
+        if self._microphone is not None:
+            mic.mute()
+        self.wait_for_complete()
+        if self._microphone is not None:
+            mic.unmute()
+
+        self._logger.debug("Speaker.wait_for_complete LEAVE")
+
+    def wait_for_complete(self):
+        """
+        This method will block until the speak is done playing sound.
+        """
+        self._logger.debug("Speaker.wait_for_complete ENTER")
+
+        delta_in_ms = float(self._last_play_delta_in_ms)
+        self._logger.debug("Last Play delta: %f", delta_in_ms)
+
+        # set to now
+        with self._lock_wait:
+            self._last_datagram = datetime.now()
+
+        while True:
+            # sleep for a bit
+            self._exit.wait(HALF_SECOND)
+
+            # check if we should exit
+            if self._exit.is_set():
+                self._logger.debug("Exiting wait_for_complete _exit is set")
+                break
+
+            # check the time
+            with self._lock_wait:
+                delta = datetime.now() - self._last_datagram
+                diff_in_ms = delta.total_seconds() * 1000
+                if diff_in_ms < delta_in_ms:
+                    self._logger.debug("LastPlay delta is less than threshold")
+                    continue
+
+            # if we get here, we are done playing audio
+            self._logger.debug("LastPlay delta is greater than threshold. Exit wait!")
+            break
+
+        self._logger.debug("Speaker.wait_for_complete LEAVE")
+
+    def _start_receiver(self):
+        # Check if the socket is an asyncio WebSocket
+        if inspect.iscoroutinefunction(self._pull_callback_org):
+            self._logger.verbose("Starting asyncio receiver...")
+            asyncio.run_coroutine_threadsafe(self._start_asyncio_receiver(), self._loop)
+        else:
+            self._logger.verbose("Starting threaded receiver...")
+            self._start_threaded_receiver()
+
+    async def _start_asyncio_receiver(self):
+        try:
+            while True:
+                if self._exit.is_set():
+                    self._logger.verbose("Exiting receiver thread...")
+                    break
+
+                message = await self._pull_callback()
+                if message is None:
+                    self._logger.verbose("No message received...")
+                    continue
+
+                if isinstance(message, str):
+                    self._logger.verbose("Received control message...")
+                    await self._push_callback(message)
+                elif isinstance(message, bytes):
+                    self._logger.verbose("Received audio data...")
+                    await self._push_callback(message)
+                    self.add_audio_to_queue(message)
+        except websockets.exceptions.ConnectionClosedOK as e:
+            self._logger.debug("send() exiting gracefully: %d", e.code)
+        except websockets.exceptions.ConnectionClosed as e:
+            if e.code in [1000, 1001]:
+                self._logger.debug("send() exiting gracefully: %d", e.code)
+                return
+            self._logger.error("_start_asyncio_receiver - ConnectionClosed: %s", str(e))
+        except websockets.exceptions.WebSocketException as e:
+            self._logger.error(
+                "_start_asyncio_receiver- WebSocketException: %s", str(e)
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            self._logger.error("_start_asyncio_receiver exception: %s", str(e))
+
+    def _start_threaded_receiver(self):
+        try:
+            while True:
+                if self._exit.is_set():
+                    self._logger.verbose("Exiting receiver thread...")
+                    break
+
+                message = self._pull_callback()
+                if message is None:
+                    self._logger.verbose("No message received...")
+                    continue
+
+                if isinstance(message, str):
+                    self._logger.verbose("Received control message...")
+                    self._push_callback(message)
+                elif isinstance(message, bytes):
+                    self._logger.verbose("Received audio data...")
+                    self._push_callback(message)
+                    self.add_audio_to_queue(message)
+        except Exception as e:  # pylint: disable=broad-except
+            self._logger.notice("_start_threaded_receiver exception: %s", str(e))
+
+    def add_audio_to_queue(self, data: bytes) -> None:
+        """
+        add_audio_to_queue - adds audio data to the Speaker queue
+
+        Args:
+            data (bytes): The audio data to add to the queue
+        """
+        self._queue.put(data)
+
+    def finish(self) -> bool:
+        """
+        finish - stops the Speaker stream
+
+        Returns:
+            bool: True if the stream was stopped, False otherwise
+        """
+        self._logger.debug("Speaker.finish ENTER")
+
+        self._logger.notice("signal exit")
+        self._exit.set()
+
+        if self._stream is not None:
+            self._logger.notice("stopping stream...")
+            self._stream.stop_stream()
+            self._stream.close()
+            self._logger.notice("stream stopped")
+
+        if self._thread is not None:
+            self._logger.notice("joining _thread...")
+            self._thread.join()
+            self._logger.notice("thread stopped")
+
+        if self._receiver_thread is not None:
+            self._logger.notice("stopping _receiver_thread...")
+            self._receiver_thread.join()
+            self._logger.notice("_receiver_thread joined")
+
+        with self._queue.mutex:
+            self._queue.queue.clear()
+
+        self._stream = None
+        self._thread = None
+        self._receiver_thread = None
+
+        self._logger.notice("finish succeeded")
+        self._logger.debug("Speaker.finish LEAVE")
+
+        return True
+
+    def _play(self, audio_out, stream, stop):
+        """
+        _play - plays audio data from the Speaker queue callback for portaudio
+        """
+        while not stop.is_set():
+            try:
+                if self._microphone is not None and self._microphone.is_muted():
+                    with self._lock_wait:
+                        delta = datetime.now() - self._last_datagram
+                        diff_in_ms = delta.total_seconds() * 1000
+                        if diff_in_ms > float(self._last_play_delta_in_ms):
+                            self._logger.debug(
+                                "LastPlay delta is greater than threshold. Unmute!"
+                            )
+                            self._microphone.unmute()
+
+                data = audio_out.get(True, TIMEOUT)
+                with self._lock_wait:
+                    self._last_datagram = datetime.now()
+                    if self._microphone is not None and not self._microphone.is_muted():
+                        self._logger.debug("New speaker sound detected. Mute!")
+                        self._microphone.mute()
+                stream.write(data)
+            except queue.Empty:
+                pass
+            except Exception as e:  # pylint: disable=broad-except
+                self._logger.error("_play exception: %s", str(e))

deepgram/client.py

@@ -0,0 +1,669 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from typing import Optional
+from importlib import import_module
+import os
+import logging
+import deprecation  # type: ignore
+
+from . import __version__
+from .utils import verboselogs
+
+# common
+# pylint: disable=unused-import
+from .clients import (
+    TextSource,
+    BufferSource,
+    StreamSource,
+    FileSource,
+    UrlSource,
+)
+from .clients import BaseResponse
+from .clients import (
+    Average,
+    Intent,
+    Intents,
+    IntentsInfo,
+    Segment,
+    SentimentInfo,
+    Sentiment,
+    Sentiments,
+    SummaryInfo,
+    Topic,
+    Topics,
+    TopicsInfo,
+)
+from .clients import (
+    ModelInfo,
+    Hit,
+    Search,
+)
+from .clients import (
+    OpenResponse,
+    CloseResponse,
+    UnhandledResponse,
+    ErrorResponse,
+)
+from .clients import (
+    DeepgramError,
+    DeepgramTypeError,
+    DeepgramModuleError,
+    DeepgramApiError,
+    DeepgramUnknownApiError,
+)
+
+# listen client
+from .clients import ListenRouter, ReadRouter, SpeakRouter, AgentRouter
+
+# speech-to-text
+from .clients import LiveClient, AsyncLiveClient  # backward compat
+from .clients import (
+    ListenWebSocketClient,
+    AsyncListenWebSocketClient,
+)
+from .clients import (
+    ListenWebSocketOptions,
+    LiveOptions,
+    LiveTranscriptionEvents,
+)
+
+# live client responses
+from .clients import (
+    #### top level
+    LiveResultResponse,
+    ListenWSMetadataResponse,
+    SpeechStartedResponse,
+    UtteranceEndResponse,
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # ErrorResponse,
+    # UnhandledResponse,
+    #### unique
+    ListenWSMetadata,
+    ListenWSAlternative,
+    ListenWSChannel,
+    ListenWSWord,
+)
+
+# prerecorded
+from .clients import (
+    # common
+    # UrlSource,
+    # BufferSource,
+    # StreamSource,
+    # TextSource,
+    # FileSource,
+    # unique
+    PreRecordedStreamSource,
+    PrerecordedSource,
+    ListenRestSource,
+)
+
+from .clients import (
+    PreRecordedClient,
+    AsyncPreRecordedClient,
+)  # backward compat
+from .clients import (
+    ListenRESTClient,
+    AsyncListenRESTClient,
+)
+from .clients import (
+    ListenRESTOptions,
+    PrerecordedOptions,
+)
+
+# rest client responses
+from .clients import (
+    #### top level
+    AsyncPrerecordedResponse,
+    PrerecordedResponse,
+    SyncPrerecordedResponse,
+    #### shared
+    # Average,
+    # Intent,
+    # Intents,
+    # IntentsInfo,
+    # Segment,
+    # SentimentInfo,
+    # Sentiment,
+    # Sentiments,
+    # SummaryInfo,
+    # Topic,
+    # Topics,
+    # TopicsInfo,
+    #### between rest and websocket
+    # ModelInfo,
+    # Alternative,
+    # Hit,
+    # Search,
+    # Channel,
+    # Word,
+    # unique
+    Entity,
+    ListenRESTMetadata,
+    Paragraph,
+    Paragraphs,
+    ListenRESTResults,
+    Sentence,
+    Summaries,
+    SummaryV1,
+    SummaryV2,
+    Translation,
+    Utterance,
+    Warning,
+    ListenRESTAlternative,
+    ListenRESTChannel,
+    ListenRESTWord,
+)
+
+# read
+from .clients import ReadClient, AsyncReadClient
+from .clients import AnalyzeClient, AsyncAnalyzeClient
+from .clients import (
+    AnalyzeOptions,
+    AnalyzeStreamSource,
+    AnalyzeSource,
+)
+
+# read client responses
+from .clients import (
+    #### top level
+    AsyncAnalyzeResponse,
+    SyncAnalyzeResponse,
+    AnalyzeResponse,
+    #### shared
+    # Average,
+    # Intent,
+    # Intents,
+    # IntentsInfo,
+    # Segment,
+    # SentimentInfo,
+    # Sentiment,
+    # Sentiments,
+    # SummaryInfo,
+    # Topic,
+    # Topics,
+    # TopicsInfo,
+    #### unique
+    AnalyzeMetadata,
+    AnalyzeResults,
+    AnalyzeSummary,
+)
+
+# speak
+## speak REST
+from .clients import (
+    #### top level
+    SpeakRESTOptions,
+    SpeakOptions,  # backward compat
+    #### common
+    # TextSource,
+    # BufferSource,
+    # StreamSource,
+    # FileSource,
+    #### unique
+    SpeakSource,
+    SpeakRestSource,
+    SpeakRESTSource,
+)
+
+from .clients import (
+    SpeakClient,  # backward compat
+    SpeakRESTClient,
+    AsyncSpeakRESTClient,
+)
+
+from .clients import (
+    SpeakResponse,  # backward compat
+    SpeakRESTResponse,
+)
+
+## speak WebSocket
+from .clients import SpeakWebSocketEvents, SpeakWebSocketMessage
+
+from .clients import (
+    SpeakWSOptions,
+)
+
+from .clients import (
+    SpeakWebSocketClient,
+    AsyncSpeakWebSocketClient,
+    SpeakWSClient,
+    AsyncSpeakWSClient,
+)
+
+from .clients import (
+    #### top level
+    SpeakWSMetadataResponse,
+    FlushedResponse,
+    ClearedResponse,
+    WarningResponse,
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # UnhandledResponse,
+    # ErrorResponse,
+)
+
+# auth client classes
+from .clients import AuthRESTClient, AsyncAuthRESTClient
+
+# auth client responses
+from .clients import (
+    GrantTokenResponse,
+)
+
+# manage client classes/input
+from .clients import ManageClient, AsyncManageClient
+from .clients import (
+    ProjectOptions,
+    KeyOptions,
+    ScopeOptions,
+    InviteOptions,
+    UsageRequestOptions,
+    UsageSummaryOptions,
+    UsageFieldsOptions,
+)
+
+# manage client responses
+from .clients import (
+    #### top level
+    Message,
+    ProjectsResponse,
+    ModelResponse,
+    ModelsResponse,
+    MembersResponse,
+    KeyResponse,
+    KeysResponse,
+    ScopesResponse,
+    InvitesResponse,
+    UsageRequest,
+    UsageResponse,
+    UsageRequestsResponse,
+    UsageSummaryResponse,
+    UsageFieldsResponse,
+    BalancesResponse,
+    #### shared
+    Project,
+    STTDetails,
+    TTSMetadata,
+    TTSDetails,
+    Member,
+    Key,
+    Invite,
+    Config,
+    STTUsageDetails,
+    Callback,
+    TokenDetail,
+    SpeechSegment,
+    TTSUsageDetails,
+    STTTokens,
+    TTSTokens,
+    UsageSummaryResults,
+    Resolution,
+    UsageModel,
+    Balance,
+)
+
+# on-prem
+from .clients import (
+    OnPremClient,
+    AsyncOnPremClient,
+    SelfHostedClient,
+    AsyncSelfHostedClient,
+)
+
+
+# agent
+from .clients import AgentWebSocketEvents
+
+# websocket
+from .clients import (
+    AgentWebSocketClient,
+    AsyncAgentWebSocketClient,
+)
+
+from .clients import (
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # ErrorResponse,
+    # UnhandledResponse,
+    #### unique
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+)
+
+from .clients import (
+    # top level
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+    # sub level
+    Listen,
+    ListenProvider,
+    Speak,
+    SpeakProvider,
+    Header,
+    Item,
+    Properties,
+    Parameters,
+    Function,
+    Think,
+    ThinkProvider,
+    Agent,
+    Input,
+    Output,
+    Audio,
+    Endpoint,
+)
+
+
+# client errors and options
+from .options import DeepgramClientOptions, ClientOptionsFromEnv
+from .errors import DeepgramApiKeyError
+
+# pylint: enable=unused-import
+
+
+class Deepgram:  # pylint: disable=broad-exception-raised
+    """
+    The Deepgram class is no longer a class in version 3 of this SDK.
+    """
+
+    def __init__(self, *anything):
+        raise Exception(
+            """
+            FATAL ERROR:
+            You are attempting to instantiate a Deepgram object, which is no longer a class in version 3 of this SDK.
+
+            To fix this issue:
+                1. You need to revert to the previous version 2 of the SDK: pip install deepgram-sdk==2.12.0
+                2. or, update your application's code to use version 3 of this SDK. See the README for more information.
+
+            Things to consider:
+
+                - This Version 3 of the SDK requires Python 3.10 or higher.
+                  Older versions (3.9 and lower) of Python are nearing end-of-life: https://devguide.python.org/versions/
+                  Understand the risks of using a version of Python nearing EOL.
+
+                - Version 2 of the SDK will receive maintenance updates in the form of security fixes only.
+                  No new features will be added to version 2 of the SDK.
+            """
+        )
+
+
+class DeepgramClient:
+    """
+    Represents a client for interacting with the Deepgram API.
+
+    This class provides a client for making requests to the Deepgram API with various configuration options.
+
+    Attributes:
+        api_key (str): The Deepgram API key used for authentication.
+        config_options (DeepgramClientOptions): An optional configuration object specifying client options.
+
+    Raises:
+        DeepgramApiKeyError: If the API key is missing or invalid.
+
+    Methods:
+        listen: Returns a ListenClient instance for interacting with Deepgram's transcription services.
+
+        manage: (Preferred) Returns a Threaded ManageClient instance for managing Deepgram resources.
+        selfhosted: (Preferred) Returns an Threaded SelfHostedClient instance for interacting with Deepgram's on-premises API.
+
+        asyncmanage: Returns an (Async) ManageClient instance for managing Deepgram resources.
+        asyncselfhosted: Returns an (Async) SelfHostedClient instance for interacting with Deepgram's on-premises API.
+    """
+
+    _config: DeepgramClientOptions
+    _logger: verboselogs.VerboseLogger
+
+    def __init__(
+        self,
+        api_key: str = "",
+        config: Optional[DeepgramClientOptions] = None,
+    ):
+        self._logger = verboselogs.VerboseLogger(__name__)
+        self._logger.addHandler(logging.StreamHandler())
+
+        if api_key == "" and config is not None:
+            self._logger.info("Attempting to set API key from config object")
+            api_key = config.api_key
+        if api_key == "":
+            self._logger.info("Attempting to set API key from environment variable")
+            api_key = os.getenv("DEEPGRAM_API_KEY", "")
+        if api_key == "":
+            self._logger.warning("WARNING: API key is missing")
+
+        self.api_key = api_key
+        if config is None:  # Use default configuration
+            self._config = DeepgramClientOptions(self.api_key)
+        else:
+            config.set_apikey(self.api_key)
+            self._config = config
+
+    @property
+    def listen(self):
+        """
+        Returns a Listen dot-notation router for interacting with Deepgram's transcription services.
+        """
+        return ListenRouter(self._config)
+
+    @property
+    def read(self):
+        """
+        Returns a Read dot-notation router for interacting with Deepgram's read services.
+        """
+        return ReadRouter(self._config)
+
+    @property
+    def speak(self):
+        """
+        Returns a Speak dot-notation router for interacting with Deepgram's speak services.
+        """
+        return SpeakRouter(self._config)
+
+    @property
+    @deprecation.deprecated(
+        deprecated_in="3.4.0",
+        removed_in="4.0.0",
+        current_version=__version__,
+        details="deepgram.asyncspeak is deprecated. Use deepgram.speak.asyncrest instead.",
+    )
+    def asyncspeak(self):
+        """
+        DEPRECATED: deepgram.asyncspeak is deprecated. Use deepgram.speak.asyncrest instead.
+        """
+        return self.Version(self._config, "asyncspeak")
+
+    @property
+    def manage(self):
+        """
+        Returns a ManageClient instance for managing Deepgram resources.
+        """
+        return self.Version(self._config, "manage")
+
+    @property
+    def asyncmanage(self):
+        """
+        Returns an AsyncManageClient instance for managing Deepgram resources.
+        """
+        return self.Version(self._config, "asyncmanage")
+
+    @property
+    def auth(self):
+        """
+        Returns an AuthRESTClient instance for managing short-lived tokens.
+        """
+        return self.Version(self._config, "auth")
+
+    @property
+    def asyncauth(self):
+        """
+        Returns an AsyncAuthRESTClient instance for managing short-lived tokens.
+        """
+        return self.Version(self._config, "asyncauth")
+
+    @property
+    @deprecation.deprecated(
+        deprecated_in="3.4.0",
+        removed_in="4.0.0",
+        current_version=__version__,
+        details="deepgram.onprem is deprecated. Use deepgram.speak.selfhosted instead.",
+    )
+    def onprem(self):
+        """
+        DEPRECATED: deepgram.onprem is deprecated. Use deepgram.speak.selfhosted instead.
+        """
+        return self.Version(self._config, "selfhosted")
+
+    @property
+    def selfhosted(self):
+        """
+        Returns an SelfHostedClient instance for interacting with Deepgram's on-premises API.
+        """
+        return self.Version(self._config, "selfhosted")
+
+    @property
+    @deprecation.deprecated(
+        deprecated_in="3.4.0",
+        removed_in="4.0.0",
+        current_version=__version__,
+        details="deepgram.asynconprem is deprecated. Use deepgram.speak.asyncselfhosted instead.",
+    )
+    def asynconprem(self):
+        """
+        DEPRECATED: deepgram.asynconprem is deprecated. Use deepgram.speak.asyncselfhosted instead.
+        """
+        return self.Version(self._config, "asyncselfhosted")
+
+    @property
+    def asyncselfhosted(self):
+        """
+        Returns an AsyncSelfHostedClient instance for interacting with Deepgram's on-premises API.
+        """
+        return self.Version(self._config, "asyncselfhosted")
+
+    @property
+    def agent(self):
+        """
+        Returns a Agent dot-notation router for interacting with Deepgram's speak services.
+        """
+        return AgentRouter(self._config)
+
+    # INTERNAL CLASSES
+    class Version:
+        """
+        Represents a version of the Deepgram API.
+        """
+
+        _logger: verboselogs.VerboseLogger
+        _config: DeepgramClientOptions
+        _parent: str
+
+        def __init__(self, config, parent: str):
+            self._logger = verboselogs.VerboseLogger(__name__)
+            self._logger.addHandler(logging.StreamHandler())
+            self._logger.setLevel(config.verbose)
+
+            self._config = config
+            self._parent = parent
+
+        # FUTURE VERSIONING:
+        # When v2 or v1.1beta1 or etc. This allows easy access to the latest version of the API.
+        # @property
+        # def latest(self):
+        #     match self._parent:
+        #         case "manage":
+        #             return ManageClient(self._config)
+        #         case "selfhosted":
+        #             return SelfHostedClient(self._config)
+        #         case _:
+        #             raise DeepgramModuleError("Invalid parent")
+
+        def v(self, version: str = ""):
+            # pylint: disable-msg=too-many-statements
+            """
+            Returns a client for the specified version of the API.
+            """
+            self._logger.debug("Version.v ENTER")
+            self._logger.info("version: %s", version)
+            if len(version) == 0:
+                self._logger.error("version is empty")
+                self._logger.debug("Version.v LEAVE")
+                raise DeepgramModuleError("Invalid module version")
+
+            parent = ""
+            filename = ""
+            classname = ""
+            match self._parent:
+                case "manage":
+                    parent = "manage"
+                    filename = "client"
+                    classname = "ManageClient"
+                case "asyncmanage":
+                    parent = "manage"
+                    filename = "async_client"
+                    classname = "AsyncManageClient"
+                case "asyncspeak":
+                    return AsyncSpeakRESTClient(self._config)
+                case "selfhosted":
+                    parent = "selfhosted"
+                    filename = "client"
+                    classname = "SelfHostedClient"
+                case "asyncselfhosted":
+                    parent = "selfhosted"
+                    filename = "async_client"
+                    classname = "AsyncSelfHostedClient"
+                case "auth":
+                    parent = "auth"
+                    filename = "client"
+                    classname = "AuthRESTClient"
+                case "asyncauth":
+                    parent = "auth"
+                    filename = "async_client"
+                    classname = "AsyncAuthRESTClient"
+                case _:
+                    self._logger.error("parent unknown: %s", self._parent)
+                    self._logger.debug("Version.v LEAVE")
+                    raise DeepgramModuleError("Invalid parent type")
+
+            # create class path
+            path = f"deepgram.clients.{parent}.v{version}.{filename}"
+            self._logger.info("path: %s", path)
+            self._logger.info("classname: %s", classname)
+
+            # import class
+            mod = import_module(path)
+            if mod is None:
+                self._logger.error("module path is None")
+                self._logger.debug("Version.v LEAVE")
+                raise DeepgramModuleError("Unable to find package")
+
+            my_class = getattr(mod, classname)
+            if my_class is None:
+                self._logger.error("my_class is None")
+                self._logger.debug("Version.v LEAVE")
+                raise DeepgramModuleError("Unable to find class")
+
+            # instantiate class
+            my_class_instance = my_class(self._config)
+            self._logger.notice("Version.v succeeded")
+            self._logger.debug("Version.v LEAVE")
+            return my_class_instance
+
+        # pylint: enable-msg=too-many-statements

deepgram/clients/__init__.py

@@ -0,0 +1,381 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+# common
+from .common import (
+    TextSource,
+    BufferSource,
+    StreamSource,
+    FileSource,
+    UrlSource,
+)
+from .common import BaseResponse
+
+# common (shared between analze and prerecorded)
+from .common import (
+    Average,
+    Intent,
+    Intents,
+    IntentsInfo,
+    Segment,
+    SentimentInfo,
+    Sentiment,
+    Sentiments,
+    SummaryInfo,
+    Topic,
+    Topics,
+    TopicsInfo,
+)
+
+# common (shared between listen rest and websocket)
+from .common import (
+    ModelInfo,
+    Hit,
+    Search,
+)
+from .common import (
+    OpenResponse,
+    CloseResponse,
+    UnhandledResponse,
+    ErrorResponse,
+)
+from .common import (
+    DeepgramError,
+    DeepgramTypeError,
+    DeepgramApiError,
+    DeepgramUnknownApiError,
+)
+from .errors import DeepgramModuleError
+
+from .listen_router import ListenRouter
+from .read_router import ReadRouter
+from .speak_router import SpeakRouter
+from .agent_router import AgentRouter
+
+# listen
+from .listen import LiveTranscriptionEvents
+
+## backward compat
+from .prerecorded import (
+    PreRecordedClient,
+    AsyncPreRecordedClient,
+)
+from .live import (
+    LiveClient,
+    AsyncLiveClient,
+)
+
+# speech-to-text rest
+from .listen import ListenRESTClient, AsyncListenRESTClient
+
+## input
+from .listen import (
+    # common
+    # UrlSource,
+    # BufferSource,
+    # StreamSource,
+    # TextSource,
+    # FileSource,
+    # unique
+    PreRecordedStreamSource,
+    PrerecordedSource,
+    ListenRestSource,
+)
+
+from .listen import (
+    ListenRESTOptions,
+    PrerecordedOptions,
+)
+
+## output
+from .listen import (
+    #### top level
+    AsyncPrerecordedResponse,
+    PrerecordedResponse,
+    SyncPrerecordedResponse,
+    #### shared
+    # Average,
+    # Intent,
+    # Intents,
+    # IntentsInfo,
+    # Segment,
+    # SentimentInfo,
+    # Sentiment,
+    # Sentiments,
+    # SummaryInfo,
+    # Topic,
+    # Topics,
+    # TopicsInfo,
+    #### between rest and websocket
+    # ModelInfo,
+    # Alternative,
+    # Hit,
+    # Search,
+    # Channel,
+    # Word,
+    # unique
+    Entity,
+    ListenRESTMetadata,
+    Paragraph,
+    Paragraphs,
+    ListenRESTResults,
+    Sentence,
+    Summaries,
+    SummaryV1,
+    SummaryV2,
+    Translation,
+    Utterance,
+    Warning,
+    ListenRESTAlternative,
+    ListenRESTChannel,
+    ListenRESTWord,
+)
+
+
+# speech-to-text websocket
+from .listen import ListenWebSocketClient, AsyncListenWebSocketClient
+
+## input
+from .listen import (
+    ListenWebSocketOptions,
+    LiveOptions,
+)
+
+## output
+from .listen import (
+    #### top level
+    LiveResultResponse,
+    ListenWSMetadataResponse,
+    SpeechStartedResponse,
+    UtteranceEndResponse,
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # ErrorResponse,
+    # UnhandledResponse,
+    #### uniqye
+    ListenWSMetadata,
+    ListenWSWord,
+    ListenWSAlternative,
+    ListenWSChannel,
+)
+
+## clients
+from .listen import (
+    ListenWebSocketClient,
+    AsyncListenWebSocketClient,
+)
+
+
+# read/analyze
+from .analyze import ReadClient, AsyncReadClient
+from .analyze import AnalyzeClient, AsyncAnalyzeClient
+from .analyze import AnalyzeOptions
+from .analyze import (
+    # common
+    # UrlSource,
+    # TextSource,
+    # BufferSource,
+    # StreamSource,
+    # FileSource
+    # unique
+    AnalyzeStreamSource,
+    AnalyzeSource,
+)
+from .analyze import (
+    #### top level
+    AsyncAnalyzeResponse,
+    SyncAnalyzeResponse,
+    AnalyzeResponse,
+    #### shared between analyze and pre-recorded
+    # Average,
+    # Intent,
+    # Intents,
+    # IntentsInfo,
+    # Segment,
+    # SentimentInfo,
+    # Sentiment,
+    # Sentiments,
+    # SummaryInfo,
+    # Topic,
+    # Topics,
+    # TopicsInfo,
+    #### unique
+    AnalyzeMetadata,
+    AnalyzeResults,
+    AnalyzeSummary,
+)
+
+# text-to-speech
+## text-to-speech REST
+from .speak import (
+    #### top level
+    SpeakRESTOptions,
+    SpeakOptions,
+    # common
+    # TextSource,
+    # BufferSource,
+    # StreamSource,
+    # FileSource,
+    # unique
+    SpeakSource,
+    SpeakRestSource,
+    SpeakRESTSource,
+)
+
+from .speak import (
+    SpeakClient,  # backward compat
+    SpeakRESTClient,
+    AsyncSpeakRESTClient,
+)
+
+from .speak import (
+    SpeakResponse,  # backward compat
+    SpeakRESTResponse,
+)
+
+## text-to-speech WebSocket
+from .speak import SpeakWebSocketEvents, SpeakWebSocketMessage
+
+from .speak import (
+    SpeakWSOptions,
+)
+
+from .speak import (
+    SpeakWebSocketClient,
+    AsyncSpeakWebSocketClient,
+    SpeakWSClient,
+    AsyncSpeakWSClient,
+)
+
+from .speak import (
+    #### top level
+    SpeakWSMetadataResponse,
+    FlushedResponse,
+    ClearedResponse,
+    WarningResponse,
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # UnhandledResponse,
+    # ErrorResponse,
+)
+
+# manage
+from .manage import ManageClient, AsyncManageClient
+from .manage import (
+    ProjectOptions,
+    KeyOptions,
+    ScopeOptions,
+    InviteOptions,
+    UsageRequestOptions,
+    UsageSummaryOptions,
+    UsageFieldsOptions,
+)
+from .manage import (
+    #### top level
+    Message,
+    ProjectsResponse,
+    ModelResponse,
+    ModelsResponse,
+    MembersResponse,
+    KeyResponse,
+    KeysResponse,
+    ScopesResponse,
+    InvitesResponse,
+    UsageRequest,
+    UsageResponse,
+    UsageRequestsResponse,
+    UsageSummaryResponse,
+    UsageFieldsResponse,
+    BalancesResponse,
+    #### shared
+    Project,
+    STTDetails,
+    TTSMetadata,
+    TTSDetails,
+    Member,
+    Key,
+    Invite,
+    Config,
+    STTUsageDetails,
+    Callback,
+    TokenDetail,
+    SpeechSegment,
+    TTSUsageDetails,
+    STTTokens,
+    TTSTokens,
+    UsageSummaryResults,
+    Resolution,
+    UsageModel,
+    Balance,
+)
+
+# auth
+from .auth import AuthRESTClient, AsyncAuthRESTClient
+from .auth import (
+    GrantTokenResponse,
+)
+
+# selfhosted
+from .selfhosted import (
+    OnPremClient,
+    AsyncOnPremClient,
+    SelfHostedClient,
+    AsyncSelfHostedClient,
+)
+
+# agent
+from .agent import AgentWebSocketEvents
+
+# websocket
+from .agent import (
+    AgentWebSocketClient,
+    AsyncAgentWebSocketClient,
+)
+
+from .agent import (
+    #### common websocket response
+    # OpenResponse,
+    # CloseResponse,
+    # ErrorResponse,
+    # UnhandledResponse,
+    #### unique
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+)
+
+from .agent import (
+    # top level
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+    # sub level
+    Listen,
+    ListenProvider,
+    Speak,
+    SpeakProvider,
+    Header,
+    Item,
+    Properties,
+    Parameters,
+    Function,
+    Think,
+    ThinkProvider,
+    Agent,
+    Input,
+    Output,
+    Audio,
+    Endpoint,
+)

deepgram/clients/agent/__init__.py

@@ -0,0 +1,56 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from .enums import AgentWebSocketEvents
+
+# websocket
+from .client import (
+    AgentWebSocketClient,
+    AsyncAgentWebSocketClient,
+)
+
+from .client import (
+    #### common websocket response
+    OpenResponse,
+    CloseResponse,
+    ErrorResponse,
+    UnhandledResponse,
+    #### unique
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+)
+
+from .client import (
+    # top level
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+    # sub level
+    Listen,
+    ListenProvider,
+    Speak,
+    SpeakProvider,
+    Header,
+    Item,
+    Properties,
+    Parameters,
+    Function,
+    Think,
+    ThinkProvider,
+    Agent,
+    Input,
+    Output,
+    Audio,
+    Endpoint,
+)

deepgram/clients/agent/client.py

@@ -0,0 +1,102 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+# websocket
+from .v1 import (
+    AgentWebSocketClient as LatestAgentWebSocketClient,
+    AsyncAgentWebSocketClient as LatestAsyncAgentWebSocketClient,
+)
+
+from .v1 import (
+    #### common websocket response
+    BaseResponse as LatestBaseResponse,
+    OpenResponse as LatestOpenResponse,
+    CloseResponse as LatestCloseResponse,
+    ErrorResponse as LatestErrorResponse,
+    UnhandledResponse as LatestUnhandledResponse,
+    #### unique
+    WelcomeResponse as LatestWelcomeResponse,
+    SettingsAppliedResponse as LatestSettingsAppliedResponse,
+    ConversationTextResponse as LatestConversationTextResponse,
+    UserStartedSpeakingResponse as LatestUserStartedSpeakingResponse,
+    AgentThinkingResponse as LatestAgentThinkingResponse,
+    FunctionCallRequest as LatestFunctionCallRequest,
+    AgentStartedSpeakingResponse as LatestAgentStartedSpeakingResponse,
+    AgentAudioDoneResponse as LatestAgentAudioDoneResponse,
+    InjectionRefusedResponse as LatestInjectionRefusedResponse,
+)
+
+from .v1 import (
+    # top level
+    SettingsOptions as LatestSettingsOptions,
+    UpdatePromptOptions as LatestUpdatePromptOptions,
+    UpdateSpeakOptions as LatestUpdateSpeakOptions,
+    InjectAgentMessageOptions as LatestInjectAgentMessageOptions,
+    FunctionCallResponse as LatestFunctionCallResponse,
+    AgentKeepAlive as LatestAgentKeepAlive,
+    # sub level
+    Listen as LatestListen,
+    ListenProvider as LatestListenProvider,
+    Speak as LatestSpeak,
+    SpeakProvider as LatestSpeakProvider,
+    Header as LatestHeader,
+    Item as LatestItem,
+    Properties as LatestProperties,
+    Parameters as LatestParameters,
+    Function as LatestFunction,
+    Think as LatestThink,
+    ThinkProvider as LatestThinkProvider,
+    Agent as LatestAgent,
+    Input as LatestInput,
+    Output as LatestOutput,
+    Audio as LatestAudio,
+    Endpoint as LatestEndpoint,
+)
+
+
+# The vX/client.py points to the current supported version in the SDK.
+# Older versions are supported in the SDK for backwards compatibility.
+
+AgentWebSocketClient = LatestAgentWebSocketClient
+AsyncAgentWebSocketClient = LatestAsyncAgentWebSocketClient
+
+OpenResponse = LatestOpenResponse
+CloseResponse = LatestCloseResponse
+ErrorResponse = LatestErrorResponse
+UnhandledResponse = LatestUnhandledResponse
+
+WelcomeResponse = LatestWelcomeResponse
+SettingsAppliedResponse = LatestSettingsAppliedResponse
+ConversationTextResponse = LatestConversationTextResponse
+UserStartedSpeakingResponse = LatestUserStartedSpeakingResponse
+AgentThinkingResponse = LatestAgentThinkingResponse
+FunctionCallRequest = LatestFunctionCallRequest
+AgentStartedSpeakingResponse = LatestAgentStartedSpeakingResponse
+AgentAudioDoneResponse = LatestAgentAudioDoneResponse
+InjectionRefusedResponse = LatestInjectionRefusedResponse
+
+
+SettingsOptions = LatestSettingsOptions
+UpdatePromptOptions = LatestUpdatePromptOptions
+UpdateSpeakOptions = LatestUpdateSpeakOptions
+InjectAgentMessageOptions = LatestInjectAgentMessageOptions
+FunctionCallResponse = LatestFunctionCallResponse
+AgentKeepAlive = LatestAgentKeepAlive
+
+Listen = LatestListen
+ListenProvider = LatestListenProvider
+Speak = LatestSpeak
+SpeakProvider = LatestSpeakProvider
+Header = LatestHeader
+Item = LatestItem
+Properties = LatestProperties
+Parameters = LatestParameters
+Function = LatestFunction
+Think = LatestThink
+ThinkProvider = LatestThinkProvider
+Agent = LatestAgent
+Input = LatestInput
+Output = LatestOutput
+Audio = LatestAudio
+Endpoint = LatestEndpoint

deepgram/clients/agent/enums.py

@@ -0,0 +1,36 @@
+# Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from aenum import StrEnum
+
+# Constants mapping to events from the Deepgram API
+
+
+class AgentWebSocketEvents(StrEnum):
+    """
+    Enumerates the possible Agent API events that can be received from the Deepgram API
+    """
+
+    # server
+    Open: str = "Open"
+    Close: str = "Close"
+    AudioData: str = "AudioData"
+    Welcome: str = "Welcome"
+    SettingsApplied: str = "SettingsApplied"
+    ConversationText: str = "ConversationText"
+    UserStartedSpeaking: str = "UserStartedSpeaking"
+    AgentThinking: str = "AgentThinking"
+    FunctionCallRequest: str = "FunctionCallRequest"
+    AgentStartedSpeaking: str = "AgentStartedSpeaking"
+    AgentAudioDone: str = "AgentAudioDone"
+    Error: str = "Error"
+    Unhandled: str = "Unhandled"
+
+    # client
+    Settings: str = "Settings"
+    UpdatePrompt: str = "UpdatePrompt"
+    UpdateSpeak: str = "UpdateSpeak"
+    InjectAgentMessage: str = "InjectAgentMessage"
+    InjectionRefused: str = "InjectionRefused"
+    AgentKeepAlive: str = "AgentKeepAlive"

deepgram/clients/agent/v1/__init__.py

@@ -0,0 +1,60 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+# common websocket
+from ...common import (
+    OpenResponse,
+    CloseResponse,
+    UnhandledResponse,
+    ErrorResponse,
+)
+
+# websocket
+from .websocket import AgentWebSocketClient, AsyncAgentWebSocketClient
+
+from .websocket import (
+    #### common websocket response
+    BaseResponse,
+    OpenResponse,
+    CloseResponse,
+    ErrorResponse,
+    UnhandledResponse,
+    #### unique
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+)
+
+from .websocket import (
+    # top level
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+    # sub level
+    Listen,
+    ListenProvider,
+    Speak,
+    SpeakProvider,
+    Header,
+    Item,
+    Properties,
+    Parameters,
+    Function,
+    Think,
+    ThinkProvider,
+    Agent,
+    Input,
+    Output,
+    Audio,
+    Endpoint,
+)

deepgram/clients/agent/v1/websocket/__init__.py

@@ -0,0 +1,51 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from .client import AgentWebSocketClient
+from .async_client import AsyncAgentWebSocketClient
+
+from .response import (
+    #### common websocket response
+    BaseResponse,
+    OpenResponse,
+    CloseResponse,
+    ErrorResponse,
+    UnhandledResponse,
+    #### unique
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+)
+from .options import (
+    # top level
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+    # sub level
+    Listen,
+    ListenProvider,
+    Speak,
+    SpeakProvider,
+    Header,
+    Item,
+    Properties,
+    Parameters,
+    Function,
+    Think,
+    ThinkProvider,
+    Agent,
+    Input,
+    Output,
+    Audio,
+    Endpoint,
+)

deepgram/clients/agent/v1/websocket/async_client.py

@@ -0,0 +1,688 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+import asyncio
+import json
+import logging
+from typing import Dict, Union, Optional, cast, Any, Callable
+import threading
+
+from .....utils import verboselogs
+from .....options import DeepgramClientOptions
+from ...enums import AgentWebSocketEvents
+from ....common import AbstractAsyncWebSocketClient
+from ....common import DeepgramError
+
+from .response import (
+    OpenResponse,
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+    CloseResponse,
+    ErrorResponse,
+    UnhandledResponse,
+)
+from .options import (
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+)
+
+from .....audio.speaker import (
+    Speaker,
+    RATE as SPEAKER_RATE,
+    CHANNELS as SPEAKER_CHANNELS,
+    PLAYBACK_DELTA as SPEAKER_PLAYBACK_DELTA,
+)
+from .....audio.microphone import (
+    Microphone,
+    RATE as MICROPHONE_RATE,
+    CHANNELS as MICROPHONE_CHANNELS,
+)
+
+ONE_SECOND = 1
+HALF_SECOND = 0.5
+DEEPGRAM_INTERVAL = 5
+
+
+class AsyncAgentWebSocketClient(
+    AbstractAsyncWebSocketClient
+):  # pylint: disable=too-many-instance-attributes
+    """
+    Client for interacting with Deepgram's live transcription services over WebSockets.
+
+     This class provides methods to establish a WebSocket connection for live transcription and handle real-time transcription events.
+
+     Args:
+         config (DeepgramClientOptions): all the options for the client.
+    """
+
+    _logger: verboselogs.VerboseLogger
+    _config: DeepgramClientOptions
+    _endpoint: str
+
+    _event_handlers: Dict[AgentWebSocketEvents, list]
+
+    _keep_alive_thread: Union[asyncio.Task, None]
+
+    _kwargs: Optional[Dict] = None
+    _addons: Optional[Dict] = None
+    # note the distinction here. We can't use _config because it's already used in the parent
+    _settings: Optional[SettingsOptions] = None
+    _headers: Optional[Dict] = None
+
+    _speaker_created: bool = False
+    _speaker: Optional[Speaker] = None
+    _microphone_created: bool = False
+    _microphone: Optional[Microphone] = None
+
+    def __init__(self, config: DeepgramClientOptions):
+        if config is None:
+            raise DeepgramError("Config is required")
+
+        self._logger = verboselogs.VerboseLogger(__name__)
+        self._logger.addHandler(logging.StreamHandler())
+        self._logger.setLevel(config.verbose)
+
+        self._config = config
+
+        # needs to be "wss://agent.deepgram.com/agent"
+        self._endpoint = "v1/agent/converse"
+
+        # override the endpoint since it needs to be "wss://agent.deepgram.com/agent"
+        self._config.url = "agent.deepgram.com"
+        self._keep_alive_thread = None
+
+        # init handlers
+        self._event_handlers = {
+            event: [] for event in AgentWebSocketEvents.__members__.values()
+        }
+
+        if self._config.options.get("microphone_record") == "true":
+            self._logger.info("microphone_record is enabled")
+            rate = self._config.options.get("microphone_record_rate", MICROPHONE_RATE)
+            channels = self._config.options.get(
+                "microphone_record_channels", MICROPHONE_CHANNELS
+            )
+            device_index = self._config.options.get("microphone_record_device_index")
+
+            self._logger.debug("rate: %s", rate)
+            self._logger.debug("channels: %s", channels)
+            if device_index is not None:
+                self._logger.debug("device_index: %s", device_index)
+
+            self._microphone_created = True
+
+            if device_index is not None:
+                self._microphone = Microphone(
+                    rate=rate,
+                    channels=channels,
+                    verbose=self._config.verbose,
+                    input_device_index=device_index,
+                )
+            else:
+                self._microphone = Microphone(
+                    rate=rate,
+                    channels=channels,
+                    verbose=self._config.verbose,
+                )
+
+        if self._config.options.get("speaker_playback") == "true":
+            self._logger.info("speaker_playback is enabled")
+            rate = self._config.options.get("speaker_playback_rate", SPEAKER_RATE)
+            channels = self._config.options.get(
+                "speaker_playback_channels", SPEAKER_CHANNELS
+            )
+            playback_delta_in_ms = self._config.options.get(
+                "speaker_playback_delta_in_ms", SPEAKER_PLAYBACK_DELTA
+            )
+            device_index = self._config.options.get("speaker_playback_device_index")
+
+            self._logger.debug("rate: %s", rate)
+            self._logger.debug("channels: %s", channels)
+
+            self._speaker_created = True
+
+            if device_index is not None:
+                self._logger.debug("device_index: %s", device_index)
+
+                self._speaker = Speaker(
+                    rate=rate,
+                    channels=channels,
+                    last_play_delta_in_ms=playback_delta_in_ms,
+                    verbose=self._config.verbose,
+                    output_device_index=device_index,
+                    microphone=self._microphone,
+                )
+            else:
+                self._speaker = Speaker(
+                    rate=rate,
+                    channels=channels,
+                    last_play_delta_in_ms=playback_delta_in_ms,
+                    verbose=self._config.verbose,
+                    microphone=self._microphone,
+                )
+        # call the parent constructor
+        super().__init__(self._config, self._endpoint)
+
+    # pylint: disable=too-many-branches,too-many-statements
+    async def start(
+        self,
+        options: Optional[SettingsOptions] = None,
+        addons: Optional[Dict] = None,
+        headers: Optional[Dict] = None,
+        members: Optional[Dict] = None,
+        **kwargs,
+    ) -> bool:
+        """
+        Starts the WebSocket connection for agent API.
+        """
+        self._logger.debug("AsyncAgentWebSocketClient.start ENTER")
+        self._logger.info("settings: %s", options)
+        self._logger.info("addons: %s", addons)
+        self._logger.info("headers: %s", headers)
+        self._logger.info("members: %s", members)
+        self._logger.info("kwargs: %s", kwargs)
+
+        if isinstance(options, SettingsOptions) and not options.check():
+            self._logger.error("settings.check failed")
+            self._logger.debug("AsyncAgentWebSocketClient.start LEAVE")
+            raise DeepgramError("Fatal agent settings error")
+
+        self._addons = addons
+        self._headers = headers
+
+        # add "members" as members of the class
+        if members is not None:
+            self.__dict__.update(members)
+
+        # set kwargs as members of the class
+        if kwargs is not None:
+            self._kwargs = kwargs
+        else:
+            self._kwargs = {}
+
+        if isinstance(options, SettingsOptions):
+            self._logger.info("options is class")
+            self._settings = options
+        elif isinstance(options, dict):
+            self._logger.info("options is dict")
+            self._settings = SettingsOptions.from_dict(options)
+        elif isinstance(options, str):
+            self._logger.info("options is json")
+            self._settings = SettingsOptions.from_json(options)
+        else:
+            raise DeepgramError("Invalid options type")
+
+        if self._settings.agent.listen.provider.keyterms is not None and self._settings.agent.listen.provider.model is not None and not self._settings.agent.listen.provider.model.startswith("nova-3"):
+            raise DeepgramError("Keyterms are only supported for nova-3 models")
+
+        try:
+            # speaker substitutes the listening thread
+            if self._speaker is not None:
+                self._logger.notice("passing speaker to delegate_listening")
+                super().delegate_listening(self._speaker)
+
+            # call parent start
+            if (
+                await super().start(
+                    {},
+                    self._addons,
+                    self._headers,
+                    **dict(cast(Dict[Any, Any], self._kwargs)),
+                )
+                is False
+            ):
+                self._logger.error("AsyncAgentWebSocketClient.start failed")
+                self._logger.debug("AsyncAgentWebSocketClient.start LEAVE")
+                return False
+
+            if self._speaker is not None:
+                self._logger.notice("speaker is delegate_listening. Starting speaker")
+                self._speaker.start()
+
+            if self._speaker is not None and self._microphone is not None:
+                self._logger.notice(
+                    "speaker is delegate_listening. Starting microphone"
+                )
+                self._microphone.set_callback(self.send)
+                self._microphone.start()
+
+            # debug the threads
+            for thread in threading.enumerate():
+                self._logger.debug("after running thread: %s", thread.name)
+            self._logger.debug("number of active threads: %s", threading.active_count())
+
+            # keepalive thread
+            if self._config.is_keep_alive_enabled():
+                self._logger.notice("keepalive is enabled")
+                self._keep_alive_thread = asyncio.create_task(self._keep_alive())
+            else:
+                self._logger.notice("keepalive is disabled")
+
+            # debug the threads
+            for thread in threading.enumerate():
+                self._logger.debug("after running thread: %s", thread.name)
+            self._logger.debug("number of active threads: %s", threading.active_count())
+
+            # send the configurationsetting message
+            self._logger.notice("Sending Settings...")
+            ret_send_cs = await self.send(str(self._settings))
+            if not ret_send_cs:
+                self._logger.error("Settings failed")
+
+                err_error: ErrorResponse = ErrorResponse(
+                    "Exception in AsyncAgentWebSocketClient.start",
+                    "Settings failed to send",
+                    "Exception",
+                )
+                await self._emit(
+                    AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                    error=err_error,
+                    **dict(cast(Dict[Any, Any], self._kwargs)),
+                )
+
+                self._logger.debug("AgentWebSocketClient.start LEAVE")
+                return False
+
+            self._logger.notice("start succeeded")
+            self._logger.debug("AsyncAgentWebSocketClient.start LEAVE")
+            return True
+
+        except Exception as e:  # pylint: disable=broad-except
+            self._logger.error(
+                "WebSocketException in AsyncAgentWebSocketClient.start: %s", e
+            )
+            self._logger.debug("AsyncAgentWebSocketClient.start LEAVE")
+            if self._config.options.get("termination_exception_connect") is True:
+                raise e
+            return False
+
+    # pylint: enable=too-many-branches,too-many-statements
+
+    def on(self, event: AgentWebSocketEvents, handler: Callable) -> None:
+        """
+        Registers event handlers for specific events.
+        """
+        self._logger.info("event subscribed: %s", event)
+        if event in AgentWebSocketEvents.__members__.values() and callable(handler):
+            self._event_handlers[event].append(handler)
+
+    async def _emit(self, event: AgentWebSocketEvents, *args, **kwargs) -> None:
+        """
+        Emits events to the registered event handlers.
+        """
+        self._logger.debug("AsyncAgentWebSocketClient._emit ENTER")
+        self._logger.debug("callback handlers for: %s", event)
+
+        # debug the threads
+        for thread in threading.enumerate():
+            self._logger.debug("after running thread: %s", thread.name)
+        self._logger.debug("number of active threads: %s", threading.active_count())
+
+        self._logger.debug("callback handlers for: %s", event)
+        tasks = []
+        for handler in self._event_handlers[event]:
+            task = asyncio.create_task(handler(self, *args, **kwargs))
+            tasks.append(task)
+
+        if tasks:
+            self._logger.debug("waiting for tasks to finish...")
+            await asyncio.gather(*tasks, return_exceptions=True)
+            tasks.clear()
+
+        # debug the threads
+        for thread in threading.enumerate():
+            self._logger.debug("after running thread: %s", thread.name)
+        self._logger.debug("number of active threads: %s", threading.active_count())
+
+        self._logger.debug("AsyncAgentWebSocketClient._emit LEAVE")
+
+    # pylint: disable=too-many-locals,too-many-statements
+    async def _process_text(self, message: str) -> None:
+        """
+        Processes messages received over the WebSocket connection.
+        """
+        self._logger.debug("AsyncAgentWebSocketClient._process_text ENTER")
+
+        try:
+            self._logger.debug("Text data received")
+            if len(message) == 0:
+                self._logger.debug("message is empty")
+                self._logger.debug("AsyncAgentWebSocketClient._process_text LEAVE")
+                return
+
+            data = json.loads(message)
+            response_type = data.get("type")
+            self._logger.debug("response_type: %s, data: %s", response_type, data)
+
+            match response_type:
+                case AgentWebSocketEvents.Open:
+                    open_result: OpenResponse = OpenResponse.from_json(message)
+                    self._logger.verbose("OpenResponse: %s", open_result)
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Open),
+                        open=open_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.Welcome:
+                    welcome_result: WelcomeResponse = WelcomeResponse.from_json(message)
+                    self._logger.verbose("WelcomeResponse: %s", welcome_result)
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Welcome),
+                        welcome=welcome_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.SettingsApplied:
+                    settings_applied_result: SettingsAppliedResponse = (
+                        SettingsAppliedResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "SettingsAppliedResponse: %s", settings_applied_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.SettingsApplied),
+                        settings_applied=settings_applied_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.ConversationText:
+                    conversation_text_result: ConversationTextResponse = (
+                        ConversationTextResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "ConversationTextResponse: %s", conversation_text_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.ConversationText),
+                        conversation_text=conversation_text_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.UserStartedSpeaking:
+                    user_started_speaking_result: UserStartedSpeakingResponse = (
+                        UserStartedSpeakingResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "UserStartedSpeakingResponse: %s", user_started_speaking_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.UserStartedSpeaking),
+                        user_started_speaking=user_started_speaking_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.AgentThinking:
+                    agent_thinking_result: AgentThinkingResponse = (
+                        AgentThinkingResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "AgentThinkingResponse: %s", agent_thinking_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.AgentThinking),
+                        agent_thinking=agent_thinking_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.FunctionCallRequest:
+                    function_call_request_result: FunctionCallRequest = (
+                        FunctionCallRequest.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "FunctionCallRequest: %s", function_call_request_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.FunctionCallRequest),
+                        function_call_request=function_call_request_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.AgentStartedSpeaking:
+                    agent_started_speaking_result: AgentStartedSpeakingResponse = (
+                        AgentStartedSpeakingResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "AgentStartedSpeakingResponse: %s",
+                        agent_started_speaking_result,
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.AgentStartedSpeaking),
+                        agent_started_speaking=agent_started_speaking_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.AgentAudioDone:
+                    agent_audio_done_result: AgentAudioDoneResponse = (
+                        AgentAudioDoneResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "AgentAudioDoneResponse: %s", agent_audio_done_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.AgentAudioDone),
+                        agent_audio_done=agent_audio_done_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.InjectionRefused:
+                    injection_refused_result: InjectionRefusedResponse = (
+                        InjectionRefusedResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "InjectionRefused: %s", injection_refused_result
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.InjectionRefused),
+                        injection_refused=injection_refused_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.Close:
+                    close_result: CloseResponse = CloseResponse.from_json(message)
+                    self._logger.verbose("CloseResponse: %s", close_result)
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Close),
+                        close=close_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.Error:
+                    err_error: ErrorResponse = ErrorResponse.from_json(message)
+                    self._logger.verbose("ErrorResponse: %s", err_error)
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                        error=err_error,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case _:
+                    self._logger.warning(
+                        "Unknown Message: response_type: %s, data: %s",
+                        response_type,
+                        data,
+                    )
+                    unhandled_error: UnhandledResponse = UnhandledResponse(
+                        type=AgentWebSocketEvents(AgentWebSocketEvents.Unhandled),
+                        raw=message,
+                    )
+                    await self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Unhandled),
+                        unhandled=unhandled_error,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+
+            self._logger.notice("_process_text Succeeded")
+            self._logger.debug("AsyncAgentWebSocketClient._process_text LEAVE")
+
+        except Exception as e:  # pylint: disable=broad-except
+            self._logger.error(
+                "Exception in AsyncAgentWebSocketClient._process_text: %s", e
+            )
+            e_error: ErrorResponse = ErrorResponse(
+                "Exception in AsyncAgentWebSocketClient._process_text",
+                f"{e}",
+                "Exception",
+            )
+            await self._emit(
+                AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                error=e_error,
+                **dict(cast(Dict[Any, Any], self._kwargs)),
+            )
+
+            # signal exit and close
+            await super()._signal_exit()
+
+            self._logger.debug("AsyncAgentWebSocketClient._process_text LEAVE")
+
+            if self._config.options.get("termination_exception") is True:
+                raise
+            return
+
+    # pylint: enable=too-many-locals,too-many-statements
+
+    async def _process_binary(self, message: bytes) -> None:
+        self._logger.debug("AsyncAgentWebSocketClient._process_binary ENTER")
+        self._logger.debug("Binary data received")
+
+        await self._emit(
+            AgentWebSocketEvents(AgentWebSocketEvents.AudioData),
+            data=message,
+            **dict(cast(Dict[Any, Any], self._kwargs)),
+        )
+
+        self._logger.notice("_process_binary Succeeded")
+        self._logger.debug("AsyncAgentWebSocketClient._process_binary LEAVE")
+
+    # pylint: disable=too-many-return-statements
+    async def _keep_alive(self) -> None:
+        """
+        Sends keepalive messages to the WebSocket connection.
+        """
+        self._logger.debug("AsyncAgentWebSocketClient._keep_alive ENTER")
+
+        counter = 0
+        while True:
+            try:
+                counter += 1
+                await asyncio.sleep(ONE_SECOND)
+
+                if self._exit_event.is_set():
+                    self._logger.notice("_keep_alive exiting gracefully")
+                    self._logger.debug("AsyncAgentWebSocketClient._keep_alive LEAVE")
+                    return
+
+                # deepgram keepalive
+                if counter % DEEPGRAM_INTERVAL == 0:
+                    await self.keep_alive()
+
+            except Exception as e:  # pylint: disable=broad-except
+                self._logger.error(
+                    "Exception in AsyncAgentWebSocketClient._keep_alive: %s", e
+                )
+                e_error: ErrorResponse = ErrorResponse(
+                    "Exception in AsyncAgentWebSocketClient._keep_alive",
+                    f"{e}",
+                    "Exception",
+                )
+                self._logger.error(
+                    "Exception in AsyncAgentWebSocketClient._keep_alive: %s", str(e)
+                )
+                await self._emit(
+                    AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                    error=e_error,
+                    **dict(cast(Dict[Any, Any], self._kwargs)),
+                )
+
+                # signal exit and close
+                await super()._signal_exit()
+
+                self._logger.debug("AsyncAgentWebSocketClient._keep_alive LEAVE")
+
+                if self._config.options.get("termination_exception") is True:
+                    raise
+                return
+
+    async def keep_alive(self) -> bool:
+        """
+        Sends a KeepAlive message
+        """
+        self._logger.spam("AsyncAgentWebSocketClient.keep_alive ENTER")
+
+        self._logger.notice("Sending KeepAlive...")
+        ret = await self.send(json.dumps({"type": "KeepAlive"}))
+
+        if not ret:
+            self._logger.error("keep_alive failed")
+            self._logger.spam("AsyncAgentWebSocketClient.keep_alive LEAVE")
+            return False
+
+        self._logger.notice("keep_alive succeeded")
+        self._logger.spam("AsyncAgentWebSocketClient.keep_alive LEAVE")
+
+        return True
+
+    async def _close_message(self) -> bool:
+        # TODO: No known API close message # pylint: disable=fixme
+        # return await self.send(json.dumps({"type": "Close"}))
+        return True
+
+    async def finish(self) -> bool:
+        """
+        Closes the WebSocket connection gracefully.
+        """
+        self._logger.debug("AsyncAgentWebSocketClient.finish ENTER")
+
+        # stop the threads
+        self._logger.verbose("cancelling tasks...")
+        try:
+            # call parent finish
+            if await super().finish() is False:
+                self._logger.error("AsyncAgentWebSocketClient.finish failed")
+
+            if self._microphone is not None and self._microphone_created:
+                self._microphone.finish()
+                self._microphone_created = False
+
+            if self._speaker is not None and self._speaker_created:
+                self._speaker.finish()
+                self._speaker_created = False
+
+            # Before cancelling, check if the tasks were created
+            # debug the threads
+            for thread in threading.enumerate():
+                self._logger.debug("before running thread: %s", thread.name)
+            self._logger.debug("number of active threads: %s", threading.active_count())
+
+            tasks = []
+            if self._keep_alive_thread is not None:
+                self._keep_alive_thread.cancel()
+                tasks.append(self._keep_alive_thread)
+                self._logger.notice("processing _keep_alive_thread cancel...")
+
+            # Use asyncio.gather to wait for tasks to be cancelled
+            # Prevent indefinite waiting by setting a timeout
+            await asyncio.wait_for(asyncio.gather(*tasks), timeout=10)
+            self._logger.notice("threads joined")
+
+            self._speaker = None
+            self._microphone = None
+
+            # debug the threads
+            for thread in threading.enumerate():
+                self._logger.debug("after running thread: %s", thread.name)
+            self._logger.debug("number of active threads: %s", threading.active_count())
+
+            self._logger.notice("finish succeeded")
+            self._logger.spam("AsyncAgentWebSocketClient.finish LEAVE")
+            return True
+
+        except asyncio.CancelledError as e:
+            self._logger.error("tasks cancelled error: %s", e)
+            self._logger.debug("AsyncAgentWebSocketClient.finish LEAVE")
+            return False
+
+        except asyncio.TimeoutError as e:
+            self._logger.error("tasks cancellation timed out: %s", e)
+            self._logger.debug("AsyncAgentWebSocketClient.finish LEAVE")
+            return False

deepgram/clients/agent/v1/websocket/client.py

@@ -0,0 +1,677 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+import json
+import logging
+from typing import Dict, Union, Optional, cast, Any, Callable
+import threading
+import time
+
+from .....utils import verboselogs
+from .....options import DeepgramClientOptions
+from ...enums import AgentWebSocketEvents
+from ....common import AbstractSyncWebSocketClient
+from ....common import DeepgramError
+
+from .response import (
+    OpenResponse,
+    WelcomeResponse,
+    SettingsAppliedResponse,
+    ConversationTextResponse,
+    UserStartedSpeakingResponse,
+    AgentThinkingResponse,
+    FunctionCallRequest,
+    AgentStartedSpeakingResponse,
+    AgentAudioDoneResponse,
+    InjectionRefusedResponse,
+    CloseResponse,
+    ErrorResponse,
+    UnhandledResponse,
+)
+from .options import (
+    SettingsOptions,
+    UpdatePromptOptions,
+    UpdateSpeakOptions,
+    InjectAgentMessageOptions,
+    FunctionCallResponse,
+    AgentKeepAlive,
+)
+
+from .....audio.speaker import (
+    Speaker,
+    RATE as SPEAKER_RATE,
+    CHANNELS as SPEAKER_CHANNELS,
+    PLAYBACK_DELTA as SPEAKER_PLAYBACK_DELTA,
+)
+from .....audio.microphone import (
+    Microphone,
+    RATE as MICROPHONE_RATE,
+    CHANNELS as MICROPHONE_CHANNELS,
+)
+
+ONE_SECOND = 1
+HALF_SECOND = 0.5
+DEEPGRAM_INTERVAL = 5
+
+
+class AgentWebSocketClient(
+    AbstractSyncWebSocketClient
+):  # pylint: disable=too-many-instance-attributes
+    """
+    Client for interacting with Deepgram's live transcription services over WebSockets.
+
+     This class provides methods to establish a WebSocket connection for live transcription and handle real-time transcription events.
+
+     Args:
+         config (DeepgramClientOptions): all the options for the client.
+    """
+
+    _logger: verboselogs.VerboseLogger
+    _config: DeepgramClientOptions
+    _endpoint: str
+
+    _event_handlers: Dict[AgentWebSocketEvents, list]
+
+    _keep_alive_thread: Union[threading.Thread, None]
+
+    _kwargs: Optional[Dict] = None
+    _addons: Optional[Dict] = None
+    # note the distinction here. We can't use _config because it's already used in the parent
+    _settings: Optional[SettingsOptions] = None
+    _headers: Optional[Dict] = None
+
+    _speaker_created: bool = False
+    _speaker: Optional[Speaker] = None
+    _microphone_created: bool = False
+    _microphone: Optional[Microphone] = None
+
+    def __init__(self, config: DeepgramClientOptions):
+        if config is None:
+            raise DeepgramError("Config is required")
+
+        self._logger = verboselogs.VerboseLogger(__name__)
+        self._logger.addHandler(logging.StreamHandler())
+        self._logger.setLevel(config.verbose)
+
+        self._config = config
+
+        # needs to be "wss://agent.deepgram.com/agent"
+        self._endpoint = "v1/agent/converse"
+
+        # override the endpoint since it needs to be "wss://agent.deepgram.com/agent"
+        self._config.url = "agent.deepgram.com"
+
+        self._keep_alive_thread = None
+
+        # init handlers
+        self._event_handlers = {
+            event: [] for event in AgentWebSocketEvents.__members__.values()
+        }
+
+        if self._config.options.get("microphone_record") == "true":
+            self._logger.info("microphone_record is enabled")
+            rate = self._config.options.get("microphone_record_rate", MICROPHONE_RATE)
+            channels = self._config.options.get(
+                "microphone_record_channels", MICROPHONE_CHANNELS
+            )
+            device_index = self._config.options.get("microphone_record_device_index")
+
+            self._logger.debug("rate: %s", rate)
+            self._logger.debug("channels: %s", channels)
+
+            self._microphone_created = True
+
+            if device_index is not None:
+                self._logger.debug("device_index: %s", device_index)
+                self._microphone = Microphone(
+                    rate=rate,
+                    channels=channels,
+                    verbose=self._config.verbose,
+                    input_device_index=device_index,
+                )
+            else:
+                self._microphone = Microphone(
+                    rate=rate,
+                    channels=channels,
+                    verbose=self._config.verbose,
+                )
+
+        if self._config.options.get("speaker_playback") == "true":
+            self._logger.info("speaker_playback is enabled")
+            rate = self._config.options.get("speaker_playback_rate", SPEAKER_RATE)
+            channels = self._config.options.get(
+                "speaker_playback_channels", SPEAKER_CHANNELS
+            )
+            playback_delta_in_ms = self._config.options.get(
+                "speaker_playback_delta_in_ms", SPEAKER_PLAYBACK_DELTA
+            )
+            device_index = self._config.options.get("speaker_playback_device_index")
+
+            self._logger.debug("rate: %s", rate)
+            self._logger.debug("channels: %s", channels)
+
+            self._speaker_created = True
+
+            if device_index is not None:
+                self._logger.debug("device_index: %s", device_index)
+
+                self._speaker = Speaker(
+                    rate=rate,
+                    channels=channels,
+                    last_play_delta_in_ms=playback_delta_in_ms,
+                    verbose=self._config.verbose,
+                    output_device_index=device_index,
+                    microphone=self._microphone,
+                )
+            else:
+                self._speaker = Speaker(
+                    rate=rate,
+                    channels=channels,
+                    last_play_delta_in_ms=playback_delta_in_ms,
+                    verbose=self._config.verbose,
+                    microphone=self._microphone,
+                )
+
+        # call the parent constructor
+        super().__init__(self._config, self._endpoint)
+
+    # pylint: disable=too-many-statements,too-many-branches
+    def start(
+        self,
+        options: Optional[SettingsOptions] = None,
+        addons: Optional[Dict] = None,
+        headers: Optional[Dict] = None,
+        members: Optional[Dict] = None,
+        **kwargs,
+    ) -> bool:
+        """
+        Starts the WebSocket connection for agent API.
+        """
+        self._logger.debug("AgentWebSocketClient.start ENTER")
+        self._logger.info("settings: %s", options)
+        self._logger.info("addons: %s", addons)
+        self._logger.info("headers: %s", headers)
+        self._logger.info("members: %s", members)
+        self._logger.info("kwargs: %s", kwargs)
+
+        if isinstance(options, SettingsOptions) and not options.check():
+            self._logger.error("settings.check failed")
+            self._logger.debug("AgentWebSocketClient.start LEAVE")
+            raise DeepgramError("Fatal agent settings error")
+
+        self._addons = addons
+        self._headers = headers
+
+        # add "members" as members of the class
+        if members is not None:
+            self.__dict__.update(members)
+
+        # set kwargs as members of the class
+        if kwargs is not None:
+            self._kwargs = kwargs
+        else:
+            self._kwargs = {}
+
+        if isinstance(options, SettingsOptions):
+            self._logger.info("options is class")
+            self._settings = options
+        elif isinstance(options, dict):
+            self._logger.info("options is dict")
+            self._settings = SettingsOptions.from_dict(options)
+        elif isinstance(options, str):
+            self._logger.info("options is json")
+            self._settings = SettingsOptions.from_json(options)
+        else:
+            raise DeepgramError("Invalid options type")
+
+        if (
+            self._settings.agent.listen.provider
+            and self._settings.agent.listen.provider.keyterms is not None
+            and self._settings.agent.listen.provider.model is not None
+            and not self._settings.agent.listen.provider.model.startswith("nova-3")
+        ):
+            raise DeepgramError("Keyterms are only supported for nova-3 models")
+
+        try:
+            # speaker substitutes the listening thread
+            if self._speaker is not None:
+                self._logger.notice("passing speaker to delegate_listening")
+                super().delegate_listening(self._speaker)
+
+            # call parent start
+            if (
+                super().start(
+                    {},
+                    self._addons,
+                    self._headers,
+                    **dict(cast(Dict[Any, Any], self._kwargs)),
+                )
+                is False
+            ):
+                self._logger.error("AgentWebSocketClient.start failed")
+                self._logger.debug("AgentWebSocketClient.start LEAVE")
+                return False
+
+            if self._speaker is not None:
+                self._logger.notice("speaker is delegate_listening. Starting speaker")
+                self._speaker.start()
+
+            if self._speaker is not None and self._microphone is not None:
+                self._logger.notice(
+                    "speaker is delegate_listening. Starting microphone"
+                )
+                self._microphone.set_callback(self.send)
+                self._microphone.start()
+
+            # debug the threads
+            for thread in threading.enumerate():
+                self._logger.debug("after running thread: %s", thread.name)
+            self._logger.debug("number of active threads: %s", threading.active_count())
+
+            # keepalive thread
+            if self._config.is_keep_alive_enabled():
+                self._logger.notice("keepalive is enabled")
+                self._keep_alive_thread = threading.Thread(target=self._keep_alive)
+                self._keep_alive_thread.start()
+            else:
+                self._logger.notice("keepalive is disabled")
+
+            # debug the threads
+            for thread in threading.enumerate():
+                self._logger.debug("after running thread: %s", thread.name)
+            self._logger.debug("number of active threads: %s", threading.active_count())
+
+            # send the Settings message
+            self._logger.notice("Sending Settings...")
+            ret_send_cs = self.send(str(self._settings))
+            if not ret_send_cs:
+                self._logger.error("Settings failed")
+
+                err_error: ErrorResponse = ErrorResponse(
+                    "Exception in AgentWebSocketClient.start",
+                    "Settings failed to send",
+                    "Exception",
+                )
+                self._emit(
+                    AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                    error=err_error,
+                    **dict(cast(Dict[Any, Any], self._kwargs)),
+                )
+
+                self._logger.debug("AgentWebSocketClient.start LEAVE")
+                return False
+
+            self._logger.notice("start succeeded")
+            self._logger.debug("AgentWebSocketClient.start LEAVE")
+            return True
+
+        except Exception as e:  # pylint: disable=broad-except
+            self._logger.error(
+                "WebSocketException in AgentWebSocketClient.start: %s", e
+            )
+            self._logger.debug("AgentWebSocketClient.start LEAVE")
+            if self._config.options.get("termination_exception_connect") is True:
+                raise e
+            return False
+
+    # pylint: enable=too-many-statements,too-many-branches
+
+    def on(self, event: AgentWebSocketEvents, handler: Callable) -> None:
+        """
+        Registers event handlers for specific events.
+        """
+        self._logger.info("event subscribed: %s", event)
+        if event in AgentWebSocketEvents.__members__.values() and callable(handler):
+            self._event_handlers[event].append(handler)
+
+    def _emit(self, event: AgentWebSocketEvents, *args, **kwargs) -> None:
+        """
+        Emits events to the registered event handlers.
+        """
+        self._logger.debug("AgentWebSocketClient._emit ENTER")
+        self._logger.debug("callback handlers for: %s", event)
+
+        # debug the threads
+        for thread in threading.enumerate():
+            self._logger.debug("after running thread: %s", thread.name)
+        self._logger.debug("number of active threads: %s", threading.active_count())
+
+        self._logger.debug("callback handlers for: %s", event)
+        for handler in self._event_handlers[event]:
+            handler(self, *args, **kwargs)
+
+        # debug the threads
+        for thread in threading.enumerate():
+            self._logger.debug("after running thread: %s", thread.name)
+        self._logger.debug("number of active threads: %s", threading.active_count())
+
+        self._logger.debug("AgentWebSocketClient._emit LEAVE")
+
+    # pylint: disable=too-many-return-statements,too-many-statements,too-many-locals,too-many-branches
+    def _process_text(self, message: str) -> None:
+        """
+        Processes messages received over the WebSocket connection.
+        """
+        self._logger.debug("AgentWebSocketClient._process_text ENTER")
+
+        try:
+            self._logger.debug("Text data received")
+            if len(message) == 0:
+                self._logger.debug("message is empty")
+                self._logger.debug("AgentWebSocketClient._process_text LEAVE")
+                return
+
+            data = json.loads(message)
+            response_type = data.get("type")
+            self._logger.debug("response_type: %s, data: %s", response_type, data)
+
+            match response_type:
+                case AgentWebSocketEvents.Open:
+                    open_result: OpenResponse = OpenResponse.from_json(message)
+                    self._logger.verbose("OpenResponse: %s", open_result)
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Open),
+                        open=open_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.Welcome:
+                    welcome_result: WelcomeResponse = WelcomeResponse.from_json(message)
+                    self._logger.verbose("WelcomeResponse: %s", welcome_result)
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Welcome),
+                        welcome=welcome_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.SettingsApplied:
+                    settings_applied_result: SettingsAppliedResponse = (
+                        SettingsAppliedResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "SettingsAppliedResponse: %s", settings_applied_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.SettingsApplied),
+                        settings_applied=settings_applied_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.ConversationText:
+                    conversation_text_result: ConversationTextResponse = (
+                        ConversationTextResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "ConversationTextResponse: %s", conversation_text_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.ConversationText),
+                        conversation_text=conversation_text_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.UserStartedSpeaking:
+                    user_started_speaking_result: UserStartedSpeakingResponse = (
+                        UserStartedSpeakingResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "UserStartedSpeakingResponse: %s", user_started_speaking_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.UserStartedSpeaking),
+                        user_started_speaking=user_started_speaking_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.AgentThinking:
+                    agent_thinking_result: AgentThinkingResponse = (
+                        AgentThinkingResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "AgentThinkingResponse: %s", agent_thinking_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.AgentThinking),
+                        agent_thinking=agent_thinking_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.FunctionCallRequest:
+                    function_call_request_result: FunctionCallRequest = (
+                        FunctionCallRequest.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "FunctionCallRequest: %s", function_call_request_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.FunctionCallRequest),
+                        function_call_request=function_call_request_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.AgentStartedSpeaking:
+                    agent_started_speaking_result: AgentStartedSpeakingResponse = (
+                        AgentStartedSpeakingResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "AgentStartedSpeakingResponse: %s",
+                        agent_started_speaking_result,
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.AgentStartedSpeaking),
+                        agent_started_speaking=agent_started_speaking_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.AgentAudioDone:
+                    agent_audio_done_result: AgentAudioDoneResponse = (
+                        AgentAudioDoneResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "AgentAudioDoneResponse: %s", agent_audio_done_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.AgentAudioDone),
+                        agent_audio_done=agent_audio_done_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.InjectionRefused:
+                    injection_refused_result: InjectionRefusedResponse = (
+                        InjectionRefusedResponse.from_json(message)
+                    )
+                    self._logger.verbose(
+                        "InjectionRefused: %s", injection_refused_result
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.InjectionRefused),
+                        injection_refused=injection_refused_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.Close:
+                    close_result: CloseResponse = CloseResponse.from_json(message)
+                    self._logger.verbose("CloseResponse: %s", close_result)
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Close),
+                        close=close_result,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case AgentWebSocketEvents.Error:
+                    err_error: ErrorResponse = ErrorResponse.from_json(message)
+                    self._logger.verbose("ErrorResponse: %s", err_error)
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                        error=err_error,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+                case _:
+                    self._logger.warning(
+                        "Unknown Message: response_type: %s, data: %s",
+                        response_type,
+                        data,
+                    )
+                    unhandled_error: UnhandledResponse = UnhandledResponse(
+                        type=AgentWebSocketEvents(AgentWebSocketEvents.Unhandled),
+                        raw=message,
+                    )
+                    self._emit(
+                        AgentWebSocketEvents(AgentWebSocketEvents.Unhandled),
+                        unhandled=unhandled_error,
+                        **dict(cast(Dict[Any, Any], self._kwargs)),
+                    )
+
+            self._logger.notice("_process_text Succeeded")
+            self._logger.debug("SpeakStreamClient._process_text LEAVE")
+
+        except Exception as e:  # pylint: disable=broad-except
+            self._logger.error("Exception in AgentWebSocketClient._process_text: %s", e)
+            e_error: ErrorResponse = ErrorResponse(
+                "Exception in AgentWebSocketClient._process_text",
+                f"{e}",
+                "Exception",
+            )
+            self._logger.error(
+                "Exception in AgentWebSocketClient._process_text: %s", str(e)
+            )
+            self._emit(
+                AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                error=e_error,
+                **dict(cast(Dict[Any, Any], self._kwargs)),
+            )
+
+            # signal exit and close
+            super()._signal_exit()
+
+            self._logger.debug("AgentWebSocketClient._process_text LEAVE")
+
+            if self._config.options.get("termination_exception") is True:
+                raise
+            return
+
+    # pylint: enable=too-many-return-statements,too-many-statements
+
+    def _process_binary(self, message: bytes) -> None:
+        self._logger.debug("AgentWebSocketClient._process_binary ENTER")
+        self._logger.debug("Binary data received")
+
+        self._emit(
+            AgentWebSocketEvents(AgentWebSocketEvents.AudioData),
+            data=message,
+            **dict(cast(Dict[Any, Any], self._kwargs)),
+        )
+
+        self._logger.notice("_process_binary Succeeded")
+        self._logger.debug("AgentWebSocketClient._process_binary LEAVE")
+
+    # pylint: disable=too-many-return-statements
+    def _keep_alive(self) -> None:
+        """
+        Sends keepalive messages to the WebSocket connection.
+        """
+        self._logger.debug("AgentWebSocketClient._keep_alive ENTER")
+
+        counter = 0
+        while True:
+            try:
+                counter += 1
+                self._exit_event.wait(timeout=ONE_SECOND)
+
+                if self._exit_event.is_set():
+                    self._logger.notice("_keep_alive exiting gracefully")
+                    self._logger.debug("AgentWebSocketClient._keep_alive LEAVE")
+                    return
+
+                # deepgram keepalive
+                if counter % DEEPGRAM_INTERVAL == 0:
+                    self.keep_alive()
+
+            except Exception as e:  # pylint: disable=broad-except
+                self._logger.error(
+                    "Exception in AgentWebSocketClient._keep_alive: %s", e
+                )
+                e_error: ErrorResponse = ErrorResponse(
+                    "Exception in AgentWebSocketClient._keep_alive",
+                    f"{e}",
+                    "Exception",
+                )
+                self._logger.error(
+                    "Exception in AgentWebSocketClient._keep_alive: %s", str(e)
+                )
+                self._emit(
+                    AgentWebSocketEvents(AgentWebSocketEvents.Error),
+                    error=e_error,
+                    **dict(cast(Dict[Any, Any], self._kwargs)),
+                )
+
+                # signal exit and close
+                super()._signal_exit()
+
+                self._logger.debug("AgentWebSocketClient._keep_alive LEAVE")
+
+                if self._config.options.get("termination_exception") is True:
+                    raise
+                return
+
+    def keep_alive(self) -> bool:
+        """
+        Sends a KeepAlive message
+        """
+        self._logger.spam("AgentWebSocketClient.keep_alive ENTER")
+
+        self._logger.notice("Sending KeepAlive...")
+        ret = self.send(json.dumps({"type": "KeepAlive"}))
+
+        if not ret:
+            self._logger.error("keep_alive failed")
+            self._logger.spam("AgentWebSocketClient.keep_alive LEAVE")
+            return False
+
+        self._logger.notice("keep_alive succeeded")
+        self._logger.spam("AgentWebSocketClient.keep_alive LEAVE")
+
+        return True
+
+    def _close_message(self) -> bool:
+        # TODO: No known API close message # pylint: disable=fixme
+        # return self.send(json.dumps({"type": "Close"}))
+        return True
+
+    # closes the WebSocket connection gracefully
+    def finish(self) -> bool:
+        """
+        Closes the WebSocket connection gracefully.
+        """
+        self._logger.spam("AgentWebSocketClient.finish ENTER")
+
+        # call parent finish
+        if super().finish() is False:
+            self._logger.error("AgentWebSocketClient.finish failed")
+
+        if self._microphone is not None and self._microphone_created:
+            self._microphone.finish()
+            self._microphone_created = False
+
+        if self._speaker is not None and self._speaker_created:
+            self._speaker.finish()
+            self._speaker_created = False
+
+        # debug the threads
+        for thread in threading.enumerate():
+            self._logger.debug("before running thread: %s", thread.name)
+        self._logger.debug("number of active threads: %s", threading.active_count())
+
+        # stop the threads
+        self._logger.verbose("cancelling tasks...")
+        if self._keep_alive_thread is not None:
+            self._keep_alive_thread.join()
+            self._keep_alive_thread = None
+            self._logger.notice("processing _keep_alive_thread thread joined")
+
+        if self._listen_thread is not None:
+            self._listen_thread.join()
+            self._listen_thread = None
+        self._logger.notice("listening thread joined")
+
+        self._speaker = None
+        self._microphone = None
+
+        # debug the threads
+        for thread in threading.enumerate():
+            self._logger.debug("before running thread: %s", thread.name)
+        self._logger.debug("number of active threads: %s", threading.active_count())
+
+        self._logger.notice("finish succeeded")
+        self._logger.spam("AgentWebSocketClient.finish LEAVE")
+        return True

deepgram/clients/agent/v1/websocket/options.py

@@ -0,0 +1,453 @@
+# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from typing import List, Optional, Union, Any, Tuple
+import logging
+
+from dataclasses import dataclass, field
+from dataclasses_json import config as dataclass_config
+
+from deepgram.utils import verboselogs
+
+from ...enums import AgentWebSocketEvents
+from ....common import BaseResponse
+
+
+# ConfigurationSettings
+
+
+@dataclass
+class Header(BaseResponse):
+    """
+    This class defines a single key/value pair for a header.
+    """
+
+    key: str
+    value: str
+
+
+@dataclass
+class Item(BaseResponse):
+    """
+    This class defines a single item in a list of items.
+    """
+
+    type: str
+    description: str
+
+
+@dataclass
+class Properties(BaseResponse):
+    """
+    This class defines the properties which is just a list of items.
+    """
+
+    item: Item
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "item" in _dict:
+            _dict["item"] = [Item.from_dict(item) for item in _dict["item"]]
+        return _dict[key]
+
+
+@dataclass
+class Parameters(BaseResponse):
+    """
+    This class defines the parameters for a function.
+    """
+
+    type: str
+    properties: Properties
+    required: List[str]
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "properties" in _dict:
+            _dict["properties"] = _dict["properties"].copy()
+        return _dict[key]
+
+
+@dataclass
+class Endpoint(BaseResponse):
+    """
+    Define a custom endpoint for the agent.
+    """
+
+    method: Optional[str] = field(default="POST")
+    url: str = field(default="")
+    headers: Optional[List[Header]] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "headers" in _dict:
+            _dict["headers"] = [
+                Header.from_dict(headers) for headers in _dict["headers"]
+            ]
+        return _dict[key]
+
+
+@dataclass
+class Function(BaseResponse):
+    """
+    This class defines a function for the Think model.
+    """
+
+    name: str
+    description: str
+    url: str
+    method: str
+    headers: Optional[List[Header]] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    parameters: Optional[Parameters] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    endpoint: Optional[Endpoint] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "parameters" in _dict and isinstance(_dict["parameters"], dict):
+            _dict["parameters"] = Parameters.from_dict(_dict["parameters"])
+        if "headers" in _dict and isinstance(_dict["headers"], list):
+            _dict["headers"] = [Header.from_dict(header) for header in _dict["headers"]]
+        if "endpoint" in _dict and isinstance(_dict["endpoint"], dict):
+            _dict["endpoint"] = Endpoint.from_dict(_dict["endpoint"])
+        return _dict[key]
+
+
+@dataclass
+class CartesiaVoice(BaseResponse):
+    """
+    This class defines the voice for the Cartesia model.
+    """
+
+    mode: str = field(
+        default="", metadata=dataclass_config(exclude=lambda f: f is None or f == "")
+    )
+    id: str = field(
+        default="", metadata=dataclass_config(exclude=lambda f: f is None or f == "")
+    )
+
+
+@dataclass
+class ListenProvider(BaseResponse):
+    """
+    This class defines the provider for the Listen model.
+    """
+
+    type: str = field(default="")
+    model: str = field(default="")
+    keyterms: Optional[List[str]] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "keyterms" in _dict and isinstance(_dict["keyterms"], list):
+            _dict["keyterms"] = [str(keyterm) for keyterm in _dict["keyterms"]]
+        return _dict[key]
+
+
+@dataclass
+class ThinkProvider(BaseResponse):
+    """
+    This class defines the provider for the Think model.
+    """
+
+    type: Optional[str] = field(default=None)
+    model: Optional[str] = field(default=None)
+    temperature: Optional[float] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+
+@dataclass
+class SpeakProvider(BaseResponse):
+    """
+    This class defines the provider for the Speak model.
+    """
+
+    type: Optional[str] = field(default="deepgram")
+    """
+    Deepgram OR OpenAI model to use.
+    """
+    model: Optional[str] = field(
+        default="aura-2-thalia-en",
+        metadata=dataclass_config(exclude=lambda f: f is None),
+    )
+    """
+    ElevenLabs or Cartesia model to use.
+    """
+    model_id: Optional[str] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    """
+    Cartesia voice configuration.
+    """
+    voice: Optional[CartesiaVoice] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    """
+    Cartesia language.
+    """
+    language: Optional[str] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    """
+    ElevenLabs language.
+    """
+    language_code: Optional[str] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "voice" in _dict and isinstance(_dict["voice"], dict):
+            _dict["voice"] = CartesiaVoice.from_dict(_dict["voice"])
+        return _dict[key]
+
+
+@dataclass
+class Think(BaseResponse):
+    """
+    This class defines any configuration settings for the Think model.
+    """
+
+    provider: ThinkProvider = field(default_factory=ThinkProvider)
+    functions: Optional[List[Function]] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    endpoint: Optional[Endpoint] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    prompt: Optional[str] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "provider" in _dict and isinstance(_dict["provider"], dict):
+            _dict["provider"] = ThinkProvider.from_dict(_dict["provider"])
+        if "functions" in _dict and isinstance(_dict["functions"], list):
+            _dict["functions"] = [
+                Function.from_dict(function) for function in _dict["functions"]
+            ]
+        if "endpoint" in _dict and isinstance(_dict["endpoint"], dict):
+            _dict["endpoint"] = Endpoint.from_dict(_dict["endpoint"])
+        return _dict[key]
+
+
+@dataclass
+class Listen(BaseResponse):
+    """
+    This class defines any configuration settings for the Listen model.
+    """
+
+    provider: ListenProvider = field(default_factory=ListenProvider)
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "provider" in _dict and isinstance(_dict["provider"], dict):
+            _dict["provider"] = ListenProvider.from_dict(_dict["provider"])
+        return _dict[key]
+
+
+@dataclass
+class Speak(BaseResponse):
+    """
+    This class defines any configuration settings for the Speak model.
+    """
+
+    provider: SpeakProvider = field(default_factory=SpeakProvider)
+    endpoint: Optional[Endpoint] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "provider" in _dict and isinstance(_dict["provider"], dict):
+            _dict["provider"] = SpeakProvider.from_dict(_dict["provider"])
+        if "endpoint" in _dict and isinstance(_dict["endpoint"], dict):
+            _dict["endpoint"] = Endpoint.from_dict(_dict["endpoint"])
+        return _dict[key]
+
+
+@dataclass
+class Agent(BaseResponse):
+    """
+    This class defines any configuration settings for the Agent model.
+    """
+
+    listen: Listen = field(default_factory=Listen)
+    think: Think = field(default_factory=Think)
+    speak: Speak = field(default_factory=Speak)
+    greeting: Optional[str] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "listen" in _dict and isinstance(_dict["listen"], dict):
+            _dict["listen"] = Listen.from_dict(_dict["listen"])
+        if "think" in _dict and isinstance(_dict["think"], dict):
+            _dict["think"] = Think.from_dict(_dict["think"])
+        if "speak" in _dict and isinstance(_dict["speak"], dict):
+            _dict["speak"] = Speak.from_dict(_dict["speak"])
+        return _dict[key]
+
+
+@dataclass
+class Input(BaseResponse):
+    """
+    This class defines any configuration settings for the input audio.
+    """
+
+    encoding: Optional[str] = field(default="linear16")
+    sample_rate: int = field(default=16000)
+
+
+@dataclass
+class Output(BaseResponse):
+    """
+    This class defines any configuration settings for the output audio.
+    """
+
+    encoding: Optional[str] = field(default="linear16")
+    sample_rate: Optional[int] = field(default=16000)
+    bitrate: Optional[int] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
+    container: Optional[str] = field(default="none")
+
+
+@dataclass
+class Audio(BaseResponse):
+    """
+    This class defines any configuration settings for the audio.
+    """
+
+    input: Optional[Input] = field(default_factory=Input)
+    output: Optional[Output] = field(default_factory=Output)
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "input" in _dict and isinstance(_dict["input"], dict):
+            _dict["input"] = Input.from_dict(_dict["input"])
+        if "output" in _dict and isinstance(_dict["output"], dict):
+            _dict["output"] = Output.from_dict(_dict["output"])
+        return _dict[key]
+
+
+@dataclass
+class Language(BaseResponse):
+    """
+    Define the language for the agent.
+    """
+
+    type: str = field(default="en")
+
+
+@dataclass
+class SettingsOptions(BaseResponse):
+    """
+    The client should send a Settings message immediately after opening the websocket and before sending any audio.
+    """
+
+    experimental: Optional[bool] = field(default=False)
+    type: str = str(AgentWebSocketEvents.Settings)
+    audio: Audio = field(default_factory=Audio)
+    agent: Agent = field(default_factory=Agent)
+
+    def __getitem__(self, key):
+        _dict = self.to_dict()
+        if "audio" in _dict and isinstance(_dict["audio"], dict):
+            _dict["audio"] = Audio.from_dict(_dict["audio"])
+        if "agent" in _dict and isinstance(_dict["agent"], dict):
+            _dict["agent"] = Agent.from_dict(_dict["agent"])
+        return _dict[key]
+
+    def check(self):
+        """
+        Check the options for any deprecated or soon-to-be-deprecated options.
+        """
+        logger = verboselogs.VerboseLogger(__name__)
+        logger.addHandler(logging.StreamHandler())
+        prev = logger.level
+        logger.setLevel(verboselogs.ERROR)
+
+        # do we need to check anything here?
+
+        logger.setLevel(prev)
+
+        return True
+
+
+# UpdatePrompt
+
+
+@dataclass
+class UpdatePromptOptions(BaseResponse):
+    """
+    The client can send an UpdatePrompt message to provide a new prompt to the Think model in the middle of a conversation.
+    """
+
+    type: str = str(AgentWebSocketEvents.UpdatePrompt)
+    prompt: str = field(default="")
+
+
+# UpdateSpeak
+
+
+@dataclass
+class UpdateSpeakOptions(BaseResponse):
+    """
+    The client can send an UpdateSpeak message to change the Speak model in the middle of a conversation.
+    """
+
+    type: str = str(AgentWebSocketEvents.UpdateSpeak)
+    speak: Speak = field(default_factory=Speak)
+
+
+# InjectAgentMessage
+
+
+@dataclass
+class InjectAgentMessageOptions(BaseResponse):
+    """
+    The client can send an InjectAgentMessage to immediately trigger an agent statement. If the injection request arrives while the user is speaking, or while the server is in the middle of sending audio for an agent response, then the request will be ignored and the server will reply with an InjectionRefused.
+    """
+
+    type: str = str(AgentWebSocketEvents.InjectAgentMessage)
+    message: str = field(default="")
+
+
+# Function Call Response
+
+
+@dataclass
+class FunctionCallResponse(BaseResponse):
+    """
+    TheFunctionCallResponse message is a JSON command that the client should reply with every time there is a FunctionCallRequest received.
+    """
+
+    type: str = "FunctionCallResponse"
+    function_call_id: str = field(default="")
+    output: str = field(default="")
+
+
+# Agent Keep Alive
+
+
+@dataclass
+class AgentKeepAlive(BaseResponse):
+    """
+    The KeepAlive message is a JSON command that you can use to ensure that the server does not close the connection.
+    """
+
+    type: str = "KeepAlive"