pythonhere 0.3.1__py3-none-any.whl → 0.4.1__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, durable on-device task runs, or on-device AI with LiteRT-LM and `.litertlm` models."
 ---
 
 # Operate PythonHere with `there`
@@ -40,6 +40,10 @@ 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.
+- Consult [tasks.md](references/tasks.md) for durable sequential work that must
+  continue after a client disconnect or recover after PythonHere restarts.
 
 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/.agents/skills/pythonhere/references/tasks.md

@@ -0,0 +1,58 @@
+# Durable task runs
+
+Use `TaskRunner` for sequential work that must continue after the client
+disconnects, retain progress across a PythonHere restart, or retry individual
+items.
+
+## Start a run
+
+```python
+from tasks_here import TaskRunner
+
+runner = TaskRunner.create("data-import", max_attempts=3)
+runner.add([
+    {"id": "part-1", "path": "one.json"},
+    {"id": "part-2", "path": "two.json"},
+])
+runner.start(execute_task)
+```
+
+Tasks and results must contain plain JSON-compatible values. Every task needs a
+unique nonempty string `id`. `start()` returns promptly and processes one task
+at a time. Preserve the runner in a named global when later commands need it.
+
+Inspect `runner.status()`, `runner.results()`, `runner.get(id)`, or
+`runner.failed()` through normal `there get` calls. `pause()` finishes the
+current item and stops before claiming another.
+
+## Wait and inspect the outcome
+
+After starting the runner, wait in bounded intervals through the CLI:
+
+```bash
+there --json --timeout 60 get --worker \
+  "{'stopped': runner.wait(timeout=50), 'status': runner.status()}"
+```
+
+Here, `--worker` keeps the wait off the app's event loop.
+Keep the CLI timeout longer than the wait timeout to allow time for connection
+and response. If `stopped` is `false`, tasks continue running; repeat the command
+to wait again. A `true` value only means the worker is no longer running (or was
+never started), not that every task succeeded. Inspect `status.state`,
+`status.failed`, and `status.worker_error`. A `completed` state includes tasks
+that exhausted their retries; inspect `runner.failed()` for their errors.
+
+## Resume after restart
+
+After PythonHere restarts, reopen the named run, recreate resources and the
+executor callable, then restart execution:
+
+```python
+runner = TaskRunner.open("data-import")
+runner.start(execute_task)
+```
+
+Execution is at least once: an item interrupted by process death can run again.
+Make irreversible executor side effects idempotent or check their durable state
+before applying them. The executor runs in a background thread; marshal Kivy UI
+access to the main thread according to `kivy-runtime.md`.

pythonhere/main.py

@@ -26,6 +26,7 @@ from kivy.app import App
 from kivy.clock import Clock
 from kivy.config import Config, ConfigParser
 from kivy.logger import Logger
+from kivy.properties import StringProperty  # pylint: disable=no-name-in-module
 from patches_here import monkeypatch_kivy
 from server_here import run_ssh_server
 from window_here import reset_window_environment
@@ -42,6 +43,8 @@ def configure_logging():
 class PythonHereApp(App):
     """PythonHere main app."""
 
+    ssh_host_key_sha256 = StringProperty("")
+
     def __init__(self):
         super().__init__()
         self.server_task: asyncio.Task | None = None

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",
+)