programasweights 0.4.6__tar.gz → 0.4.8__tar.gz

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

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.4.8 (2026-09-20)
+
+- Reduce the source distribution to the SDK and files needed to build and
+  document the package.
+
+## 0.4.7 (2026-09-20)
+
+- Add `remote=True` to `paw.function` and `paw.compile_and_load`, plus
+  `paw run --remote`, for hosted inference without downloading model assets
+  or loading the local runtime. Local inference remains the default.
+- Use server generation defaults unless explicitly overridden. Reuse HTTP
+  connections, support `with` and `.close()`, and preserve structured
+  `paw.APIError` details.
+- Reject remote inference combined with offline mode or incompatible local
+  runtime options.
+
 ## 0.4.6 (2026-09-13)
 
 - Add an optional `logits_processor` argument to a compiled or base program

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: programasweights
-Version: 0.4.6
+Version: 0.4.8
 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
@@ -66,6 +66,19 @@ fn("I love this!")  # "positive"
 
 If you specifically want the smaller browser-compatible runtime, pass `compiler="paw-4b-gpt2"`. Otherwise, omit `compiler` and let the server default decide.
 
+## Remote inference (optional)
+
+Use the hosted API for fast inference in around 150 ms, without a local model download.
+
+```python
+import programasweights as paw
+
+with paw.function("email-triage", remote=True) as remote_fn:
+    print(remote_fn("Urgent: the server is down!"))
+```
+
+For direct HTTP calls, see the [REST API reference](https://programasweights.readthedocs.io/en/latest/api-reference/rest-api/#post-infer).
+
 ## Current Public Compilers
 
 
@@ -189,6 +202,7 @@ Generate API keys at [programasweights.com/settings](https://programasweights.co
 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 run --program <program_id> --input "[ERROR] timeout" --remote --json
 paw login
 ```
 

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

@@ -35,6 +35,19 @@ fn("I love this!")  # "positive"
 
 If you specifically want the smaller browser-compatible runtime, pass `compiler="paw-4b-gpt2"`. Otherwise, omit `compiler` and let the server default decide.
 
+## Remote inference (optional)
+
+Use the hosted API for fast inference in around 150 ms, without a local model download.
+
+```python
+import programasweights as paw
+
+with paw.function("email-triage", remote=True) as remote_fn:
+    print(remote_fn("Urgent: the server is down!"))
+```
+
+For direct HTTP calls, see the [REST API reference](https://programasweights.readthedocs.io/en/latest/api-reference/rest-api/#post-infer).
+
 ## Current Public Compilers
 
 
@@ -158,6 +171,7 @@ Generate API keys at [programasweights.com/settings](https://programasweights.co
 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 run --program <program_id> --input "[ERROR] timeout" --remote --json
 paw login
 ```
 

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

@@ -35,6 +35,19 @@ fn("I love this!")  # "positive"
 
 If you specifically want the smaller browser-compatible runtime, pass `compiler="paw-4b-gpt2"`. Otherwise, omit `compiler` and let the server default decide.
 
+## Remote inference (optional)
+
+Use the hosted API for fast inference in around 150 ms, without a local model download.
+
+```python
+import programasweights as paw
+
+with paw.function("email-triage", remote=True) as remote_fn:
+    print(remote_fn("Urgent: the server is down!"))
+```
+
+For direct HTTP calls, see the [REST API reference](docs/api-reference/rest-api.md#post-infer).
+
 ## Current Public Compilers
 
 
@@ -159,6 +172,7 @@ Generate API keys at [programasweights.com/settings](https://programasweights.co
 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 run --program <program_id> --input "[ERROR] timeout" --remote --json
 paw login
 ```
 

{programasweights-0.4.6 → programasweights-0.4.8}/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.6"
+    __version__ = "0.4.8"
 
 from ._output import ProgressCallback, ProgressEvent, report_progress
 from .cache import CachedProgram
@@ -390,6 +390,23 @@ def list_cached_programs() -> list[CachedProgram]:
     return _list_cached_programs()
 
 
+def _validate_remote_options(
+    *,
+    n_ctx: int,
+    n_gpu_layers: int | None,
+    verbose: bool,
+    offline: bool,
+    interpreter: str | None = None,
+) -> None:
+    if offline:
+        raise ValueError("remote=True cannot be combined with offline mode.")
+    if (
+        n_ctx != 2048 or n_gpu_layers is not None
+        or verbose or interpreter is not None
+    ):
+        raise ValueError("Local runtime options cannot be used with remote=True.")
+
+
 def function(
     program_id,
     n_ctx: int = 2048,
@@ -397,13 +414,15 @@ def function(
     verbose: bool = False,
     offline: bool = False,
     *,
+    remote: bool = False,
     interpreter: str | None = None,
 ):
     """Load a compiled program, or explicitly load a bare base interpreter.
 
-    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.
+    For local inference, 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
@@ -418,12 +437,15 @@ def function(
         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.
+        remote: Run hosted inference without downloading model assets. Accepts
+            program IDs, slugs, pinned versions, and Program objects. Cannot
+            be combined with offline mode or non-default local runtime options.
         interpreter: Advanced adapter-free mode. This is only valid when
             ``program_id`` is explicitly ``None``. Initially supported values
             are ``"Qwen/Qwen3-0.6B"`` and ``"gpt2"``.
 
     Returns:
-        A callable ``PawFunction`` that takes an input string and returns output.
+        A callable that takes an input string and returns an output string.
 
     Example:
         >>> fn = paw.function("email-triage")
@@ -432,6 +454,8 @@ def function(
 
         >>> fn = paw.function("da03/my-program@v2")  # pinned version
 
+        >>> fn = paw.function("email-triage", remote=True)
+
         >>> fn = paw.function("./classifier.paw")  # local bundle
 
         >>> base = paw.function(None, interpreter="gpt2")
@@ -440,6 +464,22 @@ def function(
     from . import cache
 
     offline = _offline_requested(offline)
+    if remote:
+        _validate_remote_options(
+            n_ctx=n_ctx,
+            n_gpu_layers=n_gpu_layers,
+            verbose=verbose,
+            offline=offline,
+            interpreter=interpreter,
+        )
+        from ._program_reference import local_program_path
+
+        reference = _coerce_program_reference(program_id)
+        if not reference or local_program_path(reference) is not None:
+            raise ValueError("Remote inference requires a program ID or slug.")
+        from ._remote import load_remote_function
+
+        return load_remote_function(reference)
     if n_gpu_layers is None:
         n_gpu_layers = int(os.environ.get("PAW_GPU_LAYERS", "-1"))
 
@@ -567,9 +607,11 @@ def compile_and_load(
     n_ctx: int = 2048,
     n_gpu_layers: int | None = None,
     verbose: bool = False,
+    *,
+    remote: bool = False,
     **compile_kwargs,
 ):
-    """Compile a spec and immediately load it for local inference.
+    """Compile a spec and load it for local or remote inference.
 
     Convenience wrapper that combines ``paw.compile()`` and ``paw.function()``
     into a single call.
@@ -581,18 +623,32 @@ def compile_and_load(
         n_ctx: Context window size for llama.cpp.
         n_gpu_layers: GPU layers (-1 = all, 0 = CPU only).
         verbose: Print llama.cpp debug output.
+        remote: Run hosted inference without downloading model assets.
         **compile_kwargs: Additional args passed to compile (slug, public, etc.)
 
     Returns:
-        A callable ``PawFunction``.
+        A callable that takes an input string and returns output.
 
     Example:
         >>> fn = paw.compile_and_load("Classify sentiment as positive or negative")
         >>> fn("I love this!")
         'positive'
     """
+    if remote:
+        _validate_remote_options(
+            n_ctx=n_ctx,
+            n_gpu_layers=n_gpu_layers,
+            verbose=verbose,
+            offline=_offline_requested(False),
+        )
     program = compile(spec, compiler=compiler, **compile_kwargs)
-    return function(program, n_ctx=n_ctx, n_gpu_layers=n_gpu_layers, verbose=verbose)
+    return function(
+        program,
+        n_ctx=n_ctx,
+        n_gpu_layers=n_gpu_layers,
+        verbose=verbose,
+        remote=remote,
+    )
 
 
 def list_versions(slug: str) -> dict:

programasweights-0.4.8/programasweights/_remote.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import httpx
+
+from .errors import raise_for_api_status
+
+
+def _infer(
+    client: httpx.Client,
+    program_id: str,
+    input_text: str,
+    *,
+    max_tokens: int | None = None,
+    temperature: float | None = None,
+) -> str:
+    if not isinstance(input_text, str):
+        raise TypeError("input_text must be a string.")
+
+    payload: dict[str, object] = {"program_id": program_id, "input": input_text}
+    if max_tokens is not None:
+        payload["max_tokens"] = max_tokens
+    if temperature is not None:
+        payload["temperature"] = temperature
+
+    response = client.post("api/v1/infer", json=payload)
+    raise_for_api_status(response)
+    data = response.json()
+    if not isinstance(data, dict) or not isinstance(data.get("output"), str):
+        raise ValueError("PAW inference returned an invalid output.")
+    return data["output"]
+
+
+class RemotePawFunction:
+    """A hosted program that owns its HTTP client."""
+
+    def __init__(self, client: httpx.Client, program_id: str):
+        self._client = client
+        self._program_id = program_id
+
+    def __call__(
+        self,
+        input_text: str,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        logits_processor=None,
+    ) -> str:
+        if self._client.is_closed:
+            raise RuntimeError("This RemotePawFunction has been closed.")
+        if logits_processor is not None:
+            raise ValueError("logits_processor is only supported for local inference.")
+        return _infer(
+            self._client,
+            self._program_id,
+            input_text,
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> RemotePawFunction:
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self.close()
+
+
+def load_remote_function(reference: str) -> RemotePawFunction:
+    from urllib.parse import quote
+
+    from .cache import is_program_id
+    from .config import get_api_key, get_api_url
+
+    headers = {}
+    api_key = get_api_key()
+    if api_key:
+        headers["X-API-Key"] = api_key
+    client = httpx.Client(
+        base_url=get_api_url().rstrip("/") + "/",
+        headers=headers,
+        timeout=60.0,
+    )
+    try:
+        program_id = reference
+        if not is_program_id(reference):
+            response = client.get(
+                "api/v1/programs/resolve/" + quote(reference, safe=""),
+                timeout=10.0,
+            )
+            raise_for_api_status(response)
+            data = response.json()
+            program_id = data.get("program_id") if isinstance(data, dict) else None
+            if not isinstance(program_id, str) or not is_program_id(program_id):
+                raise ValueError("PAW returned an invalid program ID.")
+        return RemotePawFunction(client, program_id)
+    except BaseException:
+        client.close()
+        raise

{programasweights-0.4.6 → programasweights-0.4.8}/programasweights/cli.py

@@ -4,7 +4,7 @@ ProgramAsWeights CLI.
 
 Usage:
     paw compile --spec "..."       Compile a spec on the server
-    paw run --program <id> --input "..."   Run a program locally
+    paw run --program <id> --input "..."   Run locally (or add --remote)
     paw rename <program> <slug>    Set or change a program's slug
     paw info <program>             Show program metadata
     paw login [key]                Save API key for authentication
@@ -85,6 +85,9 @@ def cmd_run(args):
     program = getattr(args, "program", None)
     interpreter = getattr(args, "interpreter", None)
     offline = bool(getattr(args, "offline", False))
+    remote = bool(getattr(args, "remote", False))
+    if remote and (base_mode or offline):
+        raise ValueError("--remote cannot be combined with --base or --offline.")
     if base_mode:
         if program is not None:
             raise ValueError("--base cannot be combined with --program.")
@@ -98,13 +101,24 @@ def cmd_run(args):
                 "--interpreter is only valid together with --base."
             )
 
-    fn = paw.function(
-        None if base_mode else program,
-        verbose=args.verbose,
-        offline=offline,
-        interpreter=interpreter,
+    load_kwargs = dict(
+        verbose=args.verbose, offline=offline, interpreter=interpreter,
     )
-    result = fn(args.input, max_tokens=args.max_tokens, temperature=args.temperature)
+    if remote:
+        load_kwargs["remote"] = True
+    max_tokens = args.max_tokens
+    temperature = args.temperature
+    if not remote:
+        if max_tokens is None:
+            max_tokens = 512
+        if temperature is None:
+            temperature = 0.0
+    fn = paw.function(None if base_mode else program, **load_kwargs)
+    try:
+        result = fn(args.input, max_tokens=max_tokens, temperature=temperature)
+    finally:
+        if remote:
+            fn.close()
 
     if args.json:
         print(
@@ -204,7 +218,7 @@ def main():
     p.add_argument("--private", action="store_true", help="Make program private (not listed on hub)")
     p.add_argument("--json", action="store_true", help="JSON output")
 
-    p = sub.add_parser("run", help="Run a program locally via llama.cpp")
+    p = sub.add_parser("run", help="Run a program locally or remotely")
     run_mode = p.add_mutually_exclusive_group(required=True)
     run_mode.add_argument(
         "--program",
@@ -222,8 +236,9 @@ def main():
         help="Base interpreter; only valid with --base",
     )
     p.add_argument("--input", required=True, help="Input text")
-    p.add_argument("--max-tokens", type=int, default=512)
-    p.add_argument("--temperature", type=float, default=0.0)
+    p.add_argument("--max-tokens", type=int, default=None)
+    p.add_argument("--temperature", type=float, default=None)
+    p.add_argument("--remote", action="store_true", help="Use hosted inference")
     p.add_argument("--verbose", action="store_true")
     p.add_argument(
         "--offline",
@@ -250,6 +265,8 @@ def main():
         parser.print_help()
         return 0
     if args.command == "run":
+        if args.remote and (args.base or args.offline):
+            parser.error("--remote cannot be combined with --base or --offline")
         if args.base and args.interpreter is None:
             parser.error("paw run --base requires --interpreter")
         if args.program is not None and args.interpreter is not None:

{programasweights-0.4.6 → programasweights-0.4.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "programasweights"
-version = "0.4.6"
+version = "0.4.8"
 description = "Compile natural language specifications into neural programs that run locally via llama.cpp."
 readme = "PYPI_README.md"
 requires-python = ">=3.9"
@@ -47,6 +47,16 @@ paw = "programasweights.cli:main"
 [tool.hatch.build.targets.wheel]
 packages = ["programasweights"]
 
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "programasweights",
+  "README.md",
+  "PYPI_README.md",
+  "LICENSE",
+  "CHANGELOG.md",
+  "pyproject.toml",
+]
+
 [tool.pytest.ini_options]
 addopts = "-q"
 pythonpath = ["."]

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

@@ -1,82 +0,0 @@
-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.6/.readthedocs.yaml

@@ -1,13 +0,0 @@
-version: 2
-
-build:
-  os: ubuntu-24.04
-  tools:
-    python: "3.12"
-
-mkdocs:
-  configuration: mkdocs.yml
-
-python:
-  install:
-    - requirements: docs/requirements.txt