programasweights 0.1.0.dev7__tar.gz → 0.1.0.dev9__tar.gz

programasweights-0.1.0.dev9/.cursor/rules/vllm-deployment.mdc

@@ -0,0 +1,106 @@
+---
+description: vLLM deployment rules and known issues for PAW servers
+alwaysApply: true
+---
+
+# vLLM Deployment Rules
+
+## Server: 31.22.104.226 (4x RTX PRO 6000 Blackwell, 98 GB each)
+
+### Code Location
+
+All server code lives at `/root/paw-website/` (git clone of `programasweights/website`).
+
+**Deployment (the ONLY way to update code):**
+```bash
+# Local: push changes
+git push origin main
+
+# Server: pull and restart
+cd /root/paw-website && git pull
+cd server && bash scripts/start_all.sh
+```
+
+**NEVER use rsync or scp for code.** Model weights use scp between servers.
+
+### GPU Layout
+
+| GPU | Service | Port | VRAM |
+|-----|---------|------|------|
+| 0 | Pseudo-gen (Qwen3-4B) | 8001 | 90% |
+| 1 | Qwen3 compiler pooling (4B) | 8002 | 85% |
+| 2 | GPT-2 compiler pooling (4B) | 8012 | 85% |
+| 3 | Qwen3 inference (0.6B) + GPT-2 inference (124M) | 8003 + 8013 | 50% + 40% |
+
+GPU 3 services must start sequentially: GPT-2 first (smaller, faster), then Qwen3 after GPT-2 claims its VRAM.
+
+### Services
+
+| Service | Port | Working Dir |
+|---------|------|-------------|
+| vLLM pseudo-gen | 8001 | - |
+| vLLM Qwen3 compiler | 8002 | /root/paw-website/server |
+| vLLM GPT-2 compiler | 8012 | /root/paw-website/server |
+| vLLM Qwen3 inference | 8003 | - |
+| vLLM GPT-2 inference | 8013 | - |
+| Qwen3 CompileProvider | 9000 | /root/paw-website/server |
+| GPT-2 CompileProvider | 9001 | /root/paw-website/server |
+| API gateway | 8000 | /root/paw-website/server |
+
+### Startup
+
+```bash
+cd /root/paw-website/server
+bash scripts/start_all.sh    # starts everything, waits for models to load
+```
+
+Or for full redeploy (git pull + patch + start):
+```bash
+cd /root/paw-website
+bash server/scripts/restart.sh
+```
+
+### Key Files
+
+- `.env`: `/root/paw-website/server/.env` (secrets, NOT in git)
+- Provider configs: `server/provider_configs/qwen3-0.6b.json`, `server/provider_configs/gpt2.json`
+- Compiler registry: `server/compiler_registry.json`
+- vLLM launchers: `server/scripts/launch_qwen3_compiler.py`, `server/scripts/launch_gpt2_compiler.py`
+- Patch script: `server/scripts/patch_vllm.sh` (run after every pip install vllm)
+
+## Critical Environment Variables
+
+### VLLM_ALLOW_RUNTIME_LORA_UPDATING=1
+MUST be set for inference servers with --enable-lora.
+
+### VLLM_TORCH_COMPILE_LEVEL=0
+Set on servers without full CUDA dev toolchain.
+
+## vLLM Compiler Pooling (PawCompilerForPooling)
+
+- Must use `--enforce-eager` flag
+- Must use `--runner pooling` flag
+- Must run `scripts/patch_vllm.sh` after every vLLM install
+- Endpoint: `POST /v1/embeddings`
+- Launcher scripts use `if __name__ == '__main__'` guard for multiprocessing
+
+## Post-Install Patch
+
+```bash
+cd /root/paw-website/server && bash scripts/patch_vllm.sh /root/paw-venv
+```
+
+## GPT-2 Specifics
+
+- Interpreter uses NO chat template (use_chat_template: false)
+- Compiler port: 8012 (NOT 8002 which is Qwen3)
+- Inference port: 8013 (NOT 8003 which is Qwen3)
+
+## Testing
+
+Full benchmark: 12 specs, 36 examples, expected 30/36 (83.3%) for Qwen3
+```bash
+cd /root/paw-website/server
+python benchmarks/benchmark_api.py --server https://programasweights.com
+python benchmarks/stress_test.py --server https://programasweights.com --scenario all
+```

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/AGENTS.md

