typeless-sdk 0.1.0__tar.gz

typeless_sdk-0.1.0/LICENSE

@@ -0,0 +1,97 @@
+Typeless Python SDK License
+
+Copyright (c) 2026 SIMPLY LLC. All rights reserved.
+
+This software (the "SDK") is proprietary to SIMPLY LLC ("Typeless") and is
+licensed, not sold. Your use of the SDK and of the Typeless services is also
+governed by the Typeless Terms of Service at https://www.typeless.com/terms (the
+"Terms"), which are incorporated by reference. Typeless's handling of personal
+data is described in the Privacy Policy at https://www.typeless.com/privacy (the
+"Privacy Policy"). With respect to the SDK, this license controls in the event of
+a conflict; the Terms otherwise govern your use of the Typeless services.
+
+BY INSTALLING, COPYING, OR OTHERWISE USING THE SDK, YOU AGREE TO BE BOUND BY
+THIS LICENSE. IF YOU DO NOT AGREE, DO NOT INSTALL OR USE THE SDK.
+
+1. License Grant
+
+   Subject to your continued compliance with this license and the Terms, Typeless
+   grants you a limited, non-exclusive, non-transferable (except for the limited
+   distribution right in Section 2), revocable license to install and use the SDK
+   solely to develop and operate your own applications and services that access
+   the Typeless External Transcript API (the "Typeless API").
+
+2. Limited Distribution Exception
+
+   Notwithstanding the non-transferability in Section 1, you may reproduce and
+   distribute unmodified copies of the SDK solely as an embedded dependency of
+   your own applications and services that call the Typeless API — including
+   commercial products — and solely to the end users of those applications for
+   use with them. This is a limited distribution right only. You may not
+   distribute the SDK on a standalone basis, and you may not grant your end users
+   or any third party the right to further redistribute the SDK separately from
+   your application.
+
+3. Restrictions
+
+   Except as expressly permitted in Section 2 or the Terms, you may not:
+
+   (a) distribute, publish, sublicense, sell, rent, lease, or otherwise make the
+       SDK available on a standalone basis, or as part of any product whose
+       primary purpose is to redistribute the SDK itself;
+   (b) modify, adapt, translate, or create derivative works of the SDK, or
+       distribute any such modified or derivative version;
+   (c) reverse engineer, decompile, or disassemble the SDK, except to the extent
+       this restriction is prohibited by applicable law;
+   (d) remove, alter, or obscure any proprietary notices in the SDK; or
+   (e) use the SDK to access any service other than the Typeless API.
+
+4. API Credentials
+
+   API keys and tokens are confidential. You must not embed them in publicly
+   distributed client applications, public code repositories, or any other
+   location from which they can be extracted, and you must not share, sublicense,
+   resell, or otherwise transfer them. You are responsible for all activity that
+   occurs under your credentials.
+
+5. Reservation of Rights
+
+   The SDK is licensed, not sold, and Typeless retains all right, title, and
+   interest in and to the SDK. No rights are granted by implication or estoppel.
+   This license grants no right to use any Typeless name, logo, or trademark, and
+   grants no right of access to the Typeless service, API quota or capacity, or
+   any service level (SLA), all of which are governed solely by the Terms and
+   your plan.
+
+6. Third-Party Components
+
+   The SDK depends on third-party open-source packages (including httpx and
+   websockets), each licensed under its own terms. See THIRD_PARTY_NOTICES.md.
+   Nothing in this license limits your rights under those third-party licenses.
+
+7. Disclaimer of Warranty
+
+   THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY KIND,
+   WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. Any
+   additional warranty terms in the Terms also apply.
+
+8. Limitation of Liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, TYPELESS WILL NOT BE LIABLE
+   FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR
+   FOR ANY LOSS OF PROFITS, REVENUE, OR DATA, ARISING OUT OF OR RELATED TO YOUR
+   USE OF THE SDK, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The
+   limitations of liability in the Terms also apply.
+
+9. Termination
+
+   This license terminates automatically if you breach it or the Terms. Upon
+   termination you must stop using the SDK and delete all copies in your
+   possession or control, except that you may retain one copy solely for archival
+   or legal-compliance purposes. Sections 3 through 8 and this Section 9 survive
+   termination.
+
+10. Contact
+
+    Questions about this license: hello@typeless.com.

