programasweights 0.4.4__tar.gz → 0.4.6__tar.gz

programasweights-0.4.6/.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.4 → programasweights-0.4.6}/AGENTS.md

@@ -43,6 +43,8 @@ fn = paw.compile_and_load("Classify sentiment as positive or negative")
 fn("I love this!")  # "positive"
 ```
 
+Load a local `.paw` file with `paw.function("./classifier.paw")` (SDK 0.4.5+).
+
 If you want the smaller browser-compatible runtime explicitly, pass `compiler="paw-4b-gpt2"`. Otherwise, omit `compiler` and let the server default decide.
 
 ## Current Public Compilers
@@ -89,6 +91,8 @@ Output: delete
 - Spec + input + output share a ~2048 token context window. Inputs that exceed it will error.
 - `max_tokens` defaults to `None`: generation runs until EOS or the context limit.
 - Compile runs on the hosted PAW API. Inference should usually run locally through the SDK.
+- Synchronous compile requests use a 40-minute read timeout.
+- **Run local inference sequentially by default.** With PAW’s current llama.cpp backend, simultaneous inference calls often perform worse. Reuse loaded functions and process inputs one at a time; never call the same function instance concurrently.
 - **GPU acceleration** is enabled by default (`n_gpu_layers=-1`). Uses Metal on Mac, CUDA on Linux, and falls back to CPU automatically. If GPU causes issues, set `PAW_GPU_LAYERS=0` or pass `n_gpu_layers=0`.
 - **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.
@@ -102,6 +106,8 @@ Output: delete
 
 ## Common Errors
 
+Compile API HTTP errors raise `paw.APIError`. Check `error.code` and `error.message` for details. The SDK does not retry automatically.
+
 | Error | Cause | Fix |
 |-------|-------|-----|
 | `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. |

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

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.6 (2026-09-13)
+
+- Add an optional `logits_processor` argument to a compiled or base program
+  call for caller-supplied token constraints in llama.cpp's sampler.
+  Defaults to `None`; sampling is unchanged when it is unset.
+- Propagate processor failures to the caller instead of letting native
+  callback errors silently continue with unconstrained output.
+
+## 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:

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: programasweights
-Version: 0.4.4
+Version: 0.4.6
 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
@@ -84,6 +84,18 @@ 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.
 
+## Constrained Decoding
+
+In SDK 0.4.6+, a call accepts an optional `logits_processor`: an advanced hook for caller-supplied llama.cpp-compatible token constraints, not built-in regex or JSON-schema validation. It runs at every generation step. The default, `None`, keeps sampling unchanged.
+
+```python
+import llama_cpp
+# my_processor is your compatible callable: (input_ids, scores) -> scores.
+fn("Office line: +1-555-666-7777", logits_processor=llama_cpp.LogitsProcessorList([my_processor]))
+```
+
+Processors see the full prompt and generated-token history, not just the output. Create or reset stateful processors for each call. Token limits and output whitespace trimming still apply, so validate the returned result.
+
 ## Desktop and Offline Workflows
 
 Prepare and inspect validated local assets without keeping a model loaded:
@@ -102,6 +114,19 @@ 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.
@@ -179,4 +204,4 @@ paw login
 
 ## License
 
-MIT
+MIT

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

@@ -53,6 +53,18 @@ 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.
 
+## Constrained Decoding
+
+In SDK 0.4.6+, a call accepts an optional `logits_processor`: an advanced hook for caller-supplied llama.cpp-compatible token constraints, not built-in regex or JSON-schema validation. It runs at every generation step. The default, `None`, keeps sampling unchanged.
+
+```python
+import llama_cpp
+# my_processor is your compatible callable: (input_ids, scores) -> scores.
+fn("Office line: +1-555-666-7777", logits_processor=llama_cpp.LogitsProcessorList([my_processor]))
+```
+
+Processors see the full prompt and generated-token history, not just the output. Create or reset stateful processors for each call. Token limits and output whitespace trimming still apply, so validate the returned result.
+
 ## Desktop and Offline Workflows
 
 Prepare and inspect validated local assets without keeping a model loaded:
