gaston 0.2.0__py3-none-any.whl

gaston/__init__.py

@@ -0,0 +1,60 @@
+"""Python client library for the Gaston API.
+
+Transcription, translation and full-text search of sentences within
+transcribed recordings.
+"""
+
+from __future__ import annotations
+
+from .client import GastonClient
+from .constants import (
+    SUPPORTED_LANGUAGES,
+    TRANSLATION_LANGUAGES,
+    TRANSLATION_OPTIONS,
+)
+from .exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    GastonAPIError,
+    GastonError,
+    NotFoundError,
+    RateLimitError,
+)
+from .models import (
+    Directory,
+    Media,
+    MediaList,
+    SearchResults,
+    Sentence,
+    TranscribeResult,
+    TranslateResult,
+    Usage,
+    User,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "GastonClient",
+    # exceptions
+    "GastonError",
+    "GastonAPIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "NotFoundError",
+    "RateLimitError",
+    # models
+    "User",
+    "Usage",
+    "Media",
+    "MediaList",
+    "Sentence",
+    "Directory",
+    "TranscribeResult",
+    "TranslateResult",
+    "SearchResults",
+    # constants
+    "SUPPORTED_LANGUAGES",
+    "TRANSLATION_LANGUAGES",
+    "TRANSLATION_OPTIONS",
+]

gaston/client.py

