programasweights 0.4.3__tar.gz → 0.4.5__tar.gz

programasweights-0.4.5/.github/workflows/test.yml

@@ -0,0 +1,82 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (hermetic deps only)
+        # Install httpx + pytest and the package itself without pulling the heavy
+        # 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
+          python -m pip install -e . --no-deps
+
+      - name: Run hermetic tests
+        # Scoped to tests that need no network, no model download, and no
+        # PAW_API_KEY. Auth tests (@needs_auth) auto-skip without a key; the
+        # network/model-download tests in test_sdk.py are excluded here and can
+        # be run separately against a live server.
+        run: |
+          pytest \
+            tests/test_api_errors.py \
+            tests/test_compile_timeouts.py \
+            tests/test_local_program.py \
+            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
+
+  local-files-windows:
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install hermetic test dependencies
+        run: |
+          python -m pip install httpx pytest
+          python -m pip install -e . --no-deps
+      - name: Test Windows local paths, cache locks, and compile errors
+        run: python -m pytest tests/test_api_errors.py tests/test_compile_timeouts.py tests/test_local_program.py --junitxml=test-results.xml
+      - name: Annotate Windows test failures
+        if: failure()
+        shell: python
+        run: |
+          from pathlib import Path
+          import xml.etree.ElementTree as ET
+
+          report = Path("test-results.xml")
+          if report.exists():
+              for case in ET.parse(report).iter("testcase"):
+                  for result in case:
+                      if result.tag in {"failure", "error"}:
+                          # GitHub truncates annotations, so retain the actual
+                          # exception at the end of long pytest tracebacks.
+                          detail = result.text or result.get("message", "")
+                          message = f"{case.get('name')}: {detail[-3500:]}"
+                          message = message.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+                          print(f"::error::{message}")

{programasweights-0.4.3 → programasweights-0.4.5}/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.5/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## 0.4.5 (2026-09-10)
+
+- Expose structured compile API failures as `paw.APIError`, compatible with
+  `httpx.HTTPStatusError`, preserving server code, message, request ID, and the
+  original response. Transport errors propagate unchanged; no automatic retries.
+- Allow synchronous compilation a 2,400-second read timeout while keeping
+  connect, write, and pool timeouts at 120 seconds. Async submission stays at
+  30 seconds; precheck, status, and cancellation stay at 10 seconds.
+- Load current GGUF ZIP `.paw` files through `paw.function` using explicit
+  local paths or `Path` objects. Validated imports use a separate SHA-256 cache
+  without replacing Hub caches or source files; invalid local files never fall
+  back to Hub lookup. Shared base-model assets may still need downloading unless
+  offline mode is requested. Legacy tensor-format `.paw` files are unsupported.
+
+## 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
+  `--api-url`/`--api-key` (they read the removed `paw.api_url`/`paw.api_key`
+  module attributes; now resolved via the function-based config API).
+- `--api-url` / `--api-key` now take effect on `compile`, `run`, and `login`
+  (previously accepted but silently ignored on those commands).
+- Docs: reference `paw.get_api_url()` / `paw.get_api_key()` instead of the
+  removed module attributes.
+- Add hermetic CLI auth test suite (`tests/test_cli_auth.py`) and a GitHub
+  Actions CI workflow running it on Python 3.9-3.12.
+
+## 0.2.4 (2026-04-01)
+
+- Download reliability: asset endpoints return 202 Retry-After when program is still generating, eliminating 404 race conditions
+- Guard local cleanup on HF upload success: files persist locally if upload fails
+- Stderr suppression now covers LoRA adapter loading (fixes CPU_REPACK warnings on 0.2.3)
+- Browser: fix LoRA switching bug (free old adapter + clear KV before loading new program)
+
+## 0.2.3 (2026-04-01)
+
+- Python 3.9 compatibility fix (`from __future__ import annotations`)
+
+## 0.2.2 (2026-03-19)
+
+- Add `paw.compile_and_load()` convenience method (compile + load in one call)
+- `paw.function()` now accepts a `Program` object directly (not just string ID)
+- Add `paw.list_programs()` for authenticated users to list their programs
+- Suppress `llama.cpp` stderr noise by default; use `verbose=True` to enable
+- Rewritten AGENTS.md with spec-writing tips, full API reference, common errors, and performance notes
+
+## 0.2.0 (2026-04-01)
+
+First public release.
+
+- Compile natural language specs into neural programs via `paw.compile()`
+- Load and run programs locally via `paw.function()` (llama.cpp backend)
+- HuggingFace-style slug naming: `paw.function("da03/my-classifier")`
+- Offline support: slug cache + program cache, no internet after first use
+- CLI: `paw compile`, `paw run`, `paw info`, `paw rename`, `paw login`
+- Pre-built wheels via pypi.programasweights.com for fast install
+- Privacy enforcement: private programs only accessible by owner

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: programasweights
-Version: 0.4.3
+Version: 0.4.5
 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,41 @@ 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.
+
+Load a saved current GGUF ZIP `.paw` bundle directly (SDK 0.4.5+):
+
+```python
+from pathlib import Path
+fn = paw.function(Path("classifier.paw"))
+```
+
+Local files are validated into a separate SHA-256 cache without changing the
+source or falling back to Hub lookup. Runtime metadata or the shared base model
+may still download; `offline=True` prohibits those requests. Legacy tensor-format
+`.paw` files are unsupported. Local-file inputs are supported by `function`,
+not `prepare_program` or `is_offline_ready`.
+
+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 +176,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
 ```
 
@@ -155,4 +192,4 @@ paw login
 
 ## License
 
-MIT
+MIT

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

@@ -53,6 +53,41 @@ 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.
+
+Load a saved current GGUF ZIP `.paw` bundle directly (SDK 0.4.5+):
+
+```python
+from pathlib import Path
+fn = paw.function(Path("classifier.paw"))
+```
+
+Local files are validated into a separate SHA-256 cache without changing the
+source or falling back to Hub lookup. Runtime metadata or the shared base model
+may still download; `offline=True` prohibits those requests. Legacy tensor-format
+`.paw` files are unsupported. Local-file inputs are supported by `function`,
+not `prepare_program` or `is_offline_ready`.
+
+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 +145,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
 ```
 
@@ -125,4 +161,4 @@ paw login
 
 ## License
 
-MIT
+MIT

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

@@ -53,6 +53,42 @@ 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.
+
+Load a saved current GGUF ZIP `.paw` bundle directly (SDK 0.4.5+):
+
+```python
+from pathlib import Path
+fn = paw.function(Path("classifier.paw"))
+```
+
+Local files are validated into a separate SHA-256 cache without changing the
+source or falling back to Hub lookup. Runtime metadata or the shared base model
+may still download; `offline=True` prohibits those requests. Legacy tensor-format
+`.paw` files are unsupported. Local-file inputs are supported by `function`,
+not `prepare_program` or `is_offline_ready`.
+
+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 +146,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
 ```
 
@@ -125,4 +162,4 @@ paw login
 
 ## License
 
-MIT
+MIT

{programasweights-0.4.3 → programasweights-0.4.5}/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`