@@ -71,6 +83,19 @@ 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.
@@ -148,4 +173,4 @@ paw login
 
 ## License
 
-MIT
+MIT

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

@@ -53,6 +53,18 @@ 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.
 
+## Constrained Decoding
+
+In SDK 0.4.6+, a call accepts an optional `logits_processor`: an advanced hook for caller-supplied llama.cpp-compatible token constraints, not built-in regex or JSON-schema validation. It runs at every generation step. The default, `None`, keeps sampling unchanged.
+
+```python
+import llama_cpp
+# my_processor is your compatible callable: (input_ids, scores) -> scores.
+fn("Office line: +1-555-666-7777", logits_processor=llama_cpp.LogitsProcessorList([my_processor]))
+```
+
+Processors see the full prompt and generated-token history, not just the output. Create or reset stateful processors for each call. Token limits and output whitespace trimming still apply, so validate the returned result.
+
 ## Desktop and Offline Workflows
 
 Prepare and inspect validated local assets without keeping a model loaded:
@@ -71,6 +83,19 @@ 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)
@@ -149,4 +174,4 @@ paw login
 
 ## License
 
-MIT
+MIT

{programasweights-0.4.4 → programasweights-0.4.6}/docs/api-reference/python-sdk.md

@@ -28,21 +28,23 @@ fn = paw.function(
 )
 ```
 
-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.
+Loads a compiled program and returns a callable. Hub references download the
+program and base model on first use; local `.paw` files supply the program
+bundle directly. Required runtime metadata and base models are cached for reuse.
 
 | 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. |
+| `program_id` | Required. A `Program` object, hash ID (e.g. `a6b454023d41ac9ca845`), slug (e.g. `da03/my-classifier`), official shorthand (e.g. `email-triage`), or local `.paw` path (see below). 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. |
+| `offline` | Use only local files/cache and make zero network calls; fail if required validated assets are missing. `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)
+output: str = fn(input_text, max_tokens=None, temperature=0.0, logits_processor=None)
 ```
 
 | Parameter | Description |
@@ -50,11 +52,14 @@ output: str = fn(input_text, max_tokens=None, temperature=0.0)
 | `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`). |
+| `logits_processor` | SDK 0.4.6+. Optional `llama_cpp.LogitsProcessorList` of caller-supplied processors, applied at every generation step. `None` (default) keeps sampling unchanged. |
+
+This advanced hook is not built-in regex or JSON-schema validation. Each processor takes `(input_ids, scores)` and returns modified scores. Its token history includes the full prompt (including any compiled prefix and suffix or base-model template) plus generated tokens. Create or reset stateful processors for each call; processor exceptions propagate to the caller. Token limits and the usual output whitespace trimming still apply, so validate the returned result.
 
 **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
+runtime manifest, and runtime-compatible base-model file must all validate. Version 0.4.5
 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
@@ -62,6 +67,45 @@ 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.
 
+### Loading a local `.paw` file
+
+Version 0.4.5 adds local-file inputs to `paw.function`:
+
+```python
+from pathlib import Path
+
+fn = paw.function(Path("classifier.paw"))
+# With the required runtime metadata and base model already available locally:
+fn = paw.function("./classifier.paw", offline=True)
+```
+
+Use a current GGUF ZIP `.paw` bundle, such as one downloaded from a hosted
+compile. It must contain `meta.json`, `adapter.gguf`, and `prompt_template.txt`,
+with only `pseudo_program.txt` allowed as an optional extra; serialized native
+prefix state is not accepted from archives. Local inputs are selected
+deterministically: a `Path`/`os.PathLike`
+object, an explicit path such as `./classifier.paw` or an absolute path, or a
+string ending in `.paw` (case-insensitive). Ordinary IDs and slugs such as
+`da03/my-classifier` keep their existing Hub behavior even if a matching local
+file exists. Use `Path(...)` or an explicit path for a filename without the
+`.paw` suffix. URL inputs are unsupported.
+
+The bundle is validated and imported under
+`PAW_CACHE_DIR/local_programs/<archive-sha256>` (default cache root:
+`~/.cache/programasweights`). Its source file is unchanged, and its metadata
+cannot replace a Hub program-ID or slug cache. Missing or invalid local files
+raise an error without falling back to a Hub lookup or program download.
+
+A local program does not necessarily make the first load fully offline:
+the existing runtime policy may fetch required runtime metadata from PAW and
+download the shared base model. Pass `offline=True` or set `PAW_OFFLINE=1`
+to prohibit all network access. Historical `PAW\x02` tensor containers,
+including output from the legacy `convert_peft_to_paw` module, are not supported
+by this loader; it does not convert PEFT tensors to GGUF.
+
+Only `paw.function` gains local-file inputs. `prepare_program` and
+`is_offline_ready` continue to accept Hub program references.
+
 ### Advanced: adapter-free base interpreter
 
 Pass explicit `None` plus an interpreter to run the supported base GGUF without a compiled PAW program:
@@ -155,11 +199,24 @@ Compiles a natural language spec on the server. Returns a `Program` object.
 |-----------|-------------|
 | `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. |