@@ -24,15 +24,16 @@ fn("Newsletter: spring picnic")  # "wait"
 # Compile your own from a description
 program = paw.compile(
     "Fix malformed JSON: repair missing quotes and trailing commas",
-    compiler="paw-4b-qwen3-0.6b"  # or "paw-4b-gpt2" for smaller/faster
+    compiler="paw-4b-qwen3-0.6b",  # or "paw-4b-gpt2" for smaller/faster
+    slug="json-fixer"              # optional: creates da03/json-fixer handle
 )
-fn = paw.function(program.id)
+fn = paw.function(program.slug)    # or paw.function(program.id)
 fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 ```
 
 ## Two Compilers
 
-| | Qwen3 0.6B | GPT-2 124M |
+| | Standard (Qwen3 0.6B) | Compact (GPT-2 124M) |
 |---|---|---|
 | Compiler name | `paw-4b-qwen3-0.6b` | `paw-4b-gpt2` |
 | Accuracy | Higher | Lower |
@@ -41,7 +42,7 @@ fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 | Inference speed | ~90ms (server) | ~50ms (server) |
 | Runs in browser | No | Yes |
 
-Default is Qwen3 0.6B. Use GPT-2 when you need smaller files or browser deployment.
+Default is Standard (Qwen3 0.6B). Use Compact (GPT-2) when you need smaller files or browser deployment.
 
 ## Browser / JavaScript SDK
 
@@ -68,6 +69,7 @@ Use this when you want to offload all computation to the user's browser: zero se
 - **Classification** — sentiment, urgency, categories defined in your own words
 - **Extraction** — emails, names, dates from messy unstructured text
 - **Log triage** — extract errors from verbose output, filter noise
+- **Intent routing** — map user descriptions to the closest URL, menu item, or setting
 - **Agent preprocessing** — parse tool calls, validate outputs, route tasks
 
 ## Authentication
@@ -84,12 +86,25 @@ Generate API keys at https://programasweights.com/settings
 
 The SDK automatically reads `PAW_API_KEY` from the environment. Authenticated users get higher rate limits (60 compiles/hr vs 5 for anonymous).
 
+## Program Naming
+
+Programs have an immutable hash ID (e.g. `a6b454023d41ac9ca845`). Authenticated
+users can optionally assign a slug at compile time to create a human-readable
+handle like `da03/json-fixer`. Both forms work everywhere:
+
+```python
+fn = paw.function("da03/json-fixer")     # by slug
+fn = paw.function("a6b454023d41ac9ca845") # by hash
+```
+
 ## CLI
 
 ```bash
-paw compile --spec "Classify sentiment as positive or negative" --json
-paw run --program <program_id> --input "I love this!" --json
-paw login  # Save API key for higher rate limits
+paw compile --spec "Classify sentiment" --slug "my-classifier" --json
+paw run --program "da03/my-classifier" --input "I love this!" --json
+paw rename <program> <new-slug>   # rename a program's slug
+paw info <program>                # show program metadata
+paw login                         # save API key
 ```
 
 `--json` gives structured output for programmatic use.
@@ -97,9 +112,9 @@ paw login  # Save API key for higher rate limits
 ## API
 
 ```python
