lingolix 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+lingolix/__init__.py,sha256=R7FVS4ANDOBz145vAhClAICFU6RicJwMWWW6NYH2-eo,9981
+lingolix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lingolix-0.1.0.dist-info/METADATA,sha256=eSvS1X10Eotsym_Tu-qbPOIiASweG5z-N1LsngoQPDc,4367
+lingolix-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+lingolix-0.1.0.dist-info/licenses/LICENSE,sha256=lNSXxmSbu2hVRSpqHGQyBK52fDWQf-tnlNjMcfEM_7M,1065
+lingolix-0.1.0.dist-info/RECORD,,

lingolix-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lingolix-0.1.0.dist-info/licenses/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.