+| `status` | Status returned by the server, normally `"ready"` on success. HTTP errors raise `APIError` instead of returning a failed `Program`. |
 | `compiler_snapshot` | Exact compiler version used. |
 | `timings` | Timing metadata from the server. |
 | `error` | Error message when compilation fails. |
 
+### Compile timeouts
+
+Synchronous `compile` uses `httpx.Timeout(120.0, read=2400.0)`: connect, write,
+and pool waits remain 120 seconds; the read timeout is 2,400 seconds. This
+allows for the origin's 1,900-second provider wait plus up to 330 seconds of
+artifact finalization. It is a timeout while waiting for response data, **not a
+40-minute total deadline or guarantee**; upstream services may fail earlier.
+The same setting applies to the compile step of `compile_and_load`.
+
+Async submission retains a 30-second timeout. Precheck, status polling, and
+cancellation each retain a 10-second timeout. For long finetunes, prefer the
+explicit async workflow below so you retain a job ID for later status checks.
+
 ## Long-running compile jobs
 
 The asynchronous compile endpoint is available through both `PAWClient` and top-level helpers:
@@ -183,6 +240,37 @@ Status and cancellation requests must use the same authenticated account as
 submission. Anonymous jobs are bound to the validated client IP that submitted
 them.
 
+### Compile API errors
+
+`compile`, `precheck_compile`, `compile_async`, `get_compile_status`, and
+`cancel_compile` raise `paw.APIError` for HTTP 4xx/5xx responses. It is a subclass
+of `httpx.HTTPStatusError`, so existing handlers continue to work. When supplied
+by the server, `code`, `message`, and `request_id` are available as attributes
+and included in the exception text. Missing fields are `None`; the original
+`request` and `response` remain available, including response headers and body.
+
+```python
+try:
+    job = paw.compile_async(SPEC, compiler="paw-ft-bs48")
+except paw.APIError as error:
+    print(error.code, error.message, error.request_id)
+    # error.response.status_code and error.response.headers are unchanged.
+    raise
+```
+
+For example, a `durable_queue_unavailable` 503 reports that durable Redis must
+be healthy before async compilation can proceed. That rejection occurs before
+the job is accepted; the caller can submit again after service recovery.
+The SDK does not automatically retry compilation requests: other failures may
+occur after a job has already been recorded. Invalid/non-JSON error bodies
+retain the ordinary HTTP error description rather than displaying raw content.
+
+Transport errors such as `httpx.ReadTimeout` propagate unchanged, rather than
+becoming `APIError`. A timeout does not prove the server rejected or cancelled
+the work, so the SDK does not automatically resubmit it. Both `paw.compile`
+and `paw.compile_and_load` propagate these errors; `compile_and_load` does not
+attempt to load a function when compilation raises.
+
 ## `paw.compile_and_load`
 
 ```python

{programasweights-0.4.4 → programasweights-0.4.6}/docs/api-reference/rest-api.md

@@ -136,7 +136,16 @@ List available compiler models and identifiers for use with compile requests.
 
 ### `GET /health`
 
-Liveness or readiness style health check for the API service.
+Returns HTTP 200 for API liveness. The JSON `status` is `healthy` only when
+all enabled public compilers pass their provider checks; otherwise it is
+`degraded`, with details in `warnings` and `gpu_services`, keyed by compiler
+name. Finetune checks include its base compiler, durable Redis, and at least
+one healthy worker. A healthy worker remains available while busy.
+
+Checks run concurrently with a three-second timeout and share a five-second
+cache. `queue_depth` counts waiting finetune jobs across distinct dispatchers,
+not running jobs; it is `null` when a queue cannot be verified. This is a
+readiness observation, not a guarantee that a new compilation will succeed.
 
 ## Errors
 

{programasweights-0.4.4 → programasweights-0.4.6}/programasweights/__init__.py

@@ -27,7 +27,7 @@ try:
     from importlib.metadata import version as _meta_version
     __version__ = _meta_version("programasweights")
 except Exception:
-    __version__ = "0.4.4"
+    __version__ = "0.4.6"
 
 from ._output import ProgressCallback, ProgressEvent, report_progress
 from .cache import CachedProgram
@@ -39,6 +39,7 @@ from .client import (
     Program,
 )
 from .config import get_api_url, get_api_key, set_api_key
+from .errors import APIError
 
 
 def compile(
@@ -400,18 +401,22 @@ def function(
 ):
     """Load a compiled program, or explicitly load a bare base interpreter.
 
-    Downloads the .paw bundle and base model GGUF on first use.
-    Subsequent calls use the local cache.
+    Hub references download the .paw bundle on first use; local paths supply
+    it directly. Required runtime metadata and base models may still download
+    unless offline mode is enabled. Subsequent calls reuse validated caches.
 
     Args:
         program_id: Program ID (str), slug (``da03/my-program``), pinned version
-            (``da03/my-program@v3``), or a ``Program`` object from compile().
+            (``da03/my-program@v3``), a ``Program`` object from compile(), or a
+            local GGUF-based .paw bundle. PathLike objects and explicit path
+            strings (including strings ending in .paw) select local files.
         n_ctx: Context window size for llama.cpp.
         n_gpu_layers: GPU layers (-1 = all GPU, 0 = CPU only). Defaults to -1
             (auto-uses Metal/CUDA if available, safe fallback to CPU).
             Set ``PAW_GPU_LAYERS=0`` env var to force CPU-only.
         verbose: Print llama.cpp debug output.
-        offline: Skip server check for slug resolution and use local cache only.
+        offline: Prohibit network access. Local bundles may be imported, but
+            their runtime and base model must already be available locally.
             Also set via ``PAW_OFFLINE=1`` env var.
         interpreter: Advanced adapter-free mode. This is only valid when
             ``program_id`` is explicitly ``None``. Initially supported values
@@ -427,6 +432,8 @@ def function(
 
         >>> fn = paw.function("da03/my-program@v2")  # pinned version
 
+        >>> fn = paw.function("./classifier.paw")  # local bundle
+
         >>> base = paw.function(None, interpreter="gpt2")
     """
     import os
@@ -452,7 +459,12 @@ def function(
             offline=offline,
         )
 
-    program_reference = _coerce_program_reference(program_id)
+    from ._program_reference import local_program_path
+
+    local_path = local_program_path(program_id)
+    program_reference = (
+        _coerce_program_reference(program_id) if local_path is None else None
+    )
     if program_reference == "":
         raise ValueError(
             "program_id cannot be an empty string; pass explicit None with "
@@ -464,25 +476,35 @@ def function(
             "program_id=None to request adapter-free base mode."
         )
 
-    from .runtime_llamacpp import PawFunction
+    if local_path is not None:
+        from .local_program import import_local_program
 
-    resolved_id = _resolve_program_id(program_reference, offline=offline)
-    if offline and not cache.has_valid_program_assets(resolved_id):
-        raise RuntimeError(
-            f"Program {resolved_id} is not fully cached; offline mode "
-            "prohibits program downloads."
-        )
-    if not cache.has_valid_program_assets(resolved_id):
-        from .client import PAWClient
+        # Validate explicit local input before importing the native runtime.
+        # A missing/corrupt file is never retried as a Hub ID or slug.
+        program_dir = import_local_program(local_path)
+        from .runtime_llamacpp import PawFunction
+    else:
+        # Preserve the existing Hub path's fail-fast dependency check before
+        # resolving slugs or downloading assets.
+        from .runtime_llamacpp import PawFunction
 
-        client = PAWClient(api_url=get_api_url(), api_key=get_api_key())
-        client.download_paw(resolved_id)
-    if not cache.has_valid_program_assets(resolved_id):
-        raise RuntimeError(
-            f"Program {resolved_id} is missing valid compiled assets."
-        )
+        resolved_id = _resolve_program_id(program_reference, offline=offline)
+        if offline and not cache.has_valid_program_assets(resolved_id):
+            raise RuntimeError(
+                f"Program {resolved_id} is not fully cached; offline mode "
+                "prohibits program downloads."
+            )
+        if not cache.has_valid_program_assets(resolved_id):
+            from .client import PAWClient
+
+            client = PAWClient(api_url=get_api_url(), api_key=get_api_key())
+            client.download_paw(resolved_id)
+        if not cache.has_valid_program_assets(resolved_id):
+            raise RuntimeError(
+                f"Program {resolved_id} is missing valid compiled assets."
+            )
+        program_dir = cache.get_program_dir(resolved_id)
 
-    program_dir = cache.get_program_dir(resolved_id)
     return PawFunction(
         program_dir,
         n_ctx=n_ctx,
@@ -616,6 +638,7 @@ def list_compilers() -> list[dict]:
 
 
 __all__ = [
+    "APIError",
     "CachedProgram",
     "CompileCancellation",
     "CompileJob",

programasweights-0.4.6/programasweights/_program_reference.py

@@ -0,0 +1,61 @@
+"""Deterministic local-file intent, independent of filesystem contents."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+
+_WINDOWS_DRIVE = re.compile(r"^[A-Za-z]:")
+_URI_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+def local_program_path(reference: object) -> Path | None:
+    """Return an explicit local path, or None for an ID/slug/Program.
+
+    Path-like objects always mean files. Strings select files by syntax, never
+    by existence; in particular, an ``owner/slug`` remains a Hub reference.
+    """
+    is_pathlike = isinstance(reference, os.PathLike)
+    if is_pathlike:
+        value = os.fspath(reference)
+        if not isinstance(value, str):
+            raise TypeError("Local program paths must be text, not bytes.")
+    elif isinstance(reference, str):
+        value = reference
+    else:
+        return None
+
+    if "\x00" in value:
+        raise ValueError("Program references cannot contain null bytes.")
+    windows_drive = bool(_WINDOWS_DRIVE.match(value))
+    if not is_pathlike and not windows_drive and _URI_SCHEME.match(value):
+        raise ValueError(
+            "Program URLs are not supported. Download the .paw bundle first "
+            "and pass its local path."
+        )
+
+    explicit_path = value.startswith(
+        ("./", "../", "/", "~/", "\\", ".\\", "..\\", "~\\")
+    )
+    if not (
+        is_pathlike or windows_drive or explicit_path
+        or value.lower().endswith(".paw")
+    ):
+        return None
+    if not value:
+        raise ValueError("Local program path cannot be empty.")
+
+    # A Windows-looking string must never be sent to the Hub on another OS.
+    # Path objects, however, explicitly name a native path and may contain
+    # characters that would have a different meaning on another platform.
+    windows_path = windows_drive or value.startswith(
+        ("\\", ".\\", "..\\", "~\\")
+    )
+    if not is_pathlike and os.name != "nt" and windows_path:
+        raise ValueError(
+            "This is a Windows filesystem path, which cannot be opened on "
+            "this platform. Pass a native local path instead."
+        )
+    return Path(value).expanduser()