Merge pull request #13 from uhlive/feature/sc-28389/documentation

API documentation

.gitignore

@@ -8,3 +8,4 @@ build
 .venv
 *.local
 .env
+site

MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include src/uhlive/py.typed
+

README.md

@@ -3,14 +3,20 @@
 The Uh!live Python SDK provides convenient access to the Uh!live API from
 applications written in the Python language.
 
-Read the [documentation for the Conversation API](https://docs.allo-media.net/live-api/) and [for the Recognition API (vocal bot toolkit)](https://docs.allo-media.net/stream-api-bots/).
+Read the [full documentation](https://python-uhlive-sdk.netlify.app/).
 
 ## Requirements
 
 ### Installation from source
 
 Install with `pip install .[examples]` to install the the library and all the dependencies necessary to run the examples.
 
+### Installation from Pypi
+
+```
+pip install uhlive
+```
+
 ### Audio files
 
 To play with the examples, you should have a raw audio file.

docs/auth.md

@@ -0,0 +1,6 @@
+# uhlive.auth
+
+::: uhlive.auth
+    options:
+        show_source: false
+

docs/conversation_api.md

@@ -0,0 +1,5 @@
+# uhlive.stream.conversation
+
+::: uhlive.stream.conversation
+    options:
+        show_source: false

docs/css/mkdocstrings.css

@@ -0,0 +1,41 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .15rem solid var(--secondary);
+}
+
+/*code {
+  font-size: inherit;
+}
+*/
+h2.doc-heading {
+  font-size: 1.75rem;
+/*  font-weight: 600;*/
+}
+
+h3.doc-heading {
+/*  font-weight: 600;*/
+  font-size: 1.2rem;
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: var(--md-typeset-a-color);
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}

docs/index.md

@@ -0,0 +1,105 @@
+# Welcome to the Uh!ive Python SDK
+
+The Uh!ive Python SDK is a library to access our live Automated Speech Recognition online APIs.
+It provides [I/O Free](https://sans-io.readthedocs.io/index.html) Python abstractions over the underlying protocols and workflows to hide the complexity.
+
+By providing an I/O Free implementation, we let developers choose whatever websocket transport library and paradigm — synchronous or asynchronous (asyncio) — they like most.
+
+## Access to the API
+
+In order to have access to our online APIs, your company needs to register for an account. Depending on the plan, you may get two kinds of credentials:
+
+* Either a `client_id` and `client_secret`;
+* or a `client_id`, `user_id` and `user_password`.
+
+In all cases, those credentials are used to retrieve a one time access token from our SSO.
+
+You are free to use whatever HTTP client library you like.
+
+Here is a synchronous example using `requests`:
+
+```python
+from uhlive.auth import build_authentication_request
+import requests
+
+uhlive_client = "…"
+uhlive_secret = "…"
+# user_id = "…"
+# user_password = "…"
+
+auth_url, auth_params = build_authentication_request(uhlive_client, uhlive_secret)
+# or auth_url, auth_params = build_authentication_request(uhlive_client, user_id=user_id, user_pwd=user_password)
+login = requests.post(auth_url, data=auth_params)
+login.raise_for_status()
+uhlive_token = login.json()["access_token"]
+```
+
+Here is an asynchronous example using `aiohttp`:
+
+```python
+import asyncio
+from uhlive.auth import build_authentication_request
+from aiohttp import ClientSession
+
+uhlive_client = "…"
+uhlive_secret = "…"
+# user_id = "…"
+# user_password = "…"
+
+
+async def main(uhlive_client, uhlive_secret):
+    async with ClientSession() as session:
+        auth_url, auth_params = build_authentication_request(
+            uhlive_client, uhlive_secret
+        )
+        async with session.post(auth_url, data=auth_params) as login:
+            login.raise_for_status()
+            body = await login.json()
+            uhlive_token = body["access_token"]
+        # continue with Stream API of your choice
+        # ...
+
+asyncio.run(main(uhlive_client, uhlive_secret))
+```
+
+Then this one time token allows you to connect to any subscribed API within 5 minutes.
+
+* [Auth API reference](auth.md)
+
+
+## Conversation API to analyze human to human interactions.
+
+Also known as the human to human (H2H) stream API.
+
+* [High level overview](https://docs.allo-media.net/stream-h2h/overview/#high-level-overview-and-concepts)
+* [Python SDK API documentation](conversation_api.md)
+
+## Recognition and interpretation API for voice bots.
+
+Also known as the human to bot (H2B) stream API.
+
+* [High level overview](https://docs.allo-media.net/stream-h2b/#real-time-stream-api-for-voicebots)
+* [Python SDK API documentation](recognition_api.md)
+
+
+## Changelog
+
+### v1.3.1
+
+Full API documentation.
+
+### v1.3.0
+
+* Support for `SegmentNormalized`
+* SSO
+* Concurrent test runner `test_runner_async.py` in `examples/recognition`
+
+### v1.2.0
+
+* Improved streamer
+* Improved test_runner.py
+* Forbid sharing connection between conversations
+
+### v1.1.0
+
+* Support for passing codec parameter

docs/recognition_api.md

@@ -0,0 +1,5 @@
+# uhlive.stream.recognition
+
+::: uhlive.stream.recognition
+    options:
+        show_source: false

examples/recognition/async_bot_lib.py

@@ -77,7 +77,6 @@ def callback(indata, frame_count, time_info, status):
 
 
 class Bot:
-
     TTF_CACHE: Dict[str, bytes] = {}
 
     def __init__(self, google_ttf_key):

examples/recognition/basic_sync.py

@@ -84,7 +84,6 @@ def play(self, filename, codec="linear"):
 
 
 def main(socket: ws.WebSocket, client: Recognizer, stream: AudioStreamer):
-
     # Shortcuts
     send = socket.send
 

examples/recognition/desktop-bot_async.py

@@ -116,7 +116,6 @@ async def demo_multi(self):
             await say("je vous passe le services des abonnés")
 
     async def scenario(self):
-
         # Shortcuts
         say = self.say
 

examples/recognition/desktop-bot_sync.py

@@ -13,9 +13,9 @@ def set_defaults(self):
             speech_language="fr",
             no_input_timeout=5000,
             recognition_timeout=20000,
-            speech_complete_timeout=800,
-            speech_incomplete_timeout=1200,
-            speech_nomatch_timeout=3000,
+            speech_complete_timeout=1000,
+            speech_incomplete_timeout=2000,
+            speech_nomatch_timeout=4000,
         )
 
         # Define grammars up front
@@ -66,8 +66,17 @@ def demo_address(self):
                     recognition_mode="hotword",
                 )
                 addr["zipcode"] = nlu.value
-            formatted = f"j'ai compris {addr['number'] or ''} {addr['street'] or ''} {addr['zipcode'] or ''} {addr['city'] or ''}"
-            say(formatted)
+            say("J'ai compris")
+            if addr["number"]:
+                say(f"numéro : {addr['number']}")
+            if addr["street"]:
+                say(f"voie : {addr['street']}")
+            if addr["zipcode"]:
+                say(f"code postal : {addr['zipcode']}")
+            if addr["city"]:
+                say(f"ville : {addr['city']}")
+            if addr["complement"]:
+                say(f"complément d'adresse : {addr['complement']}")
             confirm = self.confirm(
                 "Est-ce correct?",
             )
@@ -160,7 +169,6 @@ def demo_date(self):
                     say("J'ai compris, mais ce n'est pas une date valide")
 
     def scenario(self):
-
         # Scenario
         self.set_defaults()
         self.wait_activation()

examples/recognition/fixtures/fr_address.test

@@ -31,3 +31,4 @@ number = "37"
 street = "rue du docteur leroy"
 zipcode = "72000"
 city = "le mans"
+complement = ""

examples/recognition/sync_bot_lib.py

@@ -27,7 +27,6 @@
 
 
 class Bot:
-
     TTF_CACHE: Dict[str, bytes] = {}
 
     def __init__(self, google_ttf_key):
@@ -108,7 +107,6 @@ def confirm(self, text: str) -> bool:
         return res.value
 
     def run(self, uhlive_client: str, uhlive_secret: str):
-
         auth_url, auth_params = build_authentication_request(
             uhlive_client, uhlive_secret
         )

examples/recognition/transcribe.py

@@ -26,7 +26,6 @@ def main(
     codec: str,
     filepath: str,
 ):
-
     # Shortcuts
     send = socket.send
 

mkdocs.yml

@@ -0,0 +1,32 @@
+site_name: Uh!ive python SDK
+
+theme:
+  name: "mkdocs"
+
+extra_css:
+  - css/mkdocstrings.css
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_signature_annotations: true
+            group_by_category: true
+            show_category_heading: false
+            inherited_members: true
+            members_order: source
+            docstring_section_style: "list"
+            signature_crossrefs: true
+            separate_signature: true
+            line_length: 110
+            merge_init_into_class: true
+
+nav:
+  - Home: index.md
+  - Auth: auth.md
+  - H2H API: conversation_api.md
+  - H2B API: recognition_api.md

requirements.txt

@@ -0,0 +1,54 @@
+aiohttp==3.8.4
+aiosignal==1.3.1
+async-timeout==4.0.2
+attrs==23.1.0
+Babel==2.14.0
+black==23.12.1
+cachetools==5.3.2
+certifi==2023.5.7
+cffi==1.15.1
+chardet==5.2.0
+charset-normalizer==3.1.0
+click==8.1.7
+colorama==0.4.6
+distlib==0.3.8
+filelock==3.13.1
+frozenlist==1.3.3
+ghp-import==2.1.0
+griffe==0.38.1
+idna==3.4
+Jinja2==3.1.2
+Markdown==3.5.1
+MarkupSafe==2.1.3
+mergedeep==1.3.4
+mkdocs==1.5.3
+mkdocs-autorefs==0.5.0
+mkdocs-material==9.5.3
+mkdocs-material-extensions==1.3.1
+mkdocstrings==0.24.0
+mkdocstrings-python==1.7.5
+multidict==6.0.4
+mypy-extensions==1.0.0
+packaging==23.2
+paginate==0.5.6
+pathspec==0.12.1
+platformdirs==4.1.0
+pluggy==1.3.0
+pycparser==2.21
+Pygments==2.17.2
+pymdown-extensions==10.7
+pyproject-api==1.6.1
+python-dateutil==2.8.2
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.12.25
+requests==2.31.0
+six==1.16.0
+sounddevice==0.4.6
+toml==0.10.2
+tox==4.11.4
+urllib3==2.0.3
+virtualenv==20.25.0
+watchdog==3.0.0
+websocket-client==1.6.1
+yarl==1.9.2

setup.py

@@ -5,11 +5,11 @@
 
 setup(
     name="uhlive",
-    version="1.3.0",
+    version="1.3.1",
     url="https://github.com/uhlive/python-sdk",
     author="Allo-Media",
     author_email="support@allo-media.fr",
-    description="Python bindings for the Uh!ive API",
+    description="Python bindings for the Uh!ive APIs",
     long_description=long_description,
     long_description_content_type="text/markdown",
     license="MIT",