pythonhere 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

pythonhere/.agents/skills/pythonhere/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pythonhere
-description: "Build, inspect, and debug PythonHere applications by executing Python through the `there` CLI in an already-running Kivy/Python-for-Android process. Use when a task targets a PythonHere device or `there.env` connection and involves live Kivy UI, KV language, Android APIs, Pyjnius, permissions, installed Android packages, media/files, Plyer device features, BLE with able, or MIDI with midistream."
+description: "Build, inspect, and debug PythonHere applications by executing Python through the `there` CLI in an already-running Kivy/Python-for-Android process. Use when a task targets a PythonHere device or `there.env` connection and involves live Kivy UI, KV language, Android APIs, Pyjnius, permissions, installed Android packages, media/files, Plyer device features, BLE with able, MIDI with midistream, or on-device AI with LiteRT-LM and `.litertlm` models."
 ---
 
 # Operate PythonHere with `there`
@@ -40,6 +40,8 @@ when the task depends on it broadly or requires its exact current contents.
   recording, camera, file selection, GPS, battery, or sensors.
 - Consult [able.md](references/able.md) for Bluetooth Low Energy work.
 - Consult [midi.md](references/midi.md) for MIDI or synthesizer work.
+- Consult [litert.md](references/litert.md) for PythonHere's ML model helpers
+  and LiteRT-LM usage.
 
 Combine references when a feature genuinely needs details from several
 concerns; for example, an Android gallery may need permission, MediaStore, and

pythonhere/.agents/skills/pythonhere/references/litert.md

