programasweights 0.4.3__tar.gz → 0.4.4__tar.gz

{programasweights-0.4.3 → programasweights-0.4.4}/.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
 
@@ -22,8 +22,8 @@ jobs:
 
       - name: Install (hermetic deps only)
         # Install httpx + pytest and the package itself without pulling the heavy
-        # llama-cpp-python build. The hermetic tests below never import the
-        # llama.cpp runtime (it is imported lazily only when running inference).
+        # llama-cpp-python build. Runtime tests inject a fake llama_cpp module,
+        # so CI needs neither the native extension nor a model download.
         run: |
           python -m pip install --upgrade pip
           python -m pip install httpx pytest
@@ -36,6 +36,8 @@ jobs:
         # be run separately against a live server.
         run: |
           pytest \
+            tests/test_base_interpreter.py \
             tests/test_cli_auth.py \
+            tests/test_desktop_sdk.py \
             tests/test_runtime_registry_sdk.py \
             tests/test_sdk.py::TestInstallAndImport

{programasweights-0.4.3 → programasweights-0.4.4}/AGENTS.md

@@ -93,13 +93,18 @@ Output: delete
 - **First call** is usually ~1-5s because it loads the base model. Subsequent calls are typically ~0.05-0.5s depending on input length and GPU availability.
 - **Base model files are shared** across programs on disk. Each Standard LoRA adapter is ~22 MB; each Compact LoRA adapter is ~5 MB.
 - Cache root is `~/.cache/programasweights/`. Override with `PAW_CACHE_DIR`.
-- After the first download, inference works offline.
+- After the first download, inference works offline. Pass `offline=True` or set
+  `PAW_OFFLINE=1` to prohibit network access and fail if any validated asset is
+  missing.
+- Advanced only: `paw.function(None, interpreter="gpt2")` runs a supported
+  base model without a compiled adapter; consult the Python API reference for
+  its strict prompt and offline semantics.
 
 ## Common Errors
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `RuntimeError: assets not ready` on download | Program is still generating after compile | The SDK polls automatically for up to 30s. If it still fails, retry shortly or recompile. |
+| `RuntimeError: assets not ready` on download | Program is still generating after compile | The SDK polls automatically for up to 60s. If it still fails, retry shortly or recompile. |
 | `httpx.HTTPStatusError: 422` on compile | Spec too short (<10 chars) or request validation failed | Adjust spec length or request shape. |
 | `httpx.HTTPStatusError: 429` | Hosted compile API limit exceeded | Wait, or sign in for higher compile limits. |
 | GPU/Metal errors on load | GPU backend not available or incompatible | Set `PAW_GPU_LAYERS=0` or pass `n_gpu_layers=0` to force CPU. |
@@ -142,7 +147,7 @@ Hosted API limits apply to compile requests. Most inference should run locally t
 
 ## CLI
 
-Commands: `paw compile --spec "..." --json`, `paw run --program <id> --input "..."`, `paw info <id>`, `paw rename <id> <slug>`, `paw login`. All support `--json` for structured output.
+Commands: `paw compile --spec "..." --json`, `paw run --program <id> --input "..." [--offline]`, `paw info <id>`, `paw rename <id> <slug>`, `paw login`. All support `--json` for structured output.
 
 ## Versioning
 