@@ -0,0 +1,395 @@
+"""Synchronous client for the Gaston API."""
+
+from __future__ import annotations
+
+import os
+from typing import IO, Any, BinaryIO, Iterable, Mapping, Tuple, Union
+
+import requests
+
+from .constants import SUPPORTED_LANGUAGES, TRANSLATION_LANGUAGES
+from .exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    GastonAPIError,
+    GastonError,
+    NotFoundError,
+    RateLimitError,
+)
+from .models import (
+    Directory,
+    Media,
+    MediaList,
+    SearchResults,
+    TranscribeResult,
+    TranslateResult,
+    User,
+)
+
+BASE_URL = "https://api.gaston.live"
+# Undocumented escape hatch for development/testing only.
+_BASE_URL_OVERRIDE_ENV = "GASTON_API_URL_OVERRIDE"
+
+# Timeouts are passed straight to requests: a single value covers both connect
+# and read; a (connect, read) tuple sets them separately; None waits forever.
+TimeoutType = Union[float, Tuple[float, float], None]
+
+# Quick metadata calls.
+DEFAULT_TIMEOUT: TimeoutType = 30.0
+# Endpoints that upload a file or fetch a remote URL can legitimately take
+# minutes, so they get a much more generous read timeout by default.
+DEFAULT_UPLOAD_TIMEOUT: TimeoutType = (10.0, 600.0)
+
+
+class _Unset:
+    """Sentinel for "argument not provided" (since None is a valid timeout)."""
+
+
+_UNSET = _Unset()
+
+_STATUS_EXCEPTIONS = {
+    400: BadRequestError,
+    403: AuthenticationError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+class GastonClient:
+    """A client for the Gaston transcription/translation/search API.
+
+    Args:
+        token: API token (the ``gapi-...`` token issued by the platform).
+            Falls back to the ``GASTON_API_TOKEN`` environment variable.
+        timeout: Timeout for ordinary requests. A single float covers both
+            connect and read; a ``(connect, read)`` tuple sets them separately;
+            ``None`` waits indefinitely. Defaults to 30s.
+        upload_timeout: Timeout for the file-upload endpoint (``transcribe``),
+            which can take minutes for large files. Defaults to
+            ``(10s connect, 600s read)``.
+        session: An optional pre-configured :class:`requests.Session`.
+
+    Example::
+
+        from gaston import GastonClient
+
+        client = GastonClient(token="gapi-...")
+        me = client.me()
+        print(me.email, me.usage.files_left)
+
+    The client can also be used as a context manager to ensure the underlying
+    HTTP session is closed::
+
+        with GastonClient(token="gapi-...") as client:
+            client.transcribe("interview.mp4", lang="en")
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        timeout: TimeoutType = DEFAULT_TIMEOUT,
+        upload_timeout: TimeoutType = DEFAULT_UPLOAD_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        token = token or os.getenv("GASTON_API_TOKEN")
+        if not token:
+            raise GastonError(
+                "An API token is required (pass token=... or set GASTON_API_TOKEN)."
+            )
+        self.token = token
+        self.base_url = (os.getenv(_BASE_URL_OVERRIDE_ENV) or BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.upload_timeout = upload_timeout
+        self._session = session or requests.Session()
+        self._session.headers.update({"token": token})
+
+    # -- context manager -------------------------------------------------
+
+    def __enter__(self) -> "GastonClient":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    # -- low level -------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        files: Mapping[str, Any] | None = None,
+        timeout: TimeoutType | _Unset = _UNSET,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        # Drop params that are None so we don't send "dir_id=None" literally.
+        clean_params = None
+        if params is not None:
+            clean_params = {k: v for k, v in params.items() if v is not None}
+
+        try:
+            resp = self._session.request(
+                method,
+                url,
+                params=clean_params,
+                files=files,
+                timeout=self.timeout if isinstance(timeout, _Unset) else timeout,
+            )
+        except requests.RequestException as exc:
+            raise GastonError(f"Request to {url} failed: {exc}") from exc
+
+        return self._handle_response(resp)
+
+    @staticmethod
+    def _handle_response(resp: requests.Response) -> Any:
+        try:
+            body = resp.json()
+        except ValueError:
+            if resp.ok:
+                return resp.text
+            raise GastonAPIError(
+                f"Non-JSON response from server: {resp.text[:200]}",
+                status_code=resp.status_code,
+            )
+
+        # The API signals failures both via HTTP status codes and via an
+        # ``error`` key in an otherwise 200 response. Handle both.
+        error_message = body.get("error") if isinstance(body, dict) else None
+
+        if not resp.ok or error_message is not None:
+            exc_cls = _STATUS_EXCEPTIONS.get(resp.status_code, GastonAPIError)
+            details = None
+            if isinstance(body, dict):
+                details = (
+                    body.get("details")
+                    or body.get("supported_languages")
+                    or body.get("supportedLanguages")
+                )
+            raise exc_cls(
+                message=error_message or f"Request failed with status {resp.status_code}",
+                status_code=resp.status_code,
+                details=details,
+                payload=body,
+            )
+
+        return body
+
+    # -- user ------------------------------------------------------------
+
+    def me(self) -> User:
+        """Return the authenticated user and remaining usage."""
+        return User.from_dict(self._request("GET", "/user/me"))
+
+    # -- media -----------------------------------------------------------
+
+    def list_media(self, page: int = 1, dir_id: int | None = None) -> MediaList:
+        """List media in the library, paginated.
+
+        Args:
+            page: 1-based page number.
+            dir_id: Restrict to a directory (``None`` for the root listing).
+        """
+        return MediaList.from_dict(
+            self._request("GET", "/media/list", params={"page": page, "dir_id": dir_id})
+        )
+
+    def get_media(self, media_id: str, lang: str | None = None) -> Media:
+        """Fetch a single media item including its sentences.
+
+        Args:
+            media_id: The public media id (``uid``).
+            lang: Return sentences in this language (defaults to the original).
+        """
+        return Media.from_dict(
+            self._request("GET", "/media", params={"media_id": media_id, "lang": lang})
+        )
+
+    def move_media(self, media_id: str, dir_id: int | None = None) -> dict[str, Any]:
+        """Move a media item into a directory (``dir_id=None`` for root)."""
+        return self._request("PATCH", "/media", params={"media_id": media_id, "dir_id": dir_id})
+
+    def transcribe(
+        self,
+        file: str | os.PathLike[str] | BinaryIO | IO[bytes],
+        lang: str | None = None,
+        dir_id: int | None = None,
+        title: str | None = None,
+        timeout: TimeoutType | _Unset = _UNSET,
+    ) -> TranscribeResult:
+        """Upload a media file and queue it for transcription.
+
+        Args:
+            file: Path to a file, or an already-open binary file object.
+            lang: Source language hint (see :data:`SUPPORTED_LANGUAGES`). If
+                omitted the language is auto-detected.
+            dir_id: Directory to place the media into.
+            title: Display title (defaults to the file name).
+            timeout: Override the client's ``upload_timeout`` for this call.
+
+        Returns:
+            A :class:`TranscribeResult` with the new media id and state.
+        """
+        if lang is not None and lang not in SUPPORTED_LANGUAGES:
+            raise BadRequestError(
+                f"Language '{lang}' is not supported.", details=list(SUPPORTED_LANGUAGES)
+            )
+
+        params = {"lang": lang, "dir_id": dir_id, "title": title}
+
+        should_close = False
+        if isinstance(file, (str, os.PathLike)):
+            fh: IO[bytes] = open(file, "rb")
+            should_close = True
+        else:
+            fh = file
+        effective_timeout = self.upload_timeout if isinstance(timeout, _Unset) else timeout
+        try:
+            files = {"file": fh}
+            data = self._request(
+                "POST", "/media/transcribe", params=params, files=files, timeout=effective_timeout
+            )
+        finally:
+            if should_close:
+                fh.close()
+        return TranscribeResult.from_dict(data)
+
+    def transcribe_url(
+        self,
+        url: str,
+        lang: str | None = None,
+        dir_id: int | None = None,
+    ) -> TranscribeResult:
+        """Queue transcription of a remote media URL (YouTube or web).
+
+        Args:
+            url: The media URL to download and transcribe.
+            lang: Source language hint (see :data:`SUPPORTED_LANGUAGES`).
+            dir_id: Directory to place the media into.
+        """
+        if lang is not None and lang not in SUPPORTED_LANGUAGES:
+            raise BadRequestError(
+                f"Language '{lang}' is not supported.", details=list(SUPPORTED_LANGUAGES)
+            )
+        data = self._request(
+            "POST", "/media/transcribe-url", params={"url": url, "lang": lang, "dir_id": dir_id}
+        )
+        return TranscribeResult.from_dict(data)
+
+    def translate(self, media_id: str, target_lang: str) -> TranslateResult:
+        """Queue a translation of a transcribed media into ``target_lang``.
+
+        Args:
+            media_id: The public media id.
+            target_lang: Target language short code (see
+                :data:`TRANSLATION_LANGUAGES`).
+        """
+        target_lang = target_lang.lower().strip()
+        if target_lang not in TRANSLATION_LANGUAGES:
+            raise BadRequestError(
+                f"Language '{target_lang}' is not a supported translation target.",
+                details=list(TRANSLATION_LANGUAGES),
+            )
+        data = self._request(
+            "PATCH", "/media/translate", params={"media_id": media_id, "target_lang": target_lang}
+        )
+        return TranslateResult.from_dict(data)
+
+    def diarize(
+        self,
+        media_id: str,
+        lang: str,
+        speakers: int | None = None,
+    ) -> TranscribeResult:
+        """Queue speaker diarization for a (translated) media in ``lang``.
+
+        Args:
+            media_id: The public media id.
+            lang: Language of the transcript to diarize (must be fully
+                translated first).
+            speakers: Optional expected number of speakers.
+        """
+        data = self._request(
+            "PATCH",
+            "/media/diarize",
+            params={"media_id": media_id, "lang": lang, "speakers": speakers},
+        )
+        return TranscribeResult.from_dict(data)
+
+    # -- directories -----------------------------------------------------
+
+    def directory_tree(self) -> dict[str, Any]:
+        """Return the full nested directory tree for the user."""
+        return self._request("GET", "/directory/tree")
+
+    def create_directory(self, title: str, dir_id: int | None = None) -> Directory:
+        """Create a directory, optionally nested under ``dir_id``."""
+        return Directory.from_dict(
+            self._request("POST", "/directory", params={"title": title, "dir_id": dir_id})
+        )
+
+    def delete_directory(self, dir_id: int) -> bool:
+        """Delete a directory. Returns ``True`` on success."""
+        data = self._request("DELETE", "/directory", params={"dir_id": dir_id})
+        return bool(data.get("result")) if isinstance(data, dict) else bool(data)
+
+    def update_directory(
+        self,
+        dir_id: int,
+        title: str,
+        parent_id: int | None = None,
+    ) -> Directory:
+        """Rename a directory and/or move it under ``parent_id``."""
+        return Directory.from_dict(
+            self._request(
+                "PATCH",
+                "/directory",
+                params={"dir_id": dir_id, "title": title, "parent_id": parent_id},
+            )
+        )
+
+    # -- search ----------------------------------------------------------
+
+    def search(
+        self,
+        query: str,
+        from_: int = 0,
+        max_: int = 50,
+        dir_ids: Iterable[str | int] | None = None,
+        lang: str | None = None,
+    ) -> SearchResults:
+        """Search for sentences across all transcribed media.
+
+        The query supports a subset of the Lucene ``query_string`` syntax:
+
+        * Boolean operators ``AND`` / ``OR`` / ``NOT`` (e.g. ``cats AND dogs``).
+        * Grouping with parentheses (e.g. ``(cats OR dogs) AND vet``).
+        * Quoted phrases for exact matches (e.g. ``"climate change"``).
+        * Trailing wildcards (e.g. ``transcri*``). Leading wildcards
+          (``*tion``) are not allowed and are stripped.
+
+        Field selectors, fuzzy/proximity (``~``), boosts (``^``) and ranges are
+        stripped server-side.
+
+        Args:
+            query: Full text query (must be at least 3 characters).
+            from_: Offset of the first result (for pagination).
+            max_: Maximum number of results to return.
+            dir_ids: Restrict the search to one or more directory ids.
+            lang: Restrict the search to a single language.
+        """
+        if len(query) < 3:
+            raise BadRequestError("Query must be at least 3 characters.")
+        params: dict[str, Any] = {
+            "query": query,
+            "_from": from_,
+            "_max": max_,
+            "lang": lang,
+        }
+        if dir_ids is not None:
+            params["dir_ids"] = [str(d) for d in dir_ids]
+        return SearchResults.from_dict(self._request("GET", "/sentence/search", params=params))

gaston/constants.py

@@ -0,0 +1,43 @@
+"""Constants mirrored from the Gaston API.
+
+These are kept in sync with the server so the client can validate input
+locally before issuing a request.
+"""
+
+from __future__ import annotations
+
+#: Languages accepted by the transcription endpoints (Whisper language codes).
+SUPPORTED_LANGUAGES: tuple[str, ...] = (
+    "af", "am", "ar", "as", "az", "ba", "be", "bg", "bn", "bo", "br", "bs", "ca", "cs", "cy", "da", "de",
+    "el", "en", "es", "et", "eu", "fa", "fi", "fo", "fr", "gl", "gu", "ha", "haw", "he", "hi", "hr", "ht",
+    "hu", "hy", "id", "is", "it", "ja", "jw", "ka", "kk", "km", "kn", "ko", "la", "lb", "ln", "lo", "lt",
+    "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "ne", "nl", "nn", "no", "oc", "pa", "pl",
+    "ps", "pt", "ro", "ru", "sa", "sd", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta",
+    "te", "tg", "th", "tk", "tl", "tr", "tt", "uk", "ur", "uz", "vi", "yi", "yo", "zh", "yue",
+)
+
+#: Languages the translation endpoint can translate into (short code -> FLORES code).
+TRANSLATION_OPTIONS: dict[str, str] = {
+    "en": "eng_Latn", "de": "deu_Latn", "es": "spa_Latn", "pl": "pol_Latn", "hu": "hun_Latn",
+    "cs": "ces_Latn", "sk": "slk_Latn", "uk": "ukr_Cyrl", "bg": "bul_Cyrl", "hr": "hrv_Latn",
+    "da": "dan_Latn", "nl": "nld_Latn", "et": "est_Latn", "fi": "fin_Latn", "fr": "fra_Latn",
+    "el": "ell_Grek", "it": "ita_Latn", "lv": "lav_Latn", "lt": "lit_Latn", "mt": "mlt_Latn",
+    "pt": "por_Latn", "ro": "ron_Latn", "sl": "slv_Latn", "sv": "swe_Latn", "zh": "zho_Hans",
+    "ar": "arb_Arab", "hi": "hin_Deva", "ja": "jpn_Jpan", "id": "ind_Latn", "is": "isl_Latn",
+    "he": "heb_Hebr", "kk": "kaz_Cyrl", "ko": "kor_Hang", "lb": "ltz_Latn", "mk": "mkd_Cyrl",
+    "tr": "tur_Latn", "vi": "vie_Latn", "bn": "ben_Beng", "be": "bel_Cyrl", "ka": "kat_Geor",
+    "fa": "pes_Arab", "ur": "urd_Arab", "te": "tel_Telu", "ru": "rus_Cyrl",
+}
+
+#: Languages available as translation targets.
+TRANSLATION_LANGUAGES: tuple[str, ...] = tuple(TRANSLATION_OPTIONS.keys())
+
+#: Possible values of ``Media.state``.
+MEDIA_STATE_PENDING = "pending"
+MEDIA_STATE_UPLOADED = "uploaded"
+MEDIA_STATE_TRANSCRIBED = "transcribed"
+
+#: Possible values of ``Media.origin``.
+MEDIA_ORIGIN_UPLOADED = "up"
+MEDIA_ORIGIN_YOUTUBE = "yt"
+MEDIA_ORIGIN_WEB = "web"

gaston/exceptions.py

@@ -0,0 +1,50 @@
+"""Exceptions raised by the Gaston API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class GastonError(Exception):
+    """Base class for all errors raised by the client."""
+
+
+class GastonAPIError(GastonError):
+    """Raised when the API returns an error response.
+
+    Attributes:
+        message: Human readable error message returned by the API.
+        status_code: HTTP status code of the response (if any).
+        details: Optional extra payload returned alongside the error.
+        payload: The full decoded response body.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        details: Any | None = None,
+        payload: Any | None = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.details = details
+        self.payload = payload
+        prefix = f"[{status_code}] " if status_code is not None else ""
+        super().__init__(f"{prefix}{message}")
+
+
+class AuthenticationError(GastonAPIError):
+    """Raised when the token is invalid or the user is disabled (HTTP 403)."""
+
+
+class NotFoundError(GastonAPIError):
+    """Raised when a requested resource does not exist (HTTP 404)."""
+
+
+class RateLimitError(GastonAPIError):
+    """Raised when the monthly file/API limit is exhausted (HTTP 429)."""
+
+
+class BadRequestError(GastonAPIError):
+    """Raised for invalid requests (HTTP 400)."""

gaston/models.py

@@ -0,0 +1,209 @@
+"""Typed models for Gaston API responses.
+
+Every model keeps the original decoded payload in ``raw`` so that fields not
+explicitly mapped here are still accessible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Usage:
+    """Account usage information."""
+
+    files_left: int
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Usage":
+        return cls(files_left=data.get("filesLeft", 0), raw=data)
+
+
+@dataclass
+class User:
+    """The authenticated user (``GET /user/me``)."""
+
+    id: str
+    email: str
+    enabled: bool
+    usage: Usage
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "User":
+        return cls(
+            id=data.get("id"),
+            email=data.get("email"),
+            enabled=data.get("enabled", False),
+            usage=Usage.from_dict(data.get("usage", {})),
+            raw=data,
+        )
+
+
+@dataclass
+class Sentence:
+    """A single transcribed (or translated) sentence."""
+
+    id: int | None
+    speaker: Any | None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Sentence":
+        return cls(id=data.get("id"), speaker=data.get("speaker"), raw=data)
+
+    @property
+    def text(self) -> str | None:
+        return self.raw.get("text") or self.raw.get("sentence")
+
+
+@dataclass
+class Media:
+    """Full media detail (``GET /media``)."""
+
+    id: str
+    title: str | None
+    state: str | None
+    origin: str | None
+    origin_url: str | None
+    file: str | None
+    error: str | None
+    thumbnail: str | None
+    duration: int | None
+    published_at: Any | None
+    added_at: Any | None
+    transcription_progress: int | None
+    download_progress: int | None
+    language: str | None
+    available_languages: dict[str, Any]
+    sentences: list[Sentence]
+    diarized_sentences: dict[str, Any]
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Media":
+        return cls(
+            id=data.get("id"),
+            title=data.get("title"),
+            state=data.get("state"),
+            origin=data.get("origin"),
+            origin_url=data.get("originUrl"),
+            file=data.get("file"),
+            error=data.get("error"),
+            thumbnail=data.get("thumbnail"),
+            duration=data.get("duration"),
+            published_at=data.get("published_at"),
+            added_at=data.get("added_at"),
+            transcription_progress=data.get("transcription_progress"),
+            download_progress=data.get("download_progress"),
+            language=data.get("language"),
+            available_languages=data.get("available_languages") or {},
+            sentences=[Sentence.from_dict(s) for s in data.get("sentences") or []],
+            diarized_sentences=data.get("diarized_sentences") or {},
+            raw=data,
+        )
+
+
+@dataclass
+class MediaList:
+    """A page of media items (``GET /media/list``)."""
+
+    media: list[dict[str, Any]]
+    total: int
+    pages: int
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MediaList":
+        return cls(
+            media=data.get("media") or [],
+            total=data.get("total", 0),
+            pages=data.get("pages", 0),
+            raw=data,
+        )
+
+    def __iter__(self):
+        return iter(self.media)
+
+    def __len__(self) -> int:
+        return len(self.media)
+
+
+@dataclass
+class TranscribeResult:
+    """Result of a transcription request (``id`` + ``state``)."""
+
+    id: str
+    state: str | None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TranscribeResult":
+        return cls(id=data.get("id"), state=data.get("state"), raw=data)
+
+
+@dataclass
+class TranslateResult:
+    """Result of a translation request."""
+
+    id: str
+    available_languages: dict[str, Any]
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TranslateResult":
+        return cls(
+            id=data.get("id"),
+            available_languages=data.get("available_languages") or {},
+            raw=data,
+        )
+
+
+@dataclass
+class Directory:
+    """A directory in the user's library."""
+
+    id: int | None
+    title: str | None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Directory":
+        return cls(id=data.get("id"), title=data.get("title"), raw=data)
+
+
+@dataclass
+class SearchResults:
+    """Results of a sentence search (``GET /sentence/search``).
+
+    Each entry in :attr:`results` is a dict with two keys: ``_sentence`` (the
+    matched sentence and its ``media`` metadata) and ``_highlight`` (the matched
+    fragments with ``<hlt>...</hlt>`` markers around the hit terms).
+    """
+
+    results: list[dict[str, Any]]
+    total: int | None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SearchResults":
+        results: list[dict[str, Any]] = []
+        total: int | None = None
+        if isinstance(data, dict):
+            results = data.get("results") or []
+            # ``total`` is an Elasticsearch total object: {"value": N, ...}.
+            total_obj = data.get("total")
+            if isinstance(total_obj, dict):
+                total = total_obj.get("value")
+            elif isinstance(total_obj, int):
+                total = total_obj
+        return cls(results=results, total=total, raw=data)
+
+    def __iter__(self):
+        return iter(self.results)
+
+    def __len__(self) -> int:
+        return len(self.results)

gaston-0.2.0.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: gaston
+Version: 0.2.0
+Summary: Python client for the Gaston API (transcription, translation and sentence search).
+Author-email: "Streams s.r.o." <contact@streams.guru>
+License: MIT
+Project-URL: Homepage, https://gaston.live
+Project-URL: Documentation, https://www.gaston.live/en/api
+Keywords: gaston,transcription,translation,speech-to-text,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# Gaston API Client
+
+A small, typed Python client for the **Gaston API**: transcription, translation
+and full-text search of sentences within transcribed recordings.
+
+## Installation
+
+```bash
+pip install gaston
+```
+
+Requires Python 3.10+.
+
+For local development from a checkout instead:
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from gaston import GastonClient
+
+client = GastonClient(token="gapi-...")
+
+# Who am I + remaining quota
+me = client.me()
+print(me.email, "files left:", me.usage.files_left)
+
+# Transcribe a local file
+result = client.transcribe("interview.mp4", lang="en", title="My interview")
+print(result.id, result.state)
+
+# Transcribe from a URL (YouTube or web)
+client.transcribe_url("https://youtu.be/dQw4w9WgXcQ", lang="en")
+
+# Translate an existing transcription
+client.translate(result.id, target_lang="de")
+
+# Speaker diarization (requires a completed translation in that language)
+client.diarize(result.id, lang="de", speakers=2)
+
+# Fetch a media item with its sentences
+media = client.get_media(result.id, lang="en")
+for sentence in media.sentences:
+    print(sentence.id, sentence.text, sentence.speaker)
+
+# Full text search across the whole library
+results = client.search("climate change", max_=20)
+print("total matches:", results.total)
+for hit in results:
+    print(hit["_sentence"]["body"], "->", hit["_highlight"]["body"])
+```
+
+See [Search](#search) for query syntax and filtering options.
+
+### Configuration
+
+Generate an API token in the Gaston app under
+[Settings -> API](https://www.gaston.live/user/settings/api/en). Full endpoint
+documentation is available at <https://www.gaston.live/en/api>.
+
+The token can be supplied directly or via an environment variable:
+
+| Argument | Environment variable | Default    |
+|----------|----------------------|------------|
+| `token`  | `GASTON_API_TOKEN`   | (required) |
+
+```python
+# Uses GASTON_API_TOKEN from the environment
+with GastonClient() as client:
+    ...
+```
+
+### Timeouts
+
+Ordinary requests use a 30s timeout. The file upload in `transcribe` can take
+minutes for large files, so it uses a separate, more generous `upload_timeout`
+(default `(10s connect, 600s read)`).
+
+A timeout may be a single float, a `(connect, read)` tuple, or `None` to wait
+indefinitely.
+
+```python
+# Customise the defaults for all calls
+client = GastonClient(
+    token="gapi-...",
+    timeout=30,
+    upload_timeout=(10, 1800),   # allow up to 30 min to upload large files
+)
+
+# Or override per call (e.g. no read timeout for a very large file)
+client.transcribe("huge-recording.mp4", timeout=(10, None))
+```
+
+## Directories
+
+```python
+folder = client.create_directory("Podcasts")
+client.update_directory(folder.id, title="Podcast archive")
+client.move_media(media_id="me...", dir_id=folder.id)
+tree = client.directory_tree()
+client.delete_directory(folder.id)
+```
+
+## Search
+
+`client.search(query, from_=0, max_=50, dir_ids=None, lang=None)` runs a
+full-text search over every sentence in your transcribed media.
+
+### Query syntax
+
+The query supports a subset of the Lucene `query_string` syntax:
+
+| Feature           | Example                  | Notes                                    |
+|-------------------|--------------------------|------------------------------------------|
+| Boolean `AND`     | `cats AND dogs`          | both terms must appear                    |
+| Boolean `OR`      | `cats OR dogs`           | either term                              |
+| Boolean `NOT`     | `cats NOT dogs`          | exclude a term                           |
+| Grouping          | `(cats OR dogs) AND vet` | combine operators with parentheses       |
+| Exact phrase      | `"climate change"`       | quoted terms match as a phrase           |
+| Trailing wildcard | `transcri*`              | matches `transcribe`, `transcription`... |
+
+Leading wildcards (`*tion`), field selectors, fuzzy (`~`), boosts (`^`) and
+ranges are not supported and are stripped server-side. Queries must be at least
+3 characters.
+
+```python
+results = client.search('(invoice OR receipt) AND "due date" NOT draft')
+```
+
+### Filtering and pagination
+
+```python
+# Search within a single directory
+client.search("budget", dir_ids=[42])
+
+# Search across several directories
+client.search("budget", dir_ids=[42, 43, 7])
+
+# Restrict to one language, and page through results
+page2 = client.search("budget", from_=50, max_=50, lang="en")
+```
+
+### Reading results
+
+`search()` returns a `SearchResults` object. Iterate it for hits, or read
+`.total` for the overall match count. Each hit is a dict with:
+
+- `_sentence` - the matched sentence plus its `media` metadata (id, title,
+  duration, directory, thumbnail, file, originUrl).
+- `_highlight` - matched fragments with the hit terms wrapped in
+  `<hlt>...</hlt>` tags.
+
+```python
+results = client.search("climate change", max_=20)
+print("total matches:", results.total)
+for hit in results:
+    sentence = hit["_sentence"]
+    print(sentence["media"]["title"], "|", hit["_highlight"]["body"])
+```
+
+## Error handling
+
+All failures raise a subclass of `GastonError`:
+
+```python
+from gaston import GastonClient, AuthenticationError, RateLimitError, NotFoundError
+
+try:
+    client.transcribe("clip.mp4")
+except RateLimitError:
+    print("File limit reached")
+except AuthenticationError:
+    print("Bad token / disabled account")
+except NotFoundError as e:
+    print("Not found:", e.message)
+```
+
+| Exception             | Trigger                                  |
+|-----------------------|------------------------------------------|
+| `AuthenticationError` | HTTP 403, invalid token / disabled user  |
+| `BadRequestError`     | HTTP 400, invalid parameters             |
+| `NotFoundError`       | HTTP 404, resource not found             |
+| `RateLimitError`      | HTTP 429, usage limit exceeded           |
+| `GastonAPIError`      | any other API error                      |
+
+Every exception carries `.status_code`, `.message`, `.details` and the raw
+`.payload`.
+
+## Supported languages
+
+```python
+from gaston import SUPPORTED_LANGUAGES, TRANSLATION_LANGUAGES
+```
+
+`SUPPORTED_LANGUAGES` lists transcription source languages; `TRANSLATION_LANGUAGES`
+lists the available translation targets.

gaston-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+gaston/__init__.py,sha256=sgIkG-WIsaPydkKTXYpIOVUHyYSLOKnZ9Lo1BiCg4wc,1104
+gaston/client.py,sha256=lglH9_98ZV39LJxRaA-IAw7XUpbSIxub800xb3cRmAE,14170
+gaston/constants.py,sha256=6Mxtc3nMkLJJvqlFEwapGF8WRCO4wL2Yw8x1qQPKIHw,2287
+gaston/exceptions.py,sha256=E7j26kBIheRTRzwmtyyeKzPsl6T4e4QzBk4tYisK0os,1436
+gaston/models.py,sha256=qycz0Gil9XCN_ra7s5gY08dxiahVNlxB1Y8oAMyRvsQ,5994
+gaston-0.2.0.dist-info/licenses/LICENSE,sha256=4kqoIqcVwtUQeMI4Yy-mS3s_u3UwaFsHagw6QeecH9Q,1070
+gaston-0.2.0.dist-info/METADATA,sha256=hM5eyrI2HkLKdnjfbMXt-METNBDizsmn1C93KXhsCZg,7379
+gaston-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gaston-0.2.0.dist-info/top_level.txt,sha256=gccKrT4ad62T38FlJeHInqZlh5pueads-oHN79TMreA,7
+gaston-0.2.0.dist-info/RECORD,,

gaston-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gaston-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Streams s.r.o.
+
+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.

gaston-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gaston