-paw.compile(spec, compiler="paw-4b-qwen3-0.6b")  # Compile a spec
-paw.function(name_or_id)                           # Load a compiled program
-paw.login()                                        # Save API key
+paw.compile(spec, slug="my-fn")   # Compile with optional slug
+paw.function(name_or_id)          # Load by slug or hash
+paw.login()                       # Save API key
 ```
 
 ## Browse Programs

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.1.0.dev7
+Version: 0.1.0.dev9
 Summary: Compile natural language specifications into neural programs that run locally via llama.cpp.
 Project-URL: Homepage, https://programasweights.com
 Project-URL: Repository, https://github.com/programasweights/programasweights-python
@@ -22,7 +22,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: httpx<1.0,>=0.27.0
-Requires-Dist: llama-cpp-python<1.0,>=0.3.0
+Requires-Dist: llama-cpp-python<=0.3.18,>=0.3.0
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
@@ -60,7 +60,7 @@ fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 
 ## Two Compilers
 
-|                    | Qwen3 0.6B              | GPT-2 124M             |
+|                    | Standard (Qwen3 0.6B)   | Compact (GPT-2 124M)   |
 |--------------------|-------------------------|------------------------|
 | Compiler name      | `paw-4b-qwen3-0.6b`    | `paw-4b-gpt2`          |
 | Accuracy           | Higher                  | Lower                  |
@@ -69,7 +69,7 @@ fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 | Inference speed    | ~90ms (server)          | ~50ms (server)         |
 | Runs in browser    | No                      | Yes                    |
 
-Default is Qwen3 0.6B. Use GPT-2 when you need smaller files or browser deployment.
+Default is Standard (Qwen3 0.6B). Use Compact (GPT-2) when you need smaller files or browser deployment.
 
 ## Browser SDK
 
@@ -104,6 +104,7 @@ Or save [`AGENTS.md`](https://programasweights.com/agents) to your project root
 - **Classification** — sentiment, urgency, categories defined in your own words
 - **Extraction** — emails, names, dates from messy unstructured text
 - **Log triage** — extract errors from verbose output, filter noise
+- **Intent routing** — map user descriptions to the closest URL, menu item, or setting
 - **Agent preprocessing** — parse tool calls, validate outputs, route tasks
 
 ## Authentication

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/PYPI_README.md

@@ -31,7 +31,7 @@ fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 
 ## Two Compilers
 
-|                    | Qwen3 0.6B              | GPT-2 124M             |
+|                    | Standard (Qwen3 0.6B)   | Compact (GPT-2 124M)   |
 |--------------------|-------------------------|------------------------|
 | Compiler name      | `paw-4b-qwen3-0.6b`    | `paw-4b-gpt2`          |
 | Accuracy           | Higher                  | Lower                  |
@@ -40,7 +40,7 @@ fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 | Inference speed    | ~90ms (server)          | ~50ms (server)         |
 | Runs in browser    | No                      | Yes                    |
 
-Default is Qwen3 0.6B. Use GPT-2 when you need smaller files or browser deployment.
+Default is Standard (Qwen3 0.6B). Use Compact (GPT-2) when you need smaller files or browser deployment.
 
 ## Browser SDK
 
@@ -75,6 +75,7 @@ Or save [`AGENTS.md`](https://programasweights.com/agents) to your project root
 - **Classification** — sentiment, urgency, categories defined in your own words
 - **Extraction** — emails, names, dates from messy unstructured text
 - **Log triage** — extract errors from verbose output, filter noise
+- **Intent routing** — map user descriptions to the closest URL, menu item, or setting
 - **Agent preprocessing** — parse tool calls, validate outputs, route tasks
 
 ## Authentication

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/docs/api-reference/rest-api.md

@@ -25,22 +25,26 @@ Compile a specification.
 
 **Request body (JSON):**
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `spec` | string | Natural-language specification. |
-| `compiler` | string | Compiler identifier. |
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `spec` | string | Yes | Natural-language specification. |
+| `compiler` | string | No | Compiler identifier (default: `paw-4b-qwen3-0.6b`). |
+| `slug` | string | No | URL-safe handle (e.g. `message-classifier`). Creates a `username/slug` alias. Requires auth. |
+| `public` | boolean | No | List on public hub (default: true). |
+| `name` | string | No | Display title. Auto-generated if omitted. |
+| `tags` | string[] | No | Tags for discovery. |
 
-**Response (JSON):** includes `job_id`, `status`, `program_id`, `pseudo_program`, and `timings` as applicable to the job state.
+**Response (JSON):** includes `job_id`, `status`, `program_id`, `slug` (if created), `pseudo_program`, and `timings`.
 
 ### `POST /infer`
 
-Run inference for a compiled program (server-side execution when offered by the deployment).
+Run inference for a compiled program (server-side execution).
 
 **Request body (JSON):**
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `program_id` | string | Program identifier. |
+| `program_id` | string | Program identifier — hash ID or slug (e.g. `da03/message-classifier`). |
 | `input` | string | Input text. |
 | `max_tokens` | integer | Maximum tokens to generate. |
 | `temperature` | number | Sampling temperature. |

programasweights-0.1.0.dev9/docs/getting-started/naming-programs.md

@@ -0,0 +1,78 @@
+# Naming Programs
+
+ProgramAsWeights uses two ways to refer to compiled programs: immutable content hashes and optional human-readable slugs.
+
+## Content-addressable IDs
+
+Every compiled program has a stable identifier derived from its contents, similar to a Git commit hash:
+
+```text
+9b57fd6fccf77885400e
+```
+
+You can load a program by this ID with `paw.function("<id>")` wherever you have the exact string. Hash IDs never change and always work.
+
+## Slugs (human-readable handles)
+
+Authenticated users can optionally assign a slug at compile time:
+
+```python
+program = paw.compile(
+    "Classify message urgency as immediate or wait",
+    slug="message-classifier"
+)
+# Creates da03/message-classifier (username/slug)
+```
+
+The slug creates a `username/slug` handle that works everywhere a hash ID works:
+
+```python
+fn = paw.function("da03/message-classifier")
+```
+
+Slugs are **never auto-generated**. If you don't provide one, your program is
+identified by hash only. This keeps the namespace clean for intentional naming.
+
+### Adding or changing a slug later
+
+You can add a slug to an existing program, or rename it:
+
+```bash
+paw rename a6b454023d41ac9ca845 message-classifier
+```
+
+Or via the API:
+
+```python
+import httpx
+httpx.patch(
+    "https://programasweights.com/api/v1/programs/a6b454023d41ac9ca845",
+    json={"slug": "message-classifier"},
+    headers={"X-API-Key": "paw_sk_..."}
+)
+```
+
+## Official namespace
+
+Programs published under the `programasweights/` namespace are the official catalog. For these, the prefix may be omitted:
+
+- `paw.function("email-triage")` resolves to `programasweights/email-triage`.
+
+## Community programs
+
+Programs published under a user prefix must include that prefix:
+
+```python
+paw.function("da03/message-classifier")
+```
+
+## Authentication
+
+Creating or managing slugs requires signing in with GitHub on [programasweights.com](https://programasweights.com).
+
+## Convention
+
+This mirrors HuggingFace, Docker Hub, and npm:
+
+- Short names like `email-triage` refer to official programs (`programasweights/email-triage`).
+- `username/name` is for community programs, like `Qwen/Qwen3-0.6B` on HuggingFace.

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/docs/guide/browser-inference.md

@@ -2,7 +2,7 @@
 
 Run PAW programs directly in the browser via WebAssembly. No server, no API key, no setup.
 
-Programs compiled with the GPT-2 124M interpreter run entirely client-side. The base model (105 MB) downloads once and is cached; each program adds only ~5 MB.
+Programs compiled with the compact interpreter (GPT-2 124M) run entirely client-side. The base model (105 MB) downloads once and is cached; each program adds only ~5 MB.
 
 ## Quick Start
 
@@ -42,7 +42,7 @@ await fn.free();
 
 ## How It Works
 
-1. **Base model** — GPT-2 124M Q6_K GGUF (105 MB) downloads from HuggingFace CDN and is cached in the browser after first load.
+1. **Base model** — Compact interpreter (GPT-2 124M, 105 MB) downloads from HuggingFace CDN and is cached in the browser after first load.
 2. **LoRA adapter** — Each program is a ~5 MB Q4_0 GGUF LoRA adapter that specializes the base model for a specific task.
 3. **Prefix cache** — A precomputed KV cache (~7 MB) eliminates the prompt prefill step, making the first inference call fast.
 4. **Inference** — Runs via WebAssembly (llama.cpp compiled to WASM with SIMD). ~200ms per call on Chrome.
@@ -134,6 +134,6 @@ Without these headers, the SDK falls back to single-threaded WASM (still functio
 
 ## Limitations
 
-- Only programs compiled with the **GPT-2 124M** interpreter are supported. Programs compiled with Qwen3 0.6B are too large for browser inference (~594 MB base model).
+- Only programs compiled with the **compact** interpreter (GPT-2 124M) are supported. Programs compiled with the standard interpreter (Qwen3 0.6B) are too large for browser inference (~594 MB base model).
 - The 105 MB base model download may be slow on mobile connections.
 - Performance varies by browser (Chrome is fastest).

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/docs/guide/how-it-works.md

@@ -26,7 +26,7 @@ The LoRA weights are quantized to **Q4_0** GGUF format (on the order of **23 MB*
 
 When you run a program locally:
 
-- The SDK loads a **Q6_K** base model (Qwen3-0.6B, about **594 MB**, downloaded once).
+- The SDK loads the standard interpreter (Qwen3 0.6B, about **594 MB**, downloaded once).
 - It applies the **Q4_0** LoRA adapter from the bundle.
 - The pseudo-program is prepended as a **prompt prefix**; user input follows.
 - Inference uses **llama.cpp** (CPU or GPU backends as configured).

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/docs/index.md

@@ -60,7 +60,7 @@ At runtime, the SDK loads a Q6_K base model (~594 MB, downloaded once) and appli
 
 ## Browser Inference
 
-Programs compiled with the GPT-2 124M interpreter also run directly in the browser via WebAssembly -- no server needed:
+Programs compiled with the compact interpreter (GPT-2 124M) also run directly in the browser via WebAssembly -- no server needed:
 
 ```html
 <script type="module">

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/programasweights/__init__.py

