llmlatency 0.1.0__tar.gz

llmlatency-0.1.0/LICENSE

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

llmlatency-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: llmlatency
+Version: 0.1.0
+Summary: Measured latency and uptime for AI inference APIs — client for the open llmlatency.dev dataset
+Author-email: "llmlatency.dev" <bot@mail.llmlatency.dev>
+License: MIT
+Project-URL: Homepage, https://llmlatency.dev
+Project-URL: Methodology, https://llmlatency.dev/methodology
+Project-URL: Machine-readable API, https://llmlatency.dev/api/rankings.json
+Project-URL: Source, https://github.com/mazamaka/llm-latency-tracker
+Project-URL: Citable dataset (DOI), https://doi.org/10.5281/zenodo.21954788
+Keywords: llm,latency,benchmark,ai,inference,observability,time-to-first-token,api-monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# llmlatency
+
+Measured latency and uptime for AI inference APIs, as a small Python client for
+the open dataset published at **[llmlatency.dev](https://llmlatency.dev)**.
+
+Probes run every five minutes from four regions and are never routed through a
+gateway or an aggregator, so the numbers describe the providers themselves
+rather than a proxy in front of them.
+
+- **Network probe** — DNS → TCP → TLS → time to first byte.
+- **Inference probe** — time to first token on a real completion request.
+
+These are different quantities, an order of magnitude apart, and this library
+never mixes them in one ranking.
+
+## Install
+
+```bash
+pip install llmlatency
+```
+
+No dependencies — standard library only.
+
+## Use it from Python
+
+```python
+import llmlatency
+
+llmlatency.regions()
+# ['ap-tokyo', 'eu-hetzner', 'sa-east', 'us-central']
+
+llmlatency.fastest("eu-hetzner")
+# {'rank': 1, 'provider': 'nscale', 'p50_ms': 99, 'p95_ms': 203,
+#  'uptime_pct': 100, 'samples': 289}
+
+for row in llmlatency.ranking("us-central")[:3]:
+    print(row["rank"], row["provider"], row["p50_ms"], "ms")
+
+llmlatency.provider("anthropic")          # one provider across every region
+llmlatency.generated_at()                 # snapshot timestamp, ISO-8601 UTC
+```
+
+Fetch once and pass the snapshot around if you make several queries:
+
+```python
+data = llmlatency.fetch()
+fast = {r: llmlatency.fastest(r, data=data) for r in llmlatency.regions(data)}
+```
+
+## Use it from the shell
+
+```bash
+llmlatency fastest                        # fastest provider in every region
+llmlatency ranking --region eu-hetzner --top 5
+llmlatency provider openai
+llmlatency fastest --probe inference --json
+```
+
+## Data, methodology, licence
+
+- Live rankings and full methodology: <https://llmlatency.dev>
+- Machine-readable snapshot: <https://llmlatency.dev/api/rankings.json>
+- Citable archive with a DOI: <https://doi.org/10.5281/zenodo.21954788>
+- Daily snapshots in git: <https://github.com/mazamaka/llm-latency-tracker>
+
+The dataset is **CC-BY-4.0**; this client library is MIT.
+
+**Limitations, stated up front.** Vantage points are cloud data centres, not
+consumer networks, so absolute values are lower than an end user would see — the
+comparison between providers is the meaningful part. Provider coverage changes
+over time as APIs appear and shut down.

llmlatency-0.1.0/README.md

@@ -0,0 +1,71 @@
+# llmlatency
+
+Measured latency and uptime for AI inference APIs, as a small Python client for
+the open dataset published at **[llmlatency.dev](https://llmlatency.dev)**.
+
+Probes run every five minutes from four regions and are never routed through a
+gateway or an aggregator, so the numbers describe the providers themselves
+rather than a proxy in front of them.
+
+- **Network probe** — DNS → TCP → TLS → time to first byte.
+- **Inference probe** — time to first token on a real completion request.
+
+These are different quantities, an order of magnitude apart, and this library
+never mixes them in one ranking.
+
+## Install
+
+```bash
+pip install llmlatency
+```
+
+No dependencies — standard library only.
+
+## Use it from Python
+
+```python
+import llmlatency
+
+llmlatency.regions()
+# ['ap-tokyo', 'eu-hetzner', 'sa-east', 'us-central']
+
+llmlatency.fastest("eu-hetzner")
+# {'rank': 1, 'provider': 'nscale', 'p50_ms': 99, 'p95_ms': 203,
+#  'uptime_pct': 100, 'samples': 289}
+
+for row in llmlatency.ranking("us-central")[:3]:
+    print(row["rank"], row["provider"], row["p50_ms"], "ms")
+
+llmlatency.provider("anthropic")          # one provider across every region
+llmlatency.generated_at()                 # snapshot timestamp, ISO-8601 UTC
+```
+
+Fetch once and pass the snapshot around if you make several queries:
+
+```python
+data = llmlatency.fetch()
+fast = {r: llmlatency.fastest(r, data=data) for r in llmlatency.regions(data)}
+```
+
+## Use it from the shell
+
+```bash
+llmlatency fastest                        # fastest provider in every region
+llmlatency ranking --region eu-hetzner --top 5
+llmlatency provider openai
+llmlatency fastest --probe inference --json
+```
+
+## Data, methodology, licence
+
+- Live rankings and full methodology: <https://llmlatency.dev>
+- Machine-readable snapshot: <https://llmlatency.dev/api/rankings.json>
+- Citable archive with a DOI: <https://doi.org/10.5281/zenodo.21954788>
+- Daily snapshots in git: <https://github.com/mazamaka/llm-latency-tracker>
+
+The dataset is **CC-BY-4.0**; this client library is MIT.
+
+**Limitations, stated up front.** Vantage points are cloud data centres, not
+consumer networks, so absolute values are lower than an end user would see — the
+comparison between providers is the meaningful part. Provider coverage changes
+over time as APIs appear and shut down.

llmlatency-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llmlatency"
+version = "0.1.0"
+description = "Measured latency and uptime for AI inference APIs — client for the open llmlatency.dev dataset"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "llmlatency.dev", email = "bot@mail.llmlatency.dev" }]
+keywords = ["llm", "latency", "benchmark", "ai", "inference", "observability",
+            "time-to-first-token", "api-monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: System :: Monitoring",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+# Зависимостей нет сознательно: клиент к одному JSON-эндпоинту, тянущий за собой
+# requests/httpx, в чужой проект просто не ставят.
+dependencies = []
+
+[project.urls]
+Homepage = "https://llmlatency.dev"
+Methodology = "https://llmlatency.dev/methodology"
+"Machine-readable API" = "https://llmlatency.dev/api/rankings.json"
+Source = "https://github.com/mazamaka/llm-latency-tracker"
+"Citable dataset (DOI)" = "https://doi.org/10.5281/zenodo.21954788"
+
+[project.scripts]
+llmlatency = "llmlatency.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+llmlatency = ["py.typed"]

llmlatency-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llmlatency-0.1.0/src/llmlatency/__init__.py

@@ -0,0 +1,33 @@
+"""llmlatency — measured latency and uptime for AI inference APIs.
+
+Data source: https://llmlatency.dev (CC-BY-4.0).
+Archived dataset with a DOI: https://doi.org/10.5281/zenodo.21954788
+"""
+from .client import (
+    API_URL,
+    PROBES,
+    LatencyError,
+    fastest,
+    fetch,
+    generated_at,
+    provider,
+    providers,
+    ranking,
+    regions,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "API_URL",
+    "PROBES",
+    "LatencyError",
+    "__version__",
+    "fastest",
+    "fetch",
+    "generated_at",
+    "provider",
+    "providers",
+    "ranking",
+    "regions",
+]

llmlatency-0.1.0/src/llmlatency/cli.py

@@ -0,0 +1,99 @@
+"""Командная строка: `llmlatency fastest`, `ranking`, `provider`, `regions`.
+
+CLI существует не для красоты: большинство обращений к таким данным — разовые
+(«кто сейчас быстрее в Европе»), и ради них никто не пишет скрипт. Одна команда
+в терминале закрывает сценарий целиком.
+
+Сеть дёргается РОВНО ОДИН РАЗ за запуск: снимок скачивается в `main()` и дальше
+передаётся в функции. Иначе `provider` с четырьмя регионами сходил бы за одним и
+тем же JSON четыре раза.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from . import __version__
+from .client import (
+    LatencyError,
+    fastest,
+    fetch,
+    generated_at,
+    provider,
+    providers,
+    ranking,
+    regions,
+)
+
+
+def _row(r: dict[str, Any]) -> str:
+    return (f"{r.get('rank', '?'):>3}. {r.get('provider', '?'):<18} "
+            f"p50 {r.get('p50_ms', '?'):>6} ms   p95 {r.get('p95_ms', '?'):>6} ms   "
+            f"uptime {r.get('uptime_pct', '?')}%   n={r.get('samples', '?')}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="llmlatency",
+        description="Measured latency and uptime for AI inference APIs "
+                    "(data: https://llmlatency.dev, CC-BY-4.0)")
+    ap.add_argument("--version", action="version", version=f"llmlatency {__version__}")
+    ap.add_argument("--json", action="store_true", help="print raw JSON instead of a table")
+    ap.add_argument("--probe", default="network", choices=("network", "inference"),
+                    help="network = time to first byte, inference = time to first token")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_fast = sub.add_parser("fastest", help="fastest provider per region")
+    p_fast.add_argument("--region", help="limit to one region (default: all)")
+
+    p_rank = sub.add_parser("ranking", help="full ranking for a region")
+    p_rank.add_argument("--region", required=True)
+    p_rank.add_argument("--top", type=int, default=10, help="how many rows (default 10)")
+
+    p_prov = sub.add_parser("provider", help="one provider across all regions")
+    p_prov.add_argument("name")
+
+    sub.add_parser("regions", help="list region ids")
+    sub.add_parser("providers", help="list provider names")
+
+    args = ap.parse_args(argv)
+
+    try:
+        data = fetch()
+    except LatencyError as exc:
+        print(f"llmlatency: {exc}", file=sys.stderr)
+        return 2
+
+    if args.cmd == "regions":
+        out: Any = regions(data)
+    elif args.cmd == "providers":
+        out = providers(data)
+    elif args.cmd == "ranking":
+        out = ranking(args.region, args.probe, data)[: args.top]
+    elif args.cmd == "provider":
+        out = provider(args.name, args.probe, data)
+    else:  # fastest
+        targets = [args.region] if args.region else regions(data)
+        out = {reg: fastest(reg, args.probe, data) for reg in targets}
+
+    if args.json:
+        print(json.dumps(out, ensure_ascii=False, indent=1))
+        return 0
+
+    print(f"llmlatency.dev — snapshot {generated_at(data)} · probe: {args.probe}\n")
+    if args.cmd in ("regions", "providers"):
+        print("\n".join(out))
+    elif args.cmd == "ranking":
+        print("\n".join(_row(r) for r in out) or "no data for this region/probe")
+    else:
+        for reg, row in out.items():
+            # Регион без замера печатается явным «—», а не пропускается: молчание
+            # читается как «данных нет вообще», хотя причина в отсутствии пробы.
+            print(f"{reg:<12} {_row(row) if row else '—  (not measured)'}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

llmlatency-0.1.0/src/llmlatency/client.py

@@ -0,0 +1,128 @@
+"""Чтение публичного снимка замеров llmlatency.dev.
+
+Зачем пакет вообще существует. У проекта есть открытый JSON с рейтингами, но
+чтобы им пользоваться, каждый повторяет одно и то же: сходить по URL, разобрать
+вложенные словари, вспомнить, что `network` и `inference` — разные величины.
+Пакет закрывает эту рутину и заодно даёт стабильную точку входа, на которую
+можно сослаться из чужого кода.
+
+Зависимостей нет намеренно: клиент к одному JSON-эндпоинту, который тянет за
+собой httpx или requests, в чужой проект не ставят — а значит и не используют.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+API_URL = "https://llmlatency.dev/api/rankings.json"
+USER_AGENT = "llmlatency-python/0.1.0 (+https://llmlatency.dev)"
+
+#: Тип пробы. `network` — DNS→TCP→TLS→первый байт, `inference` — время до
+#: первого токена на настоящем запросе. Величины отличаются на порядок, поэтому
+#: они разведены по разным спискам и никогда не смешиваются в одном рейтинге.
+PROBES = ("network", "inference")
+
+
+class LatencyError(RuntimeError):
+    """Data could not be fetched or parsed."""
+
+
+def fetch(url: str = API_URL, timeout: float = 10.0) -> dict[str, Any]:
+    """Download the current snapshot as a plain dict.
+
+    Raises:
+        LatencyError: the endpoint is unreachable or does not return JSON.
+    """
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT,
+                                               "Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = resp.read()
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise LatencyError(f"cannot reach {url}: {exc}") from exc
+    try:
+        data = json.loads(payload)
+    except ValueError as exc:
+        raise LatencyError(f"{url} did not return JSON") from exc
+    if not isinstance(data, dict) or "regions" not in data:
+        raise LatencyError(f"{url} returned an unexpected shape")
+    return data
+
+
+def regions(data: dict[str, Any] | None = None) -> list[str]:
+    """Region ids present in the snapshot, sorted."""
+    data = data if data is not None else fetch()
+    return sorted(data.get("regions", {}))
+
+
+def ranking(region: str, probe: str = "network",
+            data: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    """Ranked providers for one region, fastest first.
+
+    Args:
+        region: region id, e.g. ``eu-hetzner``. See :func:`regions`.
+        probe: ``network`` (time to first byte) or ``inference`` (time to first
+            token). They are different quantities and are never mixed.
+
+    Returns:
+        A list of dicts with ``rank``, ``provider``, ``p50_ms``, ``p95_ms``,
+        ``uptime_pct`` and ``samples``. Empty if the region has no such probe.
+    """
+    if probe not in PROBES:
+        raise ValueError(f"probe must be one of {PROBES}, got {probe!r}")
+    data = data if data is not None else fetch()
+    block = data.get("regions", {}).get(region)
+    if block is None:
+        known = ", ".join(sorted(data.get("regions", {}))) or "none"
+        raise LatencyError(f"unknown region {region!r} (known: {known})")
+    rows = block.get(probe) or []
+    # Порядок из API уже правильный, но полагаться на него нельзя: снимок
+    # собирается несколькими задачами, и «отсортировано» — не гарантия формата.
+    return sorted(rows, key=lambda r: r.get("rank", 10**6))
+
+
+def fastest(region: str, probe: str = "network",
+            data: dict[str, Any] | None = None) -> dict[str, Any] | None:
+    """The single fastest provider in a region, or ``None`` if unmeasured."""
+    rows = ranking(region, probe, data)
+    return rows[0] if rows else None
+
+
+def providers(data: dict[str, Any] | None = None) -> list[str]:
+    """Every provider name that appears anywhere in the snapshot, sorted."""
+    data = data if data is not None else fetch()
+    names: set[str] = set()
+    for block in data.get("regions", {}).values():
+        for probe in PROBES:
+            for row in block.get(probe) or []:
+                name = row.get("provider")
+                if name:
+                    names.add(name)
+    return sorted(names)
+
+
+def provider(name: str, probe: str = "network",
+             data: dict[str, Any] | None = None) -> dict[str, dict[str, Any]]:
+    """How one provider performs across all regions.
+
+    Returns:
+        Mapping ``region id -> measurement row``. Regions where the provider was
+        not measured are omitted rather than filled with zeros: a missing probe
+        and a slow probe must not look the same to the caller.
+    """
+    data = data if data is not None else fetch()
+    out: dict[str, dict[str, Any]] = {}
+    for region in data.get("regions", {}):
+        for row in ranking(region, probe, data):
+            if row.get("provider") == name:
+                out[region] = row
+                break
+    return out
+
+
+def generated_at(data: dict[str, Any] | None = None) -> str:
+    """Timestamp of the snapshot (ISO-8601, UTC)."""
+    data = data if data is not None else fetch()
+    return str(data.get("generated", ""))

llmlatency-0.1.0/src/llmlatency.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: llmlatency
+Version: 0.1.0
+Summary: Measured latency and uptime for AI inference APIs — client for the open llmlatency.dev dataset
+Author-email: "llmlatency.dev" <bot@mail.llmlatency.dev>
+License: MIT
+Project-URL: Homepage, https://llmlatency.dev
+Project-URL: Methodology, https://llmlatency.dev/methodology
+Project-URL: Machine-readable API, https://llmlatency.dev/api/rankings.json
+Project-URL: Source, https://github.com/mazamaka/llm-latency-tracker
+Project-URL: Citable dataset (DOI), https://doi.org/10.5281/zenodo.21954788
+Keywords: llm,latency,benchmark,ai,inference,observability,time-to-first-token,api-monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# llmlatency
+
+Measured latency and uptime for AI inference APIs, as a small Python client for
+the open dataset published at **[llmlatency.dev](https://llmlatency.dev)**.
+
+Probes run every five minutes from four regions and are never routed through a
+gateway or an aggregator, so the numbers describe the providers themselves
+rather than a proxy in front of them.
+
+- **Network probe** — DNS → TCP → TLS → time to first byte.
+- **Inference probe** — time to first token on a real completion request.
+
+These are different quantities, an order of magnitude apart, and this library
+never mixes them in one ranking.
+
+## Install
+
+```bash
+pip install llmlatency
+```
+
+No dependencies — standard library only.
+
+## Use it from Python
+
+```python
+import llmlatency
+
+llmlatency.regions()
+# ['ap-tokyo', 'eu-hetzner', 'sa-east', 'us-central']
+
+llmlatency.fastest("eu-hetzner")
+# {'rank': 1, 'provider': 'nscale', 'p50_ms': 99, 'p95_ms': 203,
+#  'uptime_pct': 100, 'samples': 289}
+
+for row in llmlatency.ranking("us-central")[:3]:
+    print(row["rank"], row["provider"], row["p50_ms"], "ms")
+
+llmlatency.provider("anthropic")          # one provider across every region
+llmlatency.generated_at()                 # snapshot timestamp, ISO-8601 UTC
+```
+
+Fetch once and pass the snapshot around if you make several queries:
+
+```python
+data = llmlatency.fetch()
+fast = {r: llmlatency.fastest(r, data=data) for r in llmlatency.regions(data)}
+```
+
+## Use it from the shell
+
+```bash
+llmlatency fastest                        # fastest provider in every region
+llmlatency ranking --region eu-hetzner --top 5
+llmlatency provider openai
+llmlatency fastest --probe inference --json
+```
+
+## Data, methodology, licence
+
+- Live rankings and full methodology: <https://llmlatency.dev>
+- Machine-readable snapshot: <https://llmlatency.dev/api/rankings.json>
+- Citable archive with a DOI: <https://doi.org/10.5281/zenodo.21954788>
+- Daily snapshots in git: <https://github.com/mazamaka/llm-latency-tracker>
+
+The dataset is **CC-BY-4.0**; this client library is MIT.
+
+**Limitations, stated up front.** Vantage points are cloud data centres, not
+consumer networks, so absolute values are lower than an end user would see — the
+comparison between providers is the meaningful part. Provider coverage changes
+over time as APIs appear and shut down.

llmlatency-0.1.0/src/llmlatency.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/llmlatency/__init__.py
+src/llmlatency/cli.py
+src/llmlatency/client.py
+src/llmlatency/py.typed
+src/llmlatency.egg-info/PKG-INFO
+src/llmlatency.egg-info/SOURCES.txt
+src/llmlatency.egg-info/dependency_links.txt
+src/llmlatency.egg-info/entry_points.txt
+src/llmlatency.egg-info/top_level.txt
+tests/test_client.py

llmlatency-0.1.0/src/llmlatency.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

llmlatency-0.1.0/src/llmlatency.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+llmlatency = llmlatency.cli:main

llmlatency-0.1.0/src/llmlatency.egg-info/top_level.txt

@@ -0,0 +1 @@
+llmlatency

llmlatency-0.1.0/tests/test_client.py

@@ -0,0 +1,118 @@
+"""Тесты клиента. Сеть НЕ дёргается: снимок подставляется параметром `data`.
+
+Тест, ходящий в интернет, падает от чужого таймаута и приучает игнорировать
+красное — а именно эти тесты защищают публичный пакет, который чинить придётся
+новой версией на PyPI.
+"""
+from __future__ import annotations
+
+import pytest
+
+import llmlatency
+from llmlatency import cli
+from llmlatency.client import LatencyError
+
+SNAPSHOT = {
+    "generated": "2026-08-15T19:42:56Z",
+    "unit": "milliseconds",
+    "regions": {
+        "eu-hetzner": {
+            "label": "Europe (Hetzner)",
+            # Порядок намеренно перепутан: клиент обязан сортировать сам.
+            "network": [
+                {"rank": 2, "provider": "openai", "p50_ms": 140, "p95_ms": 300,
+                 "uptime_pct": 100, "samples": 280},
+                {"rank": 1, "provider": "nscale", "p50_ms": 99, "p95_ms": 203,
+                 "uptime_pct": 100, "samples": 289},
+            ],
+            "inference": [
+                {"rank": 1, "provider": "cerebras", "p50_ms": 3100, "p95_ms": 5200,
+                 "uptime_pct": 99, "samples": 96},
+            ],
+        },
+        "us-central": {
+            "label": "US Central",
+            "network": [
+                {"rank": 1, "provider": "openai", "p50_ms": 88, "p95_ms": 150,
+                 "uptime_pct": 100, "samples": 288},
+            ],
+        },
+    },
+}
+
+
+def test_ranking_is_sorted_by_rank_not_by_api_order():
+    """Клиент не доверяет порядку из API.
+
+    Снимок собирается несколькими задачами; «отсортировано» — свойство текущей
+    реализации сервера, а не контракт. Положись на него — и однажды `fastest()`
+    молча вернёт второго по скорости.
+    """
+    rows = llmlatency.ranking("eu-hetzner", data=SNAPSHOT)
+    assert [r["provider"] for r in rows] == ["nscale", "openai"]
+    assert llmlatency.fastest("eu-hetzner", data=SNAPSHOT)["provider"] == "nscale"
+
+
+def test_network_and_inference_never_share_a_ranking():
+    """TTFB и TTFT отличаются на порядок; общий рейтинг — правдоподобная чушь."""
+    net = llmlatency.ranking("eu-hetzner", "network", data=SNAPSHOT)
+    inf = llmlatency.ranking("eu-hetzner", "inference", data=SNAPSHOT)
+    assert {r["provider"] for r in net}.isdisjoint({r["provider"] for r in inf})
+    assert max(r["p50_ms"] for r in net) < min(r["p50_ms"] for r in inf)
+
+
+def test_missing_probe_returns_empty_not_error():
+    """У `us-central` нет inference-проб — это пустой список, а не исключение.
+
+    Регион без пробы — нормальное состояние снимка (провайдеры появляются и
+    исчезают). Падать здесь значило бы ломать чужой цикл по регионам.
+    """
+    assert llmlatency.ranking("us-central", "inference", data=SNAPSHOT) == []
+    assert llmlatency.fastest("us-central", "inference", data=SNAPSHOT) is None
+
+
+def test_unknown_region_names_the_known_ones():
+    """Ошибка обязана перечислить доступные регионы: иначе догадываться по докам."""
+    with pytest.raises(LatencyError) as exc:
+        llmlatency.ranking("mars-1", data=SNAPSHOT)
+    assert "eu-hetzner" in str(exc.value)
+
+
+def test_unknown_probe_is_rejected_up_front():
+    with pytest.raises(ValueError):
+        llmlatency.ranking("eu-hetzner", "ttfb", data=SNAPSHOT)
+
+
+def test_provider_omits_regions_without_measurement():
+    """Пропуск региона и «медленно» не должны выглядеть одинаково у вызывающего."""
+    out = llmlatency.provider("cerebras", "network", data=SNAPSHOT)
+    assert out == {}, "cerebras меряли только inference — сетевых строк быть не должно"
+
+    out = llmlatency.provider("openai", data=SNAPSHOT)
+    assert set(out) == {"eu-hetzner", "us-central"}
+    assert out["us-central"]["p50_ms"] == 88
+
+
+def test_providers_collects_names_from_all_regions_and_probes():
+    assert llmlatency.providers(SNAPSHOT) == ["cerebras", "nscale", "openai"]
+
+
+def test_cli_prints_a_table_without_touching_the_network(monkeypatch, capsys):
+    """CLI обязан ходить в сеть РОВНО один раз за запуск.
+
+    `provider` перебирает регионы; если бы снимок качался внутри каждой функции,
+    одна команда дала бы четыре запроса к сайту.
+    """
+    calls = {"n": 0}
+
+    def fake_fetch(*a, **kw):
+        calls["n"] += 1
+        return SNAPSHOT
+
+    monkeypatch.setattr(cli, "fetch", fake_fetch)
+    rc = cli.main(["fastest"])
+    out = capsys.readouterr().out
+
+    assert rc == 0
+    assert calls["n"] == 1, "снимок обязан скачиваться один раз за запуск"
+    assert "nscale" in out and "us-central" in out