@@ -164,7 +169,7 @@ Pinned versions (`@v1`) are immutable and cached locally forever. Bare slugs alw
 
 ```python
 program = paw.compile(
-    spec,                               # natural language specification (str)
+    spec,                               # natural language specification (10-16000 chars)
     compiler=None,                      # omit to use the current server default (today: paw-4b-qwen3-0.6b)
     slug=None,                          # URL-safe handle (requires auth)
     public=True,                        # list on public hub
@@ -179,8 +184,15 @@ fn = paw.function("da03/my-classifier", offline=True)  # skip server check
 
 result: str = fn(input_text: str, max_tokens=None, temperature=0.0)
 
+prepared = paw.prepare_program("da03/my-classifier")
+ready = paw.is_offline_ready("da03/my-classifier")  # zero network
+cached = paw.list_cached_programs()
+
 fn = paw.compile_and_load(spec)
 
+job = paw.compile_async(spec, compiler="paw-ft-bs48")  # explicit finetune compiler required
+status = paw.get_compile_status(job["job_id"])
+
 versions = paw.list_versions("da03/my-classifier")  # version history
 programs = paw.list_programs(sort="recent", per_page=20)  # requires auth
 compilers = paw.list_compilers()  # discover available compilers at runtime

{programasweights-0.4.3 → programasweights-0.4.4}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.4 (2026-07-18)
+
+- Add desktop preparation and cache inspection APIs with structured progress:
+  `prepare_program`, `is_offline_ready`, and `list_cached_programs`.
+- Make program/runtime/model caching strict and race-safe: immutable IDs win
+  over slugs, streamed bundles are bounded and validated before atomic
+  installation, runtime manifests are versioned, prefix state is atomically
+  locked, and known GGUF runtimes enforce canonical size/SHA-256 metadata.
+- Enforce true offline behavior through `offline=True` or `PAW_OFFLINE=1`;
+  missing assets now fail clearly without a network call.
+- Add precheck, explicit-finetune `compile_async`, status, and cancellation
+  helpers for long-running compiles. Async compilation now requires a compiler
+  and exposes ready slug/version metadata in its typed responses.
+- Extend `paw run` with mutually exclusive compiled/base routing, `--offline`,
+  and mode/program/interpreter fields in JSON output.
+- Add an advanced, explicit adapter-free path with
+  `paw.function(None, interpreter=...)` for Qwen3-0.6B and GPT-2. It uses
+  versioned built-in prompts and never silently replaces compiled execution.
+- Expand hermetic cache/runtime/CLI tests, add a fake-llama base-runtime suite,
+  and test Python 3.9 through 3.13 in CI.
+
 ## 0.4.3 (2026-07-06)
 
 - Fix `paw info` / `paw rename` crashing with `AttributeError` when run without

{programasweights-0.4.3 → programasweights-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.4.3
+Version: 0.4.4
 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
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
@@ -83,6 +84,28 @@ If you need to inspect available compiler aliases programmatically, use `paw.lis
 
 GPU acceleration is enabled by default (Metal on Mac, CUDA on Linux, falls back to CPU). Set `PAW_GPU_LAYERS=0` to force CPU if GPU causes issues.
 
+## Desktop and Offline Workflows
+
+Prepare and inspect validated local assets without keeping a model loaded:
+
+```python
+prepared = paw.prepare_program("da03/my-classifier")
+assert prepared["offline_ready"]
+
+fn = paw.function("da03/my-classifier", offline=True)
+cached = paw.list_cached_programs()
+```
+
+`offline=True` (or `PAW_OFFLINE=1`) makes zero network calls and fails clearly
+if a required validated program, runtime, adapter, or base model is missing. Long-running
+finetune compiles can be queued with
+`paw.compile_async(spec, compiler="paw-ft-bs48")`; an explicit finetune
+compiler is required.
+
+Advanced adapter-free inference is available with
+`paw.function(None, interpreter="gpt2")`; see the Python API reference for
+its intentionally strict semantics.
+
 ## Browser SDK
 
 Programs compiled with GPT-2 also run in the browser via WebAssembly. The initial model and program assets download automatically; inference then runs client-side.