@@ -0,0 +1,121 @@
+# ML model helpers for LiteRT
+
+PythonHere provides `ml_here` for acquiring and locating ML model files. It
+does not wrap LiteRT-LM inference.
+
+All public model helpers return paths as strings (a list of strings for
+`discover_models()`), ready to pass to `litert_lm.Engine()`.
+
+```python
+from ml_here import (
+    discover_models,
+    download_hf_model,
+    model_path,
+    models_directory,
+    require_model,
+)
+```
+
+- `models_directory(create=False)` returns PythonHere's model directory. On
+  Android this is the app-specific external files directory under `models`; on
+  Linux it is `~/.local/share/pythonhere/models`.
+- `model_path(repo_id, filename)` returns the namespaced path for a model. It
+  does not create directories and rejects unsafe path components.
+- `require_model(repo_id, filename)` returns that path when the model is
+  installed and raises `FileNotFoundError` otherwise.
+- `discover_models(extra_directories=(), extensions=".litertlm")` recursively
+  returns sorted, unique LiteRT-LM model paths from managed storage and any
+  additional directories. Pass another extension or iterable to select other
+  formats, or `extensions=None` to include every completed stored artifact.
+- `download_hf_model(repo_id, filename, *, revision="main", token=None,
+  destination=None, progress=None, cancelled=None, overwrite=False,
+  expected_sha256=None)` downloads a Hugging Face model file of any format. By
+  default, it stores the file at `model_path(repo_id, filename)`.
+
+Choose by intent: use `require_model()` to load a known installed model, the
+path returned by `download_hf_model()` after a download, and
+`discover_models()` only to inventory models whose identities are not already
+known. Use `model_path()` when only the expected location is needed.
+
+Downloads are resumable across restarts and make the final file visible only
+after the download completes. Cancellation preserves the partial download for
+resuming. Pass a token for private or gated models. The `progress` callback
+receives the following interface; use it directly rather than redefining it:
+
+```python
+class DownloadProgress:
+    repo_id: str
+    filename: str
+    destination: str
+    downloaded: int
+    total: int | None
+    elapsed: float
+    speed_bps: float
+    fraction: float | None
+    percent: float | None
+    speed_mbps: float
+    remaining: int | None
+    eta: float | None
+```
+
+Use `litert_lm` directly to load and run the returned model path.
+
+## Run an installed model
+
+Run model loading and inference on a worker (`--worker`) to keep Kivy
+responsive. In the app runtime, import model helpers from `ml_here`.
+
+```python
+import litert_lm
+from ml_here import require_model
+
+model_file = require_model(
+    "litert-community/SmolLM2-135M-Instruct",
+    "SmolLM2_135M_Instruct.litertlm",
+)
+engine = litert_lm.Engine(model_file)
+try:
+    with engine.create_conversation(max_output_tokens=128) as conversation:
+        response = conversation.send_message(
+            "What is the Kivy framework? Answer in one short paragraph."
+        )
+        text = "".join(
+            part["text"]
+            for part in response["content"]
+            if part.get("type") == "text"
+        )
+        print(text)
+finally:
+    engine.close()
+```
+
+The conversation closes before the engine, including when inference raises.
+For an interactive chat, keep the engine loaded and reuse the conversation
+for follow-up messages; close both when the chat is finished.
+
+`litert_lm.Engine(model_file)` uses CPU by default. For a model and device
+that support GPU inference, replace the engine construction above with:
+
+```python
+engine = litert_lm.Engine(model_file, backend=litert_lm.Backend.GPU())
+```
+
+## Download first when needed
+
+If the model is not installed, download it on a worker before inference:
+
+```python
+from ml_here import download_hf_model
+
+model_file = download_hf_model(
+    "litert-community/SmolLM2-135M-Instruct",
+    "SmolLM2_135M_Instruct.litertlm",
+)
+print(model_file)
+```
+
+When downloading and loading in the same script, pass the returned
+`model_file` directly to `litert_lm.Engine()`.
+
+See the [upstream Python API](https://github.com/google-ai-edge/LiteRT-LM/tree/main/python)
+for streaming, sampling, and multimodal inference.

pythonhere/ml_here/__init__.py

@@ -0,0 +1,17 @@
+"""Acquire, store, index, and discover ML model files for PythonHere."""
+
+from .huggingface import download_hf_model
+from .storage import (
+    discover_models,
+    model_path,
+    models_directory,
+    require_model,
+)
+
+__all__ = (
+    "discover_models",
+    "download_hf_model",
+    "model_path",
+    "models_directory",
+    "require_model",
+)

pythonhere/ml_here/huggingface.py

@@ -0,0 +1,998 @@
+"""
+A small cross-platform Hugging Face Hub downloader designed for PythonHere.
+
+Uses requests to download public, private, or gated files with persistent resume,
+progress callbacks, retries, integrity checks, and atomic completion. This module
+implements only the Hub features needed for model downloads; it is not a general
+replacement for huggingface_hub.
+
+Typical use:
+
+    from pythonhere.ml_here import download_hf_model
+
+    path = download_hf_model(
+        "litert-community/some-model",
+        "model.tflite",
+        token=oauth_access_token,
+        progress=lambda p: print(p.percent, p.speed_mbps),
+    )
+
+For a public model, omit `token`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import random
+import re
+import time
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from http import HTTPStatus
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import requests
+
+from .storage import model_path
+
+__all__ = [
+    "HFClient",
+    "DownloadProgress",
+    "RemoteFile",
+    "HFError",
+    "HFAuthError",
+    "HFGatedError",
+    "HFNotFoundError",
+    "HFRateLimitError",
+    "HFIntegrityError",
+    "HFCancelled",
+    "download_hf_model",
+]
+
+
+class HFError(RuntimeError):
+    """Base error for Hugging Face Hub operations."""
+
+
+class HFAuthError(HFError):
+    """Authentication is missing, invalid, or insufficient."""
+
+
+class HFGatedError(HFAuthError):
+    """The model is gated and this user does not currently have access."""
+
+
+class HFNotFoundError(HFError):
+    """Repository, revision, or file was not found."""
+
+
+class HFRateLimitError(HFError):
+    """Hugging Face rejected the request because of rate limiting."""
+
+
+class HFIntegrityError(HFError):
+    """Downloaded data did not match expected size/hash."""
+
+
+class HFCancelled(HFError):
+    """Download was cancelled by the caller."""
+
+
+@dataclass(frozen=True)
+class RemoteFile:
+    """Remote identity and metadata used to validate a download."""
+
+    repo_id: str
+    filename: str
+    revision: str
+    size: int | None
+    etag: str | None
+    commit: str | None
+    url: str
+
+
+@dataclass(frozen=True)
+class DownloadProgress:
+    """Byte counts and timing for a download progress notification."""
+
+    repo_id: str
+    filename: str
+    destination: str
+    downloaded: int
+    total: int | None
+    elapsed: float
+    speed_bps: float
+
+    @property
+    def fraction(self) -> float | None:
+        if not self.total:
+            return None
+        return min(1.0, self.downloaded / self.total)
+
+    @property
+    def percent(self) -> float | None:
+        value = self.fraction
+        return None if value is None else value * 100.0
+
+    @property
+    def speed_mbps(self) -> float:
+        return self.speed_bps / (1024 * 1024)
+
+    @property
+    def remaining(self) -> int | None:
+        if self.total is None:
+            return None
+        return max(0, self.total - self.downloaded)
+
+    @property
+    def eta(self) -> float | None:
+        remaining = self.remaining
+        if remaining is None or self.speed_bps <= 0:
+            return None
+        return remaining / self.speed_bps
+
+
+@dataclass
+class _PartialMeta:
+    repo_id: str
+    filename: str
+    revision: str
+    etag: str | None
+    commit: str | None
+    expected_size: int | None
+
+
+@dataclass
+class _ProgressReporter:
+    remote: RemoteFile
+    destination: Path
+    callback: Callable[[DownloadProgress], None] | None
+    interval: float
+    started: float = field(init=False, default=0.0)
+    initial_size: int = field(init=False, default=0)
+    last_time: float = field(init=False, default=0.0)
+    last_size: int = field(init=False, default=0)
+
+    def start(self, size: int) -> None:
+        self.started = self.last_time = time.monotonic()
+        self.initial_size = self.last_size = size
+
+    def report(self, current: int) -> None:
+        now = time.monotonic()
+        if self.callback and (
+            now - self.last_time >= self.interval
+            or (self.remote.size is not None and current >= self.remote.size)
+        ):
+            self.callback(
+                DownloadProgress(
+                    repo_id=self.remote.repo_id,
+                    filename=self.remote.filename,
+                    destination=str(self.destination),
+                    downloaded=current,
+                    total=self.remote.size,
+                    elapsed=now - self.started,
+                    speed_bps=(current - self.last_size)
+                    / max(now - self.last_time, 1e-9),
+                )
+            )
+            self.last_time = now
+            self.last_size = current
+
+    def finish(self) -> None:
+        if self.callback:
+            end = time.monotonic()
+            size = self.destination.stat().st_size
+            self.callback(
+                DownloadProgress(
+                    repo_id=self.remote.repo_id,
+                    filename=self.remote.filename,
+                    destination=str(self.destination),
+                    downloaded=size,
+                    total=self.remote.size or size,
+                    elapsed=end - self.started,
+                    speed_bps=(size - self.initial_size)
+                    / max(end - self.started, 1e-9),
+                )
+            )
+
+
+def _raise_download_error(response: requests.Response, filename: str) -> None:
+    if response.status_code == HTTPStatus.TOO_MANY_REQUESTS:
+        raise HFRateLimitError(
+            f"Hugging Face rate limit exceeded while downloading {filename!r}."
+        )
+    raise HFError(f"HTTP {response.status_code} while downloading {filename!r}.")
+
+
+_BYTES_PER_KIB = 1024
+_SECONDS_PER_MINUTE = 60
+_MINUTES_PER_HOUR = 60
+
+_RETRYABLE_STATUS = {408, 425, 429, 500, 502, 503, 504}
+_SAFE_ETAG = re.compile(r'^(?:W/)?"?(.*?)"?$')
+
+
+def _clean_etag(value: str | None) -> str | None:
+    if not value:
+        return None
+    value = value.strip()
+    m = _SAFE_ETAG.match(value)
+    return m.group(1) if m else value.strip('"')
+
+
+def _int_header(
+    headers: requests.structures.CaseInsensitiveDict, name: str
+) -> int | None:
+    value = headers.get(name)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _remote_size(response: requests.Response) -> int | None:
+    # HF exposes the actual object size through X-Linked-Size for LFS-backed
+    # files. On a final ranged/CDN response, Content-Range is the strongest
+    # source. Fall back to ordinary Content-Length.
+    linked = _int_header(response.headers, "X-Linked-Size")
+    if linked is not None:
+        return linked
+
+    content_range = response.headers.get("Content-Range")
+    if content_range and "/" in content_range:
+        tail = content_range.rsplit("/", 1)[-1]
+        if tail != "*":
+            try:
+                return int(tail)
+            except ValueError:
+                pass
+
+    # Only trust Content-Length when the body is not content-encoded.
+    encoding = response.headers.get("Content-Encoding", "identity").lower()
+    if encoding == "identity":
+        return _int_header(response.headers, "Content-Length")
+    return None
+
+
+def _retry_after(response: requests.Response) -> float | None:
+    value = response.headers.get("Retry-After")
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+def _atomic_json_write(path: Path, data: dict[str, Any]) -> None:
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+class HFClient:
+    """
+    Lightweight Hugging Face Hub download client.
+
+    Parameters
+    ----------
+    token:
+        Hugging Face user token or OAuth access token. Use None for public files.
+    endpoint:
+        Hub base URL. Mainly useful for testing or custom Hub-compatible hosts.
+    user_agent:
+        Sent on all requests.
+    timeout:
+        `(connect_timeout, read_timeout)` passed to requests.
+        The read timeout is per socket read, not a total download timeout.
+    chunk_size:
+        Streaming chunk size.
+    max_retries:
+        Retries after transient network/server failures.
+    backoff:
+        Base exponential retry delay.
+    """
+
+    # Public connection options remain individually configurable.
+    def __init__(  # noqa: PLR0913
+        self,
+        token: str | None = None,
+        *,
+        endpoint: str = "https://huggingface.co",
+        user_agent: str = "pythonhere-hf-downloader/1.0",
+        timeout: tuple[float, float] = (15.0, 60.0),
+        chunk_size: int = 1024 * 1024,
+        max_retries: int = 5,
+        backoff: float = 1.0,
+        session: requests.Session | None = None,
+    ):
+        # pylint: disable=too-many-arguments
+        self.token = token
+        self.endpoint = endpoint.rstrip("/")
+        self.user_agent = user_agent
+        self.timeout = timeout
+        self.chunk_size = chunk_size
+        self.max_retries = max_retries
+        self.backoff = backoff
+        self.session = session or requests.Session()
+
+    def resolve_url(self, repo_id: str, filename: str, revision: str = "main") -> str:
+        repo = "/".join(quote(part, safe="") for part in repo_id.split("/"))
+        rev = quote(revision, safe="")
+        file_path = "/".join(quote(part, safe="") for part in filename.split("/"))
+        return f"{self.endpoint}/{repo}/resolve/{rev}/{file_path}"
+
+    def raw_url(self, repo_id: str, filename: str, revision: str = "main") -> str:
+        repo = "/".join(quote(part, safe="") for part in repo_id.split("/"))
+        rev = quote(revision, safe="")
+        file_path = "/".join(quote(part, safe="") for part in filename.split("/"))
+        return f"{self.endpoint}/{repo}/raw/{rev}/{file_path}"
+
+    def model_url(self, repo_id: str) -> str:
+        return f"{self.endpoint}/{repo_id}"
+
+    def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        # identity matters for reliable byte ranges / sizes.
+        headers = {
+            "User-Agent": self.user_agent,
+            "Accept-Encoding": "identity",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def model_info(
+        self, repo_id: str, *, revision: str | None = None
+    ) -> dict[str, Any]:
+        """
+        Return raw model metadata from the Hub REST API.
+
+        The response includes useful fields such as `sha`, `gated`, and `siblings`.
+        """
+        repo = "/".join(quote(part, safe="") for part in repo_id.split("/"))
+        if revision:
+            rev = quote(revision, safe="")
+            url = f"{self.endpoint}/api/models/{repo}/revision/{rev}"
+        else:
+            url = f"{self.endpoint}/api/models/{repo}"
+
+        response = self._request_with_retry("GET", url, headers=self._headers())
+        self._raise_hf_error(response, repo_id=repo_id)
+        return response.json()
+
+    def list_files(self, repo_id: str, *, revision: str | None = None) -> list[str]:
+        info = self.model_info(repo_id, revision=revision)
+        return [
+            item["rfilename"]
+            for item in info.get("siblings", [])
+            if isinstance(item, dict) and item.get("rfilename")
+        ]
+
+    def file_info(
+        self,
+        repo_id: str,
+        filename: str,
+        *,
+        revision: str = "main",
+    ) -> RemoteFile:
+        """
+        Resolve a Hub file and return size/ETag/commit metadata without
+        downloading the body.
+        """
+        url = self.resolve_url(repo_id, filename, revision)
+
+        response = self._request_with_retry(
+            "HEAD",
+            url,
+            headers=self._headers(),
+            allow_redirects=True,
+        )
+        self._raise_hf_error(
+            response,
+            repo_id=repo_id,
+            filename=filename,
+        )
+
+        etag = _clean_etag(
+            response.headers.get("X-Linked-Etag") or response.headers.get("ETag")
+        )
+        commit = response.headers.get("X-Repo-Commit")
+        size = _remote_size(response)
+
+        return RemoteFile(
+            repo_id=repo_id,
+            filename=filename,
+            revision=revision,
+            size=size,
+            etag=etag,
+            commit=commit,
+            # Intentionally expose the stable HF resolve URL, not an expiring
+            # signed CDN/Xet redirect target.
+            url=url,
+        )
+
+    def git_lfs_info(
+        self,
+        repo_id: str,
+        filename: str,
+        *,
+        revision: str = "main",
+    ) -> dict[str, Any] | None:
+        """Return SHA-256 and size when the repository stores a Git LFS pointer."""
+
+        response = self._request_with_retry(
+            "GET",
+            self.raw_url(repo_id, filename, revision),
+            headers=self._headers({"Range": "bytes=0-1024"}),
+            stream=True,
+        )
+        try:
+            self._raise_hf_error(response, repo_id=repo_id, filename=filename)
+            data = response.raw.read(1025)
+        finally:
+            response.close()
+
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError:
+            return None
+        match = re.fullmatch(
+            r"version https://git-lfs\.github\.com/spec/v1\r?\n"
+            r"oid sha256:([0-9a-fA-F]{64})\r?\n"
+            r"size ([0-9]+)\r?\n?",
+            text,
+        )
+        if match:
+            return {"sha256": match.group(1).lower(), "size": int(match.group(2))}
+        if text.startswith("version https://git-lfs.github.com/spec/v1"):
+            raise HFIntegrityError(f"Malformed Git LFS pointer for {filename}")
+        return None
+
+    # Preserve the public download keyword options.
+    def download(  # noqa: PLR0913
+        self,
+        repo_id: str,
+        filename: str,
+        destination: str | os.PathLike[str],
+        *,
+        revision: str = "main",
+        resume: bool = True,
+        overwrite: bool = False,
+        progress: Callable[[DownloadProgress], None] | None = None,
+        cancelled: Callable[[], bool] | None = None,
+        expected_sha256: str | None = None,
+        progress_interval: float = 0.15,
+    ) -> Path:
+        """
+        Download one file from a Hugging Face model repository.
+
+        The final destination is written atomically:
+            destination.part
+            destination.part.json
+            -> destination
+
+        Existing partial downloads are resumed when their remote metadata still
+        matches. If the revision/file changed, the stale partial is discarded.
+
+        Parameters
+        ----------
+        progress:
+            Callback receiving DownloadProgress. It runs on the thread calling
+            `download`; for Kivy, marshal UI changes onto the UI thread.
+        cancelled:
+            Callback returning True when cancellation is requested. The .part
+            file is preserved, so calling download() later resumes it.
+        expected_sha256:
+            Optional explicit SHA-256 integrity check. Usually unnecessary for
+            ordinary HF use, but useful when your app ships a trusted catalog.
+        """
+        # Public options account for eleven of the seventeen local names.
+        # pylint: disable=too-many-arguments,too-many-locals
+        dest = Path(destination)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        part = dest.with_name(dest.name + ".part")
+        meta_path = dest.with_name(dest.name + ".part.json")
+
+        remote = self.file_info(repo_id, filename, revision=revision)
+
+        if dest.exists() and not overwrite:
+            self._check_existing(dest, remote, expected_sha256)
+            return dest
+
+        # Files above regular HF HTTP's supported range require Xet.
+        if remote.size is not None and remote.size > 50 * 1024**3:
+            raise HFError(
+                f"{filename!r} is larger than 50 GiB. Hugging Face does not "
+                "serve files of this size through its regular HTTP download "
+                "path; an Xet-capable client is required."
+            )
+
+        expected_meta = self._prepare_partial(part, meta_path, remote, resume)
+
+        # If a previous invocation finished the bytes but died before rename,
+        # finish locally without a network GET.
+        if remote.size is not None and part.stat().st_size == remote.size:
+            self._verify_and_commit(
+                part,
+                dest,
+                meta_path,
+                expected_size=remote.size,
+                expected_sha256=expected_sha256,
+            )
+            return dest
+
+        reporter = _ProgressReporter(remote, dest, progress, progress_interval)
+        reporter.start(part.stat().st_size)
+        self._download_with_retry(
+            part, meta_path, expected_meta, reporter, cancelled=cancelled, resume=resume
+        )
+
+        self._verify_and_commit(
+            part,
+            dest,
+            meta_path,
+            expected_size=remote.size,
+            expected_sha256=expected_sha256,
+        )
+
+        reporter.finish()
+
+        return dest
+
+    @staticmethod
+    def _check_existing(dest: Path, remote: RemoteFile, expected_sha256: str | None):
+        actual_size = dest.stat().st_size
+        if remote.size is not None and actual_size != remote.size:
+            raise HFIntegrityError(
+                f"Existing {dest.name} has {actual_size} bytes; expected "
+                f"{remote.size}. The file was left unchanged."
+            )
+        if expected_sha256 is not None:
+            actual_sha256 = HFClient._sha256(dest)
+            if actual_sha256.lower() != expected_sha256.lower():
+                raise HFIntegrityError(
+                    f"Existing {dest.name} has SHA-256 {actual_sha256}; "
+                    f"expected {expected_sha256}. The file was left unchanged."
+                )
+
+    def _prepare_partial(self, part, meta_path, remote, resume):
+        expected_meta = _PartialMeta(
+            repo_id=remote.repo_id,
+            filename=remote.filename,
+            revision=remote.revision,
+            etag=remote.etag,
+            commit=remote.commit,
+            expected_size=remote.size,
+        )
+
+        if not resume:
+            self._remove_partial(part, meta_path)
+        else:
+            self._validate_partial(part, meta_path, expected_meta)
+
+        if not part.exists():
+            part.touch()
+            _atomic_json_write(meta_path, asdict(expected_meta))
+
+        return expected_meta
+
+    def _download_with_retry(  # noqa: PLR0913
+        self, part, meta_path, expected_meta, reporter, *, cancelled, resume
+    ):
+        # Retry state includes partial provenance and caller cancellation policy.
+        # pylint: disable=too-many-arguments
+        remote = reporter.remote
+        filename = remote.filename
+        attempt = 0
+        while True:
+            if cancelled and cancelled():
+                raise HFCancelled(f"Download cancelled: {filename}")
+
+            current = part.stat().st_size
+            if remote.size is not None and current > remote.size:
+                self._remove_partial(part, meta_path)
+                part.touch()
+                _atomic_json_write(meta_path, asdict(expected_meta))
+                current = 0
+
+            range_headers: dict[str, str] = {}
+            if resume and current > 0:
+                range_headers["Range"] = f"bytes={current}-"
+
+            try:
+                response = self.session.get(
+                    remote.url,
+                    headers=self._headers(range_headers),
+                    stream=True,
+                    allow_redirects=True,
+                    timeout=self.timeout,
+                )
+
+                # A stale/exact-complete range can produce 416.
+                if response.status_code == HTTPStatus.REQUESTED_RANGE_NOT_SATISFIABLE:
+                    if remote.size is not None and current == remote.size:
+                        response.close()
+                        break
+                    response.close()
+                    # Do not append to something the server rejects.
+                    self._remove_partial(part, meta_path)
+                    part.touch()
+                    _atomic_json_write(meta_path, asdict(expected_meta))
+                    attempt += 1
+                    if attempt > self.max_retries:
+                        raise HFIntegrityError(
+                            f"Server rejected resume range for {filename!r}."
+                        )
+                    continue
+
+                if response.status_code in _RETRYABLE_STATUS:
+                    delay = _retry_after(response)
+                    response.close()
+                    if attempt >= self.max_retries:
+                        _raise_download_error(response, filename)
+                    self._sleep_backoff(attempt, delay)
+                    attempt += 1
+                    continue
+
+                self._raise_hf_error(
+                    response,
+                    repo_id=remote.repo_id,
+                    filename=filename,
+                )
+
+                self._stream_response(response, part, reporter, cancelled)
+
+                # A cleanly closed response should be complete. Verify below.
+                break
+
+            except (
+                requests.ConnectionError,
+                requests.Timeout,
+                requests.exceptions.ChunkedEncodingError,
+            ) as exc:
+                if attempt >= self.max_retries:
+                    raise HFError(
+                        f"Network error while downloading {filename!r} after "
+                        f"{self.max_retries + 1} attempts: {exc}"
+                    ) from exc
+                self._sleep_backoff(attempt)
+                attempt += 1
+                # Loop reopens .part and resumes from its current byte count.
+
+    def _stream_response(self, response, part, reporter, cancelled):
+        current = part.stat().st_size
+        # Never append a full response when the server ignores Range.
+        if current > 0 and response.status_code == HTTPStatus.PARTIAL_CONTENT:
+            mode = "ab"
+        else:
+            mode = "wb"
+            current = 0
+
+        with response, part.open(mode) as fp:
+            for chunk in response.iter_content(chunk_size=self.chunk_size):
+                if cancelled and cancelled():
+                    fp.flush()
+                    try:
+                        os.fsync(fp.fileno())
+                    except OSError:
+                        pass
+                    raise HFCancelled(f"Download cancelled: {reporter.remote.filename}")
+                if not chunk:
+                    continue
+                fp.write(chunk)
+                current += len(chunk)
+                reporter.report(current)
+
+    def _request_with_retry(
+        self, method: str, url: str, **kwargs: Any
+    ) -> requests.Response:
+        last_exc: BaseException | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self.session.request(
+                    method,
+                    url,
+                    timeout=self.timeout,
+                    **kwargs,
+                )
+            except (requests.ConnectionError, requests.Timeout) as exc:
+                last_exc = exc
+                if attempt >= self.max_retries:
+                    break
+                self._sleep_backoff(attempt)
+                continue
+
+            if response.status_code not in _RETRYABLE_STATUS:
+                return response
+
+            if attempt >= self.max_retries:
+                return response
+
+            delay = _retry_after(response)
+            response.close()
+            self._sleep_backoff(attempt, delay)
+
+        raise HFError(f"Network request failed: {last_exc}") from last_exc
+
+    def _sleep_backoff(self, attempt: int, explicit: float | None = None) -> None:
+        if explicit is not None:
+            delay = explicit
+        else:
+            delay = self.backoff * (2**attempt)
+            delay *= random.uniform(0.8, 1.2)
+        time.sleep(min(delay, 30.0))
+
+    def _validate_partial(
+        self,
+        part: Path,
+        meta_path: Path,
+        expected: _PartialMeta,
+    ) -> None:
+        if not part.exists():
+            if meta_path.exists():
+                meta_path.unlink()
+            return
+
+        if not meta_path.exists():
+            # Unknown provenance: unsafe to resume.
+            part.unlink()
+            return
+
+        try:
+            saved_raw = json.loads(meta_path.read_text(encoding="utf-8"))
+            saved = _PartialMeta(**saved_raw)
+        except Exception:
+            self._remove_partial(part, meta_path)
+            return
+
+        same_identity = (
+            saved.repo_id == expected.repo_id
+            and saved.filename == expected.filename
+            and saved.revision == expected.revision
+        )
+
+        # Prefer commit/etag as version identity. If HF didn't expose either,
+        # size still gives a weak but useful guard.
+        version_matches = True
+        if expected.commit and saved.commit:
+            version_matches = expected.commit == saved.commit
+        elif expected.etag and saved.etag:
+            version_matches = expected.etag == saved.etag
+        elif expected.expected_size is not None and saved.expected_size is not None:
+            version_matches = expected.expected_size == saved.expected_size
+
+        if not same_identity or not version_matches:
+            self._remove_partial(part, meta_path)
+
+    @staticmethod
+    def _remove_partial(part: Path, meta_path: Path) -> None:
+        for path in (part, meta_path):
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                pass
+
+    @staticmethod
+    def _sha256(path: Path) -> str:
+        digest = hashlib.sha256()
+        with path.open("rb") as fp:
+            while True:
+                chunk = fp.read(1024 * 1024)
+                if not chunk:
+                    break
+                digest.update(chunk)
+        return digest.hexdigest()
+
+    def _verify_and_commit(
+        self,
+        part: Path,
+        dest: Path,
+        meta_path: Path,
+        *,
+        expected_size: int | None,
+        expected_sha256: str | None,
+    ) -> None:
+        # Paths and integrity expectations are explicit at the commit boundary.
+        # pylint: disable=too-many-arguments
+        actual_size = part.stat().st_size
+
+        if expected_size is not None and actual_size != expected_size:
+            raise HFIntegrityError(
+                f"Incomplete download: expected {expected_size} bytes, "
+                f"got {actual_size} bytes. Partial file was kept for resume."
+            )
+
+        if expected_sha256 is not None:
+            actual = self._sha256(part)
+            if actual.lower() != expected_sha256.lower():
+                raise HFIntegrityError(
+                    f"SHA-256 mismatch for {dest.name}: expected "
+                    f"{expected_sha256}, got {actual}. Partial file was kept."
+                )
+
+        os.replace(part, dest)
+        try:
+            meta_path.unlink()
+        except FileNotFoundError:
+            pass
+
+    def _raise_hf_error(
+        self,
+        response: requests.Response,
+        *,
+        repo_id: str | None = None,
+        filename: str | None = None,
+    ) -> None:
+        status = response.status_code
+        if HTTPStatus.OK <= status < HTTPStatus.BAD_REQUEST:
+            return
+
+        request_id = response.headers.get("X-Request-Id") or response.headers.get(
+            "X-Amzn-Trace-Id"
+        )
+
+        body = ""
+        try:
+            body = response.text[:4096]
+        except Exception:
+            pass
+
+        lower = body.lower()
+        subject = repo_id or "Hugging Face resource"
+        if filename:
+            subject = f"{subject}/{filename}"
+
+        suffix = f" [request id: {request_id}]" if request_id else ""
+
+        if status == HTTPStatus.TOO_MANY_REQUESTS:
+            raise HFRateLimitError(
+                f"Hugging Face rate limit exceeded for {subject}.{suffix}"
+            )
+
+        # HF gated-resource responses are commonly 401/403 with an explanatory
+        # body. Detect this before the generic auth case.
+        if status in (401, 403) and (
+            "gated" in lower
+            or "access to model" in lower
+            or "access to this model" in lower
+            or "request access" in lower
+        ):
+            model_page = self.model_url(repo_id) if repo_id else self.endpoint
+            raise HFGatedError(
+                f"Access to {subject} is gated. The signed-in Hugging Face user "
+                f"must be granted/accept access first: {model_page}{suffix}"
+            )
+
+        if status in (401, 403):
+            if self.token:
+                raise HFAuthError(
+                    f"Hugging Face denied access to {subject}. The token may "
+                    f"be invalid or lack permission.{suffix}"
+                )
+            raise HFAuthError(
+                f"{subject} requires Hugging Face authentication.{suffix}"
+            )
+
+        if status == HTTPStatus.NOT_FOUND:
+            raise HFNotFoundError(
+                f"Hugging Face repository, revision, or file not found: "
+                f"{subject}.{suffix}"
+            )
+
+        message = f"Hugging Face returned HTTP {status} for {subject}"
+        if body:
+            # Keep server text useful but bounded.
+            compact = " ".join(body.split())
+            message += f": {compact[:500]}"
+        raise HFError(message + suffix)
+
+
+# Keep the convenience wrapper compatible with existing callers.
+def download_hf_model(  # noqa: PLR0913
+    repo_id: str,
+    filename: str,
+    *,
+    revision: str = "main",
+    token: str | None = None,
+    destination: str | os.PathLike[str] | None = None,
+    progress: Callable[[DownloadProgress], None] | None = None,
+    cancelled: Callable[[], bool] | None = None,
+    overwrite: bool = False,
+    expected_sha256: str | None = None,
+) -> str:
+    """Download one Hugging Face model file and return its local path as a string."""
+
+    # pylint: disable=too-many-arguments
+    client = HFClient(token=token)
+    remote = client.file_info(repo_id, filename, revision=revision)
+    lfs_info = client.git_lfs_info(repo_id, filename, revision=revision)
+    if lfs_info is not None:
+        if remote.size is not None and lfs_info["size"] != remote.size:
+            raise HFIntegrityError(
+                f"Conflicting sizes for {filename}: download metadata reports "
+                f"{remote.size}, Git LFS reports {lfs_info['size']}"
+            )
+        if expected_sha256 is None:
+            expected_sha256 = lfs_info["sha256"]
+
+    if destination is None:
+        destination = model_path(repo_id, filename)
+    else:
+        destination = Path(destination)
+
+    path = client.download(
+        repo_id,
+        filename,
+        destination,
+        revision=revision,
+        overwrite=overwrite,
+        progress=progress,
+        cancelled=cancelled,
+        expected_sha256=expected_sha256,
+    )
+    return str(path)
+
+
+def format_bytes(value: int | None) -> str:
+    if value is None:
+        return "?"
+    n = float(value)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if n < _BYTES_PER_KIB or unit == "TiB":
+            return f"{n:.1f} {unit}" if unit != "B" else f"{int(n)} B"
+        n /= _BYTES_PER_KIB
+    return f"{n:.1f} TiB"
+
+
+def format_eta(seconds: float | None) -> str:
+    if seconds is None:
+        return "?"
+    seconds = max(0, int(seconds))
+    if seconds < _SECONDS_PER_MINUTE:
+        return f"{seconds}s"
+    minutes, sec = divmod(seconds, _SECONDS_PER_MINUTE)
+    if minutes < _MINUTES_PER_HOUR:
+        return f"{minutes}m {sec:02d}s"
+    hours, minutes = divmod(minutes, _MINUTES_PER_HOUR)
+    return f"{hours}h {minutes:02d}m"
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Download one file from Hugging Face.")
+    parser.add_argument("repo_id")
+    parser.add_argument("filename")
+    parser.add_argument("destination")
+    parser.add_argument("--revision", default="main")
+    parser.add_argument("--token", default=os.environ.get("HF_TOKEN"))
+    args = parser.parse_args()
+
+    cli_client = HFClient(token=args.token)
+
+    def show(p: DownloadProgress) -> None:
+        pct = f"{p.percent:5.1f}%" if p.percent is not None else "  ?  "
+        print(
+            f"\r{pct}  {format_bytes(p.downloaded)} / {format_bytes(p.total)}  "
+            f"{p.speed_mbps:.1f} MiB/s  ETA {format_eta(p.eta)}",
+            end="",
+            flush=True,
+        )
+
+    result = cli_client.download(
+        args.repo_id,
+        args.filename,
+        args.destination,
+        revision=args.revision,
+        progress=show,
+    )
+    print(f"\nSaved to {result}")

pythonhere/ml_here/storage.py

@@ -0,0 +1,145 @@
+"""Find ML model files managed by PythonHere."""
+
+import os
+import sys
+
+
+def _android_models_directory():
+    """Return the model directory belonging to the running Android app."""
+
+    from jnius import autoclass
+
+    PythonActivity = autoclass("org.kivy.android.PythonActivity")
+    activity = PythonActivity.mActivity
+    if activity is None:
+        raise RuntimeError("A running PythonHere activity is required")
+
+    external_files = activity.getExternalFilesDir(None)
+    if external_files is None:
+        raise RuntimeError("Android external app storage is unavailable")
+
+    return os.path.join(str(external_files.getAbsolutePath()), "models")
+
+
+def _is_android():
+    return sys.platform == "android" or "ANDROID_ARGUMENT" in os.environ
+
+
+def models_directory(create=False):
+    """Return PythonHere's platform-specific model directory.
+
+    Android uses the app-specific external files directory. Linux uses
+    PythonHere's per-user application data directory.
+    """
+
+    if _is_android():
+        path = _android_models_directory()
+    else:
+        path = os.path.expanduser("~/.local/share/pythonhere/models")
+
+    path = os.path.abspath(path)
+    if create:
+        os.makedirs(path, exist_ok=True)
+    return path
+
+
+def _relative_parts(value, label):
+    """Return safe POSIX-style path components for a remote identifier."""
+
+    parts = value.split("/")
+    if not value or any(part in {"", ".", ".."} for part in parts):
+        raise ValueError(f"{label} must be a relative path without dot components")
+    return parts
+
+
+def model_path(repo_id, filename):
+    """Return the local path for a model identified by repository and file."""
+
+    path = os.path.join(
+        models_directory(),
+        *_relative_parts(repo_id, "repo_id"),
+        *_relative_parts(filename, "filename"),
+    )
+    return os.path.abspath(path)
+
+
+def require_model(repo_id, filename):
+    """Return an installed model path, or raise ``FileNotFoundError``."""
+
+    path = model_path(repo_id, filename)
+    if not os.path.isfile(path):
+        raise FileNotFoundError(
+            f"ML model is not installed: {repo_id}/{filename} ({path})"
+        )
+    return path
+
+
+def _model_extensions(extensions):
+    """Normalize an optional model-extension filter."""
+
+    if extensions is None:
+        return None
+    if isinstance(extensions, str):
+        extensions = (extensions,)
+
+    normalized = set()
+    for extension in extensions:
+        if not isinstance(extension, str) or not extension:
+            raise ValueError("extensions must contain non-empty strings")
+        normalized_extension = extension.lower()
+        normalized.add(
+            normalized_extension
+            if normalized_extension.startswith(".")
+            else f".{normalized_extension}"
+        )
+    return tuple(sorted(normalized))
+
+
+def _discover_directory(directory, extensions):
+    """Yield model files recursively beneath a directory."""
+
+    path = os.path.abspath(os.fspath(directory))
+    if not os.path.isdir(path):
+        return
+
+    def ignore_error(_error):
+        pass
+
+    for root, directories, files in os.walk(path, onerror=ignore_error):
+        directories.sort(key=str.casefold)
+        for filename in files:
+            lower_filename = filename.lower()
+            if lower_filename.endswith((".part", ".part.json")):
+                continue
+            if extensions is None or lower_filename.endswith(extensions):
+                yield os.path.abspath(os.path.join(root, filename))
+
+
+def discover_models(extra_directories=(), *, extensions=".litertlm"):
+    """Find local model files, optionally filtered by filename extension.
+
+    ``extensions`` may be one extension or an iterable, with or without the
+    leading dot. The default finds LiteRT-LM models. Pass ``None`` to return
+    all completed files. Temporary files belonging to an in-progress download
+    are always ignored.
+    """
+
+    if isinstance(extra_directories, (str, bytes, os.PathLike)):
+        extra_directories = (extra_directories,)
+    extensions = _model_extensions(extensions)
+
+    models = []
+    seen = set()
+    for directory in (models_directory(), *extra_directories):
+        for discovered_path in _discover_directory(directory, extensions):
+            key = os.path.normcase(discovered_path)
+            if key not in seen:
+                seen.add(key)
+                models.append(discovered_path)
+    return sorted(
+        models,
+        key=lambda path: (os.path.basename(path).casefold(), path.casefold()),
+    )
+
+
+__all__ = ("discover_models", "model_path", "models_directory", "require_model")

pythonhere/version_here.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.4.0"

{pythonhere-0.3.1.dist-info → pythonhere-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonhere
-Version: 0.3.1
+Version: 0.4.0
 Summary: Here is the Kivy based app to run code from the Jupyter magic %there
 Author-email: b3b <ash.b3b@gmail.com>
 License-Expression: MIT
@@ -20,6 +20,9 @@ Requires-Dist: herethere[magic]>=0.3.2
 Requires-Dist: ipython
 Requires-Dist: ipywidgets
 Requires-Dist: Pillow
+Provides-Extra: litert
+Requires-Dist: litert-lm-api==0.16.0; extra == "litert"
+Requires-Dist: requests; extra == "litert"
 Dynamic: license-file
 
 PythonHere

{pythonhere-0.3.1.dist-info → pythonhere-0.4.0.dist-info}/RECORD

@@ -10,9 +10,9 @@ pythonhere/patches_here.py,sha256=zB7Ohbk5PIXt0imnnrV5Mtl-Y7jpD_p5IBPlijQcCCQ,17
 pythonhere/pythonhere.kv,sha256=x1xwiKvJAevqBhtXGLb_axIf-VRos4V_jM9Q2i44f2U,1453
 pythonhere/server_here.py,sha256=dhNMJj1Abz6RZq6SGqkh8-PVOxKThpI519Msoy5WCgM,1862
 pythonhere/tools_here.py,sha256=RWPBX309d7E4mjkiszzsoJwdaSwXZIqb7ODcRBljC0Y,11437
-pythonhere/version_here.py,sha256=r4xAFihOf72W9TD-lpMi6ntWSTKTP2SlzKP1ytkjRbI,22
+pythonhere/version_here.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
 pythonhere/window_here.py,sha256=oFPoNMGafGo4Eij3iU1WwaftmRa05Thm1jzuEAQIwK8,2584
-pythonhere/.agents/skills/pythonhere/SKILL.md,sha256=pLQbCWq7fWrFZ58Fy--tzxJ2UYWwwyn6h6yqxI7FrsM,10927
+pythonhere/.agents/skills/pythonhere/SKILL.md,sha256=sZruiB7DaMeFLNAm2YLrPE7emmHELj2SEieMfxGrGJw,11080
 pythonhere/.agents/skills/pythonhere/agents/openai.yaml,sha256=LuAs_jPFRl9Mhvb8bU8E8JSnCc8uc5JYFqYxlhd5elw,210
 pythonhere/.agents/skills/pythonhere/references/able.md,sha256=3KFblzcGy8VDmriqgcWtqyfZZXoYfDV7kZyKIESCZ_c,22918
 pythonhere/.agents/skills/pythonhere/references/android-media.md,sha256=vM55sxJmvkLQmKAjHZYL_z0F0SR__PjOHSXtGIgP1BI,6631
@@ -22,6 +22,7 @@ pythonhere/.agents/skills/pythonhere/references/android-runtime.md,sha256=VCZkyw
 pythonhere/.agents/skills/pythonhere/references/jnius.md,sha256=lyjdGUsZXw2lS-0eppS2-JNTVgEED30z1DglzT6H0D8,14999
 pythonhere/.agents/skills/pythonhere/references/kivy-kv.md,sha256=9PQR4j-LT66cOUKYCM6AuHXIs5ywmutOQKfxr3frDYw,8546
 pythonhere/.agents/skills/pythonhere/references/kivy-runtime.md,sha256=ggPCmea5lkdg4p6LlxIVUstJhxC40SbrysqXXQ7-lmM,14616
+pythonhere/.agents/skills/pythonhere/references/litert.md,sha256=MAchOo-acMlSwkmtSkAizNMdwKJHzIe87gFyzq6hyZE,4238
 pythonhere/.agents/skills/pythonhere/references/midi.md,sha256=1rB4t7LWnMi139Ou896FzgU-6CGFSNVO1QF9kRBvUgo,10934
 pythonhere/.agents/skills/pythonhere/references/plyer.md,sha256=FYqumbRo826aLrOiRGckS8Oq26v_PoVrSTVbTBZRBs8,6713
 pythonhere/data/logo/logo-128.png,sha256=4sitDJcVBHOU5UPxicmrzc6YqFY7_xtYrc_ULyrw9ks,4161
@@ -41,6 +42,9 @@ pythonhere/magic_here/prompts/kivy-kv.md,sha256=ajIDSo6PG1_7gHcgfNrOARQOUlUEPUae
 pythonhere/magic_here/prompts/kivy-runtime.md,sha256=cAgOF0uE3RKYdKQus7h4lklKtANaLPcOYilGShjNtgM,14621
 pythonhere/magic_here/prompts/midi.md,sha256=2rKvgrwlmeA4MfdnRH9xnTSN0OFOm4mTxtgdYdMAd3Q,10611
 pythonhere/magic_here/prompts/plyer.md,sha256=wplCHPXkN1vU_thGIxvALuYPB6QDdjCHFhoc93ppvAE,6708
+pythonhere/ml_here/__init__.py,sha256=TiAtiBcGl5jkTmm3Rbt1mlPWRFo4BQTcgHHAzYOs_i0,346
+pythonhere/ml_here/huggingface.py,sha256=857iOkJh90jbxhwyTo1EJ2enVwql3rI8-wUvK04UM9s,33030
+pythonhere/ml_here/storage.py,sha256=JlKIad1bjVR7OSY2KFkyujyQA0dTH2DQPFJvFGH7AEE,4606
 pythonhere/ui_here/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pythonhere/ui_here/actionbar_here.kv,sha256=cOjY4ByOyBDUbeS9kbI3JAhi_X3kJ3Pb5h4RL58urwU,214
 pythonhere/ui_here/common_here.kv,sha256=vnNyDwAKKNbRKvh0QKMbTvR0jNDKiY8DdGRnoEEexSc,324
@@ -51,8 +55,8 @@ pythonhere/ui_here/server_screen_here.kv,sha256=x0Se8hmgjS57gFIPa1r2lf6yJchs3lXO
 pythonhere/ui_here/server_screen_here.py,sha256=2zQv1YFmiKNxa__7UZDYbAAAwYFLoZPSZPhr7vjCAkU,925
 pythonhere/ui_here/settings_here.kv,sha256=stMcDq8dCYjay4idK30_7EUu5edkMDAQVPv0H0GuAcM,710
 pythonhere/ui_here/settings_here.py,sha256=7NflZBUqY2ANZaSEuubaX9wIKniqbekcNQkUbqhhmto,4093
-pythonhere-0.3.1.dist-info/licenses/LICENSE,sha256=nW9_eVi3dSMOkr6xghsobAovBEJiffjl_5WjujJTa74,1071
-pythonhere-0.3.1.dist-info/METADATA,sha256=RJucgFL5w5WwQ9g6zcWOcWJOS4-wj4LxnabwupsSxF4,5348
-pythonhere-0.3.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-pythonhere-0.3.1.dist-info/top_level.txt,sha256=dvkfRGF1tFbkjXzD9vwqXTge1Znkv7ga5fRJy5yhJsE,11
-pythonhere-0.3.1.dist-info/RECORD,,
+pythonhere-0.4.0.dist-info/licenses/LICENSE,sha256=nW9_eVi3dSMOkr6xghsobAovBEJiffjl_5WjujJTa74,1071
+pythonhere-0.4.0.dist-info/METADATA,sha256=_Fwxkb2YFoMe4IHOHzOaRLEmWsHjUi8A6JGiLKzN3-4,5470
+pythonhere-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pythonhere-0.4.0.dist-info/top_level.txt,sha256=dvkfRGF1tFbkjXzD9vwqXTge1Znkv7ga5fRJy5yhJsE,11
+pythonhere-0.4.0.dist-info/RECORD,,