programasweights 0.4.2__tar.gz → 0.4.4__tar.gz

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

@@ -0,0 +1,43 @@
+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_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.2 → 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.4/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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
+  `--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.2 → programasweights-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.4.2
+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.2 → 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.2 → 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.2 → 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.2 → programasweights-0.4.4}/docs/api-reference/rest-api.md

@@ -158,7 +158,12 @@ Successful responses may include:
 | `X-RateLimit-Limit` | Maximum requests per window. |
 | `X-RateLimit-Remaining` | Remaining requests in the current window. |
 
-Clients should backoff when receiving `429 Too Many Requests` and respect `Retry-After` when present.
+Hosted compile quotas:
+
+- Anonymous: **20 compiles/hour**, **1 concurrent compile**
+- Authenticated: **60 compiles/hour**, **2 concurrent compiles**
+
+Hosted server-side endpoints may also enforce additional operational concurrency or safety limits. Clients should back off when receiving `429 Too Many Requests` and respect `Retry-After` when present.
 
 ## Related