lingolix 0.1.0__tar.gz

lingolix-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+node_modules/

lingolix-0.1.0/LICENSE

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

lingolix-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: lingolix
+Version: 0.1.0
+Summary: Python client for the Lingolix pronunciation scoring API
+Project-URL: Homepage, https://lingolix.com
+Project-URL: Documentation, https://lingolix.com/api-portal/docs
+Project-URL: Source, https://github.com/lingolix/lingolix-sdk
+Project-URL: Issues, https://github.com/lingolix/lingolix-sdk/issues
+Author-email: Lingolix <info@lingolix.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ipa,language-learning,phonetics,pronunciation,speech
+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: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# lingolix
+
+Python client for the [Lingolix](https://lingolix.com) pronunciation scoring API. Send a
+recording, get back per-syllable accuracy with expected vs. detected IPA, pitch and
+timing — in 17 languages.
+
+Get an API key at [lingolix.com/api-portal](https://lingolix.com/api-portal), then set
+`LINGOLIX_API_KEY` in your environment. Keep it server-side — never ship it to a browser.
+
+## Install
+
+```bash
+pip install lingolix      # or: uv add lingolix
+```
+
+## Usage
+
+```python
+from lingolix import Lingolix
+
+with Lingolix() as client:                       # key from $LINGOLIX_API_KEY
+    r = client.check("audio.wav", sentence="Guten Morgen", language="de")
+
+    print(r.accuracy, r.completeness, r.speaking_rate)
+    for word in r.words:
+        for s in word.syllables:
+            print(s.text, s.expected_ipa, "→", s.detected_ipa, s.pitch, round(s.accuracy, 2))
+```
+
+Async is the same class with an `Async` prefix:
+
+```python
+from lingolix import AsyncLingolix
+
+async with AsyncLingolix() as client:
+    r = await client.check(audio_bytes, sentence="こんにちは", language="ja")
+```
+
+`check()` takes a path, `bytes`, or any file-like object. Drop `sentence` and the audio is
+transcribed first, then scored against its own transcription — useful for free-form speech.
+
+## Result shape
+
+| Field | Meaning |
+| --- | --- |
+| `text` | What the audio was scored against — your `sentence`, or the transcription |
+| `accuracy` | Overall pronunciation accuracy, 0–1 |
+| `completeness` | How much of the expected utterance was actually said, 0–1 |
+| `speaking_rate` | Syllables per second |
+| `words[]` | `text`, `accuracy`, `completeness`, `start_ms`, `end_ms`, `char_start`, `char_end` |
+| `words[].syllables[]` | `text`, `expected_ipa`, `detected_ipa`, `accuracy`, `completeness`, `pitch`, `duration_ms`, `start_ms`, `end_ms`, `is_missing`, `is_extra` |
+
+`pitch` is one of `"high"`, `"flat"`, `"low"`, `"unknown"`.
+
+## Errors
+
+Every failure is a subclass of `LingolixError` carrying `.status` and `.detail`.
+
+| Class | HTTP | Cause |
+| --- | --- | --- |
+| `InvalidAudioError` | 400, 413 | Undecodable audio, or over the 10 MiB limit |
+| `AuthenticationError` | 401 | Missing, malformed or unknown API key |
+| `SubscriptionError` | 403 | No active API subscription |
+| `QuotaExceededError` | 429 | Monthly quota exhausted |
+| `ServiceUnavailableError` | 503 | Scoring service temporarily down |
+
+`QuotaExceededError` also carries `plan`, `remaining_minutes`, `quota_percentage` and
+`upgrade_url`:
+
+```python
+from lingolix import Lingolix, QuotaExceededError
+
+try:
+    r = Lingolix().check("audio.wav", language="en")
+except QuotaExceededError as e:
+    print(f"{e.plan} plan is out of minutes — upgrade at {e.upgrade_url}")
+```
+
+## Languages
+
+`bg cs de el en es fi fr hu it ja ko nl pl pt sv uk` — the default is `ja`.
+
+## Audio
+
+Anything ffmpeg can read: WAV, MP3, M4A, OGG/Opus, FLAC, WebM. Uploads are capped at
+10 MiB, checked client-side before sending. Prefer a compressed format — a single utterance
+is well under 1 MiB as MP3 or Opus.
+
+## Links
+
+- [TypeScript client](https://www.npmjs.com/package/@lingolix/sdk)
+- [API documentation](https://lingolix.com/api-portal/docs)
+- [Pricing](https://lingolix.com/api-portal/pricing)
+- [Source and issues](https://github.com/lingolix/lingolix-sdk)
+
+MIT licensed.

lingolix-0.1.0/README.md

@@ -0,0 +1,96 @@
+# lingolix
+
+Python client for the [Lingolix](https://lingolix.com) pronunciation scoring API. Send a
+recording, get back per-syllable accuracy with expected vs. detected IPA, pitch and
+timing — in 17 languages.
+
+Get an API key at [lingolix.com/api-portal](https://lingolix.com/api-portal), then set
+`LINGOLIX_API_KEY` in your environment. Keep it server-side — never ship it to a browser.
+
+## Install
+
+```bash
+pip install lingolix      # or: uv add lingolix
+```
+
+## Usage
+
+```python
+from lingolix import Lingolix
+
+with Lingolix() as client:                       # key from $LINGOLIX_API_KEY
+    r = client.check("audio.wav", sentence="Guten Morgen", language="de")
+
+    print(r.accuracy, r.completeness, r.speaking_rate)
+    for word in r.words:
+        for s in word.syllables:
+            print(s.text, s.expected_ipa, "→", s.detected_ipa, s.pitch, round(s.accuracy, 2))
+```
+
+Async is the same class with an `Async` prefix:
+
+```python
+from lingolix import AsyncLingolix
+
+async with AsyncLingolix() as client:
+    r = await client.check(audio_bytes, sentence="こんにちは", language="ja")
+```
+
+`check()` takes a path, `bytes`, or any file-like object. Drop `sentence` and the audio is
+transcribed first, then scored against its own transcription — useful for free-form speech.
+
+## Result shape
+
+| Field | Meaning |
+| --- | --- |
+| `text` | What the audio was scored against — your `sentence`, or the transcription |
+| `accuracy` | Overall pronunciation accuracy, 0–1 |
+| `completeness` | How much of the expected utterance was actually said, 0–1 |
+| `speaking_rate` | Syllables per second |
+| `words[]` | `text`, `accuracy`, `completeness`, `start_ms`, `end_ms`, `char_start`, `char_end` |
+| `words[].syllables[]` | `text`, `expected_ipa`, `detected_ipa`, `accuracy`, `completeness`, `pitch`, `duration_ms`, `start_ms`, `end_ms`, `is_missing`, `is_extra` |
+
+`pitch` is one of `"high"`, `"flat"`, `"low"`, `"unknown"`.
+
+## Errors
+
+Every failure is a subclass of `LingolixError` carrying `.status` and `.detail`.
+
+| Class | HTTP | Cause |
+| --- | --- | --- |
+| `InvalidAudioError` | 400, 413 | Undecodable audio, or over the 10 MiB limit |
+| `AuthenticationError` | 401 | Missing, malformed or unknown API key |
+| `SubscriptionError` | 403 | No active API subscription |
+| `QuotaExceededError` | 429 | Monthly quota exhausted |
+| `ServiceUnavailableError` | 503 | Scoring service temporarily down |
+
+`QuotaExceededError` also carries `plan`, `remaining_minutes`, `quota_percentage` and
+`upgrade_url`:
+
+```python
+from lingolix import Lingolix, QuotaExceededError
+
+try:
+    r = Lingolix().check("audio.wav", language="en")
+except QuotaExceededError as e:
+    print(f"{e.plan} plan is out of minutes — upgrade at {e.upgrade_url}")
+```
+
+## Languages
+
+`bg cs de el en es fi fr hu it ja ko nl pl pt sv uk` — the default is `ja`.
+
+## Audio
+
+Anything ffmpeg can read: WAV, MP3, M4A, OGG/Opus, FLAC, WebM. Uploads are capped at
+10 MiB, checked client-side before sending. Prefer a compressed format — a single utterance
+is well under 1 MiB as MP3 or Opus.
+
+## Links
+
+- [TypeScript client](https://www.npmjs.com/package/@lingolix/sdk)
+- [API documentation](https://lingolix.com/api-portal/docs)
+- [Pricing](https://lingolix.com/api-portal/pricing)
+- [Source and issues](https://github.com/lingolix/lingolix-sdk)
+
+MIT licensed.

lingolix-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lingolix"
+dynamic = ["version"]
+description = "Python client for the Lingolix pronunciation scoring API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Lingolix", email = "info@lingolix.com" }]
+keywords = ["pronunciation", "speech", "language-learning", "ipa", "phonetics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://lingolix.com"
+Documentation = "https://lingolix.com/api-portal/docs"
+Source = "https://github.com/lingolix/lingolix-sdk"
+Issues = "https://github.com/lingolix/lingolix-sdk/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6"]
+
+[tool.hatch.version]
+path = "src/lingolix/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lingolix"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

lingolix-0.1.0/src/lingolix/__init__.py

@@ -0,0 +1,326 @@
+"""Lingolix pronunciation API client.
+
+    from lingolix import Lingolix
+
+    with Lingolix() as client:                    # key from $LINGOLIX_API_KEY
+        r = client.check("audio.wav", sentence="Guten Morgen", language="de")
+        print(r.accuracy)
+
+Async is the same with ``AsyncLingolix`` and ``await``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import mimetypes
+import os
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, Literal, TypeVar, Union
+
+import httpx
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Lingolix",
+    "AsyncLingolix",
+    "PronunciationResult",
+    "Word",
+    "Syllable",
+    "LingolixError",
+    "AuthenticationError",
+    "SubscriptionError",
+    "InvalidAudioError",
+    "QuotaExceededError",
+    "ServiceUnavailableError",
+    "LANGUAGES",
+    "Pitch",
+    "MAX_UPLOAD_BYTES",
+    "__version__",
+]
+
+DEFAULT_BASE_URL = "https://api.lingolix.com"
+CHECK_PATH = "/api/pronunciation/v3/check"
+
+#: Mirrors the server limit in the backend's pronunciation API.
+MAX_UPLOAD_BYTES = 10 * 1024 * 1024
+
+#: Languages accepted by the v3 endpoint.
+LANGUAGES = (
+    "bg", "cs", "de", "el", "en", "es", "fi", "fr",
+    "hu", "it", "ja", "ko", "nl", "pl", "pt", "sv", "uk",
+)
+
+AudioInput = Union[str, "os.PathLike[str]", bytes, bytearray, BinaryIO]
+
+#: Relative pitch of a syllable.
+Pitch = Literal["high", "flat", "low", "unknown"]
+
+T = TypeVar("T")
+
+
+# --------------------------------------------------------------------------- errors
+
+
+class LingolixError(Exception):
+    """Base class for every error this client raises."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        detail: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.detail = detail
+
+
+class AuthenticationError(LingolixError):
+    """The API key is missing, malformed or unknown (HTTP 401)."""
+
+
+class SubscriptionError(LingolixError):
+    """No active API subscription for this key (HTTP 403)."""
+
+
+class InvalidAudioError(LingolixError):
+    """The audio could not be decoded, or was too large (HTTP 400 / 413)."""
+
+
+class QuotaExceededError(LingolixError):
+    """The monthly quota is exhausted (HTTP 429)."""
+
+    def __init__(self, message: str, *, status: int | None = None, detail: Any = None) -> None:
+        super().__init__(message, status=status, detail=detail)
+        d = detail if isinstance(detail, dict) else {}
+        self.error: str | None = d.get("error")
+        self.plan: str | None = d.get("plan")
+        self.upgrade_url: str | None = d.get("upgrade_url")
+        self.remaining_minutes: float | None = d.get("remaining_minutes")
+        self.quota_percentage: float | None = d.get("quota_percentage")
+
+
+class ServiceUnavailableError(LingolixError):
+    """The scoring service is temporarily unreachable (HTTP 503)."""
+
+
+_ERRORS: dict[int, type[LingolixError]] = {
+    400: InvalidAudioError,
+    401: AuthenticationError,
+    403: SubscriptionError,
+    413: InvalidAudioError,
+    429: QuotaExceededError,
+    503: ServiceUnavailableError,
+}
+
+
+# --------------------------------------------------------------------------- results
+
+
+@dataclass(frozen=True)
+class Syllable:
+    """One syllable of a word, with expected vs. detected pronunciation."""
+
+    text: str
+    expected_ipa: str
+    detected_ipa: str
+    accuracy: float
+    completeness: float
+    pitch: Pitch
+    duration_ms: float
+    start_ms: float
+    end_ms: float
+    is_missing: bool
+    is_extra: bool
+
+
+@dataclass(frozen=True)
+class Word:
+    """One word, broken into syllables."""
+
+    text: str
+    syllables: list[Syllable]
+    accuracy: float
+    completeness: float
+    start_ms: float
+    end_ms: float
+    char_start: int = -1
+    char_end: int = -1
+
+
+@dataclass(frozen=True)
+class PronunciationResult:
+    """The scored utterance.
+
+    ``text`` is the reference the audio was scored against: the ``sentence`` you
+    passed, or the transcription when you passed none.
+    """
+
+    text: str
+    speaking_rate: float
+    accuracy: float
+    completeness: float
+    words: list[Word] = field(default_factory=list)
+
+
+def _mk(cls: type[T], data: dict[str, Any]) -> T:
+    # ponytail: drop unknown keys so a new backend field doesn't break installed clients
+    names = {f.name for f in dataclasses.fields(cls)}  # type: ignore[arg-type]
+    return cls(**{k: v for k, v in data.items() if k in names})
+
+
+def _to_result(data: dict[str, Any]) -> PronunciationResult:
+    words = [
+        _mk(Word, {**w, "syllables": [_mk(Syllable, s) for s in w.get("syllables", [])]})
+        for w in data.get("words", [])
+    ]
+    return _mk(PronunciationResult, {**data, "words": words})
+
+
+# --------------------------------------------------------------------------- clients
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("LINGOLIX_API_KEY")
+        if not key:
+            raise LingolixError(
+                "No API key. Pass Lingolix(api_key=...) or set the LINGOLIX_API_KEY "
+                "environment variable. Create a key at https://lingolix.com/api-portal"
+            )
+        self.api_key = key
+        self.base_url = (
+            base_url or os.environ.get("LINGOLIX_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        # Scoring is slow; a short default timeout would just cause spurious failures.
+        self.timeout = timeout if timeout is not None else httpx.Timeout(120.0, connect=10.0)
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"lingolix-python/{__version__}",
+        }
+
+    @staticmethod
+    def _multipart(
+        audio: AudioInput, sentence: str | None, language: str
+    ) -> tuple[dict[str, Any], dict[str, str]]:
+        if isinstance(audio, (bytes, bytearray)):
+            content: Any = bytes(audio)
+            name, mime = "audio.wav", "application/octet-stream"
+        elif isinstance(audio, (str, os.PathLike)):
+            path = os.fspath(audio)
+            with open(path, "rb") as fh:
+                content = fh.read()
+            name = os.path.basename(path) or "audio.wav"
+            mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
+        else:  # file-like
+            content = audio.read()
+            name = os.path.basename(getattr(audio, "name", "") or "") or "audio.wav"
+            mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
+
+        if len(content) > MAX_UPLOAD_BYTES:
+            raise InvalidAudioError(
+                f"Audio is {len(content) / 1048576:.1f} MiB, over the "
+                f"{MAX_UPLOAD_BYTES // 1048576} MiB limit. Send a compressed format "
+                "(MP3, Opus/WebM, AAC) instead of WAV — a single utterance is well "
+                "under 1 MiB when encoded."
+            )
+
+        data = {"language_code": language}
+        if sentence is not None:
+            data["sentence"] = sentence
+        return {"speechdata": (name, content, mime)}, data
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> PronunciationResult:
+        if response.status_code == 200:
+            return _to_result(response.json())
+
+        try:
+            # FastAPI puts a string here normally, and a dict for the 429 quota payload.
+            detail = response.json().get("detail")
+        except ValueError:
+            detail = response.text or None
+
+        if isinstance(detail, dict):
+            message = detail.get("message") or detail.get("error") or str(detail)
+        else:
+            message = detail or f"HTTP {response.status_code}"
+
+        cls = _ERRORS.get(response.status_code, LingolixError)
+        raise cls(str(message), status=response.status_code, detail=detail)
+
+
+class Lingolix(_BaseClient):
+    """Synchronous client. Usable as a context manager."""
+
+    def __init__(self, api_key: str | None = None, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._client = httpx.Client(
+            base_url=self.base_url, headers=self._headers, timeout=self.timeout
+        )
+
+    def check(
+        self,
+        audio: AudioInput,
+        *,
+        sentence: str | None = None,
+        language: str = "ja",
+    ) -> PronunciationResult:
+        """Score ``audio``.
+
+        Pass ``sentence`` to score against known text; omit it to have the audio
+        transcribed first and scored against its own transcription.
+        """
+        files, data = self._multipart(audio, sentence, language)
+        return self._parse(self._client.post(CHECK_PATH, files=files, data=data))
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Lingolix:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncLingolix(_BaseClient):
+    """Asynchronous client. Usable as an async context manager."""
+
+    def __init__(self, api_key: str | None = None, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url, headers=self._headers, timeout=self.timeout
+        )
+
+    async def check(
+        self,
+        audio: AudioInput,
+        *,
+        sentence: str | None = None,
+        language: str = "ja",
+    ) -> PronunciationResult:
+        """Score ``audio``. See :meth:`Lingolix.check`."""
+        files, data = self._multipart(audio, sentence, language)
+        return self._parse(await self._client.post(CHECK_PATH, files=files, data=data))
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncLingolix:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()

lingolix-0.1.0/tests/test_client.py

@@ -0,0 +1,205 @@
+"""Client tests against a mocked transport — no network, no extra dependencies."""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import pytest
+
+from lingolix import (
+    AsyncLingolix,
+    AuthenticationError,
+    InvalidAudioError,
+    Lingolix,
+    QuotaExceededError,
+    ServiceUnavailableError,
+)
+
+KEY = "lx_test_key"
+
+# A real-shaped v3 response, plus an unknown field the backend might add later.
+OK_BODY = {
+    "text": "Guten Morgen",
+    "speaking_rate": 3.5,
+    "accuracy": 0.87,
+    "completeness": 1.0,
+    "future_field": "ignored",
+    "words": [
+        {
+            "text": "Guten",
+            "accuracy": 0.9,
+            "completeness": 1.0,
+            "start_ms": 0.0,
+            "end_ms": 400.0,
+            "char_start": 0,
+            "char_end": 5,
+            "syllables": [
+                {
+                    "text": "Gu",
+                    "expected_ipa": "ɡuː",
+                    "detected_ipa": "ɡu",
+                    "accuracy": 0.92,
+                    "completeness": 1.0,
+                    "pitch": "high",
+                    "duration_ms": 200.0,
+                    "start_ms": 0.0,
+                    "end_ms": 200.0,
+                    "is_missing": False,
+                    "is_extra": False,
+                    "future_field": "ignored",
+                }
+            ],
+        }
+    ],
+}
+
+QUOTA_BODY = {
+    "detail": {
+        "error": "quota_exceeded",
+        "message": "Monthly quota exhausted.",
+        "quota_percentage": 100.0,
+        "remaining_minutes": 0.0,
+        "plan": "free",
+        "upgrade_url": "https://lingolix.com/api-portal/pricing",
+    }
+}
+
+
+def make_client(handler, *, cls=Lingolix):
+    """Build a client whose HTTP layer is `handler` instead of the network."""
+    client = cls(KEY)
+    transport = httpx.MockTransport(handler)
+    inner = client._client
+    client._client = type(inner)(
+        base_url=inner.base_url, headers=inner.headers, transport=transport
+    )
+    return client
+
+
+def test_request_shape():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["auth"] = request.headers["authorization"]
+        seen["body"] = request.content.decode("utf-8", "replace")
+        return httpx.Response(200, json=OK_BODY)
+
+    with make_client(handler) as client:
+        client.check(b"RIFFfake", sentence="Guten Morgen", language="de")
+
+    assert seen["url"] == "https://api.lingolix.com/api/pronunciation/v3/check"
+    assert seen["auth"] == f"Bearer {KEY}"
+    assert 'name="speechdata"' in seen["body"]
+    assert 'name="sentence"' in seen["body"] and "Guten Morgen" in seen["body"]
+    assert 'name="language_code"' in seen["body"] and "de" in seen["body"]
+
+
+def test_sentence_omitted_when_none():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = request.content.decode("utf-8", "replace")
+        return httpx.Response(200, json=OK_BODY)
+
+    with make_client(handler) as client:
+        client.check(b"RIFFfake")
+
+    assert 'name="sentence"' not in seen["body"]
+    assert 'name="language_code"' in seen["body"]
+
+
+def test_parses_nested_result_and_ignores_unknown_fields():
+    with make_client(lambda r: httpx.Response(200, json=OK_BODY)) as client:
+        result = client.check(b"RIFFfake", sentence="Guten Morgen", language="de")
+
+    assert result.accuracy == 0.87
+    assert result.text == "Guten Morgen"
+    assert result.words[0].text == "Guten"
+    syllable = result.words[0].syllables[0]
+    assert syllable.expected_ipa == "ɡuː"
+    assert syllable.pitch == "high"
+    assert syllable.is_missing is False
+
+
+def test_quota_error_exposes_upgrade_url():
+    handler = lambda r: httpx.Response(429, json=QUOTA_BODY)  # noqa: E731
+    with make_client(handler) as client:
+        with pytest.raises(QuotaExceededError) as excinfo:
+            client.check(b"RIFFfake")
+
+    err = excinfo.value
+    assert err.status == 429
+    assert err.plan == "free"
+    assert err.upgrade_url == "https://lingolix.com/api-portal/pricing"
+    assert "quota" in str(err).lower()
+
+
+@pytest.mark.parametrize(
+    ("status", "expected"),
+    [
+        (401, AuthenticationError),
+        (400, InvalidAudioError),
+        (503, ServiceUnavailableError),
+    ],
+)
+def test_string_detail_errors(status, expected):
+    handler = lambda r: httpx.Response(status, json={"detail": "nope"})  # noqa: E731
+    with make_client(handler) as client:
+        with pytest.raises(expected, match="nope"):
+            client.check(b"RIFFfake")
+
+
+def test_oversized_audio_rejected_before_request():
+    def handler(request: httpx.Request) -> httpx.Response:  # pragma: no cover
+        raise AssertionError("request should not have been sent")
+
+    with make_client(handler) as client:
+        with pytest.raises(InvalidAudioError, match="10 MiB limit"):
+            client.check(b"x" * (10 * 1024 * 1024 + 1))
+
+
+def test_missing_api_key(monkeypatch):
+    monkeypatch.delenv("LINGOLIX_API_KEY", raising=False)
+    with pytest.raises(Exception, match="LINGOLIX_API_KEY"):
+        Lingolix()
+
+
+def test_file_path_upload(tmp_path):
+    path = tmp_path / "sample.wav"
+    path.write_bytes(b"RIFFfake")
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = request.content.decode("utf-8", "replace")
+        return httpx.Response(200, json=OK_BODY)
+
+    with make_client(handler) as client:
+        client.check(path, language="ja")
+
+    assert "sample.wav" in seen["body"]
+    assert "RIFFfake" in seen["body"]
+
+
+def test_async_client():
+    async def run():
+        client = make_client(lambda r: httpx.Response(200, json=OK_BODY), cls=AsyncLingolix)
+        async with client:
+            return await client.check(b"RIFFfake", sentence="Guten Morgen", language="de")
+
+    result = asyncio.run(run())
+    assert result.accuracy == 0.87
+    assert result.words[0].syllables[0].text == "Gu"
+
+
+def test_async_quota_error():
+    async def run():
+        client = make_client(
+            lambda r: httpx.Response(429, json=QUOTA_BODY), cls=AsyncLingolix
+        )
+        async with client:
+            await client.check(b"RIFFfake")
+
+    with pytest.raises(QuotaExceededError):
+        asyncio.run(run())