pythonhere 0.3.1__tar.gz → 0.4.0__tar.gz

{pythonhere-0.3.1/pythonhere.egg-info → pythonhere-0.4.0}/PKG-INFO

@@ -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 → pythonhere-0.4.0}/pyproject.toml

@@ -28,6 +28,12 @@ dependencies = [
     "Pillow",
 ]
 
+[project.optional-dependencies]
+litert = [
+    "litert-lm-api==0.16.0",
+    "requests",
+]
+
 [dependency-groups]
 dev = [
     { include-group = "docker" },
@@ -66,6 +72,7 @@ pythonpath = ["pythonhere"]
 [tool.setuptools]
 packages = [
     "pythonhere",
+    "pythonhere.ml_here",
     "pythonhere.magic_here",
     "pythonhere.ui_here",
 ]

{pythonhere-0.3.1 → pythonhere-0.4.0}/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-0.4.0/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-0.4.0/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",
+)