lexiafrik 2.0.0__tar.gz

lexiafrik-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XEL SOFT AI
+
+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.

lexiafrik-2.0.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: lexiafrik
+Version: 2.0.0
+Summary: Python SDK and command line for LexiAfrik: speech-to-text for African languages
+Home-page: https://lexiafrik.com
+Author: XEL SOFT AI
+Author-email: contact@xelsoftai.com
+License: MIT
+Project-URL: Documentation, https://docs.lexiafrik.com
+Project-URL: Source, https://github.com/xelsoft-ai/lexiafrik-python
+Project-URL: Contact, https://lexiafrik.com/contact
+Keywords: wolof,african-languages,speech-to-text,transcription,lexiafrik,asr
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# LexiAfrik Python SDK
+
+Official Python SDK and command line for the [LexiAfrik API](https://docs.lexiafrik.com): speech-to-text for
+Wolof and 30+ other African languages. Full documentation: **https://docs.lexiafrik.com**
+
+🇫🇷 [Version française](https://github.com/xelsoft-ai/lexiafrik-python/blob/main/README.fr.md)
+
+## Installation
+
+```bash
+pip install lexiafrik
+```
+
+Python 3.8 or newer.
+
+## Sign in from the terminal
+
+```bash
+lexiafrik login      # prints a code, opens your browser, saves a key
+lexiafrik whoami     # the saved key and its plan
+lexiafrik logout     # deletes the credentials and revokes this terminal's key
+```
+
+`lexiafrik login` needs no password and no key to copy: you sign in on lexiafrik.com, check the code shown
+in the terminal and approve. An API key dedicated to this terminal is created on your account and saved in
+`~/.lexiafrik/credentials.json` (readable by you only). You can revoke it at any time from
+**lexiafrik.com > API keys**.
+
+Key lookup order: the `api_key=` argument, the `LEXIAFRIK_API_KEY` environment variable, then the file saved
+by `lexiafrik login`. On a server or in CI, create a key on the website and use the environment variable.
+
+## Usage
+
+```python
+from lexiafrik import LexiAfrikClient
+
+client = LexiAfrikClient()
+
+# Short file (50 MB maximum): immediate response
+result = client.transcribe("speech.wav", language="wo", include_segments=True)
+print(result.text)
+for seg in result.segments:
+    print(seg)                    # [0.4s → 6.1s] First segment.
+
+# Large file or video: direct upload, asynchronous job, wait for the result
+result = client.transcribe_large("conference.mp4", language="wo",
+                                 on_progress=lambda n: print(n, "segments"))
+
+# Direct link to an audio or video file
+result = client.transcribe_url("https://example.com/recording.mp3")
+
+# Languages, account, history
+print([l.code for l in client.list_languages()])
+print(client.get_account().available_minutes, "minutes available")
+for t in client.list_transcriptions(page_size=5).items:
+    print(t.request_id, t.status)
+```
+
+Links to streaming platforms (YouTube, TikTok…) are not accepted: provide a direct link or upload the file.
+
+## Error handling
+
+```python
+from lexiafrik import LexiAfrikClient, AuthenticationError, QuotaExceededError, LexiAfrikError
+
+try:
+    result = client.transcribe("audio.wav")
+except AuthenticationError:
+    print("Invalid key: run `lexiafrik login` again")
+except QuotaExceededError:
+    print("Monthly quota and credit exhausted")
+except LexiAfrikError as e:
+    print(e)            # English message; e.detail holds the server's own text, if any
+```
+
+Exceptions: `AuthenticationError` (401/403), `QuotaExceededError` (402), `NotFoundError` (404),
+`AudioTooLargeError` (413), `UnsupportedFormatError` (415), `TranscriptionError` (422),
+`RateLimitError` (429), `APIError` (5xx).
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `LEXIAFRIK_API_KEY` | API key (takes priority over the saved file). |
+| `LEXIAFRIK_BASE_URL` | Another API address (tests). Default: `https://api.lexiafrik.com`. |
+| `LEXIAFRIK_CREDENTIALS` | Another location for the credentials file. |
+| `LEXIAFRIK_LANG` | Preferred language of server messages, sent as `Accept-Language` (default: `en`). |
+
+## Migrating from version 1
+
+SDK 2.0 follows the current API: a single result type (`TranscriptionResult`) for every mode, `get_usage()`
+returns the account (plan, monthly quota, credit) rather than daily limits, and the `model`, `n_tokens`
+and `rtf` fields of the result no longer exist.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+No external network and no real key needed.
+
+## Get an API key
+
+Create an account on [lexiafrik.com](https://lexiafrik.com), or run `lexiafrik login`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lexiafrik-2.0.0/README.md

@@ -0,0 +1,109 @@
+# LexiAfrik Python SDK
+
+Official Python SDK and command line for the [LexiAfrik API](https://docs.lexiafrik.com): speech-to-text for
+Wolof and 30+ other African languages. Full documentation: **https://docs.lexiafrik.com**
+
+🇫🇷 [Version française](https://github.com/xelsoft-ai/lexiafrik-python/blob/main/README.fr.md)
+
+## Installation
+
+```bash
+pip install lexiafrik
+```
+
+Python 3.8 or newer.
+
+## Sign in from the terminal
+
+```bash
+lexiafrik login      # prints a code, opens your browser, saves a key
+lexiafrik whoami     # the saved key and its plan
+lexiafrik logout     # deletes the credentials and revokes this terminal's key
+```
+
+`lexiafrik login` needs no password and no key to copy: you sign in on lexiafrik.com, check the code shown
+in the terminal and approve. An API key dedicated to this terminal is created on your account and saved in
+`~/.lexiafrik/credentials.json` (readable by you only). You can revoke it at any time from
+**lexiafrik.com > API keys**.
+
+Key lookup order: the `api_key=` argument, the `LEXIAFRIK_API_KEY` environment variable, then the file saved
+by `lexiafrik login`. On a server or in CI, create a key on the website and use the environment variable.
+
+## Usage
+
+```python
+from lexiafrik import LexiAfrikClient
+
+client = LexiAfrikClient()
+
+# Short file (50 MB maximum): immediate response
+result = client.transcribe("speech.wav", language="wo", include_segments=True)
+print(result.text)
+for seg in result.segments:
+    print(seg)                    # [0.4s → 6.1s] First segment.
+
+# Large file or video: direct upload, asynchronous job, wait for the result
+result = client.transcribe_large("conference.mp4", language="wo",
+                                 on_progress=lambda n: print(n, "segments"))
+
+# Direct link to an audio or video file
+result = client.transcribe_url("https://example.com/recording.mp3")
+
+# Languages, account, history
+print([l.code for l in client.list_languages()])
+print(client.get_account().available_minutes, "minutes available")
+for t in client.list_transcriptions(page_size=5).items:
+    print(t.request_id, t.status)
+```
+
+Links to streaming platforms (YouTube, TikTok…) are not accepted: provide a direct link or upload the file.
+
+## Error handling
+
+```python
+from lexiafrik import LexiAfrikClient, AuthenticationError, QuotaExceededError, LexiAfrikError
+
+try:
+    result = client.transcribe("audio.wav")
+except AuthenticationError:
+    print("Invalid key: run `lexiafrik login` again")
+except QuotaExceededError:
+    print("Monthly quota and credit exhausted")
+except LexiAfrikError as e:
+    print(e)            # English message; e.detail holds the server's own text, if any
+```
+
+Exceptions: `AuthenticationError` (401/403), `QuotaExceededError` (402), `NotFoundError` (404),
+`AudioTooLargeError` (413), `UnsupportedFormatError` (415), `TranscriptionError` (422),
+`RateLimitError` (429), `APIError` (5xx).
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `LEXIAFRIK_API_KEY` | API key (takes priority over the saved file). |
+| `LEXIAFRIK_BASE_URL` | Another API address (tests). Default: `https://api.lexiafrik.com`. |
+| `LEXIAFRIK_CREDENTIALS` | Another location for the credentials file. |
+| `LEXIAFRIK_LANG` | Preferred language of server messages, sent as `Accept-Language` (default: `en`). |
+
+## Migrating from version 1
+
+SDK 2.0 follows the current API: a single result type (`TranscriptionResult`) for every mode, `get_usage()`
+returns the account (plan, monthly quota, credit) rather than daily limits, and the `model`, `n_tokens`
+and `rtf` fields of the result no longer exist.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+No external network and no real key needed.
+
+## Get an API key
+
+Create an account on [lexiafrik.com](https://lexiafrik.com), or run `lexiafrik login`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lexiafrik-2.0.0/lexiafrik/__init__.py

@@ -0,0 +1,54 @@
+"""
+LexiAfrik SDK — speech-to-text for Wolof and other African languages
+
+Quick start:
+    from lexiafrik import LexiAfrikClient
+
+    client = LexiAfrikClient()          # key: api_key=, LEXIAFRIK_API_KEY or `lexiafrik login`
+    result = client.transcribe("audio.wav", language="wo")
+    print(result.text)
+"""
+
+from .client import LexiAfrikClient
+from .models import (
+    AccountInfo,
+    Language,
+    SegmentResult,
+    TranscriptionPage,
+    TranscriptionResult,
+    TranscriptionSummary,
+    URLTranscriptionResult,
+)
+from .exceptions import (
+    LexiAfrikError,
+    AuthenticationError,
+    QuotaExceededError,
+    RateLimitError,
+    NotFoundError,
+    AudioTooLargeError,
+    UnsupportedFormatError,
+    TranscriptionError,
+    APIError,
+)
+
+__version__ = "2.0.0"
+__author__ = "XEL SOFT AI"
+__all__ = [
+    "LexiAfrikClient",
+    "TranscriptionResult",
+    "URLTranscriptionResult",
+    "SegmentResult",
+    "AccountInfo",
+    "Language",
+    "TranscriptionPage",
+    "TranscriptionSummary",
+    "LexiAfrikError",
+    "AuthenticationError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "NotFoundError",
+    "AudioTooLargeError",
+    "UnsupportedFormatError",
+    "TranscriptionError",
+    "APIError",
+]

lexiafrik-2.0.0/lexiafrik/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

lexiafrik-2.0.0/lexiafrik/auth.py

@@ -0,0 +1,143 @@
+"""
+LexiAfrik SDK — Sign in a terminal without a password (device-code flow, RFC 8628).
+
+    from lexiafrik.auth import login
+    login()                      # prints a code, opens the browser, saves the key
+
+The API key is created on your account when you approve, then saved in
+``~/.lexiafrik/credentials.json`` (readable by you only). ``LexiAfrikClient()`` finds it
+afterwards without any parameter. It stays revocable from lexiafrik.com > API keys.
+"""
+
+import json
+import os
+import platform
+import socket
+import time
+import webbrowser
+from pathlib import Path
+from typing import Callable, Optional
+
+import httpx
+
+from .exceptions import AuthenticationError, LexiAfrikError
+
+DEFAULT_BASE_URL = "https://api.lexiafrik.com"
+
+
+def credentials_path() -> Path:
+    """Credentials file (set LEXIAFRIK_CREDENTIALS to move it)."""
+    override = os.environ.get("LEXIAFRIK_CREDENTIALS")
+    return Path(override) if override else Path.home() / ".lexiafrik" / "credentials.json"
+
+
+def load_credentials() -> Optional[dict]:
+    try:
+        data = json.loads(credentials_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) and data.get("api_key") else None
+
+
+def save_credentials(data: dict) -> Path:
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        pass
+    # Created directly as 0600: the key is never readable by other users.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    return path
+
+
+def clear_credentials() -> bool:
+    try:
+        credentials_path().unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def default_client_name() -> str:
+    try:
+        host = socket.gethostname()
+    except OSError:
+        host = "terminal"
+    return f"{host} ({platform.system() or 'CLI'})"[:60]
+
+
+def login(
+    base_url: Optional[str] = None,
+    client_name: Optional[str] = None,
+    open_browser: bool = True,
+    echo: Callable[[str], None] = print,
+    save: bool = True,
+    timeout: float = 30.0,
+) -> dict:
+    """
+    Connect this terminal to your LexiAfrik account.
+
+    Returns:
+        ``{"api_key", "key_hash", "prefix", "name", "base_url"}`` (saved to disk when ``save``).
+
+    Raises:
+        AuthenticationError: sign-in denied in the browser.
+        LexiAfrikError: code expired or API unreachable.
+    """
+    base = (base_url or os.environ.get("LEXIAFRIK_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+    with httpx.Client(base_url=base, timeout=timeout) as http:
+        try:
+            r = http.post("/v1/auth/device", json={"client_name": client_name or default_client_name()})
+        except httpx.HTTPError as e:
+            raise LexiAfrikError(f"API unreachable ({base}): {e}") from e
+        if r.status_code == 429:
+            raise LexiAfrikError("Too many attempts. Try again in a few minutes.")
+        if r.status_code != 200:
+            raise LexiAfrikError(f"Could not start the sign-in (HTTP {r.status_code}).")
+        d = r.json()
+
+        url = d["verification_uri_complete"]
+        echo("")
+        echo("To connect this terminal, open:")
+        echo(f"  {url}")
+        echo("")
+        echo(f"Confirmation code: {d['user_code']}")
+        echo("(only approve if you just ran this command)")
+        echo("")
+        if open_browser:
+            try:
+                webbrowser.open(url)
+            except Exception:  # no browser (server, SSH): the URL stays displayed
+                pass
+        echo("Waiting for your approval…")
+
+        interval = max(1, int(d.get("interval", 5)))
+        deadline = time.monotonic() + int(d.get("expires_in", 600))
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            try:
+                r = http.post("/v1/auth/device/token", json={"device_code": d["device_code"]})
+            except httpx.HTTPError:
+                continue  # transient network failure
+            if r.status_code == 200:
+                creds = {**r.json(), "base_url": base}
+                if save:
+                    path = save_credentials(creds)
+                    echo(f"Signed in. Key '{creds['name']}' saved to {path}")
+                return creds
+            is_json = r.headers.get("content-type", "").startswith("application/json")
+            err = (r.json() if is_json else {}).get("error")
+            if err == "authorization_pending":
+                continue
+            if err == "slow_down":
+                interval += 5
+                continue
+            if err == "access_denied":
+                raise AuthenticationError("Sign-in denied in the browser.")
+            if err == "expired_token":
+                raise LexiAfrikError("The code has expired. Run `lexiafrik login` again.")
+            raise LexiAfrikError(f"Sign-in failed ({err or r.status_code}).")
+    raise LexiAfrikError("The code has expired. Run `lexiafrik login` again.")

lexiafrik-2.0.0/lexiafrik/cli.py

@@ -0,0 +1,82 @@
+"""LexiAfrik SDK — command line: ``lexiafrik login | logout | whoami``."""
+
+import argparse
+import sys
+
+import httpx
+
+from . import __version__
+from .auth import DEFAULT_BASE_URL, clear_credentials, credentials_path, load_credentials, login
+from .exceptions import LexiAfrikError
+
+
+def _login(args) -> int:
+    login(base_url=args.base_url, client_name=args.name, open_browser=not args.no_browser)
+    return 0
+
+
+def _logout(args) -> int:
+    creds = load_credentials()
+    if not creds:
+        print("No saved credentials.")
+        return 0
+    if not args.keep_key and creds.get("key_hash"):
+        # Revoke this terminal's key on the LexiAfrik side (best effort: the file is deleted regardless).
+        try:
+            r = httpx.delete(f"{creds.get('base_url', DEFAULT_BASE_URL)}/v1/keys/{creds['key_hash']}",
+                             headers={"X-API-Key": creds["api_key"]}, timeout=15)
+            print("Key revoked." if r.status_code < 300 else
+                  "The key could not be revoked; revoke it from lexiafrik.com > API keys.")
+        except httpx.HTTPError:
+            print("API unreachable: revoke the key from lexiafrik.com > API keys.")
+    clear_credentials()
+    print(f"Credentials deleted ({credentials_path()}).")
+    return 0
+
+
+def _whoami(_args) -> int:
+    creds = load_credentials()
+    if not creds:
+        print("Not signed in. Run `lexiafrik login`.")
+        return 1
+    r = httpx.get(f"{creds.get('base_url', DEFAULT_BASE_URL)}/v1/whoami",
+                  headers={"X-API-Key": creds["api_key"]}, timeout=15)
+    if r.status_code != 200:
+        print("Invalid or revoked key. Run `lexiafrik login` again.")
+        return 1
+    who = r.json()
+    print(f"Key: {creds.get('name', '')} ({creds.get('prefix', '')}…)  Plan: {who.get('tier', '?')}")
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="lexiafrik", description="LexiAfrik - speech-to-text for African languages")
+    parser.add_argument("--version", action="version", version=f"lexiafrik {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("login", help="connect this terminal to your account (no password)")
+    p.add_argument("--no-browser", action="store_true", help="print the link without opening the browser")
+    p.add_argument("--name", help="name of this terminal (shown when you approve it)")
+    p.add_argument("--base-url", help=f"API URL (default: {DEFAULT_BASE_URL})")
+    p.set_defaults(func=_login)
+
+    p = sub.add_parser("logout", help="delete saved credentials and revoke this terminal's key")
+    p.add_argument("--keep-key", action="store_true", help="do not revoke the key on the LexiAfrik side")
+    p.set_defaults(func=_logout)
+
+    p = sub.add_parser("whoami", help="show the saved key and its plan")
+    p.set_defaults(func=_whoami)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except LexiAfrikError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())