@@ -22,7 +22,7 @@ API reference:
     paw.api_key                API key (set via login() or PAW_API_KEY env var)
 """
 
-__version__ = "0.1.0.dev7"
+__version__ = "0.1.0.dev9"
 
 from .config import get_api_url, get_api_key, set_api_key
 
@@ -37,33 +37,38 @@ def compile(
     name: str | None = None,
     tags: list[str] | None = None,
     public: bool = True,
+    slug: str | None = None,
 ):
     """Compile a natural language specification into a neural program.
 
     The compilation runs on the PAW server. The resulting program can be
-    downloaded and run locally via ``paw.function(program.id)``.
+    downloaded and run locally via ``paw.function(program.id)`` or
+    ``paw.function(program.slug)`` if a slug was provided.
 
     Args:
         spec: Full specification text. Include examples in the text if desired.
         compiler: Compiler model (alias or snapshot name).
-        name: Human-readable program name for the hub.
+        name: Human-readable program name (display title for the hub).
         tags: Tags for hub discovery.
         public: Whether to list on the public hub.
+        slug: URL-safe handle (e.g. 'message-classifier'). Creates a
+            ``username/slug`` alias. Requires authentication.
 
     Returns:
-        A ``Program`` object with ``id``, ``status``, and ``timings``.
+        A ``Program`` object with ``id``, ``slug``, ``status``, and ``timings``.
 
     Example:
         >>> program = paw.compile(
-        ...     "Fix malformed JSON: repair missing quotes and trailing commas"
+        ...     "Fix malformed JSON: repair missing quotes and trailing commas",
+        ...     slug="json-fixer"
         ... )