@@ -140,6 +163,7 @@ Generate API keys at [programasweights.com/settings](https://programasweights.co
 ```bash
 paw compile --spec "Extract error lines from logs" --json
 paw run --program <program_id> --input "[ERROR] timeout" --json
+paw run --program <program_id> --input "[ERROR] timeout" --offline --json
 paw login
 ```
 

{programasweights-0.4.3 → programasweights-0.4.4}/PYPI_README.md

@@ -53,6 +53,28 @@ If you need to inspect available compiler aliases programmatically, use `paw.lis
 
 GPU acceleration is enabled by default (Metal on Mac, CUDA on Linux, falls back to CPU). Set `PAW_GPU_LAYERS=0` to force CPU if GPU causes issues.
 
+## Desktop and Offline Workflows
+
+Prepare and inspect validated local assets without keeping a model loaded:
+
+```python
+prepared = paw.prepare_program("da03/my-classifier")
+assert prepared["offline_ready"]
+
+fn = paw.function("da03/my-classifier", offline=True)
+cached = paw.list_cached_programs()
+```
+
+`offline=True` (or `PAW_OFFLINE=1`) makes zero network calls and fails clearly
+if a required validated program, runtime, adapter, or base model is missing. Long-running
+finetune compiles can be queued with
+`paw.compile_async(spec, compiler="paw-ft-bs48")`; an explicit finetune
+compiler is required.
+
+Advanced adapter-free inference is available with
+`paw.function(None, interpreter="gpt2")`; see the Python API reference for
+its intentionally strict semantics.
+
 ## Browser SDK
 
 Programs compiled with GPT-2 also run in the browser via WebAssembly. The initial model and program assets download automatically; inference then runs client-side.
@@ -110,6 +132,7 @@ Generate API keys at [programasweights.com/settings](https://programasweights.co
 ```bash
 paw compile --spec "Extract error lines from logs" --json
 paw run --program <program_id> --input "[ERROR] timeout" --json
+paw run --program <program_id> --input "[ERROR] timeout" --offline --json
 paw login
 ```
 

{programasweights-0.4.3 → programasweights-0.4.4}/README.md

@@ -53,6 +53,29 @@ If you need to inspect available compiler aliases programmatically, use `paw.lis
 
 GPU acceleration is enabled by default (Metal on Mac, CUDA on Linux, falls back to CPU). Set `PAW_GPU_LAYERS=0` to force CPU if GPU causes issues.
 
+## Desktop and Offline Workflows
+
+Prepare and inspect validated local assets without keeping a model loaded:
+
+```python
+prepared = paw.prepare_program("da03/my-classifier")
+assert prepared["offline_ready"]
+
+fn = paw.function("da03/my-classifier", offline=True)
+cached = paw.list_cached_programs()
+```
+
+`offline=True` (or `PAW_OFFLINE=1`) makes zero network calls and fails clearly
+if a required validated program, runtime, adapter, or base model is missing. Long-running
+finetune compiles can be queued with
+`paw.compile_async(spec, compiler="paw-ft-bs48")`; an explicit finetune
+compiler is required.
+
+Advanced adapter-free inference is available with
+`paw.function(None, interpreter="gpt2")`; see the
+[Python API reference](docs/api-reference/python-sdk.md#advanced-adapter-free-base-interpreter)
+for its intentionally strict semantics.
+
 ## Browser SDK
 
 Programs compiled with GPT-2 also run in the browser via WebAssembly. The initial model and program assets download automatically; inference then runs client-side.
@@ -110,6 +133,7 @@ Generate API keys at [programasweights.com/settings](https://programasweights.co
 ```bash
 paw compile --spec "Extract error lines from logs" --json
 paw run --program <program_id> --input "[ERROR] timeout" --json
+paw run --program <program_id> --input "[ERROR] timeout" --offline --json
 paw login
 ```
 

{programasweights-0.4.3 → programasweights-0.4.4}/docs/api-reference/cli.md

@@ -31,20 +31,35 @@ paw compile --spec "Classify message urgency" [--compiler paw-4b-qwen3-0.6b] [--
 
 ## `paw run`
 
-Run inference locally against a compiled program.
+Run inference locally against a compiled program (the normal mode), or
+explicitly against a bare base interpreter (advanced mode).
 
 ```bash
-paw run --program <id_or_slug> --input "your text" [--max-tokens 512] [--temperature 0.0] [--json]
+paw run --program <id_or_slug> --input "your text" [--offline] [--json]
+
+# Advanced adapter-free mode
+paw run --base --interpreter gpt2 --input "raw prompt" [--offline] [--json]
 ```
 
 | Option | Description |
 |--------|-------------|
 | `--program` | Program hash ID, slug (e.g. `da03/my-classifier`), or official name (e.g. `email-triage`). |
+| `--base` | Select adapter-free base mode. Mutually exclusive with `--program` and requires `--interpreter`. |
+| `--interpreter` | Base interpreter: `Qwen/Qwen3-0.6B` or `gpt2`. Only valid with `--base`. |
 | `--input` | Input text for the program. |
 | `--max-tokens` | Maximum tokens to generate (default: 512). |
 | `--temperature` | Sampling temperature (default: 0.0). |
 | `--verbose` | Print llama.cpp debug output. |
-| `--json` | JSON output with `program`, `input`, `output`. |
+| `--offline` | Require all selected assets to already be cached and make zero network calls. |
+| `--json` | JSON output with `mode`, `program`, `interpreter`, `input`, and `output`. |
+
+Exactly one of `--program` and `--base` is required. An empty or
+whitespace-only `--program` is rejected. Base mode makes no PAW API, slug,
+program, adapter, or prefix-cache calls; online it may download only the
+selected base GGUF. It resets state and tokenizes the complete versioned
+runtime prompt on every invocation. See the
+[Python SDK reference](python-sdk.md#advanced-adapter-free-base-interpreter)
+for the exact prompt bytes and error semantics.
 
 ## `paw rename`
 

programasweights-0.4.4/docs/api-reference/python-sdk.md

@@ -0,0 +1,244 @@
+# Python SDK Reference
+
+The `programasweights` package compiles natural language specs into neural programs that run locally.
+
+## Install
+
+```bash
+pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/
+```
+
+## Import
+
+```python
+import programasweights as paw
+```
+
+## `paw.function`
+
+```python
+fn = paw.function(
+    program_id,
+    n_ctx=2048,
+    n_gpu_layers=None,
+    verbose=False,
+    offline=False,
+    *,
+    interpreter=None,
+)
+```
+
+Loads a compiled program and returns a callable. Downloads the program and base model on first use; cached locally after that. Works offline after first download.
+
+| Parameter | Description |
+|-----------|-------------|
+| `program_id` | Required. A `Program` object, hash ID (e.g. `a6b454023d41ac9ca845`), slug (e.g. `da03/my-classifier`), or official shorthand (e.g. `email-triage`). A `Program` resolves by immutable `id`, not its mutable slug. |
+| `n_ctx` | Context length for the local runtime (default `2048`). |
+| `n_gpu_layers` | GPU layers to offload (`0` = CPU-only, `-1` = all). The default is `-1`, or `PAW_GPU_LAYERS` when set. |
+| `verbose` | Enable verbose logging (default `False`). |
+| `offline` | Require all program/runtime/model assets to already be cached and make zero network calls. `PAW_OFFLINE=1` has the same effect. |
+| `interpreter` | Advanced adapter-free mode only. Must be passed by keyword and only when `program_id` is explicitly `None`. Supported values are `Qwen/Qwen3-0.6B` and `gpt2`. |
+
+The returned callable:
+
+```python
+output: str = fn(input_text, max_tokens=None, temperature=0.0)
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `input_text` | Input string for the program. |
+| `max_tokens` | Maximum tokens to generate. `None` (default) = use all remaining context window. |
+| `temperature` | Sampling temperature (default `0.0`). |
+
+**Context limits:** Spec + input + output share a ~2048 token window. Inputs that exceed it will error. `max_tokens` defaults to `None`: generation runs until EOS or the context limit.
+
+Compiled mode is strict: the adapter, prompt template, matching metadata,
+runtime manifest, and runtime-compatible base-model file must all validate. Version 0.4.4
+accepts runtime manifest version 1 with `adapter_format="gguf_lora"`.
+Built-in models are checked against pinned size/SHA-256 metadata and GGUF
+magic. Historical manifests for those known runtime IDs are normalized to the
+same canonical integrity metadata, so missing server-side checksum fields
+cannot weaken validation. Missing or failed adapters raise an error; the SDK
+never silently falls back to an unadapted base model.
+
+### Advanced: adapter-free base interpreter
+
+Pass explicit `None` plus an interpreter to run the supported base GGUF without a compiled PAW program:
+
+```python
+base = paw.function(None, interpreter="gpt2")
+output = base("raw prompt text")
+```
+
+This mode is intentionally explicit:
+
+- `paw.function()` still requires the `program_id` argument.
+- `program_id=None` without `interpreter` raises `ValueError`.
+- `program_id=""` raises `ValueError` and explains that base mode requires explicit `None`.
+- A non-empty program reference together with `interpreter` raises `ValueError`.
+- No PAW API, slug lookup, program download, adapter load, or disk prefix cache is used.
+- Online mode may download only the selected base GGUF from its built-in runtime manifest. Offline mode never downloads.
+- Every invocation resets model state, renders the complete prompt, and tokenizes that complete rendered prompt in one call.
+
+The built-in prompt contract is versioned with each runtime manifest and must contain exactly one `{INPUT_PLACEHOLDER}`:
+
+```text
+# Qwen/Qwen3-0.6B
+<|im_start|>user
+{INPUT_PLACEHOLDER}<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+
+
+# gpt2
+{INPUT_PLACEHOLDER}
+```
+
+The Qwen bytes are the exact raw-user rendering of
+`apply_chat_template(add_generation_prompt=True, enable_thinking=False)`.
+Zero-token prompts and prompts that consume the full context window raise
+`ValueError`.
+
+## Preparing programs for offline use
+
+```python
+prepared = paw.prepare_program("da03/my-classifier")
+assert prepared["offline_ready"]
+
+ready = paw.is_offline_ready("da03/my-classifier")  # local check; no network
+cached = paw.list_cached_programs()
+```
+
+`prepare_program` resolves and downloads the program, runtime manifest, and shared base model without retaining a loaded `PawFunction`. Pass `offline=True` to require an already complete local cache and prohibit network access.
+
+Desktop applications can receive structured progress without parsing stderr:
+
+```python
+paw.prepare_program(
+    "da03/my-classifier",
+    progress=lambda event: print(event["stage"], event["status"]),
+)
+```
+
+Without a callback, downloads keep using the existing CLI-style status output on stderr.
+
+## `paw.compile`
+
+```python
+program = paw.compile(
+    spec,
+    compiler="paw-4b-qwen3-0.6b",
+    name=None,
+    tags=None,
+    public=True,
+    slug=None,
+)
+```
+
+Compiles a natural language spec on the server. Returns a `Program` object.
+
+| Parameter | Description |
+|-----------|-------------|
+| `spec` | Natural language specification (10-16000 chars). |
+| `compiler` | Compiler name: `paw-4b-qwen3-0.6b` (Standard) or `paw-4b-gpt2` (Compact). |
+| `name` | Display title for the hub (auto-generated if omitted). |
+| `tags` | Tags for discovery (list of strings, max 10). |
+| `public` | Whether to list on the public hub (default `True`). |
+| `slug` | URL-safe handle (e.g. `my-classifier`). Creates a `username/slug` alias. Requires authentication. |
+
+**Return value** -- `Program` object:
+
+| Attribute | Description |
+|-----------|-------------|
+| `id` | Hash-based program identifier. Use with `paw.function(program.id)`. |
+| `slug` | Full slug handle (e.g. `da03/my-classifier`) if one was created, `None` otherwise. |
+| `status` | `"ready"` on success, `"failed"` on error. |
+| `compiler_snapshot` | Exact compiler version used. |
+| `timings` | Timing metadata from the server. |
+| `error` | Error message when compilation fails. |
+
+## Long-running compile jobs
+
+The asynchronous compile endpoint is available through both `PAWClient` and top-level helpers:
+
+```python
+check = paw.precheck_compile(SPEC, compiler="paw-ft-bs48")
+job = paw.compile_async(
+    SPEC,
+    compiler="paw-ft-bs48",
+    public=False,
+)
+
+status = paw.get_compile_status(job["job_id"])
+if status["status"] == "queued":
+    paw.cancel_compile(job["job_id"])
+```
+
+`compile_async` requires an explicit finetune compiler. It submits the request synchronously and returns the queued job metadata immediately; mapper compilers must use `compile`. Poll `get_compile_status` for `queued`, `compiling`, `ready`, `failed`, or `cancelled`. Ready status data includes the immutable program ID and, when naming was requested, `slug`, `version`, and `version_action`.
+
+Status and cancellation requests must use the same authenticated account as
+submission. Anonymous jobs are bound to the validated client IP that submitted
+them.
+
+## `paw.compile_and_load`
+
+```python
+fn = paw.compile_and_load(spec, compiler="paw-4b-qwen3-0.6b", **kwargs)
+```
+
+Convenience method that compiles a spec and immediately loads the result for local inference. Equivalent to `paw.function(paw.compile(spec, ...).id)`. Returns a callable.
+
+Accepts all the same parameters as `paw.compile`.
+
+## `paw.list_programs`
+
+```python
+result = paw.list_programs(sort="recent", per_page=20)
+```
+
+Returns a dict with the authenticated user's compiled programs. Requires authentication.
+
+| Parameter | Description |
+|-----------|-------------|
+| `sort` | Sort order: `"recent"` (default), `"votes"`, `"recommended"`. |
+| `per_page` | Number of results per page (default `20`). |
+
+**Return value** -- dict:
+
+| Key | Description |
+|-----|-------------|
+| `programs` | List of program dicts with `id`, `spec`, `name`, `compiler`, etc. |
+| `total` | Total number of programs. |
+
+## `paw.login`
+
+```python
+paw.login(key=None)
+```
+
+Saves an API key for authenticated requests. If `key` is provided, saves it directly. If omitted, opens the browser to generate a key at `programasweights.com/settings`.
+
+Keys are stored in `~/.config/programasweights/config.json` and loaded automatically on subsequent imports.
+
+You can also set the `PAW_API_KEY` environment variable instead:
+
+```bash
+export PAW_API_KEY=paw_sk_...
+```
+
+## Configuration
+
+| Name | Description |
+|------|-------------|
+| `paw.get_api_url()` | Base URL for API requests. Default: `https://programasweights.com`. Override with `PAW_API_URL` env var. |
+| `paw.get_api_key()` | API key for authenticated calls. Set via `paw.login()` or `PAW_API_KEY` env var. |
+| `paw.__version__` | Installed package version string. |
+
+## Related
+
+- [CLI Reference](cli.md)
+- [REST API Reference](rest-api.md)
+- [Naming Programs](../getting-started/naming-programs.md)

{programasweights-0.4.3 → programasweights-0.4.4}/docs/getting-started/installation.md

@@ -11,6 +11,10 @@ The `--extra-index-url` flag provides pre-built binaries for `llama-cpp-python`,
 ## Requirements
 
 - **Python:** 3.9 through 3.13.
+- **Local runtime:** `llama-cpp-python` is installed with the package.
+
+GPU offload defaults to all available layers (`n_gpu_layers=-1`). Set
+`PAW_GPU_LAYERS=0` to force CPU-only execution.
 
 ## Anaconda on Linux: OpenMP / libgomp errors
 
@@ -27,6 +31,20 @@ CMAKE_ARGS="-DGGML_OPENMP=OFF" pip install programasweights --extra-index-url ht
 | `~/.cache/programasweights/` | Downloaded models and compiled programs |
 | `~/.config/programasweights/` | Local configuration |
 
+Program bundles, runtime manifests, slug mappings, and base models are
+validated before use and installed with atomic cache updates. Built-in base
+models must match their pinned Hugging Face LFS byte size and SHA-256 digest
+and have GGUF magic; adapters must also be nontrivial GGUF files. To prohibit
+all network access, pass `offline=True` to
+`paw.function`/`paw.prepare_program` or set:
+
+```bash
+export PAW_OFFLINE=1
+```
+
+Offline mode fails clearly when any required validated bundle, runtime
+manifest, adapter, or base-model file is missing.
+
 ## Verify the install
 
 ```bash

{programasweights-0.4.3 → programasweights-0.4.4}/docs/guide/local-inference.md

@@ -22,8 +22,9 @@ Common options exposed by the runtime include:
 | Option | Role |
 |--------|------|
 | `n_ctx` | Context window size (default often **2048**). |
-| `n_gpu_layers` | Offload layers to **Metal** or **CUDA** when available. |
+| `n_gpu_layers` | Offload layers to **Metal** or **CUDA** when available (default **-1**, all layers). |
 | `verbose` | Enable detailed logging from the inference backend. |
+| `offline` | Prohibit network access and require validated cached assets. |
 
 Exact names and defaults follow the SDK; refer to the package API for the authoritative list.
 
@@ -35,6 +36,13 @@ Models and program bundles are stored under:
 
 Manage disk usage by removing cached files there if you need to reclaim space or force a fresh download.
 
+Downloads use unique staging directories and per-program locks. The SDK
+streams `.paw` bytes directly to staging with a compressed-size cap, then
+validates adapter, prompt, metadata, member-count, and expansion limits before
+atomically installing them. Incomplete or stale files are never treated as a
+runnable program. Built-in base GGUFs are checked against canonical pinned byte
+sizes and SHA-256 digests before use.
+
 ## Backend
 
 Inference uses **llama.cpp**. Platform-specific optimizations (Metal on Apple GPUs, CUDA on NVIDIA, SIMD such as AVX on CPU) are selected by the build you install; you do not configure those low-level details separately.