pythonhere 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonhere
-Version: 0.3.0
+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
@@ -16,10 +16,13 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: herethere[magic]>=0.3.1
+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.0 → pythonhere-0.4.0}/pyproject.toml

@@ -22,12 +22,18 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-    "herethere[magic]>=0.3.1",
+    "herethere[magic]>=0.3.2",
     "ipython",
     "ipywidgets",
     "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.0 → 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
@@ -66,9 +68,11 @@ They complement rather than restrict normal Python:
 These helpers may be called on Kivy's main thread or from a worker. Worker calls
 are transparently marshaled to Kivy's thread and block that worker until Kivy
 finishes the operation, normally on its next frame. Continue to prefer normal
-foreground `there get` and `there run` for quick UI operations. Background
-execution is useful when surrounding work would otherwise block the UI; it does
-not make other Kivy access thread-safe.
+foreground `there get` and `there run` for quick UI operations. Add `--worker`
+to `get` or `run` when surrounding slow or blocking work would otherwise block
+the UI. The CLI remains attached, waits for completion, and then returns the
+value or captured output. Worker execution does not make other Kivy access
+thread-safe.
 
 Do not call a worker-marshaled helper while Kivy's main thread is synchronously
 waiting for that same worker. Neither side can progress in that cross-thread
@@ -179,7 +183,9 @@ there --json run --code "from tools_here import pin_shortcut; pin_shortcut('demo
    - Keep callbacks non-blocking and marshal UI changes to the Kivy thread.
 4. For more than a short expression, create a local UTF-8 Python file and run it
    with `there --json run FILE`. Prefer a file over fragile shell quoting or a
-   long `--code` value. Keep within the installed CLI's input limit.
+   long `--code` value. Keep within the installed CLI's input limit. Add
+   `--worker` for slow or blocking code that should not occupy Kivy's main
+   thread.
 5. Make only the requested live-app mutation. Reuse existing state when
    practical and provide cleanup helpers for scheduled events, sensors,
    Bluetooth, MIDI, files, or other held resources.
@@ -223,6 +229,13 @@ Run a prepared UI change:
 there --json run /tmp/pythonhere-ui.py
 ```
 
+Run slow or blocking non-UI work without freezing Kivy, while waiting for its
+buffered output:
+
+```console
+there --json run --worker /tmp/pythonhere-long-task.py
+```
+
 Verify a named status left by that code:
 
 ```console

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