typeless_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: typeless-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Typeless External Transcript API
+Keywords: transcription,speech-to-text,api,typeless,websocket
+Author: Typeless
+Author-email: Typeless <hello@typeless.com>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.24,<0.29
+Requires-Dist: websockets>=14.0,<17.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://www.typeless.com/
+Project-URL: Documentation, https://docs.typelessapi.com
+Project-URL: Console, https://platform.typelessapi.com
+Project-URL: Changelog, https://docs.typelessapi.com/sdk/python#changelog
+Project-URL: Terms of Service, https://www.typeless.com/terms
+Description-Content-Type: text/markdown
+
+# Typeless Python SDK
+
+Official Python SDK for the [Typeless External Transcript API](https://docs.typelessapi.com).
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+pip install typeless-sdk
+```
+
+## Quick Start
+
+```python
+from typeless import TypelessClient
+
+client = TypelessClient(api_key="tls_sk_xxx")
+result = client.transcribe("recording.wav", model="typeless-1.0-max")
+
+print(result.transcript)
+print(result.detected_language)
+print(result.duration_seconds)
+print(result.request_id)
+print(result.usage.billed_audio_seconds)
+```
+
+## Authentication
+
+Read the API key from the environment:
+
+```bash
+export TYPELESS_API_KEY=tls_sk_xxx
+```
+
+```python
+from typeless import TypelessClient
+
+client = TypelessClient()
+```
+
+You can also override the API base URL:
+
+```bash
+export TYPELESS_BASE_URL=https://api.typelessapi.com
+```
+
+## Audio Input
+
+`transcribe()` accepts a file path, in-memory bytes, or a readable binary file object.
+The API detects the audio format from the file content.
+Supported container formats include WAV, OGG (Opus), and WebM.
+
+```python
+# file path
+result = client.transcribe("recording.wav", model="typeless-1.0-max")
+
+# in-memory bytes
+result = client.transcribe(audio_bytes, model="typeless-1.0-max")
+
+# binary file object
+with open("recording.wav", "rb") as audio_file:
+    result = client.transcribe(audio_file, model="typeless-1.0-max")
+```
+
+Optional language hint:
+
+```python
+result = client.transcribe("recording.wav", model="typeless-1.0-max", language="zh")
+```
+
+## Models
+
+The `model` parameter is required on every request.
+The SDK does not inject a default model.
+
+| Tier | Model name |
+| --- | --- |
+| Lite | `typeless-1.0-lite` |
+| Pro | `typeless-1.0-pro` |
+| Max | `typeless-1.0-max` |
+
+Unknown model values are rejected by the API with `INVALID_REQUEST`.
+
+## Limits
+
+Per-request limits are enforced by the API and may vary by account.
+Typical defaults include a maximum file size of about 50 MB and a maximum audio
+duration of about 300 seconds per request.
+
+## WebSocket Streaming
+
+Use `stream()` for real-time raw PCM16 audio such as microphone capture.
+For offline files in WAV, OGG, or WebM format, use HTTP `transcribe()` instead.
+
+```python
+from typeless import AudioReceived, StreamResult
+from typeless.exceptions import TypelessError
+
+client = TypelessClient(api_key="tls_sk_xxx")
+
+with client.stream(
+    model="typeless-1.0-max",
+    sample_rate=16000,
+    channels=1,
+    read_timeout=None,
+) as conn:
+    conn.send(pcm_chunk_bytes)
+    conn.send(pcm_chunk_bytes)
+    conn.finish()
+
+    try:
+        for msg in conn:
+            if isinstance(msg, AudioReceived):
+                print(f"processed {msg.duration_seconds}s")
+            elif isinstance(msg, StreamResult):
+                print(msg.transcript)
+                print(msg.detected_language)
+    except TypelessError as exc:
+        print(f"stream failed: [{exc.code}] {exc.message}")
+```
+
+`send()` accepts raw PCM16 bytes only (16-bit signed integer, little-endian).
+The SDK sends keep-alive messages automatically while the connection is open.
+
+| Parameter | Description |
+| --- | --- |
+| `channels` | Number of audio channels from 1 to 2 (default `1`) |
+| `read_timeout` | Maximum seconds to wait for each server message during iteration, or `None` for no limit |
+
+## Async Client
+
+```python
+from typeless import AsyncTypelessClient
+import asyncio
+
+async def main() -> None:
+    async with AsyncTypelessClient(api_key="tls_sk_xxx") as client:
+        result = await client.transcribe("audio.wav", model="typeless-1.0-max")
+
+        results = await asyncio.gather(
+            client.transcribe("a.wav", model="typeless-1.0-max"),
+            client.transcribe("b.wav", model="typeless-1.0-max"),
+            client.transcribe("c.wav", model="typeless-1.0-max"),
+        )
+
+asyncio.run(main())
+```
+
+Async streaming:
+
+```python
+from typeless import AsyncTypelessClient, StreamResult
+from typeless.exceptions import TypelessError
+
+async with AsyncTypelessClient(api_key="tls_sk_xxx") as client:
+    async with client.stream(model="typeless-1.0-max", sample_rate=16000) as conn:
+        await conn.send(pcm_chunk_bytes)
+        await conn.finish()
+        try:
+            async for msg in conn:
+                if isinstance(msg, StreamResult):
+                    print(msg.transcript)
+        except TypelessError as exc:
+            print(f"stream failed: [{exc.code}] {exc.message}")
+```
+
+## Error Handling
+
+```python
+from typeless.exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AudioFormatError,
+    AudioTooLargeError,
+    AudioTooLongError,
+    AuthenticationError,
+    ConcurrentLimitError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    RateLimitError,
+    TypelessError,
+)
+
+try:
+    result = client.transcribe("audio.wav", model="typeless-1.0-max")
+except AuthenticationError:
+    print("invalid api key")
+except InvalidRequestError as exc:
+    print(f"invalid request: {exc.message}")
+except RateLimitError as exc:
+    print(f"rate limited, retry after {exc.retry_after}s")
+except InsufficientBalanceError:
+    print("insufficient account balance")
+except AudioTooLongError as exc:
+    print(
+        f"audio too long: limit {exc.max_duration_seconds}s, "
+        f"actual {exc.actual_duration_seconds}s"
+    )
+except AudioFormatError as exc:
+    print(f"unsupported format: {exc.supported_formats}")
+except AudioTooLargeError as exc:
+    print(f"file too large: limit {exc.max_size_bytes} bytes")
+except ConcurrentLimitError as exc:
+    print(f"concurrent limit exceeded: {exc.message}")
+except APIConnectionError as exc:
+    print(f"connection failed: {exc.message}")
+except APITimeoutError as exc:
+    print(f"request timed out: {exc.message}")
+except TypelessError as exc:
+    print(f"[{exc.code}] {exc.message} (req_id={exc.request_id})")
+```
+
+## Configuration
+
+```python
+client = TypelessClient(
+    api_key="tls_sk_xxx",
+    base_url="https://api.typelessapi.com",
+    timeout=300.0,
+    max_retries=3,
+)
+```
+
+| Parameter | Description |
+| --- | --- |
+| `api_key` | API key, or read from `TYPELESS_API_KEY` when omitted |
+| `base_url` | API base URL, or read from `TYPELESS_BASE_URL` when omitted |
+| `timeout` | Request timeout in seconds (default `300`) |
+| `max_retries` | Maximum retries for transient HTTP failures (default `3`) |
+
+## Resource Management
+
+Reuse a single client instance across multiple requests so the HTTP connection pool can reuse TCP connections.
+
+```python
+with TypelessClient(api_key="tls_sk_xxx") as client:
+    result = client.transcribe("audio.wav", model="typeless-1.0-max")
+```
+
+```python
+client = TypelessClient(api_key="tls_sk_xxx")
+try:
+    result = client.transcribe("audio.wav", model="typeless-1.0-max")
+finally:
+    client.close()
+```
+
+Async client:
+
+```python
+async with AsyncTypelessClient(api_key="tls_sk_xxx") as client:
+    result = await client.transcribe("audio.wav", model="typeless-1.0-max")
+```
+
+## Response Fields
+
+A successful HTTP transcription returns a `TranscriptResult`:
+
+| Field | Description |
+| --- | --- |
+| `transcript` | Final transcript text |
+| `detected_language` | Detected language code, or `None` when unknown |
+| `duration_seconds` | Audio duration in seconds |
+| `request_id` | Request identifier for support |
+| `usage.billed_audio_seconds` | Billed audio duration in seconds |
+| `usage.output_token_count` | Output token count reported by the API |
+
+## Logging
+
+The SDK uses the standard library `logging` module with logger name `typeless`.
+By default it attaches a `NullHandler` and does not write to stderr.
+
+```python
+import logging
+
+logging.getLogger("typeless").setLevel(logging.DEBUG)
+```
+
+## Development
+
+Install the package and development dependencies in your local environment:
+
+```bash
+pip install typeless-sdk
+uv sync
+uv run ruff check src/typeless tests
+uv run mypy
+uv run pytest -m "not integration" -q
+uv build --no-sources
+```
+
+### Integration tests
+
+Unit tests run by default and do not require API credentials.
+Integration tests call a live API endpoint.
+
+```bash
+export TYPELESS_API_KEY=tls_sk_xxx
+export TYPELESS_BASE_URL=https://your-test-endpoint
+uv run pytest tests/integration -m integration -v
+```
+
+## Support
+
+Questions, bug reports, or access requests: email [hello@typeless.com](mailto:hello@typeless.com)
+and include the `request_id` from any failed response.
+
+## License
+
+Proprietary. See the [LICENSE](LICENSE) file. Use of this SDK is also subject to
+the Typeless [Terms of Service](https://www.typeless.com/terms) and
+[Privacy Policy](https://www.typeless.com/privacy).
+
+You may install the SDK and distribute it, unmodified, as an embedded dependency
+of your own applications (including commercial products) that call the Typeless
+API, and to the end users of those applications. Standalone redistribution,
+modification, and reverse engineering are not permitted. See the LICENSE file for
+the full terms.
+
+Third-party open-source components are listed in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).