Merge pull request #45 from google-ai-edge:refactor/setup-instructions-and-robust-venv

PiperOrigin-RevId: 917926900

Author: copybara-github

.agents/skills/litert_cli/SKILL.md

@@ -9,66 +9,41 @@ This skill allows the agent to download, convert, quantize, run, benchmark, and
 visualize LiteRT models using the `litert` command on desktop, device, or Google
 Cloud.
 
-## Setup & Prerequisites
+## Setup & Prerequisites (Agent Auto-Setup Guide)
 
-Before running any `litert` commands, an agent should ensure it is in a Python
-virtual environment and `litert-cli` is installed.
+When an agent invokes this skill, they **MUST** automatically verify the environment and install dependencies using the following logical workflow. Do not prompt the user; perform these checks and setup steps proactively:
 
-### 1. Check/Create Virtual Environment
+### Step 1. Check if `litert` is already installed
 
-We highly recommend using **`uv`** (written in Rust) for extremely fast environment management and package installs.
+First, check if the `litert` command-line tool is already available and
+functioning: `bash litert --help` If this succeeds, you can **skip the remaining
+setup steps** and proceed directly to executing commands!
 
-**Option A: Use UV (Recommended - Super Fast):**
-```bash
-
-# Create a virtual environment with Python 3.13.
-
-# We use --seed to pre-install pip, setuptools, and wheel inside the venv.
-
-# This is critical to allow our CLI dynamic dependency auto-installers (deps.py) to function.
-
-# When meeting dependency resolution error, try to set environment variable:
+### Step 2. Verify or create a Python Virtual Environment
 
-# UV_INDEX_URL=https://pypi.org/simple
+If `litert` is not found, check if a Python virtual environment is currently active (e.g., by checking if the `$VIRTUAL_ENV` environment variable is set). If not, create and activate one:
 
-uv venv --clear --python=3.13 --seed source .venv/bin/activate ```
+*   **If `uv` is installed (Recommended - Extremely Fast)**: `bash # Create venv
+    with seed packages (critical for dynamic dependency auto-installers) # Use
+    UV_INDEX_URL if you encounter dependency resolution issues
+    UV_INDEX_URL=https://pypi.org/simple uv venv --clear --python=3.13 --seed
+    source .venv/bin/activate`
+*   **Otherwise (Use standard venv/pip)**: `bash python3 -m venv .venv source
+    .venv/bin/activate pip install --upgrade pip setuptools wheel`
 
-**Option B: Use Standard Pip/Venv:** ```bash
+### Step 3. Install `litert-cli`
 
-# Create and activate a standard Python virtual environment.
+Verify if you are in the `LiteRT-CLI` local repository directory (containing
+`pyproject.toml`) to decide the installation source:
 
-python3 -m venv litert-cli-venv source litert-cli-venv/bin/activate
+*   **Option A: If local repository clone exists** (Install in editable mode):
+    *   **Using `uv`**: `bash uv pip install -e .`
+    *   **Using `pip`**: `bash pip install -e .`
 
-# Upgrade pip, setuptools, and wheel immediately.
+*   **Option B: Otherwise** (Install the pre-built nightly package from PyPI):
 
-# This is crucial to meet the project's PEP 517 requirements (setuptools>=61.0).
-
-pip install --upgrade pip setuptools wheel ```
-
-### 2. Check/Install LiteRT CLI
-
-Ensure `litert-cli` and any required optional extensions (extras) are installed:
-
-**Using UV:**
-```bash
-# Install in editable mode from local source
-uv pip install -e .
-
-# Or install from local source with extras (e.g., convert, lm, compile)
-
-uv pip install -e ".[convert,lm,compile]"
-```
-
-**Using standard Pip:** ```bash
-
-# Install in editable mode
-
-pip install -e .
-
-# Or install with extras
-
-pip install -e ".[convert,lm,compile]"
-```
+    *   **Using `uv`**: `bash uv pip install litert-cli-nightly`
+    *   **Using `pip`**: `bash pip install litert-cli-nightly`
 
 ## Core Commands
 

README.md

@@ -1,7 +1,7 @@
 # LiteRT CLI (Preview)
 
 A convenient command-line toolkit to streamline
-[LiteRT](https://ai.google.dev/edge/litert) related development workflow,
+[LiteRT](https://ai.google.dev/edge/litert) related development workflows,
 including converting, quantizing, compiling, managing, running, and benchmarking
 LiteRT (TFLite) models on various hardware (CPU / GPU / NPU) across platforms
 (desktop, mobile, or cloud).
@@ -148,8 +148,8 @@ Verified in Python 3.13.
 
 *   **Host Machines**:
     *   Linux (Ubuntu)
-    *   macOS (Apple Silicon): don't support `litert compile`
-    *   Windows: partially supported
+    *   macOS (Apple Silicon): don't support `litert compile` yet.
+    *   Windows: `litert compile` and `litert convert` not supported yet
 *   **Android**:
     *   CPU, GPU
     *   NPU: Qualcomm, MediaTek (soon), Google Tensor (soon)
@@ -352,10 +352,19 @@ litert delete my_model
 
 ### 11. Run and benchmark a generative LLM model using LiteRT-LM CLI
 
+`litert lm` command will utlitize `litert-lm`, and you can use the same command
+with `litert-lm`, for example, when you use `litert lm run`, you can also use
+`litert-lm run`.
+
+Please follow the
+[LiteRT-LM CLI guide](https://ai.google.dev/edge/litert-lm/cli) for detailed
+instructions.
+
 ```bash
 # Run a generative LLM model, and load from hugging face
-litert lm run \
+litert lm run  \
   --from-huggingface-repo=litert-community/gemma-4-E2B-it-litert-lm \
+  gemma-4-E2B-it.litertlm \
   --prompt="What is the capital of France?"
 
 # Or load from local LLM model file

examples/utils.sh

@@ -80,7 +80,7 @@ function setup_test_env() {
     mkdir -p "$test_root"
     cd "$test_root"
 
-    if [ ! -d ".venv" ]; then
+    if [ ! -d ".venv" ] || [ ! -f ".venv/bin/litert" ]; then
       echo -e "\n${YELLOW}Creating Shared Python virtual environment with UV...${NC}"
       UV_INDEX_URL=https://pypi.org/simple uv venv --clear --python=3.13 --seed
       source .venv/bin/activate