-        >>> fn = paw.function(program.id)
+        >>> fn = paw.function(program.slug)  # or paw.function(program.id)
         >>> fn("{name: 'Alice',}")
         '{"name": "Alice"}'
     """
     from .client import PAWClient
     client = PAWClient(api_url=api_url, api_key=api_key)
-    return client.compile(spec, compiler=compiler, name=name, tags=tags, public=public)
+    return client.compile(spec, compiler=compiler, name=name, tags=tags, public=public, slug=slug)
 
 
 def function(
@@ -94,7 +99,7 @@ def function(
     """
     import os
     import re
-    from .cache import is_program_cached, get_program_dir
+    from .cache import is_program_cached, get_program_dir, get_cached_slug, save_slug_mapping
     from .runtime_llamacpp import PawFunction
 
     if n_gpu_layers is None:
@@ -102,9 +107,14 @@ def function(
 
     resolved_id = program_id
     if not re.fullmatch(r"[a-f0-9]{16,64}", program_id):
-        from .client import PAWClient
-        client = PAWClient(api_url=api_url, api_key=api_key)
-        resolved_id = client.resolve_slug(program_id)
+        cached = get_cached_slug(program_id)
+        if cached:
+            resolved_id = cached
+        else:
+            from .client import PAWClient
+            client = PAWClient(api_url=api_url, api_key=api_key)
+            resolved_id = client.resolve_slug(program_id)
+            save_slug_mapping(program_id, resolved_id)
 
     if not is_program_cached(resolved_id):
         from .client import PAWClient

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/programasweights/cache.py

@@ -10,10 +10,12 @@ Cache structure:
                 adapter.gguf            # ~23 MB, Q4_0 LoRA
                 prompt_template.txt
                 meta.json
+        slug_cache.json                 # slug -> program_id mapping
 """
 
 from __future__ import annotations
 
+import json
 import os
 from pathlib import Path
 
@@ -80,3 +82,36 @@ def _download_file(url: str, dest: Path):
                     mb = downloaded / 1024 / 1024
                     print(f"\r  {mb:.1f} MB ({pct:.0f}%)", end="", flush=True)
         print()
+
+
+def _slug_cache_path() -> Path:
+    return config.get_cache_dir() / "slug_cache.json"
+
+
+def get_cached_slug(slug: str) -> str | None:
+    """Look up a slug in the local cache. Returns program_id or None."""
+    path = _slug_cache_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        program_id = data.get(slug)
+        if program_id and is_program_cached(program_id):
+            return program_id
+    except (json.JSONDecodeError, OSError):
+        pass
+    return None
+
+
+def save_slug_mapping(slug: str, program_id: str) -> None:
+    """Save a slug -> program_id mapping to the local cache."""
+    path = _slug_cache_path()
+    data: dict = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    data[slug] = program_id
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data))

{programasweights-0.1.0.dev7 → programasweights-0.1.0.dev9}/programasweights/cli.py

@@ -26,11 +26,12 @@ def cmd_compile(args):
     if not args.json:
         print(f"Compiling: {args.spec[:80]}...")
 
-    program = paw.compile(args.spec, compiler=args.compiler)
+    program = paw.compile(args.spec, compiler=args.compiler, slug=getattr(args, 'slug', None))
 
     if args.json:
         print(json.dumps({
             "program_id": program.id,
+            "slug": program.slug,
             "status": program.status,
             "error": program.error,
             "timings": program.timings,
@@ -42,15 +43,18 @@ def cmd_compile(args):
         return 1
 
     print(f"Program ID: {program.id}")
+    if program.slug:
+        print(f"Slug: {program.slug}")
     print(f"Status: {program.status}")
     if program.timings:
         total = program.timings.get("total_ms", 0)
         print(f"Total time: {total:.0f}ms")
+    ref = program.slug or program.id
     print(f"\nTo run locally:")
-    print(f"  paw run {program.id} \"your input here\"")
+    print(f"  paw run --program \"{ref}\" --input \"your input here\"")
     print(f"\nOr in Python:")
     print(f"  import programasweights as paw")
-    print(f"  fn = paw.function(\"{program.id}\")")
+    print(f"  fn = paw.function(\"{ref}\")")
     print(f"  fn(\"your input here\")")
     return 0
 
@@ -80,6 +84,37 @@ def cmd_login(args):
     return 0
 
 
+def cmd_rename(args):
+    import programasweights as paw
+    if args.api_url:
+        paw.api_url = args.api_url
+    if args.api_key:
+        paw.api_key = args.api_key
+
+    import httpx
+    from programasweights.client import PAWClient
+    client = PAWClient(api_url=paw.api_url, api_key=paw.api_key)
+
+    resp = httpx.patch(
+        f"{client._api_url}/api/v1/programs/{args.program}",
+        json={"slug": args.new_slug},
+        headers=client._headers(),
+        timeout=10.0,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+
+    if args.json:
+        print(json.dumps(data))
+    else:
+        slug = data.get("slug")
+        if slug:
+            print(f"Renamed to: {slug}")
+        else:
+            print("Slug removed.")
+    return 0
+
+
 def cmd_info(args):
     import programasweights as paw
     if args.api_url:
@@ -129,6 +164,7 @@ def main():
     p = sub.add_parser("compile", help="Compile a spec on the server")
     p.add_argument("--spec", required=True, help="Natural language specification")
     p.add_argument("--compiler", default="paw-4b-qwen3-0.6b", help="Compiler model")
+    p.add_argument("--slug", default=None, help="URL-safe handle (e.g. 'message-classifier')")
     p.add_argument("--json", action="store_true", help="JSON output")
 
     p = sub.add_parser("run", help="Run a program locally via llama.cpp")
@@ -142,6 +178,11 @@ def main():
     p = sub.add_parser("login", help="Save API key for authentication")
     p.add_argument("key", nargs="?", default=None, help="API key (paw_sk_...). Omit to open browser.")
 
+    p = sub.add_parser("rename", help="Set or change a program's slug")
+    p.add_argument("program", help="Program ID or current slug")
+    p.add_argument("new_slug", help="New slug (e.g. 'message-classifier') or empty string to remove")
+    p.add_argument("--json", action="store_true", help="JSON output")
+
     p = sub.add_parser("info", help="Show program info")
     p.add_argument("program", help="Program name or ID")
     p.add_argument("--json", action="store_true", help="JSON output")
@@ -156,6 +197,7 @@ def main():
         "compile": cmd_compile,
         "run": cmd_run,
         "login": cmd_login,
+        "rename": cmd_rename,
         "info": cmd_info,
     }